@sovereignfs/ui 0.41.0 → 0.54.0

package/src/stories/DeviceOnlyGate.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { DeviceOnlyGate } from '../components/DeviceOnlyGate/DeviceOnlyGate';
+
+const sampleContent = (
+  <div style={{ padding: 'var(--sv-space-4)' }}>
+    <p style={{ margin: 0, fontFamily: 'var(--sv-font-family)' }}>
+      The wrapped content — a wallet's card list, a health log, anything a `device-only` plugin
+      keeps entirely on-device.
+    </p>
+  </div>
+);
+
+const meta = {
+  title: 'Components/DeviceOnlyGate',
+  component: DeviceOnlyGate,
+  parameters: { layout: 'padded' },
+} satisfies Meta<typeof DeviceOnlyGate>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// `available` is the caller's own isDeviceOnlyTierAvailable() result — a
+// real bridge-handshake check, not something this story can drive live, so
+// it's passed directly as an arg here instead.
+export const Available: Story = {
+  args: { children: sampleContent, available: true, surfaceName: 'Wallet' },
+};
+
+export const Restricted: Story = {
+  args: { children: sampleContent, available: false, surfaceName: 'Wallet' },
+};
+
+export const RestrictedGenericPhrasing: Story = {
+  args: { children: sampleContent, available: false },
+};

package/src/stories/DeviceStorageKeyGate.stories.tsx

@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { DeviceStorageKeyGate } from '../components/DeviceStorageKeyGate/DeviceStorageKeyGate';
+
+const sampleContent = (
+  <div style={{ padding: 'var(--sv-space-4)' }}>
+    <p style={{ margin: 0, fontFamily: 'var(--sv-font-family)' }}>
+      The wrapped content — a notes list, a health log, anything a `device-only` plugin keeps
+      entirely on-device.
+    </p>
+  </div>
+);
+
+const setupAction = (
+  <a href="/account/security" style={{ color: 'var(--sv-color-accent)' }}>
+    Go to Account → Security
+  </a>
+);
+
+const meta = {
+  title: 'Components/DeviceStorageKeyGate',
+  component: DeviceStorageKeyGate,
+  parameters: { layout: 'padded' },
+} satisfies Meta<typeof DeviceStorageKeyGate>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// `status` is the caller's own getDeviceStorageKeyStatus() result — an OPFS
+// read this story can't drive live, so it's passed directly as an arg here.
+export const SetUp: Story = {
+  args: { children: sampleContent, status: 'set-up', surfaceName: 'Notes' },
+};
+
+export const NotSetUp: Story = {
+  args: {
+    children: sampleContent,
+    status: 'not-set-up',
+    surfaceName: 'Notes',
+    setupAction,
+  },
+};
+
+export const NotSetUpGenericPhrasing: Story = {
+  args: { children: sampleContent, status: 'not-set-up', setupAction },
+};
+
+export const Unsupported: Story = {
+  args: { children: sampleContent, status: 'unsupported', surfaceName: 'Notes' },
+};
+
+export const NoDeviceAuth: Story = {
+  args: { children: sampleContent, status: 'no-device-auth', surfaceName: 'Notes' },
+};
+
+export const Checking: Story = {
+  args: { children: sampleContent, status: 'checking', surfaceName: 'Notes' },
+};

package/src/stories/InteractionHooks.stories.tsx

@@ -2,11 +2,17 @@ import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Card } from '../components/Card/Card';
 import {
+  useCarouselRouteSync,
   useCommitOnEnterOrBlur,
   useDoubleTapHandler,
   useIsMobile,
+  useIsOffline,
   useLongPress,
+  useOfflineTileState,
+  useResponsiveLayout,
   useSingleOrDoubleTap,
+  useSnapCarousel,
+  useSwipeReveal,
 } from '../hooks';
 
 // ---------------------------------------------------------------------------
@@ -331,6 +337,385 @@ function IsMobileDemo() {
   );
 }
 
