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

285
README.md
View File

@ -1,16 +1,23 @@
![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
* [Usage](#usage)
* [Icon Category](#icon-category)
* [Font Category](#font-category)
* [Color Category](#color-category)
* [Font Category](#font-category)
* [Icon Category](#icon-category)
* [Catalog Category](#catalog-category)
* [Custom Component Category](#custom-component-category)
* [Custom View Controller Category](#custom-view-controller-category)
* [Small Component Category](#small-component-category)
* [Medium Component Category](#medium-component-category)
* [Large Component Category](#large-component-category)
* [Contributing to Y—Component-Browser](#contributing-to-ycomponent-browser)
* [Versioning Stratergy](#versioning-strategy)
* [Branching Stratergy](#branching-strategy)
@ -18,196 +25,198 @@ A standalone component browser package that intelligently displays design compon
* [Pull Requests](#pull-requests)
* [Releasing New Versions](#releasing-new-versions)
* [Requirements](#requirements)
* [Jazzy(documentation)](#jazzy-documentation)
* [SwiftLint (linter)](#swiftlint-linter)
* [Jazzy (documentation)](#jazzy-documentation)
* [Setup](#setup)
* [Generating Documentation (via Jazzy)](#generating-documentation-via-jazzy)
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 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 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()
)
)
]
)
}
}
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.
### Color category
We can display colors by declaring a `ColorCategory` object:
```
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
a user can create a color category as follows:
```
enum ColorSample {
static var category: ColorCategory {
ColorCategory(
let category = ColorCategory(
name: "Easter",
models: [
.init(
title: "Purple",
detail: "HEX: #D9D7F1",
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 you need to specify:
* `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:
```
where the user needs to provide the following parameters:
* The name of the category.
* Model for the view to be displayed
* `name`: font category name
* `models`: information about the fonts to be displayed
![EasterColor](https://user-images.githubusercontent.com/61827955/193548046-e5bfb718-1237-4558-bdbe-fbe99c889287.png)
![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
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",
subcategories: [
ColorSample.category,
IconSample.category,
FontSample.category
]
)
```
where the user needs to provide the following parameters:
* The name of the category.
* Array of subcategories.
)
```
where you need to specify:
* `name`: category name
* `subcategories`: array of subcategories
![category](https://user-images.githubusercontent.com/61827955/193548041-f4641d5f-44e2-40a2-9955-f69c195eec16.png)
### Custom Component Category
Suppose a user wants to display a button named DemoButton from their project.
### Small Component Category
We can display small custom components (such as buttons) by declaring a `CustomCategory` object that leverages `CatalogDisplayView`:
```
enum DemoButtonSample {
static var demoButtonCategory: CustomCategory<CatalogDisplayView<DemoButton>> {
CustomCategory<CatalogDisplayView<DemoButton>>(
let category = CustomCategory<CatalogDisplayView<DemoButton>>(
name: "Demo Button",
models: [
CatalogDisplayView<DemoButton>.Model(
.init(
title: "Login",
model: DemoButtonModel(
model: .init(
backgroundColor: .systemBlue,
title: "Login",
titleColor: .white
)
),
.init(
title: "Logout",
model: .init(
backgroundColor: .systemRed,
cornerRadius: 25,
title: "Logout",
titleColor: .white
)
),
]
)
}
}
)
```
where the user needs to provide the following parameters:
* name for the category.
* model needed to initialise the button.
where you need to specify:
* `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)
### Custom View Category
We can display a custom view within the catalog.
Suppose a user wants to display a custom view named DemoView from their project.
```
enum DemoViewSample {
static var demoViewCategory: CustomCategory<DemoView> {
CustomCategory<DemoView>(
### Medium Component Category
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:
```
let category = CustomCategory<NoteView>(
name: "Demo View",
models: [
DemoViewModel(
NoteView.Model(
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
)
]
)
}
}
```
where the user needs to provide the following parameters:
* name for the category.
* model needed to initialise the custom view.
)
```
where you need to specify:
* `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)
### 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
We can display view controllers in the catalog
1. First create a custom destination that returns the view controller
```
struct CarouselDestination: Destination {
var navigationTitle: String?
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.
```
struct CarouselDestination: Destination {
let navigationTitle: String?
var presentationStyle: Presentation = .detail
let presentationStyle: Presentation = .detail
func getDestinationController() -> UIViewController {
return CarouselDemoViewController(navigationTitle: navigationTitle ?? "")
}
init(presentationStyle: Presentation = .detail, navigationTitle: String) {
self.presentationStyle = presentationStyle
self.navigationTitle = navigationTitle
CarouselDemoViewController(navigationTitle: navigationTitle)
}
}
```
2. Create a custom category for that particular view controller
```
struct CarouselCategory: Classification {
@ -216,23 +225,16 @@ struct CarouselCategory: Classification {
var destination: Destination {
CarouselDestination(navigationTitle: name)
}
}
```
init(name: String) {
self.name = name
}
}
3. Declare an instance of the category
```
3. Create instance of the category
```
enum CarouselSample {
static var category: CarouselCategory {
CarouselCategory(name: "Carousel Demo View Controller")
}
}
let category = CarouselCategory(name: "Carousel Demo View Controller")
```
![carouselViewController](https://user-images.githubusercontent.com/61827955/193548020-4b272329-e0e9-4d96-a3f4-f99f8ef751e8.png)
Contributing to Y—Component-Browser
----------
@ -302,6 +304,11 @@ When merging a pull request:
Requirements
----------
#### SwiftLint (linter)
```
brew install swiftlint
```
### Jazzy (documentation)
```
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
public enum CatalogFactory {
/// Types of generic display ViewController
/// Display type
public enum DisplayType {
/// TableViewController
/// Table view
case table
/// CollectionViewController
/// Collection view
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
/// Initializes a classification view controller
/// - Parameters:
/// - datasource: data source for the catalog view
/// - Parameter datasource: data source for the catalog view
public init(datasource: DataSource) {
self.datasource = datasource
super.init(nibName: nil, bundle: nil)

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

@ -6,7 +6,7 @@
import Foundation
/// Catalog category
/// Catalog category: a category that contains other subcategories
public struct CatalogCategory: Classification {
/// Name of the catalog category
public let name: String
@ -24,8 +24,8 @@ public struct CatalogCategory: Classification {
/// Initializes a catalog category
/// - Parameters:
/// - name: Name of the category
/// - subcategories: Array of sub categories
/// - name: category name
/// - subcategories: array of subcategories
public init(name: String, subcategories: [Classification]) {
self.name = name
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)
}
/// Initializes a category
/// Initializes a color category
/// - Parameters:
/// - name: name of the category
/// - models: model for the components to be displayed
/// - name: color category name
/// - models: information about the colors to be displayed
public init(name: String, models: [View.Model]) {
self.name = name
self.models = models

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

@ -6,7 +6,9 @@
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 {
/// The type of View category supports
public typealias DisplayView = CatalogDisplayView<View>
@ -22,10 +24,10 @@ public struct ComponentCategory<View: ContentView>: Classification {
CatalogDetailDestination<DisplayView>(navigationTitle: name, models: models)
}
/// Initializes a category
/// Initializes a component category
/// - Parameters:
/// - name: name of the category
/// - models: model for the components to be displayed
/// - name: component category name
/// - models: information about the components to be displayed
public init(name: String, models: [DisplayView.Model]) {
self.name = name
self.models = models

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

@ -6,7 +6,11 @@
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 {
/// Name of the category
public let name: String
@ -19,10 +23,10 @@ public struct CustomCategory<View: ContentView>: Classification {
CatalogDetailDestination<View>(navigationTitle: name, models: models)
}
/// Initializes a category
/// Initializes a custom category
/// - Parameters:
/// - name: name of the category
/// - models: model for the components to be displayed
/// - name: category name
/// - models: information about the components to be displayed
public init(name: String, models: [View.Model]) {
self.name = name
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)
}
/// Initializes a category
/// Initializes a font category
/// - Parameters:
/// - name: name of the category
/// - models: model for the components to be displayed
/// - name: font category name
/// - models: information about the fonts to be displayed
public init(name: String, models: [View.Model]) {
self.name = name
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)
}
/// Initializes a category
/// Initializes an icon category
/// - Parameters:
/// - name: name of the category
/// - models: model for the components to be displayed
/// - name: icon category name
/// - models: information about the icons to be displayed
public init(name: String, models: [View.Model]) {
self.name = name
self.models = models

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

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

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

@ -8,7 +8,7 @@ import Foundation
/// Represents anything that can be selected
public protocol Selectable {
/// Used to set isSelected for the given UI component
/// - Parameter isSelected: Bool indicating if UI component is selected
/// Selects the given UI component
/// - Parameter isSelected: whether the UI component is selected
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
/// - Parameters:
/// - title: title
/// - detail: detail description
/// - displayViewAxis: primary axis for content view
/// - displayViewModel: model to populate the content view
/// - detail: detail description (optional), defaults to `nil`
/// - axis: primary axis for the content view, defaults to .horizontal
/// - model: model to populate the content view
public init(
title: String?,
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
final public class FontView: UILabel {
/// Model to initialize the the `FontView`
/// Font view 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."
/// Font for the label