@lotics/ui 27.17.0 → 28.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "27.17.0",
+  "version": "28.0.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -93,6 +93,7 @@
     "./agent_progress": "./src/agent_progress.tsx",
     "./approval_prompt": "./src/approval_prompt.tsx",
     "./message_actions": "./src/message_actions.tsx",
+    "./comments_button": "./src/comments_button.tsx",
     "./copy_button": "./src/copy_button.tsx",
     "./copy_text": {
       "react-native": "./src/copy_text.ts",
@@ -176,6 +177,7 @@
     "./form_field": "./src/form_field.tsx",
     "./checkbox_input": "./src/checkbox_input.tsx",
     "./check_circle": "./src/check_circle.tsx",
+    "./checklist": "./src/checklist.tsx",
     "./radio_picker": "./src/radio_picker.tsx",
     "./form_text_input": "./src/form_text_input.tsx",
     "./form_switch": "./src/form_switch.tsx",
@@ -194,7 +196,6 @@
     "./detail_row": "./src/detail_row.tsx",
     "./record_summary": "./src/record_summary.tsx",
     "./capture_row": "./src/capture_row.tsx",
-    "./task": "./src/task.tsx",
     "./suggestion_chip": "./src/suggestion_chip.tsx",
     "./danger_zone": "./src/danger_zone.tsx",
     "./scan_field": "./src/scan_field.tsx",
@@ -216,7 +217,6 @@
     "./card": "./src/card.tsx",
     "./accordion": "./src/accordion.tsx",
     "./stepper": "./src/stepper.tsx",
-    "./pipeline": "./src/pipeline.tsx",
     "./step_progress": "./src/step_progress.tsx",
     "./tabs": "./src/tabs.tsx",
     "./segmented_control": "./src/segmented_control.tsx",

package/src/checklist.tsx

@@ -0,0 +1,339 @@
+import { type ReactNode } from "react";
+import { Pressable, View } from "react-native";
+import { Text } from "./text";
+import { TextLink } from "./text_link";
+import { Stepper, Step, type StepPositional } from "./stepper";
+import { useLoticsLocale } from "./locale";
+
+/**
+ * THE CHECKLIST — an ordered run of rows a reader ticks off, optionally grouped
+ * into phases, optionally strung on a connecting spine.
+ *
+ * It replaces two families that had converged on one anatomy. `task` modelled N
+ * items ticked in any order; `pipeline` modelled ONE thing walking N positions.
+ * That distinction is real about the DATA and turned out to be invisible in the
+ * COMPONENT: both ended up as a ring, a title, a value beside it, a muted note,
+ * a detail block and an optional grouping level — and the proof is that a single
+ * afternoon added `trailing`/`meta` to `TaskTitle` and, separately, the same two
+ * to `PipelineStep`, then `tone` to `TaskCaption` and `tone`+`action` to
+ * `PipelineNote`. One feature, implemented twice, because the surfaces were
+ * twins. What actually differed was a LINE between the rings, which is a mode,
+ * and the kit's own rule is that a mode is a variant rather than a second
+ * component.
+ *
+ * The ORDERING lives in the caller's model, not here. Whether ticking rung 4
+ * implies 1–3, whether un-ticking walks the record back, what a tick even MEANS
+ * (reached, or stamped) — only the caller's data knows. This renders rows.
+ *
+ * ```tsx
+ * <Checklist connected>
+ *   <ChecklistGroup title="Sales" />
+ *   <ChecklistItem title="Quote sent" done onToggle={…} trailing={<DateStamp …/>}>
+ *     <ChecklistNote tone="warning" action={{ label: "Set in General", onPress }}>
+ *       Nobody is assigned to this desk.
+ *     </ChecklistNote>
+ *     <ChecklistActions><Button title="Hand off" /></ChecklistActions>
+ *   </ChecklistItem>
+ *   <ChecklistGroup title="Operations" />
+ *   <ChecklistItem title="Collected" onToggle={…} />
+ * </Checklist>
+ * ```
+ *
+ * Groups and items are SIBLINGS, not nested. One run, one spine, one ring column,
+ * one text edge — a group is simply a row that carries a name and no control.
+ * Nesting them put the group's own lines on a different x from its items' and
+ * needed two containers to reconcile.
+ */
+export interface ChecklistProps {
+  children?: ReactNode;
+  /**
+   * String the rings on a connecting line — for a run whose rows are POSITIONS
+   * (one record walking a process), where the line says "these are sequential".
+   * Off for a set of independent items, where a line would claim an order the
+   * work does not have.
+   */
+  connected?: boolean;
+  /**
+   * What the mark MEANS: `check` (default) for rows someone COMPLETES — a ring —
+   * and `select` for rows someone PICKS, which wear the square box selection
+   * wears everywhere else in the kit.
+   *
+   * A document picker is the case: "produce this form" is a choice, not work
+   * carried out, and a filled RING there reads as already done to anyone who has
+   * learned what a ring means. Same anatomy, same gutter; only the mark differs.
+   */
+  mark?: "check" | "select";
+  /** Accent ink for reached rings + the line. Defaults to neutral. */
+  color?: string;
+  accessibilityLabel?: string;
+}
+
+export function Checklist({ children, connected = true, mark = "check", color, accessibilityLabel }: ChecklistProps) {
+  return (
+    <Stepper
+      orientation="vertical"
+      connected={connected}
+      mark={mark === "select" ? "box" : "ring"}
+      color={color}
+      gap={CHECKLIST_ROW_GAP}
+      accessibilityLabel={accessibilityLabel}
+    >
+      {children}
+    </Stepper>
+  );
+}
+
+/** Between rows. Tight, because these are one-line rows rather than stages
+ *  carrying bodies: at a group's rhythm the line between two of them stretches
+ *  until it reads as a dash instead of a spine. */
+const CHECKLIST_ROW_GAP = 8;
+/** Above a group heading — the air that makes it a heading rather than the last
+ *  row's caption. Larger than the row gap on purpose; the two are a pair. */
+const CHECKLIST_GROUP_TOP = 18;
+/** Under a group heading. A little more than rows give each other (8) — enough
+ *  that the name reads as heading all of them rather than belonging to the first,
+ *  and no more: the heading and its first row are one block, so air between them
+ *  works against the grouping it is there to state. */
+const CHECKLIST_GROUP_BOTTOM = 4;
+
+export interface ChecklistGroupProps extends StepPositional {
+  /** The phase's name. */
+  title: string;
+  /**
+   * Whether this phase's rows are showing. CONTROLLED — and deliberately: who may
+   * be open at once is the CALLER's rule (one at a time, several, or the live one
+   * by default), and a component-local default would silently pick one. The group
+   * does not hide its own rows either: they are its SIBLINGS in the run, so the
+   * caller simply does not render them.
+   */
+  open?: boolean;
+  /** Show the disclosure — a small pressable text beside the name. Omit for a
+   *  phase that is always open. */
+  onToggleOpen?: () => void;
+  /** Override the disclosure's wording; otherwise the locale's. */
+  labels?: { expand?: string; collapse?: string };
+}
+
+/**
+ * A PHASE — a name over the rows that follow it, and nothing else.
+ *
+ * OPTIONAL: a flat checklist renders none, and one run may group only part of
+ * itself. It carries no control, because a phase owns no completion of its own —
+ * its rows do. A ring here would be a control that never responds, and one
+ * identical to the pressable rings under it invites the press it will refuse,
+ * which is worse than showing nothing: the reader clicks and the product says
+ * nothing back.
+ *
+ * It carries no BODY either. A condition or an act hung off a heading leaves the
+ * reader working out which of the rows beneath it they were about; on the row
+ * that owes the work there is no ambiguity.
+ *
+ * TYPE: `sm`, medium, full ink — the treatment a BAND heading already wears
+ * elsewhere on a record (a billing group, a ledger band). One surface should not
+ * teach two looks for the same job, and a reader who has learned that this is
+ * what "a named group of rows" looks like should not have to learn it again a
+ * section later.
+ *
+ * It was briefly an uppercase muted eyebrow, on the reasoning that a heading at
+ * the row's own `sm` medium is indistinguishable from the `sm` medium a CURRENT
+ * row wears. True of the TYPE alone, and irrelevant here: a group carries no
+ * ring and sits on the ring column's own left edge, while every row is ringed and
+ * indented past it. The structure already separates them, so spending case and
+ * ink on saying it again only made the label quieter than the prose it organises
+ * — which inverts the hierarchy it exists to state.
+ */
+export function ChecklistGroup({ title, open, onToggleOpen, labels, ...positional }: ChecklistGroupProps) {
+  const locale = useLoticsLocale();
+  const word = open ? labels?.collapse ?? locale.checklist.collapse : labels?.expand ?? locale.checklist.expand;
+  return (
+    <Step status="upcoming" marker={false} {...positional}>
+      <View
+        style={{
+          paddingTop: positional._first ? 0 : CHECKLIST_GROUP_TOP,
+          // A closed phase needs no air beneath it — the space belongs to the rows
+          // it is heading, and kept when there are none it reads as a gap the
+          // reader looks into for something that is not there.
+          paddingBottom: onToggleOpen != null && !open ? 0 : CHECKLIST_GROUP_BOTTOM,
+          flexDirection: "row",
+          alignItems: "baseline",
+          gap: 10,
+        }}
+      >
+        <Text size="sm" weight="medium">
+          {title}
+        </Text>
+        {/* A TEXT link, not a chevron: the phase is a heading rather than a row, so
+            a disclosure triangle would give it the affordance of something that
+            opens INTO a place. This only shows and hides rows already in the run,
+            and it says which in words. */}
+        {onToggleOpen != null ? (
+          <Pressable onPress={onToggleOpen} accessibilityRole="button" accessibilityLabel={`${word} · ${title}`}>
+            <TextLink size="xs">{word}</TextLink>
+          </Pressable>
+        ) : null}
+      </View>
+    </Step>
+  );
+}
+
+/**
+ * Declares that this component renders a markerless row, so `Stepper` can END the
+ * line above it rather than running one into a column that draws nothing.
+ *
+ * A STATIC on the component, not a guess about its name or its rendered output:
+ * the run is built from siblings, so the only thing that can know a heading is
+ * coming is the heading's own type, and it says so itself.
+ */
+ChecklistGroup.markerless = true as const;
+
+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;
+  /** Ticked. */
+  done?: boolean;
+  /** The row the reader is waiting on — medium weight, so a run full of ticks
+   *  still says which one is owed. */
+  current?: boolean;
+  /** Tick / un-tick. Omit for a run that only reports. */
+  onToggle?: (done: boolean) => void;
+  /**
+   * ONE value on the title's row — in practice the row's own STAMP (a
+   * `DateStamp`), which is how a milestone gets BACKDATED. The tick cannot: it
+   * writes today, and a run filled in after the fact is full of days that already
+   * passed.
+   *
+   * The row's OWN value only. A field with a home elsewhere — an assignee, an
+   * address, a portal login that a section already owns — is reported by a
+   * `ChecklistNote` naming the gap, never edited here: a list that also collects
+   * gives every row two modes and asks the reader which one they are in.
+   */
+  trailing?: ReactNode;
+  /** SHORT muted text after `trailing` — how long this row has been owed, who it
+   *  waits on. Two words; prose that grows is a `ChecklistNote`, which owns its
+   *  own line. */
+  meta?: string;
+  /** The row's overflow — an `ActionMenu`, at the end of its title row. */
+  menu?: ReactNode;
+  /** The row's own notes, acts and detail. */
+  children?: ReactNode;
+}
+
+/** ONE ROW — the level that carries the ticks. */
+export function ChecklistItem({
+  title,
+  done,
+  current,
+  onToggle,
+  trailing,
+  meta,
+  menu,
+  children,
+  ...positional
+}: ChecklistItemProps) {
+  return (
+    <Step
+      status={done ? "done" : current ? "current" : "upcoming"}
+      onToggle={onToggle}
+      accessibilityLabel={title}
+      {...positional}
+    >
+      <View style={{ gap: 6 }}>
+        {/* BASELINE, not centre: the title is `sm` and the meta `xs`, and two
+            sizes centred in one row share no baseline — the smaller floats.
+            WRAPS, so a long title drops its stamp to the next line rather than
+            crushing it. */}
+        <View style={{ flexDirection: "row", alignItems: "baseline", gap: 10, flexWrap: "wrap" }}>
+          <Text size="sm" weight={current ? "medium" : "regular"} color={done ? "muted" : "default"}>
+            {title}
+          </Text>
+          {trailing}
+          {meta ? (
+            <Text size="xs" color="muted">
+              {meta}
+            </Text>
+          ) : null}
+          {menu != null ? <View style={{ marginLeft: "auto" }}>{menu}</View> : null}
+        </View>
+        {children != null ? <View style={{ gap: 8 }}>{children}</View> : null}
+      </View>
+    </Step>
+  );
+}
+
+export interface ChecklistNoteProps {
+  children: ReactNode;
+  /** `warning` for something outstanding, `danger` for a refusal, `muted` for a
+   *  plain remark. */
+  tone?: "muted" | "warning" | "danger";
+  /**
+   * Where the reader goes to resolve it — the section that OWNS the missing
+   * value, jumped to by name.
+   *
+   * This is the whole answer to "that value is not set". A checklist REPORTS: it
+   * does not collect, and it does not PREVIEW. An editor here is a second edit
+   * surface for one fact; a rendered value — an avatar, a badge — is a copy that
+   * has to be kept in step with the field's real home, and readers start treating
+   * the list as the place the value lives. Naming the gap and handing over the
+   * navigation is the complete job.
+   */
+  action?: { label: string; onPress: () => void };
+}
+
+/** A CONDITION on one row, in words. Its own line, never inline: two words that
+ *  ride the title belong in `ChecklistItem.meta`, and prose that grows would wrap
+ *  into the title. */
+export function ChecklistNote({ children, tone = "muted", action }: ChecklistNoteProps) {
+  const text = (
+    <Text size="xs" color={tone}>
+      {children}
+    </Text>
+  );
+  if (!action) return text;
+  return (
+    <View style={{ flexDirection: "row", alignItems: "baseline", flexWrap: "wrap", columnGap: 6 }}>
+      {text}
+      <Pressable onPress={action.onPress} accessibilityRole="button" accessibilityLabel={action.label}>
+        <TextLink size="xs">{action.label}</TextLink>
+      </Pressable>
+    </View>
+  );
+}
+
+/** The act(s) that complete or leave this row. Wraps on a narrow column so a row
+ *  with two verbs never pushes the run sideways. */
+export function ChecklistActions({ children }: { children: ReactNode }) {
+  return <View style={{ flexDirection: "row", gap: 8, flexWrap: "wrap", paddingTop: 2 }}>{children}</View>;
+}
+
+export interface ChecklistFieldProps {
+  /** The value's name, stacked ABOVE the control: the row's content column is
+   *  already indented past the ring, and a second fixed column inside it leaves
+   *  nothing for the value. */
+  label?: string;
+  children: ReactNode;
+  /** Cap the control so a lone text input does not run the full column. */
+  maxWidth?: number;
+}
+
+/**
+ * A value the ROW itself owns, editable in place — and the narrow exception to
+ * "a checklist reports".
+ *
+ * Reach for it only when the value has NO OTHER HOME: a portal login created at
+ * this step and existing on no other surface would otherwise be unreachable the
+ * moment the row is behind you. Anything a section already owns is that section's
+ * to collect, and this row's `ChecklistNote` names the gap instead.
+ */
+export function ChecklistField({ label, children, maxWidth = 320 }: ChecklistFieldProps) {
+  return (
+    <View style={{ gap: 2, maxWidth }}>
+      {label ? (
+        <Text size="xs" color="muted">
+          {label}
+        </Text>
+      ) : null}
+      {children}
+    </View>
+  );
+}

