@multiplatform.one/frappe-ui 7.23.2 → 7.24.0

package/src/insights/InsightsRecords.tsx

@@ -0,0 +1,71 @@
+import { Text, XStack, YStack } from "@multiplatform.one/components";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { ImageWell } from "../list/ImageWell";
+import type { InsightsRecordView } from "./insightsRecord";
+
+export interface InsightsRecordTile<TDoc> {
+  id: string;
+  label: string;
+  doc: TDoc;
+  value: string;
+}
+
+export interface InsightsRecordsProps<TDoc> {
+  tiles: readonly InsightsRecordTile<TDoc>[];
+  record: InsightsRecordView<TDoc>;
+  testID?: string;
+}
+
+/**
+ * Record holders as quiet fact tiles: the holder's tinted image well, its
+ * title and code, and the value. Nested chrome steps with the compact
+ * nestedControl, not the page's 44px floor (LC-73).
+ */
+export function InsightsRecords<TDoc>({ tiles, record, testID }: InsightsRecordsProps<TDoc>) {
+  const { knobProps } = useResolvedKnobs({ compact: true });
+  const { knobProps: pageKnobs } = useResolvedKnobs();
+  const wellPx = knobProps.nestedControl.px * 2;
+  return (
+    <XStack {...pageKnobs.gap} flexWrap="wrap" testID={testID}>
+      {tiles.map((tile) => {
+        const title = record.title(tile.doc);
+        const code = record.code(tile.doc);
+        const tints = record.tints(tile.doc);
+        return (
+          <XStack
+            key={tile.id}
+            {...knobProps.cardSurface}
+            backgroundColor="$color2"
+            flexGrow={1}
+            flexBasis={220}
+            alignItems="center"
+            minWidth={0}
+            {...knobProps.gap}
+          >
+            <YStack width={wellPx} flexShrink={0} data-nested-px={knobProps.nestedControl.px}>
+              <ImageWell sources={record.images(tile.doc)} alt={title} tints={tints} inset={0.04} />
+            </YStack>
+            <YStack gap="$1" flexShrink={1} minWidth={0}>
+              <Text {...knobProps.label} color="$color10">
+                {tile.label}
+              </Text>
+              <XStack gap="$1.5" alignItems="baseline" flexWrap="wrap" minWidth={0}>
+                <Text fontWeight="700" numberOfLines={1} flexShrink={1}>
+                  {title}
+                </Text>
+                {code ? (
+                  <Text {...knobProps.label} color="$color10" fontWeight="600">
+                    {code}
+                  </Text>
+                ) : null}
+              </XStack>
+              <Text fontSize="$6" fontWeight="700">
+                {tile.value}
+              </Text>
+            </YStack>
+          </XStack>
+        );
+      })}
+    </XStack>
+  );
+}

package/src/insights/InsightsTable.tsx

