@lotics/ui 41.4.0 → 42.0.0

package/AGENTS.md

@@ -18,6 +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, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW — list + one CTA, `multiple` decides add-vs-replace; the `FilesEditor` COMPOUND for a whole section — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, whether a multiline value keeps its fixed reserve or `autoGrow`s (who decides the length — the field, or whoever is typing), the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
 | [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 (machine → a gate: a diff when something is being replaced, a full editable preview when records are being created from a document; human-typed → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; **after the run** — a stored record that fills up from several writers (a person, a chat agent, an extraction, an automation) and remembers none of them: an unwritten value must not render like a written one, a machine's prose and a person's must not share a treatment, model markdown goes in `variant="embedded"`, and the read path must project every field the write paths set; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md)., the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer, **Stop** while streaming), **stopping** (`cancel` stops the run, `abort` only stops listening — so closing a dialog must `cancel` or it keeps billing); **review surfaces compose from atoms** — `DiffValue` (a changed value, droppable in any cell/row/total), `DiffMark` (what happened to the row — ONE circular disc, every surface), `useChangeSet` (accept/reject/undo bookkeeping, no layout) — see [MIGRATION.md](./MIGRATION.md) for the `ChangeReview` family they replace |
 | [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), the button ladder and **what underlined text may mean** (it GOES somewhere or REVEALS something — never mutates; blue leaves the surface, muted stays on it, and the one in-prose disclosure exception is scoped there), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), color discipline, typography, whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
