@multiplatform.one/frappe-ui 7.23.2 → 7.25.0

package/src/record/RecordPage.tsx

@@ -0,0 +1,358 @@
+import {
+  Breadcrumbs,
+  Chip,
+  H1,
+  PageHeader,
+  PageSection,
+  Quote,
+  Screen,
+  ScreenToolbar,
+  Tabs,
+  Text,
+  Timeline,
+  Tooltip,
+  XStack,
+  YStack,
+  type TimelineEntry,
+} from "@multiplatform.one/components";
+import { Button } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { ArrowLeftIcon, HeartIcon } from "@phosphor-icons/react";
+import type { ComponentType } from "react";
+import { useTranslation } from "react-i18next";
+import { frappeRouteHref } from "../frappeNavigation";
+import { metricValue, type FrappeInsightsMetric } from "../insights/insightsRecord";
+import { FacetBadge } from "../list/FacetBadge";
+import { favoritesKey, useFavorites } from "../list/favorites";
+import type { FrappeListFacet } from "../list/listState";
+import { recordTitle, type FrappeRecordLook } from "../list/recordLook";
+import { adjacentRecords, recordFacetValues, recordHistory } from "./recordData";
+import { RecordBars } from "./RecordBars";
+import { RecordGallery } from "./RecordGallery";
+import {
+  RecordHeroArtColumn,
+  RecordHeroFrame,
+  RecordHeroIdentityColumn,
+  RecordHeroRow,
+  RecordVitals,
+} from "./RecordHero";
+import { RecordPager, type RecordPagerEntry } from "./RecordPager";
+import { RecordRows } from "./RecordRows";
+import type { FrappeRecordSection, FrappeRecordTab } from "./recordSections";
+
+/** A hop from the record to another page of it (the backoffice form). */
+export interface FrappeRecordAction<TDoc> {
+  label: string;
+  icon: ComponentType<{ size?: number }>;
+  href: (doc: Partial<TDoc>) => string;
+  testID?: string;
+}
+
+type Row = Record<string, unknown>;
+
+export interface RecordPageProps<TDoc extends { name: string; doctype: string }> {
+  doc: Partial<TDoc>;
+  linked: Record<string, Row[]>;
+  doctype: string;
+  route: string;
+  listName: string;
+  listRows: Partial<TDoc>[];
+  look?: FrappeRecordLook<TDoc>;
+  titleField?: string;
+  facet?: FrappeListFacet;
+  metrics: readonly FrappeInsightsMetric[];
+  summary?: (doc: Partial<TDoc>) => { text: string; cite?: string } | undefined;
+  tabs: readonly FrappeRecordTab[];
+  favorites?: boolean | string;
+  actions: readonly FrappeRecordAction<TDoc>[];
+  history: boolean;
+  slug: string;
+  baseURL?: string;
+  navigate: (href: string) => void;
+  /** The session may write this record: Edit shows. */
+  canEdit: boolean;
+}
+
+/**
+ * A record page drawn from a record already read: the header with Back,
+ * the heart, hops and Edit; the hero; the tabs; the neighbors. The data
+ * wrapper (FrappeRecordView) reads the record, its rows and the rights.
+ */
+export function RecordPage<TDoc extends { name: string; doctype: string }>({
+  doc,
+  linked,
+  doctype,
+  route,
+  listName,
+  listRows,
+  look,
+  titleField,
+  facet,
+  metrics,
+  summary,
+  tabs,
+  favorites,
+  actions,
+  history,
+  slug,
+  baseURL,
+  navigate,
+  canEdit,
+}: RecordPageProps<TDoc>) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  const { knobProps: nested } = useResolvedKnobs({ compact: true });
+  const row = doc as Row;
+  const name = String(row.name ?? "");
+  const { isFavorite, toggle } = useFavorites(
+    favorites ? (typeof favorites === "string" ? favorites : favoritesKey(doctype)) : undefined,
+  );
+
+  const title = recordTitle(doc, look, titleField);
+  const code = look?.code?.(doc);
+  const values = facet ? recordFacetValues(facet, row, linked) : [];
+  const tints = values.slice(0, 2).map((value) => facet?.tint?.(value));
+  const images = look?.images?.(doc, baseURL) ?? [];
+  const slides = (look?.gallery?.(doc, baseURL) ?? []).filter(
+    (slide) => slide.src && slide.src !== images[0],
+  );
+  const favorite = favorites ? isFavorite(name) : false;
+  const favoriteLabel = favorite
+    ? t("Remove {{name}} from favorites", { name: title })
+    : t("Add {{name}} to favorites", { name: title });
+
+  const { prev, next } = adjacentRecords(listRows, name);
+  const pagerEntry = (neighbor: Partial<TDoc> | null): RecordPagerEntry | null =>
+    neighbor?.name
+      ? {
+          title: recordTitle(neighbor, look, titleField),
+          code: look?.code?.(neighbor),
+          image: look?.images?.(neighbor, baseURL)[0],
+          onPress: () =>
+            navigate(frappeRouteHref(route, { mode: "view", name: neighbor.name as string })),
+        }
+      : null;
+
+  const entries: TimelineEntry[] = history
+    ? recordHistory(row).map((entry) =>
+        entry.kind === "modified"
+          ? {
+              id: `${name}-modified`,
+              type: "version",
+              author: entry.author,
+              timestamp: entry.timestamp,
+            }
+          : {
+              id: `${name}-created`,
+              type: "info",
+              author: entry.author,
+              content: t("Created this {{doctype}}", { doctype }),
+              timestamp: entry.timestamp,
+            },
+      )
+    : [];
+
+  const drawSection = (section: FrappeRecordSection, index: number) => {
+    if (section.kind === "bars") {
+      const tableRows = Array.isArray(row[section.table]) ? (row[section.table] as Row[]) : [];
+      return (
+        <RecordBars
+          key={`bars-${section.id}`}
+          rows={tableRows}
+          section={section}
+          testID={`${slug}-${section.id}-chart`}
+        />
+      );
+    }
+    const rows = <RecordRows rows={linked[section.doctype] ?? []} section={section} />;
+    if (!section.title) {
+      return (
+        <YStack key={`rows-${index}`} {...knobProps.gap}>
+          {section.description ? (
+            <Text {...nested.label} color="$color10">
+              {section.description}
+            </Text>
+          ) : null}
+          {rows}
+        </YStack>
+      );
+    }
+    return (
+      <PageSection
+        key={`rows-${index}`}
+        title={section.title}
+        description={section.description}
+        divider={false}
+      >
+        {rows}
+      </PageSection>
+    );
+  };
+
+  const quote = summary?.(doc);
+  const tabItems = tabs.map((tab, index) => {
+    const count = tab.count ? (linked[tab.count] ?? []).length : 0;
+    const Icon = tab.icon;
+    return {
+      value: tab.value,
+      label: tab.label,
+      icon: Icon ? <Icon size={16} /> : undefined,
+      badge: count > 0 ? <Chip size="$2">{count}</Chip> : undefined,
+      content: (
+        <YStack {...knobProps.gapLg}>
+          {index === 0 && quote ? (
+            <Quote marginVertical={0} cite={quote.cite}>
+              {quote.text}
+            </Quote>
+          ) : null}
+          {tab.sections.map(drawSection)}
+          {index === 0 && entries.length > 0 ? (
+            <PageSection title={t("Record history")} surface>
+              <Timeline entries={entries} labels={{ madeChanges: t("last updated this record") }} />
+            </PageSection>
+          ) : null}
+        </YStack>
+      ),
+    };
+  });
+
+  const toolbar = (
+    <ScreenToolbar
+      leading={
+        <Button
+          outlined
+          minHeight={knobProps.sizeToken}
+          onPress={() => navigate(route)}
+          icon={<ArrowLeftIcon size={16} />}
+          testID={`${slug}-detail-back`}
+        >
+          {t("Back")}
+        </Button>
+      }
+      trailing={
+        <XStack {...knobProps.gap} alignItems="center">
+          {favorites || actions.length > 0 ? (
+            <XStack {...knobProps.borderRadius} backgroundColor="$color2" alignItems="center">
+              {favorites ? (
+                <Tooltip content={favoriteLabel}>
+                  <Button
+                    circular
+                    chromeless
+                    minWidth={knobProps.sizeToken}
+                    minHeight={knobProps.sizeToken}
+                    onPress={() => toggle(name)}
+                    col={(favorite ? "$red9" : "$color10") as never}
+                    icon={<HeartIcon size={22} weight={favorite ? "fill" : "regular"} />}
+                    aria-label={favoriteLabel}
+                    aria-pressed={favorite}
+                    render="button"
+                    type="button"
+                    testID={`${slug}-detail-favorite`}
+                  />
+                </Tooltip>
+              ) : null}
+              {actions.map((action) => {
+                const Icon = action.icon;
+                return (
+                  <Tooltip key={action.label} content={action.label}>
+                    <Button
+                      circular
+                      chromeless
+                      minWidth={knobProps.sizeToken}
+                      minHeight={knobProps.sizeToken}
+                      onPress={() => navigate(action.href(doc))}
+                      col={"$color10" as never}
+                      icon={<Icon size={20} />}
+                      aria-label={action.label}
+                      testID={action.testID}
+                    />
+                  </Tooltip>
+                );
+              })}
+            </XStack>
+          ) : null}
+          {canEdit ? (
+            <Button
+              theme="accent"
+              minHeight={knobProps.sizeToken}
+              onPress={() => navigate(frappeRouteHref(route, { mode: "edit", name }))}
+              testID={`${slug}-detail-edit`}
+            >
+              {t("Edit")}
+            </Button>
+          ) : null}
+        </XStack>
+      }
+    />
+  );
+
+  return (
+    <Screen>
+      <YStack gap="$2">
+        <Breadcrumbs
+          items={[{ label: listName, href: route }, { label: code ? `${code} ${title}` : title }]}
+          onNavigate={(href) => navigate(href)}
+        />
+        {toolbar}
+      </YStack>
+
+      <RecordHeroFrame tint={tints[0]} testID={`${slug}-detail-stage`}>
+        <RecordHeroRow>
+          <RecordHeroArtColumn testID={`${slug}-hero-art`}>
+            <RecordGallery images={images} slides={slides} alt={title} tints={tints} />
+          </RecordHeroArtColumn>
+          <RecordHeroIdentityColumn testID={`${slug}-hero-identity`}>
+            {code ? (
+              <Text
+                {...nested.label}
+                fontWeight="700"
+                color={(tints[0] ? `$${tints[0]}11` : "$color11") as never}
+                letterSpacing={1}
+              >
+                {code}
+              </Text>
+            ) : null}
+            <PageHeader
+              heading={
+                <H1 margin={0} size="$10" $max-sm={{ size: "$9" }}>
+                  {title}
+                </H1>
+              }
+              subtitle={look?.subtitle?.(doc) || undefined}
+              divider={false}
+            />
+            {values.length > 0 ? (
+              <XStack gap="$2" flexWrap="wrap">
+                {values.map((value) => (
+                  <FacetBadge
+                    key={value}
+                    label={facet?.optionLabel?.(value) ?? value}
+                    tint={facet?.tint?.(value)}
+                  />
+                ))}
+              </XStack>
+            ) : null}
+            <RecordVitals
+              tiles={metrics.map((metric) => {
+                const value = metricValue(doc, metric.field);
+                return {
+                  id: metric.field,
+                  label: metric.label,
+                  value: metric.format ? metric.format(value) : String(value),
+                  percent: metric.max ? Math.min((value / metric.max) * 100, 100) : undefined,
+                };
+              })}
+            />
+          </RecordHeroIdentityColumn>
+        </RecordHeroRow>
+      </RecordHeroFrame>
+
+      <YStack {...knobProps.gapLg} paddingBottom="$6">
+        {tabItems.length > 0 ? (
+          <Tabs defaultValue={tabItems[0]?.value} lazyMount items={tabItems} />
+        ) : null}
+        <RecordPager prev={pagerEntry(prev)} next={pagerEntry(next)} testID={slug} />
+      </YStack>
+    </Screen>
+  );
+}

