` element. ## Example ```heex

<:action> Add New Profile

``` """ @doc type: :component @doc since: "0.3.0" attr :title, :string, required: true, doc: "The title for the current page." attr :subtitle, :string, default: nil, doc: "An optional sub title." attr :class, :any, default: [], doc: "Additional CSS classes. Can be a string or a list of strings." attr :rest, :global, doc: "Any additional HTML attributes." slot :action, doc: "A slot for action buttons related to the current page." def page_header(assigns) do ~H""" """ end @doc """ Renders a list of properties, i.e. key/value pairs. ## Example ```heex <:prop label={gettext("Name")}>George <:prop label={gettext("Age")}>42 ``` """ @doc type: :component @doc since: "0.1.0" slot :prop, doc: "A property to be rendered." do attr :label, :string, required: true end attr :class, :any, default: [], doc: "Additional CSS classes. Can be a string or a list of strings." attr :rest, :global, doc: "Any additional HTML attributes." def property_list(assigns) do ~H"""

<%= prop.label %>: <%= render_slot(prop) %>

""" end @doc """ Renders a group of radio buttons, for example for a toolbar. To render radio buttons within a regular form, use `input/1` with the `"radio-group"` type instead. ## Example ```heex ``` ## CSS To target the wrapper, use an attribute selector: ```css [role="radio-group"] {} ``` """ @doc type: :component @doc since: "0.5.0" attr :id, :string, required: true attr :name, :string, required: true, doc: "The `name` attribute for the `input` elements." attr :label, :string, default: nil, doc: """ A accessibility label for the radio group. Set as `aria-label` attribute. You should ensure that either the `label` or the `labelledby` attribute is set. """ attr :labelledby, :string, default: nil, doc: """ The DOM ID of an element that labels this radio group. Example: ```html

Favorite Dog

<.radio_group labelledby="dog-rg-label"> ``` You should ensure that either the `label` or the `labelledby` attribute is set. """ attr :options, :list, required: true, doc: """ A list of options. It can be given a list values or as a list of `{label, value}` tuples. """ attr :value, :any, default: nil, doc: """ The currently selected value, which is compared with the option value to determine whether a radio button is checked. """ attr :class, :any, default: [], doc: "Additional CSS classes. Can be a string or a list of strings." attr :rest, :global, doc: "Any additional HTML attributes." def radio_group(assigns) do ensure_label!(assigns, "Doggo.radio_group", "Favorite Dog") ~H"""

<.radio :for={option <- @options} option={option} name={@name} id={@id} value={@value} errors={[]} description={[]} />

""" end @doc """ Renders a skeleton loader, a placeholder for content that is in the process of loading. It mimics the layout of the actual content, providing a better user experience during loading phases. ## Usage Render one of several primitive types: ```heex ``` Combine primitives for complex layouts: ```heex

``` To modify the primitives for your use cases, you can use custom classes or CSS properties: ```heex ``` ```heex ``` ## Aria-busy attribute When using skeleton loaders, apply `aria-busy="true"` to the container element that contains the skeleton layout. For standalone use, add the attribute directly to the individual skeleton loader. ## Async result component The easiest way to load data asynchronously and render a skeleton loader is to use LiveView's [async operations](`m:Phoenix.LiveView#module-async-operations`) and `Phoenix.Component.async_result/1`. Assuming you defined a card skeleton component as described above: ```heex <.async_result :let={puppy} assign={@puppy}> <:loading><.card_skeleton /> <:failed :let={_reason}>There was an error loading the puppy. ``` """ @doc type: :component @doc since: "0.3.0" attr :type, :atom, required: true, values: @skeleton_types attr :class, :any, default: [], doc: "Additional CSS classes. Can be a string or a list of strings." attr :rest, :global, doc: "Any additional HTML attributes." def skeleton(assigns) do ~H"""

