@sovereignfs/ui 0.45.0 → 0.54.0

package/src/stories/DesignSystemOverview.stories.tsx

@@ -8,6 +8,9 @@ import { Card } from '../components/Card/Card';
 import { Dialog } from '../components/Dialog/Dialog';
 import { Drawer } from '../components/Drawer/Drawer';
 import { EmptyState } from '../components/EmptyState/EmptyState';
+import { OfflineGate } from '../components/OfflineGate/OfflineGate';
+import { DeviceOnlyGate } from '../components/DeviceOnlyGate/DeviceOnlyGate';
+import { DeviceStorageKeyGate } from '../components/DeviceStorageKeyGate/DeviceStorageKeyGate';
 import { FormField } from '../components/FormField/FormField';
 import { Icon } from '../components/Icon/Icon';
 import type { IconName } from '../components/Icon/Icon';
@@ -21,9 +24,19 @@ import { StatusBadge } from '../components/StatusBadge/StatusBadge';
 import { SplitPane } from '../components/SplitPane/SplitPane';
 import { TagInput } from '../components/TagInput/TagInput';
 import { SuggestionInput } from '../components/SuggestionInput/SuggestionInput';
+import { MobileAppsDrawer } from '../components/MobileAppsDrawer/MobileAppsDrawer';
+import { MobileFooter } from '../components/MobileFooter/MobileFooter';
+import { MobileHeader } from '../components/MobileHeader/MobileHeader';
 import { NavTabs } from '../components/NavTabs/NavTabs';
 import { PageHeader } from '../components/PageHeader/PageHeader';
+import { PageContainer } from '../components/PageContainer/PageContainer';
 import { Popover } from '../components/Popover/Popover';
+import { ResponsiveSurface } from '../components/ResponsiveSurface/ResponsiveSurface';
+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 { SwipableMobileCarouselDots } from '../components/SwipableMobileCarouselDots/SwipableMobileCarouselDots';
 import { SegmentedControl } from '../components/SegmentedControl/SegmentedControl';
 import { Select } from '../components/Select/Select';
 import { Spinner } from '../components/Spinner/Spinner';
@@ -46,6 +59,8 @@ import {
 } from '../components/Table/Table';
 import { Alert } from '../components/Alert/Alert';
 import { Breadcrumb } from '../components/Breadcrumb/Breadcrumb';
+import { LegalLinks } from '../components/LegalLinks/LegalLinks';
+import { Markdown } from '../components/Markdown/Markdown';
 import { Pagination } from '../components/Pagination/Pagination';
 import { Kbd } from '../components/Kbd/Kbd';
 import { Accordion } from '../components/Accordion/Accordion';
@@ -631,6 +646,28 @@ function DrawerDemo() {
   );
 }
 
