A hierarchical tree view: the file-explorer staple.

A tree is for data you EXPLORE, not pages you navigate to. It is a composite widget - one tab stop, arrow keys traverse it, screen readers announce it as a tree - which is exactly wrong for site navigation (the APG says so too): links belong in PetalComponents.Menu.vertical_menu/1, where Tab and aria-current do what a reader expects. Both drop straight into a PetalComponents.Sidebar.sidebar_nav/1 - the shell holds either; they never hold each other. If it's a page, it's a menu item; if it's a thing, it's a tree node.

tree/1 takes a nested list of maps and renders arbitrary depth with expand/collapse, single selection, optional connecting indent guides, and the WAI-ARIA TreeView keyboard map. Nodes need nothing but an :id and a :label; :children makes a node a branch.

<.tree
  id="files"
  label="Project files"
  show_guides
  default_expanded={["lib"]}
  items={[
    %{id: "lib", label: "lib", children: [%{id: "app.ex", label: "app.ex"}]},
    %{id: "mix.exs", label: "mix.exs"}
  ]}
/>

Node maps

Any other key rides along untouched and is handed to the :item slot, so custom rows can read whatever they need off the node.

The two expansion models

Pick one. Both render identical markup and identical ARIA, so a tree can move from one to the other without a visual change.

Client-side (the default). Leave :expanded unset and seed the open branches with :default_expanded. The chevron toggles data-expanded and aria-expanded with Phoenix.LiveView.JS, and CSS animates the height. No round-trip, no assigns to keep, nothing to handle. The catch: the open/closed state lives only in the DOM, so a LiveView patch that re-renders the tree resets it to :default_expanded. Right for static trees (docs navigation, a settings outline, anything that renders once).

Server-controlled. Pass :expanded (a list or MapSet of branch ids) and an :on_expand event name. The chevron pushes that event with the node id in phx-value-id and your handle_event/3 decides what opens. Required for :lazy branches, whose children only exist after the server has been asked for them, and for any tree that has to survive phx-update patches.

def handle_event("toggle", %{"id" => id}, socket) do
  {:noreply, update(socket, :expanded, &toggle(&1, id))}
end

Clicking a row

Either model, clicking anywhere on a branch row toggles that branch, and when selection is wired the same click also selects it - one click, both outcomes, the way a folder behaves in VS Code or Finder. That is what :expand_on_click turns on and it defaults to true, because a row-sized hit target is what people expect from a file tree and hunting a 16px chevron is the worse default. Set expand_on_click={false} for rows whose click already has a job - a link tree that must navigate, a row with its own controls - and expansion goes back to the chevron alone. The chevron toggles and never selects in both modes, leaves are untouched by either, and the keyboard map does not move: Enter/Space still selects without expanding.

Selection

Selection is single-select and always server-owned: pass the chosen id as :selected and give :select_event a name to hear about clicks (the node id arrives as phx-value-id). The component also flips aria-selected and the selected class client-side on click, so the highlight lands immediately rather than a round-trip later. :on_select composes your own JS commands onto that.

Selection only exists when you wire it: with none of :selected, :select_event or :on_select set, the tree is purely navigational - nodes carry no aria-selected at all (per the APG, a tree that does not support selection must not announce it) and label clicks do nothing.

Keyboard

The PetalTree hook implements the APG map over a roving tabindex: the tree is a single tab stop and exactly one node carries tabindex="0".

Expansion and selection are JS commands and server events, not hook internals, so a tree still expands and selects with the pointer if the hook never runs.