@scaffold-ui-kit/preview 0.0.0-stage → 2.3.0

package/application/shells/charcell/components/Hint/index.tsx

@@ -0,0 +1,81 @@
+// A hint beside a control, in place of a `title`: charcell's Tooltip, which
+// opens as the reader hovers or focuses the control and closes on Escape. The
+// control renders through `children`, handed the trigger's props to spread
+// on the element the hint is for; with no text it renders bare. A control
+// that is already another part's trigger (a popover's, a sortable grip) passes
+// those `triggerProps`: the hint takes their id as its trigger's, so both
+// find the one element, and the two descriptions stay. A hint the kit wrote
+// (`markdown`) renders its markdown, as a description does.
+//
+// A control that takes its handlers on an element other than the one the
+// reader sees passes `around`: the trigger is then a span around the control,
+// which hears the pointer over any of it and the focus of anything inside,
+// and the control is handed the description alone. charcell's Toggle is one:
+// its handlers reach the checkbox it hides, which no pointer reaches. A
+// disabled control takes no focus, so with `focusable` the span takes it in
+// the control's place, and the hint opens from the keyboard too: a group
+// named by the control's `label` (the hint's text without one) and described
+// by the hint, so the stop says which control it stands for. Styled in its
+// index.css.
+import { Tooltip } from 'charcell/react/unlinked';
+import { mergeProps } from '@zag-js/react';
+import type { ReactNode } from 'react';
+import { Markdown } from '../Markdown';
+import './index.css';
+
+export function Hint({
+  text,
+  markdown = false,
+  triggerProps,
+  around = false,
+  focusable = false,
+  label,
+  children,
+}: {
+  text?: string;
+  markdown?: boolean;
+  triggerProps?: Record<string, unknown>;
+  around?: boolean;
+  focusable?: boolean;
+  label?: string;
+  children: (triggerProps: Record<string, unknown>) => ReactNode;
+}) {
+  if (!text?.trim()) {
+    const bare = children(triggerProps ?? {});
+    return around ? <span className="Hint">{bare}</span> : <>{bare}</>;
+  }
+  const triggerId = typeof triggerProps?.id === 'string' ? triggerProps.id : undefined;
+  return (
+    <Tooltip
+      triggerId={around ? undefined : triggerId}
+      trigger={(tooltip) => {
+        if (!around)
+          return children(triggerProps ? merged(triggerProps, tooltip.triggerProps) : tooltip.triggerProps);
+        const { 'aria-describedby': described, ...wrapper } = tooltip.triggerProps;
+        const describedBy = typeof described === 'string' ? described : undefined;
+        return (
+          <span
+            {...wrapper}
+            className={`Hint${focusable ? ' Hint--focusable' : ''}`}
+            {...(focusable
+              ? { tabIndex: 0, role: 'group', 'aria-label': label ?? text, 'aria-describedby': describedBy }
+              : {})}
+          >
+            {children(merged(triggerProps ?? {}, { 'aria-describedby': describedBy }))}
+          </span>
+        );
+      }}
+    >
+      {markdown ? <Markdown text={text} /> : text}
+    </Tooltip>
+  );
+}
+
+/** A part's trigger props with the hint's over them, keeping both descriptions. */
+function merged(own: Record<string, unknown>, hint: Record<string, unknown>): Record<string, unknown> {
+  const describedBy = [own['aria-describedby'], hint['aria-describedby']].filter((id) => typeof id === 'string' && id);
+  return {
+    ...mergeProps(own, hint),
+    ...(describedBy.length ? { 'aria-describedby': describedBy.join(' ') } : { 'aria-describedby': undefined }),
+  };
+}

package/application/shells/charcell/components/HtmlWarnings/index.tsx

