feat(ui-vue,roxy-data,format): add Vue wrappers, fix the WordPress render regression and the wall-clock DST bug

Author: ph33nx

.github/workflows/release.yml

@@ -36,6 +36,34 @@ jobs:
 
       - run: bun install --frozen-lockfile
 
+      # Trusted publishing (OIDC) CANNOT create a package. npmjs.com requires the
+      # package to already exist before a Trusted Publisher can be configured on it,
+      # so the first version of any new package must be pushed by a human once
+      # (npm/cli#8544, still open).
+      #
+      # Without this gate the run would publish @roxyapi/ui and @roxyapi/ui-react,
+      # THEN die on the first-ever @roxyapi/ui-vue publish. The job aborts before
+      # "Commit, tag, push", so npm ends up bumped while the repo has no version
+      # commit, no tag and no GitHub release, and the re-run is then rejected for
+      # republishing an existing version. Fail BEFORE anything is published instead.
+      - name: Preflight — every package must already exist on npm
+        run: |
+          MISSING=""
+          for pkg in packages/ui packages/ui-react packages/ui-vue; do
+            NAME=$(jq -r '.name' "$pkg/package.json")
+            npm view "$NAME" version >/dev/null 2>&1 || MISSING="$MISSING $NAME"
+          done
+          if [ -n "$MISSING" ]; then
+            echo "::error::Never published, so OIDC cannot publish it either:$MISSING"
+            echo "Bootstrap each package ONCE from a logged-in machine:"
+            echo "    (cd packages/<name> && npm publish --access public)"
+            echo "then on npmjs.com open the package and set"
+            echo "    Trusted Publisher -> GitHub Actions -> RoxyAPI/ui -> release.yml"
+            echo "Re-run this workflow afterwards. See npm/cli#8544."
+            exit 1
+          fi
+          echo "All packages exist on npm. Trusted publishing can proceed."
+
       - name: Regenerate types from spec
         run: bun run generate
 
@@ -131,6 +159,7 @@ jobs:
           }
           bump packages/ui
           bump packages/ui-react
+          bump packages/ui-vue
           VERSION=$(jq -r '.version' packages/ui/package.json)
           echo "version=$VERSION" >> $GITHUB_OUTPUT
           bun run build
@@ -146,6 +175,11 @@ jobs:
         run: |
           (cd packages/ui-react && npm publish --access public --provenance)
 
+      - name: Publish @roxyapi/ui-vue
+        if: steps.diff.outputs.changed == 'true' || github.event_name == 'workflow_dispatch'
+        run: |
+          (cd packages/ui-vue && npm publish --access public --provenance)
+
       - name: Commit, tag, push
         if: steps.diff.outputs.changed == 'true' || github.event_name == 'workflow_dispatch'
         run: |
@@ -166,6 +200,7 @@ jobs:
           mkdir -p .release-assets
           (cd packages/ui && npm pack --pack-destination ../../.release-assets)
           (cd packages/ui-react && npm pack --pack-destination ../../.release-assets)
+          (cd packages/ui-vue && npm pack --pack-destination ../../.release-assets)
           ls -la .release-assets/
 
       - name: Create GitHub release

.gitignore

@@ -9,18 +9,19 @@ node_modules/
 # the live one before a release goes out.
 packages/ui/src/types/
 
-# packages/ui/dist and packages/ui-react/dist are pure build output. The
+# packages/ui/dist and the wrapper-package dist dirs are pure build output. The
 # Release workflow runs `bun run build` then `npm publish`, which includes
 # dist via each package.json `files` allowlist; the Pages workflow rebuilds
 # before deploy. Nothing serves dist from the git repo (the shadcn registry
 # is served from `@main`, dist is served from npm via jsDelivr), so dist
 # never needs to be git-tracked.
 packages/ui/dist/
 packages/ui-react/dist/
+packages/ui-vue/dist/
 
 # Root README.md, LICENSE, and AGENTS.md are the canonical source files.
 # `copyRootDocsToWorkspaces` in `scripts/build.ts` mirrors all three into
-# both packages on every `bun run build` so the npm tarballs (which ship
+# every package on every `bun run build` so the npm tarballs (which ship
 # these files via each package.json `files` allowlist) carry an up-to-date
 # copy. The per-package copies are build artifacts; never edit them
 # directly, edit the root files only.
@@ -30,6 +31,9 @@ packages/ui/AGENTS.md
 packages/ui-react/README.md
 packages/ui-react/LICENSE
 packages/ui-react/AGENTS.md
