@ozsarman/clarityjs 0.6.0

package/types/index.d.ts

@@ -0,0 +1,366 @@
+/**
+ * Clarity.js — AI-Native UI Framework
+ * TypeScript ambient declarations for the compiler/runtime API.
+ *
+ * The .clarity DSL is compiled to vanilla JS by the Clarity compiler.
+ * These types describe the public API of the compiler and runtime that
+ * TypeScript users interact with directly (e.g., calling compile() or
+ * mounting components from JS/TS code).
+ */
+
+// ─── Runtime Types ────────────────────────────────────────────────────────────
+
+/** A reactive value container. Read with .get(), write with .set(). */
+export interface Signal<T> {
+  get(): T;
+  set(value: T): void;
+  update(fn: (current: T) => T): void;
+  peek(): T;
+  readonly _type: 'signal';
+  readonly _subscribers: Set<unknown>;
+}
+
+/** A read-only derived value. Recomputes lazily when dependencies change. */
+export interface Computed<T> {
+  get(): T;
+  peek(): T;
+  readonly _type: 'computed';
+}
+
+/** The AI contract attached to a mounted component's root DOM element. */
+export interface AIContract {
+  /** Component name for display / debugging. */
+  component: string;
+  /** Getters for each declared-readable signal. */
+  readable: Record<string, () => unknown>;
+  /** Returns a plain-object snapshot of all readable state. */
+  snapshot(): Record<string, unknown>;
+  /** Callable actions declared safe for AI agents. */
+  actionable: Record<string, (...args: unknown[]) => unknown>;
+  /** Invoke a declared action by name. */
+  act(name: string, ...args: unknown[]): unknown;
+  /** Names that AI agents must never read or modify. */
+  forbidden: string[];
+}
+
+// ─── Runtime API ─────────────────────────────────────────────────────────────
+
+/** Create a reactive signal with an initial value. */
+export declare function signal<T>(initialValue: T): Signal<T>;
+
+/** Run a function reactively; re-runs whenever its signal dependencies change. */
+export declare function effect(fn: () => void | (() => void)): () => void;
+
+/** Create a read-only computed value derived from other signals. */
+export declare function computed<T>(fn: () => T): Computed<T>;
+
+/** Batch multiple signal writes — effects flush once after all updates. */
+export declare function batch(fn: () => void): void;
+
+/** A Clarity component function: receives props, returns a DOM element. */
+export type ClarityComponent<P extends Record<string, unknown> = Record<string, unknown>> =
+  (props?: P) => HTMLElement;
+
+/** Mount a Clarity component into a container DOM element. */
+export declare function mount<P extends Record<string, unknown> = Record<string, unknown>>(
+  ComponentFn: ClarityComponent<P>,
+  container: HTMLElement,
+  props?: P
+): () => void;
+
+// ─── Hydration API ─────────────────────────────────────────────────────────────
+
+export interface HydrateRootResult {
+  /** Remove the component, dispose all effects, and clean up the container. */
+  unmount: () => void;
+}
+
+/**
+ * Attach client-side reactivity to server-rendered HTML.
+ *
+ * Call this on the client entry point after importing the same component
+ * that was used in `renderToDocument()` on the server.
+ *
+ * @example
+ * ```ts
+ * import { hydrateRoot } from '@ozsarman/clarityjs/hydrate';
+ * import { App } from './App.js';
+ *
+ * hydrateRoot(document.getElementById('app')!, App);
+ * ```
+ */
+export declare function hydrateRoot<P extends Record<string, unknown> = Record<string, unknown>>(
+  container: Element,
+  ComponentFn: ClarityComponent<P>,
+  props?: Omit<P, '__ssr'>
+): HydrateRootResult;
+
+/**
+ * Returns true if the given container has already been hydrated by Clarity.
+ */
+export declare function isHydrated(container: Element | null | undefined): boolean;
+
+/**
+ * Read the server-serialised state object (`window.__CLARITY_DATA__`).
+ * Returns an empty object when not available (client-only render, test env).
+ */
+export declare function getSSRData(): Record<string, unknown>;
+
+// ─── Error Boundary ────────────────────────────────────────────────────────────
+
+export interface ErrorBoundaryOptions {
+  /**
+   * Child component factory — called to produce the protected content.
+   * Any error thrown here is caught by the boundary.
+   */
+  children: (() => HTMLElement | Node) | HTMLElement | Node;
+  /**
+   * Fallback UI to display when an error is caught.
+   * Can be a function that receives the Error and returns a Node,
+   * or a static Node.  Defaults to a styled dev-friendly error box.
+   */
+  fallback?: ((error: Error) => Node) | Node;
+  /**
+   * Called when an error is caught.  Use for logging or telemetry.
+   */
+  onError?: (error: Error) => void;
+}
+
+export interface ErrorBoundaryElement extends HTMLElement {
+  /** Re-renders the child content, clearing any caught error state. */
+  reset(): void;
+  /** Returns the currently caught Error, or null when healthy. */
+  getError(): Error | null;
+}
+
+/**
+ * Wrap a component subtree in an error boundary.
+ * Errors thrown during the child's initial render are caught and the
+ * fallback UI is shown instead of crashing the page.
+ *
+ * @example
+ * ```ts
+ * mount(
+ *   () => ErrorBoundary({
+ *     children: () => MyComponent({ data }),
+ *     fallback: (err) => h('p', {}, [err.message]),
+ *     onError:  (err) => logger.error(err),
+ *   }),
+ *   document.getElementById('app')!
+ * );
+ * ```
+ */
+export declare function ErrorBoundary(options: ErrorBoundaryOptions): ErrorBoundaryElement;
+
+/**
+ * Query the AI contract for a DOM element (or its nearest Clarity ancestor).
+ * Returns null if the element has no Clarity component above it.
+ */
+export declare function aiQuery(element: Element): AIContract | null;
+
+/** Returns all live Clarity components that have declared AI contracts. */
+export declare function aiDiscover(): AIContract[];
+
+// ─── Compiler API ─────────────────────────────────────────────────────────────
+
+export interface CompileOptions {
+  /** Filename used in error messages and source maps. */
+  filename?: string;
+  /** Runtime import path (default: './clarity-runtime.js'). */
+  runtimePath?: string;
+  /** Emit a V3 source map inline in the output. */
+  sourceMap?: boolean;
+  /** Generate TypeScript .d.ts declarations. */
+  types?: boolean;
+}
+
+export interface CompileResult {
+  /** Generated JavaScript source. */
+  code: string;
+  /** V3 source map (populated when sourceMap: true). */
+  map: object | null;
+  /** TypeScript declaration string (populated when types: true). */
+  dts: string;
+  /** Parsed AST (useful for tooling). */
+  ast: object;
+  /** Flat token array (useful for tooling). */
+  tokens: unknown[];
+}
+
+/** Compile a .clarity source string to JavaScript. */
+export declare function compile(source: string, options?: CompileOptions): CompileResult;
+
+/** Tokenize a .clarity source string (returns the raw token array). */
+export declare function tokenize(source: string, filename?: string): unknown[];
+
+/** Parse a token array to an AST. */
+export declare function parse(tokens: unknown[], source?: string): object;
+
+// ─── Async State — createQuery / createMutation ────────────────────────────────
+
+export interface CreateQueryOptions<T = unknown> {
+  /** Set false to disable auto-fetch on creation (default: true). */
+  enabled?: boolean;
+  /** Milliseconds until cached data is considered stale (default: 30 000). */
+  staleTime?: number;
+  /** Milliseconds to keep data in the global cache after last use (default: 300 000). */
+  cacheTime?: number;
+  /** Number of automatic retries on fetch failure (default: 3). */
+  retry?: number;
+  /** Fixed delay in ms, or a function `(attempt) => ms` for exponential back-off. */
+  retryDelay?: number | ((attempt: number) => number);
+  /** Re-fetch when the browser tab regains focus (default: true). */
+  refetchOnWindowFocus?: boolean;
+  /** Polling interval in ms; false/0 to disable (default: false). */
+  refetchInterval?: number | false;
+  /** Called after a successful fetch. */
+  onSuccess?: (data: T, key: string) => void;
+  /** Called after all retries are exhausted. */
+  onError?: (error: Error, key: string) => void;
+  /** Pre-seed data — skips the first network fetch. */
+  initialData?: T;
+  /** When true, `invalidate()` triggers an immediate background refetch (default: true). */
+  invalidateImmediately?: boolean;
+}
+
+/** Reactive data-fetching state object returned by `createQuery`. */
+export interface QueryState<T = unknown> {
+  /** Current data — `undefined` while the first fetch is in-flight. */
+  readonly data: Signal<T | undefined>;
+  /** Current error — `null` when healthy. */
+  readonly error: Signal<Error | null>;
+  /** `true` while the initial (loading) fetch is in-flight. */
+  readonly loading: Signal<boolean>;
+  /** `true` when serving stale cached data while a background refetch is running. */
+  readonly stale: Signal<boolean>;
+  /** Force a refetch regardless of cache freshness. */
+  refetch(): Promise<void>;
+  /**
+   * Optimistic update — set data immediately, optionally revalidate.
+   * @param updater New value, or an updater function `(current) => next`.
+   */
+  mutate(updater: T | ((current: T | undefined) => T), options?: { revalidate?: boolean }): void;
+  /** Mark as stale and optionally trigger a background refetch. */
+  invalidate(): void;
+  /** Best-effort cancellation of any in-flight request. */
+  cancel(): void;
+  /** Dispose timers and event listeners. Call when unmounting. */
+  dispose(): void;
+}
+
+/**
+ * Create a reactive, cached, auto-fetching data source.
+ *
+ * @param key     Cache key string, or a reactive function `() => string` that
+ *                re-fetches automatically when the returned key changes.
+ * @param fetchFn Async function that receives the resolved key and returns data.
+ * @param options Optional configuration.
+ *
+ * @example
+ * ```ts
+ * const todos = createQuery(
+ *   'todos',
+ *   () => fetch('/api/todos').then(r => r.json()),
+ *   { staleTime: 60_000 }
+ * );
+ *
+ * // Dynamic key — re-fetches when userId signal changes
+ * const post = createQuery(
+ *   () => `post/${userId.get()}`,
+ *   (key) => fetch(`/api/${key}`).then(r => r.json())
+ * );
+ * ```
+ */
+export declare function createQuery<T = unknown>(
+  key: string | (() => string),
+  fetchFn: (key: string) => Promise<T>,
+  options?: CreateQueryOptions<T>
+): QueryState<T>;
+
+export interface CreateMutationOptions<T = unknown, V = unknown> {
+  /** Called after a successful mutation. */
+  onSuccess?: (data: T, variables: V) => void;
+  /** Called when the mutation throws. */
+  onError?: (error: Error, variables: V) => void;
+  /** Called after either success or failure. */
+  onSettled?: (data: T | null, error: Error | null, variables: V) => void;
+  /** Query key(s) to invalidate on success. */
+  invalidates?: string | string[];
+}
+
+export interface MutationState<T = unknown, V = unknown> {
+  /** Execute the mutation. Throws on failure so callers can catch. */
+  mutate(variables: V): Promise<T>;
+  /** `true` while the mutation is in-flight. */
+  readonly loading: Signal<boolean>;
+  /** Current error — `null` when healthy. */
+  readonly error: Signal<Error | null>;
+  /** Data returned by the last successful mutation. */
+  readonly data: Signal<T | undefined>;
+  /** Reset loading/error/data to their initial states. */
+  reset(): void;
+}
+
+/**
+ * Create a reactive mutation for POST / PUT / DELETE operations.
+ *
+ * @example
+ * ```ts
+ * const addTodo = createMutation(
+ *   (title: string) =>
+ *     fetch('/api/todos', { method: 'POST', body: JSON.stringify({ title }) })
+ *       .then(r => r.json()),
+ *   { invalidates: 'todos' }
+ * );
+ *
+ * await addTodo.mutate('Buy milk');
+ * ```
+ */
+export declare function createMutation<T = unknown, V = unknown>(
+  mutateFn: (variables: V) => Promise<T>,
+  options?: CreateMutationOptions<T, V>
+): MutationState<T, V>;
+
+// ─── Developer Tools ────────────────────────────────────────────────────────────
+
+export interface DevtoolsOptions {
+  /** Whether the panel starts in the open/visible state (default: false). */
+  open?: boolean;
+  /** Corner to anchor the panel: 'tl' | 'tr' | 'bl' | 'br' (default: 'br'). */
+  position?: 'tl' | 'tr' | 'bl' | 'br';
+  /** DOM element to mount the devtools into (default: document.body). */
+  container?: HTMLElement;
+}
+
+export interface DevtoolsHandle {
+  /** Remove the devtools overlay from the DOM and clean up all listeners. */
+  dispose(): void;
+}
+
+/**
+ * Mount the Clarity in-page developer tools overlay.
+ *
+ * The panel is encapsulated in a Shadow DOM so it never conflicts with
+ * the host page's styles.  Keyboard shortcut: Ctrl+Shift+D / ⌘⇧D.
+ *
+ * This is a no-op in environments without `document` (SSR / Node.js).
+ *
+ * @example
+ * ```ts
+ * import { initDevtools } from '@ozsarman/clarityjs/devtools';
+ * if (import.meta.env.DEV) initDevtools({ open: true });
+ * ```
+ */
+export declare function initDevtools(options?: DevtoolsOptions): DevtoolsHandle;
+
+/** Manually remove a query from the global cache by key. */
+export declare function invalidateQuery(key: string): void;
+
+/** Pre-populate the global cache (useful for SSR → client state transfer). */
+export declare function prefetchQuery<T = unknown>(key: string, data: T): void;
+
+/** Clear the entire query cache. */
+export declare function clearQueryCache(): void;
+
+/** Read a raw cache entry (useful for testing or SSR state inspection). */
+export declare function getCacheEntry<T = unknown>(key: string): { data: T; timestamp: number } | undefined;