@vibeflow-tools/prototyping 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @vibeflow-tools/prototyping
+
+## 0.2.0
+
+### Minor Changes
+
+- Add `@vibeflow-tools/prototyping` React package for in-app variant switching. Provides `useVariant`, `useActiveVariant`, `VariantProvider`, `PageVariantSwitcher`, `VariantSwitcher`, and `VariantDevToolbar` components with URL param and localStorage persistence, keyboard shortcuts (Alt+H / Ctrl+Shift+V, configurable), overlay integration (MutationObserver + polling for bookmarklet injection), and zero runtime dependencies.
+
+### Patch Changes
+
+- c525ae7: Make `VariantSwitcher` draggable — same hold-to-drag behaviour as the vibeflow corner trigger. Hold the indicator dot for 300ms, then drag to reposition anywhere on the viewport. Position is persisted to `localStorage` per scope name (`vf-variant-pos-<name>`), so it survives page reloads. Cursor changes to `grab` on hold and `grabbing` during drag for clear affordance.
+- Add production-ready README with full API reference, quick start, persistence docs, keyboard shortcuts, and Vibeflow overlay integration guide.

package/README.md

@@ -0,0 +1,341 @@
+# @vibeflow-tools/prototyping
+
+> **In-app variant switching for React** — page-level and component-level prototyping with URL persistence and zero runtime dependencies.
+
+[![npm](https://img.shields.io/npm/v/@vibeflow-tools/prototyping)](https://www.npmjs.com/package/@vibeflow-tools/prototyping)
+[![website](https://img.shields.io/badge/website-vibeflow.tools-2563eb)](https://www.vibeflow.tools/ui-prototyping.html)
+
+```bash
+npm install @vibeflow-tools/prototyping
+```
+
+---
+
+## Built for Coding Agents
+
+`ui-prototyping` was built to enable coding agents to propose UI variants directly in your running app — without screenshots, back-and-forth prompts, or external design tools.
+
+An agent can define multiple named variants (layouts, colour schemes, component densities) and register them with a few lines of code. You switch between them with a click, see the result immediately in your real app, and tell the agent which one to keep. **No Figma. No mockups. No rebuild cycle.**
+
+This makes `ui-prototyping` one of the most efficient ways for developers to give and receive UI feedback when working with AI coding assistants.
+
+---
+
+## Why It Matters
+
+Designing and reviewing UI variations is slow when you have to change code, rebuild, and refresh every time you want to see a different state. `ui-prototyping` brings the switch directly into your running app:
+
+- **Click to switch** — numbered dot on each component, floating toolbar for all scopes at once
+- **URL-persisted** — share a URL and your reviewer sees the exact variant you're showing them
+- **TypeScript-first** — variant keys are narrowed to their literal types, config objects are fully typed
+- **Zero runtime deps** — peer-deps only (`react`, `react-dom`); nothing extra in your bundle
+- **Vibeflow overlay integration** — when the Vibeflow overlay is detected, the toolbar is accessible via the right-click context menu ("Prototyping" option)
+
+---
+
+## Quick Start
+
+```tsx
+import { VariantProvider, useVariant, PageVariantSwitcher } from '@vibeflow-tools/prototyping'
+
+// 1. Define your variants
+const heroVariants = {
+  default:  {},
+  compact:  { spacing: 'tight', titleSize: 'md' },
+  expanded: { spacing: 'loose', titleSize: 'xl' },
+}
+
+// 2. Read the active variant
+function HeroSection() {
+  const v = useVariant('Hero', heroVariants)
+  return (
+    <section className={v.spacing === 'tight' ? 'py-4' : 'py-12'}>
+      <PageVariantSwitcher name="Hero" variants={heroVariants} />
+      <h1 className={v.titleSize === 'xl' ? 'text-4xl' : 'text-2xl'}>Welcome</h1>
+    </section>
+  )
+}
+
+// 3. Wrap your app
+function App() {
+  return (
+    <VariantProvider>
+      <HeroSection />
+    </VariantProvider>
+  )
+}
+```
+
+---
+
+## Installation
+
+```bash
+npm install @vibeflow-tools/prototyping
+# or
+pnpm add @vibeflow-tools/prototyping
+# or
+yarn add @vibeflow-tools/prototyping
+```
+
+**Requirements:** React 18+, Node.js 18+.
+
+---
+
+## Core API
+
+### `<VariantProvider>`
+
+Wrap your app (or a subtree) with `VariantProvider` to enable the variant switching system. All hooks and switcher components below it share state via this provider.
+
+```tsx
+<VariantProvider>
+  <App />
+</VariantProvider>
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `mode` | `"dev" \| "always"` | `"dev"` | `"dev"` hides switcher UI in production (`NODE_ENV === "production"`). `"always"` always shows it — useful for A/B testing demos. |
+| `defaultVisible` | `boolean` | `true` | Initial UI visibility. Persisted in `localStorage` so users can hide/show across sessions. |
+| `shortcuts` | `KeyboardShortcut[] \| false` | default shortcuts | Custom keyboard shortcuts for toggling the variant UI. Pass `false` to disable. |
+
+---
+
+### `useVariant(name, variants)`
+
+Core hook. Registers the scope, resolves the active variant from URL → localStorage → default, and returns the matching config object.
+
+```tsx
+const variants = {
+  default:  {},
+  compact:  { compact: true, density: 'low' },
+  detailed: { showMeta: true, showComments: true },
+}
+
+function TaskCard() {
+  const v = useVariant('TaskCard', variants)
+  // v is typed as typeof variants[keyof typeof variants]
+  return <div className={v.compact ? 'p-2' : 'p-4'}>…</div>
+}
+```
+
+The first key is always the default variant (applied when no URL param or storage entry is present).
+
+---
+
+### `<VariantSwitcher>`
+
+A subtle indicator dot positioned on the edge of the parent element. Clicking it expands a numbered-dots picker.
+
+```tsx
+function TaskCard() {
+  const v = useVariant('TaskCard', variants)
+  return (
+    <div style={{ position: 'relative' }}>
+      <VariantSwitcher name="TaskCard" variants={variants} />
+      {v.compact ? <CompactView /> : <FullView />}
+    </div>
+  )
+}
+```
+
+**The parent must have `position: relative` for correct placement.**
+
+Deduplicates per scope — only the first `VariantSwitcher` for a given scope renders, even if the component is used multiple times on the page.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | required | Scope name — must match the `useVariant` call |
+| `variants` | `Record<string, object>` | required | Same variant definitions passed to `useVariant` |
+| `position` | `"right" \| "left"` | `"right"` | Which side the dot appears on |
+
+---
+
+### `<PageVariantSwitcher>`
+
+A dark segmented control fixed to the top-left of the viewport — ideal for page-level layout or theme switching.
+
+```tsx
+function DashboardPage() {
+  const layout = useVariant('DashboardLayout', layoutVariants)
+  return (
+    <>
+      <PageVariantSwitcher name="DashboardLayout" variants={layoutVariants} />
+      <main className={layout.sidebar ? 'with-sidebar' : ''}>…</main>
+    </>
+  )
+}
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | required | Scope name — must match the `useVariant` call |
+| `variants` | `Record<string, object>` | required | Same variant definitions passed to `useVariant` |
+
+---
+
+### `<VariantDevToolbar>`
+
+An optional floating toolbar that shows **all registered variant scopes** at once in a single panel. Use this when you have many scopes and want a central control panel.
+
+```tsx
+function App() {
+  return (
+    <VariantProvider>
+      <VariantDevToolbar />  {/* ← add once near the root */}
+      <MainContent />
+    </VariantProvider>
+  )
+}
+```
+
+The toolbar button (vibeflow icon) appears bottom-right of the page. When the Vibeflow overlay is detected, the button is hidden — access the toolbar instead via the overlay's right-click context menu.
+
+**Keyboard shortcuts:**
+- `Alt+H` — toggle all switchers on/off
+- `Ctrl+Shift+V` — toggle all switchers on/off
+- `Escape` — close the toolbar panel
+
+---
+
+### `registerVariant(name, variants)`
+
+Module-level registration. Use this to centralise all variant definitions in one file instead of re-passing them to every component.
+
+```ts
+// variants.ts
+import { registerVariant } from '@vibeflow-tools/prototyping'
+
+registerVariant('TaskCard', {
+  default:  {},
+  minimal:  { compact: true },
+  detailed: { showMeta: true, showComments: true },
+})
+
+registerVariant('KanbanBoard', {
+  default: {},
+  dense:   { rowHeight: 'sm' },
+})
+```
+
+```tsx
+// TaskCard.tsx
+function TaskCard() {
+  // Pass an empty object — registered variants are merged automatically
+  const v = useVariant('TaskCard', {})
+  return <div className={v.compact ? 'p-2' : 'p-4'}>…</div>
+}
+```
+
+Inline variants always win over registered ones when both are provided.
+
+---
+
+## Persistence
+
+Active variants are persisted in two places:
+
+| Layer | Storage | Scope |
+|-------|---------|-------|
+| URL param | `?vf-<name>=<variant>` | Shareable — copy the URL to share a specific variant |
+| localStorage | `vf-<name>` | Session — survives page reloads in the same browser |
+
+URL takes precedence over localStorage.
+
+---
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Alt+H` | Toggle all variant switchers on/off |
+| `Ctrl+Shift+V` | Toggle all variant switchers on/off |
+
+Both shortcuts call `toggleUiVisible()` on the `VariantProvider`. To open the `VariantDevToolbar` panel, click the vibeflow icon button in the bottom-right corner.
+
+Customise or disable shortcuts via the `shortcuts` prop on `VariantProvider`:
+
+```tsx
+// Custom shortcuts
+<VariantProvider shortcuts={[{ key: 'v', alt: true }]}>
+  <App />
+</VariantProvider>
+
+// Disable all shortcuts
+<VariantProvider shortcuts={false}>
+  <App />
+</VariantProvider>
+```
+
+---
+
+## Vibeflow Overlay Integration
+
+When the [Vibeflow](https://vibeflow.tools) overlay is injected into the page, `VariantDevToolbar` automatically hides its standalone vibeflow icon button and registers itself with the overlay. The toolbar is then accessible via the overlay's right-click context menu under **"Prototyping"** — both on the bottom-right trigger and when right-clicking any element on the page.
+
+No configuration needed — detection is automatic.
+
+> **Tip for AI coding agents:** Combine `ui-prototyping` with the [Vibeflow overlay](https://vibeflow.tools) so variants are instantly accessible via right-click anywhere on the page. The agent defines the variants; you switch and approve. See the [ui-prototyping webpage](https://www.vibeflow.tools/ui-prototyping.html) for a live demo.
+
+---
+
+## Advanced: Power User Utilities
+
+The following URL/localStorage utilities are exported for cases where you need manual control:
+
+```ts
+import {
+  readVariantFromUrl,
+  writeVariantToUrl,
+  removeVariantFromUrl,
+  readVariantFromStorage,
+  writeVariantToStorage,
+  removeVariantFromStorage,
+  resolveActiveVariant,
+  readUiVisibleFromStorage,
+  writeUiVisibleToStorage,
+} from '@vibeflow-tools/prototyping'
+```
+
+---
+
+## TypeScript
+
+All exports are fully typed. The `useVariant` hook preserves key-literal types so your IDE autocompletes variant config properties:
+
+```tsx
+const variants = {
+  default: {},
+  compact: { compact: true as const, rows: 3 as const },
+}
+
+function MyComponent() {
+  const v = useVariant('MyComponent', variants)
+  // v.compact is typed as `true | undefined`
+  // v.rows is typed as `3 | undefined`
+}
+```
+
+---
+
+## Contributing
+
+```bash
+pnpm install
+pnpm --filter @vibeflow-tools/prototyping run build
+pnpm --filter @vibeflow-tools/prototyping run test
+pnpm --filter @vibeflow-tools/prototyping run test:coverage
+```
+
+---
+
+## License
+
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) — see [NOTICE](https://github.com/zorcec/vibeflow/blob/main/NOTICE) for third-party attributions.

package/dist/index.d.ts

@@ -0,0 +1,292 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/** Default keyboard shortcuts for toggling the variant UI. */
+interface KeyboardShortcut {
+    /** The key value (e.g. "h", "V"). Case-sensitive for Ctrl+Shift combos. */
+    key: string;
+    /** Whether Alt must be held. */
+    alt?: boolean;
+    /** Whether Ctrl must be held. */
+    ctrl?: boolean;
+    /** Whether Shift must be held. */
+    shift?: boolean;
+    /** Whether Meta (Cmd/Win) must be held. */
+    meta?: boolean;
+}
+interface KeyboardShortcutsOptions {
+    /** Called when a toggle shortcut is pressed. */
+    onToggleUi: () => void;
+    /**
+     * Custom shortcut definitions. Defaults to [Alt+H, Ctrl+Shift+V].
+     * Set to `false` to disable all keyboard shortcuts.
+     */
+    shortcuts?: KeyboardShortcut[] | false;
+}
+/**
+ * Registers global keyboard shortcuts for the prototyping system.
+ *
+ * | Default Shortcut | Action               |
+ * |------------------|----------------------|
+ * | Alt + H          | Toggle all switchers |
+ * | Ctrl+Shift+V     | Toggle all switchers |
+ *
+ * Shortcuts can be customized via the `shortcuts` option, or disabled
+ * entirely by passing `false`.
+ */
+declare function useKeyboardShortcuts({ onToggleUi, shortcuts, }: KeyboardShortcutsOptions): void;
+
+/**
+ * Core TypeScript types for @vibeflow-tools/prototyping.
+ *
+ * VariantDefinitions maps variant names to arbitrary config objects.
+ * The generic V type preserves key-literal types for TypeScript consumers.
+ */
+
+/** A map of variant name → arbitrary config object. */
+type VariantDefinitions<V extends Record<string, Record<string, unknown>>> = V;
+/** The mode controls when variant switcher UI is visible. */
+type VariantMode = "dev" | "always";
+/** Internal state stored per named scope. */
+interface VariantState {
+    /** Currently active variant name. */
+    activeVariant: string;
+    /** All registered variant names for this scope. */
+    variantNames: string[];
+}
+/** The shape of the context value exposed by VariantProvider. */
+interface VariantContextValue {
+    /** Get the active variant name for a given scope. */
+    getActiveVariant: (name: string) => string;
+    /** Set the active variant for a scope. */
+    setActiveVariant: (name: string, variant: string) => void;
+    /** Register a scope with its variant names (called by useVariant / VariantSwitcher). */
+    registerScope: (name: string, variantNames: string[]) => void;
+    /**
+     * Register a VariantSwitcher instance for a scope.
+     * Returns true if this is the first instance (should render), false if duplicate (should skip).
+     */
+    registerSwitcher: (name: string) => boolean;
+    /** Unregister a VariantSwitcher instance (called on unmount). */
+    unregisterSwitcher: (name: string) => void;
+    /** All registered scopes and their states. */
+    scopes: Record<string, VariantState>;
+    /** Whether switcher UI should be visible. */
+    uiVisible: boolean;
+    /** Toggle switcher UI visibility. */
+    toggleUiVisible: () => void;
+    /** The current mode ("dev" | "always"). */
+    mode: VariantMode;
+}
+/** Props for VariantProvider. */
+interface VariantProviderProps {
+    children: React.ReactNode;
+    /**
+     * "dev" (default) — switcher UI is hidden unless NODE_ENV !== "production".
+     * "always" — switcher UI is always visible (useful for A/B testing / user-facing demos).
+     */
+    mode?: VariantMode;
+    /**
+     * Initial UI visibility state.
+     * Defaults to true when mode allows it.
+     */
+    defaultVisible?: boolean;
+    /**
+     * Custom keyboard shortcuts for toggling the variant UI.
+     * Defaults to [Alt+H, Ctrl+Shift+V]. Pass `false` to disable shortcuts.
+     */
+    shortcuts?: KeyboardShortcut[] | false;
+}
+/** Props shared by switcher components. */
+interface SwitcherProps {
+    /** Scope name — must match the first argument of useVariant. */
+    name: string;
+    /** Variant definitions object — same as passed to useVariant. */
+    variants: Record<string, Record<string, unknown>>;
+    /** Preferred side for floating placement. Default: "right". */
+    position?: "right" | "left";
+}
+
+declare const VariantContext: react.Context<VariantContextValue | null>;
+/** Access the variant context. Throws if used outside VariantProvider. */
+declare function useVariantContext(): VariantContextValue;
+/**
+ * VariantProvider wraps your app (or a subtree) and provides the variant
+ * switching system. All useVariant hooks and switcher components below it
+ * share state via this provider.
+ *
+ * @example
+ * <VariantProvider>
+ *   <App />
+ * </VariantProvider>
+ *
+ * @example
+ * // Always visible — for A/B testing or user-facing demos
+ * <VariantProvider mode="always">
+ *   <App />
+ * </VariantProvider>
+ */
+declare function VariantProvider({ children, mode, defaultVisible, shortcuts, }: VariantProviderProps): ReactNode;
+
+/**
+ * Core hook for reading the active variant config.
+ *
+ * Registers the scope with the VariantProvider, resolves the active variant
+ * from URL → localStorage → default, and returns the corresponding config.
+ *
+ * @param name  - Unique scope name (e.g. "TaskCard", "KanbanBoard")
+ * @param variants - Variant definitions object; first key is the default
+ * @returns The config object for the active variant
+ *
+ * @example
+ * const variants = {
+ *   default: {},
+ *   minimal: { compact: true },
+ *   detailed: { showMeta: true, showComments: true },
+ * }
+ *
+ * function TaskCard() {
+ *   const variant = useVariant('TaskCard', variants)
+ *   return <div className={variant.compact ? 'compact' : ''}>…</div>
+ * }
+ */
+declare function useVariant<V extends Record<string, Record<string, unknown>>>(name: string, variants: V): V[keyof V];
+
+/**
+ * Resolves the active variant key for a scope.
+ *
+ * Checks context first, then falls back to URL → localStorage → default.
+ * Used by useVariant, VariantSwitcher, and PageVariantSwitcher to avoid
+ * duplicating the same resolution logic.
+ */
+declare function useActiveVariant(name: string, variantKeys: string[]): string;
+
+interface PageVariantSwitcherProps {
+    /** Scope name — must match the first argument of useVariant. */
+    name: string;
+    /** Variant definitions — same as passed to useVariant. */
+    variants: Record<string, Record<string, unknown>>;
+}
+/**
+ * Dark segmented bar floating top-left of the page.
+ * Renders automatically via VariantProvider for page-level variant switching.
+ *
+ * Place this component anywhere inside VariantProvider — typically at the
+ * top of the page component alongside useVariant.
+ *
+ * @example
+ * function App() {
+ *   const layout = useVariant('Layout', layoutVariants)
+ *   return (
+ *     <>
+ *       <PageVariantSwitcher name="Layout" variants={layoutVariants} />
+ *       <main>…</main>
+ *     </>
+ *   )
+ * }
+ */
+declare function PageVariantSwitcher({ name, variants, }: PageVariantSwitcherProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Component variant switcher with a subtle indicator dot.
+ *
+ * Shows a small, non-intrusive dot on the right (or left) side of the parent.
+ * Clicking the dot expands the full numbered-dots picker.
+ * Clicking outside or pressing Escape collapses it back.
+ *
+ * The dot is draggable — hold for 300ms, then drag to reposition anywhere on
+ * the viewport. The new position is persisted to localStorage per scope name.
+ *
+ * Deduplicates per scope — only the first VariantSwitcher for a given
+ * scope renders. Multiple components using the same scope share one switcher.
+ *
+ * The parent element must have `position: relative` for correct placement.
+ *
+ * @example
+ * function TaskCard({ task }) {
+ *   const variant = useVariant('TaskCard', taskCardVariants)
+ *   return (
+ *     <div style={{ position: 'relative' }}>
+ *       <VariantSwitcher name="TaskCard" variants={taskCardVariants} />
+ *       {variant.compact ? <CompactView /> : <FullView />}
+ *     </div>
+ *   )
+ * }
+ */
+declare function VariantSwitcher({ name, variants, position, }: SwitcherProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Optional floating toolbar that shows all registered variant scopes.
+ * Toggled via Ctrl+Shift+V keyboard shortcut or programmatically.
+ *
+ * **Vibeflow overlay integration:** When the Vibeflow overlay is detected,
+ * the standalone vibeflow icon button is hidden. Instead, the toolbar is accessible
+ * via the overlay's right-click context menu ("Prototyping" option).
+ *
+ * Place this once near the root of your app inside VariantProvider.
+ *
+ * @example
+ * function App() {
+ *   return (
+ *     <VariantProvider>
+ *       <VariantDevToolbar />
+ *       <MainContent />
+ *     </VariantProvider>
+ *   )
+ * }
+ */
+declare function VariantDevToolbar(): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Global variant registry.
+ *
+ * Optional module-level registration of variant definitions so they don't
+ * have to be re-passed to every useVariant call in deeply nested trees.
+ * Registered variants are merged with inline variant definitions — inline
+ * always wins.
+ */
+type VariantDefs = Record<string, Record<string, unknown>>;
+/**
+ * Register a variant definition at module level.
+ * Useful when you want to centralise all variant registrations in one file.
+ *
+ * @example
+ * registerVariant('TaskCard', {
+ *   default: {},
+ *   minimal: { compact: true },
+ *   detailed: { showMeta: true },
+ * })
+ */
+declare function registerVariant(name: string, variants: VariantDefs): void;
+/**
+ * Retrieve previously registered variant definitions for a scope.
+ * Returns undefined if the scope was never registered.
+ */
+declare function getRegisteredVariant(name: string): VariantDefs | undefined;
+/** Clear all registrations. Primarily used in tests. */
+declare function clearVariantRegistry(): void;
+
+/** Read the active variant for a scope from the current URL search params. */
+declare function readVariantFromUrl(name: string): string | null;
+/** Write the active variant for a scope into the URL (pushState — no reload). */
+declare function writeVariantToUrl(name: string, variant: string): void;
+/** Remove a scope's variant from the URL. */
+declare function removeVariantFromUrl(name: string): void;
+/** Read the active variant for a scope from localStorage. */
+declare function readVariantFromStorage(name: string): string | null;
+/** Write the active variant for a scope to localStorage. */
+declare function writeVariantToStorage(name: string, variant: string): void;
+/** Remove a scope's variant from localStorage. */
+declare function removeVariantFromStorage(name: string): void;
+/** Persist the UI visibility flag. */
+declare function writeUiVisibleToStorage(visible: boolean): void;
+/** Read the persisted UI visibility flag. Returns null when not set. */
+declare function readUiVisibleFromStorage(): boolean | null;
+/**
+ * Resolve the active variant for a scope.
+ * Priority: URL param → localStorage → provided default key.
+ */
+declare function resolveActiveVariant(name: string, variantKeys: string[], defaultKey: string): string;
+
+export { type KeyboardShortcut, PageVariantSwitcher, type SwitcherProps, VariantContext, type VariantContextValue, type VariantDefinitions, VariantDevToolbar, type VariantMode, VariantProvider, type VariantProviderProps, type VariantState, VariantSwitcher, clearVariantRegistry, getRegisteredVariant, readUiVisibleFromStorage, readVariantFromStorage, readVariantFromUrl, registerVariant, removeVariantFromStorage, removeVariantFromUrl, resolveActiveVariant, useActiveVariant, useKeyboardShortcuts, useVariant, useVariantContext, writeUiVisibleToStorage, writeVariantToStorage, writeVariantToUrl };