@multiplatform.one/table 6.6.0 → 7.0.0

package/src/components/DataTableFacetMenu/DataTableFacetMenu.spec.tsx

@@ -0,0 +1,264 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { fireEvent, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { DataTableFacetMenu, type DataTableFacetOption } from "./index";
+
+const options: DataTableFacetOption[] = [
+  { value: "alice@example.com", label: "Alice", count: 12 },
+  { value: "bob@example.com", label: "Bob", count: 4 },
+  { value: "carol@example.com", label: "Carol", count: 0 },
+];
+
+async function openMenu(
+  utils: ReturnType<typeof renderWithProviders>,
+  name = "Assigned To",
+): Promise<void> {
+  fireEvent.click(utils.getByRole("button", { name }));
+  await waitFor(
+    () => {
+      expect(utils.getAllByRole("menuitemcheckbox").length).toBeGreaterThan(0);
+    },
+    { timeout: 3000 },
+  );
+}
+
+describe("DataTableFacetMenu", () => {
+  describe("trigger", () => {
+    it("renders the facet label as the trigger", () => {
+      const { getByRole } = renderWithProviders(
+        <DataTableFacetMenu label="Assigned To" options={options} />,
+      );
+      const trigger = getByRole("button", { name: "Assigned To" });
+      expect(trigger).toBeDefined();
+      expect(trigger.textContent).toContain("Assigned To");
+    });
+
+    it("carries the active count on the trigger", () => {
+      const { getByRole } = renderWithProviders(
+        <DataTableFacetMenu
+          label="Assigned To"
+          options={options}
+          activeValues={["alice@example.com"]}
+        />,
+      );
+      expect(getByRole("button", { name: "Assigned To" }).textContent).toContain(
+        "Assigned To (1)",
+      );
+    });
+
+    it("does not render menu rows while closed", () => {
+      const { queryAllByRole } = renderWithProviders(
+        <DataTableFacetMenu label="Assigned To" options={options} />,
+      );
+      expect(queryAllByRole("menuitemcheckbox").length).toBe(0);
+    });
+  });
+
+  describe("menu content", () => {
+    it("renders one checkbox row per option with its count", async () => {
+      const utils = renderWithProviders(
+        <DataTableFacetMenu label="Assigned To" options={options} />,
+      );
+      await openMenu(utils);
+      const rows = utils.getAllByRole("menuitemcheckbox");
+      expect(rows.length).toBe(3);
+      expect(rows[0].textContent).toContain("Alice");
+      expect(rows[0].textContent).toContain("12");
+      expect(rows[1].textContent).toContain("Bob");
+      expect(rows[1].textContent).toContain("4");
+    });
+
+    it("falls back to the raw value when an option has no label", async () => {
+      const utils = renderWithProviders(
+        <DataTableFacetMenu label="Tags" options={[{ value: "urgent", count: 2 }]} />,
+      );
+      await openMenu(utils, "Tags");
+      expect(utils.getAllByRole("menuitemcheckbox")[0].textContent).toContain("urgent");
+    });
+
+    it("marks active options checked", async () => {
+      const utils = renderWithProviders(
+        <DataTableFacetMenu
+          label="Assigned To"
+          options={options}
+          activeValues={["bob@example.com"]}
+        />,
+      );
+      await openMenu(utils);
+      const rows = utils.getAllByRole("menuitemcheckbox");
+      expect(rows[0].getAttribute("aria-checked")).toBe("false");
+      expect(rows[1].getAttribute("aria-checked")).toBe("true");
+    });
+
+    it("shows an empty state when there are no options and not loading", async () => {
+      const utils = renderWithProviders(<DataTableFacetMenu label="Tags" options={[]} />);
+      fireEvent.click(utils.getByRole("button", { name: "Tags" }));
+      await waitFor(() => {
+        expect(utils.getByText("No options")).toBeDefined();
+      });
+    });
+
+    it("shows a loading indicator and keeps stale options visible", async () => {
+      const utils = renderWithProviders(
+        <DataTableFacetMenu label="Assigned To" options={options} loading />,
+      );
+      await openMenu(utils);
+      // Stale-while-visible: prior options stay rendered while revalidating.
+      expect(utils.getAllByRole("menuitemcheckbox").length).toBe(3);
+      expect(utils.baseElement.querySelector("[data-facet-loading='true']")).toBeTruthy();
+    });
+
+    it("suppresses the empty state while loading with no options", async () => {
+      const utils = renderWithProviders(
+        <DataTableFacetMenu label="Assigned To" options={[]} loading />,
+      );
+      fireEvent.click(utils.getByRole("button", { name: "Assigned To" }));
+      await waitFor(() => {
+        expect(utils.baseElement.querySelector("[data-facet-loading='true']")).toBeTruthy();
+      });
+      expect(utils.queryByText("No options")).toBeNull();
+    });
+  });
+
+  describe("replace selection (desk facet semantics)", () => {
+    it("replaces the selection with the pressed option", async () => {
+      const onActiveValuesChange = vi.fn();
+      const utils = renderWithProviders(
+        <DataTableFacetMenu
+          label="Assigned To"
+          options={options}
+          activeValues={["alice@example.com"]}
+          onActiveValuesChange={onActiveValuesChange}
+        />,
+      );
+      await openMenu(utils);
+      fireEvent.click(utils.getAllByRole("menuitemcheckbox")[1]);
+      expect(onActiveValuesChange).toHaveBeenCalledWith(["bob@example.com"], options[1]);
+    });
+
+    it("clears the selection when the active option is pressed", async () => {
+      const onActiveValuesChange = vi.fn();
+      const utils = renderWithProviders(
+        <DataTableFacetMenu
+          label="Assigned To"
+          options={options}
+          activeValues={["alice@example.com"]}
+          onActiveValuesChange={onActiveValuesChange}
+        />,
+      );
+      await openMenu(utils);
+      fireEvent.click(utils.getAllByRole("menuitemcheckbox")[0]);
+      expect(onActiveValuesChange).toHaveBeenCalledWith([], options[0]);
+    });
+  });
+
+  describe("toggle selection (multi-select)", () => {
+    it("adds the pressed option to the active set", async () => {
+      const onActiveValuesChange = vi.fn();
+      const utils = renderWithProviders(
+        <DataTableFacetMenu
+          label="Tags"
+          selection="toggle"
+          options={options}
+          activeValues={["alice@example.com"]}
+          onActiveValuesChange={onActiveValuesChange}
+        />,
+      );
+      await openMenu(utils, "Tags");
+      fireEvent.click(utils.getAllByRole("menuitemcheckbox")[1]);
+      expect(onActiveValuesChange).toHaveBeenCalledWith(
+        ["alice@example.com", "bob@example.com"],
+        options[1],
+      );
+    });
+
+    it("removes only the pressed option when it is active", async () => {
+      const onActiveValuesChange = vi.fn();
+      const utils = renderWithProviders(
+        <DataTableFacetMenu
+          label="Tags"
+          selection="toggle"
+          options={options}
+          activeValues={["alice@example.com", "bob@example.com"]}
+          onActiveValuesChange={onActiveValuesChange}
+        />,
+      );
+      await openMenu(utils, "Tags");
+      fireEvent.click(utils.getAllByRole("menuitemcheckbox")[0]);
+      expect(onActiveValuesChange).toHaveBeenCalledWith(["bob@example.com"], options[0]);
+    });
+  });
+
+  describe("compose behavior", () => {
+    it("keeps the menu open after a selection (counts revalidate in place)", async () => {
+      const utils = renderWithProviders(
+        <DataTableFacetMenu
+          label="Assigned To"
+          options={options}
+          onActiveValuesChange={() => {}}
+        />,
+      );
+      await openMenu(utils);
+      fireEvent.click(utils.getAllByRole("menuitemcheckbox")[0]);
+      // CheckboxItem COMPOSE default: the menu must not close on select.
+      expect(utils.getAllByRole("menuitemcheckbox").length).toBe(3);
+    });
+  });
+
+  describe("compound composition", () => {
+    it("renders custom Item children instead of options", async () => {
+      const onPress = vi.fn();
+      const utils = renderWithProviders(
+        <DataTableFacetMenu label="Status">
+          <DataTableFacetMenu.Item label="Open" count={7} active onPress={onPress} />
+          <DataTableFacetMenu.Item label="Closed" count={1} onPress={() => {}} />
+        </DataTableFacetMenu>,
+      );
+      await openMenu(utils, "Status");
+      const rows = utils.getAllByRole("menuitemcheckbox");
+      expect(rows.length).toBe(2);
+      expect(rows[0].textContent).toContain("Open");
+      expect(rows[0].textContent).toContain("7");
+      expect(rows[0].getAttribute("aria-checked")).toBe("true");
+      fireEvent.click(rows[0]);
+      expect(onPress).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("disabled state", () => {
+    it("renders a disabled trigger with its reason", () => {
+      const { getByRole } = renderWithProviders(
+        <DataTableFacetMenu
+          label="Assigned To"
+          options={options}
+          disabled
+          disabledReason="Assignments are unavailable offline"
+        />,
+      );
+      const trigger = getByRole("button", { name: /Assigned To/ });
+      expect(trigger.getAttribute("aria-disabled") ?? trigger.getAttribute("disabled")).not.toBe(
+        null,
+      );
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles option presses without an onActiveValuesChange handler", async () => {
+      const utils = renderWithProviders(
+        <DataTableFacetMenu label="Assigned To" options={options} />,
+      );
+      await openMenu(utils);
+      expect(() => {
+        fireEvent.click(utils.getAllByRole("menuitemcheckbox")[0]);
+      }).not.toThrow();
+    });
+
+    it("renders options without counts (no trailing number)", async () => {
+      const utils = renderWithProviders(
+        <DataTableFacetMenu label="Module" options={[{ value: "Core", label: "Core" }]} />,
+      );
+      await openMenu(utils, "Module");
+      expect(utils.getAllByRole("menuitemcheckbox")[0].textContent).toBe("Core");
+    });
+  });
+});

package/src/components/DataTableFacetMenu/DataTableFacetMenu.stories.tsx

@@ -0,0 +1,212 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta } from "@storybook/react-native-web-vite";
+import { useMemo, useState } from "react";
+import { XStack, YStack } from "tamagui";
+import type { DataTableColumn } from "../../types";
+import { DataTable } from "../DataTable";
+import { DataTableToolbar } from "../DataTableToolbar";
+import { DataTableFacetMenu, type DataTableFacetOption } from "./index";
+
+const meta: Meta<typeof DataTableFacetMenu> = {
+  title: "Table/DataTableFacetMenu",
+  component: DataTableFacetMenu,
+  parameters: {
+    status: { type: "stable" },
+  },
+};
+
+export default meta;
+
+interface Ticket {
+  id: number;
+  title: string;
+  assignee: string;
+  status: "Open" | "Working" | "Closed";
+  tags: string;
+}
+
+const tickets: Ticket[] = [
+  { id: 1, title: "Fix login redirect", assignee: "Alice", status: "Open", tags: "bug" },
+  { id: 2, title: "Dark mode pass", assignee: "Bob", status: "Working", tags: "design" },
+  { id: 3, title: "Broken CSV export", assignee: "Alice", status: "Open", tags: "bug,export" },
+  { id: 4, title: "Onboarding tour", assignee: "Carol", status: "Closed", tags: "design" },
+  { id: 5, title: "Rate limit uploads", assignee: "Alice", status: "Working", tags: "infra" },
+  { id: 6, title: "Audit log screen", assignee: "Bob", status: "Open", tags: "infra,bug" },
+];
+
+const ticketColumns: DataTableColumn<Ticket>[] = [
+  { accessorKey: "title", header: "Title" },
+  { accessorKey: "assignee", header: "Assignee" },
+  { accessorKey: "status", header: "Status" },
+  { accessorKey: "tags", header: "Tags" },
+];
+
+function countBy(rows: Ticket[], pick: (row: Ticket) => string[]): DataTableFacetOption[] {
+  const counts = new Map<string, number>();
+  for (const row of rows) {
+    for (const value of pick(row)) counts.set(value, (counts.get(value) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .map(([value, count]) => ({ value, count }))
+    .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
+}
+
+/**
+ * The intended composition: facet menus slot into the DataTableToolbar
+ * action cluster (customActions) beside the Filter button, feeding the
+ * host's own filter state — here the story filters the rows it hands the
+ * table, the same shape a Frappe host gets from useFrappeFacets.
+ */
+const InToolbarStory = () => {
+  const [assignee, setAssignee] = useState<string[]>([]);
+  const [statuses, setStatuses] = useState<string[]>([]);
+
+  const rows = useMemo(
+    () =>
+      tickets.filter(
+        (ticket) =>
+          (assignee.length === 0 || assignee.includes(ticket.assignee)) &&
+          (statuses.length === 0 || statuses.includes(ticket.status)),
+      ),
+    [assignee, statuses],
+  );
+
+  // Desk parity: each facet's counts respect every OTHER facet's selection.
+  const assigneeOptions = useMemo(
+    () =>
+      countBy(
+        tickets.filter((row) => statuses.length === 0 || statuses.includes(row.status)),
+        (row) => [row.assignee],
+      ),
+    [statuses],
+  );
+  const statusOptions = useMemo(
+    () =>
+      countBy(
+        tickets.filter((row) => assignee.length === 0 || assignee.includes(row.assignee)),
+        (row) => [row.status],
+      ),
+    [assignee],
+  );
+
+  return (
+    <YStack padding="$4">
+      <DataTable
+        data={rows}
+        columns={ticketColumns}
+        enableGlobalSearch
+        renderToolbar={(props) => (
+          <DataTableToolbar
+            {...props}
+            customActions={
+              <XStack gap="$2" alignItems="center">
+                <DataTableFacetMenu
+                  label="Assignee"
+                  options={assigneeOptions}
+                  activeValues={assignee}
+                  onActiveValuesChange={(next, pressed) => {
+                    setAssignee(next);
+                    action("assignee-change")(next, pressed.value);
+                  }}
+                />
+                <DataTableFacetMenu
+                  label="Status"
+                  selection="toggle"
+                  options={statusOptions}
+                  activeValues={statuses}
+                  onActiveValuesChange={(next, pressed) => {
+                    setStatuses(next);
+                    action("status-change")(next, pressed.value);
+                  }}
+                />
+              </XStack>
+            }
+          />
+        )}
+        aria-label="Tickets with facet menus"
+      />
+    </YStack>
+  );
+};
+
+export const Default = {
+  name: "Main",
+  render: () => <InToolbarStory />,
+};
+
+const ReplaceSelectionStory = () => {
+  const [active, setActive] = useState<string[]>(["Alice"]);
+  return (
+    <YStack padding="$4" alignItems="flex-start" gap="$3">
+      <DataTableFacetMenu
+        label="Created By"
+        options={[
+          { value: "Alice", label: "Me", count: 3 },
+          { value: "Bob", count: 2 },
+          { value: "Carol", count: 1 },
+        ]}
+        activeValues={active}
+        onActiveValuesChange={(next, pressed) => {
+          setActive(next);
+          action("created-by-change")(next, pressed.value);
+        }}
+      />
+    </YStack>
+  );
+};
+
+export const ReplaceSelection = {
+  render: () => <ReplaceSelectionStory />,
+};
+
+const ToggleSelectionStory = () => {
+  const [active, setActive] = useState<string[]>(["bug"]);
+  return (
+    <YStack padding="$4" alignItems="flex-start" gap="$3">
+      <DataTableFacetMenu
+        label="Tags"
+        selection="toggle"
+        options={[
+          { value: "bug", count: 3 },
+          { value: "design", count: 2 },
+          { value: "infra", count: 2 },
+          { value: "export", count: 1 },
+        ]}
+        activeValues={active}
+        onActiveValuesChange={(next, pressed) => {
+          setActive(next);
+          action("tags-change")(next, pressed.value);
+        }}
+      />
+    </YStack>
+  );
+};
+
+export const ToggleSelection = {
+  render: () => <ToggleSelectionStory />,
+};
+
+export const LoadingWithStaleCounts = {
+  render: () => (
+    <YStack padding="$4" alignItems="flex-start">
+      <DataTableFacetMenu
+        label="Assigned To"
+        loading
+        options={[
+          { value: "Alice", count: 12 },
+          { value: "Bob", count: 4 },
+        ]}
+        activeValues={["Alice"]}
+        onActiveValuesChange={action("change")}
+      />
+    </YStack>
+  ),
+};
+
+export const Empty = {
+  render: () => (
+    <YStack padding="$4" alignItems="flex-start">
+      <DataTableFacetMenu label="Tags" options={[]} onActiveValuesChange={action("change")} />
+    </YStack>
+  ),
+};

package/src/components/DataTableFacetMenu/index.tsx

@@ -0,0 +1,202 @@
+/**
+ * DataTableFacetMenu — presentational facet menu for the toolbar action
+ * cluster (sits beside DataTableFilterButton / SavedFilterDropdown, slotted
+ * through DataTableToolbar's `customActions`). A label trigger opens a menu
+ * of options with trailing counts; active options render checked and the
+ * trigger carries the active count (accent — same anatomy as the Filter
+ * button's active state).
+ *
+ * Selection SEMANTICS are prop-owned (`selection`):
+ *   - "replace" (default — desk list_sidebar_group_by parity): pressing a
+ *     row replaces the facet's whole selection with that row; pressing the
+ *     active row clears it (toggle off / replace).
+ *   - "toggle": rows accumulate (multi-select); pressing an active row
+ *     removes only that row.
+ *
+ * Purely presentational: options, counts, and active values arrive via
+ * props (feed from `useFrappeFacets` in @multiplatform.one/frappe-ui or any
+ * host source) and the component reports the NEXT active set through
+ * `onActiveValuesChange` — it holds no selection state of its own. The menu
+ * stays open on selection (LC-21 COMPOSE, CheckboxItem class default) so
+ * revalidated counts paint in place while the user composes.
+ */
+
+import { CaretDownIcon } from "@phosphor-icons/react";
+import { DropdownMenu, type DropdownMenuPlacement } from "@multiplatform.one/components";
+import { Button, Spinner } from "@multiplatform.one/forms";
+import type { ReactNode } from "react";
+import { useCallback } from "react";
+import { Text, XStack, withStaticProperties } from "tamagui";
+import { t } from "../../shared/t";
+
+export interface DataTableFacetOption {
+  /** Raw facet value (user id, tag, status value, …). */
+  value: string;
+  /** Display label; defaults to `value`. */
+  label?: string;
+  /** Result count for the option (omit to hide the trailing count). */
+  count?: number;
+}
+
+/** Selection semantics for option presses (see component doc). */
+export type DataTableFacetSelection = "replace" | "toggle";
+
+export interface DataTableFacetMenuProps {
+  /** Facet label — the trigger text and the menu's accessible name. */
+  label: string;
+  /** Options with counts. Ignored when compound children are provided. */
+  options?: readonly DataTableFacetOption[];
+  /** Values currently applied (highlighted / checked options). */
+  activeValues?: readonly string[];
+  /** Press semantics (default "replace" — desk facet parity). */
+  selection?: DataTableFacetSelection;
+  /**
+   * Fires with the NEXT active set (per `selection` semantics) and the
+   * pressed option. The host owns state — map the set to filters there.
+   */
+  onActiveValuesChange?: (next: string[], pressed: DataTableFacetOption) => void;
+  /** True while counts load — renders a menu spinner when no options yet. */
+  loading?: boolean;
+  disabled?: boolean;
+  /** DG-ST-03 — why the trigger is disabled (renders on the trigger). */
+  disabledReason?: string;
+  /** Menu placement (default "bottom-start"). */
+  placement?: DropdownMenuPlacement;
+  /**
+   * Compound composition: custom rows (DataTableFacetMenu.Item) replace the
+   * `options` list; loading/empty chrome stays prop-driven.
+   */
+  children?: ReactNode;
+}
+
+export interface DataTableFacetMenuItemProps {
+  label: string;
+  /** Trailing count (omit to hide). */
+  count?: number;
+  /** Row renders checked / highlighted. */
+  active?: boolean;
+  onPress: () => void;
+  disabled?: boolean;
+  /** DG-ST-03 — why the row is disabled; renders inline under the label. */
+  disabledReason?: string;
+}
+
+/**
+ * One facet row — label, optional trailing count, checked when active.
+ * Rides DropdownMenu.CheckboxItem so the menu stays open on press (COMPOSE)
+ * and the row exposes menuitemcheckbox semantics.
+ */
+function DataTableFacetMenuItem({
+  label,
+  count,
+  active = false,
+  onPress,
+  disabled,
+  disabledReason,
+}: DataTableFacetMenuItemProps) {
+  return (
+    <DropdownMenu.CheckboxItem
+      checked={active}
+      onCheckedChange={onPress}
+      {...(disabled ? { disabled } : {})}
+      {...(disabledReason ? { disabledReason } : {})}
+      // Trailing muted slot — the count reads as part of the row.
+      {...(typeof count === "number" ? { shortcut: String(count) } : {})}
+    >
+      {label}
+    </DropdownMenu.CheckboxItem>
+  );
+}
+
+function DataTableFacetMenuComponent({
+  label,
+  options,
+  activeValues,
+  selection = "replace",
+  onActiveValuesChange,
+  loading = false,
+  disabled,
+  disabledReason,
+  placement = "bottom-start",
+  children,
+}: DataTableFacetMenuProps) {
+  const active = activeValues ?? [];
+  const activeCount = active.length;
+
+  const handlePress = useCallback(
+    (option: DataTableFacetOption) => {
+      if (!onActiveValuesChange) return;
+      const isActive = active.includes(option.value);
+      let next: string[];
+      if (selection === "toggle") {
+        next = isActive
+          ? active.filter((value) => value !== option.value)
+          : [...active, option.value];
+      } else {
+        // "replace" — desk semantics: one active value per facet; pressing
+        // the active row clears the facet.
+        next = isActive ? [] : [option.value];
+      }
+      onActiveValuesChange(next, option);
+    },
+    [active, onActiveValuesChange, selection],
+  );
+
+  const rows = children ?? (
+    <>
+      {(options ?? []).map((option) => (
+        <DataTableFacetMenuItem
+          key={option.value}
+          label={option.label ?? option.value}
+          count={option.count}
+          active={active.includes(option.value)}
+          onPress={() => handlePress(option)}
+        />
+      ))}
+      {(options?.length ?? 0) === 0 && !loading && (
+        <Text fontSize="$2" color="$color10" paddingHorizontal="$3" paddingVertical="$2">
+          {t("No options")}
+        </Text>
+      )}
+    </>
+  );
+
+  return (
+    <DropdownMenu placement={placement}>
+      <DropdownMenu.Trigger asChild>
+        <Button
+          size="$3"
+          compact
+          // Active facet = accent trigger with count — the same active
+          // anatomy as DataTableFilterButton ("Filter (n)").
+          {...(activeCount > 0 ? { accent: true } : { variant: "outlined" as const })}
+          iconAfter={<CaretDownIcon size={14} />}
+          aria-haspopup="menu"
+          aria-label={label}
+          {...(disabled ? { disabled } : {})}
+          {...(disabledReason ? { disabledReason } : {})}
+        >
+          {activeCount > 0 ? `${label} (${activeCount})` : label}
+        </Button>
+      </DropdownMenu.Trigger>
+      <DropdownMenu.Content aria-label={label} minWidth={200}>
+        {rows}
+        {loading && (
+          <XStack
+            alignItems="center"
+            justifyContent="center"
+            paddingVertical="$2"
+            aria-live="polite"
+            data-facet-loading="true"
+          >
+            <Spinner size="small" />
+          </XStack>
+        )}
+      </DropdownMenu.Content>
+    </DropdownMenu>
+  );
+}
+
+export const DataTableFacetMenu = withStaticProperties(DataTableFacetMenuComponent, {
+  Item: DataTableFacetMenuItem,
+});