@close-by/clay 0.2.19 → 0.2.20

package/docs/api.md

@@ -1220,6 +1220,21 @@ ui.radialChart({
 });
 ```
 
+#### Live chart updates
+
+Every chart factory and `ui.chart.*` builder returns a `ChartElement`:
+
+| Method | What it sends |
+|--------|---------------|
+| `appendData(rows, { max? })` | `appendRows` with only the new rows; client trims to the last `max` |
+| `setData(rows)` | `updateProps` (`data`) |
+| `upsertData(row, { key?, max? })` | Replaces the row with the same `key` (default `xKey`, or `nameKey` for pies) or appends it |
+| `setSeries(series)` / `setHeadline(h)` / `setTitle(t)` / `setDescription(d)` / `setLoading(b)` | `updateProps` for that prop |
+
+`ui.stat(items)` returns a `StatElement` with `setItems(items)`, `updateItem(titleOrIndex, patch)` and `appendSparkline(titleOrIndex, points, { max? })`. Each sends one `updateProps` (`items`).
+
+All charts accept `animate?: boolean` (default `true`). See [Updating in place](./updating-in-place.md#live-charts-appenddata--setdata--upsertdata).
+
 #### Structured charts (`ui.chart`)
 
 Optional sugar over the props APIs above. Mode-first builders compile to the same `Element` types — legacy `ui.areaChart` / `ui.pieChart` / etc. remain fully supported.

package/docs/examples.md

@@ -26,6 +26,7 @@ Each page sets `group` / `groupIcon` in its `pageMeta`, so the sidebar and the h
 | `/examples/reui-batches` | `ReuiBatchesDemo.ts` | ReUI batches 3–6: `buttonGroup`, `empty`, `pagination`, `filterBar`, form inputs, `navigationMenu`, `notice`, `stat`+sparkline, `eventCalendar`, datatable `showFilterChips` |
 | `/examples/reui-batch-7` | `ReuiBatch7Demo.ts` | ReUI batch 7: `inputGroup`, `toggle`, `descriptionList`, `staticTable`, `aspectRatio`, `itemList`, `checkboxGroup` |
 | `/examples/charts` | `ChartDemo.ts` | `ui.chart.*`, `ui.sparkline`, composed/scatter charts |
+| `/examples/live-charts` | `LiveCharts.ts` | Live charts: `appendData` sliding windows, `setData` tweens, `upsertData` buckets, live gauge and sparklines |
 | `/examples/slider-demo` | `SliderDemo.ts` | Slider, checkbox, select + bindings |
 | `/examples/themes` | `ThemesDemo.ts` | Palette gallery: `ui.theme.palette`, light/dark, component preview |
 | `/examples/layout` | `LayoutDemo.ts` | Fill layout: `fillViewport`, `grow`, `scroll`, `ui.grid` |

package/docs/protocol.md

@@ -79,6 +79,7 @@ Browser Back/Forward (or other `popstate`) changed the query and/or hash **witho
 | `replace` | `id`, `node` | Replace entire subtree at `id` |
 | `updateProps` | `id`, `props` | Shallow-merge props |
 | `setChildren` | `id`, `children` | Replace children array |
+| `appendRows` | `id`, `prop`, `rows`, `max?` | Append `rows` to the array prop `prop`, then keep the last `max` items (chart streaming) |
 | `remove` | `id` | Remove node from parent |
 
 ### `navigate`

package/docs/updating-in-place.md

@@ -20,6 +20,7 @@ The flicker is caused by the remount, not by the new value. If a frame carries o
 | Change one value (a label, badge, or input) | `label.setText(…)`, `el.setValue(…)`, `el.update({ … })` | `updateProps` for that element |
 | Live table data | `table.setRows(rows)` on a table created with a stable `keyField` (add `highlightChanges: true` to flash changed rows) | `updateProps` on the table; rows keyed by `keyField` keep their DOM |
 | Table refetch | `table.setLoading(true)` / `table.withLoading(fn)` | `updateProps` (`loading`); previous rows stay, dimmed, instead of blanking |
+| Live chart data (any chart) | `chart.appendData(point, { max })` for a stream, `chart.setData(rows)` for a snapshot, `chart.upsertData(row)` for a growing bucket | `appendRows` with only the new points, or `updateProps` (`data`); the chart stays mounted |
 | A section whose structure depends on data | `ui.refreshable(() => …)` + `.refresh()`, or `ui.auto(() => …)` | Reconciled: matched children get `updateProps` only; added, removed, or reordered children cause one `setChildren` per affected parent |
 | Items in a list inside either of the above | `.key(item.id)` on each item | Items keep their identity through reorder, filter, and prepend |
 
@@ -31,7 +32,7 @@ When a `refreshable` or `auto` block re-runs, Clay builds a fresh tree and match
 
 1. **Keyed first.** A new child with `.key(k)` matches the old child with the same key and the same element type. Keyed children are matched only by key.
 2. **Unkeyed by position.** Unkeyed children are matched in order, by element type. If the next old child matches the current new one, the current old child was removed and is skipped. If the current old child matches the next new one, the new child was inserted. Otherwise the pair is treated as a replacement at that position. This lookahead covers a single insert or remove; larger reshuffles should be keyed.
-3. **Matched pairs keep the old element and its id.** The fresh element's handlers and props are copied onto the old one. Only props that actually changed are sent, as one `updateProps`.
+3. **Matched pairs keep the id on screen.** The freshly built element takes over the old element's id and the old one is destroyed. Only props that actually changed are sent, as one `updateProps`. Because the fresh instance is the one that stays live, its built-in handlers (table search, sort and paging, map drags) and any reference you saved while building (`table = ui.dataTable(...)`) keep working after the refresh.
 4. **Leftovers.** Old children with no match are destroyed. New children with no match are mounted. The parent sends one `setChildren` only if its list of ids changed. A child whose type changed at a position is replaced; its siblings keep their ids.
 5. **Nested blocks keep their instance.** A nested `refreshable` or `auto` keeps its id and its subscriptions and adopts the new builder, so its own refreshes keep working.
 
@@ -103,11 +104,35 @@ async function refresh() {
 
 If you want columns to stay fixed across refreshes, pass `columns` explicitly. Otherwise columns are inferred again on each `setRows`.
 
+### Live charts (`appendData` / `setData` / `upsertData`)
+
+Every chart (`ui.lineChart`, `areaChart`, `barChart`, `composedChart`, `scatterChart`, `pieChart`, `radarChart`, `radialChart`, `sparkline`, and the `ui.chart.*` builders) returns a `ChartElement`. Create it once and push data into it.
+
+```typescript
+const latency = ui.lineChart({ data: seed, xKey: 't', series: [{ key: 'p50', label: 'p50' }] });
+const byRegion = ui.barChart({ data: regions, xKey: 'region', series: [{ key: 'orders', label: 'Orders' }] });
+
+ui.timer(1, () => {
+  latency.appendData({ t: clock(), p50: sample() }, { max: 60 }); // only the new point is sent
+  latency.setHeadline({ value: `${p50} ms` });
+});
+ui.timer(5, async () => byRegion.setData(await fetchRegions())); // bars tween to the new values
+```
+
+- **`appendData(rows, { max })`** sends only the new rows. The client appends them and drops the oldest past `max`, so a sliding window costs one point per tick.
+- **`setData(rows)`** replaces the data. When the row count and first x value are unchanged, the marks tween to their new values.
+- **`upsertData(row, { key, max })`** replaces the row with the same x value (or `nameKey` for pies), or appends it. Use it for a bucket that keeps growing, such as the current minute.
+- **`setSeries`, `setHeadline`, `setTitle`, `setDescription`, `setLoading`** patch one prop each. Anything else goes through `update({ … })`.
+
+KPI stat grids work the same way: `ui.stat(items)` returns a `StatElement`. `updateItem(titleOrIndex, patch)` changes one card, `appendSparkline(titleOrIndex, points, { max })` extends that card's sparkline, and `setItems(items)` replaces them all.
+
+Appends and sliding windows draw without animation, so lines don't slide sideways or replay their entrance. Pass `animate: false` to turn chart animation off entirely. The interactive period tabs keep the selected period while data streams in.
+
 ## Anti-patterns
 
 - **Rebuilding a whole section when one value changes.** Wrapping a whole page in `ui.refreshable` and calling `.refresh()` every second to update a clock. Keep a reference to the clock label and call `setText`.
 - **Unkeyed lists that get sorted or filtered.** Without `.key()`, position is the identity. After a sort, the element in slot 3 is reused for whatever item is now third, so focus and typed text stay in the slot instead of following the row.
-- **Creating a new table instead of `setRows`.** A `ui.dataTable(...)` created inside a refreshable on every tick remounts the table and loses sort, scroll, selection, and search. Create the table once and call `setRows`.
+- **Creating a new table instead of `setRows`.** A `ui.dataTable(...)` rebuilt inside a refreshable keeps its id and stays interactive, but each rebuild starts the table's server-side state over, so sort, search, page and selection reset. Create the table once and call `setRows`.
 - **Tables without `keyField`.** Rows are stamped `__rowId` by their index, so inserting or re-sorting the source shifts every row's identity. Set `keyField` to your primary key.
 - **Toggling a constructor option by rebuilding.** Recreating a table with `zebra: on` inside an `auto` block. Use the setters instead: `setZebra`, `setDensity`, `setHighlightChanges`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@close-by/clay",
-  "version": "0.2.19",
+  "version": "0.2.20",
   "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.19",
-    "@close-by/clay-core": "0.2.19",
-    "@close-by/clay-components": "0.2.19",
-    "@close-by/clay-server": "0.2.19",
+    "@close-by/clay-compiler": "0.2.20",
+    "@close-by/clay-core": "0.2.20",
+    "@close-by/clay-components": "0.2.20",
+    "@close-by/clay-server": "0.2.20",
     "@tailwindcss/cli": "^4.3.3",
     "tailwindcss": "^4.3.3"
   }

package/src/index.ts

@@ -203,6 +203,8 @@ import {
   type CheckboxGroupProps,
   type CheckboxGroupOption,
   type StatItem,
+  type StatItemRef,
+  type StatElement,
   type DataTableProps,
   type DataTableAction,
   type DataTableView,
@@ -235,6 +237,7 @@ import {
   type ComposedChartProps,
   type ComposedChartSeries,
   type ComposedSeriesType,
+  type ChartElement,
   type CartesianChartProps,
   type ChartSeries,
   type ChartHeadline,
@@ -423,7 +426,6 @@ import {
   DialogElement,
   DialogStackElement,
   StepperElement,
-  NavigationMenuElement,
   AlertDialogElement,
   DropdownMenuElement,
   ContextMenuElement,
@@ -527,6 +529,9 @@ export {
 } from './tailwind';
 
 
+export { ChartElement, StatElement } from '@close-by/clay-components';
+export type { StatItemRef } from '@close-by/clay-components';
+
 export type {
   GridProps,
   LayoutProps,
@@ -1223,7 +1228,7 @@ export function flow(a: any, b?: any): FlowElement {
 }
 
 /** Stat strip (label/value items). Prefer `ui.stat`. */
-export function stat(items: StatItem[], props?: { className?: string }): Element {
+export function stat(items: StatItem[], props?: { className?: string }): StatElement {
   return statFactory(items, props);
 }
 
@@ -1247,47 +1252,47 @@ export const chart = chartNamespace;
 export const ai = aiNamespace;
 
 /** Area chart. Prefer `ui.areaChart`. See {@link AreaChartProps}. */
-export function areaChart(props: AreaChartProps): Element {
+export function areaChart(props: AreaChartProps): ChartElement {
   return areaChartFactory(props);
 }
 
 /** Bar chart. Prefer `ui.barChart`. See {@link BarChartProps}. */
-export function barChart(props: BarChartProps): Element {
+export function barChart(props: BarChartProps): ChartElement {
   return barChartFactory(props);
 }
 
 /** Line chart. Prefer `ui.lineChart`. See {@link LineChartProps}. */
-export function lineChart(props: LineChartProps): Element {
+export function lineChart(props: LineChartProps): ChartElement {
   return lineChartFactory(props);
 }
 
 /** Pie / donut chart. Prefer `ui.pieChart`. See {@link PieChartProps}. */
-export function pieChart(props: PieChartProps): Element {
+export function pieChart(props: PieChartProps): ChartElement {
   return pieChartFactory(props);
 }
 
 /** Radar chart. Prefer `ui.radarChart`. See {@link RadarChartProps}. */
-export function radarChart(props: RadarChartProps): Element {
+export function radarChart(props: RadarChartProps): ChartElement {
   return radarChartFactory(props);
 }
 
 /** Radial / gauge chart. Prefer `ui.radialChart`. See {@link RadialChartProps}. */
-export function radialChart(props: RadialChartProps): Element {
+export function radialChart(props: RadialChartProps): ChartElement {
   return radialChartFactory(props);
 }
 
 /** Scatter chart. Prefer `ui.scatterChart`. See {@link ScatterChartProps}. */
-export function scatterChart(props: ScatterChartProps): Element {
+export function scatterChart(props: ScatterChartProps): ChartElement {
   return scatterChartFactory(props);
 }
 
 /** Composed multi-geometry chart. Prefer `ui.composedChart`. See {@link ComposedChartProps}. */
-export function composedChart(props: ComposedChartProps): Element {
+export function composedChart(props: ComposedChartProps): ChartElement {
   return composedChartFactory(props);
 }
 
 /** KPI card with inline sparkline. Prefer `ui.sparkline`. See {@link SparklineProps}. */
-export function sparkline(props: SparklineProps): Element {
+export function sparkline(props: SparklineProps): ChartElement {
   return sparklineFactory(props);
 }