@close-by/clay 0.2.1 → 0.2.3

package/package.json

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

package/src/index.ts

@@ -52,6 +52,7 @@ import {
   command as commandFactory,
   resizable as resizableFactory,
   scrollArea as scrollAreaFactory,
+  viewportEnter as viewportEnterFactory,
   keybind as keybindFactory,
   kbd as kbdFactory,
   sheet as sheetFactory,
@@ -66,6 +67,7 @@ import {
   markdown as markdownFactory,
   html as htmlFactory,
   image as imageFactory,
+  iframe as iframeFactory,
   upload as uploadFactory,
   rating as ratingFactory,
   colorPicker as colorPickerFactory,
@@ -175,6 +177,7 @@ import {
   type ResizablePanelProps,
   type ResizableHandleProps,
   type ScrollAreaProps,
+  type ViewportEnterProps,
   type KeybindProps,
   type KbdProps,
   type BreadcrumbItem,
@@ -200,6 +203,8 @@ import {
   type MarkdownProps,
   type HtmlProps,
   type ImageProps,
+  type IframeProps,
+  type ViewportEnterProps,
   type UploadProps,
   type UploadVariant,
   type UploadedFile,
@@ -383,8 +388,23 @@ import {
   type NavFromPagesOptions,
 } from './pages';
 import { resolveClayClientDir } from './client-dir';
+import {
+  detectClayTailwindContent,
+  ensureClayTailwindCss,
+  mergeClayCss,
+  type ClayTailwindOptions,
+} from './tailwind';
+
 
 export { resolveClayClientDir } from './client-dir';
+export {
+  detectClayTailwindContent,
+  ensureClayTailwindCss,
+  mergeClayCss,
+  type ClayTailwindOptions,
+  type ClayTailwindResult,
+} from './tailwind';
+
 
 export type {
   ButtonProps,
@@ -459,6 +479,8 @@ export type {
   MarkdownProps,
   HtmlProps,
   ImageProps,
+  IframeProps,
+  ViewportEnterProps,
   UploadProps,
   UploadVariant,
   UploadedFile,
@@ -759,6 +781,11 @@ export function image(src: string, props?: ImageProps): Element {
   return imageFactory(src, props);
 }
 
+/** Iframe embed. Prefer `ui.iframe`. See {@link IframeProps}. */
+export function iframe(src: string, props?: IframeProps): Element {
+  return iframeFactory(src, props);
+}
+
 /** File upload control (`POST /upload`). Prefer `ui.upload`. See {@link UploadProps}. */
 export function upload(props?: UploadProps): Element {
   return uploadFactory(props);
@@ -1100,6 +1127,23 @@ export function scrollArea(a: any, b?: any): Element {
   return scrollAreaFactory(a, b);
 }
 
+/**
+ * Observe when children enter the viewport (IntersectionObserver).
+ * Prefer `ui.viewportEnter`. See {@link ViewportEnterProps}.
+ *
+ * @example
+ * ```ts
+ * ui.viewportEnter({ onEnter: () => void loadMore(), once: true }, () => {
+ *   ui.label('Lazy section');
+ * });
+ * ```
+ */
+export function viewportEnter(fn: () => void, props?: ViewportEnterProps): Element;
+export function viewportEnter(props: ViewportEnterProps, fn: () => void): Element;
+export function viewportEnter(a: any, b?: any): Element {
+  return viewportEnterFactory(a, b);
+}
+
 /**
  * Headless keyboard chord listener. Prefer `ui.keybind`. See {@link KeybindProps}.
  *
@@ -1333,8 +1377,61 @@ export function page(path: string, fn: () => void, options?: PageOptions): void
 export type RunConfig = ClayServerConfig & {
   /** Global dashboard shell; wraps every page unless `ui.page(..., { shell: false })`. */
   app?: AppProps;
+  /**
+   * Auto-build Tailwind utilities from app modules and inject after the client CSS.
+   *
+   * - `undefined` — on when `pages/`, `src/`, or `app/` exists under cwd
+   * - `true` — same auto-detect
+   * - `false` — off
+   * - object — custom `content` paths, `watch`, `appendCss`, …
+   *
+   * Scans `className` / `.classes(...)` strings; no app-level Tailwind config required.
+   */
+  tailwind?: boolean | (Omit<ClayTailwindOptions, 'content'> & { content?: string[] });
 };
 
+const pathDelimiter = process.platform === 'win32' ? ';' : ':';
+
+function applyClayTailwind(cfg: RunConfig): RunConfig {
+  if (cfg.tailwind === false || process.env.CLAY_NO_TAILWIND === '1') {
+    return { ...cfg, tailwind: false };
+  }
+
+  const tw = cfg.tailwind;
+  const cwd = process.cwd();
+  const envContent = process.env.CLAY_TAILWIND_CONTENT?.split(pathDelimiter).filter(Boolean) ?? [];
+
+  const opts =
+    tw === undefined || tw === true
+      ? {
+          content: envContent.length ? envContent : detectClayTailwindContent(cwd),
+          watch: process.env.CLAY_TAILWIND_WATCH === '1',
+        }
+      : {
+          content: tw.content?.length
+            ? tw.content
+            : envContent.length
+              ? envContent
+              : detectClayTailwindContent(cwd),
+          watch: tw.watch ?? process.env.CLAY_TAILWIND_WATCH === '1',
+          appendCss: tw.appendCss,
+          outFile: tw.outFile,
+          cwd: tw.cwd ?? cwd,
+        };
+
+  if (!opts.content.length) return cfg;
+
+  const { cssPath } = ensureClayTailwindCss({
+    content: opts.content,
+    cwd: opts.cwd ?? cwd,
+    watch: opts.watch,
+    appendCss: opts.appendCss,
+    outFile: opts.outFile,
+  });
+
+  return { ...cfg, css: mergeClayCss(cfg.css, cssPath) };
+}
+
 let runCalled = false;
 
 /** Whether `ui.run` has been invoked in this process (used by the `clay` CLI). */
@@ -1374,7 +1471,9 @@ export function run(rootOrConfig: PageFn | RunConfig = {}, config: RunConfig = {
     cfg = { ...cfg, clientDir: resolveClayClientDir() };
   }
 
-  const { app: appProps, ...serverConfig } = cfg;
+  cfg = applyClayTailwind(cfg);
+
+  const { app: appProps, tailwind: _tailwind, ...serverConfig } = cfg;
   if (appProps) {
     setPageWrapper((pageFn) => app(appProps, pageFn));
   } else {
@@ -1415,6 +1514,7 @@ export const ui = {
   markdown,
   html,
   image,
+  iframe,
   upload,
   rating,
   colorPicker,
@@ -1463,6 +1563,7 @@ export const ui = {
   command,
   resizable,
   scrollArea,
+  viewportEnter,
   keybind,
   kbd,
   breadcrumb,

package/src/tailwind.ts

@@ -0,0 +1,238 @@
+/**
+ * Zero-config Tailwind for Clay apps: scan page modules, emit utilities CSS,
+ * inject via `ui.run({ css })` / CLI.
+ *
+ * Uses `@tailwindcss/cli` (utilities + theme only — client already ships base/preflight).
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { createRequire } from 'module';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+export type ClayTailwindOptions = {
+  /**
+   * Directories/files to scan for `className` / `.classes(...)` strings.
+   * Absolute or cwd-relative. Prefer app dirs — never the repo root with `node_modules`.
+   */
+  content: string[];
+  /** Working directory for relative paths. Default `process.cwd()`. */
+  cwd?: string;
+  /** Output CSS path. Default `<cwd>/.clay/tailwind.css`. */
+  outFile?: string;
+  /** Keep `@tailwindcss/cli --watch` running after the first build. */
+  watch?: boolean;
+  /** Extra CSS appended after the generated input (token overrides, keyframes). */
+  appendCss?: string;
+};
+
+export type ClayTailwindResult = {
+  cssPath: string;
+  /** Stop the background watch process (if any). */
+  stop: () => void;
+};
+
+const THEME_SNIPPET = `
+/* Token utilities for app-scanned classes (vars come from the Clay client). */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+`.trim();
+
+function resolveContentPaths(content: string[], cwd: string): string[] {
+  const out: string[] = [];
+  for (const raw of content) {
+    const p = isAbsolute(raw) ? raw : resolve(cwd, raw);
+    if (existsSync(p)) out.push(p);
+  }
+  return out;
+}
+
+/** Guess scan roots under `cwd` (`pages/`, `src/`, `app/`). */
+export function detectClayTailwindContent(cwd = process.cwd()): string[] {
+  const candidates = ['pages', 'src', 'app'];
+  return candidates.map((d) => join(cwd, d)).filter((p) => existsSync(p));
+}
+
+function resolveTailwindcssRoot(): string {
+  const require = createRequire(import.meta.url);
+  const tryPkg = (req: NodeJS.Require): string | null => {
+    try {
+      return dirname(req.resolve('tailwindcss/package.json'));
+    } catch {
+      return null;
+    }
+  };
+  const fromUi = tryPkg(require);
+  if (fromUi) return fromUi;
+  try {
+    const rootReq = createRequire(
+      join(fileURLToPath(new URL('.', import.meta.url)), '../../../package.json'),
+    );
+    const fromRoot = tryPkg(rootReq);
+    if (fromRoot) return fromRoot;
+  } catch {
+    // ignore
+  }
+  throw new Error(
+    'tailwindcss package not found. Install with: bun add tailwindcss @tailwindcss/cli',
+  );
+}
+
+function writeInputCss(inputFile: string, sources: string[], appendCss?: string): void {
+  mkdirSync(dirname(inputFile), { recursive: true });
+  const twRoot = resolveTailwindcssRoot();
+  // Absolute CSS imports so builds work even when `.clay/` is outside node_modules.
+  const themeCss = join(twRoot, 'theme.css');
+  const utilitiesCss = join(twRoot, 'utilities.css');
+  const sourceLines = sources.map((s) => `@source ${JSON.stringify(s)};`).join('\n');
+  const body = [
+    '/* Generated by @close-by/clay — do not edit */',
+    `@import ${JSON.stringify(themeCss)} layer(theme);`,
+    `@import ${JSON.stringify(utilitiesCss)} layer(utilities);`,
+    '',
+    sourceLines,
+    '',
+    THEME_SNIPPET,
+    appendCss ? `\n${appendCss.trim()}\n` : '',
+  ].join('\n');
+  writeFileSync(inputFile, body, 'utf8');
+}
+
+function resolveTailwindCliEntry(): string {
+  const require = createRequire(import.meta.url);
+  const tryPkg = (req: NodeJS.Require): string | null => {
+    try {
+      const pkgJsonPath = req.resolve('@tailwindcss/cli/package.json');
+      return join(dirname(pkgJsonPath), 'dist/index.mjs');
+    } catch {
+      return null;
+    }
+  };
+
+  const fromUi = tryPkg(require);
+  if (fromUi && existsSync(fromUi)) return fromUi;
+
+  try {
+    const rootReq = createRequire(
+      join(fileURLToPath(new URL('.', import.meta.url)), '../../../package.json'),
+    );
+    const fromRoot = tryPkg(rootReq);
+    if (fromRoot && existsSync(fromRoot)) return fromRoot;
+  } catch {
+    // ignore
+  }
+
+  throw new Error(
+    'Tailwind CLI not found. Install with: bun add tailwindcss @tailwindcss/cli\n' +
+      '(shipped with @close-by/clay — ensure the package is installed).',
+  );
+}
+
+/**
+ * Build (and optionally watch) Tailwind CSS for Clay page modules.
+ * Returns a stylesheet path suitable for `ui.run({ css })`.
+ */
+export function ensureClayTailwindCss(options: ClayTailwindOptions): ClayTailwindResult {
+  const cwd = options.cwd ?? process.cwd();
+  const sources = resolveContentPaths(options.content, cwd);
+  if (sources.length === 0) {
+    throw new Error(
+      'Clay Tailwind: no content paths found. Pass content: ["./pages"] or create a pages/ directory.',
+    );
+  }
+
+  const outFile = options.outFile
+    ? isAbsolute(options.outFile)
+      ? options.outFile
+      : resolve(cwd, options.outFile)
+    : join(cwd, '.clay', 'tailwind.css');
+  const inputFile = join(dirname(outFile), 'tailwind.input.css');
+  mkdirSync(dirname(outFile), { recursive: true });
+  writeInputCss(inputFile, sources, options.appendCss);
+
+  const cliEntry = resolveTailwindCliEntry();
+  const buildArgs = [cliEntry, '-i', inputFile, '-o', outFile];
+
+  const built = Bun.spawnSync({
+    cmd: [process.execPath, ...buildArgs],
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  if (built.exitCode !== 0) {
+    const err = built.stderr.toString() || built.stdout.toString() || `exit ${built.exitCode}`;
+    throw new Error(`Clay Tailwind build failed:\n${err}`);
+  }
+  if (!existsSync(outFile)) {
+    throw new Error(`Clay Tailwind build produced no file at ${outFile}`);
+  }
+
+  let child: ReturnType<typeof Bun.spawn> | null = null;
+  if (options.watch) {
+    child = Bun.spawn({
+      cmd: [process.execPath, ...buildArgs, '--watch'],
+      cwd,
+      stdout: 'ignore',
+      stderr: 'inherit',
+      stdin: 'ignore',
+    });
+  }
+
+  return {
+    cssPath: outFile,
+    stop: () => {
+      if (!child) return;
+      try {
+        child.kill();
+      } catch {
+        // already exited
+      }
+      child = null;
+    },
+  };
+}
+
+/** Merge a Tailwind stylesheet into existing `css` config (append). */
+export function mergeClayCss(
+  existing: string | string[] | undefined,
+  extra: string | string[],
+): string[] {
+  const a = existing == null ? [] : Array.isArray(existing) ? existing : [existing];
+  const b = Array.isArray(extra) ? extra : [extra];
+  return [...a, ...b].map((p) => p.trim()).filter(Boolean);
+}