@lotics/ui 46.13.0 → 46.14.0

package/AGENTS.md

@@ -17,8 +17,8 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
 | [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; **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), 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, the only one that catches a row whose halves both measure fine and whose text is cut. Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
+| [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), 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). 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. |
 

package/docs/composition.md

@@ -1389,6 +1389,25 @@ reader can see, sort and filter — the column is the fact, the grouping is one
 Ship the column first, offer grouping as a control, and let `TableGroup` render whatever the reader
 picked. Everything below governs how the bands look and behave once they are on.
 
+**"The column is the floor" asks for the fact to be VISIBLE, not for a badge.** A status column
+earns its slot when it carries something the rest of the row cannot produce — a REASON, a name, a
+next step. When the state is already derivable from a neighbour, the badge is a second copy of one
+fact, free to disagree with the first, and it costs a column on every screen to say what the
+reader already read.
+
+The clean discriminator is what the badge would say that the row does not:
+
+- A gate register whose status reads *"paperwork not closed"* keeps its column. No other cell
+  yields that; it is the sentence the operator repeats to the person in front of them.
+- A ticket register pairing two timestamps in one cell (`in → out`) does not. A second timestamp
+  present means closed, absent means open — the state IS the shape of the cell, and an added
+  *Open / Closed* badge restates it in a column's worth of width.
+
+Two things usually carry the state better than a badge, and both are already on the row: the
+INTERVAL cell, where a missing second half is the open case, and the per-row ACTION, which exists
+only in one state and is the more useful signal because it can be pressed. Where the reader needs
+to isolate a state rather than spot it, that is the facet's job, not a column's.
+
 **A value's filter renders the value the same way its cell does.** If the status cell is a
 `Badge variant="dot"`, the status filter's options are dot badges too — same vocabulary, same
 colours, same shapes. Re-rendering it as plain text makes the reader translate between two

package/docs/reviewing.md

@@ -453,7 +453,60 @@ band has only a `SearchInput`.
 → [composition.md](./composition.md) §"Choice, filter & navigation controls"; the rule itself is in
 `src/summary_line.tsx`'s contract.
 
