@close-by/clay 0.2.13 → 0.2.15

package/SKILL.md

@@ -62,6 +62,7 @@ ui.label(() => `Count: ${s.count}`);
 | API | Use when |
 |-----|----------|
 | `ui.state(initial)` | Reactive object; writes trigger tracked rebuilds |
+| `ui.urlState(defaults, opts?)` | Like `state`, hydrated from / synced to the query string |
 | `ui.auto(fn)` | Rebuild a UI block when tracked state changes |
 | `ui.label(() => …)` / `bindText` | Patch text only (stable tree) |
 | `bindValue` | Two-way inputs |
@@ -94,7 +95,7 @@ ui.page('/dashboard', () => {
 ## Do not
 
 - Import React, write JSX, or add client components for screens.
-- Use `window`, `document`, `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.openExternal`.
+- Use `window`, `document`, `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.getUrlSearch` / `ui.updateUrlSearch`, `ui.openExternal`.
 - Assume `let` is shared across tabs or users.
 - Use `ui.ai.*` as an LLM runtime — it is visual primitives only.
 

package/docs/README.md

@@ -15,7 +15,8 @@ For coding agents: the repo-root [llms.txt](../llms.txt) is a short map of these
 | [Tailwind](./tailwind.md) | Zero-config utilities from page modules; optional tokens |
 | [Sample app](./tutorial.md) | Step-by-step tasks list, then two pages + shell |
 | [Concepts](./concepts.md) | Mental model: sessions, elements, patches; **canonical `state`/`auto`/`timer` recipe**; reactive `let` alternative |
-| [Browser APIs](./browser-apis.md) | Prefer `ui.clipboard` / hash / `openExternal` — never `window` in page code |
+| [Browser APIs](./browser-apis.md) | Prefer `ui.clipboard` / hash / search / `openExternal` — never `window` in page code |
+| [URL search](./url-search.md) | `ui.urlState` + query helpers for shareable filters |
 | [Production & security](./production.md) | Auth, server exposure, rate limits, boot parity |
 | [Ops patterns](./ops-patterns.md) | Dense consoles: chips, master–detail, feeds, sensitive logs, auth nav |
 | [API reference](./api.md) | `ui.*`, `Element` methods, `reactive`, helpers |

package/docs/SKILL.md

@@ -62,6 +62,7 @@ ui.label(() => `Count: ${s.count}`);
 | API | Use when |
 |-----|----------|
 | `ui.state(initial)` | Reactive object; writes trigger tracked rebuilds |
+| `ui.urlState(defaults, opts?)` | Like `state`, hydrated from / synced to the query string |
 | `ui.auto(fn)` | Rebuild a UI block when tracked state changes |
 | `ui.label(() => …)` / `bindText` | Patch text only (stable tree) |
 | `bindValue` | Two-way inputs |
@@ -94,7 +95,7 @@ ui.page('/dashboard', () => {
 ## Do not
 
 - Import React, write JSX, or add client components for screens.
-- Use `window`, `document`, `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.openExternal`.
+- Use `window`, `document`, `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.getUrlSearch` / `ui.updateUrlSearch`, `ui.openExternal`.
 - Assume `let` is shared across tabs or users.
 - Use `ui.ai.*` as an LLM runtime — it is visual primitives only.
 

package/docs/api.md

@@ -1052,7 +1052,7 @@ ui.stat([
 
 #### `ui.areaChart(props)`
 
-Stacked area chart (Recharts). Optional card chrome via `title` / `description`. Set `interactive: true` with ISO date `xKey` values for client-side period tabs (default 7d / 30d / 90d; override with `periods`). Optional `headline: { value, trend?, trendDirection? }` for a KPI row above the chart; `loading: true` shows a skeleton. Legend is always shown. Pass `stacked: false` to overlay series instead of stacking (default `true`).
+Stacked area chart (Recharts). Optional card chrome via `title` / `description`. Set `interactive: true` with ISO date `xKey` values for client-side period tabs (default 7d / 30d / 90d; override with `periods`). Optional `headline: { value, trend?, trendDirection? }` for a KPI row above the chart; `loading: true` shows a skeleton. Legend is shown by default; pass `showLegend: false` to hide. Pass `stacked: false` to overlay series instead of stacking (default `true`).
 
 ```typescript
 ui.areaChart({
@@ -1071,7 +1071,7 @@ ui.areaChart({
 
 #### `ui.barChart(props)`
 
-Bar chart with the same cartesian props as area (`data`, `xKey`, `series`, title/description/height/interactive, `headline`, `periods`, `loading`). Optional `stacked` (default `false`) and `layout: 'vertical' | 'horizontal'` (default `'vertical'` — category on X).
+Bar chart with the same cartesian props as area (`data`, `xKey`, `series`, title/description/height/interactive, `headline`, `periods`, `loading`, `showLegend?`). Optional `stacked` (default `false`) and `layout: 'vertical' | 'horizontal'` (default `'vertical'` — category on X).
 
 ```typescript
 ui.barChart({
@@ -1089,11 +1089,22 @@ ui.barChart({
 
 #### `ui.lineChart(props)`
 
-Line chart with the same cartesian props as area (including interactive date ranges, headline, periods, loading).
+Line chart with the same cartesian props as area (including interactive date ranges, headline, periods, loading, `showLegend?`). Line styling:
+
+| Prop | Default | Description |
+|------|---------|-------------|
+| `curve` | `'monotone'` | Recharts interpolation: `'linear'`, `'natural'`, `'step'`, `'stepBefore'`, `'stepAfter'`, `'basis'` |
+| `strokeWidth` | `2` | Line thickness in px |
+| `dots` | `false` | Show point markers |
+| `strokeDasharray` / `dashed` | — | Dashed stroke; `dashed: true` → `'4 4'` |
+| `variant` | `'default'` | `'minimal'` hides the grid for a cleaner plot |
 
 ```typescript
 ui.lineChart({
   title: 'Traffic trend',
+  showLegend: false,
+  curve: 'step',
+  dots: true,
   data: monthly,
   xKey: 'month',
   series: [
@@ -1782,6 +1793,11 @@ onClick: async () => {
 | `ui.clipboard(content)` | `void` | Write text to clipboard (prefer over `navigator.clipboard`) |
 | `ui.getUrlHash()` | `string` | Current hash without `#` (from hello / last set) |
 | `ui.setUrlHash(hash)` | `void` | Set `location.hash` on the client |
+| `ui.getUrlSearch()` | `string` | Current search without `?` (from hello / last set) |
+| `ui.getUrlSearchParams()` | `URLSearchParams` | Mutable parse of `getUrlSearch()` |
+| `ui.setUrlSearch(search, opts?)` | `void` | Set `location.search` (`opts.mode`: `replace` \| `push`) |
+| `ui.updateUrlSearch(patch, opts?)` | `void` | Merge query keys; `null`/`''` deletes |
+| `ui.urlState(defaults, opts?)` | reactive object | `ui.state` + hydrate/sync query string (prefer this) |
 | `ui.openExternal(url)` | `void` | `window.open` in a new tab (`noopener`) |
 | `ui.theme.set(mode)` | `void` | Push `light` \| `dark` \| `system` to this client |
 | `ui.theme.get()` | `ThemeMode \| null` | Last value set on this session |

package/docs/browser-apis.md

@@ -8,6 +8,7 @@ Page builders and event handlers run on the **server** (Bun), not in the browser
 |------|-----|
 | Copy text | `ui.clipboard(text)` |
 | Read / set URL hash | `ui.getUrlHash()` / `ui.setUrlHash(hash)` |
+| Read / set URL search (query) | `ui.urlState(defaults)` (prefer) or `ui.getUrlSearch` / `ui.updateUrlSearch` |
 | Open a URL in a new tab | `ui.openExternal(url)` |
 | In-app route change | `ui.navigate(path)` |
 | Scroll | `ui.scroll.to` / `ui.scroll.intoView` |
@@ -23,17 +24,23 @@ ui.button('Copy id', {
 
 const focus = ui.getUrlHash(); // from last hello / setUrlHash
 ui.setUrlHash(traceId);
+
+const partner = ui.getUrlSearchParams().get('partner');
+ui.updateUrlSearch({ partner: 'UBER', page: null }); // omit empty defaults
 ui.openExternal('https://signoz.example/trace/' + traceId);
 ```
 
 `getUrlHash` returns the hash **without** a leading `#`. It is hydrated from the client on each `hello` (connect, reconnect, SPA navigate) and updated when you call `setUrlHash`.
 
+`getUrlSearch` returns the query string **without** a leading `?` (same hydration / write path). Prefer **`ui.urlState`** for filter objects; use `ui.updateUrlSearch` for one-off merges. See [URL search](./url-search.md).
+
 ## Don’t
 
 ```ts
 // Wrong — server has no clipboard / location
 await navigator.clipboard.writeText(value);
 window.location.hash = traceId;
+window.location.search = '?partner=UBER';
 window.open(url, '_blank');
 ```
 
@@ -61,5 +68,5 @@ With **`clay --reactive-let`**, transformed files that import known-fragile CJS
 ## Related
 
 - Helpers table: [API — dialogs and feedback](./api.md#dialogs-and-feedback)
-- Protocol: `clipboard`, `setUrlHash`, `openExternal` in [WebSocket protocol](./protocol.md)
+- Protocol: `clipboard`, `setUrlHash`, `setUrlSearch`, `openExternal` in [WebSocket protocol](./protocol.md)
 - Phase 1 reactivity (preferred over DOM hacks): [reactive-let](./reactive-let.md)

package/docs/elements.md

@@ -102,9 +102,9 @@ Each factory creates an `Element` with a wire `type` string. The React client ma
 | `upload` | `upload` | File picker / dropzone → `POST /upload` (progress/abort) → WS `upload` / `progress` / `error` / `abort` |
 | `stat` | `stat` | Grid of metric cards (optional per-item `sparkline`) |
 | `sparkline` | `sparkline` | KPI card with inline area/line mini chart (`headline`, `value`/`trend` shorthand) |
-| `areaChart` | `areachart` | Recharts stacked area (+ legend, optional interactive periods, `headline`, `loading`, `stacked?`) |
-| `barChart` | `barchart` | Recharts bar (`stacked?`, `layout?: 'vertical' \| 'horizontal'`, shared cartesian chrome) |
-| `lineChart` | `linechart` | Recharts line (+ optional interactive periods, headline, loading) |
+| `areaChart` | `areachart` | Recharts stacked area (+ legend, optional interactive periods, `headline`, `loading`, `stacked?`, `showLegend?`) |
+| `barChart` | `barchart` | Recharts bar (`stacked?`, `layout?: 'vertical' \| 'horizontal'`, shared cartesian chrome, `showLegend?`) |
+| `lineChart` | `linechart` | Recharts line (+ interactive periods, headline, loading, `curve`/`strokeWidth`/`dots`/`dashed`/`variant`, `showLegend?`) |
 | `pieChart` | `piechart` | Recharts pie/donut (`nameKey`/`valueKey` or `series`, `innerRadius?`) |
 | `radarChart` | `radarchart` | Recharts radar (`angleKey` + `series`, optional `fillOpacity`) |
 | `radialChart` | `radialchart` | Recharts radial bar (`nameKey`/`valueKey` or stacked `series`, optional center text / angles) |

package/docs/llms.txt

@@ -9,7 +9,7 @@ Notes for agents:
 - Public API and wire protocol are camelCase (`onClick`, `bindValue`, `setText`).
 - Page builders run once per WebSocket session (per browser tab). `let` is per-tab, not shared.
 - Update existing nodes with `setText` / `setValue` / bindings. Prefer `ui.state` + `ui.auto` (+ `ui.timer`) for async/live UIs; `ui.refreshable` for simple one-shot rebuilds. Shared or persisted state: `ui.storage` (`tab` / `user` / `app`).
-- Never use `window` / `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.openExternal`.
+- Never use `window` / `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.getUrlSearch` / `ui.updateUrlSearch`, `ui.openExternal`.
 - Runtime is Bun. In this repo: `bun run build:client`, then `bun run demo` (http://localhost:4000) or `bun run clay hello.ts`.
 - `ui.ai.*` is visual primitives only — no model or streaming runtime.
 - Agent skill (Cursor / compatible tools): `@close-by/clay/SKILL.md` — copy to `.cursor/skills/clay/SKILL.md` or read from `node_modules` when installed.

package/docs/protocol.md

@@ -19,7 +19,7 @@ On unexpected socket close, the client reconnects with exponential backoff (500m
 { "op": "hello", "path": "/examples/counter", "userId": "optional-stable-id", "hash": "optional-hash-without-hash-sign", "browserStorage": {}, "clientStorage": {}, "tabStorage": {} }
 ```
 
-Client connects (or sends another `hello` after navigate on the same socket) and identifies the page. Optional `userId` (from localStorage/cookie) enables `ui.storage.user` unless overridden by `resolveUserId`. Optional `hash` (no leading `#`) hydrates `ui.getUrlHash()`. Optional `browserStorage` / `clientStorage` / `tabStorage` bags hydrate `ui.storage.browser` / `ui.storage.client` / `ui.storage.tab`.
+Client connects (or sends another `hello` after navigate on the same socket) and identifies the page. Optional `userId` (from localStorage/cookie) enables `ui.storage.user` unless overridden by `resolveUserId`. Optional `hash` (no leading `#`) hydrates `ui.getUrlHash()`. Optional `search` (no leading `?`) hydrates `ui.getUrlSearch()`. Optional `browserStorage` / `clientStorage` / `tabStorage` bags hydrate `ui.storage.browser` / `ui.storage.client` / `ui.storage.tab`.
 
 Sent on connect and after client-side navigation. The React client keeps matching `app` shell chrome mounted across remounts; only inset content is replaced.
 
@@ -163,6 +163,14 @@ Client writes `content` with `navigator.clipboard.writeText` (shows an error toa
 
 Client sets `location.hash` via `history.replaceState` (`hash` has no leading `#`; empty string clears). Hydrated the other way on `hello.hash`. Prefer `ui.setUrlHash` / `ui.getUrlHash`.
 
+### `setUrlSearch`
+
+```json
+{ "op": "setUrlSearch", "search": "tab=orders&partner=UBER", "mode": "replace" }
+```
+
+Client sets `location.search` via `history.replaceState` or `pushState` (`mode`, default `replace`). `search` has no leading `?`; empty string clears. Pathname and hash are preserved. Hydrated the other way on `hello.search`. Prefer `ui.setUrlSearch` / `ui.updateUrlSearch` / `ui.getUrlSearch`. See [URL search](./url-search.md).
+
 ### `openExternal`
 
 ```json

package/docs/url-search.md

@@ -0,0 +1,97 @@
+# URL search (query string) helpers
+
+Ops consoles often need **shareable filter state** in the address bar
+(`?tab=orders&partner=UBER&from=2026-01-01`). Page builders run on the server, so
+they must not read `window.location`. Clay mirrors the existing hash helpers.
+
+## Prefer `ui.urlState`
+
+Like `ui.state`, but hydrated from the query string and write-through synced:
+
+```ts
+import { ui } from '@close-by/clay';
+
+ui.page('/lastmile', () => {
+  const filters = ui.urlState({
+    tab: 'dashboard',
+    partner: '',
+    from: '',
+    page: 1,
+  });
+
+  // ?partner=UBER&page=2 — defaults (dashboard / '' / 1) are omitted
+  filters.partner = 'UBER';
+  filters.page = 2;
+
+  ui.select({
+    label: 'Partner',
+    value: filters.partner || '__all__',
+    options: [
+      { value: '__all__', label: 'All' },
+      { value: 'UBER', label: 'Uber Eats' },
+    ],
+    onChange: (v) => {
+      filters.partner = v === '__all__' ? '' : v;
+    },
+  });
+});
+```
+
+| Option | Default | Role |
+|--------|---------|------|
+| `omitDefaults` | `true` | Drop keys whose value equals the default |
+| `mode` | `'replace'` | History write (`'push'` when Back should undo) |
+| `keys` | identity | Remap state keys → query names (`{ page: 'p' }`) |
+
+Works with `ui.auto` / `bindValue` the same way as `ui.state`.
+
+## Low-level helpers
+
+Escape hatches when you need a one-off read/write without a reactive object:
+
+| Helper | Role |
+|--------|------|
+| `ui.getUrlSearch()` | Current search **without** leading `?` (from `hello` / last set) |
+| `ui.getUrlSearchParams()` | Mutable `URLSearchParams` copy of that string |
+| `ui.setUrlSearch(search, opts?)` | Replace the whole query string (empty clears) |
+| `ui.updateUrlSearch(patch, opts?)` | Merge keys; `null` / `undefined` / `''` deletes |
+
+`opts.mode` is `'replace'` (default) or `'push'`. Prefer **replace** for filter
+tweaks so Back is not flooded.
+
+## Protocol
+
+**Client → server** (`hello`):
+
+```json
+{ "op": "hello", "path": "/lastmile", "hash": "", "search": "tab=orders&partner=UBER" }
+```
+
+**Server → client**:
+
+```json
+{ "op": "setUrlSearch", "search": "tab=orders&partner=UBER", "mode": "replace" }
+```
+
+Client writes `pathname + ?search + hash` via `history.replaceState` / `pushState`.
+Hash is preserved (same as `setUrlHash` preserves search).
+
+## Path vs query
+
+| Concern | Prefer |
+|---------|--------|
+| Resource identity | Path (`/orders/:id`) via `ui.page` / `ui.navigate` |
+| Active tab, filters, sort, page | **Query string** (`ui.urlState`) |
+| In-page focus / trace id | Hash (`ui.setUrlHash`) when you already use it |
+
+## Limits / follow-ups
+
+- Hydration runs on each `hello` (connect, reconnect, SPA path change). Pure
+  Back/Forward that only changes the query does **not** remount yet — same
+  limitation as hash today. A future `urlchange` client event (or popstate →
+  hello) would close that gap and re-hydrate `urlState` in place.
+
+## Related
+
+- [Browser APIs](./browser-apis.md)
+- [WebSocket protocol](./protocol.md) — `hello.search`, `setUrlSearch`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@close-by/clay",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "NiceGUI-like ui.* facade for Clay apps",
   "license": "MIT",
   "type": "module",
@@ -37,10 +37,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@close-by/clay-compiler": "0.2.13",
-    "@close-by/clay-core": "0.2.13",
-    "@close-by/clay-components": "0.2.13",
-    "@close-by/clay-server": "0.2.13",
+    "@close-by/clay-compiler": "0.2.15",
+    "@close-by/clay-core": "0.2.15",
+    "@close-by/clay-components": "0.2.15",
+    "@close-by/clay-server": "0.2.15",
     "@tailwindcss/cli": "^4.3.3",
     "tailwindcss": "^4.3.3"
   }

package/src/index.ts

@@ -237,6 +237,9 @@ import {
   type ChartPeriod,
   type ChartReferenceLine,
   type ChartReferenceArea,
+  type LineCurve,
+  type LineChartVariant,
+  type LineChartStyleProps,
   type SparklineProps,
   type CardProps,
   type DialogProps,
@@ -440,6 +443,10 @@ import {
   runJavaScript as runJavaScriptCore,
   getUrlHash as getUrlHashCore,
   setUrlHash as setUrlHashCore,
+  getUrlSearch as getUrlSearchCore,
+  getUrlSearchParams as getUrlSearchParamsCore,
+  setUrlSearch as setUrlSearchCore,
+  updateUrlSearch as updateUrlSearchCore,
   openExternal as openExternalCore,
   scroll as scrollCore,
   timer as timerCore,
@@ -448,6 +455,7 @@ import {
   reactive as reactiveCore,
   state as stateCore,
   subscribe as subscribeCore,
+  urlState as urlStateCore,
   auto as autoCore,
   draft as draftCore,
   validate as validateCore,
@@ -465,6 +473,8 @@ import {
   type ThemeMode,
   type DraftStorage,
   type DraftOptions,
+  type UrlStateOptions,
+  type UrlStateValue,
 } from '@close-by/clay-core';
 import {
   ClayServer,
@@ -1590,6 +1600,35 @@ export function setUrlHash(hash: string): void {
   setUrlHashCore(hash);
 }
 
+/** URL search without `?` (from hello / last `setUrlSearch`). Prefer over `window.location`. */
+export function getUrlSearch(): string {
+  return getUrlSearchCore();
+}
+
+/** Parse {@link getUrlSearch} as `URLSearchParams` (mutable copy). */
+export function getUrlSearchParams(): URLSearchParams {
+  return getUrlSearchParamsCore();
+}
+
+/** Set the browser query string. Prefer over `window.history` / `location.search`. */
+export function setUrlSearch(
+  search: string,
+  opts?: { mode?: 'replace' | 'push' },
+): void {
+  setUrlSearchCore(search, opts);
+}
+
+/**
+ * Merge keys into the current query string.
+ * `null` / `undefined` / `''` deletes the key.
+ */
+export function updateUrlSearch(
+  patch: Record<string, string | number | boolean | null | undefined>,
+  opts?: { mode?: 'replace' | 'push' },
+): void {
+  updateUrlSearchCore(patch, opts);
+}
+
 /** Open a URL in a new tab. Prefer over `runJavaScript('window.open…')`. */
 export function openExternal(url: string): void {
   openExternalCore(url);
@@ -1627,6 +1666,18 @@ export const reactive = reactiveCore;
 /** Alias for `reactive` — NiceGUI-ish mutable page state. Prefer `ui.state`. */
 export const state = stateCore;
 
+/**
+ * Like `ui.state`, but hydrated from the query string and write-through synced
+ * via `ui.updateUrlSearch`. Prefer for shareable filters / tabs.
+ * See {@link UrlStateOptions}.
+ */
+export function urlState<T extends Record<string, UrlStateValue>>(
+  defaults: T,
+  opts?: UrlStateOptions<T>,
+): T {
+  return urlStateCore(defaults, opts);
+}
+
 /** Listen for a reactive property change. Prefer this over importing from `@close-by/clay-core`. */
 export const subscribe = subscribeCore;
 
@@ -1912,6 +1963,10 @@ export const ui = {
   clipboard,
   getUrlHash,
   setUrlHash,
+  getUrlSearch,
+  getUrlSearchParams,
+  setUrlSearch,
+  updateUrlSearch,
   openExternal,
   runJavaScript,
   scroll,
@@ -1920,6 +1975,7 @@ export const ui = {
   theme,
   reactive,
   state,
+  urlState,
   subscribe,
   draft,
   validate,