@lotics/ui 47.14.0 → 47.15.0

package/AGENTS.md

@@ -18,7 +18,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, choosing a CHOICE control by option count, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW, the `FilesEditor` COMPOUND for a whole section, plus the three-way file INTAKE), stage gates, and the commit-on-blur vs action-press ordering law. |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values; findings, provenance, confidence (`Finding` is filed here because AI produces most of them, NOT because it is AI-only — a rules-derived contradiction is as in scope as an extraction's); **after the run** — a stored record that fills up from several writers; the whole run in a dialog, **stopping**; **review surfaces compose from atoms** — `DiffValue`, `DiffMark`, `useChangeSet`. |
 | [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), **a width floor answers can this be READ and never can this be operated** (the operating question passes a row whose every string is already cut), **a status column earns its slot by carrying a REASON rather than a state** (the floor asks for the fact to be visible, not for a badge), **an identity mark's GLYPH is derived from the name's distinguishing part** (an organization's first word is its legal form, so untreated every row marks one letter), **a row subject's supporting line takes a REFERENCE and never a sentence** (an explanation truncates to the clause the reader already knew), **a list stays fast by keeping IDENTITY rather than memoizing** (key by the record not the index; `memo` is the last resort and does nothing against a freshly-built prop), **a surface keyed by a whole MONTH takes a `MonthStepper`, never a range field** (its `max` bound is the contract), **a subject-by-date sheet of STATES is a `StateMatrix`** (a glyph per cell, the legend derived from the same list; not a `Matrix`, where a blank means zero), **a report's comparator is DERIVED from the selected range with `previousPeriod`, never a second control** (show it on the figure — `KPIStripItem.trend`/`caption`, `Metric previousValue`, a second `LineChart` series; a grain `SegmentedControl` beside the date field re-adds the mode the field removed), and where a commit sits. |
-| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then the probes, each naming what to COLLECT and the SIGNATURE in the numbers — including the truncation sweep (a row whose halves both measure fine and whose text is cut) the summary-vs-facet check (a strip that keeps describing the unfiltered set) and the derivable-column test (a status badge its neighbour already answers) the first-line drift a column shows when its cell is sometimes one line and sometimes two, the cross-FRAME check (what the screen destroys when a row arrives — the one defect that exists in no single frame), and the semantic-section check (a danger or empty section drawn as an ordinary one, and the primitive nobody reached for). Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
+| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then the probes, each naming what to COLLECT and the SIGNATURE in the numbers — including the truncation sweep (a row whose halves both measure fine and whose text is cut) the summary-vs-facet check (a strip that keeps describing the unfiltered set) and the derivable-column test (a status badge its neighbour already answers) the opinions-the-reader-cannot-operate pair (bands nobody asked for, pills crowding a search) the first-line drift a column shows when its cell is sometimes one line and sometimes two, the cross-FRAME check (what the screen destroys when a row arrives — the one defect that exists in no single frame), and the semantic-section check (a danger or empty section drawn as an ordinary one, and the primitive nobody reached for). Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
 | [docs/testing.md](./docs/testing.md) | Driving the kit in a browser — the three anatomies where the a11y tree says one thing and a driver must do another: a `PressDoor` row whose named button always intercepts pointer events (by design), portalled overlays that render at the top of the DOM, and custom pointer drag that `dragTo` cannot move. |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget) and the ACTIVITY shape — a communications feed where the row's label is the GIST and the body varies by medium, one anatomy rather than a row type per kind. |
 
@@ -159,7 +159,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   reading rather than a neutral one, and `toggleStripWidth(n)` for the column that seats it.
   Selected wears `chipSurfaceStyle`'s doubled dark edge — a brand ground on a selection is the
   decision the kit already reversed once.
-  → [catalog.md §"Choice controls"](./docs/catalog.md).
+  → [catalog.md §"Pickers & selection controls"](./docs/catalog.md).
 - **Pure primitives only** — no i18n, analytics, or domain types in `src/` (pass `labels`,
   callbacks); Lotics-coupled UI belongs in `@lotics/ui-internal`.
 - **A button never contains a control** — a row that presses open AND carries its own controls

package/docs/catalog.md

@@ -696,8 +696,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `vi`→`vi-VN`); date/time controls read it via **`useLocaleTag`** (`resolveLocaleTag` is its
   pure core) so the segmented field's part ORDER (dd/MM vs MM/dd), the picker calendar's
   weekday/month names, and `formatDate` display all follow the provider with no per-instance
