@multiplatform.one/frappe-ui 7.23.2 → 7.24.0

package/src/list/favorites.ts

@@ -0,0 +1,79 @@
+/**
+ * A list's favorites: the record names a reader starred, kept on the device
+ * (no bench write, so a guest can star too). One persistent store per
+ * storage key, following docs/standards/frontend/persistent-stores.md.
+ */
+import {
+  Store,
+  createPersistStore,
+  storage,
+  useStore,
+  type PersistStore,
+  type Storage,
+} from "@multiplatform.one/store";
+import { useMemo } from "react";
+
+export interface FavoritesState {
+  /** Starred record names, in the order they were starred. */
+  names: string[];
+}
+
+export function createFavoritesStore(
+  key: string,
+  storageImpl: Storage = storage,
+): PersistStore<FavoritesState> {
+  return createPersistStore<FavoritesState>({ names: [] }, { key, storage: storageImpl });
+}
+
+const stores = new Map<string, PersistStore<FavoritesState>>();
+
+/** The shared store for a storage key. */
+export function favoritesStore(key: string): PersistStore<FavoritesState> {
+  let store = stores.get(key);
+  if (!store) {
+    store = createFavoritesStore(key);
+    stores.set(key, store);
+  }
+  return store;
+}
+
+/** The storage key a doctype's favorites default to. */
+export function favoritesKey(doctype: string): string {
+  return `frappe-favorites-${doctype}`;
+}
+
+export function toggleFavoriteIn(store: PersistStore<FavoritesState>, name: string): void {
+  store.setState((prev) =>
+    prev.names.includes(name)
+      ? { names: prev.names.filter((n) => n !== name) }
+      : { names: [...prev.names, name] },
+  );
+}
+
+export interface UseFavorites {
+  favorites: string[];
+  favoriteSet: ReadonlySet<string>;
+  isFavorite: (name: string) => boolean;
+  toggle: (name: string) => void;
+  count: number;
+}
+
+const noFavorites = new Store<FavoritesState>({ names: [] });
+
+/** A key's favorites; without a key, none (and toggling does nothing). */
+export function useFavorites(key: string | undefined): UseFavorites {
+  const store = key ? favoritesStore(key) : noFavorites;
+  const names = useStore(store, (state) => state.names);
+  return useMemo(() => {
+    const favoriteSet = new Set(names);
+    return {
+      favorites: names,
+      favoriteSet,
+      isFavorite: (name: string) => favoriteSet.has(name),
+      toggle: (name: string) => {
+        if (store !== noFavorites) toggleFavoriteIn(store as PersistStore<FavoritesState>, name);
+      },
+      count: names.length,
+    };
+  }, [names, store]);
+}

package/src/list/listState.spec.ts

