@close-by/clay 0.2.10 → 0.2.12

package/SKILL.md

@@ -116,7 +116,7 @@ Resolve docs programmatically: `resolveClayDocsDir()` from `@close-by/clay/docs-
 
 ## Optional compile-time reactive `let`
 
-Opt-in via `// @clay-reactive` + `clay app.ts --reactive-let`. Prefer explicit `ui.state` + `ui.auto` for production/async-heavy apps.
+Auto-registers when pages use `// @clay-reactive` / `"use reactive"` (`clay` / `loadPages` default). Prefer explicit `ui.state` + `ui.auto` for production/async-heavy apps; force with `--reactive-let` if needed.
 
 ## Package map (monorepo)
 

package/docs/SKILL.md

@@ -116,7 +116,7 @@ Resolve docs programmatically: `resolveClayDocsDir()` from `@close-by/clay/docs-
 
 ## Optional compile-time reactive `let`
 
-Opt-in via `// @clay-reactive` + `clay app.ts --reactive-let`. Prefer explicit `ui.state` + `ui.auto` for production/async-heavy apps.
+Auto-registers when pages use `// @clay-reactive` / `"use reactive"` (`clay` / `loadPages` default). Prefer explicit `ui.state` + `ui.auto` for production/async-heavy apps; force with `--reactive-let` if needed.
 
 ## Package map (monorepo)
 

package/docs/api.md

