@multiplatform.one/frappe-ui 7.34.4 → 7.35.0

package/src/list/ListToolsSheet.spec.tsx

@@ -0,0 +1,82 @@
+// ListToolsSheet: the compact list's Filters sheet (§ ListControls rows).
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, fireEvent, screen, waitFor, within } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ListToolsSheet, countListNarrowings } from "./ListToolsSheet";
+import { fixtureControls, fixtureList } from "./listControls.fixture";
+
+afterEach(cleanup);
+
+function renderSheet(update = vi.fn(), toggle = vi.fn(), state = {}) {
+  renderWithProviders(
+    <ListToolsSheet
+      controls={fixtureControls}
+      list={fixtureList(state, update)}
+      showFavorites
+      shuffle={{ open: false, toggle, panelId: "roster-shuffle" }}
+      facets={fixtureControls.facets!.slice(1)}
+      testID="roster"
+    />,
+  );
+  fireEvent.click(screen.getByTestId("roster-tools"));
+  return { update, toggle };
+}
+
+describe("ListToolsSheet", () => {
+  it("counts active facets, bands, ranges and favorites-only, not search or sort", () => {
+    expect(countListNarrowings(fixtureList({ search: "pika", sort: "xp" }))).toBe(0);
+    expect(
+      countListNarrowings(
+        fixtureList({
+          facets: { type: "fire", region: "" },
+          ranges: { xp: 0 },
+          bands: { generation: "1", empty: "" },
+          favoritesOnly: true,
+        }),
+      ),
+    ).toBe(3);
+  });
+
+  it("opens a sheet with sort, favorites, shuffle, ranges and the remaining facets", async () => {
+    renderSheet();
+    await waitFor(() => expect(screen.getByTestId("roster-tools-sheet")).toBeTruthy());
+    expect(screen.getByRole("radiogroup", { name: "Sort by" })).toBeTruthy();
+    expect(screen.getByRole("radiogroup", { name: "Region" })).toBeTruthy();
+    expect(screen.queryByRole("radiogroup", { name: "Type" })).toBeNull();
+    expect(screen.getByTestId("roster-tools-favorites")).toBeTruthy();
+    expect(screen.getByTestId("roster-tools-shuffle")).toBeTruthy();
+    expect(await screen.findByText("Min XP")).toBeTruthy();
+  });
+
+  it("commits a sort and the favorites toggle through the list's update", async () => {
+    const { update } = renderSheet();
+    await waitFor(() => expect(screen.getByTestId("roster-tools-sheet")).toBeTruthy());
+    fireEvent.click(screen.getByRole("radio", { name: "XP" }));
+    expect(update).toHaveBeenCalledWith({ sort: "xp" });
+    fireEvent.click(screen.getByTestId("roster-tools-favorites"));
+    expect(update).toHaveBeenCalledWith({ favoritesOnly: true });
+  });
+
+  it("shuffle opens the pick and steps the sheet aside", async () => {
+    const { toggle } = renderSheet();
+    await waitFor(() => expect(screen.getByTestId("roster-tools-sheet")).toBeTruthy());
+    fireEvent.click(screen.getByTestId("roster-tools-shuffle"));
+    expect(toggle).toHaveBeenCalledTimes(1);
+    await waitFor(() => expect(screen.queryByTestId("roster-tools-sheet")).toBeNull());
+  });
+});
+
+describe("ListToolsSheet bands", () => {
+  it("shows counts and updates or clears a selected band inside the sheet", async () => {
+    const { update } = renderSheet(vi.fn(), vi.fn(), { bands: { generation: "1" } });
+    const group = await screen.findByRole("radiogroup", { name: "Generation" });
+    expect(screen.getByTestId("roster-tools-sheet").contains(group)).toBe(true);
+    const first = within(group).getByRole("radio", { name: /Generation I\b/ });
+    expect(first.getAttribute("aria-checked")).toBe("true");
+    expect(first.textContent).toContain("8");
+    fireEvent.click(within(group).getByRole("radio", { name: /Generation II\b/ }));
+    expect(update).toHaveBeenCalledWith({ bands: { generation: "2" } });
+    fireEvent.click(within(group).getByRole("radio", { name: /All generations/ }));
+    expect(update).toHaveBeenCalledWith({ bands: { generation: "" } });
+  });
+});

package/src/list/ListToolsSheet.tsx

