@lotics/ui 34.0.0 → 35.0.0

package/AGENTS.md

@@ -17,7 +17,7 @@ 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, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (the `FilesEditor` COMPOUND — 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, 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; 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, 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/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), 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/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). |
 
 ## Iron rules

package/MIGRATION.md

@@ -4,6 +4,35 @@ 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.
 
+## 35.0.0 — `FilterChip` has no Clear footer; the × is the clear
+
+`FilterChip` no longer renders a Clear button in its popover footer. **Nothing to
+change at a call site** — `onClear` and `clearLabel` are unchanged, and the × on
+the pill still clears, still carries `clearLabel` as its tooltip, and still
+replaces the chevron whenever the chip is active.
+
+**Why.** The pill's × and the footer button did the same thing, and the footer
+cost a whole bordered band to say it twice. The editors this pill exists to wrap
+bring their own bottom actions — an `OptionList` with `enableSelectAll` renders
+"Select all / Deselect all" in a bordered band of its own — so a multi-select
+filter ended with TWO stacked rules, the lower one holding a single button that
+"Deselect all" directly above it already performed. Measured on a live filter:
+bands of 49px and 47px, each with its own 1px top border.
+
+The × is also the more reachable of the two: it is on the pill, which is on
+screen whether or not the popover is open, while the footer button needed the
+panel opened first.
+
+**One behaviour change worth knowing:** passing a custom `footer` no longer
+suppresses the ×. `showClear` used to gate both, so a Save-footer pill silently
+lost its clear — if you were relying on that to hide the ×, pass no `onClear`
+instead, which is what "not clearable" has always meant.
+
+**If your filter had no other way to empty itself**, it still does: the ×. And if
+your editor genuinely needs a clear INSIDE the panel (a range slider, a counter —
+controls with no per-option deselect), put one in the `footer` slot, which is
+still there and is now the only thing that draws a footer band.
+
 ## 34.0.0 — one avatar rung fits a control band
 
 **`AVATAR_PX.md` is 28, not 36.** Nothing to change at a call site — `md` is still

package/docs/catalog.md

@@ -1117,7 +1117,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `isColumnFilterActive` + `columnFilterSummary`: the typed per-column filter pill; for a
   register filtering on several columns.
 - **`filter_chip`** — `FilterChip` + `selectSummary`: the toolbar filter pill hosting a
-  facet (options, a `Slider range`, a `Counter`).
+  facet (options, a `Slider range`, a `Counter`). It draws NO bottom band of its own — the ×
+  on the pill is the clear, and the editor inside brings whatever actions it has, so a
+  multi-select's "select all / deselect all" is the only rule in the panel. `footer` is for an
+  editor that must COMMIT (Cancel / Save); reach for it only then, since it adds a second band
+  under an editor that already has one.
 - **`summary_line`** — `SummaryLine`: the light inline summary of a register/list's FILTERED
   view, sits below the toolbar; NOT the boxed dashboard `kpi_strip` band. Every item is an
   AGGREGATE over the rows in view (a count, a sum, a fill), and the strip goes with the set it

package/docs/composition.md

@@ -397,6 +397,58 @@ so `Table` also serves read-only tabular data (a fee breakdown, a spec sheet), n
 registers. A pressable `TableRow` REQUIRES `accessibilityLabel` ("Open …") — its keyboard door is
 an empty overlay with no content to derive a name from.
 
