@multiplatform.one/frappe-ui 7.23.1 → 7.24.0

package/src/insights/insightsData.spec.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from "vitest";
+import {
+  average,
+  bucketWidth,
+  facetDistribution,
+  foldDistribution,
+  histogram,
+  multiValued,
+  orderRows,
+  topBy,
+} from "./insightsData";
+
+const rows = [
+  { name: "bulbasaur", xp: 64, height: 7 },
+  { name: "charmander", xp: 62, height: 6 },
+  { name: "charizard", xp: 240, height: 17 },
+  { name: "pikachu", xp: 112, height: 4 },
+  { name: "mew", xp: null, height: 4 },
+];
+
+const types = new Map<string, string[]>([
+  ["bulbasaur", ["grass", "poison"]],
+  ["charmander", ["fire"]],
+  ["charizard", ["fire", "flying"]],
+  ["pikachu", ["electric"]],
+  ["missingno", ["normal"]],
+]);
+
+describe("facetDistribution", () => {
+  it("counts the listed records per value, most common first, ties A to Z", () => {
+    expect(facetDistribution(types, rows)).toEqual([
+      { value: "fire", count: 2 },
+      { value: "electric", count: 1 },
+      { value: "flying", count: 1 },
+      { value: "grass", count: 1 },
+      { value: "poison", count: 1 },
+    ]);
+  });
+
+  it("ignores values of records outside the rows", () => {
+    expect(facetDistribution(types, rows).some((entry) => entry.value === "normal")).toBe(false);
+  });
+});
+
+describe("foldDistribution", () => {
+  const entries = facetDistribution(types, rows);
+
+  it("keeps a distribution that fits", () => {
+    expect(foldDistribution(entries, 5)).toEqual(entries);
+  });
+
+  it("folds the tail into one other entry holding its sum", () => {
+    expect(foldDistribution(entries, 3)).toEqual([
+      { value: "fire", count: 2 },
+      { value: "electric", count: 1 },
+      { value: "", count: 3, other: true },
+    ]);
+  });
+});
+
+describe("multiValued", () => {
+  it("counts the listed records carrying more than one value", () => {
+    expect(multiValued(types, rows)).toBe(2);
+  });
+});
+
+describe("average", () => {
+  it("means a field over every row, a missing value as 0", () => {
+    expect(average(rows, "xp")).toBeCloseTo((64 + 62 + 240 + 112) / 5);
+  });
+
+  it("is 0 for no rows", () => {
+    expect(average([], "xp")).toBe(0);
+  });
+});
+
+describe("topBy", () => {
+  it("ranks by a field, largest first, ties in the rows' order", () => {
+    expect(topBy(rows, "height", 3).map((row) => row.name)).toEqual([
+      "charizard",
+      "bulbasaur",
+      "charmander",
+    ]);
+    expect(
+      topBy(rows, "height", 5)
+        .slice(3)
+        .map((row) => row.name),
+    ).toEqual(["pikachu", "mew"]);
+  });
+
+  it("never mutates its input", () => {
+    const before = rows.map((row) => row.name);
+    topBy(rows, "xp", 2);
+    expect(rows.map((row) => row.name)).toEqual(before);
+  });
+});
+
+describe("histogram", () => {
+  it("buckets a field from 0 and keeps the empty buckets between", () => {
+    expect(histogram(rows, "xp", 60)).toEqual([
+      { label: "0–59", value: 1 },
+      { label: "60–119", value: 3 },
+      { label: "120–179", value: 0 },
+      { label: "180–239", value: 0 },
+      { label: "240–299", value: 1 },
+    ]);
+  });
+
+  it("is empty for no rows", () => {
+    expect(histogram([], "xp", 60)).toEqual([]);
+  });
+
+  it("picks a round width for about six buckets when none is given", () => {
+    expect(bucketWidth(240)).toBe(50);
+    expect(bucketWidth(17)).toBe(5);
+    expect(bucketWidth(0)).toBe(1);
+    expect(histogram(rows, "height").map((bucket) => bucket.label)).toEqual([
+      "0–4",
+      "5–9",
+      "10–14",
+      "15–19",
+    ]);
+  });
+});
+
+describe("orderRows", () => {
+  it("orders by each key in turn, a missing value first ascending", () => {
+    expect(
+      orderRows(rows, [
+        { field: "height", order: "desc" },
+        { field: "name", order: "asc" },
+      ]).map((row) => row.name),
+    ).toEqual(["charizard", "bulbasaur", "charmander", "mew", "pikachu"]);
+    expect(orderRows(rows, [{ field: "xp", order: "asc" }])[0].name).toBe("mew");
+  });
+
+  it("keeps the rows as they are without an order, and never mutates them", () => {
+    expect(orderRows(rows, undefined)).toEqual(rows);
+    const before = rows.map((row) => row.name);
+    orderRows(rows, [{ field: "xp", order: "desc" }]);
+    expect(rows.map((row) => row.name)).toEqual(before);
+  });
+});

