@wibly/ui-kit 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# `@wibly/ui-kit` — Changelog
+
+## 0.1.1 — 2026-05-30
+
+Initial public npm release. Eight shared React components plus the Wibly
+shell theme stylesheet (`styles/wibly-shell-theme.css`), meant to be bundled
+into Experience `host.mjs` / `player.mjs` alongside React.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@wibly/ui-kit",
+  "version": "0.1.1",
+  "description": "Wibly @wibly/ui-kit",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles/wibly-shell-theme.css": "./styles/wibly-shell-theme.css"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wibly/wibly"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1"
+  },
+  "peerDependencies": {
+    "@wibly/sdk": "0.1.1",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}

package/src/components/avatar-stage.tsx

@@ -0,0 +1,98 @@
+/**
+ * `AvatarStage` — renders the bound persona's avatar with simple
+ * animation states (idle, speaking, judging).
+ */
+
+import * as React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type AvatarStageState = 'idle' | 'speaking' | 'judging';
+
+export type AvatarStageProps = {
+  readonly state: AvatarStageState;
+  readonly children?: React.ReactNode;
+  /** Optional accessible label, e.g. the persona's display name. */
+  readonly label?: string;
+  /** Override the default size. */
+  readonly size?: 'sm' | 'md' | 'lg';
+  /** Show the state caption under the avatar. Default true. */
+  readonly showStateLabel?: boolean;
+  readonly className?: string;
+};
+
+const SIZE_CLASS: Record<NonNullable<AvatarStageProps['size']>, string> = {
+  sm: 'size-24',
+  md: 'size-40',
+  lg: 'size-64',
+};
+
+const STATE_SHELL: Record<AvatarStageState, string> = {
+  idle: cn(
+    'wibly-avatar-stage-idle border border-border bg-gradient-to-br from-card via-card to-secondary',
+    'shadow-sm',
+  ),
+  speaking: cn(
+    'wibly-avatar-stage-speaking border-2 border-primary bg-gradient-to-br from-card via-primary/5 to-card',
+  ),
+  judging: cn(
+    'wibly-avatar-stage-judging border-2 border-accent bg-gradient-to-br from-card via-accent/10 to-card',
+  ),
+};
+
+const STATE_LABEL: Record<AvatarStageState, string> = {
+  idle: 'Idle',
+  speaking: 'Speaking',
+  judging: 'Thinking',
+};
+
+const AvatarFallback = (): React.ReactElement => (
+  <div className="flex size-full flex-col items-center justify-center gap-1 bg-gradient-to-br from-primary/10 via-card to-mint/15">
+    <svg
+      aria-hidden="true"
+      viewBox="0 0 24 24"
+      className="size-1/3 text-primary/70"
+      fill="currentColor"
+    >
+      <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z" />
+    </svg>
+    <span className="text-[10px] font-medium uppercase tracking-wide text-muted-foreground">
+      Avatar
+    </span>
+  </div>
+);
+
+export const AvatarStage = ({
+  state,
+  children,
+  label,
+  size = 'md',
+  showStateLabel = true,
+  className,
+}: AvatarStageProps): React.ReactElement => (
+  <div className={cn('inline-flex shrink-0 flex-col items-center gap-2.5', className)}>
+    <div
+      role="img"
+      aria-label={label ?? `Persona avatar, ${STATE_LABEL[state]}`}
+      data-state={state}
+      className={cn(
+        'relative shrink-0 overflow-hidden rounded-full',
+        'aspect-square',
+        SIZE_CLASS[size],
+        STATE_SHELL[state],
+      )}
+    >
+      <div className="flex size-full items-center justify-center overflow-hidden rounded-full">
+        {children ?? <AvatarFallback />}
+      </div>
+    </div>
+    {showStateLabel ? (
+      <span
+        aria-live="polite"
+        className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground"
+      >
+        {STATE_LABEL[state]}
+      </span>
+    ) : null}
+  </div>
+);