""" end @doc """ Renders a horizontal or vertical resizable split pane. > #### In Development {: .warning} > > The necessary JavaScript for making this component fully functional and > accessible will be added in a future version. > > **Missing features** > > - Resize panes with the mouse > - Resize panes with the keyboard ## Examples Horizontal separator with label: ```heex ``` Horizontal separator with visible label: ```heex ``` Nested window splitters: ```heex ``` """ @doc type: :component @doc since: "0.5.0" attr :label, :string, default: nil, doc: """ An accessibility label for the separator if the primary pane has no visible label. If it has a visible label, set the `labelledby` attribute instead. Note that the label should describe the primary pane, not the resize handle. """ attr :labelledby, :string, default: nil, doc: """ If the primary pane has a visible label, set this attribute to the DOM ID of that label. Otherwise, provide a label via the `label` attribute. """ attr :id, :string, required: true attr :orientation, :string, values: ["horizontal", "vertical"], required: true attr :default_size, :integer, required: true attr :min_size, :integer, default: 0 attr :max_size, :integer, default: 100 slot :primary, required: true slot :secondary, required: true def split_pane(assigns) do ensure_label!(assigns, "Doggo.split_pane", "Sidebar") ~H"""

<%= render_slot(@primary) %>

<%= render_slot(@secondary) %>

""" end @doc """ Renders a navigation for form steps. ## Examples With patch navigation: ```heex <:step on_click={JS.patch(to: ~p"/form/step/personal-information")}> Profile <:step on_click={JS.patch(to: ~p"/form/step/delivery")}> Delivery <:step on_click={JS.patch(to: ~p"/form/step/confirmation")}> Confirmation ``` With push events: ```heex <:step on_click={JS.push("go-to-step", value: %{step: "profile"})}> Profile <:step on_click={JS.push("go-to-step", value: %{step: "delivery"})}> Delivery <:step on_click={JS.push("go-to-step", value: %{step: "confirmation"})}> Confirmation ``` """ @doc type: :navigation @doc since: "0.3.0" attr :label, :string, default: "Form steps" attr :current_step, :integer, required: true, doc: """ The current form step, zero-based index. """ attr :completed_label, :string, default: "Completed: ", doc: """ Visually hidden text that is rendered for screen readers for completed steps. """ attr :linear, :boolean, default: false, doc: """ If `true`, clickable links are only rendered for completed steps. If `false`, also upcoming steps are clickable. If you don't want any clickable links to be rendered, omit the `on_click` attribute on the `:step` slots. """ attr :class, :any, default: [], doc: "Additional CSS classes. Can be a string or a list of strings." attr :rest, :global, doc: "Any additional HTML attributes." slot :step, required: true do attr :on_click, :any, doc: """ Event name or `Phoenix.LiveView.JS` command to execute when clicking on the step. """ end def steps(assigns) do ~H""" """ end defp step_class(index, index), do: "is-current" defp step_class(index, current) when index < current, do: "is-completed" defp step_class(index, current) when index > current, do: "is-upcoming" @doc """ Renders a switch as a button. If you want to render a switch as part of a form, use the `input/1` component with the type `"switch"` instead. Note that this component only renders a button with a label, a state, and `` with the class `switch-control`. You will need to style the switch control span with CSS in order to give it the appearance of a switch. ## Examples ```heex ``` """ @doc type: :component @doc since: "0.1.0" attr :label, :string, required: true attr :on_text, :string, default: "On" attr :off_text, :string, default: "Off" attr :checked, :boolean, default: false attr :rest, :global def switch(assigns) do ~H""" """ end @doc """ Renders a simple table. ## Examples ```heex <:col :let={p} label="name"><%= p.name %> <:col :let={p} label="age"><%= p.age %> ``` """ @doc type: :component @doc since: "0.1.0" attr :id, :string, required: true attr :rows, :list, required: true, doc: "The list of items to be displayed in rows." attr :caption, :string, default: nil, doc: "Content for the `` element." attr :row_id, :any, default: nil, doc: """ Overrides the default function that retrieves the row ID from a stream item. """ attr :row_click, :any, default: nil, doc: """ Sets the `phx-click` function attribute for each row `td`. Expects to be a function that receives a row item as an argument. This does not add the `phx-click` attribute to the `action` slot. Example: ```elixir row_click={&JS.navigate(~p"/users/\#{&1}")} ``` """ attr :row_item, :any, default: &Function.identity/1, doc: """ This function is called on the row item before it is passed to the :col and :action slots. """ slot :col, required: true, doc: """ For each column to render, add one `<:col>` element. ```elixir <:col :let={pet} label="Name" field={:name} col_style="width: 20%;"> <%= pet.name %> ``` Any additional assigns will be added as attributes to the `` elements. """ do attr :label, :any, doc: "The content for the header column." attr :col_attrs, :list, doc: """ If set, a `` element is rendered and the attributes are added to the `` element of the respective column. """ end slot :action, doc: """ The slot for showing user actions in the last table column. These columns do not receive the `row_click` attribute. ```elixir <:action :let={user}> <.link navigate={~p"/users/\#{user}"}>Show ``` """ do attr :label, :string, doc: "The content for the header column." attr :col_attrs, :list, doc: """ If set, a `` element is rendered and the attributes are added to the `` element of the respective column. """ end slot :foot, doc: """ You can optionally add a `foot`. The inner block will be rendered inside a `tfoot` element. <:foot> Total: <%= @total %> """ def table(assigns) do assigns = with %{rows: %Phoenix.LiveView.LiveStream{}} <- assigns do assign(assigns, row_id: assigns.row_id || fn {id, _item} -> id end) end ~H"""

