@sovereignfs/ui 0.54.0 → 0.83.1

package/src/components/NotificationsPanel/NotificationsPanel.module.css

@@ -0,0 +1,258 @@
+.trigger {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: none;
+  border-radius: var(--sv-radius-md);
+  background: transparent;
+  color: var(--sv-color-text-primary);
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .trigger:hover {
+    background: var(--sv-color-surface-sunken);
+  }
+}
+
+.badge {
+  position: absolute;
+  top: 2px;
+  right: 2px;
+  min-width: 14px;
+  height: 14px;
+  padding: 0 3px;
+  background: var(--sv-color-error-text);
+  color: white;
+  border-radius: var(--sv-radius-full);
+  font-size: 9px;
+  font-weight: 700;
+  line-height: 14px;
+  text-align: center;
+  pointer-events: none;
+}
+
+/* ── Header ─────────────────────────────────────────────────────────────── */
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--sv-space-2);
+  padding: var(--sv-space-3) var(--sv-space-3) var(--sv-space-3) var(--sv-space-4);
+  border-bottom: var(--sv-border-width-hairline) solid var(--sv-color-border);
+}
+
+.headerTitle {
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-semibold);
+  color: var(--sv-color-text-primary);
+  flex: 1;
+}
+
+.headerActions {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-2);
+}
+
+.actionBtn {
+  background: none;
+  border: none;
+  padding: 0;
+  cursor: pointer;
+  font-size: var(--sv-font-size-caption);
+  color: var(--sv-color-text-muted);
+  white-space: nowrap;
+}
+
+@media (hover: hover) {
+  .actionBtn:hover {
+    color: var(--sv-color-text-primary);
+  }
+}
+
+.closeBtn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: none;
+  border-radius: var(--sv-radius-sm);
+  background: none;
+  color: var(--sv-color-text-muted);
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .closeBtn:hover {
+    color: var(--sv-color-text-primary);
+    background: var(--sv-color-surface-sunken);
+  }
+}
+
+/* ── List ───────────────────────────────────────────────────────────────── */
+
+.list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  max-height: 420px;
+  overflow-y: auto;
+}
+
+/* ── Empty state ────────────────────────────────────────────────────────── */
+
+.empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--sv-space-3);
+  padding: var(--sv-space-10) var(--sv-space-4);
+}
+
+.emptyIcon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 44px;
+  height: 44px;
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-color-surface-sunken);
+  color: var(--sv-color-text-muted);
+}
+
+.emptyText {
+  font-size: var(--sv-font-size-sm);
+  color: var(--sv-color-text-muted);
+}
+
+/* ── Notification item ─────────────────────────────────────────────────── */
+
+.item {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--sv-space-3);
+  padding: var(--sv-space-3);
+  border-bottom: var(--sv-border-width-hairline) solid var(--sv-color-border);
+}
+
+.item:last-child {
+  border-bottom: none;
+}
+
+.categoryIcon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 32px;
+  height: 32px;
+  border-radius: var(--sv-radius-full);
+  margin-top: 1px;
+  background: var(--sv-color-surface-sunken);
+  color: var(--sv-color-text-muted);
+}
+
+.itemBody {
+  flex: 1 1 auto;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.itemTitle {
+  display: block;
+  width: 100%;
+  border: none;
+  padding: 0;
+  background: none;
+  font: inherit;
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-semibold);
+  color: var(--sv-color-text-primary);
+  text-decoration: none;
+  text-align: left;
+  line-height: 1.4;
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  a.itemTitle:hover,
+  button.itemTitle:hover {
+    text-decoration: underline;
+  }
+}
+
+.itemRead .itemTitle {
+  color: var(--sv-color-text-subtle);
+  cursor: default;
+}
+
+.itemTime {
+  font-size: var(--sv-font-size-caption);
+  color: var(--sv-color-text-muted);
+}
+
+.itemEnd {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-2);
+  flex: none;
+  padding-top: 2px;
+}
+
+.unreadDot {
+  display: block;
+  width: 7px;
+  height: 7px;
+  border-radius: var(--sv-radius-full);
+  background: var(--sv-color-accent);
+  flex: none;
+}
+
+.dismissBtn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  padding: 0;
+  border: none;
+  border-radius: var(--sv-radius-sm);
+  background: none;
+  color: var(--sv-color-text-muted);
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .dismissBtn:hover {
+    color: var(--sv-color-text-primary);
+    background: var(--sv-color-surface-sunken);
+  }
+}
+
+.viewAll {
+  display: block;
+  text-align: center;
+  padding: var(--sv-space-2) var(--sv-space-3);
+  border-top: var(--sv-border-width-hairline) solid var(--sv-color-border);
+  font-size: var(--sv-font-size-caption);
+  color: var(--sv-color-text-muted);
+  text-decoration: none;
+}
+
+@media (hover: hover) {
+  .viewAll:hover {
+    color: var(--sv-color-text-primary);
+    background: var(--sv-color-surface-sunken);
+  }
+}

