@sovereignfs/ui 0.54.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/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/PageContainer.stories.tsx

@@ -10,28 +10,73 @@ const demoBlock = (
       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.
+    Page content goes here. This component supplies the page's gutter and constrains its width
+    — the runtime shell contributes neither.
   </div>
 );
 
 const meta = {
   title: 'Components/PageContainer',
   component: PageContainer,
-  parameters: { layout: 'fullscreen' },
+  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>;
 
-export const Medium: Story = {};
+/** Defaults: full width, `md` gutter. */
+export const Default: Story = {};
 
-export const Small: Story = { args: { maxWidth: 'sm' } };
-export const Large: Story = { args: { maxWidth: 'lg' } };
-export const Full: Story = { args: { maxWidth: 'full' } };
+// ── 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>
+    ),
+  ],
+};

package/src/stories/PageHeader.stories.tsx

@@ -5,7 +5,15 @@ import { Button } from '../components/Button/Button';
 const meta = {
   title: 'Components/PageHeader',
   component: PageHeader,
-  parameters: { layout: 'padded' },
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          "A page's title section. Web: title + description on the left, action on the right. Mobile: an optional back button, a single-line title (description drops out), the same action slot, and an optional vertical-ellipsis menu trigger — a compact single row, generalized from Kanban's own hand-rolled MobileBoardHeader. The web/mobile fork is ResponsiveSurface; only one tree is ever mounted.",
+      },
+    },
+  },
 } satisfies Meta<typeof PageHeader>;
 
 export default meta;
@@ -30,6 +38,16 @@ export const WithAction: Story = {
   },
 };
 
