@12-apps/ui 6.22.0 → 6.24.0

package/src/components/data-display/FleetMap/NATIVE-NOTES.md

@@ -0,0 +1,14 @@
+# FleetMap on React Native
+
+Known rendering gaps, one bullet each; `pnpm native:ledger` reads them.
+
+- There is no MAP. `MapPreview` — which projects, tiles and decorates its own surface across ~2,200 lines — has no React Native build, so the native board renders the roster alone and its copy interface has neither `map` nor `mapLabel`: a caller should not be asked to name controls nothing draws. What that costs is smaller than the missing half suggests, because the web already treats this list as the component's real content rather than a sidebar — every fact a pin carries (who, how recently, how precisely, what they are carrying) is on a row, in an order the map cannot express. It is where the map goes when `MapPreview` is ported.
+- Every row is ALSO a tab stop. The list itself carries `tabIndex={0}` and `aria-activedescendant` exactly as the web's listbox does, so the arrow keys work and the selection is announced — but react-native-web additionally gives each `Pressable` its own `tabindex`, which the web half's `Box` rows never had. Measured on the rendered DOM: a fleet of thirty is thirty-one tab stops here against the web's one. Removing them would mean making the rows non-focusable, which would take the press target away on the renderer that has no touch.
+- The arrow keys are web-only. `onKeyDown` reaches the list through react-native-web's DOM events, so a browser still walks the roster with Up and Down, wrapping at both ends, declining a modified arrow and leaving the page to scroll when nothing can move. React Native delivers no key events to a `View`, so on a DEVICE none of it runs and the selection is made by touch.
+- `aria-selected` is passed as the attribute AND as `accessibilityState.selected`, because react-native-web derives neither from the other: without the attribute the web build announced no selection at all and conveyed it by background colour alone, which is the one thing this component refuses to do for freshness.
+- Hover has no touch equivalent, so the pressed wash stands in for it — and, as on the web, it must never WEAKEN the selection: a selected row keeps `action.selected` whether or not a finger is on it, rather than taking the lighter `action.hover`.
+- Keeping the selected row in view is the web's own arithmetic against different numbers. The web reads `offsetTop`/`scrollTop`/`clientHeight`; native gathers the same three from a row's `onLayout`, the `ScrollView`'s `onLayout` and its `onScroll`. So it needs one layout pass before it can act: a board mounted with a selection already set scrolls on the next commit rather than the first, where the web scrolls immediately.
+- The reload announcement is `accessibilityLiveRegion="polite"` plus `aria-live="polite"`. The first is Android's and the second is react-native-web's; iOS has no live region at all, and announcing there needs `AccessibilityInfo.announceForAccessibility`, which this component does not call — a host that must be heard on iOS makes that call itself.
+- A long unbroken label overflows rather than breaking mid-token: the web sets `overflowWrap: 'anywhere'` and React Native has no equivalent style, so a 40-character name with no spaces is clipped by the row instead of wrapped inside it.
+- `maxHeight` is a NUMBER of pixels where the web's `height` is any CSS length: React Native has no `calc`, no viewport units, and no percentage that resolves against a parent which has not sized itself.
+- The title, the row label and the meta line are set in MUI's default `body1`/`body2`/`caption` numbers; a host that re-themes MUI's typography variants moves the web only.

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

@@ -0,0 +1,10 @@
+export { FleetMap, default } from './FleetMap.native';
+export { FleetRoster } from './FleetRoster.native';
+export type {
+  FleetFreshness,
+  FleetMapBaseProps,
+  FleetMapCopy,
+  FleetMapCopyBase,
+  FleetMapProps,
+  FleetUnit,
+} from './FleetMap.types.native';

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,84 @@
+# 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 — web 35 (16 helpers + 8 hook + 9 guards + 2 theme),
+      native 14 (`FleetMap.native.test.tsx`, run by the `Native` lane rather
+      than by `pnpm test`, so each runs once)
+- [x] React Native build shipped — `@12-apps/ui/data-display/FleetMap` carries a
+      `react-native` export condition; the rendering gaps, the map's absence
+      among them, are in `NATIVE-NOTES.md` and counted by `pnpm native:ledger`

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"

package/src/platform/aria.ts