@@ -1682,17 +1682,18 @@ ui.scrollArea(
 
 #### `ui.viewportEnter(fn, props?)` / `ui.viewportEnter(props, fn)`
 
-IntersectionObserver wrapper. Fires `onEnter` when the element intersects the viewport — default **once**.
+IntersectionObserver wrapper. Fires `onEnter` when the element intersects the scroll root — default **once**, root = browser viewport.
 
 ```typescript
 ui.viewportEnter(
   {
     once: true,
+    root: 'nearest-scroll', // overflow panel / scroll-area, not only the window
     rootMargin: '80px',
-    onEnter: () => void loadSection(),
+    onEnter: () => void loadMore(),
   },
   () => {
-    ui.label('Lazy block');
+    ui.label('Load more…');
   },
 );
 ```
@@ -1702,9 +1703,12 @@ ui.viewportEnter(
 | `className` | `string` | |
 | `onEnter` | `() => void \| Promise<void>` | — client emits `enter` |
 | `once` | `boolean` | `true` |
+| `root` | `'viewport' \| 'nearest-scroll' \| string` | `'viewport'` |
 | `rootMargin` | `string` | `'0px'` |
 | `threshold` | `number \| number[]` | `0` |
 
+`nearest-scroll` walks ancestors for overflow scroll or `[data-slot="scroll-area-viewport"]`. A CSS selector uses `closest` / `querySelector`.
+
 #### `ui.keybind(props)`
 
 Headless keyboard chord listener. Renders nothing; while the node is in the tree the client listens on `window` `keydown`, matches a chord, and emits `press` → `onPress`.

package/docs/boot.md

@@ -90,7 +90,11 @@ Legacy `_clay-reload-*.ts` files under `pages/` (pre-0.2.5) should be deleted; m
 
 ## Reactive-let
 
-The CLI leaves the compile-time `let` transform **off** unless you pass `--reactive-let`. Library mode never registers the Bun loader unless you call `registerReactiveLetPlugin()` yourself. Prefer Phase 1 `ui.state` / `ui.auto` for real apps — see [reactive-let](./reactive-let.md).
+The CLI **auto-registers** the compile-time `let` transform when any loaded page contains `// @clay-reactive` or `"use reactive"`. Force on with `--reactive-let`, force off with `--no-reactive-let`.
+
+`ui.loadPages` does the same scan-before-import in library mode (default `reactiveLet: 'auto'`), so apps no longer need a manual `registerReactiveLetPlugin()` before `loadPages`. Prefer Phase 1 `ui.state` / `ui.auto` for dense/async production apps until you are ready for the pragma path — see [reactive-let](./reactive-let.md).
+
+`configureRun` Tailwind options (`appendCss`, custom `content`, …) are **merged** with CLI defaults; the CLI no longer replaces the whole `tailwind` object.
 
 ## Checklist (avoid drift)
 

package/docs/elements.md

@@ -91,7 +91,7 @@ Each factory creates an `Element` with a wire `type` string. The React client ma
 | `command` | `command` (+ `commandgroup` / `commanditem` / `commandseparator`) | Command palette (`mode: 'dialog' \| 'inline'`; dialog owns `open`) |
 | `resizable` | `resizable` (+ `resizablepanel` / `resizablehandle`) | `react-resizable-panels` |
 | `scrollArea` | `scrollarea` | ShadCN `ScrollArea` (`onNearEnd` for infinite scroll) |
-| `viewportEnter` | `viewportEnter` | IntersectionObserver wrapper (`onEnter`, `once?`) |
+| `viewportEnter` | `viewportEnter` | IntersectionObserver (`onEnter`, `once?`, `root?`) |
 | `keybind` | `keybind` | Headless `window` `keydown` chord listener (`return null`) |
 | `kbd` | `kbd` | Display-only chord glyphs (`Kbd` / `KbdGroup`; same tokens as `keybind`) |
 | `markdown` | `markdown` | Client `marked` + DOMPurify |

package/docs/examples.md

@@ -18,6 +18,7 @@ After `bun run build:client && bun run demo` (or `bun run demo:cli`), open http:
 | `/examples/dashboard` | `Dashboard.ts` | `stat`, `areaChart`, full-chrome `dataTable` (views, editors, detail drawer) |
 | `/examples/datatable` | `DataTableDemo.ts` | Multi-sort (Shift+click / badges), footer aggregates + a11y hints, column pin, remote filter/sort + pagination; density/zebra, editors (Enter/Esc + focus restore), resize, virtualization (≥40, coexists with reorder via windowed drop targets); facets, bulk, collapse/expand, loading/empty; `ui.table` sugar |
 | `/examples/composed` | `ComposedDemo.ts` | ReUI batch 1: `ui.timeline`, `ui.stepper`, `ui.dateRange`, `ui.feedList`/`ui.feedRow`, `ui.sparkline` |
+| `/examples/ops-console` | `OpsConsoleDemo.ts` | Dogfood ops console: `filterBar` → `feedList` → `descriptionList` / `staticTable` (batches 1–7 in one surface) |
 | `/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 |

package/docs/ops-patterns.md

@@ -2,6 +2,8 @@
 
 Dense internal tools (live feeds, master–detail, logs/traces) push Clay past card dashboards. Prefer Phase 1 reactivity ([Concepts](./concepts.md#canonical-recipe-state--auto--timer)) and the helpers below.
 
+**Runnable dogfood:** `/examples/ops-console` (`OpsConsoleDemo.ts`) — one Orders-shaped surface using `filterBar`, `inputGroup`, `feedList`/`feedRow`, `descriptionList`, `staticTable`, `pagination`, `empty`, `notice`, and `toggle`. Use that page to find API friction before adding more wire types.
+
 ## Status chips
 
 ```ts
@@ -37,9 +39,9 @@ const live = ui.state({ selectedId: null as string | null, rows: [] as Row[] });
 
 ui.auto(() => {
   ui.resizable(
-    { orientation: 'horizontal', className: 'h-[calc(100vh-8rem)] w-full min-h-[24rem]' },
+    { orientation: 'horizontal', fill: 'viewport' },
     (r) => {
-      r.panel({ defaultSize: 40, minSize: 28 }, () => {
+      r.panel({ defaultSize: 40, minSize: 28, className: 'min-h-0 overflow-hidden' }, () => {
         ui.auto(() => {
           for (const row of live.rows) {
             ui.button(row.id, {
@@ -52,11 +54,12 @@ ui.auto(() => {
           }
         });
       });
-      r.panel({ defaultSize: 60, minSize: 36 }, () => {
+      r.handle();
+      r.panel({ defaultSize: 60, minSize: 36, className: 'min-h-0 overflow-hidden' }, () => {
         ui.auto(() => {
           const row = live.rows.find((x) => x.id === live.selectedId);
           if (!row) {
-            ui.label('Select a row').classes('text-sm text-muted-foreground');
+            ui.empty({ title: 'Select a row', density: 'inline' });
             return;
           }
           // detail…
@@ -68,7 +71,7 @@ ui.auto(() => {
 });
 ```
 
-Keep **separate** `ui.auto` regions for list vs detail so selection updates do not remount the whole shell. Default panel sizes (`defaultSize` / `minSize`) are percentages.
+Keep **separate** `ui.auto` regions for list vs detail so selection updates do not remount the whole shell. Default panel sizes (`defaultSize` / `minSize`) are percentages. Prefer `fill: 'parent' | 'viewport'` over viewport `calc` height utilities.
 
 ## Live feed rows (not `ui.list`)
 
@@ -154,6 +157,49 @@ ui.auto(() => {
 
 For **`ui.dataTable`**, pass `showFilterChips: true` to surface active search + column filters as removable chips in the table chrome (`views` remain the saved-view tabs API).
 
+## Infinite scroll / load-more
+
+**Blessed pattern for overflow feeds** (master–detail panels): `ui.viewportEnter` with `root: 'nearest-scroll'`. Remount the sentinel while a page is in flight if you need to re-arm after `once: true`:
+
+```ts
+ui.auto(() => {
+  if (live.loadingMore) {
+    ui.label('Loading…', { tone: 'muted', size: 'xs' });
+    return;
+  }
+  if (!live.hasMore) return;
+  ui.viewportEnter(
+    {
+      once: true,
+      root: 'nearest-scroll',
+      rootMargin: '120px',
+      onEnter: () => void loadNextPage(),
+    },
+    () => {
+      ui.label(' ').classes('h-1');
+    },
+  );
+});
+```
+
+Alternative when you already wrap the list in **`ui.scrollArea`**: use `onNearEnd` on the scroll area (scroll-root is built-in). Prefer one pattern per surface — `viewportEnter` + `nearest-scroll` does **not** require `scrollArea`.
+
+## Fewer classes (ops density)
+
+Prefer semantic props over Tailwind soup:
+
+| Instead of… | Prefer… |
+|-------------|---------|
+| `.classes('text-sm text-muted-foreground')` | `ui.label(…, { tone: 'muted', size: 'sm' })` |
+| Title + subtitle stacks | `ui.pageHeading('Orders', { description: '…' })` |
+| `className: 'flex-row w-[10rem]'` on filters | `ui.select({ inline: true, width: 'sm', … })` |
+| `ui.spinner({ className: 'h-3 w-3' })` | `ui.spinner({ size: 'xs' })` |
+| Feed empty muted label | `ui.empty({ title: '…', density: 'inline' })` |
+| `h-[calc(100%-7rem)]!` on resizable | `ui.resizable({ fill: 'parent' \| 'viewport' }, …)` |
+| `className: 'items-end justify-between'` on rows | `ui.row({ align: 'end', justify: 'between' }, …)` |
+
+`className` remains an escape hatch.
+
 ## Logs / traces — sensitive bodies
 
 Structured logs often contain API keys or partner tokens. Scrubbing is the **app’s** job; Clay can still reduce shoulder-surfing:

package/docs/reactive-let.md

@@ -75,17 +75,17 @@ Phase 1 remains the **escape hatch** — copy patterns from [`ReactiveLetOrders.
 
 Package `@close-by/clay-compiler` rewrites a **documented subset** of `let` into Phase 1 APIs.
 
-### Opt-in (required)
+### Opt-in
 
-Both of:
-
-1. **CLI / loader:** pass `--reactive-let` to `clay` (or call `registerReactiveLetPlugin()` yourself). Off by default.
-2. **Source:** one of:
+1. **Source:** one of:
    - File pragma: `// @clay-reactive` (near the top of the file) — applies to **`ui.page` / `page` callbacks only**
    - Block directive as the first statement: `"use reactive";` — required for nested helpers / `ui.column(() => …)` lets
+2. **Loader:** by default, `clay` and `ui.loadPages` **auto-register** the Bun plugin when any scanned page has the pragma / directive. Force with `--reactive-let` / `loadPages(dir, { reactiveLet: true })`; disable with `--no-reactive-let` / `{ reactiveLet: false }`. Manual `registerReactiveLetPlugin()` is still fine (and idempotent).
 
 `ui.page(...)` alone does **not** opt in. Module-level helpers (`function mergeUnits() { … }`) and nested `function` / arrow bodies do **not** inherit the file pragma — use `"use reactive";` inside the page callback or a nested site when needed.
 
+**Hard fail:** a local that shadows lifted state and whose initializer reads that name (`const detail = detail` or `const detail = rows.find(… detail …)`) **refuses to emit** — rename the local. Silent `undefined` after fetch was a hub dogfood failure mode.
+
 ### Who wraps `ui.auto`?
 
 Compile-time region analysis **does not** see into nested function bodies. Authors must still wrap rebuild regions when UI is built from helpers or widget callbacks:
@@ -111,7 +111,8 @@ Inline UI in widget callbacks (`ui.label(expr)`, `ui.icon(…, { className: expr
 | `units.filter(u => { … })` reading lifted state | Plain JS (no `ui.auto` inside filter) | Nothing |
 | `onClick` / `onChange` / `ui.timer` handler | Not a build region | Normal JS |
 | `const live = ui.state({…})` (no pragma) | Unchanged | Explicit `ui.auto` (Phase 1) |
-| Local `const detail = …` shadows lifted `let detail` | Renames in emit + compile warning | Prefer distinct names |
+| Local `const detail = …` shadows lifted `let detail` (no self-read) | Renames in emit + compile warning | Prefer distinct names |
+| Local `const detail = detail` / initializer reads `detail` | **Hard error** — transform refuses to emit | Rename the local |
 
 ### What transforms
 

package/package.json

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

package/src/index.ts

@@ -34,6 +34,7 @@ import {
   pagination as paginationFactory,
   filterBar as filterBarFactory,
   filterChips as filterChipsFactory,
+  pageHeading as pageHeadingFactory,
   numberField as numberFieldFactory,
   phoneInput as phoneInputFactory,
   field as fieldFactory,
@@ -120,7 +121,10 @@ import {
   type ButtonVariant,
   type ButtonSize,
   type LabelProps,
+  type LabelTone,
+  type LabelSize,
   type InputProps,
+  type FieldWidth,
   type CheckboxProps,
   type SwitchProps,
   type SelectProps,
@@ -144,6 +148,7 @@ import {
   type BadgeProps,
   type AlertProps,
   type SpinnerProps,
+  type SpinnerSize,
   type ProgressProps,
   type SeparatorProps,
   type IconProps,
@@ -157,6 +162,8 @@ import {
   type ButtonGroupProps,
   type ButtonGroupOrientation,
   type EmptyProps,
+  type EmptyDensity,
+  type PageHeadingProps,
   type PaginationProps,
   type FilterBarProps,
   type FilterChip,
@@ -253,11 +260,13 @@ import {
   type CommandMode,
   type CommandItemOptions,
   type ResizableProps,
+  type ResizableFill,
   type ResizableOrientation,
   type ResizablePanelProps,
   type ResizableHandleProps,
   type ScrollAreaProps,
   type ViewportEnterProps,
+  type ViewportEnterRoot,
   type KeybindProps,
   type KbdProps,
   type BreadcrumbItem,
@@ -284,7 +293,6 @@ import {
   type HtmlProps,
   type ImageProps,
   type IframeProps,
-  type ViewportEnterProps,
   type UploadProps,
   type UploadVariant,
   type UploadedFile,
@@ -494,7 +502,10 @@ export type {
   ButtonVariant,
   ButtonSize,
   LabelProps,
+  LabelTone,
+  LabelSize,
   InputProps,
+  FieldWidth,
   CheckboxProps,
   BadgeProps,
   LinkProps,
@@ -555,6 +566,7 @@ export type {
   AvatarProps,
   SkeletonProps,
   SpinnerProps,
+  SpinnerSize,
   ProgressProps,
   SeparatorProps,
   IconProps,
@@ -571,6 +583,7 @@ export type {
   ImageProps,
   IframeProps,
   ViewportEnterProps,
+  ViewportEnterRoot,
   UploadProps,
   UploadVariant,
   UploadedFile,
@@ -930,6 +943,11 @@ export function empty(props: EmptyProps, footer?: () => void): Element {
   return emptyFactory(props, footer);
 }
 
+/** Page title + optional description. Prefer over stacked muted labels. */
+export function pageHeading(props: PageHeadingProps, trailing?: () => void): Element {
+  return pageHeadingFactory(props, trailing);
+}
+
 /** Standalone pager. See {@link PaginationProps}. */
 export function pagination(props?: PaginationProps): Element {
   return paginationFactory(props);
@@ -1788,6 +1806,7 @@ export const ui = {
   feedList,
   buttonGroup,
   empty,
+  pageHeading,
   pagination,
   filterBar,
   filterChips,

package/src/pages.ts

@@ -7,6 +7,10 @@ import {
   type PageFn,
 } from '@close-by/clay-core';
 import { warnClayPageIssues } from '@close-by/clay-compiler';
+import {
+  ensureReactiveLetPluginForPaths,
+  registerReactiveLetPlugin,
+} from '@close-by/clay-compiler/plugin';
 import type { AppNavItem } from '@close-by/clay-components';
 
 /**
@@ -109,11 +113,26 @@ function shouldSkipPageFile(relativePath: string): boolean {
  * Clears prior registrations first, then fresh-imports each module (cache-busted)
  * so `--reload` picks up edits. Each module should call `ui.page` once; optional
  * `pageMeta` is attached to the new path.
+ *
+ * When `reactiveLet` is `'auto'` (default), scans pages for `// @clay-reactive` /
+ * `"use reactive"` and registers the Bun plugin **before** imports so library
+ * boot does not need a manual `registerReactiveLetPlugin()` call.
  */
-export async function loadPages(dir: string | URL): Promise<string[]> {
+export async function loadPages(
+  dir: string | URL,
+  opts?: { reactiveLet?: boolean | 'auto' },
+): Promise<string[]> {
   const absDir = typeof dir === 'string' ? dir : fileURLToPath(dir);
   const glob = new Bun.Glob('**/*.{ts,tsx}');
   const files = [...glob.scanSync({ cwd: absDir })].filter((f) => !shouldSkipPageFile(f)).sort();
+  const fullPaths = files.map((relative) => join(absDir, relative));
+
+  const reactiveMode = opts?.reactiveLet ?? 'auto';
+  if (reactiveMode === true) {
+    registerReactiveLetPlugin();
+  } else if (reactiveMode === 'auto') {
+    await ensureReactiveLetPluginForPaths(fullPaths);
+  }
 
   clearPages();
   clearPageMeta();