@chrisflippen/blueprint-document-assembly 3.0.0 → 3.0.1

package/README.md

@@ -1,49 +1,33 @@
 # Blueprint Document Assembly
 
-An animation-heavy React component for visualizing multi-step processes as a Blueprint/Technical Document Assembly system. Perfect for legal document generation, compliance workflows, technical process visualization, and any multi-step assembly process.
+An animation-heavy React component library for visualizing multi-step processes as a Blueprint/Technical Document Assembly system. Features progressive document construction, streaming logs, cinematic completion effects, theming, animation presets, and accessibility support.
 
-![Version](https://img.shields.io/npm/v/blueprint-document-assembly.svg)
-![License](https://img.shields.io/npm/l/blueprint-document-assembly.svg)
+![Version](https://img.shields.io/npm/v/@chrisflippen/blueprint-document-assembly.svg)
+![License](https://img.shields.io/npm/l/@chrisflippen/blueprint-document-assembly.svg)
 
-## ✨ Features
+## Features
 
-- **🎬 Cinematic Animations**: Smooth, professional animations powered by Motion (Framer Motion)
-- **📝 Progressive Document Assembly**: Watch documents build piece-by-piece as steps complete
-- **📊 Real-time Metrics**: Track tokens, costs, and elapsed time
-- **🔄 Sequential Log Streaming**: Logs stream in order, following the step progression
-- **📱 Responsive Design**: Works beautifully on desktop and mobile
-- **🌗 Dark Mode Support**: Respects system theme preferences
-- **✨ Celebration Effects**: Dramatic zoom-out and sparkle effects on completion
-- **🎯 TypeScript Support**: Fully typed for excellent developer experience
-- **🎨 Customizable**: Extensive props for customization
+- **Cinematic Animations** — Smooth, professional animations powered by Motion (Framer Motion) with 4 built-in presets
+- **Progressive Document Assembly** — Watch documents build piece-by-piece as steps complete with typewriter effects
+- **ThemeProvider** — Full React Context theming; change all colors by passing a single config
+- **Animation Presets** — Smooth, Snappy, Cinematic, and Minimal presets with configurable timings
+- **Accessibility** — `prefers-reduced-motion` support, ARIA roles (`progressbar`, `log`, `listitem`), `aria-live` regions
+- **Mobile Responsive** — Automatic vertical stacking on small screens via `useResponsiveLayout`
+- **Headless Hook** — `useDocumentAssembly()` for full control without any UI
+- **Generic Presets** — Squiggle text presets (`~~~~~ ~~~ ~~~~~~~`) for non-domain-specific demos
+- **Real-time Metrics** — Track tokens, costs, and elapsed time
+- **Dark Mode** — Respects system theme preferences
+- **TypeScript** — Fully typed with exported interfaces
 
-## 📦 Installation
+## Installation
 
 ```bash
-npm install blueprint-document-assembly motion lucide-react
+npm install @chrisflippen/blueprint-document-assembly motion lucide-react
 ```
 
-Or with yarn:
+## Styling Requirements
 
-```bash
-yarn add blueprint-document-assembly motion lucide-react
-```
-
-Or with pnpm:
-
-```bash
-pnpm add blueprint-document-assembly motion lucide-react
-```
-
-## 🎨 Styling Requirements
-
-This component requires **Tailwind CSS v4**. Make sure you have Tailwind CSS installed and configured:
-
-```bash
-npm install tailwindcss @tailwindcss/vite
-```
-
-Your Tailwind CSS theme should include these CSS variables for optimal styling:
+This component requires **Tailwind CSS v4**. Your theme should include these CSS variables:
 
 ```css
 @theme {
@@ -52,7 +36,6 @@ Your Tailwind CSS theme should include these CSS variables for optimal styling:
   --color-muted: #f4f4f5;
   --color-muted-foreground: #71717a;
   --color-border: #e4e4e7;
-  /* Add more theme variables as needed */
 }
 
 @media (prefers-color-scheme: dark) {
@@ -66,215 +49,333 @@ Your Tailwind CSS theme should include these CSS variables for optimal styling:
 }
 ```
 
-## 🚀 Quick Start
+### Tailwind Safelist (required when using ThemeProvider)
+
+Dynamic theme colors generate Tailwind classes at runtime. Add them to your safelist:
+
+```ts
+import { getThemeSafelist } from '@chrisflippen/blueprint-document-assembly';
+
+// In your Tailwind config
+safelist: getThemeSafelist({ primary: 'blue', success: 'green' })
+```
+
+## Quick Start
 
 ```tsx
-import { BlueprintDocumentAssembly } from 'blueprint-document-assembly';
+import { BlueprintDocumentAssembly } from '@chrisflippen/blueprint-document-assembly';
 
 function App() {
   return <BlueprintDocumentAssembly />;
 }
 ```
 
-That's it! The component comes with sensible defaults for a sworn affidavit assembly process.
+Zero-config renders a sworn affidavit assembly with default steps, logs, and document sections.
 
-## 📖 Usage Examples
+## Usage Examples
 
-### Basic Usage with Callbacks
+### Callbacks
 
 ```tsx
-import { BlueprintDocumentAssembly } from 'blueprint-document-assembly';
-import type { DocumentMetrics, Step } from 'blueprint-document-assembly';
+import { BlueprintDocumentAssembly } from '@chrisflippen/blueprint-document-assembly';
+import type { DocumentMetrics, Step } from '@chrisflippen/blueprint-document-assembly';
 
 function App() {
-  const handleComplete = (metrics: DocumentMetrics) => {
-    console.log('Assembly complete!', metrics);
-    // { tokens: 2847, cost: 0.0234, elapsed: 14.2 }
-  };
-
-  const handleStepComplete = (step: Step, metrics: DocumentMetrics) => {
-    console.log(`Step ${step.number} completed:`, step.title);
-  };
-
   return (
     <BlueprintDocumentAssembly
-      onComplete={handleComplete}
-      onStepComplete={handleStepComplete}
+      onComplete={(metrics: DocumentMetrics) => console.log('Done!', metrics)}
+      onStepComplete={(step: Step) => console.log(`Step ${step.number} done`)}
     />
   );
 }
 ```
 
-### Custom Animation Speed
+### ThemeProvider — Custom Colors
+
+Pass a `theme` prop to recolor all components. Colors map to Tailwind color names.
 
 ```tsx
 <BlueprintDocumentAssembly
-  animationSpeed={2} // 2x faster
+  theme={{ primary: 'blue', success: 'green', processing: 'indigo' }}
 />
+```
 
-<BlueprintDocumentAssembly
-  animationSpeed={0.5} // 2x slower
-/>
+Under the hood this wraps the component tree in a `<ThemeProvider>` that resolves color names into Tailwind class strings. Components read from context via `useThemeOptional()` and fall back to hardcoded styles when no provider is present.
+
+You can also use the provider directly for sub-components:
+
+```tsx
+import { ThemeProvider, useTheme, resolveTheme } from '@chrisflippen/blueprint-document-assembly';
+
+function CustomUI() {
+  const theme = useTheme(); // throws if no provider
+  return <div className={theme.primary.bg}>Themed content</div>;
+}
 ```
 
-### Disable Whole Document View
+### Animation Presets
+
+Four built-in presets control all animation timings, springs, stagger delays, and typewriter speeds:
 
 ```tsx
-<BlueprintDocumentAssembly
-  showWholeDocumentView={false} // Skip the zoom-out finale
-/>
+import {
+  BlueprintDocumentAssembly,
+  SMOOTH_PRESET,   // Default — balanced
+  SNAPPY_PRESET,   // Fast, responsive
+  CINEMATIC_PRESET, // Slow, dramatic
+  MINIMAL_PRESET,  // Near-instant (used automatically for reduced motion)
+} from '@chrisflippen/blueprint-document-assembly';
+
+<BlueprintDocumentAssembly animationPreset={SNAPPY_PRESET} />
 ```
 
-### Custom Document IDs
+You can also override individual timings without a full preset:
 
 ```tsx
 <BlueprintDocumentAssembly
-  documentIds={{
-    caseNumber: '2026-CV-1234',
-    fileNumber: 'LAW-456'
+  animationTimings={{
+    stepActivation: 400,
+    substepDelay: 250,
+    typewriterSpeed: 15,
   }}
 />
 ```
 
-### Custom Steps
+### Squiggle Text Presets
+
+Generic document presets using tilde characters instead of real content — useful for demos, portfolios, and non-legal use cases:
 
 ```tsx
-import type { Step } from 'blueprint-document-assembly';
-
-const customSteps: Step[] = [
-  {
-    id: 'init',
-    number: 1,
-    title: 'System Initialization',
-    status: 'pending',
-    substeps: [
-      { id: 'init1', label: 'Load configuration', completed: false, logs: [] },
-      { id: 'init2', label: 'Connect to database', completed: false, logs: [] }
-    ],
-    documentSection: 'header',
-    logs: []
-  },
-  // ... more steps
-];
-
-<BlueprintDocumentAssembly steps={customSteps} />
+import {
+  BlueprintDocumentAssembly,
+  SQUIGGLE_STEPS,
+  SQUIGGLE_STEP_LOGS,
+  SQUIGGLE_SUBSTEP_LOGS,
+  SQUIGGLE_DOCUMENT_SECTIONS,
+} from '@chrisflippen/blueprint-document-assembly';
+
+<BlueprintDocumentAssembly
+  steps={SQUIGGLE_STEPS}
+  stepLogs={SQUIGGLE_STEP_LOGS}
+  substepLogs={SQUIGGLE_SUBSTEP_LOGS}
+  documentSections={SQUIGGLE_DOCUMENT_SECTIONS}
+/>
 ```
 
-## 📚 API Reference
+Squiggle presets use the same section IDs and substep triggers as the legal preset, so they're a drop-in replacement.
 
-### Props
+### Headless Hook
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `steps` | `Step[]` | Default affidavit steps | Array of steps to process |
-| `stepLogs` | `Record<string, string[][]>` | Default logs | Custom log data for each step |
-| `substepLogs` | `Record<string, string[][]>` | Default logs | Custom log data for each substep |
-| `autoScroll` | `boolean` | `true` | Auto-scroll to show new content |
-| `showWholeDocumentView` | `boolean` | `true` | Show zoom-out view on completion |
-| `documentIds` | `DocumentIds` | Auto-generated | Custom case/file numbers |
-| `animationSpeed` | `number` | `1` | Animation speed multiplier |
-| `onComplete` | `(metrics: DocumentMetrics) => void` | - | Callback when complete |
-| `onStepComplete` | `(step: Step, metrics: DocumentMetrics) => void` | - | Callback when step completes |
-| `className` | `string` | - | Custom className for root |
-
-### Types
-
-```typescript
-interface Step {
-  id: string;
-  number: number;
-  title: string;
-  status: 'pending' | 'active' | 'processing' | 'completed';
-  substeps?: SubStep[];
-  documentSection?: string;
-  logs: LogEntry[];
-}
+Use `useDocumentAssembly()` for full programmatic control without the built-in UI:
 
-interface SubStep {
-  id: string;
-  label: string;
-  completed: boolean;
-  logs: LogEntry[];
-}
+```tsx
+import { useDocumentAssembly } from '@chrisflippen/blueprint-document-assembly';
+
+function CustomAssembly() {
+  const {
+    steps, progress, isRunning, isComplete, metrics,
+    completedSubsteps, completedSections,
+    start, pause, resume, reset, goToStep,
+  } = useDocumentAssembly({
+    autoStart: false,
+    animationTimings: { stepActivation: 500 },
+    onComplete: (m) => console.log('Done', m),
+  });
 
-interface LogEntry {
-  id: string;
-  timestamp: string;
-  level: 'info' | 'success' | 'warning' | 'processing';
-  message: string;
+  return (
+    <div>
+      <p>Progress: {progress}%</p>
+      <button onClick={start}>Start</button>
+      <button onClick={pause}>Pause</button>
+      <button onClick={resume}>Resume</button>
+      <button onClick={reset}>Reset</button>
+    </div>
+  );
 }
+```
 
-interface DocumentMetrics {
-  tokens: number;
-  cost: number;
-  elapsed: number;
-}
+### Imperative Control via Ref
 
-interface DocumentIds {
-  caseNumber: string;
-  fileNumber: string;
+```tsx
+import { useRef } from 'react';
+import { BlueprintDocumentAssembly } from '@chrisflippen/blueprint-document-assembly';
+import type { BlueprintDocumentAssemblyRef } from '@chrisflippen/blueprint-document-assembly';
+
+function App() {
+  const ref = useRef<BlueprintDocumentAssemblyRef>(null);
+
+  return (
+    <>
+      <BlueprintDocumentAssembly ref={ref} autoStart={false} />
+      <button onClick={() => ref.current?.start()}>Start</button>
+      <button onClick={() => ref.current?.pause()}>Pause</button>
+    </>
+  );
 }
 ```
 
-## 🎯 Use Cases
+## Accessibility
 
-- **Legal Document Generation**: Sworn affidavits, contracts, legal filings
-- **Compliance Workflows**: Multi-step verification and approval processes
-- **Technical Documentation**: System build processes, deployment pipelines
-- **Manufacturing**: Assembly line visualization
-- **Medical**: Patient intake and verification processes
-- **Financial**: Loan application processing, KYC workflows
+### Reduced Motion
 
-## 🎨 Customization
+The library automatically detects `prefers-reduced-motion: reduce` and:
+- Skips typewriter animations (shows full text immediately)
+- Disables sparkle/celebration effects
+- Uses `MINIMAL_PRESET` timings (near-instant transitions)
+- Removes entrance slide/scale animations
 
-The component uses Tailwind CSS and can be customized through:
+When using `AnimationProvider`, reduced motion detection is automatic:
 
-1. **Tailwind Theme**: Customize colors through CSS variables
-2. **Custom Steps**: Provide your own step configuration
-3. **Custom Logs**: Provide custom log messages for each step/substep
-4. **Props**: Use the extensive props API for behavior customization
+```tsx
+import { AnimationProvider, useAnimation } from '@chrisflippen/blueprint-document-assembly';
 
-## 🏗️ Architecture
+function MyComponent() {
+  const { reducedMotion, preset } = useAnimation();
+  // reducedMotion === true when user prefers reduced motion
+}
+```
+
+You can also use the hook standalone:
 
-The component follows a clean, modular architecture:
+```tsx
+import { useReducedMotion } from '@chrisflippen/blueprint-document-assembly';
 
+const prefersReduced = useReducedMotion(); // boolean
 ```
-blueprint-document-assembly/
-├── src/
-│   ├── components/
-│   │   ├── BlueprintDocumentAssembly.tsx   # Main component
-│   │   ├── StepItem.tsx                    # Step visualization
-│   │   ├── SubStepItem.tsx                 # Substep visualization
-│   │   ├── DocumentPreview.tsx             # Document builder
-│   │   ├── WholeDocumentView.tsx           # Completion overlay
-│   │   ├── WholeDocumentContent.tsx        # Static document
-│   │   └── LogComponents.tsx               # Log display
-│   ├── types.ts                            # TypeScript definitions
-│   ├── constants.ts                        # Default log data
-│   ├── default-steps.ts                    # Default step config
-│   └── index.tsx                           # Public exports
+
+### ARIA Attributes
+
+- Progress bar: `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
+- Log containers: `role="log"` with `aria-live="polite"`
+- Log toggles: `aria-expanded` and `aria-label`
+- Substep lists: `role="list"` and `role="listitem"`
+- Root container: `aria-label="Document assembly"`
+
+## Mobile Responsive
+
+On screens narrower than 768px, the layout automatically switches from horizontal (side-by-side) to vertical (stacked). Use the hook directly:
+
+```tsx
+import { useResponsiveLayout } from '@chrisflippen/blueprint-document-assembly';
+
+const { isMobile, isTablet, direction } = useResponsiveLayout();
+// direction: 'vertical' on mobile, 'horizontal' on desktop
 ```
 
-## 🤝 Contributing
+Or override via the `layout` prop:
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+```tsx
+<BlueprintDocumentAssembly layout={{ direction: 'vertical' }} />
+```
 
-## 📄 License
+## API Reference
 
-MIT © [Your Name]
+### BlueprintDocumentAssembly Props
 
-## 🙏 Acknowledgments
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `steps` | `Step[]` | Default affidavit steps | Steps to process |
+| `stepLogs` | `Record<string, string[][]>` | Default logs | Log data per step |
+| `substepLogs` | `Record<string, string[][]>` | Default logs | Log data per substep |
+| `documentSections` | `DocumentSection[]` | Legal preset | Document content sections |
+| `autoStart` | `boolean` | `true` | Start assembly on mount |
+| `autoScroll` | `boolean` | `true` | Auto-scroll document |
+| `showWholeDocumentView` | `boolean` | `true` | Show completion overlay |
+| `documentIds` | `DocumentIds` | Auto-generated | Custom case/file numbers |
+| `animationSpeed` | `number` | `1` | Speed multiplier |
+| `animationPreset` | `AnimationPreset` | - | Animation preset (SMOOTH, SNAPPY, etc.) |
+| `animationTimings` | `AnimationTimings` | - | Override individual timing values |
+| `theme` | `ThemeConfig` | - | Theme color config |
+| `classNames` | `ClassNameSlots` | - | CSS class overrides for internal slots |
+| `labels` | `LabelConfig` | - | UI string overrides |
+| `layout` | `LayoutConfig` | - | Layout direction and panel widths |
+| `className` | `string` | - | Root container className |
+| `renderStep` | `(step, default) => ReactNode` | - | Custom step renderer |
+| `renderSubstep` | `(substep, default) => ReactNode` | - | Custom substep renderer |
+| `renderLog` | `(log, default) => ReactNode` | - | Custom log renderer |
+| `renderDocumentSection` | `(section, substeps) => ReactNode` | - | Custom section renderer |
+| `onComplete` | `(metrics) => void` | - | Assembly complete callback |
+| `onStepStart` | `(step, index) => void` | - | Step started callback |
+| `onStepComplete` | `(step, metrics) => void` | - | Step complete callback |
+| `onSubstepComplete` | `(substepId, stepIndex) => void` | - | Substep complete callback |
+| `onSectionReveal` | `(sectionId) => void` | - | Section revealed callback |
+| `onLogEntry` | `(log) => void` | - | Log entry added callback |
+| `onPause` | `() => void` | - | Paused callback |
+| `onResume` | `() => void` | - | Resumed callback |
+| `onReset` | `() => void` | - | Reset callback |
+
+### Exports
+
+**Components:**
+`BlueprintDocumentAssembly`, `StepItem`, `SubStepItem`, `LogLine`, `LogContainer`, `DocumentPreview`, `DocumentLine`, `WholeDocumentView`, `WholeDocumentContent`
+
+**Theme:**
+`ThemeProvider`, `useTheme`, `useThemeOptional`, `resolveTheme`, `getThemeSafelist`
+
+**Animation:**
+`AnimationProvider`, `useAnimation`, `useAnimationOptional`, `SMOOTH_PRESET`, `SNAPPY_PRESET`, `CINEMATIC_PRESET`, `MINIMAL_PRESET`
+
+**Hooks:**
+`useDocumentAssembly`, `useReducedMotion`, `useResponsiveLayout`
+
+**Presets:**
+`LEGAL_DOCUMENT_SECTIONS`, `LEGAL_WHOLE_DOCUMENT_SECTIONS`, `SQUIGGLE_DOCUMENT_SECTIONS`, `SQUIGGLE_WHOLE_DOCUMENT_SECTIONS`, `SQUIGGLE_STEPS`, `SQUIGGLE_STEP_LOGS`, `SQUIGGLE_SUBSTEP_LOGS`
+
+**Constants:**
+`DEFAULT_STEPS`, `DEFAULT_STEP_LOGS`, `DEFAULT_SUBSTEP_LOGS`, `DEFAULT_LABELS`, `DEFAULT_THEME`, `STEP_ICON_MAP`
+
+**Factories:**
+`createStep`, `createSubStep`, `createDocumentSection`, `resetStepCounter`
+
+**Types:**
+`Step`, `SubStep`, `LogEntry`, `DocumentMetrics`, `DocumentIds`, `DocumentSection`, `DocumentSubsection`, `ClassNameSlots`, `ThemeConfig`, `AnimationTimings`, `AnimationPreset`, `ResolvedTheme`, `ResolvedThemeColors`, `LabelConfig`, `LayoutConfig`, `UseDocumentAssemblyOptions`, `UseDocumentAssemblyReturn`, `BlueprintDocumentAssemblyRef`, `BlueprintDocumentAssemblyProps`, and all component prop types
+
+## Architecture
 
-- Built with [Motion](https://motion.dev/) (Framer Motion)
-- Icons by [Lucide](https://lucide.dev/)
-- Styled with [Tailwind CSS](https://tailwindcss.com/)
+```
+src/
+├── components/
+│   ├── BlueprintDocumentAssembly.tsx   # Main component (providers, responsive, ARIA)
+│   ├── StepItem.tsx                    # Step card with theme context
+│   ├── SubStepItem.tsx                 # Substep with ARIA listitem
+│   ├── LogComponents.tsx               # Log display with ARIA log role
+│   ├── DocumentPreview.tsx             # Progressive document builder
+│   ├── DocumentLine.tsx                # Typewriter text (reduced motion aware)
+│   ├── WholeDocumentView.tsx           # Completion overlay (GPU-safe glow)
+│   └── WholeDocumentContent.tsx        # Static document renderer
+├── theme/
+│   ├── ThemeContext.tsx                # ThemeProvider, resolveTheme, safelist
+│   └── index.ts
+├── animation/
+│   ├── presets.ts                     # SMOOTH, SNAPPY, CINEMATIC, MINIMAL
+│   ├── AnimationContext.tsx            # AnimationProvider, useAnimation
+│   └── index.ts
+├── hooks/
+│   ├── useDocumentAssembly.ts         # Headless assembly hook
+│   ├── useReducedMotion.ts            # prefers-reduced-motion detection
+│   ├── useResponsiveLayout.ts         # Breakpoint detection
+│   └── index.ts
+├── presets/
+│   ├── legal-document-sections.ts     # Sworn affidavit sections
+│   ├── legal-whole-document.ts        # Legal completion view
+│   ├── squiggle-document-sections.ts  # Generic squiggle text sections
+│   ├── squiggle-steps.ts             # Generic steps + logs
+│   └── index.ts
+├── constants/
+│   ├── default-labels.ts
+│   └── default-theme.ts
+├── types.ts
+├── constants.ts
+├── default-steps.ts
+└── index.tsx                          # Public API
+```
 
-## 📞 Support
+## License
 
-- 📫 Issues: [GitHub Issues](https://github.com/yourusername/blueprint-document-assembly/issues)
-- 💬 Discussions: [GitHub Discussions](https://github.com/yourusername/blueprint-document-assembly/discussions)
-- 📧 Email: your.email@example.com
+MIT
 
----
+## Acknowledgments
 
-Made with ❤️ by [Your Name]
+- Built with [Motion](https://motion.dev/) (Framer Motion)
+- Icons by [Lucide](https://lucide.dev/)
+- Styled with [Tailwind CSS](https://tailwindcss.com/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrisflippen/blueprint-document-assembly",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "An animation-heavy React component for visualizing multi-step processes as a Blueprint/Technical Document Assembly system with streaming logs, progressive document construction, and cinematic completion effects",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",