@multiplatform.one/components 6.0.4 → 6.3.0

package/src/Pagination.tsx

@@ -1,56 +1,302 @@
 import { useResolvedKnobs } from "@multiplatform.one/theme";
-import { ArrowLeftIcon, ArrowRightIcon, CheckIcon } from "@phosphor-icons/react";
-import { useCallback } from "react";
+import {
+  ArrowLeftIcon,
+  ArrowRightIcon,
+  CaretDoubleLeftIcon,
+  CaretDoubleRightIcon,
+  CaretLeftIcon,
+  CaretRightIcon,
+  CheckIcon,
+} from "@phosphor-icons/react";
+import type React from "react";
+import { useCallback, useState } from "react";
+import { useTranslation } from "react-i18next";
 import { Button } from "@multiplatform.one/forms";
-import { View, XStack, type XStackProps } from "tamagui";
+import { Text, View, XStack, type XStackProps } from "tamagui";
 import { componentColors } from "./componentColors";
+import { useDirection } from "./hooks/useDirection";
+import { bidiIsolate, withInterp } from "./shared/t";
+
+export type PaginationItem = number | "ellipsis-start" | "ellipsis-end";
+
+const range = (start: number, end: number) =>
+  Array.from({ length: Math.max(end - start + 1, 0) }, (_, i) => start + i);
+
+/**
+ * Ellipsis windowing for the numbered variant: always show the boundary
+ * pages, the current page and its siblings, and collapse the gaps into
+ * ellipses — e.g. total=20, page=5 → [1, …, 4, 5, 6, …, 20].
+ */
+export function getPaginationItems(
+  total: number,
+  page: number,
+  siblingCount = 1,
+  boundaryCount = 1,
+): PaginationItem[] {
+  if (total <= 0) return [];
+  const startPages = range(1, Math.min(boundaryCount, total));
+  const endPages = range(Math.max(total - boundaryCount + 1, boundaryCount + 1), total);
+
+  const siblingsStart = Math.max(
+    Math.min(page - siblingCount, total - boundaryCount - siblingCount * 2 - 1),
+    boundaryCount + 2,
+  );
+  const siblingsEnd = Math.min(
+    Math.max(page + siblingCount, boundaryCount + siblingCount * 2 + 2),
+    endPages.length > 0 ? endPages[0] - 2 : total - 1,
+  );
+
+  const items: PaginationItem[] = [...startPages];
+  if (siblingsStart > boundaryCount + 2) {
+    items.push("ellipsis-start");
+  } else if (boundaryCount + 1 < total - boundaryCount) {
+    items.push(boundaryCount + 1);
+  }
+  items.push(...range(siblingsStart, siblingsEnd));
+  if (siblingsEnd < total - boundaryCount - 1) {
+    items.push("ellipsis-end");
+  } else if (total - boundaryCount > boundaryCount) {
+    items.push(total - boundaryCount);
+  }
+  items.push(...endPages);
+  return items;
+}
 
 export interface PaginationProps extends Omit<XStackProps, "children" | "onChange"> {
   /** Total number of pages/steps */
   total: number;
-  /** Current active index (0-based) */
-  activeIndex: number;
-  /** Called when the user requests a page change */
-  onChange: (index: number) => void;
-  /** Set of completed step indices (shows checkmarks) */
+  /** Current active index (0-based, controlled). Prefer `page` for the numbered variant. */
+  activeIndex?: number;
+  /** Called with the new 0-based index when the user requests a page change */
+  onChange?: (index: number) => void;
+  /** Current page (1-based, controlled). Equivalent to `activeIndex + 1`. */
+  page?: number;
+  /** Initial page (1-based) when uncontrolled */
+  defaultPage?: number;
+  /** Called with the new 1-based page when the user requests a page change */
+  onPageChange?: (page: number) => void;
+  /** Set of completed step indices (shows checkmarks, dots variant) */
   completedSteps?: Set<number>;
-  /** Whether clicking a dot navigates directly to that step */
+  /** Whether clicking a dot navigates directly to that step (dots variant) */
   allowJumpTo?: boolean;
-  /** Whether the last step triggers onSubmit instead of onChange */
+  /** Whether the last step triggers onSubmit instead of onChange (dots variant) */
   isLastStep?: boolean;
-  /** Called when submit is triggered on the last step */
+  /** Called when submit is triggered on the last step (dots variant) */
   onSubmit?: () => void;
   /** Disable all navigation */
   disabled?: boolean;
-  /** Visual variant */
-  variant?: "dots" | "bars";
+  /** Visual variant: dots/bars = carousel & wizard idiom, numbered = table & data idiom */
+  variant?: "dots" | "bars" | "numbered";
+  /** Total number of items across all pages (numbered summary slot) */
+  totalItems?: number;
+  /** Items per page (numbered summary slot) */
+  pageSize?: number;
+  /** Show the "1–25 of 312" summary. Requires totalItems + pageSize. */
+  showSummary?: boolean;
+  /** Pages shown either side of the current page before collapsing to an ellipsis */
+  siblingCount?: number;
+  /** Pages always shown at the start and end */
+  boundaryCount?: number;
+  /** Show first/last double-chevron buttons (numbered variant) */
+  showFirstLast?: boolean;
 }
 
 export function Pagination({
   total,
   activeIndex,
   onChange,
+  page,
+  defaultPage,
+  onPageChange,
   completedSteps,
   allowJumpTo = false,
   isLastStep = false,
   onSubmit,
   disabled = false,
   variant = "dots",
+  totalItems,
+  pageSize,
+  showSummary = false,
+  siblingCount = 1,
+  boundaryCount = 1,
+  showFirstLast = false,
   ...stackProps
 }: PaginationProps) {
+  const { t } = useTranslation();
   const { knobProps } = useResolvedKnobs();
+  // LC-25: discrete page jumps tween indicator geometry/color; no continuous drag here.
+  const motionTransition = (knobProps.transition as string | undefined) || "quick";
+
+  // Directional glyphs encode direction-of-travel (Axiom 15), so they must
+  // point toward their targets in RTL too. Mechanism: swap the paired glyph
+  // (CaretLeft ⇄ CaretRight) keyed on useDirection() — pixel-exact for the
+  // symmetric caret/arrow pairs and portable to native, unlike a scaleX(-1)
+  // transform. The checkmark is direction-neutral and never mirrors.
+  const isRTL = useDirection() === "rtl";
+  const PrevIcon = isRTL ? CaretRightIcon : CaretLeftIcon;
+  const NextIcon = isRTL ? CaretLeftIcon : CaretRightIcon;
+  const FirstIcon = isRTL ? CaretDoubleRightIcon : CaretDoubleLeftIcon;
+  const LastIcon = isRTL ? CaretDoubleLeftIcon : CaretDoubleRightIcon;
+  const PrevArrowIcon = isRTL ? ArrowRightIcon : ArrowLeftIcon;
+  const NextArrowIcon = isRTL ? ArrowLeftIcon : ArrowRightIcon;
+
+  // Controlled via `page` (1-based) or `activeIndex` (0-based); uncontrolled otherwise.
+  const [uncontrolledPage, setUncontrolledPage] = useState(defaultPage ?? 1);
+  const controlledIndex = page != null ? page - 1 : activeIndex;
+  const index = controlledIndex ?? uncontrolledPage - 1;
+  const currentPage = index + 1;
+
+  const goTo = useCallback(
+    (nextIndex: number) => {
+      const clamped = Math.max(0, Math.min(nextIndex, total - 1));
+      if (controlledIndex == null) setUncontrolledPage(clamped + 1);
+      onChange?.(clamped);
+      onPageChange?.(clamped + 1);
+    },
+    [controlledIndex, total, onChange, onPageChange],
+  );
 
   const handlePrev = useCallback(() => {
-    if (activeIndex > 0) onChange(activeIndex - 1);
-  }, [activeIndex, onChange]);
+    if (index > 0) goTo(index - 1);
+  }, [index, goTo]);
 
   const handleNext = useCallback(() => {
     if (isLastStep && onSubmit) {
       onSubmit();
-    } else if (activeIndex < total - 1) {
-      onChange(activeIndex + 1);
+    } else if (index < total - 1) {
+      goTo(index + 1);
     }
-  }, [activeIndex, total, isLastStep, onSubmit, onChange]);
+  }, [index, total, isLastStep, onSubmit, goTo]);
+
+  const activateOnEnterSpace = (fn: () => void, enabled: boolean) =>
+    ((e: React.KeyboardEvent) => {
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        if (enabled) fn();
+      }
+    }) as unknown as () => void;
+
+  if (variant === "numbered") {
+    const items = getPaginationItems(total, currentPage, siblingCount, boundaryCount);
+    const canPrev = !disabled && currentPage > 1;
+    const canNext = !disabled && currentPage < total;
+    // Bidi-isolate the whole formatted range so an RTL paragraph can't
+    // reorder the latin/numeric runs ("1–5 of 5" ⇏ "of 5 5–1").
+    const summary =
+      showSummary && totalItems != null && pageSize != null
+        ? bidiIsolate(
+            totalItems === 0
+              ? t("0 of 0")
+              : withInterp(t("{{start}}–{{end}} of {{total}}"), {
+                  start: (currentPage - 1) * pageSize + 1,
+                  end: Math.min(currentPage * pageSize, totalItems),
+                  total: totalItems,
+                }),
+          )
+        : undefined;
+
+    return (
+      <XStack
+        alignItems="center"
+        justifyContent="center"
+        role="navigation"
+        aria-label={t("Pagination")}
+        {...knobProps.gap}
+        {...stackProps}
+      >
+        {showFirstLast && (
+          <Button
+            size={knobProps.sizeToken}
+            variant="outlined"
+            icon={FirstIcon}
+            onPress={() => goTo(0)}
+            disabled={!canPrev}
+            aria-label={t("Go to first page")}
+            onKeyDown={activateOnEnterSpace(() => goTo(0), canPrev)}
+          />
+        )}
+        <Button
+          size={knobProps.sizeToken}
+          variant="outlined"
+          icon={PrevIcon}
+          onPress={handlePrev}
+          disabled={!canPrev}
+          aria-label={t("Go to previous page")}
+          onKeyDown={activateOnEnterSpace(handlePrev, canPrev)}
+        />
+
+        <XStack alignItems="center" gap="$1">
+          {items.map((item) => {
+            if (typeof item !== "number") {
+              return (
+                <Text
+                  key={item}
+                  aria-hidden
+                  userSelect="none"
+                  textAlign="center"
+                  minWidth="$2"
+                  {...knobProps.body}
+                  color={componentColors.text.muted}
+                >
+                  …
+                </Text>
+              );
+            }
+            const isCurrent = item === currentPage;
+            return (
+              <Button
+                key={item}
+                size={knobProps.sizeToken}
+                minWidth={knobProps.sizeToken}
+                paddingHorizontal="$2"
+                accent={isCurrent}
+                chromeless={!isCurrent}
+                disabled={disabled}
+                onPress={() => goTo(item - 1)}
+                aria-label={withInterp(t("Page {{number}}"), { number: item })}
+                aria-current={isCurrent ? "page" : undefined}
+                onKeyDown={activateOnEnterSpace(() => goTo(item - 1), !disabled)}
+              >
+                {String(item)}
+              </Button>
+            );
+          })}
+        </XStack>
+
+        <Button
+          size={knobProps.sizeToken}
+          variant="outlined"
+          icon={NextIcon}
+          onPress={handleNext}
+          disabled={!canNext}
+          aria-label={t("Go to next page")}
+          onKeyDown={activateOnEnterSpace(handleNext, canNext)}
+        />
+        {showFirstLast && (
+          <Button
+            size={knobProps.sizeToken}
+            variant="outlined"
+            icon={LastIcon}
+            onPress={() => goTo(total - 1)}
+            disabled={!canNext}
+            aria-label={t("Go to last page")}
+            onKeyDown={activateOnEnterSpace(() => goTo(total - 1), canNext)}
+          />
+        )}
+
+        {summary && (
+          <Text
+            {...knobProps.body}
+            color={componentColors.text.muted}
+            aria-live="polite"
+            userSelect="none"
+          >
+            {summary}
+          </Text>
+        )}
+      </XStack>
+    );
+  }
 
   const dotSize = variant === "bars" ? "$1.5" : "$0.75";
   const activeDotSize = variant === "bars" ? "$3" : "$2";
