@vanduo-oss/framework 1.3.8 → 1.4.0

package/README.md

@@ -1,4 +1,4 @@
-# Vanduo Framework v1.3.8
+# Vanduo Framework v1.4.0
 
 <p align="center">
   <img src="vanduo-banner.svg" alt="Vanduo Framework Banner" width="100%">
@@ -10,41 +10,43 @@
   <a href="https://github.com/vanduo-oss/framework/blob/main/LICENSE"><img src="https://img.shields.io/github/license/vanduo-oss/framework?style=flat-square&color=64748b" alt="License"></a>
 </p>
 
-**Essential just like water is.**
-
-Vanduo is a lightweight, zero-dependency UI framework built with pure HTML, CSS, and JavaScript. It ships 47+ components, responsive utilities, dark mode support, and a flexible theming system.
+Vanduo is a zero-dependency UI framework built with HTML, CSS, and vanilla JavaScript. It ships a full component bundle, scoped runtime initialization, a canonical `--vd-*` token API, and compatibility aliases for existing `1.3.x` consumers.
 
 [Browse Docs](https://vanduo.dev/#docs)
 
 ## Highlights
 
-- Pure CSS/JS with no runtime dependencies
-- Modular architecture with optional per-component imports
-- 47+ components, including Expanding Cards and animated Timeline controls in v1.3.8
-- Niche canvas hex-grid support is distributed as `@vanduo-oss/hex-grid`
-- Built-in dark/light/system theme switching
-- Runtime Theme Customizer for color, font, and radius tokens
-- Accessibility-focused components and utilities
+- Zero runtime dependencies
+- 47+ components across layout, navigation, overlays, search, and effects
+- Scoped runtime APIs for dynamic DOM work
+- Canonical semantic token API under `--vd-*`
+- Built-in dark, light, and system theming
+- Theme customizer with color, font, and radius controls
+- Playwright-based browser coverage across Chromium, Firefox, and WebKit
 
 ## Quick Start
 
-### CDN (recommended)
+### CDN
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@v1.3.8/dist/vanduo.min.css">
-<script src="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@v1.3.8/dist/vanduo.min.js"></script>
-<script>Vanduo.init();</script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@v1.4.0/dist/vanduo.min.css">
+<script src="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@v1.4.0/dist/vanduo.min.js"></script>
+<script>
+  Vanduo.init();
+</script>
 ```
 
-### Local dist files
+### Local Dist Files
 
 ```html
 <link rel="stylesheet" href="dist/vanduo.min.css">
 <script src="dist/vanduo.min.js"></script>
-<script>Vanduo.init();</script>
+<script>
+  Vanduo.init();
+</script>
 ```
 
-### Package install (bundlers)
+### Package Install
 
 ```bash
 pnpm add @vanduo-oss/framework
@@ -57,39 +59,83 @@ import { Vanduo } from '@vanduo-oss/framework';
 Vanduo.init();
 ```
 
-## Docs and Resources
+## Runtime API
+
+```js
+Vanduo.init(root);
+Vanduo.initComponents(root);
+Vanduo.reinit('lazyLoad', root);
+Vanduo.destroy(root);
+Vanduo.destroyAll();
+Vanduo.getComponent('docSearch');
+```
+
+- Omit `root` to target the full document.
+- Pass an `Element` to initialize or destroy only a subtree.
+- Canonical component registry names use `lowerCamelCase`.
+- `LazyLoad` remains available as a compatibility alias for `lazyLoad` in `1.4.x`.
 
-- Website: [vanduo.dev](https://vanduo.dev)
-- Docs: [vanduo.dev/#docs](https://vanduo.dev/#docs)
-- npm: [@vanduo-oss/framework](https://www.npmjs.com/package/@vanduo-oss/framework)
-- Releases: [GitHub Releases](https://github.com/vanduo-oss/framework/releases)
-- LLM reference: [`llms.txt`](llms.txt)
+## Token API
+
+Vanduo `1.4.0` treats `--vd-*` as the canonical semantic API:
+
+- Colors: `--vd-color-*`
+- Backgrounds: `--vd-bg-*`
+- Text: `--vd-text-*`
+- Borders: `--vd-border-*`
+- Shadows: `--vd-shadow-*`
+
+Legacy semantic aliases like `--color-*`, `--bg-*`, and `--text-*` are still supported throughout the `1.4.x` line.
+
+```css
+.cta {
+  color: var(--vd-text-inverse);
+  background: var(--vd-color-primary);
+  border-color: var(--vd-border-color);
+}
+```
+
+More detail lives in [TOKENS.md](TOKENS.md).
+
+## CSS Bundle Notes
+
+- `css/vanduo.css` remains the main framework entrypoint in `1.4.0`.
+- The main bundle still includes framework-wide form defaults for native inputs and textareas.
+- New component styling should prefer `.vd-*` hooks over new raw element selectors.
 
 ## Project Structure
 
 ```text
-vanduo-framework/
-├── dist/          # Production bundles
-├── css/           # Core, components, utilities, effects
-├── js/            # Framework runtime and components
-├── fonts/         # Bundled web fonts
-├── icons/         # Phosphor icons bundle
-└── tests/         # Playwright + linting
+framework/
+├── css/          # Foundation, utilities, effects, components
+├── js/           # Runtime, lifecycle, components
+├── dist/         # Built artifacts
+├── tests/        # Playwright fixtures and specs
+├── scripts/      # Build, verification, and inventory scripts
+└── docs/*.md     # Release and architecture notes
 ```
 
-## Browser Support
+## Development
 
-- Chrome (last 2 versions)
-- Firefox (last 2 versions)
-- Safari (last 2 versions)
-- Edge (last 2 versions)
+```bash
+corepack enable
+pnpm install
+pnpm run lint
+pnpm run build
+pnpm run check:versions
+pnpm test
+pnpm run stats:css
+```
+
+## Release Notes
+
+- Architecture notes: [ARCHITECTURE.md](ARCHITECTURE.md)
+- Token model: [TOKENS.md](TOKENS.md)
+- `1.4.0` migration notes: [changes-v140.md](changes-v140.md)
+- QA strategy: [QA-Automation-Strategy.md](QA-Automation-Strategy.md)
+- Contributor workflow: [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ## License
 
 MIT - see [LICENSE](LICENSE).  
 Third-party notices are listed in [THIRD-PARTY-LICENSES](THIRD-PARTY-LICENSES).
-
-## Credits
-
-- [Open Color](https://yeun.github.io/open-color/) (MIT)
-- [Phosphor Icons](https://phosphoricons.com/) (MIT)

package/css/components/affix.css

@@ -49,5 +49,5 @@
 
 .vd-affix-bordered.is-stuck {
   box-shadow: none;
-  border-bottom: 1px solid var(--border-color, #dee2e6);
+  border-bottom: 1px solid var(--vd-border-color, #dee2e6);
 }

package/css/components/alerts.css

@@ -11,43 +11,43 @@
   --alert-border-width: 1px;
 
   /* Alert Colors */
-  --alert-primary-bg: var(--color-primary-alpha-10);
-  --alert-primary-border: var(--color-primary);
-  --alert-primary-text: var(--color-primary-dark);
+  --alert-primary-bg: var(--vd-color-primary-alpha-10);
+  --alert-primary-border: var(--vd-color-primary);
+  --alert-primary-text: var(--vd-color-primary-dark);
 
-  --alert-success-bg: var(--color-success-alpha-10);
-  --alert-success-border: var(--color-success);
-  --alert-success-text: var(--color-success-dark);
+  --alert-success-bg: var(--vd-color-success-alpha-10);
+  --alert-success-border: var(--vd-color-success);
+  --alert-success-text: var(--vd-color-success-dark);
 
-  --alert-warning-bg: var(--color-warning-alpha-10);
-  --alert-warning-border: var(--color-warning);
-  --alert-warning-text: var(--color-warning-dark);
+  --alert-warning-bg: var(--vd-color-warning-alpha-10);
+  --alert-warning-border: var(--vd-color-warning);
+  --alert-warning-text: var(--vd-color-warning-dark);
 
-  --alert-error-bg: var(--color-error-alpha-10);
-  --alert-error-border: var(--color-error);
-  --alert-error-text: var(--color-error-dark);
+  --alert-error-bg: var(--vd-color-error-alpha-10);
+  --alert-error-border: var(--vd-color-error);
+  --alert-error-text: var(--vd-color-error-dark);
 
-  --alert-info-bg: var(--color-info-alpha-10);
-  --alert-info-border: var(--color-info);
-  --alert-info-text: var(--color-info-dark);
+  --alert-info-bg: var(--vd-color-info-alpha-10);
+  --alert-info-border: var(--vd-color-info);
+  --alert-info-text: var(--vd-color-info-dark);
 }
 
 /* Dark Theme Overrides */
 [data-theme="dark"] {
-  --alert-primary-text: var(--color-primary-light);
-  --alert-success-text: var(--color-success-light);
-  --alert-warning-text: var(--color-warning-light);
-  --alert-error-text: var(--color-error-light);
-  --alert-info-text: var(--color-info-light);
+  --alert-primary-text: var(--vd-color-primary-light);
+  --alert-success-text: var(--vd-color-success-light);
+  --alert-warning-text: var(--vd-color-warning-light);
+  --alert-error-text: var(--vd-color-error-light);
+  --alert-info-text: var(--vd-color-info-light);
 }
 
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme]) {
-    --alert-primary-text: var(--color-primary-light);
-    --alert-success-text: var(--color-success-light);
-    --alert-warning-text: var(--color-warning-light);
-    --alert-error-text: var(--color-error-light);
-    --alert-info-text: var(--color-info-light);
+    --alert-primary-text: var(--vd-color-primary-light);
+    --alert-success-text: var(--vd-color-success-light);
+    --alert-warning-text: var(--vd-color-warning-light);
+    --alert-error-text: var(--vd-color-error-light);
+    --alert-info-text: var(--vd-color-info-light);
   }
 }
 
