@wibly/ui-kit 0.1.1

package/src/components/prompt-input.test.tsx

@@ -0,0 +1,143 @@
+/**
+ * Tier-1 invariant tests for `PromptInput`.
+ *
+ * Per Dev Spec §6.6 chunk-B10 acceptance: "PromptInput's character
+ * cap (cap enforced; trims correctly; does not break on multi-byte
+ * characters)."
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { useState } from 'react';
+
+import { PromptInput, type PromptInputProps } from './prompt-input.js';
+
+/**
+ * Most tests need React state semantics — `onChange` updates a
+ * caller-side store; the next render reflects the cap behaviour.
+ * The harness wires that store inline so the test files don't have
+ * to re-implement it per case.
+ */
+const Harness = (props: Omit<PromptInputProps, 'value' | 'onChange'> & {
+  readonly initialValue?: string;
+  readonly onChangeSpy?: (next: string) => void;
+}) => {
+  const { initialValue, onChangeSpy, ...rest } = props;
+  const [value, setValue] = useState(initialValue ?? '');
+  return (
+    <PromptInput
+      {...rest}
+      value={value}
+      onChange={(next) => {
+        onChangeSpy?.(next);
+        setValue(next);
+      }}
+    />
+  );
+};
+
+describe('PromptInput', () => {
+  it('renders a controlled textarea with the supplied value', () => {
+    render(<Harness initialValue="hello" maxChars={10} onSubmit={vi.fn()} />);
+    expect(screen.getByRole('textbox')).toHaveProperty('value', 'hello');
+  });
+
+  it('forwards under-cap input verbatim to onChange', () => {
+    const onChangeSpy = vi.fn();
+    render(<Harness maxChars={10} onSubmit={vi.fn()} onChangeSpy={onChangeSpy} />);
+    fireEvent.change(screen.getByRole('textbox'), { target: { value: 'hello' } });
+    expect(onChangeSpy).toHaveBeenLastCalledWith('hello');
+  });
+
+  it('truncates over-cap ASCII pastes to the cap before reaching onChange', () => {
+    const onChangeSpy = vi.fn();
+    render(<Harness maxChars={5} onSubmit={vi.fn()} onChangeSpy={onChangeSpy} />);
+    fireEvent.change(screen.getByRole('textbox'), {
+      target: { value: 'helloWORLD' },
+    });
+    expect(onChangeSpy).toHaveBeenLastCalledWith('hello');
+  });
+
+  it('counts emoji as one grapheme — not two — in the visible counter and the cap', () => {
+    const onChangeSpy = vi.fn();
+    render(
+      <Harness
+        initialValue={'😀😀'}
+        maxChars={3}
+        onSubmit={vi.fn()}
+        onChangeSpy={onChangeSpy}
+      />,
+    );
+    expect(screen.getByText('2/3')).toBeTruthy();
+
+    // A paste that would exceed the cap is grapheme-truncated.
+    fireEvent.change(screen.getByRole('textbox'), {
+      target: { value: '😀😀😀😀😀' },
+    });
+    expect(onChangeSpy).toHaveBeenLastCalledWith('😀😀😀');
+  });
+
+  it('does not split a surrogate pair on truncation', () => {
+    const onChangeSpy = vi.fn();
+    render(<Harness maxChars={2} onSubmit={vi.fn()} onChangeSpy={onChangeSpy} />);
+    fireEvent.change(screen.getByRole('textbox'), { target: { value: 'a😀b' } });
+    const value = onChangeSpy.mock.calls[0]?.[0];
+    expect(value).toBe('a😀');
+    // Sanity: the truncation did not slice mid-surrogate (length === 3).
+    expect((value as string).length).toBe(3);
+  });
+
+  it('counts ZWJ family clusters as one grapheme', () => {
+    const family = '\u{1F468}\u200D\u{1F469}\u200D\u{1F467}';
+    render(
+      <Harness initialValue={family} maxChars={5} onSubmit={vi.fn()} />,
+    );
+    expect(screen.getByText('1/5')).toBeTruthy();
+  });
+
+  it('submits the trimmed value on Enter when valid', () => {
+    const onSubmit = vi.fn();
+    render(<Harness initialValue="  hello  " maxChars={20} onSubmit={onSubmit} />);
+    fireEvent.keyDown(screen.getByRole('textbox'), { key: 'Enter' });
+    expect(onSubmit).toHaveBeenCalledWith('hello');
+  });
+
+  it('does not submit on Enter when the value is empty after trim', () => {
+    const onSubmit = vi.fn();
+    render(<Harness initialValue="   " maxChars={20} onSubmit={onSubmit} />);
+    fireEvent.keyDown(screen.getByRole('textbox'), { key: 'Enter' });
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('does not submit on Enter while pending', () => {
+    const onSubmit = vi.fn();
+    render(<Harness initialValue="hello" maxChars={20} onSubmit={onSubmit} pending />);
+    fireEvent.keyDown(screen.getByRole('textbox'), { key: 'Enter' });
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('does not submit on Enter while disabled', () => {
+    const onSubmit = vi.fn();
+    render(<Harness initialValue="hello" maxChars={20} onSubmit={onSubmit} disabled />);
+    fireEvent.keyDown(screen.getByRole('textbox'), { key: 'Enter' });
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('lets Shift+Enter pass through (newline insertion)', () => {
+    const onSubmit = vi.fn();
+    render(<Harness initialValue="hello" maxChars={20} onSubmit={onSubmit} />);
+    const event = fireEvent.keyDown(screen.getByRole('textbox'), {
+      key: 'Enter',
+      shiftKey: true,
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+    // fireEvent returns false when default was prevented; true otherwise.
+    expect(event).toBe(true);
+  });
+
+  it('locks the textarea and surfaces the pending hint when pending=true', () => {
+    render(<Harness initialValue="hello" maxChars={20} onSubmit={vi.fn()} pending />);
+    expect((screen.getByRole('textbox') as HTMLTextAreaElement).disabled).toBe(true);
+    expect(screen.getByText('Sending…')).toBeTruthy();
+  });
+});

package/src/components/prompt-input.tsx

@@ -0,0 +1,114 @@
+'use client';
+
+/**
+ * `PromptInput` — text submission with grapheme cap and Enter-to-submit.
+ */
+
+import * as React from 'react';
+
+import { graphemeCount, truncateToGraphemes } from '../lib/char-count.js';
+import { cn } from '../lib/cn.js';
+
+export type PromptInputProps = {
+  readonly value: string;
+  readonly onChange: (next: string) => void;
+  readonly onSubmit: (final: string) => void;
+  readonly maxChars: number;
+  readonly placeholder?: string;
+  readonly disabled?: boolean;
+  readonly pending?: boolean;
+  readonly label?: string;
+  readonly id?: string;
+  readonly className?: string;
+  readonly autoFocus?: boolean;
+};
+
+export const PromptInput = ({
+  value,
+  onChange,
+  onSubmit,
+  maxChars,
+  placeholder,
+  disabled = false,
+  pending = false,
+  label,
+  id,
+  className,
+  autoFocus = false,
+}: PromptInputProps): React.ReactElement => {
+  const count = graphemeCount(value);
+  const isLocked = disabled || pending;
+  const trimmed = value.trim();
+  const canSubmit = !isLocked && trimmed.length > 0 && count <= maxChars;
+
+  const handleChange = React.useCallback(
+    (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+      const next = event.target.value;
+      const capped = graphemeCount(next) > maxChars
+        ? truncateToGraphemes(next, maxChars)
+        : next;
+      onChange(capped);
+    },
+    [maxChars, onChange],
+  );
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
+      if (event.key !== 'Enter' || event.shiftKey) return;
+      if (!canSubmit) {
+        event.preventDefault();
+        return;
+      }
+      event.preventDefault();
+      onSubmit(trimmed);
+    },
+    [canSubmit, onSubmit, trimmed],
+  );
+
+  const counterClass = count > maxChars
+    ? 'text-destructive'
+    : count >= maxChars
+      ? 'text-primary'
+      : 'text-muted-foreground';
+
+  return (
+    <div className={cn('flex flex-col gap-2', className)}>
+      {label !== undefined ? (
+        <label
+          htmlFor={id}
+          className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground"
+        >
+          {label}
+        </label>
+      ) : null}
+      <textarea
+        id={id}
+        autoFocus={autoFocus}
+        aria-label={label}
+        aria-disabled={isLocked || undefined}
+        disabled={isLocked}
+        value={value}
+        placeholder={placeholder}
+        onChange={handleChange}
+        onKeyDown={handleKeyDown}
+        rows={3}
+        data-pending={pending || undefined}
+        className={cn(
+          'w-full resize-none rounded-lg border border-input bg-card p-3',
+          'text-base text-foreground',
+          'placeholder:text-muted-foreground',
+          'focus:border-primary focus:outline-none focus:ring-2 focus:ring-ring',
+          'disabled:cursor-not-allowed disabled:opacity-60',
+        )}
+      />
+      <div className="flex items-center justify-between text-xs">
+        <span aria-live="polite" className="text-muted-foreground">
+          {pending ? 'Sending…' : '\u00A0'}
+        </span>
+        <span className={cn('tabular-nums', counterClass)} aria-live="polite">
+          {count}/{maxChars}
+        </span>
+      </div>
+    </div>
+  );
+};

package/src/components/recovery-code-badge.tsx

@@ -0,0 +1,58 @@
+/**
+ * `RecoveryCodeBadge` — host-only recovery code surface for orphan seats.
+ *
+ * Per Platform Spec §3.11.1 the recovery code appears only on the Host
+ * shell as the social-trust mechanism. Renders nothing when no code is
+ * active beyond an empty-state hint.
+ */
+
+import * as React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type RecoveryCodeBadgeProps = {
+  readonly code: string | null;
+  readonly hint?: React.ReactNode;
+  readonly label?: React.ReactNode;
+  readonly emptyHint?: React.ReactNode;
+  readonly className?: string;
+  readonly testId?: string;
+};
+
+export const RecoveryCodeBadge = ({
+  code,
+  hint,
+  label,
+  emptyHint,
+  className,
+  testId = 'ui-kit-recovery-code',
+}: RecoveryCodeBadgeProps): React.ReactElement => (
+  <section
+    aria-live="polite"
+    className={cn(
+      'flex flex-col gap-3 rounded-xl border border-border bg-card p-6 shadow-sm',
+      className,
+    )}
+  >
+    {label !== undefined ? (
+      <h2 className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground">
+        {label}
+      </h2>
+    ) : null}
+    {code ? (
+      <>
+        <p
+          data-testid={testId}
+          className="font-mono text-4xl font-semibold tracking-[0.3em] text-primary"
+        >
+          {code}
+        </p>
+        {hint !== undefined ? (
+          <p className="text-sm text-muted-foreground">{hint}</p>
+        ) : null}
+      </>
+    ) : (
+      <p className="text-sm text-muted-foreground">{emptyHint}</p>
+    )}
+  </section>
+);

package/src/components/response-card.tsx

@@ -0,0 +1,70 @@
+/**
+ * `ResponseCard` — player submission display with optional reveal animation.
+ */
+
+import * as React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type ResponseCardAttribution = {
+  readonly displayName: string;
+  readonly visible: boolean;
+};
+
+export type ResponseCardProps = {
+  readonly body: React.ReactNode;
+  readonly attribution: ResponseCardAttribution;
+  readonly state: 'hidden' | 'revealing' | 'revealed';
+  readonly badge?: React.ReactNode;
+  readonly className?: string;
+};
+
+export const ResponseCard = ({
+  body,
+  attribution,
+  state,
+  badge,
+  className,
+}: ResponseCardProps): React.ReactElement => {
+  const isHidden = state === 'hidden';
+  const isRevealed = state === 'revealed';
+  const showAuthor = isRevealed && attribution.visible;
+
+  return (
+    <article
+      data-state={state}
+      data-revealed={isRevealed || undefined}
+      className={cn(
+        'wibly-response-card flex flex-col rounded-xl border border-border bg-card shadow-sm',
+        'transition-all duration-500 ease-out',
+        state === 'revealing' && 'blur-[1px]',
+        className,
+      )}
+    >
+      <header className="flex items-center justify-between gap-4 border-b border-border/70 pb-3">
+        <span className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground">
+          {showAuthor ? attribution.displayName : 'Anonymous'}
+        </span>
+        {badge !== undefined ? (
+          <span className="shrink-0 rounded-full bg-primary px-2.5 py-1 text-xs font-semibold text-primary-foreground">
+            {badge}
+          </span>
+        ) : null}
+      </header>
+      <div
+        aria-hidden={isHidden}
+        className={cn(
+          'pt-4 text-base leading-relaxed text-foreground',
+          'transition-opacity duration-500',
+          isHidden && 'select-none opacity-0',
+        )}
+      >
+        {isHidden ? (
+          <span className="block h-14 w-full rounded-lg bg-border/50" aria-hidden="true" />
+        ) : (
+          body
+        )}
+      </div>
+    </article>
+  );
+};

package/src/components/session-aborted-overlay.tsx

@@ -0,0 +1,60 @@
+'use client';
+
+/**
+ * Full-screen overlay shown when a live session is aborted by the host.
+ */
+
+import * as React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type SessionAbortedOverlayProps = {
+  readonly gameName: string;
+  readonly onAck: () => void;
+  /** Auto-invoke `onAck` after this many milliseconds. Defaults to 10s. */
+  readonly redirectMs?: number;
+  readonly className?: string;
+  readonly testId?: string;
+};
+
+export const SessionAbortedOverlay = ({
+  gameName,
+  onAck,
+  redirectMs = 10_000,
+  className,
+  testId = 'session-aborted-overlay',
+}: SessionAbortedOverlayProps): React.ReactElement => {
+  React.useEffect(() => {
+    const timer = window.setTimeout(onAck, redirectMs);
+    return () => window.clearTimeout(timer);
+  }, [onAck, redirectMs]);
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="session-aborted-title"
+      data-testid={testId}
+      className={cn(
+        'fixed inset-0 z-50 flex items-center justify-center bg-background/80 p-6 backdrop-blur-sm',
+        className,
+      )}
+    >
+      <section className="flex w-full max-w-md flex-col items-center gap-6 rounded-3xl border border-foreground/10 bg-card px-8 py-10 text-center shadow-lg">
+        <h1
+          id="session-aborted-title"
+          className="font-display text-2xl font-bold text-foreground md:text-3xl"
+        >
+          {gameName} has been aborted by the Host
+        </h1>
+        <button
+          type="button"
+          onClick={onAck}
+          className="rounded-xl bg-primary px-6 py-3 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90"
+        >
+          Okay
+        </button>
+      </section>
+    </div>
+  );
+};

package/src/components/timer.test.tsx

@@ -0,0 +1,157 @@
+/**
+ * Tier-1 invariant tests for `Timer`.
+ *
+ * Per Dev Spec §6.6 chunk-B10 acceptance: "Tests for components
+ * that have meaningful logic (Timer's deadline math, …)."
+ *
+ * The component renders under happy-dom with vitest's fake timers.
+ * `nowMs` is a controllable thunk so the tests advance simulated
+ * server time without waiting on the wall clock.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, render, screen } from '@testing-library/react';
+
+import { Timer } from './timer.js';
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+const readDisplay = (): string => {
+  // The countdown is the only `<span>` with a numeric `M:SS` /
+  // `SS` body inside the timer surface; selecting by role + class
+  // would over-couple to internals, so the value goes via the
+  // role+aria-label combination.
+  const timer = screen.getByRole('timer');
+  return timer.textContent?.trim() ?? '';
+};
+
+describe('Timer', () => {
+  it('renders the initial remaining duration on first paint', () => {
+    const fixedNow = 1_000_000;
+    render(<Timer deadlineMs={fixedNow + 30_500} nowMs={() => fixedNow} />);
+    expect(readDisplay()).toBe('0:31');
+  });
+
+  it('updates the displayed countdown as nowMs advances', () => {
+    let now = 1_000_000;
+    render(<Timer deadlineMs={now + 10_000} nowMs={() => now} tickMs={250} />);
+    expect(readDisplay()).toBe('0:10');
+
+    now += 5_000;
+    act(() => {
+      vi.advanceTimersByTime(250);
+    });
+    expect(readDisplay()).toBe('0:05');
+
+    now += 4_000;
+    act(() => {
+      vi.advanceTimersByTime(250);
+    });
+    expect(readDisplay()).toBe('0:01');
+  });
+
+  it('reads `nowMs` via a ref so a changing thunk identity does not resubscribe the interval', () => {
+    const now = 1_000_000;
+    const deadline = now + 10_000;
+
+    const view = render(
+      <Timer deadlineMs={deadline} nowMs={() => now} tickMs={250} />,
+    );
+
+    const setIntervalSpy = vi.spyOn(globalThis, 'setInterval');
+    setIntervalSpy.mockClear();
+    view.rerender(
+      <Timer deadlineMs={deadline} nowMs={() => now} tickMs={250} />,
+    );
+    expect(setIntervalSpy).not.toHaveBeenCalled();
+    setIntervalSpy.mockRestore();
+  });
+
+  it('renders 0:00 and exposes data-expired when the deadline has passed', () => {
+    const now = 1_000_000;
+    render(<Timer deadlineMs={now - 5_000} nowMs={() => now} />);
+    expect(readDisplay()).toBe('0:00');
+    expect(screen.getByRole('timer').getAttribute('data-expired')).toBe('true');
+  });
+
+  it('fires onExpire exactly once when remaining crosses 0', () => {
+    let now = 1_000_000;
+    const deadline = now + 1_000;
+    const onExpire = vi.fn();
+    render(
+      <Timer
+        deadlineMs={deadline}
+        nowMs={() => now}
+        onExpire={onExpire}
+        tickMs={250}
+      />,
+    );
+    expect(onExpire).not.toHaveBeenCalled();
+
+    now += 1_500;
+    act(() => {
+      vi.advanceTimersByTime(250);
+    });
+    expect(onExpire).toHaveBeenCalledTimes(1);
+
+    now += 1_000;
+    act(() => {
+      vi.advanceTimersByTime(1_000);
+    });
+    expect(onExpire).toHaveBeenCalledTimes(1);
+  });
+
+  it('resets the expired-once latch when deadlineMs changes', () => {
+    let now = 1_000_000;
+    let deadline = now + 1_000;
+    const onExpire = vi.fn();
+
+    const view = render(
+      <Timer
+        deadlineMs={deadline}
+        nowMs={() => now}
+        onExpire={onExpire}
+        tickMs={250}
+      />,
+    );
+
+    now += 1_500;
+    act(() => {
+      vi.advanceTimersByTime(250);
+    });
+    expect(onExpire).toHaveBeenCalledTimes(1);
+
+    deadline = now + 1_000;
+    view.rerender(
+      <Timer
+        deadlineMs={deadline}
+        nowMs={() => now}
+        onExpire={onExpire}
+        tickMs={250}
+      />,
+    );
+
+    now += 1_500;
+    act(() => {
+      vi.advanceTimersByTime(250);
+    });
+    expect(onExpire).toHaveBeenCalledTimes(2);
+  });
+
+  it('clears the interval on unmount', () => {
+    const clearSpy = vi.spyOn(globalThis, 'clearInterval');
+    const now = 1_000_000;
+    const view = render(
+      <Timer deadlineMs={now + 10_000} nowMs={() => now} tickMs={250} />,
+    );
+    view.unmount();
+    expect(clearSpy).toHaveBeenCalled();
+    clearSpy.mockRestore();
+  });
+});