+function IsOfflineDemo() {
+  const isOffline = useIsOffline();
+  return (
+    <div
+      style={{
+        padding: 'var(--sv-space-4)',
+        borderRadius: 'var(--sv-radius-md)',
+        background: isOffline
+          ? 'var(--sv-color-warning-surface)'
+          : 'var(--sv-color-success-surface)',
+        color: isOffline ? 'var(--sv-color-warning-text)' : 'var(--sv-color-success-text)',
+        fontFamily: ff,
+        fontSize: 'var(--sv-font-size-sm)',
+        fontWeight: 600,
+        textAlign: 'center',
+      }}
+    >
+      useIsOffline() → {String(isOffline)} — toggle DevTools &gt; Network &gt; Offline (or your OS's
+      airplane mode) to see this flip.
+    </div>
+  );
+}
+
+function OfflineTileStateDemo() {
+  const [tier, setTier] = useState<'none' | 'offline-first' | 'device-only'>('device-only');
+  const [deviceOnlyAvailable, setDeviceOnlyAvailable] = useState(false);
+  const state = useOfflineTileState(tier === 'none' ? undefined : tier, deviceOnlyAvailable);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--sv-space-3)' }}>
+      <div
+        style={{ display: 'flex', gap: 'var(--sv-space-4)', alignItems: 'center', fontFamily: ff }}
+      >
+        <label style={{ fontSize: 'var(--sv-font-size-sm)' }}>
+          offline tier:{' '}
+          <select value={tier} onChange={(e) => setTier(e.target.value as typeof tier)}>
+            <option value="none">(none)</option>
+            <option value="offline-first">offline-first</option>
+            <option value="device-only">device-only</option>
+          </select>
+        </label>
+        <label style={{ fontSize: 'var(--sv-font-size-sm)' }}>
+          <input
+            type="checkbox"
+            checked={deviceOnlyAvailable}
+            onChange={(e) => setDeviceOnlyAvailable(e.target.checked)}
+          />{' '}
+          deviceOnlyAvailable
+        </label>
+      </div>
+      <div
+        style={{
+          padding: 'var(--sv-space-4)',
+          borderRadius: 'var(--sv-radius-md)',
+          background:
+            state === 'connectivity-dimmed'
+              ? 'var(--sv-color-warning-surface)'
+              : state === 'capability-restricted'
+                ? 'var(--sv-color-info-surface)'
+                : 'var(--sv-color-success-surface)',
+          color:
+            state === 'connectivity-dimmed'
+              ? 'var(--sv-color-warning-text)'
+              : state === 'capability-restricted'
+                ? 'var(--sv-color-info-text)'
+                : 'var(--sv-color-success-text)',
+          fontFamily: ff,
+          fontSize: 'var(--sv-font-size-sm)',
+          fontWeight: 600,
+          textAlign: 'center',
+        }}
+      >
+        useOfflineTileState() → {String(state)}
+      </div>
+      <p
+        style={{
+          margin: 0,
+          fontFamily: ff,
+          fontSize: 'var(--sv-font-size-xs)',
+          color: 'var(--sv-color-text-muted)',
+        }}
+      >
+        connectivity-dimmed also reacts live to DevTools &gt; Network &gt; Offline — try it with
+        tier set to (none).
+      </p>
+    </div>
+  );
+}
+
+function SwipeRevealDemo() {
+  const [open, setOpen] = useState(false);
+  const [events, setEvents] = useState<string[]>([]);
+  const log = (msg: string) =>
+    setEvents((e) => [...e, `${new Date().toLocaleTimeString()} — ${msg}`]);
+  const { rowRef, handlers } = useSwipeReveal({
+    revealWidth: 88,
+    open,
+    onOpen: () => {
+      setOpen(true);
+      log('opened');
+    },
+    onClose: () => {
+      setOpen(false);
+      log('closed');
+    },
+  });
+
+  return (
+    <div>
+      <div
+        style={{
+          position: 'relative',
+          overflow: 'hidden',
+          borderRadius: 'var(--sv-radius-md)',
+          border: '1px solid var(--sv-color-border)',
+        }}
+      >
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            display: 'flex',
+            justifyContent: 'flex-end',
+          }}
+        >
+          <button
+            type="button"
+            onClick={() => {
+              setOpen(false);
+              log('Delete tapped');
+            }}
+            style={{
+              width: 88,
+              border: 'none',
+              background: 'var(--sv-color-error-surface)',
+              color: 'var(--sv-color-error-text)',
+              fontFamily: ff,
+              fontSize: 'var(--sv-font-size-sm)',
+              fontWeight: 600,
+              cursor: 'pointer',
+            }}
+          >
+            Delete
+          </button>
+        </div>
+        <div
+          ref={rowRef}
+          {...handlers}
+          style={{
+            position: 'relative',
+            padding: 'var(--sv-space-4)',
+            background: 'var(--sv-color-surface)',
+            fontFamily: ff,
+            fontSize: 'var(--sv-font-size-sm)',
+            color: 'var(--sv-color-text-primary)',
+            touchAction: 'pan-y',
+            transform: open ? 'translateX(-88px)' : undefined,
+            transition: 'transform 150ms ease-out',
+          }}
+        >
+          Drag me left to reveal Delete
+        </div>
+      </div>
+      <EventLog events={events} />
+      <Callout type="info">
+        Drag with a mouse in this preview, or touch on a real device/device toolbar. The hook only
+        writes an imperative transform during the drag itself — the CSS transition above only takes
+        over once the gesture resolves to open or closed on release.
+      </Callout>
+    </div>
+  );
+}
+
+function SnapCarouselDemo() {
+  const slides = ['Lists', 'Groceries', 'Errands'];
+  const [index, setIndex] = useState(0);
+  const [events, setEvents] = useState<string[]>([]);
+  const log = (msg: string) =>
+    setEvents((e) => [...e, `${new Date().toLocaleTimeString()} — ${msg}`]);
+  const { scrollRef, scrollToIndex } = useSnapCarousel({
+    itemCount: slides.length,
+    onSettle: (i) => {
+      setIndex(i);
+      log(`settled on slide ${i}`);
+    },
+  });
+
+  return (
+    <div>
+      <div
+        ref={scrollRef}
+        style={{
+          display: 'flex',
+          overflowX: 'auto',
+          scrollSnapType: 'x mandatory',
+          borderRadius: 'var(--sv-radius-md)',
+          border: '1px solid var(--sv-color-border)',
+        }}
+      >
+        {slides.map((label, i) => (
+          <div
+            key={label}
+            style={{
+              flex: '0 0 100%',
+              scrollSnapAlign: 'start',
+              padding: 'var(--sv-space-6)',
+              textAlign: 'center',
+              fontFamily: ff,
+              fontSize: 'var(--sv-font-size-sm)',
+              color: 'var(--sv-color-text-primary)',
+              background:
+                i === index ? 'var(--sv-color-surface-sunken)' : 'var(--sv-color-surface)',
+            }}
+          >
+            {label}
+          </div>
+        ))}
+      </div>
+      <div style={{ display: 'flex', gap: 'var(--sv-space-2)', marginTop: 'var(--sv-space-3)' }}>
+        {slides.map((label, i) => (
+          <button
+            key={label}
+            type="button"
+            onClick={() => scrollToIndex(i)}
+            style={{
+              padding: 'var(--sv-space-1) var(--sv-space-3)',
+              borderRadius: 'var(--sv-radius-md)',
+              border: '1px solid var(--sv-color-border)',
+              background: i === index ? 'var(--sv-color-accent)' : 'var(--sv-color-surface)',
+              color:
+                i === index ? 'var(--sv-color-text-on-accent)' : 'var(--sv-color-text-primary)',
+              fontFamily: ff,
+              fontSize: '0.75rem',
+              cursor: 'pointer',
+            }}
+          >
+            Slide {i}
+          </button>
+        ))}
+      </div>
+      <EventLog events={events} />
+      <Callout type="info">
+        Swipe or scroll the strip above horizontally, or use the buttons. Settle detection is
+        debounced (120ms default) rather than tied to the <code>scrollend</code> event, which
+        pre-17.4 iOS Safari/WKWebView doesn&apos;t support.
+      </Callout>
+    </div>
+  );
+}
+
+function ResponsiveLayoutDemo() {
+  const { isMobile, value } = useResponsiveLayout({
+    web: (
+      <div
+        style={{
+          padding: 'var(--sv-space-6)',
+          textAlign: 'center',
+          fontFamily: ff,
+          fontSize: 'var(--sv-font-size-sm)',
+          color: 'var(--sv-color-text-primary)',
+        }}
+      >
+        Web tree — a three-column layout, for example.
+      </div>
+    ),
+    mobile: (
+      <div
+        style={{
+          padding: 'var(--sv-space-6)',
+          textAlign: 'center',
+          fontFamily: ff,
+          fontSize: 'var(--sv-font-size-sm)',
+          color: 'var(--sv-color-text-primary)',
+        }}
+      >
+        Mobile tree — an entirely different component, not a CSS squeeze.
+      </div>
+    ),
+  });
+
+  return (
+    <div>
+      <div
+        style={{
+          borderRadius: 'var(--sv-radius-md)',
+          border: '1px solid var(--sv-color-border)',
+          background: 'var(--sv-color-surface)',
+        }}
+      >
+        {value}
+      </div>
+      <Callout type="info">
+        Currently showing the <strong>{isMobile ? 'mobile' : 'web'}</strong> tree. Resize the
+        Storybook viewport (or the toolbar&apos;s viewport picker) below 768px to see it swap — only
+        the active side is ever mounted, the other tree doesn&apos;t exist in the DOM at all.
+      </Callout>
+    </div>
+  );
+}
+
+function CarouselRouteSyncDemo() {
+  const PATHS = ['/tasks', '/tasks/starred', '/tasks/groceries'];
+  const LABELS = ['Lists', 'Starred', 'Groceries'];
+  const [pathname, setPathname] = useState(PATHS[0] as string);
+  const [events, setEvents] = useState<string[]>([]);
+  const log = (msg: string) =>
+    setEvents((e) => [...e, `${new Date().toLocaleTimeString()} — ${msg}`]);
+
+  const { activeIndex, onSettle } = useCarouselRouteSync({
+    indexForPathname: (p) => Math.max(0, PATHS.indexOf(p)),
+    pathForIndex: (i) => PATHS[i] ?? '/tasks',
+    pathname,
+    onNavigate: (path) => {
+      log(`onNavigate("${path}") — simulating router.replace`);
+      setPathname(path);
+    },
+  });
+
+  return (
+    <div>
+      <div style={{ display: 'flex', gap: 'var(--sv-space-2)', marginBottom: 'var(--sv-space-3)' }}>
+        {LABELS.map((label, i) => (
+          <button
+            key={label}
+            type="button"
+            onClick={() => {
+              log(`swipe settled on "${label}" (index ${i})`);
+              onSettle(i);
+            }}
+            style={{
+              padding: 'var(--sv-space-2) var(--sv-space-3)',
+              borderRadius: 'var(--sv-radius-md)',
+              border: '1px solid var(--sv-color-border)',
+              background: i === activeIndex ? 'var(--sv-color-accent)' : 'var(--sv-color-surface)',
+              color:
+                i === activeIndex
+                  ? 'var(--sv-color-text-on-accent)'
+                  : 'var(--sv-color-text-primary)',
+              fontFamily: ff,
+              fontSize: '0.8rem',
+              cursor: 'pointer',
+            }}
+          >
+            {label}
+          </button>
+        ))}
+        <button
+          type="button"
+          onClick={() => {
+            const other = PATHS[(activeIndex + 1) % PATHS.length] as string;
+            log(`external nav to "${other}" (e.g. a tapped <Link>, browser back/forward)`);
+            setPathname(other);
+          }}
+          style={{
+            padding: 'var(--sv-space-2) var(--sv-space-3)',
+            borderRadius: 'var(--sv-radius-md)',
+            border: '1px dashed var(--sv-color-border)',
+            background: 'var(--sv-color-surface)',
+            color: 'var(--sv-color-text-primary)',
+            fontFamily: ff,
+            fontSize: '0.8rem',
+            cursor: 'pointer',
+          }}
+        >
+          Simulate external nav
+        </button>
+      </div>
+      <EventLog events={events} />
+      <Callout type="info">
+        This demo fakes a router with local <code>useState</code> — in a real app, pass{' '}
+        <code>next/navigation</code>&apos;s <code>usePathname()</code> as <code>pathname</code> and{' '}
+        <code>router.replace</code> as <code>onNavigate</code>. Note the &quot;swipe settled&quot;
+        buttons never log a redundant external-nav resync afterwards — that&apos;s the isInternalNav
+        dance being handled internally.
+      </Callout>
+    </div>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Main story component
 // ---------------------------------------------------------------------------
@@ -412,6 +797,104 @@ function InteractionHooksDoc() {
 
 const isMobile = useIsMobile(); // defaults to MOBILE_BREAKPOINT_PX (768)`}</CodeBlock>
       </section>
+
+      <section style={{ marginBottom: 'var(--sv-space-10)' }}>
+        <SectionHeader
+          title="useIsOffline"
+          subtitle="SSR-safe navigator.onLine tracking, shared by OfflineBanner, the login page, and Console/Account's offline gate (research 0012)."
+        />
+        <Card padding="md">
+          <IsOfflineDemo />
+        </Card>
+        <CodeBlock>{`import { useIsOffline } from '@sovereignfs/ui';
+
+const isOffline = useIsOffline();`}</CodeBlock>
+      </section>
+
+      <section style={{ marginBottom: 'var(--sv-space-10)' }}>
+        <SectionHeader
+          title="useOfflineTileState"
+          subtitle="Which of the two app-tile states, if any, applies given a plugin's declared offline tier — connectivity-dimmed (no tier, offline right now) vs. capability-restricted (device-only, unavailable here), never conflated (research 0012)."
+        />
+        <Card padding="md">
+          <OfflineTileStateDemo />
+        </Card>
+        <CodeBlock>{`import { useOfflineTileState } from '@sovereignfs/ui';
+
+// deviceOnlyAvailable comes from isDeviceOnlyTierAvailable() in
+// @sovereignfs/sdk/device-client — passed in, not computed here, so
+// @sovereignfs/ui never depends on @sovereignfs/sdk.
+const state = useOfflineTileState(plugin.offline, deviceOnlyAvailable);
+// 'connectivity-dimmed' | 'capability-restricted' | null`}</CodeBlock>
+      </section>
+
+      <section style={{ marginBottom: 'var(--sv-space-10)' }}>
+        <SectionHeader
+          title="useSwipeReveal"
+          subtitle="Horizontal swipe-to-reveal for a row's Done/Delete actions — extracted from sovereign-tasks' two independent hand-rolled implementations (RFC 0079)."
+        />
+        <Card padding="md">
+          <SwipeRevealDemo />
+        </Card>
+        <CodeBlock>{`const { rowRef, handlers } = useSwipeReveal({
+  revealWidth: 88,
+  open,
+  onOpen: () => setOpen(true),
+  onClose: () => setOpen(false),
+});
+<div ref={rowRef} {...handlers} style={{ transform: open ? 'translateX(-88px)' : undefined }}>
+  Row content
+</div>`}</CodeBlock>
+      </section>
+
+      <section style={{ marginBottom: 'var(--sv-space-10)' }}>
+        <SectionHeader
+          title="useSnapCarousel"
+          subtitle="Debounced settled-slide detection over a native scroll-snap container — extracted from sovereign-tasks and sovereign-shopper's independently duplicated carousels (RFC 0079)."
+        />
+        <Card padding="md">
+          <SnapCarouselDemo />
+        </Card>
+        <CodeBlock>{`const { scrollRef, scrollToIndex } = useSnapCarousel({
+  itemCount: slides.length,
+  onSettle: (index) => setActiveIndex(index),
+});
+<div ref={scrollRef} style={{ display: 'flex', overflowX: 'auto', scrollSnapType: 'x mandatory' }}>
+  {slides.map((slide) => <div style={{ scrollSnapAlign: 'start' }}>{slide}</div>)}
+</div>`}</CodeBlock>
+      </section>
+
+      <section style={{ marginBottom: 'var(--sv-space-10)' }}>
+        <SectionHeader
+          title="useResponsiveLayout"
+          subtitle="Picks between a web and mobile value for the current viewport — formalizes the 'render an entirely different tree below a breakpoint' fork plugins have hand-rolled per plugin. See also the ResponsiveSurface component for the equivalent as plain JSX."
+        />
+        <Card padding="md">
+          <ResponsiveLayoutDemo />
+        </Card>
+        <CodeBlock>{`const { isMobile, value } = useResponsiveLayout({ web: <WebShell />, mobile: <MobileShell /> });
+// or, as a component:
+<ResponsiveSurface web={<WebShell />} mobile={<MobileShell />} />`}</CodeBlock>
+      </section>
+
+      <section style={{ marginBottom: 'var(--sv-space-10)' }}>
+        <SectionHeader
+          title="useCarouselRouteSync"
+          subtitle="Router-agnostic pathname↔slide-index sync for SwipableMobileCarousel — centralizes the isInternalNav dance both sovereign-tasks and sovereign-shopper hand-roll identically today."
+        />
+        <Card padding="md">
+          <CarouselRouteSyncDemo />
+        </Card>
+        <CodeBlock>{`const { activeIndex, onSettle } = useCarouselRouteSync({
+  indexForPathname: (p) => indexForPathname(p, lists), // your plugin's own logic, unchanged
+  pathForIndex: (i) => pathForIndex(i, lists),
+  pathname: usePathname(),
+  onNavigate: (path) => router.replace(path, { scroll: false }),
+});
+<SwipableMobileCarousel activeIndex={activeIndex} onSettle={onSettle} aria-label="Task lists">
+  ...
+</SwipableMobileCarousel>`}</CodeBlock>
+      </section>
     </div>
   );
 }