@@ -0,0 +1,45 @@
+// How many warnings a story's html has, as a dense charcell Button that opens
+// them in a charcell Popover on a click, Enter or Space, where they stay open
+// to be read and copied until a click outside or Escape closes them. Hovering
+// or focusing it shows a short hint saying what it opens (Hint), as the
+// description button's does. The pane that holds it gives its color through
+// `className`.
+import { Button, Popover } from 'charcell/react/unlinked';
+import { Hint } from '../Hint';
+import { Markdown } from '../Markdown';
+import { htmlWarningsHint, htmlWarningsLabel } from '../../html-warnings';
+
+export function HtmlWarnings({
+  warnings,
+  className,
+  attributes,
+}: {
+  warnings: readonly string[];
+  className?: string;
+  attributes?: Record<string, string>;
+}) {
+  return (
+    <Popover
+      label="html warnings"
+      width={64}
+      trigger={({ triggerProps }) => (
+        <Hint
+          text="what the html leaves out at rest"
+          triggerProps={triggerProps}
+        >
+          {(props) => (
+            <Button
+              variant="dense"
+              label={htmlWarningsLabel(warnings)}
+              className={className}
+              {...props}
+              {...attributes}
+            />
+          )}
+        </Hint>
+      )}
+    >
+      <Markdown text={htmlWarningsHint(warnings)} />
+    </Popover>
+  );
+}

package/application/shells/charcell/components/KeyHints/index.css

@@ -0,0 +1,27 @@
+@layer charcell.components {
+  /* The hint and the list's button, a band's items apart. */
+  .KeyHints {
+    display: flex;
+    align-items: center;
+    gap: 2ch;
+  }
+  .KeyHints__hint {
+    color: var(--charcell-mid);
+  }
+  /* The list: the keys in one column, what they do in the next. */
+  .KeyHints__list {
+    margin: 0;
+    display: grid;
+    grid-template-columns: max-content minmax(0, 1fr);
+    column-gap: 2ch;
+  }
+  .KeyHints__entry {
+    display: contents;
+  }
+  .KeyHints__key {
+    font-weight: 700;
+  }
+  .KeyHints__meaning {
+    margin: 0;
+  }
+}

package/application/shells/charcell/components/KeyHints/index.tsx