package/src/insights/insightsData.ts

@@ -0,0 +1,122 @@
+/**
+ * The aggregates an insights page draws from the rows one list reads and the
+ * values its facet reading found: no React, no IO.
+ */
+
+type Row = { name?: string } & Record<string, unknown>;
+
+export interface InsightsCount {
+  value: string;
+  count: number;
+  /** The folded tail of a distribution. */
+  other?: boolean;
+}
+
+export interface InsightsBucket {
+  /** The bucket's range, "60–119". */
+  label: string;
+  value: number;
+}
+
+function numberOf(row: Row, field: string): number {
+  const value = Number(row[field]);
+  return Number.isFinite(value) ? value : 0;
+}
+
+/** Records per facet value among `rows`, most common first, ties A to Z. */
+export function facetDistribution(
+  values: ReadonlyMap<string, readonly string[]>,
+  rows: readonly Row[],
+): InsightsCount[] {
+  const counts = new Map<string, number>();
+  for (const row of rows) {
+    for (const value of values.get(row.name ?? "") ?? []) {
+      counts.set(value, (counts.get(value) ?? 0) + 1);
+    }
+  }
+  return [...counts]
+    .map(([value, count]) => ({ value, count }))
+    .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
+}
+
+/** At most `max` entries: the tail folds into one `other` entry holding its sum. */
+export function foldDistribution(entries: readonly InsightsCount[], max: number): InsightsCount[] {
+  if (entries.length <= max) return [...entries];
+  const kept = entries.slice(0, Math.max(0, max - 1));
+  const tail = entries.slice(kept.length).reduce((sum, entry) => sum + entry.count, 0);
+  return [...kept, { value: "", count: tail, other: true }];
+}
+
+/** Records among `rows` carrying more than one facet value. */
+export function multiValued(
+  values: ReadonlyMap<string, readonly string[]>,
+  rows: readonly Row[],
+): number {
+  return rows.filter((row) => (values.get(row.name ?? "") ?? []).length > 1).length;
+}
+
+export function average(rows: readonly Row[], field: string): number {
+  if (rows.length === 0) return 0;
+  return rows.reduce((sum, row) => sum + numberOf(row, field), 0) / rows.length;
+}
+
+function compareValues(a: unknown, b: unknown): number {
+  if (a === b) return 0;
+  if (a === null || a === undefined) return -1;
+  if (b === null || b === undefined) return 1;
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  return String(a).localeCompare(String(b));
+}
+
+/**
+ * The rows in an order-by's order, key by key: a collection does not promise
+ * it (a fixture corpus answers in insertion order), and ranks break their
+ * ties in this order.
+ */
+export function orderRows<TRow extends Row>(
+  rows: readonly TRow[],
+  orderBy: ReadonlyArray<{ field: string; order: string }> | undefined,
+): TRow[] {
+  if (!orderBy?.length) return [...rows];
+  return [...rows].sort((a, b) => {
+    for (const { field, order } of orderBy) {
+      const compared = compareValues(a[field], b[field]);
+      if (compared !== 0) return order === "desc" ? -compared : compared;
+    }
+    return 0;
+  });
+}
+
+/** The `n` rows with the largest `field`; ties keep the rows' order. */
+export function topBy<TRow extends Row>(rows: readonly TRow[], field: string, n: number): TRow[] {
+  return [...rows].sort((a, b) => numberOf(b, field) - numberOf(a, field)).slice(0, Math.max(0, n));
+}
+
+/** A round bucket width (1, 2 or 5 times a power of ten) for about six buckets up to `max`. */
+export function bucketWidth(max: number): number {
+  const raw = max / 6;
+  if (!(raw > 1)) return 1;
+  const magnitude = 10 ** Math.floor(Math.log10(raw));
+  return [1, 2, 5, 10].map((step) => step * magnitude).find((width) => width >= raw) ?? raw;
+}
+
+/**
+ * Counts of `field` in `width`-wide buckets from 0, empty buckets between
+ * occupied ones kept so a bar chart's axis reads as a scale.
+ */
+export function histogram(rows: readonly Row[], field: string, width?: number): InsightsBucket[] {
+  if (rows.length === 0) return [];
+  const values = rows.map((row) => Math.max(0, numberOf(row, field)));
+  const size = width && width > 0 ? width : bucketWidth(Math.max(...values));
+  const counts = new Map<number, number>();
+  let last = 0;
+  for (const value of values) {
+    const bucket = Math.floor(value / size);
+    counts.set(bucket, (counts.get(bucket) ?? 0) + 1);
+    last = Math.max(last, bucket);
+  }
+  return Array.from({ length: last + 1 }, (_, bucket) => ({
+    label: `${bucket * size}–${(bucket + 1) * size - 1}`,
+    value: counts.get(bucket) ?? 0,
+  }));
+}