@@ -0,0 +1,219 @@
+/**
+ * Compact list tools — the one badge-counted "Filters" button a list's
+ * control row carries on compact viewports (< 640,
+ * `useLayoutSizeClass() === "compact"`). Sort, favorites, shuffle, the range
+ * sliders, any facet past the first (the band keeps the first as its chip
+ * row) and Clear filters move behind it into a catalog SheetModal (LC-06:
+ * sheet on native and narrow web). Modelled on backoffice's
+ * list-tools-sheet.tsx, typed on {@link FrappeListControls}.
+ *
+ * Sheet content is inline and sheet-safe: chip rails, buttons and sliders
+ * only — no nested Popover/Select trigger that would portal behind the
+ * RN-Modal sheet on native. Sort is a chip rail for that reason.
+ */
+import { Badge, SheetModal, SizableText, Text, YStack, isWeb } from "@multiplatform.one/components";
+import { Button } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { DiceFiveIcon, FunnelIcon, HeartIcon } from "@phosphor-icons/react";
+import { useEffect, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { BandFilter } from "./BandFilters";
+import { FacetRail } from "./FacetRail";
+import {
+  activeFilterCount,
+  isListNarrowed,
+  type FrappeListControls,
+  type FrappeListFacet,
+} from "./listState";
+import { RangeFilter, rangeCeiling } from "./RangeFilter";
+import type { ListControlsResult } from "./useListControls";
+
+export interface ListToolsSheetProps {
+  controls: FrappeListControls;
+  list: ListControlsResult;
+  showFavorites: boolean;
+  /** Present when the list offers a random pick. */
+  shuffle?: { open: boolean; toggle: () => void; panelId: string };
+  /** Facets the sheet carries: every facet the band's chip row does not. */
+  facets: readonly FrappeListFacet[];
+  testID: string;
+}
+
+export function countListNarrowings(list: ListControlsResult): number {
+  return activeFilterCount(list.state);
+}
+
+function SectionLabel({ children }: { children: string }) {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <Text {...knobProps.label} color={knobProps.textAccentColor} textTransform="uppercase">
+      {children}
+    </Text>
+  );
+}
+
+export function ListToolsSheet({
+  controls,
+  list,
+  showFavorites,
+  shuffle,
+  facets,
+  testID,
+}: ListToolsSheetProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  const iconSize = knobProps.controlIcon.width;
+  const [open, setOpen] = useState(false);
+  const { state, update, favorites } = list;
+  const sorts = controls.sorts ?? [];
+  const ranges = controls.ranges ?? [];
+  const count = countListNarrowings(list);
+  const filtersLabel = t("Filters");
+
+  // SheetModal leaves Escape dismissal to the consumer (LC-21 dismissal
+  // intent) — web-only document listener, backoffice list-tools precedent.
+  useEffect(() => {
+    if (!isWeb || typeof document === "undefined" || !open) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setOpen(false);
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [open]);
+
+  return (
+    <>
+      <Badge count={count}>
+        <Button
+          outlined={count === 0}
+          theme={count > 0 ? "accent" : undefined}
+          icon={<FunnelIcon size={iconSize} weight={count > 0 ? "fill" : "regular"} />}
+          onPress={() => setOpen(true)}
+          aria-label={count > 0 ? t("Filters ({{count}})", { count }) : filtersLabel}
+          aria-haspopup="dialog"
+          aria-expanded={open}
+          testID={`${testID}-tools`}
+        >
+          {filtersLabel}
+        </Button>
+      </Badge>
+      <SheetModal
+        open={open}
+        onOpenChange={setOpen}
+        snapPoint={85}
+        scrollable
+        header={<SizableText {...knobProps.heading}>{t("Filter & sort")}</SizableText>}
+      >
+        {/* Mounted only while open: a closed sheet must not leave a second
+            sort, facet rail or favorites toggle in the page's tree. */}
+        {open ? (
+          <YStack {...knobProps.gapLg} testID={`${testID}-tools-sheet`}>
+            {sorts.length > 0 ? (
+              <YStack {...knobProps.gap}>
+                <SectionLabel>{t("Sort by")}</SectionLabel>
+                <FacetRail
+                  label={t("Sort by")}
+                  value={state.sort ?? ""}
+                  onChange={(value) => update({ sort: value })}
+                  options={sorts.map((sort) => ({ value: sort.value, label: sort.label }))}
+                  testID={`${testID}-tools-sort`}
+                />
+              </YStack>
+            ) : null}
+            {facets.map((facet) => {
+              const reading = list.facets[facet.param];
+              return (
+                <YStack key={facet.param} {...knobProps.gap}>
+                  <SectionLabel>{facet.label}</SectionLabel>
+                  <FacetRail
+                    label={facet.label}
+                    value={state.facets[facet.param] ?? ""}
+                    onChange={(value) => update({ facets: { [facet.param]: value } })}
+                    testID={`${testID}-tools-${facet.param}`}
+                    options={[
+                      { value: "", label: facet.allLabel ?? t("All"), count: list.total },
+                      ...facet.options.map((value) => ({
+                        value,
+                        label: facet.optionLabel?.(value) ?? value,
+                        tint: facet.tint?.(value),
+                        count: reading?.counts[value],
+                      })),
+                    ]}
+                  />
+                </YStack>
+              );
+            })}
+            {(controls.bands ?? []).map((band) => (
+              <YStack key={band.param} {...knobProps.gap}>
+                <SectionLabel>{band.label}</SectionLabel>
+                <BandFilter
+                  band={band}
+                  list={list}
+                  layout="list"
+                  testID={`${testID}-tools-${band.param}`}
+                />
+              </YStack>
+            ))}
+            {ranges.map((range) => (
+              <RangeFilter
+                key={range.param}
+                label={range.label}
+                value={state.ranges[range.param] ?? 0}
+                max={rangeCeiling(list.highest[range.param] ?? 0)}
+                step={range.step}
+                onChange={(value) => update({ ranges: { [range.param]: value } })}
+              />
+            ))}
+            {showFavorites || shuffle ? (
+              <YStack {...knobProps.gap} alignItems="flex-start">
+                {showFavorites ? (
+                  <Button
+                    outlined={!state.favoritesOnly}
+                    theme={state.favoritesOnly ? "accent" : undefined}
+                    onPress={() => update({ favoritesOnly: !state.favoritesOnly })}
+                    aria-pressed={state.favoritesOnly}
+                    icon={
+                      <HeartIcon
+                        size={iconSize}
+                        weight={state.favoritesOnly ? "fill" : "regular"}
+                      />
+                    }
+                    testID={`${testID}-tools-favorites`}
+                  >
+                    {favorites.count > 0
+                      ? t("Favorites ({{count}})", { count: favorites.count })
+                      : t("Favorites")}
+                  </Button>
+                ) : null}
+                {shuffle ? (
+                  <Button
+                    outlined={!shuffle.open}
+                    theme={shuffle.open ? "accent" : undefined}
+                    onPress={() => {
+                      // The pick opens under the band, so the sheet steps aside.
+                      shuffle.toggle();
+                      setOpen(false);
+                    }}
+                    icon={<DiceFiveIcon size={iconSize} />}
+                    aria-expanded={shuffle.open}
+                    aria-controls={shuffle.panelId}
+                    testID={`${testID}-tools-shuffle`}
+                  >
+                    {t("Surprise me")}
+                  </Button>
+                ) : null}
+              </YStack>
+            ) : null}
+            {isListNarrowed(state) ? (
+              <YStack alignItems="flex-start">
+                <Button chromeless onPress={list.clear} testID={`${testID}-tools-clear`}>
+                  {t("Clear filters")}
+                </Button>
+              </YStack>
+            ) : null}
+          </YStack>
+        ) : null}
+      </SheetModal>
+    </>
+  );
+}

package/src/list/RangeFilter.spec.tsx

@@ -0,0 +1,88 @@
+// The base-XP filter is a stock Tamagui Slider: Track, TrackActive and one
+// Thumb from the tamagui barrel, the track a thin size token, the thumb a
+// size token, at row and stacked (sidebar / sheet) layouts alike. The thumb
+// follows input at once and the minimum commits once it rests.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { act, cleanup, fireEvent, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { RangeFilter } from "./RangeFilter";
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+const source = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), "RangeFilter.tsx"),
+  "utf8",
+);
+
+async function renderSlider(layout: "row" | "stack", onChange = vi.fn(), value = 0) {
+  renderWithProviders(
+    <RangeFilter
+      label="Base XP"
+      value={value}
+      max={300}
+      step={5}
+      layout={layout}
+      onChange={onChange}
+      testID="xp"
+    />,
+  );
+  const slider = await screen.findByTestId("xp", {}, { timeout: 5000 });
+  return { slider, onChange };
+}
+
+describe("RangeFilter stock slider", () => {
+  it("composes the tamagui Slider's own parts, not the forms wrapper", () => {
+    expect(source).toMatch(/await import\("tamagui"\)/);
+    expect(source).not.toMatch(/@multiplatform\.one\/forms"\)/);
+    expect(source).toMatch(/<Slider\.Track/);
+    expect(source).toMatch(/<Slider\.TrackActive/);
+    expect(source).toMatch(/<Slider\.Thumb/);
+  });
+
+  it("sizes the track and thumb from tokens: a thin track, a token thumb", () => {
+    expect(source).toMatch(/<Slider\.Track height="\$0\.5"/);
+    expect(source).toMatch(/size="\$1\.5"/);
+  });
+
+  for (const layout of ["row", "stack"] as const) {
+    it(`renders track, filled range and thumb in the ${layout} layout`, async () => {
+      const { slider } = await renderSlider(layout, vi.fn(), 60);
+      expect(slider.querySelector('[data-slider-part="track"]')).not.toBeNull();
+      expect(slider.querySelector('[data-slider-part="range"]')).not.toBeNull();
+      const thumb = screen.getByRole("slider");
+      expect(thumb.getAttribute("aria-valuenow")).toBe("60");
+      expect(thumb.getAttribute("aria-valuemax")).toBe("300");
+      expect(document.querySelector(`[data-range-layout="${layout}"]`)).not.toBeNull();
+    });
+  }
+
+  it("reads Any at no minimum and the minimum with a plus once set", async () => {
+    await renderSlider("stack", vi.fn(), 0);
+    expect(document.querySelector("[data-range-readout]")?.textContent).toBe("Any");
+    cleanup();
+    await renderSlider("stack", vi.fn(), 120);
+    expect(document.querySelector("[data-range-readout]")?.textContent).toBe("120+");
+  });
+
+  it("moves the thumb at once and commits the minimum once it rests", async () => {
+    const { onChange } = await renderSlider("stack", vi.fn(), 60);
+    const thumb = screen.getByRole("slider");
+    vi.useFakeTimers();
+    act(() => {
+      fireEvent.keyDown(thumb, { key: "ArrowRight" });
+    });
+    expect(document.querySelector("[data-range-readout]")?.textContent).toBe("65+");
+    expect(onChange).not.toHaveBeenCalled();
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    vi.useRealTimers();
+    await waitFor(() => expect(onChange).toHaveBeenCalledWith(65));
+  });
+});

package/src/list/RangeFilter.tsx

@@ -1,6 +1,6 @@
 import { Text, XStack, YStack } from "@multiplatform.one/components";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
-import { Suspense, lazy, type ComponentType } from "react";
+import { Suspense, lazy, useEffect, useRef, useState, type ComponentType } from "react";
 import { useTranslation } from "react-i18next";
 
 export interface RangeFilterProps {
@@ -11,64 +11,151 @@ export interface RangeFilterProps {
   max: number;
   step?: number;
   onChange: (value: number) => void;
+  /**
+   * `row`: label, track and readout on one line (a toolbar band).
+   * `stack`: label and readout above a full-width track (a sidebar or sheet).
+   */
+  layout?: "row" | "stack";
+  testID?: string;
 }
 
-const readoutWidth = 44;
-const trackMinWidth = 100;
+/** Quiet time after the last slider move before the minimum commits. */
+const commitDelayMs = 150;
 
-// The forms Slider is not in the curated GNOME forms shim, so the row
-// resolves lazily and checks the barrel: a target without a Slider renders
-// no row (a label without its control is worse than nothing).
+// A stock Tamagui Slider: a thin token-high track, the filled range from the
+// accent ramp and a token-sized round thumb. Resolved lazily from the
+// tamagui barrel so a target whose tamagui build carries no Slider (the
+// curated GNOME shim) renders no row: a label without its control is worse
+// than nothing.
 const RangeRowLazy = lazy(async () => {
-  const forms = await import("@multiplatform.one/forms");
-  const MaybeSlider = (forms as Partial<typeof forms>).Slider;
+  const tamagui = await import("tamagui");
+  const MaybeSlider = (tamagui as Partial<typeof tamagui>).Slider;
   if (!MaybeSlider) {
     const Absent: ComponentType<RangeFilterProps> = () => null;
     return { default: Absent };
   }
   const Slider = MaybeSlider;
 
-  function RangeRow({ label, value, max, step = 5, onChange }: RangeFilterProps) {
+  function RangeRow({
+    label,
+    value,
+    max,
+    step = 5,
+    onChange,
+    layout = "row",
+    testID,
+  }: RangeFilterProps) {
     const { t } = useTranslation();
     const { knobProps } = useResolvedKnobs();
-    return (
-      <XStack {...knobProps.gap} alignItems="center" flexGrow={1} minWidth={0}>
-        <Text fontSize="$2" color="$color11" flexShrink={0} userSelect="none">
-          {label}
-        </Text>
-        {/* A column on purpose: the Slider's %-width chain collapses to 0
-            inside a row; a column's cross-axis stretch hands the track the
-            flexed width. */}
-        <YStack flexGrow={1} flexShrink={1} minWidth={trackMinWidth} justifyContent="center">
-          <Slider
-            value={[value]}
-            min={0}
-            max={max}
-            step={step}
-            onChange={(values) => {
-              if (typeof values[0] === "number") onChange(values[0]);
-            }}
+    // The thumb follows the finger at once; the list narrows once it rests.
+    const [draft, setDraft] = useState(value);
+    const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    useEffect(() => setDraft(value), [value]);
+    useEffect(
+      () => () => {
+        if (timer.current) clearTimeout(timer.current);
+      },
+      [],
+    );
+    const move = (next: number) => {
+      setDraft(next);
+      if (timer.current) clearTimeout(timer.current);
+      timer.current = setTimeout(() => onChangeRef.current(next), commitDelayMs);
+    };
+
+    const readout = (
+      <Text
+        {...knobProps.label}
+        color={draft > 0 ? "$color12" : "$color10"}
+        flexShrink={0}
+        userSelect="none"
+        textAlign="right"
+        data-range-readout=""
+      >
+        {draft > 0 ? `${draft}+` : t("Any")}
+      </Text>
+    );
+    const caption = (
+      <Text {...knobProps.label} color="$color11" flexShrink={0} userSelect="none">
+        {label}
+      </Text>
+    );
+    // A column on purpose: the Slider's %-width chain collapses to 0 inside
+    // a row; a column's cross-axis stretch hands the track the flexed width.
+    const track = (
+      // Inset by half the thumb so it stays inside the column at either end.
+      <YStack
+        flexGrow={1}
+        flexShrink={1}
+        minWidth={0}
+        justifyContent="center"
+        paddingHorizontal="$2"
+      >
+        <Slider
+          value={[Math.min(draft, max)]}
+          min={0}
+          max={max}
+          step={step}
+          size="$2"
+          onValueChange={(values: number[]) => {
+            if (typeof values[0] === "number") move(values[0]);
+          }}
+          aria-label={label}
+          testID={testID}
+          data-range-slider=""
+        >
+          <Slider.Track height="$0.5" backgroundColor="$color5" data-slider-part="track">
+            <Slider.TrackActive backgroundColor="$color9" data-slider-part="range" />
+          </Slider.Track>
+          <Slider.Thumb
+            index={0}
+            size="$1.5"
+            circular
+            backgroundColor="$background"
+            borderColor="$color9"
+            borderWidth={knobProps.surface.borderWidth}
+            elevation={knobProps.elevation}
+            hoverStyle={{ borderColor: "$color10" }}
+            pressStyle={{ borderColor: "$color11" }}
+            focusVisibleStyle={{ outlineColor: "$outlineColor", outlineWidth: 2 }}
             aria-label={label}
-            compact
+            data-slider-part="thumb"
           />
+        </Slider>
+      </YStack>
+    );
+
+    if (layout === "stack") {
+      return (
+        <YStack {...knobProps.gapSm} data-range-layout="stack">
+          <XStack alignItems="baseline" {...knobProps.gap}>
+            {caption}
+            {readout}
+          </XStack>
+          {track}
         </YStack>
-        <Text
-          fontSize="$2"
-          fontWeight="600"
-          color={value > 0 ? "$color12" : "$color10"}
-          minWidth={readoutWidth}
-          textAlign="right"
-          userSelect="none"
-        >
-          {value > 0 ? `${value}+` : t("Any")}
-        </Text>
+      );
+    }
+    return (
+      <XStack
+        {...knobProps.gap}
+        alignItems="center"
+        flexGrow={1}
+        minWidth={0}
+        data-range-layout="row"
+      >
+        {caption}
+        {track}
+        {readout}
       </XStack>
     );
   }
   return { default: RangeRow };
 });
 
-/** A "minimum value" filter for a numeric field: label, slider, readout. */
+/** A "minimum value" filter for a numeric field: label, stock slider, readout. */
 export function RangeFilter(props: RangeFilterProps) {
   return (
     <Suspense fallback={null}>