@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/src/Editing/timeShorthand.ts

@@ -0,0 +1,157 @@
+/**
+ * Time shorthand for the schedule grid (B4, G-41): what a planner types into a Time or Duration cell, read without
+ * chrono so a server and a browser read it the same way. `@xos/ui/quick-add` re-exports this file.
+ *
+ *   en  8, 8a, 8am, 830p, 8:30 pm, 20:30, noon, midnight; ranges 8a-5p, 8-11:30p (the end's meridiem carries back to
+ *       the start when that keeps the start first), 9 to 5
+ *   es  8 a. m., 8:30 p. m., 20 h, mediodía, medianoche; ranges 8 a 10, 9 hasta 17
+ *
+ * An end at or before the start rolls to the next day (endDayOffset 1), so 22-2 runs past midnight. Times come back
+ * as 24-hour HH:MM on the wall clock; the grid reads them in the project's zone.
+ */
+
+export interface TimeShorthand {
+  /** Start as HH:MM, 24-hour. */
+  readonly start: string;
+  /** End as HH:MM, 24-hour; null for a single time. */
+  readonly end: string | null;
+  /** 1 when the end falls on the next day. */
+  readonly endDayOffset: 0 | 1;
+}
+
+export interface TimeShorthandOptions {
+  /** en-US or es-US; both languages' words are read either way, the locale only breaks ties. */
+  readonly locale?: string;
+}
+
+type Meridiem = "a" | "p" | "h" | null;
+
+interface Clock {
+  readonly h: number;
+  readonly m: number;
+  readonly meridiem: Meridiem;
+}
+
+const WORDS: Readonly<Record<string, Clock>> = {
+  noon: { h: 12, m: 0, meridiem: "h" },
+  midday: { h: 12, m: 0, meridiem: "h" },
+  midnight: { h: 0, m: 0, meridiem: "h" },
+  mediodía: { h: 12, m: 0, meridiem: "h" },
+  mediodia: { h: 12, m: 0, meridiem: "h" },
+  medianoche: { h: 0, m: 0, meridiem: "h" },
+};
+
+const ONE =
+  /^(\d{1,4})(?:[:.h](\d{2}))?\s*(a|am|a\.m\.|a\.\s?m\.|p|pm|p\.m\.|p\.\s?m\.|h|hrs|horas)?$/u;
+
+function normalize(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/\u00a0/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function readOne(raw: string): Clock | null {
+  const text = normalize(raw);
+  const word = WORDS[text];
+  if (word) return word;
+  const match = ONE.exec(text);
+  if (!match) return null;
+  const digits = match[1] ?? "";
+  let h: number;
+  let m: number;
+  if (match[2] !== undefined) {
+    h = Number(digits);
+    m = Number(match[2]);
+  } else if (digits.length >= 3) {
+    h = Number(digits.slice(0, -2));
+    m = Number(digits.slice(-2));
+  } else {
+    h = Number(digits);
+    m = 0;
+  }
+  const suffix = match[3] ?? "";
+  const meridiem: Meridiem = suffix.startsWith("a")
+    ? "a"
+    : suffix.startsWith("p")
+      ? "p"
+      : suffix
+        ? "h"
+        : null;
+  if (m > 59) return null;
+  if (meridiem === "a" || meridiem === "p") {
+    if (h < 1 || h > 12) return null;
+  } else if (h > 24 || (h === 24 && m > 0)) {
+    return null;
+  }
+  return { h, m, meridiem };
+}
+
+function to24(c: Clock, meridiem: Meridiem): number {
+  const h = c.h === 24 ? 0 : c.h;
+  if (meridiem === "a") return (h % 12) * 60 + c.m;
+  if (meridiem === "p") return ((h % 12) + 12) * 60 + c.m;
+  return h * 60 + c.m;
+}
+
+function hhmm(minutes: number): string {
+  const within = ((minutes % 1440) + 1440) % 1440;
+  return `${String(Math.floor(within / 60)).padStart(2, "0")}:${String(within % 60).padStart(2, "0")}`;
+}
+
+const RANGE = /\s*(?:-|\u2013|\u2014|\bto\b|\bhasta\b|\s(?:a)\s(?=\d))\s*/u;
+
+/** Reads a time or a time range typed as shorthand, or null when the text is not shorthand. */
+export function parseTimeShorthand(
+  text: string,
+  options: TimeShorthandOptions = {},
+): TimeShorthand | null {
+  void options;
+  const value = normalize(text);
+  if (value === "") return null;
+  const parts = value.split(RANGE).filter((p) => p !== "");
+  if (parts.length === 1) {
+    const one = readOne(parts[0] ?? "");
+    return one ? { start: hhmm(to24(one, one.meridiem)), end: null, endDayOffset: 0 } : null;
+  }
+  if (parts.length !== 2) return null;
+  const start = readOne(parts[0] ?? "");
+  const end = readOne(parts[1] ?? "");
+  if (!start || !end) return null;
+  const endMinutes = to24(end, end.meridiem);
+  let startMinutes = to24(start, start.meridiem);
+  // The end's meridiem carries back to a bare start (8-11:30p is 20:00 to 23:30), unless that would put the start
+  // after the end (10-2p is 10:00 to 14:00).
+  if (start.meridiem === null && (end.meridiem === "a" || end.meridiem === "p") && start.h <= 12) {
+    const carried = to24(start, end.meridiem);
+    const other = to24(start, end.meridiem === "a" ? "p" : "a");
+    startMinutes = carried <= endMinutes ? carried : other <= endMinutes ? other : carried;
+  }
+  return {
+    start: hhmm(startMinutes),
+    end: hhmm(endMinutes),
+    endDayOffset: endMinutes <= startMinutes ? 1 : 0,
+  };
+}
+
+/**
+ * Reads a length typed as shorthand, in whole minutes: 45, 45m, 45 min, 90 min, 1h, 1 h, 1h30, 1:30, 1.5h. Null when
+ * the text is not a length.
+ */
+export function parseDuration(text: string): number | null {
+  const value = normalize(text).replace(/\s+/g, "");
+  if (value === "") return null;
+  let match = /^(\d+)(?:m|min|mins|minutes|minutos)?$/u.exec(value);
+  if (match) return Number(match[1]);
+  match = /^(\d+):(\d{2})$/u.exec(value);
+  if (match) return Number(match[2]) > 59 ? null : Number(match[1]) * 60 + Number(match[2]);
+  match = /^(\d+(?:[.,]\d+)?)(?:h|hr|hrs|hora|horas)(?:(\d{1,2})(?:m|min)?)?$/u.exec(value);
+  if (match) {
+    const hours = Number((match[1] ?? "0").replace(",", "."));
+    const minutes = match[2] ? Number(match[2]) : 0;
+    if (minutes > 59) return null;
+    return Math.round(hours * 60) + minutes;
+  }
+  return null;
+}

package/src/Editing/useQuickAdd.ts

@@ -0,0 +1,201 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useLocale } from "../lib/context.tsx";
+import type { parseQuickAdd } from "./parseQuickAdd.tsx";
+import {
+  finalizeQuickAdd,
+  quickAddKey,
+  tidyTitle,
+  type QuickAddParse,
+  type QuickAddResolution,
+  type QuickAddResolver,
+  type QuickAddResult,
+  type QuickAddToken,
+} from "./quickAddCore.ts";
+
+export interface UseQuickAddOptions {
+  /** The line as typed; the caller owns the input. */
+  text: string;
+  referenceDate?: Date;
+  /** The language of date phrases; the provider's locale by default. */
+  locale?: string;
+  /** The IANA zone date phrases are read in; the device's by default. */
+  timeZone?: string;
+  /** Resolves people, tags, kinds and scopes; without one, every token applies as typed. */
+  resolve?: QuickAddResolver;
+  /** How long typing pauses before tokens are resolved, in milliseconds. */
+  delay?: number;
+}
+
+export interface QuickAddController {
+  parse: QuickAddParse;
+  /** Resolutions by token key, or undefined when there is no resolver. */
+  resolutions: Readonly<Record<string, QuickAddResolution>> | undefined;
+  /** True while a token of the line waits for its resolution. */
+  pending: boolean;
+  /** Candidates the person chose for ambiguous tokens, by token key. */
+  choices: Readonly<Record<string, string>>;
+  /** Turns a token back into text. */
+  dismiss: (token: QuickAddToken) => void;
+  /** Picks one candidate of an ambiguous token. */
+  choose: (token: QuickAddToken, id: string) => void;
+  /** The line to save: waits for any resolution still out, then folds unresolved tokens back. */
+  finalize: () => Promise<QuickAddResult>;
+  /** Forgets dismissed tokens and choices, after a save. */
+  reset: () => void;
+}
+
+const resolvable = (t: QuickAddToken) => t.type !== "date";
+
+type Parser = typeof parseQuickAdd;
+
+let parserModule: Promise<Parser> | null = null;
+let loadedParser: Parser | null = null;
+
+/**
+ * The parser and its date library (chrono-node, English and Spanish) load with the first
+ * character typed or the field's focus, not with the page that shows a quick add (ADR 0027). Until
+ * then the line is plain text, with no chips.
+ */
+export function loadQuickAddParser(): Promise<Parser> {
+  parserModule ??= import("./parseQuickAdd.tsx").then(
+    (m) => (loadedParser = m.parseQuickAdd),
+    (error: unknown) => {
+      // A failed chunk fetch (offline, a new deploy) may succeed on the next attempt.
+      parserModule = null;
+      throw error;
+    },
+  );
+  return parserModule;
+}
+
+const plainParse = (text: string): QuickAddParse => ({ text, title: tidyTitle(text), tokens: [] });
+
+/**
+ * Quick add state for any input (Section 11.7): the parse of the current line in the person's
+ * language and the org's zone, resolutions fetched once per token after typing pauses, dismissed
+ * tokens and chosen candidates. `QuickAdd` uses it with its own input; the Atlas Create menu uses it
+ * with the command menu's.
+ */
+export function useQuickAdd({
+  text,
+  referenceDate,
+  locale,
+  timeZone,
+  resolve,
+  delay = 250,
+}: UseQuickAddOptions): QuickAddController {
+  const contextLocale = useLocale();
+  const [dismissed, setDismissed] = useState<readonly string[]>([]);
+  const [choices, setChoices] = useState<Readonly<Record<string, string>>>({});
+  const [cache, setCache] = useState<Readonly<Record<string, QuickAddResolution>>>({});
+  const cacheRef = useRef(cache);
+  const inFlight = useRef(new Map<string, Promise<void>>());
+  const resolveRef = useRef(resolve);
+  useEffect(() => {
+    resolveRef.current = resolve;
+  }, [resolve]);
+
+  const [parser, setParser] = useState<Parser | null>(() => loadedParser);
+  useEffect(() => {
+    if (parser !== null || text === "") return undefined;
+    let live = true;
+    loadQuickAddParser().then(
+      (p) => {
+        if (live) setParser(() => p);
+      },
+      (error: unknown) => console.error("Could not load the quick add parser", error),
+    );
+    return () => {
+      live = false;
+    };
+  }, [parser, text]);
+
+  const parseWith = useCallback(
+    (p: Parser | null) =>
+      p === null
+        ? plainParse(text)
+        : p(text, {
+            locale: locale ?? contextLocale,
+            dismissed,
+            ...(referenceDate ? { referenceDate } : {}),
+            ...(timeZone ? { timeZone } : {}),
+          }),
+    [text, locale, contextLocale, dismissed, referenceDate, timeZone],
+  );
+  const parse = useMemo(() => parseWith(parser), [parseWith, parser]);
+
+  /** Resolves the tokens with no answer yet; tokens already asked about wait for that answer. */
+  const fetchMissing = useCallback((tokens: readonly QuickAddToken[]): Promise<void> => {
+    const fn = resolveRef.current;
+    if (fn === undefined) return Promise.resolve();
+    const waiting: Promise<void>[] = [];
+    const ask: QuickAddToken[] = [];
+    for (const token of tokens) {
+      const key = quickAddKey(token);
+      if (key in cacheRef.current) continue;
+      const flying = inFlight.current.get(key);
+      if (flying) waiting.push(flying);
+      else if (!ask.some((t) => quickAddKey(t) === key)) ask.push(token);
+    }
+    if (ask.length > 0) {
+      const request = fn(ask)
+        .catch(() => ({}) as Readonly<Record<string, QuickAddResolution>>)
+        .then((answer) => {
+          const next = { ...cacheRef.current };
+          for (const token of ask) {
+            const key = quickAddKey(token);
+            next[key] = answer[key] ?? { status: "unresolved" };
+            inFlight.current.delete(key);
+          }
+          cacheRef.current = next;
+          setCache(next);
+        });
+      for (const token of ask) inFlight.current.set(quickAddKey(token), request);
+      waiting.push(request);
+    }
+    return Promise.all(waiting).then(() => undefined);
+  }, []);
+
+  const wanted = parse.tokens.filter(resolvable);
+  const wantedKeys = wanted.map(quickAddKey).join("\u0000");
+  useEffect(() => {
+    if (resolveRef.current === undefined || wantedKeys === "") return undefined;
+    const timer = setTimeout(() => void fetchMissing(wanted), delay);
+    return () => clearTimeout(timer);
+    // `wanted` changes with its keys: it is derived from the same parse.
+  }, [wantedKeys, delay, fetchMissing]);
+
+  const resolutions = resolve === undefined ? undefined : cache;
+  const pending = resolve !== undefined && wanted.some((t) => !(quickAddKey(t) in cache));
+
+  const finalize = useCallback(async (): Promise<QuickAddResult> => {
+    // A line saved before the parser arrived is read once it has.
+    const line = parser === null ? parseWith(await loadQuickAddParser()) : parse;
+    await fetchMissing(line.tokens.filter(resolvable));
+    return finalizeQuickAdd(
+      line,
+      resolveRef.current === undefined ? undefined : cacheRef.current,
+      choices,
+    );
+  }, [fetchMissing, parse, parser, parseWith, choices]);
+
+  return {
+    parse,
+    resolutions,
+    pending,
+    choices,
+    dismiss: useCallback(
+      (token: QuickAddToken) => setDismissed((d) => [...d, quickAddKey(token)]),
+      [],
+    ),
+    choose: useCallback(
+      (token: QuickAddToken, id: string) => setChoices((c) => ({ ...c, [quickAddKey(token)]: id })),
+      [],
+    ),
+    finalize,
+    reset: useCallback(() => {
+      setDismissed([]);
+      setChoices({});
+    }, []),
+  };
+}

