@vllnt/ui 0.2.1-canary.8b618ce → 0.2.1-canary.95faa10

package/CHANGELOG.md

@@ -4,6 +4,40 @@ All notable changes to `@vllnt/ui` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+> Target version: **`0.3.0`** — canary only; not yet published. See [ROADMAP.md](../../ROADMAP.md) for shipping criteria.
+
+### Added
+
+- **Hooks + utility primitives** — `CopyButton` (+ `useCopyToClipboard` hook), `Banner` + `BannerAction`, `Kbd`, `EmptyState`, `DocumentSiblingNav`.
+- **Pricing + identity cards** — `PricingTable` + `PricingPlan`, `HistoricalFigureCard`, `CivilizationCard` (+ `CivilizationComparison`).
+- **Newsletter** — `NewsletterSignup` (state-machine driven submit flow).
+- **AI compound families** — `ModelComparison` (+ `Column`, `Meta`, `Vote`), `PromptTemplates`, `AgentActivity`, `AISidebar`, `AIArtifact`.
+- **Era / financial** — `EraComparison`, `TransactionList`.
+- **Forms** — `Form`, `MultiSelect`, `SegmentedControl`, `TagsInput`, `AutoReload`.
+- **Educational** — `KnowledgeCheck` (inline question runner).
+- **Charts + timelines** — `GanttChart`, `ParallelTimeline`, `Timeline` + `TimelineItem`, `HistoricTimeline`, `InteractiveTimeline`, `ChronologicalTimeline`, `TreeView`.
+- **Document + reading** — `PrimarySourceViewer` compound family.
+- **Maps + geography** — `Map2D`, `ChoroplethMap`, `RouteMap`, `HeatMapOverlay`, `GeographyQuizMap`, `MapTimeline`, `StoryMap`, `Globe3D`.
+- **Canvas foundation** — `CanvasShell`, `CanvasView`, `InfinitePlane`, `ViewportBookmarks`, `WorldBreadcrumbs`, `TopBar`, `LeftRail`, `RightDock`, `ZoomHud`, `MiniMapPanel`, `WorkspaceSwitcher`.
+- **Canvas selection + manipulation** — `SelectionHalo`, `SnapGuides`, `FloatingToolbar`, `MultiSelectLasso`, `FollowMode`, `HandoffBeacon`.
+- **Canvas spatial objects** — `ObjectCard`, `ObjectHandle`, `AnchorPort`, `ConnectorEdge`, `EdgeLabel`, `GroupHull`.
+- **Canvas collaboration primitives** — `LiveCursor`, `CommentPin`, `PresenceSyncIndicator`, `PresenceStack`, `SelectionPresence`, `ThreadBubble`.
+- **Inspector + dock panels** — `PropertySection`, `ObjectInspector`, `RelationshipInspector`, `RuntimeOverviewPanel`, `RoutingAssignmentPanel`, `PolicyDeliveryPanel`.
+- **Runtime overlays** — `AlertPulse`, `ThresholdRing`, `StickyMetric`, `HeatOverlay`, `StateBadgeOverlay`, `MetricCluster`, `JarvisDock`, `ContextLens`.
+- **Time navigation** — `TimelineScrubber`, `PlaybackGhost`, `BottomActivityStrip`, `RunTimeline`.
+- Total component count: **225** (up from 140).
+
+### Changed
+
+- Registry installs use a **hybrid CLI strategy** — leaf component source is inlined, sibling registry items resolve via `@vllnt/ui` to keep installs minimal and dedupe shared primitives.
+
+### Notes
+
+- `ROADMAP.md` added at repo root tracking 50 open issues across 8 phases gating the `0.3.0` cut.
+- `0.3.0` requires the codebase-health gate (`react-doctor` CI + 0 errors), the agent-first surface (`/llms.txt`, `/mcp`, sitemap, JSON-LD), and the rebuilt landing page before shipping.
+
 ## [0.2.1] - 2026-04-21
 
 ### Fixed

package/README.md

