@multiplatform.one/frappe-ui 7.23.1 → 7.24.0

package/src/list/RecordCard.tsx

@@ -0,0 +1,260 @@
+import { Anchor, Card, Text, XStack, YStack, isWeb } from "@multiplatform.one/components";
+import { Button } from "@multiplatform.one/forms";
+import {
+  ensureFocusVisibleRing,
+  ensureKeyboardModalityTracking,
+  keyboardFocusRingProps,
+  useResolvedKnobs,
+  wasKeyboardFocus,
+} from "@multiplatform.one/theme";
+import { HeartIcon } from "@phosphor-icons/react";
+import { useState } from "react";
+import { useTranslation } from "react-i18next";
+import { FacetBadge } from "./FacetBadge";
+import { ImageWell } from "./ImageWell";
+
+export interface RecordCardBadge {
+  value: string;
+  label: string;
+  tint?: string;
+}
+
+export interface RecordCardProps {
+  title: string;
+  subtitle?: string;
+  /** Stamped on the well's corner ("#025"). */
+  code?: string;
+  /** Image candidates in order; a failed load moves to the next. */
+  images: readonly string[];
+  /** Theme hues painting the well: one fills it, two split it. */
+  tints?: readonly (string | undefined)[];
+  /** Facet values stickered on the well. */
+  badges?: readonly RecordCardBadge[];
+  /** The record's page: the card becomes a real link (SSR, new tab). */
+  href?: string;
+  onPress?: () => void;
+  favorite?: { active: boolean; toggle: () => void };
+  /** Fetch the image only as it nears the viewport. */
+  lazy?: boolean;
+  testID?: string;
+  favoriteTestID?: string;
+}
+
+interface PressLikeEvent {
+  metaKey?: boolean;
+  ctrlKey?: boolean;
+  shiftKey?: boolean;
+  altKey?: boolean;
+  button?: number;
+  preventDefault?: () => void;
+  stopPropagation?: () => void;
+  nativeEvent?: PressLikeEvent;
+}
+
+function isModifiedPress(event?: PressLikeEvent): boolean {
+  const native = event?.nativeEvent ?? event;
+  return Boolean(
+    native &&
+    (native.metaKey ||
+      native.ctrlKey ||
+      native.shiftKey ||
+      native.altKey ||
+      (native.button ?? 0) !== 0),
+  );
+}
+
+/**
+ * A record as a tile: the image well is the card (tinted by the record's
+ * facet, its values stickered on it, its code stamped in the corner) with
+ * the title and a muted subtitle under it. A routed card is a stretched
+ * link with the heart as its sibling button (LC-74), so a first-paint click
+ * on the heart never follows the link; modified clicks keep the browser's
+ * new-tab semantics.
+ */
+export function RecordCard({
+  title,
+  subtitle,
+  code,
+  images,
+  tints,
+  badges = [],
+  href,
+  onPress,
+  favorite,
+  lazy = false,
+  testID,
+  favoriteTestID,
+}: RecordCardProps) {
+  const { t } = useTranslation();
+  const { knobProps, elevation: elevationState } = useResolvedKnobs({ component: "Card" });
+  const focusRing = ensureFocusVisibleRing({ outlineOffset: -2 });
+  const [anchorKeyboardFocus, setAnchorKeyboardFocus] = useState(false);
+  if (isWeb) ensureKeyboardModalityTracking();
+
+  const handlePress = (event: unknown) => {
+    const press = event as PressLikeEvent | undefined;
+    if (href && isModifiedPress(press)) return;
+    press?.preventDefault?.();
+    press?.stopPropagation?.();
+    onPress?.();
+  };
+
+  const handleToggleFavorite = (event: unknown) => {
+    const press = event as PressLikeEvent | undefined;
+    press?.preventDefault?.();
+    press?.stopPropagation?.();
+    press?.nativeEvent?.preventDefault?.();
+    press?.nativeEvent?.stopPropagation?.();
+    favorite?.toggle();
+  };
+
+  const passThrough = href ? "box-none" : undefined;
+  const inert = href ? "none" : undefined;
+
+  return (
+    <Card
+      testID={testID}
+      position="relative"
+      {...knobProps.cardSurface}
+      elevation={knobProps.elevation}
+      cursor="pointer"
+      transition={knobProps.transition}
+      hoverStyle={{ ...elevationState.hoverKnobProps }}
+      pressStyle={{ ...elevationState.pressKnobProps }}
+      {...(href
+        ? anchorKeyboardFocus
+          ? keyboardFocusRingProps
+          : null
+        : {
+            role: "button",
+            "aria-label": title,
+            onPress: handlePress,
+            focusVisibleStyle: focusRing,
+          })}
+    >
+      {href ? (
+        <Anchor
+          href={href as never}
+          position="absolute"
+          top={0}
+          left={0}
+          right={0}
+          bottom={0}
+          zIndex={0}
+          textDecorationLine="none"
+          outlineWidth={0}
+          aria-label={title}
+          onPress={handlePress}
+          {...(isWeb
+            ? {
+                onFocus: () => {
+                  if (wasKeyboardFocus()) setAnchorKeyboardFocus(true);
+                },
+                onBlur: () => setAnchorKeyboardFocus(false),
+              }
+            : undefined)}
+        />
+      ) : null}
+      <YStack gap="$1.5" zIndex={1} pointerEvents={passThrough}>
+        <YStack position="relative" pointerEvents={passThrough}>
+          <ImageWell
+            sources={images}
+            alt={title}
+            tints={tints}
+            inset={0.04}
+            lazy={lazy}
+            pointerEvents={inert}
+          />
+          {code ? (
+            <XStack
+              position="absolute"
+              top="$2"
+              left="$2"
+              {...knobProps.borderRadius}
+              borderWidth={0}
+              backgroundColor="$background08"
+              paddingHorizontal="$1.5"
+              paddingVertical="$0.5"
+              zIndex={1}
+              pointerEvents={inert}
+            >
+              <Text fontSize="$1" fontWeight="800" letterSpacing={1} color="$color12">
+                {code}
+              </Text>
+            </XStack>
+          ) : null}
+          {favorite ? (
+            <XStack
+              position="absolute"
+              top="$1"
+              right="$1"
+              zIndex={2}
+              pointerEvents="auto"
+              {...(isWeb
+                ? {
+                    onClickCapture: (event: { preventDefault: () => void }) => {
+                      event.preventDefault();
+                    },
+                  }
+                : undefined)}
+            >
+              <Button
+                size="$3"
+                circular
+                chromeless
+                minWidth={knobProps.sizeToken}
+                minHeight={knobProps.sizeToken}
+                transition={knobProps.transition}
+                backgroundColor="$background08"
+                hoverStyle={{ backgroundColor: "$background", scale: 1.08 }}
+                pressStyle={{ backgroundColor: "$background", scale: 0.92 }}
+                onPress={handleToggleFavorite}
+                render="button"
+                type="button"
+                col={(favorite.active ? "$red9" : "$color11") as never}
+                icon={<HeartIcon size={20} weight={favorite.active ? "fill" : "regular"} />}
+                aria-label={
+                  favorite.active
+                    ? t("Remove {{name}} from favorites", { name: title })
+                    : t("Add {{name}} to favorites", { name: title })
+                }
+                aria-pressed={favorite.active}
+                testID={favoriteTestID}
+              />
+            </XStack>
+          ) : null}
+          {badges.length > 0 ? (
+            <XStack
+              position="absolute"
+              bottom="$2"
+              left="$2"
+              right="$2"
+              gap="$1.5"
+              flexWrap="wrap"
+              zIndex={1}
+              pointerEvents="none"
+            >
+              {badges.map((badge) => (
+                <FacetBadge key={badge.value} label={badge.label} tint={badge.tint} compact />
+              ))}
+            </XStack>
+          ) : null}
+        </YStack>
+        <YStack gap="$0.5" pointerEvents={inert}>
+          <Text
+            {...knobProps.heading}
+            fontWeight="700"
+            fontSize="$4"
+            numberOfLines={1}
+            color="$color12"
+          >
+            {title}
+          </Text>
+          <Text {...knobProps.body} fontSize="$2" color="$color10" numberOfLines={1}>
+            {subtitle || " "}
+          </Text>
+        </YStack>
+      </YStack>
+    </Card>
+  );
+}