package/src/insights/insightsRecord.ts

@@ -0,0 +1,36 @@
+/** A record as the insights sections draw it, resolved once by FrappeInsights. */
+export interface InsightsRecordView<TDoc> {
+  title: (doc: TDoc) => string;
+  code: (doc: TDoc) => string | undefined;
+  images: (doc: TDoc) => string[];
+  /** The facet values' tints, first value first. */
+  tints: (doc: TDoc) => (string | undefined)[];
+  /** The record's facet values. */
+  values: (doc: TDoc) => string[];
+  valueLabel: (value: string) => string;
+  valueTint: (value: string) => string | undefined;
+  open: (doc: TDoc) => void;
+}
+
+export interface FrappeInsightsMetric {
+  /** A numeric field of the doctype. */
+  field: string;
+  label: string;
+  /** A value as shown (units, precision); defaults to the number. */
+  format?: (value: number) => string;
+  /** Names the metric's record-holder tile ("Tallest"); without it, no tile. */
+  record?: string;
+  /** Histogram bucket width; defaults to a round width for about six buckets. */
+  bucket?: number;
+  /** A record page fills a bar under the value to this ceiling. */
+  max?: number;
+}
+
+export function metricValue(doc: unknown, field: string): number {
+  const value = Number((doc as Record<string, unknown>)[field]);
+  return Number.isFinite(value) ? value : 0;
+}
+
+export function formatMetric(metric: FrappeInsightsMetric, value: number): string {
+  return metric.format ? metric.format(value) : String(value);
+}

package/src/list/FacetBadge.tsx

@@ -0,0 +1,41 @@
+import { Text, XStack } from "@multiplatform.one/components";
+import { hairlineWidth, useResolvedKnobs } from "@multiplatform.one/theme";
+
+export interface FacetBadgeProps {
+  label: string;
+  /** Theme hue (`"grass"`) painting the badge from its ramp. */
+  tint?: string;
+  /** A step smaller, for image wells and table cells. */
+  compact?: boolean;
+}
+
+/**
+ * One facet value as a static badge: nested density (LC-73), the tint's
+ * step-4 fill, step-7 border and step-12 text (DF-04, AA in both schemes).
+ */
+export function FacetBadge({ label, tint = "gray", compact = false }: FacetBadgeProps) {
+  const { knobProps } = useResolvedKnobs({ compact: true });
+  return (
+    <XStack
+      {...knobProps.borderRadius}
+      paddingHorizontal={compact ? "$1.5" : "$2"}
+      paddingVertical={compact ? "$0.5" : "$1"}
+      backgroundColor={`$${tint}4` as never}
+      borderColor={`$${tint}7` as never}
+      borderWidth={hairlineWidth}
+      alignItems="center"
+    >
+      <Text
+        {...knobProps.label}
+        {...knobProps.body}
+        textTransform="capitalize"
+        fontWeight="700"
+        color={`$${tint}12` as never}
+        {...(compact ? { fontSize: "$1" as const } : null)}
+        letterSpacing={0.3}
+      >
+        {label}
+      </Text>
+    </XStack>
+  );
+}

