Update documentation

Author: danielsaidi

README.md

@@ -14,15 +14,13 @@
 
 # TagKit
 
-TagKit is a Swift SDK that makes it easy to work with tags and string/ID slugification in `Swift` and `SwiftUI`.
+TagKit is a Swift SDK that makes it easy to work with tags and slugify strings in `Swift` and `SwiftUI`.
 
 <p align="center">
     <img src="Resources/Demo-v2.gif" width=450 />
 </p>
 
-Tags and tag views can be customized to fit your needs. You can slug and tag any model and customize the slug format. When presenting tags, you can apply custom styling and use any views you like.
-
-TagKit also has a views that make it easier to work with tags. For instance, ``TagList`` and ``TagEditList`` let you list and edit tags, ``TagCapsule`` renders styled tags and ``TagTextField`` automatically slugifies text as you type.
+You can slug and tag any type, customize the slug format, and use the built-in views to list and edit tags with ease.
 
 
 
@@ -39,7 +37,47 @@ https://github.com/danielsaidi/TagKit.git
 
 ## Getting started
 
-The online documentation has a [getting-started guide][Getting-Started] that helps you get started with TagKit.
+TagKit lets you slugify strings and manage tags for any taggable type.
+
+
+### Slugs
+
+Slugifying a string means to remove unwanted characters and replacing whitespaces with a separator. This is often used in urls, where a page slug creates a unique, valid url that also describes the content.
+
+TagKit has a ``Swift/String/slugified(with:)`` string extension that lets you slugify strings with a standard or custom ``SlugConfiguration``:
+
+```
+let custom = SlugConfiguration(
+    separator: "+",
+    allowedCharacters: .init(charactersIn: "hewo")
+)
+
+"Hello, world!".slugified()             // "hello-world" 
+"Hello, world!".slugified(with: custom) // "he+wo"
+```
+
+Slugified strings are automatically lowercased, since a slug should be case-insensitively unique.
+
+
+### Tags
+
+Tagging is the process of adding tags to an item, with the intent to categorize, group, filter and search among tags.
+
+TagKit has a ``Taggable`` protocol that can be implemented by any type that has mutable ``Taggable/tags``:
+
+```swift
+public protocol Taggable {
+
+    var tags: [String] { get set }
+}
+```
+
+Once a type implements ``Taggable``, it can make use of a lot of automatically implemented functionality that the protocol provides, like ``Taggable/hasTags``, ``Taggable/slugifiedTags``, ``Taggable/addTag(_:)``, ``Taggable/removeTag(_:)``, ``Taggable/toggleTag(_:)``. All ``Taggable`` collections are extended as well.
+
+
+### Views
+
+TagKit has a bunch of tag related types, like ``TagCapsule``, ``TagList``, ``TagEditList`` and ``TagTextField``.
 
 
 
@@ -85,5 +123,4 @@ TagKit is available under the MIT license. See the [LICENSE][License] file for m
 [Twitter]: https://twitter.com/danielsaidi
 
 [Documentation]: https://danielsaidi.github.io/TagKit
-[Getting-Started]: https://danielsaidi.github.io/TagKit/documentation/tagkit/getting-started
 [License]: https://github.com/danielsaidi/TagKit/blob/master/LICENSE

RELEASE_NOTES.md

@@ -8,9 +8,13 @@ TagKit will use semver after 1.0.
 
 This version makes TagKit use Swift 6.
 
+### 🗑️ Deprecated
+
+* `Slugifiable` has been deprecated. Just use the `slugified` string extension instead.
+
 ### 💥 Breaking Changes
 
-* `FlowLayout` did not support Swift 6 strict concurrency and has been removed.
+* `FlowLayout` could not be refactored to support strict concurrency, and has been removed.
 
 
 

Sources/TagKit/SlugConfiguration.swift

@@ -11,18 +11,18 @@ import Foundation
 /// This configuration defines how ``Slugifiable`` types are
 /// slugified.
 ///