-### 8e. Truncation — every string the layout cut, at the width a phone actually is
+### 8e. Derivable columns — every column another cell already answers
+
+**Measure.** Per column, ask what it would say that its neighbours do not, and try to produce its
+value from them. A column you can compute from the row is not a column; it is a restatement that
+can drift from its source.
+
+The frequent one is a STATUS badge beside an interval: `start → end` already distinguishes open
+from closed, so *Open / Closed* spends a column repeating the shape of the cell next to it. Same
+test for a total beside its parts, a duration beside two timestamps, a "has attachments" tick
+beside a file count.
+
+**Keep it when the badge carries a REASON rather than a state** — "blocked: papers expired" is not
+derivable from any other cell, and it is the sentence the operator reads aloud.
+
+**Signature in the numbers:** a column whose distinct-value count across the register is 2 while a
+neighbouring cell varies with it one-for-one.
+
+→ [composition.md](./composition.md) §"A register that TRIAGES".
+
+### 8f. Does the summary describe WHAT'S SHOWN — press a facet, then re-read it
+
+**Measure.** Record the summary strip's numbers. Press one filter value. Record them again, and
+record how many rows the register now holds.
+
+- The row count changed and **the numbers did not** → the strip is summarising a set the reader
+  cannot see. It is aggregating the raw query rather than the view.
+- Also compare the `y` of the filter controls against the `y` of the strip. Controls must come
+  FIRST: the reader filters, then reads what the filter left.
+
+```js
+const y = (sel) => { const e = document.querySelector(sel); return e ? Math.round(e.getBoundingClientRect().top) : null }
+// facet chips vs the summary strip — chips must be the smaller number
+```
+
+**Why it survives every other check.** Both halves render perfectly, the numbers are real, and
+nothing overflows or errors — the strip is simply answering a question nobody asked. It reads as
+authoritative precisely because it is stated in the same place as the honest version.
+
+**Two shapes it takes, and the second is the one that hides.** A strip computed off the raw query
+never moves. A strip computed off a PARTIALLY filtered set moves for the search box and not for
+the facet, so it looks correct in the first test you run.
+
+**A count the facet already states is a different defect on the same strip** — the chips carry
+counts, so repeating them as summary items is one number in two places, free to disagree. Keep
+the aggregates no control states: the money, the extreme, the ratio.
+
+**Source-side signature:** an aggregate reading the query result (`q.rows`, `data`, the fetch
+hook's array) where the register renders a filtered derivative of it — and the two sitting far
+apart in the file, which is what lets them drift.
+
+→ [composition.md](./composition.md) §"Register / list" — the rule this measures is already
+written there; this probe exists because reading it is not the same as obeying it.
+
+### 8g. Truncation — every string the layout cut, at the width a phone actually is
 
 **Measure.** At 375 (and again at 320), walk every leaf node and compare `scrollWidth` to
 `clientWidth`. Anything wider is being cut, and the page reports no overflow while it happens:

package/package.json

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

package/src/popover.tsx

@@ -20,6 +20,9 @@ import {
   hasModalLayerAbove,
   isInLayerAbove,
   snapshotOpenModalLayers,
+  shouldDismissOnClick,
+  takePointerOrigin,
+  trackPointerOrigin,
 } from "./popover_layers";
 import { PopoverNavContext, type PopoverNavContextValue } from "./popover_nav";
 import { useLoticsLocale } from "./locale";
@@ -403,16 +406,28 @@ export function PopoverContent(props: PopoverContentProps) {
   // filter popover, or a file-preview Modal / Alert opened from within — those are
   // interactions WITH the popover's own flow, not a move away from it. The bottom
   // sheet (`small`) is modal and dismisses via its scrim, so it opts out here.
+  // Gắn một lần cho cả trang, KHÔNG chờ popover mở: cú pointerdown cần nhớ chính
+  // là cú mở popover ra.
+  useEffect(() => trackPointerOrigin(), []);
+
   useEffect(() => {
     if (!open || small) return;
     const onOutsideClick = (e: MouseEvent) => {
-      const node = e.target instanceof Node ? e.target : null;
-      if (!node) return;
-      if (popoverRef.current?.contains(node)) return; // inside my content
-      if (triggerRef.current?.contains(node)) return; // on my trigger — its own press toggles
-      const myLevel = Number(popoverRef.current?.getAttribute("data-popover-level") ?? "0");
-      if (isInLayerAbove(node, myLevel, modalsAtOpenRef.current)) return;
-      onOpenChange(false);
+      if (
+        shouldDismissOnClick({
+          clickTarget: e.target instanceof Node ? e.target : null,
+          // Where the gesture BEGAN. A `click` is dispatched to the common
+          // ancestor of the mousedown and mouseup elements, so a press on the
+          // trigger released over the panel targets NEITHER of them.
+          gestureOrigin: takePointerOrigin(),
+          popover: popoverRef.current,
+          trigger: triggerRef.current,
+          popoverLevel: Number(popoverRef.current?.getAttribute("data-popover-level") ?? "0"),
+          modalsAtOpen: modalsAtOpenRef.current,
+        })
+      ) {
+        onOpenChange(false);
+      }
     };
     document.addEventListener("click", onOutsideClick, true);
     return () => document.removeEventListener("click", onOutsideClick, true);

package/src/popover_layers.ts

@@ -55,3 +55,73 @@ export function hasModalLayerAbove(
   }
   return false;
 }
+
+/**
+ * The element the current pointer gesture STARTED on.
+ *
+ * A popover opens on the pointerdown of the gesture we later have to judge, so a
+ * listener installed once the popover is open has already missed it. One
+ * document-level listener, installed on first use and never removed, is enough
+ * for every popover on the page — and cheaper than one listener per instance.
+ *
+ * Non-DOM hosts (React Native) never install it and always read null, which
+ * degrades to judging a click on its own target — the behaviour before this
+ * existed.
+ */
+let lastPointerDownTarget: Node | null = null;
+let tracking = false;
+
+export function trackPointerOrigin(): void {
+  if (tracking || typeof document === "undefined") return;
+  tracking = true;
+  document.addEventListener(
+    "pointerdown",
+    (e) => {
+      lastPointerDownTarget = e.target instanceof Node ? e.target : null;
+    },
+    true,
+  );
+}
+
+/** Reads the origin and CONSUMES it: one pointerdown feeds one click, so a
+ *  keyboard-driven click that follows sees null and is judged on its own
+ *  target rather than inheriting an unrelated earlier gesture. */
+export function takePointerOrigin(): Node | null {
+  const origin = lastPointerDownTarget;
+  lastPointerDownTarget = null;
+  return origin;
+}
+
+/**
+ * Should an ambient click dismiss this popover?
+ *
+ * The subtlety is `clickTarget`. A browser fires `click` at the nearest COMMON
+ * ANCESTOR of the mousedown and mouseup elements — so a gesture that presses the
+ * trigger and releases over the popover (which opened on pointerdown, under the
+ * cursor) produces a click on neither of them. Judged on that target alone the
+ * popover dismisses itself on the very gesture that opened it, and only when the
+ * two happen to overlap: press where the panel will NOT appear and it behaves,
+ * which is why this reads as intermittent rather than broken.
+ *
+ * So the gesture's ORIGIN counts too. `gestureOrigin` is the last pointerdown
+ * target; pass null for a click with no pointer behind it (a keyboard Enter),
+ * and it falls back to the click target alone.
+ */
+export function shouldDismissOnClick(args: {
+  clickTarget: Node | null;
+  gestureOrigin: Node | null;
+  popover: Element | null;
+  trigger: Element | null;
+  popoverLevel: number;
+  modalsAtOpen: ReadonlySet<Element> | null;
+}): boolean {
+  const { clickTarget, gestureOrigin, popover, trigger, popoverLevel, modalsAtOpen } = args;
+  if (!clickTarget) return false;
+  const mine = (node: Node | null): boolean => {
+    if (!node) return false;
+    if (popover?.contains(node)) return true;
+    if (trigger?.contains(node)) return true;
+    return isInLayerAbove(node, popoverLevel, modalsAtOpen);
+  };
+  return !mine(clickTarget) && !mine(gestureOrigin);
+}