@12-apps/ui 6.40.0 → 6.41.1

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

@@ -0,0 +1,197 @@
+import Box from '@mui/material/Box/index.js';
+import React, { forwardRef, useId } from 'react';
+
+import { Icon } from '../../../icons';
+import { Button } from '../../form/Button';
+
+import { useSettingCard } from './SettingCard.hooks';
+import { LearnMore, PendingSpinner, SaveError, SettingHeader, partTestId } from './SettingCard.parts';
+import { SETTING_CARD_OPEN_ATTR, actionsStyles, summaryStyles, surfaceStyles, withCallerSx } from './SettingCard.styles';
+import type { SettingCardCopy, SettingCardProps } from './SettingCard.types';
+
+interface OpenBodyProps {
+  bodyRef: React.RefObject<HTMLDivElement | null>;
+  titleId: string;
+  errorId: string;
+  copy: SettingCardCopy;
+  learnMore?: React.ReactNode;
+  children: React.ReactNode;
+  saving: boolean;
+  error: string | null;
+  saveDisabled: boolean;
+  onSave: () => void;
+  onCancel: () => void;
+  dataTestId?: string;
+}
+
+/**
+ * The open card: the host's form, the disclosure, the failure line, and the
+ * two actions.
+ *
+ * Save is NOT `disabled` while it saves — it is `aria-disabled` and ignores
+ * the click. A disabled button drops the focus it holds, so a keyboard user
+ * who pressed Save would land on `<body>` and, if the save then failed, have
+ * to find their way back to the form from the top of the page.
+ */
+const OpenBody: React.FC<OpenBodyProps> = ({
+  bodyRef, titleId, errorId, copy, learnMore, children, saving, error, saveDisabled, onSave, onCancel, dataTestId,
+}) => {
+  const onKeyDown = (event: React.KeyboardEvent) => {
+    if (event.key !== 'Escape') return;
+    event.stopPropagation();
+    onCancel();
+  };
+
+  return (
+    <Box
+      ref={bodyRef}
+      role="group"
+      aria-labelledby={titleId}
+      onKeyDown={onKeyDown}
+      sx={{ display: 'flex', flexDirection: 'column', gap: 2, flex: 1 }}
+      data-testid={partTestId(dataTestId, 'body')}
+    >
+      <Box>{children}</Box>
+      {learnMore && (
+        <LearnMore label={copy.learnMore} dataTestId={dataTestId}>
+          {learnMore}
+        </LearnMore>
+      )}
+      <SaveError id={errorId} message={error} dataTestId={dataTestId} />
+      <Box sx={(theme) => actionsStyles(theme)}>
+        <Button variant="ghost" color="neutral" onClick={onCancel} disabled={saving} dataTestId={partTestId(dataTestId, 'cancel')}>
+          {copy.cancel}
+        </Button>
+        <Button
+          variant="solid"
+          onClick={onSave}
+          disabled={saveDisabled}
+          aria-disabled={saving || undefined}
+          aria-describedby={error ? errorId : undefined}
+          icon={saving ? <PendingSpinner dataTestId={dataTestId} /> : undefined}
+          iconPosition="left"
+          dataTestId={partTestId(dataTestId, 'save')}
+        >
+          {saving ? copy.saving : copy.save}
+        </Button>
+      </Box>
+    </Box>
+  );
+};
+
+/**
+ * A setting, summarised while closed and edited in place.
+ *
+ * Closed: title, status pill, a one-line summary and Edit. Edit opens the card
+ * where it is — no dialog, no route — around the host's form, a "learn more"
+ * disclosure and Cancel / Save. Save may be async: the card holds its saving
+ * state while the promise is pending, closes when it resolves, and stays open
+ * with the error when it rejects. Focus moves into the card as it opens and
+ * back to Edit as it closes.
+ */
+interface EditTriggerProps {
+  triggerRef: React.RefObject<HTMLButtonElement | null>;
+  id: string;
+  titleId: string;
+  label: string;
+  disabled: boolean;
+  onOpen: () => void;
+  dataTestId?: string;
+}
+
+/** Edit. Its accessible name is "Edit" AND the card's title, so a grid of them is not a list of "Edit, Edit, Edit". */
+const EditTrigger: React.FC<EditTriggerProps> = ({ triggerRef, id, titleId, label, disabled, onOpen, dataTestId }) => (
+  <Button
+    ref={triggerRef}
+    id={id}
+    variant="outline"
+    color="neutral"
+    size="sm"
+    icon={<Icon name="Edit" size="xs" />}
+    iconPosition="left"
+    disabled={disabled}
+    aria-labelledby={`${id} ${titleId}`}
+    onClick={onOpen}
+    dataTestId={partTestId(dataTestId, 'edit')}
+  >
+    {label}
+  </Button>
+);
+
+/**
+ * A setting, summarised while closed and edited in place.
+ *
+ * Closed: title, status pill, a one-line summary and Edit. Edit opens the card
+ * where it is — no dialog, no route — around the host's form, a "learn more"
+ * disclosure and Cancel / Save. Save may be async: the card holds its saving
+ * state while the promise is pending, closes when it resolves, and stays open
+ * with the error when it rejects. Focus moves into the card as it opens and
+ * back to Edit as it closes.
+ */
+export const SettingCard = forwardRef<HTMLElement, SettingCardProps>(function SettingCard(props, ref) {
+  const { title, headingLevel = 'h3', icon, status, summary, children, learnMore, copy, dataTestId, className, sx } = props;
+  const baseId = useId();
+  const titleId = `${baseId}-title`;
+  const card = useSettingCard(props);
+  const { open } = card;
+
+  return (
+    <Box
+      component="section"
+      ref={ref}
+      aria-labelledby={titleId}
+      aria-busy={card.saving || undefined}
+      data-state={open ? 'open' : 'closed'}
+      {...{ [SETTING_CARD_OPEN_ATTR]: open ? '' : undefined }}
+      data-testid={dataTestId}
+      className={className}
+      sx={withCallerSx((theme) => surfaceStyles(theme, open), sx)}
+    >
+      <SettingHeader
+        titleId={titleId}
+        title={title}
+        headingLevel={headingLevel}
+        icon={icon}
+        status={status}
+        trailing={
+          open ? null : (
+            <EditTrigger
+              triggerRef={card.editRef}
+              id={`${baseId}-edit`}
+              titleId={titleId}
+              label={copy.edit}
+              disabled={card.disabled}
+              onOpen={card.openCard}
+              dataTestId={dataTestId}
+            />
+          )
+        }
+        dataTestId={dataTestId}
+      />
+      {!open && summary != null && (
+        <Box component="p" sx={summaryStyles} data-testid={partTestId(dataTestId, 'summary')}>
+          {summary}
+        </Box>
+      )}
+      {open && (
+        <OpenBody
+          bodyRef={card.bodyRef}
+          titleId={titleId}
+          errorId={`${baseId}-error`}
+          copy={copy}
+          learnMore={learnMore}
+          saving={card.saving}
+          error={card.error}
+          saveDisabled={card.saveDisabled}
+          onSave={card.save}
+          onCancel={card.cancel}
+          dataTestId={dataTestId}
+        >
+          {children}
+        </OpenBody>
+      )}
+    </Box>
+  );
+});
+
+SettingCard.displayName = 'SettingCard';

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

