@multiplatform.one/components 7.78.0 → 7.80.0

package/src/SortableList/useUserOrder.ts

@@ -0,0 +1,96 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+/** Where a user's arrangement lives; defaults to the browser's localStorage. */
+export interface UserOrderStorage {
+  getItem: (key: string) => string | null;
+  setItem: (key: string, value: string) => void;
+}
+
+const memory = new Map<string, string>();
+const memoryStorage: UserOrderStorage = {
+  getItem: (key) => memory.get(key) ?? null,
+  setItem: (key, value) => {
+    memory.set(key, value);
+  },
+};
+
+function defaultStorage(): UserOrderStorage {
+  try {
+    const local = (globalThis as { localStorage?: UserOrderStorage }).localStorage;
+    if (local && typeof local.getItem === "function") return local;
+  } catch {
+    // storage blocked
+  }
+  return memoryStorage;
+}
+
+function readOrder(storage: UserOrderStorage, key: string): string[] {
+  try {
+    const parsed = JSON.parse(storage.getItem(key) ?? "[]") as unknown;
+    return Array.isArray(parsed) ? parsed.filter((id): id is string => typeof id === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The items in the user's order (LC-209): known ids keep their saved place,
+ * new ids land at the end in the order the source gave them. Ids missing
+ * from this read keep their slot in `order`, so a partial refresh never
+ * reshuffles them.
+ */
+export function applyUserOrder<T>(
+  items: readonly T[],
+  order: readonly string[],
+  getId: (item: T) => string,
+): { items: T[]; order: string[] } {
+  const byId = new Map(items.map((item) => [getId(item), item] as const));
+  const known = new Set(order);
+  const placed = order.flatMap((id) => {
+    const item = byId.get(id);
+    return item === undefined ? [] : [item];
+  });
+  const added = items.filter((item) => !known.has(getId(item)));
+  return {
+    items: [...placed, ...added],
+    order: [...order, ...added.map(getId)],
+  };
+}
+
+export interface UseUserOrderOptions {
+  storage?: UserOrderStorage;
+}
+
+/**
+ * Keeps a hand-arranged collection in the user's order across data refreshes
+ * and reloads. Feed `items` from any source order; render the returned
+ * `items`; pass `onChange` to SortableList.
+ */
+export function useUserOrder<T>(
+  key: string,
+  items: readonly T[],
+  getId: (item: T) => string,
+  options: UseUserOrderOptions = {},
+) {
+  const storage = useMemo(() => options.storage ?? defaultStorage(), [options.storage]);
+  const [order, setOrder] = useState(() => readOrder(storage, key));
+  const arranged = useMemo(() => applyUserOrder(items, order, getId), [items, order, getId]);
+
+  useEffect(() => {
+    if (arranged.order.length === order.length) return;
+    storage.setItem(key, JSON.stringify(arranged.order));
+    setOrder(arranged.order);
+  }, [arranged.order, order.length, storage, key]);
+
+  const onChange = useCallback(
+    (next: T[]) => {
+      const shown = new Set(next.map(getId));
+      const ids = [...next.map(getId), ...order.filter((id) => !shown.has(id))];
+      storage.setItem(key, JSON.stringify(ids));
+      setOrder(ids);
+    },
+    [getId, order, storage, key],
+  );
+
+  return { items: arranged.items, onChange };
+}

package/src/TreeSelect/TreeSelect.rows.spec.tsx

@@ -0,0 +1,44 @@
+/**
+ * LC-222 LIST-HEIGHT-IN-ROWS: the desktop tree panel caps its scroller at a
+ * visible-row count times its row pitch, not a pixel literal.
+ */
+import { listHeightForRows } from "@multiplatform.one/theme";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import type { TreeNode } from "../views/TreeView";
+import { TreeSelect } from "./index";
+
+afterEach(cleanup);
+
+const nodes: TreeNode[] = Array.from({ length: 12 }, (_, index) => ({
+  id: `n${index}`,
+  label: `Account ${index + 1}`,
+}));
+
+describe("TreeSelect panel height (LC-222)", () => {
+  it("states its cap as eight rows at the row pitch", async () => {
+    Object.defineProperty(window, "innerWidth", {
+      configurable: true,
+      writable: true,
+      value: 1200,
+    });
+    window.dispatchEvent(new Event("resize"));
+    const { baseElement } = renderWithProviders(<TreeSelect label="Account" nodes={nodes} open />);
+    const scroller = await waitFor(() => {
+      const found = baseElement.querySelector("[data-visible-rows]") as HTMLElement | null;
+      expect(found).toBeTruthy();
+      return found as HTMLElement;
+    });
+    const rows = Number(scroller.getAttribute("data-visible-rows"));
+    const pitch = Number(scroller.getAttribute("data-row-pitch"));
+    expect(rows).toBe(8);
+    expect(pitch).toBeGreaterThan(0);
+    const rowHeights = [...baseElement.querySelectorAll("[data-row-height]")].map((row) =>
+      Number(row.getAttribute("data-row-height")),
+    );
+    expect(new Set(rowHeights)).toEqual(new Set([pitch]));
+    const style = `${scroller.getAttribute("style") ?? ""} ${scroller.className}`;
+    expect(style).toContain(String(listHeightForRows(rows, pitch)));
+  });
+});

package/src/TreeSelect/index.tsx

@@ -26,6 +26,7 @@ import {
   ensureFocusVisibleRing,
   ensureKeyboardModalityTracking,
   keyboardFocusRingProps,
+  listHeightForRows,
   useMenuRowCheckInk,
   menuRowChecked,
   useResolvedKnobs,
@@ -617,6 +618,9 @@ function handleTreeKeys(args: {
   }
 }
 
+/** Rows the desktop tree panel shows before it scrolls (LC-222). */
+const TREE_SELECT_VISIBLE_ROWS = 8;
+
 function FloatingTreeSelect({
   nodes,
   value,
@@ -653,6 +657,7 @@ function FloatingTreeSelect({
   accessibilityLabel?: string;
 }) {
   const overlayZIndex = useOverlayZIndex("dropdown");
+  const { knobProps } = useResolvedKnobs();
   const treeId = useId();
   const searchRef = useRef<HTMLInputElement | null>(null);
   const state = useTreeSelectState({ nodes, value, open, defaultExpandedIds });
@@ -790,7 +795,13 @@ function FloatingTreeSelect({
                 activeDescendant={activeDescendant}
                 sizeToken={sizeToken}
               />
-              <YStack overflow="scroll" maxHeight={320} id={treeId}>
+              <YStack
+                overflow="scroll"
+                maxHeight={listHeightForRows(TREE_SELECT_VISIBLE_ROWS, knobProps.nestedControl.px)}
+                data-visible-rows={TREE_SELECT_VISIBLE_ROWS}
+                data-row-pitch={knobProps.nestedControl.px}
+                id={treeId}
+              >
                 <TreeSelectPanelBody
                   rows={state.rows}
                   selectedId={value}

package/src/appShell/AppShell.spec.tsx

@@ -0,0 +1,259 @@
+/**
+ * FZ-7996 (LC-175 MPO-ONLY-REUSE): one composed app frame. An app passes its
+ * destinations and the path; the shell picks the phone or the split layout,
+ * selects the destination, draws back on a pushed route and steps aside for a
+ * route that mounts its own chrome or a page that pins its own top bar.
+ */
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { HouseIcon, LightningIcon, SparkleIcon } from "@phosphor-icons/react";
+import { act, cleanup, fireEvent, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  CONTENT_MAX_WIDTH,
+  PageHeader,
+  READABLE_MAX_WIDTH,
+  Screen,
+  ScreenToolbar,
+} from "../layouts/page";
+import { ListPageLayout } from "../layouts/PageTemplates";
+import { AppShell, appShellRoute, type AppShellDestination } from "./AppShell";
+
+const size = vi.hoisted(() => ({ value: "compact" as string }));
+vi.mock("@multiplatform.one/theme", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@multiplatform.one/theme")>()),
+  useLayoutSizeClass: () => size.value,
+}));
+
+afterEach(() => {
+  cleanup();
+  size.value = "compact";
+});
+
+const destinations: AppShellDestination[] = [
+  { key: "/", label: "Home", icon: HouseIcon },
+  { key: "/pokemon", label: "Pokemon", icon: SparkleIcon },
+  { key: "/moves", label: "Moves", icon: LightningIcon, placement: "more" },
+];
+
+function shell(path: string, props: Partial<Parameters<typeof AppShell>[0]> = {}) {
+  const onNavigate = vi.fn();
+  const onBack = vi.fn();
+  const view = renderWithProviders(
+    <AppShell
+      destinations={destinations}
+      path={path}
+      onNavigate={onNavigate}
+      onBack={onBack}
+      title="multiplatform.one"
+      logo={<span data-testid="logo" />}
+      actions={<button type="button">Theme</button>}
+      ownChrome={["/desk"]}
+      {...props}
+    >
+      {props.children ?? <span data-testid="page">page</span>}
+    </AppShell>,
+  );
+  return { ...view, onNavigate, onBack };
+}
+
+describe("appShellRoute", () => {
+  it("selects the longest destination the path sits under", () => {
+    expect(appShellRoute(destinations, "/")).toMatchObject({ pushed: false });
+    expect(appShellRoute(destinations, "/").destination?.key).toBe("/");
+    expect(appShellRoute(destinations, "/pokemon").destination?.key).toBe("/pokemon");
+    expect(appShellRoute(destinations, "/pokemon/").pushed).toBe(false);
+    const detail = appShellRoute(destinations, "/pokemon/pikachu");
+    expect(detail.destination?.key).toBe("/pokemon");
+    expect(detail.pushed).toBe(true);
+  });
+
+  it("matches no destination outside them, and '/' only exactly", () => {
+    expect(appShellRoute(destinations, "/todos").destination).toBeUndefined();
+    expect(appShellRoute(destinations, "/pokemonx").destination).toBeUndefined();
+  });
+});
+
+describe("AppShell on a phone", () => {
+  it("draws the nav bar, the content and the tab bar of the tab destinations", () => {
+    shell("/pokemon");
+    expect(screen.getByTestId("app-shell").getAttribute("data-size")).toBe("compact");
+    expect(screen.getByTestId("app-shell-bar")).toBeTruthy();
+    expect(screen.getByTestId("page")).toBeTruthy();
+    const tabs = screen.getAllByRole("tab");
+    expect(tabs.map((tab) => tab.getAttribute("aria-label"))).toEqual(["Home", "Pokemon"]);
+    expect(tabs[1]!.getAttribute("aria-selected")).toBe("true");
+    expect(screen.queryByTestId("app-shell-sidebar")).toBeNull();
+  });
+
+  it("navigates from a tab", () => {
+    const { onNavigate } = shell("/pokemon");
+    fireEvent.click(screen.getAllByRole("tab")[0]!);
+    expect(onNavigate).toHaveBeenCalledWith("/");
+  });
+
+  it("puts the more destinations in the bar's pull-down", () => {
+    shell("/");
+    expect(screen.getByTestId("app-shell-more")).toBeTruthy();
+  });
+
+  it("draws the pull-down trigger as the bar's icon action, a bare accent glyph (LC-176)", () => {
+    shell("/");
+    expect(
+      screen
+        .getByTestId("app-shell-more")
+        .closest("[data-top-bar-control]")
+        ?.getAttribute("data-top-bar-control"),
+    ).toBe("action");
+  });
+
+  it("leads with the app's mark at a tab root and a tinted back on a pushed route", () => {
+    shell("/pokemon");
+    expect(screen.getByTestId("app-shell-home").getAttribute("aria-label")).toBe(
+      "multiplatform.one",
+    );
+    cleanup();
+    const { onBack } = shell("/pokemon/pikachu");
+    const back = document.querySelector("[data-top-bar-control='back']") as HTMLElement;
+    expect(back.textContent).toContain("Pokemon");
+    fireEvent.click(back);
+    expect(onBack).toHaveBeenCalledWith("/pokemon");
+    expect(screen.getAllByRole("tab")[1]!.getAttribute("aria-selected")).toBe("true");
+  });
+
+  it("shows the destination as the inline title when the page has no large title", () => {
+    shell("/pokemon");
+    const title = screen.getByTestId("app-shell-bar-title");
+    expect(title.textContent).toBe("Pokemon");
+    expect(title.getAttribute("aria-hidden")).toBe("false");
+  });
+
+  it("keeps the page's large title out of the bar until it scrolls away", () => {
+    shell("/pokemon", {
+      children: (
+        <Screen>
+          <PageHeader title="All Pokemon" />
+        </Screen>
+      ),
+    });
+    const title = screen.getByTestId("app-shell-bar-title");
+    expect(title.textContent).toBe("All Pokemon");
+    expect(title.getAttribute("aria-hidden")).toBe("true");
+  });
+
+  it("steps aside for a page that pins its own top bar", () => {
+    shell("/pokemon/pikachu", {
+      children: (
+        <Screen topBar={<ScreenToolbar leading={<span>own back</span>} />}>
+          <span>record</span>
+        </Screen>
+      ),
+    });
+    expect(screen.queryByTestId("app-shell-bar")).toBeNull();
+    expect(screen.getByText("own back")).toBeTruthy();
+    expect(screen.getAllByRole("tab")).toHaveLength(2);
+  });
+
+  it("draws no tab bar outside the tab destinations", () => {
+    shell("/todos");
+    expect(screen.queryByRole("tablist")).toBeNull();
+    expect(screen.getByTestId("app-shell-bar")).toBeTruthy();
+  });
+
+  it("hands the bottom accessory to the tab bar, which floats it above its row (LC-174)", () => {
+    shell("/pokemon", { accessory: <span data-testid="pager">pager</span> });
+    const accessory = screen.getByTestId("tab-bar-accessory");
+    expect(accessory.contains(screen.getByTestId("pager"))).toBe(true);
+    expect(screen.getByTestId("tab-bar").contains(accessory)).toBe(true);
+    const tablist = screen.getByRole("tablist");
+    expect(accessory.compareDocumentPosition(tablist) & Node.DOCUMENT_POSITION_FOLLOWING).toBe(
+      Node.DOCUMENT_POSITION_FOLLOWING,
+    );
+  });
+
+  it("still hosts the accessory on a pushed route, where no tab bar shows", () => {
+    shell("/todos", { accessory: <span data-testid="pager">pager</span> });
+    expect(screen.queryByRole("tablist")).toBeNull();
+    const frame = screen.getByTestId("app-shell-content").parentElement;
+    expect(frame?.contains(screen.getByTestId("pager"))).toBe(true);
+  });
+
+  it("draws nothing around a route that mounts its own chrome", () => {
+    shell("/desk/Pokemon");
+    expect(screen.getByTestId("app-shell").getAttribute("data-chrome")).toBe("own");
+    expect(screen.queryByTestId("app-shell-bar")).toBeNull();
+    expect(screen.queryByRole("tablist")).toBeNull();
+    expect(screen.getByTestId("page")).toBeTruthy();
+  });
+});
+
+describe("AppShell at regular width", () => {
+  it("lists every destination in the sidebar, under the app's name, and no tab bar", () => {
+    size.value = "expanded";
+    const { onNavigate } = shell("/pokemon/pikachu");
+    expect(screen.getByTestId("app-shell").getAttribute("data-size")).toBe("regular");
+    const sidebar = screen.getByTestId("app-shell-sidebar");
+    expect(sidebar.textContent).toContain("multiplatform.one");
+    const rows = sidebar.querySelectorAll("[data-sidebar-row]");
+    expect([...rows].map((row) => row.textContent)).toEqual(["Home", "Pokemon", "Moves"]);
+    expect(rows[1]!.getAttribute("aria-current")).toBe("page");
+    fireEvent.click(rows[2]!);
+    expect(onNavigate).toHaveBeenCalledWith("/moves");
+    expect(screen.queryByRole("tablist")).toBeNull();
+    expect(screen.queryByTestId("app-shell-more")).toBeNull();
+  });
+
+  it("puts the app's actions at the sidebar's foot and draws no bar on a destination root", () => {
+    size.value = "expanded";
+    shell("/pokemon");
+    const actions = screen.getByTestId("app-shell-sidebar-actions");
+    expect(actions.textContent).toContain("Theme");
+    expect(screen.getByTestId("app-shell-sidebar").contains(actions)).toBe(true);
+    expect(screen.queryByTestId("app-shell-bar")).toBeNull();
+  });
+
+  it("draws the bar with the tinted back on a pushed route, without the actions", () => {
+    size.value = "expanded";
+    const { onBack } = shell("/pokemon/pikachu");
+    const bar = screen.getByTestId("app-shell-bar");
+    expect(bar.textContent).toContain("Pokemon");
+    expect(bar.textContent).not.toContain("Theme");
+    fireEvent.click(bar.querySelector('[data-top-bar-control="back"]') as HTMLElement);
+    expect(onBack).toHaveBeenCalledWith("/pokemon");
+  });
+
+  it("centres the content in the readable column", () => {
+    size.value = "expanded";
+    shell("/pokemon");
+    const readable = screen.getByTestId("app-shell-readable");
+    expect(screen.getByTestId("app-shell-content").contains(readable)).toBe(true);
+    expect(readable.contains(screen.getByTestId("page"))).toBe(true);
+    expect(READABLE_MAX_WIDTH).toBeLessThan(CONTENT_MAX_WIDTH);
+  });
+
+  it("puts the app's name in the sidebar's pinned header", () => {
+    size.value = "expanded";
+    shell("/pokemon");
+    const header = screen
+      .getByTestId("app-shell-sidebar")
+      .querySelector("[data-sidebar-header]") as HTMLElement;
+    expect(header.textContent).toContain("multiplatform.one");
+  });
+
+  it("stacks a page's panel under the sidebar's rows (LC-101)", async () => {
+    size.value = "expanded";
+    await act(async () => {
+      shell("/pokemon", {
+        children: (
+          <ListPageLayout title="Pokemon" sidebar={<span>filters</span>} sidebarLabel="Filters">
+            <span>grid</span>
+          </ListPageLayout>
+        ),
+      });
+    });
+    const panel = screen.getByTestId("app-shell-page-panel");
+    expect(panel.textContent).toContain("Filters");
+    expect(panel.textContent).toContain("filters");
+    expect(screen.getByTestId("app-shell-sidebar").contains(panel)).toBe(true);
+    expect(screen.queryByTestId("list-page-sidebar")).toBeNull();
+  });
+});

package/src/appShell/AppShell.stories.tsx

@@ -0,0 +1,112 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import {
+  GearIcon,
+  HouseIcon,
+  LightningIcon,
+  SparkleIcon,
+  SquaresFourIcon,
+  StackIcon,
+} from "@phosphor-icons/react";
+import { useState } from "react";
+import { XStack, YStack } from "tamagui";
+import { Button } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { PageBarButton, PageHeader, PageSection, Screen } from "../layouts/page";
+import { Pagination } from "../Pagination";
+import { Text } from "../Text";
+import { AppShell, type AppShellDestination } from "./AppShell";
+
+const destinations: AppShellDestination[] = [
+  { key: "/", label: "Home", icon: HouseIcon },
+  { key: "/pokemon", label: "Pokemon", icon: SparkleIcon },
+  { key: "/moves", label: "Moves", icon: LightningIcon },
+  { key: "/backoffice", label: "Backoffice", icon: SquaresFourIcon },
+  { key: "/settings", label: "Settings", icon: GearIcon, placement: "more" },
+];
+
+function Mark() {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <YStack
+      width="$2"
+      height="$2"
+      borderRadius="$3"
+      backgroundColor="$color4"
+      alignItems="center"
+      justifyContent="center"
+    >
+      <StackIcon size={knobProps.controlIcon.width} weight="bold" />
+    </YStack>
+  );
+}
+
+function DemoPage({ path, open }: { path: string; open: (path: string) => void }) {
+  const pushed = path.split("/").filter(Boolean).length > 1;
+  const name = destinations.find((item) => path.startsWith(item.key) && item.key !== "/");
+  const title = pushed ? "Pikachu" : (name?.label ?? "Home");
+  return (
+    <Screen>
+      <PageHeader title={title} subtitle={pushed ? "#025 · Electric" : "1,025 entries"} />
+      <PageSection title="Recent">
+        {Array.from({ length: 14 }, (_, index) => (
+          <XStack key={index} alignItems="center" minHeight="$4">
+            <Text flexGrow={1}>Row {index + 1}</Text>
+            {pushed ? null : (
+              <Button
+                size="$3"
+                chromeless
+                onPress={() => open(`${path === "/" ? "" : path}/pikachu`)}
+              >
+                Open
+              </Button>
+            )}
+          </XStack>
+        ))}
+      </PageSection>
+    </Screen>
+  );
+}
+
+function Demo({ initialPath, accessory }: { initialPath: string; accessory?: boolean }) {
+  const [path, setPath] = useState(initialPath);
+  return (
+    <AppShell
+      destinations={destinations}
+      path={path}
+      onNavigate={setPath}
+      onBack={setPath}
+      title="multiplatform.one"
+      logo={<Mark />}
+      actions={<PageBarButton aria-label="Theme" icon={GearIcon} edge="end" />}
+      accessory={accessory ? <Pagination total={41} defaultPage={1} variant="dots" /> : undefined}
+      ownChrome={["/backoffice"]}
+    >
+      <DemoPage path={path} open={setPath} />
+    </AppShell>
+  );
+}
+
+/**
+ * The composed app frame (LC-175). Size class follows the viewport: below
+ * `md` the phone frame (nav bar, content, bottom accessory, tab bar), above
+ * it the split frame (sidebar of destinations beside the content column).
+ */
+const meta: Meta<typeof AppShell> = {
+  title: "Components/AppShell",
+  component: AppShell,
+  parameters: { layout: "fullscreen", status: { type: "beta" } },
+};
+
+export default meta;
+type Story = StoryObj<typeof AppShell>;
+
+/** A tab root: the mark leads, the large title sits in the page, tabs below. */
+export const TabRoot: Story = { render: () => <Demo initialPath="/pokemon" /> };
+
+/** A pushed route: tinted back to the destination, its tab still selected. */
+export const Pushed: Story = { render: () => <Demo initialPath="/pokemon/pikachu" /> };
+
+/** A page that hands the shell a bottom accessory: the tab bar floats it above itself. */
+export const WithAccessory: Story = {
+  render: () => <Demo initialPath="/pokemon" accessory />,
+};