# `LedgerUI.Components.Sidebar`
[🔗](https://github.com/devaction-labs/ledger_ui/blob/v0.2.0/lib/ledger_ui/components/sidebar.ex#L1)

The side menu of the shell, in four formats that read the same data:

  * `sections` (default): the brand with a company switcher, groups with an uppercase mono
    label, "settings and help" at the foot and the plan card.
  * `rail`: a 64px rail of icons (logo, home, one icon per group, extra apps in coloured circles,
    the foot items) beside the panel of the active module (title, create button, items, "try"
    shortcuts, trial card).
  * `tree`: the brand with a collapse button, collapsible groups, children joined by a line,
    square coloured icons and the user card at the foot.
  * `nested`: the shadcn/ui sidebar: team switcher, quiet group labels, items with children and
    the user at the foot, both able to open a menu.

        <.sidebar format="rail" nav={MyAppWeb.Nav.items(assigns)} current={@current_path}
          brand={%{name: "Ledger", logo: "S"}} user={%{name: "Marina Costa", email: "marina@ledger.com"}} />

Changing `format` changes how the menu is drawn, never the items.

## `variant`

`"floating"` (default) is the card with corners and a shadow, `"sidebar"` sits flush with a line at
its edge, `"inset"` drops the card too.

## The menu data

`nav` is a list of maps, in order. A map with `group` is a group, any other is an item.

Item keys: `label`, `icon` (a short name of the table in the README, or any icon name), `navigate`
/ `patch` / `href`, `count`, `badge`, `color`, `children`, `collapsible`, `open`, `active`,
`kbd` (a shortcut at the right), `caret` (`"down"` | `"right"`: a chevron at the end without children), `loose` (drawn outside the column of the items around it), `current`, `match` (`"exact"` | `"prefix"`), `disabled` (a "coming soon" item: a `span` with
`aria-disabled="true"`), `title`, `formats` and `style`.

Group keys: `group`, `icon`, `items`, `collapsible`, `open`, `navigate` / `patch` / `href`,
`footer: true` (the foot of the menu), `action` (`%{label, navigate, icon}`) and `try`
(`%{label, items}`) for the rail panel.

## Configuration

    config :ledger_ui, :shell, sidebar: :sections, nav: {MyAppWeb.Nav, :items}, footer: :version, version: "v1.4.2"

What you pass always wins.

## The foot

`footer`: `"user"` (the user card / the avatar of the rail), `"version"` (the version line:
a status dot, `v1.4.2`, the build and a "What's new" link; `version` is a string or
`%{version, build, navigate, label, title, status}`), `"none"`, or left out (each format's own).

## Collapsing

Every format collapses to icons (tooltips with the label, counts turn into dots) with the
`LedgerUI.Sidebar` hook: `collapsed` is the start, `on_collapse` is pushed with
`%{"id" => id, "collapsed" => boolean}`, the choice is kept in `localStorage["ledger-rail"]`
(`persist`), `rail_toggle/1` collapses it from anywhere and so does Ctrl/Cmd + `shortcut`.
Below 768px the menu is a top bar with a hamburger.

# `sidebar`

## Attributes

* `id` (`:string`) - Defaults to `"sidebar"`.
* `format` (`:any`) - Defaults to `nil`.
* `nav` (`:list`) - Defaults to `nil`.
* `current` (`:any`) - The current path, matched against the items' links; or, with `<:item>` slots, an item's `name`. Defaults to `nil`.
* `brand` (`:map`) - Defaults to `nil`.
* `workspace` (`:map`) - The workspace the menu belongs to, `%{name:, context:}`: a `brand` (the chart mark, the name and the muted context line) when `brand` is not given. Defaults to `nil`.
* `views_label` (`:string`) - The caption of the group of the `<:view>` items. Defaults to `"Views"`.
* `user` (`:map`) - Defaults to `nil`.
* `footer` (`:any`) - Defaults to `nil`.
* `show_user` (`:boolean`) - Defaults to `nil`.
* `version` (`:any`) - Defaults to `nil`.
* `plan` (`:map`) - Defaults to `nil`.
* `trial` (`:map`) - Defaults to `nil`.
* `rail_extra` (`:list`) - Defaults to `[]`.
* `collapsible` (`:boolean`) - Defaults to `true`.
* `match` (`:string`) - Defaults to `"exact"`. Must be one of `"exact"`, or `"prefix"`.
* `persist_groups` (`:boolean`) - Defaults to `false`.
* `collapsed` (`:boolean`) - Defaults to `false`.
* `persist` (`:boolean`) - Defaults to `true`.
* `on_collapse` (`:string`) - Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `shortcut` (`:string`) - Defaults to `"b"`.
* `variant` (`:string`) - Defaults to `"floating"`. Must be one of `"floating"`, `"sidebar"`, or `"inset"`.
* `label` (`:any`) - Defaults to `"Main menu"`.
* `collapse_label` (`:string`) - Defaults to `"Collapse menu"`.
* `mobile_label` (`:string`) - Defaults to `"Menu"`.
* `nav_class` (`:any`) - Classes of the column that holds the items (`lu-hl-nav` animates them). Defaults to `nil`.
* `flat` (`:boolean`) - Draws the items straight in the menu, without the column that wraps a run of them. Defaults to `false`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `item` - A link of the menu, its content the label, instead of `nav` (the same keys as an item of `nav`). Accepts attributes:

  * `icon` (`:string`)
  * `name` (`:any`) - Marks the item active when `current` is this name.
  * `navigate` (`:string`)
  * `patch` (`:string`)
  * `href` (`:string`)
  * `badge` (`:any`)
  * `count` (`:any`)
  * `tone` (`:string`) - `neg`, `pos`, `warn`, `info`: the colour of the badge.
  * `active` (`:boolean`)
  * `label` (`:string`) - The text, also the tooltip and the accessible name of the collapsed and rail menus; the content when not given.
* `view` - A saved view: an item of the group `views_label` after the `<:item>`s. Accepts attributes:

  * `icon` (`:string`)
  * `name` (`:any`)
  * `navigate` (`:string`)
  * `patch` (`:string`)
  * `href` (`:string`)
  * `count` (`:any`)
  * `label` (`:string`)
* `brand_mark` - Replaces the logo and the name of the brand.
* `mobile_drawer` - Content of the menu body shown only below 768px.
* `sidebar_footer` - At the end of the foot of the menu.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