@@ -60,11 +306,14 @@ export function Pagination({
       <Button
         size={knobProps.sizeToken}
         circular
-        icon={ArrowLeftIcon}
+        icon={PrevArrowIcon}
         onPress={handlePrev}
-        disabled={disabled || activeIndex === 0}
+        disabled={disabled || index === 0}
         variant="outlined"
-        opacity={activeIndex === 0 ? 0.3 : 1}
+        // LC-40: the Button's own disabled wash owns the treatment — the
+        // legacy opacity 0.3 dim stacked on top of it (double-dim).
+        aria-label={t("Previous page")}
+        onKeyDown={activateOnEnterSpace(handlePrev, !(disabled || index === 0))}
       />
 
       <XStack
@@ -76,9 +325,9 @@ export function Pagination({
         height={knobProps.sizeToken}
         borderRadius="$10"
       >
-        {Array.from({ length: total }).map((_, index) => {
-          const isActive = index === activeIndex;
-          const isCompleted = completedSteps?.has(index);
+        {Array.from({ length: total }).map((_, dotIndex) => {
+          const isActive = dotIndex === index;
+          const isCompleted = completedSteps?.has(dotIndex);
           const canJump = allowJumpTo && !disabled;
 
           const dotProps: any = {
@@ -91,15 +340,41 @@ export function Pagination({
                 : isActive
                   ? componentColors.indicator.current
                   : componentColors.indicator.track,
-            animation: "quick",
+            transition: motionTransition,
             cursor: canJump ? "pointer" : undefined,
             alignItems: "center",
             justifyContent: "center",
-            ...(canJump ? { onPress: () => onChange(index) } : {}),
+            "aria-current": isActive ? "step" : undefined,
+            "data-pagination-dot": isActive ? "active" : "idle",
+            // Belt-and-suspenders for the CSS driver: named `transition` covers
+            // Tamagui layout props; explicit width/bg ensures measurable intermediates.
+            style: {
+              transition: `width var(--mp-transition, 100ms) ease, height var(--mp-transition, 100ms) ease, background-color var(--mp-transition, 100ms) ease`,
+            },
+            ...(canJump
+              ? {
+                  onPress: () => goTo(dotIndex),
+                  role: "button",
+                  "aria-label": withInterp(t("Go to step {{number}}"), { number: dotIndex + 1 }),
+                  tabIndex: 0,
+                  focusVisibleStyle: {
+                    outlineColor: "$outlineColor",
+                    outlineWidth: 2,
+                    outlineStyle: "solid",
+                    outlineOffset: 1,
+                  },
+                  onKeyDown: (e: React.KeyboardEvent) => {
+                    if (e.key === "Enter" || e.key === " ") {
+                      e.preventDefault();
+                      goTo(dotIndex);
+                    }
+                  },
+                }
+              : {}),
           };
 
           return (
-            <View key={index} {...dotProps}>
+            <View key={dotIndex} {...dotProps}>
               {isCompleted && !isActive && variant === "dots" && (
                 <CheckIcon size={8} color="white" weight="bold" />
               )}
@@ -111,11 +386,16 @@ export function Pagination({
       <Button
         size={knobProps.sizeToken}
         circular
-        icon={isLastStep ? CheckIcon : ArrowRightIcon}
+        icon={isLastStep ? CheckIcon : NextArrowIcon}
         onPress={handleNext}
-        disabled={disabled || (!isLastStep && activeIndex >= total - 1 && !onSubmit)}
+        disabled={disabled || (!isLastStep && index >= total - 1 && !onSubmit)}
         variant={isLastStep ? undefined : "outlined"}
         theme={isLastStep ? "active" : undefined}
+        aria-label={isLastStep ? t("Submit") : t("Next page")}
+        onKeyDown={activateOnEnterSpace(
+          handleNext,
+          !(disabled || (!isLastStep && index >= total - 1 && !onSubmit)),
+        )}
       />
     </XStack>
   );

package/src/Panel.stories.tsx

@@ -0,0 +1,72 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+// Catalog Button (G-15 story honesty / LC-18, UX-P06).
+import { Button } from "@multiplatform.one/forms";
+import { Input, Paragraph, SizableText, XStack, YStack } from "tamagui";
+import { Panel } from "./surfaces";
+
+const meta: Meta<typeof Panel> = {
+  title: "Components/Panel",
+  component: Panel,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Generic knob-aware container: surface + borderRadius + elevation + panelPadding + gap applied to a plain View.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Panel>;
+
+export const Default: Story = {
+  name: "Main",
+  render: () => (
+    <Panel maxWidth={420}>
+      <SizableText fontWeight="600">Panel title</SizableText>
+      <Paragraph>Generic knob-aware panel content.</Paragraph>
+    </Panel>
+  ),
+};
+
+export const Empty: Story = {
+  render: () => <Panel width={220} height={80} />,
+};
+
+export const Nested: Story = {
+  render: () => (
+    <Panel maxWidth={480}>
+      <SizableText fontWeight="600">Outer panel</SizableText>
+      <Panel>
+        <Paragraph>Inner nested panel — single border/radius each, no doubling.</Paragraph>
+      </Panel>
+    </Panel>
+  ),
+};
+
+export const InteractiveContent: Story = {
+  render: () => (
+    <Panel maxWidth={420}>
+      <SizableText fontWeight="600">Interactive content</SizableText>
+      <Input placeholder="Focus me" />
+      <XStack gap="$2">
+        <Button variant="outlined">Cancel</Button>
+        <Button>Submit</Button>
+      </XStack>
+    </Panel>
+  ),
+};
+
+export const Overflow: Story = {
+  render: () => (
+    <YStack maxWidth={300}>
+      <Panel maxHeight={160} overflow="hidden">
+        {Array.from({ length: 12 }).map((_, i) => (
+          <Paragraph key={i}>Overflowing panel line {i + 1}.</Paragraph>
+        ))}
+      </Panel>
+    </YStack>
+  ),
+};

package/src/PopoverContent.stories.tsx

@@ -0,0 +1,67 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useState } from "react";
+// Catalog Button (G-15 story honesty / LC-18, UX-P06).
+import { Button } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { Paragraph, Popover, SizableText, YStack } from "tamagui";
+import { PopoverContent } from "./surfaces";
+
+function PopoverHarness({
+  placement = "bottom" as const,
+  startOpen = true,
+}: {
+  placement?: "bottom" | "top" | "right" | "left";
+  startOpen?: boolean;
+}) {
+  // PopoverContent's contract leaves the inset to the caller (flush menus —
+  // LC-01 — pass none); the demo caller pad rides the space knob (LC-18).
+  const { knobProps } = useResolvedKnobs();
+  const [open, setOpen] = useState(startOpen);
+  return (
+    <YStack minHeight={320} alignItems="center" justifyContent="center">
+      <Popover open={open} onOpenChange={setOpen} placement={placement}>
+        <Popover.Trigger asChild>
+          <Button>Toggle popover</Button>
+        </Popover.Trigger>
+        <PopoverContent maxWidth={300}>
+          <YStack {...knobProps.gap} {...knobProps.panelPadding}>
+            <SizableText fontWeight="600">Popover title</SizableText>
+            <Paragraph>
+              Elevated overlay surface driven by the elevatedSurface knob recipe.
+            </Paragraph>
+          </YStack>
+        </PopoverContent>
+      </Popover>
+    </YStack>
+  );
+}
+
+const meta: Meta<typeof PopoverContent> = {
+  title: "Components/PopoverContent",
+  component: PopoverContent,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Popover.Content wrapper applying the elevatedSurface knob recipe (background, border, radius, elevation).",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof PopoverContent>;
+
+export const Default: Story = {
+  name: "Main",
+  render: () => <PopoverHarness />,
+};
+
+export const PlacementTop: Story = {
+  render: () => <PopoverHarness placement="top" />,
+};
+
+export const Closed: Story = {
+  render: () => <PopoverHarness startOpen={false} />,
+};

package/src/ProgressSteps/ProgressSteps.spec.tsx

@@ -0,0 +1,31 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { fireEvent } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { ProgressSteps } from "./index";
+
+const steps = [{ label: "One" }, { label: "Two" }, { label: "Three" }];
+
+describe("ProgressSteps", () => {
+  it("marks the current step with aria-current=step", () => {
+    const { container } = renderWithProviders(<ProgressSteps steps={steps} current={1} />);
+    const current = container.querySelector('[aria-current="step"]');
+    expect(current).toBeTruthy();
+    expect(container.textContent).toContain("Two");
+  });
+
+  it("calls onStepChange when jumping to another step", () => {
+    const onStepChange = vi.fn();
+    const { container } = renderWithProviders(
+      <ProgressSteps steps={steps} current={0} onStepChange={onStepChange} />,
+    );
+    const jump = container.querySelector('[aria-label="Go to step 2: Two"]');
+    expect(jump).toBeTruthy();
+    fireEvent.click(jump as Element);
+    expect(onStepChange).toHaveBeenCalledWith(1);
+  });
+
+  it("does not expose jump buttons without onStepChange", () => {
+    const { container } = renderWithProviders(<ProgressSteps steps={steps} current={0} />);
+    expect(container.querySelector('[aria-label="Go to step 2: Two"]')).toBeFalsy();
+  });
+});

package/src/ProgressSteps/ProgressSteps.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useState } from "react";
+import { Button } from "@multiplatform.one/forms";
+import { XStack, YStack } from "tamagui";
+import { ProgressSteps } from "./index";
+
+const meta: Meta<typeof ProgressSteps> = {
+  title: "Components/ProgressSteps",
+  component: ProgressSteps,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Multi-step wizard / progress indicator. Distinct from forms Progress (bar) and forms Stepper (quantity). Timeline covers chronological history.",
+      },
+    },
+  },
+  argTypes: {
+    current: { control: { type: "number", min: 0, max: 4 } },
+    orientation: { control: "select", options: ["horizontal", "vertical"] },
+    compact: { control: "boolean" },
+    allowJump: { control: "boolean" },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof ProgressSteps>;
+
+const demoSteps = [
+  { id: "account", label: "Account", description: "Email & password" },
+  { id: "profile", label: "Profile", description: "Name & avatar" },
+  { id: "team", label: "Team", description: "Invite coworkers" },
+  { id: "done", label: "Done", description: "Review & finish" },
+];
+
+export const Default: Story = {
+  name: "Main",
+  args: {
+    steps: demoSteps,
+    current: 1,
+  },
+};
+
+export const Interactive: Story = {
+  render: () => {
+    const [current, setCurrent] = useState(0);
+    return (
+      <YStack gap="$4" maxWidth={720}>
+        <ProgressSteps steps={demoSteps} current={current} onStepChange={setCurrent} />
+        <XStack gap="$2">
+          <Button
+            compact
+            disabled={current === 0}
+            onPress={() => setCurrent((c) => Math.max(0, c - 1))}
+          >
+            Back
+          </Button>
+          <Button
+            compact
+            accent
+            disabled={current >= demoSteps.length - 1}
+            onPress={() => setCurrent((c) => Math.min(demoSteps.length - 1, c + 1))}
+          >
+            Next
+          </Button>
+        </XStack>
+      </YStack>
+    );
+  },
+};
+
+export const Vertical: Story = {
+  args: {
+    steps: demoSteps,
+    current: 2,
+    orientation: "vertical",
+  },
+};
+
+export const Compact: Story = {
+  args: {
+    steps: demoSteps.map(({ id, label }) => ({ id, label })),
+    current: 0,
+    compact: true,
+  },
+};