@juwel-development/design-system 4.1.0 → 4.2.1

package/src/Arrangement/ColumnLayout/ColumnLayout.tsx

@@ -10,7 +10,11 @@ import {
   type ReactElement,
   type ReactNode,
   useContext,
+  useLayoutEffect,
+  useRef,
+  useState,
 } from 'react';
+import { flushSync } from 'react-dom';
 import { ColumnLayoutCompositionError } from './ColumnLayoutCompositionError';
 import { ColumnLayoutConfigurationError } from './ColumnLayoutConfigurationError';
 
@@ -47,12 +51,43 @@ const columnLayoutColumn = cva(
   'min-w-0 grow-[calc(var(--column-layout-weight)/var(--column-layout-growth-unit))] basis-[clamp(0px,(var(--column-layout-threshold)-100%)*1000000,100%)] max-w-[var(--column-layout-maximum)]',
 );
 
+// The selecting holder is the box the alternatives are measured against; it takes no space of
+// its own. The probes sit out of flow and clipped, so a shortfall never becomes overflow.
+const columnLayoutAlternatives = cva('relative min-w-0', {
+  variants: { fill: { false: '', true: 'h-full min-h-0' } },
+  defaultVariants: { fill: false },
+});
+const columnLayoutFitProbes = cva(
+  'pointer-events-none invisible absolute inset-x-0 top-0 h-0 overflow-hidden',
+);
+
+// One probe per declaration, as wide as that declaration's shortfall: the Column's own switch
+// expression against the holder's width less any reserve, so `0px` means the row would hold and
+// `1px` that it would stack. Reading the width back is the whole measurement - no length is
+// parsed in script.
+const columnLayoutFitProbe = cva(
+  'h-0 w-[clamp(0px,(var(--column-layout-threshold)-100%+var(--column-layout-reserve))*1000000,1px)]',
+  {
+    variants: {
+      gap: {
+        stack: '[--column-layout-gap:var(--space-stack)]',
+        region: '[--column-layout-gap:var(--space-region)]',
+      },
+    },
+    defaultVariants: { gap: 'region' },
+  },
+);
+
 // React's CSSProperties is closed over known properties; the custom properties the recipes
 // read are declared here so the style objects stay typed without an assertion.
 type ColumnLayoutRootStyle = CSSProperties & {
   '--column-layout-threshold': string;
   '--column-layout-growth-unit': number;
 };
