@axiom-core/vue-adapter 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +158 -35
  2. package/package.json +9 -9
package/README.md CHANGED
@@ -1,90 +1,213 @@
1
1
  # @axiom-core/vue-adapter
2
2
 
3
- Official Axiom Design System adapter for Vue 3.
3
+ The official Axiom Design System adapter for Vue 3. Connects `@axiom-core/runtime-engine` resolved themes to Vue applications by providing a provider component, deterministic CSS variable injection, and reactive theme updates through the Vue Composition API.
4
4
 
5
- **Specification Conformance:** v1.0
6
- **Status:** In Development
7
- **Framework:** Vue 3.x (Composition API)
5
+ ## Responsibilities
6
+
7
+ - **Provider component** — exposes the current resolved theme to the Vue component tree via `provide`/`inject`
8
+ - **CSS variable injection** — emits deterministic CSS custom properties into the DOM using `@axiom-core/css-bridge` and `@axiom-core/dom-injector`
9
+ - **Reactive theme updates** — watches the theme manager and triggers re-injection when the resolved theme changes
10
+ - **SSR support** — renders a `<style>` tag on the server via `@axiom-core/ssr-utils` for hydration-safe style delivery
11
+
12
+ This package does **not** contain runtime composition logic. Theme composition is handled by `@axiom-core/runtime-engine`.
13
+
14
+ ---
15
+
16
+ ## Installation
8
17
 
9
18
  ## Installation
10
19
 
11
20
  ```bash
12
- # Base entry only (pre-resolved themes)
13
- npm install @axiom-core/vue-adapter vue
21
+ pnpm add @axiom-core/runtime-engine
22
+ pnpm add @axiom-core/vue-adapter
23
+ ```
24
+
25
+ Vue 3 is a peer dependency:
14
26
 
15
- # Runtime entry (theme composition)
16
- npm install @axiom-core/vue-adapter @axiom-core/core-engine @axiom-core/invariant-engine vue
27
+ ```bash
28
+ pnpm add vue
17
29
  ```
18
30
 
31
+ ---
32
+
19
33
  ## Usage
20
34
 
21
- ### Base Entry (Pre-Resolved Themes)
35
+ ### Base Entry — Pre-Resolved Theme
22
36
 
23
- Minimal bundle overhead for pre-resolved themes:
37
+ Use the base entry when you have a pre-resolved theme (e.g., statically exported JSON) and do not need runtime axis switching:
24
38
 
25
39
  ```vue
26
40
  <script setup>
27
- import { AxiomProvider } from "@axiom-core/vue-adapter";
28
- import resolvedTheme from "./theme.resolved.json";
41
+ import { AxiomProvider } from '@axiom-core/vue-adapter';
42
+ import resolvedTheme from './theme.resolved.json';
29
43
  </script>
30
44
 
31
45
  <template>
32
- <AxiomProvider :resolvedTheme="resolvedTheme">
46
+ <AxiomProvider :resolvedTheme="resolvedTheme" scope="global">
33
47
  <YourApp />
34
48
  </AxiomProvider>
35
49
  </template>
36
50
  ```
37
51
 
38
- ### Runtime Entry (Theme Composition)
52
+ ### Runtime Entry — Dynamic Theme Composition
39
53
 
40
- Full composition engine for dynamic themes:
54
+ Use the runtime entry when you need dynamic axis switching (e.g., light/dark mode toggle, brand switching, density control):
41
55
 
42
56
  ```vue
43
57
  <script setup>
44
- import { AxiomProviderRuntime } from "@axiom-core/vue-adapter/runtime";
45
- import primitives from "./primitives.json";
58
+ import { AxiomProviderRuntime } from '@axiom-core/vue-adapter/runtime';
59
+ import { createThemeManager } from '@axiom-core/runtime-engine';
60
+ import { enterprisePrimitives } from '@axiom-core/primitives';
61
+ import { baseSemantic, semanticAxes } from '@axiom-core/semantic-baseline';
62
+
63
+ const manager = createThemeManager({
64
+ primitives: enterprisePrimitives,
65
+ baseSemantic,
66
+ registry: semanticAxes,
67
+ initialConfig: { mode: 'light' },
68
+ });
46
69
  </script>
47
70
 
48
71
  <template>
49
- <AxiomProviderRuntime :primitives="primitives">
72
+ <AxiomProviderRuntime :manager="manager">
50
73
  <YourApp />
51
74
  </AxiomProviderRuntime>
52
75
  </template>
53
76
  ```
54
77
 
