react-material-expressive 1.0.0

package/docs/components/Switch.md

@@ -0,0 +1,40 @@
+# Switch
+
+M3 switch: 52×32 track with 2dp outline, handle 16↔24 (28 while pressed),
+40px state layer. Optional handle icons (the handle stays 24 with a 16px
+icon). Controllable via `useControlled`.
+
+## Import
+
+```tsx
+import {Switch} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface SwitchProps extends Omit<
+  ComponentProps<"input">,
+  "type" | "size" | "children" | "checked" | "defaultChecked"
+> {
+  checked?: boolean; // controlled
+  className?: string; // wrapping <label>
+  defaultChecked?: boolean; // uncontrolled seed
+  icon?: ReactNode; // selected handle icon (16px)
+  label?: ReactNode;
+  uncheckedIcon?: ReactNode;
+}
+```
+
+## Examples
+
+```tsx
+<Switch defaultChecked label="Wi-Fi" />
+<Switch checked={on} onChange={(e) => setOn(e.target.checked)} label="Controlled" />
+<Switch icon={<MaterialSymbol name="check" size={16} />} label="With icon" />
+```
+
+## Gotchas
+
+- `role="switch"` is set on the input.
+- Disabled follows M3: track `on-surface/12`, handle 38%.

package/docs/components/Table.md

@@ -0,0 +1,67 @@
+# Table
+
+Data table with a horizontal-scroll wrapper, surface-container header and
+zebra rows. Fully data-agnostic — rows come from the consumer. Sub-parts:
+`Table.Head`, `Table.Body`, `Table.Row`, `Table.Cell`, `Table.HeaderCell`,
+`Table.TextContainer`.
+
+> **Note**: M3 publishes no data table component (it was retired after
+> M2), so this one is an in-house design over M3 foundations: official
+> color tokens, `title-small` headers, `body-medium` cells and zebra rows
+> on `surface-container/50` instead of dividers. Rows are non-interactive
+> by default, like Card.
+
+## Import
+
+```tsx
+import {Table} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface TableProps extends ComponentProps<"table"> {
+  wrapperClassName?: string; // scroll wrapper
+}
+// Head/Body/Row: native thead/tbody/tr props
+interface TableCellProps extends ComponentProps<"td"> {
+  data?: ReactNode;
+}
+interface TableHeaderCellProps extends ComponentProps<"th"> {
+  data?: ReactNode;
+}
+interface TextContainerProps {
+  children?;
+  className?;
+  data?;
+  width?: string;
+} // default w-[300px]
+```
+
+## Example
+
+```tsx
+<Table>
+  <Table.Head>
+    <Table.Row>
+      <Table.HeaderCell>Name</Table.HeaderCell>
+      <Table.HeaderCell>Role</Table.HeaderCell>
+    </Table.Row>
+  </Table.Head>
+  <Table.Body>
+    {rows.map((row) => (
+      <Table.Row key={row.id}>
+        <Table.Cell>{row.name}</Table.Cell>
+        <Table.Cell>
+          <Table.TextContainer>{row.longText}</Table.TextContainer>
+        </Table.Cell>
+      </Table.Row>
+    ))}
+  </Table.Body>
+</Table>
+```
+
+## Gotchas
+
+- Wrap long copy in `Table.TextContainer` to keep a readable measure.
+- Cells accept `data` as a children fallback (handy when mapping objects).

package/docs/components/Tabs.md