@@ -0,0 +1,106 @@
+// The shell's keys, and the hint of them at the end of the status bar:
+// `/ find  ? keys`, the second opening the list of them in a charcell Popover.
+// A key acts while no field takes the typing - a text input, a select's
+// list, the editor, the navigation's tree, whose rows a typed letter finds - and
+// no pane holds the focus (a pane's keys are its story's); with Ctrl, Alt or
+// Meta held it is the browser's.
+//
+//   /     find a component (the component combobox, its text selected)
+//   n     show or hide the navigation
+//   s o c e  show or hide the scenario, output, code and events views
+//   1-n   show or hide the targets, in the top bar's order (the kit's
+//         targets numbered, 1-3 for three)
+//   w     wrap the code panes' lines, or not
+//   ?     the list of keys
+//
+// The list also names Enter on a focused split handle, which puts the split
+// back where it started (split-reset.ts, as a double-click on it does); the
+// handle takes it, not this listener.
+//
+// Views and targets follow the narrow layout's one-at-a-time rule
+// (stage-toggles.ts). Styled in its index.css.
+import { Button, Popover } from 'charcell/react/unlinked';
+import { Hint } from '../Hint';
+import { useEffect, useState } from 'react';
+import { usePreviewController } from '../../controller-context';
+import { NAVIGATION_OPTION, WRAP_OPTION } from '../../shell-options';
+import { toggleTarget, toggleView, useNarrow, VIEW_OPTIONS } from '../../stage-toggles';
+import './index.css';
+
+/** The keys, as the list shows them. */
+function keys(targets: number): [string, string][] {
+  return [
+    ['/', 'find a component'],
+    ['n', 'show or hide the navigation'],
+    ['s o c e', 'show or hide the scenario, output, code and events views'],
+    [targets > 1 ? `1-${targets}` : '1', targets > 1 ? 'show or hide the targets' : 'show or hide the target'],
+    ['w', 'wrap the code panes’ lines, or not'],
+    ['enter', 'on a split handle, put the split back where it started (or double-click it)'],
+    ['?', 'this list'],
+  ];
+}
+
+/** Whether a key pressed with focus on `target` is the field's to take. */
+function typing(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  if (target.closest('input, textarea, select, [role="listbox"], [role="combobox"], [role="dialog"], [role="tree"]')) return true;
+  return false;
+}
+
+export function KeyHints() {
+  const controller = usePreviewController();
+  const narrow = useNarrow();
+  const [open, setOpen] = useState(false);
+  useEffect(() => {
+    function onKey(event: KeyboardEvent) {
+      if (event.ctrlKey || event.altKey || event.metaKey || event.defaultPrevented) return;
+      if (typing(event.target)) return;
+      const state = controller.getState();
+      const viewKey = { s: 0, o: 1, c: 2, e: 3 }[event.key];
+      if (event.key === '/') {
+        // The component combobox, its text selected: typing replaces the
+        // current name and opens the list, narrowed to the matches.
+        const find = document.querySelector<HTMLInputElement>('[data-testid="select-component"]');
+        if (!find) return;
+        find.focus();
+        find.select();
+      } else if (event.key === '?') setOpen((shown) => !shown);
+      else if (viewKey !== undefined) toggleView(controller, VIEW_OPTIONS[viewKey], narrow);
+      else if (/^[1-9]$/.test(event.key)) {
+        const target = controller.catalog.targets[Number(event.key) - 1];
+        if (!target) return;
+        toggleTarget(controller, target, narrow);
+      } else if (event.key === 'n') controller.actions.setOption(NAVIGATION_OPTION, state.options[NAVIGATION_OPTION] === false);
+      else if (event.key === 'w') controller.actions.setOption(WRAP_OPTION, state.options[WRAP_OPTION] === false);
+      else return;
+      event.preventDefault();
+    }
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [controller, narrow]);
+  return (
+    <span className="KeyHints">
+      <span className="KeyHints__hint">/ find</span>
+      <Popover
+        label="keys"
+        open={open}
+        onOpenChange={setOpen}
+        trigger={({ triggerProps }) => (
+          <Hint text="the shell's keys" triggerProps={triggerProps}>
+            {(props) => <Button variant="dense" label="? keys" {...props} />}
+          </Hint>
+        )}
+      >
+        <dl className="KeyHints__list">
+          {keys(controller.catalog.targets.length).map(([key, meaning]) => (
+            <div key={key} className="KeyHints__entry">
+              <dt className="KeyHints__key">{key}</dt>
+              <dd className="KeyHints__meaning">{meaning}</dd>
+            </div>
+          ))}
+        </dl>
+      </Popover>
+    </span>
+  );
+}

package/application/shells/charcell/components/KitCodeBlock/index.css

@@ -0,0 +1,55 @@
+@layer charcell.components {
+  /* The block's place: the rest of the code pane, its iframe filling it. */
+  .KitCodeBlock {
+    position: relative;
+    flex: 1 1 auto;
+    display: flex;
+    min-height: 0;
+  }
+  /* While the block's iframe loads, as a preview pane's does (PreviewPane). */
+  .KitCodeBlock:has(> iframe:not([data-preview-shown]))::after {
+    content: 'loading';
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-items: center;
+    color: var(--charcell-mid);
+    visibility: hidden;
+    animation:
+      KitCodeBlock-loading 0s 300ms forwards,
+      KitCodeBlock-dots 1.2s 300ms steps(1, end) infinite;
+  }
+  @keyframes KitCodeBlock-loading {
+    to {
+      visibility: visible;
+    }
+  }
+  /* The dots count up, one a step; spaces hold the dots' place, so the
+     word stays put in the monospace face. */
+  @keyframes KitCodeBlock-dots {
+    0% {
+      content: 'loading\00a0\00a0\00a0';
+    }
+    25% {
+      content: 'loading.\00a0\00a0';
+    }
+    50% {
+      content: 'loading..\00a0';
+    }
+    75%,
+    100% {
+      content: 'loading...';
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .KitCodeBlock:has(> iframe:not([data-preview-shown]))::after {
+      animation: KitCodeBlock-loading 0s 300ms forwards;
+    }
+  }
+  .KitCodeBlock > iframe {
+    flex: 1;
+    min-height: 0;
+    width: 100%;
+    border: 0;
+  }
+}

package/application/shells/charcell/components/KitCodeBlock/index.tsx

@@ -0,0 +1,18 @@
+// The kit's own code block (`catalog.codeBlock`) in a code pane: the element
+// the controller mounts the block's iframe in, filling the pane's place for
+// the source. The block shows the target's source, follows it, and wraps
+// its long lines as the shell's `wrap` option says. Styled in its index.css.
+import { useEffect, useRef } from 'react';
+import type { PreviewTarget } from '../../../../../src/shell';
+import { usePreviewController, usePreviewState } from '../../controller-context';
+import { WRAP_OPTION } from '../../shell-options';
+import './index.css';
+
+export function KitCodeBlock({ target }: { target: PreviewTarget }) {
+  const controller = usePreviewController();
+  const element = useRef<HTMLDivElement>(null);
+  const wrapped = usePreviewState((state) => state.options[WRAP_OPTION] !== false);
+  useEffect(() => controller.frames.mountCode(element.current!, target), [controller, target]);
+  useEffect(() => controller.frames.wrapCode(wrapped), [controller, wrapped]);
+  return <div ref={element} className="KitCodeBlock" data-preview-kit-code={target} />;
+}

package/application/shells/charcell/components/Markdown/index.tsx

@@ -0,0 +1,16 @@
+// A description as the kit wrote it, in markdown: parsed into React elements
+// and set in charcell's RichText, which gives its paragraphs, inline code,
+// code blocks, lists and links charcell's cells. Raw html in the text is shown
+// as text, never parsed, so a tag a description mentions without backticks
+// cannot swallow what follows it. A code block scrolls rather than wraps.
+import { compiler } from 'markdown-to-jsx/react';
+import { RichText } from 'charcell/react/unlinked';
+import { useMemo } from 'react';
+
+export function Markdown({ text }: { text: string }) {
+  const content = useMemo(
+    () => compiler(text.trim(), { disableParsingRawHTML: true, forceBlock: true, wrapper: null }),
+    [text],
+  );
+  return <RichText>{content}</RichText>;
+}

package/application/shells/charcell/components/Navigation/index.css

@@ -0,0 +1,13 @@
+@layer charcell.components {
+  /* The navigation: fills its panel of the navigation split, its
+     charcell ScrollArea filling it in turn, and ends a row past the tree. */
+  .Navigation {
+    flex: 1 1 auto;
+    display: flex;
+    min-width: 0;
+    min-height: 0;
+  }
+  .Navigation__content {
+    padding-bottom: var(--charcell-row);
+  }
+}

package/application/shells/charcell/components/Navigation/index.tsx

@@ -0,0 +1,98 @@
+// The navigation renders the catalog's navigation tree: per source, custom views (a
+// tokens page, an icon gallery) and the component tree interleave by order, the
+// root (core) source hoisted to the top level and every other source a collapsible
+// wrapper. The tree is the controller's catalog data; this component only draws it.
+// It scrolls in a charcell ScrollArea, a whole row at a time, its scrollbar
+// drawn in cells; a scroll at either end stops there, moving nothing else.
+// Which groups are collapsed is its parent's to keep (`collapsed`), so they
+// stay as they were left while the navigation is hidden and shown.
+import { useEffect, useRef, type Dispatch, type SetStateAction } from 'react';
+import { ScrollArea, Tree, TreeGroup, TreeItem } from 'charcell/react/unlinked';
+import type { PreviewNavigationNode } from '../../../../../src/shell';
+import { usePreviewController, usePreviewState } from '../../controller-context';
+import './index.css';
+
+export function Navigation({
+  collapsed,
+  onCollapsedChange,
+}: {
+  /** The keys of the collapsed groups. */
+  collapsed: ReadonlySet<string>;
+  /** Sets the keys as a group opens or collapses, as a state setter does. */
+  onCollapsedChange: Dispatch<SetStateAction<ReadonlySet<string>>>;
+}) {
+  const controller = usePreviewController();
+  const selection = usePreviewState((state) => state.selection);
+  // A page opened on a selection (a followed link) scrolls the selected entry
+  // to the middle of the navigation once, so a long list opens around it,
+  // with what comes before and after it in view.
+  const navigation = useRef<HTMLElement>(null);
+  useEffect(() => {
+    // The navigation's scrolling region (its ScrollArea's, by its role)
+    // scrolls, a whole row at a time, and nothing around it.
+    const selected = navigation.current?.querySelector('[aria-current]');
+    const viewport = selected?.closest('[role="region"]');
+    if (!(selected instanceof HTMLElement) || !(viewport instanceof HTMLElement)) return;
+    const row = parseFloat(getComputedStyle(viewport).lineHeight) || 1;
+    const offset =
+      selected.getBoundingClientRect().top - viewport.getBoundingClientRect().top + viewport.scrollTop;
+    viewport.scrollTop = Math.max(0, Math.round((offset - viewport.clientHeight / 2) / row) * row);
+  }, []);
+  function syncGroup(key: string, open: boolean) {
+    onCollapsedChange((previous) => {
+      const next = new Set(previous);
+      if (open) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  }
+  // The nested navigation: groups are charcell TreeGroups (open state on the
+  // row's aria-expanded, connectors structural), leaves TreeItems; depth 0 renders the
+  // bold root variants. The Tree is one tab stop, its rows reached with the
+  // arrow keys.
+  function renderNavigation(nodes: PreviewNavigationNode[], depth: number): React.ReactNode {
+    return nodes.map((node) => {
+      if (node.kind === 'group') {
+        return (
+          <TreeGroup
+            key={node.key}
+            root={depth === 0}
+            label={node.label}
+            open={!collapsed.has(node.key)}
+            onOpenChange={(open) => syncGroup(node.key, open)}
+          >
+            {renderNavigation(node.children, depth + 1)}
+          </TreeGroup>
+        );
+      }
+      const selected = node.id === selection.id && (node.kind === 'view') === (selection.kind === 'view');
+      return (
+        <TreeItem
+          key={node.kind === 'view' ? `view:${node.id}` : node.id}
+          data-preview-entry={`${node.kind}:${node.id}`}
+          root={depth === 0}
+          label={node.label}
+          current={selected}
+          // The selected entry stays focusable, the tree's one tab stop;
+          // choosing it again changes nothing.
+          onClick={() => {
+            if (!selected) controller.actions.select({ kind: node.kind, id: node.id });
+          }}
+        />
+      );
+    });
+  }
+
+  return (
+    <nav ref={navigation} className="Navigation">
+      {/* The composed navigation: depth-0 entries are bold roots (a source wrapper, the
+          "Components" tree, or a root-level view such as a tokens page); deeper entries
+          are the box-drawing category tree. Groups collapse; leaves select. */}
+      <ScrollArea label="components" overscroll="none" fill>
+        <div className="Navigation__content">
+          <Tree aria-label="stories and views">{renderNavigation(controller.catalog.navigation, 0)}</Tree>
+        </div>
+      </ScrollArea>
+    </nav>
+  );
+}

package/application/shells/charcell/components/NavigationSplit/index.css

@@ -0,0 +1,16 @@
+@layer charcell.components {
+  /* The body under the prompt bar, which the split fills. */
+  .NavigationSplit {
+    display: grid;
+    grid-template: minmax(0, 1fr) / minmax(0, 1fr);
+    min-height: 0;
+  }
+  /* The navigation's panel: the navigation, then the navigation's line, a column
+     down the panel's height. */
+  .NavigationSplit__navigation {
+    flex: 1 1 auto;
+    display: flex;
+    min-width: 0;
+    min-height: 0;
+  }
+}

package/application/shells/charcell/components/NavigationSplit/index.tsx

@@ -0,0 +1,82 @@
+// The body under the prompt bar: the navigation beside the stage, in a charcell
+// Splitter. The navigation ends in its line, a faint vertical Separator joined to
+// the prompt bar's and the status bar's rules above and below as ┬ and ┴; the
+// handle is the empty column between that line and the stage's, its grip in
+// the middle, and drags the boundary a whole column at a time. The navigation
+// starts wide enough for its longest entry, as the tree indents it, from 27
+// columns up to 40, its line one more, measured by the split in the face's
+// own columns once the fonts have loaded; keeps at least 16, so
+// the tree's labels still read; and keeps its columns when the window
+// resizes, the stage taking the difference. While the navigation is hidden the
+// split holds the stage alone, in the same place, so the stage keeps its
+// frames.
+import { useMemo, type ReactNode } from 'react';
+import type { PreviewNavigationNode } from '../../../../../src/shell';
+import { usePreviewController } from '../../controller-context';
+import { Separator, SplitterDriver, SplitterHandle, SplitterPanel, SplitterVisual } from 'charcell/react/unlinked';
+import './index.css';
+
+/** The fewest and the most columns the navigation starts at, its line one more. */
+const NAVIGATION_START_COLUMNS = { least: 27, most: 40 };
+
+/** The columns the navigation's entries take as the tree lays them out: a
+ *  cell's margin, three columns of tree lines per level, the label, on a
+ *  group a cell and its `[+]` after it; then a cell's margin and the
+ *  scrollbar's column. */
+function navigationColumns(nodes: PreviewNavigationNode[], depth = 0): number {
+  return nodes.reduce((widest, node) => {
+    const disclosure = node.kind === 'group' ? 4 : 0;
+    const own = 1 + depth * 3 + disclosure + node.label.length + 2;
+    const children = node.kind === 'group' ? navigationColumns(node.children, depth + 1) : 0;
+    return Math.max(widest, own, children);
+  }, 0);
+}
+
+/** The fewest columns the navigation keeps, its line one more. */
+const NAVIGATION_LEAST_COLUMNS = 16;
+
+export function NavigationSplit({ navigation, main, shown }: { navigation: ReactNode; main: ReactNode; shown: boolean }) {
+  const { navigation: entries } = usePreviewController().catalog;
+  const startColumns = useMemo(
+    () =>
+      Math.min(NAVIGATION_START_COLUMNS.most, Math.max(NAVIGATION_START_COLUMNS.least, navigationColumns(entries))),
+    [entries],
+  );
+  const panels = useMemo(
+    () =>
+      shown
+        ? [
+            {
+              id: 'navigation',
+              minimumCells: NAVIGATION_LEAST_COLUMNS + 1,
+              keepCells: true,
+              defaultCells: startColumns + 1,
+            },
+            { id: 'main' },
+          ]
+        : [{ id: 'main' }],
+    [shown, startColumns],
+  );
+  return (
+    <div className="NavigationSplit">
+      <SplitterDriver panels={panels}>
+        {({ api }) => (
+          <SplitterVisual fill {...api.getRootProps()}>
+            {/* The navigation and its handle come first and leave holes while
+                hidden, so the stage keeps its place in the tree. */}
+            {shown && (
+              <SplitterPanel {...api.getPanelProps({ id: 'navigation' })}>
+                <div className="NavigationSplit__navigation">
+                  {navigation}
+                  <Separator orientation="vertical" decorative join="both" />
+                </div>
+              </SplitterPanel>
+            )}
+            {shown && <SplitterHandle label="resize navigation" {...api.getResizeTriggerProps({ id: 'navigation:main' })} />}
+            <SplitterPanel {...api.getPanelProps({ id: 'main' })}>{main}</SplitterPanel>
+          </SplitterVisual>
+        )}
+      </SplitterDriver>
+    </div>
+  );
+}

package/application/shells/charcell/components/OptionControls/index.tsx

@@ -0,0 +1,93 @@
+// The preview's option controls, rendered from the descriptors the controller
+// holds: the kit's options and the shell's own. An option says what it means,
+// and this shell decides where it goes (placement.ts). The widget follows the
+// option's kind: a select for a choice, an on/off toggle for a boolean.
+import { Field as CharcellField, Toggle } from 'charcell/react/unlinked';
+import { useId } from 'react';
+import { optionKind, type OptionValue, type PreviewOptionDescriptor } from '../../../../../src/shell';
+import type { CharcellRegion } from '../../configuration';
+import { usePreviewController, usePreviewState, useShellConfiguration } from '../../controller-context';
+import { optionPlacement } from '../../placement';
+import { Select } from '../Select';
+import { Hint } from '../Hint';
+
+// One preview-option control (a Select or an on/off toggle).
+function OptionControl({
+  option,
+  value,
+  onChange,
+}: {
+  option: PreviewOptionDescriptor;
+  value: OptionValue | undefined;
+  onChange: (value: OptionValue) => void;
+}) {
+  const labelId = useId();
+  if (optionKind(option) === 'boolean') {
+    // The toggle's text is its state; the option's label names it.
+    return (
+      <CharcellField label={option.label} labelId={labelId}>
+        <Hint text={option.title} markdown around>
+          {(hint) => (
+            <Toggle
+              variant="dense"
+              {...hint}
+              aria-labelledby={labelId}
+              label={value ? 'on' : 'off'}
+              pressed={Boolean(value)}
+              onPressedChange={() => onChange(!value)}
+            />
+          )}
+        </Hint>
+      </CharcellField>
+    );
+  }
+  return (
+    <Select
+      label={option.label}
+      value={String(value ?? '')}
+      onChange={(value) => onChange(value)}
+      options={option.values ?? []}
+    />
+  );
+}
+
+// The controls of the kit's options placed in one region, in registry order.
+// The options the current story marks unavailable are hidden.
+export function OptionControls({ placement }: { placement: CharcellRegion }) {
+  const controller = usePreviewController();
+  const { groups } = useShellConfiguration();
+  const values = usePreviewState((state) => state.options);
+  const unavailable = usePreviewState((state) => state.unavailableOptions);
+  const options = kitOptions(controller.options).filter(
+    (option) => optionPlacement(option, groups) === placement && !unavailable.includes(option.id),
+  );
+  return (
+    <>
+      {options.map((option) => (
+        <OptionControl
+          key={option.id}
+          option={option}
+          value={values[option.id]}
+          onChange={(value) => controller.actions.setOption(option.id, value)}
+        />
+      ))}
+    </>
+  );
+}
+
+/** Whether any option the current story offers is placed in a region - so a
+ *  bar can leave out an empty zone. */
+export function useHasOptionControls(placement: CharcellRegion): boolean {
+  const controller = usePreviewController();
+  const { groups } = useShellConfiguration();
+  const unavailable = usePreviewState((state) => state.unavailableOptions);
+  return kitOptions(controller.options).some(
+    (option) => optionPlacement(option, groups) === placement && !unavailable.includes(option.id),
+  );
+}
+
+/** The kit's options: the shell's own (the navigation, the views, the code
+ *  panes' wrapping) have controls of their own. */
+function kitOptions(options: PreviewOptionDescriptor[]): PreviewOptionDescriptor[] {
+  return options.filter((option) => option.origin === 'kit');
+}

package/application/shells/charcell/components/PaneStatus/index.css

@@ -0,0 +1,7 @@
+@layer charcell.components {
+  /* The panes' state sits at the status bar's tone; a failure steps up to
+     the foreground, so it is the one word that stands out. */
+  .PaneStatus--failed {
+    color: var(--charcell-foreground);
+  }
+}