@@ -164,34 +164,34 @@
 
 /* Solid Variants (filled background) */
 .vd-alert-solid.vd-alert-primary {
-  background-color: var(--color-primary);
-  border-color: var(--color-primary);
-  color: var(--color-white);
+  background-color: var(--vd-color-primary);
+  border-color: var(--vd-color-primary);
+  color: var(--vd-color-white);
 }
 
 .vd-alert-solid.vd-alert-success {
-  background-color: var(--color-success);
-  border-color: var(--color-success);
-  color: var(--color-white);
+  background-color: var(--vd-color-success);
+  border-color: var(--vd-color-success);
+  color: var(--vd-color-white);
 }
 
 .vd-alert-solid.vd-alert-warning {
-  background-color: var(--color-warning);
-  border-color: var(--color-warning);
-  color: var(--color-gray-900);
+  background-color: var(--vd-color-warning);
+  border-color: var(--vd-color-warning);
+  color: var(--vd-color-gray-900);
 }
 
 .vd-alert-solid.vd-alert-error,
 .vd-alert-solid.vd-alert-danger {
-  background-color: var(--color-error);
-  border-color: var(--color-error);
-  color: var(--color-white);
+  background-color: var(--vd-color-error);
+  border-color: var(--vd-color-error);
+  color: var(--vd-color-white);
 }
 
 .vd-alert-solid.vd-alert-info {
-  background-color: var(--color-info);
-  border-color: var(--color-info);
-  color: var(--color-white);
+  background-color: var(--vd-color-info);
+  border-color: var(--vd-color-info);
+  color: var(--vd-color-white);
 }
 
 /* Outline Variants */