package/src/comments_button.tsx

@@ -0,0 +1,108 @@
+import { StyleSheet, type GestureResponderEvent } from "react-native";
+import { colors } from "./colors";
+import { Icon } from "./icon";
+import { PressableHighlight } from "./pressable_highlight";
+import { ROW_CONTROL_HOVER, ROW_CONTROL_PRESS } from "./control_surface";
+import { Text } from "./text";
+import { useLoticsLocale } from "./locale";
+
+export interface CommentsButtonProps {
+  /** How many comments the thread holds. Render the button only where there ARE
+   *  some — see the note on zero below. */
+  count: number;
+  /** What the thread is about — the record's name. It only reaches the accessible
+   *  label, which is where a screen-reader user needs it: "3 comments on Northwind
+   *  Packaging" is a destination, "3 comments" on the fortieth row is not. */
+  subject?: string;
+  /** Open the discussion. A count the reader cannot act on states that a
+   *  conversation exists and leaves them to find it. */
+  onPress?: (event: GestureResponderEvent) => void;
+  /** `sm` (the register row's) or `md`. Matches `CopyButton`'s scale so the two
+   *  affordances a row carries sit at one size. */
+  size?: "sm" | "md";
+  /** Override the wording; otherwise the locale's. */
+  labels?: { comments?: string; comment?: string };
+  disabled?: boolean;
+  testID?: string;
+}
+
+/**
+ * A row's DISCUSSION — the count, the bubble, and the way in.
+ *
+ * Reach for it wherever a record is listed and its thread would otherwise be
+ * invisible until opened: a register row, a card, a compact header. It is the
+ * peer of `CopyButton` — the other thing a dense row lets you press — and shares
+ * its surface, its scale and its focus ring, so a row carrying both reads as one
+ * grammar rather than two authors.
+ *
+ * **ONE control, not a number beside a button.** The count and the glyph are the
+ * same target: the number IS what the reader aims at ("three comments" is the
+ * thing they saw), and splitting them leaves half the affordance dead under the
+ * pointer. It was briefly an `IconButton` with the count as loose text — which
+ * gave the glyph a hover state and the number none.
+ *
+ * **Full ink.** Everything else on a register row is a value ABOUT the record;
+ * this is people talking about it, and it is the one thing on the row that can be
+ * UNREAD. Muted, it files itself with the phone number.
+ *
+ * **Render it only when `count > 0`.** A zero on every quiet row is a column of
+ * noise that trains the eye to skip exactly where the signal will appear. The
+ * component does not decide that for you — an empty-state row may legitimately
+ * want a way to START a thread — but a register should not.
+ */
+export function CommentsButton(props: CommentsButtonProps) {
+  const { count, subject, onPress, size = "sm", labels, disabled, testID } = props;
+  const locale = useLoticsLocale();
+  const noun = count === 1 ? labels?.comment ?? locale.commentsButton.comment : labels?.comments ?? locale.commentsButton.comments;
+  // The subject rides the NAME, never the visible label: a row already says whose
+  // record it is, and repeating it beside the count spends the row's width on
+  // something the eye has just read.
+  const name = subject ? `${count} ${noun} · ${subject}` : `${count} ${noun}`;
+
+  return (
+    <PressableHighlight
+      focusRing
+      testID={testID}
+      tooltip={name}
+      accessibilityRole="button"
+      accessibilityLabel={name}
+      onPress={onPress}
+      disabled={disabled || onPress == null}
+      // The row it rides hovers to `zinc[100]`, so this takes the row-control
+      // wash a step darker — matching `IconButton`, so the two things a dense row
+      // lets you press respond identically.
+      style={(state: { hovered?: boolean; pressed?: boolean }) => [
+        styles.button,
+        styles[size],
+        { backgroundColor: state.pressed ? ROW_CONTROL_PRESS : state.hovered ? ROW_CONTROL_HOVER : undefined },
+        disabled && styles.disabled,
+      ]}
+      // The same 40px touch target `IconButton` reserves at these sizes, without
+      // the visual box growing into the row.
+      hitSlop={size === "sm" ? 8 : 6}
+    >
+      <Icon size={size === "sm" ? 14 : 16} name="message-square" color={colors.zinc[900]} />
+      <Text size="xs" weight="medium" tabular>
+        {count}
+      </Text>
+    </PressableHighlight>
+  );
+}
+
+const styles = StyleSheet.create({
+  button: {
+    flexDirection: "row",
+    alignItems: "center",
+    // Tight: the glyph and its number are ONE word, not two things in a row.
+    gap: 3,
+    // A pill rather than `IconButton`'s circle — it holds two glyphs' worth of
+    // content, and a circle sized to fit them would balloon beside a 24px copy
+    // control on the same line.
+    borderRadius: 999,
+  },
+  // 24 at `sm` — the SAME box `IconButton` reserves there, so a row carrying
+  // both lands them on one baseline and one height.
+  sm: { paddingHorizontal: 6, height: 24 },
+  md: { paddingHorizontal: 8, height: 28 },
+  disabled: { opacity: 0.3 },
+});

