@multiplatform.one/frappe-ui 7.34.4 → 7.36.0

package/src/list/listControls.fixture.ts

@@ -0,0 +1,67 @@
+import type { FrappeListControls, FrappeListState } from "./listState";
+import type { ListControlsResult } from "./useListControls";
+
+export const fixtureControls: FrappeListControls = {
+  sorts: [
+    { value: "number", label: "Number", orderBy: [] },
+    { value: "xp", label: "XP", orderBy: [] },
+  ],
+  facets: [
+    {
+      param: "type",
+      field: "poke_type",
+      label: "Type",
+      allLabel: "All types",
+      options: ["fire", "water"],
+    },
+    { param: "region", field: "region", label: "Region", options: ["kanto", "johto"] },
+  ],
+  bands: [
+    {
+      param: "generation",
+      field: "poke_id",
+      label: "Generation",
+      allLabel: "All generations",
+      options: [
+        { value: "1", label: "Generation I", min: 1, max: 151 },
+        { value: "2", label: "Generation II", min: 152, max: 251 },
+      ],
+    },
+  ],
+  ranges: [{ param: "xp", label: "Min XP", field: "base_experience" }],
+};
+
+/** A ListControlsResult stand-in: the band reads it, `update` records patches. */
+export function fixtureList(
+  state: Partial<FrappeListState> = {},
+  update: (patch: Partial<FrappeListState>) => void = () => {},
+): ListControlsResult {
+  return {
+    state: {
+      search: "",
+      sort: "number",
+      facets: {},
+      bands: {},
+      ranges: {},
+      favoritesOnly: false,
+      view: undefined,
+      ...state,
+    },
+    searchText: state.search ?? "",
+    setSearchText: () => {},
+    update,
+    clear: () => {},
+    favorites: {
+      favorites: [],
+      favoriteSet: new Set(),
+      isFavorite: () => false,
+      toggle: () => {},
+      count: 0,
+    },
+    facets: {},
+    bandCounts: { generation: { "1": 8, "2": 4 } },
+    total: 12,
+    highest: { xp: 300 },
+    readers: null,
+  };
+}

package/src/list/listState.spec.ts

@@ -1,6 +1,8 @@
 import { Order } from "@multiplatform.one/frappe";
 import { describe, expect, it } from "vitest";
 import {
+  activeFilterCount,
+  bandOptionFor,
   isListNarrowed,
   listStateFilters,
   listStateFromParams,
@@ -36,6 +38,7 @@ describe("listStateFromParams", () => {
       sort: "number",
       facets: {},
       ranges: {},
+      bands: {},
       favoritesOnly: false,
       view: "grid",
     });
@@ -52,6 +55,7 @@ describe("listStateFromParams", () => {
       sort: "name",
       facets: { type: "grass" },
       ranges: { xp: 60 },
+      bands: {},
       favoritesOnly: true,
       view: "table",
     });
@@ -154,3 +158,66 @@ describe("listStateOrderBy", () => {
     ).toEqual([{ field: "modified", order: Order.Desc }]);
   });
 });
+
+describe("bands", () => {
+  const banded: FrappeListControls = {
+    ...controls,
+    bands: [
+      {
+        param: "gen",
+        field: "poke_id",
+        label: "Generation",
+        options: [
+          { value: "1", label: "I", min: 1, max: 151 },
+          { value: "2", label: "II", min: 152, max: 251 },
+          { value: "9", label: "IX", min: 906 },
+        ],
+      },
+    ],
+  };
+
+  it("reads a band from its param and drops values it does not offer", () => {
+    expect(listStateFromParams({ gen: "2" }, banded).bands).toEqual({ gen: "2" });
+    expect(listStateFromParams({ gen: "7" }, banded).bands).toEqual({});
+  });
+
+  it("writes a band's param and drops it when cleared", () => {
+    expect(listStateParams({ bands: { gen: "1" } }, banded)).toEqual({ gen: "1" });
+    expect(listStateParams({ bands: { gen: "" } }, banded)).toEqual({ gen: undefined });
+  });
+
+  it("turns a band into its inclusive bounds, an open side adding no filter", () => {
+    const base = listStateFromParams({}, banded);
+    expect(listStateFilters({ ...base, bands: { gen: "2" } }, banded)).toEqual([
+      ["poke_id", ">=", 152],
+      ["poke_id", "<=", 251],
+    ]);
+    expect(listStateFilters({ ...base, bands: { gen: "9" } }, banded)).toEqual([
+      ["poke_id", ">=", 906],
+    ]);
+  });
+
+  it("counts the filters a reader set, search aside", () => {
+    const base = listStateFromParams({}, banded);
+    expect(activeFilterCount(base)).toBe(0);
+    expect(activeFilterCount({ ...base, search: "pika" })).toBe(0);
+    expect(isListNarrowed({ ...base, bands: { gen: "1" } })).toBe(true);
+    expect(
+      activeFilterCount({
+        ...base,
+        facets: { type: "grass" },
+        ranges: { xp: 60 },
+        bands: { gen: "1" },
+        favoritesOnly: true,
+      }),
+    ).toBe(4);
+  });
+
+  it("finds the option a value falls in", () => {
+    const band = banded.bands![0];
+    expect(bandOptionFor(band, 25)?.value).toBe("1");
+    expect(bandOptionFor(band, 152)?.value).toBe("2");
+    expect(bandOptionFor(band, 1000)?.value).toBe("9");
+    expect(bandOptionFor(band, 400)).toBeUndefined();
+  });
+});

