@wibly/ui-kit 0.1.1 → 0.1.3

package/src/components/player-roster.tsx

@@ -0,0 +1,71 @@
+/**
+ * `PlayerRoster` — horizontal player chips with optional running scores.
+ */
+
+import * as React from 'react';
+
+import { cn } from '../lib/cn.js';
+import { PlayerAvatar, type PlayerAvatarProps } from './player-avatar.js';
+
+export type PlayerRosterEntry = {
+  readonly playerId: string;
+  readonly displayName: string;
+  readonly imageUrl?: string | null;
+  readonly score?: number;
+  readonly connected?: boolean;
+  readonly highlighted?: boolean;
+};
+
+export type PlayerRosterProps = {
+  readonly players: readonly PlayerRosterEntry[];
+  readonly size?: PlayerAvatarProps['size'];
+  readonly className?: string;
+  readonly emptyState?: React.ReactNode;
+  readonly testId?: string;
+};
+
+export const PlayerRoster = ({
+  players,
+  size = 'md',
+  className,
+  emptyState,
+  testId = 'player-roster',
+}: PlayerRosterProps): React.ReactElement => {
+  if (players.length === 0) {
+    return (
+      <div
+        data-testid={testId}
+        className={cn(
+          'rounded-xl border border-dashed border-border p-4 text-center text-sm text-muted-foreground',
+          className,
+        )}
+      >
+        {emptyState ?? 'No players yet.'}
+      </div>
+    );
+  }
+
+  return (
+    <ul
+      data-testid={testId}
+      className={cn(
+        'flex flex-wrap items-end justify-center gap-4',
+        className,
+      )}
+    >
+      {players.map((player) => (
+        <li key={player.playerId}>
+          <PlayerAvatar
+            playerId={player.playerId}
+            displayName={player.displayName}
+            imageUrl={player.imageUrl}
+            score={player.score}
+            connected={player.connected}
+            highlighted={player.highlighted}
+            size={size}
+          />
+        </li>
+      ))}
+    </ul>
+  );
+};

package/src/components/shell-brand-mark.tsx

@@ -0,0 +1,33 @@
+/**
+ * `ShellBrandMark` — minimal Wibly mark for Host linked-session chrome.
+ */
+
+import * as React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type ShellBrandMarkProps = {
+  readonly src?: string;
+  readonly alt?: string;
+  readonly className?: string;
+  readonly testId?: string;
+};
+
+export const ShellBrandMark = ({
+  src = '/logo.png',
+  alt = 'Wibly',
+  className,
+  testId = 'shell-brand-mark',
+}: ShellBrandMarkProps): React.ReactElement => (
+  <div
+    data-testid={testId}
+    className={cn(
+      'pointer-events-none fixed top-[max(0.75rem,env(safe-area-inset-top))] left-[max(0.75rem,env(safe-area-inset-left))] z-30 opacity-40',
+      className,
+    )}
+    aria-hidden
+  >
+    {/* eslint-disable-next-line @next/next/no-img-element -- ui-kit is framework-agnostic */}
+    <img src={src} alt={alt} className="h-7 w-auto select-none" />
+  </div>
+);

package/src/components/shell-glass-toolbar.tsx

