@lotics/ui 19.1.0 → 20.0.0

package/MIGRATION.md

@@ -4,6 +4,41 @@ 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.
 
+## v20 from 19.x
+
+**`@lotics/ui/section` is DELETED.** Two modules exported a `Section` — the layout grammar's
+card-less region (`section_heading`) and a standalone titled block with its own `title` string,
+`collapsible` flag and imperative `SectionHandlers.expand/collapse`. The second one predated both
+the fixed heading ramp and the `Accordion` family, so a collapsible section had a heading that
+could not take the ramp's rungs and a disclosure that could not be driven from state.
+
+A collapsible section is now the `Accordion` family with a heading rung composed inside it — one
+heading family and one disclosure across static and collapsible. Replace the imperative handle
+with the controlled `expanded`/`onToggle` pair (or `defaultExpanded` when nothing outside needs to
+drive it).
+
+```tsx
+// BEFORE
+const ref = useRef<SectionHandlers>(null);
+<Section ref={ref} icon="eye-off" title="Hidden fields" collapsible initialCollapsed>
+  {body}
+</Section>
+// …elsewhere: ref.current?.expand()
+
+// AFTER
+<Accordion expanded={open} onToggle={setOpen}>
+  <AccordionHeader>
+    <DialogSectionHeadingTitle icon="eye-off">Hidden fields</DialogSectionHeadingTitle>
+  </AccordionHeader>
+  <AccordionContent>{body}</AccordionContent>
+</Accordion>
+```
+
+Pick the heading rung by where the surface sits, exactly as for a static section:
+`SectionHeadingTitle` (`##`), `SubsectionHeadingTitle` (`###`), `DialogSectionHeadingTitle`
+(`####`). The last one gained `icon` and `description` in this release, so every rung of the ramp
+now carries the same slots.
+
 ## v19 from 18.x
 
 **`TaskFields` is DELETED, with `fieldsWidth`.** A task row was carrying a

package/docs/catalog.md

@@ -150,7 +150,10 @@ Two columnar shapes, and the choice is about data size:
 `TrendChip` (delta), `Sparkline`, `BarChart` / `LineChart` / `PieChart` (the canonical SVG
 set — no recharts), `RingGauge`, `ProgressBar` (its `compact` prop = ONE row, track + a
 plain sm tabular count beside it — the cell/heading/peek-trigger meter; a caption floating
-above a tiny bar reads misaligned) / `StackedProgressBar` / `StepProgress`, `Breakdown` (a
+above a tiny bar reads misaligned. **The track clamps at 100%, the caption does not** — over
+its max it reads `2,100 / 2,000 · 105%`, because a meter that says "100%" when you are over
+tells the reader they are exactly at the limit. Numbers format in the reader's locale, so
+never hand-format the value you pass in) / `StackedProgressBar` / `StepProgress`, `Breakdown` (a
 stacked bar + ranked share rows, pressable to drill; `maxRows` folds the long tail behind a
 "Show N more" toggle — `labels` to localize — so several facet cards align to one height in
 a row), `Funnel` (a CONVERSION funnel — ordered stages as bars that NARROW; the step
@@ -172,6 +175,8 @@ to drill).
 gap-spaced region + `SectionHeading`/`SectionHeadingTitle`/`SectionHeadingMeta`; no body
 component — children are the body), `Subsection` (+ `SubsectionHeading`/
 `SubsectionHeadingTitle` — the named group INSIDE a section, `###` lg-semibold title),
+`DialogSectionHeadingTitle` (`####` md-semibold — the rung for a surface inside a DIALOG, whose
+`DialogHeaderTitle` already occupies lg; composes with the Subsection layout),
 `SectionStack` (the flat page's content column — owns the fixed 56px beat + hairline between
 top-level blocks), `SubsectionStack` (a section's `Subsection` groups — fixed 32px beat,
 space-only while the groups are SHORT, `divided` once they run long), `SectionCard`, `PageHeader` /
@@ -378,19 +383,17 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `warning`/`error` render as an ARIA `alert`) — wrapping form fields in an alert is wrong.
   The law: **content + fields → `Inset`; a message → `Callout`.**
 - **`section_heading`** — `Section` · `SectionHeading` · `SectionHeadingTitle` ·
