kingdomcoding / pyro

Phoenix components and tooling with (optional) declarative UI for Ash Framework.

Pyro

️⚠️ THIS LIBRARY IS HIGHLY EXPERIMENTAL!! ⚠️

🔥 THERE WILL BE BREAKING CHANGES!! 🔥

Phoenix components and tooling with (optional) declarative UI for Ash Framework.

Pyro's documentation is housed on hexdocs, which includes detailed installation instructions and other guides.

Dependencies

def deps do
  [
    {:pyro, "~> 0.0.4"},
    {:ash_phoenix, "~> 1.2"}, # Optional: Ash integration
    {:ash, "~> 2.8"}, # Optional: Ash integration
  ]
end

What is Pyro?

1. Component tooling for Phoenix LiveView
2. A library of pre-built components that are api-compatible replacements of core_components.ex plus additional components to cover most common UI requirements
3. An Ash extension providing a declarative UI DSL
4. A library of (optional) "smart components" that leverage 1-3 to automatically render forms/data tables/etc. for Ash resources
5. A set of default, customizable themes for all the above

For more details, check out the About page.

Roadmap

• Core components
  • back/1
  • button/1
  • error/1
  • flash/1
  • flash_group/1
  • header/1
  • icon/1
  • input/1
  • label/1
  • list/1
  • simple_form/1
  • table/1
  • modal/1
• Extra components
  • a/1
  • code/1
  • copy_to_clipboard/1
  • nav_link/1
  • progress/1
  • spinner/1
  • tooltip/1
  • Navbar/NavItem #5
  • SlideOver #4
  • Tabs #13
  • Breadcrumbs #11
  • Dark/Light theme selector #3
• Live Components
  • Pyro.Components.Autocomplete
• Smart Components
  • Pyro.Components.SmartForm
  • Pyro.Components.SmartDataTable #16
  • Pyro.Components.SmartCardGrid #10
  • Extensible AshAuthentication support #15
• DX
  • Simplified setup #2
    • Create a Tailwind plugin
    • Figure out a better way to avoid needing to include :reloadable_compilers and mix.exs compilers config
  • Strong test suite
  • More override presets
  • Code patching tools #1

Development

As long as Elixir is already installed:

git clone [e-mail]:frankdugan3/pyro.git
cd pyro
mix setup
iex -S mix phx.server

You will now have a component previewer running on http://localhost:9001 (running on that alternate port allows it to run alongside another app running the default Phoenix port). There are links to a component's hexdocs on every page in the component previewer.

Note: The component previewer is intended exclusively for Pyro development, not as a showcase to demo how to use components. So, the previewer is very clunky and has no context as it is simply intended to be a very concise way for me to verify things are working properly. The components are documented on HexDocs.

If you are working on writing docs, there is a handy watcher script you can run to automatically rebuild/reload the docs locally:

./watch_docs.sh

Welcome Contributions

• Improvements to default overrides (I am not a designer!)
• A better logo and banner
• Open issues on Github
• Things marked with TODO: in the codebase itself
• Fixes to obvious bugs/flaws
• Improvements to sloppy/redundant code
• Improvements to macros/compilers/generators/patchers
• Documentation improvements/more examples
• More tests/coverage, especially for components
• Getting mix check to pass 100%

Also open to more component ideas. Since it's easy to make your own components, there's little risk to writing your own then tossing the idea here to see if we want to pull it in officially. There is an issue template for component proposals.

Prior Art

• petal: Petal is an established project with a robust set of components, and served as a substantial inspiration for this project.
• Surface UI: Surface changed the game for LiveView. Many of its improvements have made it upstream, with the exceptions of special handling of classes and code patching tooling. Pyro has already tackled classes, and there are plans to do the same for code patching. #1
• AshAuthenticationPhoenix: The component override system is pretty awesome, and directly inspired Pyro's override system.