@@ -27,6 +27,19 @@ export interface WebAria {
    * it expands is a listbox — which is what the web's own trigger carries.
    */
   'aria-haspopup'?: 'listbox' | 'menu' | 'dialog' | 'true';
+  /**
+   * Which option a composite widget's single tab stop is currently on — the
+   * listbox pattern, where the LIST holds focus and the selection moves inside
+   * it. React Native has no equivalent because it has no roving focus to
+   * describe: a device selects by touching the row.
+   *
+   * Note the interaction with `aria-atomic` documented on {@link webAria}:
+   * react-native-web reads THIS value when it means the atomic flag, so a
+   * component that sets both gets the descendant id emitted as `aria-atomic`.
+   * Nothing here sets both, and a component that needs to should pass its own
+   * atomic flag directly rather than through this helper.
+   */
+  'aria-activedescendant'?: string;
 }
 
 /**

package/dist/chunk-X3HL5C6H.js

@@ -1 +0,0 @@
-//# sourceMappingURL=chunk-X3HL5C6H.js.map

package/dist/native/chunks/chunk-T6BJPP3E.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../src/platform/aria.ts"],"sourcesContent":["/**\n * WEB ATTRIBUTES REACT NATIVE DOES NOT DECLARE.\n *\n * React Native's `ViewProps` (0.83) type a dozen `aria-*` props and stop:\n * `aria-level`, `aria-atomic` and `aria-describedby` are not among them.\n * react-native-web forwards all three to the DOM — and `aria-level` also\n * picks the heading tag, so a `role=\"heading\"` at level 3 renders an `<h3>`\n * exactly as the MUI half's `component=\"h3\"` does — while a device ignores\n * them. A native component spreads them through here rather than widening\n * the element's props type or casting at every call site.\n */\nexport interface WebAria {\n  'aria-level'?: 1 | 2 | 3 | 4 | 5 | 6;\n  'aria-atomic'?: 'true' | 'false';\n  'aria-describedby'?: string;\n  /**\n   * A field's validity and whether it must be filled. React Native's\n   * `accessibilityState` has neither — its five flags are disabled, selected,\n   * checked, busy and expanded — so these are web-only, and a device reads the\n   * error text instead. react-native-web forwards both.\n   */\n  'aria-invalid'?: boolean;\n  'aria-required'?: boolean;\n  /**\n   * What a control pops open. React Native has `aria-expanded` and no\n   * `aria-haspopup`, so a `combobox` needs this one from here to say the thing\n   * it expands is a listbox — which is what the web's own trigger carries.\n   */\n  'aria-haspopup'?: 'listbox' | 'menu' | 'dialog' | 'true';\n}\n\n/**\n * `attrs` as something JSX can spread onto a react-native element without\n * that element's props type having to know them.\n *\n * `aria-atomic` travels under react-native-web's own older name. Its\n * `createDOMProps` (0.20.0) reads `aria-activedescendant` where it means\n * `aria-atomic` — `_ariaAtomic = ariaAtomic != null ? ariaActiveDescendant :\n * accessibilityAtomic` — so the modern spelling never reaches the DOM and\n * the legacy one, still accepted and still emitted as `aria-atomic`, does.\n * Neither name exists on a device, so nothing is lost there.\n */\nexport function webAria(attrs: WebAria): object {\n  const { 'aria-atomic': atomic, ...rest } = attrs;\n  return atomic === undefined ? rest : { ...rest, accessibilityAtomic: atomic };\n}\n\n/**\n * `disabled` for a react-native-web form control.\n *\n * React Native's `TextInput` has `editable` and no `disabled`, because a\n * device has no disabled state to speak of — an uneditable field simply does\n * not take the keyboard. The DOM does: only a real `disabled` attribute takes\n * an `<input>` out of the tab order, and it is what `toBeDisabled()` reads. So\n * a native field spreads this ALONGSIDE `editable={false}` and\n * `aria-disabled`: react-native-web puts the attribute on the input, and a\n * device ignores a prop it does not know.\n */\nexport function webDisabled(disabled: boolean): object {\n  return disabled ? { disabled: true } : {};\n}\n\n/**\n * `onClick` for a react-native-web element whose React Native twin has no\n * click of its own.\n *\n * react-native-web's `TextInput` forwards `onClick` to the DOM input and drops\n * `onPressIn`; a device does the opposite. A field that must answer a press on\n * both renderers spreads this ALONGSIDE `onPressIn`, and exactly one of the two\n * fires on each side — never both.\n */\nexport function webClick<E>(handler: ((event: E) => void) | undefined): object {\n  return handler === undefined ? {} : { onClick: handler };\n}\n\n/**\n * A `role` React Native's own union does not carry.\n *\n * `Role` (0.83) stops at `list` and `menu`: `listbox`, the role a dropdown's\n * option list owes a screen reader, is not in it. react-native-web forwards\n * whatever string it is given, and a device ignores a role it does not know —\n * the same trade `webAria` makes for the attributes below it.\n */\nexport function webRole(role: string): object {\n  return { role };\n}\n\n/** The half of a DOM keyboard event a component needs, without the DOM lib. */\nexport interface WebKeyEvent {\n  key: string;\n}\n\n/**\n * `onKeyDown` for a react-native-web element.\n *\n * React Native has no key events on a `View` — a phone has no keyboard to\n * press Escape on — so nothing here is typed by react-native and nothing here\n * fires on a device. react-native-web forwards it to the DOM, which is what\n * lets a native dropdown still answer Escape and the arrow keys in a browser.\n */\nexport function webKeyDown(handler: (event: WebKeyEvent) => void): object {\n  return { onKeyDown: handler };\n}\n"],"mappings":";AA0CO,SAAS,QAAQ,OAAwB;AAC9C,QAAM,EAAE,eAAe,QAAQ,GAAG,KAAK,IAAI;AAC3C,SAAO,WAAW,SAAY,OAAO,EAAE,GAAG,MAAM,qBAAqB,OAAO;AAC9E;AAaO,SAAS,YAAY,UAA2B;AACrD,SAAO,WAAW,EAAE,UAAU,KAAK,IAAI,CAAC;AAC1C;AAWO,SAAS,SAAY,SAAmD;AAC7E,SAAO,YAAY,SAAY,CAAC,IAAI,EAAE,SAAS,QAAQ;AACzD;AAUO,SAAS,QAAQ,MAAsB;AAC5C,SAAO,EAAE,KAAK;AAChB;AAeO,SAAS,WAAW,SAA+C;AACxE,SAAO,EAAE,WAAW,QAAQ;AAC9B;","names":[]}