+function MobileAppsDrawerDemo() {
+  const [open, setOpen] = useState(false);
+  const items = [
+    { key: 'home', icon: <Icon name="house" size="lg" aria-hidden />, label: 'Home' },
+    { key: 'notes', icon: <Icon name="file" size="lg" aria-hidden />, label: 'Notes' },
+    { key: 'gallery', icon: <Icon name="grid-2x2" size="lg" aria-hidden />, label: 'Gallery' },
+  ];
+  return (
+    <>
+      <Button size="sm" variant="secondary" onClick={() => setOpen(true)}>
+        Open drawer
+      </Button>
+      <MobileAppsDrawer
+        open={open}
+        onClose={() => setOpen(false)}
+        aria-label="Sections"
+        items={items.map((item) => ({ ...item, onClick: () => setOpen(false) }))}
+      />
+    </>
+  );
+}
+
 function PopoverDemo() {
   const [open, setOpen] = useState(false);
   return (
@@ -921,6 +958,100 @@ function FileDropzoneDemo() {
   );
 }
 
+function ResponsiveSurfaceDemo() {
+  return (
+    <div
+      style={{
+        border: '1px dashed var(--sv-color-border)',
+        borderRadius: 'var(--sv-radius-md)',
+        padding: 'var(--sv-space-4)',
+        fontFamily: ff,
+        fontSize: 'var(--sv-font-size-sm)',
+        color: 'var(--sv-color-text-muted)',
+      }}
+    >
+      <ResponsiveSurface
+        web={
+          <span style={{ color: 'var(--sv-color-text-primary)' }}>
+            Web tree (resize below 768px)
+          </span>
+        }
+        mobile={<span style={{ color: 'var(--sv-color-text-primary)' }}>Mobile tree</span>}
+      />
+    </div>
+  );
+}
+
+const SWIPABLE_CAROUSEL_DEMO_SLIDES = [
+  { key: 'lists', label: 'Lists' },
+  { key: 'groceries', label: 'Groceries' },
+  { key: 'errands', label: 'Errands' },
+];
+
+function SwipableMobileCarouselDemo() {
+  const [activeIndex, setActiveIndex] = useState(0);
+  return (
+    <div
+      style={{
+        height: 220,
+        border: '1px solid var(--sv-color-border)',
+        borderRadius: 'var(--sv-radius-md)',
+        overflow: 'hidden',
+      }}
+    >
+      <SwipableMobileCarousel
+        activeIndex={activeIndex}
+        onSettle={setActiveIndex}
+        aria-label="Task lists"
+      >
+        {SWIPABLE_CAROUSEL_DEMO_SLIDES.map((slide) => (
+          <SwipableMobileCarouselSlide key={slide.key} slideKey={slide.key} label={slide.label}>
+            <SwipableMobileCarouselSlideHeader>
+              <div
+                style={{
+                  padding: 'var(--sv-space-3)',
+                  fontFamily: ff,
+                  fontWeight: 'var(--sv-font-weight-semibold)',
+                  color: 'var(--sv-color-text-primary)',
+                }}
+              >
+                {slide.label}
+              </div>
+            </SwipableMobileCarouselSlideHeader>
+            <SwipableMobileCarouselSlideBody>
+              <div
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                  height: '100%',
+                  fontFamily: ff,
+                  color: 'var(--sv-color-text-muted)',
+                }}
+              >
+                {slide.label} content
+              </div>
+            </SwipableMobileCarouselSlideBody>
+          </SwipableMobileCarouselSlide>
+        ))}
+      </SwipableMobileCarousel>
+    </div>
+  );
+}
+
+function SwipableMobileCarouselDotsDemo() {
+  const [activeIndex, setActiveIndex] = useState(0);
+  return (
+    <SwipableMobileCarouselDots
+      count={3}
+      activeIndex={activeIndex}
+      onJump={setActiveIndex}
+      labels={['Lists', 'Groceries', 'Errands']}
+      aria-label="Task lists"
+    />
+  );
+}
+
 function IconPickerDemo() {
   const [value, setValue] = useState<IconName | null>('banana');
   const options: IconName[] = [
@@ -1423,6 +1554,21 @@ font-weight: var(--sv-font-weight-medium);    /* 500 */
 font-weight: var(--sv-font-weight-semibold);  /* 600 */
 font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
           </div>
+
+          <div style={{ marginTop: 'var(--sv-space-4)' }}>
+            <p
+              style={{
+                fontSize: 'var(--sv-font-size-caption)',
+                color: 'var(--sv-color-text-muted)',
+              }}
+            >
+              Every size above is rem-based, so the whole scale responds to the in-app text-size
+              control (Account → Preferences → Appearance, task 10.2), which sets{' '}
+              <code>[data-text-size]</code> on <code>&lt;html&gt;</code> to override{' '}
+              <code>--sv-text-size-scale</code> — see the &quot;Text-size presets&quot; section of
+              the Token Gallery.
+            </p>
+          </div>
         </section>
 
         {/* ── Spacing & Radius ─────────────────────────────────────────── */}
@@ -1582,7 +1728,7 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
         <section style={{ marginBottom: 'var(--sv-space-12)' }}>
           <SectionHeader
             title="Component gallery"
-            subtitle="All 22 components — click each story in the sidebar for the full API, variants, and controls."
+            subtitle="All 74 components — click each story in the sidebar for the full API, variants, and controls."
           />
 
           <div style={{ marginBottom: 'var(--sv-space-6)' }}>
@@ -2013,6 +2159,85 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               </div>
             </ComponentCard>
 
+            {/* PageContainer */}
+            <ComponentCard
+              name="PageContainer"
+              importLine="import { PageContainer } from '@sovereignfs/ui';"
+              usage="Constrains and centers a plugin's main content width (sm/md/lg/full). Adds no padding of its own — the runtime shell already pads plugin content. Use instead of local container CSS in a plugin's layout."
+            >
+              <div style={{ width: '100%', background: 'var(--sv-color-surface-sunken)' }}>
+                <PageContainer maxWidth="sm">
+                  <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)',
+                    }}
+                  >
+                    maxWidth=&quot;sm&quot;
+                  </div>
+                </PageContainer>
+              </div>
+            </ComponentCard>
+
+            {/* MobileHeader */}
+            <ComponentCard
+              name="MobileHeader"
+              importLine="import { MobileHeader } from '@sovereignfs/ui';"
+              usage="Mobile shell header content row (RFC 0088). Bell and avatarMenu are always rendered by the consumer; logo is optional — omit it for a default 'S' badge (matching the shell's own fallback brand icon), or supply your own. Title is the only content-level override. Presentational only — see Overview/Mobile Patterns for the full immutable/overridable boundary."
+            >
+              <div
+                style={{
+                  width: '100%',
+                  background: 'var(--sv-color-surface)',
+                  border: '1px solid var(--sv-color-border)',
+                  borderRadius: 'var(--sv-radius-md)',
+                  padding: '0 var(--sv-space-3)',
+                }}
+              >
+                <MobileHeader
+                  title="Tasks"
+                  bell={<Icon name="bell" size="lg" aria-label="Notifications" />}
+                  avatarMenu={<Avatar name="Jamie Doe" size="sm" />}
+                />
+              </div>
+            </ComponentCard>
+
+            {/* MobileFooter */}
+            <ComponentCard
+              name="MobileFooter"
+              importLine="import { MobileFooter } from '@sovereignfs/ui';"
+              usage="Mobile shell footer nav row (RFC 0088). The centered launcher (onOpenApps) is always rendered; leftIcons/rightIcons take 1 or 2 items each, symmetric so the launcher stays centered."
+            >
+              <div
+                style={{
+                  width: '100%',
+                  background: 'var(--sv-color-surface)',
+                  border: '1px solid var(--sv-color-border)',
+                  borderRadius: 'var(--sv-radius-md)',
+                  padding: '0 var(--sv-space-3)',
+                }}
+              >
+                <MobileFooter
+                  onOpenApps={() => {}}
+                  leftIcons={[{ icon: <Icon name="house" size="md" aria-hidden />, label: 'Home' }]}
+                  rightIcons={[
+                    { icon: <Icon name="search" size="md" aria-hidden />, label: 'Search' },
+                  ]}
+                />
+              </div>
+            </ComponentCard>
+
+            {/* MobileAppsDrawer */}
+            <ComponentCard
+              name="MobileAppsDrawer"
+              importLine="import { MobileAppsDrawer } from '@sovereignfs/ui';"
+              usage="The mobile 'Apps' bottom sheet: a 3-column tile grid matching the runtime shell's own Apps drawer exactly (56px icon tiles, radius 14px). No header row — Drawer's own grab handle plus swipe-down/scrim-tap dismissal are enough. The tile list is supplied by the consumer via `items` — e.g. installed plugins for the shell, or a plugin's own sections for its own launcher button."
+            >
+              <MobileAppsDrawerDemo />
+            </ComponentCard>
+
             {/* EmptyState */}
             <ComponentCard
               name="EmptyState"