package/src/record/RecordPager.tsx

@@ -0,0 +1,97 @@
+import { Avatar, Text, XStack, YStack } from "@multiplatform.one/components";
+import { Button } from "@multiplatform.one/forms";
+import { sizeRecipeEscape, useResolvedKnobs } from "@multiplatform.one/theme";
+import { ArrowLeftIcon, ArrowRightIcon } from "@phosphor-icons/react";
+import { useTranslation } from "react-i18next";
+
+export interface RecordPagerEntry {
+  title: string;
+  code?: string;
+  image?: string;
+  onPress: () => void;
+}
+
+function PagerButton({
+  direction,
+  entry,
+  testID,
+}: {
+  direction: "prev" | "next";
+  entry: RecordPagerEntry;
+  testID?: string;
+}) {
+  const { t } = useTranslation();
+  const { knobProps: nested } = useResolvedKnobs({ compact: true });
+  const isPrev = direction === "prev";
+  const avatar = (
+    <Avatar
+      src={entry.image}
+      name={entry.title}
+      backgroundColor="$color4"
+      fallbackBackgroundColor="$color4"
+    />
+  );
+  return (
+    <Button
+      outlined
+      minHeight={sizeRecipeEscape(
+        56,
+        "pager button: room for the neighbor's two-line label beside its avatar",
+      )}
+      flexShrink={1}
+      minWidth={0}
+      onPress={entry.onPress}
+      icon={isPrev ? <ArrowLeftIcon size={18} /> : undefined}
+      iconAfter={isPrev ? undefined : <ArrowRightIcon size={18} />}
+      testID={testID}
+    >
+      <XStack gap="$2" alignItems="center" flexShrink={1} minWidth={0}>
+        {isPrev ? avatar : null}
+        <YStack alignItems={isPrev ? "flex-start" : "flex-end"} flexShrink={1} minWidth={0}>
+          <Text {...nested.label} color="$color10" textTransform="uppercase" letterSpacing={1}>
+            {isPrev ? t("Previous") : t("Next")}
+          </Text>
+          <XStack gap="$1.5" alignItems="baseline" minWidth={0}>
+            {entry.code ? (
+              <Text {...nested.label} color="$color10" fontWeight="600">
+                {entry.code}
+              </Text>
+            ) : null}
+            <Text fontWeight="700" numberOfLines={1} flexShrink={1}>
+              {entry.title}
+            </Text>
+          </XStack>
+        </YStack>
+        {isPrev ? null : avatar}
+      </XStack>
+    </Button>
+  );
+}
+
+/** The records either side of this one in the list's order, by face and name. */
+export function RecordPager({
+  prev,
+  next,
+  testID,
+}: {
+  prev: RecordPagerEntry | null;
+  next: RecordPagerEntry | null;
+  testID?: string;
+}) {
+  const { knobProps } = useResolvedKnobs();
+  if (!prev && !next) return null;
+  return (
+    <XStack justifyContent="space-between" {...knobProps.gap} marginTop="$2">
+      {prev ? (
+        <PagerButton direction="prev" entry={prev} testID={testID && `${testID}-prev`} />
+      ) : (
+        <YStack />
+      )}
+      {next ? (
+        <PagerButton direction="next" entry={next} testID={testID && `${testID}-next`} />
+      ) : (
+        <YStack />
+      )}
+    </XStack>
+  );
+}

