@12-apps/ui 6.21.0 → 6.23.0

package/src/components/data-display/FleetMap/FleetMap.types.ts

@@ -0,0 +1,148 @@
+import type { MapPreviewCopy } from '../../../copy';
+
+/**
+ * One tracked unit's newest position, as the caller resolved it.
+ *
+ * Deliberately says nothing about WHAT is being tracked. A courier, a service
+ * van, a field engineer — the component draws a labelled dot with a freshness,
+ * and every word that names the domain arrives through {@link FleetMapCopy}.
+ */
+export interface FleetUnit {
+  id: string;
+  /** The name a human reads, on the pin and in the roster. */
+  label: string;
+  latitude: number;
+  longitude: number;
+  /**
+   * The fix's accuracy radius in metres, when the platform reported one.
+   *
+   * Kept because it is what separates a rooftop GPS fix from a cell-tower guess
+   * three blocks wide, and a map that draws both identically tells its reader
+   * something false.
+   */
+  accuracyM?: number | null;
+  /**
+   * Seconds since the fix was ACCEPTED, on the server's clock.
+   *
+   * The caller computes it, and the distinction matters: a device whose own
+   * clock is an hour slow would otherwise report itself as an hour stale while
+   * reporting perfectly.
+   */
+  staleSeconds: number;
+  /** A short pre-formatted badge beside the name, e.g. `"2 entregas"`. */
+  badge?: string;
+}
+
+/** How current a unit's newest fix is, derived from the thresholds below. */
+export type FleetFreshness = 'live' | 'lagging' | 'stale';
+
+/**
+ * Every word the board prints, and the two it FORMATS.
+ *
+ * `lastSeen` and `accuracy` are functions rather than strings because a
+ * duration and a distance are locale rules, and this package holds the same
+ * line `StatCard` does: presentation only, the caller owns the formatting. A
+ * `lastSeenMinutes: string` template would have made "há 2 min" the only
+ * shape any consumer could ever render.
+ */
+export interface FleetMapCopy {
+  /** The panel's heading. */
+  title: string;
+  /** What the roster says when nobody is reporting. */
+  emptyTitle: string;
+  emptyDescription?: string;
+  /** The roster list's accessible name — it is the map's readable half. */
+  rosterLabel: string;
+  /**
+   * What a screen reader hears while the roster reloads, e.g. "Atualizando a
+   * frota". OPTIONAL, and silence is the honest default: `aria-busy` marks the
+   * region stale without uttering anything, the skeletons are `aria-hidden`,
+   * and this component cannot invent the sentence in the reader's language.
+   * Set it and the panel announces politely; leave it and it stays quiet.
+   *
+   * Announced on a TRANSITION into loading. A board mounted already loading is
+   * silent — as any live region is at mount, since there is no change for a
+   * reader to observe.
+   */
+  loading?: string;
+  /**
+   * The map region's accessible name.
+   *
+   * The map is NOT `aria-hidden`, and that is deliberate rather than an
+   * oversight: it carries focusable controls (zoom, centre, map type), and
+   * `aria-hidden` over a focusable subtree is the `aria-hidden-focus`
+   * violation — a keyboard user tabs into a region a screen reader insists is
+   * not there. So it is a NAMED region a reader can skip past instead, and the
+   * roster beside it carries every fact a pin does.
+   *
+   * Skipping it does not silence it: `MapPreview` carries its own
+   * `aria-live="polite"` and announces its centre in English on every
+   * re-centre. See `FleetCanvas` for why that is stated rather than fixed here.
+   */
+  mapLabel: string;
+  /** The three freshness words, as a reader sees them on a row. */
+  freshness: Record<FleetFreshness, string>;
+  /** `(seconds) => "há 2 min"`. */
+  lastSeen: (staleSeconds: number) => string;
+  /** `(metres) => "±12 m"`. A unit with no accuracy renders none. */
+  accuracy: (metres: number) => string;
+  /** The map control bar's own six names. */
+  map: MapPreviewCopy;
+}
+
+/** Props for the {@link FleetMap} live board. */
+export interface FleetMapProps {
+  /** Everyone currently reporting. An empty array renders the empty state. */
+  units: readonly FleetUnit[];
+  copy: FleetMapCopy;
+  /**
+   * Which unit is highlighted: the map centres on it and the roster marks it
+   * selected. `null` selects nobody and centres on the whole fleet.
+   *
+   * PASSING IT AT ALL IS THE DECISION. Present on the first render — `null`
+   * included — and the board is controlled for life: it renders what you pass
+   * and never moves the selection itself. Absent on the first render and it
+   * keeps its own, reporting each change through {@link onSelect}. The mode is
+   * latched on that first render, the way React latches an `<input>`, so the
+   * component cannot change its own semantics halfway through a session.
+   *
+   * A controlled board reads `undefined` as "nobody is selected", so
+   * `useState<string>()` in the caller behaves: clearing it clears the roster.
+   */
+  selectedId?: string | null;
+  /**
+   * A click on a row or a pin, and each arrow-key move. Fires in both modes, so
+   * an uncontrolled board can still be observed.
+   *
+   * Passing {@link selectedId} WITHOUT this is a selection nothing can move:
+   * the arrow keys then decline to act and leave the page to scroll, rather
+   * than swallowing a keypress that would do nothing.
+   */
+  onSelect?: (id: string) => void;
+  /**
+   * Seconds after which a unit stops reading as `live`, and then as `lagging`.
+   *
+   * Both carry a GENERIC default (90s and 300s, sized for a phone reporting
+   * every twenty seconds) and no domain one, because the answer is entirely a
+   * property of the fleet's own ping cadence: a phone reporting every twenty
+   * seconds is late at ninety, and a tracker reporting every five minutes is
+   * not. A component that picked one would be picking it for every consumer.
+   */
+  laggingAfterSeconds?: number;
+  staleAfterSeconds?: number;
+  /** Map height, any CSS length. */
+  height?: string;
+  /**
+   * While true the map and roster are marked `aria-busy`, and the roster renders
+   * skeletons IF no units have landed yet — a poll over a populated roster keeps
+   * the list, because unmounting it throws away the focus inside it.
+   *
+   * It only ANNOUNCES if {@link FleetMapCopy.loading} is set — `aria-busy` is a
+   * state, not an utterance. The panel root is deliberately not the busy
+   * element, so that announcement sits outside the busy subtree.
+   */
+  loading?: boolean;
+  className?: string;
+  /** Test id for the panel root; every child id is derived from it. */
+  dataTestId?: string;
+}