package/src/list/ShufflePanel.tsx

@@ -0,0 +1,107 @@
+import { Button, Wheel, XStack, YStack } from "@multiplatform.one/components";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { ArrowCounterClockwiseIcon, ArrowRightIcon } from "@phosphor-icons/react";
+import type React from "react";
+import { useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
+
+export interface ShufflePanelProps<TDoc extends { name?: string }> {
+  /** DOM id the toggle names in aria-controls. */
+  id?: string;
+  label: string;
+  /** Records to pick from, in wheel order. */
+  rows: readonly TDoc[];
+  /** A record's wheel label. */
+  itemLabel: (doc: TDoc) => string;
+  /** Draws the current pick beside the wheel. */
+  renderPick: (doc: TDoc) => React.ReactNode;
+  onGo: (doc: TDoc) => void;
+  testID?: string;
+}
+
+const pickWidth = "$12";
+
+function randomOtherIndex(current: number, length: number): number {
+  if (length < 2) return Math.max(0, current);
+  const offset = 1 + Math.floor(Math.random() * (length - 1));
+  return (Math.max(0, current) + offset) % length;
+}
+
+/**
+ * Pick a random record: a wheel of record labels beside the current pick.
+ * Drag or flick the wheel, or Spin for a random jump, then Go opens it.
+ */
+export function ShufflePanel<TDoc extends { name?: string }>({
+  id,
+  label,
+  rows,
+  itemLabel,
+  renderPick,
+  onGo,
+  testID,
+}: ShufflePanelProps<TDoc>) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  const named = useMemo(() => rows.filter((row) => row.name), [rows]);
+  const items = useMemo(
+    () => named.map((row) => ({ value: row.name as string, label: itemLabel(row) })),
+    [named, itemLabel],
+  );
+  const [selected, setSelected] = useState<string>(
+    () => named[randomOtherIndex(0, named.length)]?.name ?? "",
+  );
+  // The rows can change while the panel is open; a pick that dropped out
+  // falls back to the first row.
+  const pick = named.find((row) => row.name === selected) ?? named[0];
+  if (!pick) return null;
+
+  const spin = () => {
+    const current = named.findIndex((row) => row.name === pick.name);
+    setSelected(named[randomOtherIndex(current, named.length)]?.name ?? "");
+  };
+
+  return (
+    <XStack
+      id={id}
+      role="region"
+      aria-label={label}
+      {...knobProps.surface}
+      {...knobProps.borderRadius}
+      {...knobProps.panelPadding}
+      {...knobProps.gap}
+      alignItems="center"
+      flexWrap="wrap"
+      testID={testID}
+    >
+      <Wheel
+        items={items}
+        value={pick.name as string}
+        onChange={(next) => setSelected(String(next))}
+        visibleItems={3}
+        loop
+        aria-label={label}
+      />
+      <YStack width={pickWidth} flexShrink={0}>
+        {renderPick(pick)}
+      </YStack>
+      <XStack {...knobProps.gap} alignItems="center" flexShrink={0}>
+        <Button
+          outlined
+          onPress={spin}
+          icon={<ArrowCounterClockwiseIcon size={16} />}
+          testID={testID ? `${testID}-spin` : undefined}
+        >
+          {t("Spin")}
+        </Button>
+        <Button
+          theme="accent"
+          onPress={() => onGo(pick)}
+          iconAfter={<ArrowRightIcon size={16} />}
+          testID={testID ? `${testID}-go` : undefined}
+        >
+          {t("Go")}
+        </Button>
+      </XStack>
+    </XStack>
+  );
+}