@@ -0,0 +1,156 @@
+import { Order } from "@multiplatform.one/frappe";
+import { describe, expect, it } from "vitest";
+import {
+  isListNarrowed,
+  listStateFilters,
+  listStateFromParams,
+  listStateOrderBy,
+  listStateParams,
+  type FrappeListControls,
+} from "./listState";
+
+const controls: FrappeListControls = {
+  sorts: [
+    { value: "number", label: "Number", orderBy: [{ field: "poke_id", order: Order.Asc }] },
+    { value: "name", label: "Name", orderBy: [{ field: "pokemon_name", order: Order.Asc }] },
+  ],
+  facets: [
+    {
+      param: "type",
+      doctype: "Pokemon Poke Type",
+      field: "poke_type",
+      label: "Type",
+      options: ["grass", "fire"],
+    },
+    { param: "gen", field: "generation", label: "Generation", options: ["1", "2"] },
+  ],
+  ranges: [{ param: "xp", field: "base_experience", label: "Min XP" }],
+  defaultView: "grid",
+  views: ["grid", "list", "table"],
+};
+
+describe("listStateFromParams", () => {
+  it("reads nothing into the defaults", () => {
+    expect(listStateFromParams({}, controls)).toEqual({
+      search: "",
+      sort: "number",
+      facets: {},
+      ranges: {},
+      favoritesOnly: false,
+      view: "grid",
+    });
+  });
+
+  it("reads every control from its param", () => {
+    expect(
+      listStateFromParams(
+        { q: "bulba", sort: "name", type: "grass", xp: "60", fav: "1", view: "table" },
+        controls,
+      ),
+    ).toEqual({
+      search: "bulba",
+      sort: "name",
+      facets: { type: "grass" },
+      ranges: { xp: 60 },
+      favoritesOnly: true,
+      view: "table",
+    });
+  });
+
+  it("drops values the controls do not offer", () => {
+    expect(
+      listStateFromParams({ sort: "height", type: "water", xp: "-4", view: "kanban" }, controls),
+    ).toEqual(listStateFromParams({}, controls));
+  });
+});
+
+describe("listStateParams", () => {
+  it("writes defaults as absent params so a clean list has a clean URL", () => {
+    expect(
+      listStateParams(
+        { search: "", sort: "number", facets: { type: "" }, ranges: { xp: 0 }, view: "grid" },
+        controls,
+      ),
+    ).toEqual({ q: undefined, sort: undefined, type: undefined, xp: undefined, view: undefined });
+  });
+
+  it("writes a patch as only the params it touches", () => {
+    expect(listStateParams({ favoritesOnly: true }, controls)).toEqual({ fav: "1" });
+    expect(listStateParams({ sort: "name", facets: { type: "fire" } }, controls)).toEqual({
+      sort: "name",
+      type: "fire",
+    });
+  });
+
+  it("round-trips through listStateFromParams", () => {
+    const state = listStateFromParams(
+      { q: "25", sort: "name", gen: "2", xp: "100", fav: "1", view: "list" },
+      controls,
+    );
+    expect(listStateFromParams(listStateParams(state, controls), controls)).toEqual(state);
+  });
+});
+
+describe("listStateFilters", () => {
+  const empty = listStateFromParams({}, controls);
+
+  it("is undefined when nothing narrows, so the list reads its unfiltered query", () => {
+    expect(listStateFilters(empty, controls)).toBeUndefined();
+    expect(isListNarrowed(empty)).toBe(false);
+  });
+
+  it("turns each control into a bench filter", () => {
+    const state = {
+      ...empty,
+      search: " bulba ",
+      facets: { type: "grass", gen: "1" },
+      ranges: { xp: 60 },
+      favoritesOnly: true,
+    };
+    expect(
+      listStateFilters(state, controls, {
+        search: (query) => [["pokemon_name", "like", `%${query}%`]],
+        favorites: new Set(["ivysaur", "bulbasaur"]),
+      }),
+    ).toEqual([
+      ["pokemon_name", "like", "%bulba%"],
+      ["Pokemon Poke Type", "poke_type", "=", "grass"],
+      ["generation", "=", "1"],
+      ["base_experience", ">=", 60],
+      ["name", "in", ["bulbasaur", "ivysaur"]],
+    ]);
+    expect(isListNarrowed(state)).toBe(true);
+  });
+
+  it("keeps the given filters first", () => {
+    expect(
+      listStateFilters({ ...empty, ranges: { xp: 10 } }, controls, {
+        base: [["species", "=", "seed"]],
+      }),
+    ).toEqual([
+      ["species", "=", "seed"],
+      ["base_experience", ">=", 10],
+    ]);
+  });
+
+  it("filters favorites-only with no favorites to an empty match", () => {
+    expect(listStateFilters({ ...empty, favoritesOnly: true }, controls)).toEqual([
+      ["name", "in", []],
+    ]);
+  });
+});
+
+describe("listStateOrderBy", () => {
+  it("is the chosen sort's order, else the fallback", () => {
+    const empty = listStateFromParams({}, controls);
+    expect(listStateOrderBy({ ...empty, sort: "name" }, controls)).toEqual([
+      { field: "pokemon_name", order: Order.Asc },
+    ]);
+    expect(listStateOrderBy(empty, controls)).toEqual([{ field: "poke_id", order: Order.Asc }]);
+    expect(
+      listStateOrderBy(empty, { ...controls, sorts: [] }, [
+        { field: "modified", order: Order.Desc },
+      ]),
+    ).toEqual([{ field: "modified", order: Order.Desc }]);
+  });
+});

