@sovereignfs/ui 0.54.0 → 0.83.1

package/src/components/PageContainer/PageContainer.module.css

@@ -1,8 +1,20 @@
 .container {
   width: 100%;
   margin-inline: auto;
+  /* Declared explicitly rather than inherited from a host reset: `maxWidth`
+     and `padding` land on this same element, so whether the max-width bound
+     includes the padding must not depend on whether the consuming app ships
+     a global `box-sizing` reset. @sovereignfs/ui is usable standalone
+     (task 9.17), where no such reset is guaranteed. Same reason Input,
+     Select, Combobox, DatePicker, and FileDropzone each set it locally. */
+  box-sizing: border-box;
 }
 
+/* ── Max width ──────────────────────────────────────────────────────────── */
+
+/* Outer bound, padding included (see box-sizing above): `md` + `padding="md"`
+   yields a 960px box with 896px of content, not 1024px. */
+
 .sm {
   max-width: 640px;
 }
@@ -18,3 +30,53 @@
 .full {
   max-width: none;
 }
+
+/* ── Padding ────────────────────────────────────────────────────────────── */
+
+/* The page gutter, owned by the plugin rather than the runtime shell
+   (task 9.25). `md` reproduces the exact values the shell used to apply
+   (--sv-space-8 desktop / --sv-space-4 mobile), so a bare <PageContainer>
+   renders identically to a pre-9.25 plugin that relied on the shell.
+
+   A fixed four-step scale, deliberately: the review behind task 9.18 found
+   four different ad-hoc padding combinations across plugins, and a free-form
+   value would relocate that inconsistency from CSS modules into JSX.
+
+   --sv-page-gutter is the stand-down hook for an ancestor that *already*
+   supplies the gutter: Dialog sets it to 0 on its content region, so an
+   overlay plugin whose page is one tree rendered into two hosts — the
+   Dialog on soft navigation, the runtime shell on a hard load — is padded
+   exactly once in both, with no prop threading and no knowledge of which
+   host it is in. Setting it to anything other than 0 defeats the fixed
+   scale above and is not a supported use. */
+
+.padNone {
+  padding: 0;
+}
+
+.padSm {
+  padding: var(--sv-page-gutter, var(--sv-space-4));
+}
+
+.padMd {
+  padding: var(--sv-page-gutter, var(--sv-space-8));
+}
+
+.padLg {
+  padding: var(--sv-page-gutter, var(--sv-space-12));
+}
+
+/* Matches the breakpoint Dialog, MobileHeader, and MobileFooter already use. */
+@media (max-width: 768px) {
+  .padSm {
+    padding: var(--sv-page-gutter, var(--sv-space-3));
+  }
+
+  .padMd {
+    padding: var(--sv-page-gutter, var(--sv-space-4));
+  }
+
+  .padLg {
+    padding: var(--sv-page-gutter, var(--sv-space-6));
+  }
+}

package/src/components/PageContainer/PageContainer.tsx

@@ -2,9 +2,23 @@ import type { HTMLAttributes, ReactNode } from 'react';
 import styles from './PageContainer.module.css';
 
 export interface PageContainerProps extends HTMLAttributes<HTMLDivElement> {
-  /** Constrains and centers content width. Adds no padding of its own — the
-   * runtime shell already pads plugin content. Defaults to 'md'. */
+  /**
+   * Constrains and centers content width. The bound includes `padding`
+   * (the container is `border-box`). Defaults to `'full'` — narrowing is
+   * opt-in, so wrapping a page in `PageContainer` never silently clamps it.
+   */
   maxWidth?: 'sm' | 'md' | 'lg' | 'full';
+  /**
+   * The page gutter. Responsive — each step is tighter at ≤768px. Defaults
+   * to `'md'`, which is exactly what the runtime shell used to apply
+   * (`--sv-space-8` desktop / `--sv-space-4` mobile), so a bare
+   * `<PageContainer>` is the correct wrapper for a plugin that previously
+   * relied on the shell for its padding.
+   *
+   * Use `'none'` when an ancestor already supplies the gutter — inside a
+   * `Dialog`, whose own content region is padded.
+   */
+  padding?: 'none' | 'sm' | 'md' | 'lg';
   children: ReactNode;
 }
 
@@ -15,13 +29,32 @@ const maxWidthClass: Record<NonNullable<PageContainerProps['maxWidth']>, string>
   full: styles.full as string,
 };
 