@@ -0,0 +1,107 @@
+/**
+ * `ShellGlassToolbar` — floating transparent toolbar for Host linked mode.
+ */
+
+import * as React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type ShellGlassToolbarProps = {
+  readonly children: React.ReactNode;
+  readonly className?: string;
+  readonly testId?: string;
+};
+
+export const ShellGlassToolbar = ({
+  children,
+  className,
+  testId = 'shell-glass-toolbar',
+}: ShellGlassToolbarProps): React.ReactElement => (
+  <div
+    data-testid={testId}
+    className={cn(
+      'fixed top-[max(0.75rem,env(safe-area-inset-top))] right-[max(0.75rem,env(safe-area-inset-right))] z-40',
+      'flex items-center gap-1 rounded-full border border-foreground/10 bg-background/35 p-1 shadow-lg backdrop-blur-md',
+      className,
+    )}
+    role="toolbar"
+    aria-label="Host session controls"
+  >
+    {children}
+  </div>
+);
+
+export type ShellToolbarButtonProps = {
+  readonly label: string;
+  readonly onClick?: () => void;
+  readonly disabled?: boolean;
+  readonly className?: string;
+  readonly testId?: string;
+  readonly 'aria-expanded'?: boolean;
+  readonly 'aria-controls'?: string;
+};
+
+export const ShellToolbarButton = ({
+  label,
+  onClick,
+  disabled = false,
+  className,
+  testId,
+  'aria-expanded': ariaExpanded,
+  'aria-controls': ariaControls,
+}: ShellToolbarButtonProps): React.ReactElement => (
+  <button
+    type="button"
+    onClick={onClick}
+    disabled={disabled}
+    data-testid={testId}
+    aria-expanded={ariaExpanded}
+    aria-controls={ariaControls}
+    className={cn(
+      'rounded-full px-3 py-1.5 text-xs font-semibold tracking-wide text-foreground uppercase',
+      'transition-colors hover:bg-foreground/10 disabled:cursor-not-allowed disabled:opacity-40',
+      className,
+    )}
+  >
+    {label}
+  </button>
+);
+
+export type ShellToolbarMenuProps = {
+  readonly triggerLabel?: string;
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly children: React.ReactNode;
+  readonly testId?: string;
+};
+
+export const ShellToolbarMenu = ({
+  triggerLabel = '…',
+  open,
+  onOpenChange,
+  children,
+  testId = 'shell-toolbar-menu',
+}: ShellToolbarMenuProps): React.ReactElement => {
+  const menuId = React.useId();
+
+  return (
+    <div className="relative" data-testid={testId}>
+      <ShellToolbarButton
+        label={triggerLabel}
+        onClick={() => onOpenChange(!open)}
+        aria-expanded={open}
+        aria-controls={menuId}
+        testId={`${testId}-trigger`}
+      />
+      {open ? (
+        <div
+          id={menuId}
+          role="menu"
+          className="absolute top-full right-0 z-50 mt-2 min-w-[12rem] rounded-xl border border-border bg-popover p-2 text-popover-foreground shadow-xl"
+        >
+          {children}
+        </div>
+      ) : null}
+    </div>
+  );
+};

package/src/components/shell-menu-avatar.tsx

@@ -0,0 +1,73 @@
+/**
+ * `ShellMenuAvatar` — Player linked-session menu trigger (top-right).
+ */
+
+import * as React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type ShellMenuAvatarProps = {
+  readonly imageUrl?: string | null;
+  readonly displayName?: string;
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly menuContent: React.ReactNode;
+  readonly className?: string;
+  readonly testId?: string;
+};
+
+const initialsFromName = (name: string): string => {
+  const parts = name.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return '?';
+  if (parts.length === 1) return parts[0]!.slice(0, 2).toUpperCase();
+  return `${parts[0]![0] ?? ''}${parts[1]![0] ?? ''}`.toUpperCase();
+};
+
+export const ShellMenuAvatar = ({
+  imageUrl,
+  displayName = 'Player',
+  open,
+  onOpenChange,
+  menuContent,
+  className,
+  testId = 'shell-menu-avatar',
+}: ShellMenuAvatarProps): React.ReactElement => {
+  const menuId = React.useId();
+  const initials = initialsFromName(displayName);
+
+  return (
+    <div
+      className={cn(
+        'fixed top-[max(0.75rem,env(safe-area-inset-top))] right-[max(0.75rem,env(safe-area-inset-right))] z-40',
+        className,
+      )}
+      data-testid={testId}
+    >
+      <button
+        type="button"
+        aria-label="Session menu"
+        aria-expanded={open}
+        aria-controls={menuId}
+        onClick={() => onOpenChange(!open)}
+        data-testid={`${testId}-trigger`}
+        className="flex size-11 items-center justify-center overflow-hidden rounded-full border border-foreground/15 bg-card/80 shadow-lg backdrop-blur-md transition-transform hover:scale-105"
+      >
+        {imageUrl ? (
+          // eslint-disable-next-line @next/next/no-img-element
+          <img src={imageUrl} alt="" className="size-full object-cover" />
+        ) : (
+          <span className="text-sm font-bold text-foreground">{initials}</span>
+        )}
+      </button>
+      {open ? (
+        <div
+          id={menuId}
+          role="menu"
+          className="absolute top-full right-0 z-50 mt-2 min-w-[12rem] rounded-xl border border-border bg-popover p-2 text-popover-foreground shadow-xl"
+        >
+          {menuContent}
+        </div>
+      ) : null}
+    </div>
+  );
+};