@@ -0,0 +1,67 @@
+# TabsPrimary / TabsSecondary
+
+M3 tabs with `title-small` labels and proper a11y roles. Primary: 48dp
+container (64 with 24px icons) and a 3px content-width indicator (inset 2dp
+each side, min length 24dp, fully-rounded top corners). Secondary: 48dp with
+inline 24px icons and a 2px full-width indicator. Active label/icon is
+`primary` (primary) / `on-surface` (secondary); inactive is
+`on-surface-variant` and darkens to `on-surface` on hover/focus. The
+indicator slides between tabs with the default-spatial spring (FLIP).
+Controllable; each tab may carry panel `content`.
+
+## Import
+
+```tsx
+import {TabsPrimary, TabsSecondary} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface TabItem {
+  content?: ReactNode; // panel rendered below when selected
+  disabled?: boolean;
+  header?: ReactNode;
+  icon?: ReactNode;
+  id: string;
+}
+
+interface TabsPrimaryProps {
+  className?: string;
+  defaultSelected?: string; // falls back to the first tab
+  onChange?: (id: string) => void;
+  panelClassName?: string;
+  selected?: string; // controlled
+  tabs: TabItem[];
+}
+// TabsSecondaryProps: identical
+```
+
+## Example
+
+```tsx
+<TabsPrimary
+  onChange={setSection}
+  tabs={[
+    {
+      content: <Flights />,
+      header: "Flights",
+      icon: <MaterialSymbol name="flight" />,
+      id: "f",
+    },
+    {
+      content: <Hotels />,
+      header: "Hotels",
+      icon: <MaterialSymbol name="hotel" />,
+      id: "h",
+    },
+  ]}
+/>
+```
+
+## Gotchas
+
+- Omit `content` to use the tabs as pure navigation and render panels
+  yourself (wire `onChange`).
+- Primary's indicator hugs the icon+label width per M3 (it sits inside the
+  content wrapper).

package/docs/components/TextElement.md

@@ -0,0 +1,37 @@
+# TextElement
+
+Label / title / body text stack on the M3 type scale: overline
+`label-medium` (on-surface-variant), title `title-medium` (on-surface),
+body `body-medium` (on-surface-variant).
+
+## Import
+
+```tsx
+import {TextElement} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface TextElementProps {
+  body?: ReactNode;
+  bodyStyle?: string; // class override
+  className?: string;
+  label?: ReactNode;
+  labelStyle?: string;
+  title?: ReactNode;
+  titleStyle?: string;
+}
+```
+
+## Examples
+
+```tsx
+<TextElement label="OVERLINE" title="Headline" body="Supporting copy" />
+<TextElement title="Bigger" titleStyle="text-headline-small" />
+```
+
+## Gotchas
+
+- Each slot renders only when provided; `*Style` props are class strings
+  merged with `cn`.

package/docs/components/TextField.md

@@ -0,0 +1,70 @@
+# Text fields — InputOutlined / InputFilled / TextFieldOutlined / TextFieldFilled
+
+M3 text fields: height 56, shape **extra-small** (4 — filled: top corners
+only), `body-large` input text, `on-surface-variant` placeholder, 24px
+leading/trailing icons (12dp from the edge, 16dp gap to the text → 52dp
+input padding on that side). The floating label is driven by **focus/value
+state** (not `:placeholder-shown`), so it always lands in the same place.
+`Input*` are single-line `<input>`; `TextField*` are `<textarea>`.
+
+## Import
+
+```tsx
+import {
+  InputFilled,
+  InputOutlined,
+  TextFieldFilled,
+  TextFieldOutlined,
+} from "react-material-expressive";
+```
+
+## API (shared shape)
+
+```ts
+interface InputOutlinedProps extends Omit<ComponentProps<"input">, "size"> {
+  className?: string; // wrapper
+  error?: boolean;
+  errorText?: ReactNode; // replaces supportingText while error
+  inputClassName?: string;
+  label?: string; // floating label
+  leftElement?: ReactNode; // 24px icon box
+  rightElement?: ReactNode;
+  supportingText?: ReactNode;
+}
+// InputFilled: same. TextField*: extends ComponentProps<"textarea"> (rows = 4).
+```
+
+Controlled (`value` + `onChange`) and uncontrolled (`defaultValue`) both
+work — the float state tracks either.
+
+## Anatomy notes
+
+- Outlined: the label notches the border via `fieldset/legend`, so it works
+  over any background (cards, sheets, colored sections).
+- Filled: surface-container-highest container, hover state layer and an
+  active indicator line (1px on-surface-variant → on-surface on hover →
+  2px primary on focus, error on error).
+- `placeholder` only shows while the label is floated (or when no label).
+- The float animation is a transform-only tween between two label copies
+  (the @material/web technique) — font-size never interpolates, so the
+  text doesn't re-rasterize mid-motion.
+
+## Example
+
+```tsx
+<InputOutlined
+    label="Email"
+    leftElement={<MaterialSymbol name="mail" />}
+    placeholder="you@example.com"
+    supportingText="We never share it"
+    type="email"
+/>
+<InputFilled error errorText="Taken" label="Username" defaultValue="grace" />
+<TextFieldOutlined label="Message" rows={5} />
+```
+
+## Gotchas
+
+- Pass `label` for the M3 look; with only `placeholder` they behave as
+  plain fields.
+- `disabled` follows M3 (38% content, 4% filled container).