package/css/components/avatar.css

@@ -14,27 +14,27 @@
   --avatar-size-2xl: 14.5625rem;/* 233px - fib */
 
   /* Avatar Colors */
-  --avatar-bg: var(--color-gray-300);
-  --avatar-text: var(--color-gray-700);
-  --avatar-border: var(--color-white);
-  --avatar-status-online: var(--color-success);
-  --avatar-status-offline: var(--color-gray-400);
-  --avatar-status-busy: var(--color-error);
-  --avatar-status-away: var(--color-warning);
+  --avatar-bg: var(--vd-color-gray-300);
+  --avatar-text: var(--vd-color-gray-700);
+  --avatar-border: var(--vd-color-white);
+  --avatar-status-online: var(--vd-color-success);
+  --avatar-status-offline: var(--vd-color-gray-400);
+  --avatar-status-busy: var(--vd-color-error);
+  --avatar-status-away: var(--vd-color-warning);
 }
 
 /* Dark Theme Overrides */
 [data-theme="dark"] {
-  --avatar-bg: var(--color-gray-600);
-  --avatar-text: var(--color-gray-200);
-  --avatar-border: var(--color-gray-800);
+  --avatar-bg: var(--vd-color-gray-600);
+  --avatar-text: var(--vd-color-gray-200);
+  --avatar-border: var(--vd-color-gray-800);
 }
 
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme]) {
-    --avatar-bg: var(--color-gray-600);
-    --avatar-text: var(--color-gray-200);
-    --avatar-border: var(--color-gray-800);
+    --avatar-bg: var(--vd-color-gray-600);
+    --avatar-text: var(--vd-color-gray-200);
+    --avatar-border: var(--vd-color-gray-800);
   }
 }
 