package/src/EmergencyCodeCard/README.md

@@ -0,0 +1,10 @@
+# EmergencyCodeCard
+
+EmergencyCodeCard shows one emergency code's protocol for one operational domain, readable offline in Compass Reference.
+
+- Emergency codes are global (decision D15). The 14 codes (Code Red through Code Adam) and their protocol per operational domain (Site, Stage, Food & Beverage, Guest Experience, Back of House, Front of House Operations) are one Standard Library shared by every organization and project. Record keys sort in numeric order (EMG-001 onward).
+- Protocol steps never name an agency. They name a service as `{fire}`, `{ems}`, `{lawEnforcement}`, `{bombSquad}` or `{federal}`, and the card resolves each from `authorities`, the responding agencies for the project's jurisdiction. Matching agencies are listed under the steps with their contact. Without a jurisdiction, the generic service name renders ("local law enforcement"), so the card is always correct.
+- The radio channel is a project join from Radio Channels, not part of the code.
+- `swatch` names an `ecode-*` token. The swatch is for recognition only; the code name is always written out, so color never carries the meaning alone.
+- The preview shows Standard Library rows EMG-001, EMG-007 and EMG-025 with the CSMIA26 venue jurisdiction (Mana Wynwood, US-FL-MIAMI-DADE in Bible tab 11). EMG-025 has no authorities passed and shows the generic service name.
+- This card is text. Never draw or approximate a regulatory safety symbol (ISO 7010, ISA) here; licensed marks go in their own slot.

