@sovereignfs/ui 0.21.0 → 0.21.2

package/README.md

@@ -0,0 +1,75 @@
+# @sovereignfs/ui
+
+Sovereign Design System — design tokens and React components for building [Sovereign](https://github.com/sovereignfs/sovereign) plugins.
+
+## Installation
+
+```bash
+npm install @sovereignfs/ui
+# pnpm add @sovereignfs/ui
+```
+
+**Peer dependencies:** React 19+
+
+## Usage
+
+### Components
+
+```tsx
+import { Button, Input, Card, Dialog, Drawer } from '@sovereignfs/ui';
+```
+
+Available components: `Avatar`, `Badge`, `Button`, `Card`, `Dialog`, `Drawer`, `EmptyState`, `FormField`, `Icon`, `Input`, `NavTabs`, `PageHeader`, `Popover`, `SegmentedControl`, `Select`, `Spinner`, `SystemBanner`, `Tabs`, `Toast` / `useToast`, `Toggle`, `Tooltip`.
+
+### Tokens
+
+The Sovereign runtime injects design tokens globally. Reference them directly in your CSS — no import needed at runtime:
+
+```css
+.my-component {
+  color: var(--sv-color-text-primary);
+  background: var(--sv-color-surface);
+  padding: var(--sv-space-4);
+  border-radius: var(--sv-radius-md);
+}
+```
+
+If you need tokens outside the Sovereign runtime (e.g. Storybook, standalone use), import the CSS file:
+
+```ts
+import '@sovereignfs/ui/tokens.css';
+```
+
+### Token architecture
+
+Tokens follow a two-tier model:
+
+```
+Primitive tokens   --sv-grey-50 … --sv-grey-950  /  --sv-space-1 … --sv-space-16
+                          │
+                          ▼ mapped by semantic layer
+Semantic tokens    --sv-color-surface  /  --sv-color-text-primary  /  --sv-shadow-card
+```
+
+Plugin developers reference **semantic tokens** — never primitive colours directly. Dark mode and instance theming work by swapping semantic token values; no component changes required.
+
+## Icon component
+
+```tsx
+import { Icon } from '@sovereignfs/ui';
+
+<Icon name="bell" size={20} />;
+```
+
+Available icon names: `activity`, `alert-triangle`, `bell`, `check`, `chevron-down`, `chevron-left`, `chevron-right`, `chevron-up`, `eye`, `eye-off`, `grid-2x2`, `house`, `info`, `lock`, `log-out`, `mail`, `package`, `pencil`, `plus`, `rotate-ccw`, `search`, `settings`, `shield`, `sliders-horizontal`, `terminal`, `trash-2`, `user`, `x`.
+
+## Documentation
+
+- [Storybook — live component & token gallery](https://sovereignfs.github.io/storybook)
+- [Design system reference](https://github.com/sovereignfs/sovereign/blob/main/docs/design-system.md)
+- [Plugin development guide](https://github.com/sovereignfs/sovereign/blob/main/docs/plugin-development.md)
+- [SDK stability & semver policy](https://github.com/sovereignfs/sovereign/blob/main/docs/sdk-stability.md)
+
+## License
+
+AGPL-3.0-or-later

package/dist/Dialog.module.css

@@ -49,6 +49,10 @@
   flex: 1 1 auto;
   overflow-y: auto;
   padding: var(--sv-space-6);
+  /* Prevent iOS scroll-chaining: when the dialog content reaches its top/bottom
+     boundary, stop the gesture from propagating to the document (which would
+     scroll the shell header and footer out of view in standalone PWA mode). */
+  overscroll-behavior: contain;
 }
 
 /* Fixed sizes. `max-*: 100%` caps to the scrim's content box (viewport minus

package/dist/Drawer.module.css

@@ -20,6 +20,7 @@
   width: 100%;
   max-height: 80dvh;
   overflow-y: auto;
+  overscroll-behavior: contain;
   background: var(--sv-color-surface-raised);
   border-top: 1px solid var(--sv-color-border);
   border-radius: var(--sv-radius-3xl) var(--sv-radius-3xl) 0 0;

package/dist/index.js

@@ -905,6 +905,20 @@ function Input({ type = "text", className, ...rest }) {
 
 // src/components/Dialog/Dialog.tsx
 import { useEffect as useEffect2, useRef as useRef2 } from "react";
+
+// src/scroll-lock.ts
+function lockBodyScroll() {
+  const count = parseInt(document.body.dataset.scrollLocks ?? "0", 10);
+  document.body.dataset.scrollLocks = String(count + 1);
+  if (count === 0) document.body.style.overflow = "hidden";
+}
+function unlockBodyScroll() {
+  const next = Math.max(0, parseInt(document.body.dataset.scrollLocks ?? "0", 10) - 1);
+  document.body.dataset.scrollLocks = String(next);
+  if (next === 0) document.body.style.overflow = "";
+}
+
+// src/components/Dialog/Dialog.tsx
 import styles11 from "./Dialog.module.css";
 import { jsx as jsx39, jsxs as jsxs26 } from "react/jsx-runtime";
 var FOCUSABLE = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
@@ -918,6 +932,11 @@ function Dialog({
 }) {
   const panelRef = useRef2(null);
   const previouslyFocused = useRef2(null);
+  useEffect2(() => {
+    if (!open) return;
+    lockBodyScroll();
+    return unlockBodyScroll;
+  }, [open]);
   useEffect2(() => {
     if (!open) return;
     previouslyFocused.current = document.activeElement;
@@ -1012,6 +1031,11 @@ var FOCUSABLE2 = 'a[href], button:not([disabled]), textarea:not([disabled]), inp
 function Drawer({ open, onClose, "aria-label": ariaLabel, children }) {
   const panelRef = useRef3(null);
   const previouslyFocused = useRef3(null);
+  useEffect3(() => {
+    if (!open) return;
+    lockBodyScroll();
+    return unlockBodyScroll;
+  }, [open]);
   useEffect3(() => {
     if (!open) return;
     previouslyFocused.current = document.activeElement;

package/package.json

@@ -1,8 +1,18 @@
 {
   "name": "@sovereignfs/ui",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "type": "module",
   "description": "Sovereign Design System — design tokens and React components.",
+  "keywords": [
+    "sovereign",
+    "design-system",
+    "react",
+    "components",
+    "css-modules",
+    "tokens",
+    "plugin",
+    "self-hosted"
+  ],
   "license": "AGPL-3.0-or-later",
   "publishConfig": {
     "access": "public"

package/src/components/Dialog/Dialog.module.css

@@ -49,6 +49,10 @@
   flex: 1 1 auto;
   overflow-y: auto;
   padding: var(--sv-space-6);
+  /* Prevent iOS scroll-chaining: when the dialog content reaches its top/bottom
+     boundary, stop the gesture from propagating to the document (which would
+     scroll the shell header and footer out of view in standalone PWA mode). */
+  overscroll-behavior: contain;
 }
 
 /* Fixed sizes. `max-*: 100%` caps to the scrim's content box (viewport minus

package/src/components/Dialog/Dialog.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import { type ReactNode, useEffect, useRef } from 'react';
+import { lockBodyScroll, unlockBodyScroll } from '../../scroll-lock';
 import styles from './Dialog.module.css';
 
 export type DialogSize = 'sm' | 'md' | 'lg' | 'full';
@@ -44,6 +45,15 @@ export function Dialog({
   const panelRef = useRef<HTMLDivElement>(null);
   const previouslyFocused = useRef<HTMLElement | null>(null);
 
+  // Prevent document-level scroll while open. Ref-counted so nested overlays
+  // (e.g. a confirmation dialog inside an overlay plugin) don't release the
+  // lock while a sibling is still open.
+  useEffect(() => {
+    if (!open) return;
+    lockBodyScroll();
+    return unlockBodyScroll;
+  }, [open]);
+
   // Capture focus on open; restore it on close/unmount.
   useEffect(() => {
     if (!open) return;

package/src/components/Drawer/Drawer.module.css

@@ -20,6 +20,7 @@
   width: 100%;
   max-height: 80dvh;
   overflow-y: auto;
+  overscroll-behavior: contain;
   background: var(--sv-color-surface-raised);
   border-top: 1px solid var(--sv-color-border);
   border-radius: var(--sv-radius-3xl) var(--sv-radius-3xl) 0 0;

package/src/components/Drawer/Drawer.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import { type ReactNode, useEffect, useRef } from 'react';
+import { lockBodyScroll, unlockBodyScroll } from '../../scroll-lock';
 import styles from './Drawer.module.css';
 
 export interface DrawerProps {
@@ -30,6 +31,12 @@ export function Drawer({ open, onClose, 'aria-label': ariaLabel, children }: Dra
   const panelRef = useRef<HTMLDivElement>(null);
   const previouslyFocused = useRef<HTMLElement | null>(null);
 
+  useEffect(() => {
+    if (!open) return;
+    lockBodyScroll();
+    return unlockBodyScroll;
+  }, [open]);
+
   useEffect(() => {
     if (!open) return;
     previouslyFocused.current = document.activeElement as HTMLElement | null;

package/src/scroll-lock.ts

@@ -0,0 +1,16 @@
+// Ref-counted body scroll lock. Multiple overlays (Dialog, Drawer) can be
+// open simultaneously; the body stays locked until all of them close.
+// Uses data-scroll-locks on <body> as a counter so concurrent callers
+// don't clobber each other's lock state.
+
+export function lockBodyScroll(): void {
+  const count = parseInt(document.body.dataset.scrollLocks ?? '0', 10);
+  document.body.dataset.scrollLocks = String(count + 1);
+  if (count === 0) document.body.style.overflow = 'hidden';
+}
+
+export function unlockBodyScroll(): void {
+  const next = Math.max(0, parseInt(document.body.dataset.scrollLocks ?? '0', 10) - 1);
+  document.body.dataset.scrollLocks = String(next);
+  if (next === 0) document.body.style.overflow = '';
+}