@lotics/ui 28.0.0 → 28.1.0

package/MIGRATION.md

@@ -4,6 +4,20 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 28.1.0 — `ChecklistItem` can announce more than its title
+
+Additive; nothing to change. `accessibilityLabel` overrides the row's accessible name, which
+still defaults to `title`. It exists for a surface carrying one checklist PER person, party or
+period, where the same row labels repeat and only the headings between them tell the copies
+apart — a reader moving control to control does not get those headings. Put the distinguishing
+noun in the accessible name, not in `title`, so the visible rows stay free of what the heading
+above already says.
+
+Also fixed here: **`TASK_TEXT_INSET` was cut in 28.0.0 without a replacement named.** It is
+`CONTROL_TEXT_INSET` from `@lotics/ui/control_surface` — the same 9 (1px border + 8px padding),
+and always about a CONTROL's text rather than a step's, which is why it did not follow the rest
+of `task` into `checklist`.
+
 ## 28.0.0 — `task` and `pipeline` merge into `checklist`
 
 Two families had converged on one anatomy: a ring, a title, a value beside it, a muted note, a

package/docs/catalog.md

@@ -399,7 +399,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`spacing`** — the `SPACE` scale + `SpaceToken`.
 - **`control_surface`** — `CONTROL_HEIGHT` (40), `CONTROL_RADIUS` (10), `CONTROL_TEXT_INSET`
   (9 — how far a control insets its OWN text: 1px border + 8px padding; anything that must line
-  up with a control's WORDS rather than its box carries it, and `TASK_TEXT_INSET` IS it),
+  up with a control's WORDS rather than its box carries it — a caption under an inline editor,
+  a note under a figure — rather than a hand-measured 8),
   `FOCUS_RING` (a 2px OUTSET ring, so a container that CLIPS — any `ScrollView` — has to
   keep padding on an edge a focusable child sits against, or the ring shears off on the
   one interaction it signals; the padding still comes off the 8-grid, the ring is only
@@ -1295,8 +1296,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   today, so a run filled in after the fact needs the correction in reach — and `ChecklistField`
   for a value with NO other home (a portal login created at that step, unreachable otherwise).
   `ChecklistItem.meta` is two words on the title's row; prose that grows is a `ChecklistNote`,
-  which owns its line. Worked screens: `tpl_record` § Progress (connected, grouped) and its
-  document desk (unconnected set).
+  which owns its line. A row ANNOUNCES its `title`; `ChecklistItem.accessibilityLabel` overrides
+  that for the one case the title cannot carry alone — a surface with one checklist PER person,
+  party or period, where the same labels repeat and only the headings between them separate the
+  copies, which a reader moving control to control never hears. The distinguishing noun goes in
+  the accessible name, never the title, or every visible row repeats its own heading. Worked
+  screens: `tpl_record` § Progress (connected, grouped) and its document desk (unconnected set).
 - **`stepper`** — `Stepper` + `Step` — done/current/upcoming/warning/complete progress on a
   track (horizontal) or spine (vertical); compound `<Step status>children` OR data
   `steps[]`+`current`; **navigable** via `Step.onPress` (both orientations — the whole step

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "28.0.0",
+  "version": "28.1.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/checklist.tsx

@@ -190,6 +190,19 @@ export interface ChecklistItemProps extends StepPositional {
   /** The row's name. Doubles as the ring's accessible name — the ring carries no
    *  visible label of its own, so the text rides beside it. */
   title: string;
+  /**
+   * Override that accessible name. Defaults to `title`, which is right whenever
+   * the title identifies the row on its own.
+   *
+   * Reach for it when the SAME titles repeat down a surface and only their
+   * surroundings tell them apart — one checklist per person, per party, per
+   * period, each listing the same rows. A reader moving control to control gets
+   * the names without the headings between them, so three rows all announcing
+   * "Đơn đăng ký" are three controls they cannot tell apart. Put the
+   * distinguishing noun in here, NOT in `title`: the heading above already says
+   * it, and repeating it in every visible row is noise for everyone else.
+   */
+  accessibilityLabel?: string;
   /** Ticked. */
   done?: boolean;
   /** The row the reader is waiting on — medium weight, so a run full of ticks
@@ -222,6 +235,7 @@ export interface ChecklistItemProps extends StepPositional {
 /** ONE ROW — the level that carries the ticks. */
 export function ChecklistItem({
   title,
+  accessibilityLabel,
   done,
   current,
   onToggle,
@@ -235,7 +249,7 @@ export function ChecklistItem({
     <Step
       status={done ? "done" : current ? "current" : "upcoming"}
       onToggle={onToggle}
-      accessibilityLabel={title}
+      accessibilityLabel={accessibilityLabel ?? title}
       {...positional}
     >
       <View style={{ gap: 6 }}>