package/src/control_surface.ts

@@ -56,6 +56,19 @@ export const CONTROL_TEXT_INSET = 9;
  *  `CONTROL_TRANSITION` so the change eases in. */
 export const HOVER_BORDER = colors.zinc[400];
 
+/**
+ * The wash a control paints when it rides a HOVERABLE surface — a register row,
+ * a list item, a card.
+ *
+ * One step darker than the generic hover, and it has to be. A row's own hover is
+ * `zinc[100]`; a control that also hovers to `zinc[100]` paints the same grey on
+ * the same grey the moment the pointer is over both — which is always, since
+ * reaching the control means crossing the row. The control then reads as dead
+ * exactly when the reader is pointing at it, and no amount of size fixes that.
+ */
+export const ROW_CONTROL_HOVER = colors.zinc[200];
+export const ROW_CONTROL_PRESS = colors.zinc[300];
+
 /** The ease applied to a bordered control's interactive edges (border + ring), so
  *  hover/focus transitions read smooth, not snapped. Web-only; ignored on native. */
 export const CONTROL_TRANSITION = {

package/src/detail_row.tsx

@@ -18,7 +18,7 @@ interface DetailTableColumns {
 const DetailTableContext = createContext<DetailTableColumns | null>(null);
 
 /** THE kit's label column — ~18 characters, where real field names live. It is
- *  this table's default AND a `TaskList`'s, so a record's fields and a task's
+ *  this table's default, so a record's fields and a checklist's
  *  read as one language on a surface carrying both; that only holds while the
  *  two are ONE number. A name longer than the column WRAPS inside it: the
  *  column belongs to the SURFACE, so no one field's name may push its own value
@@ -158,7 +158,7 @@ export function DetailRow(props: DetailRowProps) {
   );
   // THE field-annotation anatomy — severity, tones, a11y and the control's own
   // text inset, defined once in `field_annotations` and rendered identically by
-  // a task's `TaskSubRow`. A record's field and a task's field are the same
+  // a checklist row's field. A record's field and a checklist's are the same
   // thing on two surfaces; they may not say a fault two different ways.
   const annotations = <FieldAnnotations description={description} warning={warning} error={error} />;
   if (table?.stacked) {

package/src/field_annotations.tsx

@@ -4,7 +4,7 @@ import { Text } from "./text";
 
 /**
  * What a FIELD says about itself under its own value — ONE anatomy, shared by every field
- * surface in the kit (`DetailRow` on a record, `TaskSubRow` on a task). A record's field and a
+ * surface in the kit — `DetailRow` on a record, `ChecklistField` on a checklist row. A record's field and a
  * task's field carry the same three tones, in the same order, with the same a11y, because they
  * ARE the same thing on two surfaces: a name, a value the reader sets, and whatever has to be
  * said about it. Where the two disagreed, an app with a field-level fault had to demote it into

package/src/icon.tsx

@@ -9,8 +9,18 @@
  *    (find the file name via: grep "IconName" node_modules/lucide-react-native/dist/esm/lucide-react-native.js)
  * 2. Add the icon to the iconComponents object with kebab-case key
  * The type will be automatically derived from the object keys.
+ *
+ * The reference below is load-bearing, not tidiness: lucide ships these icon
+ * files as JS with no `.d.ts` and does not list them in its `exports`, so the
+ * ambient declaration beside this file is the only thing that types them. An
+ * ambient file joins a program only when the program INCLUDES it, and a
+ * consumer's `include` covers the consumer's own directory — never ours. Every
+ * consumer therefore has to reach it through the file that needs it, which is
+ * this one.
  */
 
+/// <reference path="./lucide-react-native.d.ts" />
+
 import { View } from "react-native";
 import Activity from "lucide-react-native/dist/esm/icons/activity";
 import TextAlignCenter from "lucide-react-native/dist/esm/icons/text-align-center";

package/src/icon_button.tsx

@@ -2,6 +2,7 @@ import { ActivityIndicator, GestureResponderEvent, StyleProp, StyleSheet, View,
 import { Icon, IconName } from "./icon";
 import { colors } from "./colors";
 import { PressableHighlight } from "./pressable_highlight";
+import { ROW_CONTROL_HOVER, ROW_CONTROL_PRESS } from "./control_surface";
 import { type ButtonColor } from "./button";
 import { getButtonIconColor } from "./button_colors";
 import { Ref } from "react";
@@ -80,7 +81,22 @@ export function IconButton(props: IconButtonProps) {
       tooltipSide={tooltipSide}
       accessibilityRole="button"
       accessibilityLabel={accessibilityLabel ?? tooltip}
-      style={[styles.button, styles[size], styles[color], elevated && styles.elevated, disabledOrLoading && styles.disabled, style]}
+      // A glyph-only control rides ROWS more often than it stands alone, and a
+      // row hovers to `zinc[100]` — so the generic hover would paint the same
+      // grey on the same grey the moment the pointer reaches this, which is
+      // always. The colored variants keep their own fill; only `none`/`white`,
+      // which have no fill to darken, take the row-control wash.
+      style={(state: { hovered?: boolean; pressed?: boolean }) => [
+        styles.button,
+        styles[size],
+        styles[color],
+        elevated && styles.elevated,
+        color === "none" || color === "white"
+          ? { backgroundColor: state.pressed ? ROW_CONTROL_PRESS : state.hovered ? ROW_CONTROL_HOVER : undefined }
+          : null,
+        disabledOrLoading && styles.disabled,
+        style,
+      ]}
       onPress={handlePress}
       disabled={disabledOrLoading}
       // 40px touch target regardless of visual size (28 + 2×6 / 24 + 2×8)

package/src/locale.tsx

@@ -69,10 +69,14 @@ export interface LoticsLocale {
   /** `Ledger`: the screen-reader name of a peekable row. */
   ledger: { rowDetails: (label: string) => string };
   /** `SectionHeadingTitle`: the info-popover trigger's screen-reader name. */
-  /** `Step`/`PipelineStage`'s toggleable MARKER, when the caller names no
+  /** `Step`/`ChecklistItem`'s toggleable MARKER, when the caller names no
    *  label of its own. A pipeline stage always passes its title, so this is the
    *  bare-`Step` fallback. */
   stepper: { complete: string; progress: string };
+  /** `ChecklistGroup`'s disclosure — the small pressable text that shows or hides
+   *  a phase's rows. The kit owns the wording so one app does not say "Show" while
+   *  the next says "Expand" for the same gesture. */
+  checklist: { expand: string; collapse: string };
   sectionHeading: { info: string };
   /** `ErrorState`'s retry button. The kit owns the wording so "try again" is
    *  phrased identically everywhere instead of hand-written per app. */
@@ -213,6 +217,9 @@ export interface LoticsLocale {
    *  copied stays a per-instance `label` ("Copy phone number") — that names a
    *  value only the call site knows, the same split `referenceField.open` draws. */
   copyButton: { copy: string; copied: string };
+  /** `CommentsButton`'s accessible name — the kit owns the noun so one surface
+   *  does not say "comments" while the next says "notes" for the same thread. */
+  commentsButton: { comment: string; comments: string };
 }
 
 /** The platform default — English. Every component's hardcoded default lives
@@ -245,6 +252,7 @@ export const en: LoticsLocale = {
   clarify: { otherPlaceholder: "Or type your own answer…", back: "Back", next: "Next", cancel: "Cancel", submit: "Submit" },
   ledger: { rowDetails: (label) => `${label} details` },
   stepper: { complete: "Complete step", progress: "Progress" },
+  checklist: { expand: "Show", collapse: "Hide" },
   sectionHeading: { info: "About this data" },
   errorState: { retry: "Try again" },
   chip: { remove: "Remove" },
@@ -375,6 +383,7 @@ export const en: LoticsLocale = {
   approvalPrompt: { message: "The assistant wants to perform an action that needs your approval.", approve: "Approve", deny: "Deny" },
   messageActions: { copy: "Copy", copied: "Copied", regenerate: "Regenerate", edit: "Edit", previousVersion: "Previous version", nextVersion: "Next version" },
   copyButton: { copy: "Copy", copied: "Copied" },
+  commentsButton: { comment: "comment", comments: "comments" },
 };
 
 /** Vietnamese. Maintained once here so every app (and the frontend) shares one
@@ -407,6 +416,7 @@ export const vi: LoticsLocale = {
   clarify: { otherPlaceholder: "Hoặc nhập câu trả lời khác…", back: "Quay lại", next: "Tiếp", cancel: "Hủy", submit: "Gửi" },
   ledger: { rowDetails: (label) => `Chi tiết ${label}` },
   stepper: { complete: "Hoàn thành bước", progress: "Tiến trình" },
+  checklist: { expand: "Mở", collapse: "Thu gọn" },
   sectionHeading: { info: "Giải thích dữ liệu" },
   errorState: { retry: "Thử lại" },
   chip: { remove: "Xóa" },
@@ -534,6 +544,7 @@ export const vi: LoticsLocale = {
   approvalPrompt: { message: "Trợ lý muốn thực hiện thao tác cần bạn duyệt.", approve: "Cho phép", deny: "Từ chối" },
   messageActions: { copy: "Sao chép", copied: "Đã sao chép", regenerate: "Tạo lại", edit: "Chỉnh sửa", previousVersion: "Phiên bản trước", nextVersion: "Phiên bản sau" },
   copyButton: { copy: "Sao chép", copied: "Đã sao chép" },
+  commentsButton: { comment: "bình luận", comments: "bình luận" },
 };
 
 const LoticsLocaleContext = createContext<LoticsLocale>(en);