@heyramzi/ui 7.0.0 → 8.1.0

package/src/agents/agent-cast.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
   import AgentAvatar from './agent-avatar.svelte';
-  import type { Agent } from './types';
+  import type { Agent, AgentState } from './types';
 
   type Props = {
     /** The cast to lay out. */
@@ -32,6 +32,12 @@
 
   const keyOf = (agent: Agent) => agent.id ?? agent.name;
 
+  /* The card under the pointer or focus wakes up and works; the rest idle.
+     A `state` in avatarProps wins. */
+  let awake = $state<string | null>(null);
+  const stateFor = (id: string) =>
+    (avatarProps.state as AgentState | undefined) ?? (awake === id ? 'working' : 'default');
+
   /* Group when any agent asks for one, otherwise a single flat grid. */
   const sections = $derived.by(() => {
     const anyGroup = agents.some((agent) => agent.group);
@@ -72,8 +78,12 @@
             <button
               type="button"
               class="agent-cast__card"
-              aria-current={id === selectedId ? 'true' : undefined}
+              aria-pressed={onSelect ? id === selectedId : undefined}
               onclick={() => onSelect?.(agent)}
+              onpointerenter={() => (awake = id)}
+              onpointerleave={() => awake === id && (awake = null)}
+              onfocus={() => (awake = id)}
+              onblur={() => awake === id && (awake = null)}
             >
               <span class="agent-cast__slot">
                 <AgentAvatar
@@ -81,7 +91,9 @@
                   role={agent.role}
                   shape={agent.shape ?? 'clover'}
                   color={agent.color}
+                  aria-hidden
                   {...avatarProps}
+                  state={stateFor(id)}
                 />
               </span>
               <span class="agent-cast__meta">
@@ -133,11 +145,21 @@
     border-radius: 0.75rem;
     cursor: pointer;
     transition:
-      border-color 0.15s ease,
-      transform 0.15s ease;
+      border-color var(--duration-quick, 150ms) var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1)),
+      transform var(--duration-quick, 150ms) var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
   }
