{"id":18789792,"url":"https://github.com/woylie/doggo","last_synced_at":"2025-05-15T15:09:37.278Z","repository":{"id":61197148,"uuid":"542117866","full_name":"woylie/doggo","owner":"woylie","description":"Headless UI components for Phoenix","archived":false,"fork":false,"pushed_at":"2024-10-19T20:53:37.000Z","size":4632,"stargazers_count":257,"open_issues_count":10,"forks_count":9,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-10-20T12:33:33.817Z","etag":null,"topics":["component-library","headless-ui","phoenix","phoenix-liveview"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/woylie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"woylie","buy_me_a_coffee":"woylie"}},"created_at":"2022-09-27T14:06:59.000Z","updated_at":"2024-10-20T11:34:44.000Z","dependencies_parsed_at":"2024-01-20T22:24:34.791Z","dependency_job_id":"3dec96db-0bfe-4d9b-a39c-71d71fbf158c","html_url":"https://github.com/woylie/doggo","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woylie%2Fdoggo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woylie%2Fdoggo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woylie%2Fdoggo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woylie%2Fdoggo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/woylie","download_url":"https://codeload.github.com/woylie/doggo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247730068,"owners_count":20986404,"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":["component-library","headless-ui","phoenix","phoenix-liveview"],"created_at":"2024-11-07T21:08:41.015Z","updated_at":"2025-04-07T21:11:54.755Z","avatar_url":"https://github.com/woylie.png","language":"Elixir","funding_links":["https://github.com/sponsors/woylie","https://buymeacoffee.com/woylie"],"categories":["Elixir"],"sub_categories":[],"readme":"# Doggo\n\n[![Hex](https://img.shields.io/hexpm/v/doggo)](https://hex.pm/packages/doggo) ![CI](https://github.com/woylie/doggo/workflows/CI/badge.svg) [![Coverage Status](https://coveralls.io/repos/github/woylie/doggo/badge.svg)](https://coveralls.io/github/woylie/doggo)\n\n\u003cimg src=\"https://github.com/woylie/doggo/raw/main/assets/doggo.png\" alt=\"Illustration of a happy Shiba Inu dog wearing a traditional Japanese kimono. The dog is centered within a circular frame, adorned with decorative patterns that include waves and stripes, indicative of a Japanese aesthetic. The Shiba Inu is smiling with its tongue out, suggesting a cheerful and playful demeanor. The kimono features bold red and white accents, complementing the dog's tan and white fur.\" width=\"200\"/\u003e\n\nHeadless UI component collection for Phoenix, focused on semantics and\naccessibility.\n\nFor a full list of available components, please refer to the\n[documentation](https://hexdocs.pm/doggo/Doggo.html).\n\n## Installation\n\nThe package can be installed by adding `doggo` to your list of dependencies in\n`mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:doggo, \"~\u003e 0.10.4\"}\n  ]\nend\n```\n\n## Usage\n\nUse `Doggo.Components` in your core components module or in a separate module.\n`Doggo.Components` defines macros that generate Phoenix components.\n\n```elixir\ndefmodule MyAppWeb.CoreComponents do\n  use Doggo.Components\n  use Phoenix.Component\n\n  build_alert()\n  build_alert_dialog()\n\n  build_button(\n    modifiers: [\n      size: [values: [\"normal\", \"small\"], default: \"normal\"]\n    ]\n  )\nend\n```\n\nEach modifier results in an additional attribute that is translated into a CSS\nclass. You can use the button defined above like this:\n\n```html\n\u003c.button size=\"small\"\u003eEdit\u003c/.button\u003e\n```\n\nMost of the components have a base class that matches the component name.\nBy default, `Doggo.modifier_class_name/2` is used to build the CSS class name\nfor modifier attributes. The button above would be rendered with the class\n`\"button is-small\"`.\n\nYou can override both the base class and the modifier class function:\n\n```elixir\ndefmodule MyAppWeb.CoreComponents do\n  use Doggo.Components\n  use Phoenix.Component\n\n  build_button(\n    base_class: \"alt-button\",\n    modifiers: [small: [size: [\"normal\", \"small\"], default: \"normal\"]],\n    class_name_fun: \u0026MyAppWeb.CoreComponents.modifier_class/2\n  )\n\n  def modifier_class(name, value) do\n    \"#{name} #{value}\"\n  end\nend\n```\n\nWith these changes, the class would now be `\"alt-button size-small`. To remove\nthe base class, just set it to `nil`.\n\nIt is also possible to change the name of the generated component, which can be\nuseful if you want to compile multiple variants of the same component, or if\nyour design system uses different names.\n\n```elixir\nbuild_button(name: :alt_button, base_class: \"alt-button\")\n```\n\nThis button could be used with:\n\n```elixir\n\u003c.alt_button\u003eEdit\u003c/.alt_button\u003e\n```\n\nRefer to the `Doggo.Components` module documentation for more information about\nthe options and the individual components.\n\n### Storybook\n\nDoggo can generate\n[Phoenix Storybook](https://hex.pm/packages/phoenix_storybook) stories for the\ngenerated components. After you followed the installation instructions of\nPhoenix Storybook, you can run a mix task to generate the stories:\n\n```bash\nmix dog.gen.stories -m MyAppWeb.CoreComponents -o storybook --all\n```\n\nHere, `MyAppWeb.CoreComponents` is the module in which you added\n`use Doggo.Components`, and `storybook` is the path to the storybook folder.\n\nThe task will only generate story modules for the components that you\nconfigured. The stories will include variations for all configured modifiers.\n\nYou don't need to update the stories after changing the modifiers of a\ncomponent. However, you'll need to run the task again after adding new\ncomponents to your module, or potentially after a new Doggo version was\nreleased.\n\nThe task will ask for confirmation to overwrite existing stories. To only\nwrite the story for a single component, you can run:\n\n```bash\nmix dog.gen.stories -m MyAppWeb.CoreComponents -o storybook -c button\n```\n\n### PurgeCSS\n\nIf you use PurgeCSS, you can get a list of CSS class names of all configured\ncomponents:\n\n```bash\nmix dog.classes -m MyAppWeb.CoreComponents -o assets/modifiers.txt\n```\n\nAdd the generated file to your PurgeCSS configuration.\n\n## Design decisions\n\n- Favor semantic HTML elements over CSS classes for structure and clarity.\n- Adhere to accessibility guidelines with appropriate ARIA attributes and roles.\n- Utilize semantic HTML and ARIA attributes for style bindings to states, rather\n  than relying on CSS classes.\n- Where state or variations can not be expressed semantically, use modifier\n  classes named `.is-*` or `.has-*`.\n- The library is designed without default styles and does not prefer any\n  particular CSS framework.\n\n## Demo app\n\nThe repository contains a demo application that renders a storybook with all\ncomponents using their default options. For some of the components, CSS was\nadded, while others are still unstyled.\n\nThe demo application is deployed at: https://doggo.wlyx.dev\n\nTo run the application locally:\n\n```bash\ngit clone git@github.com:woylie/doggo.git\ncd doggo/demo\nmix setup\nmix phx.server\n```\n\nThe storybook can be accessed at http://localhost:4000.\n\n## Status\n\nThe library is actively developed. Being in its early stages, the library may\nstill undergo significant changes, including potential breaking changes.\n\n### Maturity Levels\n\nEach component in the library is marked with one of four maturity levels.\n\n- **Experimental**: These components are in the early development phase. They\n  are incomplete, have unstable APIs, and are subject to significant changes.\n  Not recommended for production use.\n- **Developing**: Components at this stage have complete semantics, but\n  interactivity features may still be missing. The API may still change based on\n  feedback and testing. Suitable for internal testing and early feedback.\n- **Refining**: Feature-complete components with a stable API, full\n  configurability, and all required keyboard interactivity for accessibility\n  implemented. The focus is on identifying and fixing remaining issues. Suitable\n  for broader testing and cautious production use.\n- **Stable**: Fully developed, tested, and ready for production use. These\n  components have a stable API, are fully interactive, include a complete\n  storybook module, and have exemplary CSS styles defined.\n\n## Feedback\n\nIf you encounter any issues with a component, have suggestions for improvements,\nor need a component for a specific use case that isn't currently available,\nplease don't hesitate to open a\n[Github issue](https://github.com/woylie/doggo/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwoylie%2Fdoggo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwoylie%2Fdoggo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwoylie%2Fdoggo/lists"}