"-tbody"} phx-update={match?(%Phoenix.LiveView.LiveStream{}, @rows) && "stream"} > <%= render_slot(@foot) %>

<%= @caption %>
<%= col[:label] %>	<%= action[:label] %>
<%= render_slot(col, @row_item.(row)) %>	<%= render_slot(action, @row_item.(row)) %>

""" end @doc """ Renders navigation tabs. This component is meant for tabs that link to a different view or live action. If you want to render tabs that switch between in-page content panels, use `tabs/1` instead. ## Example ```heex <:item patch={~p"/pets/\#{@pet}"} value={[:show, :edit]} > Profile <:item patch={~p"/pets/\#{@pet}/appointments"} value={:appointments} > Appointments <:item patch={~p"/pets/\#{@pet}/messages"} value={:messages} > Messages ``` """ @doc type: :navigation @doc since: "0.2.0" attr :label, :string, default: "Tabs", doc: """ Aria label for the `

` element. The label is especially important if you have multiple `

` elements on the same page. If the page is localized, the label should be translated, too. Do not include "navigation" in the label, since screen readers will already announce the "navigation" role as part of the label. """ attr :current_value, :any, required: true, doc: """ The current value used to compare the item values with. If you use this component to patch between different view actions, this could be the `@live_action` attribute. """ attr :class, :any, default: [], doc: "Additional CSS classes. Can be a string or a list of strings." attr :rest, :global, doc: "Any additional HTML attributes." slot :item, required: true do attr :href, :string, doc: "Passed to `Phoenix.Component.link/1`." attr :navigate, :string, doc: "Passed to `Phoenix.Component.link/1`." attr :patch, :string, doc: "Passed to `Phoenix.Component.link/1`." attr :value, :any, doc: """ The value of the item is compared to the `current_value` attribute to determine whether to add the `aria-current` attribute. This can be a single value or a list of values, e.g. multiple live actions for which the item should be marked as current. """ end def tab_navigation(assigns) do ~H""" """ end @doc """ Renders tab panels. This component is meant for tabs that toggle content panels within the page. If you want to link to a different view or live action, use `tab_navigation/1` instead. > #### In Development {: .warning} > > The necessary JavaScript for making this component fully functional and > accessible will be added in a future version. > > **Missing features** > > - Roving tabindex > - Move focus with arrow keys ## Example ```heex <:panel label="Golden Retriever">

Friendly, intelligent, great with families. Origin: Scotland. Needs regular exercise.

<:panel label="Siberian Husky">

Energetic, outgoing, distinctive appearance. Origin: Northeast Asia. Loves cold climates.

<:panel label="Dachshund">

Playful, stubborn, small size. Origin: Germany. Enjoys sniffing games.