+packages/ui-vue/README.md
+packages/ui-vue/LICENSE
+packages/ui-vue/AGENTS.md
 
 # apps/docs/dist is mirrored from packages/ui/dist on each `bun run build`
 # so local preview at apps/docs/ matches the GitHub Pages layout exactly.

AGENTS.md

@@ -2,7 +2,7 @@
 
 This file teaches AI coding agents (Claude Code, Cursor, Copilot, Codex, Gemini CLI, and any MCP-compatible client) how to use Roxy UI when integrating RoxyAPI into a project.
 
-This file ships inside both `@roxyapi/ui` and `@roxyapi/ui-react` on npm. After install, read it at `node_modules/@roxyapi/ui/AGENTS.md`.
+This file ships inside `@roxyapi/ui`, `@roxyapi/ui-react`, and `@roxyapi/ui-vue` on npm. After install, read it at `node_modules/@roxyapi/ui/AGENTS.md`.
 
 Live preview: <https://roxyapi.github.io/ui/>. Source of truth for component types: the combined OpenAPI spec at `https://roxyapi.com/api/v2/openapi.json`, regenerated into `packages/ui/src/types/types.gen.ts`. Per-product specs live at `https://roxyapi.com/api/v2/{slug}/openapi.json`.
 
@@ -96,7 +96,7 @@ Use the table below for the formal endpoint to component mapping.
 | `<roxy-forecast-timeline>` | Forecast | POST /forecast/timeline | Date-grouped events across Western, Vedic, and biorhythm domains, weighted by significance |
 | `<roxy-forecast-digest>` | Forecast | POST /forecast/digest | Per-window event counts, domain breakdown, and the highest-significance events |
 | `<roxy-biorhythm-chart>` | Biorhythm | POST /biorhythm/{daily,forecast,critical-days} | Daily bars, forecast cycle lines, critical days |
-| `<roxy-hexagram>` | I Ching | GET /iching/hexagrams/{number}, /iching/cast, POST /iching/daily, /iching/daily/cast | Hexagram with trigrams, judgment, image, changing lines |
+| `<roxy-hexagram>` | I Ching | GET /iching/hexagrams/{number}, /iching/cast, POST /iching/daily, /iching/daily/cast | Hexagram figure with trigrams, judgment, image, and a reading per line (statement plus meaning); a cast highlights the moving lines and the resulting hexagram |
 | `<roxy-crystal-card>` | Crystals | GET /crystals/{id} | Photo, meaning sections, chakra, zodiac, element, hardness, keywords, and pairings |
 | `<roxy-crystal-grid>` | Crystals | GET /crystals, /crystals/chakra/{chakra}, /crystals/element/{element}, /crystals/zodiac/{sign}, /crystals/birthstone/{month}, /crystals/search | Crystal gallery tiles with photo, name, and colour swatches |
 | `<roxy-dream-card>` | Dreams | GET /dreams/symbols/{id} | Symbol name, interpretation body, and letter chip |
