@juwel-development/design-system 3.11.0 → 4.0.0

package/src/Display/Typography/Prose/Prose.tsx

@@ -1,15 +1,26 @@
 import type { VariantProps } from 'class-variance-authority';
 import { cva } from 'class-variance-authority';
-import type { FunctionComponent, ReactNode } from 'react';
+import {
+  createContext,
+  type FunctionComponent,
+  type ReactNode,
+  useContext,
+} from 'react';
 
-// The reading column. It caps every child at --measure and sets no font-size, so the ch measure
-// keeps resolving against inherited body type - the same rule Form follows when it takes the measure.
-// The sibling gap is the type-scale --space-stack, never a one-idea-per-screen gap: the air the block
-// wants is at its edges (the 66ch measure) and inside the type, not between the blocks. It sets no
-// margin, so the page - not the component - owns the vertical rhythm around the column.
-const proseRoot = cva(
-  'flex max-w-[var(--measure)] flex-col gap-[var(--space-stack)]',
-);
+// Root sets letter family and size to resolve its ch measure, but leaves leading inherited so
+// Tail keeps its existing line height. Letter leading belongs only to Body (ADR 0004).
+const proseRoot = cva('flex flex-col gap-[var(--space-stack)]', {
+  variants: {
+    variant: {
+      default: 'max-w-[var(--measure)]',
+      letter:
+        'min-w-0 max-w-[min(100%,var(--measure-letter))] font-letter text-letter',
+    },
+  },
+  defaultVariants: { variant: 'default' },
+});
+
+const LetterContext = createContext(false);
 
 // The opening paragraph, at the new lede role: larger than body and led tighter (docs/adr/0004), but
 // still running-text leading, not a heading's. Colour is the foreground token, re-pointed by `.dark`.
@@ -18,8 +29,12 @@ const proseLede = cva('font-body text-lede leading-lede text-foreground');
 // The body role inside the column - the same utilities P emits, restated because the no-cross-import
 // rule forbids reusing P's recipe. A test pins the two equal so they cannot drift. Colour is a
 // semantic token re-pointed by `.dark`, so no variant carries a `dark:` class.
