@echothink-ui/layout 0.2.0

package/src/layout-system/renderer/renderer.tsx

@@ -0,0 +1,200 @@
+/**
+ * Recursive renderer (`layout-spec.md` §8.2).
+ *
+ * Walks a `LayoutNode`: resolves its registry item, renders each slot's content
+ * into a React node under a recomposed child context, computes the physical
+ * plan, and hands the pre-rendered `slots` map to the item's renderer.
+ *
+ * `SlotContentRenderer` is exported so composition renderers (Tabs/Stepper) can
+ * render inline `SlotContent` (switch items / stepper steps) with correct child
+ * context.
+ */
+import * as React from "react";
+import { StyleScope } from "@echothink-ui/style";
+import type {
+  ComponentSlotContent,
+  LayoutNode,
+  LayoutRuntimeContext,
+  SlotContent,
+  SlotDefinition,
+} from "../schema/types.js";
+import { composeLayoutContext } from "../inference/context.js";
+import { resolvePhysicalPlan } from "../inference/responsive.js";
+import {
+  LayoutContextProvider,
+  useLayoutContext,
+  useLayoutEngine,
+  type LayoutEngine,
+} from "./context.js";
+
+/* ------------------------------------------------------------------ *
+ * Fallback surfaces for unknown types — never throw at render time.
+ * ------------------------------------------------------------------ */
+
+function UnknownLayout({ type }: { type: string }) {
+  return (
+    <div data-ls-unknown-layout={type} className="eth-ls-unknown" role="note">
+      Unknown layout type: <code>{type}</code>
+    </div>
+  );
+}
+
+function UnknownComponent({ name }: { name: string }) {
+  return (
+    <div data-ls-unknown-component={name} className="eth-ls-unknown" role="note">
+      Unknown component: <code>{name}</code>
+    </div>
+  );
+}
+
+function EmptySlot({ reason }: { reason?: string }) {
+  return (
+    <div data-ls-empty={reason ?? "not-configured"} className="eth-ls-empty" aria-hidden="true" />
+  );
+}
+
+/* ------------------------------------------------------------------ *
+ * Component leaf — the style boundary.
+ * ------------------------------------------------------------------ */
+
+function ComponentRenderer({
+  content,
+  context,
+}: {
+  content: ComponentSlotContent;
+  context: LayoutRuntimeContext;
+}) {
+  const engine = useLayoutEngine();
+  const Component = engine.componentResolver(content.component);
+  if (!Component) return <UnknownComponent name={content.component} />;
+  const s = context.componentStyle;
+  // The StyleScope wrapper is the ONLY place style reaches a component: it sets
+  // the preset/palette/density/typeScale classes + data-attrs the `@echothink-ui`
+  // components read via the CSS cascade. We intentionally do NOT inject
+  // styleParams/layoutContext as props (avoids DOM prop leakage).
+  return (
+    <StyleScope
+      preset={s.preset}
+      palette={s.palette}
+      density={s.density}
+      typeScale={s.typeScale}
+      global={false}
+      className="eth-ls-component"
+      data-ls-component={content.component}
+    >
+      <Component {...(content.props ?? {})} />
+    </StyleScope>
+  );
+}
+
+/* ------------------------------------------------------------------ *
+ * Render a SlotContent within an already-composed child context.
+ * ------------------------------------------------------------------ */
+
+function renderContent(
+  content: SlotContent,
+  context: LayoutRuntimeContext,
+  engine: LayoutEngine,
+): React.ReactNode {
+  switch (content.kind) {
+    case "component":
+      return <ComponentRenderer content={content} context={context} />;
+    case "layout":
+      return <LayoutRenderer node={content.layout} />;
+    case "template": {
+      const resolved = engine.templateResolver?.(content.template);
+      if (!resolved) return <UnknownComponent name={`template:${content.template}`} />;
+      return <LayoutRenderer node={resolved} />;
+    }
+    case "fragment": {
+      const direction =
+        content.composition?.op === "stack" && content.composition.direction === "horizontal"
+          ? "row"
+          : "column";
+      return (
+        <div className="eth-ls-fragment" style={{ display: "flex", flexDirection: direction, gap: context.tokens.gap }}>
+          {content.items.map((item, i) => (
+            <React.Fragment key={i}>{renderContent(item, context, engine)}</React.Fragment>
+          ))}
+        </div>
+      );
+    }
+    case "empty":
+      return <EmptySlot reason={content.reason} />;
+    default:
+      return null;
+  }
+}
+
+export interface SlotContentRendererProps {
+  node: LayoutNode;
+  slot: SlotDefinition;
+  content: SlotContent;
+  /** Context of the layout node that owns the slot. */
+  parentContext: LayoutRuntimeContext;
+}
+
+/** Render one slot's content under a freshly composed child context. */
+export function SlotContentRenderer({
+  node,
+  slot,
+  content,
+  parentContext,
+}: SlotContentRendererProps) {
+  const engine = useLayoutEngine();
+  const childContext = React.useMemo(
+    () => composeLayoutContext({ parent: parentContext, node, slot, content }),
+    [parentContext, node, slot, content],
+  );
+  return (
+    <LayoutContextProvider value={childContext}>
+      {renderContent(content, childContext, engine)}
+    </LayoutContextProvider>
+  );
+}
+
+/* ------------------------------------------------------------------ *
+ * The recursive layout renderer.
+ * ------------------------------------------------------------------ */
+
+export function LayoutRenderer({ node }: { node: LayoutNode }) {
+  const parentContext = useLayoutContext();
+  const engine = useLayoutEngine();
+  const item = engine.registry.get(node.type);
+
+  if (!item) return <UnknownLayout type={node.type} />;
+
+  const slots: Record<string, React.ReactNode> = {};
+  for (const slotDef of item.slots) {
+    const content = node.slots[slotDef.name] ?? slotDef.fallback?.empty;
+    if (content === undefined) continue;
+    slots[slotDef.name] = (
+      <SlotContentRenderer
+        node={node}
+        slot={slotDef}
+        content={content}
+        parentContext={parentContext}
+      />
+    );
+  }
+
+  const plan = resolvePhysicalPlan({
+    node,
+    item,
+    viewport: parentContext.viewport,
+    state: engine.stateStore.get(node.id),
+  });
+
+  const Renderer = item.renderer;
+  return (
+    <Renderer
+      node={node}
+      variant={node.variant}
+      props={{ ...item.defaultProps, ...node.props }}
+      slots={slots}
+      context={parentContext}
+      composition={node.composition ?? item.defaultComposition}
+      plan={plan}
+    />
+  );
+}