``` """ @doc type: :component @doc since: "0.5.0" attr :id, :string, required: true attr :label, :string, default: nil, doc: """ A accessibility label for the tabs. Set as `aria-label` attribute. You should ensure that either the `label` or the `labelledby` attribute is set. Do not repeat the word `tab list` or similar in the label, since it is already announced by screen readers. """ attr :labelledby, :string, default: nil, doc: """ The DOM ID of an element that labels the tabs. Example: ```html

Dogs

``` You should ensure that either the `label` or the `labelledby` attribute is set. """ attr :class, :any, default: [], doc: "Additional CSS classes. Can be a string or a list of strings." attr :rest, :global, doc: "Any additional HTML attributes." slot :panel, required: true do attr :label, :string end def tabs(assigns) do ensure_label!(assigns, "Doggo.tabs", "Dog Facts") ~H"""

""" end @doc """ Shows the tab with the given index of the `tabs/1` component with the given ID. ## Example Doggo.show_tab("my-tabs", 2) """ @doc since: "0.5.0" def show_tab(js \\ %JS{}, id, index) when is_binary(id) and is_integer(index) do other_tabs = "##{id} [role='tab']:not(##{id}-tab-#{index})" other_panels = "##{id} [role='tabpanel']:not(##{id}-panel-#{index})" js |> JS.set_attribute({"aria-selected", "true"}, to: "##{id}-tab-#{index}") |> JS.set_attribute({"tabindex", "0"}, to: "##{id}-tab-#{index}") |> JS.remove_attribute("hidden", to: "##{id}-panel-#{index}") |> JS.set_attribute({"aria-selected", "false"}, to: other_tabs) |> JS.set_attribute({"tabindex", "-1"}, to: other_tabs) |> JS.set_attribute({"hidden", "hidden"}, to: other_panels) end @doc """ Renders a button that toggles a state. Use this component to switch a feature or setting on or off, for example to toggle dark mode or mute/unmute sound. See also `button/1`, `button_link/1`, and `disclosure_button/1`. ## Examples With a `Phoenix.LiveView.JS` command: ```heex Mute ``` ## Accessibility The button state is conveyed via the `aria-pressed` attribute and the button styling. The button text should not change depending on the state. You may however include an icon that changes depending on the state. ## CSS A toggle button can be identified with an attribute selector for the `aria-pressed` attribute. ```css // any toggle button regardless of state button[aria-pressed] {} // unpressed toggle buttons button[aria-pressed="false"] {} // pressed toggle buttons button[aria-pressed="true"] {} ``` """ @doc type: :button @doc since: "0.4.0" attr :pressed, :boolean, default: false attr :on_click, JS, required: true, doc: """ Phoenix.LiveView.JS command or event name to trigger when the button is clicked. """ attr :variant, :atom, values: @variants, default: :primary attr :fill, :atom, values: @fills, default: :solid attr :size, :atom, values: @sizes, default: :normal attr :shape, :atom, values: [nil | @shapes], default: nil attr :disabled, :boolean, default: nil attr :rest, :global slot :inner_block, required: true def toggle_button(assigns) do ~H""" """ end @doc """ Renders content with a tooltip. There are different ways to render a tooltip. This component renders a `

` with the `tooltip` role, which is hidden unless the element is hovered on or focused. For example CSS for this kind of tooltip, refer to [ARIA: tooltip role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role). A simpler alternative for styled text-only tooltips is to use a data attribute and the [`attr` CSS function](https://developer.mozilla.org/en-US/docs/Web/CSS/attr). Doggo does not provide a component for that kind of tooltip, since it is controlled by attributes only. You can check [Pico CSS](https://v2.picocss.com/docs/tooltip) for an example implementation. ## Example With an inline text: ```heex

Did you know that the Labrador Retriever <:tooltip>

Labrador Retriever

Labradors are known for their friendly nature and excellent swimming abilities.

is one of the most popular dog breeds in the world?

``` If the inner block contains a link, add the `:contains_link` attribute: ```heex

Did you know that the <.link navigate={~p"/labradors"}>Labrador Retriever <:tooltip>

Labrador Retriever