@@ -201,7 +201,24 @@ Several components select a view, mode, or chart layout in addition to `data`. T
 <RoxyPanchangTable data={panchang} detail="detailed" />
 ```
 
-The full set: `RoxyNatalChart` `houseSystem`, `RoxyHoroscopeCard` `period`, `RoxyMoonPhase` `mode`, `RoxyCompatibilityCard` `mode`, `RoxyVedicKundli` and `RoxyDivisionalChart` `chartStyle`, `RoxyPanchangTable` `detail`, `RoxyDashaTimeline` `period`, `RoxyDoshaCard` `type`, `RoxyNumerologyCard` `type`, `RoxyTarotSpread` `spread`, `RoxyBiorhythmChart` `mode`, `RoxyHexagram` `mode`. Outside React, set the same value as a kebab-case attribute or a JS property on the element (for example `chart-style="south"` or `el.chartStyle = 'south'`).
+The full set: `RoxyNatalChart` `houseSystem`, `RoxyHoroscopeCard` `period`, `RoxyMoonPhase` `mode`, `RoxyCompatibilityCard` `mode`, `RoxyVedicKundli` and `RoxyDivisionalChart` `chartStyle`, `RoxyPanchangTable` `detail`, `RoxyDashaTimeline` `period`, `RoxyDoshaCard` `type`, `RoxyNumerologyCard` `type`, `RoxyTarotSpread` `spread`, `RoxyBiorhythmChart` `mode`, `RoxyHexagram` `mode`. Outside React and Vue, set the same value as a kebab-case attribute or a JS property on the element (for example `chart-style="south"` or `el.chartStyle = 'south'`).
+
+### 6c. Vue and Nuxt
+
+`@roxyapi/ui-vue` exposes the same components with the same prop names. Bind `data` and the config props normally; the package sets them as DOM properties for you, so an object payload never gets stringified into an attribute. Listen to widget events with the usual `@` syntax.
+
+```vue
+<script setup lang="ts">
+import { RoxyVedicKundli, RoxyLocationSearch } from '@roxyapi/ui-vue';
+</script>
+
+<template>
+	<RoxyVedicKundli :data="chart" chart-style="south" />
+	<RoxyLocationSearch @roxy-location-select="onCity" />
+</template>
+```
+
+In Nuxt, render these in a client context (`<ClientOnly>` or a `.client.vue` component): they mount Custom Elements and need the DOM, the same constraint as `'use client'` in the Next.js App Router.
 
 ### 7. Local response interface drift
 
@@ -451,8 +468,8 @@ When listing domains in user-visible copy, use the canonical order: Western astr
 
 ## What not to ship
 
-- Do not bundle `@roxyapi/ui` and `@roxyapi/ui-react` together; they ship independently.
-- Use `@roxyapi/ui-react` for React projects. Use `@roxyapi/ui` directly elsewhere.
+- Do not bundle `@roxyapi/ui` with `@roxyapi/ui-react` or `@roxyapi/ui-vue`; they ship independently.
+- Use `@roxyapi/ui-react` for React projects and `@roxyapi/ui-vue` for Vue and Nuxt projects. Use `@roxyapi/ui` directly elsewhere.
 - Do not write your own kundli component. The lifted layout in `<roxy-vedic-kundli>` is the canonical RoxyAPI render path.
 - Do not call astrology endpoints with hardcoded coordinates. Always geocode first via `<roxy-location-search>` or `roxy.location.searchCities()`.
 - Do not declare a local `interface XyzData` to describe a RoxyAPI response. Import the type from the spec-derived bundle: `import type { XyzResponse } from '@roxyapi/sdk'`. Local interfaces drift the moment the spec changes.

README.md

@@ -196,7 +196,7 @@ Every chart, table, and card adapts to light and dark automatically. Hover any i
 <td width="50%"><strong>I Ching hexagram</strong> · <code>&lt;roxy-hexagram&gt;</code><br><sub>GET /iching/hexagrams/&lbrace;number&rbrace;, /iching/cast</sub><br>
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/hexagram-dark.png">
-  <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/hexagram-light.png" alt="Hexagram with trigrams, judgment, image, changing lines">
+  <img src="https://raw.githubusercontent.com/RoxyAPI/ui/main/assets/screenshots/hexagram-light.png" alt="Hexagram figure with trigrams, judgment, image, and a reading for every line">
 </picture>
 </td>
 <td width="50%"><strong>Numerology</strong> · <code>&lt;roxy-numerology-card&gt;</code><br><sub>POST /numerology/&lbrace;life-path,expression,personal-year,chart&rbrace;</sub><br>
@@ -268,6 +268,24 @@ export function Chart({ data }: { data: NatalChart }) {
 }
 ```
 
+Vue users get the same typed surface.
+
+```bash
+npm install @roxyapi/ui-vue
+```
+
+```vue
+<script setup lang="ts">
+import { RoxyNatalChart } from '@roxyapi/ui-vue';
+
+defineProps<{ data: NatalChart }>();
+</script>
+
+<template>
+	<RoxyNatalChart :data="data" />
+</template>
+```
+
 ## Quick start
 
 ```ts
@@ -298,6 +316,24 @@ Serialize with the shipped helper, never a bare `JSON.stringify`. `@roxyapi/ui`
 
 Load the bundle once anywhere on the page. It registers every `roxy-*` element and loads the design tokens, so every component on the page renders themed, in light or dark, from that single tag. Nothing else to add.
 
+### No-JavaScript fallback
+
+The two modes degrade differently, and only one of them can be rescued.
+
+**Controlled mode** (the `<script class="roxy-data">` island above) already holds the reading in the page. Render it server-side as ordinary HTML alongside the island and put that markup *inside* the element. Components render into a shadow root and none of them expose a `<slot>`, so light-DOM children are painted only while the element is un-upgraded, and disappear the moment the bundle registers it. You get the server HTML without JavaScript and the live component with it, from the same markup, with no flash of both.
+
+**Form mode** (`data-endpoint` + a `pk_` key) is a self-fetch widget: it cannot work without JavaScript, because there is nothing to render until the visitor submits the form. Give it a light-DOM fallback that says so and links out.
+
+```html
+<roxy-natal-chart data-endpoint="astrology/natal-chart" publishable-key="pk_live_…">
+  <!-- Painted only when JavaScript is off. Replaced by the component otherwise. -->
+  <p>JavaScript is required to generate this chart.
+     <a href="https://roxyapi.com/products/astrology">Open it on roxyapi.com</a>.</p>
+</roxy-natal-chart>
+```
+
+A `<noscript>` block works too, and is the safer choice if you also need to hide the fallback from screen readers once the component takes over.
+
 ```ts
 import { roxyDataScript } from '@roxyapi/ui';
 
