@sovereignfs/ui 0.45.0 → 0.83.1

package/src/stories/MenuEntries.stories.tsx

@@ -0,0 +1,86 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { MenuEntries } from '../components/Menu/Menu';
+import type { MenuEntry } from '../components/Menu/Menu';
+
+/** Plain action entries — no separator, label, or checkable state. */
+const actionItems: MenuEntry[] = [
+  { label: 'Rename', icon: 'pencil' },
+  { label: 'Duplicate', icon: 'plus' },
+  { label: 'Delete', icon: 'trash-2', destructive: true },
+];
+
+const meta = {
+  title: 'Components/MenuEntries',
+  component: MenuEntries,
+  parameters: { layout: 'padded' },
+  args: {
+    items: actionItems,
+    onSelect: (entry) => console.log(`MenuEntries selected: ${entry.label}`),
+  },
+} satisfies Meta<typeof MenuEntries>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * The `<ul role="menu">` item list itself, factored out of `Menu` so other
+ * adaptive-surface components (`ContextMenu`, `Menubar`) can render the exact
+ * same items/destructive/checked/icon markup inside their own positioning
+ * shell (a floating `Popover` panel, a `Drawer` bottom sheet, or a `Menubar`
+ * flyout) instead of re-deriving it and risking drift. Renders with no panel
+ * chrome of its own here — the surrounding background, border, and shadow
+ * belong to whichever surface hosts it; see `Menu` in this gallery for the
+ * composed, positioned result.
+ */
+export const Default: Story = {};
+
+/**
+ * The full entry vocabulary in one list: a `{ type: 'label' }` section
+ * heading, a checkable `menuitemradio` group (pass `checked` on every item in
+ * the group, including the unchecked ones, so their labels stay aligned with
+ * the checked one's reserved checkmark gutter), a `{ type: 'separator' }`
+ * divider, and a run of plain/destructive actions — the same composition
+ * `Menu`'s own "List actions" demo (Components/Menu) renders.
+ */
+export const GroupedWithLabelAndSeparator: Story = {
+  args: {
+    items: [
+      { type: 'label', label: 'Sort by' },
+      { label: 'Manual', checked: true },
+      { label: 'Title', checked: false },
+      { label: 'Due date', checked: false },
+      { type: 'separator' },
+      ...actionItems,
+    ],
+  },
+};
+
+/**
+ * A `disabled` item stays in the list but renders `disabled` on its
+ * `<button>` — it can't be activated and `onSelect` never fires for it.
+ */
+export const WithDisabledItem: Story = {
+  args: {
+    items: [
+      { label: 'Rename', icon: 'pencil' },
+      { label: 'Duplicate', icon: 'plus', disabled: true },
+      { label: 'Delete', icon: 'trash-2', destructive: true },
+    ],
+  },
+};
+
+/**
+ * An `href` entry renders as an `<a role="menuitem">` instead of a
+ * `<button>` — same href-vs-onClick convention as `MobileAppsDrawer`'s
+ * items — for a pure navigation entry that needs no extra `onSelect`.
+ */
+export const WithLinkItems: Story = {
+  args: {
+    items: [
+      { label: 'View profile', icon: 'user', href: '#profile' },
+      { label: 'Settings', icon: 'settings', href: '#settings' },
+      { type: 'separator' },
+      { label: 'Sign out', icon: 'log-out', destructive: true },
+    ],
+  },
+};

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/NavList.stories.tsx

