@sovereignfs/ui 0.21.3 → 0.33.0

package/dist/tokens/primitives.css

@@ -78,6 +78,7 @@
   --sv-font-weight-bold: 700;
 
   /* Icon sizes — scale tokens used directly by the Icon component */
+  --sv-icon-size-xs: 0.75rem; /* 12px — inline metadata (e.g. a due-date badge) */
   --sv-icon-size-sm: 1rem; /* 16px — inline with body text */
   --sv-icon-size-md: 1.25rem; /* 20px — standard affordance */
   --sv-icon-size-lg: 1.5rem; /* 24px — prominent / standalone */
@@ -96,4 +97,22 @@
      touch without a pointing device. Applied to icon-only controls on mobile
      (avatar, footer button, Drawer nav items). */
   --sv-touch-target-min: 44px;
+
+  /* Motion scale — durations and easings for overlay enter/exit transitions
+     (Dialog, Drawer, and their Phase-B successors: Sheet, ConfirmDialog,
+     Menu). Theme-stable like the other scale tokens above — dark mode does
+     not change motion, so there is no semantic tier. Components must pair
+     every transition with `@media (prefers-reduced-motion: reduce)` collapsing
+     it to near-instant; the durations here are not a substitute for that. */
+  --sv-motion-duration-fast: 150ms; /* micro-interactions — hover/press feedback */
+  --sv-motion-duration-base: 250ms; /* default overlay enter/exit (Dialog, Drawer) */
+  --sv-motion-duration-slow: 350ms; /* larger surfaces / bigger travel distance */
+  --sv-motion-ease-out: cubic-bezier(0, 0, 0.2, 1); /* entrances — fast start, gentle settle */
+  --sv-motion-ease-in-out: cubic-bezier(0.4, 0, 0.2, 1); /* state changes with no fixed direction */
+  --sv-motion-ease-spring: cubic-bezier(
+    0.34,
+    1.56,
+    0.64,
+    1
+  ); /* slight overshoot — playful emphasis, use sparingly */
 }

package/dist/tokens/semantic.css

@@ -25,6 +25,10 @@
 
   --sv-color-accent: var(--sv-grey-900);
   --sv-color-accent-hover: var(--sv-grey-700);
+  /* Derived from --sv-color-accent via color-mix, so it re-themes automatically —
+     no separate dark-mode override needed. Tinted background for badges/chips
+     paired with --sv-color-accent text. */
+  --sv-color-accent-subtle: color-mix(in srgb, var(--sv-color-accent) 12%, transparent);
 
   --sv-color-focus-ring: var(--sv-grey-900);
 
@@ -41,6 +45,19 @@
   --sv-color-success-text: var(--sv-green-800);
   --sv-color-success-border: var(--sv-green-200);
 
+  /* Status solids — a saturated fill for status affordances that need to
+     read as a filled action button rather than a tinted surface (e.g. a
+     mobile swipe-to-reveal Delete/Done action). Paired with
+     --sv-color-text-on-error/-success (white) for the icon/label on top.
+     Intentionally NOT overridden under [data-theme='dark'] below — like
+     --sv-color-accent-subtle, a solid action fill reads the same regardless
+     of overall page theme; it's the surrounding surface that inverts, not
+     this fixed-contrast pairing. */
+  --sv-color-error-solid: var(--sv-red-700);
+  --sv-color-success-solid: var(--sv-green-800);
+  --sv-color-text-on-error: var(--sv-white);
+  --sv-color-text-on-success: var(--sv-white);
+
   /* Info surfaces — blue palette. Use for informational banners and badges.
      Never hardcode colour hex in components — reference these tokens. */
   --sv-color-info-surface: var(--sv-blue-100);
@@ -56,6 +73,7 @@
   --sv-shadow-popover:
     0 4px 16px rgba(0, 0, 0, 0.14), 0 2px 6px rgba(0, 0, 0, 0.08); /* e2 — floating panels */
   --sv-shadow-overlay: 0 10px 38px rgba(0, 0, 0, 0.18), 0 6px 12px rgba(0, 0, 0, 0.12);