package/src/components/shell-session-frame.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest';
+
+import { playerLinkedMaxWidth } from './shell-session-frame.js';
+
+describe('playerLinkedMaxWidth', () => {
+  it('returns 33% of viewport height', () => {
+    expect(playerLinkedMaxWidth(900)).toBe(297);
+    expect(playerLinkedMaxWidth(0)).toBe(0);
+  });
+});

package/src/components/shell-session-frame.tsx

@@ -0,0 +1,76 @@
+/**
+ * `ShellSessionFrame` — layout wrapper for linked Host / Player sessions.
+ */
+
+import * as React from 'react';
+
+import { HostDisplayViewport } from './host-display-viewport.js';
+import { cn } from '../lib/cn.js';
+
+export type ShellSessionFrameVariant = 'host' | 'player';
+
+export type ShellSessionFrameProps = {
+  readonly variant: ShellSessionFrameVariant;
+  readonly chrome?: React.ReactNode;
+  readonly children: React.ReactNode;
+  /** Host only — contain scale/backdrop inside a preview card instead of the browser viewport. */
+  readonly embedded?: boolean;
+  /** Host only — fill a parent flex region (e.g. shell devtools body) instead of 100dvh. */
+  readonly fillParent?: boolean;
+  readonly className?: string;
+  readonly testId?: string;
+};
+
+export const playerLinkedMaxWidth = (viewportHeightPx: number): number =>
+  Math.max(0, viewportHeightPx * 0.33);
+
+export const ShellSessionFrame = ({
+  variant,
+  chrome,
+  children,
+  embedded = false,
+  fillParent = false,
+  className,
+  testId,
+}: ShellSessionFrameProps): React.ReactElement => {
+  if (variant === 'host') {
+    return (
+      <div
+        data-shell-mode="linked"
+        {...(embedded ? { 'data-shell-embedded': '' } : {})}
+        data-testid={testId ?? 'shell-session-frame-host'}
+        className={cn(
+          'relative flex w-full min-h-0 flex-col overflow-hidden text-foreground',
+          embedded || fillParent ? 'h-full min-h-0 flex-1' : 'h-[100dvh]',
+          className,
+        )}
+      >
+        {chrome}
+        <HostDisplayViewport embedded={embedded}>{children}</HostDisplayViewport>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      data-shell-mode="linked"
+      data-testid={testId ?? 'shell-session-frame-player'}
+      className={cn(
+        'flex h-[100dvh] w-full items-stretch justify-center overflow-hidden bg-background text-foreground',
+        className,
+      )}
+    >
+      <div
+        className={cn(
+          'relative flex min-h-0 w-full max-w-[min(100vw,33dvh)] flex-col overflow-hidden',
+          'pb-[env(safe-area-inset-bottom)] pt-[env(safe-area-inset-top)]',
+        )}
+      >
+        {chrome}
+        <div className="relative min-h-0 min-w-0 flex-1 overflow-hidden">
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+};

package/src/index.ts

@@ -20,6 +20,17 @@
  * Visual review for the kit lives in `apps/uikit-preview`.
  */
 
+export {
+  CameraCaptureModal,
+  type CameraCaptureModalProps,
+} from './components/camera-capture-modal.js';
+
+export {
+  PlayerAvatarPicker,
+  type PlayerAvatarPickerProps,
+  type PlayerAvatarPickerShape,
+} from './components/player-avatar-picker.js';
+
 export {
   PromptInput,
   type PromptInputProps,
@@ -52,6 +63,65 @@ export {
   type ResponseCardProps,
 } from './components/response-card.js';
 
+export {
+  ShellBrandMark,
+  type ShellBrandMarkProps,
+} from './components/shell-brand-mark.js';
+
+export {
+  ShellGlassToolbar,
+  ShellToolbarButton,
+  ShellToolbarMenu,
+  type ShellGlassToolbarProps,
+  type ShellToolbarButtonProps,
+  type ShellToolbarMenuProps,
+} from './components/shell-glass-toolbar.js';
+
+export {
+  ShellMenuAvatar,
+  type ShellMenuAvatarProps,
+} from './components/shell-menu-avatar.js';
+
+export {
+  HostDisplayViewport,
+  type HostDisplayViewportProps,
+} from './components/host-display-viewport.js';
+
+export {
+  ShellSessionFrame,
+  playerLinkedMaxWidth,
+  type ShellSessionFrameProps,
+  type ShellSessionFrameVariant,
+} from './components/shell-session-frame.js';
+
+export {
+  computeHostCanvasScale,
+  HOST_BACKDROP_CSS_VAR,
+  HOST_CANVAS_HEIGHT,
+  HOST_CANVAS_WIDTH,
+} from './lib/host-canvas.js';
+
+export {
+  buildHostIframeLoaderScript,
+  HOST_IFRAME_BRIDGE_KEY,
+  HOST_IFRAME_CLEANUP_KEY,
+  HOST_IFRAME_MOUNT_ID,
+  initHostIframeDocument,
+  resolveHostMountElement,
+  type HostIframeBridge,
+} from './lib/host-mount.js';
+
+export {
+  PlayerAvatar,
+  type PlayerAvatarProps,
+} from './components/player-avatar.js';
+
+export {
+  PlayerRoster,
+  type PlayerRosterEntry,
+  type PlayerRosterProps,
+} from './components/player-roster.js';
+
 export {
   JoinCodeBadge,
   type JoinCodeBadgeProps,

package/src/lib/host-canvas.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  computeHostCanvasScale,
+  HOST_CANVAS_HEIGHT,
+  HOST_CANVAS_WIDTH,
+} from './host-canvas.js';
+
+describe('HOST_CANVAS constants', () => {
+  it('uses 16:9 at 1080p logical resolution', () => {
+    expect(HOST_CANVAS_WIDTH).toBe(1920);
+    expect(HOST_CANVAS_HEIGHT).toBe(1080);
+    expect(HOST_CANVAS_WIDTH / HOST_CANVAS_HEIGHT).toBeCloseTo(16 / 9);
+  });
+});
+
+describe('computeHostCanvasScale', () => {
+  it('returns 1 when the available area matches the design canvas', () => {
+    expect(computeHostCanvasScale(1920, 1080)).toBe(1);
+  });
+
+  it('letterboxes by the limiting axis (width)', () => {
+    expect(computeHostCanvasScale(960, 1080)).toBe(0.5);
+  });
+
+  it('letterboxes by the limiting axis (height)', () => {
+    expect(computeHostCanvasScale(1920, 540)).toBe(0.5);
+  });
+
+  it('upscales on large displays without a cap', () => {
+    expect(computeHostCanvasScale(3840, 2160)).toBe(2);
+    expect(computeHostCanvasScale(7680, 4320)).toBe(4);
+  });
+
+  it('returns 0 for non-positive available dimensions', () => {
+    expect(computeHostCanvasScale(0, 1080)).toBe(0);
+    expect(computeHostCanvasScale(1920, 0)).toBe(0);
+    expect(computeHostCanvasScale(-100, 1080)).toBe(0);
+  });
+});

package/src/lib/host-canvas.ts

@@ -0,0 +1,30 @@
+/**
+ * Logical design canvas for Host (TV) surfaces.
+ *
+ * Experience bundles should lay out Host UI against these dimensions.
+ * The shell scales the canvas uniformly to fit the available viewport
+ * (after devtools chrome), without capping upscale on 4K / 8K displays.
+ */
+
+/** Host design canvas width — 16:9 at 1080p. */
+export const HOST_CANVAS_WIDTH = 1920;
+
+/** Host design canvas height — 16:9 at 1080p. */
+export const HOST_CANVAS_HEIGHT = 1080;
+
+/** CSS custom property bundles set on the mount container for the viewport backdrop. */
+export const HOST_BACKDROP_CSS_VAR = '--host-backdrop';
+
+export const computeHostCanvasScale = (
+  availableWidth: number,
+  availableHeight: number,
+): number => {
+  if (availableWidth <= 0 || availableHeight <= 0) {
+    return 0;
+  }
+
+  return Math.min(
+    availableWidth / HOST_CANVAS_WIDTH,
+    availableHeight / HOST_CANVAS_HEIGHT,
+  );
+};

package/src/lib/host-mount.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildHostIframeLoaderScript,
+  HOST_IFRAME_MOUNT_ID,
+  initHostIframeDocument,
+} from './host-mount.js';
+
+describe('initHostIframeDocument', () => {
+  it('creates a fixed-size mount node in the iframe document', () => {
+    const doc = document.implementation.createHTMLDocument('host');
+    const mount = initHostIframeDocument(doc);
+
+    expect(mount.id).toBe(HOST_IFRAME_MOUNT_ID);
+    expect(mount.getAttribute('data-host-mount')).not.toBeNull();
+    expect(doc.body.style.width).toBe('1920px');
+    expect(doc.body.style.height).toBe('1080px');
+  });
+});
+
+describe('buildHostIframeLoaderScript', () => {
+  it('embeds the bundle URL and mount id', () => {
+    const script = buildHostIframeLoaderScript(
+      'https://example.test/host.js?dev=1',
+    );
+
+    expect(script).toContain('https://example.test/host.js?dev=1');
+    expect(script).toContain(HOST_IFRAME_MOUNT_ID);
+    expect(script).toContain('bridge.onReady?.()');
+  });
+});

package/src/lib/host-mount.ts

@@ -0,0 +1,68 @@
+import { HOST_CANVAS_HEIGHT, HOST_CANVAS_WIDTH } from './host-canvas.js';
+
+export const HOST_IFRAME_MOUNT_ID = 'wibly-host-mount';
+
+export const HOST_IFRAME_BRIDGE_KEY = '__WIBLY_HOST_IFRAME_BRIDGE__';
+
+export const HOST_IFRAME_CLEANUP_KEY = '__WIBLY_HOST_IFRAME_CLEANUP__';
+
+export type HostIframeBridge = {
+  readonly getSession: () => unknown;
+  readonly onError: (error: Error) => void;
+  readonly onReady?: () => void;
+};
+
+export const initHostIframeDocument = (doc: Document): HTMLElement => {
+  doc.open();
+  doc.write(`<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=${HOST_CANVAS_WIDTH}, initial-scale=1"></head><body style="margin:0;overflow:hidden;width:${HOST_CANVAS_WIDTH}px;height:${HOST_CANVAS_HEIGHT}px"><div id="${HOST_IFRAME_MOUNT_ID}" data-host-mount style="width:100%;height:100%;overflow:hidden"></div></body></html>`);
+  doc.close();
+
+  const mount = doc.getElementById(HOST_IFRAME_MOUNT_ID);
+  if (!mount) {
+    throw new Error('Host iframe mount node was not created.');
+  }
+
+  return mount;
+};
+
+export const buildHostIframeLoaderScript = (bundleUrl: string): string => {
+  const urlLiteral = JSON.stringify(bundleUrl);
+  return `
+(async () => {
+  const bridge = window.parent[${JSON.stringify(HOST_IFRAME_BRIDGE_KEY)}];
+  if (!bridge) {
+    throw new Error('Host iframe bridge is not available.');
+  }
+  try {
+    const mod = await import(/* webpackIgnore: true */ /* turbopackIgnore: true */ ${urlLiteral});
+    if (typeof mod.mount !== 'function') {
+      throw new Error('Experience bundle does not export mount(session, container).');
+    }
+    const container = document.getElementById(${JSON.stringify(HOST_IFRAME_MOUNT_ID)});
+    if (!container) {
+      throw new Error('Host iframe mount node is missing.');
+    }
+    window.parent[${JSON.stringify(HOST_IFRAME_CLEANUP_KEY)}] = mod.mount(
+      bridge.getSession(),
+      container,
+    );
+    bridge.onReady?.();
+  } catch (cause) {
+    bridge.onError(cause instanceof Error ? cause : new Error(String(cause)));
+  }
+})();
+`.trim();
+};
+
+export const resolveHostMountElement = (canvas: HTMLElement): Element | null => {
+  const iframe = canvas.querySelector('iframe[data-host-mount]');
+  if (iframe instanceof HTMLIFrameElement) {
+    return (
+      iframe.contentDocument?.querySelector('[data-host-mount]') ??
+      iframe.contentDocument?.getElementById(HOST_IFRAME_MOUNT_ID) ??
+      null
+    );
+  }
+
+  return canvas.querySelector('[data-host-mount]');
+};