feat(widgets): spec-driven inputs, practitioner theme, one-tag widgets.js

Turn the components into copy-paste widgets for non-technical site owners. Everything derives from the spec, the manifest, and the bindings, so a new endpoint or component flows through with zero widget code.

Input system v2: a param-shape registry maps every spec param to an input kind (sign tile picker with glyphs, filterable select above 12 options, boolean toggle, date, time, number, text). Required fields render visible, optional fields collapse under one Advanced disclosure, and a form whose only visible required field is an enum submits on selection. Adds lang, submit-label and attribution attributes, person-group cards, visible validation, and a sticky picker with an Edit affordance.

Perf: per-operation schema slices at dist/schemas replace the 1.5 MB runtime spec fetch, keeping the full-spec fetch as a fallback.

Security: location-search now fails closed on a secret key like every other component, via a shared key guard.

Theme: new --roxy-font-display token (defaults to sans) plus dist/styles/themes/practitioner.css, a rosewater light and dark preset. The Customise dialog gains a Presets dropdown.

widgets.js: the hardcoded 16-entry endpoint map is gone. The map is generated at build from bindings x manifest x spec (51 slugs). When every required param is present as data attributes it fetches immediately, otherwise it renders form mode. Guarded against double-defining elements when the full bundle is also on the page.

Demo: a fourth Embed tab per card, derived from the bindings mirror with zero per-card authoring.

CI: a bundle-size gate (150 KB gzip full, 30 KB gzip per component, 8 KB raw widgets.js) wired into ci.yml and lefthook, plus a taxonomy gate asserting every spec param resolves to a known input kind.

Spec reconciled with live, picking up the human-design nodeType toggle.

All changes are additive. Controlled mode, tag names, token names and event names are unchanged, so the WordPress plugin contract and every data-prop consumer stay unaffected.

Author: ph33nx

.github/workflows/ci.yml

@@ -29,6 +29,8 @@ jobs:
       - run: bun run typecheck
       - run: bun run build
       - run: bun run test
+      - name: Bundle-size budget (gzip full + per-component, raw widgets.js)
+        run: bun run size:check
 
       # packages/ui-{react,vue}/src is GENERATED from packages/ui. A diff here
       # means generated output was hand-edited; the next build would revert it.

AGENTS.md

@@ -362,7 +362,7 @@ For a static chart with no picker, fetch in a Server Component and pass `data` t
 
 ### Pattern 3: schema-driven form
 
-`<roxy-endpoint-form>` reads the OpenAPI spec and renders the inputs for any endpoint. On `roxy-submit`, POST the validated values to your own route, which calls the SDK with the secret key, then set the returned data on the target component.
+`<roxy-endpoint-form>` reads the OpenAPI spec and renders the inputs for any endpoint. On `roxy-submit`, POST the validated values to your own route, which calls the SDK with the secret key, then set the returned data on the target component. For an endpoint that needs coordinates, add `publishable-key="pk_live_..."` so the built-in city search can geocode.
 
 ```html
 <roxy-endpoint-form
@@ -393,7 +393,7 @@ When you do not want a backend at all, mint a **publishable key** (`pk_live_*` /
 ></roxy-natal-chart>
 ```
 
-That single element shows a schema-driven form (city search included for endpoints that need coordinates), fetches on submit, shows a loading then error-or-result state, and re-shows the form so the user can try another query. `method` defaults to `POST`; set `method="GET"` for GET endpoints. Set `data-endpoint` to the spec path without the leading slash (`dreams/symbols/{id}`, `astrology/horoscope/{sign}/daily`).
+That single element renders a schema-driven form (a zodiac/enum tile picker, a boolean toggle, native date and time inputs, and a city search for endpoints that need coordinates), fetches on submit, and shows a loading then error-or-result state. Optional fields collapse under one Advanced disclosure, and a form whose only required field is an enum submits on selection (tap a sign, get a reading, no button). The result keeps a re-query affordance: a single-enum picker stays above the result and refetches when the selection changes, any other form gets a compact Edit query control that restores it with the previous values. `method` defaults to `POST`; set `method="GET"` for GET endpoints. Set `data-endpoint` to the spec path without the leading slash (`dreams/symbols/{id}`, `astrology/horoscope/{sign}/daily`).
 
 **Key handling is the contract. The component enforces it, not you:**
 