@@ -2031,6 +2256,53 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               />
             </ComponentCard>
 
+            {/* OfflineGate */}
+            <ComponentCard
+              name="OfflineGate"
+              importLine="import { OfflineGate } from '@sovereignfs/ui';"
+              usage="Blocks an administrative/settings surface from rendering possibly-stale cached content while offline, showing an EmptyState instead. Reads the live useIsOffline() hook — toggle DevTools > Network > Offline to see it swap. Wrap the body of a surface like Console or Account where operating against stale data is actively wrong, not every page."
+            >
+              <OfflineGate surfaceName="Console">
+                <p style={{ margin: 0, fontFamily: 'var(--sv-font-family)', fontSize: 14 }}>
+                  Renders normally while online.
+                </p>
+              </OfflineGate>
+            </ComponentCard>
+
+            {/* DeviceOnlyGate */}
+            <ComponentCard
+              name="DeviceOnlyGate"
+              importLine="import { DeviceOnlyGate } from '@sovereignfs/ui';"
+              usage="Blocks a device-only-tier plugin's content on a surface without the durable, encrypted, device-auth-gated store that tier needs. `available` is the caller's own isDeviceOnlyTierAvailable() result (from @sovereignfs/sdk/device-client) — a capability signal, never a security boundary; the real protection is that the data is encrypted regardless."
+            >
+              <DeviceOnlyGate available={false} surfaceName="Wallet">
+                <p style={{ margin: 0, fontFamily: 'var(--sv-font-family)', fontSize: 14 }}>
+                  Renders normally when available.
+                </p>
+              </DeviceOnlyGate>
+            </ComponentCard>
+
+            {/* DeviceStorageKeyGate */}
+            <ComponentCard
+              name="DeviceStorageKeyGate"
+              importLine="import { DeviceStorageKeyGate } from '@sovereignfs/ui';"
+              usage="Blocks a device-only-tier plugin's content until the user has set up their Device Storage Key. `status` is the caller's own getDeviceStorageKeyStatus() result (from @sovereignfs/sdk/device-only-storage). Enrollment is centralized in Account > Security, not per-plugin — `setupAction` is where the caller supplies a link there."
+            >
+              <DeviceStorageKeyGate
+                status="not-set-up"
+                surfaceName="Notes"
+                setupAction={
+                  <a href="/account/security" style={{ color: 'var(--sv-color-accent)' }}>
+                    Go to Account → Security
+                  </a>
+                }
+              >
+                <p style={{ margin: 0, fontFamily: 'var(--sv-font-family)', fontSize: 14 }}>
+                  Renders normally once set up.
+                </p>
+              </DeviceStorageKeyGate>
+            </ComponentCard>
+
             {/* Spinner */}
             <ComponentCard
               name="Spinner"
