@juwel-development/design-system 3.1.0 → 3.3.0

package/src/Display/Collection/Collection.tsx

@@ -0,0 +1,58 @@
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+const collectionRoot = cva('m-0 list-none p-0');
+const collectionItem = cva(
+  'py-[var(--space-collection-item)] [&+li]:border-t [&+li]:border-solid [&+li]:border-border',
+);
+
+export interface ICollectionRootProps {
+  /** Collection.Item children, including mapped items and conditional omissions. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+export interface ICollectionItemProps {
+  /** Freely composed content; its typography, arrangement and interaction remain its own. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+const CollectionRoot: FunctionComponent<ICollectionRootProps> = ({
+  children,
+  testId,
+}) => (
+  // biome-ignore lint/a11y/noRedundantRoles: list-style:none removes list semantics in Safari/VoiceOver; Checklist establishes this explicit-role precedent.
+  <ul className={collectionRoot()} role={'list'} data-testid={testId}>
+    {children}
+  </ul>
+);
+
+const CollectionItem: FunctionComponent<ICollectionItemProps> = ({
+  children,
+  testId,
+}) => (
+  <li className={collectionItem()} data-testid={testId}>
+    {children}
+  </li>
+);
+
+/**
+ * A vertical group of freely composed items with internal hairlines and open outer edges.
+ * The library owns spacing and separation; the consumer owns content, arrangement and interaction.
+ *
+ * @Guarantees
+ * - Root is a semantic list and Item a list item, with no visual markers or horizontal indent.
+ * - Each item takes vertical padding from --space-collection-item; adjacent items share one
+ *   hairline in the border colour role. Empty and single-item roots have no rules or placeholder.
+ * - Children render in supplied order, retaining their own typography and arrangement.
+ * - Neither member adds focus stops, interaction, or responsive content rearrangement.
+ *
+ * @CallerMustEnsure
+ * - Supply Collection.Item as Root's rendered children, directly or through fragments and maps.
+ * - Compose each item's content with typography, arrangements and controls for the jobs it contains.
+ */
+export const Collection = {
+  Root: CollectionRoot,
+  Item: CollectionItem,
+} as const;

package/src/Interaction/Tabs/Tabs.tsx

@@ -0,0 +1,284 @@
+import { cva } from 'class-variance-authority';
+import {
+  createContext,
+  type FocusEvent,
+  type FunctionComponent,
+  type KeyboardEvent,
+  type ReactNode,
+  useContext,
+  useId,
+} from 'react';
+import type { Subject } from 'rxjs';
+import { TabsCompositionError } from './TabsCompositionError';
+
+// The row is a single scrolling line, never a wrap: overflow is an accommodation, not a strip. The
+// ring room is written from the two focus-ring tokens so it cannot drift from the ring it exists
+// for: padding holds the scroll clip off the outline, the negative margin hands the room back to
+// the page, and scroll-padding makes a nearest scrollIntoView stop with the ring inside the clip.
+const tabsList = cva(
+  [
+    'flex flex-row overflow-x-auto',
+    'p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))]',
+    'm-[calc(-1*(var(--focus-ring-width)+var(--focus-ring-offset)))]',
+    'scroll-p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))]',
+  ].join(' '),
+);
+
+// Navigation typography - the tracked grotesk label, muted at rest, foreground when current -
+// keyed on aria-selected, so the attribute the device reads is the one the paint follows. The
+// marker keeps one thickness and flips only colour on the shared motion token, so selection
+// shifts no geometry. The focus ring sits in the base with its colour at rest, as on Button.
+const tabsTab = cva(
+  [
+    'font-secondary text-label tracking-label',
+    'text-muted hover:text-foreground aria-selected:text-foreground',
+    'border-b-[length:var(--tab-marker-thickness)] border-solid border-transparent aria-selected:border-foreground',
+    'shrink-0 cursor-pointer select-none text-nowrap px-[var(--tab-inset-inline)] py-[var(--tab-inset-block)]',
+    'transition-colors duration-[var(--motion-duration-color)]',
+    'outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
+  ].join(' '),
+);
+
+// The panel paints nothing of its own; the recipe carries only the focus ring its Tab stop needs -
+// the ring follows focusability, not control-ness.
+const tabsPanel = cva(
+  'outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
+);
+
+type TabsContract = {
+  active: string;
+  onSelect$: Subject<string>;
+  label: string;
+  baseId: string;
+};
+
+const TabsContext = createContext<TabsContract | undefined>(undefined);
+
+const useTabsContract = (member: string): TabsContract => {
+  const contract = useContext(TabsContext);
+  if (contract === undefined) {
+    throw new TabsCompositionError(member);
+  }
+  return contract;
+};
+
+// Fixed-width UTF-16 units preserve every string, including lone surrogates, without whitespace
+// or collisions between escaped and literal values. Encoding changes IDs only, never selection.
+const encodeValue = (value: string): string =>
+  value
+    .split('')
+    .map((unit) => unit.charCodeAt(0).toString(16).padStart(4, '0'))
+    .join('');
+
+const keepFocusedTabVisible = (event: FocusEvent<HTMLButtonElement>): void => {
+  event.currentTarget.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+};
+
+const tabId = (baseId: string, value: string): string =>
+  `${baseId}tab-${encodeValue(value)}`;
+const panelId = (baseId: string, value: string): string =>
+  `${baseId}panel-${encodeValue(value)}`;
+
+// The wrap-around rule on its own: the neighbouring tab in the arrow's direction, from the
+// rendered row (`:scope >` keeps a nested instance's tabs out of it), wrapping at either end -
+// so tab order is rendered order.
+const neighbourTab = (
+  current: HTMLButtonElement,
+  step: 1 | -1,
+): HTMLButtonElement | undefined => {
+  const row = current.closest('[role="tablist"]');
+  if (row === null) {
+    return undefined;
+  }
+  const tabs = Array.from(
+    row.querySelectorAll<HTMLButtonElement>(':scope > [role="tab"]'),
+  );
+  const index = tabs.indexOf(current);
+  return tabs[(index + step + tabs.length) % tabs.length];
+};
+
+export interface ITabsRootProps {
+  /** The key of the active tab. Must name a declared tab/panel pair; the consumer owns it. */
+  active: string;
+  /** Emits the selected key on click and on arrow navigation. Tabs never selects on its own. */
+  onSelect$: Subject<string>;
+  /** The tab list's accessible name. */
+  label: string;
+  children: ReactNode;
+  testId?: string;
+}
+
+export interface ITabsListProps {
+  children: ReactNode;
+  testId?: string;
+}
+
+export interface ITabsTabProps {
+  /** The stable identity connecting this tab to its panel and emitted by selection requests.
+   *  Not React's `key`, and never inferred from the label or the position. */
+  value: string;
+  /** The visible text label. Text only - no icons, no per-tab markup. */
+  children: string;
+  testId?: string;
+}
+
+export interface ITabsPanelProps {
+  /** The tab this panel belongs to - exactly one panel per tab value within a Root. */
+  value: string;
+  /** Mounted only while active; departure unmounts it, return mounts it fresh. */
+  children: ReactNode;
+  testId?: string;
+}
+
+// useId gives each Root one stable id namespace, so two instances on a page cannot collide and the
+// tab/panel associations survive rerenders. That hook and the context are the component's only
+// state-shaped machinery; the selection itself stays the consumer's.
+const TabsRoot: FunctionComponent<ITabsRootProps> = ({
+  active,
+  onSelect$,
+  label,
+  children,
+  testId,
+}) => {
+  const baseId = useId();
+  return (
+    <TabsContext.Provider value={{ active, onSelect$, label, baseId }}>
+      <div data-testid={testId}>{children}</div>
+    </TabsContext.Provider>
+  );
+};
+
+const TabsList: FunctionComponent<ITabsListProps> = ({ children, testId }) => {
+  const { label } = useTabsContract('List');
+  return (
+    <div
+      role="tablist"
+      aria-label={label}
+      className={tabsList()}
+      data-testid={testId}
+    >
+      {children}
+    </div>
+  );
+};
+
+const TabsTab: FunctionComponent<ITabsTabProps> = ({
+  value,
+  children,
+  testId,
+}) => {
+  const { active, onSelect$, baseId } = useTabsContract('Tab');
+  const isActive = active === value;
+
+  // Left/Right move focus to the neighbouring tab and request its selection immediately -
+  // activation follows focus. Other keys fall through: Up/Down keep scrolling the page, Tab
+  // leaves the list for the active panel.
+  const requestNeighbour = (event: KeyboardEvent<HTMLButtonElement>): void => {
+    if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') {
+      return;
+    }
+    event.preventDefault();
+    const neighbour = neighbourTab(
+      event.currentTarget,
+      event.key === 'ArrowRight' ? 1 : -1,
+    );
+    if (neighbour === undefined) {
+      return;
+    }
+    neighbour.focus();
+    const neighbourValue = neighbour.dataset.value;
+    if (neighbourValue !== undefined) {
+      onSelect$.next(neighbourValue);
+    }
+  };
+
+  return (
+    <button
+      type="button"
+      role="tab"
+      id={tabId(baseId, value)}
+      aria-selected={isActive}
+      aria-controls={panelId(baseId, value)}
+      tabIndex={isActive ? 0 : -1}
+      data-value={value}
+      data-testid={testId}
+      className={tabsTab()}
+      onClick={() => onSelect$.next(value)}
+      onKeyDown={requestNeighbour}
+      onFocus={keepFocusedTabVisible}
+    >
+      {children}
+    </button>
+  );
+};
+
+const TabsPanel: FunctionComponent<ITabsPanelProps> = ({
+  value,
+  children,
+  testId,
+}) => {
+  const { active, baseId } = useTabsContract('Panel');
+  const isActive = active === value;
+  return (
+    <div
+      role="tabpanel"
+      id={panelId(baseId, value)}
+      aria-labelledby={tabId(baseId, value)}
+      hidden={!isActive}
+      tabIndex={isActive ? 0 : undefined}
+      className={tabsPanel()}
+      data-testid={testId}
+    >
+      {isActive ? children : undefined}
+    </div>
+  );
+};
+
+/**
+ * A few named views sharing one surface: a horizontal tab list over exactly one visible panel,
+ * following the WAI-ARIA tabs pattern. Controlled - the consumer owns the active key and all
+ * content; Tabs owns the controls and the panels that present it. Composed from four members:
+ * `Root` carries the contract, `List` the scrolling row, `Tab` one control, `Panel` one view.
+ *
+ * @Guarantees — enforced on every render
+ * - Renders `role="tablist"`/`tab`/`tabpanel` with `aria-selected`, `aria-controls` and
+ *   `aria-labelledby` wired per pair; ids are namespaced per instance, so two Tabs on one page
+ *   cannot collide and associations survive rerenders.
+ * - Selection is the value of `active`, nothing else: a selection request that goes unanswered
+ *   changes nothing, and no fallback selection is invented or emitted - ever.
+ * - Only the active panel mounts its children; inactive panels stay hidden and empty, so departure
+ *   unmounts a view and returning mounts it fresh, with no cache and no preserved state.
+ * - Left/Right move focus to the neighbouring tab, wrapping at either end, and request selection
+ *   immediately; focus stays on the operated tab. Up/Down are left to the browser.
+ * - Roving tabindex: Tab enters the list at the active tab, then the active panel - a consistent
+ *   Tab stop whether or not its content is focusable. Inactive panels add no stop.
+ * - The row scrolls horizontally on overflow - one line, no wrap, no shrink - and holds its own
+ *   ring room, so the focused tab's ring survives the scroll clip.
+ * - Selection is marked by a persistent line under the active tab: `--tab-marker-thickness` in
+ *   `foreground`, constant thickness in both states, so switching shifts no widths and no weights.
+ *   Keyboard focus is the separate shared focus ring. Colour moves on the one motion token.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - One List with Tab elements as direct DOM children (arrays and fragments are supported),
+ *   and sibling Panels under Root. Do not wrap tabs in host elements.
+ * - At least two tabs, each `value` unique and stable, each with exactly one matching `Panel`
+ *   under the same `Root`, and `active` naming a declared pair. Invalid input is a contract
+ *   violation, not a request for a fallback.
+ * - An update removing the active tab supplies a valid replacement `active` and the matching
+ *   composition in the same update.
+ * - The newly selected view renders without noticeable delay - slower data belongs inside the
+ *   immediately displayed view. Any state shared or preserved across views is the consumer's.
+ *
+ * @UXGuidelines
+ * - Labels are short names for views, not actions; the consuming app words and translates them.
+ * - This is not a router: no location, no history, no deep links. Wire `onSelect$` to whatever
+ *   owns the active key and pass that key back in.
+ * - The panel is an opaque slot: compose the view's own rhythm inside it - a `Stack`, a `Prose` -
+ *   as the view owns it; Tabs sets no spacing between the row and the panel.
+ */
+export const Tabs = {
+  Root: TabsRoot,
+  List: TabsList,
+  Tab: TabsTab,
+  Panel: TabsPanel,
+} as const;