+const paddingClass: Record<NonNullable<PageContainerProps['padding']>, string> = {
+  none: styles.padNone as string,
+  sm: styles.padSm as string,
+  md: styles.padMd as string,
+  lg: styles.padLg as string,
+};
+
+/**
+ * The shared page wrapper every plugin's own layout or page renders through.
+ *
+ * A plugin owns its page gutter; the runtime shell does not impose one
+ * (task 9.25). The shell still reserves space for chrome a plugin cannot
+ * know about — the offline banner's height and the mobile footer's — but it
+ * contributes no inset of its own, so this component is the single place a
+ * plugin's four-sided padding comes from.
+ */
 export function PageContainer({
-  maxWidth = 'md',
+  maxWidth = 'full',
+  padding = 'md',
   className,
   children,
   ...rest
 }: PageContainerProps) {
-  const cls = [styles.container, maxWidthClass[maxWidth], className].filter(Boolean).join(' ');
+  const cls = [styles.container, maxWidthClass[maxWidth], paddingClass[padding], className]
+    .filter(Boolean)
+    .join(' ');
 
   return (
     <div className={cls} {...rest}>

package/src/components/PageContainer/__tests__/PageContainer.test.tsx

@@ -5,24 +5,57 @@ import { PageContainer } from '../PageContainer';
 
 afterEach(cleanup);
 
+/** Classes are unhashed under Vitest's CSS-module transform, so compare token
+ *  membership rather than substrings — `toContain('md')` would also match
+ *  `padMd`, which is exactly the confusion these two prop scales invite. */
+function classes(el: Element): string[] {
+  return el.className.split(/\s+/).filter(Boolean);
+}
+
 describe('PageContainer', () => {
   it('renders its children', () => {
     render(<PageContainer>content</PageContainer>);
     expect(screen.getByText('content')).toBeDefined();
   });
 
-  it('defaults to md max-width', () => {
+  it('defaults to full max-width, so wrapping a page never silently clamps it', () => {
+    render(<PageContainer>content</PageContainer>);
+    expect(classes(screen.getByText('content'))).toContain('full');
+  });
+
+  it('defaults to md padding — the gutter the runtime shell used to apply', () => {
     render(<PageContainer>content</PageContainer>);
-    expect(screen.getByText('content').className).toContain('md');
+    expect(classes(screen.getByText('content'))).toContain('padMd');
   });
 
-  it('applies sm, lg, and full max-width classes', () => {
+  it('applies sm, md, and lg max-width classes', () => {
     const { rerender } = render(<PageContainer maxWidth="sm">content</PageContainer>);
-    expect(screen.getByText('content').className).toContain('sm');
+    expect(classes(screen.getByText('content'))).toContain('sm');
+    rerender(<PageContainer maxWidth="md">content</PageContainer>);
+    expect(classes(screen.getByText('content'))).toContain('md');
     rerender(<PageContainer maxWidth="lg">content</PageContainer>);
-    expect(screen.getByText('content').className).toContain('lg');
-    rerender(<PageContainer maxWidth="full">content</PageContainer>);
-    expect(screen.getByText('content').className).toContain('full');
+    expect(classes(screen.getByText('content'))).toContain('lg');
+  });
+
+  it('applies none, sm, and lg padding classes', () => {
+    const { rerender } = render(<PageContainer padding="none">content</PageContainer>);
+    expect(classes(screen.getByText('content'))).toContain('padNone');
+    rerender(<PageContainer padding="sm">content</PageContainer>);
+    expect(classes(screen.getByText('content'))).toContain('padSm');
+    rerender(<PageContainer padding="lg">content</PageContainer>);
+    expect(classes(screen.getByText('content'))).toContain('padLg');
+  });
+
+  it('composes max-width and padding independently', () => {
+    render(
+      <PageContainer maxWidth="sm" padding="none">
+        content
+      </PageContainer>,
+    );
+    const cls = classes(screen.getByText('content'));
+    expect(cls).toContain('sm');
+    expect(cls).toContain('padNone');
+    expect(cls).not.toContain('padSm');
   });
 
   it('forwards className and other div props', () => {
@@ -32,6 +65,6 @@ describe('PageContainer', () => {
       </PageContainer>,
     );
     const el = screen.getByTestId('container');
-    expect(el.className).toContain('custom');
+    expect(classes(el)).toContain('custom');
   });
 });

package/src/components/PageHeader/PageHeader.module.css

@@ -13,6 +13,17 @@
   min-width: 0;
 }
 
+/* Wraps the optional icon + `.title` so the icon sizes/aligns itself
+   without touching `.title`'s own rules — every existing icon-less usage
+   renders identically, since a single flex child behaves the same as a
+   non-flex one. */
+.titleRow {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-2);
+  color: var(--sv-color-text-primary);
+}
+
 .title {
   margin: 0;
   font-size: var(--sv-font-size-2xl);
@@ -30,3 +41,46 @@
 .action {
   flex-shrink: 0;
 }
+
+/* ── Mobile ─────────────────────────────────────────────────────────────── */
+/* A compact single row — back (optional) + title + action (optional) —
+   generalized from Kanban's own hand-rolled MobileBoardHeader. Deliberately
+   no description handling and no border; stays consistent with .header's
+   own minimal, borderless treatment, just tighter. */
+
+.mobileHeader {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-2);
+  margin-bottom: var(--sv-space-3);
+}
+
+.mobileBack {
+  flex-shrink: 0;
+}
+
+.mobileTitleIcon {
+  flex-shrink: 0;
+  color: var(--sv-color-text-primary);
+}
+
+.mobileTitle {
+  flex: 1;
+  min-width: 0;
+  margin: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: var(--sv-font-size-md);
+  font-weight: var(--sv-font-weight-semibold);
+  color: var(--sv-color-text-primary);
+  line-height: 1.2;
+}
+
+.mobileAction {
+  flex-shrink: 0;
+}
+
+.mobileMenu {
+  flex-shrink: 0;
+}

package/src/components/PageHeader/PageHeader.tsx

@@ -1,35 +1,176 @@
+'use client';
+
 import type { ReactNode } from 'react';
+import { Button } from '../Button/Button';
+import { Icon } from '../Icon/Icon';
+import type { IconName } from '../Icon/Icon';
+import { ResponsiveSurface } from '../ResponsiveSurface/ResponsiveSurface';
 import styles from './PageHeader.module.css';
 
 export interface PageHeaderProps {
   title: string;
   description?: string;
+  /** Optional icon rendered inline before the title text, on both breakpoints — e.g. `folder-open` next to a folder's name. */
+  icon?: IconName;
+  /**
+   * Page-level controls — anywhere from one button to a whole toolbar.
+   * Renders on both breakpoints unchanged; if it needs to look different on
+   * mobile (e.g. collapsing into its own "⋮" trigger), that's the action
+   * content's own responsibility — same pattern Shopper's `ListHeaderActions`
+   * already follows (it calls `useIsMobile()` internally). `PageHeader`
+   * itself has no opinion on what's inside this slot.
+   */
   action?: ReactNode;
   className?: string;
   /** Heading level for the title. Defaults to `1` for standalone use; pass
    * `2` or `3` when the page already sits under a shell/plugin `<h1>`, to
    * avoid a duplicate top-level heading. Visual style is unchanged at every
-   * level — only the rendered tag changes. */
+   * level — only the rendered tag changes. Applies on both breakpoints. */
   headingLevel?: 1 | 2 | 3;
+  /** Mobile only — shows a back button (calling this) to the left of the
+   *  title when provided. Omit it to render without one. */
+  onBack?: () => void;
+  /** Mobile only — shows a vertical-ellipsis icon button (calling this) at
+   *  the far right when provided, typically to open a drawer/menu. PageHeader
+   *  has no opinion on what that menu contains — it only renders the trigger
+   *  and calls back. Separate from `action`, which renders identically on
+   *  both breakpoints; this is a mobile-only affordance with no web
+   *  equivalent. */
+  onMenuClick?: () => void;
 }
 
 const HEADING_TAG = { 1: 'h1', 2: 'h2', 3: 'h3' } as const;
 
-export function PageHeader({
+interface PageHeaderWebProps {
+  title: string;
+  description?: string;
+  icon?: IconName;
+  action?: ReactNode;
+  headingLevel: 1 | 2 | 3;
+  className?: string;
+}
+
+// internal — not exported
+function PageHeaderWeb({
   title,
   description,
+  icon,
   action,
+  headingLevel,
   className,
-  headingLevel = 1,
-}: PageHeaderProps) {
+}: PageHeaderWebProps) {
   const Heading = HEADING_TAG[headingLevel];
   return (
     <header className={[styles.header, className].filter(Boolean).join(' ')}>
       <div className={styles.text}>
-        <Heading className={styles.title}>{title}</Heading>
+        <div className={styles.titleRow}>
+          {icon && <Icon name={icon} size="lg" aria-hidden={true} />}
+          <Heading className={styles.title}>{title}</Heading>
+        </div>
         {description && <p className={styles.description}>{description}</p>}
       </div>
       {action && <div className={styles.action}>{action}</div>}
     </header>
   );
 }
+
+interface PageHeaderMobileProps {
+  title: string;
+  icon?: IconName;
+  action?: ReactNode;
+  headingLevel: 1 | 2 | 3;
+  onBack?: () => void;
+  onMenuClick?: () => void;
+  className?: string;
+}
+
+// internal — not exported
+// No `description` here, deliberately — matches the one real mobile
+// page-header precedent this was generalized from (Kanban's own
+// MobileBoardHeader), which has no subtitle handling either. A single
+// fixed-shape row, consistent with every other mobile chrome bar in this
+// design system rather than a variable-height two-line header.
+function PageHeaderMobile({
+  title,
+  icon,
+  action,
+  headingLevel,
+  onBack,
+  onMenuClick,
+  className,
+}: PageHeaderMobileProps) {
+  const Heading = HEADING_TAG[headingLevel];
+  return (
+    <header className={[styles.mobileHeader, className].filter(Boolean).join(' ')}>
+      {onBack && (
+        <Button
+          variant="ghost"
+          size="sm"
+          aria-label="Back"
+          onClick={onBack}
+          className={styles.mobileBack}
+        >
+          <Icon name="circle-chevron-left" size="md" aria-hidden />
+        </Button>
+      )}
+      {icon && <Icon name={icon} size="md" aria-hidden={true} className={styles.mobileTitleIcon} />}
+      <Heading className={styles.mobileTitle}>{title}</Heading>
+      {action && <div className={styles.mobileAction}>{action}</div>}
+      {onMenuClick && (
+        <Button
+          variant="ghost"
+          size="sm"
+          aria-label="Menu"
+          onClick={onMenuClick}
+          className={styles.mobileMenu}
+        >
+          <Icon name="ellipsis-vertical" size="md" aria-hidden />
+        </Button>
+      )}
+    </header>
+  );
+}
+
+/**
+ * PageHeader — a page's title section. Web: title + description on the
+ * left, action on the right. Mobile: an optional back button, a single-line
+ * title, and the same action slot — a compact single row, matching Kanban's
+ * own hand-rolled MobileBoardHeader this was generalized from. The
+ * web/mobile fork is `ResponsiveSurface` — only one tree is ever mounted.
+ */
+export function PageHeader({
+  title,
+  description,
+  icon,
+  action,
+  className,
+  headingLevel = 1,
+  onBack,
+  onMenuClick,
+}: PageHeaderProps) {
+  return (
+    <ResponsiveSurface
+      web={
+        <PageHeaderWeb
+          title={title}
+          description={description}
+          icon={icon}
+          action={action}
+          headingLevel={headingLevel}
+          className={className}
+        />
+      }
+      mobile={
+        <PageHeaderMobile
+          title={title}
+          icon={icon}
+          action={action}
+          headingLevel={headingLevel}
+          onBack={onBack}
+          onMenuClick={onMenuClick}
+          className={className}
+        />
+      }
+    />
+  );
+}

package/src/components/PageHeader/__tests__/PageHeader.test.tsx

@@ -0,0 +1,103 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { PageHeader } from '../PageHeader';
+
+let matches = false;
+
+function installMatchMedia() {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches,
+      media: query,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}
+
+describe('PageHeader', () => {
+  beforeEach(() => {
+    matches = false;
+    installMatchMedia();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('web: renders title, description, and action', () => {
+    render(
+      <PageHeader
+        title="Users"
+        description="Manage who has access to this instance."
+        action={<button type="button">Invite user</button>}
+      />,
+    );
+
+    expect(screen.getByRole('heading', { name: 'Users' })).toBeDefined();
+    expect(screen.getByText('Manage who has access to this instance.')).toBeDefined();
+    expect(screen.getByRole('button', { name: 'Invite user' })).toBeDefined();
+  });
+
+  it('web: renders no back button even when onBack is given', () => {
+    render(<PageHeader title="Users" onBack={() => undefined} />);
+
+    expect(screen.queryByRole('button', { name: 'Back' })).toBeNull();
+  });
+
+  it('mobile: renders no description, no back button, no menu button by default', () => {
+    matches = true;
+    installMatchMedia();
+
+    render(<PageHeader title="Users" description="Manage who has access to this instance." />);
+
+    expect(screen.getByRole('heading', { name: 'Users' })).toBeDefined();
+    expect(screen.queryByText('Manage who has access to this instance.')).toBeNull();
+    expect(screen.queryByRole('button', { name: 'Back' })).toBeNull();
+    expect(screen.queryByRole('button', { name: 'Menu' })).toBeNull();
+  });
+
+  it('mobile: renders a back button that calls onBack when given', () => {
+    matches = true;
+    installMatchMedia();
+    const onBack = vi.fn();
+
+    render(<PageHeader title="Users" onBack={onBack} />);
+
+    const back = screen.getByRole('button', { name: 'Back' });
+    fireEvent.click(back);
+    expect(onBack).toHaveBeenCalledOnce();
+  });
+
+  it('mobile: renders a menu button that calls onMenuClick when given', () => {
+    matches = true;
+    installMatchMedia();
+    const onMenuClick = vi.fn();
+
+    render(<PageHeader title="Users" onMenuClick={onMenuClick} />);
+
+    const menu = screen.getByRole('button', { name: 'Menu' });
+    fireEvent.click(menu);
+    expect(onMenuClick).toHaveBeenCalledOnce();
+  });
+
+  it('web: renders no menu button even when onMenuClick is given', () => {
+    render(<PageHeader title="Users" onMenuClick={() => undefined} />);
+
+    expect(screen.queryByRole('button', { name: 'Menu' })).toBeNull();
+  });
+
+  it('mobile: renders the same action content as web', () => {
+    matches = true;
+    installMatchMedia();
+
+    render(<PageHeader title="Users" action={<button type="button">Invite user</button>} />);
+
+    expect(screen.getByRole('button', { name: 'Invite user' })).toBeDefined();
+  });
+});

package/src/components/PageLayout/PageLayout.module.css

@@ -0,0 +1,51 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  min-width: 100%;
+  min-height: 100%;
+}
+
+.header {
+  flex-shrink: 0;
+}
+
+.content {
+  flex: 1;
+}
+
+/* ── Padding ────────────────────────────────────────────────────────────── */
+/* Same four-step scale and --sv-page-gutter stand-down hook as
+   PageContainer (see that component's own CSS comment for the full
+   rationale) — kept identical so this can absorb PageContainer's role
+   later without a behavior change for existing consumers. */
+
+.padNone {
+  padding: 0;
+}
+
+.padSm {
+  padding: var(--sv-page-gutter, var(--sv-space-4));
+}
+
+.padMd {
+  padding: var(--sv-page-gutter, var(--sv-space-8));
+}
+
+.padLg {
+  padding: var(--sv-page-gutter, var(--sv-space-12));
+}
+
+/* Matches the breakpoint Dialog, MobileHeader, and MobileFooter already use. */
+@media (max-width: 768px) {
+  .padSm {
+    padding: var(--sv-page-gutter, var(--sv-space-3));
+  }
+
+  .padMd {
+    padding: var(--sv-page-gutter, var(--sv-space-4));
+  }
+
+  .padLg {
+    padding: var(--sv-page-gutter, var(--sv-space-6));
+  }
+}

package/src/components/PageLayout/PageLayout.stories.tsx

@@ -0,0 +1,73 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { PageLayout } from './PageLayout';
+
+function Content() {
+  return (
+    <div
+      style={{
+        fontFamily: 'var(--sv-font-family)',
+        fontSize: 'var(--sv-font-size-sm)',
+        color: 'var(--sv-color-text-primary)',
+      }}
+    >
+      {Array.from({ length: 6 }, (_, index) => (
+        <p key={index}>Page content row {index + 1}.</p>
+      ))}
+    </div>
+  );
+}
+
+function PageHeader() {
+  return (
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        padding: 'var(--sv-space-3) var(--sv-space-4)',
+        borderBottom: '1px solid var(--sv-color-border)',
+        fontFamily: 'var(--sv-font-family)',
+        fontSize: 'var(--sv-font-size-md)',
+        fontWeight: 600,
+        color: 'var(--sv-color-text-primary)',
+      }}
+    >
+      Sv Wallet
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Components/PageLayout',
+  component: PageLayout,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          "A single page's content area, nested inside RootLayout's main slot — not a replacement for RootLayout. No padding by default; opt in via the padding prop (same scale as PageContainer). The optional header is page-specific (e.g. a board title/toolbar), not the app-level header RootLayout already renders.",
+      },
+    },
+  },
+  args: {
+    children: <Content />,
+  },
+} satisfies Meta<typeof PageLayout>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithPadding: Story = {
+  args: {
+    padding: 'lg',
+  },
+};
+
+export const WithHeader: Story = {
+  args: {
+    header: <PageHeader />,
+    padding: 'md',
+  },
+};