@@ -2238,6 +2510,28 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               />
             </ComponentCard>
 
+            {/* LegalLinks */}
+            <ComponentCard
+              name="LegalLinks"
+              importLine="import { LegalLinks } from '@sovereignfs/ui';"
+              usage="Privacy Policy / Terms of Service link row for standalone auth pages (login, register, forgot/reset password). Pass renderLink to keep navigation client-side if ever mounted inside an SPA-like shell."
+            >
+              <LegalLinks />
+            </ComponentCard>
+
+            {/* Markdown */}
+            <ComponentCard
+              name="Markdown"
+              importLine="import { Markdown } from '@sovereignfs/ui';"
+              usage="Renders a constrained markdown subset (headings, paragraphs, bold/italic/code, links, lists, blockquotes) as Typography-based React elements — no HTML string injection. Built for first-party long-form content pages (privacy policy, terms of service), not arbitrary or user-supplied markdown."
+            >
+              <Markdown
+                content={
+                  '## Heading\n\nA paragraph with **bold** and a [link](/privacy).\n\n- One\n- Two'
+                }
+              />
+            </ComponentCard>
+
             {/* Pagination */}
             <ComponentCard
               name="Pagination"
@@ -2676,6 +2970,33 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
             >
               <FileDropzoneDemo />
             </ComponentCard>
+
+            {/* ResponsiveSurface */}
+            <ComponentCard
+              name="ResponsiveSurface"
+              importLine="import { ResponsiveSurface } from '@sovereignfs/ui';"
+              usage="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."
+            >
+              <ResponsiveSurfaceDemo />
+            </ComponentCard>
+
+            {/* SwipableMobileCarousel */}
+            <ComponentCard
+              name="SwipableMobileCarousel"
+              importLine="import { SwipableMobileCarousel, SwipableMobileCarouselSlide, SwipableMobileCarouselSlideHeader, SwipableMobileCarouselSlideBody } from '@sovereignfs/ui';"
+              usage="Compound component for swiping between full-width slides. A Slide's Header/Footer always render; only Body's own loading prop gates its content, so a title can show immediately while the body's own fetch is still in flight. Owns mount-window/reorder mechanics only — never put cross-slide aggregation or a detail overlay inside a Slide."
+            >
+              <SwipableMobileCarouselDemo />
+            </ComponentCard>
+
+            {/* SwipableMobileCarouselDots */}
+            <ComponentCard
+              name="SwipableMobileCarouselDots"
+              importLine="import { SwipableMobileCarouselDots } from '@sovereignfs/ui';"
+              usage="A real, tappable, labeled slide indicator (role=tablist/tab) — standalone and reusable outside SwipableMobileCarousel too, and its default renderIndicator."
+            >
+              <SwipableMobileCarouselDotsDemo />
+            </ComponentCard>
           </div>
         </section>
 

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' },
+};