Labradors are known for their friendly nature and excellent swimming abilities.

is one of the most popular dog breeds in the world?

``` """ @doc type: :component @doc since: "0.3.0" attr :id, :string, required: true attr :contains_link, :boolean, default: false, doc: """ If `false`, the component sets `tabindex="0"` on the element wrapping the inner block, so that the tooltip can be made visible by focusing the element. If the inner block already contains an element that is focusable, such as a link or a button, set this attribute to `true`. """ slot :inner_block, required: true slot :tooltip, required: true def tooltip(assigns) do ~H""" <%= render_slot(@inner_block) %> """ end @doc """ Applies a vertical margin between the child elements. ## Example ```heex

some block

some other block

``` To apply a vertical margin on nested elements as well, set `recursive` to `true`. ```heex

some nested block

another nested block

some other block

``` """ @doc type: :component @doc since: "0.1.0" slot :inner_block, required: true attr :recursive, :boolean, default: false, doc: "If `true`, the stack margins will be applied to nested elements as well." attr :class, :any, default: [], doc: "Additional CSS classes. Can be a string or a list of strings." attr :rest, :global, doc: "Any additional HTML attributes." def stack(assigns) do ~H"""

<%= render_slot(@inner_block) %>

""" end @doc """ Renders a tag, typically used for displaying labels, categories, or keywords. ## Examples Plain tag: ```heex Well-Trained ``` With icon: ```heex Puppy ``` With delete button: ```heex High Energy ``` """ @doc type: :component @doc since: "0.3.0" attr :size, :atom, values: @sizes, default: :normal attr :variant, :atom, values: [nil | @variants], default: nil attr :shape, :atom, values: [nil, :pill], default: nil slot :inner_block, required: true def tag(assigns) do ~H""" <%= render_slot(@inner_block) %> """ end @doc """ Renders a container for a set of controls. > #### In Development {: .warning} > > The necessary JavaScript for making this component fully functional and > accessible will be added in a future version. > > **Missing features** > > - Roving tabindex > - Move focus with arrow keys ## Example Direct children of this component can be any types buttons or groups of buttons. ```heex

``` """ @doc type: :component @doc since: "0.5.0" attr :label, :string, default: nil, doc: """ A accessibility label for the toolbar. Set as `aria-label` attribute. You should ensure that either the `label` or the `labelledby` attribute is set. Do not repeat the word `toolbar` in the label, since it is already announced by screen readers. """ attr :labelledby, :string, default: nil, doc: """ The DOM ID of an element that labels this tree. Example: ```html ``` You should ensure that either the `label` or the `labelledby` attribute is set. """ attr :controls, :string, default: nil, doc: """ DOM ID of the element that is controlled by this toolbar. For example, if the toolbar provides text formatting options for an editable content area, the values should be the ID of that content area. """ attr :rest, :global, doc: "Any additional HTML attributes." slot :inner_block, required: true, doc: """ Place any number of buttons, groups of buttons, toggle buttons, menu buttons, or disclosure buttons here. """ def toolbar(assigns) do ensure_label!(assigns, "Doggo.toolbar", "Dog profile actions") ~H""" """ end @doc """ Renders a hierarchical list as a tree. A good use case for this component is a folder structure. For navigation and other menus, a regular nested list should be preferred. > #### In Development {: .warning} > > The necessary JavaScript for making this component fully functional and > accessible will be added in a future version. > > **Missing features** > > - Expand and collapse nodes > - Select nodes > - Navigate tree with arrow keys ## Example ```heex Breeds <:items> Golden Retriever Labrador Retriever Characteristics <:items> Playful Loyal ``` ## CSS To target the wrapper, use an attribute selector: ```css [role="tree"] {} ``` """ @doc type: :component @doc since: "0.5.0" attr :label, :string, default: nil, doc: """ A accessibility label for the tree. Set as `aria-label` attribute. You should ensure that either the `label` or the `labelledby` attribute is set. Do not repeat the word `tree` in the label, since it is already announced by screen readers. """ attr :labelledby, :string, default: nil, doc: """ The DOM ID of an element that labels this tree. Example: ```html

