@crewlethq/ui 0.82.0 → 0.84.0

package/README.md

@@ -53,7 +53,7 @@ import { Button } from '@crewlethq/ui/Button';  // 8 KB of CSS, not 182 KB
 | Hooks and seams | `useModalLayer`, `usePopupLayer`, `LayerHost`, `useListbox`, `useOptionKeys`, `useHighlightRest` and `HIGHLIGHT_REST_MS`, `useClipboard`, `useDownload`, `downloadText`, `downloadBlob`, `safeFilename`, `toCsv`, `elementToPng` and `ElementToPngError`, `useOutcome`, `useAnnouncer`, `useNow`, `formatRelative`, `HeadingLevelProvider`, `cx`, the node hues (`NODE_HUES`, `NODE_HUE_NAMES`, `isNodeHue`) |
 | Layout | `Container`, `Section`, `Card`, `TileGrid`, `ListDetail`, `AsideLayout`, `Tabs`, `Accordion`, `Disclosure`, `Outline` (with `useActiveHeading` and `scrollToHeading`), `TreeGrid` |
 | Arranging a page | `ArrangeBoard`, `ArrangeGrid`, `ArrangeFrame` (with `useGridResize`), `ArrangeGroup`, `ArrangeList`, and the reorder hooks under them (`useReorder`, `useReorderLists`, `moveKey`) |
