# Panel rail

A bar of panel toggles at the frame's end edge, for AppLayout's `panelRail`: each item opens its panel beside the page, and pressing the open one closes it. It is a toolbar, not navigation: one tab stop, Up and Down between items, Home and End to the ends, and each item a button with `aria-expanded` (never the current page).

Items are icon-only, each at least 44 px square: the label is the item's name and shows in a tooltip on hover and focus, on the side towards the page (it moves to the other side in right to left). `labels="below"` puts the words under each icon instead, in a wider rail, for touch screens, where a tooltip never shows. An open item is tinted, with a bar in the marks colour on the edge facing the panel and, in forced colours, a Highlight outline, so it is never colour alone.

A count sits on the icon's top-end corner only when the app gives one above 0: filled in the marks colour when it is `urgent`, quiet otherwise, and always read in the name ("Comments, 3 waiting"). An item that is `locked` stays in the rail, marked `aria-disabled` and with a lock on its icon; it opens nothing, and its tooltip and description say why.

Inside an AppLayout with `panels` it reads them, and the open panel, from `useAppLayout()`. Below the layout's `panelRailAt` it draws as one "Panels" button in the banner, which opens a menu of the panels with the open one checked; the button's name counts what waits in the panels that can be opened, and each item keeps its own count. Outside an AppLayout (an editor's own layout), give it `items`, `openId`, `onOpen`, `onClose` and `controls`. The rail is 3rem wide (5rem with `labels="below"`); a brand may set `--cd-panel-rail-width`.

- Registry name: `panel-rail` (`@candor/panel-rail`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/panel-rail

## Install

```bash
npx candor-ui@4 add panel-rail
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/panel-rail`.
It brings in: app-layout, bidi, button, dropdown-menu, locale, motion, tokens, tooltip, utils.
npm packages: @base-ui/react@^1.9.0, lucide-react@^1.67.0.

## Example

```tsx
"use client"

import * as React from "react"
import { BookOpen, History, Home, MessageSquare, MessagesSquare, Search } from "lucide-react"
import { AppLayout, type AppLayoutPanel } from "@/components/candor/app-layout"
import { PanelRail } from "@/components/candor/panel-rail"
import { NavRail } from "@/components/candor/nav-rail"

const panels: AppLayoutPanel[] = [
  { id: "binder", label: "Binder", Icon: BookOpen, content: <p className="p-3 text-sm">The project's files.</p> },
  // An urgent count is filled and read in the name: "Comments, 3 waiting".
  { id: "comments", label: "Comments", Icon: MessageSquare, count: 3, urgent: true, content: <p className="p-3 text-sm">Three comments wait on you.</p> },
  { id: "search", label: "Search", Icon: Search, content: <p className="p-3 text-sm">Search the project.</p> },
  // A panel that can't be opened now stays on the rail, and says why.
  { id: "history", label: "History", Icon: History, locked: "Only the project's owners see its history.", content: <p className="p-3 text-sm">Changes</p> },
]

export default function Example() {
  // One frame at a time: a page has one main. The phone's frame is narrower than panelRailAt, so the rail is one button.
  const [size, setSize] = React.useState<"wide" | "phone">("wide")
  const [labels, setLabels] = React.useState<"tooltip" | "below">("tooltip")
  const [panelId, setPanelId] = React.useState<string | null>("comments")
  const width = size === "wide" ? 640 : 360
  return (
    <div className="flex flex-col gap-3">
      <div className="flex flex-wrap gap-4 text-xs text-muted-foreground">
        <label className="flex items-center gap-2">
          Frame
          <select
            value={size}
            onChange={(e) => {
              // On a phone an open panel is a sheet over the frame: start the phone with none open.
              setPanelId(null)
              setSize(e.target.value as "wide" | "phone")
            }}
            className="max-w-full min-w-0 rounded-md border bg-background px-2 py-1 text-foreground"
          >
            <option value="wide">Wide: the rail at the end edge</option>
            <option value="phone">Phone: one Panels button in the banner</option>
          </select>
        </label>
        <label className="flex items-center gap-2">
          Labels
          <select value={labels} onChange={(e) => setLabels(e.target.value as "tooltip" | "below")} className="max-w-full min-w-0 rounded-md border bg-background px-2 py-1 text-foreground">
            <option value="tooltip">Icons, each label in a tooltip</option>
            <option value="below">Words under the icons</option>
          </select>
        </label>
      </div>
      <div className="h-[420px] max-w-full overflow-hidden rounded-lg border" style={{ width }}>
        <AppLayout
          key={size}
          frame="app"
          // Sized for this preview box; in a full-screen app the defaults suit.
          defaultWidth={width}
          sidebarAt={560}
          panelAt={560}
          minPanel={200}
          defaultPanel={220}
          minPage={200}
          brand={<span className="flex size-8 items-center justify-center rounded-lg bg-primary text-sm font-bold text-primary-foreground">K</span>}
          sidebar={
            <NavRail
              places={[
                { id: "home", label: "Home", Icon: Home },
                { id: "chat", label: "Chat", Icon: MessagesSquare },
              ]}
              activeId="chat"
            />
          }
          top={<p className="flex h-12 items-center px-3 text-sm font-medium">Atlas</p>}
          panels={panels}
          panelId={panelId}
          onPanelIdChange={setPanelId}
          // The rail reads the panels and the open one from the layout.
          panelRail={<PanelRail labels={labels} />}
        >
          <div className="p-4 text-sm">
            <h2 className="font-semibold">Chat</h2>
            <p className="mt-2 text-muted-foreground">The rail opens a panel beside the chat; press the open item to close it.</p>
          </div>
        </AppLayout>
      </div>
    </div>
  )
}
```

## <PanelRail>

Props:

- `items?: readonly PanelRailItem[] | undefined`: The panels, in order. Left out inside an AppLayout with `panels`, which gives them.
- `openId?: string | null | undefined`: The id of the open panel, or null for none. With `items`; inside an AppLayout, its open panel.
- `onOpen?: ((id: string) => void) | undefined`: Called with an item's id when the person opens its panel, or switches to it from another. With `items`; inside an AppLayout, its `openPanel`.
- `onClose?: (() => void) | undefined`: Called when the person presses the open item to close its panel. With `items`; inside an AppLayout, its `closePanel`.
- `controls?: string | undefined`: The id of the element the open panel is drawn in, for the open item's `aria-controls`. With `items`; inside an AppLayout, its region.
- `labels?: "tooltip" | "below" | undefined` (default `"tooltip"`): Where the labels show: "tooltip" (the default), icon-only with each label in a tooltip, or "below", under each icon.
- `label?: string | undefined`: The toolbar's accessible name, and the menu button's on a narrow frame. Defaults to "Panels".
- `className?: string | undefined`: Classes for the rail, merged with Candor's.

## Strings (`panelRail`)

The fixed words, English by default. Override any of them under `panelRail` in `<LocaleProvider strings={{ panelRail: { … } }}>`; the table is exported as `panelRailStrings`.

- `panels`: Panels
- `waiting`: { one: "{label}, {count} waiting", other: "{label}, {count} waiting" }
- `counted`: { one: "{label}, {count}", other: "{label}, {count}" }

## Types

### PanelRailItem

Declared in `app-layout` and re-exported here. One of the layout's panels as a PanelRail draws it: AppLayout's `panels` without their content. `panel-rail` exports it too, so it can be imported from either.

```ts
{
  /** The panel's id: AppLayout's `panelId`, and what `openPanel` takes. */
  id: string;
  /** The panel's name: its heading, its region's name, and the rail item's name and tooltip. */
  label: string;
  /** The panel's icon, on the rail and in the panel's head. */
  Icon: LucideIcon;
  /** A count on the rail item, drawn and named only when given and above 0. */
  count?: number | undefined;
  /** The count means "needs you": drawn filled, not quiet, and named "waiting". */
  urgent?: boolean | undefined;
  /**
   * Why the panel can't be opened now. Its rail item stays, `aria-disabled`, and says why; `openPanel` ignores it. Asked
   * for through `panelId` or `defaultPanelId`, or locked while open, it isn't drawn, and `onPanelIdChange(null)` says so.
   */
  locked?: string | null | undefined;
}
```

## Motion

- **tint** (tint): An item's background and text colour change when the pointer is over it and when its panel opens or closes, and a ring fades in on keyboard focus. An item whose panel is open when the rail first appears is drawn open at once.

Set with `--cd-motion-panel-rail-<moment>-*` in your brand file; the families are in the design reference.

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.
