@12-apps/ui 6.30.1 → 6.30.3

package/src/components/layout/SettingCard/SettingCard.focus.ts

@@ -0,0 +1,49 @@
+/**
+ * A private copy of `feedback/Dialog`'s `focusFirstTabbable` (FUT-2696), which
+ * this maintenance line predates. `SettingCard` needs the same "move focus to
+ * the first tabbable descendant, or the element itself" rule when it opens in
+ * place — pulling the shared `Dialog.focus` module forward would drag the
+ * Dialog focus-trap fix it shipped with onto a line that only takes security
+ * and backport fixes.
+ */
+
+/**
+ * The candidate list `FocusTrap`'s own `defaultGetTabbable` uses
+ * (`@mui/material/Unstable_TrapFocus/FocusTrap.js`). A match whose resolved
+ * `tabIndex` is -1 is skipped, as the trap itself skips one.
+ */
+const FOCUSABLE_SELECTOR = [
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  'a[href]',
+  'button:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+  'audio[controls]',
+  'video[controls]',
+  '[contenteditable]:not([contenteditable="false"])',
+].join(',');
+
+/**
+ * Move focus into `target`: its first tabbable descendant, or `target`
+ * itself — given `tabIndex={-1}` if it does not already carry one — when
+ * nothing inside is focusable.
+ *
+ * Backs off when focus already sits on a DESCENDANT of `target` other than
+ * `target` itself: that is a caller's `autoFocus` (or an explicit `.focus()`
+ * of their own) that arrived before this ran, and it keeps winning.
+ */
+export function focusFirstTabbable(target: HTMLElement): void {
+  const active = target.ownerDocument.activeElement;
+  if (active !== target && target.contains(active)) return;
+
+  const tabbable = Array.from(target.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).find(
+    (element) => element.tabIndex >= 0,
+  );
+  if (tabbable) {
+    tabbable.focus();
+    return;
+  }
+  if (!target.hasAttribute('tabindex')) target.setAttribute('tabindex', '-1');
+  target.focus();
+}

package/src/components/layout/SettingCard/SettingCard.hooks.ts

