@close-by/clay 0.2.11 → 0.2.13

package/docs/boot.md

@@ -2,6 +2,18 @@
 
 Clay has two entry styles. Prefer **one production path** (library mode) and treat the CLI as a thin dev wrapper so port, CSS, and `clientDir` do not drift.
 
+### Dev HTML comments
+
+When `dev` is on (default unless `NODE_ENV=production`, or set `ui.run({ dev: true })`), the shell sets `window.__CLAY_DEV__` and the client inserts HTML comments around each wire node:
+
+```html
+<!-- clay:staticTable -->
+…table markup…
+<!-- /clay:staticTable -->
+```
+
+Pass `dev: false` to disable.
+
 ## Recommended production path — library mode
 
 ```typescript

package/docs/elements.md

@@ -34,7 +34,7 @@ Each factory creates an `Element` with a wire `type` string. The React client ma
 | `inputGroup` | `inputGroup` | Input with prefix/suffix addons |
 | `toggle` | `toggle` | Pressed toolbar toggle |
 | `descriptionList` | `descriptionList` | Key-value detail rows |
-| `staticTable` | `staticTable` | Read-only HTML table |
+| `staticTable` | `staticTable` | Read-only HTML table (`bordered`/`hoverable` default on; `density`, `emptyTitle`, column `mono`) |
 | `aspectRatio` | `aspectRatio` | Fixed-ratio child wrapper |
 | `itemList` | `itemList` | Settings / notification rows |
 | `checkboxGroup` | `checkboxGroup` | Multi-select checkboxes |
@@ -76,6 +76,7 @@ Each factory creates an `Element` with a wire `type` string. The React client ma
 | `badge` | `badge` | ShadCN `Badge` |
 | `alert` | `alert` | Bordered alert box |
 | `spinner` | `spinner` | Lucide spinner |
+| `spacer` | `spacer` | Fixed gap (`orientation` default `horizontal`; `size` xs–xl) |
 | `skeleton` | `skeleton` | ShadCN `Skeleton` placeholder |
 | `avatar` | `avatar` | ShadCN `Avatar` (+ fallback) |
 | `progress` | `progress` | ShadCN `Progress` (0–100) |

package/docs/ops-patterns.md

@@ -39,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, {
@@ -54,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…
@@ -70,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`)
 
@@ -163,7 +164,7 @@ For **`ui.dataTable`**, pass `showFilterChips: true` to surface active search +
 ```ts
 ui.auto(() => {
   if (live.loadingMore) {
-    ui.label('Loading…').classes('text-xs text-muted-foreground p-2');
+    ui.label('Loading…', { tone: 'muted', size: 'xs' });
     return;
   }
   if (!live.hasMore) return;
@@ -183,6 +184,23 @@ ui.auto(() => {
 
 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: 'mb-2'` between uneven blocks | Parent `column({ gap })`, or `ui.spacer({ orientation: 'vertical', size: 'md' })` |
+
+Prefer even stacks via parent `gap`. Use `ui.spacer` for uneven breaks (`orientation` default **`horizontal`**; `vertical` for column stacks). `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/package.json

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

package/src/index.ts

@@ -34,6 +34,8 @@ import {
   pagination as paginationFactory,
   filterBar as filterBarFactory,
   filterChips as filterChipsFactory,
+  pageHeading as pageHeadingFactory,
+  spacer as spacerFactory,
   numberField as numberFieldFactory,
   phoneInput as phoneInputFactory,
   field as fieldFactory,
@@ -120,7 +122,10 @@ import {
   type ButtonVariant,
   type ButtonSize,
   type LabelProps,
+  type LabelTone,
+  type LabelSize,
   type InputProps,
+  type FieldWidth,
   type CheckboxProps,
   type SwitchProps,
   type SelectProps,
@@ -144,6 +149,7 @@ import {
   type BadgeProps,
   type AlertProps,
   type SpinnerProps,
+  type SpinnerSize,
   type ProgressProps,
   type SeparatorProps,
   type IconProps,
@@ -157,6 +163,11 @@ import {
   type ButtonGroupProps,
   type ButtonGroupOrientation,
   type EmptyProps,
+  type EmptyDensity,
+  type PageHeadingProps,
+  type SpacerProps,
+  type SpacerSize,
+  type SpacerOrientation,
   type PaginationProps,
   type FilterBarProps,
   type FilterChip,
@@ -181,6 +192,7 @@ import {
   type DescriptionListItem,
   type StaticTableProps,
   type StaticTableColumn,
+  type StaticTableDensity,
   type AspectRatioProps,
   type ItemListProps,
   type ItemListEntry,
@@ -253,6 +265,7 @@ import {
   type CommandMode,
   type CommandItemOptions,
   type ResizableProps,
+  type ResizableFill,
   type ResizableOrientation,
   type ResizablePanelProps,
   type ResizableHandleProps,
@@ -494,7 +507,10 @@ export type {
   ButtonVariant,
   ButtonSize,
   LabelProps,
+  LabelTone,
+  LabelSize,
   InputProps,
+  FieldWidth,
   CheckboxProps,
   BadgeProps,
   LinkProps,
@@ -555,6 +571,7 @@ export type {
   AvatarProps,
   SkeletonProps,
   SpinnerProps,
+  SpinnerSize,
   ProgressProps,
   SeparatorProps,
   IconProps,
@@ -931,6 +948,19 @@ 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);
+}
+
+/**
+ * Explicit space between siblings. Default orientation is horizontal (width).
+ * Prefer parent `gap` for even stacks; use spacer for uneven breaks.
+ */
+export function spacer(props?: SpacerProps): Element {
+  return spacerFactory(props);
+}
+
 /** Standalone pager. See {@link PaginationProps}. */
 export function pagination(props?: PaginationProps): Element {
   return paginationFactory(props);
@@ -1789,6 +1819,8 @@ export const ui = {
   feedList,
   buttonGroup,
   empty,
+  pageHeading,
+  spacer,
   pagination,
   filterBar,
   filterChips,