@multiplatform.one/frappe-ui 7.34.3 → 7.35.0

package/src/list/listColumns.spec.tsx

@@ -0,0 +1,63 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { fireEvent, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { buildListColumns } from "./listColumns";
+
+const platform = vi.hoisted(() => ({ web: true }));
+vi.mock("@multiplatform.one/components", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@multiplatform.one/components")>()),
+  get isWeb() {
+    return platform.web;
+  },
+}));
+
+afterEach(() => {
+  platform.web = true;
+});
+
+describe("document list title", () => {
+  it("lets a native title press reach the row instead of opening a web permalink", () => {
+    platform.web = false;
+    const onRowPress = vi.fn();
+    const column = buildListColumns({
+      t: (_key, fallback) => fallback,
+      getDocHref: (name) => `/backoffice/todo/${name}`,
+    })[0]!;
+    const renderTitle = column.cell;
+    if (typeof renderTitle !== "function") throw new Error("Expected a title cell renderer");
+    renderWithProviders(
+      <div onClick={onRowPress}>
+        {renderTitle({
+          row: { original: { name: "TODO-001" } },
+          getValue: () => "Native title",
+        } as never)}
+      </div>,
+    );
+    expect(screen.queryByRole("link")).toBeNull();
+    fireEvent.click(screen.getByText("Native title"));
+    expect(onRowPress).toHaveBeenCalledOnce();
+  });
+  it("constrains a linked title so its single-line text can ellipsize", () => {
+    const title = "A long document title that must truncate within the reserved subject width";
+    const column = buildListColumns({
+      t: (_key, fallback) => fallback,
+      getDocHref: (name) => `/backoffice/todo/${name}`,
+    })[0]!;
+    const renderTitle = column.cell;
+    if (typeof renderTitle !== "function") throw new Error("Expected a title cell renderer");
+    renderWithProviders(
+      <>
+        {renderTitle({
+          row: { original: { name: "TODO-001" } },
+          getValue: () => title,
+        } as never)}
+      </>,
+    );
+    const link = screen.getByRole("link", { name: title });
+    expect(link.getAttribute("href")).toBe("/backoffice/todo/TODO-001");
+    expect(getComputedStyle(link).display).toBe("flex");
+    expect(getComputedStyle(link).minWidth).toBe("0px");
+    expect(getComputedStyle(screen.getByText(title)).textOverflow).toBe("ellipsis");
+    expect(getComputedStyle(screen.getByText(title)).whiteSpace).toBe("nowrap");
+  });
+});

package/src/list/listColumns.tsx

@@ -10,7 +10,15 @@
 // of the subject link (LC-74). Extra ID / Last Updated columns stay out —
 // the timestamp lives in the activity cluster.
 import type { ReactNode } from "react";
-import { Avatar, Anchor, Chip, Text, XStack, type ChipColor } from "@multiplatform.one/components";
+import {
+  Avatar,
+  Anchor,
+  Chip,
+  Text,
+  XStack,
+  isWeb,
+  type ChipColor,
+} from "@multiplatform.one/components";
 // House control for the like toggle — the icon rides the Button icon slot
 // (LC-53 GLYPH-SLOT) and the sub-44 circular size resolves the press floor
 // through the house channel (LC-54: 44px box + hitSlop).
@@ -65,6 +73,7 @@ export interface BuildListColumnsArgs {
 }
 
 const NUMERIC_FIELDTYPES = new Set(["Currency", "Float", "Int", "Percent", "Duration"]);
+const DATE_FIELDTYPES = new Set(["Date", "Datetime", "Time"]);
 
 // Fieldtypes whose stored value is markup — list cells render a stripped
 // one-line plain-text preview (desk strip_html parity), never raw HTML.