@@ -0,0 +1,140 @@
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+import type { ReactNode } from 'react';
+
+import type { SettingCardCopy, SettingSwitchCopy } from '../../../copy';
+import type { ColorValue } from '../../../tokens/vocabulary';
+
+export type { SettingCardCopy, SettingSwitchCopy } from '../../../copy';
+
+/**
+ * What a save handler may return. A promise holds the card in its saving
+ * state until it settles; a rejection is the failure path. A plain return is
+ * a synchronous success.
+ */
+export type SettingSaveResult = void | Promise<unknown>;
+
+/**
+ * Turns whatever a rejected save threw into the sentence the card shows.
+ * Return `undefined` to fall back to the copy's `saveFailed`. The card never
+ * renders an `Error.message` on its own: that string is usually written for a
+ * developer, in the developer's language.
+ */
+export type SettingErrorFormatter = (error: unknown) => string | undefined;
+
+/** The heading level a card's title renders at, so it fits the page outline. */
+export type SettingHeadingLevel = 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+
+/** The pill beside a closed card's title: the setting's current state, in words. */
+export interface SettingStatus {
+  /** What the state IS, in the host's language: "On", "Not configured". */
+  label: string;
+  /** A house colour. Colour is never the only carrier: `label` is always shown. Defaults to `neutral`. */
+  color?: ColorValue;
+}
+
+/** What every card in the family shares. */
+interface SettingSurfaceProps {
+  /** The setting's name. Also the accessible name of the card's region. */
+  title: string;
+  /** The heading level of `title`. Defaults to `h3`. */
+  headingLevel?: SettingHeadingLevel;
+  /** A decorative glyph before the title. */
+  icon?: ReactNode;
+  /** Maps a rejected save to the sentence shown; see {@link SettingErrorFormatter}. */
+  formatError?: SettingErrorFormatter;
+  /** Root test id. Parts derive theirs from it (`<id>-edit`, `<id>-save`, …). */
+  dataTestId?: string;
+  className?: string;
+  sx?: SxProps<Theme>;
+}
+
+export interface SettingCardProps extends SettingSurfaceProps {
+  /** The chrome words (Edit, Cancel, Save, …). REQUIRED — no default copy. */
+  copy: SettingCardCopy;
+  /** The one line a closed card shows under its title: the setting's current value. */
+  summary?: ReactNode;
+  /** The pill beside the title. Omit for none. */
+  status?: SettingStatus;
+  /** The form, rendered only while the card is open (so an uncontrolled draft is discarded on close). */
+  children: ReactNode;
+  /** Longer explanation behind a "learn more" disclosure in the open card. Omit for no disclosure. */
+  learnMore?: ReactNode;
+  /**
+   * Persist the draft. The card stays in its saving state while a returned
+   * promise is pending, closes when it resolves, and STAYS OPEN showing the
+   * error when it rejects.
+   */
+  onSave: () => SettingSaveResult;
+  /** The card closed without saving — reset the host's draft here. */
+  onCancel?: () => void;
+  /** Controlled open state. Pair with `onOpenChange`. */
+  open?: boolean;
+  /** Uncontrolled initial open state. */
+  defaultOpen?: boolean;
+  /** Every open/close request: Edit, Cancel, Escape, and a successful save. */
+  onOpenChange?: (open: boolean) => void;
+  /** Disables Edit on a closed card (the setting cannot be changed from here). */
+  disabled?: boolean;
+  /** Disables Save — for a draft the host knows is invalid. */
+  saveDisabled?: boolean;
+}
+
+interface SettingSwitchProps extends SettingSurfaceProps {
+  /** The saving and failure words. REQUIRED — no default copy. */
+  copy: SettingSwitchCopy;
+  /** Explanation under the title. Read to screen readers as the switch's description. */
+  summary?: ReactNode;
+  /** The persisted value. The switch shows the flip optimistically while it saves, then this again. */
+  checked: boolean;
+  /**
+   * Persist a flip. The switch shows the new value and a saving state while a
+   * returned promise is pending; a rejection reverts it and shows the error.
+   */
+  onChange: (checked: boolean) => SettingSaveResult;
+  /** Disables the switch. */
+  disabled?: boolean;
+}
+
+/**
+ * `card` draws the surface; `row` draws the same content flat, for a
+ * dependent row inside a `SettingGroup` (a card inside a card reads as two
+ * subjects).
+ */
+export type SettingToggleVariant = 'card' | 'row';
+
+export interface SettingToggleProps extends SettingSwitchProps {
+  /** Defaults to `card`. */
+  variant?: SettingToggleVariant;
+}
+
+export interface SettingGroupProps extends SettingSwitchProps {
+  /**
+   * Why the dependent rows are inactive while the main switch is off —
+   * "Turn on notifications to choose which ones you get". Shown only then.
+   */
+  inactiveHint: string;
+  /** The dependent rows. Stay rendered while the main switch is off, dimmed and inert. */
+  children: ReactNode;
+}
+
+/** The most columns a `SettingGrid` lays out. */
+export type SettingGridColumns = 1 | 2 | 3;
+
+export interface SettingGridProps {
+  children: ReactNode;
+  /**
+   * The narrowest a column may get, in design px (scaled with the type
+   * scale). The grid adds a column each time its OWN width fits one more.
+   * Defaults to 320.
+   */
+  minColumnWidth?: number;
+  /** Defaults to 3. */
+  maxColumns?: SettingGridColumns;
+  /** Gap between cards, in theme spacing units. Defaults to 2. */
+  gap?: number;
+  /** Accessible name. When set the grid renders as a labelled `region`. */
+  'aria-label'?: string;
+  dataTestId?: string;
+  className?: string;
+  sx?: SxProps<Theme>;
+}

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

