@12-apps/ui 6.40.0 → 6.41.0

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 '../../../tokens/relative';
+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.styles.ts

@@ -0,0 +1,142 @@
+import type { CSSObject, SxProps, Theme } from '@mui/material/styles/index.js';
+
+import { rem } from '../../../tokens/relative';
+import { CARD_BORDER_WIDTH, CARD_RADIUS_UNITS } from '../Card/Card.metrics';
+
+import { SETTING_CARD, SETTING_GROUP_INACTIVE_OPACITY } from './SettingCard.metrics';
+
+/**
+ * The attribute an open `SettingCard` carries, which `SettingGrid` reads to
+ * give it the whole row. An attribute rather than a class so a host's wrapper
+ * around the card can be matched with `:has()` as well.
+ */
+export const SETTING_CARD_OPEN_ATTR = 'data-setting-card-open';
+
+/** `sx` as MUI documents it for composition: the component's own first, the caller's after. */
+export const withCallerSx = (
+  own: SxProps<Theme>,
+  sx: SxProps<Theme> | undefined,
+): SxProps<Theme> => [own, ...(Array.isArray(sx) ? sx : [sx])] as SxProps<Theme>;
+
+/**
+ * The card surface — `Card`'s outlined hairline and medium radius, so a
+ * settings screen and a content screen are drawn with one kit.
+ *
+ * `height: 100%` is what turns the grid's per-row stretch into equal-height
+ * cards: a grid item stretches, but a card that sized itself to its content
+ * would not fill the item it sits in.
+ *
+ * `gridColumn: 1 / -1` while open is the full-row span. It lives on the card,
+ * not only in the grid's CSS, so it also holds when the card sits in a host's
+ * own grid. Outside a grid the property does nothing.
+ */
+export const surfaceStyles = (theme: Theme, open: boolean): CSSObject => ({
+  boxSizing: 'border-box',
+  height: '100%',
+  minWidth: 0,
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.spacing(1.5),
+  padding: theme.spacing(2.5),
+  backgroundColor: theme.palette.background.paper,
+  border: `${CARD_BORDER_WIDTH}px solid ${open ? theme.palette.primary.main : theme.palette.divider}`,
+  borderRadius: theme.spacing(CARD_RADIUS_UNITS.lg),
+  boxShadow: open ? theme.shadows[4] : 'none',
+  transition: theme.transitions.create(['border-color', 'box-shadow'], {
+    duration: theme.transitions.duration.short,
+  }),
+  ...(open ? { gridColumn: '1 / -1' } : {}),
+});
+
+/** A `row` toggle: the card's content with none of its surface. */
+export const flatStyles = (theme: Theme): CSSObject => ({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.spacing(0.5),
+  padding: theme.spacing(1.25, 0),
+  minWidth: 0,
+});
+
+export const headerStyles = (theme: Theme): CSSObject => ({
+  display: 'flex',
+  alignItems: 'center',
+  gap: rem(theme, SETTING_CARD.iconGap),
+  minWidth: 0,
+});
+
+/**
+ * The title names its colour rather than inheriting it: a card rendered under
+ * a theme other than the page's (a dark panel on a light page) would otherwise
+ * take the page's text colour onto its own surface.
+ */
+export const titleStyles = (theme: Theme): CSSObject => ({
+  ...theme.typography.subtitle1,
+  fontWeight: theme.typography.fontWeightMedium,
+  color: theme.palette.text.primary,
+  margin: 0,
+  minWidth: 0,
+  overflowWrap: 'anywhere',
+});
+
+/** The one line a closed card shows. Long values end in an ellipsis, not a second line. */
+export const summaryStyles = (theme: Theme): CSSObject => ({
+  ...theme.typography.body2,
+  color: theme.palette.text.secondary,
+  margin: 0,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+});
+
+/** A switch card's explanation, which may wrap: it is read, not scanned. */
+export const descriptionStyles = (theme: Theme): CSSObject => ({
+  ...theme.typography.body2,
+  color: theme.palette.text.secondary,
+  margin: 0,
+});
+
+/** The inactive group's hint: a glyph and the sentence, so it does not read as a second summary. */
+export const hintStyles = (theme: Theme): CSSObject => ({
+  ...descriptionStyles(theme),
+  display: 'flex',
+  alignItems: 'flex-start',
+  gap: theme.spacing(1),
+  // Centre the 16px glyph on the first 20px line; later lines wrap under the text.
+  '& > svg': { flexShrink: 0, marginTop: rem(theme, 2) },
+});
+
+export const errorStyles = (theme: Theme): CSSObject => ({
+  ...theme.typography.body2,
+  color: theme.palette.error.main,
+  margin: 0,
+});
+
+export const actionsStyles = (theme: Theme): CSSObject => ({
+  display: 'flex',
+  flexWrap: 'wrap',
+  justifyContent: 'flex-end',
+  gap: theme.spacing(1),
+  marginTop: 'auto',
+});
+
+export const iconStyles = (theme: Theme): CSSObject => ({
+  display: 'inline-flex',
+  flexShrink: 0,
+  color: theme.palette.text.secondary,
+});
+
+/**
+ * A group's dependent rows: indented under the main switch, with a rule down
+ * their left edge so the "belongs to" reads without words. While the main
+ * switch is off they fade — and `inert` (set by the component) is what makes
+ * them unreachable; opacity alone would only make them look it.
+ */
+export const dependentsStyles = (theme: Theme, active: boolean): CSSObject => ({
+  display: 'flex',
+  flexDirection: 'column',
+  marginLeft: rem(theme, SETTING_CARD.groupIndent / 2),
+  paddingLeft: rem(theme, SETTING_CARD.groupIndent / 2),
+  borderLeft: `${rem(theme, SETTING_CARD.groupRuleWidth)} solid ${theme.palette.divider}`,
+  opacity: active ? 1 : SETTING_GROUP_INACTIVE_OPACITY,
+  transition: theme.transitions.create('opacity', { duration: theme.transitions.duration.short }),
+});

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>;
+}