55
- ### Accessing Theme
78
+ ---
79
+
80
+ ## Provider Setup
81
+
82
+ `AxiomProvider` (base) and `AxiomProviderRuntime` (runtime) are both Vue 3 components that call Vue's `provide()` to make the Axiom context available to all descendant components.
83
+
84
+ #### Props — `AxiomProvider` (base entry)
85
+
86
+ | Prop | Type | Required | Description |
87
+ |---|---|---|---|
88
+ | `resolvedTheme` | `ResolvedSemanticTokens` | Yes | Pre-resolved theme object. All token references must already be resolved to primitive values. |
89
+ | `scope` | `string` | No | CSS scope identifier. Defaults to `'global'`. Use unique values for nested scoped providers. |
90
+ | `mode` | `'dev' \| 'prod'` | No | CSS variable naming mode. `dev` = readable names, `prod` = hashed names. |
91
+
92
+ #### Props — `AxiomProviderRuntime` (runtime entry)
93
+
94
+ | Prop | Type | Required | Description |
95
+ |---|---|---|---|
96
+ | `manager` | `ThemeManager` | Yes | A theme manager created by `createThemeManager()` from `@axiom-core/runtime-engine`. |
97
+ | `scope` | `string` | No | CSS scope identifier. |
98
+ | `mode` | `'dev' \| 'prod'` | No | CSS variable naming mode. |
99
+
100
+ ---
101
+
102
+ ## Reactive Updates
103
+
104
+ The Vue adapter integrates with Vue's reactivity system. When using the runtime entry, axis changes propagate automatically:
56
105
 
57
106
  ```vue
58
107
  <script setup>
59
- import { useAxiomTheme } from "@axiom-core/vue-adapter";
108
+ import { useAxiomTheme } from '@axiom-core/vue-adapter';
109
+
110
+ const { resolvedTheme, config, updateAxis } = useAxiomTheme();
60
111
 
61
- const theme = useAxiomTheme();
112
+ function toggleDarkMode() {
113
+ updateAxis('mode', config.value.mode === 'light' ? 'dark' : 'light');
114
+ }
62
115
  </script>
116
+
117
+ <template>
118
+ <button @click="toggleDarkMode">Toggle Dark Mode</button>
119
+ </template>
63
120
  ```
64
121
 
65
- ### Server-Side Rendering
122
+ ### `useAxiomTheme()` Composable
123
+
124
+ Returns reactive Axiom context from the nearest `AxiomProvider` ancestor.
125
+
126
+ | Return Value | Type | Description |
127
+ |---|---|---|
128
+ | `resolvedTheme` | `Ref<ResolvedSemanticTokens>` | Reactive resolved theme. Updates automatically when axes change. |
129
+ | `config` | `Ref<ThemeConfig>` | Reactive axis configuration. |
130
+ | `updateAxis` | `(axis: ThemeAxis, value: string) => void` | Updates a single axis (e.g., `'mode'`, `'brand'`) and triggers re-injection. |
131
+
132
+ ---
133
+
134
+ ## Variable Name Modes
135
+
136
+ | Mode | Variable Format | Use Case |
137
+ |---|---|---|
138
+ | `dev` | `--axiom-surface-background` | Human-readable names. Easier to debug in Vue DevTools. |
139
+ | `prod` | `--ax-a1b2c3` | Hashed names. Shorter, collision-free, minimal footprint. |
140
+
141
+ CSS variable values are identical in both modes. Only the property names differ.
142
+
143
+ ---
144
+
145
+ ## SSR Compatibility
146
+
147
+ `vue-adapter` is fully compatible with Vue SSR (Nuxt, `renderToString`, etc.). Use `renderAxiomStyles` to produce a `<style>` tag for injection into the server-rendered HTML:
66
148
 
67
149
  ```typescript
68
- import { getAxiomStyleTag } from "@axiom-core/vue-adapter";
150
+ import { renderAxiomStyles } from '@axiom-core/vue-adapter';
151
+
152
+ const { cssText, attributes } = renderAxiomStyles({
153
+ resolvedTheme,
154
+ mode: 'prod',
155
+ scope: 'global',
156
+ });
157
+
158
+ const html = `
159
+ <!DOCTYPE html>
160
+ <html>
161
+ <head>
162
+ <style id="axiom-ssr">${cssText}</style>
163
+ </head>
164
+ <body>${appHtml}</body>
165
+ </html>
166
+ `;
167
+ ```
168
+
169
+ On hydration, the client-side provider detects the existing SSR style tag and skips the initial injection to avoid a flash of unstyled content.
69
170
 