@@ -161,19 +161,19 @@
 
 /* Avatar with Ring/Border */
 .vd-avatar-ring {
-  box-shadow: 0 0 0 3px var(--avatar-border), 0 0 0 5px var(--color-primary);
+  box-shadow: 0 0 0 3px var(--avatar-border), 0 0 0 5px var(--vd-color-primary);
 }
 
 .vd-avatar-ring-success {
-  box-shadow: 0 0 0 3px var(--avatar-border), 0 0 0 5px var(--color-success);
+  box-shadow: 0 0 0 3px var(--avatar-border), 0 0 0 5px var(--vd-color-success);
 }
 
 .vd-avatar-ring-warning {
-  box-shadow: 0 0 0 3px var(--avatar-border), 0 0 0 5px var(--color-warning);
+  box-shadow: 0 0 0 3px var(--avatar-border), 0 0 0 5px var(--vd-color-warning);
 }
 
 .vd-avatar-ring-error {
-  box-shadow: 0 0 0 3px var(--avatar-border), 0 0 0 5px var(--color-error);
+  box-shadow: 0 0 0 3px var(--avatar-border), 0 0 0 5px var(--vd-color-error);
 }
 
 /* Avatar Group (stacked avatars) */
@@ -212,8 +212,8 @@
   width: var(--avatar-size);
   height: var(--avatar-size);
   border-radius: 50%;
-  background-color: var(--color-gray-200);
-  color: var(--text-primary);
+  background-color: var(--vd-color-gray-200);
+  color: var(--vd-text-primary);
   font-size: var(--font-size-sm);
   font-weight: var(--font-weight-medium);
   border: 2px solid var(--avatar-border);
@@ -221,38 +221,38 @@
 }
 
 [data-theme="dark"] .vd-avatar-group-count {
-  background-color: var(--color-gray-700);
+  background-color: var(--vd-color-gray-700);
 }
 
 /* Color Variants */
 .vd-avatar-primary {
-  background-color: var(--color-primary);
-  color: var(--color-white);
+  background-color: var(--vd-color-primary);
+  color: var(--vd-color-white);
 }
 
 .vd-avatar-secondary {
-  background-color: var(--color-secondary);
-  color: var(--color-white);
+  background-color: var(--vd-color-secondary);
+  color: var(--vd-color-white);
 }
 
 .vd-avatar-success {
-  background-color: var(--color-success);
-  color: var(--color-white);
+  background-color: var(--vd-color-success);
+  color: var(--vd-color-white);
 }
 
 .vd-avatar-warning {
-  background-color: var(--color-warning);
-  color: var(--color-gray-900);
+  background-color: var(--vd-color-warning);
+  color: var(--vd-color-gray-900);
 }
 
 .vd-avatar-error {
-  background-color: var(--color-error);
-  color: var(--color-white);
+  background-color: var(--vd-color-error);
+  color: var(--vd-color-white);
 }
 
 .vd-avatar-info {
-  background-color: var(--color-info);
-  color: var(--color-white);
+  background-color: var(--vd-color-info);
+  color: var(--vd-color-white);
 }
 
 /* Clickable Avatar */
