@vanduo-oss/framework 1.3.9 → 1.4.1

package/README.md

@@ -1,4 +1,4 @@
-# Vanduo Framework v1.3.9
+# Vanduo Framework v1.4.1
 
 <p align="center">
   <img src="vanduo-banner.svg" alt="Vanduo Framework Banner" width="100%">
@@ -10,42 +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, and a strict canonical `--vd-*` token API.
 
 [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.9
-- Current Theme Customizer defaults in this worktree are `charcoal` for neutral color and `ubuntu` for font family
-- Niche canvas hex-grid support is distributed as [`@vanduo-oss/hex-grid`](https://www.npmjs.com/package/@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
+- Strict design 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.9/dist/vanduo.min.css">
-<script src="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@v1.3.9/dist/vanduo.min.js"></script>
-<script>Vanduo.init();</script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@v1.4.1/dist/vanduo.min.css">
+<script src="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@v1.4.1/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
@@ -58,39 +59,85 @@ 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.1` treats `--vd-*` as the only shipped custom-property namespace:
+
+- Palette: `--vd-red-*`, `--vd-primary-*`, `--vd-gray-*`, and related scales
+- Colors: `--vd-color-*`
+- Backgrounds: `--vd-bg-*`
+- Text: `--vd-text-*`
+- Borders: `--vd-border-*`
+- Shadows: `--vd-shadow-*`
+- Components/effects: `--vd-btn-*`, `--vd-card-*`, `--vd-morph-*`, and related internals
+
+Legacy unprefixed token aliases were removed in `1.4.1`; update custom themes and overrides to use the `--vd-*` equivalents.
+
+```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.1`.
+- 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.1` token migration notes: [changes-v141.md](changes-v141.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

@@ -5,19 +5,19 @@
  */
 
 :root {
-  --affix-top-offset: 0;
-  --affix-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
-  --affix-transition: box-shadow 0.2s ease, background-color 0.2s ease;
-  --affix-z-index: 1020;
+  --vd-affix-top-offset: 0;
+  --vd-affix-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+  --vd-affix-transition: box-shadow 0.2s ease, background-color 0.2s ease;
+  --vd-affix-z-index: 1020;
 }
 
 [data-theme="dark"] {
-  --affix-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
+  --vd-affix-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
 }
 
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme]) {
-    --affix-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
+    --vd-affix-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
   }
 }
 
@@ -27,9 +27,9 @@
 .vd-sticky,
 [data-vd-affix] {
   position: sticky;
-  top: var(--affix-top-offset);
-  transition: var(--affix-transition);
-  z-index: calc(var(--affix-z-index) - 1);
+  top: var(--vd-affix-top-offset);
+  transition: var(--vd-affix-transition);
+  z-index: calc(var(--vd-affix-z-index) - 1);
 }
 
 /* ========== Stuck State ========== */
@@ -37,8 +37,8 @@
 .vd-affix.is-stuck,
 .vd-sticky.is-stuck,
 [data-vd-affix].is-stuck {
-  z-index: var(--affix-z-index);
-  box-shadow: var(--affix-shadow);
+  z-index: var(--vd-affix-z-index);
+  box-shadow: var(--vd-affix-shadow);
 }
 
 /* ========== Variants ========== */
@@ -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