package/docs/components/TimePicker.md

@@ -0,0 +1,83 @@
+# TimePicker
+
+M3 modal time picker built over the library's `Dialog`: a 256dp clock dial
+with a draggable selector, the big HH:MM time selector, an AM/PM period
+selector, and a keyboard-input toggle. Container surface-container-high,
+level 3, extra-large (28). Controllable and presentational.
+
+- **Dial** (default) — pick the hour on the clock (releasing advances to
+  minutes), then the minute. The selected field is `primary-container`; the
+  dial selector is `primary` (2dp track, 48dp handle, 8dp centre).
+- **Input** (`input`) — two editable fields (display-medium, focus
+  `primary-container` + 2dp primary outline) plus the AM/PM selector.
+
+Selection is drafted and committed on **OK**.
+
+## Import
+
+```tsx
+import {TimePicker, type TimeValue} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface TimeValue {
+  hours: number; // 0–23
+  minutes: number; // 0–59
+}
+
+interface TimePickerProps {
+  input?: boolean; // start in keyboard-input mode
+  isVisible: boolean;
+  labels?: TimePickerLabels; // every user-facing string (see below)
+  onClose: () => void;
+  onConfirm?: (value: TimeValue) => void; // OK
+  value?: TimeValue; // default { hours: 12, minutes: 0 }
+}
+
+// All text lives in `labels` — each key optional, English defaults shown.
+interface TimePickerLabels {
+  supporting?: ReactNode; // "Select time"
+  cancel?: ReactNode; // "Cancel"
+  confirm?: ReactNode; // "OK"
+  am?: string; // "AM"
+  pm?: string; // "PM"
+  switchToDial?: string; // aria (input→dial toggle)
+  switchToInput?: string; // aria (dial→input toggle)
+  hour?: string; // aria "Hour"
+  minute?: string; // aria "Minute"
+}
+```
+
+## Example
+
+```tsx
+const [open, setOpen] = useState(false);
+const [time, setTime] = useState<TimeValue>({hours: 10, minutes: 30});
+
+<Button onClick={() => setOpen(true)}>Pick a time</Button>
+<TimePicker
+    isVisible={open}
+    onClose={() => setOpen(false)}
+    onConfirm={setTime}
+    value={time}
+/>;
+```
+
+## Gotchas
+
+- `value.hours` is 24-hour (0–23); the dial/fields display 12-hour with the
+  AM/PM selector, which rewrites `hours` by ±12.
+- The dial is pointer-driven (tap or drag a number). The keyboard-input
+  mode is the accessible path for exact entry.
+- Every user-facing string (visible text **and** aria-labels) is in
+  `labels`, e.g. `labels={{cancel: "Cancelar", am: "a.m.", pm: "p.m."}}`;
+  unset keys keep the English defaults.
+
+## Accepted gaps (criterion)
+
+- 12-hour with AM/PM only; the 24-hour dial (inner ring) is not
+  implemented.
+- The dial selection is pointer-only; there is no arrow-key rotation of the
+  hand (use input mode for keyboard).

package/docs/components/ToggleTheme.md

