@multiplatform.one/components 6.1.0 → 6.4.0

package/src/SheetModal/index.tsx

@@ -0,0 +1,66 @@
+/**
+ * SheetModal — modal bottom sheet presentation (web).
+ *
+ * Thin wrapper over the tamagui `Sheet modal` grammar (Overlay + Handle +
+ * SheetFrame) so catalog surfaces present the same sheet everywhere. The
+ * native twin (./index.native.tsx) swaps the tamagui Sheet for a core RN
+ * `Modal`: on device (Expo Go, tamagui 2.0.0-rc.41) the modal Sheet's
+ * portal/animation machinery never (re)presents from a trigger tap — the
+ * same upstream issue FloatingPanel's RN-Modal variant works around.
+ *
+ * Dismissal intent on web stays with the consumer (Escape wiring, LC-21):
+ * the Sheet itself only dismisses on overlay tap / snap-to-bottom.
+ */
+
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import type { ReactNode } from "react";
+import { Sheet } from "tamagui";
+import { SheetFrame } from "../surfaces";
+
+export interface SheetModalProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  children?: ReactNode;
+  /** Fixed content above the (scrollable) body, e.g. the sheet title. */
+  header?: ReactNode;
+  /** Percent snap point for the web Sheet (native sizes to content). */
+  snapPoint?: number;
+  /** Wrap children in the sheet's scroll container. */
+  scrollable?: boolean;
+}
+
+export function SheetModal({
+  open,
+  onOpenChange,
+  children,
+  header,
+  snapPoint = 60,
+  scrollable,
+}: SheetModalProps) {
+  const { knobProps } = useResolvedKnobs();
+  // LC-24: Sheet slide + overlay fade need a transition token (animation=none → undefined).
+  const transition = knobProps.transition;
+  return (
+    <Sheet
+      modal
+      open={open}
+      onOpenChange={onOpenChange}
+      dismissOnSnapToBottom
+      snapPointsMode="percent"
+      snapPoints={[snapPoint]}
+      transition={transition}
+    >
+      <Sheet.Overlay
+        backgroundColor="$shadow6"
+        transition={transition}
+        enterStyle={{ opacity: 0 }}
+        exitStyle={{ opacity: 0 }}
+      />
+      <Sheet.Handle />
+      <SheetFrame>
+        {header}
+        {scrollable ? <Sheet.ScrollView>{children}</Sheet.ScrollView> : children}
+      </SheetFrame>
+    </Sheet>
+  );
+}

package/src/Skeleton/SkeletonCircle.stories.tsx