@@ -403,6 +403,12 @@ That single element shows a schema-driven form (city search included for endpoin
 
 In React, the same props are typed: `<RoxyNatalChart endpoint="astrology/natal-chart" publishableKey={process.env.NEXT_PUBLIC_ROXY_PK} />`.
 
+**Three optional attributes on the self-fetch element.** `lang` sets the response language (`en`, `tr`, `de`, `es`, `hi`, `pt`, `fr`, `ru`): put it on the element (`<roxy-horoscope-card lang="de" ...>`) and the form routes it to the `?lang=` query on submit, so visitors never see a language field. `submit-label` overrides the derived button label. `attribution` renders a small "Spiritual data by RoxyAPI" credit under the result: off by default, and the one-tag script below turns it on unless you set `data-attribution="off"`. None of these apply in controlled mode.
+
+**One tag, no element wiring.** For the simplest embed, load `dist/cdn/widgets.js` and drop a `<div data-roxy-widget="{slug}" data-publishable-key="pk_live_...">`. The script mounts the matching component from a generated slug map: with every path parameter supplied as a `data-*` attribute (`data-sign`, `data-id`) it fetches on mount, otherwise it renders the same input form. A second `data-*` attribute picks a variant (`data-period`, `data-mode`, `data-type`, `data-spread`).
+
+**Theme every widget in one link.** Add `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/styles/themes/practitioner.css">` for a warm rosewater serif look, or set the `--roxy-font-display` token alone to swap result headings to a display face (it defaults to the body font, so nothing changes until you set it). See [THEMING.md](packages/ui/THEMING.md).
+
 ### Pattern 5: MCP tool-call response
 
 A remote MCP server at `roxyapi.com/mcp/{domain}` exposes each RoxyAPI endpoint as an MCP tool. The JSON returned by the tool call has the same shape as the SDK response. Pass it straight into the matching component.
@@ -490,7 +496,7 @@ const { data } = await roxy.humanDesign.generateBodygraph({
 });
 ```
 
-`lang` is a query parameter even on a POST endpoint. Put it in `query`, never in `body`; a `lang` key in the body is ignored and you get English back. In the self-fetch pattern the component reads the parameter from the spec and sends it correctly, so the generated form simply offers the language as a field.
+`lang` is a query parameter even on a POST endpoint. Put it in `query`, never in `body`; a `lang` key in the body is ignored and you get English back. In the self-fetch pattern you do not fill a language field: set `lang` as an attribute on the element (`<roxy-horoscope-card lang="de" ...>`) and the form routes it to the `?lang=` query on submit.
 
 The structural labels the components draw (section headings such as Reading or Centers, and column headers) are English.
 

README.md

@@ -602,6 +602,8 @@ Two ways to feed a component, and the key rule for each:
 
 Set `ROXY_API_KEY` to your secret key in your server env for the server-side SDK examples on this page. For self-fetch embedding with no backend, use a publishable key (see the fully client-side pattern in [`AGENTS.md`](AGENTS.md)).
 
+The self-fetch form renders spec-driven inputs (a zodiac tile picker, a boolean toggle, native date and time, a city search), collapses optional fields under one Advanced disclosure, and reads a `lang` attribute for localized responses. For the simplest embed, load `dist/cdn/widgets.js` and drop one `<div data-roxy-widget="{slug}" data-publishable-key="pk_live_...">`: with the required attributes present it fetches on mount, otherwise it renders the form. A single `<link>` to the [practitioner theme preset](https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/styles/themes/practitioner.css) restyles every widget on the page.
+
 ## Distribution
 
 | Surface | URL |
@@ -611,7 +613,8 @@ Set `ROXY_API_KEY` to your secret key in your server env for the server-side SDK
 | 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` |
+| Widgets auto-mount (one tag, browser keys) | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn/widgets.js` |
+| Practitioner theme preset (one link, warm rosewater) | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/styles/themes/practitioner.css` |
 | shadcn registry | `npx shadcn@latest add https://cdn.jsdelivr.net/gh/RoxyAPI/ui@latest/registry/{name}.json` |
 | Components catalog (JSON: every component, domain, and endpoint) | `cdn.jsdelivr.net/npm/@roxyapi/ui@latest/components-catalog.json` |
 
@@ -771,7 +774,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 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.
+Per-component bundles run 13-26 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 108 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>
@@ -895,11 +898,11 @@ For CSP, allow `script-src https://cdn.jsdelivr.net` if loading the bundle from
 Semver. Pre-1.0, minor bumps may include breaking changes (we will note them in the changelog). Patch bumps are always backwards-compatible. Pin a concrete version in production code:
 
 ```bash
-npm install @roxyapi/ui@0.8.x
+npm install @roxyapi/ui@0.15.x
 ```
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@0.8.0/dist/cdn/roxy-ui.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@0.15.0/dist/cdn/roxy-ui.js"></script>
 ```
 
 The `@latest` URL on this page is for paste-friendly marketing; production code should pin.

apps/docs/components-manifest.js

@@ -25,17 +25,74 @@ const PERSON2 = {
 
 const REGISTRY_BASE = 'https://cdn.jsdelivr.net/gh/RoxyAPI/ui@main/registry';
 const UI_CDN = 'https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/cdn';
+const PRACTITIONER_THEME_URL =
+	'https://cdn.jsdelivr.net/npm/@roxyapi/ui@latest/dist/styles/themes/practitioner.css';
 
 const MANIFEST_BY_TAG = Object.fromEntries(
 	(window.ROXY_COMPONENTS || []).map((c) => [c.tag, c]),
 );
 
+// Generated endpoint map (window.ROXY_ENDPOINT_BINDINGS, mirrored by
+// scripts/sync-manifest.ts). The Embed tab derives from it, so a binding change
+// flows through with no per-card edit here.
+const ENDPOINT_BINDINGS = window.ROXY_ENDPOINT_BINDINGS || {};
+
 function lookup(tag) {
 	const meta = MANIFEST_BY_TAG[tag];
 	if (!meta) throw new Error(`Unknown tag in demo manifest: ${tag}`);
 	return meta;
 }
 
+/**
+ * Derive the Embed-tab snippets for an endpoint-bound component from its tag,
+ * slug, and the generated endpoint bindings. The tag's FIRST binding (the
+ * widgets-map default; bindings are path-sorted) drives both the script-mode
+ * element and the one-tag widgets.js div, so there is zero per-card authoring.
+ * Returns null for a component with no binding (the three helpers), and the demo
+ * hides the tab for those.
+ */
+function embedSnippet(tag, slug) {
+	const bindings = ENDPOINT_BINDINGS[tag];
+	if (!bindings || !bindings.length) return null;
+	const def = bindings[0];
+	const endpoint = def.path.replace(/^\//, '');
+	// POST is the element default, so only a GET binding needs an explicit method.
+	const methodAttr = def.method === 'POST' ? '' : ` method="${def.method}"`;
+	// The default variant's selector attribute (period/mode/type/spread/detail),
+	// so the script element renders the same view the one-tag default resolves to.
+	const configAttr = def.attrs
+		? Object.entries(def.attrs)
+				.map(([k, v]) => ` ${k}="${v}"`)
+				.join('')
+		: '';
+
+	const script = `<!-- Optional: warm practitioner theme (drop this line for the default look) -->
+<!-- <link rel="stylesheet" href="${PRACTITIONER_THEME_URL}"> -->
+<script src="${UI_CDN}/roxy-ui.js" defer></script>
+<${tag}${configAttr} data-endpoint="${endpoint}"${methodAttr} publishable-key="pk_live_..." lang="en"></${tag}>`;
+
+	const oneTag = `<script src="${UI_CDN}/widgets.js" defer></script>
+<div data-roxy-widget="${slug}" data-publishable-key="pk_live_..."></div>`;
+
+	// The selector attribute and its non-default values, surfaced on the hint line
+	// so one data-* attribute on the one-tag div switches variant.
+	const selector = def.attrs ? Object.keys(def.attrs)[0] : undefined;
+	const otherValues = selector
+		? bindings
+				.slice(1)
+				.map((b) => b.attrs && b.attrs[selector])
+				.filter(Boolean)
+		: [];
+	const variantHint =
+		selector && otherValues.length
+			? ` Switch variant with data-${selector} (${otherValues.map((v) => `"${v}"`).join(', ')}) on the one-tag div.`
+			: '';
+
+	const hint = `Mint a publishable key at roxyapi.com/account, register the origins you embed on, and replace the pk_live_ placeholder. Works on any site that allows script tags.${variantHint}`;
+
+	return { script, oneTag, hint };
+}
+
 function serverRender(tag, body) {
 	// body is indented one level for the shadcn RSC block; dedent it to sit at
 	// the top level of this standalone server snippet.
@@ -84,6 +141,8 @@ function entry({ id, tag, seoLine, heading, topic, attrs = '', sdkCall, code, sh
 		attrs,
 		code: code ?? serverRender(tag, sdkCall),
 		shadcn: shadcnOverride ?? shadcn(tag, sdkCall),
+		// null for the three unbound helpers, so page.js hides the Embed tab.
+		embed: embedSnippet(tag, meta.slug),
 	};
 }
 

apps/docs/index.html

@@ -340,6 +340,27 @@
 		}
 		.copy-btn:hover { color: var(--roxy-fg); border-color: var(--roxy-fg); }
 
+		/* The card is a flex column and the grid cell is minmax(0, 1fr), but a
+		 * flex/grid item defaults to min-width: auto, so a long jsDelivr line in a
+		 * <pre> sets the card min-content wide and the pre never scrolls: it drags
+		 * the whole card past its cell and gets clipped. min-width: 0 lets the
+		 * panel shrink so the pre's own overflow-x scrollbar takes over. */
+		[role="tabpanel"] { min-width: 0; }
+		.code-block, .code-block pre { min-width: 0; }
+
+		.embed-panel .embed-lead {
+			margin: 0;
+			font-size: 0.8125rem;
+			font-weight: 500;
+			color: var(--roxy-fg);
+		}
+		.embed-panel .embed-hint {
+			margin: 0;
+			font-size: 0.78125rem;
+			line-height: 1.5;
+			color: var(--roxy-muted);
+		}
+
 		.quickstart {
 			background: color-mix(in srgb, var(--roxy-border) 14%, transparent);
 			border: 1px solid var(--roxy-border);
@@ -592,7 +613,7 @@
 				"name": "How do I theme RoxyAPI UI components?",
 				"acceptedAnswer": {
 					"@type": "Answer",
-					"text": "Override CSS custom properties on the root or per element. About 30 design tokens cover color, typography, spacing, radius, shadow, and motion. No Tailwind required, no class-name overrides, no rebuild step. Light and dark defaults are built in. The Customize Colors panel on this page generates the override CSS for you."
+					"text": "Override CSS custom properties on the root or per element. About 47 design tokens cover color, typography, spacing, radius, shadow, and motion. No Tailwind required, no class-name overrides, no rebuild step. Light and dark defaults are built in. The Customize Colors panel on this page generates the override CSS for you."
 				}
 			}
 		]
@@ -774,7 +795,7 @@ <h2 id="faq-title">Frequently asked</h2>
 			</details>
 			<details>
 				<summary>How do I theme components?</summary>
-				<p>Override CSS custom properties on the root or per element. About 30 design tokens cover color, typography, spacing, radius, shadow, and motion. The Customize Colors panel above generates the override CSS for you.</p>
+				<p>Override CSS custom properties on the root or per element. About 47 design tokens cover color, typography, spacing, radius, shadow, and motion. The Customize Colors panel above generates the override CSS for you.</p>
 			</details>
 		</section>
 
@@ -787,6 +808,13 @@ <h2 id="customize-title">Customize colors</h2>
 				<p style="color: var(--roxy-muted); font-size: 0.875rem; margin: 0 0 0.875rem;">
 					Override CSS custom properties on <code>:root</code> for light, on <code>:root[data-theme="dark"]</code> for dark. Edits below preview live.
 				</p>
+				<div class="preset-row" style="display: flex; align-items: center; gap: 0.5rem; margin-bottom: 0.875rem;">
+					<label for="preset-select" style="font-size: 0.875rem; color: var(--roxy-muted);">Preset</label>
+					<select id="preset-select" style="padding: 0.35rem 0.5rem; border: 1px solid var(--roxy-border); border-radius: 6px; background: var(--roxy-bg); color: var(--roxy-fg); font: inherit;">
+						<option value="default">Default</option>
+						<option value="practitioner">Practitioner</option>
+					</select>
+				</div>
 				<div class="mode-tabs" role="tablist" aria-label="Theme mode">
 					<button id="mode-light" type="button" role="tab" aria-selected="true" data-mode="light">Light</button>
 					<button id="mode-dark" type="button" role="tab" aria-selected="false" data-mode="dark">Dark</button>
@@ -796,6 +824,13 @@ <h2 id="customize-title">Customize colors</h2>
 					<button type="button" class="copy-btn" data-copy-target="customize-snippet">Copy</button>
 					<pre><code id="customize-snippet"></code></pre>
 				</div>
+				<div id="preset-link-alt" hidden style="margin-top: 0.75rem;">
+					<p style="color: var(--roxy-muted); font-size: 0.8125rem; margin: 0 0 0.375rem;">Or link the preset stylesheet, no snippet to paste:</p>
+					<div class="code-block">
+						<button type="button" class="copy-btn" data-copy-target="preset-link-snippet">Copy</button>
+						<pre><code id="preset-link-snippet"></code></pre>
+					</div>
+				</div>
 			</section>
 			<footer>
 				<button type="button" id="customize-reset" class="btn btn--xs btn--ghost">Reset</button>