-  `SectionHeadingMeta` · `Subsection` · `SubsectionHeading` · `SubsectionHeadingTitle` — the
+  `SectionHeadingMeta` · `Subsection` · `SubsectionHeading` · `SubsectionHeadingTitle` ·
+  `DialogSectionHeadingTitle` — the
   card-less twin of the Card family, compound, owns no margin; spacing via the Section gap
   (16, fixed), no body component. `SectionHeadingTitle` is ALWAYS `##` (xl semibold;
   `weight="medium"` opt-down only) + `info` for an ⓘ provenance popover after the title,
   same as `CardHeaderTitle.info`. `SubsectionHeadingTitle` is the `###` lg-semibold level-3
   title of a named group inside a section (same `info` ⓘ affordance as the section title) —
-  heading-row siblings ride its right edge; the
-  heading ramp is FIXED: `#` xxl / `##` xl / `###` lg, no size props.
-- **`section`** — a SECOND, standalone `Section`: a self-contained titled block
-  (`title`/`description`/`collapsible`/`icon`/`titleRight`, imperative
-  `SectionHandlers.expand/collapse`). **Warning:** two modules export a `Section` — the
-  layout grammar's card-less region is the one in `section_heading`; import from
-  `@lotics/ui/section` only when you specifically want this collapsible titled block.
+  heading-row siblings ride its right edge. `DialogSectionHeadingTitle` is the `####`
+  md-semibold rung with the SAME `icon`/`description`/`info` slots as the section title, so a
+  dialog surface loses only the type size, never an affordance. The heading ramp is FIXED:
+  `#` xxl / `##` xl / `###` lg / `####` md, no size props.
 - **`section_stack`** — `SectionStack` · `SubsectionStack` — stacks that own the
   between-block law, skipping null children: `SectionStack` = a fixed 56px beat + a hairline
   `Divider` between top-level blocks; `SubsectionStack` = a fixed 32px beat, space-only while

package/docs/composition.md

@@ -53,12 +53,14 @@ restyle a heading level per-page.
   slots carry each section's count and CTA); a `Text size="sm" weight="semibold"` stand-in is only
   for small sub-groups. Do NOT wrap each section in its own `CardHeader`, do NOT hand-roll
   sm-semibold lead lines on a flat page, and NEVER use a bare eyebrow as a section title.