@@ -0,0 +1,55 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { XStack, YStack } from "tamagui";
+import { SkeletonCircle } from "./index";
+
+const meta: Meta<typeof SkeletonCircle> = {
+  title: "Components/SkeletonCircle",
+  component: SkeletonCircle,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component: "Circular loading placeholder (avatar-shaped). Default diameter 40px.",
+      },
+    },
+  },
+  argTypes: {
+    size: { control: "number" },
+    animate: { control: "boolean" },
+  },
+  args: {
+    animate: true,
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof SkeletonCircle>;
+
+export const Default: Story = {
+  name: "Main",
+  render: (args) => <SkeletonCircle {...args} />,
+};
+
+export const Sizes: Story = {
+  render: (args) => (
+    <XStack gap="$4" alignItems="center">
+      {[0, 16, 24, 40, 64, 96, 200].map((size) => (
+        <SkeletonCircle key={size} {...args} size={size} />
+      ))}
+    </XStack>
+  ),
+};
+
+export const ConstrainedParent: Story = {
+  args: { size: 120 },
+  render: (args) => (
+    <YStack width={80} borderWidth={1} borderColor="$color6" borderStyle="dashed">
+      <SkeletonCircle {...args} />
+    </YStack>
+  ),
+};
+
+export const Static: Story = {
+  args: { animate: false },
+  render: (args) => <SkeletonCircle {...args} />,
+};

package/src/Skeleton/SkeletonText.stories.tsx

@@ -0,0 +1,107 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { YStack } from "tamagui";
+import { SkeletonText } from "./index";
+
+const meta: Meta<typeof SkeletonText> = {
+  title: "Components/SkeletonText",
+  component: SkeletonText,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Multi-line text loading placeholder. Last line renders at lastLineWidth (default 70%).",
+      },
+    },
+  },
+  argTypes: {
+    lines: { control: "number" },
+    gap: { control: "text" },
+    lastLineWidth: { control: "text" },
+    animate: { control: "boolean" },
+    width: { control: "text" },
+    height: { control: "text" },
+  },
+  args: {
+    lines: 3,
+    animate: true,
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof SkeletonText>;
+
+export const Default: Story = {
+  name: "Main",
+  render: (args) => (
+    <YStack maxWidth={400}>
+      <SkeletonText {...args} />
+    </YStack>
+  ),
+};
+
+export const SingleLine: Story = {
+  args: { lines: 1 },
+  render: (args) => (
+    <YStack maxWidth={400}>
+      <SkeletonText {...args} />
+    </YStack>
+  ),
+};
+
+export const ManyLines: Story = {
+  args: { lines: 12 },
+  render: (args) => (
+    <YStack maxWidth={400}>
+      <SkeletonText {...args} />
+    </YStack>
+  ),
+};
+
+export const ZeroLines: Story = {
+  args: { lines: 0 },
+  render: (args) => (
+    <YStack
+      maxWidth={400}
+      borderWidth={1}
+      borderColor="$color6"
+      borderStyle="dashed"
+      minHeight={24}
+    >
+      <SkeletonText {...args} />
+    </YStack>
+  ),
+};
+
+export const NegativeLines: Story = {
+  args: { lines: -3 },
+  render: (args) => (
+    <YStack
+      maxWidth={400}
+      borderWidth={1}
+      borderColor="$color6"
+      borderStyle="dashed"
+      minHeight={24}
+    >
+      <SkeletonText {...args} />
+    </YStack>
+  ),
+};
+
+export const CustomMetricsNarrow: Story = {
+  args: { lines: 4, gap: "$4", lastLineWidth: "40%", height: 24 },
+  render: (args) => (
+    <YStack width={220} borderWidth={1} borderColor="$color6" borderStyle="dashed">
+      <SkeletonText {...args} />
+    </YStack>
+  ),
+};
+
+export const Static: Story = {
+  args: { lines: 3, animate: false },
+  render: (args) => (
+    <YStack maxWidth={400}>
+      <SkeletonText {...args} />
+    </YStack>
+  ),
+};

package/src/SkipLink/SkipLink.spec.tsx

@@ -0,0 +1,45 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { fireEvent } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { SkipLink } from "./index";
+
+function renderWithTarget() {
+  return renderWithProviders(
+    <div>
+      <SkipLink targetId="main-content">Skip to content</SkipLink>
+      <div id="main-content">Main</div>
+    </div>,
+  );
+}
+
+describe("SkipLink", () => {
+  it("renders an anchor pointing at the target id", () => {
+    const { container } = renderWithTarget();
+    const anchor = container.querySelector('a[href="#main-content"]');
+    expect(anchor).toBeTruthy();
+    expect(anchor?.textContent).toContain("Skip to content");
+  });
+
+  it("moves focus to the target on activation", () => {
+    const { container } = renderWithTarget();
+    const anchor = container.querySelector('a[href="#main-content"]') as HTMLElement;
+    fireEvent.click(anchor);
+    const target = document.getElementById("main-content") as HTMLElement;
+    expect(target.getAttribute("tabindex")).toBe("-1");
+    expect(document.activeElement).toBe(target);
+  });
+
+  it("reports the focused target through onSkip", () => {
+    const onSkip = vi.fn();
+    const { container } = renderWithProviders(
+      <div>
+        <SkipLink targetId="content-x" onSkip={onSkip}>
+          Skip
+        </SkipLink>
+        <div id="content-x">X</div>
+      </div>,
+    );
+    fireEvent.click(container.querySelector('a[href="#content-x"]') as HTMLElement);
+    expect(onSkip).toHaveBeenCalledWith(document.getElementById("content-x"));
+  });
+});

package/src/SkipLink/SkipLink.stories.tsx

@@ -0,0 +1,89 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Button, Input } from "@multiplatform.one/forms";
+import { SizableText, XStack, YStack, View } from "tamagui";
+import { SkipLink } from "./index";
+
+const meta: Meta<typeof SkipLink> = {
+  title: "Components/SkipLink",
+  component: SkipLink,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Keyboard-only 'Skip to content' link: visually hidden until it receives focus (first Tab on the page), then revealed fixed top-left on a themed elevated surface. Activating it (Enter) moves focus and scroll to the target element. Intended consumer: DeskShell, rendered as the first child so Tab #1 lets keyboard users jump past the sidebar/toolbar straight to the form.",
+      },
+    },
+  },
+  argTypes: {
+    targetId: { control: "text", description: "id of the element to jump to" },
+    children: { control: "text", description: "Link label" },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof SkipLink>;
+
+/** Press Tab once — the link appears top-left. Press Enter — focus jumps
+ * past the fake toolbar/sidebar into the main content region. */
+export const Default: Story = {
+  name: "Main",
+  args: { targetId: "story-main-content", children: "Skip to content" },
+  render: (args) => (
+    <YStack gap="$4" maxWidth={720}>
+      <SkipLink {...args} />
+      <SizableText color="$color11" fontSize="$3">
+        Click the canvas, then press Tab: the skip link appears top-left. Enter jumps focus past the
+        chrome below into the main region.
+      </SizableText>
+      <XStack gap="$2" alignItems="center" flexWrap="wrap">
+        <Button compact>File</Button>
+        <Button compact>Edit</Button>
+        <Button compact>View</Button>
+        <Button compact>Workspace</Button>
+        <Button compact>Help</Button>
+      </XStack>
+      <XStack gap="$4">
+        <YStack gap="$2" width={160}>
+          <Button compact outlined>
+            Inbox
+          </Button>
+          <Button compact outlined>
+            Projects
+          </Button>
+          <Button compact outlined>
+            Reports
+          </Button>
+        </YStack>
+        <View flexGrow={1} id="story-main-content" role="main" aria-label="Main content">
+          <YStack gap="$3">
+            <SizableText fontWeight="600" fontSize="$5">
+              New Contact
+            </SizableText>
+            <Input label="Full name" placeholder="Ada Lovelace" />
+            <Input label="Email" placeholder="ada@example.com" />
+            <XStack>
+              <Button accent>Save</Button>
+            </XStack>
+          </YStack>
+        </View>
+      </XStack>
+    </YStack>
+  ),
+};
+
+export const CustomLabel: Story = {
+  render: () => (
+    <YStack gap="$4" maxWidth={720}>
+      <SkipLink targetId="story-form-region">Skip to form</SkipLink>
+      <SizableText color="$color11" fontSize="$3">
+        The label is any text; Tab once to reveal it.
+      </SizableText>
+      <View id="story-form-region">
+        <YStack gap="$3">
+          <Input label="Search" placeholder="Type to filter…" />
+        </YStack>
+      </View>
+    </YStack>
+  ),
+};

package/src/SkipLink/index.tsx

@@ -0,0 +1,147 @@
+import { useState, type CSSProperties, type ReactNode, type RefObject } from "react";
+import { zIndex } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import type { GetProps } from "tamagui";
+import { SizableText, YStack, isWeb, styled, useTheme } from "tamagui";
+
+// ── Types ─────────────────────────────────────────────────────
+
+export interface SkipLinkProps {
+  /** id of the element to jump to (rendered as href="#<targetId>"). */
+  targetId?: string;
+  /** Alternative to targetId: a ref whose current element receives focus. */
+  targetRef?: RefObject<HTMLElement | { focus?: () => void } | null>;
+  /** Link label (default "Skip to content"). */
+  children?: ReactNode;
+  /** Called after focus has been moved to the target. */
+  onSkip?: (target: HTMLElement | null) => void;
+}
+
+// ── Styled components ─────────────────────────────────────────
+
+// Themed chip surface shown once the link has focus: elevated overlay tier.
+const SkipLinkSurface = styled(YStack, {
+  name: "SkipLink",
+  paddingVertical: "$2.5",
+  paddingHorizontal: "$3.5",
+});
+
+// The standard visually-hidden-but-focusable recipe on a REAL anchor element
+// (react-native-web keeps `tag` as an attribute, so a genuine <a> is the only
+// way to get native link semantics + free Enter activation).
+const hiddenStyle: CSSProperties = {
+  position: "absolute",
+  top: 0,
+  insetInlineStart: 0,
+  width: 1,
+  height: 1,
+  margin: -1,
+  padding: 0,
+  overflow: "hidden",
+  clip: "rect(0 0 0 0)",
+  whiteSpace: "nowrap",
+  border: 0,
+  // Sheet tier (Axiom 14): the revealed chip must sit above page content
+  // and sticky chrome when the first Tab lands on it.
+  zIndex: zIndex.sheet,
+  textDecoration: "none",
+};
+
+const revealedStyle: CSSProperties = {
+  position: "fixed",
+  top: 12,
+  insetInlineStart: 12,
+  width: "auto",
+  height: "auto",
+  margin: 0,
+  padding: 0,
+  overflow: "visible",
+  clip: "auto",
+  zIndex: zIndex.sheet,
+  textDecoration: "none",
+};
+
+// ── SkipLink Component ────────────────────────────────────────
+
+/**
+ * "Skip to content" link for keyboard users: invisible until it receives
+ * focus (first Tab on the page), then revealed fixed top-start on a themed
+ * elevated surface. Activating it (Enter/click) moves focus and scroll to
+ * the target element.
+ *
+ * Renders nothing on native — there is no Tab-order to skip.
+ */
+export function SkipLink({
+  targetId,
+  targetRef,
+  children = "Skip to content",
+  onSkip,
+}: SkipLinkProps) {
+  const { knobProps } = useResolvedKnobs({ component: "SkipLink" });
+  const theme = useTheme();
+  const [focused, setFocused] = useState(false);
+  if (!isWeb) return null;
+
+  const handleActivate = (event: { preventDefault?: () => void }) => {
+    event?.preventDefault?.();
+    let target: HTMLElement | null = null;
+    if (targetRef?.current) {
+      const current = targetRef.current;
+      if (typeof (current as { focus?: () => void }).focus === "function") {
+        target = current as HTMLElement;
+      }
+    } else if (targetId && typeof document !== "undefined") {
+      target = document.getElementById(targetId);
+    }
+    if (target) {
+      // Containers aren't focusable by default; make this one a valid
+      // programmatic focus target without adding it to the Tab order.
+      if (target instanceof HTMLElement && !target.hasAttribute("tabindex")) {
+        target.setAttribute("tabindex", "-1");
+      }
+      target.focus?.();
+      if (target instanceof HTMLElement) {
+        target.scrollIntoView?.({ block: "start" });
+      }
+    }
+    onSkip?.(target instanceof HTMLElement ? target : null);
+  };
+
+  return (
+    <a
+      href={targetId ? `#${targetId}` : "#"}
+      style={{
+        ...(focused ? revealedStyle : hiddenStyle),
+        // Focus ring on the revealed chip: the theme's $outlineColor token
+        // (DG-A11Y-01, ≥3:1 vs page surfaces). The previous color8 measured
+        // 1.89:1 on the light page — an invisible ring on the one control
+        // whose entire job is keyboard visibility.
+        outline: focused
+          ? `2px solid ${theme.outlineColor?.get() ?? theme.color8?.get() ?? "currentColor"}`
+          : "none",
+        outlineOffset: 2,
+      }}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      onClick={handleActivate}
+    >
+      <SkipLinkSurface
+        {...knobProps.elevatedSurface}
+        borderWidth={Math.max(knobProps.elevatedSurface.borderWidth, 1)}
+        elevation={knobProps.elevatedSurface.elevation ?? "$2"}
+      >
+        <SizableText
+          {...knobProps.body}
+          fontWeight="600"
+          fontSize="$3"
+          color="$color12"
+          whiteSpace="nowrap"
+        >
+          {children}
+        </SizableText>
+      </SkipLinkSurface>
+    </a>
+  );
+}
+
+export type SkipLinkSurfaceProps = GetProps<typeof SkipLinkSurface>;

package/src/Tabs/Tabs.spec.tsx

@@ -0,0 +1,70 @@
+import { fireEvent, screen } from "@testing-library/react";
+import { Text } from "tamagui";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { describe, expect, it, vitest } from "vitest";
+import { Tabs, type TabsItem } from "./index";
+
+const items: TabsItem[] = [
+  { value: "one", label: "One", content: <Text>Panel one</Text> },
+  { value: "two", label: "Two", content: <Text>Panel two</Text> },
+  { value: "three", label: "Three", disabled: true, content: <Text>Panel three</Text> },
+];
+
+describe("Tabs", () => {
+  it("renders a tablist with aria-selected on the active tab", () => {
+    renderWithProviders(<Tabs items={items} />);
+    expect(screen.getByRole("tablist")).toBeInTheDocument();
+    const tabs = screen.getAllByRole("tab");
+    expect(tabs).toHaveLength(3);
+    expect(tabs[0]).toHaveAttribute("aria-selected", "true");
+    expect(tabs[1]).toHaveAttribute("aria-selected", "false");
+    expect(screen.getByText("Panel one")).toBeInTheDocument();
+    expect(screen.queryByText("Panel two")).not.toBeInTheDocument();
+  });
+
+  it("switches panels on click and calls onChange (uncontrolled)", () => {
+    const onChange = vitest.fn();
+    renderWithProviders(<Tabs items={items} onChange={onChange} />);
+    fireEvent.click(screen.getByText("Two"));
+    expect(onChange).toHaveBeenCalledWith("two");
+    expect(screen.getByText("Panel two")).toBeInTheDocument();
+    expect(screen.queryByText("Panel one")).not.toBeInTheDocument();
+    const tabs = screen.getAllByRole("tab");
+    expect(tabs[1]).toHaveAttribute("aria-selected", "true");
+  });
+
+  it("respects defaultValue", () => {
+    renderWithProviders(<Tabs items={items} defaultValue="two" />);
+    expect(screen.getByText("Panel two")).toBeInTheDocument();
+  });
+
+  it("stays controlled: value wins and does not change on its own", () => {
+    const onChange = vitest.fn();
+    renderWithProviders(<Tabs items={items} value="one" onChange={onChange} />);
+    fireEvent.click(screen.getByText("Two"));
+    expect(onChange).toHaveBeenCalledWith("two");
+    // still on panel one because the parent did not update `value`
+    expect(screen.getByText("Panel one")).toBeInTheDocument();
+    expect(screen.queryByText("Panel two")).not.toBeInTheDocument();
+  });
+
+  it("does not activate a disabled tab", () => {
+    const onChange = vitest.fn();
+    renderWithProviders(<Tabs items={items} onChange={onChange} />);
+    fireEvent.click(screen.getByText("Three"));
+    expect(onChange).not.toHaveBeenCalled();
+    expect(screen.getByText("Panel one")).toBeInTheDocument();
+  });
+
+  it("lazyMount keeps a visited panel mounted after switching away", () => {
+    renderWithProviders(<Tabs items={items} lazyMount />);
+    // panel two not mounted yet
+    expect(screen.queryByText("Panel two")).not.toBeInTheDocument();
+    fireEvent.click(screen.getByText("Two"));
+    expect(screen.getByText("Panel two")).toBeInTheDocument();
+    fireEvent.click(screen.getByText("One"));
+    // panel two stays in the DOM (hidden) once visited
+    expect(screen.getByText("Panel two")).toBeInTheDocument();
+    expect(screen.getByText("Panel one")).toBeInTheDocument();
+  });
+});