@sovereignfs/ui 0.40.0 → 0.45.0

package/src/components/HoverCard/HoverCard.tsx

@@ -0,0 +1,111 @@
+'use client';
+
+import { cloneElement, useEffect, useRef, useState } from 'react';
+import type { ReactElement, ReactNode } from 'react';
+import { Popover } from '../Popover/Popover';
+import styles from './HoverCard.module.css';
+
+export interface HoverCardProps {
+  /** The element that opens the card — cloned with hover/focus handlers
+   * (desktop) or a tap handler (touch). */
+  trigger: ReactElement;
+  children: ReactNode;
+  align?: 'left' | 'right';
+  width?: number | 'trigger';
+  'aria-label': string;
+}
+
+const OPEN_DELAY_MS = 400;
+const CLOSE_DELAY_MS = 150;
+
+/** Whether the primary pointer can hover. Distinct from viewport-width-based
+ * mobile detection: a touchscreen laptop with a mouse as its primary
+ * pointer should still get real hover behavior, and a large-viewport tablet
+ * with only touch should not — viewport width doesn't capture that, `(hover:
+ * hover)` does, matching the pointer-based gating this design system already
+ * uses in CSS (e.g. Button/Checkbox's touch-target expansion). Defaults to
+ * `true`: this only changes which event handlers get attached, not the
+ * initial DOM shape, so there's no hydration-mismatch risk to guard against
+ * the way `useIsMobile` does. */
+function useHoverCapable(): boolean {
+  const [hoverCapable, setHoverCapable] = useState(true);
+
+  useEffect(() => {
+    const mql = window.matchMedia('(hover: hover)');
+    setHoverCapable(mql.matches);
+    function handleChange(e: MediaQueryListEvent) {
+      setHoverCapable(e.matches);
+    }
+    mql.addEventListener('change', handleChange);
+    return () => mql.removeEventListener('change', handleChange);
+  }, []);
+
+  return hoverCapable;
+}
+
+/**
+ * HoverCard — hover-triggered popover on desktop, tap-to-toggle on touch.
+ *
+ * Built on `Popover` rather than reimplementing positioning/collision
+ * detection: this only adds the hover-intent open/close timing (avoids
+ * flicker on an accidental mouse pass-over, and gives the pointer time to
+ * travel from the trigger to the card itself across the gap between them)
+ * and the touch fallback. Also opens on keyboard focus and closes on blur —
+ * a hover-only trigger is a WCAG failure, since keyboard users can't hover.
+ */
+export function HoverCard({
+  trigger,
+  children,
+  align,
+  width,
+  'aria-label': ariaLabel,
+}: HoverCardProps) {
+  const [open, setOpen] = useState(false);
+  const hoverCapable = useHoverCapable();
+  const openTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  function scheduleOpen() {
+    clearTimeout(closeTimer.current);
+    openTimer.current = setTimeout(() => setOpen(true), OPEN_DELAY_MS);
+  }
+
+  function scheduleClose() {
+    clearTimeout(openTimer.current);
+    closeTimer.current = setTimeout(() => setOpen(false), CLOSE_DELAY_MS);
+  }
+
+  function cancelScheduledClose() {
+    clearTimeout(closeTimer.current);
+  }
+
+  const triggerHandlers = hoverCapable
+    ? {
+        onMouseEnter: scheduleOpen,
+        onMouseLeave: scheduleClose,
+        onFocus: () => setOpen(true),
+        onBlur: scheduleClose,
+      }
+    : { onClick: () => setOpen((o) => !o) };
+
+  const wrappedTrigger = cloneElement(trigger, triggerHandlers);
+
+  return (
+    <div
+      className={styles.root}
+      onMouseEnter={hoverCapable ? cancelScheduledClose : undefined}
+      onMouseLeave={hoverCapable ? scheduleClose : undefined}
+    >
+      <Popover
+        trigger={wrappedTrigger}
+        open={open}
+        onClose={() => setOpen(false)}
+        align={align}
+        width={width}
+        aria-label={ariaLabel}
+      >
+        {children}
+      </Popover>
+    </div>
+  );
+}

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

