@multiplatform.one/frappe-ui 7.23.1 → 7.24.0

package/src/insights/InsightsFacetTags.tsx

@@ -0,0 +1,131 @@
+import { Tags, Text, XStack, isWeb } from "@multiplatform.one/components";
+import {
+  ensureFocusVisibleRing,
+  ensureKeyboardModalityTracking,
+  keyboardFocusRingProps,
+  useResolvedKnobs,
+  wasKeyboardFocus,
+} from "@multiplatform.one/theme";
+import { useState } from "react";
+import { useTranslation } from "react-i18next";
+import type { InsightsCount } from "./insightsData";
+
+const chipFocusRing = ensureFocusVisibleRing(keyboardFocusRingProps);
+
+interface FacetTagChipProps {
+  value: string;
+  count: number;
+  label: string;
+  tint?: string;
+  onPress: () => void;
+  testID?: string;
+}
+
+/**
+ * A pressable facet value painted from its tint's ramp (DF-04), at the
+ * compact nestedControl height with the press target restored by hitSlop
+ * (LC-54, LC-73); the keyboard ring rides the whole chip (LC-71).
+ */
+function FacetTagChip({ value, count, label, tint = "gray", onPress, testID }: FacetTagChipProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs({ compact: true });
+  const nested = knobProps.nestedControl;
+  const [kbFocus, setKbFocus] = useState(false);
+  if (isWeb) ensureKeyboardModalityTracking();
+  return (
+    <XStack
+      {...knobProps.borderRadius}
+      role="button"
+      tabIndex={0}
+      aria-label={t("{{value}}, {{count}} records", { value: label, count })}
+      cursor="pointer"
+      alignItems="center"
+      gap="$1.5"
+      paddingHorizontal="$2"
+      minHeight={nested.px}
+      height={nested.px}
+      hitSlop={nested.hitSlop}
+      data-nested-px={nested.px}
+      backgroundColor={`$${tint}3` as never}
+      hoverStyle={{ backgroundColor: `$${tint}4` as never }}
+      pressStyle={{ backgroundColor: `$${tint}5` as never }}
+      outlineWidth={0}
+      focusStyle={{ outlineWidth: 0 }}
+      focusVisibleStyle={chipFocusRing}
+      {...(isWeb
+        ? {
+            onFocus: () => {
+              if (wasKeyboardFocus()) setKbFocus(true);
+            },
+            onBlur: () => setKbFocus(false),
+            onKeyDown: (event: { key?: string; preventDefault?: () => void }) => {
+              if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault?.();
+                onPress();
+              }
+            },
+          }
+        : undefined)}
+      {...(kbFocus ? keyboardFocusRingProps : undefined)}
+      onPress={onPress}
+      testID={testID ? `${testID}-${value}` : undefined}
+    >
+      <XStack
+        width="$1"
+        height="$1"
+        borderRadius={1000}
+        backgroundColor={`$${tint}9` as never}
+        flexShrink={0}
+      />
+      <Text
+        {...knobProps.label}
+        fontWeight="600"
+        color={`$${tint}11` as never}
+        textTransform="capitalize"
+        userSelect="none"
+      >
+        {label}
+      </Text>
+      <Text {...knobProps.label} color={`$${tint}11` as never} opacity={0.7} userSelect="none">
+        {count}
+      </Text>
+    </XStack>
+  );
+}
+
+export interface InsightsFacetTagsProps {
+  distribution: readonly InsightsCount[];
+  label: (value: string) => string;
+  tint?: (value: string) => string | undefined;
+  onSelect: (value: string) => void;
+  testID?: string;
+}
+
+/** A facet's values with their record counts, each opening the list narrowed to it. */
+export function InsightsFacetTags({
+  distribution,
+  label,
+  tint,
+  onSelect,
+  testID,
+}: InsightsFacetTagsProps) {
+  const { t } = useTranslation();
+  return (
+    <Tags
+      tags={distribution.map((entry) => ({ id: entry.value, label: label(entry.value) }))}
+      enableAdd={false}
+      enableRemove={false}
+      labels={{ noTags: t("No values yet") }}
+      renderTag={(tag) => (
+        <FacetTagChip
+          value={tag.id}
+          count={distribution.find((entry) => entry.value === tag.id)?.count ?? 0}
+          label={tag.label}
+          tint={tint?.(tag.id)}
+          onPress={() => onSelect(tag.id)}
+          testID={testID}
+        />
+      )}
+    />
+  );
+}