@@ -0,0 +1,71 @@
+# ToggleTheme / ToggleThemeMenu
+
+Prebuilt theme controls. `ToggleTheme` flips
+light↔dark; `ToggleThemeMenu` opens an OverflowMenu listing the built-in
+themes (light/dark) or a custom set, marking the active one.
+
+## Import
+
+```tsx
+import {ToggleTheme, ToggleThemeMenu} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface ToggleThemeProps {
+  className?: string;
+  darkIcon?: ReactNode; // shown while light (click → dark)
+  label?: boolean; // show the current theme name
+  labels?: ToggleThemeLabels; // accessible names
+  lightIcon?: ReactNode; // shown while dark (click → light)
+  variant?: IconButtonVariant; // default "tonal"
+}
+
+interface ToggleThemeLabels {
+  toLight?: string; // aria-label while dark (default "Switch to light theme")
+  toDark?: string; // aria-label while light (default "Switch to dark theme")
+  name?: string; // visible suffix when `label` is shown (default "theme")
+}
+
+interface ToggleThemeMenuProps {
+  className?: string;
+  icon?: ReactNode; // trigger icon (default palette)
+  label?: boolean;
+  labels?: ToggleThemeMenuLabels; // accessible names
+  themes?: {id: "light" | "dark"; label: string}[];
+  variant?: IconButtonVariant;
+}
+
+interface ToggleThemeMenuLabels {
+  trigger?: string; // trigger aria-label (default "Choose theme")
+  name?: string; // visible suffix when `label` is shown (default "theme")
+}
+```
+
+## Example
+
+```tsx
+<ToggleTheme label />
+<ToggleThemeMenu themes={[{id: "light", label: "Claro"}, {id: "dark", label: "Oscuro"}]} />
+```
+
+## Gotchas
+
+- They mutate `data-theme`/`.dark` on `<html>` and persist to
+  `localStorage("md-theme")`.
+- Default icons are inline SVGs; pass your own for brand consistency.
+- **Not an M3 component.** Theme switching has no Material 3 spec — these are
+  app-level helpers. `ToggleTheme` is an [IconButton](IconButton.md) (default
+  `tonal`) whose icon/`aria-label` swap with the resolved theme;
+  `ToggleThemeMenu` is an [OverflowMenu](OverflowMenu.md) over the shared M3E
+  [vertical Menu](Menu.md). All M3 fidelity (sizing, shape morph, state
+  layers, menu visuals) is inherited from those components.
+- `ToggleThemeMenu` marks the active theme **visually only** (the item turns
+  `tertiary-container`, no checkmark) — same convention as `Menu.Item`
+  `selected`; there is no `aria-checked`/`aria-current`. Pass a custom
+  `themes` list when shipping custom token sets (`id` must match the theme
+  you set via tokens).
+- The theme **names** ("Light"/"Dark") are translated through the existing
+  `themes` prop (an `{id, label}` list), not through `labels` — `labels` only
+  covers the trigger aria-label and the visible "theme" suffix.

package/docs/components/Toolbar.md

