dnrops
/
YComponentBrowser
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update README and doc comments

This commit is contained in:
Mark Pospesel 2022-10-05 13:40:20 +02:00 committed by Mark Pospesel
parent b5deabff24
commit 34632313ae
16 changed files with 232 additions and 220 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

265
README.md
View File

@ -1,16 +1,23 @@
![Y—Component-Browser](https://user-images.githubusercontent.com/1037520/193869618-43383e11-d01f-4604-899d-6fbdb0d7dc3c.jpeg) ![Y—Component-Browser](https://user-images.githubusercontent.com/1037520/193869618-43383e11-d01f-4604-899d-6fbdb0d7dc3c.jpeg)
_Easily extend any project to include an intelligent design component browser._
A standalone component browser package that intelligently displays design components. Licensing
----------
Y—Component Browser is licensed under the [Apache 2.0 license](LICENSE).
Documentation
----------
Documentation is automatically generated from source code comments and rendered as a static website hosted via GitHub Pages at: https://yml-org.github.io/YComponentBrowser/
## Table of Contents ## Table of Contents
* [Usage](#usage) * [Usage](#usage)
* [Icon Category](#icon-category)
* [Font Category](#font-category)
* [Color Category](#color-category) * [Color Category](#color-category)
* [Font Category](#font-category)
* [Icon Category](#icon-category)
* [Catalog Category](#catalog-category) * [Catalog Category](#catalog-category)
* [Custom Component Category](#custom-component-category) * [Small Component Category](#small-component-category)
* [Custom View Controller Category](#custom-view-controller-category) * [Medium Component Category](#medium-component-category)
* [Large Component Category](#large-component-category)
* [Contributing to Y—Component-Browser](#contributing-to-ycomponent-browser) * [Contributing to Y—Component-Browser](#contributing-to-ycomponent-browser)
* [Versioning Stratergy](#versioning-strategy) * [Versioning Stratergy](#versioning-strategy)
* [Branching Stratergy](#branching-strategy) * [Branching Stratergy](#branching-strategy)
@ -18,107 +25,108 @@ A standalone component browser package that intelligently displays design compon
* [Pull Requests](#pull-requests) * [Pull Requests](#pull-requests)
* [Releasing New Versions](#releasing-new-versions) * [Releasing New Versions](#releasing-new-versions)
* [Requirements](#requirements) * [Requirements](#requirements)
* [SwiftLint (linter)](#swiftlint-linter)
* [Jazzy (documentation)](#jazzy-documentation) * [Jazzy (documentation)](#jazzy-documentation)
* [Setup](#setup) * [Setup](#setup)
* [Generating Documentation (via Jazzy)](#generating-documentation-via-jazzy) * [Generating Documentation (via Jazzy)](#generating-documentation-via-jazzy)
Usage Usage
---------- ----------
The category is a collection of components utilized in a project that share common traits. A category with a number of subcategories can be created. By default, components are laid out in nested table views, with each component being represented by a single row. A CatalogDisplayView is used to display a component in a single row. It displays small components together with a title and optional subtitle text. This is used for icons, fonts, and colors, but also works well for smaller components such as buttons. It uses generics to display any view (together with an associated model). The framework includes some pre-defined categories for displaying common tasks: icons, colors, and fonts. A category is a collection of components that share common traits. A category may contain subcategories. By default, components are laid out in nested table views, with each component being represented by a single row. A `CatalogDisplayView` is used to display a component in a single row. It displays small components together with a title and optional detail description. This is used for icons, fonts, and colors, but also works well for smaller components such as buttons. By using generics, `CaralogDisplayView` can display any view (populated with an associated model). The framework includes pre-defined categories for displaying common components: colors, fonts, and icons.
The catalog display view model has four parameters: The catalog display view model has four parameters:
* The title of the component
* The model of the component
* The description, an optional argument, is nil by default but allows the user to provide more information about the component if necessary.
* A user may choose whether they want the title, description, and components to be shown vertically or horizontally using the axis attribute, which is an optional parameter and is horizontal by default.
Using the custom category defined in the package, a bigger component, such as a card view, can be shown. These custom component may take up a full row by itself. For a components like a view controller, we may skip the table view controller and show the component on the full screen by defining a custom category and destination that comply with the Classification protocol and Destination protocol, respectively. * `title`: title
* `detail`: detail description (optional), defaults to `nil`
* `axis`: primary axis for the content view, defaults to `.horizontal`
* `model`: model to populate the content view
By using `CustomCategory`, a larger component, such as a card view, can be shown. Each custom component might occupy a full row by itself.
### Icon Category For even larger components such as a view controller, we may skip the table view controller and display the component on a full screen by itself. This is accomplished by defining a custom category and destination that conform to the `Classification` and `Destination` protocols, respectively.
For example, a user can create an icon category as follows:
```
enum IconSample {
static var media: IconCategory {
IconCategory(
name: "Media",
models: [
.init(
title: "Play",
model: UIImage(systemName: "play.fill") ?? UIImage()
)
]
)
}
}
```
where the user needs to provide the following parameters:
* The name of the category.
* Model for the image to be displayed
![mediaIcon](https://user-images.githubusercontent.com/61827955/193548051-8da7a620-899b-4f5f-97c0-c998028946bc.png)
### Font Category
a user can create a font category as follows:
```
enum FontSample {
static var tiemposHeadlineBold: FontCategory {
FontCategory(
name: "TiemposHeadline Bold",
models: [
.init(
title: "Title 1",
model: FontView.Model(
font: UIFont(name: "TiemposHeadline-Bold", size: 36) ?? UIFont()
)
)
]
)
}
}
```
where the user needs to provide the following parameters:
* The name of the category.
* Model for the font to be displayed
![font](https://user-images.githubusercontent.com/61827955/193548426-a1e98f0e-4bb1-434e-9d65-9b4e46f554ea.png)
### Color category ### Color category
a user can create a color category as follows: We can display colors by declaring a `ColorCategory` object:
``` ```
enum ColorSample { let category = ColorCategory(
static var category: ColorCategory {
ColorCategory(
name: "Easter", name: "Easter",
models: [ models: [
.init( .init(
title: "Purple", title: "Purple",
detail: "HEX: #D9D7F1", detail: "HEX: #D9D7F1",
model: UIColor(red: 217/255, green: 215/255, blue: 241/255, alpha: 1) model: UIColor(red: 217/255, green: 215/255, blue: 241/255, alpha: 1)
),
.init(
title: "Light Yellow",
detail: "HEX: #FFFDDE",
model: UIColor(red: 1, green: 253/255, blue: 222/255, alpha: 1)
) )
] ]
) )
}
}
``` ```
where the user needs to provide the following parameters: where you need to specify:
* The name of the category.
* Model for the view to be displayed
![EasterColor](https://user-images.githubusercontent.com/61827955/193548046-e5bfb718-1237-4558-bdbe-fbe99c889287.png) * `name`: color category name
* `models`: information about the colors to be displayed
![Easter colors](https://user-images.githubusercontent.com/61827955/193548046-e5bfb718-1237-4558-bdbe-fbe99c889287.png)
### Font Category
We can display fonts by declaring a `FontCategory` object:
```
let category = FontCategory(
name: "TiemposHeadline Bold",
models: [
.init(
title: "Title 1",
model: FontView.Model(
font: UIFont(name: "TiemposHeadline-Bold", size: 36)!
)
),
.init(
title: "Title 2",
model: FontView.Model(
font: UIFont(name: "TiemposHeadline-Bold", size: 26)!
)
)
]
)
```
where you need to specify:
* `name`: font category name
* `models`: information about the fonts to be displayed
![Tiempos Headline Bold fonts](https://user-images.githubusercontent.com/61827955/193548426-a1e98f0e-4bb1-434e-9d65-9b4e46f554ea.png)
### Icon Category
We can display icons by declaring an `IconCategory` object:
```
let category = IconCategory(
name: "Media",
models: [
.init(
title: "Play",
model: UIImage(systemName: "play.fill")!
),
.init(
title: "Pause",
model: UIImage(systemName: "pause.fill")!
)
]
)
```
where you need to specify:
* `name`: icon category name
* `models`: information about the icons to be displayed
![Media icons](https://user-images.githubusercontent.com/61827955/193548051-8da7a620-899b-4f5f-97c0-c998028946bc.png)
### Catalog Category ### Catalog Category
We can create a category which contains other categories. We can display nested subcategories by declaring a `CatalogCategory` object:
``` ```
let foundationalCategory = CatalogCategory( let category = CatalogCategory(
name: "Foundational", name: "Foundational",
subcategories: [ subcategories: [
ColorSample.category, ColorSample.category,
@ -127,87 +135,88 @@ We can create a category which contains other categories.
] ]
) )
``` ```
where the user needs to provide the following parameters: where you need to specify:
* The name of the category.
* Array of subcategories.
* `name`: category name
* `subcategories`: array of subcategories
![category](https://user-images.githubusercontent.com/61827955/193548041-f4641d5f-44e2-40a2-9955-f69c195eec16.png) ![category](https://user-images.githubusercontent.com/61827955/193548041-f4641d5f-44e2-40a2-9955-f69c195eec16.png)
### Small Component Category
### Custom Component Category We can display small custom components (such as buttons) by declaring a `CustomCategory` object that leverages `CatalogDisplayView`:
Suppose a user wants to display a button named DemoButton from their project.
``` ```
enum DemoButtonSample { let category = CustomCategory<CatalogDisplayView<DemoButton>>(
static var demoButtonCategory: CustomCategory<CatalogDisplayView<DemoButton>> {
CustomCategory<CatalogDisplayView<DemoButton>>(
name: "Demo Button", name: "Demo Button",
models: [ models: [
CatalogDisplayView<DemoButton>.Model( .init(
title: "Login", title: "Login",
model: DemoButtonModel( model: .init(
backgroundColor: .systemBlue, backgroundColor: .systemBlue,
title: "Login", title: "Login",
titleColor: .white titleColor: .white
) )
),
.init(
title: "Logout",
model: .init(
backgroundColor: .systemRed,
cornerRadius: 25,
title: "Logout",
titleColor: .white
) )
),
] ]
) )
}
}
``` ```
where the user needs to provide the following parameters: where you need to specify:
* name for the category.
* model needed to initialise the button.
* `name`: category name
* `models`: information about the components to be displayed (in this case buttons)
![demoButton](https://user-images.githubusercontent.com/61827955/193549940-a8aa876f-4ff7-4bff-9f70-b320e2d798fe.png) ![demoButton](https://user-images.githubusercontent.com/61827955/193549940-a8aa876f-4ff7-4bff-9f70-b320e2d798fe.png)
### Custom View Category ### Medium Component Category
We can display a custom view within the catalog. We can display medium-sized custom components (such as a card or a note) by declaring a `CustomCategory` object that directly uses the view to be displayed:
Suppose a user wants to display a custom view named DemoView from their project.
``` ```
enum DemoViewSample { let category = CustomCategory<NoteView>(
static var demoViewCategory: CustomCategory<DemoView> {
CustomCategory<DemoView>(
name: "Demo View", name: "Demo View",
models: [ models: [
DemoViewModel( NoteView.Model(
title: "Grocery List", title: "Grocery List",
description: "1) apples\n 2) sugar\n 3) coffee\n 4)snacks", body: "1) apples\n 2) sugar\n 3) coffee\n 4)snacks",
backgroundColor: .systemYellow
),
NoteView.Model(
title: "Todo List",
body: ""1)Buy Grocery\n 2)Prepare meal\n 3) Call a friend\n "",
backgroundColor: .systemYellow backgroundColor: .systemYellow
) )
] ]
) )
}
}
``` ```
where the user needs to provide the following parameters: where you need to specify:
* name for the category.
* model needed to initialise the custom view. * `name`: category name
* `models`: information about the components to be displayed (in this case notes)
![customView](https://user-images.githubusercontent.com/61827955/193548024-46fb42b4-0244-45ee-89db-67526d7c080b.png) ![customView](https://user-images.githubusercontent.com/61827955/193548024-46fb42b4-0244-45ee-89db-67526d7c080b.png)
### Large Component Category
In order to display large custom components (including full-screen views and even view controllers), we need to:
### Custom View Controller category 1. Create a custom destination that returns a view controller to be presented. If your component is not a view controller, this would be a view controller that contains your component.
We can display view controllers in the catalog
1. First create a custom destination that returns the view controller
``` ```
struct CarouselDestination: Destination { struct CarouselDestination: Destination {
var navigationTitle: String? let navigationTitle: String?
var presentationStyle: Presentation = .detail let presentationStyle: Presentation = .detail
func getDestinationController() -> UIViewController { func getDestinationController() -> UIViewController {
return CarouselDemoViewController(navigationTitle: navigationTitle ?? "") CarouselDemoViewController(navigationTitle: navigationTitle)
}
init(presentationStyle: Presentation = .detail, navigationTitle: String) {
self.presentationStyle = presentationStyle
self.navigationTitle = navigationTitle
} }
} }
``` ```
2. Create a custom category for that particular view controller 2. Create a custom category for that particular view controller
``` ```
struct CarouselCategory: Classification { struct CarouselCategory: Classification {
@ -216,23 +225,16 @@ struct CarouselCategory: Classification {
var destination: Destination { var destination: Destination {
CarouselDestination(navigationTitle: name) CarouselDestination(navigationTitle: name)
} }
}
```
init(name: String) { 3. Declare an instance of the category
self.name = name
}
}
``` ```
3. Create instance of the category let category = CarouselCategory(name: "Carousel Demo View Controller")
```
enum CarouselSample {
static var category: CarouselCategory {
CarouselCategory(name: "Carousel Demo View Controller")
}
}
``` ```
![carouselViewController](https://user-images.githubusercontent.com/61827955/193548020-4b272329-e0e9-4d96-a3f4-f99f8ef751e8.png) ![carouselViewController](https://user-images.githubusercontent.com/61827955/193548020-4b272329-e0e9-4d96-a3f4-f99f8ef751e8.png)
Contributing to Y—Component-Browser Contributing to Y—Component-Browser
---------- ----------
@ -302,6 +304,11 @@ When merging a pull request:
Requirements Requirements
---------- ----------
#### SwiftLint (linter)
```
brew install swiftlint
```
### Jazzy (documentation) ### Jazzy (documentation)
``` ```
sudo gem install jazzy sudo gem install jazzy

6
Sources/YComponentBrowser/CatalogFactory.swift
View File

@ -8,12 +8,12 @@ import UIKit
/// Catalog factory to encapsulate the creation logic of catalog and controllers /// Catalog factory to encapsulate the creation logic of catalog and controllers
public enum CatalogFactory { public enum CatalogFactory {
/// Types of generic display ViewController /// Display type
public enum DisplayType { public enum DisplayType {
/// TableViewController /// Table view
case table case table
/// CollectionViewController /// Collection view
case collection(UICollectionViewLayout) case collection(UICollectionViewLayout)
} }

3
Sources/YComponentBrowser/ClassificationScene/ClassificationViewController.swift
View File

@ -11,8 +11,7 @@ public final class ClassificationViewController<DataSource: CatalogDataSource>:
public let datasource: DataSource public let datasource: DataSource
/// Initializes a classification view controller /// Initializes a classification view controller
/// - Parameters: /// - Parameter datasource: data source for the catalog view
/// - datasource: data source for the catalog view
public init(datasource: DataSource) { public init(datasource: DataSource) {
self.datasource = datasource self.datasource = datasource
super.init(nibName: nil, bundle: nil) super.init(nibName: nil, bundle: nil)

6
Sources/YComponentBrowser/Models/Categories/CatalogCategory.swift
View File

@ -6,7 +6,7 @@
import Foundation import Foundation
/// Catalog category /// Catalog category: a category that contains other subcategories
public struct CatalogCategory: Classification { public struct CatalogCategory: Classification {
/// Name of the catalog category /// Name of the catalog category
public let name: String public let name: String
@ -24,8 +24,8 @@ public struct CatalogCategory: Classification {
/// Initializes a catalog category /// Initializes a catalog category
/// - Parameters: /// - Parameters:
/// - name: Name of the category /// - name: category name
/// - subcategories: Array of sub categories /// - subcategories: array of subcategories
public init(name: String, subcategories: [Classification]) { public init(name: String, subcategories: [Classification]) {
self.name = name self.name = name
self.subcategories = subcategories self.subcategories = subcategories

6
Sources/YComponentBrowser/Models/Categories/ColorCategory.swift
View File

@ -22,10 +22,10 @@ public struct ColorCategory: Classification {
CatalogDetailDestination<View>(navigationTitle: name, models: models) CatalogDetailDestination<View>(navigationTitle: name, models: models)
} }
/// Initializes a category /// Initializes a color category
/// - Parameters: /// - Parameters:
/// - name: name of the category /// - name: color category name
/// - models: model for the components to be displayed /// - models: information about the colors to be displayed
public init(name: String, models: [View.Model]) { public init(name: String, models: [View.Model]) {
self.name = name self.name = name
self.models = models self.models = models

10
Sources/YComponentBrowser/Models/Categories/ComponentCategory.swift
View File

@ -6,7 +6,9 @@
import Foundation import Foundation
/// Category for any view that satisfies ContentView /// Category for small views that will be displayed in a table or collection view cell.
///
/// Suitable for buttons, switches, badges, and other small components.
public struct ComponentCategory<View: ContentView>: Classification { public struct ComponentCategory<View: ContentView>: Classification {
/// The type of View category supports /// The type of View category supports
public typealias DisplayView = CatalogDisplayView<View> public typealias DisplayView = CatalogDisplayView<View>
@ -22,10 +24,10 @@ public struct ComponentCategory<View: ContentView>: Classification {
CatalogDetailDestination<DisplayView>(navigationTitle: name, models: models) CatalogDetailDestination<DisplayView>(navigationTitle: name, models: models)
} }
/// Initializes a category /// Initializes a component category
/// - Parameters: /// - Parameters:
/// - name: name of the category /// - name: component category name
/// - models: model for the components to be displayed /// - models: information about the components to be displayed
public init(name: String, models: [DisplayView.Model]) { public init(name: String, models: [DisplayView.Model]) {
self.name = name self.name = name
self.models = models self.models = models

12
Sources/YComponentBrowser/Models/Categories/CustomCategory.swift
View File

@ -6,7 +6,11 @@
import Foundation import Foundation
/// Custom category for View that satisfies protocols /// Custom category for components that will not utilize `CatalogDisplayView`.
///
/// Suitable for larger components, such as cards, that might occupy an entire table view (or collection view) cell
/// by themselves.
/// Also suitable when you wish to define your own custom `ContentView` to display the component.
public struct CustomCategory<View: ContentView>: Classification { public struct CustomCategory<View: ContentView>: Classification {
/// Name of the category /// Name of the category
public let name: String public let name: String
@ -19,10 +23,10 @@ public struct CustomCategory<View: ContentView>: Classification {
CatalogDetailDestination<View>(navigationTitle: name, models: models) CatalogDetailDestination<View>(navigationTitle: name, models: models)
} }
/// Initializes a category /// Initializes a custom category
/// - Parameters: /// - Parameters:
/// - name: name of the category /// - name: category name
/// - models: model for the components to be displayed /// - models: information about the components to be displayed
public init(name: String, models: [View.Model]) { public init(name: String, models: [View.Model]) {
self.name = name self.name = name
self.models = models self.models = models

6
Sources/YComponentBrowser/Models/Categories/FontCategory.swift
View File

@ -22,10 +22,10 @@ public struct FontCategory: Classification {
CatalogDetailDestination<View>(navigationTitle: name, models: models) CatalogDetailDestination<View>(navigationTitle: name, models: models)
} }
/// Initializes a category /// Initializes a font category
/// - Parameters: /// - Parameters:
/// - name: name of the category /// - name: font category name
/// - models: model for the components to be displayed /// - models: information about the fonts to be displayed
public init(name: String, models: [View.Model]) { public init(name: String, models: [View.Model]) {
self.name = name self.name = name
self.models = models self.models = models

6
Sources/YComponentBrowser/Models/Categories/IconCategory.swift
View File

@ -22,10 +22,10 @@ public struct IconCategory: Classification {
CatalogDetailDestination<View>(navigationTitle: name, models: models) CatalogDetailDestination<View>(navigationTitle: name, models: models)
} }
/// Initializes a category /// Initializes an icon category
/// - Parameters: /// - Parameters:
/// - name: name of the category /// - name: icon category name
/// - models: model for the components to be displayed /// - models: information about the icons to be displayed
public init(name: String, models: [View.Model]) { public init(name: String, models: [View.Model]) {
self.name = name self.name = name
self.models = models self.models = models

4
Sources/YComponentBrowser/Protocols/Highlightable.swift
View File

@ -8,7 +8,7 @@ import Foundation
/// Represents anything that can be highlighted /// Represents anything that can be highlighted
public protocol Highlightable { public protocol Highlightable {
/// Method to set highlighted for the given UI component /// Highlights the UI component
/// - Parameter isHighlighted: bool indicating if UI component is highlighted /// - Parameter isHighlighted: whether the UI component is highlighted
func setHighlighted(_ isHighlighted: Bool) func setHighlighted(_ isHighlighted: Bool)
} }

4
Sources/YComponentBrowser/Protocols/Selectable.swift
View File

@ -8,7 +8,7 @@ import Foundation
/// Represents anything that can be selected /// Represents anything that can be selected
public protocol Selectable { public protocol Selectable {
/// Used to set isSelected for the given UI component /// Selects the given UI component
/// - Parameter isSelected: Bool indicating if UI component is selected /// - Parameter isSelected: whether the UI component is selected
func setSelected(_ isSelected: Bool) func setSelected(_ isSelected: Bool)
} }

6
Sources/YComponentBrowser/UI Components/Generic Views/CatalogDisplayView.swift
View File

@ -27,9 +27,9 @@ final public class CatalogDisplayView<View: ContentView>: UIView {
/// Initializes a catalog display view /// Initializes a catalog display view
/// - Parameters: /// - Parameters:
/// - title: title /// - title: title
/// - detail: detail description /// - detail: detail description (optional), defaults to `nil`
/// - displayViewAxis: primary axis for content view /// - axis: primary axis for the content view, defaults to .horizontal
/// - displayViewModel: model to populate the content view /// - model: model to populate the content view
public init( public init(
title: String?, title: String?,
detail: String? = nil, detail: String? = nil,

4
Sources/YComponentBrowser/UI Components/Generic Views/FontView.swift
View File

@ -8,9 +8,9 @@ import UIKit
/// A view to display a given font and text /// A view to display a given font and text
final public class FontView: UILabel { final public class FontView: UILabel {
/// Model to initialize the the `FontView` /// Font view model
public struct Model { public struct Model {
/// Default display text for FontView Model /// Default display text
public static let defaultText = "The quick brown fox jumped over the lazy dog." public static let defaultText = "The quick brown fox jumped over the lazy dog."
/// Font for the label /// Font for the label