-| Application shell | `AppShell` with `AppShell.Rail`, the compact rail (`rail="compact"`, the one fold control from `onRailChange`, and `useAppShell().rail` to pick the shape) and `fill="flush"`, the `aside` track and the `peek` slot (`useAppShellAside`, `useAppShellPeek`), `AppShell.ResizeHandle` (also `ResizeHandle`) and `useStoredWidth`, `SidePanel` and `SidePanelFrame`, `PeekRail` and `PeekHost` (with `PeekNeighbours`, `usePeekNeighbours`, `usePeekStep`, `peekClickHandler`, `peekRowActivation`), `SectionFrame` (with `SectionFrame.Nav` and `SectionFrame.Body`), `LockedLabel`, `AppShell.Topbar`, `AppShell.AccountRow` and `useAppShell`, `AuthLayout`, `SidebarNav` and `NavItem` (with `dense` lists, `unread` and `muted` rows and `collapsible` groups), `CompactNav` with `CompactNavItem`, `CompactNavGroup` and `CompactNavSeparator` (the rail folded to its marks, fed from the same places), `DirectoryList`, `BrandLockup`, `SearchTrigger`, `PageHeader`, `Toolbar`, `Stack`, `Inline`, `Spacer`, `AutoGrid`, `ErrorBoundary`, `useShortcut`, `useFullscreen`, `useIdle`, `useMediaMatch` |
+| Application shell | `AppShell` with `AppShell.Rail`, the compact rail (`rail="compact"`, the one fold control from `onRailChange`, and `useAppShell().rail` to pick the shape) and `fill="flush"`, the `aside` track and the `peek` slot (`useAppShellAside`, `useAppShellPeek`), `AppShell.ResizeHandle` (also `ResizeHandle`) and `useStoredWidth`, `SidePanel` and `SidePanelFrame`, `PeekRail` and `PeekHost` (with `PeekNeighbours`, `usePeekNeighbours`, `usePeekStep`, `peekClickHandler`, `peekRowActivation`), `SectionFrame` (with `SectionFrame.Nav` and `SectionFrame.Body`), `DockColumn` and `usePresence`, `LockedLabel`, `AppShell.Topbar`, `AppShell.AccountRow` and `useAppShell`, `AuthLayout`, `SidebarNav` and `NavItem` (with `dense` lists, `unread` and `muted` rows and `collapsible` groups), `CompactNav` with `CompactNavItem`, `CompactNavGroup` and `CompactNavSeparator` (the rail folded to its marks, fed from the same places), `DirectoryList`, `BrandLockup`, `SearchTrigger`, `PageHeader`, `Toolbar`, `Stack`, `Inline`, `Spacer`, `AutoGrid`, `ErrorBoundary`, `useShortcut`, `useFullscreen`, `useIdle`, `useMediaMatch` |
 | Preferences | `ThemeToggle`, `ThemeSwitcher`, `DensitySwitcher`, `ThemeGallery`, `ThemeSwatch`, `useThemePreference`, `useDensityPreference`, `useSystemTheme`, `resolveTheme`, `applyStoredPreferences`, and the framework-free `applyTheme`, `applyPalette`, `applyDensity` with `THEME_PREFERENCES`, `DENSITY_PREFERENCES` and their guards |
 | Artifacts | `SandboxedFrame` (with `SandboxedFramePlaceholder` and `SandboxedFrameNotice`), `LinkInterstitial` and `openExternal`, `VersionTimeline`, `ShareDialog` with the role ladder (`ARTIFACT_ROLES`, `SHAREABLE_ROLES`, `roleAtLeast`), `PrincipalPicker`, `Principal` and `PrincipalAvatar`, `ArtifactCard`, `ArtifactKindGlyph` and `ArtifactPreviewGlyph` (the preview a card draws with no cover, for a cover with nothing to draw), `ArtifactBar` and `ArtifactVersionChip` (an open artifact's one slim bar), `ArtifactPanel` and `ArtifactWorkspace` (the panels it opens beside or over the artifact), `CanvasBoard` (a design's artboards and notes on a `Canvas`, with the visibility budget `liveBoards`), `CanvasToolbar` (a canvas's tool palette, with `toolForKey`), `LayersList` (the list of a canvas's items beside it, marked by the canvas's selection), `CanvasSchematic` (a design's cover, drawn from its boards' frames), `AccessDeniedCard`, `ArtifactIcon` (with `artifactIconGlyph` and `ARTIFACT_ICON_WORDS`), the native gallery covers (`DocCover`, `SheetCover`, `DashboardCover`), `MergeConflicts`, the dashboard pieces (`WidgetFrame`, `DatasetSource` and `DatasetSourceList`), and `FrameProtocol` (the wire between a host page and an embedded artifact, with no React in it), `ArtifactNameCell` and `ArtifactAccessLabel` (with `ArtifactAccessGlyph`) for a list of artifacts |
 | Sheets | `SheetGrid`, the cells on their own (`CheckboxCell`, `TextCell`, `LongTextCell`, `NumberCell`, `SelectCell`, `MultiSelectCell`, `PersonCell`, `StatusCell`, `DateCell`, `UrlCell`, `RatingCell`, and `SheetCell` for any type), `ChangeMark`, and `SheetModel` (every rule a sheet is drawn from, with no React in it: values, parsing, the keyboard model, TSV, the pending edits of D23) |
@@ -205,6 +205,68 @@ places:
 - A surface that pans or zooms dispatches `LAYER_REPOSITION_EVENT` on its host
   when the content beneath it moves, and every panel anchored inside follows.
 
+## Changes in 0.84.0
+
+### The application rail
+
+**The fold control is a chevron again, before the brand's mark.** The plus and minus of 0.83.0 give way to the chevrons the control drew before them, pointing left to fold the rail while it is full and right to unfold it while it is compact, and the control moves from the rail's top left corner onto the head's row, just before the brand's mark. The control and the mark are one pair, a step apart (`--spacing-1`) and centred together in the compact column, so the 76px column holds both (12, 24, 4, 24, 12) and neither moves when the rail folds; the mark's inset follows from the same arithmetic. Its names, `aria-expanded`, `aria-controls`, `aria-keyshortcuts`, the keys in its tooltip, its target floor and its ring inside its own box are unchanged. In the compact rail the lockup gives up its end inset, so the mark is all the column holds. Props are unchanged.
+
+**A badge takes a tone.** `NavItem`'s and `CompactNavItem`'s `badge` (type `NavBadge`) take `tone`, `'attention' | 'quiet'` (Count's own `CountTone`), with `attention` the default, so the inbox's accent pill is unchanged. `quiet` keeps the round pill, its size and its place on the row's end line, in the quiet count's grey: a neutral wash (`--color-fill-soft`) carrying the secondary ink, lifting to the row's ink on the reader's own row, measured on every ground a row can have in every palette. It is for work that is the reader's own and waits but does not call: My work beside the Inbox. In the compact rail a quiet badge is the tile's quiet figure, and a folded group's tile adds up only the badges that call. Story: `SidebarNav` Badge Tones.
+
+**Choosing a place in a folded group's flyout leaves focus somewhere.** The flyout closed on every choice, by a press, by the pointer resting and by the keys, but only a choice made with the keys handed focus back to the tile; a press left focus on the place's link, which went with the flyout, so the reader's next Tab started from the top of the document. Focus now follows the navigation: the destination takes it first (the place's handler, or a router that focuses the page it lands on, in its handler or its effects, often only where nothing holds focus), and only where nothing has taken it by the next frame does it go back to the tile, by a press as by a key (without a ring for a pointer reader). A place with no `href` closes like Escape, with focus straight back on the tile.
+
+**A choice does not reopen the flyout under a resting pointer.** Choosing a place closed the flyout with the pointer still on the tile or beside it, and resting there opened it again a moment later, over the page just chosen, so the flyout looked as if it had stayed open. After a choice, resting no longer opens it until the pointer has been somewhere other than the tile; a press and the keys still open it at once.
+
+### Screens that fill the window
+
+**A list's detail draws its scrollbar on the sheet's edge.** On a fill screen the scroller reserved its scrollbar's gutter and the content column padded inside it, so a `ListDetail`'s detail drew its scrollbar 31px inside the sheet beside an empty strip, and a trailing control (a header's Disconnect, a tile's Open) touched that scrollbar. A fill screen's scroller now reserves no gutter: its column pads its end by the inset plus the gutter instead, so its content stands exactly where it did, publishes that length as `--crewlet-app-shell-bleed-end`, and runs the sheet's whole width (a fill column no longer takes the `--size-content-max` measure; prose inside it keeps its own). A `ListDetail` placed directly in that column takes the length back, so its detail is the pane's outermost box and its scrollbar the sheet's last pixel. The detail reserves its gutter (`scrollbar-gutter: stable`) and keeps the screen's side inset inside itself (`--crewlet-list-detail-end`, the shell's inset by default), so its content, header actions and right-aligned section buttons end under the bar's last control whether or not it scrolls; folded to one pane, the list does the same. Only there: a `ListDetail` on a scrolling or a flush screen, or outside a shell, is as wide as its box, with nothing reserved. On a fill screen the shell reads the scrollbar's width off a hidden gauge, so the bar's controls keep their place between a fill screen and a scrolling one; a flush screen is unchanged. The bar and the column now share one inset, `--crewlet-app-shell-inset` (20px, 16px under the shell's breakpoint). Props are unchanged. Story: `ListDetail` In A Fill Screen, whose play function measures these edges.
+
+**A directory's lines clear its scrollbar.** `DirectoryList`'s groups, which scroll on their own above the foot, now reserve their scrollbar's gutter and end their lines a step (`--spacing-2`) before it, so a line's state pill no longer touches the scrollbar and does not move when the list grows long enough to scroll. Props are unchanged.
+
+### Catalogue tiles
+
+**Breaking: `CatalogTile`'s `status` is a tone and a word.** It took any node, so one row of tiles drew a service's In use as a soft pill and an app's Connected as a dot and a word, at two heights. It now takes `{ tone, label }` (type `CatalogTileStatus`, `tone` from the kit's `Tone`), and the tile draws every state the same way, the tone's dot and its word, at the caption step. On a compact tile the state stands after the name and the fact after the state on the header line; on a comfortable tile the fact stays in the foot. Pass `status={{ tone: 'success', label: 'In use' }}` where a `Tag` or a `StatusDot` was passed.
+
+### Answering in the inbox
+
+**A row taken from a group closes its height.** An `InboxGroup` keeps a keyed row that leaves its children drawn in its place, inert (focus inside it is let go), while its one track eases from `1fr` to `0fr` and it fades, on the slow step with the emphasized curve, so the rows under it slide up rather than jump; it is drawn no more once that motion has ended. The host only removes the row, in the same commit it adds it to another group. Rows need stable keys of their own, such as their ids: a row without one is told apart by its position, so it is not kept while it leaves (it goes at once), and the group says so once in development. Any keyed component child is kept as a row, so a host that draws its rows through a wrapper of its own (a memoized item) has the wrapper forward `leaving` and `onLeft` to its `InboxRow`; a plain element such as an empty state's `li` goes at once. The host's own `onLeft` on a row still runs, once, when the row has closed, which is how a host keeps a group that has emptied drawn until its last row has gone. A list of the host's own can drive the same with `InboxRow`'s `leaving` and `onLeft`. The row's content now stands in one box (`crewlet-inbox-row__body`) so its track can close over it. The motion a suite fakes is exported as `INBOX_ROW_LEAVE` (a transition of the row's own `grid-template-rows`).
+
+**An arrival is washed.** `InboxRow`'s `arrived` plays a brief wash of the accent that fades back to the row's own ground, and `InboxGroup`'s `arrived`, a token such as the arriving row's key, plays it over the group's label and count each time it changes, so a row that lands in a closed group is seen to land. Pass either only for a row that has just arrived.
+
+**`ReadingPane` moves on with its item.** `contentKey` names what the pane shows: a new value draws the item afresh and plays it in (a short fade and rise on the moderate step, `READING_PANE_ENTER` on the column), and moves focus to its title, without scrolling the page, where the reader was last in the pane (focus came into it, or a press landed in it), as after the control they answered with has gone with its item. A focused body is not taken as the pane's: Safari does not focus a pressed control and a live update moves nothing, so a reader in the list, or nowhere, keeps their place. Every change plays the item in, a return to the first item included. `focusTarget` names another place for it. `ReadingPaneTitle` is now focusable from code (`tabIndex={-1}`), never a tab stop. Under reduced motion nothing moves, and focus still follows. Story: `InboxList` Answering Moves On.
+
+### First-step cards
+
+**`ActionCard` is calmer, in light and dark.** The cards a new room opens with ("Add people and agents", "Add a description", "Start from a template") stood on saturated slabs of the kind's hue, deep purple, navy and brown on the dark sheet, under a full-hue edge and a muddy glow. Each ground is now a calm tint: the card rung, tinted by a share of the kind's hue (`--color-artifact-kind-<kind>-ground` and its steps, derived by the tokens build at 0.42 of the hue's chroma and 0.12 of its lightness from the card's neutral, 0.6 and 0.18 under the pointer, held to a chroma ceiling and to 4.5:1 for the title in every palette). The edge is the kind's own, at 3:1: its hue stepped toward the palette's ink until it clears 3:1 on the sheet and on the card's tint (`--color-artifact-kind-<kind>-edge`, derived by the tokens build), and a step further under the pointer (`-edge-strong`, against the strong tint), where the tint deepens and a small shadow lifts the card; the ring is drawn over the card's own edge. The corner and the shadow are from the edge scale (`--radius-xl`, `--shadow-xs`, `--shadow-sm` under the pointer). Every kind's drawing takes the same box, the card's width less its inset at the drawing canvas's own shape, so a tall page and a wide slide weigh the same, set a step into the card's foot on a soft shadow of the kind's Fill, with a lower halo (the glow at 0.24, was 0.46). Props are unchanged.
+
+## Changes in 0.83.0
+
+### The application rail
+
+**The fold control is a plus and a minus in the rail's top left corner.** The chevron in the row under the rail's head is gone. In its place `AppShell` draws one control in the corner the head leaves empty, up and to the left of the brand's mark: a minus (`MinusGlyph`) while the rail is full, to make it smaller, and a plus (`PlusGlyph`) while it is compact, to open it. It is the same element in both shapes and never moves, so focus stays on it across a fold. It keeps its names ("Collapse the sidebar" and "Expand the sidebar", or `railFoldLabels`), `aria-controls`, `aria-keyshortcuts` and the keys in its tooltip, and now says `aria-expanded` (true while the rail is full). It stands at the target floor (`--size-target-min`, 24px) at every density, its ring is drawn inside its own box, and it is quiet until the rail is pointed at. Full, the search field keeps the nav's own columns, since nothing stands before it any more. Props are unchanged.
+
+**The rail eases between its two shapes.** Its width moves on the slow step with the emphasized curve, the motion a `DockColumn` opens by, and what it holds keeps the width of the shape drawn, so the moving edge clips the rail's words rather than squeezing or rewrapping them, and the column under the edge never drifts. Folding, the full rail's middle, foot and status stay drawn and inert while its words fade out (focus inside them goes to the rail's first live control: the fold control, or the brand's link in the head, which stays live; with neither, the folded rail's first control once it is drawn), then the compact column fades in once the rail has moved; unfolding, the full rail is drawn at once and fades in while the edge uncovers it. The brand's mark and the fold control do not move or fade. Both shapes are a `usePresence` each, so the rail waits on the motion actually running on it, as a `DockColumn` does. `useAppShell().rail` reports the shape drawn, so it stays `full` until a fold has moved; the root's `data-rail-motion` (`fold`, `folded`, `unfold`, and `reverse` for a fold pressed again mid way, type `AppShellRailMotion`) names the phase under way. The words leave by a transition of their opacity, so a reversal brings them back from wherever their fade had reached rather than blinking them out and in; `usePresence` reports such a return as `returning`. Under reduced motion, and wherever nothing moves, the new shape is drawn at once. A change that arrives with the window crossing into the wide layout is drawn at once too. The rail's grid track is now `auto` and the rail takes `--crewlet-app-shell-rail` as its own width, which is still the one variable a host sets for a narrower rail. An aside column capped by the page's floor (`asideReserve`) now takes what the grid leaves it beside the rail's LIVE width, so it widens and narrows with the rail frame by frame, where a cap computed from the rail's variable jumped at both ends of a fold (story: `AppShellAside` Cap Follows A Folding Rail). While the rail moves the shell holds what it measures (the screen's width that `useScreenWidth` and `useScreenBelow` read, the scroller's gutter, the aside's width) and takes each once when the rail comes to rest, so no screen re-renders on every frame of a fold or changes shape mid way; a container query on the content column still follows every frame.
+
+**In the compact rail the status has a row of its own under the brand's mark**, where the fold chevron stood, rather than at the top of the foot: the `AppShell.RailStatus` dot and count, centred, a small control step tall, before the places. It keeps its button, its name ("Engine serving, 2 alarms"), its popup attributes and its ref. A panel it opens now stands at the top of the rail, so open it below the status (`side="bottom"`) in both shapes. Full, it stays at the end of the head's line.
+
+**The compact account face is centred on the tiles' line.** It took the full row's badge column and the step after it, which stood the face 4px left of the column's centre in a box 8px wider than the face. It now sits in a box of its own size, centred under the tiles. Hand the face at the tiles' height in the compact rail (`Avatar size="sm"`, 26px); the full row keeps `size="md"`.
+
+**A place that waits on the reader takes the badge, whichever place it is.** `NavItem` and `CompactNavItem` draw a `badge` as the one filled accent pill, centred on the row's line and ending on the row's end inset, so a column of badges lines up down the rail; a `count` is the quiet figure. Nothing changed in how either is drawn: to show the reader's own work as the inbox is shown, pass `badge` rather than `count`. New stories: `AppShell` Fold Control In Both Shapes, `SidebarNav` Badges On The Rows About You, and `DockColumn` (Pinned Beside A Conversation, Unpinned, At The End).
+
+### Columns that ease open and shut
+
+**`usePresence` is new**: something kept drawn while it leaves. `usePresence(shown, ref, { transitions, animations, instant })` answers `present` (draw it), `leaving` (drawn only to finish leaving: make it `inert`) and `entering` (shown again, never on the first draw, while its motion runs: the window a stylesheet scopes an entrance to). It waits only for the surface's OWN motion (`MotionOwnership`), as it is actually running (`getAnimations()`), never for a duration written in code: the transitions on `ref`'s element itself (by property; any, if `transitions` is left out) and the keyframes it names in `animations`, wherever they run under it. A motion something else inside it runs (a meter filling, a badge arriving), a paused one and an endless one (a pulse) are never waited for, a motion replaced mid way is waited out in its turn, a reopen on the way out cancels the wait, and no wait outlasts the motion's own remaining time and a margin (the fast step), so a tab hidden mid motion still settles. Under `prefers-reduced-motion: reduce`, where nothing runs, where the Web Animations API is missing, and for a change the host marks `instant`, it goes straight through in the same commit, before any paint. `afterMotion(element, done, owned)` and `runningMotion(element, owned)` are the same wait for a host with its own state, `tokenMs(motion.duration.fast)` turns a motion token into milliseconds (Tooltip and CompactNav each kept a copy), `releaseFocus(container, target)` takes focus out of something about to turn inert (to the host's `target`, or off it). The reader's motion preference is now asked through one spelling of the query, **`REDUCED_MOTION_QUERY`**, with **`prefersReducedMotion(view)`** for a read outside render, both beside `useMediaMatch`; `ChatThread`, `Outline`, `useReorder` and `TreeCanvas` use them where each kept a copy of the string. The ui-tests helper `apps/ui-tests/src/motion.ts` (`driveMotion`, `settleMotion`, `preferReducedMotion`) starts and ends motion by hand in jsdom.
+
+**`DockColumn` is new**: a column a host docks beside its content and takes away again, such as a list of rooms pinned beside a conversation. It stands in the host's own `auto` grid track (or as a flex item that does not grow) and eases its width between none and its panel's (`width`, px or any length) on the slow step with the emphasized curve, so the content beside it resizes frame by frame rather than jumping. The panel keeps its own width and is held to the edge that faces the content, so it slides in from the outer edge, and on close it stays drawn and `inert` until the column has closed over it; opened again on the way out, it is live where it is. Closed from inside (an Unpin in its own head), focus goes to `focusOnClose`, the control that docks it again, and is never left in the panel. `side` (`start`, the default, or `end`) places it, `divider` (on by default) draws the hairline on the edge that faces the content, and `--crewlet-dock-column-ground` gives the panel a ground. It is a plain column, not a landmark: what it holds names itself. Under reduced motion it simply is or is not. Types: `DockColumnProps`, `DockColumnSide`.
+
+### React
+
+**The package asks for React 19** (`react` and `react-dom` `>=19`, was `>=18`). The components already used what React 19 brought, `inert` as a boolean prop and `ref` as a plain prop of a function component and of an element (`ArrangeFrame`, `Tooltip`, `ListInput`, and now `DockColumn`, the folding rail and `Popover`), and under React 18 neither fails loudly: `inert` is dropped with a warning, so a panel on its way out stays focusable, and a ref read from props is undefined, so a trigger's own ref is lost. Every Crewlet application is on React 19. A suite holds the peer range to the source.
+
+### Refs
+
+**A trigger keeps its own ref across re-renders.** `Tooltip` cloned its trigger with a new ref callback on every render, so React took the element away from the trigger's own ref and gave it back in each commit, and a layout effect earlier in the tree read null while the control stood in the document (a `DockColumn` handing focus to a tooltip-wrapped Pin control as it closed). `Tooltip`, `Popover`, `Menu`'s trigger props and `Modal`'s frame now join their refs with **`useComposedRef(...refs)`** (new, with **`composeRefs`** for code outside a component and **`attachRef`** for one ref), one callback for any number of refs that is the same callback while they are the same and releases each the way React would. `Popover` also keeps the ref its trigger carried, which it used to replace.
+
 ## Changes in 0.82.0
 
 ### A conversation's messages