package/src/record/RecordRows.tsx

@@ -0,0 +1,90 @@
+import { Accordion, Card, Chip, Text, XStack, YStack } from "@multiplatform.one/components";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useTranslation } from "react-i18next";
+import { groupRows, sortRows } from "./recordData";
+import { slugWords, type FrappeRecordRowsSection } from "./recordSections";
+
+type Row = Record<string, unknown>;
+
+function RowTiles({ rows, section }: { rows: readonly Row[]; section: FrappeRecordRowsSection }) {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <XStack {...knobProps.gap} flexWrap="wrap">
+      {rows.map((row, index) => {
+        const detail = section.detail ? Number(row[section.detail.field]) : 0;
+        return (
+          <Card
+            key={typeof row.name === "string" ? row.name : index}
+            {...knobProps.cardSurface}
+            backgroundColor="$color2"
+            paddingVertical="$2"
+            paddingHorizontal="$3"
+            flexGrow={0}
+          >
+            <XStack alignItems="center" gap="$2">
+              <Text textTransform="capitalize" fontWeight="600">
+                {slugWords(String(row[section.field] ?? ""))}
+              </Text>
+              {section.flag && row[section.flag.field] ? (
+                <Chip size="$2" color="purple">
+                  {section.flag.label}
+                </Chip>
+              ) : null}
+              {section.detail && detail > 0 ? (
+                <Chip size="$2" color="blue">
+                  {section.detail.label(detail)}
+                </Chip>
+              ) : null}
+            </XStack>
+          </Card>
+        );
+      })}
+    </XStack>
+  );
+}
+
+/**
+ * A record's linked rows as flat tiles that wrap, in the declared order,
+ * flagged and detailed per row; grouped, each group is an accordion section
+ * with its count, the first open.
+ */
+export function RecordRows({
+  rows,
+  section,
+}: {
+  rows: readonly Row[];
+  section: FrappeRecordRowsSection;
+}) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  if (rows.length === 0) {
+    return (
+      <Text color="$color10" fontSize="$3">
+        {section.empty ?? t("None yet")}
+      </Text>
+    );
+  }
+  const sorted = sortRows(rows, section.orderBy ?? []);
+  if (!section.groupBy) return <RowTiles rows={sorted} section={section} />;
+  const groups = groupRows(sorted, section.groupBy.field);
+  const groupValue = (value: string) => value || "other";
+  return (
+    <YStack {...knobProps.gap}>
+      <Accordion type="multiple" defaultValue={[groupValue(groups[0]?.value ?? "")]}>
+        {groups.map((group) => (
+          <Accordion.Item key={groupValue(group.value)} value={groupValue(group.value)}>
+            <Accordion.Trigger>
+              <XStack alignItems="center" gap="$2" flexWrap="wrap">
+                <Text fontWeight="600">{section.groupBy?.label(group.value)}</Text>
+                <Chip size="$2">{group.rows.length}</Chip>
+              </XStack>
+            </Accordion.Trigger>
+            <Accordion.Content>
+              <RowTiles rows={group.rows} section={section} />
+            </Accordion.Content>
+          </Accordion.Item>
+        ))}
+      </Accordion>
+    </YStack>
+  );
+}