package/src/list/listState.ts

@@ -0,0 +1,184 @@
+/**
+ * The state of a list page's controls (search, sort, facets, ranges,
+ * favorites, view) and its two codecs: URL params, so a refresh or a shared
+ * link reproduces the list, and bench filters, so the list reads exactly
+ * 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).
+ */
+import type { Order } from "@multiplatform.one/frappe";
+
+export type FrappeListViewMode = "list" | "table" | "grid";
+
+export interface FrappeListSort {
+  /** URL value. */
+  value: string;
+  label: string;
+  orderBy: ReadonlyArray<{ field: string; order: Order }>;
+}
+
+/** Narrow the list to records carrying one value of a field. */
+export interface FrappeListFacet {
+  /** URL param and state key. */
+  param: string;
+  /** Field whose value narrows. */
+  field: string;
+  /**
+   * A connection doctype whose rows carry `field` (Pokemon's types live on
+   * Pokemon Poke Type rows). Omitted, `field` is the list doctype's own.
+   */
+  doctype?: string;
+  /** Values offered, in display order. */
+  options: readonly string[];
+  /** Names the rail for assistive tech. */
+  label: string;
+  /** The chip that clears the facet. */
+  allLabel?: string;
+  optionLabel?: (value: string) => string;
+  /** A theme hue per value (`"grass"`), painting its chip from that ramp. */
+  tint?: (value: string) => string | undefined;
+  /** Connection field that orders one record's values (a `slot`). */
+  orderBy?: string;
+}
+
+/** Narrow the list to records whose numeric field is at least a value. */
+export interface FrappeListRange {
+  param: string;
+  field: string;
+  label: string;
+  step?: number;
+}
+
+export interface FrappeListControls {
+  sorts?: readonly FrappeListSort[];
+  facets?: readonly FrappeListFacet[];
+  ranges?: readonly FrappeListRange[];
+  views?: readonly FrappeListViewMode[];
+  defaultView?: FrappeListViewMode;
+}
+
+export interface FrappeListState {
+  search: string;
+  /** The chosen sort's value; the first sort when none was chosen. */
+  sort: string | undefined;
+  /** Facet param to the value it narrows to. */
+  facets: Record<string, string>;
+  /** Range param to its minimum; absent or 0 is no minimum. */
+  ranges: Record<string, number>;
+  favoritesOnly: boolean;
+  view: FrappeListViewMode | undefined;
+}
+
+export type FrappeListParams = Record<string, string | undefined>;
+
+export type FrappeListFilter = [string, string, unknown] | [string, string, string, unknown];
+
+function positiveInt(value: string | undefined): number {
+  const parsed = Number.parseInt(value ?? "", 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+export function listStateFromParams(
+  params: FrappeListParams,
+  controls: FrappeListControls,
+): FrappeListState {
+  const sorts = controls.sorts ?? [];
+  const sort = sorts.find((option) => option.value === params.sort)?.value ?? sorts[0]?.value;
+  const facets: Record<string, string> = {};
+  for (const facet of controls.facets ?? []) {
+    const value = params[facet.param];
+    if (value && facet.options.includes(value)) facets[facet.param] = value;
+  }
+  const ranges: Record<string, number> = {};
+  for (const range of controls.ranges ?? []) {
+    const value = positiveInt(params[range.param]);
+    if (value > 0) ranges[range.param] = value;
+  }
+  const views = controls.views ?? [];
+  const view = views.find((mode) => mode === params.view) ?? controls.defaultView;
+  return {
+    search: params.q ?? "",
+    sort,
+    facets,
+    ranges,
+    favoritesOnly: params.fav === "1",
+    view,
+  };
+}
+
+/** A state patch as the URL params it changes; a default value drops its param. */
+export function listStateParams(
+  patch: Partial<FrappeListState>,
+  controls: FrappeListControls,
+): FrappeListParams {
+  const params: FrappeListParams = {};
+  if (patch.search !== undefined) params.q = patch.search.trim() || undefined;
+  if (patch.sort !== undefined) {
+    params.sort = patch.sort === controls.sorts?.[0]?.value ? undefined : patch.sort;
+  }
+  for (const [param, value] of Object.entries(patch.facets ?? {})) {
+    params[param] = value || undefined;
+  }
+  for (const [param, value] of Object.entries(patch.ranges ?? {})) {
+    params[param] = value > 0 ? String(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;
+  }
+  return params;
+}
+
+/** Search, a facet, a range or favorites narrows the rows. */
+export function isListNarrowed(state: FrappeListState): boolean {
+  return (
+    state.search.trim() !== "" ||
+    Object.values(state.facets).some(Boolean) ||
+    Object.values(state.ranges).some((value) => value > 0) ||
+    state.favoritesOnly
+  );
+}
+
+export interface ListStateFilterOptions {
+  /** Filters that always apply, ahead of the controls'. */
+  base?: readonly FrappeListFilter[];
+  /** The bench filters a search query becomes. */
+  search?: (query: string) => readonly FrappeListFilter[];
+  /** Starred names, for favorites only. */
+  favorites?: ReadonlySet<string>;
+}
+
+/** The bench filters the state describes, or undefined when nothing filters. */
+export function listStateFilters(
+  state: FrappeListState,
+  controls: FrappeListControls,
+  options: ListStateFilterOptions = {},
+): FrappeListFilter[] | undefined {
+  const filters: FrappeListFilter[] = [...(options.base ?? [])];
+  const query = state.search.trim();
+  if (query && options.search) filters.push(...options.search(query));
+  for (const facet of controls.facets ?? []) {
+    const value = state.facets[facet.param];
+    if (!value) continue;
+    filters.push(
+      facet.doctype ? [facet.doctype, facet.field, "=", value] : [facet.field, "=", value],
+    );
+  }
+  for (const range of controls.ranges ?? []) {
+    const value = state.ranges[range.param] ?? 0;
+    if (value > 0) filters.push([range.field, ">=", value]);
+  }
+  if (state.favoritesOnly) filters.push(["name", "in", [...(options.favorites ?? [])].sort()]);
+  return filters.length > 0 ? filters : undefined;
+}
+
+export function listStateOrderBy(
+  state: FrappeListState,
+  controls: FrappeListControls,
+  fallback?: ReadonlyArray<{ field: string; order: Order }>,
+): ReadonlyArray<{ field: string; order: Order }> | undefined {
+  const sorts = controls.sorts ?? [];
+  return (sorts.find((option) => option.value === state.sort) ?? sorts[0])?.orderBy ?? fallback;
+}

package/src/list/recordLook.ts

@@ -0,0 +1,37 @@
+/**
+ * How a doctype's records present beyond their fields: a display title, a
+ * short code beside it, candidate images. Lists, insights and record pages
+ * draw a record the same way from one declaration.
+ */
+export interface FrappeRecordLook<TDoc> {
+  /** The record's display name; defaults to the title field, then the name. */
+  title?: (doc: Partial<TDoc>) => string;
+  /** A short code shown beside the title ("#025"). */
+  code?: (doc: Partial<TDoc>) => string;
+  /** A muted line under the title on cards (a Pokemon's species). */
+  subtitle?: (doc: Partial<TDoc>) => string | undefined;
+  /** Image candidates in order; a failed load moves to the next. */
+  images?: (doc: Partial<TDoc>, baseURL: string | undefined) => string[];
+  /** Further images a record page shows after the first, one slide each. */
+  gallery?: (doc: Partial<TDoc>, baseURL: string | undefined) => FrappeRecordSlide[];
+}
+
+export interface FrappeRecordSlide {
+  src: string;
+  label: string;
+  /** Nearest-neighbor upscaling, for pixel art. */
+  pixelated?: boolean;
+}
+
+export function recordTitle<TDoc>(
+  doc: Partial<TDoc>,
+  look: FrappeRecordLook<TDoc> | undefined,
+  titleField?: string,
+): string {
+  const custom = look?.title?.(doc);
+  if (custom) return custom;
+  const row = doc as Record<string, unknown>;
+  const field = titleField ? row[titleField] : undefined;
+  if (typeof field === "string" && field) return field;
+  return typeof row.name === "string" ? row.name : "";
+}

package/src/list/useListControls.tsx

@@ -0,0 +1,223 @@
+import type React from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { FrappeConnection } from "../frappeConnections";
+import type { FrappeRouter } from "../frappeNavigation";
+import { FrappeRowsReader, type FrappeRowsSnapshot } from "../FrappeRowsReader";
+import type { FrappeRowsConnection } from "../useFrappeRows";
+import { facetRead, readFacet, type FacetReading } from "./facetReading";
+import { useFavorites, type UseFavorites } from "./favorites";
+import {
+  listStateFromParams,
+  listStateParams,
+  type FrappeListControls,
+  type FrappeListParams,
+  type FrappeListState,
+} from "./listState";
+
+type Row = Record<string, unknown> & { name: string; doctype: string };
+type Snapshot = FrappeRowsSnapshot<Row>;
+
+export interface ListControlsOptions {
+  doctype: string;
+  controls: FrappeListControls;
+  connections: readonly FrappeConnection[] | undefined;
+  connection: FrappeRowsConnection | undefined;
+  /** The list's row ceiling; the base read (count, range ceilings) shares it. */
+  limit?: number;
+  /** Storage key of the favorites; undefined offers none. */
+  favoritesKey?: string;
+  /** Read and write the state through the router's query params. */
+  router?: FrappeRouter;
+  /** Read every record's name (and range fields) for counts and ceilings. */
+  readBase: boolean;
+}
+
+export interface ListControlsResult {
+  state: FrappeListState;
+  /** The search box's text, ahead of its debounced commit to `state.search`. */
+  searchText: string;
+  setSearchText: (text: string) => void;
+  update: (patch: Partial<FrappeListState>) => void;
+  /** Drops search, facets, ranges and favorites-only. */
+  clear: () => void;
+  favorites: UseFavorites;
+  facets: Readonly<Record<string, FacetReading>>;
+  /** Records the base read found, capped at the list's limit. */
+  total: number | undefined;
+  /** Highest value per range param in the base read. */
+  highest: Readonly<Record<string, number>>;
+  /** Mount these: the facet and base reads. */
+  readers: React.ReactNode;
+}
+
+function mergeState(prev: FrappeListState, patch: Partial<FrappeListState>): FrappeListState {
+  return {
+    ...prev,
+    ...patch,
+    facets: patch.facets ? { ...prev.facets, ...patch.facets } : prev.facets,
+    ranges: patch.ranges ? { ...prev.ranges, ...patch.ranges } : prev.ranges,
+  };
+}
+
+/**
+ * The state behind a list page's controls, the favorites it filters by and
+ * the reads that label them (facet values and counts, the record count, the
+ * range ceilings). With a router that hands over query params the state
+ * seeds from them once and writes back after each commit: the write rides
+ * a post-commit effect, since a host router notifies its subscribers
+ * synchronously and a notify inside a render-phase update is a React error.
+ */
+export function useListControls({
+  doctype,
+  controls,
+  connections,
+  connection,
+  limit,
+  favoritesKey,
+  router,
+  readBase,
+}: ListControlsOptions): ListControlsResult {
+  const controlsRef = useRef(controls);
+  controlsRef.current = controls;
+  const setParams = router?.setSearchParams;
+  const setParamsRef = useRef(setParams);
+  setParamsRef.current = setParams;
+
+  const [state, setState] = useState<FrappeListState>(() =>
+    listStateFromParams(router?.searchParams ?? {}, controls),
+  );
+  const [searchText, setSearchText] = useState(state.search);
+  const pending = useRef<FrappeListParams>({});
+  const [flushTick, setFlushTick] = useState(0);
+
+  const update = useCallback((patch: Partial<FrappeListState>) => {
+    setState((prev) => mergeState(prev, patch));
+    if (!setParamsRef.current) return;
+    pending.current = { ...pending.current, ...listStateParams(patch, controlsRef.current) };
+    setFlushTick((tick) => tick + 1);
+  }, []);
+
+  useEffect(() => {
+    if (flushTick === 0) return;
+    const patch = pending.current;
+    pending.current = {};
+    if (Object.keys(patch).length === 0) return;
+    try {
+      setParamsRef.current?.(patch);
+    } catch {
+      // A host router that cannot take params right now; local state holds.
+    }
+  }, [flushTick]);
+
+  const clear = useCallback(() => {
+    setSearchText("");
+    const current = controlsRef.current;
+    update({
+      search: "",
+      favoritesOnly: false,
+      facets: Object.fromEntries((current.facets ?? []).map((facet) => [facet.param, ""])),
+      ranges: Object.fromEntries((current.ranges ?? []).map((range) => [range.param, 0])),
+    });
+  }, [update]);
+
+  const favorites = useFavorites(favoritesKey);
+
+  const [snapshots, setSnapshots] = useState<Record<string, Snapshot>>({});
+  const handlers = useRef(new Map<string, (snapshot: Snapshot) => void>());
+  const handlerFor = useCallback((key: string) => {
+    let handler = handlers.current.get(key);
+    if (!handler) {
+      handler = (snapshot: Snapshot) => setSnapshots((prev) => ({ ...prev, [key]: snapshot }));
+      handlers.current.set(key, handler);
+    }
+    return handler;
+  }, []);
+
+  const facetsKey = JSON.stringify(
+    (controls.facets ?? []).map(({ param, field, doctype: on, orderBy }) => [
+      param,
+      field,
+      on,
+      orderBy,
+    ]),
+  );
+  const rangeFieldsKey = JSON.stringify((controls.ranges ?? []).map((range) => range.field));
+  const connectionsKey = JSON.stringify(connections ?? null);
+
+  const reads = useMemo(() => {
+    const declared = JSON.parse(connectionsKey) as FrappeConnection[] | null;
+    const facetReads = (controlsRef.current.facets ?? []).map((facet) => ({
+      key: `facet:${facet.param}`,
+      facet,
+      ...facetRead(facet, doctype, declared ?? undefined, limit),
+    }));
+    const rangeFields = JSON.parse(rangeFieldsKey) as string[];
+    const base = readBase
+      ? {
+          key: "base",
+          doctype,
+          options: { fields: ["name", ...rangeFields], limit: limit ?? 0 },
+        }
+      : undefined;
+    return { facetReads: facetReads.filter((read) => read.ready), base };
+    // facetsKey stands for controls.facets, read through the ref.
+  }, [facetsKey, rangeFieldsKey, connectionsKey, doctype, limit, readBase]);
+
+  const facetReadings = useMemo(() => {
+    const readings: Record<string, FacetReading> = {};
+    for (const read of reads.facetReads) {
+      const rows = snapshots[read.key]?.rows ?? [];
+      readings[read.facet.param] = readFacet(read.facet, read.linkField, rows);
+    }
+    return readings;
+  }, [reads, snapshots]);
+
+  const baseRows = reads.base ? snapshots.base?.rows : undefined;
+  const { total, highest } = useMemo(() => {
+    if (!baseRows) return { total: undefined, highest: {} };
+    const peaks: Record<string, number> = {};
+    for (const range of controlsRef.current.ranges ?? []) {
+      peaks[range.param] = baseRows.reduce(
+        (acc, row) => Math.max(acc, Number(row[range.field]) || 0),
+        0,
+      );
+    }
+    return { total: baseRows.length, highest: peaks };
+  }, [baseRows]);
+
+  const readers = (
+    <>
+      {reads.facetReads.map((read) => (
+        <FrappeRowsReader
+          key={read.key}
+          connection={connection}
+          doctype={read.doctype}
+          options={read.options as never}
+          onChange={handlerFor(read.key)}
+        />
+      ))}
+      {reads.base ? (
+        <FrappeRowsReader
+          key="base"
+          connection={connection}
+          doctype={reads.base.doctype}
+          options={reads.base.options as never}
+          onChange={handlerFor("base")}
+        />
+      ) : null}
+    </>
+  );
+
+  return {
+    state,
+    searchText,
+    setSearchText,
+    update,
+    clear,
+    favorites,
+    facets: facetReadings,
+    total,
+    highest,
+    readers,
+  };
+}