@@ -432,10 +441,11 @@ export function buildListColumns({
           {label}
         </Text>
       );
-      if (!href) return subject;
+      if (!isWeb || !href) return subject;
       return (
         <Anchor
           href={href}
+          display="flex"
           textDecorationLine="none"
           minWidth={0}
           flexShrink={1}
@@ -453,6 +463,10 @@ export function buildListColumns({
       header: field.label || field.fieldname,
       accessorKey: field.fieldname,
       ...(NUMERIC_FIELDTYPES.has(field.fieldtype) ? { align: "right" as const } : {}),
+      // Numbers and dates are the list row's fixed-width trailing columns.
+      ...(NUMERIC_FIELDTYPES.has(field.fieldtype) || DATE_FIELDTYPES.has(field.fieldtype)
+        ? { meta: { role: "trailing" } }
+        : {}),
       cell: fieldCell(field, meta, onFilterClick),
     });
   }

package/src/list/listControls.fixture.ts

@@ -0,0 +1,67 @@
+import type { FrappeListControls, FrappeListState } from "./listState";
+import type { ListControlsResult } from "./useListControls";
+
+export const fixtureControls: FrappeListControls = {
+  sorts: [
+    { value: "number", label: "Number", orderBy: [] },
+    { value: "xp", label: "XP", orderBy: [] },
+  ],
+  facets: [
+    {
+      param: "type",
+      field: "poke_type",
+      label: "Type",
+      allLabel: "All types",
+      options: ["fire", "water"],
+    },
+    { param: "region", field: "region", label: "Region", options: ["kanto", "johto"] },
+  ],
+  bands: [
+    {
+      param: "generation",
+      field: "poke_id",
+      label: "Generation",
+      allLabel: "All generations",
+      options: [
+        { value: "1", label: "Generation I", min: 1, max: 151 },
+        { value: "2", label: "Generation II", min: 152, max: 251 },
+      ],
+    },
+  ],
+  ranges: [{ param: "xp", label: "Min XP", field: "base_experience" }],
+};
+
+/** A ListControlsResult stand-in: the band reads it, `update` records patches. */
+export function fixtureList(
+  state: Partial<FrappeListState> = {},
+  update: (patch: Partial<FrappeListState>) => void = () => {},
+): ListControlsResult {
+  return {
+    state: {
+      search: "",
+      sort: "number",
+      facets: {},
+      bands: {},
+      ranges: {},
+      favoritesOnly: false,
+      view: undefined,
+      ...state,
+    },
+    searchText: state.search ?? "",
+    setSearchText: () => {},
+    update,
+    clear: () => {},
+    favorites: {
+      favorites: [],
+      favoriteSet: new Set(),
+      isFavorite: () => false,
+      toggle: () => {},
+      count: 0,
+    },
+    facets: {},
+    bandCounts: { generation: { "1": 8, "2": 4 } },
+    total: 12,
+    highest: { xp: 300 },
+    readers: null,
+  };
+}

package/src/list/listState.spec.ts

@@ -1,6 +1,8 @@
 import { Order } from "@multiplatform.one/frappe";
 import { describe, expect, it } from "vitest";
 import {
+  activeFilterCount,
+  bandOptionFor,
   isListNarrowed,
   listStateFilters,
   listStateFromParams,
@@ -36,6 +38,7 @@ describe("listStateFromParams", () => {
       sort: "number",
       facets: {},
       ranges: {},
+      bands: {},
       favoritesOnly: false,
       view: "grid",
     });
@@ -52,6 +55,7 @@ describe("listStateFromParams", () => {
       sort: "name",
       facets: { type: "grass" },
       ranges: { xp: 60 },
+      bands: {},
       favoritesOnly: true,
       view: "table",
     });
@@ -154,3 +158,66 @@ describe("listStateOrderBy", () => {
     ).toEqual([{ field: "modified", order: Order.Desc }]);
   });
 });
+
+describe("bands", () => {
+  const banded: FrappeListControls = {
+    ...controls,
+    bands: [
+      {
+        param: "gen",
+        field: "poke_id",
+        label: "Generation",
+        options: [
+          { value: "1", label: "I", min: 1, max: 151 },
+          { value: "2", label: "II", min: 152, max: 251 },
+          { value: "9", label: "IX", min: 906 },
+        ],
+      },
+    ],
+  };
+
+  it("reads a band from its param and drops values it does not offer", () => {
+    expect(listStateFromParams({ gen: "2" }, banded).bands).toEqual({ gen: "2" });
+    expect(listStateFromParams({ gen: "7" }, banded).bands).toEqual({});
+  });
+
+  it("writes a band's param and drops it when cleared", () => {
+    expect(listStateParams({ bands: { gen: "1" } }, banded)).toEqual({ gen: "1" });
+    expect(listStateParams({ bands: { gen: "" } }, banded)).toEqual({ gen: undefined });
+  });
+
+  it("turns a band into its inclusive bounds, an open side adding no filter", () => {
+    const base = listStateFromParams({}, banded);
+    expect(listStateFilters({ ...base, bands: { gen: "2" } }, banded)).toEqual([
+      ["poke_id", ">=", 152],
+      ["poke_id", "<=", 251],
+    ]);
+    expect(listStateFilters({ ...base, bands: { gen: "9" } }, banded)).toEqual([
+      ["poke_id", ">=", 906],
+    ]);
+  });
+
+  it("counts the filters a reader set, search aside", () => {
+    const base = listStateFromParams({}, banded);
+    expect(activeFilterCount(base)).toBe(0);
+    expect(activeFilterCount({ ...base, search: "pika" })).toBe(0);
+    expect(isListNarrowed({ ...base, bands: { gen: "1" } })).toBe(true);
+    expect(
+      activeFilterCount({
+        ...base,
+        facets: { type: "grass" },
+        ranges: { xp: 60 },
+        bands: { gen: "1" },
+        favoritesOnly: true,
+      }),
+    ).toBe(4);
+  });
+
+  it("finds the option a value falls in", () => {
+    const band = banded.bands![0];
+    expect(bandOptionFor(band, 25)?.value).toBe("1");
+    expect(bandOptionFor(band, 152)?.value).toBe("2");
+    expect(bandOptionFor(band, 1000)?.value).toBe("9");
+    expect(bandOptionFor(band, 400)).toBeUndefined();
+  });
+});