package/src/list/facetReading.ts

@@ -0,0 +1,79 @@
+/**
+ * How a facet's values are read: which rows, and how they fold into each
+ * record's values and each value's record count. Pure: no React, no IO.
+ */
+import type { FrappeConnection } from "../frappeConnections";
+import type { FrappeListFacet } from "./listState";
+
+type Row = Record<string, unknown>;
+
+export interface FacetReading {
+  /** Record name to its values, ordered by the facet's `orderBy`. */
+  values: ReadonlyMap<string, string[]>;
+  /** Value to the number of records carrying it. */
+  counts: Readonly<Record<string, number>>;
+}
+
+export interface FacetRead {
+  /** The doctype whose rows carry the facet's field. */
+  doctype: string;
+  /** The field of those rows naming the record; "name" on the list doctype. */
+  linkField: string;
+  options: { fields: string[]; limit: number };
+  /** False while a connection doctype's link is still unknown. */
+  ready: boolean;
+}
+
+/**
+ * The read behind a facet. A connection doctype's read asks for the fields
+ * its declared connection reads too, so both share one collection.
+ */
+export function facetRead(
+  facet: FrappeListFacet,
+  doctype: string,
+  connections: readonly FrappeConnection[] | undefined,
+  limit: number | undefined,
+): FacetRead {
+  const link = facet.doctype
+    ? connections?.find((candidate) => candidate.doctype === facet.doctype)
+    : undefined;
+  const linkField = facet.doctype ? (link?.fieldname ?? "") : "name";
+  const fields = new Set<string>(["name", linkField, facet.field]);
+  if (facet.orderBy) fields.add(facet.orderBy);
+  for (const field of link?.fields ?? []) fields.add(field);
+  fields.delete("");
+  return {
+    doctype: facet.doctype ?? doctype,
+    linkField,
+    options: { fields: [...fields], limit: facet.doctype ? (link?.limit ?? 0) : (limit ?? 0) },
+    ready: !facet.doctype || Boolean(link),
+  };
+}
+
+export function readFacet(
+  facet: FrappeListFacet,
+  linkField: string,
+  rows: readonly Row[],
+): FacetReading {
+  const byRecord = new Map<string, Array<{ value: string; order: number }>>();
+  for (const row of rows) {
+    const record = row[linkField];
+    const value = row[facet.field];
+    if (typeof record !== "string" || !record || value === null || value === undefined) continue;
+    if (value === "") continue;
+    const entry = byRecord.get(record) ?? [];
+    entry.push({
+      value: String(value),
+      order: Number(facet.orderBy ? row[facet.orderBy] : 0) || 0,
+    });
+    byRecord.set(record, entry);
+  }
+  const values = new Map<string, string[]>();
+  const counts: Record<string, number> = {};
+  for (const [record, entries] of byRecord) {
+    const ordered = [...new Set(entries.sort((a, b) => a.order - b.order).map((e) => e.value))];
+    values.set(record, ordered);
+    for (const value of ordered) counts[value] = (counts[value] ?? 0) + 1;
+  }
+  return { values, counts };
+}