package/src/Interaction/Tabs/TabsCompositionError.ts

@@ -0,0 +1,6 @@
+export class TabsCompositionError extends Error {
+  constructor(member: string) {
+    super(`Tabs.${member} must be composed inside Tabs.Root`);
+    this.name = 'TabsCompositionError';
+  }
+}

package/src/Layout/Cover/Cover.tsx

@@ -0,0 +1,85 @@
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// One recipe, no variants: both-axes centring is the component's whole job (#96), so there is nothing
+// to choose - a distribution axis waits for evidence under ADR 0008's test. items-center centres the
+// inline axis, the slot's auto margins (below) the block axis; alone among the composables it carries
+// its own inset - the deliberate exception to "Section owns the gutter" (CONTEXT.md: Cover).
+const cover = cva(
+  [
+    'flex flex-col items-center',
+    'min-h-[var(--cover-height)]',
+    'px-[var(--gutter)] py-[var(--space-region)]',
+  ].join(' '),
+);
+
+// Not a second recipe - the slot has nothing to vary, and the standard allows one cva()
+// (design-system-components.md §4), the frame's own above. Block-axis auto margins split the leftover
+// space equally, so a foot after the slot still lands on the bottom edge. The full-width cap keeps a
+// definite-width child - an action column asking for its bound (#99) - inside the frame's inset.
+const slot = 'my-auto max-w-full';
+
+export interface ICoverProps {
+  /** The screen's one opaque slot, centred on both axes. Rendered unmodified: a menu composes a title,
+   *  a tagline and a stack of actions here; a sign-in composes a form. `Cover` imposes no anatomy. */
+  children: ReactNode;
+  /** The line on the screen's bottom edge - a version line, a legal line - centred on the inline axis.
+   *  Omitted - or given nothing: `null`, a flag's `false` - nothing renders: no empty container
+   *  holds its place. */
+  foot?: ReactNode;
+  testId?: string;
+}
+
+/**
+ * A whole screen's frame: a plain container at least the cover height tall that centres one column in
+ * the leftover space, on both axes, with an optional foot pinned to the bottom edge. It is the fold's
+ * counterpart (CONTEXT.md): a menu, a sign-in, a splash is the entire app for a moment, and nothing
+ * follows it - so where `Hero` deliberately stops short of the viewport to say the page continues, a
+ * cover reaches it, because stopping short would signal a continuation that does not exist. It renders
+ * no heading and no landmark: whatever the screen says is composed in the slot.
+ *
+ * @Guarantees — enforced on every render
+ * - It is at least `--cover-height` tall: a `min-height` floor, not a fixed height, so content longer
+ *   than the viewport grows the frame rather than overflowing it.
+ * - `children` sit in the middle of the leftover space, centred on both axes; the centring is fixed,
+ *   with no distribution to choose.
+ * - `foot` renders on the frame's bottom edge, centred on the inline axis, and renders nothing - not
+ *   even an empty container - when not given or given nothing to render (`null`, a flag's `false`).
+ * - `children` and `foot` render unmodified; the component adds nothing to and strips nothing from
+ *   them, and sets no colour, no heading and no landmark of its own.
+ * - It owns its own inset - `--gutter` on the inline axis, `--space-region` on the block axis - the
+ *   deliberate exception to "`Section` owns the gutter": the frame equals the viewport, so it cannot
+ *   sit inside a `Section` band without overflowing it, and there is no band around it to carry one.
+ * - It is never sticky or fixed and needs no JavaScript, so it renders identically server-side.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - The cover stands on its own, never inside a `Section`: the band's vertical air would push the
+ *   frame past the viewport it exists to equal. A page that continues past its first screen wants
+ *   `Section` and `Hero` instead - the fold, not the screen.
+ * - Anything the page must announce - a landmark, a heading - is composed in the slot; the frame
+ *   declares nothing over it.
+ *
+ * @UXGuidelines
+ * - A cover is for a page that is the whole app for a moment - a menu, a sign-in, a splash. The
+ *   moment content follows on the same page, the screen has become a fold and stopping short of the
+ *   viewport is the honest signal: reach for `Hero` inside a `Section` instead.
+ * - The foot is a quiet line, not a footer: a version, a legal notice. Content a viewer must reach
+ *   belongs in the slot, where it sits in the column the screen is actually about.
+ */
+export const Cover: FunctionComponent<ICoverProps> = ({
+  children,
+  foot,
+  testId,
+}) => {
+  // Absence, not falsiness, after Form's note guard: `foot={showLegal && <p/>}` hands over `false`,
+  // and an empty <div> would still be a flex item sitting on the bottom edge.
+  const hasFoot =
+    foot !== undefined && foot !== null && typeof foot !== 'boolean';
+
+  return (
+    <div className={cover()} data-testid={testId}>
+      <div className={slot}>{children}</div>
+      {hasFoot && <div>{foot}</div>}
+    </div>
+  );
+};