@@ -0,0 +1,147 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { NavList } from '../components/NavList/NavList';
+
+const overviewGroup = {
+  id: 'overview',
+  items: [
+    { id: 'overview', label: 'Overview', href: '#overview', icon: 'layout-dashboard' as const },
+  ],
+};
+
+const peopleGroup = {
+  id: 'people',
+  label: 'People',
+  items: [
+    { id: 'users', label: 'Users', href: '#users', icon: 'users' as const },
+    { id: 'groups', label: 'Groups', href: '#groups', icon: 'layers' as const },
+  ],
+};
+
+const appsGroup = {
+  id: 'apps',
+  label: 'Apps',
+  items: [
+    { id: 'plugins', label: 'Apps', href: '#plugins', icon: 'layout-grid' as const },
+    { id: 'entitlements', label: 'Entitlements', href: '#entitlements', icon: 'shield' as const },
+  ],
+};
+
+const meta = {
+  title: 'Components/NavList',
+  component: NavList,
+  parameters: { layout: 'padded' },
+  args: {
+    groups: [overviewGroup, peopleGroup, appsGroup],
+    variant: 'static',
+    'aria-label': 'Example sections',
+  },
+} satisfies Meta<typeof NavList>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Desktop sidebar shape — active row highlighted, no chevron. */
+export const StaticActiveItem: Story = {
+  args: {
+    groups: [
+      {
+        id: 'overview',
+        items: [
+          {
+            id: 'overview',
+            label: 'Overview',
+            href: '#overview',
+            icon: 'layout-dashboard',
+            active: true,
+          },
+        ],
+      },
+      peopleGroup,
+      appsGroup,
+    ],
+  },
+};
+
+/**
+ * `density="compact"` — shrinks row height/padding for a short, always-
+ * visible `static` list (e.g. Warden's sidebar "New chat"/"Providers"/
+ * "Models" rows above its longer session list), where the default's full
+ * touch-target height reads as needlessly spaced out. Only meaningful with
+ * `variant="static"`; every other story on this page stays at the default
+ * density, unaffected.
+ */
+export const CompactDensity: Story = {
+  args: {
+    density: 'compact',
+    groups: [
+      {
+        id: 'primary',
+        items: [
+          { id: 'new', label: 'New chat', href: '#new', icon: 'plus' },
+          { id: 'providers', label: 'Providers', href: '#providers', icon: 'link' },
+          { id: 'models', label: 'Models', href: '#models', icon: 'layers' },
+        ],
+      },
+    ],
+  },
+};
+
+/** Mobile index shape — every row gets a trailing chevron, no active state; tapping navigates to a full-screen section. */
+export const Drilldown: Story = {
+  args: { variant: 'drilldown' },
+  parameters: { viewport: { defaultViewport: 'mobile' } },
+};
+
+/** `group.label` omitted entirely renders a flat list with no section headers. */
+export const Ungrouped: Story = {
+  args: {
+    groups: [
+      {
+        id: 'flat',
+        items: [
+          { id: 'a', label: 'First', href: '#a', icon: 'house' },
+          { id: 'b', label: 'Second', href: '#b', icon: 'settings' },
+        ],
+      },
+    ],
+  },
+};
+
+/** Simulates a consumer swapping in a client-side router link (e.g. Next's `<Link>`) instead of a plain `<a>`. */
+export const WithCustomLinkRenderer: Story = {
+  args: {
+    groups: [
+      {
+        id: 'overview',
+        items: [
+          {
+            id: 'overview',
+            label: 'Overview',
+            href: '#overview',
+            icon: 'layout-dashboard',
+            active: true,
+          },
+        ],
+      },
+      peopleGroup,
+    ],
+    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',
+          textAlign: 'left',
+          width: '100%',
+        }}
+      >
+        {linkProps.children}
+      </button>
+    ),
+  },
+};

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,82 @@
+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. This component supplies the page&apos;s gutter and constrains its width
+    — the runtime shell contributes neither.
+  </div>
+);
+
+const meta = {
+  title: 'Components/PageContainer',
+  component: PageContainer,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'The wrapper every plugin page renders through. `padding` is the page gutter (the ' +
+          'runtime shell no longer applies one) and `maxWidth` constrains content, padding ' +
+          'included. Both default to the common case: a full-width page with the standard ' +
+          '32px/16px gutter.',
+      },
+    },
+  },
+  args: { children: demoBlock },
+} satisfies Meta<typeof PageContainer>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Defaults: full width, `md` gutter. */
+export const Default: Story = {};
+
+// ── maxWidth ──────────────────────────────────────────────────────────────
+
+export const WidthSmall: Story = { args: { maxWidth: 'sm' } };
+export const WidthMedium: Story = { args: { maxWidth: 'md' } };
+export const WidthLarge: Story = { args: { maxWidth: 'lg' } };
+
+// ── padding ───────────────────────────────────────────────────────────────
+
+/** For a page whose ancestor already supplies the gutter, or a full-bleed layout. */
+export const PaddingNone: Story = { args: { padding: 'none' } };
+export const PaddingSmall: Story = { args: { padding: 'sm' } };
+export const PaddingLarge: Story = { args: { padding: 'lg' } };
+
+/** Every gutter step tightens below 768px. */
+export const MobileViewport: Story = {
+  args: { maxWidth: 'md' },
+  parameters: { viewport: { defaultViewport: 'mobile1' } },
+};
+
+/**
+ * An ancestor that already pads its content sets `--sv-page-gutter: 0` and
+ * PageContainer stands its own gutter down — how `Dialog` keeps an overlay
+ * plugin from being padded twice when the same page renders inside it.
+ */
+export const GutterSuppressedByAncestor: Story = {
+  args: { maxWidth: 'md' },
+  decorators: [
+    (Story) => (
+      <div
+        style={{
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any -- CSS custom property
+          ['--sv-page-gutter' as any]: '0px',
+          border: '1px solid var(--sv-color-border)',
+          padding: 'var(--sv-space-6)',
+        }}
+      >
+        <Story />
+      </div>
+    ),
+  ],
+};