package/src/components/NotificationsPanel/NotificationsPanel.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { NotificationsPanel } from './NotificationsPanel';
+import { Icon } from '../Icon/Icon';
+
+const items = [
+  {
+    id: '1',
+    icon: <Icon name="layers" size="sm" aria-hidden />,
+    title: 'Added to a project',
+    timeLabel: '2d ago',
+    read: false,
+    onDismiss: () => {},
+  },
+  {
+    id: '2',
+    icon: <Icon name="user-round-plus" size="sm" aria-hidden />,
+    title: 'Jamie invited you to Notes',
+    timeLabel: '3d ago',
+    read: true,
+    href: '/notes',
+    onDismiss: () => {},
+  },
+];
+
+const meta = {
+  title: 'Components/NotificationsPanel',
+  component: NotificationsPanel,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          "The bell trigger + dropdown, generalized from the runtime shell's own NotificationBell. Pure presentation — no fetch/SSE/mark-read logic; the consumer supplies already-resolved items and wires onOpen/onDismiss/onMarkAllRead/onClearAll.",
+      },
+    },
+  },
+  args: {
+    items,
+    unreadCount: 1,
+    onMarkAllRead: () => {},
+    onClearAll: () => {},
+  },
+} satisfies Meta<typeof NotificationsPanel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Empty: Story = {
+  args: {
+    items: [],
+    unreadCount: 0,
+  },
+};
+
+export const WithViewAll: Story = {
+  args: {
+    viewAllHref: '/inbox',
+  },
+};

package/src/components/NotificationsPanel/NotificationsPanel.tsx