Dogs

<.tree labelledby="dog-tree-label"> ``` You should ensure that either the `label` or the `labelledby` attribute is set. """ attr :class, :any, default: [], doc: "Additional CSS classes. Can be a string or a list of strings." attr :rest, :global, doc: "Any additional HTML attributes." slot :inner_block, required: true, doc: """ Slot for the root nodes of the tree. Use the `tree_item/1` component as direct children. """ def tree(assigns) do ensure_label!(assigns, "Doggo.tree", "Dog Breeds") ~H"""

<%= render_slot(@inner_block) %> """ end @doc """ Renders a tree item within a `tree/1`. This component can be used as a direct child of `tree/1` or within the `items` slot of this component. > #### In Development {: .warning} > > The necessary JavaScript for making this component fully functional and > accessible will be added in a future version. > > **Missing features** > > - Expand and collapse nodes > - Select nodes > - Navigate tree with arrow keys ## Example ```heex Breeds <:items> Golden Retriever Labrador Retriever Characteristics <:items> Playful Loyal ``` Icons can be added before the label: Breeds <:items> Golden Retriever Labrador Retriever """ @doc type: :component @doc since: "0.5.0" slot :items, doc: """ Slot for children of this item. Place one or more additional `tree_item/1` components within this slot, or omit if this is a leaf node. """ slot :inner_block, required: true, doc: """ Slot for the item label. """ def tree_item(assigns) do ~H"""

<%= render_slot(@inner_block) %>

<%= render_slot(@items) %>

""" end ## Helpers defp humanize(atom) when is_atom(atom) do atom |> Atom.to_string() |> humanize() end defp humanize(s) when is_binary(s) do if String.ends_with?(s, "_id") do s |> binary_part(0, byte_size(s) - 3) |> to_titlecase() else to_titlecase(s) end end defp to_titlecase(s) do s |> String.replace("_", " ") |> :string.titlecase() end ## Modifier classes for fill <- @fills do str = fill |> to_string() |> String.replace("_", "-") defp fill_class(unquote(fill)), do: "is-#{unquote(str)}" end for {w, h} <- @ratios do defp ratio_class({unquote(w), unquote(h)}) do "is-#{unquote(w)}-by-#{unquote(h)}" end end defp ratio_class(nil), do: nil for size <- @sizes do str = size |> to_string() |> String.replace("_", "-") defp size_class(unquote(size)), do: "is-#{unquote(str)}" end for shape <- @shapes do str = shape |> to_string() |> String.replace("_", "-") defp shape_class(unquote(shape)), do: "is-#{unquote(str)}" end defp shape_class(nil), do: nil for type <- @skeleton_types do str = type |> to_string() |> String.replace("_", "-") defp skeleton_type_class(unquote(type)), do: "is-#{unquote(str)}" end for variant <- @variants do str = variant |> to_string() |> String.replace("_", "-") defp variant_class(unquote(variant)), do: "is-#{unquote(str)}" end defp variant_class(nil), do: nil @doc false def fills, do: @fills @doc false def ratios, do: @ratios @doc false def shapes, do: @shapes @doc false def sizes, do: @sizes @doc false def skeleton_types, do: @skeleton_types @doc false def variants, do: @variants @doc false def modifier_classes do %{ fills: Enum.map(fills(), &fill_class/1), ratios: Enum.map(ratios(), &ratio_class/1), shapes: Enum.map(shapes(), &shape_class/1), sizes: Enum.map(sizes(), &size_class/1), skeleton_types: Enum.map(skeleton_types(), &skeleton_type_class/1), variants: Enum.map(variants(), &variant_class/1) } end defp ensure_label!(%{label: s, labelledby: nil}, _, _) when is_binary(s) do :ok end defp ensure_label!(%{label: nil, labelledby: s}, _, _) when is_binary(s) do :ok end defp ensure_label!(_, component, example_label) do raise Doggo.InvalidLabelError, component: component, example_label: example_label end end

<%= render_slot(@title) %>

<%= @title %>

Dog Fashion Show

Dog Actions

Sidebar