package/src/list/listState.ts

@@ -5,8 +5,8 @@
  * the rows the controls describe. Pure: no React, no IO.
  *
  * Params: `q` search, `sort` the sort's value (absent for the first sort),
- * one param per facet and per range (absent when unset), `fav=1` favorites
- * only, `view` (absent for the default view).
+ * one param per facet, per range and per band (absent when unset), `fav=1`
+ * favorites only, `view` (absent for the default view).
  */
 import type { Order } from "@multiplatform.one/frappe";
 
@@ -51,10 +51,31 @@ export interface FrappeListRange {
   step?: number;
 }
 
+/** One named span of a numeric field (Generation I is Pokédex 1 to 151). */
+export interface FrappeListBandOption {
+  /** URL value. */
+  value: string;
+  label: string;
+  /** Inclusive bounds; an absent bound leaves that side open. */
+  min?: number;
+  max?: number;
+}
+
+/** Narrow the list to records whose numeric field falls in one named span. */
+export interface FrappeListBand {
+  param: string;
+  field: string;
+  label: string;
+  /** The option that clears the band. */
+  allLabel?: string;
+  options: readonly FrappeListBandOption[];
+}
+
 export interface FrappeListControls {
   sorts?: readonly FrappeListSort[];
   facets?: readonly FrappeListFacet[];
   ranges?: readonly FrappeListRange[];
+  bands?: readonly FrappeListBand[];
   views?: readonly FrappeListViewMode[];
   defaultView?: FrappeListViewMode;
 }
@@ -67,6 +88,8 @@ export interface FrappeListState {
   facets: Record<string, string>;
   /** Range param to its minimum; absent or 0 is no minimum. */
   ranges: Record<string, number>;
+  /** Band param to the chosen option's value. */
+  bands: Record<string, string>;
   favoritesOnly: boolean;
   view: FrappeListViewMode | undefined;
 }
@@ -96,6 +119,11 @@ export function listStateFromParams(
     const value = positiveInt(params[range.param]);
     if (value > 0) ranges[range.param] = value;
   }