@@ -269,7 +269,7 @@ button.vd-avatar:hover {
 
 a.vd-avatar:focus-visible,
 button.vd-avatar:focus-visible {
-  outline: 2px solid var(--color-primary);
+  outline: 2px solid var(--vd-color-primary);
   outline-offset: 2px;
 }
 

package/css/components/badges.css

@@ -37,24 +37,24 @@
 
 /* Dark Theme - Light badge needs different colors */
 [data-theme="dark"] .vd-badge-light {
-  background-color: var(--color-gray-700);
-  color: var(--color-gray-100);
+  background-color: var(--vd-color-gray-700);
+  color: var(--vd-color-gray-100);
 }
 
 [data-theme="dark"] .vd-badge-outlined.vd-badge-light {
-  color: var(--color-gray-300);
-  border-color: var(--color-gray-500);
+  color: var(--vd-color-gray-300);
+  border-color: var(--vd-color-gray-500);
 }
 
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme]) .vd-badge-light {
-    background-color: var(--color-gray-700);
-    color: var(--color-gray-100);
+    background-color: var(--vd-color-gray-700);
+    color: var(--vd-color-gray-100);
   }
 
   :root:not([data-theme]) .vd-badge-outlined.vd-badge-light {
-    color: var(--color-gray-300);
-    border-color: var(--color-gray-500);
+    color: var(--vd-color-gray-300);
+    border-color: var(--vd-color-gray-500);
   }
 }
 
@@ -65,53 +65,53 @@
   font-size: var(--badge-font-size);
   font-weight: var(--badge-font-weight);
   line-height: var(--badge-line-height);
-  color: var(--color-white);
+  color: var(--vd-color-white);
   text-align: center;
   white-space: nowrap;
   vertical-align: baseline;
   border-radius: var(--badge-border-radius);
-  background-color: var(--color-secondary);
+  background-color: var(--vd-color-secondary);
 }
 
 /* Badge Variants */
 .vd-badge-primary {
-  background-color: var(--color-primary);
-  color: var(--color-white);
+  background-color: var(--vd-color-primary);
+  color: var(--vd-color-white);
 }
 
 .vd-badge-secondary {
-  background-color: var(--color-secondary);
-  color: var(--color-white);
+  background-color: var(--vd-color-secondary);
+  color: var(--vd-color-white);
 }
 
 .vd-badge-success {
-  background-color: var(--color-success);
-  color: var(--color-white);
+  background-color: var(--vd-color-success);
+  color: var(--vd-color-white);
 }
 
 .vd-badge-warning {
-  background-color: var(--color-warning);
-  color: var(--color-gray-900);
+  background-color: var(--vd-color-warning);
+  color: var(--vd-color-gray-900);
 }
 
 .vd-badge-error {
-  background-color: var(--color-error);
-  color: var(--color-white);
+  background-color: var(--vd-color-error);
+  color: var(--vd-color-white);
 }
 
 .vd-badge-info {
-  background-color: var(--color-info);
-  color: var(--color-white);
+  background-color: var(--vd-color-info);
+  color: var(--vd-color-white);
 }
 
 .vd-badge-light {
-  background-color: var(--color-gray-100);
-  color: var(--color-gray-900);
+  background-color: var(--vd-color-gray-100);
+  color: var(--vd-color-gray-900);
 }
 
 .vd-badge-dark {
-  background-color: var(--color-gray-800);
-  color: var(--color-white);
+  background-color: var(--vd-color-gray-800);
+  color: var(--vd-color-white);
 }
 
 /* Badge Sizes */