@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, render, screen, fireEvent } from '@testing-library/react';
+import { HoverCard } from '../HoverCard';
+
+let matches = true;
+
+function installMatchMedia() {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches,
+      media: query,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}
+
+describe('HoverCard', () => {
+  beforeEach(() => {
+    matches = true; // hover-capable by default
+    installMatchMedia();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.runOnlyPendingTimers();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('does not open immediately on mouse enter (hover-intent delay)', () => {
+    render(
+      <HoverCard trigger={<button type="button">Profile</button>} aria-label="Profile preview">
+        Card content
+      </HoverCard>,
+    );
+    fireEvent.mouseEnter(screen.getByRole('button', { name: 'Profile' }));
+    expect(screen.queryByText('Card content')).toBeNull();
+  });
+
+  it('opens after the hover-intent delay elapses', () => {
+    render(
+      <HoverCard trigger={<button type="button">Profile</button>} aria-label="Profile preview">
+        Card content
+      </HoverCard>,
+    );
+    fireEvent.mouseEnter(screen.getByRole('button', { name: 'Profile' }));
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+    expect(screen.getByText('Card content')).toBeDefined();
+  });
+
+  it('cancels the open timer if the pointer leaves before the delay elapses', () => {
+    render(
+      <HoverCard trigger={<button type="button">Profile</button>} aria-label="Profile preview">
+        Card content
+      </HoverCard>,
+    );
+    const trigger = screen.getByRole('button', { name: 'Profile' });
+    fireEvent.mouseEnter(trigger);
+    fireEvent.mouseLeave(trigger);
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(screen.queryByText('Card content')).toBeNull();
+  });
+
+  it('opens immediately on keyboard focus, for keyboard accessibility', () => {
+    render(
+      <HoverCard trigger={<button type="button">Profile</button>} aria-label="Profile preview">
+        Card content
+      </HoverCard>,
+    );
+    fireEvent.focus(screen.getByRole('button', { name: 'Profile' }));
+    expect(screen.getByText('Card content')).toBeDefined();
+  });
+
+  it('falls back to tap-to-toggle when the pointer cannot hover', () => {
+    matches = false;
+    installMatchMedia();
+    render(
+      <HoverCard trigger={<button type="button">Profile</button>} aria-label="Profile preview">
+        Card content
+      </HoverCard>,
+    );
+    const trigger = screen.getByRole('button', { name: 'Profile' });
+    fireEvent.click(trigger);
+    expect(screen.getByText('Card content')).toBeDefined();
+    fireEvent.click(trigger);
+    expect(screen.queryByText('Card content')).toBeNull();
+  });
+});

package/src/components/Icon/icons/circle-check.tsx

@@ -0,0 +1,21 @@
+// Generated by scripts/generate-icons.ts — do not edit.
+// Source: Lucide (https://lucide.dev) — ISC license, see packages/ui/NOTICE.
+import type { SVGProps } from 'react';
+
+export function CircleCheckIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...props}
+    >
+      <circle cx="12" cy="12" r="10" />
+      <path d="m9 12 2 2 4-4" />
+    </svg>
+  );
+}

package/src/components/Icon/icons/circle-x.tsx

@@ -0,0 +1,22 @@
+// Generated by scripts/generate-icons.ts — do not edit.
+// Source: Lucide (https://lucide.dev) — ISC license, see packages/ui/NOTICE.
+import type { SVGProps } from 'react';
+
+export function CircleXIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...props}
+    >
+      <circle cx="12" cy="12" r="10" />
+      <path d="m15 9-6 6" />
+      <path d="m9 9 6 6" />
+    </svg>
+  );
+}

package/src/components/Icon/icons/index.ts

@@ -26,6 +26,8 @@ import { PackageIcon } from './package';
 import { Grid2x2Icon } from './grid-2x2';
 import { InfoIcon } from './info';
 import { AlertTriangleIcon } from './alert-triangle';
+import { CircleCheckIcon } from './circle-check';
+import { CircleXIcon } from './circle-x';
 import { CalendarIcon } from './calendar';
 import { SlidersHorizontalIcon } from './sliders-horizontal';
 import { EllipsisVerticalIcon } from './ellipsis-vertical';
@@ -80,6 +82,8 @@ export type IconName =
   | 'grid-2x2'
   | 'info'
   | 'alert-triangle'
+  | 'circle-check'
+  | 'circle-x'
   | 'calendar'
   | 'sliders-horizontal'
   | 'ellipsis-vertical'