@@ -0,0 +1,191 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type RefObject } from 'react';
+
+import { focusFirstTabbable } from './SettingCard.focus';
+
+import type { SettingCardProps, SettingErrorFormatter, SettingSaveResult } from './SettingCard.types';
+
+/** The sentence a rejected save shows: the host's, else the copy's fallback. */
+export function saveErrorMessage(
+  error: unknown,
+  formatError: SettingErrorFormatter | undefined,
+  fallback: string,
+): string {
+  return formatError?.(error) ?? fallback;
+}
+
+/**
+ * Open state that is controlled when `open` is passed and uncontrolled
+ * otherwise — the shape MUI's own `useControlled` has, without its dev-only
+ * warnings reaching into this package's surface.
+ */
+export function useControllableOpen(
+  open: boolean | undefined,
+  defaultOpen: boolean,
+  onOpenChange: ((open: boolean) => void) | undefined,
+): [boolean, (next: boolean) => void] {
+  const [inner, setInner] = useState(defaultOpen);
+  const controlled = open !== undefined;
+  const value = controlled ? open : inner;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!controlled) setInner(next);
+      onOpenChange?.(next);
+    },
+    [controlled, onOpenChange],
+  );
+
+  return [value, setOpen];
+}
+
+/**
+ * Runs a save that may or may not be async and reports how it went.
+ *
+ * `Promise.resolve().then(save)` rather than `await save()`: it also catches a
+ * handler that throws SYNCHRONOUSLY, which an `await` inside `try` would too —
+ * but it keeps the pending state visible for one tick even when the handler
+ * returns nothing, so a save never "succeeds" in the middle of the click that
+ * started it. A sequence id drops the outcome of a run the card has since
+ * abandoned (closed, or started again).
+ */
+export function useSaveRunner(formatError: SettingErrorFormatter | undefined, fallback: string) {
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const seq = useRef(0);
+
+  useEffect(
+    () => () => {
+      // Unmounted: whatever is still in flight has nobody left to report to.
+      seq.current += 1;
+    },
+    [],
+  );
+
+  const run = useCallback(
+    async (save: () => SettingSaveResult): Promise<boolean> => {
+      const mine = (seq.current += 1);
+      setSaving(true);
+      setError(null);
+      try {
+        await Promise.resolve().then(save);
+        if (seq.current !== mine) return false;
+        setSaving(false);
+        return true;
+      } catch (cause) {
+        if (seq.current !== mine) return false;
+        setSaving(false);
+        setError(saveErrorMessage(cause, formatError, fallback));
+        return false;
+      }
+    },
+    [formatError, fallback],
+  );
+
+  const reset = useCallback(() => {
+    seq.current += 1;
+    setSaving(false);
+    setError(null);
+  }, []);
+
+  return { saving, error, run, reset };
+}
+
+/**
+ * A switch that saves the moment it flips.
+ *
+ * It shows the flip at once (`pending`) and holds it while the save runs; a
+ * success hands back to the host's `checked`, which by then says the same
+ * thing, and a failure drops `pending` so the switch returns to what is
+ * actually saved. A flip while one is in flight is ignored rather than queued:
+ * two racing writes of a boolean have no right answer.
+ */
+export function useAsyncSwitch(options: {
+  checked: boolean;
+  onChange: (checked: boolean) => SettingSaveResult;
+  formatError: SettingErrorFormatter | undefined;
+  fallback: string;
+}) {
+  const { checked, onChange, formatError, fallback } = options;
+  const [pending, setPending] = useState<boolean | null>(null);
+  const { saving, error, run } = useSaveRunner(formatError, fallback);
+
+  const flip = useCallback(
+    async (next: boolean) => {
+      if (saving) return;
+      setPending(next);
+      await run(() => onChange(next));
+      setPending(null);
+    },
+    [saving, run, onChange],
+  );
+
+  return { shown: pending ?? checked, saving, error, flip };
+}
+
+/**
+ * Focus follows the card: into it when it opens, back to the trigger when it
+ * closes.
+ *
+ * Inward, it is the Dialog's own rule (`focusFirstTabbable`, FUT-2696): the
+ * first tabbable descendant, and a caller's `autoFocus` keeps winning. The
+ * card is NOT a trap — it is inline, the rest of the page is still there, and
+ * locking Tab inside it would strand a keyboard user who wants to leave
+ * mid-edit. What it owes them is the round trip: the Edit trigger unmounts
+ * while the card is open, so without the return focus would fall to <body>
+ * and the reader would start again from the top of the page.
+ *
+ * Only a TRANSITION moves focus: a card mounted open (or closed) leaves focus
+ * where the page put it.
+ */
+export function useFocusHandoff(
+  open: boolean,
+  body: RefObject<HTMLElement | null>,
+  trigger: RefObject<HTMLElement | null>,
+): void {
+  const previous = useRef(open);
+
+  useLayoutEffect(() => {
+    if (previous.current === open) return;
+    previous.current = open;
+    if (open && body.current) focusFirstTabbable(body.current);
+    if (!open) trigger.current?.focus();
+  }, [open, body, trigger]);
+}
+
+/**
+ * Everything an editable card DOES, apart from how it looks: its open state,
+ * the save and its outcome, Cancel, and where focus goes.
+ */
+export function useSettingCard(props: SettingCardProps) {
+  const { copy, onSave, onCancel, open: openProp, defaultOpen = false, onOpenChange, formatError } = props;
+  const disabled = props.disabled ?? false;
+  const saveDisabled = props.saveDisabled ?? false;
+  const [open, setOpen] = useControllableOpen(openProp, defaultOpen, onOpenChange);
+  const { saving, error, run, reset } = useSaveRunner(formatError, copy.saveFailed);
+  const bodyRef = useRef<HTMLDivElement>(null);
+  const editRef = useRef<HTMLButtonElement>(null);
+  useFocusHandoff(open, bodyRef, editRef);
+
+  // However the card closed — Cancel, a save, or a controlling host — the
+  // next opening starts without the last one's error.
+  useEffect(() => {
+    if (!open) reset();
+  }, [open, reset]);
+
+  const openCard = useCallback(() => setOpen(true), [setOpen]);
+
+  const cancel = useCallback(() => {
+    if (saving) return;
+    setOpen(false);
+    onCancel?.();
+  }, [saving, setOpen, onCancel]);
+
+  const save = useCallback(() => {
+    if (saving || saveDisabled) return;
+    void run(onSave).then((saved) => {
+      if (saved) setOpen(false);
+    });
+  }, [saving, saveDisabled, run, onSave, setOpen]);
+
+  return { open, disabled, saveDisabled, saving, error, bodyRef, editRef, openCard, cancel, save };
+}

