@lotics/ui 47.1.1 → 47.2.1

package/MIGRATION.md

@@ -1,8 +1,47 @@
 # @lotics/ui — migration notes
 
 Breaking changes, newest first — normally per major, plus the rare minor that broke a type
-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.
+anyway (recorded under its exact version), **and a minor that changes what an existing call site
+LOOKS LIKE with no code change**. That last kind needs an entry precisely because nothing forces
+the author to read one: their screens shift on an `npm update` and they have nothing to attribute
+it to, so they revert or file a bug. The current contract lives in `AGENTS.md` + `docs/`; this
+file exists only to move an app from one release to the next.
+
+## 47.1.0
+
+**No API breaks and no action required — but four things change what an existing screen looks
+like.** All four are fixes to a component asserting something it could not know, so the new
+rendering is the correct one; they are listed so nobody spends an afternoon on them.
+
+- **`ProgressBar`'s compact caption is muted at every ratio.** It used to paint `success` at
+  ≥ 100%. A meter can mean "done" (a task, an upload) or "used up" (a credit limit, a quota), and
+  the same 100% is good in one and bad in the other — so every usage-against-a-cap meter drew a red
+  bar with a green number beside it. The verdict now lives only where the caller states it: the
+  FILL, via `completeColor`. A task meter that wants a green number renders its own caption
+  (`format="none"` plus your text).
+- **`Breakdown`'s value is `medium` and `StackedBarChart`'s label is `regular`.** They draw the same
+  row — label left, right-aligned figure, proportion bar — and disagreed about weight, so a card
+  placing them side by side made one read as more important for no stated reason. One rule now: the
+  label names the series and stays regular, the figure carries the weight, and `semibold` stays
+  reserved for selection.
+- **A disabled `MenuButton` now looks disabled.** It blocked the press and announced
+  `aria-disabled` while rendering at full ink, so a blocked item was pixel-identical to a live one.
+  If you were hiding items rather than disabling them to work around this, you can stop.
+- **`ChargeLines`' narrow quantity slot is 60px (was 48).** `28,9` needed 33px in the 30 available
+  and clipped. Slightly less room for the price column in the narrow fork.
+
+Two smaller layout corrections in the same release: `Finding`'s readings stretch instead of
+shrink-wrapping past their column, and `RecordSummary`'s identity row wraps rather than letting the
+title shrink while the metric keeps full width.
+
+**New, all additive and defaulted to the previous behaviour:** `TableColumn.lead` (declare the
+fixed chrome inside a flexible cell, so the fit's read floor is for the TEXT — pass it wherever you
+put a mark in the subject cell), `MemberChip.showAvatar` (`false` where the member is one field
+among columns rather than the row's subject), `InlineStatic.actions` and `InlineSlot.actions` (a
+verb about a read-only value, on the value's own surface), `ChargeLines.formatQuantity`
+(band-level, like `formatMoney` — without it the kit printed `28.9` in a locale that writes
+`28,9`), `ThumbnailStack.decorative` (silence the marks where the row already names the thing),
+and `FormTextInput` now forwards `optionalLabel`, which it previously accepted and dropped.
 
 ## 47.0.0
 

package/docs/catalog.md

@@ -1712,6 +1712,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`column_filter`** — `ColumnFilter` + `columnFilterToConditions` +
   `isColumnFilterActive` + `columnFilterSummary`: the typed per-column filter pill; for a
   register filtering on several columns.
+- **`filter_band`** — `FilterBand`: the toolbar ROW above a list — search, the `FilterChip`s,
+  and the screen's primary action. **On a small screen the chips collapse into one `Filters (n)`
+  button** that opens a sheet where the same chips render as full-width disclosure rows, one
+  editor open at a time. Laid out inline, a search box plus five chips plus a segmented control
+  is three wrapped rows; on a 390px phone that is most of the viewport spent before the first
+  record. Search and the action never collapse — both are on the shortest path to what someone
+  opened the screen for. Pass `activeCount` so the collapsed button still says the list is
+  filtered, and `onClearAll` to put one clear in the sheet. Compose the band with this rather
+  than a hand-rolled `<View flexDirection="row">`: a hand-rolled band is the one that does not
+  collapse.
 - **`filter_chip`** — `FilterChip` + `selectSummary`: the toolbar filter pill hosting a
   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

package/docs/data_entry.md

@@ -83,6 +83,15 @@ already has: errors arrive from a validate pass, and editing a field clears that
 
 ## A picker over a select FIELD keeps the field's colours — `optionPicker`
 
+**First, the precondition nobody states: the field's colours have to MEAN something.** A platform
+that auto-assigns option colours does it **by position** — the first option blue, then green,
+amber, red, purple, teal — so a field whose options were created without colours carries a
+sequence nobody chose. Propagate that faithfully and you ship the accident consistently: measured
+on a real workspace, the same rule would have painted an in-transit order **red** and a customer on
+delivery hold **green**, inches from the control that decides whether to keep delivering to them.
+So: set the colours on the FIELD, semantically, then carry them everywhere. Carrying an
+auto-assigned default is worse than plain text, because plain text does not assert anything.
+
     <InlineSelect {...optionPicker(fields.city?.options ?? [])}                    // a category
                   value={cityKey} onSave={(v) => save({ city: v })} />
     <InlineSelect {...optionPicker(fields.status?.options ?? [], { badge: "dot" })} // a status

package/docs/reviewing.md

@@ -560,6 +560,23 @@ on a defect that does not exist. Walk the surface with real `Tab` presses and re
 `box-shadow` at each stop; `.focus()` is only good for asking what CAN take focus, never for how it
 looks when it does.
 
+### 9b. One VALUE, one treatment — the cross-shape check
+Probe 1 asks "same shape → same treatment", which groups filter chips with filter chips and table
+cells with table cells, finds each group internally consistent, and passes. The defect it cannot
+see is **one datum reading two ways across shapes**: a stage drawn as a coloured badge in the
+register and as plain text in the filter that selects it, on the same screen.
+
+**Collect**, per select field: every surface its value renders on — register cell, filter chip and
+its dropdown, drawer, record field at rest and editing, picker option, diff row, summary line,
+chart legend — and the colour each one paints. **The signature** is one field whose renders
+disagree: some coloured, some plain, or two different colours for one key.
+
+Two causes, both silent. The picker's own option shape has no colour member, so the obvious
+adapter drops it and compiles; and a hand-written key→colour map beside the field's own colours is
+a second copy free to disagree — check it against the FIELD, not against itself.
+
+→ [data_entry.md](./data_entry.md) §"A picker over a select FIELD keeps the field's colours".
+
 ### 10. Microcopy
 - **No punctuation doing a word's job.** ` · ` is banned outright — it claims a relationship while
   refusing to name it, and it is the loudest templated-metadata tell there is. If a mark cannot be

package/docs/templates.md

@@ -386,8 +386,11 @@ The corollaries, each of which a register is routinely missing:
   information — a badge that shows nothing for a row missing its invoice is exactly the column
   that earns its width.
 
-- **One toolbar row** — search + a status `Select` + facet `FilterChip`s LEFT, the New CTA
-  RIGHT; then a light `SummaryLine` of the filtered view BELOW it, above the rows.
+- **One toolbar row, built with `FilterBand`** — search + a status `Select` + facet `FilterChip`s LEFT,
+  the New CTA RIGHT. **Use `FilterBand` rather than a hand-rolled `<View flexDirection="row">`**: on a
+  phone it collapses the facets into one `Filters (n)` button and a sheet, and a hand-rolled band is the
+  one that does not — inline, this row is three wrapped lines at 390px and eats the screen before the
+  first record. Search and the CTA stay on the band at every width; then a light `SummaryLine` of the filtered view BELOW it, above the rows.
   **Search is ALWAYS the leftmost control**, and the order after it is stated rather than left to
   the author: search, then the scope the rest of the row filters WITHIN (a site, an account, a
   period), then the facets. Search is the one control every register carries and the one a reader

package/examples/tpl_item_list.tsx

@@ -28,6 +28,7 @@ import { Pagination } from "@lotics/ui/pagination";
 import { Table, TableRow, TableCell, type TableColumn } from "@lotics/ui/table";
 import { SearchInput } from "@lotics/ui/search_input";
 import { Select } from "@lotics/ui/select";
+import { FilterBand } from "@lotics/ui/filter_band";
 import { FilterChip, selectSummary } from "@lotics/ui/filter_chip";
 import { ColumnFilter, type ColumnFilterValue } from "@lotics/ui/column_filter";
 import { OptionList } from "@lotics/ui/option_list";
@@ -1245,21 +1246,25 @@ export function TplItemList() {
 
         {/* toolbar — search + consolidated filters LEFT, New case RIGHT, one row.
             A search is present, so status is a dropdown (Select), not pills.
-
-            `flex-start`, not `center`: the filter block wraps to two or three
-            lines on a phone, and centring floats the CTA against the whole
-            wrapped block — measured landing level with the SECOND row of chips,
-            anchored to nothing. The band's top edge is what it belongs to. */}
-        <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 8 }}>
-          <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 8, alignItems: "center", flex: 1 }}>
-            <View style={{ flexGrow: 1, flexBasis: 220, minWidth: 200, maxWidth: 340 }}>
-              <SearchInput
-                placeholder="Search by ID, name, or phone…"
-                value={search}
-                onChangeText={doiTimKiem}
-                accessibilityLabel="Search records"
-              />
-            </View>
+            `FilterBand` owns the row. On a phone it collapses the filters into a
+            single `Filters (n)` button and a sheet, so search and the CTA stay on
+            one line. This row used to wrap to two or three lines there, which also
+            left the CTA anchored to nothing — centred, it floated against the whole
+            wrapped block and landed level with the SECOND row of chips. Collapsing
+            the filters removes the wrap, and the alignment question with it. */}
+        <FilterBand
+          activeCount={[assignee.length > 0, feeStatus != null, feeAmount != null].filter(Boolean).length}
+          onClearAll={() => { setAssignee([]); setFeeStatus(null); setFeeAmount(undefined); resetPaging(); }}
+          action={<Button title="Enter data" color="primary" onPress={openIntake} />}
+          search={
+            <SearchInput
+              placeholder="Search by ID, name, or phone…"
+              value={search}
+              onChangeText={doiTimKiem}
+              accessibilityLabel="Search records"
+            />
+          }
+        >
             <Select
               placeholder="Status"
               options={TABS.map((t) => ({
@@ -1310,11 +1315,7 @@ export function TplItemList() {
               value={feeAmount}
               onChange={(v) => { setFeeAmount(v); resetPaging(); }}
             />
-          </View>
-          {/* the intake TRIGGER — the register's whole-surface drop/paste opens
-              the same dialog (see the FileDropTarget wrapper below) */}
-          <Button title="Enter data" color="primary" onPress={openIntake} />
-        </View>
+        </FilterBand>
 
         {/* THE SUMMARY READS THE FILTERED SET, so it sits BELOW the controls that
             produce it. These figures move every time the reader touches a chip:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "47.1.1",
+  "version": "47.2.1",
   "type": "module",
   "exports": {
     "./accordion": "./src/accordion.tsx",
@@ -113,6 +113,7 @@
     "./file_thumbnail": "./src/file_thumbnail.tsx",
     "./file_thumbnail_grid": "./src/file_thumbnail_grid.tsx",
     "./files_editor": "./src/files_editor.tsx",
+    "./filter_band": "./src/filter_band.tsx",
     "./filter_chip": "./src/filter_chip.tsx",
     "./finding": "./src/finding.tsx",
     "./floating_action_bar": "./src/floating_action_bar.tsx",

package/src/filter_band.tsx

@@ -0,0 +1,103 @@
+import { createContext, useContext, useState, type ReactNode } from "react";
+import { View } from "react-native";
+import { Button } from "./button";
+import { Dialog, DialogFooter, DialogHeader, DialogHeaderTitle, DialogScrollArea } from "./dialog";
+import { SPACE } from "./spacing";
+import { useLoticsLocale } from "./locale";
+import { useScreenSize } from "./use_screen_size";
+
+interface FilterBandContextValue {
+  /** How a `FilterChip` inside this band should render itself. */
+  presentation: "chip" | "row";
+}
+
+const FilterBandContext = createContext<FilterBandContextValue | null>(null);
+
+/** How the nearest enclosing `FilterBand` wants its filters drawn. `"chip"`
+ *  outside a band, so a lone `FilterChip` is unaffected. */
+export function useFilterBandPresentation(): "chip" | "row" {
+  return useContext(FilterBandContext)?.presentation ?? "chip";
+}
+
+export interface FilterBandProps {
+  /** The search control. Stays on the band at every width — it is the one
+   *  filter people reach for without thinking. */
+  search?: ReactNode;
+  /** The band's primary action. Stays visible at every width, because a screen
+   *  whose only verb is behind a filter sheet reads as read-only. */
+  action?: ReactNode;
+  /** How many dimensions are filtering right now — badges the collapsed
+   *  button, so a narrow screen still says the list is not showing everything. */
+  activeCount?: number;
+  /** Clears every dimension at once. Rendered inside the sheet when given. */
+  onClearAll?: () => void;
+  /** The `FilterChip`s. */
+  children: ReactNode;
+  testID?: string;
+}
+
+/**
+ * The toolbar row above a list: search, the secondary filter dimensions, and
+ * the screen's primary action.
+ *
+ * **On a narrow screen the dimensions collapse into ONE button.** Laid out
+ * inline, a search box plus five chips plus a segmented control is three
+ * wrapped rows — on a 390px phone that is most of the viewport spent before a
+ * single record, which is what this component exists to prevent. Collapsed, the
+ * band is one row: search, a `Filters (n)` button, and the action. The chips
+ * move into a sheet and render as full-width rows there, one editor open at a
+ * time — the SAME `FilterChip`s, re-presented, so a filter never has two
+ * implementations to keep in step.
+ *
+ * Search and the action never collapse. Both are one tap on the shortest path
+ * to what someone opened the screen for, and burying either behind a sheet
+ * costs more than the row it saves.
+ */
+export function FilterBand(props: FilterBandProps) {
+  const { search, action, activeCount = 0, onClearAll, children, testID } = props;
+  const t = useLoticsLocale().filterBand;
+  const { small } = useScreenSize();
+  const [open, setOpen] = useState(false);
+
+  if (!small) {
+    return (
+      <View
+        testID={testID}
+        style={{ flexDirection: "row", alignItems: "center", gap: SPACE.sm, flexWrap: "wrap" }}
+      >
+        {search != null && (
+          <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: 220, minWidth: 180, maxWidth: 320 }}>{search}</View>
+        )}
+        <FilterBandContext.Provider value={{ presentation: "chip" }}>{children}</FilterBandContext.Provider>
+        {action != null && <View style={{ marginLeft: "auto" }}>{action}</View>}
+      </View>
+    );
+  }
+
+  return (
+    <View testID={testID} style={{ flexDirection: "row", alignItems: "center", gap: SPACE.sm }}>
+      {search != null && <View style={{ flexGrow: 1, flexShrink: 1, minWidth: 0 }}>{search}</View>}
+      <Button
+        color="secondary"
+        title={activeCount > 0 ? `${t.filters} (${activeCount})` : t.filters}
+        onPress={() => setOpen(true)}
+        testID={testID ? `${testID}-filters` : undefined}
+      />
+      {action}
+      <Dialog open={open} onOpenChange={setOpen} width="92%" maxWidth={520}>
+        <DialogHeader>
+          <DialogHeaderTitle>{t.filters}</DialogHeaderTitle>
+        </DialogHeader>
+        <DialogScrollArea>
+          <FilterBandContext.Provider value={{ presentation: "row" }}>{children}</FilterBandContext.Provider>
+        </DialogScrollArea>
+        <DialogFooter>
+          {onClearAll != null && activeCount > 0 && (
+            <Button color="muted" title={t.clearAll} onPress={onClearAll} />
+          )}
+          <Button title={t.done} onPress={() => setOpen(false)} />
+        </DialogFooter>
+      </Dialog>
+    </View>
+  );
+}

package/src/filter_chip.tsx

@@ -7,6 +7,8 @@ import { Chip } from "./chip";
 import { Popover, PopoverTrigger, PopoverContent, PopoverFooter } from "./popover";
 import type { PopoverSide, PopoverAlign } from "./popover";
 import { useLoticsLocale } from "./locale";
+import { useFilterBandPresentation } from "./filter_band";
+import { Pressable } from "react-native";
 
 export interface FilterChipProps {
   /** The dimension name — shown alone when inactive ("Owner"), prefixed when
@@ -103,6 +105,7 @@ export function FilterChip(props: FilterChipProps) {
   // Own the open state so the editor can close itself via the render-prop
   // `close`, while still honoring a controlled `open`/`onOpenChange` from the
   // parent (the Save-footer VALUE-pill case).
+  const presentation = useFilterBandPresentation();
   const [internalOpen, setInternalOpen] = useState(false);
   const isOpen = open ?? internalOpen;
   const setOpen = (next: boolean) => {
@@ -110,6 +113,41 @@ export function FilterChip(props: FilterChipProps) {
     onOpenChange?.(next);
   };
 
+  // Inside a COLLAPSED `FilterBand` the pill is the wrong shape: a sheet is a
+  // vertical list, and a row of pills in it wraps exactly the way the band did
+  // on the screen this collapse exists to fix. Same component, same state, same
+  // editor — re-presented as a full-width disclosure row.
+  if (presentation === "row") {
+    return (
+      <View style={styles.row}>
+        <Pressable
+          testID={testID}
+          onPress={() => setOpen(!isOpen)}
+          accessibilityRole="button"
+          aria-expanded={isOpen}
+          style={styles.rowHeader}
+        >
+          <Text size="sm" weight="medium" color="zinc-700">{label}</Text>
+          <View style={styles.rowRight}>
+            {active ? (
+              typeof summary === "string" ? (
+                <Text size="sm" numberOfLines={1} style={{ color: colors.accent }}>{summary}</Text>
+              ) : (
+                summary
+              )
+            ) : null}
+            <Icon name={isOpen ? "chevron-up" : "chevron-down"} size={14} color={colors.zinc["400"]} />
+          </View>
+        </Pressable>
+        {isOpen ? (
+          <View style={styles.rowBody}>
+            {typeof children === "function" ? children({ close: () => setOpen(false) }) : children}
+          </View>
+        ) : null}
+      </View>
+    );
+  }
+
   return (
     <Popover side={side} align={align} open={isOpen} onOpenChange={setOpen}>
       <PopoverTrigger>
@@ -164,4 +202,24 @@ const styles = StyleSheet.create({
     alignItems: "center",
     gap: 5,
   },
+  row: {
+    borderTopWidth: StyleSheet.hairlineWidth,
+    borderTopColor: colors.zinc["200"],
+  },
+  rowHeader: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: 12,
+    paddingVertical: 14,
+  },
+  rowRight: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+    flexShrink: 1,
+  },
+  rowBody: {
+    paddingBottom: 12,
+  },
 });

package/src/locale.tsx

@@ -68,6 +68,7 @@ export interface LoticsLocale {
   /** `FilterChip` (and `ColumnFilter`): the generic clear affordance, used when
    *  a call site doesn't pass a dimension-specific `clearLabel`. */
   filterChip: { clear: string };
+  filterBand: { filters: string; clearAll: string; done: string };
   /** `FloatingActionBar`: the escape that drops the selection. The COUNT's noun is
    *  the call site's `label` (it names the rows), so only the escape lives here. */
   floatingActionBar: { clear: string };
@@ -348,6 +349,7 @@ export const en: LoticsLocale = {
     empty: "Nothing scheduled",
   },
   filterChip: { clear: "Clear" },
+  filterBand: { filters: "Filters", clearAll: "Clear all", done: "Done" },
   floatingActionBar: { clear: "Clear" },
   formField: { optional: "Optional" },
   dangerZone: { title: "Danger zone" },
@@ -567,6 +569,7 @@ export const vi: LoticsLocale = {
     empty: "Chưa có việc nào",
   },
   filterChip: { clear: "Xóa" },
+  filterBand: { filters: "Bộ lọc", clearAll: "Xoá lọc", done: "Xong" },
   floatingActionBar: { clear: "Bỏ chọn" },
   formField: { optional: "Tùy chọn" },
   dangerZone: { title: "Vùng nguy hiểm" },