elan-ui 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to **Elan (`elan-ui`)** are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] - 2026-10-24
+
+### 🚀 Initial Public Release Candidate
+
+#### Added
+- **Core Motion & Physics Engine**:
+  - Priority queue requestAnimationFrame ticker with deterministic DOM read/write batching.
+  - Analytical damped spring physics engine with 6 presets (`default`, `gentle`, `wobbly`, `stiff`, `slow`, `molasses`).
+  - Cubic Bezier solver with all standard CSS easing curves and custom 4-point curves.
+  - Pooled `IntersectionObserver` and `ResizeObserver` tracking with automatic disconnect.
+  - Multi-theme token engine supporting `dark`, `light`, `minimal`, `neon`, `glass`, and `brutalist` themes with OS `prefers-color-scheme` synchronization.
+- **Scroll Journey & Scrubber**:
+  - Declarative scroll reveal directives (`data-reveal="up|down|left|right|fade|zoom|blur"`).
+  - Multi-chapter storytelling scroll journeys (`data-journey`) with progress indicators.
+  - Section pin-spacers and synchronized scrub animations (`data-pin`, `data-scrub`).
+  - Native CSS Scroll-Driven Animations engine (`@supports (animation-timeline: scroll())`) with automated requestAnimationFrame fallback.
+- **Accessible UI Components**:
+  - WAI-ARIA compliant Modal Dialog with focus trapping, `aria-modal="true"`, and `Escape` key capture.
+  - Command Palette (`Cmd/Ctrl+K`) with fuzzy query filtering, keyboard arrow navigation, and live result counts.
+  - Disclosure Accordion (`data-accordion`) with fluid CSS grid height transitions and full keyboard operability.
+  - Tab panels (`data-tabs`) with W3C roving tabindex keyboard navigation.
+  - Queue-managed Toast notifications with `aria-live="polite"` screen reader announcements.
+  - Native Popover API integration with fallback click-outside and keydown dismiss handlers.
+- **Reactive JSX Runtime**:
+  - Fine-grained reactive signals (`signal`, `computed`, `effect`) with automatic dependency tracking.
+  - Sub-5KB virtual DOM runtime (`createElement`, `h`, `diff`, `Fragment`, `memo`, `forwardRef`).
+  - Zero-dependency Server-Side Rendering pipeline (`renderToString`) with SSR hydration support.
+- **Progressive Enhancement & Fallbacks**:
+  - Native View Transitions API router (`document.startViewTransition`) with seamless crossfade fallback.
+  - Web Animations API helper (`safeAnimate`) with automatic style application when WAAPI is unsupported.
+  - Vestibular safety guard: Fail-safe reduced motion detection defaulting to `reduce` if `matchMedia` is unavailable.
+- **Developer CLI & Diagnostics**:
+  - `elan doctor` / `bin/site-doctor.cjs`: Automated site auditor checking viewport meta tags, Elan bundles, `@layer elan` usage, and semantic accessibility trees.
+  - `create-elan` scaffolder for rapid initialization of SaaS, Portfolio, and Agency templates.
+
+#### Security Hardening
+- **Audited HTML Sanitizer**: Inert DOMParser sanitizer stripping `<script>`, `<style>`, `<iframe>`, `<object>`, `<embed>`, inline `on*` event handlers, and dangerous URI schemes.
+- **W3C Trusted Types**: Automatic registration and integration with `elan-policy` for strict CSP compliance.
+- **Safe URL Validator (`safeURL`)**: Strips unencoded control characters, scheme-relative `//` URLs without host allowlist, and malicious protocols (`javascript:`, `vbscript:`, `file:`, `data:`).
+- **Constant-Time String Comparison (`timingSafeEqual`)**: Bitwise XOR comparison protecting tokens and signatures against timing side-channel attacks.
+- **WebAuthn / Passkey Security**: Cryptographic challenge generation and Relying Party ID origin validation.
+- **Realtime WebSocket Guards**: Enforced protocol allowlist (`ws://`, `wss://`), frame size limit enforcement, and safe handling of malformed frames.
+
+#### Changed
+- Wrapped all framework stylesheets (`elan.css`, `elan-native.css`, `elan-polish.css`) inside `@layer elan` for clean consumer override specificity.
+- Enforced strict monorepo encapsulation with `"private": true` across all 22 workspace sub-packages.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gaurang Agarwal (GaurangBuilds)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,237 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="site/assets/elan-wordmark.svg" alt="Elan UI" width="380" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center"><strong>The Complete Website UI/UX, Motion Engine &amp; Reactive Component Library</strong></p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
+  <img src="https://img.shields.io/badge/version-0.1.0-informational.svg" alt="Version 0.1.0" />
+  <img src="https://img.shields.io/badge/dependencies-0-success.svg" alt="Zero Runtime Dependencies" />
+  <img src="https://img.shields.io/badge/typescript-zero--any-success.svg" alt="Zero Any Types" />
+  <img src="https://img.shields.io/badge/tree--shaking-verified-brightgreen.svg" alt="Tree-Shaking Verified" />
+  <img src="https://img.shields.io/badge/a11y-tested--automated--%26--manual-success.svg" alt="Accessibility Tested" />
+</p>
+
+<p align="center">
+  <a href="REVIEW.md"><strong>10-Minute Reviewer Tour</strong></a> •
+  <a href="CLAIMS.md"><strong>Verified Claims</strong></a> •
+  <a href="SCORECARD.md"><strong>Architectural Scorecard</strong></a> •
+  <a href="THREAT_MODEL.md"><strong>Threat Model</strong></a> •
+  <a href="docs/a11y/conformance.md"><strong>Accessibility Conformance</strong></a>
+</p>
+
+---
+
+## ⚡ The Master One-Command Verification
+
+To clone and independently verify every quantitative, architectural, security, accessibility, and packaging claim in a single command:
+
+```bash
+git clone https://github.com/GaurangBuilds/elan.git
+cd elan
+npm install
+npm run verify
+```
+
+---
+
+## 🌟 The Vision & Architecture
+
+Elan is a unified, production-ready website engine that brings together the best of modern web interaction—scroll storytelling, physics-based motion, accessible interactive UI components, standards-based Autonomous Custom Elements, and progressive reactivity—into a clean, zero-dependency architecture.
+
+- **ZERO RUNTIME DEPENDENCIES**: 0 external npm dependencies in `src/`. Clean security profile, zero supply-chain risk.
+- **STRICT TYPE SAFETY**: Written in 100% strict TypeScript with **0 errors and zero `any` types**.
+- **ATTRIBUTE-FIRST**: Author cinematic scroll reveals, timelines, accordions, carousels, and dialogs in plain HTML with declarative `data-*` attributes—zero JavaScript required for basic use.
+- **AUTONOMOUS CUSTOM ELEMENTS**: W3C standards-based Web Components (`<elan-rating>`, `<elan-marquee>`, `<elan-spotlight>`, `<elan-video-player>`, `<elan-a11y-toolbar>`) usable in plain HTML or any framework.
+- **ACCESSIBLE BY DESIGN**: Built for keyboard and screen-reader accessibility; tested with automated checks (`axe-core`) plus a documented manual testing plan. Known gaps and considerations are documented transparently in [docs/a11y/conformance.md](docs/a11y/conformance.md).
+- **NATIVE & FAST**: Uses native CSS Scroll-Driven Animations (`animation-timeline`) and the View Transitions API when supported, falling back smoothly to performant JavaScript observers.
+- **AI-READY**: Ships with a Model Context Protocol (MCP) server (`ElanMcpServer`), structured `llms.txt`, and `AGENTS.md` for AI pair-programming assistants.
+
+---
+
+## 📊 Verified Real-World Measurements
+
+> [!IMPORTANT]
+> **The #1 Rule: Build Everything Real.**  
+> Every number in the tables below was measured by bundling real production consumer apps using `esbuild` with minification and tree-shaking enabled (`es2022`).  
+> **Exact Reproduction Command**: `node scripts/measure.mjs`
+
+### 1. Full Module Import Graphs (Complete Subsystems)
+
+When an author imports an entire subsystem, here are the real, measured bundle sizes including all internal dependencies:
+
+| Module / Subsystem | Raw Size | Gzip Size | Brotli Size | Scope & Capabilities |
+|---|---|---|---|---|
+| **Full Library (All Modules)** | 605.36 KB | **159.41 KB** | 127.38 KB | Complete umbrella import with all components, motion, forms & runtime |
+| **Core Engine** | 13.78 KB | **5.46 KB** | 4.89 KB | Spring physics, easings, ticker scheduler, theme manager, plugins |
+| **Scroll Module** | 48.15 KB | **12.47 KB** | 11.09 KB | Smooth scroll, reveals, parallax, pinning, scrubbers, sticky story |
+| **Motion Module** | 107.92 KB | **25.58 KB** | 22.19 KB | Chained timeline engine, FLIP layout animations, draggable, magnetic, gestures |
+| **Components (UI)** | 56.86 KB | **13.67 KB** | 11.74 KB | Accessible modals, carousel, tabs, accordions, tooltips, toasts |
+| **Navigation Module** | 19.10 KB | **5.77 KB** | 5.10 KB | Mobile drawer, mega menu, breadcrumbs, sticky subnav, scroll restoration |
+| **Conversion Module** | 23.08 KB | **6.70 KB** | 5.92 KB | Pricing table, FAQ accordion with schema, testimonials slider, exit-intent |
+| **Forms Module** | 38.12 KB | **10.65 KB** | 9.48 KB | Validation engine, honeypot spam trap, submission timing, multi-step wizard |
+| **Data Module** | 29.03 KB | **8.60 KB** | 7.67 KB | Sortable/filterable data table, fuzzy search, skeletons, notification center |
+| **Commerce Module** | 28.34 KB | **7.81 KB** | 6.89 KB | Product gallery with zoom, cart drawer, variant & size selector, wishlist |
+| **Media Module** | 34.87 KB | **10.52 KB** | 9.40 KB | Lightbox, privacy video facade, charts suite, audio mini-player |
+| **Compliance Module** | 17.53 KB | **5.68 KB** | 4.72 KB | Granular cookie consent manager, WebAuthn / Passkeys, a11y toolbar |
+| **i18n Module** | 4.01 KB | **1.47 KB** | 1.29 KB | RTL support, locale-aware date/number helpers, text attribute swapper |
+| **Performance Module** | 5.62 KB | **1.92 KB** | 1.68 KB | Low-power / slow-network detection, Core Web Vitals & LoAF monitor |
+| **Theming Module** | 33.45 KB | **10.87 KB** | 9.37 KB | 10 preset themes, i18n localization engine (10 languages + RTL auto-dir) |
+| **Devtools Module** | 27.04 KB | **8.92 KB** | 7.74 KB | Visual scroll marker overlay, trigger inspector, MCP server for AI |
+| **Runtime (VDOM + Signals)** | 49.08 KB | **15.66 KB** | 14.03 KB | Signals, computed, effects, JSX VDOM diffing, hooks, suspense, hydration |
+| **React Compat Layer** | 21.76 KB | **7.40 KB** | 6.66 KB | Component adapter compatibility layer (`createRoot`, `useSyncExternalStore`) |
+| **Stylesheet (`elan.css`)** | 100.33 KB | **18.84 KB** | 15.69 KB | Complete framework styling, themes, animations, utilities |
+
+---
+
+### 2. Individual Feature Imports (Tree-Shaking Proof)
+
+When you import only a single specific feature for a landing page or widget, unused modules are stripped. You only pay for what you actually use:
+
+| Isolated Feature Import | Raw Size | Gzip Size | Brotli Size | Capabilities & Feature Set |
+|---|---|---|---|---|
+| `Only Spring Physics` | 1.21 KB | **0.49 KB** | 0.46 KB | Damped harmonic oscillator physics with mass, stiffness, damping |
+| `Only Accordion` | 2.78 KB | **0.97 KB** | 0.83 KB | Accessible keyboard disclosure with ARIA controls |
+| `Only Signals (Reactivity)` | 2.14 KB | **1.09 KB** | 0.95 KB | Fine-grained reactive state container with atomic subscriptions |
+| `Only Reveal` | 3.39 KB | **1.24 KB** | 1.11 KB | IntersectionObserver-driven viewport entry triggers |
+| `Only Smooth Scroll` | 4.03 KB | **1.42 KB** | 1.26 KB | Inertial momentum scroll with pointer normalization |
+| `Only Magnetic Effect` | 5.21 KB | **1.74 KB** | 1.56 KB | Cursor magnetic snap and spring return |
+| `Only Lightbox` | 5.35 KB | **1.80 KB** | 1.53 KB | Accessible modal media viewer with gestures |
+| `Only Form Validator` | 5.23 KB | **1.81 KB** | 1.55 KB | Async & sync schema validation engine |
+| `Only Tooltip` | 5.63 KB | **2.05 KB** | 1.76 KB | Floating positioning with arrow alignment |
+| `Only Tilt Effect` | 5.92 KB | **2.06 KB** | 1.85 KB | 3D perspective card rotation on pointer move |
+| `Only FLIP Layout Transitions`| 5.03 KB | **2.10 KB** | 1.91 KB | Automatic layout reordering with bounding rect inversion |
+| `Only Draggable Gestures` | 7.53 KB | **2.27 KB** | 2.03 KB | Pointer drag with inertia and boundary clamping |
+| `Only Toast Notifications` | 6.38 KB | **2.29 KB** | 1.96 KB | Animated dismissible notifications with live region |
+| `Only Cookie Consent` | 7.74 KB | **2.37 KB** | 1.92 KB | Granular consent manager with category controls |
+| `Only Modal Dialog` | 6.99 KB | **2.40 KB** | 2.07 KB | Focus-trapped accessible dialog with backdrop |
+| `Only Theme Switcher` | 7.61 KB | **2.82 KB** | 2.41 KB | Design-token CSS custom property theme manager |
+| `Only Carousel Pro` | 10.15 KB | **3.08 KB** | 2.69 KB | Touch-friendly slide track with pagination and autoplay |
+| `Only Data Table` | 10.08 KB | **3.35 KB** | 2.95 KB | Sortable, filterable table with accessible headers |
+| `Only Timeline Animator` | 11.74 KB | **4.04 KB** | 3.67 KB | Chained multi-track keyframe sequencer |
+| `Only JSX/VDOM Render` | 12.86 KB | **4.75 KB** | 4.28 KB | Virtual DOM createElement and double-ended diffing |
+
+---
+
+## 🛠️ The Feature Suites
+
+### 1. Unified Elan CLI (`elan`)
+A unified command-line tool for scaffolding, auditing, and adding components:
+```bash
+# Scaffold a new site from templates
+npx elan create my-site --template saas
+
+# Audit a site for accessibility, performance, and security
+npx elan audit ./dist
+
+# Add a block or layout
+npx elan add pricing-table
+```
+
+### 2. Accessible SVG Charts Suite
+Lightweight, zero-dependency data visualizations with screen-reader data table fallbacks:
+```ts
+import { Charts } from 'elan-ui';
+
+const svg = Charts.renderLineChart({
+  data: [{ label: 'Q1', value: 120 }, { label: 'Q2', value: 240 }],
+  title: 'Revenue Growth',
+  curved: true
+});
+```
+
+### 3. In-Memory Fuzzy Search Indexer
+Typo-tolerant, fast search with multi-field weighted scoring:
+```ts
+import { createFuzzySearch } from 'elan-ui';
+
+const searcher = createFuzzySearch(products, { keys: ['title', 'category'] });
+const results = searcher.search('crosel'); // Matches "Carousel"
+```
+
+### 4. Real-Time WebSocket Client
+Resilient WebSocket connections with exponential backoff and offline queue:
+```ts
+import { createRealtimeClient } from 'elan-ui';
+
+const client = createRealtimeClient({ url: 'wss://api.example.com/live' });
+client.on('metric', (data) => console.log(data));
+client.connect();
+```
+
+### 5. WebAuthn & Passkey Authentication
+Passwordless biometric authentication with binary-safe Base64URL helpers:
+```ts
+import { PasskeyHelper } from 'elan-ui';
+
+if (await PasskeyHelper.isSupported()) {
+  const credential = await PasskeyHelper.authenticate({ challenge: serverChallenge });
+}
+```
+
+### 6. Mobile Touch & Gesture Kit
+Multi-directional swipe recognition, pull-to-refresh, and bottom sheets:
+```ts
+import { SwipeRecognizer, BottomSheet } from 'elan-ui';
+
+new SwipeRecognizer(myCard, {
+  onSwipeLeft: () => console.log('Dismissed'),
+  onSwipeRight: () => console.log('Saved')
+});
+```
+
+### 7. End-User Accessibility Toolbar
+Interactive floating widget allowing users to toggle high contrast, dyslexia fonts, and text scaling:
+```ts
+import { initA11yToolbar } from 'elan-ui';
+
+initA11yToolbar();
+```
+
+---
+
+## 🧪 Verification Standard
+
+```bash
+# Run the master verification suite (all 11 gates)
+npm run verify
+
+# Individual checks:
+npm run typecheck       # tsc --noEmit
+npm run test:unit       # Vitest unit test suite (36 suites, 374 tests)
+npm run check:old-name  # Zero former brand references
+npm run check:denylist  # Zero competitor references
+npm run measure         # Real production bundle sizes
+```
+
+---
+
+## 📄 License & Legal Notice
+
+This project is licensed under the terms of the standard **MIT License**.  
+See the full text in the [LICENSE](LICENSE) file.
+
+```text
+MIT License
+
+Copyright (c) 2026 Gaurang Agarwal (GaurangBuilds)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```