package/src/components/layout/SettingCard/SettingCard.md

@@ -0,0 +1,121 @@
+# SettingCard
+
+## Purpose
+
+One setting, summarised while closed and edited **in place**. A settings screen
+built from these reads as a list of answers ("Sign out after 30 minutes") with
+one Edit each, instead of a wall of open forms.
+
+- **Closed:** title, a status pill, a one-line summary, and Edit.
+- **Open:** Edit opens the card where it is — no dialog, no route change —
+  around the host's form (`children`), a collapsible "learn more" disclosure and
+  Cancel / Save.
+
+The card knows nothing about what it edits. The form, the draft and the save
+are the host's; the card owns the open/closed state, the save's pending and
+failed states, and focus.
+
+Part of the `layout/SettingCard` family, with
+[`SettingToggle`](./SettingToggle.md), [`SettingGroup`](./SettingGroup.md) and
+[`SettingGrid`](./SettingGrid.md).
+
+## Usage
+
+```tsx
+import { SettingCard } from '@12-apps/ui/layout/SettingCard';
+import { NumberField } from '@12-apps/ui/form/NumberField';
+import { useLocaleCopy } from '@12-apps/i18n/react';
+import { SETTING_CARD_COPY } from '@12-apps/ui/locales';
+
+const copy = useLocaleCopy(SETTING_CARD_COPY);
+const [draft, setDraft] = useState<number | null>(saved);
+
+<SettingCard
+  copy={copy}
+  title="Session timeout"
+  summary={`Sign out after ${saved} minutes`}
+  status={{ label: 'On', color: 'success' }}
+  learnMore="A shorter timeout protects shared devices."
+  onCancel={() => setDraft(saved)}
+  onSave={() => api.saveTimeout(draft)}   // may return a promise
+>
+  <NumberField label="Minutes" value={draft} onChange={setDraft} min={5} max={240} suffix="min" />
+</SettingCard>
+```
+
+## Props
+
+| prop | type | default | effect |
+|---|---|---|---|
+| `copy` | `SettingCardCopy` | **required** | Edit / Cancel / Save / Saving / Learn more / the fallback error. No shipped default — pass `EN_US_SETTING_CARD_COPY`, `PT_BR_SETTING_CARD_COPY`, or `SETTING_CARD_COPY` through `useLocaleCopy`. |
+| `title` | `string` | **required** | The setting's name. A heading, and the accessible name of the card's region. |
+| `onSave` | `() => void \| Promise<unknown>` | **required** | Persist the draft. See *Saving* below. |
+| `children` | `ReactNode` | **required** | The form. Rendered only while open. |
+| `summary` | `ReactNode` | — | The one line a closed card shows. Ends in an ellipsis rather than wrapping. |
+| `status` | `{ label: string; color?: ColorValue }` | — | The pill beside the title. `label` is always shown, so colour never carries the meaning alone. |
+| `learnMore` | `ReactNode` | — | Longer explanation behind a disclosure in the open card. Omit for no disclosure. |
+| `onCancel` | `() => void` | — | The card closed without saving. Reset the host's draft here. |
+| `open` / `defaultOpen` / `onOpenChange` | | uncontrolled, closed | Controlled or uncontrolled open state. `onOpenChange` hears Edit, Cancel, Escape and a successful save. |
+| `disabled` | `boolean` | `false` | Disables Edit. |
+| `saveDisabled` | `boolean` | `false` | Disables Save — for a draft the host knows is invalid. |
+| `formatError` | `(error: unknown) => string \| undefined` | — | The sentence to show for a rejected save. `undefined` falls back to `copy.saveFailed`. |
+| `headingLevel` | `'h2' … 'h6'` | `'h3'` | Where the title sits in the page outline. |
+| `icon` | `ReactNode` | — | A decorative glyph before the title. |
+| `dataTestId` | `string` | — | Root test id; parts derive `-edit`, `-save`, `-cancel`, `-summary`, `-status`, `-error`, `-saving`, `-body`, `-learn-more`, `-title`. |
+| `className`, `sx` | | | Styling hooks on the root `<section>`. |
+
+## Saving
+
+- **Pending.** While the promise `onSave` returned is pending, Save shows a
+  spinner and `copy.saving`, the card is `aria-busy`, Cancel is disabled and
+  further presses of Save are ignored — `onSave` runs once.
+- **Resolved.** The card closes and focus returns to Edit. Update `summary` from
+  the saved value in the same handler.
+- **Rejected** (or `onSave` throws). The card **stays open**, the draft is
+  untouched, and the error appears in a `role="alert"` line that Save is
+  described by. The card never prints `error.message` by itself — that string
+  is written for a developer; map it with `formatError`.
+
+Save is `aria-disabled`, not `disabled`, while pending: a disabled button drops
+the focus it holds, and a keyboard user whose save then failed would be sent
+back to the top of the page.
+
+## Cancelling
+
+Cancel (or Escape inside the open card) closes the card and calls `onCancel`.
+`children` unmount on close, so any **uncontrolled** state inside the form is
+discarded by construction; a controlled draft is the host's to reset in
+`onCancel`, as in the example above.
+
+## In a grid
+
+An open card sets `grid-column: 1 / -1` on itself and carries
+`data-setting-card-open`, so inside a [`SettingGrid`](./SettingGrid.md) — or any
+CSS grid — its form gets the whole row. `height: 100%` lets it match the other
+cards in its row while closed.
+
+## Accessibility
+
+- The root is a `<section>` labelled by the title; the title is a real heading
+  (`headingLevel`).
+- Edit's accessible name is `copy.edit` **plus the title** ("Edit Session
+  timeout"), so a grid of cards is not a list of identical buttons.
+- **Focus round trip.** Opening moves focus to the first tabbable element in the
+  form — the rule `Dialog` uses (`focusFirstTabbable`, FUT-2696), so a field's
+  own `autoFocus` still wins. Closing, by any path, returns focus to Edit. A
+  card mounted open does not take focus.
+- **No focus trap.** The card is inline and the page around it stays usable; a
+  trap would strand a keyboard user who wants to leave mid-edit. Escape
+  cancels.
+- The "learn more" trigger owns `aria-expanded` / `aria-controls`; the region is
+  kept mounted so `aria-controls` always resolves.
+- The save failure is `role="alert"`, announced without moving focus.
+
+## Best practices
+
+- Keep `summary` to the current **value** in words, not a description of the
+  setting — the title already says what it is.
+- Use `status` for a state that changes how the summary reads ("Off",
+  "Managed by your organisation"); skip it when the summary says it all.
+- A setting that is a single on/off is a [`SettingToggle`](./SettingToggle.md),
+  not a card with a switch inside.