+  const bands: Record<string, string> = {};
+  for (const band of controls.bands ?? []) {
+    const value = params[band.param];
+    if (value && band.options.some((option) => option.value === value)) bands[band.param] = value;
+  }
   const views = controls.views ?? [];
   const view = views.find((mode) => mode === params.view) ?? controls.defaultView;
   return {
@@ -103,6 +131,7 @@ export function listStateFromParams(
     sort,
     facets,
     ranges,
+    bands,
     favoritesOnly: params.fav === "1",
     view,
   };
@@ -124,6 +153,9 @@ export function listStateParams(
   for (const [param, value] of Object.entries(patch.ranges ?? {})) {
     params[param] = value > 0 ? String(value) : undefined;
   }
+  for (const [param, value] of Object.entries(patch.bands ?? {})) {
+    params[param] = value || undefined;
+  }
   if (patch.favoritesOnly !== undefined) params.fav = patch.favoritesOnly ? "1" : undefined;
   if (patch.view !== undefined) {
     params.view = patch.view === controls.defaultView ? undefined : patch.view;
@@ -131,13 +163,33 @@ export function listStateParams(
   return params;
 }
 
-/** Search, a facet, a range or favorites narrows the rows. */
+/** Search, a facet, a range, a band or favorites narrows the rows. */
 export function isListNarrowed(state: FrappeListState): boolean {
+  return state.search.trim() !== "" || activeFilterCount(state) > 0;
+}
+
+/**
+ * The filters a reader set, search aside: each facet, range and band with a
+ * value, and favorites only. A Filters button wears this as its count.
+ */
+export function activeFilterCount(state: FrappeListState): number {
   return (
-    state.search.trim() !== "" ||
-    Object.values(state.facets).some(Boolean) ||
-    Object.values(state.ranges).some((value) => value > 0) ||
-    state.favoritesOnly
+    Object.values(state.facets).filter(Boolean).length +
+    Object.values(state.ranges).filter((value) => value > 0).length +
+    Object.values(state.bands ?? {}).filter(Boolean).length +
+    (state.favoritesOnly ? 1 : 0)
+  );
+}
+
+/** The option of a band a numeric value falls in, if any. */
+export function bandOptionFor(
+  band: FrappeListBand,
+  value: number,
+): FrappeListBandOption | undefined {
+  return band.options.find(
+    (option) =>
+      (option.min === undefined || value >= option.min) &&
+      (option.max === undefined || value <= option.max),
   );
 }
 
@@ -170,6 +222,12 @@ export function listStateFilters(
     const value = state.ranges[range.param] ?? 0;
     if (value > 0) filters.push([range.field, ">=", value]);
   }
+  for (const band of controls.bands ?? []) {
+    const option = band.options.find((candidate) => candidate.value === state.bands?.[band.param]);
+    if (!option) continue;
+    if (option.min !== undefined) filters.push([band.field, ">=", option.min]);
+    if (option.max !== undefined) filters.push([band.field, "<=", option.max]);
+  }
   if (state.favoritesOnly) filters.push(["name", "in", [...(options.favorites ?? [])].sort()]);
   return filters.length > 0 ? filters : undefined;
 }

package/src/list/useListControls.tsx

@@ -7,6 +7,7 @@ import type { FrappeRowsConnection } from "../useFrappeRows";
 import { facetRead, readFacet, type FacetReading } from "./facetReading";
 import { useFavorites, type UseFavorites } from "./favorites";
 import {
+  bandOptionFor,
   listStateFromParams,
   listStateParams,
   type FrappeListControls,
@@ -46,6 +47,8 @@ export interface ListControlsResult {
   total: number | undefined;
   /** Highest value per range param in the base read. */
   highest: Readonly<Record<string, number>>;
+  /** Records per band option, per band param, in the base read. */
+  bandCounts: Readonly<Record<string, Readonly<Record<string, number>>>>;
   /** Mount these: the facet and base reads. */
   readers: React.ReactNode;
 }
@@ -56,6 +59,7 @@ function mergeState(prev: FrappeListState, patch: Partial<FrappeListState>): Fra
     ...patch,
     facets: patch.facets ? { ...prev.facets, ...patch.facets } : prev.facets,
     ranges: patch.ranges ? { ...prev.ranges, ...patch.ranges } : prev.ranges,
+    bands: patch.bands ? { ...prev.bands, ...patch.bands } : prev.bands,
   };
 }
 
@@ -117,6 +121,7 @@ export function useListControls({
       favoritesOnly: false,
       facets: Object.fromEntries((current.facets ?? []).map((facet) => [facet.param, ""])),
       ranges: Object.fromEntries((current.ranges ?? []).map((range) => [range.param, 0])),
+      bands: Object.fromEntries((current.bands ?? []).map((band) => [band.param, ""])),
     });
   }, [update]);
 
@@ -141,7 +146,12 @@ export function useListControls({
       orderBy,
     ]),
   );