+type ColumnLayoutFitProbeStyle = CSSProperties & {
+  '--column-layout-threshold': string;
+  '--column-layout-reserve': string;
+};
 type ColumnLayoutColumnStyle = CSSProperties & {
   '--column-layout-weight': number;
   '--column-layout-maximum': string;
@@ -227,6 +262,240 @@ const ColumnLayoutColumn: FunctionComponent<IColumnLayoutColumnProps> = ({
   );
 };
 
+export interface IColumnLayoutAlternativesProps
+  extends VariantProps<typeof columnLayoutAlternatives> {
+  /** Accept the parent's allocated height and pass it to the mounted arrangement or fallback,
+   *  which must accept it in turn (`ColumnLayout.Root fill`, `Tabs.Root fill`). */
+  fill?: VariantProps<typeof columnLayoutAlternatives>['fill'];
+  /** Mounted when none of the alternatives fits. Omitted, `undefined`, `null` or `false`, the
+   *  last declared arrangement stays mounted instead, under its own stacking contract. */
+  fallback?: ReactNode;
+  /** The alternative arrangements in order of preference, as `ColumnLayout.Root` elements with
+   *  at least one column each: direct children, or arrays and fragments of them. A conditional
+   *  that renders nothing declares nothing. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+type Arrangement = ReactElement<IColumnLayoutRootProps>;
+
+// What an alternative contributes to selection: the Root to mount and the width its row holds at.
+type Declaration = { arrangement: Arrangement; threshold: string };
+
+// The outcome of one measurement, kept with the declarations it was taken for: an index into
+// them, or NONE_FITS.
+type Selection = { measured: string; firstFit: number };
+
+// A selection change: the choice it mounted and the holder width that asked for it.
+type Change = { to: number; width: number };
+
+const NONE_FITS = -1;
+
+// Changes further apart than this are separate events, not one mount answering another: a skipped
+// observation is delivered in the next frame, and a content update the frame after.
+const FEEDBACK_FRAMES = 3;
+
+// The width the holder loses to `asked`, where the trail shows it: two round trips, to `asked` at
+// this width and away at one other width. Only a holder whose width answers to what is mounted
+// repeats itself this exactly.
+const lossTo = (
+  trail: readonly Change[],
+  asked: number,
+  width: number,
+): number | undefined => {
+  const [first, away, second, awayAgain] = trail;
+  const isRepeated =
+    first?.to === asked &&
+    second?.to === asked &&
+    first.width === width &&
+    second.width === width &&
+    away?.to === awayAgain?.to &&
+    away?.width === awayAgain?.width;
+  return isRepeated && awayAgain !== undefined && awayAgain.width !== width
+    ? Math.abs(width - awayAgain.width)
+    : undefined;
+};
+
+const isRoot = (node: ReactNode): node is Arrangement =>
+  isValidElement(node) && node.type === ColumnLayoutRoot;
+
+const collectArrangements = (children: ReactNode): Arrangement[] =>
+  Children.toArray(children).flatMap((child) => {
+    if (isFragment(child)) {
+      return collectArrangements(child.props.children);
+    }
+    if (!isRoot(child)) {
+      throw new ColumnLayoutConfigurationError(
+        'Alternatives takes ColumnLayout.Root elements only (arrays and fragments are fine; other content or a wrapping component is not)',
+      );
+    }
+    return [child];
+  });
+
+const toDeclaration = (
+  arrangement: Arrangement,
+  index: number,
+): Declaration => {
+  const tracks = collectColumns(arrangement.props.children).map(toTrack);
+  if (tracks.length === 0) {
+    throw new ColumnLayoutConfigurationError(
+      `alternative ${index + 1} declares no columns, so it has no minimum to fit`,
+    );
+  }
+  return { arrangement, threshold: thresholdOf(tracks) };
+};
+
+const probeStyleOf = (
+  threshold: string,
+  reserve: string,
+): ColumnLayoutFitProbeStyle => ({
+  '--column-layout-threshold': threshold,
+  '--column-layout-reserve': reserve,
+});
+
+// A probe is as wide as its declaration's shortfall, so a width of zero is a fit. No declaration
+// at all answers NONE_FITS, which is also what "none fits" reads as.
+const firstFitOf = (probes: HTMLElement): number =>
+  Array.from(probes.children).findIndex(
+    (probe) => probe.getBoundingClientRect().width === 0,
+  );
+
+// Declaration order is the preference; the fallback and the retained last declaration come after
+// every declaration that fits.
+const preferenceOf = (firstFit: number): number =>
+  firstFit === NONE_FITS ? Number.POSITIVE_INFINITY : firstFit;
+
+const ColumnLayoutAlternatives: FunctionComponent<
+  IColumnLayoutAlternativesProps
+> = ({ fill, fallback, children, testId }) => {
+  const declarations = collectArrangements(children).map(toDeclaration);
+  const declared = declarations
+    .map(
+      ({ arrangement, threshold }) => `${arrangement.props.gap} ${threshold}`,
+    )
+    .join('\n');
+  const probes = useRef<HTMLDivElement>(null);
+  const mounted = useRef<ReactNode>(null);
+  const [selection, setSelection] = useState<Selection | undefined>(undefined);
+  const [reserve, setReserve] = useState(0);
+
+  // The first selection is made before the first paint; from then on a probe changes size only
+  // when its declaration's fit flips - on a holder resize or a re-pointed token alike. flushSync
+  // commits the new arrangement inside the observation, so no frame paints the outgoing one.
+  useLayoutEffect(() => {
+    const holder = probes.current;
+    if (holder === null) {
+      return;
+    }
+    let selected: number | undefined;
+    let trail: readonly Change[] = [];
+    const keep = (change: Change): void => {
+      const kept = [...trail.slice(-3), change];
+      let frames = FEEDBACK_FRAMES;
+      const tick = (): void => {
+        if (trail !== kept) {
+          return;
+        }
+        frames -= 1;
+        if (frames === 0) {
+          trail = [];
+        } else {
+          requestAnimationFrame(tick);
+        }
+      };
+      trail = kept;
+      requestAnimationFrame(tick);
+    };
+    const select = (): void => {
+      const asked = firstFitOf(holder);
+      if (asked === selected) {
+        return;
+      }
+      const { width } = holder.getBoundingClientRect();
+      const lost = lossTo(trail, asked, width);
+      if (lost !== undefined) {
+        // Hold the loss back from the preferred of the two, and settle on the later declaration.
+        setReserve((reserved) => Math.max(reserved, lost));
+        trail = [];
+        if (
+          selected !== undefined &&
+          preferenceOf(asked) < preferenceOf(selected)
+        ) {
+          return;
+        }
+      }
+      keep({ to: asked, width });
+      selected = asked;
+      setSelection({ measured: declared, firstFit: asked });
+    };
+    setReserve(0);
+    select();
+    if (typeof ResizeObserver === 'undefined') {
+      return;
+    }
+    const observer = new ResizeObserver(() => flushSync(select));
+    for (const probe of holder.children) {
+      observer.observe(probe);
+    }
+    return () => {
+      trail = [];
+      observer.disconnect();
+    };
+  }, [declared]);
+
+  const hasFallback =
+    fallback !== undefined && fallback !== null && fallback !== false;
+  // A selection measured for other declarations says nothing about these: what it mounted stays
+  // until the effect above has measured them, so no unselected arrangement mounts in between.
+  const current = selection?.measured === declared ? selection : undefined;
+  const fitting =
+    current === undefined
+      ? undefined
+      : declarations[current.firstFit]?.arrangement;
+  const chosen =
+    fitting ?? (hasFallback ? undefined : declarations.at(-1)?.arrangement);
+  const content: ReactNode =
+    current === undefined ? (
+      mounted.current
+    ) : chosen === undefined ? (
+      hasFallback && <Fragment key="fallback">{fallback}</Fragment>
+    ) : (
+      <ColumnLayoutRoot
+        key="arrangement"
+        gap={chosen.props.gap}
+        fill={chosen.props.fill}
+        testId={chosen.props.testId}
+      >
+        {chosen.props.children}
+      </ColumnLayoutRoot>
+    );
+  useLayoutEffect(() => {
+    mounted.current = content;
+  });
+
+  // Only a declaration preferred to the mounted one is judged with the reserve: the mounted one
+  // and those after it are measured at the width the holder has.
+  const reserveOf = (index: number): string =>
+    current !== undefined && index < preferenceOf(current.firstFit)
+      ? `${reserve}px`
+      : '0px';
+  return (
+    <div className={columnLayoutAlternatives({ fill })} data-testid={testId}>
+      <div ref={probes} aria-hidden="true" className={columnLayoutFitProbes()}>
+        {declarations.map(({ arrangement, threshold }, index) => (
+          <div
+            // biome-ignore lint/suspicious/noArrayIndexKey: a probe's identity is its place in the order of preference
+            key={index}
+            className={columnLayoutFitProbe({ gap: arrangement.props.gap })}
+            style={probeStyleOf(threshold, reserveOf(index))}
+          />
+        ))}
+      </div>
+      {content}
+    </div>
+  );
+};
+
 /**
  * An arrangement of weighted columns that becomes one column when the space it is given cannot
  * satisfy every column's minimum at the requested proportions. It owns the arrangement and nothing
@@ -275,6 +544,38 @@ const ColumnLayoutColumn: FunctionComponent<IColumnLayoutColumnProps> = ({
  *   `Root` - loose, nested in another column, or reached through a wrapping component - throws
  *   {@link ColumnLayoutCompositionError}. Both are programmer errors, raised loud and early.
  *
+ * @Guarantees — `Alternatives`, the consumer's choice between arrangements
+ * - Its children are `Root`s in the consumer's order of preference. It mounts the first whose
+ *   row would hold at its own width - the same threshold, tokens and gap that Root switches at,
+ *   compared by the browser, with equality fitting - also when later ones fit too. Nothing is
+ *   ranked, inferred or keyed to the viewport; two instances on a page select independently.
+ * - When none fits it mounts `fallback` if one was supplied, and otherwise keeps the last
+ *   declared Root, which stacks under its own contract. Selection never floors a width, so it
+ *   causes no horizontal overflow. With nothing declared it mounts the fallback, or nothing.
+ * - Selection follows the holder's width and every token the thresholds read - a re-pointed
+ *   minimum, a space role, a font-relative unit - without a resize, and is committed before the
+ *   next paint. Until the first measurement (a server render, the first client render) no
+ *   arrangement is mounted. Without layout, as in jsdom, every declaration measures as fitting.
+ * - Only the selected arrangement is mounted: no second copy of an area, an id or a control, and
+ *   nothing kept hidden. A change that leaves the selection alone touches no content. When the
+ *   declarations themselves change, what is mounted stays until the new ones are measured, in
+ *   the same update: nothing they do not select is mounted in between.
+ * - A holder that loses width to what is mounted in it - a scroll body whose scrollbar shows for
+ *   one arrangement only - settles. Once the same two selections have alternated at the same two
+ *   widths twice, no more than three frames apart, the later declaration stays and the width lost
+ *   is held back from every declaration preferred to the mounted one until the declarations
+ *   change: an earlier one returns once it fits with that much to spare. Otherwise nothing is
+ *   held back, and a width that merely drops and returns is followed exactly.
+ * - On a selection change a column declared in both arrangements under the same React `key`
+ *   (unkeyed: the same position) with the same element types inside stays mounted, with its
+ *   state and focus. Everything else unmounts; content that returns mounts fresh, and no focus,
+ *   text selection, scroll position or local state is cached or restored for it.
+ * - It adds no role, name, tab stop, spacing, scrolling or selection request of its own. With
+ *   `fill` it passes its parent's allocated height to what it mounts.
+ * - A child that is not a `Root` - text, another element, a component wrapping a Root - or a
+ *   Root without columns throws {@link ColumnLayoutConfigurationError}. Every declaration is
+ *   validated, whether or not it is the one mounted.
+ *
  * @CallerMustEnsure — the component cannot see these and does not check them
  * - Every `minWidth` and supplied `maxWidth` token is declared, on the Root or an ancestor of it,
  *   as a valid nonnegative CSS length: `24rem`, `20em`, `40ch`, `320px`. A `rem` resolves against
@@ -293,6 +594,13 @@ const ColumnLayoutColumn: FunctionComponent<IColumnLayoutColumnProps> = ({
  * - `Root`'s children are `Column`s. Anything else placed beside them is rendered as given but is
  *   not a column: it takes no weight, counts for no gap or threshold, and sits in the row as
  *   content of its own width, which breaks the proportions. Content belongs inside a `Column`.
+ * - For `Alternatives`: state that must survive a removal - a draft, the active tab - is kept
+ *   by the application and supplied to the fresh mount; Tabs inside an arrangement receive a
+ *   valid `active` whenever they mount. An area that should stay mounted carries the same `key`
+ *   in each arrangement. With `fill`, the Roots and the fallback accept the height themselves.
+ *   A holder whose width answers to the mounted arrangement more than three frames after the
+ *   mount, or differently each time, is outside the contract: that dependency is not recognised
+ *   and can alternate.
  *
  * @UXGuidelines
  * - A minimum is the width below which the column's content stops being readable or operable -
@@ -300,8 +608,12 @@ const ColumnLayoutColumn: FunctionComponent<IColumnLayoutColumnProps> = ({
  *   lines - not the width the designer would like. The stack is the readable fallback.
  * - Weights are structural relationships: `2` and `1` say the table is the subject and the summary
  *   its support. A ratio chosen to hit a pixel width is a measurement, and the theme owns those.
+ * - Alternatives are for one screen arranged differently, not for different screens: declare the
+ *   same areas in the same reading order and let the narrower arrangement group some of them,
+ *   in `Tabs` for instance. Which areas exist and how they group is the application's decision.
  */
 export const ColumnLayout = {
   Root: ColumnLayoutRoot,
   Column: ColumnLayoutColumn,
+  Alternatives: ColumnLayoutAlternatives,
 } as const;

package/src/Display/Table/Table.tsx

@@ -325,8 +325,8 @@ const useOverflow = (
   table: { current: HTMLElement | null },
   caption: { current: HTMLElement | null },
   bounded: boolean,
-): boolean => {
-  const [isOverflowing, setIsOverflowing] = useState(true);
+): number | undefined => {
+  const [scrollTabIndex, setScrollTabIndex] = useState<number | undefined>(0);
   useLayoutEffect(() => {
     const element = wrapper.current;
     if (element === null) return;
@@ -341,10 +341,27 @@ const useOverflow = (
           Number.parseFloat(getComputedStyle(element).paddingTop) || 0;
         element.style.scrollPaddingTop = `${headerHeight + 2 * ringRoom}px`;
       }
-      setIsOverflowing(
+      // Only bounded tables participate in Dialog release. Reading an absent inherited custom
+      // property is depth-dependent in jsdom 29.1.1, even for ordinary content tables (#157).
+      const isReleased =
+        bounded &&
+        getComputedStyle(element)
+          .getPropertyValue('--_scroll-released')
+          .trim() === '1';
+      const isFocused = element === document.activeElement;
+      const overflows =
         element.scrollWidth > element.clientWidth ||
-          (bounded && element.scrollHeight > element.clientHeight) ||
-          element === document.activeElement,
+        (bounded && element.scrollHeight > element.clientHeight);
+      // Removing tabindex from an active element blurs it in Chromium. A retained -1 keeps
+      // that focus through release while removing the extra scrolling stop from Tab order.
+      setScrollTabIndex(
+        isReleased
+          ? isFocused
+            ? -1
+            : undefined
+          : overflows || isFocused
+            ? 0
+            : undefined,
       );
     };
     measure();
@@ -376,11 +393,16 @@ const useOverflow = (
       element.removeEventListener('blur', measure);
     };
   }, [wrapper, table, caption, bounded]);
-  return isOverflowing;
+  return scrollTabIndex;
 };
 
 const revealFocus = (event: FocusEvent<HTMLDivElement>): void => {
   const wrapper = event.currentTarget;
+  if (
+    getComputedStyle(wrapper).getPropertyValue('--_scroll-released').trim() ===
+    '1'
+  )
+    return;
   const target = event.target;
   if (target === wrapper) return;
   const bounds = wrapper.getBoundingClientRect();
@@ -428,12 +450,13 @@ const TableRoot: FunctionComponent<ITableRootProps> = ({
   const tableElement = useRef<HTMLTableElement>(null);
   const captionElement = useRef<HTMLTableCaptionElement>(null);
   const trackList = trackListOf(columns);
-  const isOverflowing = useOverflow(
+  const scrollTabIndex = useOverflow(
     wrapper,
     tableElement,
     captionElement,
     bounded === true,
   );
+  const isOverflowing = scrollTabIndex !== undefined;
   const style: TableRootStyle | undefined =
     trackList === undefined ? undefined : { '--table-columns': trackList };
   const columnCount = trackList === undefined ? undefined : columns?.length;
@@ -500,7 +523,7 @@ const TableRoot: FunctionComponent<ITableRootProps> = ({
       data-testid={testId}
       role={isOverflowing ? 'group' : undefined}
       aria-label={isOverflowing ? caption : undefined}
-      tabIndex={isOverflowing ? 0 : undefined}
+      tabIndex={scrollTabIndex}
     >
       {content}
     </div>
@@ -683,6 +706,10 @@ const TableCell: FunctionComponent<ITableCellProps> = ({
  *   table holding an interactive row makes ring room around itself, so a focused row's ring is never
  *   clipped by the scroll region. A table with neither keeps its static geometry exactly.
  *
+ * - In Dialog's insufficient-height fallback the enclosing Dialog releases this wrapper's
+ *   bound and pinned header. It contributes no independent scroll region or scroll tab stop;
+ *   content and focus stay mounted while sufficient space restores bounded scrolling.
+ *
  * @CallerMustEnsure — the component cannot see these and does not check them
  * - For bounded mode supply finite usable parent height, with room for the header and readable rows.
  *   Compose directly inside `Pane.Body scrollOwner="child"` or `Dialog.Content scrollOwner="child"`:

package/src/Interaction/Choices/Choices.tsx

@@ -1,4 +1,4 @@
-import { cva } from 'class-variance-authority';
+import { cva, type VariantProps } from 'class-variance-authority';
 import {
   createContext,
   type FunctionComponent,
@@ -10,7 +10,15 @@ import {
 import type { Subject } from 'rxjs';
 import { ChoicesCompositionError } from './ChoicesCompositionError';
 
-const choicesGroup = cva('flex flex-col gap-[var(--space-stack)]');
+const choicesGroup = cva('flex min-w-0 gap-[var(--space-stack)]', {
+  variants: {
+    arrangement: {
+      vertical: 'flex-col [&>[role=radio]]:w-full',
+      wrapping: 'flex-row flex-wrap items-start',
+    },
+  },
+  defaultVariants: { arrangement: 'vertical' },
+});
 
 // The selected row is told apart by the marker dot and a boundary flip from `controlBorder` to
 // `foreground` - Tabs' marker treatment, keyed on aria-checked so the attribute the device reads
@@ -18,7 +26,7 @@ const choicesGroup = cva('flex flex-col gap-[var(--space-stack)]');
 // geometry. Inert mutes only the name's ink (the Sidebar treatment); the selection stays visible.
 const choicesChoice = cva(
   [
-    'group/choice flex w-full flex-row items-start gap-3 text-left',
+    'group/choice flex min-w-0 max-w-full flex-none flex-row items-start gap-3 text-left wrap-anywhere',
     'rounded-[var(--radius-control)] border border-solid border-control-border bg-transparent aria-checked:border-foreground',
     'px-3 py-2',
     'cursor-pointer disabled:cursor-not-allowed',
@@ -68,7 +76,10 @@ const ARROW_STEP: Record<string, 1 | -1> = {
   ArrowLeft: -1,
 };
 
-export interface IChoicesRootProps {
+export interface IChoicesRootProps extends VariantProps<typeof choicesGroup> {
+  /** Full-width vertical rows by default; wrapping uses content-sized choices that flow onto
+   *  further lines. Both arrangements keep declared-order keyboard movement. */
+  arrangement?: VariantProps<typeof choicesGroup>['arrangement'];
   /** The key of the selected choice. Must name a declared choice; the consumer owns it. */
   selected: string;
   /** Emits a choice's key when an available non-selected row is activated by pointer or arrow
@@ -76,7 +87,7 @@ export interface IChoicesRootProps {
   onSelect$: Subject<string>;
   /** The radio group's accessible name. */
   label: string;
-  /** Present with its retained selection and every description visible, but unavailable:
+  /** Present with its retained selection and every supplied description visible, but unavailable:
    *  semantically disabled, skipped by Tab, and deaf to pointer and keyboard input. */
   inert?: boolean;
   children: ReactNode;
@@ -89,12 +100,13 @@ export interface IChoicesChoiceProps {
   value: string;
   /** The visible name. Text only - no icons, no per-row markup. */
   children: string;
-  /** The visible description under the name, exposed as the row's accessible description. */
-  description: string;
+  /** Optional visible text under the name, exposed as the choice's accessible description. */
+  description?: string;
   testId?: string;
 }
 
 const ChoicesRoot: FunctionComponent<IChoicesRootProps> = ({
+  arrangement,
   selected,
   onSelect$,
   label,
@@ -109,7 +121,7 @@ const ChoicesRoot: FunctionComponent<IChoicesRootProps> = ({
       role={'radiogroup'}
       aria-label={label}
       aria-disabled={inert === true ? 'true' : undefined}
-      className={choicesGroup()}
+      className={choicesGroup({ arrangement })}
       data-testid={testId}
     >
       {children}
@@ -157,7 +169,7 @@ const ChoicesChoice: FunctionComponent<IChoicesChoiceProps> = ({
       role={'radio'}
       aria-checked={isSelected}
       aria-labelledby={nameId}
-      aria-describedby={descriptionId}
+      aria-describedby={description ? descriptionId : undefined}
       tabIndex={isSelected && !inert ? 0 : -1}
       disabled={inert}
       data-value={value}
@@ -200,19 +212,21 @@ const ChoicesChoice: FunctionComponent<IChoicesChoiceProps> = ({
         >
           {children}
         </span>
-        <span
-          id={descriptionId}
-          className={'font-secondary text-muted text-small'}
-        >
-          {description}
-        </span>
+        {description && (
+          <span
+            id={descriptionId}
+            className={'font-secondary text-muted text-small'}
+          >
+            {description}
+          </span>
+        )}
       </span>
     </button>
   );
 };
 
 /**
- * A single selection from a small set of described options: vertically arranged choice rows,
+ * A single selection from a small set of named options with optional descriptions: choice rows,
  * exactly one selected, following the WAI-ARIA radio-group pattern. Controlled - the consumer owns
  * the selected key and every word; Choices owns the rows, the marker and the highlight. Composed
  * from two members: `Root` carries the contract, `Choice` one row.
@@ -220,7 +234,8 @@ const ChoicesChoice: FunctionComponent<IChoicesChoiceProps> = ({
  * @Guarantees — enforced on every render
  * - Renders `role="radiogroup"` named by `label`, with each row a `role="radio"` button carrying
  *   `aria-checked`, its visible name as accessible name and its description as accessible
- *   description; ids are minted per row, so two groups on a page cannot collide.
+ *   description when supplied; omitted or empty descriptions render no content or association.
+ *   Ids are minted per row, so two groups on a page cannot collide.
  * - Selection is the value of `selected`, nothing else: activating an available non-selected row
  *   emits its key on `onSelect$`; the selected row, an unanswered request and every render emit
  *   nothing, and no fallback selection is invented - ever.
@@ -232,7 +247,10 @@ const ChoicesChoice: FunctionComponent<IChoicesChoiceProps> = ({
  * - An inert group keeps the selected marker, highlight and every name and description visible,
  *   mutes only the names' ink, exposes `aria-disabled` on the group with every row disabled, adds
  *   no Tab stop, and emits nothing for any pointer or keyboard input.
- * - Names and descriptions wrap at narrow widths; a row never widens its group.
+ * - `arrangement="vertical"` (the default) gives every choice the group's width. `wrapping`
+ *   sizes choices to content without sharing surplus width and flows whole choices onto further
+ *   lines. Names, unbroken words and supplied descriptions wrap within the available group width.
+ * - Arrow order is declared order even across visual line breaks, never spatial row navigation.
  *
  * @CallerMustEnsure — the component cannot see these and does not check them
  * - Choice rows are direct children of `Root` (arrays and fragments are supported), each `value`
@@ -243,7 +261,7 @@ const ChoicesChoice: FunctionComponent<IChoicesChoiceProps> = ({
  *   a consumer that ignores a request has decided the selection stays.
  *
  * @UXGuidelines
- * - Names are short nouns for options and descriptions one or two sentences under them; the
+ * - Names are short nouns for options and optional descriptions one or two sentences under them; the
  *   consuming app words and translates both - the library ships no text of its own.
  * - This is not a form field: no `<label>` pairing, no validation, no submission. Wire `onSelect$`
  *   to whatever owns the selected key and pass that key back in.