+  --sv-shadow-control: 0 1px 3px rgba(0, 0, 0, 0.2); /* small interactive-control shadows, e.g. Toggle thumb */
 
   /*
    * Instance identity tokens (RFC 0027 / RFC 0032 rename). Distinct namespace from --sv-color-*:
@@ -108,4 +126,5 @@
   --sv-shadow-hover: 0 2px 6px rgba(0, 0, 0, 0.3);
   --sv-shadow-popover: 0 4px 16px rgba(0, 0, 0, 0.5), 0 2px 6px rgba(0, 0, 0, 0.3);
   --sv-shadow-overlay: 0 10px 38px rgba(0, 0, 0, 0.6), 0 6px 12px rgba(0, 0, 0, 0.5);
+  --sv-shadow-control: 0 1px 3px rgba(0, 0, 0, 0.5);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sovereignfs/ui",
-  "version": "0.21.3",
+  "version": "0.33.0",
   "type": "module",
   "description": "Sovereign Design System — design tokens and React components.",
   "keywords": [

package/src/__tests__/motion.test.tsx

@@ -0,0 +1,105 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, render } from '@testing-library/react';
+import { useMountTransition, usePrefersReducedMotion } from '../motion';
+
+let matches = false;
+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(),
+    })),
+  );
+}
+
+function MountTransitionHarness({ open, durationMs }: { open: boolean; durationMs: number }) {
+  const { mounted, phase } = useMountTransition(open, durationMs);
+  return <span data-testid="out">{mounted ? phase : 'unmounted'}</span>;
+}
+
+describe('useMountTransition', () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => {
+    vi.useRealTimers();
+    cleanup();
+  });
+
+  it('animates the entrance even on a fresh mount that starts open (e.g. a route-driven overlay)', () => {
+    const { getByTestId } = render(<MountTransitionHarness open durationMs={250} />);
+    // Renders 'entering' first — the closed-position styles — so the CSS
+    // transition has somewhere to animate from; the effect below flips it to
+    // 'open' one frame later, same as a prop-driven open transition would.
+    expect(getByTestId('out').textContent).toBe('entering');
+    act(() => void vi.advanceTimersByTime(16)); // flush the requestAnimationFrame callback
+    expect(getByTestId('out').textContent).toBe('open');
+  });
+
+  it('starts unmounted when closed from the first render', () => {
+    const { getByTestId } = render(<MountTransitionHarness open={false} durationMs={250} />);
+    expect(getByTestId('out').textContent).toBe('unmounted');
+  });
+
+  it('animates entrance: entering on the same frame, open one frame later', () => {
+    const { getByTestId, rerender } = render(
+      <MountTransitionHarness open={false} durationMs={250} />,
+    );
+    rerender(<MountTransitionHarness open durationMs={250} />);
+    expect(getByTestId('out').textContent).toBe('entering');
+    act(() => {
+      vi.advanceTimersByTime(16); // flush the requestAnimationFrame callback
+    });
+    expect(getByTestId('out').textContent).toBe('open');
+  });
+
+  it('stays mounted through "closing" for durationMs, then unmounts', () => {
+    const { getByTestId, rerender } = render(<MountTransitionHarness open durationMs={250} />);
+    rerender(<MountTransitionHarness open={false} durationMs={250} />);
+    // Still mounted immediately after `open` flips false — this is the whole
+    // point: the exit transition needs to actually play, not jump-cut.
+    expect(getByTestId('out').textContent).toBe('closing');
+    act(() => void vi.advanceTimersByTime(249));
+    expect(getByTestId('out').textContent).toBe('closing');
+    act(() => void vi.advanceTimersByTime(1));
+    expect(getByTestId('out').textContent).toBe('unmounted');
+  });
+
+  it('honours a near-zero durationMs (the reduced-motion path)', () => {
+    const { getByTestId, rerender } = render(<MountTransitionHarness open durationMs={0} />);
+    rerender(<MountTransitionHarness open={false} durationMs={0} />);
+    act(() => void vi.advanceTimersByTime(0));
+    expect(getByTestId('out').textContent).toBe('unmounted');
+  });
+});
+
+function ReducedMotionHarness() {
+  const reduced = usePrefersReducedMotion();
+  return <span data-testid="out">{String(reduced)}</span>;
+}
+
+describe('usePrefersReducedMotion', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    cleanup();
+  });
+
+  it('defaults to false and reflects a true matchMedia result after mount', () => {
+    matches = true;
+    installMatchMedia();
+    const { getByTestId } = render(<ReducedMotionHarness />);
+    expect(getByTestId('out').textContent).toBe('true');
+  });
+
+  it('reflects a false matchMedia result', () => {
+    matches = false;
+    installMatchMedia();
+    const { getByTestId } = render(<ReducedMotionHarness />);
+    expect(getByTestId('out').textContent).toBe('false');
+  });
+});

package/src/components/Button/Button.module.css

@@ -9,6 +9,9 @@
   font-weight: var(--sv-font-weight-medium);
   line-height: 1;
   cursor: pointer;
+  /* Removes the ~300ms double-tap-to-zoom delay on touch — this is a tap
+     target, never a pinch-zoom surface. */
+  touch-action: manipulation;
   transition:
     background-color 0.15s ease,
     border-color 0.15s ease,
@@ -25,6 +28,15 @@
   cursor: not-allowed;
 }
 