package/src/EmptyState/README.md

@@ -0,0 +1,5 @@
+# EmptyState
+
+EmptyState shows one sentence and one button that fills the view.
+
+When the page header already carries the same primary action, pass `actionVariant="secondary"` so the screen keeps one primary action (gate 27).

package/src/EngagementTimeline/README.md

@@ -0,0 +1,3 @@
+# EngagementTimeline
+
+EngagementTimeline shows the nine engagement stages and where this engagement is.

package/src/ErrorState/README.md

@@ -0,0 +1,3 @@
+# ErrorState
+
+ErrorState replaces one failed region with a plain cause, a retry and a support reference; the rest of the page keeps working.

package/src/FAQ/README.md

@@ -0,0 +1,7 @@
+# FAQ
+
+FAQ lists questions and answers, built on Accordion.
+
+Each question is a heading inside its disclosure button, and every answer stays in the document while closed, so search and answer engines read the full text. The visible text must match the page's FAQPage structured data word for word.
+
+Write questions the way a buyer asks them, and answer in the first sentence. The consumer provides eight to ten items; open the first.

package/src/FeatureGrid/README.md

@@ -0,0 +1,7 @@
+# FeatureGrid
+
+FeatureGrid arranges short feature cards in two to five columns.
+
+An item with a department `code` draws that department's glyph and prints the code in a mono chip beside the name, so a code never appears alone; coded items stay in numeric order. Other items take any Lucide `icon`. Columns collapse to two from bp-sm and one below.
+
+The consumer provides a title, one sentence of body copy and, where it helps, one link per item.