+**A CELL THAT DOES NOT SET THE ROW'S HEIGHT MUST NOT VARY WITH THE DATA.** A row centres its
+cells, so such a cell's first line lands at `(rowH − cellH) / 2`: one line on some rows and two
+on others puts that first line at two different offsets, and the column stops having a baseline.
+Uniform ROW heights hide it completely — the rows measure identical, the content inside them does
+not — and the drift is against the row's own centred chrome (ordinal, checkbox) as much as
+against the neighbouring columns.
+
+**It takes a height FLOOR to bite**, which is the part worth understanding rather than
+memorising. A `TableRow` with `minHeight` above its tallest cell holds slack that centring then
+distributes; without the floor the tallest cell sets the row, every cell starts at the top of its
+own row, and nothing drifts. So the cell that IS tallest may vary freely — it just makes the rows
+ragged instead, which is a different and far more visible problem. It is the cells living inside
+another cell's slack that have to hold still.
+
+**"Fixed" means the same every row, NOT one line.** A two-line cell is fine if it is two lines on
+every row. And the cost is real: bounding a cell usually means `numberOfLines={1}` and
+truncation, so you are buying a baseline with clipped text. Worth it for an identifier beside a
+contact; think harder for a cell whose job is prose, where the honest answer may be to move that
+content off the register entirely.
+
+Two corollaries, both counter-intuitive enough to state:
+
+- **Shrinking a NEIGHBOURING cell does not fix it.** The spread is a function of the varying
+  cell's own range, not of the row's height: a 20/42 cell spreads 11px in a 52px row and 11px in
+  a 68px one. Only bounding the cell that varies removes it.
+- **The fix is never a cross-axis knob.** `Table` has no `align` (see MIGRATION 32.0.0): topping
+  the cells leaves the chrome centred, so the row reads as scatter instead.
+
+Bound a cell by giving every row the same content, not by hoping the data is uniform. A line that
+appears only when its field is set is the defect; RESERVING the line is the fix — **but only when
+the field is nearly always present.** A box reserved for a value that half the rows lack reads as
+a column that forgot something, which is its own defect: prefer a field the rows actually carry
+(an identifier, a contact) over one that is merely interesting. A cell may hold more than one line
+freely when something FIXED occupies its top — a meter, a thumbnail — because the primary text
+then still lands near the row's centre, where the chrome already is. `tpl_item_list`'s identity
+cell is the worked example: name on top, the supporting values UNCONDITIONALLY beneath.
+
+**A pressable CELL wears `ROW_CONTROL_HOVER` / `ROW_CONTROL_PRESS`, never a hand-picked grey.**
+Reaching a cell means crossing its row, so both wash at once — a cell painting the row's own
+`zinc-100` vanishes under the pointer, and anything LIGHTER reads as a hole punched in the row.
+The tokens are one step darker for exactly that reason, and they are what `IconButton`,
+`CopyButton` and `CommentsButton` already paint, so a register whose cells use them speaks one
+hover language. Bleed the wash outward (`marginHorizontal: -8` against its own padding) so the
+cell's content stays on the column's edge — see `ROW_WASH_BLEED`.
+
+**Size a flexible column by what it CARRIES, measured.** A `flex` share is a claim about content;
+when the content shrinks — a value moves to the record, a stacked pair becomes a count — the
+share left behind is white space, and the columns beside it pay for it. Measure the widest row's
+content per column and set `flex` from that. A column whose cell holds a PROPORTION (a meter, a
+bar) is the exception in one direction only: cap it, because a gauge stops reading as an
+instrument once its track is long enough to be a rule across the row.
+
 Make a register SELECTABLE with the `Table` `leading` gutter + `selectAll` slot — a
 `CheckboxInput` per `TableRow` (its `leading` slot) + a select-all in the header band, the ticked
 rows `marked`, paired with a `FloatingActionBar` (its "Clear" escape is locale-resolved — pass

package/examples/tpl_item_list.tsx

@@ -237,7 +237,16 @@ function HoSoRow({ hs, ordinal, daThu, selected, marked, selectable, onToggle, o
               because it is the one value copied often enough to earn one (a desk
               pastes it into a message, a rep dials it). The verb rides the value
               inside its own cell: the trailing gutter belongs to the ⋯, and with
-              two values in this cell it would have nothing to name. */}
+              two values in this cell it would have nothing to name.
+
+              UNCONDITIONAL, and that is the load-bearing part of this shape. A
+              row centres its cells, so a supporting line that appears only when
+              its field is set makes this cell two heights, and the NAME above it
+              then sits at two different offsets down the column while every row
+              still measures the same. That is why the values here are ones every
+              record carries — a key, a contact — rather than whichever field is
+              most interesting: the line has to be honest on every row to be
+              reservable at all. */}
           <View style={{ flexDirection: "row", alignItems: "center", gap: 2 }}>
             {/* The KEY, muted, on the supporting line — at most this, never a
                 column and never the row's name.
@@ -250,8 +259,13 @@ function HoSoRow({ hs, ordinal, daThu, selected, marked, selectable, onToggle, o
                 gives way, which is also the right order of loss: the phone has a
                 Copy control beside it that hands over the full value regardless. */}
             <Text size="xs" color="muted" tabular numberOfLines={1} style={{ flexShrink: 0 }}>{hs.ma}</Text>
-            <Text size="xs" color="muted" style={{ flexShrink: 0 }}> · </Text>
-            <Text size="xs" color="muted" tabular numberOfLines={1} style={{ flexShrink: 1 }}>{hs.dienThoai}</Text>
+            {/* A GAP, not a middot. Two facts of different kinds sat either side
+                of a ` · ` here, which is the separator this kit bans outright —
+                punctuation claiming a relation it refuses to name, and dropped
+                entirely by a screen reader. Spacing separates them without
+                asserting anything, and the two are already told apart by shape:
+                one is a key, one is a number with a Copy control on it. */}
+            <Text size="xs" color="muted" tabular numberOfLines={1} style={{ flexShrink: 1, marginLeft: 8 }}>{hs.dienThoai}</Text>
             <CopyButton value={hs.dienThoai} label="Copy phone number" />
           </View>
         </View>

package/package.json

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

package/src/filter_chip.tsx

@@ -7,7 +7,6 @@ import { Chip } from "./chip";
 import { Popover, PopoverTrigger, PopoverContent, PopoverFooter } from "./popover";
 import type { PopoverSide, PopoverAlign } from "./popover";
 import { useLoticsLocale } from "./locale";
-import { Button } from "./button";
 
 export interface FilterChipProps {
   /** The dimension name — shown alone when inactive ("Owner"), prefixed when
@@ -18,10 +17,12 @@ export interface FilterChipProps {
    *  selection RICHLY in the trigger (member avatars, colour dots). Empty /
    *  undefined renders the inactive pill (label + chevron, no clear). */
   summary?: ReactNode;
-  /** Clears the dimension — renders the × on the pill AND a Clear in the popover
-   *  footer whenever a summary is present. */
+  /** Clears the dimension — renders the × on the pill whenever a summary is
+   *  present. The × is the ONLY clear: the editor inside brings its own bottom
+   *  actions, and a second clear in the popover footer stacked a redundant band
+   *  under them. */
   onClear?: () => void;
-  /** Label for the clear affordances (pass a translated string). */
+  /** Tooltip on the pill's × (pass a translated string). */
   clearLabel?: string;
   /** The editor revealed on press — a premium primitive (`Slider range`,
    *  `Counter`, `OptionList` multi) or any composed control. `FilterChip` owns
@@ -35,8 +36,11 @@ export interface FilterChipProps {
   /** Optional controlled popover state — for an editor that closes on Save. */
   open?: boolean;
   onOpenChange?: (open: boolean) => void;
-  /** A custom popover footer (e.g. Cancel / Save) — replaces the baked Clear.
-   *  Lets a non-filter VALUE pill (a setting gate) reuse the same shell. */
+  /** A custom popover footer (e.g. Cancel / Save) — for an editor that commits
+   *  rather than applying live. Lets a non-filter VALUE pill (a setting gate)
+   *  reuse the same shell. Reach for it only when the editor NEEDS a commit: an
+   *  editor that already carries bottom actions of its own gets a second
+   *  bordered band from this. */
   footer?: ReactNode;
 }
 
@@ -61,9 +65,11 @@ export function selectSummary(
  * filter dimension, the sibling of `ChipGroup` (which lays ONE hot dimension's
  * options out inline). Many dimensions stay scannable because each collapses to
  * a single pill: inactive reads "Label ⌄", active reads "Label: summary" with an
- * × to clear. `FilterChip` bakes the consistent chrome — the preview pill, a
- * padded popover body for the composed editor, and a Clear footer when active —
- * so every filter looks and behaves the same. Drop a premium primitive inside
+ * × to clear. `FilterChip` bakes the consistent chrome — the preview pill and a
+ * padded popover body for the composed editor — so every filter looks and
+ * behaves the same. It adds NO bottom band of its own: the editor inside brings
+ * whatever actions it has, and a shell that also contributed one gave every
+ * multi-select filter two stacked rules. Drop a premium primitive inside
  * (`Slider range`, `Counter`, `OptionList` multi). With `footer` (+ controlled
  * `open`/`onOpenChange`) the same shell wraps a non-filter VALUE pill — a
  * setting gate with Cancel/Save — keeping it on the one pill surface. The table
@@ -73,9 +79,23 @@ export function FilterChip(props: FilterChipProps) {
   const { label, summary, onClear, children, side = "bottom", align = "start", open, onOpenChange, footer } = props;
   const clearLabel = props.clearLabel ?? useLoticsLocale().filterChip.clear;
   const active = summary != null && (typeof summary !== "string" || summary.length > 0);
-  // The clear × / Clear footer only when there's a clearable selection AND no
-  // custom footer — a valued, non-clearable pill ("Target: 20") keeps its chevron.
-  const showClear = active && !!onClear && !footer;
+  // THE × IS THE CLEAR, and it is the only one. A valued, non-clearable pill
+  // ("Target: 20") keeps its chevron.
+  //
+  // There used to be a baked Clear in the popover footer as well, and it was a
+  // duplicate that cost a whole extra band. The editors this pill is built for
+  // bring their own bottom actions — an `OptionList` with `enableSelectAll`
+  // renders "Select all / Deselect all" in a bordered band of its own — so the
+  // popover ended with TWO stacked rules whose lower one held a single button
+  // that "Deselect all" directly above it already performed. Measured on a live
+  // filter: bands at 49px and 47px, each with its own 1px top border.
+  //
+  // The × is also the more discoverable of the two: it sits on the pill, which
+  // is on screen whether or not the popover is open, and it carries `clearLabel`
+  // as its tooltip. The footer button was reachable only by opening the panel
+  // first. A custom `footer` (Cancel / Save) no longer suppresses it either —
+  // that coupling meant a Save-footer pill silently lost its clear.
+  const showClear = active && !!onClear;
 
   // Own the open state so the editor can close itself via the render-prop
   // `close`, while still honoring a controlled `open`/`onOpenChange` from the
@@ -112,13 +132,7 @@ export function FilterChip(props: FilterChipProps) {
       </PopoverTrigger>
       <PopoverContent style={styles.body} disableBodyScroll>
         {typeof children === "function" ? children({ close: () => setOpen(false) }) : children}
-        {footer ? (
-          <PopoverFooter>{footer}</PopoverFooter>
-        ) : showClear ? (
-          <PopoverFooter align="start">
-            <Button title={clearLabel} color="muted" onPress={onClear} />
-          </PopoverFooter>
-        ) : null}
+        {footer ? <PopoverFooter>{footer}</PopoverFooter> : null}
       </PopoverContent>
     </Popover>
   );
@@ -126,9 +140,9 @@ export function FilterChip(props: FilterChipProps) {
 
 const styles = StyleSheet.create({
   // The popover hugs its content — a wide control (e.g. Slider) sets its
-  // OWN fixed width; the shell never forces one. No extra padding: the editor and
-  // the Clear footer then share the popover's own 8px inset, so a multi-select's
-  // options, its select-all, and the Clear all line up on one left edge.
+  // OWN fixed width; the shell never forces one. No extra padding: the editor
+  // then sits on the popover's own 8px inset, so a multi-select's options and
+  // its select-all band line up on one left edge.
   body: {
     gap: 8,
   },