+/* Touch target: gated to (pointer: coarse) — the *primary* pointer, not
+   (any-pointer: coarse) — so a touchscreen laptop with mouse/trackpad as
+   primary keeps desktop density (see mobile design-system plan, Part 4 #5). */
+@media (pointer: coarse) {
+  .button {
+    min-height: var(--sv-touch-target-min, 44px);
+  }
+}
+
 /* Sizes */
 .sm {
   padding: var(--sv-space-1) var(--sv-space-3);
@@ -37,14 +49,51 @@
   font-weight: var(--sv-font-weight-semibold);
 }
 
+/* Loading spinner — a self-contained token-only spinner rather than reusing
+   the Spinner component: Spinner's border colors are semantic-fixed
+   (`--sv-color-accent`), which would be invisible against a primary button's
+   accent background, and overriding a second CSS module's rule on the same
+   element is a cross-module cascade-order gamble (see ConfirmDialog's
+   `.destructiveConfirm` comment for the same tradeoff). `currentColor` picks
+   up each variant's own text color for free. */
+.spinner {
+  display: inline-block;
+  width: var(--sv-icon-size-sm);
+  height: var(--sv-icon-size-sm);
+  flex-shrink: 0;
+  border: 2px solid currentColor;
+  border-top-color: transparent;
+  border-radius: var(--sv-radius-full);
+  opacity: 0.7;
+  animation: button-spin 0.7s linear infinite;
+}
+
+@keyframes button-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .spinner {
+    animation-play-state: paused;
+  }
+}
+
 /* Variants */
 .primary {
   background-color: var(--sv-color-accent);
   color: var(--sv-color-text-on-accent);
 }
 