package/src/layout-system/renderer/root.tsx

@@ -0,0 +1,95 @@
+/**
+ * `LayoutRoot` — the top-level entry that mounts the layout engine.
+ *
+ * Wires the registry + resolvers + state store into an engine context, builds
+ * the root runtime context (optionally observing the live viewport), validates
+ * the tree once, and renders the recursive `LayoutRenderer`.
+ */
+import * as React from "react";
+import type {
+  LayoutDiagnostic,
+  LayoutNode,
+  LayoutViewport,
+} from "../schema/types.js";
+import { createRootContext, type RootContextInput } from "../inference/context.js";
+import { LayoutRegistry } from "../registry/registry.js";
+import { createDefaultLayoutRegistry } from "../registry/builtins.js";
+import type { LayoutStateStore } from "../runtime/state.js";
+import { useViewport } from "../runtime/viewport.js";
+import { validateLayout } from "../schema/validate.js";
+import {
+  LayoutContextProvider,
+  LayoutEngineProvider,
+  buildEngine,
+  type ComponentResolver,
+  type TemplateResolver,
+} from "./context.js";
+import { LayoutRenderer } from "./renderer.js";
+
+export interface LayoutRootProps {
+  /** The layout AST to render. */
+  node: LayoutNode;
+  /** Resolves component names → React components (host-injected). */
+  componentResolver: ComponentResolver;
+  /** Resolves template names → layout nodes (host-injected). */
+  templateResolver?: TemplateResolver;
+  /** Layout registry; defaults to the MVP builtin registry. */
+  registry?: LayoutRegistry;
+  /** Root context overrides (surface/style/route/permissions/viewport). */
+  context?: RootContextInput;
+  /** Pluggable panel-state store. */
+  stateStore?: LayoutStateStore;
+  /** Observe the live viewport and feed it into the root context. Default true. */
+  observeViewport?: boolean;
+  /** Receives validation diagnostics whenever the tree changes. */
+  onDiagnostics?: (diagnostics: LayoutDiagnostic[]) => void;
+}
+
+export function LayoutRoot({
+  node,
+  componentResolver,
+  templateResolver,
+  registry,
+  context,
+  stateStore,
+  observeViewport = true,
+  onDiagnostics,
+}: LayoutRootProps) {
+  const resolvedRegistry = React.useMemo(
+    () => registry ?? createDefaultLayoutRegistry(),
+    [registry],
+  );
+
+  const observed = useViewport({ initial: context?.viewport as LayoutViewport | undefined });
+  const viewport = observeViewport ? observed : (context?.viewport as LayoutViewport | undefined);
+
+  const rootContext = React.useMemo(
+    () => createRootContext({ ...context, viewport }),
+    [context, viewport],
+  );
+
+  const engine = React.useMemo(
+    () =>
+      buildEngine({
+        registry: resolvedRegistry,
+        componentResolver,
+        templateResolver,
+        stateStore,
+        onDiagnostics,
+      }),
+    [resolvedRegistry, componentResolver, templateResolver, stateStore, onDiagnostics],
+  );
+
+  React.useEffect(() => {
+    if (!onDiagnostics) return;
+    onDiagnostics(validateLayout(node, resolvedRegistry));
+  }, [node, resolvedRegistry, onDiagnostics]);
+
+  return (
+    <LayoutEngineProvider value={engine}>
+      <LayoutContextProvider value={rootContext}>
+        <LayoutRenderer node={node} />
+      </LayoutContextProvider>
+    </LayoutEngineProvider>
+  );
+}