-  const rangeFieldsKey = JSON.stringify((controls.ranges ?? []).map((range) => range.field));
+  const rangeFieldsKey = JSON.stringify([
+    ...new Set([
+      ...(controls.ranges ?? []).map((range) => range.field),
+      ...(controls.bands ?? []).map((band) => band.field),
+    ]),
+  ]);
   const connectionsKey = JSON.stringify(connections ?? null);
 
   const reads = useMemo(() => {
@@ -173,8 +183,8 @@ export function useListControls({
   }, [reads, snapshots]);
 
   const baseRows = reads.base ? snapshots.base?.rows : undefined;
-  const { total, highest } = useMemo(() => {
-    if (!baseRows) return { total: undefined, highest: {} };
+  const { total, highest, bandCounts } = useMemo(() => {
+    if (!baseRows) return { total: undefined, highest: {}, bandCounts: {} };
     const peaks: Record<string, number> = {};
     for (const range of controlsRef.current.ranges ?? []) {
       peaks[range.param] = baseRows.reduce(
@@ -182,7 +192,18 @@ export function useListControls({
         0,
       );
     }
-    return { total: baseRows.length, highest: peaks };
+    const counts: Record<string, Record<string, number>> = {};
+    for (const band of controlsRef.current.bands ?? []) {
+      const tally: Record<string, number> = {};
+      for (const row of baseRows) {
+        const value = Number(row[band.field]);
+        if (!Number.isFinite(value)) continue;
+        const option = bandOptionFor(band, value);
+        if (option) tally[option.value] = (tally[option.value] ?? 0) + 1;
+      }
+      counts[band.param] = tally;
+    }
+    return { total: baseRows.length, highest: peaks, bandCounts: counts };
   }, [baseRows]);
 
   const readers = (
@@ -218,6 +239,7 @@ export function useListControls({
     facets: facetReadings,
     total,
     highest,
+    bandCounts,
     readers,
   };
 }

package/src/record/RecordBars.tsx

@@ -1,116 +1,36 @@
-import {
-  BarSeries,
-  ChartSurface,
-  Text,
-  Tooltip,
-  XAxis,
-  XStack,
-  YAxis,
-  YStack,
-  approximateTextWidth,
-  createBandScale,
-  createLinearScale,
-  describeChart,
-  formatChartValue,
-  getLinearTicks,
-  useChartTheme,
-  type ChartDatum,
-} from "@multiplatform.one/components";
-import { sizeRecipeEscape, useResolvedKnobs } from "@multiplatform.one/theme";
+import { Separator, Text, XStack, YStack } from "@multiplatform.one/components";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { useTranslation } from "react-i18next";
 import { childBars } from "./recordData";
+import { RecordGroupFrame } from "./RecordRows";
 import type { FrappeRecordBarsSection } from "./recordSections";
 
-const chartHeight = 220;
-const chartTicks = 4;
+const labelWidth = "$8";
+const valueWidth = "$3";
 
 /**
- * Bars on a domain pinned to 0..max, composed from the catalog chart
- * primitives: the packaged BarChart scales to each dataset's own maximum,
- * which makes two records' bars incomparable. `nice: false` keeps the
- * ceiling exactly `max`.
- */
-function FixedScaleBars({
-  data,
-  max,
-  label,
-  testID,
-}: {
-  data: ChartDatum[];
-  max: number;
-  label: string;
-  testID?: string;
-}) {
-  const { palette, labelFontSize } = useChartTheme();
-  const fills = data.map(() => palette.single);
-  const domain: [number, number] = [0, max];
-  return (
-    <ChartSurface label={label} height={chartHeight} testID={testID}>
-      {(size) => {
-        const marginScale = createLinearScale({ domain, range: [0, 1], nice: false });
-        const tickLabels = getLinearTicks(marginScale, chartTicks).map((value) =>
-          formatChartValue(value),
-        );
-        const widestTick = Math.max(
-          0,
-          ...tickLabels.map((tick) => approximateTextWidth(tick, labelFontSize)),
-        );
-        const top = Math.ceil(labelFontSize / 2) + 2;
-        const right = 4;
-        const bottom = 4 + 3 + Math.ceil(labelFontSize * 1.15);
-        const left = Math.ceil(widestTick) + 4 + 3 + 2;
-        const plot = {
-          x: left,
-          y: top,
-          width: Math.max(0, size.width - left - right),
-          height: Math.max(0, size.height - top - bottom),
-        };
-        if (plot.width <= 0 || plot.height <= 0 || data.length === 0) return null;
-        const xScale = createBandScale({
-          domain: data.map((datum) => datum.label),
-          range: [plot.x, plot.x + plot.width],
-        });
-        const yScale = createLinearScale({
-          domain,
-          range: [plot.y + plot.height, plot.y],
-          nice: false,
-        });
-        return (
-          <>
-            <YAxis
-              plot={plot}
-              scale={yScale}
-              ticks={chartTicks}
-              tickFormat={(value) => formatChartValue(value)}
-            />
-            <BarSeries data={data} xScale={xScale} yScale={yScale} plot={plot} fills={fills} />
-            <XAxis plot={plot} scale={xScale} />
-          </>
-        );
-      }}
-    </ChartSurface>
-  );
-}
-
-/**
- * A child table's numbers as bars on one shared scale: the sum above, the
- * chart, then each exact value in a chip (the axis only approximates).
+ * A child table's numbers as horizontal bars on one shared 0..max scale,
+ * so two records' bars compare: a row per value (its name, its number, its
+ * bar), then the sum. Each bar is a meter; the numbers are the state, so no
+ * caption restates the scale. The highest values take the record's tint.
  */
 export function RecordBars({
   rows,
   section,
+  tint,
   testID,
 }: {
   rows: readonly Record<string, unknown>[];
   section: FrappeRecordBarsSection;
+  /** A theme hue for the record's highest bars. */
+  tint?: string;
   testID?: string;
 }) {
   const { t } = useTranslation();
   const { knobProps } = useResolvedKnobs();
-  const { knobProps: nested } = useResolvedKnobs({ compact: true });
+  const { knobProps: nested } = useResolvedKnobs();
   const { bars, total } = childBars(rows, section);
   const name = (key: string) => section.barLabel?.(key) ?? key;
-  const data = bars.map((bar) => ({ label: name(bar.key), value: bar.value }));
 
   if (bars.length === 0) {
     return (
@@ -120,68 +40,87 @@ export function RecordBars({
     );
   }
 
+  const top = Math.max(...bars.map((bar) => bar.value));
   return (
-    <YStack {...knobProps.gapLg}>
-      <XStack
-        {...knobProps.gap}
-        alignItems="baseline"
-        justifyContent="space-between"
-        flexWrap="wrap"
-      >
-        <YStack>
-          <Text {...nested.label} color="$color10" textTransform="uppercase" letterSpacing={1}>
-            {section.totalLabel ?? t("Total")}
-          </Text>
-          <Text fontSize="$10" fontWeight="700">
-            {total}
-          </Text>
-        </YStack>
-        {section.description ? (
-          <Text
-            {...nested.label}
-            color="$color10"
-            flexShrink={1}
-            maxWidth={sizeRecipeEscape(420, "chart caption: a readable measure beside the total")}
-          >
-            {section.description}
-          </Text>
-        ) : null}
-      </XStack>
-      <FixedScaleBars
-        data={data}
-        max={section.max}
-        testID={testID}
-        label={[
-          describeChart({ typeLabel: t("Bar chart"), title: section.title, data }),
-          t("Values on a fixed 0 to {{max}} scale.", { max: section.max }),
-        ].join(" ")}
-      />
-      <XStack {...nested.gap} flexWrap="wrap">
-        {bars.map((bar) => (
-          <Tooltip
-            key={bar.key}
-            content={t("{{name}}: {{value}}", { name: name(bar.key), value: bar.value })}
-          >
+    <RecordGroupFrame
+      {...knobProps.panelPadding}
+      {...knobProps.gap}
+      testID={testID}
+      role="figure"
+      aria-label={section.title}
+    >
+      <YStack role="list" {...knobProps.gap}>
+        {bars.map((bar) => {
+          const percent = Math.max(0, Math.min(100, (bar.value / section.max) * 100));
+          const fill = tint && bar.value === top ? `$${tint}9` : "$color9";
+          return (
             <XStack
-              {...nested.borderRadius}
-              backgroundColor="$color2"
-              borderWidth={0}
-              paddingHorizontal="$2"
-              paddingVertical="$0.5"
-              gap="$1"
-              alignItems="baseline"
-              cursor="help"
+              key={bar.key}
+              role="listitem"
+              alignItems="center"
+              {...knobProps.gap}
+              data-record-bar={bar.key}
             >
-              <Text {...nested.label} {...nested.body} color="$color10">
+              <Text
+                {...nested.label}
+                color="$color11"
+                width={labelWidth}
+                flexShrink={0}
+                numberOfLines={1}
+              >
                 {name(bar.key)}
               </Text>
-              <Text {...nested.label} fontWeight="700">
+              <Text
+                {...nested.label}
+                fontWeight="700"
+                color="$color12"
+                width={valueWidth}
+                flexShrink={0}
+                textAlign="right"
+              >
                 {bar.value}
               </Text>
+              <YStack
+                flex={1}
+                minWidth={0}
+                height="$0.75"
+                borderRadius="$true"
+                backgroundColor="$color4"
+                overflow="hidden"
+                role="meter"
+                aria-label={name(bar.key)}
+                aria-valuenow={bar.value}
+                aria-valuemin={0}
+                aria-valuemax={section.max}
+              >
+                <YStack
+                  height="100%"
+                  width={`${percent}%`}
+                  borderRadius="$true"
+                  backgroundColor={fill as never}
+                  data-record-bar-fill=""
+                />
+              </YStack>
             </XStack>
-          </Tooltip>
-        ))}
+          );
+        })}
+      </YStack>
+      <Separator />
+      <XStack alignItems="center" {...knobProps.gap} data-record-bars-total="">
+        <Text {...nested.label} color="$color11" width={labelWidth} flexShrink={0}>
+          {section.totalLabel ?? t("Total")}
+        </Text>
+        <Text
+          {...nested.label}
+          fontWeight="800"
+          color="$color12"
+          width={valueWidth}
+          flexShrink={0}
+          textAlign="right"
+        >
+          {total}
+        </Text>
       </XStack>
-    </YStack>
+    </RecordGroupFrame>
   );
 }