@apliteni/apliteni-ui 0.120.1 → 0.122.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.120.1",
+  "version": "0.122.0",
   "workspaces": [
     "react"
   ],

package/react/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { InputHTMLAttributes, ReactNode, ButtonHTMLAttributes, RefAttributes, ReactElement, AnchorHTMLAttributes, HTMLAttributes, RefObject, MouseEvent, ElementType, ComponentPropsWithoutRef, SelectHTMLAttributes, TextareaHTMLAttributes, SVGAttributes } from 'react';
+import { FieldsetHTMLAttributes, ReactNode, InputHTMLAttributes, ButtonHTMLAttributes, RefAttributes, ReactElement, AnchorHTMLAttributes, HTMLAttributes, RefObject, MouseEvent, ElementType, ComponentPropsWithoutRef, SelectHTMLAttributes, TextareaHTMLAttributes, SVGAttributes } from 'react';
 import { ACCENTS } from '@apliteni/apliteni-ui';
 
 declare function Icon({ name }: {
@@ -8,12 +8,22 @@ declare function Icon({ name }: {
 
 type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'children'> & {
     label: ReactNode;
+    /** Shown under the label words and described to assistive technology. */
+    hint?: ReactNode;
     type?: 'checkbox' | 'radio';
 };
 declare const Checkbox: react.ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "children"> & {
     label: ReactNode;
+    /** Shown under the label words and described to assistive technology. */
+    hint?: ReactNode;
     type?: "checkbox" | "radio";
 } & react.RefAttributes<HTMLInputElement>>;
+type CheckListProps = Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, 'children'> & {
+    legend: ReactNode;
+    children: ReactNode;
+};
+/** A group of `Checkbox` children under a legend. */
+declare function CheckList({ legend, children, className, ...props }: CheckListProps): react.JSX.Element;
 
 type SwitchProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'children'> & {
     label: string;
@@ -1060,4 +1070,4 @@ declare const AccentPicker: react.ForwardRefExoticComponent<Omit<HTMLAttributes<
 declare const PAGE_SIZES: readonly number[];
 declare const DEFAULT_PAGE_SIZE: number;
 
-export { type Accent, AccentPicker, type AccentPickerProps, type AddFilter, AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Chart, type ChartBridgeStep, type ChartBridgeTones, type ChartPeriod, type ChartProps, type ChartSeries, type ChartTone, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DatePicker, type DatePickerMode, type DatePickerPreset, type DatePickerProps, type DatePickerRange, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileDrop, type FileDropFile, type FileDropProps, type FileDropStatus, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };
+export { type Accent, AccentPicker, type AccentPickerProps, type AddFilter, AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Chart, type ChartBridgeStep, type ChartBridgeTones, type ChartPeriod, type ChartProps, type ChartSeries, type ChartTone, CheckList, type CheckListProps, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DatePicker, type DatePickerMode, type DatePickerPreset, type DatePickerProps, type DatePickerRange, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileDrop, type FileDropFile, type FileDropProps, type FileDropStatus, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };

package/react/dist/index.js

@@ -15,18 +15,33 @@ function Icon({ name }) {
 }
 
 // src/Checkbox.tsx
-import { forwardRef } from "react";
+import { forwardRef, useId } from "react";
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
 var Checkbox = forwardRef(function Checkbox2({
   label,
+  hint,
   type = "checkbox",
+  "aria-describedby": describedBy,
   ...props
 }, ref) {
-  return /* @__PURE__ */ jsxs("label", { className: "ui-check", children: [
-    /* @__PURE__ */ jsx2("input", { ...props, ref, type }),
+  const hintId = useId();
+  const described = [describedBy, hint ? hintId : void 0].filter(Boolean).join(" ") || void 0;
+  const check = /* @__PURE__ */ jsxs("label", { className: "ui-check", children: [
+    /* @__PURE__ */ jsx2("input", { ...props, ref, type, "aria-describedby": described }),
     /* @__PURE__ */ jsx2("span", { children: label })
   ] });
+  if (!hint) return check;
+  return /* @__PURE__ */ jsxs("div", { className: "ui-check-item", children: [
+    check,
+    /* @__PURE__ */ jsx2("div", { id: hintId, className: "ui-check__hint", children: hint })
+  ] });
 });
+function CheckList({ legend, children, className = "", ...props }) {
+  return /* @__PURE__ */ jsxs("fieldset", { ...props, className: `ui-check-list ${className}`.trim(), children: [
+    /* @__PURE__ */ jsx2("legend", { className: "ui-field__label", children: legend }),
+    children
+  ] });
+}
 
 // src/Switch.tsx
 import { forwardRef as forwardRef2 } from "react";
@@ -269,7 +284,7 @@ function Callout({ variant, icon: icon6 = calloutIcons[variant ?? "neutral"], ch
 }
 
 // src/primitives/StatBand.tsx
-import { useId as useId2 } from "react";
+import { useId as useId3 } from "react";
 
 // src/tip.ts
 var TIP_GAP = 8;
@@ -311,7 +326,7 @@ function placeTip(host, mark, tip, bound, placement = "top") {
 }
 
 // src/Tooltip.tsx
-import { useEffect, useId, useLayoutEffect as useLayoutEffect2, useRef as useRef2, useState } from "react";
+import { useEffect, useId as useId2, useLayoutEffect as useLayoutEffect2, useRef as useRef2, useState } from "react";
 import { Fragment, jsx as jsx10, jsxs as jsxs6 } from "react/jsx-runtime";
 var DOC_EVENTS = ["pointerdown", "pointercancel", "click", "keydown", "touchend"];
 var CAPTURED = /* @__PURE__ */ new Set(["pointerdown", "pointercancel"]);
@@ -345,7 +360,7 @@ var Text = ({ label = "", value = "", detail: detail2 = "" }) => /* @__PURE__ */
   /* @__PURE__ */ jsx10("span", { className: "ui-tip__detail", hidden: !detail2, children: detail2 })
 ] });
 function Tooltip({ text: text2, label = text2, value, detail: detail2, placement = "top", children }) {
-  const id = useId();
+  const id = useId2();
   const host = useRef2(null);
   const trigger = useRef2(null);
   const tip = useRef2(null);
@@ -526,7 +541,7 @@ function ContextRow({ caption, delta, basisId }) {
   ] });
 }
 function StatBand({ stats, variant = "tiles", basis, basisId: sharedBasisId, label, id }) {
-  const auto = useId2();
+  const auto = useId3();
   const v = ["band", "tiles", "open"].includes(variant) ? variant : "tiles";
   const basisId = basis ? `${id || auto}-basis` : sharedBasisId;
   const root = ["ui-stats", `ui-stats--${v}`, v === "band" && "ui-card"].filter(Boolean).join(" ");
@@ -549,7 +564,7 @@ function StatBand({ stats, variant = "tiles", basis, basisId: sharedBasisId, lab
 import { useRef as useRef5 } from "react";
 
 // src/Modal.tsx
-import { useId as useId3, useRef as useRef4 } from "react";
+import { useId as useId4, useRef as useRef4 } from "react";
 import { createPortal } from "react-dom";
 
 // src/dialog.ts
@@ -755,7 +770,7 @@ function useDialog(active, { root, panel, body, initialFocus }, onClose) {
 // src/Modal.tsx
 import { jsx as jsx12, jsxs as jsxs8 } from "react/jsx-runtime";
 function Modal({ open, title, onClose, footer, children, initialFocusRef, role = "dialog" }) {
-  const id = useId3();
+  const id = useId4();
   const titleId = `${id}-title`;
   const bodyId = `${id}-body`;
   const root = useRef4(null);
@@ -821,7 +836,7 @@ function Confirm({
 }
 
 // src/Drawer.tsx
-import { useId as useId4, useRef as useRef6 } from "react";
+import { useId as useId5, useRef as useRef6 } from "react";
 import { createPortal as createPortal2 } from "react-dom";
 import { jsx as jsx14, jsxs as jsxs10 } from "react/jsx-runtime";
 function Drawer({
@@ -837,7 +852,7 @@ function Drawer({
   const root = useRef6(null);
   const panel = useRef6(null);
   const body = useRef6(null);
-  const titleId = useId4();
+  const titleId = useId5();
   const { mounted, shown } = usePresence(open, root, panel);
   const scope = useDialog(shown, { root, panel, body }, onClose);
   if (!mounted) return null;
@@ -870,7 +885,7 @@ function Drawer({
 }
 
 // src/CommandPalette.tsx
-import { useCallback, useEffect as useEffect3, useId as useId5, useMemo, useRef as useRef7, useState as useState3 } from "react";
+import { useCallback, useEffect as useEffect3, useId as useId6, useMemo, useRef as useRef7, useState as useState3 } from "react";
 import { createPortal as createPortal3 } from "react-dom";
 import { rankGroups, icon as icon2 } from "@apliteni/apliteni-ui";
 import { jsx as jsx15, jsxs as jsxs11 } from "react/jsx-runtime";
@@ -890,7 +905,7 @@ function CommandPalette({
   rank = true,
   onQueryChange
 }) {
-  const uid = useId5().replace(/:/g, "");
+  const uid = useId6().replace(/:/g, "");
   const root = useRef7(null);
   const panel = useRef7(null);
   const search = useRef7(null);
@@ -1067,7 +1082,7 @@ import { useCallback as useCallback2, useEffect as useEffect5, useMemo as useMem
 import { DEFAULT_PAGE_SIZE as DEFAULT_PAGE_SIZE2 } from "@apliteni/apliteni-ui";
 
 // src/Pagination.tsx
-import { useEffect as useEffect4, useId as useId6, useRef as useRef8, useState as useState4 } from "react";
+import { useEffect as useEffect4, useId as useId7, useRef as useRef8, useState as useState4 } from "react";
 import { DEFAULT_PAGE_SIZE } from "@apliteni/apliteni-ui";
 import { jsx as jsx16, jsxs as jsxs12 } from "react/jsx-runtime";
 var GHOST_SM = "ui-btn ui-btn--ghost ui-btn--sm";
@@ -1111,7 +1126,7 @@ function Pagination({
   onPageChange,
   onPageSizeChange
 }) {
-  const auto = useId6();
+  const auto = useId7();
   const [draft, setDraft] = useState4("");
   const [drafting, setDrafting] = useState4(false);
   const nav = useRef8(null);
@@ -2058,7 +2073,7 @@ import {
   Fragment as Fragment5,
   useCallback as useCallback4,
   useEffect as useEffect7,
-  useId as useId7,
+  useId as useId8,
   useRef as useRef11,
   useState as useState7
 } from "react";
@@ -2142,7 +2157,7 @@ function Dropdown({
   const field = useRef11(null);
   const landOn = useRef11(null);
   const at = useRef11("");
-  const auto = useId7().replace(/:/g, "");
+  const auto = useId8().replace(/:/g, "");
   const uid = id ?? auto;
   const setOpen = useCallback4((next) => {
     if (openProp === void 0) setSelfOpen(next);
@@ -2936,11 +2951,11 @@ function Snippet({ label = "shell", code = "", children, copy = true, reveal = f
 }
 
 // src/Tabs.tsx
-import { useEffect as useEffect9, useId as useId8, useRef as useRef14 } from "react";
+import { useEffect as useEffect9, useId as useId9, useRef as useRef14 } from "react";
 import { playEntrance } from "@apliteni/apliteni-ui/motion";
 import { Fragment as Fragment9, jsx as jsx27, jsxs as jsxs22 } from "react/jsx-runtime";
 function Tabs({ items, value, onChange, label }) {
-  const id = useId8();
+  const id = useId9();
   const previous = useRef14(value);
   const activePanel = useRef14(null);
   const buttons = useRef14([]);
@@ -3063,7 +3078,7 @@ function Timeline({ events, className, ...rest }) {
 }
 
 // src/Field.tsx
-import { forwardRef as forwardRef6, useEffect as useEffect11, useId as useId9, useRef as useRef16, useState as useState10 } from "react";
+import { forwardRef as forwardRef6, useEffect as useEffect11, useId as useId10, useRef as useRef16, useState as useState10 } from "react";
 import { esc, icon as icon4 } from "@apliteni/apliteni-ui";
 import { jsx as jsx29, jsxs as jsxs24 } from "react/jsx-runtime";
 function messages(id, hint, error) {
@@ -3092,12 +3107,12 @@ function wiring(id, hint, error) {
   return { id, "aria-describedby": messages(id, hint, error), "aria-invalid": error ? true : void 0 };
 }
 function Field({ id: suppliedId, label, hint, error, required, children }) {
-  const generatedId = useId9();
+  const generatedId = useId10();
   const id = suppliedId ?? generatedId;
   return /* @__PURE__ */ jsx29(Frame, { ...{ id, label, hint, error, required }, children: children({ ...wiring(id, hint, error), required }) });
 }
 var TextField = forwardRef6(function TextField2({ label, hint, error, required, type = "text", unit, icon: glyph, className = "", ...props }, ref) {
-  const id = useId9();
+  const id = useId10();
   const hasUnit = type === "number" && !!unit;
   const describedBy = [messages(id, hint, error), hasUnit ? `${id}-unit` : ""].filter(Boolean).join(" ") || void 0;
   const control = /* @__PURE__ */ jsx29(
@@ -3124,7 +3139,7 @@ var TextField = forwardRef6(function TextField2({ label, hint, error, required,
   ] }) : control });
 });
 function TextArea({ label, hint, error, required, className = "", ...props }) {
-  const id = useId9();
+  const id = useId10();
   return /* @__PURE__ */ jsx29(Frame, { ...{ id, label, hint, error, required }, children: /* @__PURE__ */ jsx29(
     "textarea",
     {
@@ -3137,7 +3152,7 @@ function TextArea({ label, hint, error, required, className = "", ...props }) {
   ) });
 }
 function SelectField({ label, hint, error, required, className = "", children, ...props }) {
-  const id = useId9();
+  const id = useId10();
   return /* @__PURE__ */ jsx29(Frame, { ...{ id, label, hint, error, required }, children: /* @__PURE__ */ jsx29(
     "select",
     {
@@ -3150,7 +3165,7 @@ function SelectField({ label, hint, error, required, className = "", children, .
   ) });
 }
 function FileField({ label, hint, error, required, disabled, onFileChange, className = "", ...props }) {
-  const id = useId9();
+  const id = useId10();
   const input = useRef16(null);
   const [file, setFile] = useState10(null);
   const [dragging, setDragging] = useState10(false);
@@ -3517,16 +3532,16 @@ function Toast({ children }) {
 }
 
 // src/AppShell.tsx
-import { useEffect as useEffect14, useId as useId11, useState as useState14 } from "react";
+import { useEffect as useEffect14, useId as useId12, useState as useState14 } from "react";
 import { paletteHotkey, prism, railCollapsed } from "@apliteni/apliteni-ui";
 
 // src/SidebarNav.tsx
-import { forwardRef as forwardRef8, useEffect as useEffect13, useId as useId10, useState as useState13 } from "react";
+import { forwardRef as forwardRef8, useEffect as useEffect13, useId as useId11, useState as useState13 } from "react";
 import { ENTRANCE_FALLBACK_MS } from "@apliteni/apliteni-ui/motion";
 import { Fragment as Fragment11, jsx as jsx33, jsxs as jsxs28 } from "react/jsx-runtime";
 var badgeText = (badge) => typeof badge === "object" ? badge.text : badge;
 function Row({ item, active, activeIs, collapsed, renderLink, sub }) {
-  const uid = useId10();
+  const uid = useId11();
   const group = !sub && !!item.items?.length;
   const childActive = group && item.items.some((child) => child.id === active);
   const [expanded, setExpanded] = useState13();
@@ -3583,7 +3598,7 @@ function Row({ item, active, activeIs, collapsed, renderLink, sub }) {
   return /* @__PURE__ */ jsx33("li", { children: renderLink ? renderLink(item, props) : /* @__PURE__ */ jsx33("a", { ...props }) });
 }
 function Section({ section, ...props }) {
-  const uid = useId10();
+  const uid = useId11();
   return /* @__PURE__ */ jsxs28("div", { className: "ui-nav__section", children: [
     section.label && /* @__PURE__ */ jsx33("div", { className: "ui-nav__cap", id: uid, "aria-hidden": props.collapsed || void 0, children: section.label }),
     /* @__PURE__ */ jsx33("ul", { className: "ui-nav__list", "aria-labelledby": section.label ? uid : void 0, children: section.items.map((item) => /* @__PURE__ */ jsx33(Row, { item, ...props }, item.id)) })
@@ -3712,7 +3727,7 @@ function AppShell({
   palette,
   renderLink
 }) {
-  const uid = useId11();
+  const uid = useId12();
   const [collapsed, setCollapsed] = useState14(defaultCollapsed);
   const [search, setSearch] = useState14(false);
   const [more, setMore] = useState14(false);
@@ -4011,7 +4026,7 @@ var Success = forwardRef9(function Success2({
 import {
   useCallback as useCallback6,
   useEffect as useEffect16,
-  useId as useId12,
+  useId as useId13,
   useLayoutEffect as useLayoutEffect5,
   useMemo as useMemo4,
   useRef as useRef20,
@@ -4179,7 +4194,7 @@ function Chart(props) {
   const spark = variant === "spark";
   const plotHeight = height ?? HEIGHT[variant];
   const showTable = table ?? !spark;
-  const uid = useId12().replace(/[^\w-]/g, "");
+  const uid = useId13().replace(/[^\w-]/g, "");
   const frameEl = useRef20(null);
   const scroller = useRef20(null);
   const plot = useRef20(null);
@@ -4741,6 +4756,7 @@ export {
   Callout,
   Card,
   Chart,
+  CheckList,
   Checkbox,
   CommandPalette,
   Confirm,

package/src/styles/input.css

@@ -211,6 +211,32 @@
    holds go quiet with the box beside them. */
 .ui-check:has(input:disabled) { /* muted-ink: state — unavailable control */ color: var(--disabled-ink); cursor: not-allowed; }
 
+/* A hint under a box. It sits outside the label, so the label's name stays the label
+   words and the hint is read as a description (aria-describedby), and it takes the
+   field hint's type and ink. The left edge is the label words': the 19px box and the
+   11px gap, a sum that lies between two grid steps for that reason alone. */
+.ui-check-item { display: flex; flex-direction: column; align-items: flex-start; }
+.ui-check__hint {
+  color: var(--text);
+  font-size: var(--text-sm);
+  line-height: 1.5;
+  margin-top: var(--space-1);
+  margin-left: 30px;
+}
+.ui-check-item:has(input:disabled) .ui-check__hint { /* muted-ink: state — unavailable control */ color: var(--disabled-ink); }
+
+/* A group of boxes under a legend, the legend in the field label's type. */
+.ui-check-list {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--space-4);
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+
 /* Toggle switch */
 .ui-switch {
   --sw-w: 44px;

package/src/styles/topbar.css

@@ -231,49 +231,45 @@
    the same neutral chip fill rather than the card surface — which, inside a panel that
    is itself lighter than a card, was darker than the ground it sat on. #453 */
 .vbadge.arch { /* muted-ink: state — archived version */ color: var(--muted); background: var(--chip-neutral-fill); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
-/* The phone step — the same one the rail folds at: docs/foundations.md#breakpoints.
-   The switcher keeps its glyph and drops its label.
-   The menu hangs the other way here. Anchored by its left edge it opened
-   rightwards off a band that is as wide as the page, and a CLOSED menu is still
-   laid out, so it scrolled the page sideways with nothing visible to explain it.
-   `.amenu` beside it has always been anchored right. On a 320px viewport the
-   page's scroll width was 527px and is 397px; the band's own controls still want
-   more room than that page has, which is #558.
-   why: guidelines/layout-and-density.md#use-the-three-breakpoints
-   held by: stories/overlay-css.test.js */
+/* The version label drops at the shell breakpoint.
+   Anchor the menu to its right edge so a closed panel cannot widen the page. */
 @media (max-width: 720px) {
   .vsw__btn .lbl { display: none; }
   .vsw__menu { left: auto; right: 0; }
 }
 
-/* One column, and the band is at its tightest. The row is already full at 390,
-   and at the gap above this one the account avatar stood from 365 to 397 and was
-   cut at the screen edge — the one control on this screen that opens the account
-   area. Packed to --space-2 and a flat 14px trailing gutter the band needs 367.53
-   of the 362px it has there, a 5.53px shortfall, because layout.css now pins the
-   theme switch to a full 34px square so it keeps the tap floor it was given.
-   The wordmark, the Deck/Text switch and the version label are each already at
-   the width their own text needs, and the switch must not shrink again, so the
-   account block's trailing gutter is what gives — but a FLAT 14px gutter has no
-   fallback below the width it was sized for: at 375 it has already given every
-   one of its 14px and the row is still 6.53px short, so the avatar was cut and
-   the page gained 7px of horizontal scroll (#486 review round 2), worse again
-   at 320.
-   Both carry a share now, continuously, rather than the gutter alone holding a
-   fixed budget: the gutter still narrows first, from 14px at 390 down to 0 by
-   381.53px of available row width, and once it is spent the inter-control gap
-   takes the rest, from --space-2 down to its own floor of --space-1. 381.53px is
-   this row's own fixed width minus its gutter's full 14px — not a general
-   formula, a number that belongs to this composition's own wordmark, switch and
-   version label. The avatar is whole and the page carries no horizontal scroll
-   down to 375px. 320 still falls 41.53px short with both all the way down,
-   which stays #558; it is 5px better than main's own 46.53px there, not solved.
-   why: docs/foundations.md#breakpoints */
+/* Keep the identity controls above the view controls on a phone.
+   The toolbar pattern uses the same inset for both rows. */
 @media (max-width: 560px) {
+  .topbar { height: auto; min-height: 52px; }
   .topbar__in {
-    gap: clamp(var(--space-1), calc(var(--space-2) - (381.53px - 100vw) / 5), var(--space-2));
-    padding-right: clamp(0px, calc(100vw - 381.53px), 14px);
+    display: grid;
+    grid-template-columns: max-content minmax(0, 1fr) auto auto;
+    grid-auto-rows: minmax(44px, auto);
+    gap: var(--space-2) 0;
+    /* 4px above and 3px below, because the band's 1px border is the fourth: one row is
+       then 52px, as on a wide screen, and the shell offset below stays true. */
+    padding: var(--space-1) var(--space-3) 3px;
   }
+  .topbar__in > .brand { grid-area: 1 / 1 / 2 / 3; justify-self: start; }
+  .topbar__in > .toggle { grid-area: 1 / 3; justify-self: end; }
+  /* The 8px beside the account is its own margin, so a hidden account leaves no gap and
+     the theme switch ends on the inset. */
+  .topbar__in > .acct { grid-area: 1 / 4; justify-self: end; margin-left: var(--space-2); }
+  .topbar__in > .spacer { display: none; }
+  .topbar__in > .dtsw { grid-area: 2 / 1; justify-self: start; }
+  /* The first column is as wide as Deck/Text and no wider, because the brand spans past it.
+     The version switch takes the flexible column and the two auto columns beside it, so its
+     width never widens the columns that pin the theme switch and the account to the row's
+     end inset. A long label gives way to an ellipsis, and 8px always stays between the
+     two controls. */
+  .topbar__in > .vsw { grid-area: 2 / 2 / 3 / -1; justify-self: end; min-width: 0; max-width: calc(100% - var(--space-2)); margin-left: var(--space-2); }
+  .vsw__btn { max-width: 100%; }
+  .vsw__btn .cur { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .vsw__btn .car { flex: none; }
+  /* Two 44px rows, an 8px gap, the 4px and 3px insets and the bottom border. */
+  .ui-app-page:has(.topbar .dtsw.on),
+  .ui-app-page:has(.topbar .vsw) { --ui-app-top: 104px; }
 }
 
 /* Account — avatar + dropdown. Gated: hidden until the app confirms a session