@@ -0,0 +1,65 @@
+# SettingGrid
+
+## Purpose
+
+Lays setting cards out in **one, two or three columns by the width it is
+given**. Part of the `layout/SettingCard` family.
+
+- **Container queries, not media queries.** A settings grid lives beside a
+  navigation rail, inside a drawer, in half a split view; the viewport says
+  nothing about how wide any of those are. The grid asks its own width.
+- **Equal-height rows, without measuring.** Each row is as tall as its tallest
+  card and every card in it stretches to match (`grid-auto-rows: auto` with
+  `align-items: stretch`). Not `1fr` rows — those make *every* row as tall as the
+  tallest one on the page.
+- **An open card spans the row.** A [`SettingCard`](./SettingCard.md) mid-edit
+  takes the whole row, wherever it sat, so its form has room.
+
+## Usage
+
+```tsx
+import { SettingCard, SettingGrid, SettingToggle } from '@12-apps/ui/layout/SettingCard';
+
+<SettingGrid aria-label="Security">
+  <SettingCard … />
+  <SettingToggle … />
+  <SettingGroup … />
+</SettingGrid>
+```
+
+## Props
+
+| prop | type | default | effect |
+|---|---|---|---|
+| `children` | `ReactNode` | **required** | The cards. |
+| `minColumnWidth` | `number` | `320` | The narrowest a column may get, in design px (scaled through the type scale). A column is added each time the grid's own width fits one more. |
+| `maxColumns` | `1 \| 2 \| 3` | `3` | The most columns laid out. |
+| `gap` | `number` | `2` | Gap between cards, in theme spacing units. |
+| `aria-label` | `string` | — | When set, the grid is a labelled `region`. |
+| `dataTestId` | `string` | — | On the container; the inner grid is `<id>-grid`. |
+| `className`, `sx` | | | On the container. |
+
+## How the columns are decided
+
+The outer element is an `inline-size` container named `setting-grid`
+(`SETTING_GRID_CONTAINER`); the inner element is the grid, because a container
+query is answered by an **ancestor**. `n` columns apply from
+
+```
+calc(n × minColumnWidth + (n − 1) × gap)
+```
+
+so a column is never narrower than `minColumnWidth`. Nested grids each answer
+to their own container.
+
+## The open-card span
+
+`SettingCard` sets `grid-column: 1 / -1` on itself while open and carries
+`data-setting-card-open`. The grid also gives the whole row to a direct child
+that **contains** an open card (`:has()`), so a host that wraps each card in an
+element of its own keeps the behaviour.
+
+## Accessibility
+
+Layout only: reading and tab order are the children's source order at every
+width — the grid never reorders them.

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

