@multiplatform.one/frappe-ui 7.23.2 → 7.25.0

package/src/fields/Heading/index.tsx

@@ -3,7 +3,18 @@ import { Skeleton } from "@multiplatform.one/forms";
 import { sizeRecipeEscape, useResolvedKnobs } from "@multiplatform.one/theme";
 import type React from "react";
 import { useCallback, useEffect, useId, useState } from "react";
-import { H1, H2, H3, H4, Separator, Text, XStack, YStack, type YStackProps } from "tamagui";
+import {
+  getTokenValue,
+  H1,
+  H2,
+  H3,
+  H4,
+  Separator,
+  Text,
+  XStack,
+  YStack,
+  type YStackProps,
+} from "tamagui";
 
 export type HeadingLevel = 1 | 2 | 3 | 4;
 
@@ -154,23 +165,30 @@ export function Heading({
     </XStack>
   );
 
+  const spacePx = (token: unknown) =>
+    Number(getTokenValue(token as Parameters<typeof getTokenValue>[0], "space")) || 0;
+  const descriptionGap = Math.max(0, spacePx(stackProps.gap ?? knobProps.gap.gap) - spacePx("$1"));
+  const showDescription = Boolean(resolvedDescription) && !isCollapsed;
+
   return (
     <YStack {...knobProps.gap} {...stackProps}>
-      {headingContent}
-      {resolvedDescription && !isCollapsed && (
-        <Text
-          fontSize={knobProps.sizeToken}
-          {...knobProps.body}
-          color="$color10"
-          marginTop="$-1"
-          marginBottom="$1"
-          paddingInlineStart={canCollapse ? "$6" : undefined}
-        >
-          {resolvedDescription}
-        </Text>
-      )}
+      <YStack gap={descriptionGap} paddingBottom={showDescription ? "$1" : undefined}>
+        {headingContent}
+        {showDescription && (
+          <Text
+            fontSize={knobProps.sizeToken}
+            {...knobProps.body}
+            color="$color10"
+            paddingInlineStart={canCollapse ? "$6" : undefined}
+          >
+            {resolvedDescription}
+          </Text>
+        )}
+      </YStack>
       {showSeparator && (
-        <Separator marginVertical={compact ? "$0.5" : "$1"} backgroundColor="$color5" />
+        <YStack paddingVertical={compact ? "$0.5" : "$1"}>
+          <Separator backgroundColor="$color5" />
+        </YStack>
       )}
       {collapsible ? (
         // Always mounted so the aria-controls target exists while collapsed

package/src/frappeNavigation.loader.spec.tsx

@@ -0,0 +1,45 @@
+// MPO-411. A routed view reads what its route's loader rendered on the server
+// through the host's navigation, so an app hands the view its loader instead
+// of reading the router itself.
+import { render } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import {
+  FrappeNavigationProvider,
+  useRouteLoaderData,
+  type FrappeNavigation,
+} from "./frappeNavigation";
+
+const loader = async () => ({ rows: [] });
+
+function Probe({ of, seen }: { of?: typeof loader; seen: (value: unknown) => void }) {
+  seen(useRouteLoaderData(of));
+  return null;
+}
+
+function read(navigation: FrappeNavigation | undefined, of?: typeof loader): unknown {
+  const seen = vi.fn();
+  render(
+    <FrappeNavigationProvider navigation={navigation}>
+      <Probe of={of} seen={seen} />
+    </FrappeNavigationProvider>,
+  );
+  return seen.mock.calls.at(-1)?.[0];
+}
+
+const base: FrappeNavigation = { usePathname: () => "/pokemon", useNavigate: () => () => {} };
+
+describe("useRouteLoaderData", () => {
+  it("hands the host the loader and returns what it read", () => {
+    const useLoader = vi.fn(() => ({ rows: ["bulbasaur"] }));
+    expect(read({ ...base, useLoader }, loader)).toEqual({ rows: ["bulbasaur"] });
+    expect(useLoader).toHaveBeenCalledWith(loader);
+  });
+
+  it("reads nothing without a loader or a host that runs them", () => {
+    const useLoader = vi.fn(() => ({ rows: ["bulbasaur"] }));
+    expect(read({ ...base, useLoader })).toBeUndefined();
+    expect(useLoader).not.toHaveBeenCalled();
+    expect(read(base, loader)).toBeUndefined();
+    expect(read(undefined, loader)).toBeUndefined();
+  });
+});

package/src/frappeNavigation.tsx

@@ -15,12 +15,28 @@ export interface FrappeNavigation {
   usePathname(): string;
   /** A function that pushes an href onto the history. */
   useNavigate(): (href: string) => void;
+  /**
+   * The query params of the route the caller renders in. A host without
+   * them leaves a routed list's controls out of the URL.
+   */
+  useSearchParams?(): Record<string, string | undefined>;
+  /** A function that replaces query params in place; undefined drops one. */
+  useSetSearchParams?(): (params: Record<string, string | undefined>) => void;
+  /**
+   * What the route's loader returned (the page it rendered on the server),
+   * given the loader the route exports. A host without loaders leaves it
+   * out, and a view reads live from the start.
+   */
+  useLoader?(loader: (...args: never[]) => unknown): unknown;
 }
 
 /** A routed view's handle on the host router. */
 export interface FrappeRouter {
   pathname: string;
   navigate(href: string): void;
+  /** Present when the host hands its query params to routed views. */
+  searchParams?: Record<string, string | undefined>;
+  setSearchParams?: (params: Record<string, string | undefined>) => void;
 }
 
 const FrappeNavigationContext = createContext<FrappeNavigation | undefined>(undefined);
@@ -44,6 +60,17 @@ export function useFrappeNavigation(): FrappeNavigation | undefined {
   return useContext(FrappeNavigationContext);
 }
 
+/**
+ * What `loader` returned for the route the caller renders in, through the
+ * host's navigation; undefined without a loader or a host that runs them.
+ */
+export function useRouteLoaderData(loader: ((...args: never[]) => unknown) | undefined): unknown {
+  const navigation = useContext(FrappeNavigationContext);
+  if (!loader || !navigation?.useLoader) return undefined;
+  // oxlint-disable-next-line rules-of-hooks -- one navigation and one loader per view
+  return navigation.useLoader(loader);
+}
+
 /** The host router for a routed view, or undefined when the host gave none. */
 export function useFrappeRouter(): FrappeRouter | undefined {
   const navigation = useFrappeNavigation();
@@ -52,7 +79,11 @@ export function useFrappeRouter(): FrappeRouter | undefined {
   const pathname = navigation.usePathname();
   // oxlint-disable-next-line rules-of-hooks -- one navigation per tree
   const navigate = navigation.useNavigate();
-  return { pathname, navigate };
+  // oxlint-disable-next-line rules-of-hooks -- one navigation per tree
+  const searchParams = navigation.useSearchParams?.();
+  // oxlint-disable-next-line rules-of-hooks -- one navigation per tree
+  const setSearchParams = navigation.useSetSearchParams?.();
+  return { pathname, navigate, searchParams, setSearchParams };
 }
 
 /**

package/src/index.ts

@@ -26,6 +26,7 @@ export {
 } from "./FrappeProvider";
 export {
   FrappeNavigationProvider,
+  useRouteLoaderData,
   frappeRouteHref,
   frappeRouteTarget,
   useFrappeNavigation,
@@ -67,7 +68,58 @@ export {
   type SidebarPerson,
 } from "./FormSidebar";
 export { FrappeList, type FrappeListProps } from "./FrappeList";
-export { FrappeListView, type FrappeListViewProps, type ListViewMode } from "./FrappeListView";
+export {
+  FrappeListView,
+  type FrappeListAction,
+  type FrappeListCard,
+  type FrappeListViewProps,
+  type ListViewMode,
+} from "./FrappeListView";
+export {
+  isListNarrowed,
+  listStateFilters,
+  listStateFromParams,
+  listStateOrderBy,
+  listStateParams,
+  type FrappeListControls,
+  type FrappeListFacet,
+  type FrappeListFilter,
+  type FrappeListParams,
+  type FrappeListRange,
+  type FrappeListSort,
+  type FrappeListState,
+} from "./list/listState";
+export {
+  createFavoritesStore,
+  favoritesKey,
+  favoritesStore,
+  toggleFavoriteIn,
+  useFavorites,
+  type FavoritesState,
+  type UseFavorites,
+} from "./list/favorites";
+export { FacetRail, type FacetRailOption, type FacetRailProps } from "./list/FacetRail";
+export { RangeFilter, rangeCeiling, type RangeFilterProps } from "./list/RangeFilter";
+export { ShufflePanel, type ShufflePanelProps } from "./list/ShufflePanel";
+export { FacetBadge, type FacetBadgeProps } from "./list/FacetBadge";
+export { ImageWell, type ImageWellProps } from "./list/ImageWell";
+export { RecordCard, type RecordCardBadge, type RecordCardProps } from "./list/RecordCard";
+export { recordTitle, type FrappeRecordLook, type FrappeRecordSlide } from "./list/recordLook";
+export {
+  FrappeRecordView,
+  type FrappeRecordAction,
+  type FrappeRecordBarsSection,
+  type FrappeRecordRowsSection,
+  type FrappeRecordSection,
+  type FrappeRecordTab,
+  type FrappeRecordViewProps,
+} from "./FrappeRecordView";
+export { RecordBars } from "./record/RecordBars";
+export {
+  FrappeInsights,
+  type FrappeInsightsMetric,
+  type FrappeInsightsProps,
+} from "./FrappeInsights";
 export {
   useConnectionFilters,
   type ConnectionFiltersResult,

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