@@ -138,43 +138,43 @@
 }
 
 .vd-badge-outlined.vd-badge-primary {
-  color: var(--color-primary);
-  border-color: var(--color-primary);
+  color: var(--vd-color-primary);
+  border-color: var(--vd-color-primary);
 }
 
 .vd-badge-outlined.vd-badge-secondary {
-  color: var(--color-secondary);
-  border-color: var(--color-secondary);
+  color: var(--vd-color-secondary);
+  border-color: var(--vd-color-secondary);
 }
 
 .vd-badge-outlined.vd-badge-success {
-  color: var(--color-success);
-  border-color: var(--color-success);
+  color: var(--vd-color-success);
+  border-color: var(--vd-color-success);
 }
 
 .vd-badge-outlined.vd-badge-warning {
-  color: var(--color-warning);
-  border-color: var(--color-warning);
+  color: var(--vd-color-warning);
+  border-color: var(--vd-color-warning);
 }
 
 .vd-badge-outlined.vd-badge-error {
-  color: var(--color-error);
-  border-color: var(--color-error);
+  color: var(--vd-color-error);
+  border-color: var(--vd-color-error);
 }
 
 .vd-badge-outlined.vd-badge-info {
-  color: var(--color-info);
-  border-color: var(--color-info);
+  color: var(--vd-color-info);
+  border-color: var(--vd-color-info);
 }
 
 .vd-badge-outlined.vd-badge-light {
-  color: var(--color-gray-600);
-  border-color: var(--color-gray-300);
+  color: var(--vd-color-gray-600);
+  border-color: var(--vd-color-gray-300);
 }
 
 .vd-badge-outlined.vd-badge-dark {
-  color: var(--color-gray-800);
-  border-color: var(--color-gray-800);
+  color: var(--vd-color-gray-800);
+  border-color: var(--vd-color-gray-800);
 }
 
 /* Badge Positioning (for use with buttons, avatars, etc.) */

package/css/components/breadcrumbs.css

@@ -11,14 +11,14 @@
 
   /* Breadcrumb Separator */
   --breadcrumb-separator: "/";
-  --breadcrumb-separator-color: var(--text-muted);
+  --breadcrumb-separator-color: var(--vd-text-muted);
   --breadcrumb-separator-padding: 0.5rem; /* 8px - fib */
   
   /* Breadcrumb Colors */
   --breadcrumb-bg: transparent;
-  --breadcrumb-link-color: var(--color-primary);
-  --breadcrumb-link-hover-color: var(--color-primary-dark);
-  --breadcrumb-active-color: var(--text-secondary);
+  --breadcrumb-link-color: var(--vd-color-primary);
+  --breadcrumb-link-hover-color: var(--vd-color-primary-dark);
+  --breadcrumb-active-color: var(--vd-text-secondary);
 }
 
 /* Dark Theme Overrides - breadcrumbs use CSS variables that already adapt */
@@ -70,7 +70,7 @@
 
 .vd-breadcrumb-link:focus,
 .vd-breadcrumb-item > a:focus {
-  outline: 2px solid var(--color-primary);
+  outline: 2px solid var(--vd-color-primary);
   outline-offset: 2px;
   border-radius: 0.25rem;
 }

package/css/components/bubble.css

@@ -7,8 +7,8 @@
 :root {
   /* Bubble Colors */
   --bubble-bg: var(--card-bg, #fff);
-  --bubble-text: var(--text-primary, #212529);
-  --bubble-border-color: var(--border-color, #dee2e6);
+  --bubble-text: var(--vd-text-primary, #212529);
+  --bubble-border-color: var(--vd-border-color, #dee2e6);
   --bubble-shadow: 0 0.5rem 1.3125rem rgba(0, 0, 0, 0.12); /* 8px 21px - fib */
 
   /* Bubble Spacing (Fibonacci) */
@@ -31,14 +31,14 @@
 /* Dark Theme */
 [data-theme="dark"] {
   --bubble-bg: var(--card-bg, #2d2d44);
-  --bubble-border-color: var(--border-color, #3d3d5c);
+  --bubble-border-color: var(--vd-border-color, #3d3d5c);
   --bubble-shadow: 0 0.5rem 1.3125rem rgba(0, 0, 0, 0.3);
 }
 
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme]) {
     --bubble-bg: var(--card-bg, #2d2d44);
-    --bubble-border-color: var(--border-color, #3d3d5c);
+    --bubble-border-color: var(--vd-border-color, #3d3d5c);
     --bubble-shadow: 0 0.5rem 1.3125rem rgba(0, 0, 0, 0.3);
   }
 }