@@ -136,6 +140,8 @@ export const ICONS: Record<IconName, IconComponent> = {
   'grid-2x2': Grid2x2Icon,
   info: InfoIcon,
   'alert-triangle': AlertTriangleIcon,
+  'circle-check': CircleCheckIcon,
+  'circle-x': CircleXIcon,
   calendar: CalendarIcon,
   'sliders-horizontal': SlidersHorizontalIcon,
   'ellipsis-vertical': EllipsisVerticalIcon,
@@ -190,6 +196,8 @@ export { PackageIcon } from './package';
 export { Grid2x2Icon } from './grid-2x2';
 export { InfoIcon } from './info';
 export { AlertTriangleIcon } from './alert-triangle';
+export { CircleCheckIcon } from './circle-check';
+export { CircleXIcon } from './circle-x';
 export { CalendarIcon } from './calendar';
 export { SlidersHorizontalIcon } from './sliders-horizontal';
 export { EllipsisVerticalIcon } from './ellipsis-vertical';

package/src/components/Input/Input.module.css

@@ -1,7 +1,12 @@
 .input {
   display: block;
   width: 100%;
-  padding: var(--sv-space-2) var(--sv-space-3);
+  /* 36px rendered height. Explicit height + border-box (rather than
+     deriving height from padding and line-height) gives an exact,
+     browser-independent target instead of an approximation. */
+  height: 36px;
+  box-sizing: border-box;
+  padding: 4px var(--sv-space-3);
   font-family: var(--sv-font-family);
   font-size: var(--sv-font-size-sm);
   line-height: 1.5;

package/src/components/Item/Item.module.css

@@ -0,0 +1,70 @@
+.root {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-3);
+  width: 100%;
+  padding: var(--sv-space-3);
+  border: none;
+  border-radius: var(--sv-radius-md);
+  background: transparent;
+  text-align: left;
+  font-family: var(--sv-font-family);
+  color: inherit;
+}
+
+.interactive {
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .interactive:not(:disabled):hover {
+    background: var(--sv-color-surface-sunken);
+  }
+}
+
+.interactive:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: -2px;
+}
+
+.interactive:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+@media (pointer: coarse) {
+  .root {
+    min-height: var(--sv-touch-target-min, 44px);
+  }
+}
+
+.leading,
+.trailing {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+}
+
+.content {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  flex: 1;
+}
+
+.title {
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-medium);
+  color: var(--sv-color-text-primary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.description {
+  font-size: var(--sv-font-size-caption);
+  color: var(--sv-color-text-muted);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}

package/src/components/Item/Item.stories.tsx

@@ -0,0 +1,62 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Item } from './Item';
+import { Icon } from '../Icon/Icon';
+
+const meta = {
+  title: 'Components/Item',
+  component: Item,
+  parameters: { layout: 'padded' },
+  args: {
+    title: 'Notifications',
+  },
+} satisfies Meta<typeof Item>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {};
+
+export const WithDescription: Story = {
+  args: { description: 'Manage email and push alerts' },
+};
+
+export const Interactive: Story = {
+  args: {
+    description: 'Manage email and push alerts',
+    leading: <Icon name="bell" aria-hidden />,
+    trailing: <Icon name="chevron-right" size="sm" aria-hidden />,
+    onClick: () => {},
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    description: 'Requires admin role',
+    onClick: () => {},
+    disabled: true,
+  },
+};
+
+export const List: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+      <Item
+        title="Notifications"
+        description="Manage email and push alerts"
+        leading={<Icon name="bell" aria-hidden />}
+        trailing={<Icon name="chevron-right" size="sm" aria-hidden />}
+        onClick={() => {}}
+      />
+      <Item
+        title="Privacy"
+        description="Control what others can see"
+        leading={<Icon name="shield" aria-hidden />}
+        trailing={<Icon name="chevron-right" size="sm" aria-hidden />}
+        onClick={() => {}}
+      />
+      <Item title="Sign out" leading={<Icon name="log-out" aria-hidden />} onClick={() => {}} />
+    </div>
+  ),
+};

