@slipstream-ui/core 0.3.0 → 0.4.0

package/src/components/select-menu/SelectMenu.tsx

@@ -0,0 +1,368 @@
+'use client';
+
+import * as React from 'react';
+import { createPortal } from 'react-dom';
+import { cn } from '../../utils/cn';
+
+export type SelectMenuItem = {
+  value: string;
+  label: string;
+  /** Muted supporting line under the label. */
+  description?: string;
+  icon?: React.ReactNode;
+  disabled?: boolean;
+  /** Section heading the item renders under. */
+  group?: string;
+};
+
+export type SelectMenuProps = Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  'value' | 'defaultValue' | 'onChange' | 'children' | 'type'
+> & {
+  items: SelectMenuItem[];
+  /** Selected value(s): a string, or string[] when multiple. */
+  value?: string | string[];
+  defaultValue?: string | string[];
+  onValueChange?: (value: string | string[]) => void;
+  /** Allow choosing several items (the listbox stays open). */
+  multiple?: boolean;
+  placeholder?: string;
+  /** Name for hidden form inputs (renders one input per selected value). */
+  name?: string;
+  /** Custom trigger content for the current selection. */
+  renderValue?: (selected: SelectMenuItem[]) => React.ReactNode;
+  /** Custom option row. */
+  renderItem?: (item: SelectMenuItem, state: { selected: boolean; active: boolean }) => React.ReactNode;
+  emptyText?: string;
+};
+
+function useOutsideClose(open: boolean, close: () => void, refs: Array<React.RefObject<HTMLElement | null>>) {
+  React.useEffect(() => {
+    if (!open) return;
+    const onPointerDown = (event: MouseEvent) => {
+      const target = event.target as Node;
+      if (refs.some((ref) => ref.current?.contains(target))) return;
+      close();
+    };
+    document.addEventListener('mousedown', onPointerDown);
+    return () => document.removeEventListener('mousedown', onPointerDown);
+  }, [open, close, refs]);
+}
+
+/**
+ * Custom dropdown select for rich options: descriptions, icons, grouped
+ * headings, multi-select and custom row rendering. Unlike `Select` (native
+ * `<select>`), this renders a real listbox, so option content is not limited
+ * to text. Keyboard model follows the button/listbox pattern: arrows move the
+ * active option, Home/End jump, Enter/Space selects, Escape closes, and
+ * first-letter typeahead jumps to matching options.
+ */
+export const SelectMenu = React.forwardRef<HTMLButtonElement, SelectMenuProps>(function SelectMenu(
+  {
+    items,
+    value,
+    defaultValue,
+    onValueChange,
+    multiple = false,
+    placeholder = 'Select…',
+    name,
+    renderValue,
+    renderItem,
+    emptyText = 'No options',
+    className,
+    disabled,
+    onKeyDown,
+    ...buttonProps
+  },
+  ref
+) {
+  const [internal, setInternal] = React.useState<string[]>(() => {
+    if (defaultValue === undefined) return [];
+    return Array.isArray(defaultValue) ? defaultValue : [defaultValue];
+  });
+  const selectedValues = React.useMemo(() => {
+    if (value === undefined) return internal;
+    return Array.isArray(value) ? value : [value];
+  }, [value, internal]);
+
+  const [open, setOpen] = React.useState(false);
+  const [activeIndex, setActiveIndex] = React.useState(-1);
+  const [position, setPosition] = React.useState<{ top: number; left: number; width: number } | null>(null);
+  const triggerRef = React.useRef<HTMLButtonElement | null>(null);
+  const listRef = React.useRef<HTMLDivElement | null>(null);
+  const listboxId = React.useId();
+  const labelId = React.useId();
+  const typeahead = React.useRef({ query: '', at: 0 });
+
+  const setTriggerRef = React.useCallback(
+    (node: HTMLButtonElement | null) => {
+      triggerRef.current = node;
+      if (typeof ref === 'function') ref(node);
+      else if (ref) ref.current = node;
+    },
+    [ref]
+  );
+
+  const close = React.useCallback(() => setOpen(false), []);
+  useOutsideClose(open, close, [triggerRef, listRef]);
+
+  const measure = React.useCallback(() => {
+    const node = triggerRef.current;
+    if (!node) return;
+    const rect = node.getBoundingClientRect();
+    setPosition({ top: rect.bottom + 4, left: rect.left, width: Math.max(rect.width, 200) });
+  }, []);
+
+  React.useEffect(() => {
+    if (!open) return;
+    measure();
+    const onScroll = () => measure();
+    window.addEventListener('resize', onScroll);
+    window.addEventListener('scroll', onScroll, true);
+    return () => {
+      window.removeEventListener('resize', onScroll);
+      window.removeEventListener('scroll', onScroll, true);
+    };
+  }, [open, measure]);
+
+  // Index of the first enabled option for initial highlight.
+  const firstEnabled = React.useMemo(() => items.findIndex((item) => !item.disabled), [items]);
+
+  const openMenu = () => {
+    if (disabled) return;
+    setOpen(true);
+    const selectedIndex = items.findIndex((item) => selectedValues.includes(item.value) && !item.disabled);
+    setActiveIndex(selectedIndex >= 0 ? selectedIndex : firstEnabled);
+  };
+
+  const commit = (next: string[]) => {
+    if (value === undefined) setInternal(next);
+    onValueChange?.(multiple ? next : next[0] ?? '');
+  };
+
+  const select = (item: SelectMenuItem) => {
+    if (item.disabled) return;
+    if (multiple) {
+      const next = selectedValues.includes(item.value)
+        ? selectedValues.filter((entry) => entry !== item.value)
+        : [...selectedValues, item.value];
+      commit(next);
+      return;
+    }
+    commit([item.value]);
+    setOpen(false);
+  };
+
+  const move = (direction: 1 | -1) => {
+    if (items.length === 0) return;
+    let index = activeIndex;
+    for (let step = 0; step < items.length; step += 1) {
+      index = (index + direction + items.length) % items.length;
+      if (!items[index]?.disabled) {
+        setActiveIndex(index);
+        return;
+      }
+    }
+  };
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
+    onKeyDown?.(event);
+    if (event.defaultPrevented) return;
+
+    if (!open) {
+      if (event.key === 'ArrowDown' || event.key === 'ArrowUp' || event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault();
+        openMenu();
+      }
+      return;
+    }
+
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault();
+        move(1);
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        move(-1);
+        break;
+      case 'Home':
+        event.preventDefault();
+        setActiveIndex(firstEnabled);
+        break;
+      case 'End': {
+        event.preventDefault();
+        for (let i = items.length - 1; i >= 0; i -= 1) {
+          if (!items[i]?.disabled) {
+            setActiveIndex(i);
+            break;
+          }
+        }
+        break;
+      }
+      case 'Enter':
+      case ' ':
+        event.preventDefault();
+        if (activeIndex >= 0 && items[activeIndex]) select(items[activeIndex]);
+        break;
+      case 'Escape':
+        event.preventDefault();
+        setOpen(false);
+        break;
+      case 'Tab':
+        setOpen(false);
+        break;
+      default: {
+        if (event.key.length !== 1 || event.metaKey || event.ctrlKey || event.altKey) return;
+        const now = Date.now();
+        const buffer = now - typeahead.current.at > 600 ? event.key : typeahead.current.query + event.key;
+        typeahead.current = { query: buffer, at: now };
+        const query = buffer.toLowerCase();
+        const index = items.findIndex((item) => !item.disabled && item.label.toLowerCase().startsWith(query));
+        if (index >= 0) setActiveIndex(index);
+      }
+    }
+  };
+
+  const selectedItems = items.filter((item) => selectedValues.includes(item.value));
+  const triggerContent = renderValue ? (
+    renderValue(selectedItems)
+  ) : selectedItems.length === 0 ? (
+    <span className="text-muted-foreground">{placeholder}</span>
+  ) : multiple ? (
+    <span className="truncate">
+      {selectedItems.length === 1 ? selectedItems[0].label : `${selectedItems.length} selected`}
+    </span>
+  ) : (
+    <span className="truncate">{selectedItems[0].label}</span>
+  );
+
+  const activeOptionId = activeIndex >= 0 ? `${listboxId}-option-${activeIndex}` : undefined;
+
+  // Group headings, keeping the flat index aligned with `items`.
+  const rows = React.useMemo(() => {
+    const out: Array<{ heading?: string; item?: SelectMenuItem; index: number }> = [];
+    let lastGroup: string | undefined;
+    items.forEach((item, index) => {
+      if (item.group && item.group !== lastGroup) {
+        out.push({ heading: item.group, index: -1 });
+        lastGroup = item.group;
+      }
+      out.push({ item, index });
+    });
+    return out;
+  }, [items]);
+
+  return (
+    <>
+      <span id={labelId} className="sr-only">
+        {typeof buttonProps['aria-label'] === 'string' ? buttonProps['aria-label'] : 'Select'}
+      </span>
+      {name &&
+        selectedValues.map((selected) => (
+          <input key={selected} type="hidden" name={name} value={selected} />
+        ))}
+      <button
+        ref={setTriggerRef}
+        type="button"
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        aria-controls={open ? listboxId : undefined}
+        aria-activedescendant={open ? activeOptionId : undefined}
+        aria-labelledby={labelId}
+        disabled={disabled}
+        onClick={() => (open ? setOpen(false) : openMenu())}
+        onKeyDown={handleKeyDown}
+        className={cn(
+          'flex h-10 w-full items-center justify-between gap-2 rounded-md border border-input bg-background px-3 py-2 text-left text-sm',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+          'disabled:cursor-not-allowed disabled:opacity-50',
+          className
+        )}
+        {...buttonProps}
+      >
+        <span className="min-w-0 flex-1">{triggerContent}</span>
+        <span aria-hidden="true" className="text-muted-foreground">▾</span>
+      </button>
+
+      {open &&
+        position &&
+        createPortal(
+          <div
+            ref={listRef}
+            id={listboxId}
+            role="listbox"
+            aria-labelledby={labelId}
+            aria-multiselectable={multiple || undefined}
+            style={{
+              position: 'fixed',
+              top: position.top,
+              left: position.left,
+              width: position.width,
+              zIndex: 50,
+            }}
+            className="max-h-64 overflow-y-auto rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-md"
+          >
+            {items.length === 0 ? (
+              <p role="presentation" className="px-3 py-2 text-sm text-muted-foreground">
+                {emptyText}
+              </p>
+            ) : (
+              rows.map((row, rowIndex) =>
+                row.heading ? (
+                  <p
+                    key={`heading-${row.heading}-${rowIndex}`}
+                    role="presentation"
+                    className="px-3 pb-1 pt-2 text-xs font-medium uppercase tracking-wide text-muted-foreground"
+                  >
+                    {row.heading}
+                  </p>
+                ) : (
+                  <div
+                    key={row.item!.value}
+                    id={`${listboxId}-option-${row.index}`}
+                    role="option"
+                    aria-selected={selectedValues.includes(row.item!.value)}
+                    aria-disabled={row.item!.disabled || undefined}
+                    onMouseDown={(event) => event.preventDefault()}
+                    onMouseEnter={() => !row.item!.disabled && setActiveIndex(row.index)}
+                    onClick={() => select(row.item!)}
+                    className={cn(
+                      'flex cursor-pointer items-start gap-2 rounded-sm px-3 py-2 text-sm outline-none',
+                      row.index === activeIndex ? 'bg-accent text-accent-foreground' : 'hover:bg-accent/60',
+                      row.item!.disabled && 'pointer-events-none opacity-50'
+                    )}
+                  >
+                    {renderItem ? (
+                      renderItem(row.item!, {
+                        selected: selectedValues.includes(row.item!.value),
+                        active: row.index === activeIndex,
+                      })
+                    ) : (
+                      <>
+                        {row.item!.icon && <span className="mt-0.5 shrink-0 [&_svg]:size-4">{row.item!.icon}</span>}
+                        <span className="min-w-0 flex-1">
+                          <span className="block">{row.item!.label}</span>
+                          {row.item!.description && (
+                            <span className="mt-0.5 block text-xs text-muted-foreground">
+                              {row.item!.description}
+                            </span>
+                          )}
+                        </span>
+                        {multiple && selectedValues.includes(row.item!.value) && (
+                          <span aria-hidden="true" className="ml-auto text-primary">
+                            ✓
+                          </span>
+                        )}
+                      </>
+                    )}
+                  </div>
+                )
+              )
+            )}
+          </div>,
+          document.body
+        )}
+    </>
+  );
+});