package/src/list/listState.ts

@@ -5,8 +5,8 @@
  * the rows the controls describe. Pure: no React, no IO.
  *
  * Params: `q` search, `sort` the sort's value (absent for the first sort),
- * one param per facet and per range (absent when unset), `fav=1` favorites
- * only, `view` (absent for the default view).
+ * one param per facet, per range and per band (absent when unset), `fav=1`
+ * favorites only, `view` (absent for the default view).
  */
 import type { Order } from "@multiplatform.one/frappe";
 
@@ -51,10 +51,31 @@ export interface FrappeListRange {
   step?: number;
 }
 
+/** One named span of a numeric field (Generation I is Pokédex 1 to 151). */
+export interface FrappeListBandOption {
+  /** URL value. */
+  value: string;
+  label: string;
+  /** Inclusive bounds; an absent bound leaves that side open. */
+  min?: number;
+  max?: number;
+}
+
+/** Narrow the list to records whose numeric field falls in one named span. */
+export interface FrappeListBand {
+  param: string;
+  field: string;
+  label: string;
+  /** The option that clears the band. */
+  allLabel?: string;
+  options: readonly FrappeListBandOption[];
+}
+
 export interface FrappeListControls {
   sorts?: readonly FrappeListSort[];
   facets?: readonly FrappeListFacet[];
   ranges?: readonly FrappeListRange[];
+  bands?: readonly FrappeListBand[];
   views?: readonly FrappeListViewMode[];
   defaultView?: FrappeListViewMode;
 }
@@ -67,6 +88,8 @@ export interface FrappeListState {
   facets: Record<string, string>;
   /** Range param to its minimum; absent or 0 is no minimum. */
   ranges: Record<string, number>;
+  /** Band param to the chosen option's value. */
+  bands: Record<string, string>;
   favoritesOnly: boolean;
   view: FrappeListViewMode | undefined;
 }
@@ -96,6 +119,11 @@ export function listStateFromParams(
     const value = positiveInt(params[range.param]);
     if (value > 0) ranges[range.param] = value;
   }
