Doggo Documentation

To use Doggo, include use Doggo.Components in your core components module (or a dedicated module). Doggo.Components provides macros that generate Phoenix components with built-in support for modifiers, base classes, and custom naming.

Modifiers and Data Attributes

Modifiers are defined in the macro and are translated into data-* attributes on the rendered HTML.

• Standard modifiers: The value is converted to a string and added as a data attribute (e.g., size: "small" becomes data-size="small").
• Boolean modifiers: If the type is set to :boolean, the attribute is added as a presence-only attribute if true, and omitted if false or omitted.

Customizing Components

• base_class: Most components have a default base class matching their name. You can override this with a string or remove it by setting it to nil.
• name: You can change the name of the generated component (e.g., from build_button to build_alt_button) to allow multiple variants or to match your design system.

defmodule MyAppWeb.CoreComponents do
  use Doggo.Components
  use Phoenix.Component

  # Basic component with modifiers
  build_button(
    modifiers: [
      size: [values: ["normal", "small"], default: "normal"]
    ]
  )

  # Boolean modifier example
  build_button(modifiers: [full_width: [type: :boolean]])

  # Overriding base class and name
  build_button(
    name: :alt_button,
    base_class: "alt-button",
    modifiers: [size: [values: ["normal", "small"], default: "normal"]]
  )
end

The Doggo.Components.MenuBar component renders a menu bar similar to those found in desktop applications. It is intended for organizing application actions rather than site navigation.

To use it, wrap your menu buttons and menus within the <.menu_bar> component using the :item slot. You can use the :item slot to provide menu buttons, groups, or visual separators.

Accessibility Requirements: You must provide either a label or a labelledby attribute to ensure the component is accessible. label sets the aria-label, while labelledby sets aria-labelledby to the ID of an existing element.

<.menu_bar label="Main">
  <:item>
    <.menu_button controls="actions-menu" id="actions-button">
      Actions
    </.menu_button>

    <.menu id="actions-menu" labelledby="actions-button" hidden>
      <:item>
        <.menu_item on_click={JS.push("view-dog-profiles")}>
          View Dog Profiles
        </.menu_item>
      </:item>
      <:item>
        <.menu_item on_click={JS.push("add-dog-profile")}>
          Add Dog Profile
        </.menu_item>
      </:item>
      <:item>
        <.menu_item on_click={JS.push("dog-care-tips")}>
          Dog Care Tips
        </.menu_item>
      </:item>
    </.menu>
  </:item>
  <:item role="separator"></:item>
  <:item>
    <.menu_item on_click={JS.dispatch("myapp:help")}>
      Help
    </.menu_item>
  </:item>
</.menu_bar>

The Doggo.Components.Steps component renders a navigation list for multi-step forms. It supports two primary interaction patterns: using Phoenix.LiveView.JS.patch/1 for URL-based navigation or Phoenix.LiveView.JS.push/2 for sending LiveView events.

Interaction Patterns

1. Patch Navigation (URL-based): Use this when each step corresponds to a unique URL path.

<.steps current_step={0}>
  <:step on_click={JS.patch(to: ~p"/form/step/personal-information")}>
    Profile
  </:step>
  <:step on_click={JS.patch(to: ~p"/form/step/delivery")}>
    Delivery
  </:step>
  <:step on_click={JS.patch(to: ~p"/form/step/confirmation")}>
    Confirmation
  </:step>
</.steps>

2. Push Events (LiveView-based): Use this when you want to trigger a specific LiveView event (e.g., go-to-step) with a payload.

<.steps current_step={0}>
  <:step on_click={JS.push("go-to-step", value: %{step: "profile"})}>
    Profile
  </:step>
  <:step on_click={JS.push("go-to-step", value: %{step: "delivery"})}>
    Delivery
  </:step>
  <:step on_click={JS.push("go-to-step", value: %{step: "confirmation"})}>
    Confirmation
  </:step>
</.steps>