@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/sidebar.md

@@ -0,0 +1,88 @@
+## What it is
+
+**The app navigation rail**: a collapsible column of nav items beside a card app's content, which folds to icon width, goes off-canvas, or becomes a drawer in a narrow pane. It is shadcn's most-copied layout block, rebuilt so it works without a mouse. The family is four components in one module:
+
+- **Sidebar** is the rail itself.
+- **SidebarTrigger** is the toolbar button that toggles it.
+- **SidebarGroup** is a labelled section of the rail.
+- **SidebarItem** is a nav row that survives the collapse to icon width.
+
+Reach for a neighbour when you need something else:
+
+- **PageScaffold** (also exported as **AppShell**) is the whole page frame: masthead, navigation, main, aside, footer.
+- **Drawer** is a modal panel with no persistent rail.
+- **Tabs** is navigation within a view.
+
+## The contract
+
+```
+@open?, @defaultOpen?, @onOpenChange?, @persistKey?
+@label?, @placement? ('start' | 'end'; left/right map), @collapsible? ('rail' | 'offcanvas' | 'none')
+@width?, @railWidth?, @mobileWidth?, @mobile?, @mobileBreakpoint?
+@shortcut?, @shortcutKey?, @bordered?
+<:header> <:nav> <:footer> <:default>   — each yielded { open, collapsed, mobile }; nav and default add toggle, default adds controls
+Element: HTMLDivElement
+
+<SidebarTrigger @open @onToggle @controls @label? @size?>
+<SidebarGroup @label? @hideLabel?>        — <:default> <:action>
+<SidebarItem @label @href? @onClick? @active? @badge? @collapsed? @disabled?>   — <:icon>
+```
+
+**Collapse modes.** `rail` (the default) folds to icon width, and items keep their names with a tooltip. `offcanvas` slides the rail away entirely and removes it from the tab order and the accessibility tree with `visibility: hidden`. `none` pins it open and drops the handle.
+
+**Controlled or not.** Pass `@open` to control it, or let it keep its own state with `@defaultOpen`. `@onOpenChange` reports every toggle either way.
+
+**Persistence is opt-in and named.** With no `@persistKey` the rail touches no storage at all. With one, it writes the preference to `localStorage` and restores it on the next mount, and a stored value never overrides a controlled `@open`.
+
+**The shortcut** (Cmd/Ctrl + `@shortcutKey`, default `b`) toggles the rail. It needs the modifier, it is ignored while focus is in a text field, and `@shortcut={{false}}` turns it off. It is owned by a modifier that removes it on teardown.
+
+**Mobile is the pane, not the viewport.** The rail measures its own shell with a ResizeObserver and becomes a **Drawer** (native `<dialog>` top layer) below `@mobileBreakpoint`. A sidebar in a 400px pane folds whatever the window is doing, and `@mobile` forces either mode.
+
+**Everything is logical**, so RTL is a `dir` attribute, and the width slide lands on its end state under reduced motion.
+
+## Prior art
+
+**shadcn `Sidebar`** is 23 exports across 726 lines: Provider, Trigger, Rail, Group, Menu, MenuItem, MenuButton, MenuSkeleton and more. **Ant `Layout.Sider`** has `collapsible`, `collapsed`, `collapsedWidth`, `breakpoint` and `trigger`. **Mantine `AppShell.Navbar`** has `collapsed` and `breakpoint`.
+
+Where Pretui is better:
+
+- **The handle is keyboard reachable.** shadcn's rail button has `tabIndex={-1}`, and Ant's triggers are clickable divs with no role, so an Ant sider cannot be collapsed from the keyboard at all.
+- **State is announced.** The rail is a named `<nav>`, and every control that toggles it carries `aria-expanded` and `aria-controls`.
+- **No hidden cookie.** shadcn writes one on every toggle, unconditionally.
+- **The mobile switch measures the pane.**
+- **A collapsed rail is not tabbable.** Mantine only translates it off screen.
+- **Every dimension is an arg or a token**, not a module constant.
+
+Where it is thinner: **no menu sub-components.** There is no `SidebarMenuSub` or skeleton rows. Nest SidebarGroups, and use **Skeleton** for loading. There is **no resizable width**; use **SplitPanes**.
+
+## Accessibility
+
+APG **Disclosure** for the toggle, on a named navigation landmark.
+
+- **The rail is a `<nav>` named by `@label`.** The handle is a `<button>` in the tab order, with `aria-expanded` and `aria-controls` pointing at the rail, and a name that states the action. The tests assert the landmark, the wiring and that the name follows the state.
+- **SidebarTrigger** carries the same `aria-expanded` and `aria-controls` from outside the rail.
+- **Offcanvas collapse** removes the rail from the tab order and the tree. **Rail collapse** keeps each item's name and adds a tooltip. The tests assert both.
+- **SidebarGroup** is a `role="group"` labelled by its heading. `@hideLabel` keeps the name while hiding the text, and no label means no dangling `aria-labelledby`. The tests assert all three.
+- **SidebarItem** is a link with `aria-current="page"` when `@active` and `@href`, and a button otherwise. Disabled stays focusable and refuses to act, and a disabled link becomes a button, because a link can't be disabled. The tests assert all of these.
+- **The shortcut** needs a modifier and ignores text fields, which the tests assert.
+- **Mobile** is a **Drawer**: native focus trap, Escape and inert background.
+
+## Theming
+
+`--pretui-sidebar-width`, `--pretui-sidebar-rail-width`, `--pretui-sidebar-bg`, `--pretui-sidebar-track`, `--pretui-drawer-size` (mobile), `--pretui-selected` and `--pretui-primary-ink` (the active item), `--primary`, `--foreground`, `--muted-foreground`, `--border`, `--hover`, `--ring`, `--radius-chip`, `--control-h`, `--inset`, `--pretui-z-raised`, `--pretui-dur-morph` / `--pretui-ease-morph` (the width slide), `--pretui-dur-snap` / `--pretui-ease-snap`, the `--pretui-size-*` steps, `--font-mono`, `--track-eyebrow`, `--track-ui`, the `--text-ui-*` sizes and `--space-2` / `--space-3`.
+
+Widths are args as well as tokens. The slide is dropped under reduced motion.
+
+Sidebar, SidebarTrigger and SidebarGroup sit in `@layer PretComponent`. SidebarItem sits in `@layer PretComposite`, above Tooltip's `PretComponent` layer, so what it sets on Tooltip wins by layer order. A caller's unlayered CSS overrides all of them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                                 | Give them                                    |
+| ------------------------------------------- | -------------------------------------------- |
+| shadcn `<SidebarProvider><Sidebar>`         | `<Sidebar>`; no provider                     |
+| shadcn `<SidebarTrigger>`                   | `<SidebarTrigger @open @onToggle @controls>` |
+| shadcn `collapsible="icon" \| "offcanvas"`  | `@collapsible='rail' \| 'offcanvas'`         |
+| shadcn `SidebarGroup` / `SidebarGroupLabel` | `<SidebarGroup @label>`                      |
+| shadcn `SidebarMenuButton isActive`         | `<SidebarItem @active>`                      |
+| Ant `<Sider collapsible collapsed>`         | `<Sidebar @open>`                            |
+| Ant / Mantine `breakpoint`                  | `@mobileBreakpoint` (measured on the pane)   |

