@sovereignfs/ui 0.45.0 → 0.54.0

package/src/stories/MobilePatterns.stories.tsx

@@ -8,6 +8,8 @@ import { EmptyState } from '../components/EmptyState/EmptyState';
 import { FormField } from '../components/FormField/FormField';
 import { Icon } from '../components/Icon/Icon';
 import { Input } from '../components/Input/Input';
+import { MobileFooter } from '../components/MobileFooter/MobileFooter';
+import { MobileHeader } from '../components/MobileHeader/MobileHeader';
 import { NavTabs } from '../components/NavTabs/NavTabs';
 import { PageHeader } from '../components/PageHeader/PageHeader';
 
@@ -263,6 +265,175 @@ function DrawerDemo() {
   );
 }
 
+function MobileHeaderFooterDemo() {
+  const [showTitle, setShowTitle] = useState(false);
+  const [customLogo, setCustomLogo] = useState(true);
+  const [wideFooter, setWideFooter] = useState(false);
+  const [appsOpen, setAppsOpen] = useState(false);
+
+  const logo = (
+    <span
+      aria-label="Home"
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: 28,
+        height: 28,
+        borderRadius: 'var(--sv-radius-sm)',
+        background: 'var(--sv-color-accent)',
+        color: 'var(--sv-color-text-on-accent)',
+        fontWeight: 700,
+        fontSize: 13,
+        flexShrink: 0,
+      }}
+    >
+      S
+    </span>
+  );
+
+  const leftOne = [
+    { icon: <Icon name="house" size="md" aria-hidden />, label: 'Home', active: true },
+  ];
+  const rightOne = [{ icon: <Icon name="search" size="md" aria-hidden />, label: 'Search' }];
+  const leftTwo = [
+    ...leftOne,
+    { icon: <Icon name="calendar" size="md" aria-hidden />, label: 'Calendar' },
+  ];
+  const rightTwo = [
+    ...rightOne,
+    { icon: <Icon name="activity" size="md" aria-hidden />, label: 'Activity' },
+  ];
+
+  return (
+    <>
+      <div style={{ display: 'flex', gap: 'var(--sv-space-4)', marginBottom: 'var(--sv-space-4)' }}>
+        <label
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: 'var(--sv-space-2)',
+            fontSize: 'var(--sv-font-size-sm)',
+            color: 'var(--sv-color-text-primary)',
+            cursor: 'pointer',
+          }}
+        >
+          <input
+            type="checkbox"
+            checked={showTitle}
+            onChange={(e) => setShowTitle(e.target.checked)}
+          />
+          Header <code>title</code> prop
+        </label>
+        <label
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: 'var(--sv-space-2)',
+            fontSize: 'var(--sv-font-size-sm)',
+            color: 'var(--sv-color-text-primary)',
+            cursor: 'pointer',
+          }}
+        >
+          <input
+            type="checkbox"
+            checked={customLogo}
+            onChange={(e) => setCustomLogo(e.target.checked)}
+          />
+          Custom <code>logo</code> prop (unchecked = default badge)
+        </label>
+        <label
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: 'var(--sv-space-2)',
+            fontSize: 'var(--sv-font-size-sm)',
+            color: 'var(--sv-color-text-primary)',
+            cursor: 'pointer',
+          }}
+        >
+          <input
+            type="checkbox"
+            checked={wideFooter}
+            onChange={(e) => setWideFooter(e.target.checked)}
+          />
+          Footer: 2 + 2 icons
+        </label>
+      </div>
+
+      <div
+        style={{
+          border: '1px solid var(--sv-color-border)',
+          borderRadius: 'var(--sv-radius-lg)',
+          overflow: 'hidden',
+        }}
+      >
+        <MobileHeader
+          logo={customLogo ? logo : undefined}
+          title={showTitle ? 'Tasks' : undefined}
+          bell={
+            <button
+              type="button"
+              aria-label="Notifications"
+              style={{
+                display: 'inline-flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                width: 44,
+                height: 44,
+                background: 'none',
+                border: 'none',
+                borderRadius: 'var(--sv-radius-md)',
+                color: 'var(--sv-color-text-muted)',
+                cursor: 'pointer',
+              }}
+            >
+              <Icon name="bell" size="lg" aria-hidden />
+            </button>
+          }
+          avatarMenu={
+            <span
+              aria-label="Jamie Doe"
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                width: 36,
+                height: 36,
+                borderRadius: 'var(--sv-radius-full)',
+                background: 'var(--sv-color-accent)',
+                border: '1px solid var(--sv-color-accent)',
+                color: 'var(--sv-color-text-on-accent)',
+                fontSize: 'var(--sv-font-size-xs)',
+                fontWeight: 'var(--sv-font-weight-semibold)',
+              }}
+            >
+              JD
+            </span>
+          }
+        />
+        <div
+          style={{
+            background: 'var(--sv-color-surface-sunken)',
+            padding: 'var(--sv-space-6) var(--sv-space-4)',
+            textAlign: 'center',
+            color: 'var(--sv-color-text-muted)',
+            fontSize: 'var(--sv-font-size-xs)',
+          }}
+        >
+          Plugin content area
+        </div>
+        <MobileFooter
+          onOpenApps={() => setAppsOpen((v) => !v)}
+          launcherOpen={appsOpen}
+          leftIcons={wideFooter ? leftTwo : leftOne}
+          rightIcons={wideFooter ? rightTwo : rightOne}
+        />
+      </div>
+    </>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Main story component
 // ---------------------------------------------------------------------------