-  .agent-cast__card:hover {
-    border-color: color-mix(in oklab, var(--color-foreground, #18181b) 25%, transparent);
+  @media (prefers-reduced-motion: reduce) {
+    .agent-cast__card {
+      transition: border-color var(--duration-quick, 150ms) linear;
+    }
+    .agent-cast__card:active {
+      transform: none;
+    }
+  }
+  @media (hover: hover) and (pointer: fine) {
+    .agent-cast__card:hover {
+      border-color: color-mix(in oklab, var(--color-foreground, #18181b) 25%, transparent);
+    }
   }
   .agent-cast__card:active {
     transform: scale(0.985);
@@ -146,13 +168,15 @@
     outline: 2px solid var(--color-ring, #6366f1);
     outline-offset: 2px;
   }
-  .agent-cast__card[aria-current='true'] {
+  .agent-cast__card[aria-pressed='true'] {
     border-color: var(--color-accent, #6366f1);
     box-shadow: 0 0 0 1px var(--color-accent, #6366f1);
   }
+  /* Room above the head, so a hop or a hat never meets the card's edge. */
   .agent-cast__slot {
     display: block;
     width: 100%;
+    padding: 0.5rem 0.5rem 0;
   }
   .agent-cast__meta {
     display: flex;

package/src/agents/demo.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import AgentAvatar from './agent-avatar.svelte';
   import AgentCast from './agent-cast.svelte';
-  import type { Agent } from './types';
+  import type { Agent, AgentState } from './types';
 
   const cast: Agent[] = [
     { id: 'ada', name: 'Ada', role: 'Researcher', shape: 'clover', color: '#41C4FF', group: 'Research' },
@@ -14,7 +14,14 @@
     { id: 'hal', name: 'Hal', role: 'Watcher', shape: 'star', group: 'Craft' },
   ];
 
+  const states: { value: AgentState; label: string }[] = [
+    { value: 'default', label: 'Idle' },
+    { value: 'working', label: 'Working' },
+    { value: 'sleeping', label: 'Sleeping' },
+  ];
+
   let selected = $state<string | null>('ada');
+  let leadState = $state<AgentState>('working');
   let lead = $derived(cast.find((agent) => agent.id === selected) ?? cast[0]);
 </script>
 
@@ -26,14 +33,25 @@
         role={lead.role}
         shape={lead.shape}
         color={lead.color}
-        state="working"
-        theme="light"
+        state={leadState}
       />
     </div>
     <div class="demo__intro">
       <p class="demo__eyebrow">AgentCast</p>
       <h1 class="demo__title">{lead.name}</h1>
       <p class="demo__role">{lead.role}</p>
+      <div class="demo__states" role="radiogroup" aria-label="State">
+        {#each states as s (s.value)}
+          <button
+            type="button"
+            role="radio"
+            aria-checked={leadState === s.value}
+            onclick={() => (leadState = s.value)}
+          >
+            {s.label}
+          </button>
+        {/each}
+      </div>
     </div>
   </header>
 
@@ -45,9 +63,8 @@
     max-width: 56rem;
     margin: 0 auto;
     padding: 2rem 1.5rem 4rem;
-    font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
-    color: #18181b;
-    background: #fafafa;
+    color: var(--color-foreground, #18181b);
+    background: var(--color-background, #fafafa);
   }
   .demo__hero {
     display: flex;
@@ -64,7 +81,7 @@
     font-size: 0.75rem;
     letter-spacing: 0.14em;
     text-transform: uppercase;
-    color: #71717a;
+    color: var(--color-muted-foreground, #71717a);
   }
   .demo__title {
     margin: 0.25rem 0 0;
@@ -73,6 +90,36 @@
   }
   .demo__role {
     margin: 0.25rem 0 0;
-    color: #52525b;
+    color: var(--color-muted-foreground, #52525b);
+  }
+  .demo__states {
+    display: inline-flex;
+    gap: 0.25rem;
+    margin-top: 0.875rem;
+    padding: 0.1875rem;
+    border-radius: 0.625rem;
+    background: color-mix(in oklab, var(--color-foreground, #18181b) 6%, transparent);
+  }
+  .demo__states button {
+    padding: 0.3125rem 0.75rem;
+    font: inherit;
+    font-size: 0.8125rem;
+    color: var(--color-muted-foreground, #71717a);
+    background: transparent;
+    border: 0;
+    border-radius: 0.4375rem;
+    cursor: pointer;
+    transition:
+      color var(--duration-quick, 150ms) var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1)),
+      background-color var(--duration-quick, 150ms) var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+  }
+  .demo__states button[aria-checked='true'] {
+    color: var(--color-foreground, #18181b);
+    background: var(--color-card, #fff);
+    box-shadow: var(--elev-hairline, 0 0 0 1px rgb(0 0 0 / 0.06));
+  }
+  .demo__states button:focus-visible {
+    outline: 2px solid var(--color-ring, #6366f1);
+    outline-offset: 1px;
   }
 </style>

package/src/agents/helpers.ts

@@ -0,0 +1,58 @@
+/* Pure helpers for the avatar: numbers, theme, lights, idle scheduling. */
+import { stockLights } from './vendor/plastic';
+
+export const clamp = (v: number, lo: number, hi: number) =>
+  Math.min(hi, Math.max(lo, Number.isFinite(v) ? v : 1));
+export const q = (v: number, lo: number, hi: number) => Math.round(clamp(v, lo, hi) * 20) / 20;
+export const clampOpt = (v: number | undefined, d: number, lo: number, hi: number) =>
+  clamp(v ?? d, lo, hi);
+export const deviceDpr = () =>
+  Math.min(2, (typeof devicePixelRatio === 'number' && devicePixelRatio) || 1);
+
+export function hashSeed(id: string): number {
+  let h = 2166136261;
+  for (let i = 0; i < id.length; i++) h = Math.imul(h ^ id.charCodeAt(i), 16777619);
+  return ((h >>> 0) % 1000) / 1000;
+}
+
+export const reducedMotion = (): boolean =>
+  typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+export function resolveTheme(theme: 'auto' | 'dark' | 'light', el: HTMLElement | null): 'dark' | 'light' {
+  if (theme !== 'auto') return theme;
+  const host = el?.closest('[data-theme], .dark, .light') as HTMLElement | null;
+  if (host) {
+    const v = host.getAttribute('data-theme');
+    if (v === 'dark' || v === 'light') return v;
+    if (host.classList.contains('dark')) return 'dark';
+    if (host.classList.contains('light')) return 'light';
+  }
+  return typeof matchMedia === 'function' && matchMedia('(prefers-color-scheme: light)').matches
+    ? 'light'
+    : 'dark';
+}
+
+export function lightsFor(lightAt: number, backLight?: number, lightFront?: number) {
+  const a = (lightAt * Math.PI) / 180;
+  const b = ((backLight ?? 0) * Math.PI) / 180;
+  const lights = stockLights(Math.sin(a), -Math.cos(a));
+  if (backLight !== undefined) [lights.bx, lights.by] = [Math.sin(b), -Math.cos(b)];
+  if (lightFront !== undefined) lights.front = (Math.min(85, Math.max(0, lightFront)) * Math.PI) / 180;
+  return lights;
+}
+
+export function warmIdle(fn: () => void): () => void {
+  if (typeof requestIdleCallback === 'function') {
+    const id = requestIdleCallback(fn);
+    return () => cancelIdleCallback(id);
+  }
+  const id = setTimeout(fn, 1);
+  return () => clearTimeout(id);
+}
+
+/* Full pull up close, fading to nothing by 3 head widths. */
+export function pointerStrength(d: number) {
+  if (d < 1) return 1;
+  if (d > 3) return 0;
+  return 1 - (d - 1) / 2;
+}

package/src/agents/page-state.ts

@@ -0,0 +1,70 @@
+/* What every avatar on the page shares: the batching shown-gate, so a row of
+   them comes in together, the path caches, and one theme watcher. */
+import { bakesPending } from './vendor/plastic';
+
+export const SHOW_WITHIN = 4000;
+export const waiters = new Map<object, { ready: () => boolean; show: () => void }>();
+
+export function showReady() {
+  if (bakesPending()) return;
+  for (const w of waiters.values()) if (!w.ready()) return;
+  const all = [...waiters.values()];
+  waiters.clear();
+  for (const w of all) w.show();
+}
+
+const pathCache = new Map<string, Path2D>();
+export function bodyPath(d: string): Path2D {
+  let p = pathCache.get(d);
+  if (!p) {
+    p = new Path2D(d);
+    pathCache.set(d, p);
+  }
+  return p;
+}
+
+const partsCache = new Map<string, Path2D[]>();
+export function partPaths(d: string): Path2D[] {
+  let p = partsCache.get(d);
+  if (!p) {
+    p = d
+      .split(/(?=M)/)
+      .filter((s) => s.trim())
+      .map((s) => new Path2D(s));
+    partsCache.set(d, p);
+  }
+  return p;
+}
+
+let uidSeq = 0;
+export const nextUid = () => `ba-${++uidSeq}`;
+
+/* One observer for the whole page: a `.dark` or `data-theme` flip on
+   <html> or <body>, or the OS scheme changing, repaints every auto avatar. */
+const themeListeners = new Set<() => void>();
+let themeWatch: (() => void) | null = null;
+export function onThemeChange(fn: () => void): () => void {
+  themeListeners.add(fn);
+  if (!themeWatch && typeof MutationObserver === 'function' && typeof document !== 'undefined') {
+    const fire = () => {
+      for (const l of themeListeners) l();
+    };
+    const mo = new MutationObserver(fire);
+    const opts = { attributes: true, attributeFilter: ['class', 'data-theme'] };
+    mo.observe(document.documentElement, opts);
+    if (document.body) mo.observe(document.body, opts);
+    const mq = typeof matchMedia === 'function' ? matchMedia('(prefers-color-scheme: dark)') : null;
+    mq?.addEventListener('change', fire);
+    themeWatch = () => {
+      mo.disconnect();
+      mq?.removeEventListener('change', fire);
+    };
+  }
+  return () => {
+    themeListeners.delete(fn);
+    if (themeListeners.size === 0 && themeWatch) {
+      themeWatch();
+      themeWatch = null;
+    }
+  };
+}

package/src/agents/types.ts

@@ -61,7 +61,7 @@ export type AgentAvatarProps = Omit<
   shape?: AgentShape;
   /** Face kind. Default `eyes`. */
   face?: BotAvatarFace;
-  /** Face ink. Default `#1E1A33`. */
+  /** Face ink. Default: dark on a light body, light on a dark one. */
   ink?: string;
   /** Rendered size in px. Omit to fill 75% of the slot. */
   size?: number;
@@ -69,4 +69,6 @@ export type AgentAvatarProps = Omit<
   style?: string;
   onclick?: (event: MouseEvent) => void;
   'aria-label'?: string;
+  /** Hide the canvas from assistive tech when a parent already names the agent. */
+  'aria-hidden'?: boolean | 'true' | 'false';
 };

package/src/ai/ai-button/AiButton.svelte

@@ -0,0 +1,86 @@
+<script lang="ts" module>
+	import type { ButtonProps } from "../../shadcn/button/index.js";
+
+	export type AiStatus = "idle" | "processing" | "done";
+
+	export interface AiButtonProps {
+		status?: AiStatus;
+		label?: string;
+		processingLabel?: string;
+		variant?: ButtonProps["variant"];
+		size?: ButtonProps["size"];
+		disabled?: boolean;
+		onclick?: (e: MouseEvent) => void;
+		class?: string;
+		iconOnly?: boolean;
+	}
+</script>
+
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import { cn } from "@heyramzi/utils";
+	import { Sparkle } from "phosphor-svelte";
+	import { Spinner } from "../../shadcn/spinner/index.js";
+	import { Button } from "../../shadcn/button/index.js";
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		status = "idle",
+		label = "Generate",
+		processingLabel = "Processing...",
+		variant = "outline",
+		size = "sm",
+		disabled = false,
+		onclick,
+		class: className,
+		iconOnly = false,
+	}: AiButtonProps = $props();
+</script>
+
+<!-- ===========================
+     MARKUP
+     =========================== -->
+{#if iconOnly}
+	<Button
+		{variant}
+		size="sm"
+		icon
+		disabled={disabled || status === "processing"}
+		onclick={onclick}
+		class={cn(
+			"relative",
+			status === "processing" && "pointer-events-none",
+			className,
+		)}
+	>
+		{#if status === "processing"}
+			<Spinner class="size-4" />
+		{:else}
+			<Sparkle class="size-4" weight="fill" />
+		{/if}
+	</Button>
+{:else}
+	<Button
+		{variant}
+		{size}
+		disabled={disabled || status === "processing"}
+		onclick={onclick}
+		class={cn(
+			"gap-1.5",
+			status === "processing" && "pointer-events-none",
+			className,
+		)}
+	>
+		{#if status === "processing"}
+			<Spinner class="size-3.5" />
+			<span>{processingLabel}</span>
+		{:else}
+			<Sparkle class="size-3.5" weight="fill" />
+			<span>{label}</span>
+		{/if}
+	</Button>
+{/if}

package/src/ai/ai-button/index.ts

@@ -0,0 +1,4 @@
+import AiButton from "./AiButton.svelte";
+import type { AiButtonProps, AiStatus } from "./AiButton.svelte";
+
+export { AiButton, type AiButtonProps, type AiStatus };

package/src/ai/confirmation/Confirmation.svelte

@@ -23,15 +23,15 @@
 		...rest
 	}: ConfirmationProps = $props();
 
-	// WHY: setContext runs once on mount but the value is referenced reactively via the proxy Svelte sets up on objects passed to setContext.
-
-	// State changes rerun any $derived in child components.
-	const ctx = $state({ kind, executing });
-	$effect(() => {
-		ctx.kind = kind;
-		ctx.executing = executing;
+	// WHY getters: setContext runs once on mount, so the parts read the props through these and rerun their $derived when a prop changes.
+	setConfirmationContext({
+		get kind() {
+			return kind;
+		},
+		get executing() {
+			return executing;
+		},
 	});
-	setConfirmationContext(ctx);
 </script>
 
 {#if kind !== "idle"}

package/src/ai/confirmation/confirmation-context.svelte.ts

@@ -5,8 +5,8 @@ const CONFIRMATION_CONTEXT_KEY = Symbol("confirmation-context");
 export type ConfirmationState = "idle" | "requested" | "accepted" | "rejected" | "failed";
 
 export interface ConfirmationContextValue {
-  kind: ConfirmationState;
-  executing: boolean;
+  readonly kind: ConfirmationState;
+  readonly executing: boolean;
 }
 
 export function setConfirmationContext(value: ConfirmationContextValue) {