-const proseBody = cva('font-body text-body leading-body', {
+const proseBody = cva('', {
   variants: {
+    letter: {
+      false: 'font-body text-body leading-body',
+      true: 'font-letter text-letter leading-letter',
+    },
     color: {
       foreground: 'text-foreground',
       muted: 'text-muted',
@@ -29,13 +44,13 @@ const proseBody = cva('font-body text-body leading-body', {
       info: 'text-info',
     },
   },
-  defaultVariants: { color: 'foreground' },
+  defaultVariants: { letter: false, color: 'foreground' },
 });
 
 // The stepped-down closing note: the small role, always muted. small carries the enforced 15px floor.
 const proseTail = cva('font-body text-small text-muted');
 
-interface IProseRootProps {
+export interface IProseRootProps extends VariantProps<typeof proseRoot> {
   children?: ReactNode;
   testId?: string;
 }
@@ -44,7 +59,8 @@ interface IProseLedeProps {
   children?: ReactNode;
 }
 
-interface IProseBodyProps extends VariantProps<typeof proseBody> {
+interface IProseBodyProps
+  extends Pick<VariantProps<typeof proseBody>, 'color'> {
   children?: ReactNode;
 }
 
@@ -55,10 +71,13 @@ interface IProseTailProps {
 const ProseRoot: FunctionComponent<IProseRootProps> = ({
   children,
   testId,
+  variant,
 }) => (
-  <div className={proseRoot()} data-testid={testId}>
-    {children}
-  </div>
+  <LetterContext value={variant === 'letter'}>
+    <div className={proseRoot({ variant })} data-testid={testId}>
+      {children}
+    </div>
+  </LetterContext>
 );
 
 const ProseLede: FunctionComponent<IProseLedeProps> = ({ children }) => (
@@ -66,7 +85,9 @@ const ProseLede: FunctionComponent<IProseLedeProps> = ({ children }) => (
 );
 
 const ProseBody: FunctionComponent<IProseBodyProps> = ({ color, children }) => (
-  <p className={proseBody({ color })}>{children}</p>
+  <p className={proseBody({ color, letter: useContext(LetterContext) })}>
+    {children}
+  </p>
 );
 
 const ProseTail: FunctionComponent<IProseTailProps> = ({ children }) => (
@@ -79,15 +100,19 @@ const ProseTail: FunctionComponent<IProseTailProps> = ({ children }) => (
  * bounding the column. Composed from the four members; the consumer supplies the copy.
  *
  * @Guarantees — enforced on every render
- * - `Root` renders a `div` (never a `section`: it owns no landmark and no heading), capped at
+ * - Ordinary `Root` renders a `div` (never a `section`: it owns no landmark and no heading), capped at
  *   `--measure`, setting no font-size so the `ch` measure resolves against inherited body type.
+ * - `Root variant="letter"` selects --measure-letter resolved against its own letter family and
+ *   size, capped by available width. Body uses --text-letter and --leading-letter, and --font-letter
+ *   falling back to --font-primary at the element. Lede and Tail keep their explicit roles.
  * - `Root` stacks its children on `--space-stack` and takes no outer margin: the page owns the
  *   rhythm around the block, and the air the block wants is at its edges and inside the type.
- * - `Lede` renders a fixed-foreground `p` at the lede role; `Body` at the body role with a
+ * - `Lede` renders a fixed-foreground `p` at the lede role; `Body` at the selected root's role with a
  *   `foreground`, `muted`, `success`, `warning`, `error` or `info` `color`; `Tail` at the small
  *   role, always muted. A status tone changes colour only and adds no announcement semantics.
  *
  * @CallerMustEnsure — the component cannot see these and does not check them
+ * - Use Body throughout a letter, including the consumer-worded salutation and signature.
  * - Use `Prose.Body` for a paragraph inside this reading column; for a paragraph with no reading
  *   column around it - in a form, a card, a table cell - use `P` instead.
  * - Status-toned content communicates its status without relying on colour. The caller owns any

package/src/Interaction/Button/Button.tsx

@@ -6,7 +6,7 @@ import type { Subject } from 'rxjs';
 // No `dark:` classes here by design: every colour below is a semantic token whose value is
 // re-pointed by the `.dark` class in tokens.css, so one set of classes serves both themes.
 // Every variant shares colour motion and the focus ring. Faced controls share their typography,
-// radius and label arrangement; plain inherits its surrounding text. Long words wrap within the
+// radius and label arrangement; plain and link inherit their surrounding text. Long words wrap within the
 // available width without clipping, and faced minimum widths yield to a narrower holder (#119).
 const face =
   'font-control text-body text-balance wrap-anywhere rounded-[var(--radius-control)] select-none inline-flex flex-row items-center justify-center gap-2';
@@ -30,6 +30,7 @@ const button = cva(
         // Disabled follows Input: edge and ink go to the disabled tones and no fill appears.
         outlined: `${face} px-[calc(1rem_-_1px)] sm:px-[calc(1.5rem_-_1px)] py-[calc(0.5rem_-_1px)] min-w-[min(var(--control-min-width),100%)] border border-solid border-secondary bg-transparent text-secondary hover:bg-backing disabled:border-disabled disabled:text-muted disabled:hover:bg-transparent`,
         destructive: `${face} px-4 sm:px-6 py-2 min-w-[min(var(--control-min-width),100%)] bg-error text-error-foreground hover:bg-error-hover disabled:bg-disabled disabled:hover:bg-disabled-hover forced-colors:border`,
+        link: 'inline p-0 min-w-0 max-w-full whitespace-normal wrap-anywhere bg-transparent [font:inherit] [letter-spacing:inherit] [text-align:inherit] text-link underline decoration-[length:var(--underline-thickness)] underline-offset-[var(--underline-offset)] enabled:hover:decoration-[length:var(--underline-thickness-hover)] disabled:text-disabled',
         plain:
           'inline p-0 min-w-0 max-w-full whitespace-normal wrap-anywhere bg-transparent [font:inherit] [letter-spacing:inherit] [color:inherit] [text-align:inherit] disabled:text-disabled',
       },
@@ -40,7 +41,7 @@ const button = cva(
   },
 );
 
-interface IButtonProps extends VariantProps<typeof button> {
+export interface IButtonProps extends VariantProps<typeof button> {
   /** Optional: an icon-only button renders none, and names itself with `ariaLabel` instead. */
   children?: ReactNode;
   onClick$?: Subject<void>;
@@ -82,17 +83,23 @@ interface IButtonProps extends VariantProps<typeof button> {
  *   text around it, with no face, padding, corner or hover underline of its own. Reach for it where
  *   the action belongs to a line of content - a sortable column header composed with `Icon` - and
  *   for `ghost` where a quiet but still button-shaped action is wanted
+ * - `link` is an inline action with the prose Link treatment: persistent underline and link ink,
+ *   inheriting the surrounding face, size and line height, with no inset, corner or minimum width.
+ *   Use `Link` when there is an address; use `Button variant="link"` with `onClick$` when there is
+ *   none. The consumer owns the action and navigation. Supply text, not nested interactive content.
  * - Maintain consistent button styling throughout the application
  * - Provide visual feedback on hover/active states
- * - Ensure sufficient touch target size (minimum 44x44px) for mobile users
+ * - Inline actions take their target size from the surrounding text; use faced actions for standalone controls
  * - Position primary actions on the right for multi-button layouts
  * - A submit button's busy state is a label swap ("Send" to "Sending…"), never a spinner: it costs
  *   nothing to render server-side and keeps a Form's `sending` state driver-agnostic
  *
  * @Accessibility
  * - Ensure adequate color contrast (4.5:1 minimum ratio)
- * - Provide focus styles for keyboard navigation: every variant, `plain` included, draws the shared
+ * - Provide focus styles for keyboard navigation: every variant, including `plain` and `link`, draws the shared
  *   focus ring and nothing else changes on focus
+ * - A disabled `link` retains its underline, uses the disabled ink and does not thicken on hover.
+ *   Native disabled semantics prevent activation and remove it from the tab sequence.
  * - A disabled `plain` button is told apart by the `disabled` text tone and keeps native disabled semantics
  * - Use appropriate ARIA attributes when needed
  * - Status colour never stands alone: a destructive action is named by its words or symbol

package/src/Interaction/Slider/Slider.tsx

@@ -83,11 +83,6 @@ const assertOperatingRange = (
       `\`step\` (${range.step}) must be positive`,
     );
   }
-  if (range.value < range.min || range.value > range.max) {
-    throw new SliderConfigurationError(
-      `\`value\` (${range.value}) must lie within [${range.min}, ${range.max}]`,
-    );
-  }
 };
 
 /**
@@ -98,6 +93,9 @@ const assertOperatingRange = (
  * `Input` too: visible, associated, and the only text the component renders (#112). It is still
  * a live control and not a form field, so none of Input's annotations - hint, error, optional
  * marker - come with it. `disabled` is the explicit non-operable state.
+ *
+ * An off-range value renders at the nearest bound through the native control. The consumer still
+ * owns the value: the clamped position is not emitted on `onInput$` until the user moves the thumb.
  */
 export const Slider: FunctionComponent<ISliderProps> = ({
   min,

package/src/Interaction/Stepper/Stepper.tsx

@@ -0,0 +1,307 @@
+import { cva } from 'class-variance-authority';
+import {
+  Children,
+  createContext,
+  type FocusEvent,
+  Fragment,
+  type FunctionComponent,
+  isValidElement,
+  type KeyboardEvent,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useId,
+  useState,
+} from 'react';
+import type { Observable, Subject } from 'rxjs';
+import { StepperCompositionError } from './StepperCompositionError';
+
+const stepperRoot = cva(
+  'flex h-full min-h-0 min-w-0 flex-col gap-[var(--space-stack)]',
+);
+
+const stepperList = cva(
+  [
+    'flex flex-row shrink-0 min-w-0 overflow-x-auto',
+    'p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))]',
+    'scroll-p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))]',
+  ].join(' '),
+);
+
+const stepperStep = cva([
+  'relative isolate flex flex-1 flex-col items-center gap-[var(--space-stack)] text-center',
+  'font-secondary text-label text-foreground cursor-pointer select-none',
+  'px-[var(--step-inset-inline)] py-[var(--step-inset-block)]',
+  'border-b-[length:var(--step-selection-thickness)] border-solid border-transparent aria-selected:border-foreground',
+  'outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
+  "after:content-[''] after:absolute after:-z-10 after:top-[calc(var(--step-inset-block)+var(--step-marker-size)/2)] after:start-1/2 after:w-full after:border-t-[length:var(--step-connector-thickness)] after:border-border last:after:hidden",
+  '[&>[data-marker]]:flex [&>[data-marker]]:shrink-0 [&>[data-marker]]:items-center [&>[data-marker]]:justify-center',
+  '[&>[data-marker]]:size-[var(--step-marker-size)] [&>[data-marker]]:border [&>[data-marker]]:border-foreground [&>[data-marker]]:bg-surface [&>[data-marker]]:rounded-[var(--radius-control)]',
+  '[&>[data-value-text]]:text-small [&>[data-status-content]]:text-small',
+  'forced-colors:after:border-[CanvasText] forced-colors:aria-selected:border-[Highlight]',
+  'forced-colors:border-b-0 forced-colors:aria-selected:border-b-[length:var(--step-selection-thickness)]',
+  'forced-colors:[&>[data-marker]]:bg-[Canvas] forced-colors:[&>[data-marker]]:text-[CanvasText] forced-colors:[&>[data-marker]]:border-[CanvasText]',
+]);
+
+const stepperPanel = cva(
+  'min-h-0 min-w-0 flex-auto outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
+);
+
+type StepperContract = {
+  active: string | undefined;
+  onSelect$: Subject<string>;
+  label: string;
+  baseId: string;
+};
+
+const PositionContext = createContext<number | undefined>(undefined);
+
+const flattenSteps = (children: ReactNode): ReactNode[] =>
+  Children.toArray(children).flatMap((child) =>
+    isValidElement<{ children: ReactNode }>(child) && child.type === Fragment
+      ? flattenSteps(child.props.children)
+      : [child],
+  );
+
+const StepperContext = createContext<StepperContract | undefined>(undefined);
+
+const useStepperContract = (member: string): StepperContract => {
+  const contract = useContext(StepperContext);
+  if (contract === undefined) {
+    throw new StepperCompositionError(member);
+  }
+  return contract;
+};
+
+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)}`;
+
+const neighbourTab = (
+  current: HTMLButtonElement,
+  step: 1 | -1,
+): HTMLButtonElement | undefined => {
+  const row = current.closest('[role="tablist"]');
+  if (row === null) {
+    return undefined;
+  }
+  const stepButtons = Array.from(
+    row.querySelectorAll<HTMLButtonElement>(':scope > [role="tab"]'),
+  );
+  const index = stepButtons.indexOf(current);
+  return stepButtons[(index + step + stepButtons.length) % stepButtons.length];
+};
+
+export interface IStepperRootProps {
+  /** Consumer-owned selection. No panel is active before this source first emits. */
+  active$: Observable<string>;
+  /** Requests selection, including blocked steps, without changing the input. */
+  onSelect$: Subject<string>;
+  label: string;
+  children: ReactNode;
+  testId?: string;
+}
+
+export interface IStepperListProps {
+  children: ReactNode;
+  testId?: string;
+}
+
+export interface IStepperStepProps {
+  /** Stable identity, unique within Root, paired with exactly one Panel. */
+  value: string;
+  label: string;
+  status: 'done' | 'open' | 'blocked';
+  /** Noninteractive consumer content, rendered whole and included in the accessible name. */
+  valueText: ReactNode;
+  /** Optional visible wording, associated as the control's accessible description. */
+  statusContent?: ReactNode;
+  testId?: string;
+}
+
+export interface IStepperPanelProps {
+  /** 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;
+}
+
+const StepperRoot: FunctionComponent<IStepperRootProps> = ({
+  active$,
+  onSelect$,
+  label,
+  children,
+  testId,
+}) => {
+  const baseId = useId();
+  const [active, setActive] = useState<string>();
+  useEffect(() => {
+    setActive(undefined);
+    const subscription = active$.subscribe(setActive);
+    return () => subscription.unsubscribe();
+  }, [active$]);
+  return (
+    <StepperContext.Provider value={{ active, onSelect$, label, baseId }}>
+      <div className={stepperRoot()} data-testid={testId}>
+        {children}
+      </div>
+    </StepperContext.Provider>
+  );
+};
+
+const StepperList: FunctionComponent<IStepperListProps> = ({
+  children,
+  testId,
+}) => {
+  const { label } = useStepperContract('List');
+  return (
+    <div
+      role="tablist"
+      aria-label={label}
+      className={stepperList()}
+      data-testid={testId}
+    >
+      {flattenSteps(children).map((child, index) => (
+        <PositionContext.Provider
+          key={
+            isValidElement<{ value: string }>(child) ? child.props.value : index
+          }
+          value={index + 1}
+        >
+          {child}
+        </PositionContext.Provider>
+      ))}
+    </div>
+  );
+};
+
+const StepperStep: FunctionComponent<IStepperStepProps> = ({
+  value,
+  label,
+  status,
+  valueText,
+  statusContent,
+  testId,
+}) => {
+  const { active, onSelect$, baseId } = useStepperContract('Step');
+  const position = useContext(PositionContext);
+  if (position === undefined)
+    throw new StepperCompositionError('Step (inside List)');
+  const isActive = active === value;
+
+  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)}
+      aria-labelledby={`${tabId(baseId, value)}-label ${tabId(baseId, value)}-value`}
+      aria-describedby={
+        statusContent !== undefined
+          ? `${tabId(baseId, value)}-status`
+          : undefined
+      }
+      tabIndex={isActive ? 0 : -1}
+      data-value={value}
+      data-testid={testId}
+      className={stepperStep()}
+      onClick={() => onSelect$.next(value)}
+      onKeyDown={requestNeighbour}
+      onFocus={keepFocusedTabVisible}
+    >
+      <span data-marker aria-hidden="true">
+        {status === 'done' ? '✓' : status === 'blocked' ? '⊘' : position}
+      </span>
+      <span id={`${tabId(baseId, value)}-label`}>{label}</span>
+      <span data-value-text id={`${tabId(baseId, value)}-value`}>
+        {valueText}
+      </span>
+      {statusContent !== undefined ? (
+        <span data-status-content id={`${tabId(baseId, value)}-status`}>
+          {statusContent}
+        </span>
+      ) : undefined}
+    </button>
+  );
+};
+
+const StepperPanel: FunctionComponent<IStepperPanelProps> = ({
+  value,
+  children,
+  testId,
+}) => {
+  const { active, baseId } = useStepperContract('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={stepperPanel()}
+      data-testid={testId}
+    >
+      {isActive ? children : undefined}
+    </div>
+  );
+};
+
+/**
+ * Connected form steps with independent status and consumer-controlled selection.
+ * @Guarantees
+ * - Root observes active$ and emits identities through onSelect$ without changing selection.
+ * - Source replacement clears selection until the new source emits; subscriptions tear down.
+ * - Done and blocked steps remain selectable. Left/Right wraps focus and requests selection.
+ * - Label and value text name each tab; optional visible status content describes it.
+ * - Only the active panel mounts content; returning mounts fresh with no state cache.
+ * - The row wraps text before scrolling horizontally and reveals focused steps.
+ * - Root takes its parent's height; Panel passes the remainder without owning scrolling.
+ *   An unsized parent retains natural content height.
+ * @CallerMustEnsure
+ * - Supply a valid selected identity, unique stable Step values and matching Panels.
+ * - Compose one List of direct Steps (arrays/fragments supported), no wrapper components.
+ * - For bounded content, List and Panels are direct DOM children of Root and the Panel's
+ *   direct child accepts height (for example Pane). Fixed content must leave usable body space.
+ * - Value and status slots contain no interactive descendants. Supply localized status wording
+ *   when spoken status is needed; the library supplies shapes but no status translations.
+ * - Persist form state outside Stepper and restore it into controls when they mount.
+ */
+export const Stepper = {
+  Root: StepperRoot,
+  List: StepperList,
+  Step: StepperStep,
+  Panel: StepperPanel,
+} as const;

package/src/Interaction/Stepper/StepperCompositionError.ts

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

package/src/Interaction/Switch/Switch.tsx

@@ -0,0 +1,64 @@
+import { cva } from 'class-variance-authority';
+import { type FunctionComponent, useEffect, useState } from 'react';
+import type { Observable, Subject } from 'rxjs';
+
+const switchControl = cva([
+  'inline-flex max-w-full items-center gap-[var(--space-stack)] rounded-[var(--radius-control)] bg-transparent p-0 text-start cursor-pointer',
+  'font-secondary font-medium text-body text-foreground disabled:text-muted disabled:cursor-not-allowed',
+  'outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
+  '[&>[data-track]]:inline-flex [&>[data-track]]:shrink-0 [&>[data-track]]:box-content [&>[data-track]]:w-[calc(2*var(--switch-thumb-size))] [&>[data-track]]:p-[var(--switch-track-inset)]',
+  '[&>[data-track]]:rounded-[var(--radius-control)] [&>[data-track]]:border [&>[data-track]]:border-solid [&>[data-track]]:border-control-border [&>[data-track]]:bg-surface',
+  "[&>[data-track]::before]:content-[''] [&>[data-track]::before]:block [&>[data-track]::before]:size-[var(--switch-thumb-size)] [&>[data-track]::before]:rounded-[var(--radius-control)] [&>[data-track]::before]:bg-foreground",
+  'aria-checked:[&>[data-track]]:justify-end',
+  'disabled:[&>[data-track]]:border-disabled disabled:[&>[data-track]::before]:bg-disabled',
+  'forced-colors:[&>[data-track]]:[forced-color-adjust:none] forced-colors:[&>[data-track]]:border-[ButtonText] forced-colors:[&>[data-track]]:bg-[Canvas] forced-colors:[&>[data-track]::before]:bg-[ButtonText]',
+  'forced-colors:disabled:text-[GrayText] forced-colors:disabled:[&>[data-track]]:border-[GrayText] forced-colors:disabled:[&>[data-track]::before]:bg-[GrayText]',
+  '[&>[data-label]]:min-w-0 [&>[data-label]]:wrap-anywhere',
+]);
+
+export interface ISwitchProps {
+  /** A visible, stable name for the setting, not a changing on/off caption. */
+  label: string;
+  /** Consumer-owned state. Off until the current source first emits, including on replacement. */
+  checked$: Observable<boolean>;
+  /** Requests the opposite of the displayed state; only an input emission changes the display. */
+  onChange$: Subject<boolean>;
+  /** Native disabled conduct; the current state remains visible. */
+  disabled?: boolean;
+  testId?: string;
+}
+
+/**
+ * One immediate binary setting, named by its visible label. A native button supplies a single
+ * tab stop and Space/Enter activation without submitting a surrounding form. Thumb position and
+ * aria-checked expose the input state; neither activation nor focus changes it independently.
+ * Use Choices for described alternatives, or a checkbox in a Form for a submitted selection.
+ */
+export const Switch: FunctionComponent<ISwitchProps> = ({
+  label,
+  checked$,
+  onChange$,
+  disabled,
+  testId,
+}) => {
+  const [isChecked, setChecked] = useState(false);
+  useEffect(() => {
+    setChecked(false);
+    const subscription = checked$.subscribe(setChecked);
+    return () => subscription.unsubscribe();
+  }, [checked$]);
+  return (
+    <button
+      type="button"
+      role="switch"
+      aria-checked={isChecked}
+      disabled={disabled}
+      data-testid={testId}
+      className={switchControl()}
+      onClick={() => onChange$.next(!isChecked)}
+    >
+      <span data-track aria-hidden="true" />
+      <span data-label>{label}</span>
+    </button>
+  );
+};