+  const bands: Record<string, string> = {};
+  for (const band of controls.bands ?? []) {
+    const value = params[band.param];
+    if (value && band.options.some((option) => option.value === value)) bands[band.param] = value;
+  }
   const views = controls.views ?? [];
   const view = views.find((mode) => mode === params.view) ?? controls.defaultView;
   return {
@@ -103,6 +131,7 @@ export function listStateFromParams(
     sort,
     facets,
     ranges,
+    bands,
     favoritesOnly: params.fav === "1",
     view,
   };
@@ -124,6 +153,9 @@ export function listStateParams(
   for (const [param, value] of Object.entries(patch.ranges ?? {})) {
     params[param] = value > 0 ? String(value) : undefined;
   }
+  for (const [param, value] of Object.entries(patch.bands ?? {})) {
+    params[param] = value || undefined;
+  }
   if (patch.favoritesOnly !== undefined) params.fav = patch.favoritesOnly ? "1" : undefined;
   if (patch.view !== undefined) {
     params.view = patch.view === controls.defaultView ? undefined : patch.view;
@@ -131,13 +163,33 @@ export function listStateParams(
   return params;
 }
 
-/** Search, a facet, a range or favorites narrows the rows. */
+/** Search, a facet, a range, a band or favorites narrows the rows. */
 export function isListNarrowed(state: FrappeListState): boolean {
+  return state.search.trim() !== "" || activeFilterCount(state) > 0;
+}
+
+/**
+ * The filters a reader set, search aside: each facet, range and band with a
+ * value, and favorites only. A Filters button wears this as its count.
+ */
+export function activeFilterCount(state: FrappeListState): number {
   return (
-    state.search.trim() !== "" ||
-    Object.values(state.facets).some(Boolean) ||
-    Object.values(state.ranges).some((value) => value > 0) ||
-    state.favoritesOnly
+    Object.values(state.facets).filter(Boolean).length +
+    Object.values(state.ranges).filter((value) => value > 0).length +
+    Object.values(state.bands ?? {}).filter(Boolean).length +
+    (state.favoritesOnly ? 1 : 0)
+  );
+}
+
+/** The option of a band a numeric value falls in, if any. */
+export function bandOptionFor(
+  band: FrappeListBand,
+  value: number,
+): FrappeListBandOption | undefined {
+  return band.options.find(
+    (option) =>
+      (option.min === undefined || value >= option.min) &&
+      (option.max === undefined || value <= option.max),
   );
 }
 
@@ -170,6 +222,12 @@ export function listStateFilters(
     const value = state.ranges[range.param] ?? 0;
     if (value > 0) filters.push([range.field, ">=", value]);
   }
+  for (const band of controls.bands ?? []) {
+    const option = band.options.find((candidate) => candidate.value === state.bands?.[band.param]);
+    if (!option) continue;
+    if (option.min !== undefined) filters.push([band.field, ">=", option.min]);
+    if (option.max !== undefined) filters.push([band.field, "<=", option.max]);
+  }
   if (state.favoritesOnly) filters.push(["name", "in", [...(options.favorites ?? [])].sort()]);
   return filters.length > 0 ? filters : undefined;
 }

package/src/list/useListControls.tsx

@@ -7,6 +7,7 @@ import type { FrappeRowsConnection } from "../useFrappeRows";
 import { facetRead, readFacet, type FacetReading } from "./facetReading";
 import { useFavorites, type UseFavorites } from "./favorites";
 import {
+  bandOptionFor,
   listStateFromParams,
   listStateParams,
   type FrappeListControls,
@@ -46,6 +47,8 @@ export interface ListControlsResult {
   total: number | undefined;
   /** Highest value per range param in the base read. */
   highest: Readonly<Record<string, number>>;
+  /** Records per band option, per band param, in the base read. */
+  bandCounts: Readonly<Record<string, Readonly<Record<string, number>>>>;
   /** Mount these: the facet and base reads. */
   readers: React.ReactNode;
 }
@@ -56,6 +59,7 @@ function mergeState(prev: FrappeListState, patch: Partial<FrappeListState>): Fra
     ...patch,
     facets: patch.facets ? { ...prev.facets, ...patch.facets } : prev.facets,
     ranges: patch.ranges ? { ...prev.ranges, ...patch.ranges } : prev.ranges,
+    bands: patch.bands ? { ...prev.bands, ...patch.bands } : prev.bands,
   };
 }
 
@@ -117,6 +121,7 @@ export function useListControls({
       favoritesOnly: false,
       facets: Object.fromEntries((current.facets ?? []).map((facet) => [facet.param, ""])),
       ranges: Object.fromEntries((current.ranges ?? []).map((range) => [range.param, 0])),
+      bands: Object.fromEntries((current.bands ?? []).map((band) => [band.param, ""])),
     });
   }, [update]);
 
@@ -141,7 +146,12 @@ export function useListControls({
       orderBy,
     ]),
   );
-  const rangeFieldsKey = JSON.stringify((controls.ranges ?? []).map((range) => range.field));
+  const rangeFieldsKey = JSON.stringify([
+    ...new Set([
+      ...(controls.ranges ?? []).map((range) => range.field),
+      ...(controls.bands ?? []).map((band) => band.field),
+    ]),
+  ]);
   const connectionsKey = JSON.stringify(connections ?? null);
 
   const reads = useMemo(() => {
@@ -173,8 +183,8 @@ export function useListControls({
   }, [reads, snapshots]);
 
   const baseRows = reads.base ? snapshots.base?.rows : undefined;
-  const { total, highest } = useMemo(() => {
-    if (!baseRows) return { total: undefined, highest: {} };
+  const { total, highest, bandCounts } = useMemo(() => {
+    if (!baseRows) return { total: undefined, highest: {}, bandCounts: {} };
     const peaks: Record<string, number> = {};
     for (const range of controlsRef.current.ranges ?? []) {
       peaks[range.param] = baseRows.reduce(
@@ -182,7 +192,18 @@ export function useListControls({
         0,
       );
     }
-    return { total: baseRows.length, highest: peaks };
+    const counts: Record<string, Record<string, number>> = {};
+    for (const band of controlsRef.current.bands ?? []) {
+      const tally: Record<string, number> = {};
+      for (const row of baseRows) {
+        const value = Number(row[band.field]);
+        if (!Number.isFinite(value)) continue;
+        const option = bandOptionFor(band, value);
+        if (option) tally[option.value] = (tally[option.value] ?? 0) + 1;
+      }
+      counts[band.param] = tally;
+    }
+    return { total: baseRows.length, highest: peaks, bandCounts: counts };
   }, [baseRows]);
 
   const readers = (
@@ -218,6 +239,7 @@ export function useListControls({
     facets: facetReadings,
     total,
     highest,
+    bandCounts,
     readers,
   };
 }