@@ -0,0 +1,105 @@
+import Box from '@mui/material/Box/index.js';
+import { useTheme, type CSSObject, type Theme } from '@mui/material/styles/index.js';
+import { forwardRef } from 'react';
+
+import { rem } from '../../../tokens/relative';
+
+import { SETTING_CARD, SETTING_GRID_GAP_UNITS } from './SettingCard.metrics';
+import { partTestId } from './SettingCard.parts';
+import { SETTING_CARD_OPEN_ATTR, withCallerSx } from './SettingCard.styles';
+import type { SettingGridColumns, SettingGridProps } from './SettingCard.types';
+
+/** The container the grid's own queries are asked of. Named, so a nested grid answers to its own. */
+export const SETTING_GRID_CONTAINER = 'setting-grid';
+
+/** The track list for `n` equal columns. `minmax(0, …)` so a long word cannot widen its column. */
+const tracks = (n: SettingGridColumns): string => `repeat(${n}, minmax(0, 1fr))`;
+
+/**
+ * The narrowest the container can be and still fit `n` columns of
+ * `minColumnWidth` with the gaps between them. A `calc()` because the gap is a
+ * spacing unit and the width a type-scale length: two scales, one sum.
+ */
+const threshold = (theme: Theme, n: number, minColumnPx: number, gapUnits: number): string =>
+  `calc(${n} * ${rem(theme, minColumnPx)} + ${n - 1} * ${theme.spacing(gapUnits)})`;
+
+/**
+ * The grid itself.
+ *
+ * - Columns come from CONTAINER queries, not viewport ones: a settings grid
+ *   lives beside a rail, inside a drawer, in half a split view, and the
+ *   viewport says nothing about how wide any of those are.
+ * - `grid-auto-rows: auto` with `align-items: stretch` is the equal-height
+ *   rule: each row is as tall as its tallest card and every card in it
+ *   stretches to match. Not `1fr` rows — those would make EVERY row as tall as
+ *   the tallest, so one open card would inflate the whole page.
+ * - An open card spans the row. The card sets `grid-column` on itself; the
+ *   `:has()` rule covers a card the host wrapped in an element of its own.
+ */
+export interface SettingGridLayout {
+  /** The narrowest column, in DESIGN px (drawn through `rem`). */
+  minColumnPx: number;
+  maxColumns: SettingGridColumns;
+  /** The gap, in theme SPACING units. */
+  gapUnits: number;
+}
+
+export function settingGridStyles(theme: Theme, { minColumnPx, maxColumns, gapUnits }: SettingGridLayout): CSSObject {
+  const styles: CSSObject = {
+    display: 'grid',
+    gap: theme.spacing(gapUnits),
+    gridTemplateColumns: tracks(1),
+    gridAutoRows: 'auto',
+    alignItems: 'stretch',
+    [`& > [${SETTING_CARD_OPEN_ATTR}], & > :has([${SETTING_CARD_OPEN_ATTR}])`]: { gridColumn: '1 / -1' },
+  };
+  for (const n of [2, 3] as const) {
+    if (n > maxColumns) break;
+    styles[`@container ${SETTING_GRID_CONTAINER} (min-width: ${threshold(theme, n, minColumnPx, gapUnits)})`] = {
+      gridTemplateColumns: tracks(n),
+    };
+  }
+  return styles;
+}
+
+/**
+ * Lays setting cards out in one, two or three columns by the width it is
+ * GIVEN — see {@link settingGridStyles}. Two elements, because a container
+ * query is answered by an ANCESTOR: the outer one is the container, the inner
+ * one the grid.
+ */
+export const SettingGrid = forwardRef<HTMLDivElement, SettingGridProps>(function SettingGrid(props, ref) {
+  const {
+    children,
+    minColumnWidth = SETTING_CARD.gridMinColumnWidth,
+    maxColumns = 3,
+    gap = SETTING_GRID_GAP_UNITS,
+    'aria-label': ariaLabel,
+    dataTestId,
+    className,
+    sx,
+  } = props;
+  const theme = useTheme();
+  const gridStyles = settingGridStyles(theme, { minColumnPx: minColumnWidth, maxColumns, gapUnits: gap });
+
+  return (
+    <Box
+      ref={ref}
+      role={ariaLabel ? 'region' : undefined}
+      aria-label={ariaLabel}
+      data-testid={dataTestId}
+      className={className}
+      sx={withCallerSx({ containerType: 'inline-size', containerName: SETTING_GRID_CONTAINER, minWidth: 0 }, sx)}
+    >
+      <Box
+        sx={gridStyles}
+        data-max-columns={maxColumns}
+        data-testid={partTestId(dataTestId, 'grid')}
+      >
+        {children}
+      </Box>
+    </Box>
+  );
+});
+
+SettingGrid.displayName = 'SettingGrid';