package/src/list/favorites.spec.ts

@@ -0,0 +1,80 @@
+/**
+ * The list's favorites: a persistent store per storage key (the
+ * persistent-stores standard: hydration-gated writes, immutable updates),
+ * shared by every reader of that key.
+ */
+import type { Storage } from "@multiplatform.one/store";
+import { describe, expect, it } from "vitest";
+import { createFavoritesStore, favoritesStore, toggleFavoriteIn } from "./favorites";
+
+function makeFakeStorage(seed: Record<string, string> = {}) {
+  const data = new Map(Object.entries(seed));
+  const storage: Storage = {
+    getItem: (name) => data.get(name) ?? null,
+    setItem: (name, value) => {
+      data.set(name, value);
+    },
+    removeItem: (name) => {
+      data.delete(name);
+    },
+  };
+  return { storage, data };
+}
+
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+describe("favorites store", () => {
+  it("toggle adds then removes a name, preserving insertion order", async () => {
+    const { storage } = makeFakeStorage();
+    const store = createFavoritesStore("favs", storage);
+    await flush();
+
+    toggleFavoriteIn(store, "pikachu");
+    toggleFavoriteIn(store, "gengar");
+    expect(store.state.names).toEqual(["pikachu", "gengar"]);
+
+    toggleFavoriteIn(store, "pikachu");
+    expect(store.state.names).toEqual(["gengar"]);
+  });
+
+  it("persists under its key after hydration completes", async () => {
+    const { storage, data } = makeFakeStorage();
+    const store = createFavoritesStore("pokemon-favorites", storage);
+    await flush();
+
+    toggleFavoriteIn(store, "snorlax");
+    await flush();
+
+    expect(JSON.parse(data.get("pokemon-favorites") ?? "{}")).toEqual({ names: ["snorlax"] });
+  });
+
+  it("rehydrates previously persisted favorites", async () => {
+    const { storage } = makeFakeStorage({
+      "pokemon-favorites": JSON.stringify({ names: ["mewtwo", "eevee"] }),
+    });
+    const store = createFavoritesStore("pokemon-favorites", storage);
+    await flush();
+
+    expect(store.state.names).toEqual(["mewtwo", "eevee"]);
+  });
+
+  it("clearPersistedState removes the storage entry", async () => {
+    const { storage, data } = makeFakeStorage({
+      favs: JSON.stringify({ names: ["mew"] }),
+    });
+    const store = createFavoritesStore("favs", storage);
+    await flush();
+
+    await store.clearPersistedState();
+    expect(data.has("favs")).toBe(false);
+  });
+
+  it("hands every reader of one key the same store", () => {
+    expect(favoritesStore("frappe-favorites-Pokemon")).toBe(
+      favoritesStore("frappe-favorites-Pokemon"),
+    );
+    expect(favoritesStore("frappe-favorites-Pokemon")).not.toBe(
+      favoritesStore("frappe-favorites-Poke Move"),
+    );
+  });
+});

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]);
+}