-  `locale` prop — an explicit `locale` still overrides. **Limitation:** the calendar/gantt
-  views and the comment labels do not read the provider — pass their `labels` props directly.
+  `locale` prop — an explicit `locale` still overrides. `CalendarView` and `GanttView` are
+  wired the same way, chrome and tick names both. **Limitation:** `CommentList` carries its
+  own English defaults — pass its `labels` prop directly.
 - **`colors`** — the palette + `withAlpha`, `solid`, `tint`, `ramp`, `ColorName`,
   `isColorName`, `asColorName` (coerce a stored option/status token to a `ColorName`,
   neutral fallback).

package/docs/reviewing.md

@@ -669,6 +669,47 @@ reports two cells. And a `Text` wrapping another `Text` keeps its own words in a
 so a walk over leaf ELEMENTS measures only the nested span and reports the cell starting a
 hundred pixels in; measure text nodes with a `Range`.
 
+### 8k. Opinions the reader cannot operate — authored bands, and pills beside a search
+
+Two defects of one kind: the screen holds a view the reader can neither inspect nor put down. Both
+render perfectly, and neither shows up in any measurement of treatment.
+
+**Measure, bands.** Count the group bands a register renders, then look in the filter band for a
+control that produced them. Bands with no `group by` control are AUTHORED — the screen decided the
+cut. Then ask the harder half: is the value those bands group on also a COLUMN? A register that
+bands by something it never shows as a column leaves that fact unsortable and unfilterable, and it
+disappears the moment the reader wants a different cut.
+
+```js
+// bands rendered vs. a control that could have produced them
+const bands = document.querySelectorAll('[data-table-group], [role="rowgroup"] > [role="presentation"]').length
+const controls = [...document.querySelectorAll('button, select')].map(e => e.textContent.trim())
+```
+
+**Measure, pills.** In one filter band, count `SearchInput`s and count pill rows (`ChipGroup`). Both
+above zero is the finding: a row of pills next to a search box is two controls competing to be read
+first, and the pills win on ink while the search wins on habit.
+
+```js
+const band = document.querySelector('[data-filter-band]')
+band && { search: band.querySelectorAll('input[type="search"], input[type="text"]').length,
+          pills: band.querySelectorAll('[role="radiogroup"], [data-chip-group]').length }
+```
+
+**The source-side signature is cheaper than either.** A file rendering band headings whose label
+comes from the row's own data, with no state driving it — a `groupBy`/`lens` param absent from the
+url or component state. And an import of both `search_input` and `chip_group` in one screen.
+
+**What the fix is not.** Deleting the bands is not the fix, and neither is keeping them and adding a
+chip. Ship the value as a column first, then offer grouping as a control defaulting to none, and
+drop that column while its own grouping is on — the band states it once, the column would repeat it
+on every row beneath it.
+
+→ [composition.md](./composition.md) §"A register that TRIAGES — `TableGroup`" (flat is the
+default) and §"One view-control vocabulary" (a `ChipGroup` lens only where the band has no search).
+Both rules predate this probe; it exists because reading them is not the same as noticing you broke
+them.
+
 ### 9. The absence pass — what catches "bland"
 Every probe above reads an element that EXISTS. None fires on a screen where nothing is wrong and
 nothing is right, which is the screen reported as bland. Defect-removal converges on *inoffensive*;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "47.14.0",