package/src/components/data-display/FleetMap/FleetRoster.tsx

@@ -0,0 +1,321 @@
+import Box from '@mui/material/Box/index.js';
+import Stack from '@mui/material/Stack/index.js';
+import Typography from '@mui/material/Typography/index.js';
+import { useTheme, type SxProps, type Theme } from '@mui/material/styles/index.js';
+import React from 'react';
+
+import { Skeleton } from '../../layout/Skeleton/Skeleton';
+
+import { freshnessOf } from './FleetMap.helpers';
+import type { FleetFreshness, FleetMapCopy, FleetUnit } from './FleetMap.types';
+
+/**
+ * The roster beside the map — and the ACCESSIBLE half of this component.
+ *
+ * A map is a picture of positions and a screen reader cannot read a picture, so
+ * the panel's information is carried by this list. That is not a consolation
+ * prize: the list answers the questions a dispatcher actually asks — who is
+ * reporting, how recently, and what are they carrying — and it answers them in
+ * an order the map cannot express.
+ *
+ * The map beside it is a NAMED LANDMARK rather than an `aria-hidden` one, so a
+ * reader can skip it in one gesture — see `FleetCanvas`, which carries the
+ * reason it must not be hidden.
+ */
+
+/** Each freshness draws from the semantic palette, never a hardcoded hex. */
+function freshnessColor(freshness: FleetFreshness, theme: Theme): string {
+  if (freshness === 'live') return theme.palette.success.main;
+  if (freshness === 'lagging') return theme.palette.warning.main;
+  return theme.palette.text.disabled;
+}
+
+/**
+ * A row's two lines of text — the name, and the one-line summary under it.
+ *
+ * Split out of `FleetRow` to keep that function under the size gate, and the
+ * seam is the natural one: everything here is READ, nothing is interactive.
+ */
+function RowText({
+  unit,
+  copy,
+  freshness,
+  testId,
+}: Pick<RowProps, 'unit' | 'copy' | 'freshness' | 'testId'>): React.JSX.Element {
+  const theme = useTheme();
+
+  // Dropped rather than rendered empty: a phone that reports no accuracy radius
+  // would otherwise print a trailing separator with nothing after it.
+  const meta = [
+    copy.freshness[freshness],
+    copy.lastSeen(unit.staleSeconds),
+    unit.accuracyM == null ? null : copy.accuracy(unit.accuracyM),
+  ]
+    .filter((part): part is string => Boolean(part))
+    .join(' · ');
+
+  return (
+    <Stack sx={{ minWidth: 0, flexGrow: 1 }}>
+      <Typography
+        variant="body2"
+        component="p"
+        data-testid={`${testId}-label`}
+        sx={{ fontWeight: theme.typography.fontWeightMedium, overflowWrap: 'anywhere' }}
+      >
+        {unit.label}
+      </Typography>
+      <Typography
+        variant="caption"
+        component="p"
+        data-testid={`${testId}-meta`}
+        sx={{ color: theme.palette.text.secondary }}
+      >
+        {meta}
+      </Typography>
+    </Stack>
+  );
+}
+
+/**
+ * Keep the selected row visible INSIDE the roster.
+ *
+ * The roster caps its own height, so a dispatcher arrowing through a fleet of
+ * thirty otherwise walks the selection below the fold with nothing moving —
+ * `aria-activedescendant` follows, and a SIGHTED keyboard user sees no feedback
+ * at all.
+ *
+ * Watches the row's POSITION as well as its selectedness, because the roster
+ * re-sorts on every poll: a rider who stays selected while their staleness
+ * moves them down the list would otherwise slide out of view with the effect
+ * never re-running.
+ *
+ * Arithmetic rather than `scrollIntoView({ block: 'nearest' })` because that
+ * walks every scrollable ancestor, the document included, and `nearest` only
+ * spares an ancestor the row is already visible in — which is exactly false
+ * when the panel is off screen. Re-running on every re-sort, it would yank the
+ * whole page back to the map on a timer, and drag it there on mount for any
+ * board rendered below the fold with a selection already set.
+ */
+function useKeptInView(
+  selected: boolean,
+  position: number,
+): React.RefObject<HTMLDivElement | null> {
+  const row = React.useRef<HTMLDivElement>(null);
+
+  React.useEffect(() => {
+    const box = row.current;
+    const list = box?.parentElement;
+    if (!selected || !box || !list) return;
+    const top = box.offsetTop - list.offsetTop;
+    if (top < list.scrollTop) {
+      list.scrollTop = top;
+    } else if (top + box.offsetHeight > list.scrollTop + list.clientHeight) {
+      list.scrollTop = top + box.offsetHeight - list.clientHeight;
+    }
+  }, [selected, position]);
+
+  return row;
+}
+
+/**
+ * A row's own box, selected or not.
+ *
+ * Out of line because the hover rule needs the explanation more than the JSX
+ * has room for: hover must never WEAKEN the selection. Written flat as
+ * `'&:hover': { backgroundColor: action.hover }`, the pseudo-class wins on
+ * specificity and repaints the selected row with the hover tint — measured at
+ * `rgba(0,0,0,0.08)` idle against `rgba(0,0,0,0.04)` hovered, so pointing at
+ * the selected row visually DESELECTED it and made it indistinguishable from
+ * any other row under the cursor.
+ */
+function rowSx(theme: Theme, selected: boolean): SxProps<Theme> {
+  const resting = selected ? theme.palette.action.selected : 'transparent';
+  return {
+    display: 'flex',
+    alignItems: 'center',
+    gap: theme.spacing(1.5),
+    padding: theme.spacing(1, 1.5),
+    // `1`, not `theme.shape.borderRadius / 4`. MUI's `sx` reads a NUMBER here as
+    // a multiple of `theme.shape.borderRadius`, so dividing the theme value out
+    // and letting `sx` multiply it back in is quadratic: measured 4px on the
+    // default theme — which is why this looked right — and 36px on a host that
+    // sets its own radius to 12. In a package whose whole premise is being
+    // re-themed, only the multiple is portable.
+    borderRadius: 1,
+    cursor: 'pointer',
+    backgroundColor: resting,
+    '&:hover': {
+      backgroundColor: selected ? theme.palette.action.selected : theme.palette.action.hover,
+    },
+  };
+}
+
+interface RowProps {
+  unit: FleetUnit;
+  copy: FleetMapCopy;
+  freshness: FleetFreshness;
+  selected: boolean;
+  onSelect: (id: string) => void;
+  /** The row's DOM id, which `aria-activedescendant` points at. */
+  optionId: string;
+  /** Where the row sits in the re-sorted roster — see the scroll effect. */
+  position: number;
+  testId: string;
+}
+
+function FleetRow({
+  unit,
+  copy,
+  freshness,
+  selected,
+  onSelect,
+  optionId,
+  position,
+  testId,
+}: RowProps): React.JSX.Element {
+  const theme = useTheme();
+  const color = freshnessColor(freshness, theme);
+  const row = useKeptInView(selected, position);
+
+  return (
+    <Box
+      ref={row}
+      role="option"
+      aria-selected={selected}
+      id={optionId}
+      data-testid={testId}
+      data-freshness={freshness}
+      onClick={() => onSelect(unit.id)}
+      sx={rowSx(theme, selected)}
+    >
+      {/* The dot repeats what the freshness word beside it already says, so it
+          is hidden rather than read twice — and colour is never the only
+          carrier of the state. */}
+      <Box
+        aria-hidden="true"
+        data-testid={`${testId}-dot`}
+        sx={{
+          width: 10,
+          height: 10,
+          borderRadius: '50%',
+          flexShrink: 0,
+          backgroundColor: color,
+        }}
+      />
+      <RowText unit={unit} copy={copy} freshness={freshness} testId={testId} />
+      {unit.badge && (
+        <Typography
+          variant="caption"
+          component="span"
+          data-testid={`${testId}-badge`}
+          sx={{ color: theme.palette.text.secondary, flexShrink: 0 }}
+        >
+          {unit.badge}
+        </Typography>
+      )}
+    </Box>
+  );
+}
+
+/**
+ * What stands in for the roster before any unit has landed.
+ *
+ * `aria-hidden`, because three grey bars are not information — the panel's
+ * `aria-busy` and its optional announcement carry that. The radius is the same
+ * MULTIPLE a real row uses rather than a raw pixel count: `Skeleton` forwards
+ * the number into `sx`, where it scales with `theme.shape.borderRadius`, so a
+ * literal `4` drew 16px against the rows' 4px on the default theme and 48px
+ * against 12px on a re-themed host.
+ */
+function FirstLoad({ testId }: { testId: string }): React.JSX.Element {
+  return (
+    <Stack spacing={1} data-testid={`${testId}-skeleton`} aria-hidden="true">
+      {[0, 1, 2].map((row) => (
+        <Skeleton key={row} variant="rectangular" height={44} borderRadius={1} />
+      ))}
+    </Stack>
+  );
+}
+
+export interface FleetRosterProps {
+  units: readonly FleetUnit[];
+  copy: FleetMapCopy;
+  selectedId: string | null | undefined;
+  onSelect: (id: string) => void;
+  laggingAfterSeconds: number;
+  staleAfterSeconds: number;
+  loading: boolean;
+  testId: string;
+  onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void;
+}
+
+export function FleetRoster({
+  units,
+  copy,
+  selectedId,
+  onSelect,
+  laggingAfterSeconds,
+  staleAfterSeconds,
+  loading,
+  testId,
+  onKeyDown,
+}: FleetRosterProps): React.JSX.Element {
+  const theme = useTheme();
+  // Generated, not derived from `dataTestId`: two boards on one page filtered
+  // from the same fleet would otherwise emit duplicate DOM ids and an ambiguous
+  // `aria-activedescendant`. Same reason the heading uses one.
+  const rowIdPrefix = React.useId();
+  const optionId = (id: string): string => `${rowIdPrefix}-${id}`;
+
+  // The selection is CONTROLLED, so it can name a unit that has since dropped
+  // out of the freshness window — a courier ending their shift mid-poll. The
+  // attribute must then be absent rather than pointing at an element that no
+  // longer renders, which announces nothing and fails an axe audit. `mapCentre`
+  // and `nextSelection` both handle the same case; this is the third place.
+  const active = units.some((unit) => unit.id === selectedId) ? selectedId : null;
+
+  // Only when there is nothing to show yet. Unmounting a populated listbox on
+  // every poll destroys the focus inside it, so a dispatcher arrowing through
+  // the roster is thrown back to the top of the page each time the data
+  // refreshes — and the rows they were reading vanish and return.
+  if (loading && units.length === 0) return <FirstLoad testId={testId} />;
+
+  return (
+    <Box
+      role="listbox"
+      // A single tab stop with arrow keys inside, which is the listbox pattern:
+      // a dispatcher tabbing past a fleet of thirty should not have to press it
+      // thirty times to reach the map.
+      tabIndex={0}
+      aria-label={copy.rosterLabel}
+      aria-activedescendant={active ? optionId(active) : undefined}
+      data-testid={`${testId}-roster`}
+      onKeyDown={onKeyDown}
+      sx={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: theme.spacing(0.5),
+        overflowY: 'auto',
+        minWidth: 0,
+        '&:focus-visible': {
+          outline: `2px solid ${theme.palette.primary.main}`,
+          outlineOffset: 2,
+        },
+      }}
+    >
+      {units.map((unit, index) => (
+        <FleetRow
+          key={unit.id}
+          unit={unit}
+          copy={copy}
+          freshness={freshnessOf(unit.staleSeconds, laggingAfterSeconds, staleAfterSeconds)}
+          selected={unit.id === active}
+          onSelect={onSelect}
+          optionId={optionId(unit.id)}
+          position={index}
+          testId={`${testId}-${unit.id}`}
+        />
+      ))}
+    </Box>
+  );
+}