package/src/components/layout/SettingCard/SettingCard.metrics.ts

@@ -0,0 +1,22 @@
+/**
+ * The setting-card family's lengths, in design px. The web reads every one
+ * through `rem(theme, n)`, so they scale with the host's type scale.
+ */
+export const SETTING_CARD = {
+  /** Between the icon and the title. */
+  iconGap: 12,
+  /** The spinner beside a switch while its flip is saving. */
+  spinnerSize: 16,
+  /** How far a group's dependent rows sit in from its main switch. */
+  groupIndent: 24,
+  /** The rule down the left of a group's dependent rows. */
+  groupRuleWidth: 2,
+  /** The narrowest a grid column gets by default. */
+  gridMinColumnWidth: 320,
+} as const;
+
+/** The grid's default gap, in theme SPACING units (not px): what `sx`'s `gap: 2` means. */
+export const SETTING_GRID_GAP_UNITS = 2;
+
+/** How faded a group's dependent rows are while the main switch is off. */
+export const SETTING_GROUP_INACTIVE_OPACITY = 0.5;

package/src/components/layout/SettingCard/SettingCard.parts.tsx

@@ -0,0 +1,162 @@
+import Box from '@mui/material/Box/index.js';
+import CircularProgress from '@mui/material/CircularProgress/index.js';
+import { useTheme } from '@mui/material/styles/index.js';
+import React, { useId, useState } from 'react';
+
+import { Icon } from '../../../icons';
+import { rem } from './SettingCard.rem';
+import { Chip } from '../../data-display/Chip';
+import { Button } from '../../form/Button';
+import { BUTTON_SIZES } from '../../form/Button/Button.metrics';
+import { Collapsible } from '../Collapsible';
+
+import { SETTING_CARD } from './SettingCard.metrics';
+import { errorStyles, headerStyles, iconStyles, titleStyles } from './SettingCard.styles';
+import type { SettingHeadingLevel, SettingStatus } from './SettingCard.types';
+
+/** `<root>-<part>` when the host gave a root test id, else nothing. */
+export const partTestId = (root: string | undefined, part: string): string | undefined =>
+  root ? `${root}-${part}` : undefined;
+
+interface HeaderProps {
+  titleId: string;
+  title: string;
+  headingLevel: SettingHeadingLevel;
+  icon?: React.ReactNode;
+  status?: SettingStatus;
+  /** Rendered at the row's far end — the Edit trigger, or a switch. */
+  trailing?: React.ReactNode;
+  /** Renders the title as a `<label>` for this control instead of a heading. */
+  labelFor?: string;
+  dataTestId?: string;
+}
+
+/**
+ * Icon, title, status pill, and whatever the row ends with.
+ *
+ * A switch card's title is the switch's `<label>`, so the words are both its
+ * accessible name and a tap target far larger than the track. An editable
+ * card's title is a heading, so the page outline lists every setting.
+ */
+export const SettingHeader: React.FC<HeaderProps> = ({
+  titleId,
+  title,
+  headingLevel,
+  icon,
+  status,
+  trailing,
+  labelFor,
+  dataTestId,
+}) => {
+  const theme = useTheme();
+  return (
+    <Box sx={headerStyles(theme)}>
+      {icon && (
+        <Box component="span" aria-hidden sx={iconStyles(theme)}>
+          {icon}
+        </Box>
+      )}
+      <Box sx={{ display: 'flex', alignItems: 'center', flexWrap: 'wrap', gap: 1, minWidth: 0, flex: 1 }}>
+        <Box
+          component={labelFor ? 'label' : headingLevel}
+          id={titleId}
+          htmlFor={labelFor}
+          sx={{ ...titleStyles(theme), ...(labelFor ? { cursor: 'pointer' } : {}) }}
+          data-testid={partTestId(dataTestId, 'title')}
+        >
+          {title}
+        </Box>
+        {status && (
+          <Chip
+            label={status.label}
+            color={status.color ?? 'neutral'}
+            size="sm"
+            variant="outlined"
+            dataTestId={partTestId(dataTestId, 'status')}
+          />
+        )}
+      </Box>
+      {trailing}
+    </Box>
+  );
+};
+
+/**
+ * The failure line. `role="alert"` so it is announced the moment it appears,
+ * without anyone having to move focus to find it.
+ */
+export const SaveError: React.FC<{ id: string; message: string | null; dataTestId?: string }> = ({
+  id,
+  message,
+  dataTestId,
+}) => {
+  const theme = useTheme();
+  if (!message) return null;
+  return (
+    <Box component="p" id={id} role="alert" sx={errorStyles(theme)} data-testid={partTestId(dataTestId, 'error')}>
+      {message}
+    </Box>
+  );
+};
+
+/** The spinner that rides beside a pending control; decorative — the words are announced separately. */
+export const PendingSpinner: React.FC<{ dataTestId?: string }> = ({ dataTestId }) => {
+  const theme = useTheme();
+  return (
+    <CircularProgress
+      size={rem(theme, SETTING_CARD.spinnerSize)}
+      color="inherit"
+      aria-hidden
+      data-testid={partTestId(dataTestId, 'saving')}
+    />
+  );
+};
+
+/**
+ * The "learn more" disclosure: a text button that owns `aria-expanded`, and
+ * the collapsible region it controls. Closed by default — it is the longer
+ * explanation, and the form is what the reader came for.
+ */
+export const LearnMore: React.FC<{
+  label: string;
+  children: React.ReactNode;
+  dataTestId?: string;
+}> = ({ label, children, dataTestId }) => {
+  const [expanded, setExpanded] = useState(false);
+  const regionId = useId();
+  const theme = useTheme();
+  return (
+    // Pulled out by the button's own padding, so the words line up with the form above.
+    <Box sx={{ marginLeft: `-${rem(theme, BUTTON_SIZES.sm.paddingHorizontal)}` }}>
+      <Button
+        variant="text"
+        size="sm"
+        aria-expanded={expanded}
+        aria-controls={regionId}
+        onClick={() => setExpanded((was) => !was)}
+        icon={
+          <Box
+            component="span"
+            sx={{
+              display: 'inline-flex',
+              transform: expanded ? 'rotate(180deg)' : 'none',
+              transition: theme.transitions.create('transform'),
+            }}
+          >
+            <Icon name="ExpandMore" size="xs" />
+          </Box>
+        }
+        iconPosition="right"
+        dataTestId={partTestId(dataTestId, 'learn-more')}
+      >
+        {label}
+      </Button>
+      {/* Kept mounted so `aria-controls` always names an element that exists. */}
+      <Collapsible open={expanded} keepMounted sx={{ marginLeft: rem(theme, BUTTON_SIZES.sm.paddingHorizontal) }} dataTestId={partTestId(dataTestId, 'learn-more-content')}>
+        <Box id={regionId} sx={{ ...theme.typography.body2, color: 'text.secondary', pt: 1 }}>
+          {children}
+        </Box>
+      </Collapsible>
+    </Box>
+  );
+};

package/src/components/layout/SettingCard/SettingCard.rem.ts

@@ -0,0 +1,14 @@
+import type { Theme } from '@mui/material/styles/index.js';
+
+/**
+ * A size drawn at `px`, as rem through the theme's type scale.
+ *
+ * A private copy of `tokens/relative`'s `rem()` (FUT-2591), which this
+ * maintenance line predates: `theme.typography.pxToRem(px)` needs no gate or
+ * shared vocabulary to be correct, and pulling the shared module forward
+ * would drag its lint gate and exceptions ledger onto a line that only takes
+ * security and backport fixes.
+ */
+export function rem(theme: Theme, px: number): string {
+  return theme.typography.pxToRem(px);
+}