package/dist/ActionCard/ActionCard.d.ts

@@ -19,14 +19,14 @@ export interface ActionCardProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
     onSelect: () => void;
 }
 /**
- * A first step offered as a picture: a tall card on one of the kit's colour
- * grounds, its title at the top and a drawing at its foot. A new room opens
- * with a row of these (add people, add a description, start from a
- * template) until its first message.
+ * A first step offered as a picture: a tall card on a calm tint of one of
+ * the kit's kind colours, edged in the kind's hairline, its title at the top
+ * and a drawing at its foot. A new room opens with a row of these (add
+ * people, add a description, start from a template) until its first message.
  *
- * A QUIET HOVER. The ground deepens a step and a small shadow lifts the card
- * off the page; nothing moves, so a row of cards holds still under a pointer
- * passing over it.
+ * A QUIET HOVER. The tint deepens a step, the edge takes the kind's hue and a
+ * small shadow lifts the card off the page; nothing moves, so a row of cards
+ * holds still under a pointer passing over it.
  *
  * A BUTTON NAMED BY ITS TITLE. The drawing is hidden from assistive
  * technology, so a reader hears "Add people and agents, button" and nothing

package/dist/ActionCard/index.js

@@ -1,2 +1,2 @@
-export { ACTION_CARD_GROUND, ActionCard, ActionCardRow } from '../chunk-HTBTAIH6.js';
+export { ACTION_CARD_GROUND, ActionCard, ActionCardRow } from '../chunk-OM2LABPS.js';
 import '../chunk-ODEQTPFM.js';

package/dist/ActionCard-YZKL3CKR.css

@@ -0,0 +1,130 @@
+/*
+ * ActionCard: a first step offered as a picture, on a CALM TINT of an
+ * artifact kind's hue. The ground is the kind's own Ground steps
+ * (ArtifactKinds.css): the card rung tinted by a share of the hue's chroma,
+ * never a slab of it, which the palette suite holds to 4.5:1 for the primary
+ * text in every palette and both modes and to a chroma ceiling. The edge is
+ * the kind's hue stepped toward the ink until it clears 3:1, a step further
+ * under the pointer, and a soft halo of the hue stands behind the drawing.
+ */
+
+/*
+ * ONE ROW THAT SCROLLS SIDEWAYS when it runs out of width, so a phone shows
+ * two cards and part of the third (the part says there is more) instead of a
+ * tall stack. The block padding keeps the focus ring and the hover shadow
+ * inside the scroller's clip; the negative margin gives that space back to
+ * the layout. A host that runs the row to its container's edges sets the
+ * inline padding and `scroll-padding-inline` to its own inset.
+ */
+.crewlet-action-cards {
+  display: flex;
+  gap: var(--spacing-2);
+  overflow-x: auto;
+  margin-block: calc(var(--spacing-1) * -1) calc(var(--spacing-2) * -1);
+  padding-block: var(--spacing-1) var(--spacing-2);
+  scroll-snap-type: x mandatory;
+  overscroll-behavior-x: contain;
+  scrollbar-width: none;
+}
+
+.crewlet-action-cards::-webkit-scrollbar {
+  display: none;
+}
+
+.crewlet-action-card {
+  --crewlet-action-card-ground: var(--crewlet-kind-ground);
+  --crewlet-action-card-edge: var(--crewlet-kind-edge);
+  position: relative;
+  display: flex;
+  flex: none;
+  flex-direction: column;
+  justify-content: space-between;
+  width: 148px;
+  height: 172px;
+  box-sizing: border-box;
+  overflow: hidden;
+  padding: var(--spacing-3) var(--spacing-3) 0;
+  /* THE KIND'S OWN EDGE: its hue stepped toward the ink until it clears 3:1
+     on the sheet and on the card's tint (`--color-artifact-kind-<kind>-edge`,
+     derived by the tokens build and held by its suite). The Line step, the
+     hue at 0.38, did not clear it, and a neutral grey outline read as a card
+     from another family. */
+  border: 1px solid var(--crewlet-action-card-edge);
+  /* The edge scale: the extra-large corner a tall card of its own takes, and
+     the smallest shadow, so the card sits on the page rather than in it. */
+  border-radius: var(--radius-xl);
+  background-color: var(--color-surface-subtle);
+  background-image:
+    radial-gradient(90% 56% at 50% 100%, var(--crewlet-kind-glow) 0%, transparent 72%),
+    linear-gradient(180deg, var(--crewlet-action-card-ground) 0%, var(--crewlet-kind-ground-end) 100%);
+  box-shadow: var(--shadow-xs);
+  color: var(--color-text-primary);
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+  scroll-snap-align: start;
+  transition:
+    box-shadow var(--motion-duration-fast) var(--motion-easing-default),
+    border-color var(--motion-duration-fast) var(--motion-easing-default);
+}
+
+/* A QUIET HOVER: the tint deepens a step, the edge takes a stronger step of
+   the hue, and a small shadow lifts the card off the page. Nothing moves, so
+   a row of cards stays still under a pointer passing over it. */
+.crewlet-action-card:hover {
+  --crewlet-action-card-ground: var(--crewlet-kind-ground-strong);
+  --crewlet-action-card-edge: var(--crewlet-kind-edge-strong);
+  box-shadow: var(--shadow-sm);
+}
+
+/* The card draws its own edge, so the ring is drawn over it, on the same
+   corner. */
+.crewlet-action-card:focus-visible {
+  outline: 2px solid var(--color-focus);
+  outline-offset: var(--size-focus-ring-inset-offset);
+}
+
+/* The title at the medium weight, as every emphasis in a conversation is,
+   two lines at most at its width, balanced so neither line is one word. */
+.crewlet-action-card__title {
+  max-width: 14ch;
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--font-line-height-snug);
+  text-wrap: balance;
+}
+
+/*
+ * THE DRAWING STANDS ON THE CARD'S FOOT, still, the card's own width less its
+ * inset. Every kind's drawing is one canvas (160 by 120), so each takes the
+ * same box whatever its shape, a tall page and a wide slide alike, where a
+ * fixed width and a height cap drew a page half the size of a slide. It is
+ * set a step into the foot, so it stands on the edge rather than floating
+ * above it, on a soft shadow of the kind's Fill.
+ */
+.crewlet-action-card__art {
+  display: flex;
+  align-items: flex-end;
+  justify-content: center;
+  margin-bottom: calc(var(--spacing-2) * -1);
+}
+
+.crewlet-action-card__art .crewlet-kind-illustration {
+  width: 100%;
+  height: auto;
+  filter: drop-shadow(0 4px 10px var(--crewlet-kind-fill));
+}
+
+/* FORCED COLORS drops the ground and the hue; the edge is drawn in the
+   system's text colour, so the card keeps its outline. */
+@media (forced-colors: active) {
+  .crewlet-action-card {
+    border-color: CanvasText;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .crewlet-action-card {
+    transition: none;
+  }
+}

package/dist/AppShell/AccountRow.d.ts

@@ -13,6 +13,9 @@ export interface AccountRowProps {
     /**
      * The reader's badge, drawn decorative: the name beside it says who it is.
      * In a rail's foot the row is sized for a medium one (`size="md"`, 32px).
+     * In the compact rail the face stands among the compact places' tiles and
+     * takes their height, a small one (`size="sm"`, 26px), centred in the
+     * column as each tile is.
      */
     avatar: ReactNode;
     /** Who the reader is. */
@@ -73,6 +76,8 @@ export interface AccountRowProps {
  * IN THE COMPACT RAIL THE ROW IS THE READER'S FACE (`compact`): the same link
  * or menu button, holding the badge alone, named by the name and the detail
  * as the full row is, and showing them in a tooltip, since a face says who
- * it is only to somebody who already knows.
+ * it is only to somebody who already knows. The face is centred in the
+ * column on the line the tiles above it are centred on, and at their height
+ * when it is handed at the small step.
  */
 export declare function AccountRow({ avatar, name, detail, href, menu, current, title, linkSuffix, actions, compact: compactProp, className, }: AccountRowProps): import("react").JSX.Element;

package/dist/AppShell/AppShell.d.ts

@@ -63,6 +63,7 @@ import { type AppShellRailShape } from './railShape.js';
 export { useAppShellAside, useAppShellPeek } from './regions.js';
 export type { AppShellAsideShape, AppShellPeekShape, AppShellRegionValue } from './regions.js';
 export type { AppShellRailShape } from './railShape.js';
+export type { AppShellRailMotion } from './railMotion.js';
 /** The aside's resting width, in px, where the host names none. */
 export declare const APP_SHELL_ASIDE_WIDTH = 420;
 /** How the reader resizes the aside while it is a column. */
@@ -97,6 +98,8 @@ interface AppShellContextValue {
      * The shape the rail is drawn in NOW: `compact` only where the host asked
      * for it and the layout is wide, `full` in the drawer and everywhere else,
      * so an application picks `CompactNav` or `SidebarNav` from this alone.
+     * While the rail folds it is still `full`, and it turns `compact` when the
+     * rail reaches the compact column (see `railMotion.ts`).
      */
     rail: AppShellRailShape;
 }
@@ -129,15 +132,18 @@ export interface AppShellProps extends Omit<HTMLAttributes<HTMLDivElement>, 'tit
     /** The scroll container itself, for a router restoring a position. */
     mainRef?: Ref<HTMLElement> | undefined;
     /**
-     * Gives the screen the whole height left under the bar, as a flex column,
-     * for a canvas or a split view that draws to the bottom of the window
-     * instead of scrolling.
+     * Gives the screen the whole height and width left under the bar, as a flex
+     * column, for a canvas or a split view that draws to the bottom of the
+     * window instead of scrolling. The column keeps its pad, and its end pad
+     * counts the scrollbar's width, so its content stands where a scrolling
+     * screen's does; a `ListDetail` standing in it reaches past that pad, so
+     * its detail's scrollbar is on the sheet's edge.
      *
      * `flush` is the same column EDGE TO EDGE: the content column gives up its
-     * pad, its measure and its gap, and the scroller reserves no gutter, for a
-     * screen that draws its own frame to the sheet's edges (a conversation with
-     * a list and a pane either side of it). The column is positioned, so a
-     * `LayerHost` the screen keeps inside it fills exactly the screen.
+     * pad and its gap as well, for a screen that draws its own frame to the
+     * sheet's edges (a conversation with a list and a pane either side of it).
+     * The column is positioned, so a `LayerHost` the screen keeps inside it
+     * fills exactly the screen.
      */
     fill?: boolean | 'flush' | undefined;
     /**
@@ -159,8 +165,10 @@ export interface AppShellProps extends Omit<HTMLAttributes<HTMLDivElement>, 'tit
     rail?: AppShellRailShape | undefined;
     /**
      * Called with the other shape when the reader presses the fold control.
-     * Given, the shell draws THE fold control (never in the drawer); keeping the
-     * choice, and binding a key to it, are the application's.
+     * Given, the shell draws THE fold control (never in the drawer): a chevron
+     * on the head's row, before the brand's mark, pointing left while the rail
+     * is full and right while it is compact. Keeping the choice, and binding a
+     * key to it, are the application's.
      */
     onRailChange?: ((next: AppShellRailShape) => void) | undefined;
     /**
@@ -248,7 +256,8 @@ export interface AppShellRailProps {
      * A compact status at the end of the head's line, beside the name the head
      * carries: an `<AppShell.RailStatus>`, the application's own state in a
      * dot and a count. It takes its own width, so the name keeps the rest and
-     * truncates there, and it stands in the drawer's head the same way.
+     * truncates there, and it stands in the drawer's head the same way. In the
+     * compact rail it has a row of its own under the head's mark.
      */
     status?: ReactNode;
     /**
@@ -268,9 +277,12 @@ export interface AppShellRailProps {
  * alone (the lockup shows its mark, over the column's centre, and keeps its
  * name as the link's name and title); the field is not drawn, because a
  * 76px column has no room for one and the application draws a Search tile
- * among its `CompactNav` places instead; and the status stands at the top of
- * the foot as its dot and count, since the head has no line left beside the
- * mark. The middle and the foot are drawn as the application gives them.
+ * among its `CompactNav` places instead; and the status stands in a row of
+ * its own under the mark, as its dot and count, since the head has no line
+ * left beside the mark. That row is the first thing under the head in the
+ * column, before the places, so the state a reader checks at a glance is
+ * where their eye starts. The middle and the foot are drawn as the
+ * application gives them.
  */
 export declare function AppShellRail({ header, search, status, footer, className, children }: AppShellRailProps): import("react").JSX.Element;
 /**

package/dist/AppShell/index.d.ts

@@ -9,4 +9,4 @@ export { useScreenBelow, useScreenWidth } from './screenWidth.js';
 export type { StoredWidth, StoredWidthOptions, WidthStorage } from './storedWidth.js';
 export { AccountRow } from './AccountRow.js';
 export type { AccountRowMenu, AccountRowProps } from './AccountRow.js';
-export type { ActionRailRowProps, ActionRailStatusProps, AppShellAsideResize, AppShellAsideShape, AppShellContextValue, AppShellPeekShape, AppShellProps, AppShellRailShape, AppShellRailProps, AppShellRailRowProps, AppShellRailStatusProps, AppShellRegionValue, AppShellToggleProps, AppShellTopbarProps, RailRowCount, StaticRailRowProps, StaticRailStatusProps, } from './AppShell.js';
+export type { ActionRailRowProps, ActionRailStatusProps, AppShellAsideResize, AppShellAsideShape, AppShellContextValue, AppShellPeekShape, AppShellProps, AppShellRailMotion, AppShellRailShape, AppShellRailProps, AppShellRailRowProps, AppShellRailStatusProps, AppShellRegionValue, AppShellToggleProps, AppShellTopbarProps, RailRowCount, StaticRailRowProps, StaticRailStatusProps, } from './AppShell.js';

package/dist/AppShell/index.js

@@ -1,8 +1,11 @@
-export { APP_SHELL_ASIDE_WIDTH, AccountRow, AppShell, AppShellRail, AppShellRailRow, AppShellRailStatus, AppShellToggle, AppShellTopbar, readStoredWidth, useAppShell, useScreenBelow, useScreenWidth, useStoredWidth } from '../chunk-T4IEESXN.js';
-import '../chunk-RTPQDNW3.js';
-import '../chunk-ISQANI6Q.js';
-import '../chunk-3QQIGMY3.js';
-import '../chunk-YOJAGKTS.js';
+export { APP_SHELL_ASIDE_WIDTH, AccountRow, AppShell, AppShellRail, AppShellRailRow, AppShellRailStatus, AppShellToggle, AppShellTopbar, readStoredWidth, useAppShell, useScreenBelow, useScreenWidth, useStoredWidth } from '../chunk-ORONAXSF.js';
+import '../chunk-PCAT2EFB.js';
+import '../chunk-JLOESTT2.js';
+import '../chunk-YJQXESOJ.js';
+import '../chunk-7ZSEUO5Q.js';
+import '../chunk-HTS5RJ7S.js';
+import '../chunk-TGGYSQRD.js';
+import '../chunk-L72URIHR.js';
 export { RESIZE_HANDLE_LARGE_STEP, RESIZE_HANDLE_STEP, ResizeHandle, clampSize, useAppShellAside, useAppShellPeek } from '../chunk-PIYJNCN7.js';
 import '../chunk-CMAZZY2I.js';
 import '../chunk-DGXZ635L.js';

package/dist/AppShell/railMotion.d.ts

@@ -0,0 +1,60 @@
+/**
+ * How the rail moves between its two shapes.
+ *
+ * THE STYLESHEET MOVES IT, THIS DECIDES THE ORDER. The rail's width eases
+ * between the full rail and the compact column (AppShell.css), and its
+ * content is laid out at the width of the shape drawn, clipped by the moving
+ * edge, so nothing in it rewraps at a width it will never rest at. What the
+ * stylesheet cannot decide is WHEN the content changes shape, because the
+ * application draws a different tree for each one:
+ *
+ * - UNFOLDING, the full rail is drawn at once, and the moving edge uncovers
+ *   it while its words fade in (`unfold`).
+ * - FOLDING, the full rail stays drawn, inert, while the edge narrows over it
+ *   and its words fade out (`fold`), and the compact column is drawn once the
+ *   rail's motion has ended, fading in (`folded`). Drawn at once instead, the
+ *   column would replace the words before the reader saw them go.
+ *
+ * ONE MECHANISM FOR EVERY COLUMN THAT EASES. Both shapes are a `usePresence`
+ * each, waiting on the motion actually running on the rail, as a
+ * `DockColumn` waits on its own: no duration is written again here, nothing
+ * waits under reduced motion, and where nothing moves the new shape is drawn
+ * in the same commit, before any paint.
+ */
+import { type RefObject } from 'react';
+import type { AppShellRailShape } from './railShape.js';
+/**
+ * Where a change of shape is: `fold` while the rail narrows over the full
+ * rail's fading words, `folded` while the compact column fades in after it,
+ * `unfold` while the rail widens and the full rail's words fade in, and
+ * `reverse` while a fold pressed again mid way widens the rail back and its
+ * words return from wherever their fade had reached.
+ */
+export type AppShellRailMotion = 'fold' | 'folded' | 'unfold' | 'reverse';
+/**
+ * The rail's own motion, which a change of shape waits for: its width, on the
+ * rail itself, and the keyframes its words arrive by (AppShell.css), wherever
+ * they run inside it. Named, so that nothing else moving inside the rail (a
+ * meter filling, a badge arriving, a paused animation) holds a fold. The
+ * words LEAVE by a transition of their opacity, which a reversal turns back
+ * from where it is, and the rail's width outlasts it.
+ */
+export declare const RAIL_MOTION: {
+    readonly transitions: readonly ["width"];
+    readonly animations: readonly ["crewlet-app-shell-rail-unfold", "crewlet-app-shell-rail-settle"];
+};
+/**
+ * The shape to draw the rail's content in, the phase of the change under
+ * way, and whether the content drawn is only leaving (and so inert), for a
+ * rail whose chosen shape is `target`.
+ *
+ * `moves` is whether a change may animate at all: never in the drawer, where
+ * the rail is always the full list and a shape is not a width. A change that
+ * arrives WITH the window crossing into the wide layout does not animate
+ * either: the reader resized a window, they did not fold a rail.
+ */
+export declare function useRailMotion(target: AppShellRailShape, moves: boolean, rail: RefObject<HTMLElement | null>): {
+    drawn: AppShellRailShape;
+    motion: AppShellRailMotion | null;
+    leaving: boolean;
+};

package/dist/AppShell/railShape.d.ts

@@ -15,3 +15,8 @@ export type AppShellRailShape = 'full' | 'compact';
 export declare const RailShapeContext: import("react").Context<AppShellRailShape>;
 /** The shape the rail around this component is drawn in now: `full` outside a shell, and in the drawer. */
 export declare function useRailShape(): AppShellRailShape;
+/**
+ * Whether the rail's content is drawn only to finish leaving, while the rail
+ * folds over it (railMotion.ts): `AppShell.Rail` makes it inert then.
+ */
+export declare const RailLeavingContext: import("react").Context<boolean>;