@multiplatform.one/components 6.7.0 → 7.1.0

package/src/layouts/EmptyState.tsx

@@ -0,0 +1,169 @@
+/**
+ * EmptyState — centered empty / error placeholder (Polaris EmptyState +
+ * Primer Blankslate anatomy).
+ *
+ * Full-page: icon well → heading → helper copy → primary (and optional
+ * secondary) actions. Compact: quieter type, no flex-fill, for tables and
+ * columns. `intent="error"` is sober failure chrome (DG-ST-01) — never for a
+ * successful empty dataset.
+ */
+import {
+  Intent,
+  radiusClassProps,
+  readingWidthStyle,
+  useResolvedKnobs,
+  warnBannedErrorWords,
+} from "@multiplatform.one/theme";
+import { useId, type ReactNode } from "react";
+import { H2, Paragraph, XStack, YStack, isWeb, type YStackProps } from "tamagui";
+import { componentColors } from "../componentColors";
+
+export interface EmptyStateProps extends YStackProps {
+  title: string;
+  description?: string;
+  /** Icon or illustration shown above the title. Decorative — hidden from AT. */
+  icon?: ReactNode;
+  /** Action button(s) shown below the description. One primary; secondary outlined. */
+  action?: ReactNode;
+  /** Smaller type + no flex-fill, for inline use inside tables/columns. */
+  compact?: boolean;
+  /**
+   * Visual intent. `error` marks sober failure chrome (DG-ST-01) — use via
+   * AsyncBoundary; never for a successful empty dataset.
+   */
+  intent?: "neutral" | "error";
+}
+
+/**
+ * Centered empty/error state. Use for "no data", "not configured",
+ * "permission denied" placeholder screens.
+ *
+ * Prefer `<AsyncBoundary>` for async data views so empty chrome can never
+ * render on a failed load (DG-ST-01).
+ */
+export function EmptyState({
+  title,
+  description,
+  icon,
+  action,
+  compact = false,
+  intent = "neutral",
+  children,
+  ...rest
+}: EmptyStateProps) {
+  // compact steps the resolved size/space knobs down one level, so the
+  // icon well, gaps, and copy shrink through the one pipeline (Axiom 5).
+  const { knobProps } = useResolvedKnobs({ compact });
+  // See PageHeader: native-only heading family from the headingFont knob.
+  const headingFamily = isWeb ? null : { fontFamily: knobProps.heading.fontFamily };
+  const titleId = useId();
+  const isError = intent === "error";
+  // Polaris/Primer: icon | copy | actions are three bands; title+description
+  // sit tighter than the bands. Compact (table/column) stays on the stepped gap.
+  const frameGap = compact ? knobProps.gap : knobProps.gapLg;
+
+  if (isError) {
+    warnBannedErrorWords(title, { component: "EmptyState" });
+    warnBannedErrorWords(description, { component: "EmptyState" });
+  }
+
+  const well = icon ? (
+    <YStack
+      alignItems="center"
+      justifyContent="center"
+      backgroundColor={componentColors.interactive.background}
+      // R-PILL icon well: always a circle; its inset scales with the
+      // size knob (spec: empty icon well consumes sizeToken). Declared so
+      // the `radius:none` sweep licenses the circle instead of guessing
+      // from its geometry (D-09 / LC-60).
+      {...radiusClassProps("R-PILL", "empty icon well")}
+      padding={knobProps.sizeToken as any}
+      borderRadius={1000}
+      aria-hidden
+      {...(!isWeb ? { accessibilityElementsHidden: true } : null)}
+    >
+      {icon}
+    </YStack>
+  ) : null;
+
+  const titleNode = compact ? (
+    <Paragraph
+      {...(isWeb ? { id: titleId } : { nativeID: titleId })}
+      {...knobProps.body}
+      color={componentColors.text.primary}
+      textAlign="center"
+      margin={0}
+      width="100%"
+      {...(!isWeb && { numberOfLines: 2, adjustsFontSizeToFit: true, minimumFontScale: 0.55 })}
+    >
+      {title}
+    </Paragraph>
+  ) : (
+    <H2
+      {...(isWeb ? { id: titleId } : { nativeID: titleId })}
+      {...headingFamily}
+      {...knobProps.textWeight}
+      textAlign="center"
+      margin={0}
+      width="100%"
+      color={componentColors.text.primary}
+      {...(!isWeb && { numberOfLines: 2, adjustsFontSizeToFit: true, minimumFontScale: 0.55 })}
+    >
+      {title}
+    </H2>
+  );
+
+  return (
+    <YStack
+      flex={compact ? undefined : 1}
+      width="100%"
+      alignItems="center"
+      justifyContent="center"
+      data-empty-intent={intent}
+      {...(isWeb
+        ? {
+            role: isError ? "alert" : "status",
+            "aria-labelledby": titleId,
+            ...(!isError ? { "aria-live": "polite" as const } : null),
+          }
+        : {
+            accessibilityRole: isError ? "alert" : "text",
+            accessibilityLabel: title,
+          })}
+      {...knobProps.panelPadding}
+      {...frameGap}
+      {...rest}
+    >
+      {well && isError ? <Intent name="error">{well}</Intent> : well}
+      <YStack alignItems="center" gap="$1" {...readingWidthStyle()}>
+        {titleNode}
+        {description ? (
+          <Paragraph
+            {...knobProps.body}
+            color={knobProps.textAccentColor as any}
+            fontSize={knobProps.label.fontSize}
+            textAlign="center"
+            margin={0}
+            width="100%"
+          >
+            {description}
+          </Paragraph>
+        ) : null}
+      </YStack>
+      {action ? (
+        <XStack
+          {...knobProps.gap}
+          alignItems="center"
+          justifyContent="center"
+          flexWrap="wrap"
+          flexShrink={1}
+          minWidth={0}
+          maxWidth="100%"
+        >
+          {action}
+        </XStack>
+      ) : null}
+      {children}
+    </YStack>
+  );
+}

