CarbonPhoenix

Phoenix LiveView function components for the Carbon Design System web components.

• CarbonPhoenix.CoreComponents - Phoenix-style core components (flash, button, input, header, table, list, icon) rendered with Carbon. Every one accepts a carbon={%{...}} map for further Carbon options.
• CarbonPhoenix.WebComponents - one generated component for every Carbon component and every option in the storybook (<Carbon.modal>, <Carbon.tile>, ...), with typed and documented assigns. Regenerate with npm install && npm run generate.
• CarbonPhoenix.Icons - the Carbon icon set, read from the @carbon/icons npm package at compile time (nothing is vendored in this repo).
• priv/static/carbon_phoenix.js - the CarbonEvents LiveView hook that forwards Carbon DOM events to the server.

Installation

1. Add the dependency (git or Hex):

   {:carbon_phoenix, github: "nyannus/carbon_phoenix"}
   # or {:carbon_phoenix, "~> 0.1"}

2. Install the Carbon npm packages in your app's assets directory. They are not bundled so you control the versions:

   npm install --prefix assets @carbon/web-components @carbon/styles @carbon/icons

   Add "cmd npm install --prefix assets" to your assets.setup alias.

   @carbon/icons is read by Elixir when carbon_phoenix compiles, so run npm before compiling the dep (deps.get, assets.setup, compile). If it was missing, run mix deps.compile carbon_phoenix --force. The directory can be overridden with CARBON_ICONS_PATH=/path/to/@carbon/icons/svg/32.

3. esbuild finds the dep's JS through NODE_PATH, which the default Phoenix config already points at deps.

4. In assets/js/app.js:

   import "@carbon/web-components/es/index.js"   // or import single components
   import "@carbon/styles/css/styles.css"        // theme tokens + IBM Plex
   import {CarbonEvents} from "carbon_phoenix"
   
   const liveSocket = new LiveSocket("/live", Socket, {
     hooks: {...colocatedHooks, CarbonEvents},
     ...
   })

   Importing the CSS makes esbuild emit priv/static/assets/js/app.css; link it from your root layout.

5. Import the components in my_app_web.ex (html_helpers):

   import CarbonPhoenix.CoreComponents
   alias CarbonPhoenix.WebComponents, as: Carbon

Usage

<.button navigate={~p"/"} kind="tertiary" icon="home">Home</.button>
<.input field={@form[:email]} type="email" helper_text="We never share it" />
<Carbon.modal id="m" open={@open} on_closed="close">
  <Carbon.modal_header>
    <Carbon.modal_heading>Hi</Carbon.modal_heading>
  </Carbon.modal_header>
</Carbon.modal>

Only HTML attributes are supported (not JS-only properties). Named slots are filled with slot="name" on the child. Component events are on_* assigns holding a LiveView event name (the element needs an id). See the "Events, slots and forms" guide.

License

Apache-2.0 (Carbon web components and icons are Apache-2.0 as well).