package/src/Layout/Sidebar/Sidebar.tsx

@@ -0,0 +1,224 @@
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode, RefCallback } from 'react';
+import { Children, createContext, isValidElement, useContext } from 'react';
+import type { Subject } from 'rxjs';
+
+// One column below 64rem, the whole list above the content in normal flow; at `lg` a fixed 12rem nav
+// track beside `minmax(0,1fr)`, whose zero minimum keeps wide content from displacing the track (it
+// does not fix that content's own overflow). Root styles only its owned first child, leaving consumer
+// navigation untouched. Padding and scroll padding reserve the focus ring's width + offset.
+const sidebarRoot = cva(
+  [
+    'grid gap-[var(--space-region)] lg:grid-cols-[12rem_minmax(0,1fr)]',
+    '[&>div:first-child]:border-solid [&>div:first-child]:border-border [&>div:first-child]:border-b [&>div:first-child]:pb-[var(--space-stack)]',
+    'lg:[&>div:first-child]:border-b-0 lg:[&>div:first-child]:border-r lg:[&>div:first-child]:pb-0 lg:[&>div:first-child]:pr-[var(--space-stack)]',
+    'lg:[&>div:first-child>nav]:sticky lg:[&>div:first-child>nav]:top-0 lg:[&>div:first-child>nav]:max-h-[min(100dvh,var(--sidebar-scrollport-height,100dvh))] lg:[&>div:first-child>nav]:overflow-y-auto',
+    '[&>div:first-child>nav]:p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))] lg:[&>div:first-child>nav]:scroll-p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))]',
+    '[&>div:first-child>nav>ul]:flex [&>div:first-child>nav>ul]:flex-col [&>div:first-child>nav>ul]:gap-[var(--space-stack)]',
+  ].join(' '),
+);
+
+// A percentage max-height resolves against the content-driven grid cell, not its scrollport;
+// dvh alone left an 800px nav clipped by a 384px frame (#101). Measure that external boundary.
+// The ref runs only after client attachment; CSS owns the breakpoint and the viewport fallback.
+const observeScrollport: RefCallback<HTMLElement> = (navigation) => {
+  if (!navigation) return;
+  const ancestors: HTMLElement[] = [];
+  for (
+    let ancestor = navigation.parentElement;
+    ancestor && ancestor !== navigation.ownerDocument.documentElement;
+    ancestor = ancestor.parentElement
+  ) {
+    ancestors.push(ancestor);
+  }
+  const measure = () => {
+    const scrollport = ancestors.find((ancestor) =>
+      /^(auto|scroll|hidden|overlay)$/.test(
+        getComputedStyle(ancestor).overflowY,
+      ),
+    );
+    if (scrollport) {
+      navigation.style.setProperty(
+        '--sidebar-scrollport-height',
+        `${scrollport.clientHeight}px`,
+      );
+    } else {
+      navigation.style.removeProperty('--sidebar-scrollport-height');
+    }
+  };
+  measure();
+  // Observe ancestors so a resized wrapper or responsive change of scrollport is remeasured.
+  const observer =
+    typeof ResizeObserver === 'undefined'
+      ? undefined
+      : new ResizeObserver(measure);
+  for (const ancestor of ancestors) observer?.observe(ancestor);
+  window.addEventListener('resize', measure);
+  return () => {
+    observer?.disconnect();
+    window.removeEventListener('resize', measure);
+    navigation.style.removeProperty('--sidebar-scrollport-height');
+  };
+};
+
+// An entry at the label role, told apart by colour and underline alone - the agreed treatment carries
+// no active-background role. Active keeps a persistent underline at the at-rest thickness; usable
+// raises one on hover, instantly (underlines are off the motion allowlist, docs/adr/0001); inert is
+// muted with no interactive response. The focus ring is the library's one contract (docs/adr/0002).
+const sidebarEntry = cva(
+  [
+    'w-full text-left font-secondary text-label tracking-label',
+    'underline-offset-[var(--underline-offset)]',
+    'outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
+  ].join(' '),
+  {
+    variants: {
+      state: {
+        active:
+          'text-foreground underline decoration-[length:var(--underline-thickness)] cursor-pointer',
+        usable:
+          'text-foreground hover:underline hover:decoration-[length:var(--underline-thickness)] cursor-pointer',
+        inert: 'text-muted cursor-not-allowed',
+      },
+    },
+    defaultVariants: { state: 'usable' },
+  },
+);
+
+// What an Item derives its treatment and emission from - carried by context because the agreed surface
+// gives Item no active prop and no Subject; Root alone speaks them.
+type SidebarSelection = {
+  active: string;
+  onSelect$: Subject<string>;
+};
+
+const SidebarSelectionContext = createContext<SidebarSelection | undefined>(
+  undefined,
+);
+
+export interface ISidebarRootProps {
+  /** The key of the active entry. The caller supplies a key identifying one non-inert entry;
+   *  Sidebar renders what it is given and never selects a fallback for an invalid key. */
+  active: string;
+  /** The nav landmark's accessible name. */
+  label: string;
+  /** Emits the selected entry's key when a usable inactive entry is activated. The active and inert
+   *  entries emit nothing, and neither does any render. */
+  onSelect$: Subject<string>;
+  /** Direct `Sidebar.Item` children in display order, then one `Sidebar.Content`. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+export interface ISidebarItemProps {
+  /** Identifies the entry to the application - what `onSelect$` emits and `active` names. React's
+   *  reserved `key` is not the entry identifier. */
+  entryKey: string;
+  /** The entry's visible text. Text-only by type: an entry is a label, never arbitrary markup. */
+  children: string;
+  /** Present in the order but unavailable: muted, semantically disabled, skipped by Tab. */
+  inert?: boolean;
+  testId?: string;
+}
+
+export interface ISidebarContentProps {
+  children?: ReactNode;
+  testId?: string;
+}
+
+const SidebarItem: FunctionComponent<ISidebarItemProps> = ({
+  entryKey,
+  children,
+  inert,
+  testId,
+}) => {
+  const selection = useContext(SidebarSelectionContext);
+  const isActive = selection !== undefined && selection.active === entryKey;
+  const selectEntry = () => {
+    if (!isActive) selection?.onSelect$.next(entryKey);
+  };
+  return (
+    <li>
+      <button
+        type="button"
+        className={sidebarEntry({
+          state: inert ? 'inert' : isActive ? 'active' : 'usable',
+        })}
+        disabled={inert}
+        aria-current={isActive ? 'true' : undefined}
+        data-testid={testId}
+        onClick={selectEntry}
+      >
+        {children}
+      </button>
+    </li>
+  );
+};
+
+const SidebarContent: FunctionComponent<ISidebarContentProps> = ({
+  children,
+  testId,
+}) => <div data-testid={testId}>{children}</div>;
+
+const SidebarRoot: FunctionComponent<ISidebarRootProps> = ({
+  active,
+  label,
+  onSelect$,
+  children,
+  testId,
+}) => {
+  const parts = Children.toArray(children).filter(isValidElement);
+  return (
+    <div className={sidebarRoot()} data-testid={testId}>
+      <div>
+        <nav ref={observeScrollport} aria-label={label}>
+          <SidebarSelectionContext value={{ active, onSelect$ }}>
+            <ul>{parts.filter((part) => part.type === SidebarItem)}</ul>
+          </SidebarSelectionContext>
+        </nav>
+      </div>
+      {parts.filter((part) => part.type === SidebarContent)}
+    </div>
+  );
+};
+
+/**
+ * The standing application navigation beside the active section's content: a `nav` landmark named by
+ * `label`, listing text entries as plain buttons, and a `Content` track for the section the
+ * application shows. Selection is a request - activating a usable inactive entry emits its key through
+ * `onSelect$` - and the application answers by rerendering with a new `active`. Composed from `Root`,
+ * `Item` and `Content`; Root assembles its direct Items into the list, in order, and places Content
+ * beside them at 64rem or below them under it.
+ *
+ * @Guarantees — enforced on every render
+ * - For valid caller input, the active entry alone carries `aria-current="true"`. Sidebar owns no
+ *   selection, URL, history or fallback: it renders the key it is given; a missing key marks nothing.
+ * - Activating the active entry or an inert one emits nothing; no render emits anything. Entries are
+ *   non-submitting `type="button"` buttons with native Tab/Enter/Space behaviour - no tabs/menu model.
+ * - An inert entry stays visible but muted and disabled, so Tab skips it and activation is inert too.
+ * - At and above 64rem the nav is a fixed 12rem track, sticky at the top of the scrolling area with no
+ *   assumed top-bar offset, capped to the screen/scrolling-area height with independent entry scrolling.
+ *   Content sits beside it in `minmax(0,1fr)`, so wide content cannot displace the track.
+ * - Below 64rem the whole list lies above the content in normal flow - no stickiness, no cap, no
+ *   drawer. Sidebar sets no viewport-height minimum and grows with its content.
+ * - It separates the tracks itself (the region space role and a `border` hairline) but gives the
+ *   content track no padding and no landmark - the consumer owns everything inside `Content`.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - Entry keys are unique and `active` names one non-inert entry. Sidebar corrects nothing.
+ * - Items and the one Content are direct children of `Root` - Root assembles only what it can see,
+ *   and an Item rendered outside a Root has no selection to derive its treatment from.
+ * - Focus after the content changes belongs to the application; Sidebar leaves it on the activated
+ *   entry.
+ *
+ * @UXGuidelines
+ * - Entries are section labels: short, parallel, text-only. A destination that is a URL belongs to
+ *   `Link` in a `Header` or `Footer`, not here - Sidebar requests sections, it does not navigate.
+ * - Keep inert entries listed: a section that exists but holds nothing yet keeps its place in the
+ *   order, which is the point of inertness being a visual state rather than an absence.
+ */
+export const Sidebar = {
+  Root: SidebarRoot,
+  Item: SidebarItem,
+  Content: SidebarContent,
+} as const;