-/// The standard configuration allows `a-z`, `A-Z` and `0-9`,
-/// and will e.g. slugify `Hello, world!` into `hello-world`.
+/// The standard configuration allows `a-z0-9`, and will for
+/// instance slugify `Hello, world!` into `hello-world`.
 public struct SlugConfiguration {
 
     /// Create a new slug configurator.
     ///
     /// - Parameters:
     ///   - separator: The separator to use in the slugified string, by default `-`.
-    ///   - allowedCharacters: The characters to allow in the slugified string, by default `a-zA-Z0-9`.
+    ///   - allowedCharacters: The characters to allow in the slugified string, by default `a-z0-9`.
     public init(
         separator: String = "-",
-        allowedCharacters: String = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+        allowedCharacters: String = "abcdefghijklmnopqrstuvwxyz0123456789"
     ) {
         let chars = allowedCharacters + separator
         self.separator = separator

Sources/TagKit/String+Slugified.swift

@@ -0,0 +1,25 @@
+//
+//  String+Slug.swift
+//  TagKit
+//
+//  Created by Daniel Saidi on 2022-08-18.
+//  Copyright © 2022-2024 Daniel Saidi. All rights reserved.
+//
+
+import Foundation
+
+public extension String {
+
+    /// Create a slugified version of the string.
+    ///
+    /// - Parameters:
+    ///   - configuration: The configuration to use, by default ``SlugConfiguration/standard``.
+    func slugified(
+        with configuration: SlugConfiguration = .standard
+    ) -> String {
+        lowercased()
+            .components(separatedBy: configuration.notAllowedCharacterSet)
+            .filter { !$0.isEmpty }
+            .joined(separator: configuration.separator)
+    }
+}

Sources/TagKit/TagKit.docc/Getting-Started.md

@@ -8,11 +8,9 @@ TagKit is a Swift SDK that makes it easy to work with tags and slugification in
 
 ![TagKit logo](Logo.png)
 
-TagKit is a Swift SDK that makes it easy to work with tags and slugification in `Swift` and `SwiftUI`.
-
-Tags and views can be customized to fit your needs. You can slug and tag any model and customize the slug format. When presenting tags, you can apply custom styling and use any views you like.
+TagKit is a Swift SDK that makes it easy to work with tags and slugified strings in `Swift` and `SwiftUI`.
 
-TagKit also has a views that make it easier to work with tags. For instance, ``TagList`` and ``TagEditList`` let you list and edit tags, ``TagCapsule`` renders styled tags and ``TagTextField`` automatically slugifies text as you type.
+You can slug and tag any type and customize the slug format, and use the built-in views to list and edit tags with minimum effort.
 
 
 
@@ -28,7 +26,48 @@ https://github.com/danielsaidi/TagKit.git
 
 ## Getting started
 
-The <doc:Getting-Started> article helps you get started with TagKit.
+TagKit lets you slugify strings and manage tags for any taggable type.
+
+
+### Slugs
+
+Slugifying a string means to remove unwanted characters and replacing whitespaces with a separator. This is often used in urls, where a page slug creates a unique, valid url that also describes the content.
+
+TagKit has a ``Swift/String/slugified(with:)`` string extension that lets you slugify strings with a standard or custom ``SlugConfiguration``:
+
+```
+let custom = SlugConfiguration(
+    separator: "+",
+    allowedCharacters: .init(charactersIn: "hewo")
+)
+
+"Hello, world!".slugified()             // "hello-world" 
+"Hello, world!".slugified(with: custom) // "he+wo"
+```
+
+Slugified strings are automatically lowercased, since a slug should be case-insensitively unique.
+
+
+### Tags
+
+Tagging is the process of adding tags to an item, with the intent to categorize, group, filter and search among tags.
+
+TagKit has a ``Taggable`` protocol that can be implemented by any type that has mutable ``Taggable/tags``:
+
+```swift
+public protocol Taggable {
+
+    var tags: [String] { get set }
+}
+```
+
+Once a type implements ``Taggable``, it can make use of a lot of automatically implemented functionality that the protocol provides, like ``Taggable/hasTags``, ``Taggable/slugifiedTags``, ``Taggable/addTag(_:)``, ``Taggable/removeTag(_:)``, ``Taggable/toggleTag(_:)``. All ``Taggable`` collections are extended as well.
+
+
+### Views
+
+TagKit has a bunch of tag related types, like ``TagCapsule``, ``TagList``, ``TagEditList`` and ``TagTextField``.
+
 
 
 

Sources/TagKit/TagKit.docc/TagKit.md

@@ -8,16 +8,14 @@
 
 import Foundation
 
-/// This protocol can be implemented by any type that can be
-/// converted to a slugified string.
-///
-/// This protocol is automatically implemented by `String`.
+@available(*, deprecated, renamed: "Sluggable")
 public protocol Slugifiable {
 
     /// The value used to create a slugified representation.
     var slugifiableValue: String { get }
 }
 
+@available(*, deprecated, renamed: "Sluggable")
 public extension Slugifiable {
 
     /// Convert the slugifiable value to a slugified string.
@@ -37,7 +35,12 @@ public extension Slugifiable {
     }
 }
 
-extension String: Slugifiable {
+public extension String {
 
-    public var slugifiableValue: String { self }
+    @available(*, deprecated, renamed: "slugified(with:)")
+    func slugified(
+        configuration: SlugConfiguration
+    ) -> String {
+        slugified(with: configuration)
+    }
 }