@@ -916,11 +1087,19 @@ function MobilePatternsDoc() {
             </div>
           </div>
           <Callout type="info">
-            Plugin developers cannot customise the Launcher Drawer. Use the Drawer component from{' '}
+            Plugin developers cannot customise the Launcher Drawer. Use{' '}
+            <code style={{ fontFamily: 'var(--sv-font-family-mono)', fontSize: '0.8em' }}>
+              MobileAppsDrawer
+            </code>{' '}
+            from{' '}
             <code style={{ fontFamily: 'var(--sv-font-family-mono)', fontSize: '0.8em' }}>
               @sovereignfs/ui
             </code>{' '}
-            if you need a similar bottom-sheet pattern inside your own plugin.
+            if you need this exact grid pattern inside your own plugin (e.g. a mobile-only launcher
+            for the plugin's own sections) — same tile styling as the shell's own drawer (no header
+            row; Drawer's own grab handle/swipe-down/scrim-tap already dismiss it), with the tile
+            list supplied by you via its <code>items</code> prop. See the Component Gallery for a
+            live demo.
           </Callout>
         </Card>
 
@@ -1066,6 +1245,38 @@ function MobilePatternsDoc() {
         </Card>
       </section>
 
+      {/* ── MobileHeader / MobileFooter components (RFC 0088) ── */}
+      <section style={{ marginBottom: 'var(--sv-space-10)' }}>
+        <SectionHeader
+          title="MobileHeader / MobileFooter components"
+          subtitle="The presentational components behind the shell chrome above (RFC 0088). Bell, avatar menu, and the centered launcher are always rendered by the consumer — the header's logo/title (logo defaults to an 'S' badge when omitted) and the footer's leftIcons/rightIcons are the only overridable parts."
+        />
+        <Card padding="md">
+          <MobileHeaderFooterDemo />
+          <div style={{ marginTop: 'var(--sv-space-4)' }}>
+            <Callout type="info">
+              <code style={{ fontFamily: 'var(--sv-font-family-mono)', fontSize: '0.8em' }}>
+                leftIcons
+              </code>{' '}
+              and{' '}
+              <code style={{ fontFamily: 'var(--sv-font-family-mono)', fontSize: '0.8em' }}>
+                rightIcons
+              </code>{' '}
+              must have the same length so the launcher stays centered — a mismatch logs a
+              dev-mode-only{' '}
+              <code style={{ fontFamily: 'var(--sv-font-family-mono)', fontSize: '0.8em' }}>
+                console.error
+              </code>{' '}
+              (never thrown), the same non-fatal guard pattern used by{' '}
+              <code style={{ fontFamily: 'var(--sv-font-family-mono)', fontSize: '0.8em' }}>
+                SwipableMobileCarousel
+              </code>
+              .
+            </Callout>
+          </div>
+        </Card>
+      </section>
+
       {/* ── Touch targets ── */}
       <section style={{ marginBottom: 'var(--sv-space-10)' }}>
         <SectionHeader
@@ -1205,6 +1416,40 @@ function MobilePatternsDoc() {
         </Callout>
       </section>
 
+      {/* ── Layout: swipeable route views ── */}
+      <section style={{ marginBottom: 'var(--sv-space-10)' }}>
+        <SectionHeader
+          title="Layout: swipeable route views"
+          subtitle="Some views are route-based on web but want a different mobile UX — a swipeable filmstrip of the same sibling routes, not a squeeze of a multi-column layout. This is a recurring pattern (sovereign-tasks, sovereign-shopper) — build it with the shared primitives, not a hand-rolled scroller."
+        />
+        <p
+          style={{
+            fontFamily: ff,
+            fontSize: 'var(--sv-font-size-sm)',
+            color: 'var(--sv-color-text-muted)',
+            lineHeight: 1.6,
+          }}
+        >
+          <code style={{ fontFamily: 'var(--sv-font-family-mono)', fontSize: '0.8em' }}>
+            SwipableMobileCarousel
+          </code>{' '}
+          renders full-width slides over a native <code>scroll-snap-type: x</code> container — no
+          hand-rolled pointer/touch dragging. Pair it with <code>useCarouselRouteSync</code> to keep
+          the active slide synced to the URL, and <code>ResponsiveSurface</code>/
+          <code>useResponsiveLayout</code> for the breakpoint fork itself. See the{' '}
+          <em>Interaction Hooks</em> story for the full API and live demos of both hooks.
+        </p>
+        <Callout type="warn">
+          <code style={{ fontFamily: 'var(--sv-font-family-mono)', fontSize: '0.8em' }}>
+            SwipableMobileCarousel
+          </code>{' '}
+          owns rendering and mount-window mechanics only — it has no opinion on where slide data
+          lives. Don&apos;t aggregate cross-slide data or mount a detail overlay (Sheet, Dialog)
+          inside a Slide&apos;s children; mount overlays as a sibling of the carousel instead. See
+          docs/design-system.md&apos;s carousel section for the full rationale.
+        </Callout>
+      </section>
+
       {/* ── Checklist ── */}
       <section style={{ marginBottom: 'var(--sv-space-10)' }}>
         <SectionHeader title="Mobile readiness checklist" />

package/src/stories/NavTabs.stories.tsx

@@ -33,3 +33,21 @@ export const ManyTabs: Story = {
   },
   parameters: { viewport: { defaultViewport: 'mobile' } },
 };
+
+/** Simulates a consumer swapping in a client-side router link (e.g. Next's
+ * `<Link replace>` inside an overlay-shell plugin) instead of a plain `<a>`. */
+export const WithCustomLinkRenderer: Story = {
+  args: {
+    renderLink: (item, linkProps) => (
+      <button
+        type="button"
+        className={linkProps.className}
+        aria-current={linkProps['aria-current']}
+        onClick={() => console.log(`client-side navigate to ${item.href}`)}
+        style={{ background: 'none', border: 'none', cursor: 'pointer', font: 'inherit' }}
+      >
+        {linkProps.children}
+      </button>
+    ),
+  },
+};

package/src/stories/OfflineGate.stories.tsx

@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { OfflineGate } from '../components/OfflineGate/OfflineGate';
+import { EmptyState } from '../components/EmptyState/EmptyState';
+
+const sampleContent = (
+  <div style={{ padding: 'var(--sv-space-4)' }}>
+    <p style={{ margin: 0, fontFamily: 'var(--sv-font-family)' }}>
+      The wrapped content — a user list, a settings form, anything that shouldn&rsquo;t operate
+      against a stale cached snapshot.
+    </p>
+  </div>
+);
+
+const meta = {
+  title: 'Components/OfflineGate',
+  component: OfflineGate,
+  parameters: { layout: 'padded' },
+} satisfies Meta<typeof OfflineGate>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// `OfflineGate` reads the live `useIsOffline()` hook, which Storybook can't
+// drive via args — toggle DevTools > Network > Offline (or throttling) in this
+// preview to see it swap `children` for the blocked state below.
+export const Default: Story = {
+  args: { children: sampleContent, surfaceName: 'Console' },
+};
+
+// The offline state is not independently controllable here (same reason as
+// Default), so this renders the exact EmptyState output OfflineGate produces
+// when useIsOffline() is true, for visual review without a live toggle.
+export const OfflineState: Story = {
+  args: { children: sampleContent, surfaceName: 'Console' },
+  render: () => (
+    <EmptyState
+      icon="alert-triangle"
+      heading="You're offline"
+      description="Console needs a connection — reconnect to continue."
+    />
+  ),
+};

package/src/stories/PageContainer.stories.tsx

@@ -0,0 +1,37 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { PageContainer } from '../components/PageContainer/PageContainer';
+
+const demoBlock = (
+  <div
+    style={{
+      background: 'var(--sv-color-surface-raised)',
+      border: '1px dashed var(--sv-color-border)',
+      borderRadius: 'var(--sv-radius-md)',
+      padding: 'var(--sv-space-4)',
+    }}
+  >
+    Page content goes here. The runtime shell already pads this area — this component only
+    constrains and centers width, it adds no padding of its own.
+  </div>
+);
+
+const meta = {
+  title: 'Components/PageContainer',
+  component: PageContainer,
+  parameters: { layout: 'fullscreen' },
+  args: { children: demoBlock },
+} satisfies Meta<typeof PageContainer>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Medium: Story = {};
+
+export const Small: Story = { args: { maxWidth: 'sm' } };
+export const Large: Story = { args: { maxWidth: 'lg' } };
+export const Full: Story = { args: { maxWidth: 'full' } };
+
+export const MobileViewport: Story = {
+  args: { maxWidth: 'md' },
+  parameters: { viewport: { defaultViewport: 'mobile1' } },
+};

package/src/stories/PageHeader.stories.tsx

@@ -29,3 +29,14 @@ export const WithAction: Story = {
     action: <Button size="sm">Invite user</Button>,
   },
 };
+
+/** For use under a shell/plugin that already renders its own `<h1>` — e.g.
+ * Console's per-page headers sitting below `<h1>Console</h1>`. Visually
+ * identical to the default story; only the rendered tag changes. */
+export const NestedHeadingLevel: Story = {
+  args: {
+    title: 'Users',
+    description: 'Manage who has access to this instance.',
+    headingLevel: 2,
+  },
+};

package/src/stories/ResponsiveSurface.stories.tsx

@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { ResponsiveSurface } from '../components/ResponsiveSurface/ResponsiveSurface';
+
+function demoTree(label: string) {
+  return (
+    <div
+      style={{
+        padding: 'var(--sv-space-6)',
+        textAlign: 'center',
+        fontFamily: 'var(--sv-font-family)',
+        fontSize: 'var(--sv-font-size-sm)',
+        color: 'var(--sv-color-text-primary)',
+        border: '1px dashed var(--sv-color-border)',
+        borderRadius: 'var(--sv-radius-md)',
+      }}
+    >
+      {label}
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Components/ResponsiveSurface',
+  component: ResponsiveSurface,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Renders an entirely different component tree below a breakpoint, not a CSS squeeze of the same one — only the active side is ever mounted. See also the useResponsiveLayout hook for non-JSX values.',
+      },
+    },
+  },
+  args: {
+    web: demoTree('Web tree — e.g. a three-column layout'),
+    mobile: demoTree('Mobile tree — an entirely different component'),
+  },
+} satisfies Meta<typeof ResponsiveSurface>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const MobileViewport: Story = {
+  parameters: { viewport: { defaultViewport: 'mobile1' } },
+};