@roxyapi/ui 0.8.1 → 0.9.0

package/AGENTS.md

@@ -120,15 +120,17 @@ const { data: chart } = await roxy.astrology.generateNatalChart({
 
 Every chart endpoint accepts `timezone` as either a decimal-hour offset (`5.5` for IST, `-5` for EST) or an IANA name (`'Asia/Kolkata'`, `'America/New_York'`). The decimal form is what `/location/search` returns; the IANA form is correct over DST boundaries. Pick one and stay consistent in a single integration. Mixing them does not break the API but makes the bug surface area larger.
 
-### 4. API key in the browser
+### 4. Secret key in the browser
 
-Keys are server side only. Call `createRoxy(process.env.ROXY_API_KEY!)` on your server (Node, Bun, Hono, Next.js route handlers, Workers, Edge functions), then send the response, not the key, to the component. Never ship the key in a client bundle. Browser-safe keys for direct client-side embedding are on the roadmap, not yet available.
+Secret keys (`sk_*`) grant full account access and are server side only. Call `createRoxy(process.env.ROXY_API_KEY!)` on your server (Node, Bun, Hono, Next.js route handlers, Workers, Edge functions), then send the response, not the key, to the component. Never ship a secret key in a client bundle.
 
 ```ts
-// Server side only
+// Secret key: server side only
 const roxy = createRoxy(process.env.ROXY_API_KEY!);
 ```
 
+For direct client-side calls, use a **publishable key** (`pk_live_*` / `pk_test_*`) instead. Publishable keys are browser-safe: mint one at `roxyapi.com/account`, register the origins you embed on, and the API gateway returns 403 for any other origin. See the client-side pattern below.
+
 ### 5. Missing `'use client'` in Next.js App Router
 
 The React components in `@roxyapi/ui-react` mount Custom Elements, which need the DOM. In the App Router, files that import them must declare `'use client'` at the top. Server Components can fetch with the SDK; the client component renders.
@@ -269,9 +271,30 @@ For a static chart with no picker, fetch in a Server Component and pass `data` t
 </script>
 ```
 
-### Pattern 4: widgets auto-mount (coming soon)
+### Pattern 4: fully client-side with a publishable key (no server)
+
+When you do not want a backend at all, mint a **publishable key** (`pk_live_*`) at `roxyapi.com/account`, register the origins you embed on, and call RoxyAPI directly from the browser. The publishable key is safe to ship in client code: it is origin-restricted (any other origin gets 403) and cannot read your account. `<roxy-location-search>` accepts the key via its `publishable-key` attribute and fetches geocoding itself; for the data endpoints you make a normal browser `fetch` with the key in the `X-API-Key` header, then assign the response to the rendering component.
+
+```html
+<roxy-location-search publishable-key="pk_live_..."></roxy-location-search>
+<roxy-natal-chart></roxy-natal-chart>
+
+<script type="module">
+	const chart = document.querySelector('roxy-natal-chart');
+	document.querySelector('roxy-location-search').addEventListener('roxy-location-select', async (e) => {
+		const { latitude, longitude, timezone } = e.detail;
+		if (latitude == null || longitude == null) return;
+		const res = await fetch('https://roxyapi.com/api/v2/astrology/natal-chart', {
+			method: 'POST',
+			headers: { 'X-API-Key': 'pk_live_...', 'Content-Type': 'application/json' },
+			body: JSON.stringify({ date: '1990-01-15', time: '14:30:00', latitude, longitude, timezone }),
+		});
+		chart.data = await res.json(); // pass the unwrapped response, not an envelope
+	});
+</script>
+```
 
-A zero-wiring embed that reads `data-*` attributes and renders the matching component is on the roadmap. It needs browser-safe keys, which are not yet available. Until then, use Pattern 1 (inline JSON) for no-build pages.
+Rendering components do not fetch on their own; you set `data`. Only `<roxy-location-search>` (and `<roxy-endpoint-form>` for the spec) fetch internally. A zero-wiring `data-*` auto-mount that fetches and renders with no script is still on the roadmap.
 
 ### Pattern 5: MCP tool-call response
 
@@ -339,13 +362,13 @@ This is how the WordPress plugin renders: PHP fetches the response server-side,
 
 ## Theming and dark mode
 
-Components react to three signals in priority order. No events to dispatch. No JS bridge to write.
+Components react to three signals in priority order. No events to dispatch. No JS bridge to write. The CDN bundle (`dist/cdn/roxy-ui.js`) auto-loads the design tokens, so a single script tag yields full theming and dark mode with nothing else to add. The npm and React paths inherit the same tokens through the components; only set up `tokens.css` yourself if you import per component without the full bundle.
 
 | Signal | Where | Effect |
 |---|---|---|
 | `prefers-color-scheme: dark` | OS | Default. Follows user system setting. |
 | `data-theme="light"` or `data-theme="dark"` | `<html>` / `<body>` / any ancestor / the component itself | Wins over OS. Per-element override scope works. |
-| `.dark` class | Any ancestor | Equivalent to `data-theme="dark"`. Use when the host stack already ships a `.dark` toggle (Tailwind, shadcn). |
+| `.dark` class | The component itself or any ancestor (typically `<html>`) | Same effect as `data-theme="dark"`. Use when the host stack already ships a `.dark` toggle (Tailwind, shadcn). |
 
 To toggle at runtime:
 

package/README.md

@@ -55,7 +55,7 @@ Light, dark, your brand. Override one CSS variable and every component updates.
 ```css
 :root {
   /* Surface */
-  --roxy-bg: #fafafa;
+  --roxy-bg: #ffffff;
   --roxy-fg: #0a0a0a;
   --roxy-muted: #71717a;
   --roxy-border: #e4e4e7;
@@ -66,13 +66,13 @@ Light, dark, your brand. Override one CSS variable and every component updates.
 
   /* Status (each has a -fg variant for WCAG-AA text contrast) */
   --roxy-success: #16a34a;
-  --roxy-warning: #f59e0b;
+  --roxy-warning: #ea580c;
   --roxy-danger: #dc2626;
-  --roxy-info: #2563eb;
+  --roxy-info: #0284c7;
 
   /* Shape + motion */
-  --roxy-radius-md: 12px;
-  --roxy-shadow-md: 0 4px 12px rgba(0,0,0,0.08);
+  --roxy-radius-md: 8px;
+  --roxy-shadow-md: 0 4px 6px -1px rgba(0,0,0,0.08), 0 2px 4px -2px rgba(0,0,0,0.06);
   --roxy-motion-duration: 200ms; /* 0ms when prefers-reduced-motion */
 }
 
@@ -294,7 +294,7 @@ Always call `/location/search` first. Every chart endpoint expects latitude, lon
 
 Server-rendered and cached pages (WordPress, JSX SSR, static HTML) cannot always run JavaScript to set the `data` property per element. Render the response into a child `<script type="application/json" class="roxy-data">` on the server instead. The component reads it on load. No per-element script, no API key in the browser.
 
-Load the bundle once anywhere on the page. It registers every `roxy-*` element, so every component on the page renders from that single tag.
+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.
 
 ```html
 <!-- Once per page: defines every roxy-* element -->
@@ -535,11 +535,9 @@ const { data: random } = await roxy.iching.getRandomHexagram();
 
 Get a key at <https://roxyapi.com/account>.
 
-Today every key is a **secret key**: use it server side only (Node, Bun, Hono, Next.js route handlers, Workers). Never commit it, never ship it in a client bundle. Fetch on your server and send the rendered response, not the key, to the browser. The [Start with one component](#start-with-one-component) section and the [framework recipes](#most-used-components-per-domain) show the pattern.
+Two key types. **Secret keys** (`sk_*`) grant full account access: use them server side only (Node, Bun, Hono, Next.js route handlers, Workers). Never commit one, never ship one in a client bundle. **Publishable keys** (`pk_live_*` / `pk_test_*`) are browser-safe: mint one, register the origins you embed on, and any other origin gets a 403 at the gateway. Use a publishable key when you call RoxyAPI directly from the browser with no backend.
 
-Set `ROXY_API_KEY` to your secret key in your server env for every SDK example on this page.
-
-Browser-safe keys for direct client-side embedding are on the roadmap, not yet available. Until they ship, keep the fetch on your server.
+Set `ROXY_API_KEY` to your secret key in your server env for the server-side SDK examples on this page. For direct client-side embedding with no backend, use a publishable key (see the fully client-side pattern in [`AGENTS.md`](AGENTS.md)).
 
 ## Distribution
 
@@ -603,7 +601,7 @@ Browser-safe keys for direct client-side embedding are on the roadmap, not yet a
 
 ## Theming
 
-Every component reads from `--roxy-*` CSS custom properties. Override globally on `:root` or per element. Light + dark defaults, container queries for responsive layouts at 320px and up. See [THEMING.md](https://github.com/RoxyAPI/ui/blob/main/packages/ui/THEMING.md) for the full token reference.
+Every component reads from `--roxy-*` CSS custom properties. Override globally on `:root` or per element. Light + dark defaults, container queries for responsive layouts at 320px and up. The CDN bundle auto-loads these tokens; your `:root { --roxy-* }` overrides always win over the defaults. See [THEMING.md](https://github.com/RoxyAPI/ui/blob/main/packages/ui/THEMING.md) for the full token reference.
 
 ```css
 :root {
@@ -686,7 +684,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 6-10 KB gzipped, capped at 30 KB by CI. The full bundle (every component, helpers, base styles) stays well under the 150 KB CI cap, around 45 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 6-10 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 54 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.
 </details>
 
 <details>
@@ -799,7 +797,7 @@ Components ship in Shadow DOM for style isolation; Tailwind utilities are scoped
 <details>
 <summary><strong>What is the security model for API keys?</strong></summary>
 
-Today keys are secret keys: they live server side only and grant full access, so never ship one in a client bundle. Fetch on your server and pass the rendered response, not the key, to the browser. Browser-safe keys with an origin allowlist for direct client-side embedding are on the roadmap and not yet available.
+Two key types. Secret keys (`sk_*`) live server side only and grant full access, so never ship one in a client bundle: fetch on your server and pass the rendered response, not the key, to the browser. Publishable keys (`pk_live_*` / `pk_test_*`) are browser-safe for direct client-side embedding: they carry an origin allowlist, so a key leaked to any other origin returns 403 instead of working. Mint either at `roxyapi.com/account`.
 
 For CSP, allow `script-src https://cdn.jsdelivr.net` if loading the bundle from the CDN. Subresource Integrity hashes are available via the jsDelivr SRI API for any pinned version.
 </details>

package/THEMING.md

@@ -1,6 +1,6 @@
 # Theming Roxy UI
 
-Every Roxy UI component reads its colors, fonts, spacing, and motion from a single set of CSS custom properties on `:host`. Override them at `:root` to brand the whole library, or scope to one element to skin a single component.
+Every Roxy UI component reads its colors, fonts, spacing, and motion from a single set of `--roxy-*` CSS custom properties. Override them at `:root` to brand the whole library, or scope to one element to skin a single component. Custom properties inherit through the Shadow DOM boundary, so a value set on `:root` or any light-DOM ancestor reaches every component. The CDN bundle auto-loads the token defaults; your `:root` overrides always win over them.
 
 ## Token reference
 
@@ -99,18 +99,20 @@ roxy-natal-chart {
 
 ### Dark mode
 
-Three opt-in mechanisms work out of the box.
+Three opt-in mechanisms work out of the box. The CDN bundle auto-loads the tokens, so all three work from one script tag; on the npm path the full `@roxyapi/ui` import pulls the same tokens in.
 
 ```css
 /* System preference: nothing to do */
 
-/* data-theme on the document */
+/* data-theme on the document, an ancestor, or the element itself */
 :root[data-theme='dark'] { /* automatic */ }
 
-/* Tailwind dark class on an ancestor */
-.dark roxy-natal-chart { /* automatic */ }
+/* Tailwind dark class on the document, an ancestor, or the element itself */
+.dark { /* automatic */ }
 ```
 
+Tokens set on the `:root` / `.dark` / `[data-theme]` light-DOM element inherit through the shadow boundary into every component, so a `.dark` class anywhere above a component themes it. Per-element scope works too: `<roxy-natal-chart data-theme="dark">` runs one chart in dark on an otherwise light page.
+
 ### Map Tailwind tokens
 
 Tailwind users can map our tokens to theirs in five lines of `globals.css`. Pick the syntax that matches your Tailwind version.