@@ -0,0 +1,187 @@
+'use client';
+
+import { useState, type ReactNode } from 'react';
+import { Icon } from '../Icon/Icon';
+import { Popover } from '../Popover/Popover';
+import styles from './NotificationsPanel.module.css';
+
+export interface NotificationsPanelItem {
+  id: string;
+  /** Category icon, already resolved (sized + colored) by the consumer —
+   *  this component doesn't own category → color mapping. */
+  icon: ReactNode;
+  title: string;
+  /** Pre-formatted relative time (e.g. "2d ago") — formatting stays
+   *  consumer-side so this component needs no Date/clock dependency. */
+  timeLabel: string;
+  read: boolean;
+  /** Renders the title as a link when set. */
+  href?: string;
+  /** Called when the title is clicked/tapped — typically "mark as read". */
+  onOpen?: () => void;
+  onDismiss: () => void;
+}
+
+export interface NotificationsPanelProps {
+  items: NotificationsPanelItem[];
+  unreadCount: number;
+  onMarkAllRead?: () => void;
+  onClearAll?: () => void;
+  emptyMessage?: string;
+  /** Trigger button's accessible label base — the unread count is appended
+   *  automatically, matching the real NotificationBell. Defaults to
+   *  "Notifications". */
+  'aria-label'?: string;
+  align?: 'left' | 'right';
+  /** Optional footer link (e.g. to the consumer's own full notification
+   *  list/detail view — RFC 0048) — mirrors the real `NotificationBell`'s
+   *  "View all" link. Omit to render no footer, matching this component's
+   *  behavior before this prop existed. */
+  viewAllHref?: string;
+}
+
+function NotificationRow({ item }: { item: NotificationsPanelItem }) {
+  const titleContent = item.href ? (
+    <a href={item.href} className={styles.itemTitle} onClick={item.onOpen}>
+      {item.title}
+    </a>
+  ) : !item.read ? (
+    <button
+      type="button"
+      className={styles.itemTitle}
+      aria-label={`Mark as read: ${item.title}`}
+      onClick={item.onOpen}
+    >
+      {item.title}
+    </button>
+  ) : (
+    <span className={styles.itemTitle}>{item.title}</span>
+  );
+
+  return (
+    <li className={[styles.item, item.read ? styles.itemRead : ''].filter(Boolean).join(' ')}>
+      <div className={styles.categoryIcon}>{item.icon}</div>
+      <div className={styles.itemBody}>
+        {titleContent}
+        <span className={styles.itemTime}>{item.timeLabel}</span>
+      </div>
+      <div className={styles.itemEnd}>
+        {!item.read && <span className={styles.unreadDot} aria-label="Unread" />}
+        <button
+          type="button"
+          className={styles.dismissBtn}
+          aria-label={`Dismiss: ${item.title}`}
+          onClick={item.onDismiss}
+        >
+          <Icon name="x" size="sm" aria-hidden />
+        </button>
+      </div>
+    </li>
+  );
+}
+
+/**
+ * NotificationsPanel — the bell trigger + dropdown, generalized from the
+ * runtime shell's own `NotificationBell.tsx` visual structure and copy
+ * (title / Mark all read / Clear all / close, then a list of category-icon +
+ * title + time + unread-dot + dismiss rows, or an empty state).
+ *
+ * Deliberately **presentational only** — no fetch/SSE/polling, no
+ * category → color mapping, no mark-read/dismiss networking. The real
+ * `NotificationBell` owns real platform data (`/api/account/notifications`,
+ * a shared cross-instance store); this component can't and shouldn't know
+ * about that (SDK boundary). The consumer supplies `items` already resolved
+ * and wires `onOpen`/`onDismiss`/`onMarkAllRead`/`onClearAll` to whatever
+ * its own data layer needs, against a shared panel instead of a
+ * `shell: minimal` plugin hand-rebuilding one locally. Built on the shared
+ * `Popover` primitive (self-contained open state) rather than the
+ * original's hand-rolled outside-click/Escape listener.
+ */
+export function NotificationsPanel({
+  items,
+  unreadCount,
+  onMarkAllRead,
+  onClearAll,
+  emptyMessage = 'No notifications.',
+  'aria-label': ariaLabel = 'Notifications',
+  align = 'right',
+  viewAllHref,
+}: NotificationsPanelProps) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Popover
+      align={align}
+      width={340}
+      aria-label={ariaLabel}
+      open={open}
+      onClose={() => setOpen(false)}
+      trigger={
+        <button
+          type="button"
+          aria-label={unreadCount > 0 ? `${ariaLabel} (${unreadCount} unread)` : ariaLabel}
+          aria-haspopup="true"
+          aria-expanded={open}
+          onClick={() => setOpen((v) => !v)}
+          className={styles.trigger}
+        >
+          {/* size="lg" (24px), not "md" (20px) — matches the real
+              NotificationBell's own inline SVG, which is literally
+              width="24" height="24", not the DS Icon scale's "md" step. */}
+          <Icon name="bell" size="lg" aria-hidden />
+          {unreadCount > 0 && (
+            <span className={styles.badge} aria-hidden="true">
+              {unreadCount > 99 ? '99+' : unreadCount}
+            </span>
+          )}
+        </button>
+      }
+    >
+      <div className={styles.header}>
+        <span className={styles.headerTitle}>{ariaLabel}</span>
+        <div className={styles.headerActions}>
+          {items.length > 0 && (
+            <>
+              {unreadCount > 0 && onMarkAllRead && (
+                <button type="button" className={styles.actionBtn} onClick={onMarkAllRead}>
+                  Mark all read
+                </button>
+              )}
+              {onClearAll && (
+                <button type="button" className={styles.actionBtn} onClick={onClearAll}>
+                  Clear all
+                </button>
+              )}
+            </>
+          )}
+          <button
+            type="button"
+            className={styles.closeBtn}
+            aria-label={`Close ${ariaLabel.toLowerCase()}`}
+            onClick={() => setOpen(false)}
+          >
+            <Icon name="x" size="sm" aria-hidden />
+          </button>
+        </div>
+      </div>
+
+      <ul className={styles.list} aria-label={`${ariaLabel} list`}>
+        {items.length === 0 ? (
+          <li className={styles.empty}>
+            <span className={styles.emptyIcon} aria-hidden="true">
+              <Icon name="bell" size="lg" aria-hidden />
+            </span>
+            <span className={styles.emptyText}>{emptyMessage}</span>
+          </li>
+        ) : (
+          items.map((item) => <NotificationRow key={item.id} item={item} />)
+        )}
+      </ul>
+      {viewAllHref && (
+        <a href={viewAllHref} className={styles.viewAll} onClick={() => setOpen(false)}>
+          View all
+        </a>
+      )}
+    </Popover>
+  );
+}