package/src/components/data-display/FleetMap/index.ts

@@ -0,0 +1,9 @@
+export { FleetMap } from './FleetMap';
+export { freshnessOf, mapCentre, nextSelection, rosterOrder } from './FleetMap.helpers';
+export type { LatLng } from './FleetMap.helpers';
+export type {
+  FleetFreshness,
+  FleetMapCopy,
+  FleetMapProps,
+  FleetUnit,
+} from './FleetMap.types';

package/src/components/data-display/FleetMap/tests.md

@@ -0,0 +1,79 @@
+# FleetMap Test Status Tracking
+
+## Test Files Status
+
+- [x] `FleetMap.test.stories.tsx` created
+- [x] `__tests__/fleet-map-helpers.test.ts` created — the four pure decisions,
+      at their boundaries, where a story is expensive to stage and an
+      off-by-one reads identically on screen
+- [x] `__tests__/fleet-map-hook.test.ts` created — the two decisions the DOM
+      cannot show: `centre`'s IDENTITY across a poll, and who owns the
+      selection across a re-render
+- [x] `__tests__/fleet-map-guards.test.tsx` created — the behaviours the review
+      rounds added guards for, in the suite CI actually runs (`test-storybook`
+      is deliberately not wired into this repo's CI)
+- [x] `__tests__/fleet-map-theme.test.tsx` created — the row and its first-load
+      skeleton under two host themes, because a radius that looks right on the
+      default one is not evidence in a package built to be re-themed
+- [x] All applicable test categories implemented
+
+## Storybook Tests Status
+
+### Test Results
+
+| Test Name | Status | Pass/Fail | Notes |
+| --- | --- | --- | --- |
+| Basic Interaction | Running | PASS | rows render, roster ordered freshest first |
+| Freshness | Running | PASS | three states, words not colour, caller formats |
+| Thresholds are props | Running | PASS | same fleet reads differently on tighter bounds |
+| Selection | Running | PASS | click reports, `aria-selected` on one row only |
+| Keyboard Navigation | Running | PASS | one tab stop, arrows move and wrap |
+| Screen Reader | Running | PASS | region, named listbox, map named not hidden |
+| Empty State | Running | PASS | empty state renders, no map canvas |
+| Loading State | Running | PASS | busy, skeletons, NOT the empty state, and silent |
+| Edge Cases | Running | PASS | one unit, long name, no badge, zero seconds |
+| Active Descendant | Running | PASS | points at a row that exists, id is generated |
+| Stale Selection | Running | PASS | a selection that left the fleet dangles nothing |
+| Loading Announcement | Running | PASS | `role="status"` carries `copy.loading` |
+| Loading Keeps Roster | Running | PASS | a poll over a populated roster keeps the listbox |
+| Uncontrolled Selection | Running | PASS | works with neither selection prop passed |
+| Controlled Without Handler | Running | PASS | arrows left un-prevented for the page |
+| Idle Announcement Region | Running | PASS | the live region exists, and is empty, while idle |
+
+Legend: Pending | Running | PASS | FAIL
+
+Not implemented, and why: **Form Interaction** — the component has no form.
+**Focus Management** — covered inside Keyboard Navigation, since the listbox's
+single tab stop IS its focus contract. **Performance** — the roster is a short
+list by construction (a fleet is people, not rows), so a render benchmark would
+measure the fixture rather than the component.
+
+## Static Stories Status
+
+- [x] Default story
+- [x] Empty state
+- [x] Loading state
+- [x] One unit
+- [x] All stale
+- [x] Tight thresholds
+- [x] Long names / no accuracy
+- [x] Selectable (controlled)
+- [x] Compact height
+
+## Lint Status
+
+- [x] No lint errors
+- [x] No warnings
+- [x] Clean under `eslint.flakiness.config.mjs`
+
+## TypeCheck Status
+
+- [x] No type errors
+- [x] All props properly typed, no `any`
+
+## Overall Component Status
+
+- [x] Lint clean
+- [x] TypeCheck clean
+- [x] Stories working
+- [x] Unit tests passing (35: 16 helpers + 8 hook + 9 guards + 2 theme)

package/src/components/data-display/FleetMap/track.md

@@ -0,0 +1,50 @@
+# FleetMap
+
+Where a set of tracked units is right now: a map beside the roster that reads
+it. Product-free — it draws labelled dots with a freshness, and every word plus
+the two formatters arrive through `copy`. Built for a delivery fleet and
+deliberately not named after one.
+
+## Props
+
+| prop | effect |
+| --- | --- |
+| `units` | who is reporting; empty renders the empty state rather than an empty map |
+| `copy` | every word, and the `lastSeen` / `accuracy` formatters |
+| `selectedId` | controlled selection; the map centres on it |
+| `onSelect` | fired by a row click, each arrow-key move, and a pin click (mouse only — the pin is not focusable) |
+| `laggingAfterSeconds` | when a unit stops reading as `live` |
+| `staleAfterSeconds` | when it stops reading as `lagging` |
+| `height` | the map's height |
+| `loading` | first-load skeletons, map and roster `aria-busy` |
+| `className` | on the panel root |
+| `dataTestId` | root TEST id; DOM ids are generated separately |
+
+## Lint
+
+Clean, including the flakiness config.
+
+## Type Errors
+
+None.
+
+## Testing Scenarios
+
+Freshness at both thresholds and at their collapse; the centroid fallback and
+the Atlantic-null for an empty fleet; roster order and its tie-break; selection
+wrapping at both ends and a selection that has left the fleet; the empty state
+against the loading state, which are opposite messages.
+
+## Storybook Tests List
+
+`BasicInteraction`, `FreshnessTest`, `ThresholdsAreProps`, `SelectionTest`,
+`KeyboardNavigationTest`, `ControlledWithoutHandlerTest`, `ScreenReaderTest`,
+`ActiveDescendantTest`, `StaleSelectionTest`, `EmptyStateTest`,
+`LoadingStateTest`, `IdleAnnouncementRegionTest`, `LoadingAnnouncementTest`,
+`LoadingKeepsThePopulatedRosterTest`, `UncontrolledSelectionTest`,
+`EdgeCaseTest`.
+
+## Current
+
+Shipped. Its first consumer is an adopter's courier-tracking panel, which
+composes it with its own transport and its own words.

package/src/components/data-display/index.ts

@@ -17,6 +17,7 @@ export * from './InteractiveTooltip';
 export * from './LazyImage';
 export * from './Lightbox';
 export * from './LoadingState';
+export * from './FleetMap';
 export * from './MapPreview';
 export * from './Popover';
 export * from './Progress';

package/src/components/feedback/ConfirmAction/ConfirmAction.md

@@ -61,13 +61,19 @@ escape hatch for the same button in a context where the action is harmless.
 Refs are not forwarded (the HOC renders trigger + popup as a fragment, so there
 is no single node to hand back). Use `<ConfirmAction>` where a ref is needed.
 
-### `ConfirmButton` — the HOC, pre-applied
+### `createConfirmButton` — the HOC, pre-applied
 
-`withConfirmation(Button)` with the shared wording already in place. Use it when
-you just want a guarded button and have no reason to build your own wrapper.
+`withConfirmation(Button)`, wrapped up for you. Use it when you just want a
+guarded button and have no reason to build your own wrapper.
+
+A FACTORY rather than a ready-made component, because the wording it bakes in is
+the caller's: it takes the host's `ConfirmActionCopy` and its error sentence, and
+returns the button. Build it once at module scope and use it like any other.
 
 ```tsx
-import { ConfirmButton } from '@12-apps/ui/feedback/ConfirmAction';
+import { createConfirmButton } from '@12-apps/ui/feedback/ConfirmAction';
+
+const ConfirmButton = createConfirmButton(PT_BR_CONFIRM_ACTION_COPY, 'Algo deu errado.');
 
 <ConfirmButton
   color="danger"