package/src/layout-system/runtime/state.ts

@@ -0,0 +1,80 @@
+/**
+ * Layout state persistence (`layout-spec.md` §11).
+ *
+ * A minimal pluggable store for per-layout panel state (collapse/pin/width/
+ * active tab/split ratio) + style preference. Default is an in-memory +
+ * localStorage-backed store; the host can inject its own (e.g. server-synced).
+ */
+import type { PersistedLayoutState } from "../schema/types.js";
+
+export interface LayoutStateStore {
+  get(layoutId: string): PersistedLayoutState | undefined;
+  set(layoutId: string, state: PersistedLayoutState): void;
+  patchPanel(
+    layoutId: string,
+    slot: string,
+    patch: Partial<PersistedLayoutState["panels"][string]>,
+  ): PersistedLayoutState;
+}
+
+function emptyState(layoutId: string): PersistedLayoutState {
+  return {
+    schemaVersion: 2,
+    layoutId,
+    panels: {},
+    updatedAt: "",
+  };
+}
+
+/** In-memory store; optionally mirrors to localStorage when available. */
+export function createMemoryLayoutStateStore(opts?: {
+  persistKey?: string;
+}): LayoutStateStore {
+  const cache = new Map<string, PersistedLayoutState>();
+  const persistKey = opts?.persistKey;
+
+  function load(): void {
+    if (!persistKey || typeof localStorage === "undefined") return;
+    try {
+      const raw = localStorage.getItem(persistKey);
+      if (!raw) return;
+      const parsed = JSON.parse(raw) as Record<string, PersistedLayoutState>;
+      for (const [id, st] of Object.entries(parsed)) cache.set(id, st);
+    } catch {
+      /* ignore corrupt state */
+    }
+  }
+
+  function flush(): void {
+    if (!persistKey || typeof localStorage === "undefined") return;
+    try {
+      localStorage.setItem(persistKey, JSON.stringify(Object.fromEntries(cache)));
+    } catch {
+      /* ignore quota errors */
+    }
+  }
+
+  load();
+
+  return {
+    get(layoutId) {
+      return cache.get(layoutId);
+    },
+    set(layoutId, state) {
+      cache.set(layoutId, state);
+      flush();
+    },
+    patchPanel(layoutId, slot, patch) {
+      const current = cache.get(layoutId) ?? emptyState(layoutId);
+      const next: PersistedLayoutState = {
+        ...current,
+        panels: { ...current.panels, [slot]: { ...current.panels[slot], ...patch } },
+        // `updatedAt` is set by the caller environment; left as a marker here.
+        updatedAt: current.updatedAt || "pending",
+      };
+      cache.set(layoutId, next);
+      flush();
+      return next;
+    },
+  };
+}