package/src/insights/InsightsKpiBand.tsx

@@ -0,0 +1,114 @@
+import {
+  KPICard,
+  Sparkline,
+  Text,
+  XStack,
+  YStack,
+  type ChartConfig,
+  type KPICardConfig,
+} from "@multiplatform.one/components";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { ChartCard } from "../ChartCard";
+
+export interface InsightsTile {
+  id: string;
+  title: string;
+  value: string | number;
+  hint?: string;
+  spark?: number[];
+}
+
+export interface InsightsKpiBandProps {
+  hero: KPICardConfig;
+  tiles: readonly InsightsTile[];
+  charts: readonly ChartConfig[];
+  testID?: string;
+}
+
+/**
+ * A supporting metric beside the hero (LC-73): compact density and the
+ * label type, painted below the page's 44px floor.
+ */
+function NestedKpi({ tile, testID }: { tile: InsightsTile; testID?: string }) {
+  const { knobProps } = useResolvedKnobs({ compact: true });
+  const nestedPx = knobProps.nestedControl.px;
+  return (
+    <YStack
+      {...knobProps.cardSurface}
+      backgroundColor="$color2"
+      flexGrow={1}
+      flexShrink={1}
+      flexBasis={140}
+      minWidth={0}
+      justifyContent="space-between"
+      {...knobProps.gap}
+      data-nested-px={nestedPx}
+      testID={testID}
+    >
+      <Text {...knobProps.label} color="$color10" numberOfLines={1}>
+        {tile.title}
+      </Text>
+      <Text fontSize="$7" fontWeight="700" color="$color" numberOfLines={1}>
+        {tile.value}
+      </Text>
+      {tile.hint ? (
+        <Text {...knobProps.label} color="$color10" numberOfLines={1}>
+          {tile.hint}
+        </Text>
+      ) : null}
+      {tile.spark && tile.spark.length > 1 ? (
+        <Sparkline data={tile.spark} height={nestedPx} showArea title={tile.title} />
+      ) : null}
+    </YStack>
+  );
+}
+
+/**
+ * The hero count with its denser companions, then the charts. Rows wrap on
+ * flexBasis rather than riding the catalog Dashboard grid, whose percent
+ * widths plus its gap overflow a row that sums to 100%. Every child shrinks
+ * so a line narrower than one tile stays inside its frame (LC-10).
+ */
+export function InsightsKpiBand({ hero, tiles, charts, testID }: InsightsKpiBandProps) {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <YStack {...knobProps.gapLg} testID={testID}>
+      <XStack {...knobProps.gap} flexWrap="wrap" alignItems="stretch">
+        <KPICard config={hero} flexGrow={2} flexShrink={1} flexBasis={260} />
+        {tiles.length > 0 ? (
+          <XStack
+            {...knobProps.gap}
+            flexWrap="wrap"
+            flexGrow={3}
+            flexShrink={1}
+            flexBasis={420}
+            minWidth={0}
+          >
+            {tiles.map((tile) => (
+              <NestedKpi
+                key={tile.id}
+                tile={tile}
+                testID={testID ? `${testID}-kpi-${tile.id}` : undefined}
+              />
+            ))}
+          </XStack>
+        ) : null}
+      </XStack>
+      {charts.length > 0 ? (
+        <XStack {...knobProps.gap} flexWrap="wrap" alignItems="stretch">
+          {charts.map((chart, index) => (
+            <ChartCard
+              key={chart.id}
+              config={chart}
+              flexGrow={index === 0 ? 3 : 2}
+              flexShrink={1}
+              flexBasis={index === 0 ? 420 : 320}
+              minWidth={0}
+              minHeight={240}
+            />
+          ))}
+        </XStack>
+      ) : null}
+    </YStack>
+  );
+}

package/src/insights/InsightsLeaders.tsx

