@multiplatform.one/frappe-ui 7.34.3 → 7.35.0

package/src/list/ListFilterPanel.tsx

@@ -0,0 +1,140 @@
+import { Text, XStack, YStack } from "@multiplatform.one/components";
+import { Button, Select } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { HeartIcon } from "@phosphor-icons/react";
+import type { ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { BandFilter } from "./BandFilters";
+import { FacetList } from "./FacetList";
+import { activeFilterCount, type FrappeListControls } from "./listState";
+import { RangeFilter, rangeCeiling } from "./RangeFilter";
+import type { ListControlsResult } from "./useListControls";
+
+export interface ListFilterPanelProps {
+  controls: FrappeListControls;
+  list: ListControlsResult;
+  showFavorites: boolean;
+  /** The sort select joins the panel (the phone sheet, where no toolbar holds it). */
+  showSort?: boolean;
+  testID: string;
+}
+
+/** One group of the panel under its caps label. */
+function PanelGroup({ label, children }: { label: string; children: ReactNode }) {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <YStack {...knobProps.gapSm} role="group" aria-label={label}>
+      <Text
+        {...knobProps.label}
+        fontWeight="700"
+        color="$color10"
+        textTransform="uppercase"
+        letterSpacing={1}
+        userSelect="none"
+        aria-hidden
+      >
+        {label}
+      </Text>
+      {children}
+    </YStack>
+  );
+}
+
+/**
+ * A list's filters as one vertical panel: each facet and band as a list of
+ * values with counts, each range as a stock slider, favorites as a toggle,
+ * and Clear filters once any is set. The desktop sidebar and the phone
+ * sheet draw the same panel, so both offer the same filters.
+ */
+export function ListFilterPanel({
+  controls,
+  list,
+  showFavorites,
+  showSort = false,
+  testID,
+}: ListFilterPanelProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  const { state, update, favorites } = list;
+  const sorts = controls.sorts ?? [];
+  const active = activeFilterCount(state);
+
+  return (
+    <YStack {...knobProps.gapLg} testID={`${testID}-filters`}>
+      {showSort && sorts.length > 0 ? (
+        <PanelGroup label={t("Sort by")}>
+          <Select
+            value={state.sort}
+            onChange={(value) => update({ sort: String(value) })}
+            options={sorts.map((sort) => ({ label: sort.label, value: sort.value }))}
+            aria-label={t("Sort by")}
+          />
+        </PanelGroup>
+      ) : null}
+      {(controls.facets ?? []).map((facet) => {
+        const reading = list.facets[facet.param];
+        return (
+          <PanelGroup key={facet.param} label={facet.label}>
+            <FacetList
+              label={facet.label}
+              value={state.facets[facet.param] ?? ""}
+              onChange={(value) => update({ facets: { [facet.param]: value } })}
+              columns={2}
+              testID={`${testID}-${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 && list.total !== undefined ? (reading.counts[value] ?? 0) : undefined,
+                })),
+              ]}
+            />
+          </PanelGroup>
+        );
+      })}
+      {(controls.bands ?? []).map((band) => (
+        <PanelGroup key={band.param} label={band.label}>
+          <BandFilter band={band} list={list} layout="list" testID={`${testID}-${band.param}`} />
+        </PanelGroup>
+      ))}
+      {(controls.ranges ?? []).map((range) => (
+        <RangeFilter
+          key={range.param}
+          layout="stack"
+          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 } })}
+          testID={`${testID}-${range.param}-slider`}
+        />
+      ))}
+      {showFavorites ? (
+        <XStack>
+          <Button
+            outlined={!state.favoritesOnly}
+            theme={state.favoritesOnly ? "accent" : undefined}
+            onPress={() => update({ favoritesOnly: !state.favoritesOnly })}
+            aria-pressed={state.favoritesOnly}
+            icon={<HeartIcon size={16} weight={state.favoritesOnly ? "fill" : "regular"} />}
+            testID={`${testID}-favorites-filter`}
+          >
+            {favorites.count > 0
+              ? t("Favorites ({{count}})", { count: favorites.count })
+              : t("Favorites")}
+          </Button>
+        </XStack>
+      ) : null}
+      {active > 0 ? (
+        <XStack>
+          <Button chromeless onPress={list.clear} testID={`${testID}-clear`}>
+            {t("Clear filters")}
+          </Button>
+        </XStack>
+      ) : null}
+    </YStack>
+  );
+}

package/src/list/ListSidebarToolbar.tsx

@@ -0,0 +1,193 @@
+import {
+  Badge,
+  DropdownMenu,
+  SheetModal,
+  Text,
+  Tooltip,
+  XStack,
+  YStack,
+  type DropdownMenuEntry,
+} from "@multiplatform.one/components";
+import { Button, SearchInput, Select } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { DiceFiveIcon, DotsThreeIcon, FadersHorizontalIcon } from "@phosphor-icons/react";
+import { useState, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { ListFilterPanel } from "./ListFilterPanel";
+import { activeFilterCount, type FrappeListControls } from "./listState";
+import type { ListControlsResult } from "./useListControls";
+
+export interface ListSidebarToolbarProps {
+  controls: FrappeListControls;
+  list: ListControlsResult;
+  /** DOM id of the search box's wrapper, which the "/" shortcut focuses. */
+  searchId: string;
+  searchPlaceholder?: string;
+  showSearch: boolean;
+  showFavorites: boolean;
+  /** Present when the list offers a random pick. */
+  shuffle?: { open: boolean; toggle: () => void; panelId: string };
+  /** The random pick, under the toolbar while open. */
+  shufflePanel?: ReactNode;
+  /**
+   * The page's secondary actions. Below `md` they leave the header for the
+   * ⋯ menu beside the Filters button.
+   */
+  menuItems: readonly DropdownMenuEntry[];
+  testID: string;
+}
+
+/**
+ * The toolbar of a list whose filters live in the page's sidebar: search
+ * and sort from `md` up; below it search, a Filters button wearing the
+ * active-filter count that opens the same filters (sort included) in a
+ * bottom sheet, and a ⋯ menu holding the secondary actions.
+ */
+export function ListSidebarToolbar({
+  controls,
+  list,
+  searchId,
+  searchPlaceholder,
+  showSearch,
+  showFavorites,
+  shuffle,
+  shufflePanel,
+  menuItems,
+  testID,
+}: ListSidebarToolbarProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  const [sheetOpen, setSheetOpen] = useState(false);
+  const { state, update } = list;
+  const sorts = controls.sorts ?? [];
+  const active = activeFilterCount(state);
+  const filtersLabel = active > 0 ? t("Filters ({{count}})", { count: active }) : t("Filters");
+
+  return (
+    <YStack {...knobProps.gap} testID={`${testID}-controls`}>
+      <XStack {...knobProps.gap} alignItems="center">
+        {showSearch ? (
+          <XStack id={searchId} flex={1} minWidth={0} alignItems="center">
+            <YStack flex={1} minWidth={0}>
+              <SearchInput
+                value={list.searchText}
+                onChange={list.setSearchText}
+                onSearch={(text) => update({ search: text })}
+                placeholder={searchPlaceholder ?? t("Search...")}
+                aria-label={searchPlaceholder ?? t("Search...")}
+                debounceMs={200}
+                clearable
+              />
+            </YStack>
+          </XStack>
+        ) : (
+          <XStack flex={1} />
+        )}
+        {sorts.length > 0 ? (
+          <XStack
+            // responsive-parity: Sort moves into the phone Filters sheet.
+            flexShrink={0}
+            $max-md={{ display: "none" }}
+            testID={`${testID}-sort`}
+          >
+            <Select
+              value={state.sort}
+              onChange={(value) => update({ sort: String(value) })}
+              options={sorts.map((sort) => ({ label: sort.label, value: sort.value }))}
+              placeholder={t("Sort by")}
+              aria-label={t("Sort by")}
+            />
+          </XStack>
+        ) : null}
+        {shuffle ? (
+          <XStack
+            // responsive-parity: Surprise me remains in the phone More actions menu.
+            flexShrink={0}
+            $max-md={{ display: "none" }}
+          >
+            <Tooltip content={t("Open a random record")}>
+              <Button
+                outlined={!shuffle.open}
+                theme={shuffle.open ? "accent" : undefined}
+                circular
+                onPress={shuffle.toggle}
+                icon={<DiceFiveIcon size={16} />}
+                aria-label={t("Surprise me")}
+                aria-expanded={shuffle.open}
+                aria-controls={shuffle.panelId}
+                testID={`${testID}-shuffle-toggle`}
+              />
+            </Tooltip>
+          </XStack>
+        ) : null}
+        <XStack
+          flexShrink={0}
+          display="none"
+          $max-md={{ display: "flex" }}
+          {...knobProps.gap}
+          alignItems="center"
+          testID={`${testID}-phone-tools`}
+        >
+          <Badge count={active}>
+            <Button
+              outlined={active === 0}
+              theme={active > 0 ? "accent" : undefined}
+              icon={<FadersHorizontalIcon size={16} />}
+              onPress={() => setSheetOpen(true)}
+              aria-label={filtersLabel}
+              aria-haspopup="dialog"
+              aria-expanded={sheetOpen}
+              testID={`${testID}-filters-button`}
+            >
+              {t("Filters")}
+            </Button>
+          </Badge>
+          {menuItems.length > 0 ? (
+            <DropdownMenu items={[...menuItems]} placement="bottom-end">
+              <Button
+                outlined
+                circular
+                icon={<DotsThreeIcon size={20} weight="bold" />}
+                aria-label={t("More actions")}
+                testID={`${testID}-more`}
+              />
+            </DropdownMenu>
+          ) : null}
+        </XStack>
+      </XStack>
+      {shufflePanel}
+      <SheetModal
+        open={sheetOpen}
+        onOpenChange={setSheetOpen}
+        scrollable
+        snapPoint={85}
+        header={
+          <XStack alignItems="center" {...knobProps.gap}>
+            <Text {...knobProps.heading} fontWeight="700" role="heading" aria-level={2}>
+              {t("Filters")}
+            </Text>
+            <Button
+              theme="accent"
+              onPress={() => setSheetOpen(false)}
+              testID={`${testID}-filters-done`}
+            >
+              {t("Done")}
+            </Button>
+          </XStack>
+        }
+      >
+        {sheetOpen ? (
+          <YStack testID={`${testID}-filters-sheet`}>
+            <ListFilterPanel
+              controls={controls}
+              list={list}
+              showFavorites={showFavorites}
+              showSort
+              testID={`${testID}-sheet`}
+            />
+          </YStack>
+        ) : null}
+      </SheetModal>
+    </YStack>
+  );
+}

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