package/src/layout-system/runtime/viewport.ts

@@ -0,0 +1,71 @@
+/**
+ * Viewport observation (`layout-spec.md` §10.1, §17.5).
+ *
+ * A throttled hook that maps `window` size to a `LayoutViewport` (breakpoint,
+ * pointer, color scheme). SSR-safe: returns the provided default until mounted.
+ */
+import * as React from "react";
+import type { Breakpoint, LayoutViewport } from "../schema/types.js";
+import { defaultViewport } from "../inference/context.js";
+
+/** rem-based breakpoint thresholds mirrored from `ethBreakpoints` (px @16). */
+const BREAKPOINTS: Array<{ bp: Breakpoint; minWidth: number }> = [
+  { bp: "ultra", minWidth: 1920 },
+  { bp: "wide", minWidth: 1536 },
+  { bp: "desktop", minWidth: 1280 },
+  { bp: "laptop", minWidth: 1024 },
+  { bp: "tablet", minWidth: 768 },
+  { bp: "mobile", minWidth: 0 },
+];
+
+export function breakpointForWidth(width: number): Breakpoint {
+  for (const { bp, minWidth } of BREAKPOINTS) {
+    if (width >= minWidth) return bp;
+  }
+  return "mobile";
+}
+
+function readViewport(): LayoutViewport {
+  if (typeof window === "undefined") return defaultViewport;
+  const width = window.innerWidth;
+  const height = window.innerHeight;
+  const pointer =
+    typeof window.matchMedia === "function" && window.matchMedia("(pointer: coarse)").matches
+      ? "coarse"
+      : "fine";
+  const colorScheme =
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-color-scheme: dark)").matches
+      ? "dark"
+      : "light";
+  return { breakpoint: breakpointForWidth(width), width, height, pointer, colorScheme };
+}
+
+export interface UseViewportOptions {
+  /** Initial value used before mount / on the server. */
+  initial?: LayoutViewport;
+  /** Resize debounce in ms. */
+  debounceMs?: number;
+}
+
+export function useViewport(opts: UseViewportOptions = {}): LayoutViewport {
+  const { initial = defaultViewport, debounceMs = 120 } = opts;
+  const [viewport, setViewport] = React.useState<LayoutViewport>(initial);
+
+  React.useEffect(() => {
+    if (typeof window === "undefined") return undefined;
+    setViewport(readViewport());
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const onResize = () => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => setViewport(readViewport()), debounceMs);
+    };
+    window.addEventListener("resize", onResize);
+    return () => {
+      if (timer) clearTimeout(timer);
+      window.removeEventListener("resize", onResize);
+    };
+  }, [debounceMs]);
+
+  return viewport;
+}