@@ -0,0 +1,169 @@
+import { Avatar, Text, XStack, YStack } from "@multiplatform.one/components";
+import { DataTable, type DataTableColumn, type DataTableData } from "@multiplatform.one/table";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import { FacetBadge } from "../list/FacetBadge";
+import {
+  formatMetric,
+  metricValue,
+  type FrappeInsightsMetric,
+  type InsightsRecordView,
+} from "./insightsRecord";
+
+interface TableRow<TDoc> extends DataTableData {
+  doc: TDoc;
+  code: string;
+  title: string;
+  values: string[];
+  [metric: string]: unknown;
+}
+
+export interface InsightsTableProps<TDoc> {
+  rows: readonly TDoc[];
+  metrics: readonly FrappeInsightsMetric[];
+  record: InsightsRecordView<TDoc>;
+  /** Header of the facet column; without it, no facet column. */
+  facetLabel?: string;
+  pageSize?: number;
+  label: string;
+  testID?: string;
+}
+
+/**
+ * Every record in the catalog DataTable: sortable metric columns, a pager,
+ * and the stacked card layout below `$sm`. A row opens its record.
+ */
+export function InsightsTable<TDoc>({
+  rows,
+  metrics,
+  record,
+  facetLabel,
+  pageSize = 5,
+  label,
+  testID,
+}: InsightsTableProps<TDoc>) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs({ compact: true });
+  const nestedPx = knobProps.nestedControl.px;
+  const hasCode = rows.some((doc) => Boolean(record.code(doc)));
+
+  const data = useMemo<TableRow<TDoc>[]>(
+    () =>
+      rows.map((doc) => ({
+        doc,
+        code: record.code(doc) ?? "",
+        title: record.title(doc),
+        values: record.values(doc),
+        ...Object.fromEntries(
+          metrics.map((metric) => [metric.field, metricValue(doc, metric.field)]),
+        ),
+      })),
+    [rows, metrics, record],
+  );
+
+  const columns = useMemo<DataTableColumn<TableRow<TDoc>>[]>(
+    () => [
+      ...(hasCode
+        ? [
+            {
+              id: "code",
+              accessorKey: "code",
+              header: t("No."),
+              size: 72,
+              cell: ({ row }: { row: { original: TableRow<TDoc> } }) => (
+                <Text {...knobProps.label} color="$color10" fontWeight="600">
+                  {row.original.code}
+                </Text>
+              ),
+            } satisfies DataTableColumn<TableRow<TDoc>>,
+          ]
+        : []),
+      {
+        id: "record",
+        accessorKey: "title",
+        header: t("Record"),
+        cell: ({ row }) => (
+          <XStack gap="$2" alignItems="center" minWidth={0}>
+            <Avatar
+              src={record.images(row.original.doc)[0] || undefined}
+              name={row.original.title}
+              fallbackBackgroundColor="$color4"
+              size={nestedPx}
+              data-nested-px={nestedPx}
+            />
+            <YStack flexShrink={1} minWidth={0}>
+              <Text fontWeight="600" numberOfLines={1}>
+                {row.original.title}
+              </Text>
+            </YStack>
+          </XStack>
+        ),
+      },
+      ...(facetLabel
+        ? [
+            {
+              id: "facet",
+              header: facetLabel,
+              accessorFn: (row: TableRow<TDoc>) => row.values.join(", "),
+              enableSorting: false,
+              sortable: false,
+              cell: ({ row }: { row: { original: TableRow<TDoc> } }) => (
+                <XStack gap="$1.5" flexWrap="wrap">
+                  {row.original.values.length > 0 ? (
+                    row.original.values.map((value) => (
+                      <FacetBadge
+                        key={value}
+                        label={record.valueLabel(value)}
+                        tint={record.valueTint(value)}
+                        compact
+                      />
+                    ))
+                  ) : (
+                    <Text {...knobProps.label} color="$color10">
+                      —
+                    </Text>
+                  )}
+                </XStack>
+              ),
+            } satisfies DataTableColumn<TableRow<TDoc>>,
+          ]
+        : []),
+      ...metrics.map(
+        (metric, index) =>
+          ({
+            id: metric.field,
+            accessorKey: metric.field,
+            header: metric.label,
+            align: "right",
+            cell: ({ row }: { row: { original: TableRow<TDoc> } }) => (
+              <Text fontWeight={index === 0 ? "700" : undefined}>
+                {formatMetric(metric, row.original[metric.field] as number)}
+              </Text>
+            ),
+          }) satisfies DataTableColumn<TableRow<TDoc>>,
+      ),
+    ],
+    [t, hasCode, facetLabel, metrics, record, nestedPx, knobProps.label],
+  );
+
+  return (
+    <YStack testID={testID}>
+      <DataTable
+        data={data}
+        columns={columns}
+        enableFiltering={false}
+        enableGlobalSearch={false}
+        enableSorting
+        enablePagination
+        pageSizeOptions={[pageSize, pageSize * 2, pageSize * 5]}
+        initialState={{ pagination: { pageIndex: 0, pageSize } }}
+        readOnly
+        columnLayout="auto"
+        onRowPress={(row) => record.open(row.doc)}
+        rowLabel={(row) => row.title}
+        aria-label={label}
+      />
+    </YStack>
+  );
+}

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