@@ -5,93 +5,93 @@
 
 :root {
   /* Alert Spacing (Fibonacci: 21px/13px, ratio ~ phi) */
-  --alert-padding-x: 1.3125rem;   /* 21px - fib */
-  --alert-padding-y: 0.8125rem;   /* 13px - fib */
-  --alert-border-radius: var(--btn-border-radius);
-  --alert-border-width: 1px;
+  --vd-alert-padding-x: 1.3125rem;   /* 21px - fib */
+  --vd-alert-padding-y: 0.8125rem;   /* 13px - fib */
+  --vd-alert-border-radius: var(--vd-btn-border-radius);
+  --vd-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);
+  --vd-alert-primary-bg: var(--vd-color-primary-alpha-10);
+  --vd-alert-primary-border: var(--vd-color-primary);
+  --vd-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);
+  --vd-alert-success-bg: var(--vd-color-success-alpha-10);
+  --vd-alert-success-border: var(--vd-color-success);
+  --vd-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);
+  --vd-alert-warning-bg: var(--vd-color-warning-alpha-10);
+  --vd-alert-warning-border: var(--vd-color-warning);
+  --vd-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);
+  --vd-alert-error-bg: var(--vd-color-error-alpha-10);
+  --vd-alert-error-border: var(--vd-color-error);
+  --vd-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);
+  --vd-alert-info-bg: var(--vd-color-info-alpha-10);
+  --vd-alert-info-border: var(--vd-color-info);
+  --vd-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);
+  --vd-alert-primary-text: var(--vd-color-primary-light);
+  --vd-alert-success-text: var(--vd-color-success-light);
+  --vd-alert-warning-text: var(--vd-color-warning-light);
+  --vd-alert-error-text: var(--vd-color-error-light);
+  --vd-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);
+    --vd-alert-primary-text: var(--vd-color-primary-light);
+    --vd-alert-success-text: var(--vd-color-success-light);
+    --vd-alert-warning-text: var(--vd-color-warning-light);
+    --vd-alert-error-text: var(--vd-color-error-light);
+    --vd-alert-info-text: var(--vd-color-info-light);
   }
 }
 
 /* Base Alert */
 .vd-alert {
   position: relative;
-  padding: var(--alert-padding-y) var(--alert-padding-x);
+  padding: var(--vd-alert-padding-y) var(--vd-alert-padding-x);
   margin-bottom: 1rem;
-  border: var(--alert-border-width) solid transparent;
-  border-radius: var(--alert-border-radius);
-  font-size: var(--font-size-base);
-  line-height: var(--line-height-normal);
+  border: var(--vd-alert-border-width) solid transparent;
+  border-radius: var(--vd-alert-border-radius);
+  font-size: var(--vd-font-size-base);
+  line-height: var(--vd-line-height-normal);
 }
 
 /* Alert Variants */
 .vd-alert-primary {
-  background-color: var(--alert-primary-bg);
-  border-color: var(--alert-primary-border);
-  color: var(--alert-primary-text);
+  background-color: var(--vd-alert-primary-bg);
+  border-color: var(--vd-alert-primary-border);
+  color: var(--vd-alert-primary-text);
 }
 
 .vd-alert-success {
-  background-color: var(--alert-success-bg);
-  border-color: var(--alert-success-border);
-  color: var(--alert-success-text);
+  background-color: var(--vd-alert-success-bg);
+  border-color: var(--vd-alert-success-border);
+  color: var(--vd-alert-success-text);
 }
 
 .vd-alert-warning {
-  background-color: var(--alert-warning-bg);
-  border-color: var(--alert-warning-border);
-  color: var(--alert-warning-text);
+  background-color: var(--vd-alert-warning-bg);
+  border-color: var(--vd-alert-warning-border);
+  color: var(--vd-alert-warning-text);
 }
 
 .vd-alert-error,
 .vd-alert-danger {
-  background-color: var(--alert-error-bg);
-  border-color: var(--alert-error-border);
-  color: var(--alert-error-text);
+  background-color: var(--vd-alert-error-bg);
+  border-color: var(--vd-alert-error-border);
+  color: var(--vd-alert-error-text);
 }
 
 .vd-alert-info {
-  background-color: var(--alert-info-bg);
-  border-color: var(--alert-info-border);
-  color: var(--alert-info-text);
+  background-color: var(--vd-alert-info-bg);
+  border-color: var(--vd-alert-info-border);
+  color: var(--vd-alert-info-text);
 }
 
 /* Alert with Icon */
@@ -111,7 +111,7 @@
 
 /* Alert Title */
 .vd-alert-title {
-  font-weight: var(--font-weight-semibold);
+  font-weight: var(--vd-font-weight-semibold);
   margin-bottom: 0.25rem;
 }
 
@@ -129,7 +129,7 @@
   position: absolute;
   top: 0;
   right: 0;
-  padding: var(--alert-padding-y) var(--alert-padding-x);
+  padding: var(--vd-alert-padding-y) var(--vd-alert-padding-x);
   background: transparent;
   border: none;
   cursor: pointer;
@@ -152,7 +152,7 @@
 /* Alert Link */
 .vd-alert a,
 .vd-alert-link {
-  font-weight: var(--font-weight-semibold);
+  font-weight: var(--vd-font-weight-semibold);
   color: inherit;
   text-decoration: underline;
 }
@@ -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 */
@@ -202,18 +202,18 @@
 /* Alert Sizes */
 .vd-alert-sm {
   padding: 0.3125rem 0.5rem; /* 5px 8px - fib pair */
-  font-size: var(--font-size-sm);
+  font-size: var(--vd-font-size-sm);
 }
 
 .vd-alert-lg {
   padding: 1.3125rem 2.125rem; /* 21px 34px - fib pair */
-  font-size: var(--font-size-lg);
+  font-size: var(--vd-font-size-lg);
 }
 
 /* Alert with Border Left Accent */
 .vd-alert-accent {
   border-left-width: 4px;
-  border-radius: 0 var(--alert-border-radius) var(--alert-border-radius) 0;
+  border-radius: 0 var(--vd-alert-border-radius) var(--vd-alert-border-radius) 0;
 }
 
 /* Reduced Motion */