+  "version": "47.15.0",
   "type": "module",
   "exports": {
     "./accordion": "./src/accordion.tsx",

package/src/calendar/calendar_view.tsx

@@ -1,7 +1,7 @@
 import { useMemo, useState, type ReactNode } from "react";
 import { View, StyleSheet, type LayoutChangeEvent } from "react-native";
 import { colors } from "../colors";
-import { useLoticsLocale } from "../locale";
+import { useLoticsLocale, useLocaleTag } from "../locale";
 import { CalendarProvider, useCalendar, type CalendarContextValue } from "./context";
 import { CalendarToolbar, CALENDAR_TOOLBAR_HEIGHT } from "./calendar_toolbar";
 import { CalendarMonth, MIN_MONTH_HEIGHT } from "./month_view";
@@ -33,6 +33,8 @@ export interface CalendarViewProps<T = unknown> {
   /** Which modes the built-in toolbar offers. Default: all four. */
   views?: CalendarViewMode[];
   weekStartsOn?: Weekday;
+  /** BCP-47 tag for the weekday / month / time names. Defaults to the active
+   *  `LoticsLocaleProvider` pack's `bcp47`; pass one only to override it. */
   locale?: string;
   /** Per-instance overrides; the rest resolve from `LoticsLocale.calendarView`. */
   labels?: Partial<CalendarViewLabels>;
@@ -88,13 +90,17 @@ export interface CalendarViewProps<T = unknown> {
  */
 export function CalendarView<T = unknown>(props: CalendarViewProps<T>) {
   const {
-    events, weekStartsOn = 1, locale, views = ALL_VIEWS,
+    events, weekStartsOn = 1, views = ALL_VIEWS,
     dayStartHour = 0, dayEndHour = 24, compactBelow = DEFAULT_COMPACT_BELOW, now,
     onEventPress, onSlotPress, renderEvent, children,
   } = props;
 
   const pack = useLoticsLocale();
   const labels: CalendarViewLabels = { ...pack.calendarView, ...props.labels };
+  // Every Intl rendering the grid does (weekday and month names, the times down
+  // the day axis) reads this, so the active pack alone localizes the calendar —
+  // an app that already supplies `vi` must not also thread a `locale` prop.
+  const locale = useLocaleTag(props.locale);
 
   // One reading of the clock for the whole tree, so the badge, the now line and
   // the scroll target cannot disagree across a midnight boundary mid-render.

package/src/gantt/gantt_view.tsx

@@ -5,7 +5,7 @@ import { colors, solid } from "../colors";
 import { proportionalRadius } from "../control_surface";
 import { FocusRingPressable } from "../focus_ring_pressable";
 import { SegmentedControl, type SegmentOption } from "../segmented_control";
-import { useLoticsLocale } from "../locale";
+import { useLoticsLocale, useLocaleTag } from "../locale";
 import { dayDiff } from "../calendar/dates";
 import { axisRange, barGeometry, buildRows, buildTicks, pxPerDay } from "./scale";
 import type { GanttLabels, GanttScale, GanttTask } from "./types";
@@ -23,6 +23,8 @@ export interface GanttViewProps<T = unknown> {
   defaultScale?: GanttScale;
   /** What counts as today for the marker and the opening scroll position. */
   today?: Date;
+  /** BCP-47 tag for the axis tick names. Defaults to the active
+   *  `LoticsLocaleProvider` pack's `bcp47`; pass one only to override it. */
   locale?: string;
   /** Optional toolbar caption shown left of the zoom switch. */
   title?: string;
@@ -48,9 +50,11 @@ export interface GanttViewProps<T = unknown> {
  * Renders at its natural height — wrap in a `ScrollView` for very long lists.
  */
 export function GanttView<T = unknown>(props: GanttViewProps<T>) {
-  const { tasks, defaultScale = "week", today = new Date(), locale, title, onTaskPress } = props;
+  const { tasks, defaultScale = "week", today = new Date(), title, onTaskPress } = props;
   const pack = useLoticsLocale();
   const L: GanttLabels = { ...pack.gantt, ...props.labels };
+  // The axis tick names come from Intl, so the active pack alone localizes them.
+  const locale = useLocaleTag(props.locale);
   const [scale, setScale] = useState<GanttScale>(defaultScale);
 
   const rows = useMemo(() => buildRows(tasks), [tasks]);

package/src/vite.d.mts

@@ -6,6 +6,13 @@
  */
 export declare const loticsOptimizeDeps: readonly string[];
 
+/**
+ * The specifiers `optimizeDeps.exclude` must carry so the kit stays ONE module
+ * graph — pre-bundling a @lotics/ui subpath inlines a private copy of every
+ * context-owning kit module it reaches. `readonly` for the same reason.
+ */
+export declare const loticsOptimizeExclude: readonly string[];
+
 /**
  * The Vite `resolve` block for a Lotics custom-code app (runtime in `vite.mjs`).
  * Reads `LOTICS_UI_SRC` at call time, so the dev-link is decided per command.

package/src/vite.mjs

@@ -3,22 +3,24 @@
  *
  * ZERO-IMPORT LEAF. This module is loaded inside Vite's Node config context
  * (a scaffolded app's `vite.config.ts` imports it), so it must pull in NOTHING —
- * no react-native-web, no kit components, no other module. It exports only a
- * plain array of strings. It ships as `.mjs` (not `.ts`) on purpose: a Vite
+ * no react-native-web, no kit components, no other module. Everything it exports
+ * is plain data or computed from `process.env` / `import.meta.resolve` at call
+ * time. It ships as `.mjs` (not `.ts`) on purpose: a Vite
  * config bundle externalizes its bare imports to their on-disk paths and hands
  * them to Node's `import()`, and Node refuses to strip types for a `.ts` file
  * under `node_modules` — a source `.ts` export would fail the config load.
  *
- * `loticsOptimizeDeps` is the set of module specifiers a scaffolded app's
- * `vite.config.ts` `optimizeDeps.include` MUST carry for `lotics app dev` to
- * render. Vite's dev dep-optimizer pre-bundles these to synthesize the
- * CJS-interop (`default` / named) exports the RN-ecosystem + markdown subtree
- * ship un-prebundled — otherwise one of them blanks the dev iframe with "does
- * not provide an export named 'default'/'parse'". Dev-ONLY: the production
- * rollup build resolves the interop without it (typecheck/lint/build stay green
- * while the dev iframe goes blank), which is exactly why this list ships WITH
- * the kit — so it can never drift from what @lotics/ui's transitive deps
- * require across a major bump.
+ * `loticsOptimizeDeps` is the set of THIRD-PARTY module specifiers a scaffolded
+ * app's `vite.config.ts` `optimizeDeps.include` MUST carry for `lotics app dev`
+ * to render — @lotics/ui itself is never one of them (see
+ * {@link loticsOptimizeExclude}). Vite's dev dep-optimizer pre-bundles these to
+ * synthesize the CJS-interop (`default` / named) exports the RN-ecosystem +
+ * markdown subtree ship un-prebundled — otherwise one of them blanks the dev
+ * iframe with "does not provide an export named 'default'/'parse'". Dev-ONLY:
+ * the production rollup build resolves the interop without it (typecheck/lint/
+ * build stay green while the dev iframe goes blank), which is exactly why this
+ * list ships WITH the kit — so it can never drift from what @lotics/ui's
+ * transitive deps require across a major bump.
  *
  * Why each family is here:
  *  - `react-native-svg` — @lotics/ui's svg charts (PieChart/LineChart/Sparkline/
@@ -34,10 +36,13 @@
  *  - `react` / `react-dom` / `react-dom/client` — pinned into the pre-bundle so
  *    every kit subpath shares one React instance (else "Invalid hook call").
  *
- * Usage — consumed by a scaffolded app's `vite.config.ts`:
+ * Usage — consumed by a scaffolded app's `vite.config.ts`, always as a pair with
+ * {@link loticsOptimizeExclude}:
  *
- *     import { loticsOptimizeDeps } from "@lotics/ui/vite";
- *     export default defineConfig({ optimizeDeps: { include: loticsOptimizeDeps } });
+ *     import { loticsOptimizeDeps, loticsOptimizeExclude } from "@lotics/ui/vite";
+ *     export default defineConfig({
+ *       optimizeDeps: { include: loticsOptimizeDeps, exclude: loticsOptimizeExclude },
+ *     });
  *
  * To add app-specific pre-bundle entries, spread the list:
  *
@@ -72,6 +77,33 @@ export const loticsOptimizeDeps = [
   "@formulajs/formulajs",
 ];
 
+/**
+ * The specifiers a scaffolded app's `optimizeDeps.exclude` MUST carry — the
+ * mirror of `loticsOptimizeDeps`, and load-bearing for the same dev-only reason.
+ *
+ * THE INVARIANT: the kit is ONE module graph. @lotics/ui ships source under
+ * `node_modules`, so Vite's dep optimizer auto-DISCOVERS every subpath an app
+ * imports (`@lotics/ui/calendar`, `@lotics/ui/table`, …) and pre-bundles each as
+ * its own entry. A kit module that is not itself an entry — `./locale`,
+ * `./tooltip`, `./portal`, `./popover` — is then INLINED into every chunk that
+ * reaches it, while the app's own `@lotics/ui/locale` import is served from
+ * source. Around 30 kit modules own a React context, and a duplicated module is
+ * a duplicated `createContext`: the provider fills one instance and the
+ * component reads the other, so `LoticsLocaleProvider` silently stops reaching
+ * `CalendarView` (chrome falls back to English) and a mounted `TooltipProvider`
+ * stops reaching a `Tooltip`. Excluding the kit keeps every subpath on the
+ * source graph, where one module means one context.
+ *
+ * Dev-ONLY, and silent: the production rollup build resolves the whole kit as
+ * one graph already, so typecheck/lint/build stay green while `lotics app dev`
+ * renders the wrong strings — which is why the list ships WITH the kit rather
+ * than living in an app that cannot know how the kit's contexts are laid out.
+ *
+ * @lotics/app-sdk needs no entry here: it imports @lotics/ui nowhere (only in
+ * doc comments), so its own optimized chunk inlines no kit module.
+ */
+export const loticsOptimizeExclude = ["@lotics/ui"];
+
 /**
  * The complete Vite `resolve` block a Lotics custom-code app needs — the second
  * half of the same contract `loticsOptimizeDeps` carries, and shipped here for