package/bundled-realms/pretui/components/sidebar.usage.gts

@@ -0,0 +1,360 @@
+// Pretui — Sidebar usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { Sidebar, SidebarGroup, SidebarItem, SidebarTrigger } from './sidebar';
+import type { ShellPlacementAlias, SidebarCollapsible } from './sidebar';
+import { FreestyleUsage } from './freestyle-usage';
+import { Toolbar } from './toolbar';
+import { LIBRARY, ORIGINS } from '../internal/structure-shell-fixtures';
+
+// ── Sidebar ──────────────────────────────────────────────────────────────
+
+export class SidebarUsage extends Component {
+  @tracked open = true;
+  @tracked collapsible = 'rail';
+  @tracked placement = 'start';
+  @tracked mobile = false;
+  @tracked bordered = true;
+  @tracked activeId = 'lib-0';
+  @tracked toggles = 0;
+
+  collapsibleOptions = ['rail', 'offcanvas', 'none'];
+  placementOptions = ['start', 'end'];
+  library = LIBRARY;
+  origins = ORIGINS;
+
+  setOpen = (v: boolean) => {
+    this.open = v;
+    this.toggles = this.toggles + 1;
+  };
+  setCollapsible = (v: string) => {
+    this.collapsible = v;
+  };
+  setPlacement = (v: string) => {
+    this.placement = v;
+  };
+  setMobile = (v: boolean) => {
+    this.mobile = v;
+  };
+  setBordered = (v: boolean) => {
+    this.bordered = v;
+  };
+  isActive = (id: string) => id === this.activeId;
+  select = (id: string) => {
+    this.activeId = id;
+  };
+  selectFor = (id: string) => () => this.select(id);
+
+  // The knob rows carry plain strings; the component takes exhaustive unions.
+  // One narrowing getter per knob keeps the cast at the boundary.
+  get collapsibleValue(): SidebarCollapsible {
+    return this.collapsible as SidebarCollapsible;
+  }
+  get placementValue(): ShellPlacementAlias {
+    return this.placement as ShellPlacementAlias;
+  }
+
+  get usage(): string {
+    return [
+      '<Sidebar',
+      "  @label='Workspace'",
+      "  @persistKey='studio'",
+      "  @collapsible='" + this.collapsible + "'",
+      "  @placement='" + this.placement + "'",
+      '>',
+      '  <:header as |bar|>…</:header>',
+      '  <:nav as |bar|>…</:nav>',
+      '  <:default as |bar|>…</:default>',
+      '</Sidebar>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Sidebar'
+      @description='App chrome: a collapsible rail beside a page. The handle on the seam is a real tab stop with a name that states the action and an aria-expanded that states the state — shadcn ships its rail with tabindex minus one and no ARIA at all, and Ant cannot collapse its sider by keyboard in any way. Cmd or Ctrl plus B toggles it, and unlike the source that shortcut stays out of the way while you are typing in a field.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='shell-stage'>
+          <Sidebar
+            @label='Workspace'
+            @open={{this.open}}
+            @onOpenChange={{this.setOpen}}
+            @collapsible={{this.collapsibleValue}}
+            @placement={{this.placementValue}}
+            @mobile={{this.mobile}}
+            @bordered={{this.bordered}}
+          >
+            <:header as |bar|>
+              <div class='shell-brand' data-compact={{if bar.collapsed 'true' 'false'}}>
+                <span class='shell-mark' aria-hidden='true'>P</span>
+                {{#unless bar.collapsed}}
+                  <span class='shell-brand-name'>Pretui Estates</span>
+                {{/unless}}
+              </div>
+            </:header>
+
+            <:nav as |bar|>
+              <SidebarGroup @label='Library' @hideLabel={{bar.collapsed}}>
+                {{#each this.library key='id' as |row|}}
+                  <SidebarItem
+                    @label={{row.label}}
+                    @badge={{unless bar.collapsed row.badge}}
+                    @active={{this.isActive row.id}}
+                    @collapsed={{bar.collapsed}}
+                    @onClick={{this.selectFor row.id}}
+                  >
+                    <:icon><span class='shell-dot' aria-hidden='true'></span></:icon>
+                  </SidebarItem>
+                {{/each}}
+              </SidebarGroup>
+
+              <SidebarGroup @label='Origins' @hideLabel={{bar.collapsed}}>
+                {{#each this.origins key='id' as |row|}}
+                  <SidebarItem
+                    @label={{row.label}}
+                    @active={{this.isActive row.id}}
+                    @collapsed={{bar.collapsed}}
+                    @onClick={{this.selectFor row.id}}
+                  >
+                    <:icon><span class='shell-dot' aria-hidden='true'></span></:icon>
+                  </SidebarItem>
+                {{/each}}
+                <SidebarItem
+                  @label='Archived origins'
+                  @disabled={{true}}
+                  @collapsed={{bar.collapsed}}
+                >
+                  <:icon><span class='shell-dot' aria-hidden='true'></span></:icon>
+                </SidebarItem>
+              </SidebarGroup>
+            </:nav>
+
+            <:footer as |bar|>
+              {{#unless bar.collapsed}}
+                <p class='shell-foot'>Pretui Estates · Catalog</p>
+              {{/unless}}
+            </:footer>
+
+            <:default as |bar|>
+              <div class='shell-page'>
+                <Toolbar @title={{this.activeId}} @eyebrow='Selected'>
+                  <SidebarTrigger
+                    @open={{bar.open}}
+                    @onToggle={{bar.toggle}}
+                    @controls={{bar.controls}}
+                    @label='workspace rail'
+                  />
+                </Toolbar>
+                <p class='shell-copy'>The rail is one grid track, so collapsing
+                  it animates the track rather than sliding a pinned panel and
+                  a matching ghost spacer. In the offcanvas mode the rail also
+                  leaves the tab order and the accessibility tree, which the
+                  libraries that only translate it off screen do not do.</p>
+                <p class='shell-copy'>Narrow this pane past the breakpoint and
+                  the rail becomes a drawer — measured from the shell&apos;s own
+                  inline size with a resize observer, not from the viewport,
+                  because a card does not know the window it is in.</p>
+                <p class='shell-count'>onOpenChange fired
+                  <b>{{this.toggles}}</b>
+                  times</p>
+              </div>
+            </:default>
+          </Sidebar>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Bool
+          @name='open'
+          @description='Controlled expanded state. Leave it undefined for the uncontrolled half; the callback fires either way.'
+          @defaultValue={{true}}
+          @value={{this.open}}
+          @onInput={{this.setOpen}}
+        />
+        <Args.Bool
+          @name='defaultOpen'
+          @description='The uncontrolled initial state.'
+          @defaultValue={{true}}
+        />
+        <Args.Action
+          @name='onOpenChange'
+          @description='Fires on every toggle with the next state.'
+        />
+        <Args.String
+          @name='persistKey'
+          @description='Persist the collapse preference under this key, namespaced in local storage. Opt-in: with no key this component reads and writes no storage at all. shadcn writes a cookie on every toggle with a hardcoded name and max age, even when the consumer controls the state, and never reads it back.'
+        />
+        <Args.String
+          @name='collapsible'
+          @description='rail shrinks to icon width and keeps the rail reachable; offcanvas removes it from layout, the tab order and the accessibility tree; none pins it open and hides the handle.'
+          @options={{this.collapsibleOptions}}
+          @value={{this.collapsible}}
+          @onInput={{this.setCollapsible}}
+          @defaultValue='rail'
+        />
+        <Args.String
+          @name='placement'
+          @description='Logical start or end. left and right are accepted and mapped, because every React kit spells this physically — but the CSS is logical, so RTL is a dir attribute rather than a second stylesheet.'
+          @options={{this.placementOptions}}
+          @value={{this.placement}}
+          @onInput={{this.setPlacement}}
+          @defaultValue='start'
+        />
+        <Args.String
+          @name='label'
+          @description='Accessible name for the rail landmark, and the noun in the handle name.'
+          @defaultValue='Sidebar'
+        />
+        <Args.String
+          @name='width'
+          @description='Expanded rail width; any kit-valid CSS length. In shadcn this is a module constant with no prop.'
+          @defaultValue='16rem'
+        />
+        <Args.String
+          @name='railWidth'
+          @description='Collapsed rail width in the rail mode.'
+          @defaultValue='3.25rem'
+        />
+        <Args.Bool
+          @name='shortcut'
+          @description='Bind the Cmd or Ctrl shortcut. With several sidebars mounted, one press toggles one rail: the one holding focus, or the first mounted when focus is in none.'
+          @defaultValue={{true}}
+        />
+        <Args.String
+          @name='shortcutKey'
+          @description='The shortcut letter, matched case-insensitively because a real browser reports b with caps off and B with shift or caps on.'
+          @defaultValue='b'
+        />
+        <Args.Bool
+          @name='mobile'
+          @description='Force the drawer mode on or off, bypassing the pane measurement. The drawer is the kit Drawer, so the focus trap, Escape and stacking come from the native dialog top layer.'
+          @defaultValue={{false}}
+          @value={{this.mobile}}
+          @onInput={{this.setMobile}}
+        />
+        <Args.Number
+          @name='mobileBreakpoint'
+          @description='Pane width in px below which the rail becomes a drawer. Measured against the shell, not the viewport.'
+          @defaultValue={{640}}
+        />
+        <Args.Bool
+          @name='bordered'
+          @description='Draw the hairline between rail and content.'
+          @defaultValue={{false}}
+          @value={{this.bordered}}
+          @onInput={{this.setBordered}}
+        />
+        <Args.Yield
+          @name='header / nav / footer / default'
+          @description='Each block is yielded a hash of open, collapsed and mobile; nav and default also get toggle, and default gets controls, the rail element id. State is passed down through block params rather than sideways through a context — there is no provider to forget and the dependency is visible in the template.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-sidebar-width'
+          @type='dimension'
+          @description='Expanded rail width.'
+          @defaultValue='16rem'
+        />
+        <Css.Basic
+          @name='pretui-sidebar-rail-width'
+          @type='dimension'
+          @description='Collapsed rail width in the rail mode.'
+          @defaultValue='3.25rem'
+        />
+        <Css.Basic
+          @name='pretui-sidebar-bg'
+          @type='color'
+          @description='The rail surface.'
+          @defaultValue='var(--inset)'
+        />
+        <Css.Basic
+          @name='pretui-drawer-size'
+          @type='dimension'
+          @description='Rail width in the mobile drawer mode.'
+          @defaultValue='360px'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+
+    <style scoped>
+      .shell-stage {
+        block-size: 340px;
+        overflow: hidden;
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+      }
+      .shell-brand {
+        display: flex;
+        align-items: center;
+        gap: var(--space-3, 8px);
+        min-inline-size: 0;
+      }
+      .shell-brand[data-compact='true'] {
+        justify-content: center;
+      }
+      .shell-mark {
+        flex: none;
+        display: grid;
+        place-items: center;
+        inline-size: 22px;
+        block-size: 22px;
+        border-radius: var(--radius-chip, 6px);
+        background: var(--primary);
+        color: var(--primary-foreground);
+        font-family: var(--font-serif);
+        font-style: italic;
+        font-weight: 600;
+      }
+      .shell-brand-name {
+        min-inline-size: 0;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+        font-weight: 600;
+      }
+      .shell-dot {
+        inline-size: 0.5em;
+        block-size: 0.5em;
+        border-radius: 50%;
+        background: currentColor;
+        opacity: 0.6;
+      }
+      .shell-foot {
+        margin: 0;
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--ink-3, var(--boxel-400));
+      }
+      .shell-page {
+        block-size: 100%;
+        overflow-y: auto;
+        padding: var(--space-5, 14px);
+        display: grid;
+        gap: var(--space-4, 11px);
+        align-content: start;
+      }
+      .shell-copy {
+        margin: 0;
+        max-inline-size: 52ch;
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.55;
+        color: var(--muted-foreground);
+      }
+      .shell-count {
+        margin: 0;
+        font-size: var(--text-ui-xs, 11px);
+        font-variant-numeric: tabular-nums;
+        color: var(--ink-3, var(--boxel-400));
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SIDEBAR: Record<string, unknown> = {
+  Sidebar: SidebarUsage,
+};