package/src/components/consent-dialog.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+
+import type { ConsentRequiredPayload } from '@wibly/sdk';
+
+import { resolveConsentDialogCopy } from './consent-dialog.js';
+import { CONSENT_DIALOG_DEFAULTS } from '../lib/consent-meta.js';
+
+const basePayload = (
+  overrides: Partial<ConsentRequiredPayload> = {},
+): ConsentRequiredPayload => ({
+  personaId: 'psn_test',
+  personaDisplayName: 'Crumb',
+  scope: 'player',
+  ...overrides,
+});
+
+describe('resolveConsentDialogCopy', () => {
+  describe('kind=mid-session', () => {
+    it('falls back to the platform default when no per-Persona override is present', () => {
+      const copy = resolveConsentDialogCopy('mid-session', basePayload());
+      expect(copy.title).toBe(
+        CONSENT_DIALOG_DEFAULTS['mid-session'].title('Crumb'),
+      );
+      expect(copy.description).toBe(
+        CONSENT_DIALOG_DEFAULTS['mid-session'].description,
+      );
+    });
+  });
+
+  describe('kind=settings', () => {
+    it('uses the settings-surface defaults distinct from mid-session', () => {
+      const copy = resolveConsentDialogCopy('settings', basePayload());
+      expect(copy.title).toBe(CONSENT_DIALOG_DEFAULTS.settings.title('Crumb'));
+      expect(copy.title).not.toBe(
+        CONSENT_DIALOG_DEFAULTS['mid-session'].title('Crumb'),
+      );
+    });
+  });
+});

package/src/components/consent-dialog.tsx

@@ -0,0 +1,58 @@
+'use client';
+
+import * as React from 'react';
+
+import type {
+  ConsentRequiredCallback,
+  ConsentRequiredPayload,
+} from '@wibly/sdk';
+
+import {
+  type ConsentDialogKind,
+  CONSENT_DIALOG_DEFAULTS,
+} from '../lib/consent-meta.js';
+import { type ConsentFlowState } from '../lib/consent-flow.js';
+import {
+  ConsentPrompt,
+  type ConsentPromptCopyOverride,
+} from './consent-prompt.js';
+
+export type { ConsentDialogKind };
+
+export type ConsentDialogProps = {
+  readonly kind: ConsentDialogKind;
+  readonly payload: ConsentRequiredPayload;
+  readonly onResolve: ConsentRequiredCallback;
+  readonly onResolved?: (state: ConsentFlowState) => void;
+};
+
+export const resolveConsentDialogCopy = (
+  kind: ConsentDialogKind,
+  payload: ConsentRequiredPayload,
+): Required<ConsentPromptCopyOverride> => {
+  const surfaceDefaults = CONSENT_DIALOG_DEFAULTS[kind];
+  return {
+    title:
+      payload.consentCopy?.title ??
+      surfaceDefaults.title(payload.personaDisplayName),
+    description:
+      payload.consentCopy?.description ?? surfaceDefaults.description,
+  };
+};
+
+export const ConsentDialog = ({
+  kind,
+  payload,
+  onResolve,
+  onResolved,
+}: ConsentDialogProps): React.ReactElement | null => {
+  const copy = resolveConsentDialogCopy(kind, payload);
+  return (
+    <ConsentPrompt
+      payload={payload}
+      onResolve={onResolve}
+      copy={copy}
+      {...(onResolved ? { onResolved } : {})}
+    />
+  );
+};

package/src/components/consent-prompt.tsx