-
-  **Warning:** two different `Section` components ship. The compound one described here comes from
-  `@lotics/ui/section_heading` (alongside `SectionHeading`/`SectionHeadingTitle`/
-  `SectionHeadingMeta`/`Subsection`/…). `@lotics/ui/section` exports a LEGACY collapsible
-  `Section` with a `title` string prop — a different component. Import from `section_heading` for
-  the grammar described here.
+- **Dialog section title** — the FOURTH rung, for a surface hosted in a dialog:
+  `DialogSectionHeadingTitle` (`####` — md semibold, with the same `icon`/`description`/`info`
+  slots as `SectionHeadingTitle`, so only the type size steps down). It exists because
+  `DialogHeaderTitle` is **lg** — the rung `SubsectionHeadingTitle` occupies — so a dialog holding
+  a multi-section surface otherwise ties with, or is outranked by, its own content. Compose it
+  with the SUBSECTION layout (`Subsection` › `SubsectionHeading` › this, in a `SubsectionStack`):
+  only the type size steps down, the 12px body gap and 32px beat are already right. The ladder
+  stays ABSOLUTE — this is one more fixed size, never a `size`/`compact` knob on a rung above.
 - **Subsection title** — the level BELOW a section on a long record surface: `Subsection` ›
   `SubsectionHeading` › `SubsectionHeadingTitle` (`###` — lg semibold, with the same `info` ⓘ
   affordance as `SectionHeadingTitle`; siblings — a `Badge`, a
@@ -233,10 +235,14 @@ below the pressed element — the composable `Accordion` family (`AccordionHeade
 / `AccordionMeta` / `AccordionContent`); a header-only accordion renders a plain row of identical
 rhythm, so lists mix expandable + static rows. The body is **flush** with the header's left edge
 (aligns with the title — like a `Section` body, no indent, no tinted well). `AccordionHeader` is a
-layout slot: `AccordionTitle`/`AccordionMeta` is the compact list-row heading, but for a
-**collapsible Section** (configurable font/level/description + count) compose the SAME
-`SectionHeadingTitle`/`SectionHeadingMeta` inside it — one heading family across static +
-collapsible.
+layout slot: `AccordionTitle`/`AccordionMeta` is the compact list-row heading, but a **collapsible
+SECTION** is this same family with the heading rung composed inside it — `SectionHeadingTitle` /
+`SubsectionHeadingTitle` / `DialogSectionHeadingTitle` (+ `SectionHeadingMeta`) in the
+`AccordionHeader`, the body in `AccordionContent`. There is no separate collapsible-section
+component: one heading family and one disclosure across static + collapsible. The disclosure
+header IS the section heading — name it for what it hides, never a generic bucket ("Advanced",
+"More", "Options") wrapped around one named section: that stacks two titles of the same rank and
+leaves the reader no reason to open the chevron.
 
 ## No dead rows — registers & tables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "19.1.0",
+  "version": "20.0.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -195,7 +195,6 @@
     "./dots_indicator": "./src/dots_indicator.tsx",
     "./list": "./src/list.tsx",
     "./list_item": "./src/list_item.tsx",
-    "./section": "./src/section.tsx",
     "./section_heading": "./src/section_heading.tsx",
     "./section_stack": "./src/section_stack.tsx",
     "./separator": "./src/separator.tsx",

package/src/accordion.tsx

@@ -103,7 +103,10 @@ export function AccordionHeader(props: AccordionHeaderProps) {
     <PressableHighlight
       focusRing      onPress={toggle}
       accessibilityRole="button"
-      accessibilityState={{ expanded }}
+      // The W3C prop, NOT `accessibilityState` — this react-native-web build drops the
+      // latter silently, so a disclosure shipped a `role="button"` that never announced
+      // whether its content was showing.
+      aria-expanded={expanded}
       accessibilityLabel={accessibilityLabel}
       style={[styles.headerRow, styles.pressable, style]}
     >

package/src/breakdown.tsx

@@ -113,7 +113,8 @@ export function Breakdown(props: BreakdownProps) {
         {collapsible ? (
           <PressableHighlight
               focusRing            accessibilityRole="button"
-            accessibilityState={{ expanded }}
+            // The W3C prop — `accessibilityState` is dropped by this react-native-web build.
+            aria-expanded={expanded}
             accessibilityLabel={expanded ? labels.less : labels.more(hidden)}
             onPress={() => setExpanded((e) => !e)}
             style={[styles.row, styles.pressable, styles.toggle]}

package/src/data_grid.tsx

@@ -75,7 +75,8 @@ export function DataGrid<T>(props: DataGridProps<T>) {
               <FocusRingPressable
                 onPress={() => onToggleCollapse?.(g.key)}
                 accessibilityRole="button"
-                accessibilityState={{ expanded: !isCollapsed }}
+                // The W3C prop — `accessibilityState` is dropped by this react-native-web build.
+                aria-expanded={!isCollapsed}
                 disabled={!onToggleCollapse}
                 style={({ hovered }: { hovered?: boolean }) => [styles.section, hovered && onToggleCollapse ? styles.sectionHover : null]}
               >

package/src/progress_bar.tsx

@@ -1,6 +1,7 @@
 import { View, StyleSheet, type ViewStyle } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
+import { useLocaleTag } from "./locale";
 
 export type ProgressBarFormat = "percentage" | "fraction" | "none";
 
@@ -12,7 +13,8 @@ export interface ProgressBarProps {
    * it. */
   title?: string;
   /** Caption above-right of the bar: `percentage` → "50%", `fraction` →
-   * "1.250 / 2.500 · 50%". */
+   * "1,250 / 2,500 · 50%" (separators follow the reader's locale). Reports the
+   * TRUE ratio — over `max` it reads "105%" while the track stays clamped. */
   format?: ProgressBarFormat;
   color?: string;
   completeColor?: string;
@@ -40,12 +42,23 @@ export function ProgressBar(props: ProgressBarProps) {
     compact = false,
   } = props;
 
-  const percentage = max > 0 ? Math.min(100, Math.max(0, (value / max) * 100)) : 0;
-  const isComplete = percentage >= 100;
+  // The pack is locale-aware (see `RemainderMeter`); a hardcoded tag renders 2.100 for an
+  // English reader, which reads as 2.1.
+  const localeTag = useLocaleTag();
+  /**
+   * The TRACK clamps — a fill wider than its own track is meaningless. The CAPTION does not: a
+   * meter reading `2.100 / 2.000 · 100%` asserts a number that is false, and a reader scanning
+   * percentages sees "exactly at the limit" when they are over it. Progress-toward-completion
+   * never exceeds its max, so this only diverges for the over-allowance case, where the true
+   * figure is the whole point.
+   */
+  const ratio = max > 0 ? Math.max(0, (value / max) * 100) : 0;
+  const percentage = Math.min(100, ratio);
+  const isComplete = ratio >= 100;
 
   if (compact) {
     const label =
-      format === "percentage" ? `${Math.round(percentage)}%` : `${value.toLocaleString("vi-VN")}/${max.toLocaleString("vi-VN")}`;
+      format === "percentage" ? `${Math.round(ratio)}%` : `${value.toLocaleString(localeTag)}/${max.toLocaleString(localeTag)}`;
     return (
       <View style={styles.compactRow}>
         <View style={[styles.track, styles.compactTrack]}>
@@ -62,9 +75,9 @@ export function ProgressBar(props: ProgressBarProps) {
 
   const caption =
     format === "fraction"
-      ? `${value.toLocaleString("vi-VN")} / ${max.toLocaleString("vi-VN")} · ${Math.round(percentage)}%`
+      ? `${value.toLocaleString(localeTag)} / ${max.toLocaleString(localeTag)} · ${Math.round(ratio)}%`
       : format === "percentage"
-        ? `${Math.round(percentage)}%`
+        ? `${Math.round(ratio)}%`
         : null;
 
   return (

package/src/section_heading.tsx

@@ -110,6 +110,64 @@ export function SubsectionHeadingTitle(props: SubsectionHeadingTitleProps) {
   );
 }
 
+export interface DialogSectionHeadingTitleProps {
+  children: React.ReactNode;
+  /** Optional muted line under the title, as on `SectionHeadingTitle`. */
+  description?: string;
+  /** Leading glyph, as on `SectionHeadingTitle`. */
+  icon?: IconName;
+  /** Heading rank. Defaults to 4 — one level under `SubsectionHeadingTitle`'s 3. */
+  level?: HeadingLevel;
+  /** An ⓘ popover after the title, as on the two rungs above. */
+  info?: string;
+}
+
+/**
+ * The section title for a surface hosted in a DIALOG — ALWAYS `####` (md semibold), the fourth
+ * rung of the same fixed ladder.
+ *
+ * It exists because `DialogHeaderTitle` is `lg`, which is the rung `SubsectionHeadingTitle`
+ * occupies: a dialog holding a multi-section surface has its own title tying with, or being
+ * outranked by, its content. The ladder stays ABSOLUTE — this is one more fixed size, never a
+ * knob on an existing rung. Do not reach for a `size`/`compact` prop on the titles above; the same
+ * rank rendering at two sizes is exactly what the fixed ramp prevents.
+ *
+ * Compose it with the SUBSECTION layout — `Subsection` › `SubsectionHeading` › this, inside a
+ * `SubsectionStack`. Only the type size steps down; the 12px body gap and the 32px between-group
+ * beat are already right for a dialog, so duplicating them under a `Dialog*` name would add three
+ * exports that differ from their siblings in nothing.
+ *
+ *   <SubsectionStack divided>
+ *     <Subsection>
+ *       <SubsectionHeading>
+ *         <DialogSectionHeadingTitle info="…">Usage</DialogSectionHeadingTitle>
+ *         <SectionHeadingMeta>Aug 2 – Sep 2</SectionHeadingMeta>
+ *       </SubsectionHeading>
+ *       {body}
+ *     </Subsection>
+ *   </SubsectionStack>
+ */
+export function DialogSectionHeadingTitle(props: DialogSectionHeadingTitleProps) {
+  const { children, description, icon, level = 4, info } = props;
+  const words = useLoticsLocale();
+  return (
+    <View style={{ flex: 1, gap: 2 }}>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
+        {icon ? <Icon name={icon} size={16} /> : null}
+        <Text level={level} size="md" weight="semibold">
+          {children}
+        </Text>
+        {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}
+      </View>
+      {description ? (
+        <Text color="zinc-500" size="sm">
+          {description}
+        </Text>
+      ) : null}
+    </View>
+  );
+}
+
 export interface SectionHeadingProps {
   children: React.ReactNode;
   style?: StyleProp<ViewStyle>;

package/src/select.tsx

@@ -228,11 +228,13 @@ function SelectTrigger<T extends string>({
       testID={testID}
       // Without a role this Pressable renders as an unfocusable <div> on web — the
       // trigger drops out of the tab order and Enter/Space can't open it. `button`
-      // makes it tab-focusable and maps keyboard activation to onPress; `expanded`
-      // announces open/closed to assistive tech.
+      // makes it tab-focusable and maps keyboard activation to onPress; `aria-expanded`
+      // announces open/closed to assistive tech. The W3C props, NOT `accessibilityState` —
+      // this react-native-web build drops the latter silently.
       accessibilityRole="button"
       accessibilityLabel={accessibilityLabel}
-      accessibilityState={{ expanded: open, disabled }}
+      aria-expanded={open}
+      aria-disabled={disabled}
       style={(state) => [styles.pressable, CONTROL_TRANSITION, open && styles.opened, disabled && styles.disabled, style, state.hovered && !disabled && { borderColor: HOVER_BORDER }]}
       onPress={!disabled ? onPress : undefined}
       disabled={disabled}

package/src/spreadsheet_view.tsx

@@ -9,7 +9,9 @@ function SheetTab(props: { selected: boolean; onPress: () => void; name: string
   return (
     <FocusRingPressable
       accessibilityRole="tab"
-      accessibilityState={{ selected: props.selected }}
+      // The W3C prop — `accessibilityState` is dropped by this react-native-web build, and a
+      // tab that never announces `aria-selected` leaves the tablist with no current item.
+      aria-selected={props.selected}
       onPress={props.onPress}
       style={[styles.tab, props.selected ? styles.tabActive : null]}
     >

package/src/section.tsx

@@ -1,101 +0,0 @@
-import { Pressable, View } from "react-native";
-import { Text } from "./text";
-import { useState, useImperativeHandle } from "react";
-import { Icon, IconName } from "./icon";
-import { Spacer } from "./spacer";
-import { FOCUS_RING } from "./control_surface";
-import { useFocusRing } from "./use_focus_ring";
-
-export interface SectionHandlers {
-  expand: () => void;
-  collapse: () => void;
-}
-
-interface SectionProps {
-  children: React.ReactNode;
-  title: string;
-  description?: string;
-  collapsible?: boolean;
-  icon?: IconName;
-  titleRight?: React.ReactNode;
-  initialCollapsed?: boolean;
-  ref?: React.Ref<SectionHandlers>;
-}
-
-export function Section(props: SectionProps) {
-  const {
-    children,
-    title,
-    icon,
-    description,
-    collapsible,
-    titleRight,
-    initialCollapsed = false,
-    ref,
-  } = props;
-  const [collapsed, setCollapsed] = useState(collapsible && initialCollapsed);
-
-  useImperativeHandle(ref, () => ({
-    expand: () => {
-      if (collapsible) {
-        setCollapsed(false);
-      }
-    },
-    collapse: () => {
-      if (collapsible) {
-        setCollapsed(true);
-      }
-    },
-  }));
-
-  const { focusVisible, focusProps } = useFocusRing();
-
-  const titleComponent = collapsible ? (
-    <Pressable
-      {...focusProps}
-      style={[{ flexDirection: "row", alignItems: "center", gap: 8, flex: 1 }, focusVisible && { boxShadow: FOCUS_RING, borderRadius: 4 }]}
-      onPress={() => setCollapsed(!collapsed)}
-    >
-      <Icon name={collapsed ? "chevron-right" : "chevron-down"} size={20} />
-      {icon && <Icon name={icon} size={20} />}
-      <Text size="md" weight="medium" userSelect="none">
-        {title}
-      </Text>
-    </Pressable>
-  ) : (
-    <View style={{ flex: 1 }}>
-      <Text size="md" weight="medium">
-        {title}
-      </Text>
-    </View>
-  );
-
-  return (
-    <View>
-      <View
-        style={{
-          flexDirection: "row",
-          alignItems: "center",
-          height: 40,
-          paddingBottom: 8,
-        }}
-      >
-        {titleComponent}
-        {titleRight}
-      </View>
-      {!collapsed && (
-        <>
-          {!!description && (
-            <>
-              <Text size="sm" color="zinc-500">
-                {description}
-              </Text>
-              <Spacer size={16} />
-            </>
-          )}
-          {children}
-        </>
-      )}
-    </View>
-  );
-}