70
- const styleTag = getAxiomStyleTag(resolvedTheme);
71
- // Inject styleTag into server-rendered HTML
171
+ #### Nuxt Integration
172
+
173
+ ```typescript
174
+ // plugins/axiom.ts
175
+ import { defineNuxtPlugin } from '#app';
176
+ import { createThemeManager } from '@axiom-core/runtime-engine';
177
+ import { enterprisePrimitives } from '@axiom-core/primitives';
178
+ import { baseSemantic, semanticAxes } from '@axiom-core/semantic-baseline';
179
+
180
+ export default defineNuxtPlugin(() => {
181
+ const manager = createThemeManager({
182
+ primitives: enterprisePrimitives,
183
+ baseSemantic,
184
+ registry: semanticAxes,
185
+ initialConfig: { mode: 'light' },
186
+ });
187
+ return { provide: { axiomManager: manager } };
188
+ });
72
189
  ```
73
190
 
74
- ## Architecture
191
+ ---
192
+
193
+ ## Bundle Entries
194
+
195
+ | Import Path | Contents | When to Use |
196
+ |---|---|---|
197
+ | `@axiom-core/vue-adapter` | Provider + composables (no runtime engine) | Pre-resolved themes |
198
+ | `@axiom-core/vue-adapter/runtime` | Above + `AxiomProviderRuntime` component | Dynamic theme composition |
75
199
 
76
- This adapter strictly conforms to the Axiom Adapter Interface Specification v1.0.
200
+ ---
77
201
 
78
- - **Dual Entry Architecture:** Separate base and runtime entries for optimal bundle size
79
- - **Deterministic CSS:** Byte-identical output across all framework adapters
80
- - **Shared Infrastructure:** Delegates to @axiom-core/css-bridge, @axiom-core/dom-injector, @axiom-core/ssr-utils
81
- - **Tree-Shakeable:** `sideEffects: false` with proper DCE support
82
- - **SSR Safe:** Full server-side rendering and hydration support
202
+ ## Peer Dependencies
83
203
 
84
- ## Bundle Size
204
+ | Package | Version |
205
+ |---|---|
206
+ | `vue` | `>=3` |
207
+ | `@axiom-core/runtime-engine` | `>=0.1.0` (optional — only for runtime entry) |
208
+ | `@axiom-core/core-engine` | `>=0.1.0` (optional — only for runtime entry) |
85
209
 
86
- - **Base Entry:** Target ≤6 KB (minified + gzipped)
87
- - **Runtime Entry:** Target ≤18 KB (minified + gzipped)
210
+ ---
88
211
 
89
212
  ## License
90
213
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@axiom-core/vue-adapter",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Official Axiom Design System adapter for Vue 3",
5
5
  "author": "Axiom Platform Architecture Team",
6
6
  "license": "MIT",
@@ -18,10 +18,10 @@
18
18
  "CONFORMANCE.md"
19
19
  ],
20
20
  "dependencies": {
21
- "@axiom-core/css-bridge": "0.1.0",
22
- "@axiom-core/token-schema": "0.1.0",
23
- "@axiom-core/dom-injector": "0.1.0",
24
- "@axiom-core/ssr-utils": "0.1.0"
21
+ "@axiom-core/css-bridge": "0.1.1",
22
+ "@axiom-core/ssr-utils": "0.1.1",
23
+ "@axiom-core/token-schema": "0.1.1",
24
+ "@axiom-core/dom-injector": "0.1.1"
25
25
  },
26
26
  "devDependencies": {
27
27
  "@types/node": "^20.0.0",
@@ -30,12 +30,12 @@
30
30
  "typescript": "^5.3.0",
31
31
  "vitest": "^1.0.0",
32
32
  "vue": "^3.4.0",
33
- "@axiom-core/invariant-engine": "0.1.0",
34
- "@axiom-core/core-engine": "0.1.0"
33
+ "@axiom-core/invariant-engine": "0.1.1",
34
+ "@axiom-core/core-engine": "0.1.1"
35
35
  },
36
36
  "peerDependencies": {
37
- "@axiom-core/core-engine": ">=0.1.0",
38
- "@axiom-core/invariant-engine": ">=0.1.0",
37
+ "@axiom-core/core-engine": ">=0.1.1",
38
+ "@axiom-core/invariant-engine": ">=0.1.1",
39
39
  "vue": ">=3.0.0"
40
40
  },
41
41
  "peerDependenciesMeta": {