@@ -0,0 +1,106 @@
+'use client';
+
+import * as React from 'react';
+
+import type {
+  ConsentRequiredCallback,
+  ConsentRequiredPayload,
+} from '@wibly/sdk';
+
+import {
+  type ConsentFlowState,
+  consentFlowReducer,
+  initialConsentFlowState,
+} from '../lib/consent-flow.js';
+import { CONSENT_PROMPT_COPY } from '../lib/consent-meta.js';
+
+export type ConsentPromptCopyOverride = {
+  readonly title?: string;
+  readonly description?: string;
+};
+
+export type ConsentPromptProps = {
+  readonly payload: ConsentRequiredPayload;
+  readonly onResolve: ConsentRequiredCallback;
+  readonly onResolved?: (state: ConsentFlowState) => void;
+  readonly copy?: ConsentPromptCopyOverride;
+};
+
+export const ConsentPrompt = ({
+  payload,
+  onResolve,
+  onResolved,
+  copy,
+}: ConsentPromptProps): React.ReactElement | null => {
+  const [state, dispatch] = React.useReducer(
+    consentFlowReducer,
+    initialConsentFlowState(payload),
+  );
+
+  React.useEffect(() => {
+    if (state.kind !== 'submitting') return;
+    let cancelled = false;
+    void (async () => {
+      try {
+        await onResolve(state.payload);
+      } finally {
+        if (!cancelled) dispatch({ type: 'confirmed' });
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [state, onResolve]);
+
+  React.useEffect(() => {
+    if (state.kind === 'resolved') onResolved?.(state);
+  }, [state, onResolved]);
+
+  if (state.kind === 'resolved') return null;
+
+  const submitting = state.kind === 'submitting';
+  const titleId = 'consent-prompt-title';
+  const title =
+    copy?.title ?? CONSENT_PROMPT_COPY.title(payload.personaDisplayName);
+  const description = copy?.description ?? CONSENT_PROMPT_COPY.description;
+
+  return (
+    <section
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby={titleId}
+      className="mx-auto flex w-full max-w-md flex-col items-stretch gap-4 rounded-2xl border border-border bg-card p-6 shadow-sm"
+    >
+      <h2
+        id={titleId}
+        className="font-display text-lg font-semibold text-foreground"
+      >
+        {title}
+      </h2>
+      <p className="text-sm text-muted-foreground">
+        {description}
+      </p>
+      <div className="flex flex-col gap-2 self-stretch">
+        <button
+          type="button"
+          disabled={submitting}
+          onClick={() => dispatch({ type: 'accept' })}
+          className="rounded-lg bg-primary px-4 py-3 text-sm font-semibold text-primary-foreground disabled:opacity-60"
+        >
+          {CONSENT_PROMPT_COPY.acceptLabel}
+        </button>
+        <button
+          type="button"
+          disabled={submitting}
+          onClick={() => dispatch({ type: 'decline' })}
+          className="rounded-lg border border-border px-4 py-3 text-sm text-foreground disabled:opacity-60"
+        >
+          {CONSENT_PROMPT_COPY.declineLabel}
+        </button>
+      </div>
+      <p className="text-xs text-muted-foreground">
+        {CONSENT_PROMPT_COPY.managementHint}
+      </p>
+    </section>
+  );
+};

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

@@ -0,0 +1,69 @@
+/**
+ * `JoinCodeBadge` — large, accessible join code display for session
+ * lobbies.
+ *
+ * Sized to be legible on a TV (host) or phone (player). The consumer
+ * formats and supplies the code; the badge does not validate format.
+ */
+
+import * as React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type JoinCodeBadgeProps = {
+  /** The 6-character code, or null while the Runtime hasn't issued one. */
+  readonly code: string | null;
+  /** Optional copy under the code (e.g. "Visit play.wibly.com"). */
+  readonly hint?: React.ReactNode;
+  /** Optional small label above the code (e.g. "JOIN CODE"). */
+  readonly label?: React.ReactNode;
+  /** Visual size; the host shell uses `'lg'`. */
+  readonly size?: 'md' | 'lg';
+  readonly className?: string;
+  readonly testId?: string;
+};
+
+const PLACEHOLDER = '— — — — — —';
+
+const SIZE_CLASS: Record<NonNullable<JoinCodeBadgeProps['size']>, string> = {
+  md: 'text-4xl tracking-[0.3em]',
+  lg: 'text-6xl tracking-[0.4em]',
+};
+
+export const JoinCodeBadge = ({
+  code,
+  hint,
+  label,
+  size = 'lg',
+  className,
+  testId = 'ui-kit-join-code',
+}: JoinCodeBadgeProps): React.ReactElement => {
+  const displayCode = code ?? PLACEHOLDER;
+  return (
+    <div
+      className={cn(
+        'flex flex-col gap-3 rounded-xl border border-border bg-card p-6 shadow-sm',
+        className,
+      )}
+    >
+      {label !== undefined ? (
+        <span className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground">
+          {label}
+        </span>
+      ) : null}
+      <p
+        aria-label={code ? `Join code ${code.split('').join(' ')}` : 'Join code pending'}
+        data-testid={testId}
+        className={cn(
+          'font-mono font-semibold text-foreground',
+          SIZE_CLASS[size],
+        )}
+      >
+        {displayCode}
+      </p>
+      {hint !== undefined ? (
+        <span className="text-sm text-muted-foreground">{hint}</span>
+      ) : null}
+    </div>
+  );
+};

package/src/components/leaderboard.tsx

@@ -0,0 +1,159 @@
+/**
+ * `Leaderboard` — score display with dimensions.
+ *
+ * Uses CSS grid (not `<table>`) so layout stays stable under Tailwind v4
+ * Preflight and when utility classes are compiled from `@wibly/ui-kit`.
+ */
+
+import * as React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type LeaderboardDimension = {
+  readonly id: string;
+  readonly label: string;
+};
+
+export type LeaderboardRow = {
+  readonly playerId: string;
+  readonly displayName: string;
+  /** Per-dimension scores; missing keys render as a dash. */
+  readonly scores: Readonly<Record<string, number>>;
+  /** Optional precomputed total — when omitted, no total column renders. */
+  readonly total?: number;
+  /** Optional dense-rank position (1, 2, 2, 4, …). When omitted, derived from row order. */
+  readonly position?: number;
+  /** Highlight the row (the local player, the leader, etc.). */
+  readonly highlighted?: boolean;
+};
+
+export type LeaderboardProps = {
+  readonly dimensions: readonly LeaderboardDimension[];
+  readonly rows: readonly LeaderboardRow[];
+  readonly showTotal?: boolean;
+  readonly className?: string;
+  readonly emptyState?: React.ReactNode;
+};
+
+const formatScore = (value: number | undefined): string => {
+  if (value === undefined || Number.isNaN(value)) return '—';
+  return value.toLocaleString(undefined, { maximumFractionDigits: 2 });
+};
+
+const buildGridTemplate = (
+  dimensionCount: number,
+  showTotal: boolean,
+): string => {
+  const scoreColumns = Array.from({ length: dimensionCount }, () => '4.5rem').join(' ');
+  const totalColumn = showTotal ? ' 4.5rem' : '';
+  return `2.75rem minmax(7rem, 1.4fr)${scoreColumns.length > 0 ? ` ${scoreColumns}` : ''}${totalColumn}`;
+};
+
+export const Leaderboard = ({
+  dimensions,
+  rows,
+  showTotal = false,
+  className,
+  emptyState,
+}: LeaderboardProps): React.ReactElement => {
+  if (rows.length === 0) {
+    return (
+      <div
+        className={cn(
+          'rounded-xl border border-dashed border-border bg-card p-6 text-center text-sm text-muted-foreground shadow-sm',
+          className,
+        )}
+      >
+        {emptyState ?? 'No scores yet.'}
+      </div>
+    );
+  }
+
+  const gridTemplateColumns = buildGridTemplate(dimensions.length, showTotal);
+
+  return (
+    <div
+      className={cn(
+        'overflow-x-auto rounded-xl border border-border bg-card shadow-sm',
+        className,
+      )}
+    >
+      <div
+      className="min-w-[20rem]"
+      role="table"
+      aria-label="Leaderboard"
+    >
+        <div
+          className="grid items-center border-b border-border bg-secondary text-[11px] uppercase tracking-wide text-muted-foreground"
+          style={{ gridTemplateColumns }}
+          role="row"
+        >
+          <div className="px-3 py-2.5 font-medium" role="columnheader">
+            #
+          </div>
+          <div className="px-3 py-2.5 font-medium" role="columnheader">
+            Player
+          </div>
+          {dimensions.map((dim) => (
+            <div
+              key={dim.id}
+              className="px-3 py-2.5 text-right font-medium"
+              role="columnheader"
+            >
+              {dim.label}
+            </div>
+          ))}
+          {showTotal ? (
+            <div className="px-3 py-2.5 text-right font-medium" role="columnheader">
+              Total
+            </div>
+          ) : null}
+        </div>
+
+        {rows.map((row, index) => (
+          <div
+            key={row.playerId}
+            data-highlighted={row.highlighted || undefined}
+            className={cn(
+              'grid items-center border-b border-border text-sm last:border-b-0',
+              row.highlighted ? 'bg-secondary/70' : 'bg-card',
+            )}
+            style={{ gridTemplateColumns }}
+            role="row"
+          >
+            <div
+              className="px-3 py-2.5 font-mono tabular-nums text-muted-foreground"
+              role="cell"
+            >
+              {row.position ?? index + 1}
+            </div>
+            <div
+              className="min-w-0 truncate px-3 py-2.5 font-medium text-foreground"
+              role="cell"
+              title={row.displayName}
+            >
+              {row.displayName}
+            </div>
+            {dimensions.map((dim) => (
+              <div
+                key={dim.id}
+                className="px-3 py-2.5 text-right font-mono tabular-nums text-foreground"
+                role="cell"
+              >
+                {formatScore(row.scores[dim.id])}
+              </div>
+            ))}
+            {showTotal ? (
+              <div
+                className="px-3 py-2.5 text-right font-mono font-semibold tabular-nums text-foreground"
+                role="cell"
+              >
+                {formatScore(row.total)}
+              </div>
+            ) : null}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};

package/src/components/paused-banner.tsx

@@ -0,0 +1,66 @@
+/**
+ * `PausedBanner` — banner for paused session state.
+ *
+ * Overlays above the Experience surface during a `pause_session`
+ * lifecycle response (Platform Spec §3.8.2).
+ */
+
+import * as React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type PausedBannerReason = 'host' | 'system' | 'safety';
+
+export type PausedBannerProps = {
+  readonly reason: PausedBannerReason;
+  readonly headline: React.ReactNode;
+  readonly description?: React.ReactNode;
+  /** Action slot (e.g. a "Resume" button rendered by the User Portal). */
+  readonly action?: React.ReactNode;
+  readonly className?: string;
+  readonly testId?: string;
+};
+
+const REASON_LABEL: Record<PausedBannerReason, string> = {
+  host: 'Paused by host',
+  system: 'Paused by system',
+  safety: 'Paused — safety review',
+};
+
+const REASON_TONE: Record<PausedBannerReason, string> = {
+  host: 'border-primary/30 text-primary',
+  system: 'border-accent/40 text-accent-foreground',
+  safety: 'border-destructive/40 text-destructive',
+};
+
+export const PausedBanner = ({
+  reason,
+  headline,
+  description,
+  action,
+  className,
+  testId = 'session-paused-banner',
+}: PausedBannerProps): React.ReactElement => (
+  <section
+    role="status"
+    aria-live="polite"
+    data-reason={reason}
+    data-testid={testId}
+    className={cn(
+      'flex w-full flex-col items-center justify-center gap-3 rounded-xl border bg-card px-6 py-8 text-center shadow-sm',
+      REASON_TONE[reason],
+      className,
+    )}
+  >
+    <span className="text-[11px] font-medium uppercase tracking-[0.2em]">
+      {REASON_LABEL[reason]}
+    </span>
+    <h2 className="font-display text-2xl font-semibold text-foreground md:text-3xl">
+      {headline}
+    </h2>
+    {description !== undefined ? (
+      <p className="max-w-prose text-sm text-muted-foreground">{description}</p>
+    ) : null}
+    {action !== undefined ? <div className="pt-2">{action}</div> : null}
+  </section>
+);