@sovereignfs/ui 0.23.0 → 0.33.1

package/src/components/Calendar/Calendar.tsx

@@ -0,0 +1,213 @@
+'use client';
+
+import { type KeyboardEvent as ReactKeyboardEvent, useRef, useState } from 'react';
+import { Icon } from '../Icon/Icon';
+import {
+  addDays,
+  addMonths,
+  formatDateLabel,
+  formatMonthYear,
+  formatWeekdayShort,
+  getMonthGrid,
+  isSameDay,
+  isSameMonth,
+  isWithinRange,
+  startOfMonth,
+} from './dateUtils';
+import styles from './Calendar.module.css';
+
+export interface CalendarProps {
+  /** Selected date, or `null` for no selection. */
+  value: Date | null;
+  onChange: (date: Date) => void;
+  /** Dates before this are disabled and unselectable. */
+  minDate?: Date;
+  /** Dates after this are disabled and unselectable. */
+  maxDate?: Date;
+  'aria-label'?: string;
+}
+
+// A week's worth of dates, used once to derive the weekday header labels —
+// any Sunday-starting week works since only the day-of-week repeats.
+// getMonthGrid always returns 6 weeks (see its own doc comment), so index 0
+// is guaranteed to exist — the `?? []` is purely to satisfy the lint rule
+// against non-null assertions, not a real runtime possibility.
+const WEEKDAY_LABEL_WEEK = getMonthGrid(new Date(2026, 0, 1))[0] ?? [];
+
+/**
+ * Calendar — a keyboard-navigable month grid. Date-only (no time or range
+ * selection — decision D6 in the mobile design-system plan); a `DatePicker`
+ * field wraps this in a `Popover` (desktop) or `Drawer` (mobile).
+ *
+ * Keyboard (WAI-ARIA APG grid pattern, roving tabindex — exactly one day
+ * button is ever tab-stoppable): arrow keys move focus by day/week, Home/End
+ * jump to the start/end of the focused week, PageUp/PageDown change month,
+ * Enter/Space selects the focused date. Navigating into an adjacent month
+ * (arrow keys at a week's edge, or PageUp/PageDown) updates the displayed
+ * month to follow focus.
+ */
+export function Calendar({
+  value,
+  onChange,
+  minDate,
+  maxDate,
+  'aria-label': ariaLabel,
+}: CalendarProps) {
+  const [displayedMonth, setDisplayedMonth] = useState(() => startOfMonth(value ?? new Date()));
+  // The roving-tabindex date. Independent of `value` — you can arrow around
+  // without selecting; Enter/Space is what commits a selection.
+  const [focusedDate, setFocusedDate] = useState(() => value ?? new Date());
+  const gridRef = useRef<HTMLDivElement>(null);
+
+  const weeks = getMonthGrid(displayedMonth);
+
+  function goToMonth(next: Date) {
+    setDisplayedMonth(startOfMonth(next));
+  }
+
+  function moveFocus(next: Date) {
+    setFocusedDate(next);
+    if (!isSameMonth(next, displayedMonth)) goToMonth(next);
+    // Focus is applied after the grid re-renders with the new roving
+    // tabindex target — see the ref callback below on each day button,
+    // which focuses itself when it becomes the tabIndex=0 cell following a
+    // keyboard-driven focus change (queued via requestAnimationFrame so the
+    // DOM has committed the new grid first).
+    requestAnimationFrame(() => {
+      gridRef.current?.querySelector<HTMLButtonElement>('[tabindex="0"]')?.focus();
+    });
+  }
+
+  function selectDate(date: Date) {
+    if (!isWithinRange(date, minDate, maxDate)) return;
+    onChange(date);
+    setFocusedDate(date);
+  }
+
+  function handleKeyDown(e: ReactKeyboardEvent) {
+    switch (e.key) {
+      case 'ArrowLeft':
+        e.preventDefault();
+        moveFocus(addDays(focusedDate, -1));
+        return;
+      case 'ArrowRight':
+        e.preventDefault();
+        moveFocus(addDays(focusedDate, 1));
+        return;
+      case 'ArrowUp':
+        e.preventDefault();
+        moveFocus(addDays(focusedDate, -7));
+        return;
+      case 'ArrowDown':
+        e.preventDefault();
+        moveFocus(addDays(focusedDate, 7));
+        return;
+      case 'Home':
+        e.preventDefault();
+        moveFocus(addDays(focusedDate, -focusedDate.getDay()));
+        return;
+      case 'End':
+        e.preventDefault();
+        moveFocus(addDays(focusedDate, 6 - focusedDate.getDay()));
+        return;
+      case 'PageUp':
+        e.preventDefault();
+        moveFocus(addMonths(focusedDate, -1));
+        return;
+      case 'PageDown':
+        e.preventDefault();
+        moveFocus(addMonths(focusedDate, 1));
+        return;
+      case 'Enter':
+      case ' ':
+        e.preventDefault();
+        selectDate(focusedDate);
+        return;
+      default:
+    }
+  }
+
+  return (
+    <div className={styles.calendar} aria-label={ariaLabel}>
+      <div className={styles.header}>
+        <button
+          type="button"
+          className={styles.navButton}
+          aria-label="Previous month"
+          onClick={() => goToMonth(addMonths(displayedMonth, -1))}
+        >
+          <Icon name="chevron-left" size="sm" aria-hidden />
+        </button>
+        <span className={styles.monthLabel}>{formatMonthYear(displayedMonth)}</span>
+        <button
+          type="button"
+          className={styles.navButton}
+          aria-label="Next month"
+          onClick={() => goToMonth(addMonths(displayedMonth, 1))}
+        >
+          <Icon name="chevron-right" size="sm" aria-hidden />
+        </button>
+      </div>
+
+      <div
+        ref={gridRef}
+        role="grid"
+        aria-label={formatMonthYear(displayedMonth)}
+        className={styles.grid}
+        onKeyDown={handleKeyDown}
+        // Keyboard handling relies on roving tabindex on the day buttons
+        // (real DOM focus + bubbling), not on this container being a tab
+        // stop itself — tabIndex={-1} only satisfies jsx-a11y's expectation
+        // that an element carrying a keydown handler + interactive role be
+        // focusable; it does not change Tab-key reachability.
+        tabIndex={-1}
+      >
+        <div role="row" className={styles.weekdayRow}>
+          {WEEKDAY_LABEL_WEEK.map((d) => (
+            <span key={d.getDay()} role="columnheader" className={styles.weekday} aria-hidden>
+              {formatWeekdayShort(d)}
+            </span>
+          ))}
+        </div>
+        {weeks.map((week) => {
+          const firstDayOfWeek = week[0];
+          if (!firstDayOfWeek) return null;
+          return (
+            <div role="row" className={styles.week} key={firstDayOfWeek.toISOString()}>
+              {week.map((date) => {
+                const isCurrentMonth = isSameMonth(date, displayedMonth);
+                const isSelected = value !== null && isSameDay(date, value);
+                const isToday = isSameDay(date, new Date());
+                const isFocusTarget = isSameDay(date, focusedDate);
+                const disabled = !isWithinRange(date, minDate, maxDate);
+                return (
+                  <div role="gridcell" aria-selected={isSelected} key={date.toISOString()}>
+                    <button
+                      type="button"
+                      tabIndex={isFocusTarget ? 0 : -1}
+                      disabled={disabled}
+                      aria-current={isToday ? 'date' : undefined}
+                      aria-label={formatDateLabel(date)}
+                      className={[
+                        styles.day,
+                        !isCurrentMonth ? styles.dayOutside : '',
+                        isSelected ? styles.daySelected : '',
+                        isToday && !isSelected ? styles.dayToday : '',
+                      ]
+                        .filter(Boolean)
+                        .join(' ')}
+                      onClick={() => selectDate(date)}
+                      onFocus={() => setFocusedDate(date)}
+                    >
+                      {date.getDate()}
+                    </button>
+                  </div>
+                );
+              })}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,98 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { Calendar } from '../Calendar';
+
+// A fixed reference date so tests are deterministic regardless of when they run.
+const JAN_15_2026 = new Date(2026, 0, 15); // Thursday
+
+describe('Calendar', () => {
+  afterEach(cleanup);
+
+  it('renders the displayed month and year', () => {
+    render(<Calendar value={JAN_15_2026} onChange={() => {}} />);
+    expect(screen.getByText('January 2026')).toBeTruthy();
+  });
+
+  it('marks the selected date', () => {
+    render(<Calendar value={JAN_15_2026} onChange={() => {}} />);
+    const button = screen.getByRole('button', { name: /Thursday, January 15, 2026/ });
+    // aria-selected lives on the gridcell (the button's parent), not the
+    // button itself — the button role doesn't support aria-selected.
+    expect(button.parentElement?.getAttribute('aria-selected')).toBe('true');
+  });
+
+  it('calls onChange with the clicked date', () => {
+    const onChange = vi.fn();
+    render(<Calendar value={JAN_15_2026} onChange={onChange} />);
+    fireEvent.click(screen.getByRole('button', { name: /January 20, 2026/ }));
+    expect(onChange).toHaveBeenCalledOnce();
+    const called = onChange.mock.calls[0]?.[0] as Date;
+    expect(called.getDate()).toBe(20);
+    expect(called.getMonth()).toBe(0);
+    expect(called.getFullYear()).toBe(2026);
+  });
+
+  it('navigates to the next and previous month', () => {
+    render(<Calendar value={JAN_15_2026} onChange={() => {}} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Next month' }));
+    expect(screen.getByText('February 2026')).toBeTruthy();
+    fireEvent.click(screen.getByRole('button', { name: 'Previous month' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Previous month' }));
+    expect(screen.getByText('December 2025')).toBeTruthy();
+  });
+
+  it('disables and does not select dates outside minDate/maxDate', () => {
+    const onChange = vi.fn();
+    render(
+      <Calendar
+        value={JAN_15_2026}
+        onChange={onChange}
+        minDate={new Date(2026, 0, 10)}
+        maxDate={new Date(2026, 0, 20)}
+      />,
+    );
+    const outOfRange = screen.getByRole('button', { name: /January 5, 2026/ });
+    expect(outOfRange.hasAttribute('disabled')).toBe(true);
+    fireEvent.click(outOfRange);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('exposes exactly one roving tabIndex=0 day at a time', () => {
+    render(<Calendar value={JAN_15_2026} onChange={() => {}} />);
+    const zeroTabIndex = document.querySelectorAll('[role="gridcell"] button[tabindex="0"]');
+    expect(zeroTabIndex.length).toBe(1);
+    expect(zeroTabIndex[0]?.getAttribute('aria-label')).toMatch(/January 15, 2026/);
+  });
+
+  it('moves the roving tabIndex with ArrowRight and selects with Enter', () => {
+    const onChange = vi.fn();
+    render(<Calendar value={JAN_15_2026} onChange={onChange} />);
+    const grid = screen.getByRole('grid');
+    fireEvent.keyDown(grid, { key: 'ArrowRight' });
+    const zeroTabIndex = document.querySelector('[role="gridcell"] button[tabindex="0"]');
+    expect(zeroTabIndex?.getAttribute('aria-label')).toMatch(/January 16, 2026/);
+    fireEvent.keyDown(grid, { key: 'Enter' });
+    expect(onChange).toHaveBeenCalledOnce();
+    const called = onChange.mock.calls[0]?.[0] as Date;
+    expect(called.getDate()).toBe(16);
+  });
+
+  it('PageDown advances the focused date and displayed month by one month', () => {
+    render(<Calendar value={JAN_15_2026} onChange={() => {}} />);
+    const grid = screen.getByRole('grid');
+    fireEvent.keyDown(grid, { key: 'PageDown' });
+    expect(screen.getByText('February 2026')).toBeTruthy();
+  });
+
+  it('marks today distinctly from an ordinary day', () => {
+    const today = new Date();
+    render(<Calendar value={null} onChange={() => {}} />);
+    const todayLabel = screen.getByRole('button', {
+      name: new RegExp(
+        `${today.toLocaleDateString(undefined, { month: 'long' })} ${today.getDate()}, ${today.getFullYear()}`,
+      ),
+    });
+    expect(todayLabel.getAttribute('aria-current')).toBe('date');
+  });
+});

package/src/components/Calendar/dateUtils.ts

@@ -0,0 +1,97 @@
+// Plain-Date helpers for Calendar — deliberately self-contained (no date
+// library dependency, matching @sovereignfs/ui's zero-extra-dependency
+// philosophy). Every function operates on local calendar dates only; there is
+// no timezone or time-of-day handling here — Calendar is date-only (decision
+// D6 in the mobile design-system plan). Time and range selection are future
+// scope.
+
+export function startOfMonth(date: Date): Date {
+  return new Date(date.getFullYear(), date.getMonth(), 1);
+}
+
+export function addMonths(date: Date, count: number): Date {
+  return new Date(date.getFullYear(), date.getMonth() + count, date.getDate());
+}
+
+export function addDays(date: Date, count: number): Date {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate() + count);
+}
+
+export function isSameDay(a: Date, b: Date): boolean {
+  return (
+    a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+  );
+}
+
+export function isSameMonth(a: Date, b: Date): boolean {
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+}
+
+export function isBeforeDay(a: Date, b: Date): boolean {
+  return (
+    a.getFullYear() < b.getFullYear() ||
+    (a.getFullYear() === b.getFullYear() &&
+      (a.getMonth() < b.getMonth() || (a.getMonth() === b.getMonth() && a.getDate() < b.getDate())))
+  );
+}
+
+export function isAfterDay(a: Date, b: Date): boolean {
+  return isBeforeDay(b, a);
+}
+
+export function isWithinRange(date: Date, min?: Date, max?: Date): boolean {
+  if (min && isBeforeDay(date, min)) return false;
+  if (max && isAfterDay(date, max)) return false;
+  return true;
+}
+
+/**
+ * A 6x7 grid of dates covering `month` (any date within the target month),
+ * padded with the trailing days of the previous month and the leading days
+ * of the next so every week is a full row — Sunday-first. 6 rows always
+ * (rather than the 4-6 a month strictly needs) so the grid's own height never
+ * changes as the displayed month changes, avoiding a layout jump.
+ */
+export function getMonthGrid(month: Date): Date[][] {
+  const first = startOfMonth(month);
+  const startOffset = first.getDay(); // 0 (Sun) .. 6 (Sat)
+  const gridStart = addDays(first, -startOffset);
+
+  const weeks: Date[][] = [];
+  for (let week = 0; week < 6; week++) {
+    const days: Date[] = [];
+    for (let day = 0; day < 7; day++) {
+      days.push(addDays(gridStart, week * 7 + day));
+    }
+    weeks.push(days);
+  }
+  return weeks;
+}
+
+export function formatMonthYear(date: Date): string {
+  return new Intl.DateTimeFormat(undefined, { month: 'long', year: 'numeric' }).format(date);
+}
+
+export function formatWeekdayShort(date: Date): string {
+  return new Intl.DateTimeFormat(undefined, { weekday: 'short' }).format(date);
+}
+
+/** Compact form for a trigger/field display — e.g. "Jan 15, 2026". */
+export function formatDateShort(date: Date): string {
+  return new Intl.DateTimeFormat(undefined, {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+  }).format(date);
+}
+
+export function formatDateLabel(date: Date): string {
+  return new Intl.DateTimeFormat(undefined, {
+    weekday: 'long',
+    month: 'long',
+    day: 'numeric',
+    year: 'numeric',
+  }).format(date);
+}

package/src/components/Card/Card.module.css

@@ -24,8 +24,10 @@
   transition: border-color 0.15s ease;
 }
 
-.interactive:hover {
-  border-color: var(--sv-color-border-strong);
+@media (hover: hover) {
+  .interactive:hover {
+    border-color: var(--sv-color-border-strong);
+  }
 }
 
 .interactive:focus-visible {

package/src/components/Checkbox/Checkbox.module.css

@@ -7,10 +7,11 @@
 
 /* The visual box */
 .box {
+  --checkbox-box-size: 18px;
   position: relative;
   flex-shrink: 0;
-  width: 18px;
-  height: 18px;
+  width: var(--checkbox-box-size);
+  height: var(--checkbox-box-size);
   border-radius: var(--sv-radius-sm);
   border: 1.5px solid var(--sv-color-border-strong);
   background: var(--sv-color-surface);
@@ -43,6 +44,17 @@
   cursor: not-allowed;
 }
 
+/* Expand the tappable region to the platform's minimum touch target without
+   growing the visible box — consumers (e.g. task rows) align the box to the
+   pixel against header icons, so its visual footprint and layout must stay
+   identical. Gated to (pointer: coarse), the *primary* pointer, so a
+   touchscreen laptop with mouse/trackpad as primary keeps desktop density. */
+@media (pointer: coarse) {
+  .input {
+    inset: calc((var(--checkbox-box-size) - var(--sv-touch-target-min, 44px)) / 2);
+  }
+}
+
 .input:focus-visible + .tick,
 .input:focus-visible {
   outline: none;

package/src/components/Checkbox/Checkbox.tsx

@@ -51,18 +51,28 @@ export function Checkbox({
           </svg>
         )}
       </span>
-      <label
-        htmlFor={inputId}
-        className={[
-          styles.label,
-          strikeThrough && checked ? styles.struck : '',
-          disabled ? styles.disabled : '',
-        ]
-          .filter(Boolean)
-          .join(' ')}
-      >
-        {label}
-      </label>
+      {/* Callers pass label="" for icon-only/screen-reader-only usage (an
+          aria-label on the Checkbox's own root covers accessibility in that
+          case) — omitting the element entirely, rather than rendering an
+          empty <label>, matters because .root's flex `gap` still applies
+          between .box and a rendered-but-empty label, silently adding an
+          extra --sv-space-2 of invisible space after the checkbox that
+          every icon-only consumer was unknowingly stacking on top of their
+          own layout's spacing. */}
+      {label && (
+        <label
+          htmlFor={inputId}
+          className={[
+            styles.label,
+            strikeThrough && checked ? styles.struck : '',
+            disabled ? styles.disabled : '',
+          ]
+            .filter(Boolean)
+            .join(' ')}
+        >
+          {label}
+        </label>
+      )}
     </span>
   );
 }

package/src/components/CodeTextarea/CodeTextarea.module.css

@@ -0,0 +1,53 @@
+.textarea {
+  display: block;
+  width: 100%;
+  min-height: 180px;
+  max-height: min(70vh, 720px);
+  padding: var(--sv-space-3);
+  font-family: var(--sv-font-family-mono);
+  font-size: var(--sv-font-size-sm);
+  line-height: 1.6;
+  color: var(--sv-color-text-primary);
+  tab-size: 2;
+  white-space: pre;
+  overflow: auto;
+  resize: vertical;
+  background: var(--sv-color-surface);
+  border: 1px solid var(--sv-color-border-strong);
+  border-radius: var(--sv-radius-md);
+  transition:
+    border-color 0.15s ease,
+    box-shadow 0.15s ease;
+}
+
+.textarea::placeholder {
+  color: var(--sv-color-text-muted);
+}
+
+.textarea:focus-visible {
+  outline: none;
+  border-color: var(--sv-color-accent);
+  box-shadow: 0 0 0 2px var(--sv-color-focus-ring);
+}
+
+.textarea:read-only {
+  color: var(--sv-color-text-muted);
+  background: var(--sv-color-surface-sunken);
+  border-color: var(--sv-color-border);
+  cursor: default;
+}
+
+.textarea:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  resize: none;
+}
+
+.invalid {
+  border-color: var(--sv-color-error-border);
+}
+
+.invalid:focus-visible {
+  border-color: var(--sv-color-error-border);
+  box-shadow: 0 0 0 2px var(--sv-color-error-border);
+}

package/src/components/CodeTextarea/CodeTextarea.stories.tsx

@@ -0,0 +1,77 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { CodeTextarea } from './CodeTextarea';
+import { FormField } from '../FormField/FormField';
+
+const sampleMarkdown = `---
+title: Editorial calendar
+tags:
+  - planning
+  - launch
+---
+
+# Launch notes
+
+Draft the announcement and verify links before publishing.`;
+
+const meta = {
+  title: 'Components/CodeTextarea',
+  component: CodeTextarea,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Monospace textarea for Markdown, YAML, JSON, and other whitespace-sensitive content.',
+      },
+    },
+  },
+  args: {
+    defaultValue: sampleMarkdown,
+    'aria-label': 'Markdown source',
+  },
+} satisfies Meta<typeof CodeTextarea>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithFormField: Story = {
+  render: () => (
+    <FormField label="Frontmatter" hint="YAML is saved exactly as typed." id="frontmatter-source">
+      {(field) => <CodeTextarea {...field} defaultValue={sampleMarkdown} />}
+    </FormField>
+  ),
+};
+
+export const Error: Story = {
+  render: () => (
+    <FormField label="Raw YAML" error="Line 3: expected a value." id="yaml-source">
+      {(field) => <CodeTextarea {...field} invalid defaultValue={'title:\ntags:\n  -'} />}
+    </FormField>
+  ),
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    defaultValue: sampleMarkdown,
+  },
+};
+
+export const LongContent: Story = {
+  args: {
+    defaultValue: Array.from({ length: 24 }, (_, index) => `- item-${index + 1}: pending`).join(
+      '\n',
+    ),
+  },
+};
+
+export const Mobile: Story = {
+  parameters: {
+    viewport: { defaultViewport: 'mobile1' },
+  },
+  args: {
+    defaultValue: sampleMarkdown,
+  },
+};

package/src/components/CodeTextarea/CodeTextarea.tsx

@@ -0,0 +1,36 @@
+import type { TextareaHTMLAttributes } from 'react';
+import styles from './CodeTextarea.module.css';
+
+export interface CodeTextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+  invalid?: boolean;
+}
+
+/**
+ * CodeTextarea — monospace textarea for Markdown, YAML, JSON, and other
+ * whitespace-sensitive content. Pair with FormField for labels, hints, and
+ * validation text.
+ */
+export function CodeTextarea({
+  className,
+  rows = 12,
+  spellCheck = false,
+  wrap = 'off',
+  invalid = false,
+  'aria-invalid': ariaInvalid,
+  ...rest
+}: CodeTextareaProps) {
+  const classes = [styles.textarea, invalid ? styles.invalid : undefined, className]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <textarea
+      rows={rows}
+      spellCheck={spellCheck}
+      wrap={wrap}
+      className={classes}
+      aria-invalid={ariaInvalid ?? (invalid || undefined)}
+      {...rest}
+    />
+  );
+}