@multiplatform.one/components 6.1.0 → 6.3.0

package/src/layouts/PaneScaffold.stories.tsx

@@ -0,0 +1,132 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Paragraph, YStack } from "tamagui";
+import {
+  FeedLayout,
+  ListDetailLayout,
+  PaneScaffold,
+  ReadingWidth,
+  SupportingPaneLayout,
+} from "./PaneScaffold";
+
+function PaneBox({ label, flex }: { label: string; flex?: number }) {
+  return (
+    <YStack
+      flex={flex}
+      minHeight={160}
+      padding="$4"
+      backgroundColor="$color3"
+      borderWidth={1}
+      borderColor="$borderColor"
+      justifyContent="center"
+    >
+      <Paragraph fontWeight="600">{label}</Paragraph>
+    </YStack>
+  );
+}
+
+const meta: Meta<typeof PaneScaffold> = {
+  title: "Components/PaneScaffold",
+  component: PaneScaffold,
+  parameters: {
+    status: { type: "beta" },
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "Adaptive pane shell (DG-LAY-01/02). Size classes: compact <640, medium ≥640, expanded ≥860 (FloatingPanel), large ≥1024, xl ≥1280. Two panes from expanded up unless `maxPanes` ejects.",
+      },
+    },
+  },
+  argTypes: {
+    sizeClass: {
+      control: "select",
+      options: ["compact", "medium", "expanded", "large", "xl"],
+    },
+    activePane: { control: "radio", options: ["primary", "secondary"] },
+    maxPanes: { control: "radio", options: [1, 2, undefined] },
+  },
+  args: {
+    sizeClass: "expanded",
+    activePane: "primary",
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof PaneScaffold>;
+
+export const TwoPane: Story = {
+  name: "Main",
+  render: (args) => (
+    <YStack height={360} padding="$3">
+      <PaneScaffold
+        {...args}
+        primary={<PaneBox label="Primary" />}
+        secondary={<PaneBox label="Secondary" />}
+      />
+    </YStack>
+  ),
+};
+
+export const CompactActiveSecondary: Story = {
+  args: { sizeClass: "compact", activePane: "secondary" },
+  render: (args) => (
+    <YStack height={360} padding="$3">
+      <PaneScaffold
+        {...args}
+        primary={<PaneBox label="List (hidden)" />}
+        secondary={<PaneBox label="Detail (shown)" />}
+      />
+    </YStack>
+  ),
+};
+
+export const ListDetail: StoryObj<typeof ListDetailLayout> = {
+  render: () => (
+    <YStack height={360} padding="$3">
+      <ListDetailLayout
+        sizeClass="expanded"
+        list={<PaneBox label="List" />}
+        detail={<PaneBox label="Detail" />}
+      />
+    </YStack>
+  ),
+};
+
+export const SupportingPane: StoryObj<typeof SupportingPaneLayout> = {
+  render: () => (
+    <YStack height={360} padding="$3">
+      <SupportingPaneLayout sizeClass="large" supporting={<PaneBox label="Supporting (⅓)" />}>
+        <PaneBox label="Primary (⅔)" />
+      </SupportingPaneLayout>
+    </YStack>
+  ),
+};
+
+export const Feed: StoryObj<typeof FeedLayout> = {
+  render: () => (
+    <YStack padding="$3">
+      <FeedLayout>
+        <PaneBox label="Card A" />
+        <PaneBox label="Card B" />
+        <PaneBox label="Card C" />
+      </FeedLayout>
+    </YStack>
+  ),
+};
+
+export const ProseReadingWidth: StoryObj<typeof ReadingWidth> = {
+  render: () => (
+    <YStack padding="$4" gap="$3">
+      <ReadingWidth>
+        <Paragraph>
+          ReadingWidth caps prose at ~70ch (DG-LAY-05). This paragraph should wrap near sixty-five
+          to seventy-five characters per line rather than stretching edge-to-edge on a wide
+          viewport. Full-bleed is the eject via measure=&quot;none&quot;.
+        </Paragraph>
+      </ReadingWidth>
+      <ReadingWidth measure="none">
+        <Paragraph color="$color10">Ejected measure (full width of parent).</Paragraph>
+      </ReadingWidth>
+    </YStack>
+  ),
+};

package/src/layouts/PaneScaffold.tsx

@@ -0,0 +1,249 @@
+/**
+ * PaneScaffold + canonical layouts (DG-LAY-02) — W11.
+ *
+ * Devs declare pane roles; the scaffold picks 1 vs 2 columns from the
+ * canonical layout size class (`expanded` @ 860 = FloatingPanel pivot).
+ *
+ * - **List-detail**: secondary (detail) is meaningful on its own.
+ * - **Supporting-pane**: secondary is meaningful only relative to primary.
+ * - **Feed**: equal-weight cards in a responsive grid.
+ *
+ * Compact/medium show one pane; pass `activePane` to choose which.
+ */
+
+import {
+  defaultMaxPanes,
+  readingWidthStyle,
+  useLayoutSizeClass,
+  useMultiPane,
+  useSemanticGaps,
+  type LayoutSizeClass,
+  READING_WIDTH_CH,
+} from "@multiplatform.one/theme";
+import { Children, type ReactNode } from "react";
+import type { XStackProps, YStackProps } from "tamagui";
+import { XStack, YStack } from "tamagui";
+
+// ── PaneScaffold ──────────────────────────────────────────────────────────
+
+export type PaneRole = "primary" | "secondary";
+
+export interface PaneScaffoldProps extends Omit<XStackProps, "children"> {
+  primary: ReactNode;
+  secondary?: ReactNode;
+  /**
+   * Which pane to show when only one column fits. Default: `primary`.
+   * List-detail on compact typically flips to `secondary` once an item is selected.
+   */
+  activePane?: PaneRole;
+  /** Override the default pane budget (compact/medium → 1, expanded+ → 2). */
+  maxPanes?: 1 | 2;
+  /**
+   * Flex grow for primary : secondary when side-by-side.
+   * List-detail defaults to `[1, 1]`; supporting-pane to `[2, 1]`.
+   */
+  paneFlex?: [number, number];
+  /** Gap between panes — defaults to semantic `betweenGroups` (gapLg). */
+  paneGap?: XStackProps["gap"];
+  /** Optional size-class override (tests / Storybook viewports). */
+  sizeClass?: LayoutSizeClass;
+}
+
+/**
+ * Adaptive one-/two-pane shell. Geometry only — surface colors stay stable
+ * across breakpoints (Material M-L5).
+ */
+export function PaneScaffold({
+  primary,
+  secondary,
+  activePane = "primary",
+  maxPanes: maxPanesProp,
+  paneFlex = [1, 1],
+  paneGap,
+  sizeClass: sizeClassProp,
+  ...rest
+}: PaneScaffoldProps) {
+  const liveClass = useLayoutSizeClass();
+  const sizeClass = sizeClassProp ?? liveClass;
+  // Explicit `maxPanes` is the eject hatch (force 1 or 2 regardless of class).
+  const budget = maxPanesProp ?? defaultMaxPanes(sizeClass);
+  const hasSecondary = secondary !== null && secondary !== undefined;
+  const multi = budget >= 2 && hasSecondary;
+  const gaps = useSemanticGaps();
+  const gap = paneGap ?? gaps.betweenGroups.gap;
+
+  // flexBasis auto, not the flex:1 shorthand's 0%: react-native-web resets
+  // min-height to 0, so a 0% basis contributes zero intrinsic height inside
+  // auto-height scroll flows (Screen scroll pages) and the scaffold collapses,
+  // painting pane content over whatever follows. Bounded parents still fill
+  // (grow 1) exactly as before.
+  if (!multi) {
+    const shown = activePane === "secondary" && hasSecondary ? secondary : primary;
+    return (
+      <YStack
+        flexGrow={1}
+        flexShrink={1}
+        flexBasis="auto"
+        minWidth={0}
+        width="100%"
+        data-testid="pane-scaffold"
+        data-panes="1"
+        data-size-class={sizeClass}
+        {...rest}
+      >
+        {shown}
+      </YStack>
+    );
+  }
+
+  const [primaryFlex, secondaryFlex] = paneFlex;
+
+  return (
+    <XStack
+      flexGrow={1}
+      flexShrink={1}
+      flexBasis="auto"
+      minWidth={0}
+      width="100%"
+      gap={gap}
+      data-testid="pane-scaffold"
+      data-panes="2"
+      data-size-class={sizeClass}
+      {...rest}
+    >
+      <YStack flex={primaryFlex} minWidth={0} data-testid="pane-primary">
+        {primary}
+      </YStack>
+      <YStack flex={secondaryFlex} minWidth={0} data-testid="pane-secondary">
+        {secondary}
+      </YStack>
+    </XStack>
+  );
+}
+
+// ── List-detail ───────────────────────────────────────────────────────────
+
+export interface ListDetailLayoutProps extends Omit<
+  PaneScaffoldProps,
+  "primary" | "secondary" | "paneFlex"
+> {
+  list: ReactNode;
+  detail: ReactNode;
+  /** When true on single-pane viewports, show detail instead of list. */
+  selected?: boolean;
+}
+
+/**
+ * Canonical list-detail: explorative list + item detail. Detail remains
+ * meaningful without the list (Material M-L4).
+ */
+export function ListDetailLayout({
+  list,
+  detail,
+  selected = false,
+  activePane,
+  ...rest
+}: ListDetailLayoutProps) {
+  return (
+    <PaneScaffold
+      primary={list}
+      secondary={detail}
+      paneFlex={[1, 1]}
+      activePane={activePane ?? (selected ? "secondary" : "primary")}
+      data-canonical="list-detail"
+      {...rest}
+    />
+  );
+}
+
+// ── Supporting pane ───────────────────────────────────────────────────────
+
+export interface SupportingPaneLayoutProps extends Omit<
+  PaneScaffoldProps,
+  "primary" | "secondary" | "paneFlex"
+> {
+  /** Main content (~⅔ when side-by-side). */
+  children: ReactNode;
+  supporting: ReactNode;
+}
+
+/**
+ * Canonical supporting-pane: primary content + contextual support (~⅔ / ⅓).
+ * Supporting content is only meaningful relative to primary (Material M-L4).
+ */
+export function SupportingPaneLayout({ children, supporting, ...rest }: SupportingPaneLayoutProps) {
+  return (
+    <PaneScaffold
+      primary={children}
+      secondary={supporting}
+      paneFlex={[2, 1]}
+      data-canonical="supporting-pane"
+      {...rest}
+    />
+  );
+}
+
+// ── Feed ──────────────────────────────────────────────────────────────────
+
+export interface FeedLayoutProps extends YStackProps {
+  children: ReactNode;
+  /** Min card width before the grid adds a column. Default 280. */
+  minItemWidth?: number;
+}
+
+/**
+ * Canonical feed: equal-weight items in a responsive grid. Uses semantic
+ * `betweenGroups` gap between cards.
+ */
+export function FeedLayout({ children, minItemWidth = 280, ...rest }: FeedLayoutProps) {
+  const gaps = useSemanticGaps();
+  const multi = useMultiPane();
+
+  return (
+    <YStack
+      flexDirection={multi ? "row" : "column"}
+      flexWrap={multi ? "wrap" : undefined}
+      gap={gaps.betweenGroups.gap}
+      data-testid="feed-layout"
+      data-canonical="feed"
+      {...rest}
+    >
+      {Children.map(children, (child, i) => (
+        <YStack
+          key={i}
+          flexGrow={1}
+          flexBasis={multi ? minItemWidth : undefined}
+          minWidth={multi ? minItemWidth : undefined}
+          maxWidth={multi ? "100%" : undefined}
+        >
+          {child}
+        </YStack>
+      ))}
+    </YStack>
+  );
+}
+
+// ── Reading width (DG-LAY-05) ─────────────────────────────────────────────
+
+export interface ReadingWidthProps extends YStackProps {
+  /** Measure in `ch`. Default 70 (clamped 65–75). Pass `"none"` to eject. */
+  measure?: number | "none";
+  children: ReactNode;
+}
+
+/**
+ * Constrains prose / long-form content to a readable measure (~65–75ch).
+ * Full-bleed is the eject (`measure="none"`), not the default.
+ */
+export function ReadingWidth({ measure = READING_WIDTH_CH, children, ...rest }: ReadingWidthProps) {
+  return (
+    <YStack
+      alignSelf="flex-start"
+      {...readingWidthStyle(measure)}
+      data-testid="reading-width"
+      {...rest}
+    >
+      {children}
+    </YStack>
+  );
+}

package/src/layouts/Screen.stories.tsx

@@ -0,0 +1,104 @@
+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 { Paragraph, YStack } from "tamagui";
+import { CONTENT_MAX_WIDTH, EmptyState, PageHeader, PageSection, Screen } from "./page";
+
+const meta: Meta<typeof Screen> = {
+  title: "Components/Screen",
+  component: Screen,
+  parameters: {
+    status: { type: "beta" },
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "Outer page shell: scroll container, max-width centering, knob panel padding + gapLg between page regions.",
+      },
+    },
+  },
+  argTypes: {
+    scroll: { control: "boolean" },
+    maxWidth: { control: "number" },
+    bleed: { control: "boolean" },
+    noPadding: { control: "boolean" },
+  },
+  args: {
+    scroll: true,
+    maxWidth: CONTENT_MAX_WIDTH,
+    bleed: false,
+    noPadding: false,
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Screen>;
+
+export const Default: Story = {
+  name: "Main",
+  render: (args) => (
+    <Screen {...args}>
+      <PageHeader title="Screen" subtitle="Outer page shell with knob padding" />
+      <PageSection title="Region one">
+        <Paragraph>First page region.</Paragraph>
+      </PageSection>
+      <PageSection title="Region two">
+        <Paragraph>Second page region.</Paragraph>
+      </PageSection>
+    </Screen>
+  ),
+};
+
+export const Empty: Story = {
+  render: (args) => <Screen {...args} />,
+};
+
+export const LongContent: Story = {
+  render: (args) => (
+    <Screen {...args}>
+      <PageHeader title="Long content" subtitle="Forces internal scrolling" />
+      {Array.from({ length: 40 }).map((_, i) => (
+        <Paragraph key={i}>
+          Paragraph {i + 1} — enough repeated content to overflow the viewport and exercise the
+          internal ScrollView instead of the document scrollbar.
+        </Paragraph>
+      ))}
+    </Screen>
+  ),
+};
+
+export const NoScroll: Story = {
+  args: { scroll: false },
+  render: (args) => (
+    <Screen {...args}>
+      <PageHeader title="No scroll" subtitle="scroll=false renders a plain YStack" />
+      <Paragraph>Static content.</Paragraph>
+    </Screen>
+  ),
+};
+
+export const ShortContentCentering: Story = {
+  render: (args) => (
+    <Screen {...args}>
+      <EmptyState
+        title="Nothing here"
+        description="EmptyState should center in the viewport when content is shorter than the screen."
+        action={<Button>Create one</Button>}
+      />
+    </Screen>
+  ),
+};
+
+export const NestedScreens: Story = {
+  render: (args) => (
+    <Screen {...args}>
+      <PageHeader title="Outer screen" />
+      <YStack borderWidth={1} borderColor="$color6" borderStyle="dashed">
+        <Screen {...args} scroll={false}>
+          <PageHeader title="Inner screen" divider={false} />
+          <Paragraph>Nested screen content — check for double padding.</Paragraph>
+        </Screen>
+      </YStack>
+    </Screen>
+  ),
+};

package/src/layouts/ScreenToolbar.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+// Catalog Button (G-15 story honesty / LC-18): raw tamagui buttons pinned a
+// non-house radius and ignored every knob, poisoning the knob probes.
+import { Button, Spinner } from "@multiplatform.one/forms";
+import { YStack } from "tamagui";
+import { ScreenToolbar } from "./page";
+
+const meta: Meta<typeof ScreenToolbar> = {
+  title: "Components/ScreenToolbar",
+  component: ScreenToolbar,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Minimal toolbar with leading/trailing slots for the back-plus-primary-action pattern on detail screens.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof ScreenToolbar>;
+
+export const Default: Story = {
+  name: "Main",
+  render: () => (
+    <ScreenToolbar
+      leading={<Button variant="outlined">Back</Button>}
+      trailing={
+        <>
+          <Button variant="outlined">Cancel</Button>
+          <Button>Save</Button>
+        </>
+      }
+    />
+  ),
+};
+
+export const Empty: Story = {
+  render: () => <ScreenToolbar />,
+};
+
+export const LeadingOnly: Story = {
+  render: () => <ScreenToolbar leading={<Button>Back</Button>} />,
+};
+
+export const DisabledAndLoading: Story = {
+  render: () => (
+    <ScreenToolbar
+      leading={
+        <Button variant="outlined" disabled>
+          Back
+        </Button>
+      }
+      trailing={
+        <Button icon={<Spinner size="small" />} disabled>
+          Saving
+        </Button>
+      }
+    />
+  ),
+};
+
+export const ManyActionsNarrow: Story = {
+  render: () => (
+    <YStack maxWidth={320} borderWidth={1} borderColor="$color6" borderStyle="dashed">
+      <ScreenToolbar
+        leading={<Button variant="outlined">Back to the previous screen</Button>}
+        trailing={
+          <>
+            <Button variant="outlined">Duplicate</Button>
+            <Button variant="outlined">Archive</Button>
+            <Button variant="outlined">Delete permanently</Button>
+            <Button>Save changes</Button>
+          </>
+        }
+      />
+    </YStack>
+  ),
+};

package/src/layouts/Sidebar.stories.tsx

@@ -1,3 +1,4 @@
+import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { Paragraph, XStack, YStack } from "tamagui";
 import { Sidebar } from "./sidebar";
 
@@ -7,38 +8,43 @@ export default {
   parameters: { status: { type: "stable" } },
 };
 
-export const Default = () => (
-  <XStack
-    height={320}
-    borderWidth={1}
-    borderColor="$borderColor"
-    borderRadius="$3"
-    overflow="hidden"
-  >
-    <Sidebar
-      sections={[
-        {
-          title: "Navigation",
-          items: [
-            { label: "Dashboard", value: "dashboard", active: true, onPress: () => {} },
-            { label: "Projects", value: "projects", count: 5, onPress: () => {} },
-            { label: "Tasks", value: "tasks", count: 12, onPress: () => {} },
-            { label: "Messages", value: "messages", count: 3, onPress: () => {} },
-          ],
-        },
-        {
-          title: "Settings",
-          items: [
-            { label: "Profile", value: "profile", onPress: () => {} },
-            { label: "Preferences", value: "preferences", onPress: () => {} },
-            { label: "Billing", value: "billing", onPress: () => {} },
-          ],
-        },
-      ]}
-    />
-    <YStack flex={1} padding="$4" justifyContent="center" alignItems="center">
-      <Paragraph color="$color10">Main content area</Paragraph>
-    </YStack>
-  </XStack>
-);
+export const Default = () => {
+  // Demo app frame rides the outer-radius knob (G-15 story honesty): the
+  // pinned $3 held a 7px arc at borderRadius:none (UX-P06).
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <XStack
+      height={320}
+      borderWidth={1}
+      borderColor="$borderColor"
+      {...knobProps.borderRadiusOuter}
+      overflow="hidden"
+    >
+      <Sidebar
+        sections={[
+          {
+            title: "Navigation",
+            items: [
+              { label: "Dashboard", value: "dashboard", active: true, onPress: () => {} },
+              { label: "Projects", value: "projects", count: 5, onPress: () => {} },
+              { label: "Tasks", value: "tasks", count: 12, onPress: () => {} },
+              { label: "Messages", value: "messages", count: 3, onPress: () => {} },
+            ],
+          },
+          {
+            title: "Settings",
+            items: [
+              { label: "Profile", value: "profile", onPress: () => {} },
+              { label: "Preferences", value: "preferences", onPress: () => {} },
+              { label: "Billing", value: "billing", onPress: () => {} },
+            ],
+          },
+        ]}
+      />
+      <YStack flex={1} padding="$4" justifyContent="center" alignItems="center">
+        <Paragraph color="$color10">Main content area</Paragraph>
+      </YStack>
+    </XStack>
+  );
+};
 Default.storyName = "Main";