package/src/list/FacetRail.tsx

@@ -0,0 +1,235 @@
+import { ScrollView, Text, XStack, isWeb } from "@multiplatform.one/components";
+import {
+  ensureKeyboardModalityTracking,
+  keyboardFocusRingProps,
+  pressTargetHitSlop,
+  transitionProps,
+  useResolvedKnobs,
+  wasKeyboardFocus,
+} from "@multiplatform.one/theme";
+import { useRef, useState } from "react";
+
+export interface FacetRailOption {
+  /** Facet value; "" is the chip that clears the facet. */
+  value: string;
+  label: string;
+  /** Theme hue (`"grass"`) painting the chip from its ramp. */
+  tint?: string;
+  count?: number;
+}
+
+export interface FacetRailProps {
+  /** Names the radiogroup. */
+  label: string;
+  /** Active value, or "" for none. */
+  value: string;
+  options: readonly FacetRailOption[];
+  onChange: (value: string) => void;
+  testID?: string;
+}
+
+interface RailChipProps {
+  option: FacetRailOption;
+  selected: boolean;
+  tabStop: boolean;
+  onPress: () => void;
+  onFocusChip: () => void;
+  onBlurChip: () => void;
+  onMove: (direction: -1 | 1 | "home" | "end") => void;
+  testID?: string;
+  register: (node: { focus?: () => void } | null) => void;
+}
+
+// Chips paint a notch under the ~40px toolbar controls; hitSlop restores the
+// 44px press target (DG-LAY-04, ViewSwitcher precedent).
+const chipVisualHeight = 38;
+const chipHitSlop = pressTargetHitSlop(chipVisualHeight);
+const pipSize = "$1";
+
+/**
+ * One chip. Neutral until active; the active chip fills from its tint ramp
+ * (DF-04 pairing: tint fill, step-12 text), so selected is fill, never a
+ * sibling border (LC-71). An unselected tinted chip carries a hue pip.
+ */
+function RailChip({
+  option,
+  selected,
+  tabStop,
+  onPress,
+  onFocusChip,
+  onBlurChip,
+  onMove,
+  testID,
+  register,
+}: RailChipProps) {
+  const { knobProps } = useResolvedKnobs();
+  const [kbFocus, setKbFocus] = useState(false);
+  if (isWeb) ensureKeyboardModalityTracking();
+  const hue = option.tint;
+  const fill = selected ? (hue ? `$${hue}5` : "$color5") : hue ? `$${hue}3` : "$color3";
+  const hoverFill = selected ? fill : hue ? `$${hue}4` : "$color4";
+  const textColor = selected ? (hue ? `$${hue}12` : "$color12") : hue ? `$${hue}11` : "$color11";
+  const keys: Record<string, -1 | 1 | "home" | "end"> = {
+    ArrowRight: 1,
+    ArrowLeft: -1,
+    Home: "home",
+    End: "end",
+  };
+
+  return (
+    <XStack
+      ref={register}
+      {...knobProps.borderRadius}
+      backgroundColor={fill as never}
+      borderWidth={0}
+      paddingHorizontal="$3"
+      minHeight={chipVisualHeight}
+      hitSlop={chipHitSlop}
+      alignItems="center"
+      gap="$1.5"
+      cursor="pointer"
+      role="radio"
+      aria-checked={selected}
+      {...(isWeb ? { tabIndex: tabStop ? 0 : -1 } : undefined)}
+      {...transitionProps(knobProps.transition)}
+      hoverStyle={{ backgroundColor: hoverFill as never }}
+      pressStyle={{ backgroundColor: fill as never }}
+      outlineWidth={0}
+      focusStyle={{ outlineWidth: 0, backgroundColor: fill as never }}
+      focusVisibleStyle={{ outlineWidth: 0 }}
+      {...(isWeb
+        ? {
+            onFocus: () => {
+              onFocusChip();
+              if (wasKeyboardFocus()) setKbFocus(true);
+            },
+            onBlur: () => {
+              onBlurChip();
+              setKbFocus(false);
+            },
+            onKeyDown: (event: { key?: string; preventDefault?: () => void }) => {
+              const direction = event.key ? keys[event.key] : undefined;
+              if (direction !== undefined) {
+                event.preventDefault?.();
+                onMove(direction);
+                return;
+              }
+              if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault?.();
+                onPress();
+              }
+            },
+          }
+        : undefined)}
+      {...(kbFocus ? keyboardFocusRingProps : undefined)}
+      onPress={onPress}
+      testID={testID}
+    >
+      {hue ? (
+        <XStack
+          width={pipSize}
+          height={pipSize}
+          borderRadius={1000}
+          backgroundColor={`$${hue}9` as never}
+          flexShrink={0}
+        />
+      ) : null}
+      <Text
+        {...knobProps.label}
+        fontWeight={selected ? "700" : "500"}
+        color={textColor as never}
+        textTransform="capitalize"
+        userSelect="none"
+      >
+        {option.label}
+      </Text>
+      {typeof option.count === "number" ? (
+        <Text
+          {...knobProps.label}
+          fontSize="$1"
+          fontWeight="700"
+          color={textColor as never}
+          opacity={0.7}
+          userSelect="none"
+        >
+          {option.count}
+        </Text>
+      ) : null}
+    </XStack>
+  );
+}
+
+/**
+ * A single-select facet as a horizontally scrolling chip rail. One tap
+ * narrows, a second tap on the active chip clears. One tab stop (LC-49):
+ * arrows, Home and End move and select like a radiogroup, and the focused
+ * chip paints the only ring (LC-71). Scrolls on narrow viewports instead of
+ * wrapping into a wall of chips.
+ */
+export function FacetRail({ label, value, options, onChange, testID }: FacetRailProps) {
+  const itemRefs = useRef<Record<string, { focus?: () => void } | null>>({});
+  const [focusValue, setFocusValue] = useState<string | null>(null);
+  if (isWeb) ensureKeyboardModalityTracking();
+
+  const anchor =
+    focusValue !== null && options.some((option) => option.value === focusValue)
+      ? focusValue
+      : value;
+
+  const focusAndSelect = (next: string) => {
+    setFocusValue(next);
+    onChange(next);
+    if (!isWeb) return;
+    requestAnimationFrame(() => {
+      const node = itemRefs.current[next] as
+        | ({ focus?: () => void } & { scrollIntoView?: (options: object) => void })
+        | null;
+      node?.focus?.();
+      node?.scrollIntoView?.({ inline: "nearest", block: "nearest" });
+    });
+  };
+
+  const moveFrom = (from: string, direction: -1 | 1 | "home" | "end") => {
+    if (options.length === 0) return;
+    if (direction === "home") return focusAndSelect(options[0].value);
+    if (direction === "end") return focusAndSelect(options[options.length - 1].value);
+    const index = Math.max(
+      0,
+      options.findIndex((option) => option.value === from),
+    );
+    focusAndSelect(options[(index + direction + options.length) % options.length].value);
+  };
+
+  return (
+    <ScrollView horizontal showsHorizontalScrollIndicator={false} flexShrink={0}>
+      <XStack
+        role="radiogroup"
+        aria-label={label}
+        aria-orientation="horizontal"
+        gap="$1.5"
+        alignItems="center"
+        paddingVertical="$1"
+        testID={testID}
+      >
+        {options.map((option) => (
+          <RailChip
+            key={option.value || "__all"}
+            option={option}
+            selected={option.value === value}
+            tabStop={option.value === anchor}
+            onPress={() =>
+              onChange(option.value === value && option.value !== "" ? "" : option.value)
+            }
+            onFocusChip={() => setFocusValue(option.value)}
+            onBlurChip={() => setFocusValue((prev) => (prev === option.value ? null : prev))}
+            onMove={(direction) => moveFrom(option.value, direction)}
+            testID={testID ? `${testID}-${option.value || "all"}` : undefined}
+            register={(node) => {
+              itemRefs.current[option.value] = node;
+            }}
+          />
+        ))}
+      </XStack>
+    </ScrollView>
+  );
+}

