@procedures/splay 0.0.0-stage → 0.1.0

package/src/components/types.ts

@@ -0,0 +1,357 @@
+/**
+ * Component Types
+ *
+ * Components are procedures that return serializable UI descriptors.
+ * This enables SSR, caching, and transport over wire.
+ *
+ * Components integrate with splay's rendering model where a renderer
+ * produces output based on data, size, and path context.
+ */
+
+import type { ZodLike } from "@procedures/client/client";
+import type { ProcedureMetadata, ProcedurePath } from "@procedures/client";
+import type { IEventBus as EventBus } from "@procedures/client";
+
+// =============================================================================
+// Component Output (Serializable Descriptor)
+// =============================================================================
+
+/**
+ * Serializable component output descriptor.
+ * Can be transported over wire, cached, and hydrated by any framework.
+ *
+ * @example
+ * ```typescript
+ * const descriptor: ComponentOutput = {
+ *   type: "user-card",
+ *   props: {
+ *     name: "John Doe",
+ *     avatar: "/images/john.png",
+ *   },
+ *   children: [
+ *     { type: "badge", props: { label: "Admin" } },
+ *   ],
+ * };
+ * ```
+ */
+export interface ComponentOutput {
+  /** Component type identifier (maps to registered component) */
+  type: string;
+
+  /** Serializable props for the component */
+  props: Record<string, unknown>;
+
+  /** Nested child descriptors (optional) */
+  children?: ComponentOutput[];
+
+  /** Component key for reconciliation (optional) */
+  key?: string;
+}
+
+/**
+ * Fragment output - multiple components without wrapper.
+ */
+export interface FragmentOutput {
+  type: "__fragment__";
+  children: ComponentOutput[];
+}
+
+/**
+ * Null output - render nothing.
+ */
+export interface NullOutput {
+  type: "__null__";
+}
+
+/**
+ * Any valid component output.
+ */
+export type AnyComponentOutput = ComponentOutput | FragmentOutput | NullOutput;
+
+// =============================================================================
+// Component Context (splay-compatible)
+// =============================================================================
+
+/**
+ * Size information for responsive rendering.
+ */
+export interface Size {
+  width: number;
+  height: number;
+}
+
+/**
+ * Context passed to component factories.
+ * Compatible with splay's RenderContext.
+ *
+ * @example
+ * ```typescript
+ * factory: (ctx) => ({
+ *   type: "user-card",
+ *   props: {
+ *     user: ctx.data,
+ *     compact: ctx.size.width < 400,
+ *   },
+ *   children: ctx.data.posts?.map((post, i) =>
+ *     ctx.render(post, ctx.size, `${ctx.path}.posts[${i}]`)
+ *   ),
+ * })
+ * ```
+ */
+export interface ComponentContext<TData = unknown> {
+  /** Input data for the component */
+  data: TData;
+
+  /** Available rendering size */
+  size: Size;
+
+  /** Path in the render tree (for debugging and keys) */
+  path: string;
+
+  /** Current depth in the render tree */
+  depth: number;
+
+  /**
+   * Render a child component.
+   * Delegates to the renderer to produce a ComponentOutput.
+   *
+   * @param data - Data for the child component
+   * @param size - Size available for the child
+   * @param path - Path for the child (for keys and debugging)
+   * @returns ComponentOutput from the child render
+   */
+  render: (data: unknown, size: Size, path: string) => ComponentOutput | Promise<ComponentOutput>;
+
+  /**
+   * Event bus for streaming coordination.
+   * Available when executing in a procedure context.
+   */
+  bus?: EventBus;
+
+  /**
+   * Additional metadata from the procedure context.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+// =============================================================================
+// Component Definition
+// =============================================================================
+
+/**
+ * Component factory function (single output).
+ * Returns a serializable component descriptor.
+ */
+export type ComponentFactory<TData = unknown> = (
+  ctx: ComponentContext<TData>
+) => ComponentOutput | Promise<ComponentOutput>;
+
+/**
+ * Streaming component factory (multi-yield).
+ * Yields descriptors over time for live updates.
+ */
+export type StreamingComponentFactory<TData = unknown> = (
+  ctx: ComponentContext<TData>
+) => AsyncGenerator<ComponentOutput, void, unknown>;
+
+/**
+ * Any component factory (single or streaming).
+ */
+export type AnyComponentFactory<TData = unknown> =
+  | ComponentFactory<TData>
+  | StreamingComponentFactory<TData>;
+
+/**
+ * Component metadata (extends ProcedureMetadata).
+ */
+export interface ComponentMetadata extends ProcedureMetadata {
+  /** Component category for organization */
+  category?: string;
+
+  /** Whether the component supports streaming updates */
+  streaming?: boolean;
+
+  /** Default size constraints */
+  defaultSize?: Size;
+
+  /** Minimum size constraints */
+  minSize?: Size;
+
+  /** Maximum size constraints */
+  maxSize?: Size;
+}
+
+/**
+ * Component definition.
+ * Wraps a factory function with type information and metadata.
+ *
+ * @example
+ * ```typescript
+ * const userCard: ComponentDefinition<User> = {
+ *   type: "user-card",
+ *   namespace: "ui",
+ *   input: userSchema,
+ *   metadata: {
+ *     description: "Displays user information",
+ *     category: "profile",
+ *   },
+ *   factory: (ctx) => ({
+ *     type: "user-card",
+ *     props: { user: ctx.data },
+ *   }),
+ * };
+ * ```
+ */
+export interface ComponentDefinition<TData = unknown> {
+  /** Component type identifier */
+  type: string;
+
+  /**
+   * Namespace for the component (optional).
+   * Results in path: ["components", namespace, type]
+   *
+   * @example
+   * namespace: "ui" → ["components", "ui", "user-card"]
+   */
+  namespace?: string;
+
+  /**
+   * Input schema for validating component data.
+   * Optional - if not provided, accepts any data.
+   */
+  input?: ZodLike<TData>;
+
+  /**
+   * Component metadata for documentation and tooling.
+   */
+  metadata?: ComponentMetadata;
+
+  /**
+   * Whether this component streams updates.
+   * When true, factory is expected to be a generator.
+   */
+  streaming?: boolean;
+
+  /**
+   * Component factory function.
+   * Can be a regular function (single output) or generator (streaming).
+   */
+  factory: AnyComponentFactory<TData>;
+}
+
+/**
+ * Any component definition (type-erased for storage).
+ */
+export type AnyComponentDefinition = ComponentDefinition<unknown>;
+
+// =============================================================================
+// Component Registry Types
+// =============================================================================
+
+/**
+ * Registered component with resolved path.
+ */
+export interface RegisteredComponent<TData = unknown> {
+  /** Full procedure path */
+  path: ProcedurePath;
+
+  /** Original component definition */
+  definition: ComponentDefinition<TData>;
+}
+
+/**
+ * Component bundle - collection of components with shared namespace.
+ *
+ * @example
+ * ```typescript
+ * const uiComponents: ComponentBundle = {
+ *   namespace: "ui",
+ *   components: [
+ *     buttonComponent,
+ *     cardComponent,
+ *     modalComponent,
+ *   ],
+ * };
+ * ```
+ */
+export interface ComponentBundle {
+  /** Shared namespace for all components in bundle */
+  namespace: string;
+
+  /** Component definitions */
+  components: AnyComponentDefinition[];
+
+  /** Bundle metadata */
+  metadata?: {
+    /** Bundle name */
+    name?: string;
+    /** Bundle description */
+    description?: string;
+    /** Bundle version */
+    version?: string;
+  };
+}
+
+// =============================================================================
+// Type Inference Utilities
+// =============================================================================
+
+/**
+ * Infer input type from a component definition.
+ */
+export type InferComponentInput<T> = T extends ComponentDefinition<infer TData>
+  ? TData
+  : unknown;
+
+/**
+ * Infer whether a component is streaming.
+ */
+export type IsStreamingComponent<T> = T extends ComponentDefinition<unknown>
+  ? T["streaming"] extends true
+    ? true
+    : false
+  : false;
+
+// =============================================================================
+// Output Helpers
+// =============================================================================
+
+/**
+ * Create a null output (render nothing).
+ */
+export function nullOutput(): NullOutput {
+  return { type: "__null__" };
+}
+
+/**
+ * Create a fragment output (multiple children without wrapper).
+ */
+export function fragment(...children: ComponentOutput[]): FragmentOutput {
+  return { type: "__fragment__", children };
+}
+
+/**
+ * Check if output is a fragment.
+ */
+export function isFragment(output: AnyComponentOutput): output is FragmentOutput {
+  return output.type === "__fragment__";
+}
+
+/**
+ * Check if output is null.
+ */
+export function isNullOutput(output: AnyComponentOutput): output is NullOutput {
+  return output.type === "__null__";
+}
+
+/**
+ * Check if a factory is a streaming generator.
+ */
+export function isStreamingFactory<TData>(
+  factory: AnyComponentFactory<TData>
+): factory is StreamingComponentFactory<TData> {
+  // The tag of the prototype, not `constructor.name`: an own `constructor` property, or a
+  // bundler that renames classes, does not change it. A plain function that returns a
+  // generator is not detected here: the handler of a component streams its result anyway.
+  return Object.prototype.toString.call(factory) === "[object AsyncGeneratorFunction]";
+}

package/src/hydrate.ts

@@ -0,0 +1,355 @@
+/**
+ * Hydration
+ *
+ * Converts serializable ComponentOutput descriptors into framework-specific
+ * components (React, Vue, Svelte, etc.).
+ *
+ * This enables the following flow:
+ * 1. Server renders ComponentOutput (serializable)
+ * 2. Output is sent over wire (JSON)
+ * 3. Client hydrates to React/Vue/Svelte components
+ */
+
+import type { ComponentOutput } from "./components/index.js";
+import type { ComponentMap, HydrateOptions } from "./types.js";
+
+// Portable console access (works in Node and browser)
+type ConsoleType = {
+  warn(message: string): void;
+  log(message: string): void;
+  error(message: string): void;
+};
+const log = (globalThis as unknown as { console: ConsoleType }).console;
+
+// =============================================================================
+// Hydration Core
+// =============================================================================
+
+/**
+ * Create a hydrate function for a specific framework.
+ *
+ * @param options - Hydration options including component map
+ * @returns Hydrate function that converts descriptors to framework components
+ *
+ * @example React:
+ * ```typescript
+ * import { createElement } from "react";
+ * import { createHydrate } from "@procedures/splay";
+ *
+ * const hydrate = createHydrate({
+ *   components: {
+ *     "user-card": UserCard,
+ *     "badge": Badge,
+ *   },
+ *   fallback: UnknownComponent,
+ * });
+ *
+ * // Use with React
+ * function App({ descriptor }) {
+ *   return hydrate(descriptor, createElement);
+ * }
+ * ```
+ */
+export function createHydrate<TComponent>(
+  options: HydrateOptions<TComponent>
+): (
+  descriptor: ComponentOutput | null,
+  createElement: CreateElement<TComponent>
+) => TComponent | null {
+  const { components, fallback, onNull, onFragment } = options;
+
+  return function hydrate(
+    descriptor: ComponentOutput | null,
+    createElement: CreateElement<TComponent>
+  ): TComponent | null {
+    // Handle null
+    if (descriptor === null) {
+      return onNull?.() ?? null;
+    }
+
+    // Handle null output type
+    if (descriptor.type === "__null__") {
+      return onNull?.() ?? null;
+    }
+
+    // Handle fragment
+    if (descriptor.type === "__fragment__") {
+      const children = (descriptor.children ?? []).map((child) =>
+        hydrate(child, createElement)
+      );
+
+      if (onFragment) {
+        return onFragment(children.filter((c): c is TComponent => c !== null));
+      }
+
+      // Default: return first child or null
+      return children[0] ?? null;
+    }
+
+    // Look up component
+    const Component = components[descriptor.type] ?? fallback;
+
+    if (!Component) {
+      log.warn(`Unknown component type: ${descriptor.type}`);
+      return null;
+    }
+
+    // Hydrate children recursively
+    const hydratedChildren = descriptor.children?.map((child) =>
+      hydrate(child, createElement)
+    );
+
+    // Create the component
+    return createElement(
+      Component,
+      { ...descriptor.props, key: descriptor.key },
+      hydratedChildren
+    );
+  };
+}
+
+/**
+ * createElement function signature (React-compatible).
+ */
+export type CreateElement<TComponent> = (
+  type: TComponent,
+  props: Record<string, unknown> | null,
+  children?: (TComponent | null)[]
+) => TComponent;
+
+// =============================================================================
+// React-Specific Hydration
+// =============================================================================
+
+/**
+ * Generic React-like component type (works with any framework that has createElement).
+ */
+type ReactLikeComponent = (props: Record<string, unknown>) => unknown;
+
+/**
+ * React-specific hydration options.
+ */
+export interface ReactHydrateOptions {
+  /** Map of component types to React components */
+  components: ComponentMap<ReactLikeComponent>;
+  /** Fallback component for unknown types */
+  fallback?: ReactLikeComponent;
+}
+
+/**
+ * React-like module interface.
+ */
+interface ReactLike {
+  createElement(
+    type: ReactLikeComponent | symbol,
+    props: Record<string, unknown> | null,
+    ...children: unknown[]
+  ): unknown;
+  Fragment: symbol;
+}
+
+/**
+ * Create a React-specific hydrate function.
+ *
+ * @param react - React module (import * as React from "react")
+ * @param options - Hydration options
+ * @returns Hydrate function for React
+ *
+ * @example
+ * ```typescript
+ * import * as React from "react";
+ * import { createReactHydrate } from "@procedures/splay";
+ *
+ * const hydrate = createReactHydrate(React, {
+ *   components: {
+ *     "user-card": UserCard,
+ *     "badge": Badge,
+ *   },
+ * });
+ *
+ * function App({ descriptor }) {
+ *   return hydrate(descriptor);
+ * }
+ * ```
+ */
+export function createReactHydrate(
+  react: ReactLike,
+  options: ReactHydrateOptions
+): (descriptor: ComponentOutput | null) => unknown {
+  const { components, fallback } = options;
+
+  function hydrate(descriptor: ComponentOutput | null): unknown {
+    if (descriptor === null) {
+      return null;
+    }
+
+    if (descriptor.type === "__null__") {
+      return null;
+    }
+
+    if (descriptor.type === "__fragment__") {
+      const children = (descriptor.children ?? []).map((child: ComponentOutput) => hydrate(child));
+      return react.createElement(react.Fragment, null, ...children);
+    }
+
+    const Component = components[descriptor.type];
+
+    if (!Component) {
+      if (fallback) {
+        return react.createElement(fallback, {
+          type: descriptor.type,
+          props: descriptor.props,
+        });
+      }
+      log.warn(`Unknown component type: ${descriptor.type}`);
+      return null;
+    }
+
+    const hydratedChildren = descriptor.children?.map((child: ComponentOutput) => hydrate(child));
+
+    return react.createElement(
+      Component,
+      { ...descriptor.props, key: descriptor.key },
+      ...(hydratedChildren ?? [])
+    );
+  }
+
+  return hydrate;
+}
+
+// =============================================================================
+// Descriptor Utilities
+// =============================================================================
+
+/**
+ * Walk a descriptor tree and apply a visitor to each node.
+ */
+export function walkDescriptor(
+  descriptor: ComponentOutput,
+  visitor: (node: ComponentOutput, path: string[]) => void,
+  path: string[] = []
+): void {
+  visitor(descriptor, path);
+
+  if (descriptor.children) {
+    descriptor.children.forEach((child: ComponentOutput, index: number) => {
+      walkDescriptor(child, visitor, [...path, `children[${index}]`]);
+    });
+  }
+}
+
+/**
+ * Transform a descriptor tree.
+ */
+export function transformDescriptor(
+  descriptor: ComponentOutput,
+  transform: (node: ComponentOutput) => ComponentOutput
+): ComponentOutput {
+  const transformed = transform(descriptor);
+
+  if (transformed.children) {
+    return {
+      ...transformed,
+      children: transformed.children.map((child: ComponentOutput) =>
+        transformDescriptor(child, transform)
+      ),
+    };
+  }
+
+  return transformed;
+}
+
+/**
+ * Find all nodes in a descriptor tree matching a predicate.
+ */
+export function findInDescriptor(
+  descriptor: ComponentOutput,
+  predicate: (node: ComponentOutput) => boolean
+): ComponentOutput[] {
+  const results: ComponentOutput[] = [];
+
+  walkDescriptor(descriptor, (node) => {
+    if (predicate(node)) {
+      results.push(node);
+    }
+  });
+
+  return results;
+}
+
+/**
+ * Get all component types used in a descriptor tree.
+ */
+export function getUsedTypes(descriptor: ComponentOutput): Set<string> {
+  const types = new Set<string>();
+
+  walkDescriptor(descriptor, (node) => {
+    if (node.type !== "__null__" && node.type !== "__fragment__") {
+      types.add(node.type);
+    }
+  });
+
+  return types;
+}
+
+/**
+ * Validate that all component types in a descriptor are known.
+ */
+export function validateDescriptor(
+  descriptor: ComponentOutput,
+  knownTypes: Set<string> | string[]
+): { valid: boolean; unknownTypes: string[] } {
+  const known = knownTypes instanceof Set ? knownTypes : new Set(knownTypes);
+  const used = getUsedTypes(descriptor);
+  const unknownTypes: string[] = [];
+
+  for (const type of used) {
+    if (!known.has(type)) {
+      unknownTypes.push(type);
+    }
+  }
+
+  return {
+    valid: unknownTypes.length === 0,
+    unknownTypes,
+  };
+}
+
+// =============================================================================
+// Serialization Helpers
+// =============================================================================
+
+/**
+ * Serialize a descriptor to JSON string.
+ */
+export function serializeDescriptor(descriptor: ComponentOutput): string {
+  return JSON.stringify(descriptor);
+}
+
+/**
+ * Parse a descriptor from JSON string.
+ */
+export function parseDescriptor(json: string): ComponentOutput {
+  return JSON.parse(json) as ComponentOutput;
+}
+
+/**
+ * Create a compact representation of a descriptor.
+ * Removes undefined values and empty arrays.
+ */
+export function compactDescriptor(descriptor: ComponentOutput): ComponentOutput {
+  const result: ComponentOutput = {
+    type: descriptor.type,
+    props: descriptor.props,
+  };
+
+  if (descriptor.children && descriptor.children.length > 0) {
+    result.children = descriptor.children.map(compactDescriptor);
+  }
+
+  if (descriptor.key !== undefined) {
+    result.key = descriptor.key;
+  }
+
+  return result;
+}