@@ -0,0 +1,146 @@
+import { Tabs, 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, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { ImageWell } from "../list/ImageWell";
+import { topBy } from "./insightsData";
+import {
+  formatMetric,
+  metricValue,
+  type FrappeInsightsMetric,
+  type InsightsRecordView,
+} from "./insightsRecord";
+
+interface LeaderRow<TDoc> extends DataTableData {
+  rank: number;
+  doc: TDoc;
+  title: string;
+  value: number;
+}
+
+export interface InsightsLeadersProps<TDoc> {
+  rows: readonly TDoc[];
+  metrics: readonly FrappeInsightsMetric[];
+  record: InsightsRecordView<TDoc>;
+  /** Rows per metric. */
+  count?: number;
+  testID?: string;
+}
+
+/**
+ * The top records by a metric the reader picks on a contained tab strip,
+ * in one compact read-only DataTable; a row opens its record. Nested cell
+ * chrome uses the compact nestedControl and label type (LC-73).
+ */
+export function InsightsLeaders<TDoc>({
+  rows,
+  metrics,
+  record,
+  count = 5,
+  testID,
+}: InsightsLeadersProps<TDoc>) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs({ compact: true });
+  const [field, setField] = useState(metrics[0]?.field ?? "");
+  const metric = metrics.find((candidate) => candidate.field === field) ?? metrics[0];
+  const nestedPx = knobProps.nestedControl.px;
+
+  const leaders = useMemo<LeaderRow<TDoc>[]>(
+    () =>
+      metric
+        ? topBy(rows as never[], metric.field, count).map((doc: TDoc, index) => ({
+            rank: index + 1,
+            doc,
+            title: record.title(doc),
+            value: metricValue(doc, metric.field),
+          }))
+        : [],
+    [rows, metric, count, record],
+  );
+
+  const columns = useMemo<DataTableColumn<LeaderRow<TDoc>>[]>(
+    () => [
+      {
+        id: "rank",
+        accessorKey: "rank",
+        header: t("Rank"),
+        size: 64,
+        cell: ({ row }) => (
+          <Text {...knobProps.label} color="$color10" fontWeight="600">
+            {`#${row.original.rank}`}
+          </Text>
+        ),
+      },
+      {
+        id: "record",
+        accessorKey: "title",
+        header: t("Record"),
+        cell: ({ row }) => {
+          const tints = record.tints(row.original.doc);
+          const code = record.code(row.original.doc);
+          return (
+            <XStack gap="$2" alignItems="center" minWidth={0}>
+              <ImageWell
+                sources={record.images(row.original.doc)}
+                alt={row.original.title}
+                tints={tints}
+                inset={0.04}
+                width={nestedPx}
+                data-nested-px={nestedPx}
+              />
+              <YStack flexShrink={1} minWidth={0}>
+                <Text fontWeight="600" numberOfLines={1}>
+                  {row.original.title}
+                </Text>
+                {code ? (
+                  <Text {...knobProps.label} color="$color10">
+                    {code}
+                  </Text>
+                ) : null}
+              </YStack>
+            </XStack>
+          );
+        },
+      },
+      {
+        id: "value",
+        accessorKey: "value",
+        header: metric?.label ?? "",
+        align: "right",
+        cell: ({ row }) => (
+          <Text fontWeight="700">{metric ? formatMetric(metric, row.original.value) : ""}</Text>
+        ),
+      },
+    ],
+    [t, metric, record, nestedPx, knobProps.label],
+  );
+
+  if (!metric) return null;
+  return (
+    <YStack {...knobProps.gap} testID={testID}>
+      {metrics.length > 1 ? (
+        <Tabs
+          variant="contained"
+          compact
+          value={metric.field}
+          onChange={setField}
+          items={metrics.map((candidate) => ({ value: candidate.field, label: candidate.label }))}
+        />
+      ) : null}
+      <DataTable
+        data={leaders}
+        columns={columns}
+        enableFiltering={false}
+        enableGlobalSearch={false}
+        enableSorting={false}
+        enablePagination={false}
+        readOnly
+        columnLayout="auto"
+        onRowPress={(row) => record.open(row.doc)}
+        rowLabel={(row) => row.title}
+        aria-label={t("Leaders by {{metric}}", { metric: metric.label })}
+      />
+    </YStack>
+  );
+}

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