package/src/Feedback/Banner.tsx

@@ -0,0 +1,40 @@
+import { type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { useT } from "../lib/context.tsx";
+import { Icon } from "../Icon/Icon.tsx";
+import { Button, IconButton } from "../Button/Button.tsx";
+import { TONE_ICON, TONE_ICON_CLASS } from "./Feedback.shared.tsx";
+import { type BannerProps } from "./Feedback.types.ts";
+
+/** A page-wide condition across the top of a page; at most one per page. */
+export function Banner({
+  tone = "info",
+  icon,
+  children,
+  actionLabel,
+  onAction,
+  onDismiss,
+}: BannerProps): ReactElement {
+  const t = useT();
+  return (
+    <div
+      role={tone === "danger" ? "alert" : "status"}
+      className={cx(
+        "flex items-center gap-8 px-12 py-8 bg-bg-surface border-b border-border-subtle print:hidden",
+        tone === "warning" && "border-s-stroke-accent border-s-warning",
+        tone === "danger" && "border-s-stroke-accent border-s-danger",
+      )}
+    >
+      <span className={TONE_ICON_CLASS[tone]}>
+        <Icon name={icon ?? TONE_ICON[tone]} />
+      </span>
+      <span className="flex-1">{children}</span>
+      {actionLabel ? (
+        <Button size="sm" onClick={onAction}>
+          {actionLabel}
+        </Button>
+      ) : null}
+      {onDismiss ? <IconButton icon="X" label={t("action.dismiss")} onClick={onDismiss} /> : null}
+    </div>
+  );
+}

package/src/Feedback/EmptyState.tsx

@@ -0,0 +1,32 @@
+import { type ReactElement } from "react";
+import { Icon } from "../Icon/Icon.tsx";
+import { Button } from "../Button/Button.tsx";
+import { stateClass } from "./Feedback.shared.tsx";
+import { type EmptyStateProps } from "./Feedback.types.ts";
+
+/**
+ * One sentence and one button: "No shifts yet. Post a crew call." The button is secondary when the
+ * page header already holds the primary action (actionVariant), so a screen has one primary.
+ */
+export function EmptyState({
+  sentence,
+  actionLabel,
+  icon,
+  shortcut,
+  onAction,
+  actionVariant = "primary",
+}: EmptyStateProps): ReactElement {
+  return (
+    <div className={stateClass}>
+      {icon ? (
+        <span className="text-text-tertiary">
+          <Icon name={icon} size={24} />
+        </span>
+      ) : null}
+      <p className="m-0 text-text-14 text-text-secondary">{sentence}</p>
+      <Button variant={actionVariant} onClick={onAction} {...(shortcut ? { shortcut } : {})}>
+        {actionLabel}
+      </Button>
+    </div>
+  );
+}

package/src/Feedback/ErrorState.tsx

@@ -0,0 +1,32 @@
+import { type ReactElement } from "react";
+import { useT } from "../lib/context.tsx";
+import { Icon } from "../Icon/Icon.tsx";
+import { Button } from "../Button/Button.tsx";
+import { stateClass } from "./Feedback.shared.tsx";
+import { type ErrorStateProps } from "./Feedback.types.ts";
+
+/** A failed load: what happened, a retry and the reference to quote to support. */
+export function ErrorState({
+  title,
+  sentence,
+  actionLabel,
+  reference,
+  onRetry,
+}: ErrorStateProps): ReactElement {
+  const t = useT();
+  return (
+    <div className={stateClass} role="alert">
+      <span className="text-danger">
+        <Icon name="CircleAlert" size={24} />
+      </span>
+      <strong className="text-heading-16 font-semibold">{title}</strong>
+      <p className="m-0 text-text-14 text-text-secondary">{sentence}</p>
+      <Button variant="primary" icon="RefreshCw" onClick={onRetry}>
+        {actionLabel ?? t("action.retry")}
+      </Button>
+      {reference ? (
+        <span className="font-mono text-text-12 text-text-secondary">{reference}</span>
+      ) : null}
+    </div>
+  );
+}

package/src/Feedback/Feedback.shared.tsx

@@ -0,0 +1,38 @@
+import { createContext } from "react";
+import { cx } from "../lib/cx.ts";
+import { type Tone } from "./Feedback.types.ts";
+
+export const TONE_ICON: Record<Tone, string> = {
+  info: "Info",
+  success: "CircleCheck",
+  warning: "TriangleAlert",
+  danger: "OctagonAlert",
+};
+
+export const TONE_ICON_CLASS: Record<Tone, string> = {
+  info: cx("text-state-scheduled"),
+  success: cx("text-success"),
+  warning: cx("text-warning"),
+  danger: cx("text-danger"),
+};
+
+export const alertClass = cx(
+  "flex gap-8 p-12 max-w-(--ui-alert) rounded-card border border-border-subtle bg-bg-surface",
+  "forced-colors:border-[CanvasText]",
+);
+
+export const stateClass = cx(
+  "flex flex-col items-center gap-12 p-40 max-w-(--ui-empty) text-center rounded-card",
+  "border border-dashed border-border-strong",
+);
+
+/*
+ * Inside a ToastRegion the region is the live region, mounted before any toast arrives, so a toast
+ * added later is announced (4.1.3, A23-014). A toast outside one keeps its own status role.
+ */
+export const InToastRegion = createContext(false);
+
+export const toastClass = cx(
+  "xos-anim-fade relative inline-flex items-center gap-12 overflow-hidden py-8 ps-12 pe-8",
+  "rounded-card bg-bg-raised shadow-menu print:hidden forced-colors:border",
+);

package/src/Feedback/Feedback.tsx

@@ -0,0 +1,18 @@
+export {
+  type EmptyStateProps,
+  type ErrorStateProps,
+  type RefusalNoticeProps,
+  type InlineAlertProps,
+  type BannerProps,
+  type ToastProps,
+  type UndoToastProps,
+} from "./Feedback.types.ts";
+export { EmptyState } from "./EmptyState.tsx";
+export { ErrorState } from "./ErrorState.tsx";
+export { RefusalNotice } from "./RefusalNotice.tsx";
+export { InlineAlert } from "./InlineAlert.tsx";
+export { Banner } from "./Banner.tsx";
+export { Toast } from "./Toast.tsx";
+export { UndoToast } from "./UndoToast.tsx";
+export { ToastRegion } from "./ToastRegion.tsx";
+export { RegionBoundary, RegionError, type RegionBoundaryProps } from "./RegionBoundary.tsx";

package/src/Feedback/Feedback.types.ts

@@ -0,0 +1,40 @@
+import type {
+  BannerProps as ReferenceBannerProps,
+  EmptyStateProps as ReferenceEmptyStateProps,
+  ErrorStateProps as ReferenceErrorStateProps,
+  InlineAlertProps as ReferenceInlineAlertProps,
+  RefusalNoticeProps as ReferenceRefusalNoticeProps,
+  ToastProps as ReferenceToastProps,
+  UndoToastProps as ReferenceUndoToastProps,
+} from "../types/reference";
+
+export type EmptyStateProps = ReferenceEmptyStateProps & {
+  /**
+   * Weight of the action button. Primary by default; pass "secondary" when the page header already
+   * carries the same primary action, so the screen keeps one primary action (Section 18 gate 27).
+   */
+  actionVariant?: "primary" | "secondary";
+};
+
+export type ErrorStateProps = ReferenceErrorStateProps;
+
+export type RefusalNoticeProps = ReferenceRefusalNoticeProps & {
+  /**
+   * The outcome in words ("Refused"), shown instead of the outcome code, so the code never stands
+   * alone in product copy (Section 11.10 item 2). Without it the chip shows the code.
+   */
+  outcomeLabel?: string;
+};
+
+export type InlineAlertProps = ReferenceInlineAlertProps;
+
+export type BannerProps = ReferenceBannerProps;
+
+export type ToastProps = ReferenceToastProps;
+
+export type UndoToastProps = ReferenceUndoToastProps & {
+  /** Called once when the countdown ends without an undo. */
+  onExpire?: () => void;
+};
+
+export type Tone = "info" | "success" | "warning" | "danger";

package/src/Feedback/InlineAlert.tsx

@@ -0,0 +1,19 @@
+import { type ReactElement } from "react";
+import { Icon } from "../Icon/Icon.tsx";
+import { TONE_ICON, TONE_ICON_CLASS, alertClass } from "./Feedback.shared.tsx";
+import { type InlineAlertProps } from "./Feedback.types.ts";
+
+/** An inline message in context; danger is announced as an alert, the rest as status. */
+export function InlineAlert({ tone = "info", title, children }: InlineAlertProps): ReactElement {
+  return (
+    <div className={alertClass} role={tone === "danger" ? "alert" : "status"}>
+      <span className={TONE_ICON_CLASS[tone]}>
+        <Icon name={TONE_ICON[tone]} />
+      </span>
+      <div className="flex flex-col gap-2">
+        {title ? <div className="font-semibold">{title}</div> : null}
+        <div className="text-text-secondary">{children}</div>
+      </div>
+    </div>
+  );
+}

package/src/Feedback/RefusalNotice.tsx

@@ -0,0 +1,46 @@
+import { type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { Icon } from "../Icon/Icon.tsx";
+import { Button } from "../Button/Button.tsx";
+import { alertClass } from "./Feedback.shared.tsx";
+import { type RefusalNoticeProps } from "./Feedback.types.ts";
+
+/** A refusal (NO_ANSWER, UNRATIFIED or REFUSE) with its reason, never an empty or invented answer. */
+export function RefusalNotice({
+  outcome,
+  outcomeLabel,
+  title,
+  reason,
+  actionLabel,
+  onAction,
+}: RefusalNoticeProps): ReactElement {
+  return (
+    <div className={cx(alertClass, "border-dashed")} role="status">
+      <span className="text-text-secondary">
+        <Icon name="info" />
+      </span>
+      <div className="flex flex-col gap-4">
+        <div className="flex flex-wrap items-center gap-6">
+          {outcomeLabel ? (
+            <span className="px-4 rounded-chip border border-border-strong text-text-11 font-medium text-text-primary">
+              {outcomeLabel}
+            </span>
+          ) : (
+            <span className="px-4 rounded-chip border border-border-strong font-mono text-text-11 font-medium tracking-wide text-text-primary">
+              {outcome}
+            </span>
+          )}
+          <span className="font-semibold">{title}</span>
+        </div>
+        <div className="text-text-secondary">{reason}</div>
+        {actionLabel ? (
+          <div>
+            <Button size="sm" onClick={onAction}>
+              {actionLabel}
+            </Button>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}