package/src/layouts/PageHeader.stories.tsx

@@ -3,18 +3,21 @@ import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 // the knobs and pinned a non-house radius (UX-P06).
 import { Button } from "@multiplatform.one/forms";
 import { Preset } from "@multiplatform.one/theme";
-import { YStack } from "tamagui";
-import { PageHeader } from "./page";
+import type { ReactNode } from "react";
+import { Paragraph, YStack } from "tamagui";
+import { Tabs } from "../Tabs";
+import { PageHeader, Screen } from "./page";
 
 const meta: Meta<typeof PageHeader> = {
   title: "Components/PageHeader",
   component: PageHeader,
   parameters: {
     status: { type: "beta" },
+    layout: "fullscreen",
     docs: {
       description: {
         component:
-          "Standard page header: H1 title left, actions right, optional subtitle, thin divider rule beneath.",
+          "Page header: H1 + body-scale lede stacked left, actions right, edge-to-edge hairline. Pass `nav` (tabs) to seat the active indicator on that one rule.",
       },
     },
   },
@@ -33,28 +36,74 @@ export default meta;
 
 type Story = StoryObj<typeof PageHeader>;
 
+function HeaderCanvas({ children }: { children: ReactNode }) {
+  return (
+    <Screen scroll={false} maxWidth={720}>
+      {children}
+      <Paragraph color="$color11">
+        Page body shares the title inset. The hairline is edge-to-edge.
+      </Paragraph>
+    </Screen>
+  );
+}
+
 export const Default: Story = {
   name: "Main",
-  render: (args) => <PageHeader {...args} />,
+  render: (args) => (
+    <HeaderCanvas>
+      <PageHeader {...args} />
+    </HeaderCanvas>
+  ),
 };
 
 export const WithActions: Story = {
   render: (args) => (
-    <PageHeader
-      {...args}
-      actions={
-        <>
-          <Button variant="outlined">Secondary</Button>
-          <Button>Primary</Button>
-        </>
-      }
-    />
+    <HeaderCanvas>
+      <PageHeader
+        {...args}
+        actions={
+          <>
+            <Button variant="outlined">Secondary</Button>
+            <Button>Primary</Button>
+          </>
+        }
+      />
+    </HeaderCanvas>
+  ),
+};
+
+export const WithNav: Story = {
+  render: (args) => (
+    <HeaderCanvas>
+      <PageHeader
+        {...args}
+        actions={
+          <>
+            <Button variant="outlined">Secondary</Button>
+            <Button>Primary</Button>
+          </>
+        }
+        nav={
+          <Tabs
+            items={[
+              { value: "all", label: "All" },
+              { value: "open", label: "Open" },
+              { value: "closed", label: "Closed" },
+            ]}
+          />
+        }
+      />
+    </HeaderCanvas>
   ),
 };
 
 export const TitleOnly: Story = {
   args: { subtitle: undefined },
-  render: (args) => <PageHeader {...args} />,
+  render: (args) => (
+    <HeaderCanvas>
+      <PageHeader {...args} />
+    </HeaderCanvas>
+  ),
 };
 
 /**
@@ -82,7 +131,11 @@ export const HeroPresetSurface: Story = {
 
 export const NoTitle: Story = {
   args: { title: undefined, subtitle: undefined },
-  render: (args) => <PageHeader {...args} actions={<Button>Only action</Button>} />,
+  render: (args) => (
+    <HeaderCanvas>
+      <PageHeader {...args} actions={<Button>Only action</Button>} />
+    </HeaderCanvas>
+  ),
 };
 
 export const LongTitleNarrow: Story = {

package/src/layouts/PageTemplates.tsx

@@ -37,14 +37,16 @@ interface TemplateHeaderProps {
   title?: string;
   subtitle?: string;
   actions?: ReactNode;
+  /** Underline navigation (tabs) seated on the page-header hairline. */
+  nav?: ReactNode;
   /** Full override — replaces the default `PageHeader`. */
   header?: ReactNode;
 }
 