+| [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. |
 
 ## Iron rules

package/MIGRATION.md

@@ -4,6 +4,40 @@ 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.
 
+## 42.0.0 — `DateFilter`'s presets are a listbox, and "Custom" is not one of them
+
+Three defects with one root: the preset row used EMPHASIS to mean "current state", inside a
+panel where emphasis means "action".
+
+**The active preset was painted like a primary button.** `zinc.800` with inverted text — the
+loudest treatment the system has — spent on a row that reports state rather than offering one.
+It outshouted the panel's own Done button. It now uses `MenuButton`'s `selected`, the kit's
+listbox row: a `zinc.100` resting highlight. That prop also carries `aria-selected`, which the
+hand-rolled fill never did — until now the active preset announced **nothing**, so which period
+was selected was information available only to someone who could see the fill.
+
+**The panel rendered its phone layout on desktop.** It sized itself with `useContainerSize()`,
+which inside a `Popover` measures the popover BODY — and the body's width is decided by the
+branch that reading picks. Two calendars come to ~617px, always under the 768 phone threshold,
+so the panel resolved "small" on a 1440px viewport and its sidebar branch was unreachable: the
+presets collapsed into a horizontal strip of bare text where the only item with any chrome was
+the active one. It now reads `useScreenSize()` — the same instrument, and for the same reason,
+that `Popover` already uses to choose sheet vs anchored.
+
+**`"custom"` is gone from `PresetId`, `PRESET_IDS`, and `DateFilterLabels`.** It was the one
+entry that set no range: it CLEARED the value. So it lit up whenever the range matched no
+preset — the normal state for any hand-picked range, and the opening state of any app whose
+default period is not a preset — and clicking the lit row, the obvious move for "let me pick my
+own dates", threw the range away. The calendar is the custom picker and the footer's Clear is
+the clear.
+
+`getPresetValue` is now total: it returns `DateFilterValue`, never `| null`.
+
+**To migrate:** delete `custom` from any `DateFilterLabels` / `DateRangeFilterFieldLabels`
+object you pass — it is an excess property now and the compiler will point at it. If you called
+`getPresetValue` and branched on `null`, drop the branch. Nothing else changes: a range that
+matches no preset simply leaves every row unselected, which is what it always meant.
+
 ## 41.4.0 — embedded markdown is demoted in the OUTLINE, not only on the type ladder
 
 `<Markdown variant="embedded">` sized its headings down and left them as the tags the author

package/docs/catalog.md

@@ -857,6 +857,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   for it bare only when the calendar lives permanently on the surface, not behind a field.
 - **`date_filter`** — `DateFilter`: the date+time period filter panel — presets
   (`PresetId`), calendar, optional time segments; the body `DateRangeFilterField` opens.
+  **Every preset SETS a range** — the list holds no mode and no null case, so a hand-picked
+  range selects nothing rather than lighting a "custom" row whose click cleared the value. The
+  presets are a `listbox` of `MenuButton` options: selection is the kit's `zinc.100` row
+  highlight plus `aria-selected`, never a filled primary treatment, because the row reports
+  state rather than offering an action. Sidebar at viewports of 768 and up, strip below —
+  measured on the VIEWPORT, since a popover's own width is decided by that very branch.
   **One selection rule, no modes**: a click OPENS a range, the next CLOSES it (in either
   order — bounds come back sorted), and a single day is the same day clicked twice
   (`start`/`end` equal — which is how a consumer detects "one day" and how the trigger

package/docs/composition.md

@@ -1047,6 +1047,29 @@ most common, because it survives every other check: each piece is defensible alo
 question "what does this tell me that the screen does not already say" catches decoration wearing
 an information costume.
 
+## `accessibilityState` never reaches the DOM — write `aria-*` yourself
+
+React Native Web maps a subset of RN's accessibility props and **silently drops
+`accessibilityState`**. So a control written the RN way announces nothing:
+
+```tsx
+// renders, typechecks, and the DOM carries no state at all
+<Pressable accessibilityRole="tab" accessibilityState={{ selected: isActive }} />
+
+// what actually reaches the DOM
+<Pressable accessibilityRole="tab" aria-selected={isActive} />
+```
+
+The trap is the failure's shape rather than its cause. There is no type error —
+the prop is declared — no runtime warning, and the control looks and behaves
+correctly; only a screen reader and the DOM inspector disagree with the source.
+Nothing in a normal loop surfaces it, so it survives review, tests and QA.
+
+Write the raw `aria-*` attribute for any STATE (`aria-selected`, `aria-checked`,
+`aria-expanded`, `aria-disabled`, `aria-current`). `accessibilityRole` and
+`accessibilityLabel` do map and are fine as-is. **Verify in the DOM, never in the
+source** — the source is what lies here.
+
 ## Testing an overlay component — assert through the logic, prove in a browser
 
 **A `Popover`-backed surface does not mount under jsdom.** It positions in a `useLayoutEffect` +

package/docs/testing.md

@@ -0,0 +1,70 @@
+# Driving the kit in a browser
+
+Three kit anatomies where the accessibility tree says one thing and an automated
+driver has to do another. Each is **by design** — the shape that makes the
+component correct for a keyboard and a screen reader is the shape that defeats a
+naive `click()` — so each will read as a bug the first time, and the wrong
+reaction (`force: true`, or "the component is broken") costs a debugging session.
+
+Everything here is true wherever the kit renders. The iframe that a Lotics app
+runs inside adds one more rule on top — `lotics docs building_an_app` § 8.
+
+---
+
+## A pressable row: click the surface, not the named button
+
+A row that presses open **and** carries its own controls is a role-less
+`PressableRow` with a `PressDoor` sibling (`@lotics/ui` AGENTS.md — *a button
+never contains a control*). The door is what a keyboard and a screen reader
+use: it holds the tab stop, the accessible name and the focus ring, and it is an
+**empty absolutely-positioned element**. The cells render above it.
+
+So the a11y tree shows `button "Open ACME-1042"`, and clicking it fails:
+
+```
+subtree intercepts pointer events
+```
+
+That is the design working, not a defect — the visible row is above the door
+precisely so a pointer lands on the row rather than the door. Drive it the way a
+mouse user does:
+
+- **click the row container** — the `generic [cursor=pointer]` wrapping the door;
+  the click bubbles to `PressableRow`
+- or `dispatchEvent('click')` on the door directly
+- or exercise the keyboard path, which is the one the door exists for: focus the
+  door and press `Enter`
+
+**Never reach for `force: true`.** It suppresses the actionability check that is
+telling you the truth, and the click then lands somewhere you did not choose.
+
+## Overlays render at the top of the DOM, not inside their trigger
+
+Popovers, tooltips and dialogs go through a portal (`dom_portal`), so their
+content is a sibling near the end of the document rather than a descendant of
+the control that opened it. Looking for it under the trigger finds nothing.
+
+Assert two things, not one: that the content appeared, and that it **dismisses**
+— outside-click and `Escape` both. An open overlay usually has a click-catching
+backdrop, so clicking the trigger a second time is often intercepted; click the
+backdrop or press `Escape`.
+
+## Custom pointer drag is not `dragTo`
+
+The calendar and gantt drags are built on `use_pointer_drag`, which listens for
+real `pointerdown` / `pointermove` / `pointerup`. Playwright's `dragTo` and mouse
+emulation do not drive them — the sequence simply does nothing, with no error.
+
+Dispatch the events yourself, **in the frame's own context** so the coordinates
+and the window are the right ones. From the dragged element,
+`el.ownerDocument.defaultView` is that window:
+
+1. `pointerdown` on the element
+2. `pointermove` on the window, past the drag threshold (a few pixels — a smaller
+   move is treated as a click, deliberately)
+3. `pointerup` on the window, with `clientX`/`clientY` at the drop target
+
+Then check **both** halves: re-snapshot for the optimistic move, and re-read the
+record to confirm the mutation actually persisted. An optimistic move that never
+reached the server looks identical on screen, which is the whole reason to check
+the second one.

package/examples/tpl_dashboard.tsx

@@ -98,7 +98,7 @@ const KY_CUOI = "2026-06";
 const NHAN_BO_LOC: Partial<DateRangeFilterFieldLabels> = {
   year: "Year", month: "Month", day: "Day", hour: "Hour", minute: "Minute", dayPeriod: "AM/PM",
   today: "Today", yesterday: "Yesterday", tomorrow: "Tomorrow", thisWeek: "This week",
-  thisMonth: "This month", lastMonth: "Last month", custom: "Custom", from: "From", to: "To",
+  thisMonth: "This month", lastMonth: "Last month", from: "From", to: "To",
   selectDateRange: "Select date range", selectDate: "Select date",
   clear: "Clear", done: "Done", placeholder: "All time",
 };

package/package.json

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

package/src/date_filter.tsx

@@ -6,7 +6,7 @@ import { CONTROL_RADIUS } from "./control_surface";
 import { MenuButton } from "./menu_button";
 import { Calendar, CalendarRangeValue, CalendarRef } from "./date_calendar";
 import { TimePicker } from "./time_picker";
-import { useContainerSize } from "./size_boundary";
+import { useScreenSize } from "./use_screen_size";
 import { SegmentLabels } from "./date_segments";
 import { PresetId, PRESET_IDS, getPresetValue } from "./date_filter_presets";
 import { formatDate } from "./format_date";
@@ -33,7 +33,6 @@ export interface DateFilterLabels extends SegmentLabels {
   thisWeek: string;
   thisMonth: string;
   lastMonth: string;
-  custom: string;
   from: string;
   to: string;
   /** Accessible name of the field that OPENS this panel (`DateRangeFilterField`). */
@@ -72,8 +71,6 @@ function presetLabel(id: PresetId, labels: DateFilterLabels): string {
       return labels.thisMonth;
     case "last_month":
       return labels.lastMonth;
-    case "custom":
-      return labels.custom;
   }
 }
 
@@ -134,7 +131,21 @@ export function DateFilter(props: DateFilterProps) {
     () => ({ ...loc, ...props.labels }),
     [loc, props.labels],
   );
-  const screenSize = useContainerSize();
+  // The VIEWPORT, never this panel's own box.
+  //
+  // This read `useContainerSize()`, which inside a `Popover` measures the popover
+  // BODY — and the body's width is decided by which branch this very line picks.
+  // Two calendars come to ~617px, always under the 768 phone threshold, so the
+  // panel resolved "small" on a 1440px desktop and the sidebar branch below was
+  // unreachable: the presets rendered as the phone strip on every screen, which
+  // is why the only item in them with any chrome read as a button.
+  //
+  // `Popover` already carries this rule for its own sheet-vs-anchored decision,
+  // and its comment names the same bug being introduced by the same hook. Same
+  // instrument here, so the two agree: under 768 the popover is a bottom sheet
+  // and the presets are a strip; at or above it, an anchored panel with the
+  // sidebar.
+  const screenSize = useScreenSize();
   const calendarRef = useRef<CalendarRef>(null);
 
   // A half-picked range is held HERE and never emitted — the same rule
@@ -192,13 +203,15 @@ export function DateFilter(props: DateFilterProps) {
     [onValueChange, value],
   );
 
-  // Which preset (if any) the current value matches.
+  // Which preset (if any) the current value matches. A hand-picked range matches
+  // none, and that is `null` — no row is selected. It used to fall through to
+  // "custom", so the panel opened with a row lit for a range the member had
+  // never chosen from this list.
   const activePresetId = useMemo((): PresetId | null => {
     if (!value.start.date && !value.end.date) return null;
     const now = new Date();
     for (const id of PRESET_IDS) {
       const presetValue = getPresetValue(id, now);
-      if (!presetValue) continue; // "custom"
       if (
         value.start.date?.toDateString() === presetValue.start.date?.toDateString() &&
         value.end.date?.toDateString() === presetValue.end.date?.toDateString()
@@ -206,7 +219,7 @@ export function DateFilter(props: DateFilterProps) {
         return id;
       }
     }
-    return "custom";
+    return null;
   }, [value]);
 
   const handlePresetSelect = useCallback(
@@ -220,12 +233,6 @@ export function DateFilter(props: DateFilterProps) {
       }
 
       const presetValue = getPresetValue(id, new Date());
-      if (!presetValue) {
-        // "Custom" clears the value so the user can select manually
-        onValueChange({ start: { date: null, time: null }, end: { date: null, time: null } });
-        return;
-      }
-
       onValueChange(presetValue);
 
       if (presetValue.start.date) {
@@ -238,27 +245,39 @@ export function DateFilter(props: DateFilterProps) {
     [onValueChange, activePresetId],
   );
 
-  const renderPreset = (id: PresetId) => {
-    const isActive = activePresetId === id;
-    return (
-      <MenuButton
-        key={id}
-        title={
-          <Text size="sm" color={isActive ? "inverted" : "default"}>
-            {presetLabel(id, labels)}
-          </Text>
-        }
-        onPress={() => handlePresetSelect(id)}
-        style={[styles.presetItem, isActive && styles.presetItemActive]}
-      />
-    );
-  };
+  // `selected` + `role="option"` is the kit's listbox row, and `MenuButton` owns
+  // both halves of it: the resting `zinc.100` highlight and the `aria-selected`
+  // that carries the state to a screen reader.
+  //
+  // This used to paint `zinc.800` with inverted text and pass neither. That is
+  // the PRIMARY BUTTON treatment — the loudest thing the system has, spent on a
+  // row that reports state rather than offering an action, so the selected
+  // preset outshouted the panel's own Done button. And because no `selected` or
+  // `current` ever reached `MenuButton`, the active preset announced nothing at
+  // all: the state was visible only to someone who could see the fill.
+  const renderPreset = (id: PresetId) => (
+    <MenuButton
+      key={id}
+      role="option"
+      selected={activePresetId === id}
+      title={<Text size="sm">{presetLabel(id, labels)}</Text>}
+      onPress={() => handlePresetSelect(id)}
+      style={styles.presetItem}
+    />
+  );
 
   return (
     <View style={[styles.container, { flexDirection: screenSize.small ? "column" : "row" }]}>
       {/* Presets sidebar (desktop only) */}
       {!screenSize.small && (
-        <View style={styles.presetsSidebar}>{PRESET_IDS.map(renderPreset)}</View>
+        <View
+          style={styles.presetsSidebar}
+          accessibilityLabel={labels.selectDateRange}
+          // `listbox` is valid ARIA but absent from RN's Role enum; rn-web forwards it.
+          role={"listbox" as "list"}
+        >
+          {PRESET_IDS.map(renderPreset)}
+        </View>
       )}
 
       {/* Calendar and time pickers */}
@@ -322,7 +341,11 @@ const styles = StyleSheet.create({
     gap: 16,
   },
   presetsSidebar: {
-    minWidth: 140,
+    // 128, not 140: the calendars come to ~617px and a popover is only anchored
+    // (rather than a bottom sheet) at viewports of 768 and up, so the sidebar
+    // has ~135px to spend before the panel is wider than the narrowest screen
+    // that shows it. The longest preset label sits well inside 128.
+    minWidth: 128,
   },
   presetsScrollView: {
     borderTopWidth: 1,
@@ -337,9 +360,6 @@ const styles = StyleSheet.create({
     marginHorizontal: 0,
     marginBottom: 2,
   },
-  presetItemActive: {
-    backgroundColor: colors.zinc["800"],
-  },
   mainContent: {
     flex: 1,
   },

package/src/date_filter_presets.ts

@@ -5,7 +5,6 @@ import type { DateFilterValue } from "./date_filter";
 // `now`, never an ambient clock.
 
 export type PresetId =
-  | "custom"
   | "today"
   | "yesterday"
   | "tomorrow"
@@ -13,7 +12,17 @@ export type PresetId =
   | "this_month"
   | "last_month";
 
-/** Display order. "custom" carries no range — it clears the value. */
+/**
+ * Display order. Every id here SETS a range — that is what makes the list a set
+ * of presets rather than a set of modes.
+ *
+ * "custom" used to sit at the end and it was the one entry that set nothing: it
+ * CLEARED the value. So it lit up whenever the range matched no preset — which
+ * is the normal state for any hand-picked range — and clicking the lit item,
+ * the obvious move for "let me pick my own dates", threw the range away. The
+ * calendar above it is the custom picker, and the panel's Clear button is the
+ * clear; the item was a third name for two controls that were already there.
+ */
 export const PRESET_IDS: PresetId[] = [
   "today",
   "yesterday",
@@ -21,7 +30,6 @@ export const PRESET_IDS: PresetId[] = [
   "this_week",
   "this_month",
   "last_month",
-  "custom",
 ];
 
 function startOfDay(date: Date): Date {
@@ -66,12 +74,11 @@ function range(start: Date, end: Date): DateFilterValue {
 }
 
 /**
- * Resolve a preset to a concrete date range relative to `now`. Returns `null`
- * for "custom" (no range — the caller clears the value so the user picks
- * manually). The boundary math is identical to the view-page filter so a
- * resolved range round-trips back to the same preset.
+ * Resolve a preset to a concrete date range relative to `now`. Total — every
+ * `PresetId` names a range. The boundary math is identical to the view-page
+ * filter so a resolved range round-trips back to the same preset.
  */
-export function getPresetValue(id: PresetId, now: Date): DateFilterValue | null {
+export function getPresetValue(id: PresetId, now: Date): DateFilterValue {
   switch (id) {
     case "today":
       return range(startOfDay(now), endOfDay(now));
@@ -94,7 +101,5 @@ export function getPresetValue(id: PresetId, now: Date): DateFilterValue | null
       d.setMonth(d.getMonth() - 1);
       return range(startOfMonth(d), endOfMonth(d));
     }
-    case "custom":
-      return null;
   }
 }

package/src/locale.tsx

@@ -308,7 +308,7 @@ export const en: LoticsLocale = {
     year: "Year", month: "Month", day: "Day", hour: "Hour", minute: "Minute", dayPeriod: "AM/PM",
     today: "Today", yesterday: "Yesterday", tomorrow: "Tomorrow",
     thisWeek: "This week", thisMonth: "This month", lastMonth: "Last month",
-    custom: "Custom", from: "From", to: "To",
+    from: "From", to: "To",
     selectDateRange: "Select date range", selectDate: "Select date",
     clear: "Clear", done: "Done", placeholder: "All time",
   },
@@ -479,7 +479,7 @@ export const vi: LoticsLocale = {
     year: "Năm", month: "Tháng", day: "Ngày", hour: "Giờ", minute: "Phút", dayPeriod: "SA/CH",
     today: "Hôm nay", yesterday: "Hôm qua", tomorrow: "Ngày mai",
     thisWeek: "Tuần này", thisMonth: "Tháng này", lastMonth: "Tháng trước",
-    custom: "Tùy chọn", from: "Từ", to: "Đến",
+    from: "Từ", to: "Đến",
     selectDateRange: "Chọn khoảng ngày", selectDate: "Chọn ngày",
     clear: "Xóa", done: "Xong", placeholder: "Tất cả thời gian",
   },