@lotics/ui 7.8.0 → 7.10.0

package/src/kpi_strip.tsx

@@ -34,11 +34,11 @@ export interface KPIStripProps {
 }
 
 /**
- * THE stat band at the top of a screen — one Card, hairline-divided columns
- * of KPICard with a uniform value scale. Screens must not hand-compose stat
- * strips: the same four-numbers-in-a-row should look identical on a
- * dashboard, an inventory register, or a payroll page. Wraps on narrow
- * screens (columns keep a 180px floor).
+ * THE dashboard stat band — one Card, hairline-divided columns of KPICard with a
+ * uniform value scale, at the TOP of a DASHBOARD page. It is NOT for register /
+ * list pages: a list summarizes the FILTERED view with the light inline
+ * `SummaryLine` below its toolbar, never this boxed metric grid. Screens must
+ * not hand-compose stat bands. Wraps on narrow screens (columns keep a 180px floor).
  */
 export function KPIStrip(props: KPIStripProps) {
   const { items, size = "lg" } = props;

package/src/pressable_row.tsx

@@ -11,16 +11,19 @@ export interface PressableRowProps {
    *  it's the resting state of a ticked row in a bulk-select register. */
   marked?: boolean;
   /**
-   * - "bleed" (default): the standalone REGISTER row — px-20, square wash to
-   *   the card edges, separated by full-bleed `Divider`s. The one pattern for
-   *   top-level record lists.
+   * - "register" (THE record-list default): a rounded row whose hover/open/`marked`
+   *   wash spans the FULL row width (incl. nested controls); content stays on the
+   *   20px column gutter so a `Table` header and its cells still align. The `Table`
+   *   separates rows with a `Divider` (the wash is the hover/selection state, the
+   *   hairline the resting separation) — every app inherits this register look.
+   * - "bleed" (legacy): px-20, square wash to the edges, `Divider`-separated.
+   *   The pre-rounded register row — kept for an edge-to-edge data grid that
+   *   genuinely wants hard rules, not the floating default.
    * - "inset": a rounded, contained row — the wash is a rounded pill pulled in
    *   from the edge (radius 8, marginH -8). Lives inside a padded container (an
-   *   `Accordion`'s drill-down rows, or a gap-separated selectable list) so the
-   *   wash insets from the card edge instead of bleeding to it. Use when rows are
-   *   GAP-separated rather than `Divider`-separated.
+   *   `Accordion`'s drill-down rows, or a gap-separated selectable list).
    */
-  variant?: "bleed" | "inset";
+  variant?: "register" | "bleed" | "inset";
   /** Cells + trailing controls. Nested pressables (CTAs, checkboxes, ⋯)
    * claim their own presses; put the accessible door inside — a plain
    * `Pressable` with role="button" + "Open …" label around the row body. */
@@ -42,7 +45,7 @@ export interface PressableRowProps {
  * `variant` picks bleed (registers) or inset (Accordion drill-down rows).
  */
 export function PressableRow(props: PressableRowProps) {
-  const { onPress, selected = false, marked = false, variant = "bleed", children, style } = props;
+  const { onPress, selected = false, marked = false, variant = "register", children, style } = props;
   const [hovered, setHovered] = useState(false);
 
   // RN's types don't declare mouse handlers; react-native-web forwards them
@@ -62,7 +65,7 @@ export function PressableRow(props: PressableRowProps) {
       {...mouseProps}
       style={({ pressed }) => [
         styles.row,
-        variant === "inset" ? styles.inset : styles.bleed,
+        variant === "inset" ? styles.inset : variant === "bleed" ? styles.bleed : styles.register,
         {
           backgroundColor: pressed ? colors.zinc[200] : selected ? colors.zinc[100] : hovered ? colors.zinc[100] : marked ? colors.blue[50] : undefined,
         },
@@ -81,7 +84,16 @@ const styles = StyleSheet.create({
     gap: 12,
     ...({ cursor: "pointer", userSelect: "none", transitionDuration: "0.1s", transitionProperty: "background-color" } as ViewStyle),
   },
-  // Square, full-bleed — lines up with the Dividers between register rows.
+  // THE register row — FULL-WIDTH rounded highlight. The hover/selected wash
+  // spans the entire row (so the pressable area === the row, never narrower than
+  // the dividers around it) and rounds (radius 10); content sits on the 20px
+  // column gutter so a Table header + cells align. The Divider between rows (the
+  // Table renders it) is the resting separation; this wash is the hover state.
+  register: {
+    borderRadius: 10,
+    paddingHorizontal: 20,
+  },
+  // Square, full-bleed — lines up with the Dividers between register rows. Legacy.
   bleed: {
     paddingHorizontal: 20,
   },

package/src/sort_header.tsx

@@ -77,18 +77,23 @@ export function SortHeader(props: SortHeaderProps) {
   const { label, sortKey, sort, onSort, align = "left", style, labels } = props;
   const loc = useLoticsLocale().sortHeader;
   const active = sort?.key === sortKey;
-  const arrow = active ? (sort.dir === "asc" ? "chevron-up" : "chevron-down") : undefined;
+  // Always show a sort glyph so every sortable column READS as sortable — a faint
+  // up/down hint at rest, the solid direction chevron once active. (Before, the
+  // affordance only appeared after sorting, so columns looked un-sortable.)
+  const glyph = active ? (sort.dir === "asc" ? "chevron-up" : "chevron-down") : "chevrons-up-down";
+  const glyphColor = active ? colors.zinc[600] : colors.zinc[400];
   const dirText = active ? (sort.dir === "asc" ? (labels?.ascending ?? loc.ascending) : (labels?.descending ?? loc.descending)) : "";
   const sortByLabel = (labels?.sortBy ?? loc.sortBy)(label);
 
   return (
     <PressableHighlight
-      focusRing      accessibilityRole="button"
+      focusRing
+      accessibilityRole="button"
       accessibilityLabel={`${sortByLabel}${dirText}`}
       onPress={() => onSort(sortKey)}
       style={[styles.header, align === "right" ? styles.right : null, style]}
     >
-      {align === "right" && arrow ? <Icon name={arrow} size={12} color={colors.zinc[500]} /> : null}
+      {align === "right" ? <Icon name={glyph} size={12} color={glyphColor} /> : null}
       <Text
         size="xs"
         color={active ? "default" : "muted"}
@@ -98,7 +103,7 @@ export function SortHeader(props: SortHeaderProps) {
       >
         {label}
       </Text>
-      {align === "left" && arrow ? <Icon name={arrow} size={12} color={colors.zinc[500]} /> : null}
+      {align === "left" ? <Icon name={glyph} size={12} color={glyphColor} /> : null}
     </PressableHighlight>
   );
 }

package/src/summary_line.tsx

@@ -0,0 +1,76 @@
+import { StyleSheet, View } from "react-native";
+import { Text } from "./text";
+import { Metric, type MetricFormat, type MetricTone } from "./metric";
+import { TrendChip } from "./trend_chip";
+import { InfoPopover } from "./info_popover";
+
+export interface SummaryLineItem {
+  /** Label that reads AFTER the value ("below minimum", "stock value"). */
+  label: string;
+  value: number | string | null | undefined;
+  format?: MetricFormat;
+  currency?: string;
+  locale?: string;
+  emptyLabel?: string;
+  tone?: MetricTone;
+  /** Abbreviate large values (≥1 triệu → "486 tr"). */
+  compact?: boolean;
+  /** Optional ±% trend chip. */
+  trend?: number | null;
+  /** What this metric means — the ⓘ next to the value opens it in a popover. */
+  info?: string;
+}
+
+export interface SummaryLineProps {
+  items: SummaryLineItem[];
+}
+
+/**
+ * A LIGHT, inline "value label" summary of the CURRENT view — sits BETWEEN the
+ * toolbar and a register/list and is recomputed from the FILTERED rows, so it
+ * always describes WHAT'S SHOWN (not the whole dataset). This is NOT the
+ * dashboard stat band: that's `KPIStrip` (a boxed metric grid for dashboard
+ * pages, left untouched). Here there's no card, no big numbers, no column rules
+ * — a small `Metric` value + a muted label, items wrapping, separated by space.
+ */
+export function SummaryLine(props: SummaryLineProps) {
+  const { items } = props;
+  return (
+    <View style={styles.row}>
+      {items.map((item) => (
+        <View key={item.label} style={styles.item}>
+          <Metric
+            value={item.value}
+            format={item.format}
+            currency={item.currency}
+            locale={item.locale}
+            emptyLabel={item.emptyLabel}
+            compact={item.compact}
+            tone={item.tone}
+            size="sm"
+          />
+          <Text size="sm" color="muted">
+            {item.label}
+          </Text>
+          {item.trend != null ? <TrendChip value={item.trend} /> : null}
+          {item.info ? <InfoPopover text={item.info} accessibilityLabel={`About ${item.label}`} /> : null}
+        </View>
+      ))}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    alignItems: "center",
+    columnGap: 22,
+    rowGap: 8,
+  },
+  item: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6,
+  },
+});

package/src/table.tsx

@@ -9,8 +9,9 @@ import {
 } from "react";
 import { StyleSheet, View, Pressable, type ViewStyle } from "react-native";
 import { Text } from "./text";
-import { Divider } from "./divider";
+import { colors } from "./colors";
 import { PressableRow } from "./pressable_row";
+import { Divider } from "./divider";
 import { SortHeader, type SortState, type SortHeaderLabels } from "./sort_header";
 import { FOCUS_RING } from "./control_surface";
 import { useFocusRing } from "./use_focus_ring";
@@ -54,6 +55,9 @@ export interface TableProps {
   onSort?: (key: string) => void;
   /** Localized a11y strings for the sortable headers. Omit to keep English. */
   sortLabels?: SortHeaderLabels;
+  /** A node for the header's leading gutter — a select-all `CheckboxInput` aligned over
+   * the rows' `leading` checkboxes. Set `leading` too, to reserve the gutter width. */
+  selectAll?: ReactNode;
   /** Reserve a leading gutter (px) for rows that render a `leading` slot (a checkbox). */
   leading?: number;
   /** Reserve a trailing gutter (px) for rows that render a `trailing` slot (a ⋯ / button). */
@@ -71,13 +75,13 @@ export interface TableProps {
  * non-columnar list (entity piles, card stacks) use `PressableRow` directly.
  */
 export function Table(props: TableProps) {
-  const { columns, sort, onSort, sortLabels, leading = 0, trailing = 0, children } = props;
+  const { columns, sort, onSort, sortLabels, selectAll, leading = 0, trailing = 0, children } = props;
   const rows = Children.toArray(children).filter(isValidElement);
 
   return (
     <TableContext.Provider value={{ columns, leading, trailing }}>
       <View style={styles.headerBand}>
-        {leading > 0 ? <View style={{ width: leading }} /> : null}
+        {leading > 0 ? <View style={{ width: leading }}>{selectAll}</View> : null}
         {columns.map((col) => (
           <View key={col.key} style={colStyle(col)}>
             {col.label ? (
@@ -93,12 +97,14 @@ export function Table(props: TableProps) {
         ))}
         {trailing > 0 ? <View style={{ width: trailing }} /> : null}
       </View>
-      {rows.map((row, i) => (
-        <View key={(row as ReactElement).key ?? i}>
-          <Divider />
-          {row}
-        </View>
-      ))}
+      <View style={styles.body}>
+        {rows.map((row, i) => (
+          <View key={i}>
+            {i > 0 ? <Divider /> : null}
+            {row}
+          </View>
+        ))}
+      </View>
     </TableContext.Provider>
   );
 }
@@ -107,6 +113,8 @@ export interface TableRowProps {
   /** Opens the record (the drawer). The door + the full-row surface both call it. */
   onPress?: () => void;
   selected?: boolean;
+  /** Part of a multi-select set — a resting blue tint (the open/hover wash overrides it). */
+  marked?: boolean;
   /** Accessible name for the door (the keyboard-focusable open target). */
   accessibilityLabel?: string;
   /** Outside the door, BEFORE the cells (a selection checkbox) — width = Table `leading`. */
@@ -127,7 +135,7 @@ export interface TableRowProps {
  * win. Cells map to `Table`'s columns by position.
  */
 export function TableRow(props: TableRowProps) {
-  const { onPress, selected, accessibilityLabel, leading, trailing, minHeight = 52, children } = props;
+  const { onPress, selected, marked, accessibilityLabel, leading, trailing, minHeight = 52, children } = props;
   const ctx = useContext(TableContext);
   if (!ctx) throw new Error("TableRow must be used within a Table");
 
@@ -137,7 +145,7 @@ export function TableRow(props: TableRowProps) {
   const { focusVisible, focusProps } = useFocusRing();
 
   return (
-    <PressableRow onPress={onPress ?? noop} selected={selected} style={styles.row}>
+    <PressableRow onPress={onPress ?? noop} selected={selected} marked={marked} style={styles.row}>
       {ctx.leading > 0 ? <View style={{ width: ctx.leading }}>{leading}</View> : null}
       <Pressable
         accessibilityRole={onPress ? "button" : undefined}
@@ -168,12 +176,20 @@ export function TableCell(props: TableCellProps) {
 const noop = () => {};
 
 const styles = StyleSheet.create({
+  // A hairline under the column header anchors the columns; the rows below it are
+  // Divider-separated.
   headerBand: {
     paddingHorizontal: 20,
     paddingVertical: 10,
     flexDirection: "row",
     alignItems: "center",
     gap: 14,
+    borderBottomWidth: 1,
+    borderColor: colors.border,
+  },
+  // Rows are Divider-separated — the hairline between rows is the separation.
+  body: {
+    gap: 0,
   },
   row: {
     gap: 14,

package/src/use_selection.test.ts

@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import { useSelection } from "./use_selection";
+
+describe("useSelection", () => {
+  it("toggles an id on and off, and sets it explicitly with `on`", () => {
+    const { result } = renderHook(() => useSelection());
+    expect(result.current.count).toBe(0);
+    expect(result.current.has("a")).toBe(false);
+
+    act(() => result.current.toggle("a"));
+    expect(result.current.has("a")).toBe(true);
+    expect(result.current.count).toBe(1);
+
+    act(() => result.current.toggle("a"));
+    expect(result.current.has("a")).toBe(false);
+
+    act(() => result.current.toggle("a", true));
+    act(() => result.current.toggle("a", true)); // explicit on is idempotent
+    expect(result.current.count).toBe(1);
+    act(() => result.current.toggle("a", false));
+    expect(result.current.has("a")).toBe(false);
+  });
+
+  it("setAll selects/deselects a batch; `selected` exposes the picked ids", () => {
+    const { result } = renderHook(() => useSelection());
+    act(() => result.current.setAll(["a", "b", "c"], true));
+    expect(result.current.count).toBe(3);
+    expect([...result.current.selected].sort()).toEqual(["a", "b", "c"]);
+
+    act(() => result.current.setAll(["a", "b"], false));
+    expect([...result.current.selected]).toEqual(["c"]);
+  });
+
+  it("allSelected / indeterminate drive a select-all checkbox", () => {
+    const { result } = renderHook(() => useSelection());
+    const page = ["a", "b", "c"];
+    expect(result.current.allSelected(page)).toBe(false);
+    expect(result.current.indeterminate(page)).toBe(false);
+    expect(result.current.allSelected([])).toBe(false); // an empty set is never "all"
+
+    act(() => result.current.toggle("a", true));
+    expect(result.current.allSelected(page)).toBe(false);
+    expect(result.current.indeterminate(page)).toBe(true);
+
+    act(() => result.current.setAll(page, true));
+    expect(result.current.allSelected(page)).toBe(true);
+    expect(result.current.indeterminate(page)).toBe(false);
+  });
+
+  it("only the passed ids count — a selection outside the set isn't 'all'/'indeterminate' for it", () => {
+    const { result } = renderHook(() => useSelection());
+    act(() => result.current.setAll(["x", "y"], true));
+    expect(result.current.allSelected(["a", "b"])).toBe(false);
+    expect(result.current.indeterminate(["a", "b"])).toBe(false);
+  });
+
+  it("clear empties the whole selection", () => {
+    const { result } = renderHook(() => useSelection());
+    act(() => result.current.setAll(["a", "b"], true));
+    act(() => result.current.clear());
+    expect(result.current.count).toBe(0);
+    expect(result.current.has("a")).toBe(false);
+  });
+});

package/src/use_selection.ts

@@ -0,0 +1,75 @@
+import { useCallback, useMemo, useState } from "react";
+
+export interface Selection {
+  /** The selected ids — read `.has(id)` / `.size`, or use the helpers below.
+   * Spread it (`[...selected]`) to hand the picked ids to a bulk action. */
+  selected: ReadonlySet<string>;
+  /** Whether `id` is currently selected. */
+  has: (id: string) => boolean;
+  /** How many ids are selected — across pages, so it's the running total a
+   * `FloatingActionBar` shows. */
+  count: number;
+  /** Toggle `id`, or set it explicitly when `on` is passed (a row checkbox's `onChange`). */
+  toggle: (id: string, on?: boolean) => void;
+  /** Set a whole batch of ids on/off at once — the controlled select-all `onChange(on)`. */
+  setAll: (ids: readonly string[], on: boolean) => void;
+  /** Are ALL of `ids` selected? — a select-all checkbox's `checked` (false for an empty set). */
+  allSelected: (ids: readonly string[]) => boolean;
+  /** SOME but not all of `ids` selected? — a select-all checkbox's `indeterminate`. */
+  indeterminate: (ids: readonly string[]) => boolean;
+  /** Clear the whole selection. */
+  clear: () => void;
+}
+
+/**
+ * Always-on multi-select state for a register / list: the `selected` Set plus the
+ * toggle, select-all, and all-or-some helpers a `Table` + `FloatingActionBar` need.
+ * Items are agnostic string ids — selectability GATING (which rows can be ticked)
+ * stays with the caller: filter to the selectable ids and pass THOSE to `setAll` /
+ * `allSelected` / `indeterminate` (a non-selectable row just gets a disabled
+ * checkbox). Selection persists across pages, so `count` is the running total.
+ * (For a files-grid that ENTERS a selection mode via tap-and-hold, that's
+ * `useSelectionMode`; this is the checkbox-always-visible register variant.)
+ */
+export function useSelection(): Selection {
+  const [selected, setSelected] = useState<ReadonlySet<string>>(new Set());
+
+  const toggle = useCallback((id: string, on?: boolean) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (on ?? !prev.has(id)) next.add(id);
+      else next.delete(id);
+      return next;
+    });
+  }, []);
+
+  const setAll = useCallback((ids: readonly string[], on: boolean) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      for (const id of ids) {
+        if (on) next.add(id);
+        else next.delete(id);
+      }
+      return next;
+    });
+  }, []);
+
+  const clear = useCallback(() => setSelected(new Set()), []);
+
+  return useMemo<Selection>(
+    () => ({
+      selected,
+      has: (id) => selected.has(id),
+      count: selected.size,
+      toggle,
+      setAll,
+      allSelected: (ids) => ids.length > 0 && ids.every((id) => selected.has(id)),
+      indeterminate: (ids) => {
+        const all = ids.length > 0 && ids.every((id) => selected.has(id));
+        return !all && ids.some((id) => selected.has(id));
+      },
+      clear,
+    }),
+    [selected, toggle, setAll, clear],
+  );
+}