package/src/components/layout/SettingCard/SettingGroup.context.ts

@@ -0,0 +1,11 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * What a `SettingGroup` tells the rows inside it: whether its main switch is
+ * off. `inert` on the rows' container already makes every descendant
+ * unreachable; this is for the family's own rows (`SettingToggle`) to ALSO
+ * draw and announce themselves as disabled, which `inert` does not do.
+ */
+export const SettingGroupContext = createContext<{ inactive: boolean }>({ inactive: false });
+
+export const useSettingGroup = (): { inactive: boolean } => useContext(SettingGroupContext);

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

@@ -0,0 +1,81 @@
+# SettingGroup
+
+## Purpose
+
+**One subject**: a main switch, plus the settings that only mean something
+while it is on, indented beneath it. "Notifications" on or off, and — while on —
+which notifications and when.
+
+When the main switch is off the dependent rows **stay where they are**: dimmed,
+disabled, and explained by a short hint. They are not removed. A reader
+deciding whether to turn a feature on is helped by seeing what it would let
+them configure, and a layout that jumps when a switch flips moves the thing
+they were about to press.
+
+Part of the `layout/SettingCard` family.
+
+## One group per subject — not a container for a page
+
+A `SettingGroup` is for several settings of **the same subject**, where the
+main switch decides whether the others apply at all. It is not a way to put
+several unrelated settings in one box.
+
+| these are… | use |
+|---|---|
+| Notifications (main switch) + digest, mentions, quiet hours | **one** `SettingGroup` — the rows mean nothing with notifications off |
+| Session timeout, two-step sign-in, language | **three** cards — a `SettingCard`, a `SettingToggle`, a `SettingCard` — laid out by a `SettingGrid` |
+| Backups (main switch) + frequency, retention | **one** `SettingGroup` |
+| Backups and notifications | **two** groups, never one |
+
+The test: if turning the main switch off would **not** make a row meaningless,
+that row is a different subject and belongs in its own card. Squeezing two
+subjects into one group gives one of them a main switch it does not have, and a
+hint ("inactive until X is on") that is false for it.
+
+## Usage
+
+```tsx
+import { SettingGroup, SettingToggle } from '@12-apps/ui/layout/SettingCard';
+
+<SettingGroup
+  copy={switchCopy}
+  title="Notifications"
+  summary="What we tell you about, and when."
+  inactiveHint="Turn notifications on to choose which ones you get."
+  checked={settings.notifications}
+  onChange={(next) => api.setNotifications(next)}
+>
+  <SettingToggle variant="row" copy={switchCopy} title="Weekly digest" checked={settings.digest} onChange={api.setDigest} />
+  <SettingToggle variant="row" copy={switchCopy} title="Mentions" checked={settings.mentions} onChange={api.setMentions} />
+  <NumberField label="Quiet hours from" value={quietFrom} onChange={setQuietFrom} min={0} max={23} suffix="h" />
+</SettingGroup>
+```
+
+## Props
+
+| prop | type | default | effect |
+|---|---|---|---|
+| `copy` | `SettingSwitchCopy` | **required** | The main switch's "saving" announcement and fallback error. |
+| `title` | `string` | **required** | The subject. Names the main switch and the dependent rows' group. |
+| `checked` | `boolean` | **required** | The main switch's persisted value. |
+| `onChange` | `(checked: boolean) => void \| Promise<unknown>` | **required** | Persist the main switch — same async contract as [`SettingToggle`](./SettingToggle.md). |
+| `inactiveHint` | `string` | **required** | Why the rows are inactive. Shown only while they are. |
+| `children` | `ReactNode` | **required** | The dependent rows — `SettingToggle variant="row"`, fields, anything. |
+| `summary` | `ReactNode` | — | Explanation under the title. |
+| `disabled` | `boolean` | `false` | Disables the main switch; the rows are then inactive too. |
+| `formatError`, `icon`, `dataTestId`, `className`, `sx` | | | As on `SettingToggle`. Parts add `-dependents` and `-hint`. |
+
+## When the rows are active
+
+Only while the main switch is on **and saved**: turning it on lights the rows
+once the save lands (so nobody edits rows a failed save then disables), and
+turning it off dims them at once.
+
+## Accessibility
+
+- The dependent rows are a `role="group"` named by the subject.
+- Inactive, the group is `inert` — nothing in it is focusable or clickable,
+  whatever the host put there — and `aria-disabled`, described by the hint.
+- The family's own rows (`SettingToggle`) also render `disabled`, so they read
+  as disabled rather than merely unreachable.
+- Opacity alone never carries "inactive"; the hint says it in words.

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