-.primary:hover:not(:disabled) {
-  background-color: var(--sv-color-accent-hover);
+@media (hover: hover) {
+  .primary:hover:not(:disabled) {
+    background-color: var(--sv-color-accent-hover);
+  }
+}
+
+.primary:active:not(:disabled) {
+  background-color: color-mix(in srgb, var(--sv-color-accent) 80%, black);
 }
 
 .secondary {
@@ -53,8 +102,14 @@
   border-color: var(--sv-color-border-strong);
 }
 
-.secondary:hover:not(:disabled) {
-  background-color: var(--sv-color-surface-sunken);
+@media (hover: hover) {
+  .secondary:hover:not(:disabled) {
+    background-color: var(--sv-color-surface-sunken);
+  }
+}
+
+.secondary:active:not(:disabled) {
+  background-color: color-mix(in srgb, var(--sv-color-surface-sunken) 85%, black);
 }
 
 .ghost {
@@ -62,8 +117,14 @@
   color: var(--sv-color-text-primary);
 }
 
-.ghost:hover:not(:disabled) {
-  background-color: var(--sv-color-surface-sunken);
+@media (hover: hover) {
+  .ghost:hover:not(:disabled) {
+    background-color: var(--sv-color-surface-sunken);
+  }
+}
+
+.ghost:active:not(:disabled) {
+  background-color: color-mix(in srgb, var(--sv-color-surface-sunken) 85%, black);
 }
 
 .destructive {
@@ -72,6 +133,12 @@
   border-color: var(--sv-color-error-border);
 }
 
-.destructive:hover:not(:disabled) {
-  background-color: var(--sv-color-error-surface);
+@media (hover: hover) {
+  .destructive:hover:not(:disabled) {
+    background-color: var(--sv-color-error-surface);
+  }
+}
+
+.destructive:active:not(:disabled) {
+  background-color: color-mix(in srgb, var(--sv-color-error-surface) 85%, black);
 }

package/src/components/Button/Button.stories.tsx

@@ -18,6 +18,7 @@ const meta = {
     variant: { control: 'select', options: ['primary', 'secondary', 'ghost', 'destructive'] },
     size: { control: 'select', options: ['sm', 'md'] },
     disabled: { control: 'boolean' },
+    loading: { control: 'boolean' },
     children: { control: 'text' },
   },
   args: {
@@ -41,6 +42,11 @@ export const Medium: Story = { args: { size: 'md' } };
 export const Disabled: Story = { args: { disabled: true } };
 export const DisabledSecondary: Story = { args: { variant: 'secondary', disabled: true } };
 
+export const Loading: Story = { args: { loading: true, children: 'Saving…' } };
+export const LoadingSecondary: Story = {
+  args: { variant: 'secondary', loading: true, children: 'Saving…' },
+};
+
 export const WithLeadingIcon: Story = {
   args: {
     children: (

package/src/components/Button/Button.tsx

@@ -7,6 +7,8 @@ export type ButtonSize = 'sm' | 'md';
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   variant?: ButtonVariant;
   size?: ButtonSize;
+  /** Shows a spinner and disables the button while an async action is pending. */
+  loading?: boolean;
   children: ReactNode;
 }
 
@@ -20,6 +22,8 @@ export function Button({
   variant = 'primary',
   size = 'md',
   type = 'button',
+  loading = false,
+  disabled,
   className,
   children,
   ...rest
@@ -29,7 +33,19 @@ export function Button({
     .join(' ');
 
   return (
-    <button type={type} className={classes} {...rest}>
+    <button
+      type={type}
+      className={classes}
+      disabled={disabled || loading}
+      aria-busy={loading || undefined}
+      {...rest}
+    >
+      {loading && (
+        // aria-hidden: the button's own accessible name (its visible children,
+        // unchanged below) plus aria-busy already communicate the pending
+        // state — an unhidden Spinner-style status region would double-narrate it.
+        <span className={styles.spinner} aria-hidden="true" />
+      )}
       {children}
     </button>
   );

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

@@ -34,4 +34,23 @@ describe('Button', () => {
     render(<Button variant="destructive">Delete</Button>);
     expect(screen.getByRole('button', { name: 'Delete' }).className).toContain('destructive');
   });
+
+  it('disables the button and sets aria-busy when loading', () => {
+    render(<Button loading>Submit</Button>);
+    const button = screen.getByRole('button', { name: 'Submit' }) as HTMLButtonElement;
+    expect(button.disabled).toBe(true);
+    expect(button.getAttribute('aria-busy')).toBe('true');
+  });
+
+  it('does not set aria-busy when not loading', () => {
+    render(<Button>Continue</Button>);
+    expect(screen.getByRole('button', { name: 'Continue' }).getAttribute('aria-busy')).toBeNull();
+  });
+
+  it('respects an explicit disabled prop independent of loading', () => {
+    render(<Button disabled>Archive</Button>);
+    const button = screen.getByRole('button', { name: 'Archive' }) as HTMLButtonElement;
+    expect(button.disabled).toBe(true);
+    expect(button.getAttribute('aria-busy')).toBeNull();
+  });
 });

package/src/components/Calendar/Calendar.module.css

@@ -0,0 +1,126 @@
+/* Calendar — month grid. Tokens only. Grid columns are equal-width via
+ * `1fr` repeated 7 times rather than a fixed px size, so the component
+ * scales cleanly inside both a Popover panel (desktop) and a full-width
+ * Drawer sheet (mobile). */
+
+.calendar {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sv-space-3);
+  font-family: var(--sv-font-family);
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--sv-space-2);
+}
+
+.navButton {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--sv-touch-target-min, 44px);
+  height: var(--sv-touch-target-min, 44px);
+  flex-shrink: 0;
+  border: none;
+  border-radius: var(--sv-radius-md);
+  background: transparent;
+  color: var(--sv-color-text-muted);
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .navButton:hover {
+    background: var(--sv-color-surface-sunken);
+    color: var(--sv-color-text-primary);
+  }
+}
+
+.navButton:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: -2px;
+}
+
+.monthLabel {
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-semibold);
+  color: var(--sv-color-text-primary);
+}
+
+.grid {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sv-space-1);
+}
+
+.weekdayRow,
+.week {
+  display: grid;
+  grid-template-columns: repeat(7, 1fr);
+}
+
+.weekday {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: var(--sv-space-6);
+  font-size: var(--sv-font-size-xs);
+  font-weight: var(--sv-font-weight-medium);
+  color: var(--sv-color-text-subtle);
+  text-transform: uppercase;
+}
+
+.day {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  /* Square-ish cell that also clears the touch-target minimum — height
+     drives the grid's row size; width fills its 1fr column. */
+  min-height: var(--sv-touch-target-min, 44px);
+  border: none;
+  border-radius: var(--sv-radius-md);
+  background: transparent;
+  color: var(--sv-color-text-primary);
+  font-size: var(--sv-font-size-sm);
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .day:hover:not(:disabled) {
+    background: var(--sv-color-surface-sunken);
+  }
+}
+
+.day:focus-visible {
+  outline: 2px solid var(--sv-color-focus-ring);
+  outline-offset: -2px;
+}
+
+.day:disabled {
+  color: var(--sv-color-text-subtle);
+  cursor: not-allowed;
+}
+
+.dayOutside {
+  color: var(--sv-color-text-subtle);
+}
+
+.dayToday {
+  font-weight: var(--sv-font-weight-semibold);
+  box-shadow: inset 0 0 0 1px var(--sv-color-border-strong);
+}
+
+.daySelected,
+.daySelected:disabled {
+  background: var(--sv-color-accent);
+  color: var(--sv-color-text-on-accent);
+}
+
+@media (hover: hover) {
+  .daySelected:hover:not(:disabled) {
+    background: var(--sv-color-accent-hover);
+  }
+}