{"id":20878868,"url":"https://github.com/codeandtheory/ycomponentbrowser","last_synced_at":"2025-12-11T22:52:08.252Z","repository":{"id":63921254,"uuid":"515087534","full_name":"codeandtheory/YComponentBrowser","owner":"codeandtheory","description":"Easily extend any project to include an intelligent design component browser.","archived":false,"fork":false,"pushed_at":"2023-05-05T10:13:27.000Z","size":426,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-18T04:35:07.252Z","etag":null,"topics":["design-system","ios-framework","ios-ui","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codeandtheory.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-07-18T07:58:08.000Z","updated_at":"2024-04-21T20:47:23.000Z","dependencies_parsed_at":"2023-10-03T05:28:44.669Z","dependency_job_id":null,"html_url":"https://github.com/codeandtheory/YComponentBrowser","commit_stats":null,"previous_names":["codeandtheory/ycomponentbrowser","yml-org/ycomponentbrowser"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeandtheory%2FYComponentBrowser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeandtheory%2FYComponentBrowser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeandtheory%2FYComponentBrowser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeandtheory%2FYComponentBrowser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeandtheory","download_url":"https://codeload.github.com/codeandtheory/YComponentBrowser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253776772,"owners_count":21962553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["design-system","ios-framework","ios-ui","swift"],"created_at":"2024-11-18T07:14:27.340Z","updated_at":"2025-12-11T22:52:03.203Z","avatar_url":"https://github.com/codeandtheory.png","language":"Swift","readme":"![Y—Component-Browser](https://user-images.githubusercontent.com/1037520/193869618-43383e11-d01f-4604-899d-6fbdb0d7dc3c.jpeg)\n[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fyml-org%2FYComponentBrowser%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/yml-org/YComponentBrowser)   [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fyml-org%2FYComponentBrowser%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/yml-org/YComponentBrowser)  \n_Easily extend any project to include an intelligent design component browser._\n\nLicensing\n----------\nY—Component Browser is licensed under the [Apache 2.0 license](LICENSE).\n\n\u003cimg src=\"https://user-images.githubusercontent.com/1037520/194286091-50f70e8b-940e-47de-ba87-1484121047db.gif\" width=\"414\" /\u003e\n\nDocumentation\n----------\nDocumentation is automatically generated from source code comments and rendered as a static website hosted via GitHub Pages at:  https://yml-org.github.io/YComponentBrowser/\n\n## Table of Contents\n* [Usage](#usage)\n     * [Color Category](#color-category)\n     * [Font Category](#font-category)\n     * [Icon Category](#icon-category)\n     * [Catalog Category](#catalog-category)\n     * [Small Component Category](#small-component-category)\n     * [Medium Component Category](#medium-component-category)\n     * [Large Component Category](#large-component-category)\n* [Contributing to Y—Component-Browser](#contributing-to-ycomponent-browser)\n     * [Versioning Stratergy](#versioning-strategy)\n     * [Branching Stratergy](#branching-strategy)\n     * [Branching Naming Conventions](#branch-naming-conventions)\n     * [Pull Requests](#pull-requests)\n     * [Releasing New Versions](#releasing-new-versions)\n* [Requirements](#requirements)\n     * [SwiftLint (linter)](#swiftlint-linter)\n     * [Jazzy (documentation)](#jazzy-documentation)\n* [Setup](#setup)\n* [Generating Documentation (via Jazzy)](#generating-documentation-via-jazzy)\n\nUsage\n----------\nA 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, `CatalogDisplayView` can display any view (populated with an associated model). The framework includes pre-defined categories for displaying common components: colors, fonts, and icons.\n\nThe catalog display view model has four parameters:\n\n* `title`: title\n* `detail`: detail description (optional), defaults to `nil`\n* `axis`: primary axis for the content view, defaults to `.horizontal`\n* `model`: model to populate the content view\n\nBy using `CustomCategory`, a larger component, such as a card view, can be shown. Each custom component might occupy a full row by itself.\n\nFor 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.\n\n### Color category\nWe can display colors by declaring a `ColorCategory` object:\n```\nlet category = ColorCategory(\n    name: \"Easter\",\n    models: [\n        .init(\n            title: \"Purple\",\n            detail: \"HEX: #D9D7F1\",\n            model: UIColor(red: 217/255, green: 215/255, blue: 241/255, alpha: 1)\n        ),\n        .init(\n            title: \"Light Yellow\",\n            detail: \"HEX: #FFFDDE\",\n            model: UIColor(red: 1, green: 253/255, blue: 222/255, alpha: 1)\n        )\n    ]\n)\n```  \nwhere you need to specify:\n\n* `name`: color category name\n* `models`: information about the colors to be displayed\n\n![Easter colors](https://user-images.githubusercontent.com/61827955/193548046-e5bfb718-1237-4558-bdbe-fbe99c889287.png)\n\n### Font Category\nWe can display fonts by declaring a `FontCategory` object:\n```\nlet category = FontCategory(\n    name: \"TiemposHeadline Bold\",\n    models: [\n        .init(\n            title: \"Title 1\",\n            model: FontView.Model(\n                font: UIFont(name: \"TiemposHeadline-Bold\", size: 36)!\n            )\n        ),\n        .init(\n            title: \"Title 2\",\n            model: FontView.Model(\n                font: UIFont(name: \"TiemposHeadline-Bold\", size: 26)!\n            )\n        )\n    ]\n)\n```  \nwhere you need to specify:\n\n* `name`: font category name\n* `models`: information about the fonts to be displayed\n\n![Tiempos Headline Bold fonts](https://user-images.githubusercontent.com/61827955/193548426-a1e98f0e-4bb1-434e-9d65-9b4e46f554ea.png)\n\n### Icon Category\nWe can display icons by declaring an `IconCategory` object:\n```\nlet category = IconCategory(\n    name: \"Media\",\n    models: [\n        .init(\n            title: \"Play\",\n            model: UIImage(systemName: \"play.fill\")!\n        ),\n        .init(\n            title: \"Pause\",\n            model: UIImage(systemName: \"pause.fill\")!\n        )\n    ]\n)\n```  \nwhere you need to specify:\n\n* `name`: icon category name\n* `models`: information about the icons to be displayed\n\n![Media icons](https://user-images.githubusercontent.com/61827955/193548051-8da7a620-899b-4f5f-97c0-c998028946bc.png)\n\n### Catalog Category\nWe can display nested subcategories by declaring a `CatalogCategory` object:\n```\nlet category = CatalogCategory(\n    name: \"Foundational\",\n    subcategories: [\n        ColorSample.category,\n        IconSample.category,\n        FontSample.category\n    ]\n)\n```  \nwhere you need to specify:\n\n* `name`: category name\n* `subcategories`: array of subcategories\n\n![category](https://user-images.githubusercontent.com/61827955/193548041-f4641d5f-44e2-40a2-9955-f69c195eec16.png)\n\n### Small Component Category\nWe can display small custom components (such as buttons) by declaring a `CustomCategory` object that leverages `CatalogDisplayView`:\n```\nlet category = CustomCategory\u003cCatalogDisplayView\u003cDemoButton\u003e\u003e(\n    name: \"Demo Button\",\n    models: [\n        .init(\n            title: \"Login\",\n            model: .init(\n                backgroundColor: .systemBlue,\n                title: \"Login\",\n                titleColor: .white\n            )\n        ),\n        .init(\n            title: \"Logout\",\n            model: .init(\n                backgroundColor: .systemRed,\n                cornerRadius: 25,\n                title: \"Logout\",\n                titleColor: .white\n            )\n        ),\n    ]\n)\n```  \nwhere you need to specify:\n\n* `name`: category name\n* `models`: information about the components to be displayed (in this case buttons)\n\n![demoButton](https://user-images.githubusercontent.com/61827955/193549940-a8aa876f-4ff7-4bff-9f70-b320e2d798fe.png)\n\n### Medium Component Category\nWe 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:\n```\nlet category = CustomCategory\u003cNoteView\u003e(\n    name: \"Demo View\",\n    models: [\n        NoteView.Model(\n            title: \"Grocery List\",\n            body: \"1) apples\\n 2) sugar\\n 3) coffee\\n 4)snacks\",\n            backgroundColor: .systemYellow\n        ),\n        NoteView.Model(\n            title: \"Todo List\",\n            body: \"\"1)Buy Grocery\\n 2)Prepare meal\\n 3) Call a friend\\n \"\",\n            backgroundColor: .systemYellow\n        )\n    ]\n)\n```  \nwhere you need to specify:\n\n* `name`: category name\n* `models`: information about the components to be displayed (in this case notes)\n\n![customView](https://user-images.githubusercontent.com/61827955/193548024-46fb42b4-0244-45ee-89db-67526d7c080b.png)\n\n### Large Component Category\nIn order to display large custom components (including full-screen views and even view controllers), we need to:\n\n1. 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.\n```\nstruct CarouselDestination: Destination {\n    let navigationTitle: String?\n    \n    let presentationStyle: Presentation = .detail\n    \n    func getDestinationController() -\u003e UIViewController {\n        CarouselDemoViewController(navigationTitle: navigationTitle)\n    }\n}\n```\n\n2. Create a custom category for that particular view controller\n```  \nstruct CarouselCategory: Classification {\n    let name: String\n    \n    var destination: Destination {\n        CarouselDestination(navigationTitle: name)\n    }\n}\n```\n\n3. Declare an instance of the category \n```\nlet category = CarouselCategory(name: \"Carousel Demo View Controller\")\n```\n\n![carouselViewController](https://user-images.githubusercontent.com/61827955/193548020-4b272329-e0e9-4d96-a3f4-f99f8ef751e8.png)\n\nContributing to Y—Component-Browser\n----------\n\n### Versioning strategy\n\nWe utilize [semantic versioning](https://semver.org).\n\n```\n{major}.{minor}.{patch}\n```\n\ne.g.\n\n```\n1.0.5\n```\n\n### Branching strategy\n\nWe utilize a simplified branching strategy for our frameworks.\n\n* main (and development) branch is `main`\n* both feature (and bugfix) branches branch off of `main`\n* feature (and bugfix) branches are merged back into `main` as they are completed and approved.\n* `main` gets tagged with an updated version # for each release\n \n### Branch naming conventions:\n\n```\nfeature/{ticket-number}-{short-description}\nbugfix/{ticket-number}-{short-description}\n```\ne.g.\n```\nfeature/CM-44-button\nbugfix/CM-236-textview-color\n```\n\n### Pull Requests\n\nPrior to submitting a pull request you should:\n\n1. Compile and ensure there are no warnings and no errors (this includes warnings from SwiftLint).\n2. Run all unit tests and confirm that everything passes.\n3. Check unit test coverage and confirm that all new / modified code is fully covered.\n4. Run `jazzy` from the command line and confirm that you have 100% documentation coverage.\n5. Consider using `git rebase -i HEAD~{commit-count}` to squash your last {commit-count} commits together into functional chunks.\n6. If HEAD of the parent branch (typically `main`) has been updated since you created your branch, use `git rebase main` to rebase your branch.\n    * _Never_ merge the parent branch into your branch.\n    * _Always_ rebase your branch off of the parent branch.\n\nWhen submitting a pull request:\n\n* Use the [provided pull request template](.github/pull_request_template.md) and populate the Introduction, Purpose, and Scope fields at a minimum.\n* If you're submitting before and after screenshots, movies, or GIF's, enter them in a two-column table so that they can be viewed side-by-side.\n\nWhen merging a pull request:\n\n* Make sure the branch is rebased (not merged) off of the latest HEAD from the parent branch. This keeps our git history easy to read and understand.\n* Make sure the branch is deleted upon merge (should be automatic).\n\n### Releasing new versions\n* Tag the corresponding commit with the new version (e.g. `1.0.5`)\n* Push the local tag to remote\n\n\nRequirements\n----------\n\n#### SwiftLint (linter)\n```\nbrew install swiftlint\n```\n\n### Jazzy (documentation)\n```\nsudo gem install jazzy\n```\n\nSetup\n----------\n\nOpen `Package.swift` in Xcode.\n\n\nGenerating Documentation (via Jazzy)\n----------\n\nYou can generate your own local set of documentation directly from the source code using the following command from Terminal:\n```\njazzy\n```\nThis generates a set of documentation under `/docs`. The default configuration is set in the default config file `.jazzy.yaml` file.\n\nTo view additional documentation options type:\n```\njazzy --help\n```\nA GitHub Action automatically runs each time a commit is pushed to `main` that runs Jazzy to generate the documentation for our GitHub page at: https://yml-org.github.io/YComponentBrowser/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeandtheory%2Fycomponentbrowser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeandtheory%2Fycomponentbrowser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeandtheory%2Fycomponentbrowser/lists"}