-function renderTemplateHeader({ title, subtitle, actions, header }: TemplateHeaderProps) {
+function renderTemplateHeader({ title, subtitle, actions, nav, header }: TemplateHeaderProps) {
   if (header !== undefined) return header;
-  if (!title && !subtitle && !actions) return null;
-  return <PageHeader title={title} subtitle={subtitle} actions={actions} />;
+  if (!title && !subtitle && !actions && !nav) return null;
+  return <PageHeader title={title} subtitle={subtitle} actions={actions} nav={nav} />;
 }
 
 // ── ListPageLayout ─────────────────────────────────────────────────────────
@@ -69,13 +71,14 @@ export function ListPageLayout({
   subtitle,
   actions,
   header,
+  nav,
   toolbar,
   children,
   ...rest
 }: ListPageLayoutProps) {
   return (
     <Screen data-canonical="list-page" {...rest}>
-      {renderTemplateHeader({ title, subtitle, actions, header })}
+      {renderTemplateHeader({ title, subtitle, actions, header, nav })}
       {toolbar}
       <YStack flex={1} minWidth={0} data-testid="list-page-content">
         {children}
@@ -121,6 +124,7 @@ export function DetailPageLayout({
   subtitle,
   actions,
   header,
+  nav,
   toolbarLeading,
   toolbarTrailing,
   aside,
@@ -160,7 +164,7 @@ export function DetailPageLayout({
   return (
     <Screen data-canonical="detail-page" {...rest}>
       {toolbar}
-      {renderTemplateHeader({ title, subtitle, actions, header })}
+      {renderTemplateHeader({ title, subtitle, actions, header, nav })}
       {body}
     </Screen>
   );
@@ -190,13 +194,14 @@ export function SettingsPageLayout({
   subtitle,
   actions,
   header,
+  nav,
   maxWidth = layoutBreakpoints.expanded,
   children,
   ...rest
 }: SettingsPageLayoutProps) {
   return (
     <Screen data-canonical="settings-page" maxWidth={maxWidth} {...rest}>
-      {renderTemplateHeader({ title, subtitle, actions, header })}
+      {renderTemplateHeader({ title, subtitle, actions, header, nav })}
       {children}
     </Screen>
   );

package/src/layouts/PaneScaffold.stories.tsx

@@ -1,5 +1,14 @@
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
-import { Paragraph, YStack } from "tamagui";
+import {
+  getGroupPosition,
+  hairlineWidth,
+  stackRadiusProps,
+  useReadableTextOn,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
+import type { ReactNode } from "react";
+import { Paragraph, Text, YStack } from "tamagui";
+import { componentColors } from "../componentColors";
 import {
   FeedLayout,
   ListDetailLayout,
@@ -8,22 +17,93 @@ import {
   SupportingPaneLayout,
 } from "./PaneScaffold";
 
-function PaneBox({ label, flex }: { label: string; flex?: number }) {
+function SplitFrame({ children, height = 360 }: { children: ReactNode; height?: number }) {
+  const { knobProps } = useResolvedKnobs();
   return (
     <YStack
-      flex={flex}
-      minHeight={160}
-      padding="$4"
-      backgroundColor="$color3"
-      borderWidth={1}
+      height={height}
+      overflow="hidden"
       borderColor="$borderColor"
+      borderWidth={hairlineWidth}
+      {...knobProps.borderRadius}
+    >
+      {children}
+    </YStack>
+  );
+}
+
+function PaneFill({ label, hint, muted }: { label: string; hint?: string; muted?: boolean }) {
+  return (
+    <YStack
+      flex={1}
+      height="100%"
+      padding="$4"
+      backgroundColor={muted ? componentColors.surface.background : "$background"}
       justifyContent="center"
+      gap="$2"
     >
       <Paragraph fontWeight="600">{label}</Paragraph>
+      {hint ? (
+        <Text color={componentColors.text.muted} fontSize="$2">
+          {hint}
+        </Text>
+      ) : null}
     </YStack>
   );
 }
 
+const LIST_ITEMS = ["Inbox", "Drafts", "Sent", "Archive"];
+
+function DemoList({ active = 0 }: { active?: number }) {
+  const onAccent = useReadableTextOn("$accentBackground");
+  return (
+    <YStack flex={1} height="100%" backgroundColor={componentColors.surface.background}>
+      {LIST_ITEMS.map((label, i) => {
+        const position = getGroupPosition(i, LIST_ITEMS.length);
+        const corners = stackRadiusProps(position, 0);
+        const selected = i === active;
+        return (
+          <YStack
+            key={label}
+            {...corners}
+            padding="$3"
+            backgroundColor={selected ? "$accentBackground" : "transparent"}
+          >
+            <Text
+              fontWeight={selected ? "600" : "400"}
+              color={selected && onAccent ? onAccent : componentColors.text.primary}
+            >
+              {label}
+            </Text>
+          </YStack>
+        );
+      })}
+    </YStack>
+  );
+}
+
+function FeedCards() {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <FeedLayout>
+      {["Card A", "Card B", "Card C"].map((label) => (
+        <YStack
+          key={label}
+          minHeight={120}
+          padding="$4"
+          backgroundColor={componentColors.surface.background}
+          borderWidth={hairlineWidth}
+          borderColor="$borderColor"
+          justifyContent="center"
+          {...knobProps.borderRadius}
+        >
+          <Paragraph fontWeight="600">{label}</Paragraph>
+        </YStack>
+      ))}
+    </FeedLayout>
+  );
+}
+
 const meta: Meta<typeof PaneScaffold> = {
   title: "Components/PaneScaffold",
   component: PaneScaffold,
@@ -33,7 +113,7 @@ const meta: Meta<typeof PaneScaffold> = {
     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.",
+          "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. Side-by-side uses a hairline sash (Linear / VS Code / Polaris Frame); pass `paneGap` to eject to spaced columns.",
       },
     },
   },
@@ -44,6 +124,7 @@ const meta: Meta<typeof PaneScaffold> = {
     },
     activePane: { control: "radio", options: ["primary", "secondary"] },
     maxPanes: { control: "radio", options: [1, 2, undefined] },
+    resizable: { control: "boolean" },
   },
   args: {
     sizeClass: "expanded",
@@ -57,12 +138,14 @@ 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 height={400} padding="$4">
+      <SplitFrame>
+        <PaneScaffold
+          {...args}
+          primary={<PaneFill label="Primary" hint="Drag the seam · arrows resize" />}
+          secondary={<PaneFill label="Secondary" muted />}
+        />
+      </SplitFrame>
     </YStack>
   ),
 };
@@ -70,46 +153,56 @@ export const TwoPane: Story = {
 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 height={400} padding="$4">
+      <SplitFrame>
+        <PaneScaffold
+          {...args}
+          primary={<PaneFill label="List (hidden)" />}
+          secondary={<PaneFill label="Detail (shown)" muted />}
+        />
+      </SplitFrame>
     </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 height={400} padding="$4">
+      <SplitFrame>
+        <ListDetailLayout
+          sizeClass="expanded"
+          list={<DemoList />}
+          detail={
+            <PaneFill
+              label="Inbox"
+              hint="List is the narrower pane. Detail stays meaningful on its own."
+            />
+          }
+        />
+      </SplitFrame>
     </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 height={400} padding="$4">
+      <SplitFrame>
+        <SupportingPaneLayout
+          sizeClass="large"
+          supporting={<PaneFill label="Supporting (⅓)" muted hint="Properties · filters · meta" />}
+        >
+          <PaneFill label="Primary (⅔)" hint="Main canvas" />
+        </SupportingPaneLayout>
+      </SplitFrame>
     </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 padding="$4">
+      <FeedCards />
     </YStack>
   ),
 };
@@ -125,7 +218,9 @@ export const ProseReadingWidth: StoryObj<typeof ReadingWidth> = {
         </Paragraph>
       </ReadingWidth>
       <ReadingWidth measure="none">
-        <Paragraph color="$color10">Ejected measure (full width of parent).</Paragraph>
+        <Paragraph color={componentColors.text.muted}>
+          Ejected measure (full width of parent).
+        </Paragraph>
       </ReadingWidth>
     </YStack>
   ),