@sovereignfs/ui 0.45.0 → 0.83.1

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;
@@ -29,3 +37,59 @@ export const WithAction: Story = {
     action: <Button size="sm">Invite user</Button>,
   },
 };
+
+/** 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. */
+export const NestedHeadingLevel: Story = {
+  args: {
+    title: 'Users',
+    description: 'Manage who has access to this instance.',
+    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/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' } },
+};

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

@@ -0,0 +1,362 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { SwipableMobileCarousel } from '../components/SwipableMobileCarousel/SwipableMobileCarousel';
+import { SwipableMobileCarouselSlide } from '../components/SwipableMobileCarousel/SwipableMobileCarouselSlide';
+import { SwipableMobileCarouselSlideHeader } from '../components/SwipableMobileCarousel/SwipableMobileCarouselSlideHeader';
+import { SwipableMobileCarouselSlideBody } from '../components/SwipableMobileCarousel/SwipableMobileCarouselSlideBody';
+import { SwipableMobileCarouselSlideFooter } from '../components/SwipableMobileCarousel/SwipableMobileCarouselSlideFooter';
+import { SwipableMobileCarouselDots } from '../components/SwipableMobileCarouselDots/SwipableMobileCarouselDots';
+
+const SLIDES = [
+  { key: 'lists', label: 'Lists' },
+  { key: 'groceries', label: 'Groceries' },
+  { key: 'errands', label: 'Errands' },
+  { key: 'work', label: 'Work' },
+];
+
+function slideBodyStyle(): React.CSSProperties {
+  return {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    height: '100%',
+    fontFamily: 'var(--sv-font-family)',
+    color: 'var(--sv-color-text-primary)',
+  };
+}
+
+function headerStyle(): React.CSSProperties {
+  return {
+    padding: 'var(--sv-space-4)',
+    fontFamily: 'var(--sv-font-family)',
+    fontWeight: 'var(--sv-font-weight-semibold)',
+    color: 'var(--sv-color-text-primary)',
+    borderBottom: '1px solid var(--sv-color-border)',
+  };
+}
+
+function CarouselFrame({ children }: { children: React.ReactNode }) {
+  return (
+    <div
+      style={{
+        height: 480,
+        maxWidth: 375,
+        margin: '0 auto',
+        border: '1px solid var(--sv-color-border)',
+        borderRadius: 'var(--sv-radius-md)',
+        overflow: 'hidden',
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+function DefaultDemo() {
+  const [activeIndex, setActiveIndex] = useState(0);
+  return (
+    <CarouselFrame>
+      <SwipableMobileCarousel
+        activeIndex={activeIndex}
+        onSettle={setActiveIndex}
+        aria-label="Task lists"
+      >
+        {SLIDES.map((slide) => (
+          <SwipableMobileCarouselSlide key={slide.key} slideKey={slide.key} label={slide.label}>
+            <SwipableMobileCarouselSlideHeader>
+              <div style={headerStyle()}>{slide.label}</div>
+            </SwipableMobileCarouselSlideHeader>
+            <SwipableMobileCarouselSlideBody>
+              <div style={slideBodyStyle()}>{slide.label} content</div>
+            </SwipableMobileCarouselSlideBody>
+          </SwipableMobileCarouselSlide>
+        ))}
+      </SwipableMobileCarousel>
+    </CarouselFrame>
+  );
+}
+
+function LazyLoadingBodyDemo() {
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [loadedKeys, setLoadedKeys] = useState<Set<string>>(new Set(['lists']));
+
+  function simulateLoad(key: string) {
+    setTimeout(() => setLoadedKeys((s) => new Set(s).add(key)), 1200);
+  }
+
+  return (
+    <CarouselFrame>
+      <SwipableMobileCarousel
+        activeIndex={activeIndex}
+        onSettle={(i) => {
+          setActiveIndex(i);
+          const key = SLIDES[i]?.key;
+          if (key && !loadedKeys.has(key)) simulateLoad(key);
+        }}
+        aria-label="Task lists (simulated fetch)"
+      >
+        {SLIDES.map((slide) => (
+          <SwipableMobileCarouselSlide key={slide.key} slideKey={slide.key} label={slide.label}>
+            {/* The title renders immediately from already-known metadata —
+                only the Body below waits on its own simulated 1.2s fetch. */}
+            <SwipableMobileCarouselSlideHeader>
+              <div style={headerStyle()}>{slide.label}</div>
+            </SwipableMobileCarouselSlideHeader>
+            <SwipableMobileCarouselSlideBody loading={!loadedKeys.has(slide.key)}>
+              <div style={slideBodyStyle()}>{slide.label} content (loaded)</div>
+            </SwipableMobileCarouselSlideBody>
+          </SwipableMobileCarouselSlide>
+        ))}
+      </SwipableMobileCarousel>
+    </CarouselFrame>
+  );
+}
+
+function CustomIndicatorDemo() {
+  const [activeIndex, setActiveIndex] = useState(0);
+  return (
+    <CarouselFrame>
+      <SwipableMobileCarousel
+        activeIndex={activeIndex}
+        onSettle={setActiveIndex}
+        aria-label="Task lists"
+        renderIndicator={({ count, activeIndex: i, onJump }) => (
+          <div
+            style={{
+              position: 'absolute',
+              top: 8,
+              right: 8,
+              fontFamily: 'var(--sv-font-family)',
+              fontSize: 'var(--sv-font-size-sm)',
+              color: 'var(--sv-color-text-primary)',
+              background: 'var(--sv-color-surface-raised)',
+              borderRadius: 'var(--sv-radius-md)',
+              padding: 'var(--sv-space-1) var(--sv-space-2)',
+            }}
+          >
+            <button type="button" onClick={() => onJump(Math.max(0, i - 1))}>
+              ‹
+            </button>{' '}
+            {i + 1} / {count}{' '}
+            <button type="button" onClick={() => onJump(Math.min(count - 1, i + 1))}>
+              ›
+            </button>
+          </div>
+        )}
+      >
+        {SLIDES.map((slide) => (
+          <SwipableMobileCarouselSlide key={slide.key} slideKey={slide.key} label={slide.label}>
+            <SwipableMobileCarouselSlideHeader>
+              <div style={headerStyle()}>{slide.label}</div>
+            </SwipableMobileCarouselSlideHeader>
+            <SwipableMobileCarouselSlideBody>
+              <div style={slideBodyStyle()}>{slide.label} content</div>
+            </SwipableMobileCarouselSlideBody>
+          </SwipableMobileCarouselSlide>
+        ))}
+      </SwipableMobileCarousel>
+    </CarouselFrame>
+  );
+}
+
+function NoIndicatorDemo() {
+  const [activeIndex, setActiveIndex] = useState(0);
+  return (
+    <CarouselFrame>
+      <SwipableMobileCarousel
+        activeIndex={activeIndex}
+        onSettle={setActiveIndex}
+        aria-label="Task lists"
+        renderIndicator={null}
+      >
+        {SLIDES.map((slide) => (
+          <SwipableMobileCarouselSlide key={slide.key} slideKey={slide.key} label={slide.label}>
+            <SwipableMobileCarouselSlideHeader>
+              <div style={headerStyle()}>{slide.label}</div>
+            </SwipableMobileCarouselSlideHeader>
+            <SwipableMobileCarouselSlideBody>
+              <div style={slideBodyStyle()}>{slide.label} content</div>
+            </SwipableMobileCarouselSlideBody>
+          </SwipableMobileCarouselSlide>
+        ))}
+      </SwipableMobileCarousel>
+    </CarouselFrame>
+  );
+}
+
+function FooterDemo() {
+  const [activeIndex, setActiveIndex] = useState(0);
+  return (
+    <CarouselFrame>
+      <SwipableMobileCarousel
+        activeIndex={activeIndex}
+        onSettle={setActiveIndex}
+        aria-label="Task lists"
+      >
+        {SLIDES.map((slide) => (
+          <SwipableMobileCarouselSlide key={slide.key} slideKey={slide.key} label={slide.label}>
+            <SwipableMobileCarouselSlideHeader>
+              <div style={headerStyle()}>{slide.label}</div>
+            </SwipableMobileCarouselSlideHeader>
+            <SwipableMobileCarouselSlideBody>
+              <div style={slideBodyStyle()}>{slide.label} content</div>
+            </SwipableMobileCarouselSlideBody>
+            <SwipableMobileCarouselSlideFooter>
+              <div
+                style={{
+                  padding: 'var(--sv-space-3) var(--sv-space-4)',
+                  borderTop: '1px solid var(--sv-color-border)',
+                  fontFamily: 'var(--sv-font-family)',
+                  fontSize: 'var(--sv-font-size-sm)',
+                  color: 'var(--sv-color-text-muted)',
+                }}
+              >
+                + Add to {slide.label}
+              </div>
+            </SwipableMobileCarouselSlideFooter>
+          </SwipableMobileCarouselSlide>
+        ))}
+      </SwipableMobileCarousel>
+    </CarouselFrame>
+  );
+}
+
+function DotsStandaloneDemo() {
+  const [activeIndex, setActiveIndex] = useState(0);
+  return (
+    <SwipableMobileCarouselDots
+      count={4}
+      activeIndex={activeIndex}
+      onJump={setActiveIndex}
+      labels={['Lists', 'Groceries', 'Errands', 'Work']}
+      aria-label="Task lists"
+    />
+  );
+}
+
+// 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,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          "A compound component for swiping between full-width slides (each an independent route/view on mobile), wrapping useSnapCarousel. Owns rendering and mount-window mechanics only — it has no opinion on where slide data lives. Do NOT aggregate cross-slide data or mount a detail overlay (Sheet, Dialog) inside a Slide's children; see docs/design-system.md's carousel section.",
+      },
+    },
+  },
+  // Every story below supplies its own render(), which is stateful (activeIndex
+  // lives in useState) — these args only satisfy the required-prop typing.
+  args: {
+    activeIndex: 0,
+    onSettle: () => {},
+    'aria-label': 'Task lists',
+    children: null,
+  },
+} satisfies Meta<typeof SwipableMobileCarousel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { render: () => <DefaultDemo /> };
+
+export const LazyLoadingBody: Story = {
+  render: () => <LazyLoadingBodyDemo />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Swipe to a new slide — its title renders immediately from already-known metadata, while only the Body region shows a brief loading placeholder for its simulated 1.2s fetch. This is the fix for the "whole slide blanks out, title included, until its own fetch resolves" bug.',
+      },
+    },
+  },
+};
+
+export const CustomIndicator: Story = { render: () => <CustomIndicatorDemo /> };
+
+export const NoIndicator: Story = { render: () => <NoIndicatorDemo /> };
+
+export const WithFooter: Story = { render: () => <FooterDemo /> };
+
+export const MobileViewport: Story = {
+  render: () => <DefaultDemo />,
+  parameters: { viewport: { defaultViewport: 'mobile1' } },
+};
+
+// ---------------------------------------------------------------------------
+// SwipableMobileCarouselDots — standalone, also this carousel's default
+// indicator. Grouped in this file rather than its own (Table's sub-parts
+// share one story file too), though it has its own component subfolder and
+// barrel export for independent reuse.
+// ---------------------------------------------------------------------------
+
+export const DotsStandalone: Story = {
+  render: () => <DotsStandaloneDemo />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'SwipableMobileCarouselDots used on its own, outside a carousel — a real role="tablist"/role="tab" component (tappable, labeled, focusable), unlike the aria-hidden decorative dots both sovereign-tasks and sovereign-shopper currently hand-roll.',
+      },
+    },
+  },
+};
+
+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.',
+      },
+    },
+  },
+};