@@ -0,0 +1,73 @@
+import Box from '@mui/material/Box/index.js';
+import { useTheme } from '@mui/material/styles/index.js';
+import { forwardRef, useId, useMemo } from 'react';
+
+import { Icon } from '../../../icons';
+
+import { useAsyncSwitch } from './SettingCard.hooks';
+import { partTestId } from './SettingCard.parts';
+import { dependentsStyles, hintStyles, surfaceStyles, withCallerSx } from './SettingCard.styles';
+import type { SettingGroupProps } from './SettingCard.types';
+import { SettingGroupContext } from './SettingGroup.context';
+import { SettingSwitchBlock, useSettingSwitchIds } from './SettingSwitch';
+
+/**
+ * ONE subject: a main switch, and the settings that only mean something while
+ * it is on, indented beneath it.
+ *
+ * With the main switch off the dependent rows stay where they are — dimmed,
+ * `inert`, and explained by `inactiveHint` — rather than disappearing. A
+ * reader deciding whether to turn a feature on is helped by seeing what it
+ * would let them configure, and a layout that jumps when a switch flips moves
+ * the thing they were about to press.
+ *
+ * The rows are active only while the main switch is on AND saved: turning it
+ * on lights them once the save lands; turning it off dims them at once.
+ *
+ * Several subjects are several cards, never one group — see `SettingGroup.md`.
+ */
+export const SettingGroup = forwardRef<HTMLElement, SettingGroupProps>(function SettingGroup(props, ref) {
+  const {
+    checked, onChange, copy, formatError, inactiveHint, children, disabled = false, dataTestId, className, sx,
+  } = props;
+  const theme = useTheme();
+  const ids = useSettingSwitchIds();
+  const hintId = `${useId()}-hint`;
+  const state = useAsyncSwitch({ checked, onChange, formatError, fallback: copy.saveFailed });
+  const active = checked && state.shown && !disabled;
+  const context = useMemo(() => ({ inactive: !active }), [active]);
+
+  return (
+    <Box
+      component="section"
+      ref={ref}
+      aria-labelledby={ids.titleId}
+      aria-busy={state.saving || undefined}
+      data-active={active}
+      data-testid={dataTestId}
+      className={className}
+      sx={withCallerSx((t) => surfaceStyles(t, false), sx)}
+    >
+      <SettingSwitchBlock {...props} disabled={disabled} ids={ids} state={state} />
+      {!active && (
+        <Box component="p" id={hintId} sx={hintStyles(theme)} data-testid={partTestId(dataTestId, 'hint')}>
+          <Icon name="InfoOutlined" size="xs" />
+          <span>{inactiveHint}</span>
+        </Box>
+      )}
+      <Box
+        role="group"
+        aria-labelledby={ids.titleId}
+        aria-describedby={active ? undefined : hintId}
+        aria-disabled={active ? undefined : true}
+        inert={!active}
+        sx={dependentsStyles(theme, active)}
+        data-testid={partTestId(dataTestId, 'dependents')}
+      >
+        <SettingGroupContext.Provider value={context}>{children}</SettingGroupContext.Provider>
+      </Box>
+    </Box>
+  );
+});
+
+SettingGroup.displayName = 'SettingGroup';