package/src/components/Item/Item.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from 'react';
+import styles from './Item.module.css';
+
+export interface ItemProps {
+  leading?: ReactNode;
+  title: ReactNode;
+  description?: ReactNode;
+  trailing?: ReactNode;
+  /** Renders as a button when given; a plain row otherwise. */
+  onClick?: () => void;
+  disabled?: boolean;
+  className?: string;
+}
+
+/**
+ * Item — generic row primitive: leading slot, title + optional description,
+ * trailing slot. The building block for settings rows, list rows, and
+ * menu-adjacent rows that don't fit `Menu`'s own item shape.
+ */
+export function Item({
+  leading,
+  title,
+  description,
+  trailing,
+  onClick,
+  disabled,
+  className,
+}: ItemProps) {
+  const interactive = Boolean(onClick);
+  const classes = [styles.root, interactive ? styles.interactive : '', className]
+    .filter(Boolean)
+    .join(' ');
+
+  const content = (
+    <>
+      {leading && <span className={styles.leading}>{leading}</span>}
+      <span className={styles.content}>
+        <span className={styles.title}>{title}</span>
+        {description && <span className={styles.description}>{description}</span>}
+      </span>
+      {trailing && <span className={styles.trailing}>{trailing}</span>}
+    </>
+  );
+
+  if (interactive) {
+    return (
+      <button type="button" onClick={onClick} disabled={disabled} className={classes}>
+        {content}
+      </button>
+    );
+  }
+
+  return <div className={classes}>{content}</div>;
+}

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

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen, fireEvent } from '@testing-library/react';
+import { Item } from '../Item';
+
+afterEach(cleanup);
+
+describe('Item', () => {
+  it('renders as a plain row when no onClick is given', () => {
+    render(<Item title="Notifications" description="Manage email and push alerts" />);
+    expect(screen.queryByRole('button')).toBeNull();
+    expect(screen.getByText('Notifications')).toBeDefined();
+    expect(screen.getByText('Manage email and push alerts')).toBeDefined();
+  });
+
+  it('renders as a button and fires onClick when given', () => {
+    const onClick = vi.fn();
+    render(<Item title="Notifications" onClick={onClick} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Notifications' }));
+    expect(onClick).toHaveBeenCalled();
+  });
+
+  it('renders leading and trailing slots', () => {
+    render(
+      <Item
+        title="Notifications"
+        leading={<span data-testid="leading">icon</span>}
+        trailing={<span data-testid="trailing">chevron</span>}
+      />,
+    );
+    expect(screen.getByTestId('leading')).toBeDefined();
+    expect(screen.getByTestId('trailing')).toBeDefined();
+  });
+
+  it('disables the button when disabled is set', () => {
+    render(<Item title="Notifications" onClick={() => {}} disabled />);
+    expect(screen.getByRole('button')).toHaveProperty('disabled', true);
+  });
+});

package/src/components/Kbd/Kbd.module.css

@@ -0,0 +1,14 @@
+.kbd {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 1.5em;
+  padding: var(--sv-space-1) var(--sv-space-2);
+  border: 1px solid var(--sv-color-border-strong);
+  border-radius: var(--sv-radius-sm);
+  background: var(--sv-color-surface-sunken);
+  color: var(--sv-color-text-primary);
+  font-family: var(--sv-font-family-mono);
+  font-size: var(--sv-font-size-xs);
+  line-height: 1;
+}

package/src/components/Kbd/Kbd.stories.tsx

@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Kbd } from './Kbd';
+
+const meta = {
+  title: 'Components/Kbd',
+  component: Kbd,
+  parameters: { layout: 'padded' },
+  args: { children: '⌘K' },
+} satisfies Meta<typeof Kbd>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {};
+
+export const Letter: Story = {
+  args: { children: 'S' },
+};
+
+export const Sequence: Story = {
+  render: () => (
+    <span style={{ display: 'inline-flex', alignItems: 'center', gap: 4 }}>
+      <Kbd>Ctrl</Kbd>
+      <span>+</span>
+      <Kbd>Shift</Kbd>
+      <span>+</span>
+      <Kbd>P</Kbd>
+    </span>
+  ),
+};

package/src/components/Kbd/Kbd.tsx

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+import styles from './Kbd.module.css';
+
+export interface KbdProps {
+  children: ReactNode;
+  className?: string;
+}
+
+/** Kbd — inline keyboard-key styling. Renders a real `<kbd>` element. */
+export function Kbd({ children, className }: KbdProps) {
+  return <kbd className={[styles.kbd, className].filter(Boolean).join(' ')}>{children}</kbd>;
+}

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

@@ -0,0 +1,14 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { Kbd } from '../Kbd';
+
+afterEach(cleanup);
+
+describe('Kbd', () => {
+  it('renders a real <kbd> element', () => {
+    render(<Kbd>⌘K</Kbd>);
+    const el = screen.getByText('⌘K');
+    expect(el.tagName).toBe('KBD');
+  });
+});

package/src/components/Label/Label.module.css

@@ -0,0 +1,11 @@
+.label {
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-medium);
+  color: var(--sv-color-text-primary);
+  cursor: default;
+}
+
+.disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}

package/src/components/Label/Label.stories.tsx

@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Label } from './Label';
+
+const meta = {
+  title: 'Components/Label',
+  component: Label,
+  parameters: { layout: 'padded' },
+  args: { children: 'Label text' },
+} satisfies Meta<typeof Label>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Default: Story = {};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};
+
+export const WithControl: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+      <Label htmlFor="example-input">Email address</Label>
+      <input
+        id="example-input"
+        type="email"
+        placeholder="you@example.com"
+        style={{
+          padding: 'var(--sv-space-2) var(--sv-space-3)',
+          border: '1px solid var(--sv-color-border-strong)',
+          borderRadius: 'var(--sv-radius-md)',
+          fontFamily: 'var(--sv-font-family)',
+          fontSize: 'var(--sv-font-size-sm)',
+        }}
+      />
+    </div>
+  ),
+};