@@ -218,7 +218,7 @@ import {
 | `Alert` | `{ Alert, AlertTitle, AlertDescription, alertVariants }` | Static alert banner |
 | `Badge` | `{ Badge, badgeVariants }` | Inline status label. Variants: default, secondary, destructive, outline |
 | `Skeleton` | `{ Skeleton }` | Loading placeholder |
-| `Spinner` | `{ Spinner }` | Loading spinner |
+| `Spinner` | `{ Spinner, UnicodeSpinner }` | Styled spinner + ASCII-art `UnicodeSpinner` for terminals / code blocks |
 
 ### Navigation
 
@@ -242,7 +242,7 @@ import {
 | `BarChart` | `{ BarChart }` | Chart component |
 | `LineChart` | `{ LineChart }` | Chart component |
 | `CodeBlock` | `{ CodeBlock }` | Syntax-highlighted code via `react-syntax-highlighter` |
-| `FlowDiagram` | `{ FlowDiagram }` | Flow diagram via `@xyflow/react` |
+| `FlowDiagram` | `{ FlowDiagram, FlowControls, FlowFullscreen, FlowErrorBoundary, useFlowDiagram }` | Flow diagram via `@xyflow/react`. Extras: custom controls, fullscreen wrapper, error boundary, and the `useFlowDiagram` hook for imperative access. |
 | `TableOfContents` | `{ TableOfContents }` | Page table of contents |
 
 ### App Components
@@ -276,7 +276,10 @@ import {
 | `Flashcard` | `{ Flashcard }` | Flip-card for spaced repetition |
 | `Stepper` | `{ Stepper }` | Linear progress stepper |
 | `Tour` | `{ Tour }` | Guided product tour |
-| `Annotation` | `{ Annotation }` | Inline annotation / highlight |
+| `Annotation` | `{ Annotation, Highlight }` | Inline annotation block + inline `Highlight` span for in-prose emphasis |
+| `LearningObjectives` | `{ LearningObjectives, Prerequisites, Summary }` | Objectives list plus companion `Prerequisites` and `Summary` blocks |
+| `KeyConcept` | `{ KeyConcept, Glossary }` | Concept callout + `Glossary` term list |
+| `Comparison` | `{ Comparison, BeforeAfter }` | Side-by-side compare block + `BeforeAfter` slider |
 | `CompletionDialog` | `{ CompletionDialog }` | End-of-flow celebration dialog |
 | `TruncatedText` | `{ TruncatedText }` | Expand-on-overflow text block |
 | `TableOfContentsPanel` | `{ TableOfContentsPanel }` | Sidebar TOC panel |
@@ -334,7 +337,7 @@ import {
 | `BorderBeam` | `{ BorderBeam }` | Animated gradient border |
 | `Marquee` | `{ Marquee }` | Infinite scroll marquee |
 | `NumberTicker` | `{ NumberTicker }` | Animated number counter |
-| `Spinner` | `{ Spinner }` | Rich loading-spinner library |
+| `Spinner` | `{ Spinner, UnicodeSpinner }` | Styled spinner + ASCII-art `UnicodeSpinner` for terminals / code blocks |
 
 ### Form Additions
 
@@ -386,10 +389,22 @@ import { cn } from "@vllnt/ui";
 <div className={cn("p-4 bg-primary", isActive && "bg-accent", className)} />
 ```
 
+### Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `useDebounce(value, delayMs)` | Returns the value after `delayMs` of idle — ideal for search inputs. |
+| `useHorizontalScroll(ref)` | Drives the behavior used by `HorizontalScrollRow` — wheel → horizontal scroll, scroll-snap helpers. |
+| `useMobile(breakpoint?)` | Boolean for "viewport is below breakpoint" (default `768`). SSR-safe. |
+| `useSidebar()` | Reads `SidebarProvider` state — `{ open, setOpen, toggle }`. Throws outside a provider. |
+| `useFlowDiagram(options)` | Imperative controller for `FlowDiagram` — fit view, zoom, export to PNG. |
+| `useSocialFab()` | Drives the open/close state of `SocialFab`. |
+
 ```tsx
-import { useDebounce } from "@vllnt/ui";
+import { useDebounce, useMobile } from "@vllnt/ui";
 
-const debouncedValue = useDebounce(searchTerm, 300);
+const query = useDebounce(input, 300);
+const isMobile = useMobile();
 ```
 
 ## Types

package/dist/components/activity-log/activity-log.js

@@ -1,3 +1,4 @@
+"use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { forwardRef, useMemo, useState } from "react";
 import { ArrowRight, ChevronLeft, ChevronRight } from "lucide-react";

package/dist/components/agent-activity/agent-activity.js

@@ -0,0 +1,311 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useId,
+  useMemo,
+  useState
+} from "react";
+import {
+  AlertTriangle,
+  CheckCircle2,
+  ChevronDown,
+  Circle,
+  Loader2,
+  MinusCircle
+} from "lucide-react";
+import { cn } from "../../lib/utils";
+const STATUS_CLASSES = {
+  completed: {
+    iconClass: "text-emerald-600 dark:text-emerald-400",
+    ringClass: "ring-emerald-500/30",
+    rowClass: "border-border bg-background"
+  },
+  error: {
+    iconClass: "text-destructive",
+    ringClass: "ring-destructive/40",
+    rowClass: "border-destructive/40 bg-destructive/5"
+  },
+  pending: {
+    iconClass: "text-muted-foreground",
+    ringClass: "ring-border",
+    rowClass: "border-border bg-muted/20 text-muted-foreground"
+  },
+  running: {
+    iconClass: "text-primary",
+    ringClass: "ring-primary/30",
+    rowClass: "border-primary/30 bg-primary/5"
+  },
+  skipped: {
+    iconClass: "text-muted-foreground/60",
+    ringClass: "ring-border",
+    rowClass: "border-border bg-background text-muted-foreground/80"
+  }
+};
+const DEFAULT_STATUS_ICON = {
+  completed: /* @__PURE__ */ jsx(CheckCircle2, { "aria-hidden": "true", className: "h-4 w-4" }),
+  error: /* @__PURE__ */ jsx(AlertTriangle, { "aria-hidden": "true", className: "h-4 w-4" }),
+  pending: /* @__PURE__ */ jsx(Circle, { "aria-hidden": "true", className: "h-4 w-4" }),
+  running: /* @__PURE__ */ jsx(Loader2, { "aria-hidden": "true", className: "h-4 w-4 animate-spin" }),
+  skipped: /* @__PURE__ */ jsx(MinusCircle, { "aria-hidden": "true", className: "h-4 w-4" })
+};
+const StepContext = createContext({ status: "pending" });
+const DEFAULT_LABELS = {
+  activity: "Activity",
+  collapse: "Hide details",
+  elapsed: "Elapsed",
+  expand: "Show details"
+};
+const ACTIVITY_LIVE_REGION_ROLE = {
+  completed: "status",
+  error: "status",
+  idle: "status",
+  running: "log"
+};
+const AgentActivity = forwardRef(
+  (props, ref) => {
+    const {
+      children,
+      className,
+      elapsed,
+      labels,
+      status = "idle",
+      ...rest
+    } = props;
+    const resolvedLabels = { ...DEFAULT_LABELS, ...labels };
+    return /* @__PURE__ */ jsxs(
+      "section",
+      {
+        "aria-live": status === "running" ? "polite" : "off",
+        className: cn(
+          "flex flex-col gap-3 rounded-2xl border bg-background p-4",
+          className
+        ),
+        "data-status": status,
+        ref,
+        role: ACTIVITY_LIVE_REGION_ROLE[status],
+        ...rest,
+        children: [
+          /* @__PURE__ */ jsxs("header", { className: "flex items-center justify-between gap-3", children: [
+            /* @__PURE__ */ jsx("h3", { className: "text-sm font-semibold tracking-tight text-foreground", children: resolvedLabels.activity }),
+            elapsed ? /* @__PURE__ */ jsx(
+              "span",
+              {
+                "aria-label": resolvedLabels.elapsed,
+                className: "text-xs font-mono text-muted-foreground",
+                children: elapsed
+              }
+            ) : null
+          ] }),
+          /* @__PURE__ */ jsx("ol", { className: "flex flex-col gap-2", children })
+        ]
+      }
+    );
+  }
+);
+AgentActivity.displayName = "AgentActivity";
+function getDisplayName(value) {
+  if (value !== null && (typeof value === "object" || typeof value === "function") && "displayName" in value && typeof value.displayName === "string") {
+    return value.displayName;
+  }
+  return void 0;
+}
+function isAgentStepDetailElement(child) {
+  if (child === null || typeof child !== "object") return false;
+  if (!("type" in child)) return false;
+  return getDisplayName(child.type) === "AgentStepDetail";
+}
+function splitChildren(children) {
+  const items = Array.isArray(children) ? children : [children];
+  return items.reduce(
+    (split, child) => {
+      if (isAgentStepDetailElement(child)) {
+        split.body.push(child);
+      } else {
+        split.header.push(child);
+      }
+      return split;
+    },
+    { body: [], header: [] }
+  );
+}
+function StepRow({
+  detailsId,
+  hasDetails,
+  header,
+  icon,
+  iconClass,
+  labels,
+  onToggle,
+  open
+}) {
+  return /* @__PURE__ */ jsxs("div", { className: "flex items-start gap-3 px-3 py-2", children: [
+    /* @__PURE__ */ jsx(
+      "span",
+      {
+        "aria-hidden": "true",
+        className: cn(
+          "mt-0.5 inline-flex h-5 w-5 shrink-0 items-center justify-center",
+          iconClass
+        ),
+        children: icon
+      }
+    ),
+    /* @__PURE__ */ jsx("div", { className: "flex min-w-0 flex-1 flex-col gap-1", children: header }),
+    hasDetails ? /* @__PURE__ */ jsx(
+      "button",
+      {
+        "aria-controls": detailsId,
+        "aria-expanded": open,
+        "aria-label": open ? labels.collapse : labels.expand,
+        className: "ml-auto inline-flex h-6 w-6 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-foreground/10 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        onClick: onToggle,
+        type: "button",
+        children: /* @__PURE__ */ jsx(
+          ChevronDown,
+          {
+            "aria-hidden": "true",
+            className: cn(
+              "h-4 w-4 transition-transform",
+              open ? "rotate-180" : "rotate-0"
+            )
+          }
+        )
+      }
+    ) : null
+  ] });
+}
+const AgentStep = forwardRef(
+  (props, ref) => {
+    const {
+      children,
+      className,
+      defaultOpen = true,
+      icon,
+      status,
+      ...rest
+    } = props;
+    const split = useMemo(() => splitChildren(children), [children]);
+    const palette = STATUS_CLASSES[status];
+    const hasDetails = split.body.length > 0;
+    const [open, setOpen] = useState(defaultOpen);
+    const detailsId = useId();
+    const handleToggle = useCallback(() => {
+      setOpen((value) => !value);
+    }, []);
+    const contextValue = useMemo(
+      () => ({ status }),
+      [status]
+    );
+    const resolvedIcon = icon ?? DEFAULT_STATUS_ICON[status];
+    return /* @__PURE__ */ jsx(
+      "li",
+      {
+        className: cn(
+          "rounded-xl border ring-1",
+          palette.rowClass,
+          palette.ringClass,
+          className
+        ),
+        "data-status": status,
+        ref,
+        ...rest,
+        children: /* @__PURE__ */ jsxs(StepContext.Provider, { value: contextValue, children: [
+          /* @__PURE__ */ jsx(
+            StepRow,
+            {
+              detailsId,
+              hasDetails,
+              header: split.header,
+              icon: resolvedIcon,
+              iconClass: palette.iconClass,
+              labels: DEFAULT_LABELS,
+              onToggle: handleToggle,
+              open
+            }
+          ),
+          hasDetails && open ? /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: "border-t border-border/60 px-3 py-2 text-xs",
+              id: detailsId,
+              children: /* @__PURE__ */ jsx("div", { className: "flex flex-col gap-2 pl-8", children: split.body })
+            }
+          ) : null
+        ] })
+      }
+    );
+  }
+);
+AgentStep.displayName = "AgentStep";
+const AgentStepTitle = forwardRef(({ className, ...rest }, ref) => /* @__PURE__ */ jsx(
+  "p",
+  {
+    className: cn(
+      "text-sm font-medium leading-tight text-foreground",
+      className
+    ),
+    ref,
+    ...rest
+  }
+));
+AgentStepTitle.displayName = "AgentStepTitle";
+const AgentStepDuration = forwardRef(({ className, ...rest }, ref) => /* @__PURE__ */ jsx(
+  "span",
+  {
+    className: cn("font-mono text-xs text-muted-foreground", className),
+    ref,
+    ...rest
+  }
+));
+AgentStepDuration.displayName = "AgentStepDuration";
+const AgentStepProgress = forwardRef(({ className, label = "Step progress", value, ...rest }, ref) => {
+  const clamped = Math.max(0, Math.min(100, value));
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      "aria-label": label,
+      "aria-valuemax": 100,
+      "aria-valuemin": 0,
+      "aria-valuenow": clamped,
+      className: cn("h-1.5 w-full rounded-full bg-muted", className),
+      ref,
+      role: "progressbar",
+      ...rest,
+      children: /* @__PURE__ */ jsx(
+        "span",
+        {
+          className: "block h-full rounded-full bg-primary transition-[width]",
+          style: { width: `${clamped.toString()}%` }
+        }
+      )
+    }
+  );
+});
+AgentStepProgress.displayName = "AgentStepProgress";
+const AgentStepDetail = forwardRef(
+  ({ className, ...rest }, ref) => /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cn("text-xs text-muted-foreground", className),
+      ref,
+      ...rest
+    }
+  )
+);
+AgentStepDetail.displayName = "AgentStepDetail";
+function useAgentStepStatus() {
+  return useContext(StepContext).status;
+}
+export {
+  AgentActivity,
+  AgentStep,
+  AgentStepDetail,
+  AgentStepDuration,
+  AgentStepProgress,
+  AgentStepTitle,
+  useAgentStepStatus
+};

package/dist/components/agent-activity/index.js

@@ -0,0 +1,18 @@
+import {
+  AgentActivity,
+  AgentStep,
+  AgentStepDetail,
+  AgentStepDuration,
+  AgentStepProgress,
+  AgentStepTitle,
+  useAgentStepStatus
+} from "./agent-activity";
+export {
+  AgentActivity,
+  AgentStep,
+  AgentStepDetail,
+  AgentStepDuration,
+  AgentStepProgress,
+  AgentStepTitle,
+  useAgentStepStatus
+};