package/src/list/ImageWell.tsx

@@ -0,0 +1,110 @@
+import {
+  Image,
+  Text,
+  XStack,
+  YStack,
+  isWeb,
+  type YStackProps,
+} from "@multiplatform.one/components";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useEffect, useState } from "react";
+
+export interface ImageWellProps extends Omit<YStackProps, "children"> {
+  /** Candidate URLs in order; a failed load moves to the next. */
+  sources: readonly string[];
+  alt: string;
+  /**
+   * Theme hues (`"grass"`) painting the well from their ramps: one fills it,
+   * two split it down the middle.
+   */
+  tints?: readonly (string | undefined)[];
+  /** Nearest-neighbor upscaling, for pixel art. */
+  pixelated?: boolean;
+  /** Gap between the well's edge and the image, as a fraction of its width. */
+  inset?: number;
+  /** Fetch only as the image nears the viewport (web). */
+  lazy?: boolean;
+}
+
+/**
+ * A square image well: a tinted surface (the tint is data, from the theme's
+ * ramps) holding an image that walks its candidate list on error and fades
+ * in on web, with a "?" when every candidate fails.
+ */
+export function ImageWell({
+  sources,
+  alt,
+  tints,
+  pixelated = false,
+  inset = 0.06,
+  lazy = false,
+  ...wellProps
+}: ImageWellProps) {
+  const { knobProps } = useResolvedKnobs();
+  const [sourceIndex, setSourceIndex] = useState(0);
+  const [revealedSrc, setRevealedSrc] = useState<string | null>(null);
+  const hue = tints?.[0] ?? "gray";
+  const secondHue = tints?.[1];
+
+  const sourceKey = sources.join("|");
+  useEffect(() => {
+    setSourceIndex(0);
+  }, [sourceKey]);
+
+  const src = sources[sourceIndex] ?? "";
+  // onLoad can be missed for a cached or server-rendered image, so a short
+  // timer reveals it anyway: a slow image may pop, but none stays invisible.
+  const revealed = !isWeb || !src || revealedSrc === src;
+  useEffect(() => {
+    if (!isWeb || !src || revealedSrc === src) return;
+    const timer = setTimeout(() => setRevealedSrc(src), 350);
+    return () => clearTimeout(timer);
+  }, [src, revealedSrc]);
+
+  const imageSize = `${Math.round((1 - inset * 2) * 100)}%`;
+
+  return (
+    <YStack
+      {...knobProps.borderRadius}
+      borderWidth={0}
+      backgroundColor={secondHue ? "transparent" : (`$${hue}5` as never)}
+      aspectRatio={1}
+      width="100%"
+      alignItems="center"
+      justifyContent="center"
+      overflow="hidden"
+      position="relative"
+      {...wellProps}
+    >
+      {secondHue ? (
+        <XStack fullscreen zIndex={0} pointerEvents="none">
+          <YStack flex={1} backgroundColor={`$${hue}5` as never} />
+          <YStack flex={1} backgroundColor={`$${secondHue}5` as never} />
+        </XStack>
+      ) : null}
+      {src ? (
+        <Image
+          key={src}
+          src={src}
+          alt={alt}
+          width={imageSize as never}
+          height={imageSize as never}
+          objectFit="contain"
+          opacity={revealed ? 1 : 0}
+          transition={knobProps.transition}
+          zIndex={1}
+          {...((isWeb ? { loading: lazy ? "lazy" : "eager", decoding: "async" } : undefined) as
+            | Record<string, unknown>
+            | undefined)}
+          {...(pixelated && isWeb ? { style: { imageRendering: "pixelated" } as never } : null)}
+          onLoad={() => setRevealedSrc(src)}
+          onError={() => setSourceIndex((index) => index + 1)}
+        />
+      ) : (
+        <Text fontSize="$10" color={`$${hue}8` as never} fontWeight="700" aria-hidden zIndex={1}>
+          ?
+        </Text>
+      )}
+    </YStack>
+  );
+}