+/** A leading icon before the title text, on both breakpoints — e.g. a
+ * folder-detail page pairing `folder-open` with the folder's own name. */
+export const WithIcon: Story = {
+  args: {
+    title: 'Handbook',
+    icon: 'folder-open',
+    action: <Button size="sm">Share</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. */
@@ -40,3 +58,38 @@ export const NestedHeadingLevel: Story = {
     headingLevel: 2,
   },
 };
+
+/** Below the mobile breakpoint: description drops out of the compact row
+ * (generalized from Kanban's own hand-rolled MobileBoardHeader, which has
+ * no subtitle handling either), action stays — same content, adapts itself
+ * if it needs to look different at this width. */
+export const Mobile: Story = {
+  parameters: { viewport: { defaultViewport: 'mobile1' } },
+  args: {
+    title: 'Users',
+    description: 'Manage who has access to this instance.',
+    action: <Button size="sm">Invite user</Button>,
+  },
+};
+
+/** onBack shows a back button to the left of the title — mobile only, no
+ * web equivalent. */
+export const MobileWithBack: Story = {
+  parameters: { viewport: { defaultViewport: 'mobile1' } },
+  args: {
+    title: 'Sv Wallet',
+    onBack: () => undefined,
+  },
+};
+
+/** onMenuClick shows a vertical-ellipsis trigger at the far right — mobile
+ * only, no web equivalent. Typically opens a drawer/menu; PageHeader has no
+ * opinion on what it contains. */
+export const MobileWithMenu: Story = {
+  parameters: { viewport: { defaultViewport: 'mobile1' } },
+  args: {
+    title: 'Sovereign Platform',
+    onBack: () => undefined,
+    onMenuClick: () => undefined,
+  },
+};

package/src/stories/StepStrip.stories.tsx

@@ -0,0 +1,76 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { StepStrip, type StepStripItem } from '../components/StepStrip/StepStrip';
+
+const meta: Meta<typeof StepStrip> = {
+  title: 'Components/StepStrip',
+  component: StepStrip,
+  parameters: { layout: 'padded' },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof StepStrip>;
+
+interface Stop extends StepStripItem {
+  label: string;
+  sublabel: string;
+}
+
+const STOPS: Stop[] = [
+  { id: 'lisbon', label: 'Lisbon', sublabel: 'Aug 26 – 28 · 2 days' },
+  { id: 'porto', label: 'Porto', sublabel: 'Aug 28 – 30 · 2 days' },
+];
+
+const chipStyle = (isActive: boolean) => ({
+  boxSizing: 'border-box' as const,
+  minWidth: '160px',
+  padding: 'var(--sv-space-3) var(--sv-space-4)',
+  borderRadius: 'var(--sv-radius-lg)',
+  border: `1px solid ${isActive ? 'var(--sv-color-text-primary)' : 'var(--sv-color-border)'}`,
+  background: isActive ? 'var(--sv-color-text-primary)' : 'var(--sv-color-surface-raised)',
+  color: isActive ? 'var(--sv-color-surface)' : 'var(--sv-color-text-primary)',
+  cursor: 'pointer',
+  textAlign: 'left' as const,
+});
+
+function StopStripDemo() {
+  const [activeId, setActiveId] = useState<string>('lisbon');
+
+  return (
+    <StepStrip
+      items={STOPS}
+      activeId={activeId}
+      aria-label="Trip stops"
+      onAdd={() => alert('Add a stop')}
+      addLabel="Add a stop"
+      renderItem={(stop, { isActive }) => (
+        <button type="button" style={chipStyle(isActive)} onClick={() => setActiveId(stop.id)}>
+          <div style={{ fontWeight: 600, fontSize: 'var(--sv-font-size-sm)' }}>{stop.label}</div>
+          <div style={{ fontSize: 'var(--sv-font-size-xs)', opacity: 0.8 }}>{stop.sublabel}</div>
+        </button>
+      )}
+    />
+  );
+}
+
+export const Default: Story = {
+  render: () => <StopStripDemo />,
+  name: 'Stop strip (click to select, trailing add chip)',
+};
+
+export const NoAddAffordance: Story = {
+  render: () => (
+    <StepStrip
+      items={STOPS}
+      activeId="porto"
+      aria-label="Trip stops"
+      renderItem={(stop, { isActive }) => (
+        <div style={chipStyle(isActive)}>
+          <div style={{ fontWeight: 600, fontSize: 'var(--sv-font-size-sm)' }}>{stop.label}</div>
+          <div style={{ fontSize: 'var(--sv-font-size-xs)', opacity: 0.8 }}>{stop.sublabel}</div>
+        </div>
+      )}
+    />
+  ),
+};

package/src/stories/SwipableMobileCarousel.stories.tsx

@@ -234,6 +234,40 @@ function DotsStandaloneDemo() {
   );
 }
 
+// Matches the real scenario `density="compact"` was added for: a many-list
+// mobile task manager whose default-spacing dot row reads as long/cramped in
+// a 375px viewport — see docs/design-system.md's carousel section.
+const MANY_LABELS = [
+  'Lists',
+  'Starred',
+  'List 1',
+  'Groceries',
+  'Work',
+  'List 2',
+  'List 3',
+  'List 4',
+  'List 5',
+  'List 6',
+  'List 7',
+  'List 8',
+];
+
+function DotsManyDemo({ density }: { density?: 'default' | 'compact' }) {
+  const [activeIndex, setActiveIndex] = useState(2);
+  return (
+    <div style={{ maxWidth: 375, margin: '0 auto' }}>
+      <SwipableMobileCarouselDots
+        count={MANY_LABELS.length}
+        activeIndex={activeIndex}
+        onJump={setActiveIndex}
+        labels={MANY_LABELS}
+        aria-label="Task lists"
+        density={density}
+      />
+    </div>
+  );
+}
+
 const meta = {
   title: 'Components/SwipableMobileCarousel',
   component: SwipableMobileCarousel,
@@ -302,3 +336,27 @@ export const DotsStandalone: Story = {
     },
   },
 };
+
+export const DotsManyDefault: Story = {
+  render: () => <DotsManyDemo />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Default density with 12 slides in a 375px viewport — the row reads as long/cramped once an instance has more than a handful of lists. Compare to DotsManyCompact.',
+      },
+    },
+  },
+};
+
+export const DotsManyCompact: Story = {
+  render: () => <DotsManyDemo density="compact" />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'density="compact" halves the gap between dots and shrinks each dot\'s own hit target from 20px to 16px — the visible 6px dot itself is unchanged; only its surrounding tap-target box shrinks. Opt-in: every existing consumer\'s spacing is unchanged unless it passes this prop.',
+      },
+    },
+  },
+};