@@ -0,0 +1,102 @@
+# DockedToolbar and FloatingToolbar
+
+M3 Expressive toolbars (`md.comp.toolbar` tokens, DSDB v34): frequently
+used actions for the current page. Two variants:
+
+- **DockedToolbar** — spans the full window width, 64dp high, square
+  corners, `surface-container`, 16dp edge paddings and a 32dp default gap
+  (the spec's max-spacing; min is 4). Bottom of the window only; successor
+  of the baseline bottom app bar. FABs placed inside sit flat.
+- **FloatingToolbar** — a 64dp pill (8dp paddings, 4dp gap, shape full,
+  elevation level 3) floating above the content with a minimum 16dp screen
+  margin (24dp when vertical). Can pair with a FAB (8dp gap) and collapse
+  on scroll.
+
+Both support the **standard** (`surface-container`, low emphasis) and
+**vibrant** (`primary-container`, high emphasis) color schemes. Ghost
+buttons inside (`IconButton variant="standard"`, `Button variant="text"`)
+follow the toolbar token sets automatically: selected (`aria-pressed`,
+e.g. the IconButton `selected` toggle) becomes `secondary-container` /
+`on-secondary-container` in standard and `surface-container` /
+`on-surface` in vibrant. Unselected content is `on-surface-variant` in
+standard and `on-primary-container` in vibrant (so a text button drops its
+default `primary` to match the toolbar). Filled/tonal buttons keep their
+own colors for single-action emphasis.
+
+## Import
+
+```tsx
+import {DockedToolbar, FloatingToolbar} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface DockedToolbarProps extends ComponentProps<"div"> {
+  vibrant?: boolean; // primary-container scheme
+}
+
+interface FloatingToolbarProps extends ComponentProps<"div"> {
+  expanded?: boolean; // default true; false plays the collapse
+  fab?: ReactNode; // adjacent <FAB>, 8dp away (level 2, hover 3)
+  fabPosition?: "start" | "end"; // FAB side (default end)
+  flat?: boolean; // remove the level-3 elevation
+  leading?: ReactNode; // collapses away when expanded={false}
+  trailing?: ReactNode; // collapses away when expanded={false}
+  vertical?: boolean; // 64dp-wide column
+  vibrant?: boolean; // primary-container scheme
+}
+```
+
+## Examples
+
+```tsx
+// Docked: global actions pinned to the bottom of the window.
+<DockedToolbar className="fixed bottom-0">
+    <IconButton aria-label="Undo" variant="standard">…</IconButton>
+    <IconButton aria-label="Redo" variant="standard">…</IconButton>
+    <IconButton aria-label="Attach" variant="standard">…</IconButton>
+</DockedToolbar>
+
+// Floating with FAB: collapse on scroll — the pill clips toward the FAB,
+// which grows to the 80dp medium size (fast-spatial spring).
+<FloatingToolbar
+    className="fixed bottom-4 left-1/2 -translate-x-1/2"
+    expanded={!scrolledDown}
+    fab={
+        <FAB aria-label="Add" variant="secondary">
+            <MaterialSymbol name="add" />
+        </FAB>
+    }>
+    <IconButton aria-label="Bold" selected={bold} variant="standard">…</IconButton>
+    <IconButton aria-label="Italic" selected={italic} variant="standard">…</IconButton>
+</FloatingToolbar>
+```
+
+## Motion
+
+Expand/collapse ports the Compose fast-spatial spring (damping 0.6 /
+stiffness 800) as a 350ms CSS `linear()` curve with a 9.5% overshoot
+(`--md-sys-motion-spring-fast-spatial`). With a FAB the whole pill
+clip-reveals toward the FAB side while the FAB lerps 56 → 80dp (icon
+24 → 28); without one, only the `leading`/`trailing` slots collapse
+(1fr → 0fr grid morph), keeping the core children. Collapsed regions are
+`inert`, so they drop out of focus order and the accessibility tree.
+
+## Gotchas
+
+- Position the toolbar yourself (`fixed` wrapper): docked bars belong to
+  the window bottom; floating toolbars keep ≥16dp margins (≥24dp when
+  vertical) and must stay fully on screen.
+- `expanded` is plain-controlled (no internal toggle) — drive it from your
+  scroll handler; the spec recommends collapsing on scroll-down and
+  expanding on scroll-up (Compose uses a 40dp threshold).
+- Don't show a docked toolbar together with a navigation bar, and don't
+  use wide icon buttons in vertical floating toolbars (spec guidelines).
+- The FAB slot expects a default 56dp `<FAB>`; the toolbar overrides its
+  elevation (level 2, hover 3 — not the standalone 3 → 4) and animates its
+  size, so don't pass `size`.
+- Per spec the FAB pairs as `secondary` in standard toolbars and
+  `tertiary` in vibrant ones (`md.comp.toolbar.floating.fab` tokens).
+- Square icon buttons are fine in docked toolbars but discouraged inside
+  floating ones (shape clash with the fully-round container).

package/docs/components/Tooltip.md

@@ -0,0 +1,63 @@
+# Tooltip
+
+M3 tooltips shown on hover/focus of the wrapped trigger, animating in with
+a fade + scale (0.8→1) on the fast-spatial spring. Plain: shape extra-small
+on inverse-surface with `body-small` text. Rich: shape medium on
+surface-container (elevation 2, max 320dp wide) with optional `title-small`
+subhead and an action slot.
+
+## Import
+
+```tsx
+import {Tooltip} from "react-material-expressive";
+```
+
+## API
+
+```ts
+interface TooltipProps {
+  action?: ReactNode; // rich only (e.g. <Button variant="text">)
+  bottomLeft?: boolean;
+  bottomRight?: boolean;
+  topLeft?: boolean;
+  topRight?: boolean; // default bottomLeft
+  children?: ReactNode; // trigger
+  className?: string;
+  text?: ReactNode;
+  title?: ReactNode; // rich subhead
+  variant?: "plain" | "rich"; // default "plain"
+}
+```
+
+## Examples
+
+```tsx
+<Tooltip text="Save to favorites" topLeft>
+    <IconButton aria-label="Favorite" icon={<MaterialSymbol name="favorite" />} variant="standard" />
+</Tooltip>
+
+<Tooltip variant="rich" title="Rich tooltip" text="Longer supporting copy"
+         action={<Button variant="text">Learn more</Button>} bottomRight>
+    <IconButton aria-label="Info" icon={<MaterialSymbol name="info" />} variant="standard" />
+</Tooltip>
+```
+
+## Gotchas
+
+- Display is pure CSS (hover/focus-within) with a 150ms appearance delay,
+  animating fade + scale 0.8→1 from center on the fast-spatial spring (the
+  same FadeInFadeOutWithScale choreography as the Snackbar); hide is
+  immediate. Hover is gated under `@media (hover: hover)` so a touch tap
+  doesn't leave it stuck open. Rich tooltips become interactive
+  (`pointer-events`) while shown so the action is clickable.
+- Keep the trigger inside the wrapper — the tooltip positions against it.
+
+## Accessibility
+
+- The tooltip container is `role="tooltip"` with a generated `id`. When the
+  trigger is a single element, the library merges that id into the trigger's
+  `aria-describedby`, so the supporting text is announced when the trigger is
+  focused (the WAI-ARIA tooltip pattern). Any `aria-describedby` you already
+  set on the trigger is preserved.
+- Give the trigger its own accessible name (e.g. `aria-label` on an icon-only
+  `IconButton`) — the tooltip describes the control, it does not name it.

package/docs/components/TopAppBar.md

@@ -0,0 +1,84 @@
+# TopAppBar
+
+M3 top app bar container with the variants as sub-parts:
+`TopAppBar.Small` / `.Center` (64dp, `title-large`), `.Medium` and
+`.Large`. The container is `surface` (swap to `surface-container` on
+scroll); bar padding is 4dp. Every variant takes an optional `subtitle`
+(rendered under the title).
+
+`.Medium` and `.Large` render the **M3 Expressive flexible** variants:
+Medium is `headline-medium` (112dp, 136dp with a subtitle), Large is
+`display-small` (120dp, 152dp with a subtitle). `.Center` is the small bar
+with centered title text (M3E merged center-aligned into small).
+
+> **M3 Expressive note** — flexible is the only Medium/Large variant. The
+> baseline Medium/Large bars were removed because M3E marks them "no longer
+> recommended".
+
+## Import
+
+```tsx
+import {TopAppBar} from "react-material-expressive";
+```
+
+## API
+
+```ts
+type TopAppBarProps = ComponentProps<"header">; // bg-surface by default
+
+// Small / Center
+interface AppBarRowProps {
+  children?: ReactNode; // title fallback
+  className?: string;
+  leftElement?: ReactNode; // nav icon
+  rightElement?: ReactNode; // action icons
+  subtitle?: ReactNode; // label-medium, under the title
+  title?: ReactNode;
+}
+
+// Medium / Large (flexible only)
+interface CollapsingAppBarProps {
+  children?: ReactNode; // title fallback
+  className?: string;
+  leftElement?: ReactNode; // nav icon
+  rightElement?: ReactNode; // action icons
+  subtitle?: ReactNode; // medium label-large / large title-medium
+  title?: ReactNode;
+}
+```
+
+## Example
+
+```tsx
+<TopAppBar>
+  <TopAppBar.Small
+    leftElement={
+      <IconButton
+        aria-label="Menu"
+        icon={<MaterialSymbol name="menu" />}
+        variant="standard"
+      />
+    }
+    rightElement={
+      <IconButton
+        aria-label="More"
+        icon={<MaterialSymbol name="more_vert" />}
+        variant="standard"
+      />
+    }
+    title="Page title"
+  />
+</TopAppBar>
+```
+
+## Gotchas
+
+- On-scroll surface change is the consumer's call: toggle
+  `className="bg-surface-container shadow-mm-2"` when `scrollY > 0` (the M3
+  on-scroll color + elevation level 2). The collapse-on-scroll motion
+  (height shrink + title resize) is not built in.
+- `Center` keeps the title optically centered by reserving symmetric side
+  slots — pass compact elements (icon buttons / avatar).
+- Leading/trailing icon colors come from the `IconButton`s you pass; M3's
+  leading-`on-surface` / trailing-`on-surface-variant` split is yours to
+  set if you need it.