@@ -570,6 +606,7 @@ Set `ROXY_API_KEY` to your secret key in your server env for the server-side SDK
 |---|---|
 | npm `@roxyapi/ui` | `npmjs.com/package/@roxyapi/ui` |
 | npm `@roxyapi/ui-react` | `npmjs.com/package/@roxyapi/ui-react` |
+| npm `@roxyapi/ui-vue` | `npmjs.com/package/@roxyapi/ui-vue` |
 | jsDelivr CDN (full bundle) | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/roxy-ui.js` |
 | jsDelivr CDN (per component) | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/components/{name}.js` |
 | Widgets auto-mount (with browser keys, coming soon) | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/widgets.js` |
@@ -624,7 +661,7 @@ Set `ROXY_API_KEY` to your secret key in your server env for the server-side SDK
 | `<roxy-forecast-timeline>` | Forecast | POST /forecast/timeline | Date-grouped events across Western, Vedic, and biorhythm domains, weighted by significance |
 | `<roxy-forecast-digest>` | Forecast | POST /forecast/digest | Per-window event counts, domain breakdown, and the highest-significance events |
 | `<roxy-biorhythm-chart>` | Biorhythm | POST /biorhythm/{daily,forecast,critical-days} | Daily bars, forecast cycle lines, critical days |
-| `<roxy-hexagram>` | I Ching | GET /iching/hexagrams/{number}, /iching/cast, POST /iching/daily, /iching/daily/cast | Hexagram with trigrams, judgment, image, changing lines |
+| `<roxy-hexagram>` | I Ching | GET /iching/hexagrams/{number}, /iching/cast, POST /iching/daily, /iching/daily/cast | Hexagram figure with trigrams, judgment, image, and a reading per line (statement plus meaning); a cast highlights the moving lines and the resulting hexagram |
 | `<roxy-crystal-card>` | Crystals | GET /crystals/{id} | Photo, meaning sections, chakra, zodiac, element, hardness, keywords, and pairings |
 | `<roxy-crystal-grid>` | Crystals | GET /crystals, /crystals/chakra/{chakra}, /crystals/element/{element}, /crystals/zodiac/{sign}, /crystals/birthstone/{month}, /crystals/search | Crystal gallery tiles with photo, name, and colour swatches |
 | `<roxy-dream-card>` | Dreams | GET /dreams/symbols/{id} | Symbol name, interpretation body, and letter chip |
@@ -673,7 +710,7 @@ roxy-natal-chart {
 
 ## Built for AI agents
 
-[`AGENTS.md`](AGENTS.md) is bundled inside both npm packages. Once installed, agents can read it from `node_modules/@roxyapi/ui/AGENTS.md` (or `@roxyapi/ui-react/AGENTS.md`) for the component decision tree, integration patterns, and rules.
+[`AGENTS.md`](AGENTS.md) is bundled inside every npm package. Once installed, agents can read it from `node_modules/@roxyapi/ui/AGENTS.md` (or `@roxyapi/ui-react/AGENTS.md`, `@roxyapi/ui-vue/AGENTS.md`) for the component decision tree, integration patterns, and rules.
 
 - Works with Claude Code, Cursor, Copilot, Codex, Gemini CLI, and any MCP-compatible client.
 - Component decision tree maps each RoxyAPI endpoint to the component that renders its response.
@@ -732,7 +769,7 @@ Persist the choice in `localStorage` from your own code; the components do not o
 <details>
 <summary><strong>How big is each component? What is the bundle cost?</strong></summary>
 
-Per-component bundles run 9-21 KB gzipped, capped at 30 KB by CI. The full bundle (every component, helpers, base styles, and the inlined design tokens) stays well under the 150 KB CI cap, around 85 KB gzipped today. The React package loads the runtime on mount, so a route that renders one chart pays for one component, not the whole catalog. Pin a concrete version in production for byte-stable cache hits.
+Per-component bundles run 9-21 KB gzipped, capped at 30 KB by CI. The full bundle (every component, helpers, base styles, and the inlined design tokens) stays well under the 150 KB CI cap, around 85 KB gzipped today. The React and Vue packages load the runtime on mount, so a route that renders one chart pays for one component, not the whole catalog. Pin a concrete version in production for byte-stable cache hits.
 </details>
 
 <details>