package/src/record/recordData.spec.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+import {
+  adjacentRecords,
+  childBars,
+  groupRows,
+  recordFacetValues,
+  recordHistory,
+  sortRows,
+} from "./recordData";
+
+const facet = {
+  param: "type",
+  doctype: "Pokemon Poke Type",
+  field: "poke_type",
+  orderBy: "slot",
+  options: [],
+  label: "Type",
+};
+
+describe("recordFacetValues", () => {
+  it("reads a connection facet's values off the record's linked rows in slot order", () => {
+    const connections = {
+      "Pokemon Poke Type": [
+        { name: "b", poke_type: "poison", slot: 2 },
+        { name: "a", poke_type: "grass", slot: 1 },
+      ],
+    };
+    expect(recordFacetValues(facet, {}, connections)).toEqual(["grass", "poison"]);
+  });
+
+  it("reads a field facet off the record itself", () => {
+    const own = { ...facet, doctype: undefined, field: "status" };
+    expect(recordFacetValues(own, { status: "Open" }, {})).toEqual(["Open"]);
+    expect(recordFacetValues(own, {}, {})).toEqual([]);
+  });
+});
+
+describe("sortRows", () => {
+  it("orders by each key in turn, numbers numerically and text alphabetically", () => {
+    const rows = [
+      { method: "machine", level: 0, move: "toxic" },
+      { method: "level-up", level: 13, move: "vine-whip" },
+      { method: "level-up", level: 1, move: "tackle" },
+      { method: "level-up", level: 1, move: "growl" },
+    ];
+    expect(sortRows(rows, ["method", "level", "move"]).map((row) => row.move)).toEqual([
+      "growl",
+      "tackle",
+      "vine-whip",
+      "toxic",
+    ]);
+  });
+
+  it("leaves the rows as they came without keys", () => {
+    const rows = [{ n: 2 }, { n: 1 }];
+    expect(sortRows(rows, [])).toEqual(rows);
+  });
+});
+
+describe("groupRows", () => {
+  it("groups by a field in the order the values first appear", () => {
+    const rows = [
+      { method: "level-up", move: "a" },
+      { method: "machine", move: "b" },
+      { method: "level-up", move: "c" },
+    ];
+    expect(groupRows(rows, "method")).toEqual([
+      { value: "level-up", rows: [rows[0], rows[2]] },
+      { value: "machine", rows: [rows[1]] },
+    ]);
+  });
+});
+
+describe("adjacentRecords", () => {
+  const rows = [{ name: "a" }, { name: "b" }, { name: "c" }];
+
+  it("names the records either side without wrapping", () => {
+    expect(adjacentRecords(rows, "b")).toEqual({ prev: rows[0], next: rows[2] });
+    expect(adjacentRecords(rows, "a")).toEqual({ prev: null, next: rows[1] });
+    expect(adjacentRecords(rows, "c")).toEqual({ prev: rows[1], next: null });
+  });
+
+  it("has no neighbors for a record the list does not hold", () => {
+    expect(adjacentRecords(rows, "z")).toEqual({ prev: null, next: null });
+  });
+});
+
+describe("recordHistory", () => {
+  it("lists the last edit then the creation, newest first", () => {
+    expect(
+      recordHistory({
+        name: "pikachu",
+        owner: "ash@example.com",
+        creation: "2026-09-01 10:00:00",
+        modified: "2026-09-02 11:00:00",
+        modified_by: "misty@example.com",
+      }),
+    ).toEqual([
+      { kind: "modified", author: "misty@example.com", timestamp: "2026-09-02 11:00:00" },
+      { kind: "created", author: "ash@example.com", timestamp: "2026-09-01 10:00:00" },
+    ]);
+  });
+
+  it("shows only the creation when the record was never edited", () => {
+    expect(recordHistory({ owner: "ash", creation: "2026-09-01", modified: "2026-09-01" })).toEqual(
+      [{ kind: "created", author: "ash", timestamp: "2026-09-01" }],
+    );
+  });
+
+  it("is empty without audit fields", () => {
+    expect(recordHistory({})).toEqual([]);
+  });
+});
+
+describe("childBars", () => {
+  const stats = [
+    { stat_name: "speed", base_stat: 90 },
+    { stat_name: "hp", base_stat: 35 },
+    { stat_name: "attack", base_stat: 55 },
+  ];
+
+  it("orders the child rows by the declared order and sums them", () => {
+    expect(
+      childBars(stats, {
+        label: "stat_name",
+        value: "base_stat",
+        order: ["hp", "attack", "speed"],
+      }),
+    ).toEqual({
+      bars: [
+        { key: "hp", value: 35 },
+        { key: "attack", value: 55 },
+        { key: "speed", value: 90 },
+      ],
+      total: 180,
+    });
+  });
+
+  it("keeps undeclared rows after the declared ones and reads a missing value as zero", () => {
+    expect(
+      childBars([{ stat_name: "luck" }, ...stats], {
+        label: "stat_name",
+        value: "base_stat",
+        order: ["hp"],
+      }).bars.map((bar) => `${bar.key}:${bar.value}`),
+    ).toEqual(["hp:35", "luck:0", "speed:90", "attack:55"]);
+  });
+});