package/src/components/NotificationsPanel/__tests__/NotificationsPanel.test.tsx

@@ -0,0 +1,78 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { NotificationsPanel } from '../NotificationsPanel';
+
+afterEach(() => {
+  cleanup();
+});
+
+const items = [
+  {
+    id: '1',
+    icon: <span>icon</span>,
+    title: 'Added to a project',
+    timeLabel: '2d ago',
+    read: false,
+    onOpen: vi.fn(),
+    onDismiss: vi.fn(),
+  },
+];
+
+describe('NotificationsPanel', () => {
+  it('renders a closed trigger with an unread badge', () => {
+    render(<NotificationsPanel items={items} unreadCount={1} />);
+    expect(screen.getByRole('button', { name: /1 unread/ })).toBeTruthy();
+    expect(screen.queryByText('Added to a project')).toBeNull();
+  });
+
+  it('renders no badge when there are no unread notifications', () => {
+    render(<NotificationsPanel items={[]} unreadCount={0} />);
+    expect(screen.getByRole('button', { name: 'Notifications' })).toBeTruthy();
+  });
+
+  it('opens the panel on trigger click, showing items', () => {
+    render(<NotificationsPanel items={items} unreadCount={1} />);
+    fireEvent.click(screen.getByRole('button', { name: /unread/ }));
+    expect(screen.getByText('Added to a project')).toBeTruthy();
+    expect(screen.getByText('2d ago')).toBeTruthy();
+  });
+
+  it('shows an empty state when there are no items', () => {
+    render(<NotificationsPanel items={[]} unreadCount={0} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Notifications' }));
+    expect(screen.getByText('No notifications.')).toBeTruthy();
+  });
+
+  it('calls onOpen when an unread title is clicked', () => {
+    render(<NotificationsPanel items={items} unreadCount={1} />);
+    fireEvent.click(screen.getByRole('button', { name: /unread/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Mark as read: Added to a project' }));
+    expect(items[0]?.onOpen).toHaveBeenCalledOnce();
+  });
+
+  it('calls onDismiss when the dismiss button is clicked', () => {
+    render(<NotificationsPanel items={items} unreadCount={1} />);
+    fireEvent.click(screen.getByRole('button', { name: /unread/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Dismiss: Added to a project' }));
+    expect(items[0]?.onDismiss).toHaveBeenCalledOnce();
+  });
+
+  it('calls onMarkAllRead and onClearAll from the header actions', () => {
+    const onMarkAllRead = vi.fn();
+    const onClearAll = vi.fn();
+    render(
+      <NotificationsPanel
+        items={items}
+        unreadCount={1}
+        onMarkAllRead={onMarkAllRead}
+        onClearAll={onClearAll}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: /unread/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Mark all read' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Clear all' }));
+    expect(onMarkAllRead).toHaveBeenCalledOnce();
+    expect(onClearAll).toHaveBeenCalledOnce();
+  });
+});

package/src/components/OverlayHeader/OverlayHeader.module.css

@@ -6,7 +6,7 @@
 .header {
   flex-shrink: 0;
   background: var(--sv-color-surface);
-  border-bottom: 1px solid var(--sv-color-border);
+  border-bottom: var(--sv-border-width-hairline) solid var(--sv-color-border);
 }
 
 .row {

package/src/components/OverlayHeader/OverlayHeader.tsx

@@ -5,8 +5,12 @@ import styles from './OverlayHeader.module.css';
 export interface OverlayHeaderProps {
   /** Overlay title, shown between the optional back button and the trailing
    *  slots. Optional — some consumers (e.g. `Dialog`'s mobile bar) need the
-   *  row's close button present even when no title applies. */
-  title?: string;
+   *  row's close button present even when no title applies. Accepts any
+   *  `ReactNode`, not just a string — e.g. `Dialog`'s `header` prop passes
+   *  arbitrary content through here (an icon next to text, etc.); the
+   *  row's title slot still assumes single-line content sized like text
+   *  (see the component's own doc comment for the line this doesn't cross). */
+  title?: ReactNode;
   /** Always renders a close button; called on click. */
   onClose: () => void;
   /** When provided, renders a back-chevron button before the title (for
@@ -18,6 +22,15 @@ export interface OverlayHeaderProps {
   /** A second row below the title row — e.g. a tab strip. */
   secondRow?: ReactNode;
   className?: string;
+  /** Override the title row's own className (e.g. tighter padding to match
+   *  a consumer's own compact header elsewhere in the same surface) — the
+   *  row keeps its standard title/back/action/close layout, just restyled.
+   *  For a genuinely different shape, don't use `OverlayHeader` at all (see
+   *  this component's own doc comment). */
+  rowClassName?: string;
+  /** Override the title text's own className (e.g. a smaller font size to
+   *  match a consumer's own compact header elsewhere in the same surface). */
+  titleClassName?: string;
 }
 
 /**
@@ -41,16 +54,18 @@ export function OverlayHeader({
   action,
   secondRow,
   className,
+  rowClassName,
+  titleClassName,
 }: OverlayHeaderProps) {
   return (
     <div className={[styles.header, className].filter(Boolean).join(' ')}>
-      <div className={styles.row}>
+      <div className={[styles.row, rowClassName].filter(Boolean).join(' ')}>
         {onBack && (
           <button type="button" className={styles.backButton} aria-label="Back" onClick={onBack}>
             <Icon name="chevron-left" size="md" aria-hidden />
           </button>
         )}
-        <span className={styles.title}>{title}</span>
+        <span className={[styles.title, titleClassName].filter(Boolean).join(' ')}>{title}</span>
         {action && <div className={styles.action}>{action}</div>}
         <button type="button" className={styles.closeButton} aria-label="Close" onClick={onClose}>
           <Icon name="x" size="sm" aria-hidden />

package/src/components/OverlayHeader/__tests__/OverlayHeader.test.tsx

@@ -48,4 +48,22 @@ describe('OverlayHeader', () => {
     render(<OverlayHeader title="Account" onClose={() => {}} secondRow={<nav>Tab strip</nav>} />);
     expect(screen.getByText('Tab strip')).toBeTruthy();
   });
+
+  it('accepts arbitrary ReactNode content for title, not just a string', () => {
+    // Locks in the type widening (title?: string -> title?: ReactNode) that
+    // Dialog's `header` prop relies on (Dialog.tsx passes header through
+    // here as `title`) — a plain string title must keep working unchanged.
+    render(
+      <OverlayHeader
+        title={
+          <>
+            <strong>Card</strong> detail
+          </>
+        }
+        onClose={() => {}}
+      />,
+    );
+    expect(screen.getByText('Card').tagName).toBe('STRONG');
+    expect(screen.getByText('detail')).toBeTruthy();
+  });
 });