package/src/components/select-menu/index.ts

@@ -0,0 +1 @@
+export * from './SelectMenu';

package/src/components/stepper/Stepper.test.tsx

@@ -0,0 +1,35 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { axe } from 'jest-axe';
+import { describe, expect, it, vi } from 'vitest';
+import { Stepper } from './Stepper';
+
+const steps = [{ label: 'Account' }, { label: 'Details', description: 'Studio info' }, { label: 'Review' }];
+
+describe('Stepper', () => {
+  it('marks the active step with aria-current and states progress in text', () => {
+    render(<Stepper steps={steps} current={1} />);
+    const current = screen.getByText('Details').closest('[aria-current]');
+    expect(current).toHaveAttribute('aria-current', 'step');
+    expect(screen.getByText('(completed)')).toBeInTheDocument();
+    expect(screen.getByText('(upcoming)')).toBeInTheDocument();
+  });
+
+  it('makes steps clickable when onStepClick is provided', async () => {
+    const user = userEvent.setup();
+    const onStepClick = vi.fn();
+    render(<Stepper steps={steps} current={0} onStepClick={onStepClick} />);
+    await user.click(screen.getByRole('button', { name: /Review/ }));
+    expect(onStepClick).toHaveBeenCalledWith(2);
+  });
+
+  it('supports vertical orientation', () => {
+    const { container } = render(<Stepper steps={steps} current={0} orientation="vertical" />);
+    expect(container.querySelector('ol')).toHaveClass('flex-col');
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<Stepper steps={steps} current={1} />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/components/stepper/Stepper.tsx

@@ -0,0 +1,91 @@
+import * as React from 'react';
+import { cn } from '../../utils/cn';
+
+export type StepperStep = {
+  label: string;
+  description?: string;
+};
+
+export type StepperProps = Omit<React.OlHTMLAttributes<HTMLOListElement>, 'onClick'> & {
+  steps: StepperStep[];
+  /** Zero-based index of the active step. */
+  current: number;
+  orientation?: 'horizontal' | 'vertical';
+  /** Makes completed/upcoming steps clickable. */
+  onStepClick?: (index: number) => void;
+};
+
+/**
+ * Progress through a multi-step flow with proper semantics: an ordered list
+ * where the active step carries aria-current="step" and each marker states
+ * complete/current/upcoming in text, not only color.
+ */
+export const Stepper = React.forwardRef<HTMLOListElement, StepperProps>(function Stepper(
+  { steps, current, orientation = 'horizontal', onStepClick, className, ...props },
+  ref
+) {
+  return (
+    <ol
+      ref={ref}
+      className={cn(
+        'flex gap-4',
+        orientation === 'vertical' ? 'flex-col' : 'flex-wrap items-start',
+        className
+      )}
+      {...props}
+    >
+      {steps.map((step, index) => {
+        const state = index < current ? 'complete' : index === current ? 'current' : 'upcoming';
+        const interactive = Boolean(onStepClick);
+        const content = (
+          <>
+            <span
+              aria-hidden="true"
+              className={cn(
+                'flex h-7 w-7 shrink-0 items-center justify-center rounded-full border text-xs font-medium',
+                state === 'complete' && 'border-primary bg-primary text-primary-foreground',
+                state === 'current' && 'border-primary text-primary',
+                state === 'upcoming' && 'border-border text-muted-foreground'
+              )}
+            >
+              {state === 'complete' ? '✓' : index + 1}
+            </span>
+            <span className="min-w-0">
+              <span className={cn('block text-sm', state === 'upcoming' ? 'text-muted-foreground' : 'font-medium')}>
+                {step.label}
+              </span>
+              {step.description && (
+                <span className="block text-xs text-muted-foreground">{step.description}</span>
+              )}
+              <span className="sr-only">
+                {state === 'complete' ? ' (completed)' : state === 'current' ? ' (current step)' : ' (upcoming)'}
+              </span>
+            </span>
+          </>
+        );
+
+        return (
+          <li key={step.label} className="flex min-w-0 items-start gap-2">
+            {interactive ? (
+              <button
+                type="button"
+                onClick={() => onStepClick?.(index)}
+                aria-current={state === 'current' ? 'step' : undefined}
+                className="flex items-start gap-2 rounded-md text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              >
+                {content}
+              </button>
+            ) : (
+              <div aria-current={state === 'current' ? 'step' : undefined} className="flex items-start gap-2">
+                {content}
+              </div>
+            )}
+            {orientation === 'horizontal' && index < steps.length - 1 && (
+              <span aria-hidden="true" className="mt-3.5 hidden h-px w-8 bg-border sm:block" />
+            )}
+          </li>
+        );
+      })}
+    </ol>
+  );
+});

package/src/components/stepper/index.ts

@@ -0,0 +1 @@
+export * from './Stepper';

package/src/components/table-card/TableCard.test.tsx

@@ -0,0 +1,59 @@
+import { render, screen } from '@testing-library/react';
+import { axe } from 'jest-axe';
+import { describe, expect, it } from 'vitest';
+import { TableCard } from './TableCard';
+
+describe('TableCard', () => {
+  it('renders header, toolbar, body and footer', () => {
+    render(
+      <TableCard
+        title="Classes"
+        description="12 active"
+        actions={<button type="button">New</button>}
+        toolbar={<span>filters</span>}
+        footer={<span>Showing 1–25 of 40</span>}
+      >
+        <table aria-label="Classes table">
+          <tbody>
+            <tr>
+              <td>Yoga</td>
+            </tr>
+          </tbody>
+        </table>
+      </TableCard>
+    );
+    expect(screen.getByRole('heading', { name: 'Classes' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'New' })).toBeInTheDocument();
+    expect(screen.getByText('filters')).toBeInTheDocument();
+    expect(screen.getByRole('table', { name: 'Classes table' })).toBeInTheDocument();
+    expect(screen.getByText('Showing 1–25 of 40')).toBeInTheDocument();
+  });
+
+  it('renders without chrome when no header props are given', () => {
+    const { container } = render(
+      <TableCard>
+        <span>body</span>
+      </TableCard>
+    );
+    expect(container.querySelector('h2')).toBeNull();
+    expect(screen.getByText('body')).toBeInTheDocument();
+  });
+
+  it('supports padded (non-flush) content', () => {
+    const { container } = render(
+      <TableCard flush={false}>
+        <span>padded</span>
+      </TableCard>
+    );
+    expect(container.querySelector('.p-4')).not.toBeNull();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <TableCard title="Empty">
+        <p>Nothing to show</p>
+      </TableCard>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/components/table-card/TableCard.tsx

@@ -0,0 +1,48 @@
+import * as React from 'react';
+import { cn } from '../../utils/cn';
+
+export type TableCardProps = React.HTMLAttributes<HTMLDivElement> & {
+  title?: string;
+  description?: string;
+  /** Right-aligned header actions (create, export, column settings). */
+  actions?: React.ReactNode;
+  /** Row between the header and the table (filters, bulk actions). */
+  toolbar?: React.ReactNode;
+  /** Table/DataTable content. */
+  children: React.ReactNode;
+  /** Rendered under the table (pagination, summary). */
+  footer?: React.ReactNode;
+  /** Remove the inner padding so table edges reach the card border. */
+  flush?: boolean;
+};
+
+/**
+ * Table shell: title/description + actions, an optional toolbar, an
+ * edge-to-edge table body and a footer row. Standardizes the chrome every
+ * list page grows around a Table or DataTable.
+ */
+export const TableCard = React.forwardRef<HTMLDivElement, TableCardProps>(function TableCard(
+  { title, description, actions, toolbar, children, footer, flush = true, className, ...props },
+  ref
+) {
+  return (
+    <div
+      ref={ref}
+      className={cn('overflow-hidden rounded-xl border border-border bg-card text-card-foreground', className)}
+      {...props}
+    >
+      {(title || description || actions) && (
+        <div className="flex flex-wrap items-start justify-between gap-3 border-b border-border px-4 py-3">
+          <div className="min-w-0">
+            {title && <h2 className="text-sm font-semibold">{title}</h2>}
+            {description && <p className="mt-0.5 text-sm text-muted-foreground">{description}</p>}
+          </div>
+          {actions && <div className="flex shrink-0 items-center gap-2">{actions}</div>}
+        </div>
+      )}
+      {toolbar && <div className="border-b border-border px-4 py-2">{toolbar}</div>}
+      <div className={cn(flush ? 'overflow-x-auto' : 'p-4')}>{children}</div>
+      {footer && <div className="border-t border-border px-4 py-3">{footer}</div>}
+    </div>
+  );
+});

package/src/components/table-card/index.ts

@@ -0,0 +1 @@
+export * from './TableCard';

package/src/components/time-picker/TimePicker.test.tsx

@@ -0,0 +1,30 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { axe } from 'jest-axe';
+import { describe, expect, it, vi } from 'vitest';
+import { TimePicker } from './TimePicker';
+
+describe('TimePicker', () => {
+  it('renders a time input and reports changes', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<TimePicker aria-label="Starts at" onValueChange={onValueChange} />);
+    const input = screen.getByLabelText('Starts at');
+    expect(input).toHaveAttribute('type', 'time');
+    await user.type(input, '09:30');
+    expect(onValueChange).toHaveBeenCalled();
+  });
+
+  it('clears the value', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<TimePicker aria-label="Ends" clearable defaultValue="17:00" onValueChange={onValueChange} />);
+    await user.click(screen.getByRole('button', { name: 'Clear time' }));
+    expect(onValueChange).toHaveBeenCalledWith('');
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<TimePicker aria-label="Time" />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});