@echothink-ui/layout 0.2.0

package/src/layout-system/__tests__/layout-system.test.tsx

@@ -0,0 +1,169 @@
+import { describe, it, expect } from "vitest";
+import * as React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import {
+  LayoutRoot,
+  createDefaultLayoutRegistry,
+  validateLayout,
+  inferComponentStyle,
+  resolvePhysicalPlan,
+  createRootContext,
+  layout,
+  componentSlot,
+  layoutSlot,
+  type LayoutNode,
+  type ComponentResolver,
+} from "../index.js";
+
+const registry = createDefaultLayoutRegistry();
+
+/* -------------------------------- Validation ------------------------------- */
+
+describe("validateLayout", () => {
+  it("flags unknown layout type", () => {
+    const node = layout({ id: "x", type: "PageLayout.DoesNotExist", slots: {} });
+    const diags = validateLayout(node, registry);
+    expect(diags.some((d) => d.code === "UNKNOWN_LAYOUT_TYPE")).toBe(true);
+  });
+
+  it("flags a required slot that is missing", () => {
+    const node = layout({ id: "ds", type: "PageLayout.DataGridInspector", slots: {} });
+    const diags = validateLayout(node, registry);
+    expect(diags.some((d) => d.code === "SLOT_REQUIRED" && d.path.includes("grid"))).toBe(true);
+  });
+
+  it("accepts a well-formed tree", () => {
+    const node = layout({
+      id: "ds",
+      type: "PageLayout.DataGridInspector",
+      slots: { grid: componentSlot("EntityTable", { entityType: "Order" }) },
+    });
+    const diags = validateLayout(node, registry);
+    expect(diags.filter((d) => d.level === "error")).toHaveLength(0);
+  });
+
+  it("detects accepts violations", () => {
+    const node = layout({
+      id: "p",
+      type: "Primitive.Panel",
+      // body only accepts component/layout/fragment, not template
+      slots: { body: { kind: "template", template: "Anything" } },
+    });
+    const diags = validateLayout(node, registry);
+    expect(diags.some((d) => d.code === "SLOT_ACCEPTS_VIOLATION")).toBe(true);
+  });
+});
+
+/* ----------------------------- Style inference ----------------------------- */
+
+describe("inferComponentStyle", () => {
+  const base = {
+    surface: "page" as const,
+    depth: 1,
+    breakpoint: "desktop" as const,
+  };
+  it("workbench/console → studio-dark + compact", () => {
+    const s = inferComponentStyle({ ...base, layoutType: "PageLayout.Workbench", slotRole: "console" });
+    expect(s.preset).toBe("studio-dark");
+    expect(s.density).toBe("compact");
+  });
+  it("wizard → bright + comfortable", () => {
+    const s = inferComponentStyle({ ...base, layoutType: "PageLayout.WizardComposer", taskMode: "wizard", slotRole: "form" });
+    expect(s.preset).toBe("bright");
+  });
+  it("admin shell → carbon-like", () => {
+    const s = inferComponentStyle({ ...base, layoutType: "PageLayout.AdminShell", slotRole: "content" });
+    expect(s.preset).toBe("carbon-like");
+  });
+  it("explicit override wins", () => {
+    const s = inferComponentStyle({ ...base, layoutType: "PageLayout.AdminShell", explicit: { preset: "glass" } });
+    expect(s.preset).toBe("glass");
+  });
+});
+
+/* ---------------------------- Responsive plan ------------------------------ */
+
+describe("resolvePhysicalPlan", () => {
+  const item = registry.get("PageLayout.AdminShell")!;
+  const node = layout({
+    id: "shell",
+    type: "PageLayout.AdminShell",
+    slots: {
+      navigation: componentSlot("Nav"),
+      content: componentSlot("Content"),
+    },
+  });
+
+  it("keeps navigation on desktop", () => {
+    const plan = resolvePhysicalPlan({
+      node,
+      item,
+      viewport: { breakpoint: "desktop", width: 1440, height: 900, pointer: "fine", colorScheme: "light" },
+    });
+    const nav = plan.regions.find((r) => r.slot === "navigation")!;
+    expect(nav.visible).toBe(true);
+    expect(plan.mode).toBe("multi-pane");
+  });
+
+  it("moves navigation to a drawer on mobile", () => {
+    const plan = resolvePhysicalPlan({
+      node,
+      item,
+      viewport: { breakpoint: "mobile", width: 390, height: 800, pointer: "coarse", colorScheme: "light" },
+    });
+    const nav = plan.regions.find((r) => r.slot === "navigation")!;
+    expect(nav.layer).toBe("drawer");
+    expect(plan.mode).toBe("drawer-assisted");
+    // required content slot is never dropped
+    expect(plan.regions.find((r) => r.slot === "content")!.visible).toBe(true);
+  });
+});
+
+/* ------------------------------- Rendering --------------------------------- */
+
+describe("LayoutRoot rendering", () => {
+  const resolver: ComponentResolver = (name) => {
+    const C = (props: Record<string, unknown>) =>
+      React.createElement("div", { "data-component": name }, String(props.text ?? name));
+    return C;
+  };
+
+  it("renders a page layout with nested layout + components", () => {
+    const node: LayoutNode = layout({
+      id: "root",
+      type: "PageLayout.AdminShell",
+      slots: {
+        topbar: componentSlot("Brand", { text: "EchoThink" }),
+        navigation: componentSlot("Nav"),
+        content: layoutSlot(
+          layout({
+            id: "panel",
+            type: "Primitive.Panel",
+            slots: { body: componentSlot("Table", { text: "rows" }) },
+          }),
+        ),
+      },
+    });
+    const html = renderToStaticMarkup(
+      React.createElement(LayoutRoot, {
+        node,
+        componentResolver: resolver,
+        observeViewport: false,
+        context: createRootContext(),
+      }),
+    );
+    expect(html).toContain('data-component="Brand"');
+    expect(html).toContain("EchoThink");
+    expect(html).toContain('data-component="Table"');
+    expect(html).toContain("eth-ls-admin-shell");
+    expect(html).toContain("eth-ls-panel");
+  });
+
+  it("renders an unknown layout placeholder rather than throwing", () => {
+    const node = layout({ id: "x", type: "Nope", slots: {} });
+    const html = renderToStaticMarkup(
+      React.createElement(LayoutRoot, { node, componentResolver: resolver, observeViewport: false }),
+    );
+    expect(html).toContain("Unknown layout type");
+  });
+});

package/src/layout-system/builders.ts

@@ -0,0 +1,46 @@
+/**
+ * Ergonomic builders for hand-authoring `LayoutNode` ASTs (used by templates
+ * and tests). Pure helpers — no runtime behavior.
+ */
+import type {
+  ComponentSlotContent,
+  EmptySlotContent,
+  FragmentSlotContent,
+  LayoutNode,
+  LayoutSlotContent,
+  SlotContent,
+  TemplateSlotContent,
+} from "./schema/types.js";
+
+export interface LayoutNodeInput extends Omit<LayoutNode, "kind"> {}
+
+export function layout(input: LayoutNodeInput): LayoutNode {
+  return { kind: "layout", ...input };
+}
+
+export function componentSlot(
+  component: string,
+  props?: Record<string, unknown>,
+  styleOverride?: ComponentSlotContent["styleOverride"],
+): ComponentSlotContent {
+  return { kind: "component", component, props, styleOverride };
+}
+
+export function layoutSlot(node: LayoutNode): LayoutSlotContent {
+  return { kind: "layout", layout: node };
+}
+
+export function templateSlot(template: string, props?: Record<string, unknown>): TemplateSlotContent {
+  return { kind: "template", template, props };
+}
+
+export function fragmentSlot(
+  items: SlotContent[],
+  composition?: FragmentSlotContent["composition"],
+): FragmentSlotContent {
+  return { kind: "fragment", items, composition };
+}
+
+export function emptySlot(reason?: EmptySlotContent["reason"]): EmptySlotContent {
+  return { kind: "empty", reason };
+}

package/src/layout-system/index.ts

@@ -0,0 +1,87 @@
+/**
+ * `@echothink-ui/layout` — the layout system (layout-spec.md).
+ *
+ * A recursive, typed page-structure engine: Typed Layout AST → registry resolve
+ * → validation → context inference → responsive physical plan → recursive render.
+ */
+
+// Schema / AST types
+export * from "./schema/types.js";
+export { validateLayout, hasErrors } from "./schema/validate.js";
+export type { ValidateOptions } from "./schema/validate.js";
+
+// Tokens
+export { presetTokenMap, resolveTokens } from "./tokens/preset-tokens.js";
+
+// Inference
+export {
+  inferComponentStyle,
+  inferDensity,
+  inferTypeScale,
+  defaultComponentStyle,
+} from "./inference/style.js";
+export {
+  composeLayoutContext,
+  buildStyleInferenceInput,
+  createRootContext,
+  defaultContextPolicy,
+  defaultViewport,
+  type RootContextInput,
+} from "./inference/context.js";
+export {
+  resolvePhysicalPlan,
+  regionFor,
+  breakpointRank,
+  isNarrow,
+  type ResolvePlanInput,
+} from "./inference/responsive.js";
+
+// Registry
+export { LayoutRegistry } from "./registry/registry.js";
+export { builtinLayouts, createDefaultLayoutRegistry } from "./registry/builtins.js";
+
+// Runtime
+export {
+  createMemoryLayoutStateStore,
+  type LayoutStateStore,
+} from "./runtime/state.js";
+export {
+  useViewport,
+  breakpointForWidth,
+  type UseViewportOptions,
+} from "./runtime/viewport.js";
+
+// Renderer
+export { LayoutRoot, type LayoutRootProps } from "./renderer/root.js";
+export {
+  LayoutRenderer,
+  SlotContentRenderer,
+  type SlotContentRendererProps,
+} from "./renderer/renderer.js";
+export {
+  LayoutContextProvider,
+  LayoutEngineProvider,
+  useLayoutContext,
+  useLayoutEngine,
+  buildEngine,
+  type ComponentResolver,
+  type TemplateResolver,
+  type LayoutEngine,
+  type BuildEngineInput,
+} from "./renderer/context.js";
+
+// Builtin layout items (for direct registry composition / introspection)
+export { primitiveLayouts } from "./primitives/index.js";
+export { regionLayouts } from "./regions/index.js";
+export { pageLayouts } from "./page-layouts/index.js";
+
+// Builders
+export {
+  layout,
+  componentSlot,
+  layoutSlot,
+  templateSlot,
+  fragmentSlot,
+  emptySlot,
+  type LayoutNodeInput,
+} from "./builders.js";

package/src/layout-system/inference/context.ts

@@ -0,0 +1,158 @@
+/**
+ * Context propagation (`layout-spec.md` §6, §8).
+ *
+ * Builds the root `LayoutRuntimeContext` and composes a child context for each
+ * slot: it derives the child surface/taskMode/etc. and runs `inferComponentStyle`
+ * so the descendant components receive consistent, inferred style params.
+ */
+import type {
+  ComponentStyleParams,
+  ContextPolicy,
+  LayoutNode,
+  LayoutRuntimeContext,
+  LayoutViewport,
+  SlotContent,
+  SlotDefinition,
+  StyleInferenceInput,
+  SurfaceRole,
+} from "../schema/types.js";
+import { defaultComponentStyle, inferComponentStyle } from "./style.js";
+import { resolveTokens } from "../tokens/preset-tokens.js";
+
+export const defaultContextPolicy: ContextPolicy = {
+  inheritStyle: true,
+  inheritDensity: true,
+  inheritTypeScale: true,
+  inheritSurface: false,
+  isolateState: false,
+  isolateScroll: true,
+  allowComponentOverride: true,
+  maxDepth: 8,
+};
+
+export const defaultViewport: LayoutViewport = {
+  breakpoint: "desktop",
+  width: 1440,
+  height: 900,
+  pointer: "fine",
+  colorScheme: "light",
+};
+
+export interface RootContextInput {
+  viewport?: Partial<LayoutViewport>;
+  surface?: SurfaceRole;
+  style?: Partial<ComponentStyleParams>;
+  route?: LayoutRuntimeContext["route"];
+  permissions?: string[];
+}
+
+/** Build the top-level context an app mounts the renderer with. */
+export function createRootContext(input: RootContextInput = {}): LayoutRuntimeContext {
+  const viewport: LayoutViewport = { ...defaultViewport, ...input.viewport };
+  const componentStyle: ComponentStyleParams = {
+    ...defaultComponentStyle,
+    ...input.style,
+  };
+  return {
+    path: [],
+    depth: 0,
+    ancestry: [],
+    viewport,
+    container: { width: viewport.width, height: viewport.height },
+    route: input.route,
+    surface: input.surface ?? "app",
+    componentStyle,
+    tokens: resolveTokens(componentStyle),
+    stateScope: "session",
+    permissions: input.permissions ? { granted: new Set(input.permissions) } : undefined,
+  };
+}
+
+function inferChildSurface(
+  parent: LayoutRuntimeContext,
+  node: LayoutNode,
+  slot: SlotDefinition,
+): SurfaceRole {
+  return (
+    slot.contextTransform?.surface ??
+    node.styleIntent?.surface ??
+    (parent.surface === "app" ? "page" : parent.surface)
+  );
+}
+
+/** §7.1 — assemble the inference input from parent context + node + slot. */
+export function buildStyleInferenceInput(args: {
+  parent: LayoutRuntimeContext;
+  node: LayoutNode;
+  slot: SlotDefinition;
+  content: SlotContent;
+}): StyleInferenceInput {
+  const { parent, node, slot, content } = args;
+  const surface = inferChildSurface(parent, node, slot);
+  const explicit: Partial<ComponentStyleParams> = {
+    ...node.styleIntent,
+    ...slot.contextTransform?.styleIntent,
+    ...(slot.contextTransform?.densityHint ? { density: slot.contextTransform.densityHint } : {}),
+    ...(slot.contextTransform?.typeScaleHint ? { typeScale: slot.contextTransform.typeScaleHint } : {}),
+    ...(content.kind === "component" ? content.styleOverride : undefined),
+  };
+  return {
+    parent: parent.componentStyle,
+    explicit,
+    layoutType: node.type,
+    layoutTier: node.tier,
+    layoutVariant: node.variant,
+    surface,
+    slotRole: slot.role,
+    taskMode: node.styleIntent?.taskMode ?? parent.taskMode,
+    dataIntensity: node.styleIntent?.dataIntensity ?? parent.dataIntensity,
+    interactionMode: node.styleIntent?.interactionMode ?? parent.interactionMode,
+    visualEmphasis: node.styleIntent?.visualEmphasis ?? parent.visualEmphasis,
+    depth: parent.depth + 1,
+    breakpoint: parent.viewport.breakpoint,
+    containerWidth: parent.container.width,
+  };
+}
+
+/** §8.1 — compose the child runtime context for a slot. */
+export function composeLayoutContext(args: {
+  parent: LayoutRuntimeContext;
+  node: LayoutNode;
+  slot: SlotDefinition;
+  content: SlotContent;
+}): LayoutRuntimeContext {
+  const { parent, node, slot, content } = args;
+  const styleInput = buildStyleInferenceInput(args);
+  const componentStyle = inferComponentStyle(styleInput);
+  const surface = styleInput.surface;
+
+  return {
+    ...parent,
+    path: [...parent.path, node.id, slot.name],
+    depth: parent.depth + 1,
+    ancestry: [
+      ...parent.ancestry,
+      {
+        id: node.id,
+        type: node.type,
+        tier: node.tier,
+        surface: node.styleIntent?.surface,
+        slotRole: slot.role,
+      },
+    ],
+    slot: {
+      name: slot.name,
+      role: slot.role,
+      priority: slot.priority?.value,
+      surface: slot.contextTransform?.surface,
+    },
+    surface,
+    taskMode: node.styleIntent?.taskMode ?? parent.taskMode,
+    dataIntensity: node.styleIntent?.dataIntensity ?? parent.dataIntensity,
+    interactionMode: node.styleIntent?.interactionMode ?? parent.interactionMode,
+    visualEmphasis: node.styleIntent?.visualEmphasis ?? parent.visualEmphasis,
+    componentStyle,
+    tokens: resolveTokens(componentStyle),
+    stateScope: node.state?.scope ?? parent.stateScope,
+  };
+}

package/src/layout-system/inference/responsive.ts

@@ -0,0 +1,147 @@
+/**
+ * Responsive physical plan (`layout-spec.md` §10).
+ *
+ * Maps a logical layout node + its registry slot definitions + the viewport (and
+ * optional user collapse/pin state) to a `PhysicalLayoutPlan` describing each
+ * slot's placement, visibility and collapse. Page-layout renderers consume the
+ * plan so the same AST yields different desktop/tablet/mobile arrangements.
+ */
+import type {
+  Breakpoint,
+  LayoutNode,
+  LayoutRegistryItem,
+  LayoutViewport,
+  PersistedLayoutState,
+  PhysicalLayoutPlan,
+  PhysicalRegion,
+  SlotDefinition,
+  SlotRole,
+} from "../schema/types.js";
+
+const BREAKPOINT_ORDER: Breakpoint[] = [
+  "mobile",
+  "tablet",
+  "laptop",
+  "desktop",
+  "wide",
+  "ultra",
+];
+
+export function breakpointRank(bp: Breakpoint): number {
+  return BREAKPOINT_ORDER.indexOf(bp);
+}
+
+export function isNarrow(bp: Breakpoint): boolean {
+  return breakpointRank(bp) <= breakpointRank("tablet");
+}
+
+const PLACEMENT_BY_ROLE: Partial<Record<SlotRole, PhysicalRegion["placement"]>> = {
+  navigation: "inline-start",
+  filter: "inline-start",
+  inspector: "inline-end",
+  secondary: "inline-end",
+  toolbar: "block-start",
+  search: "block-start",
+  status: "block-start",
+  console: "block-end",
+  footer: "block-end",
+  timeline: "block-end",
+  summary: "inline-end",
+  preview: "inline-end",
+  drawer: "overlay",
+  modal: "overlay",
+  overlay: "overlay",
+};
+
+function placementFor(slot: SlotDefinition): PhysicalRegion["placement"] {
+  return PLACEMENT_BY_ROLE[slot.role] ?? "center";
+}
+
+export interface ResolvePlanInput {
+  node: LayoutNode;
+  item: LayoutRegistryItem;
+  viewport: LayoutViewport;
+  state?: PersistedLayoutState;
+}
+
+/** Compute the physical plan for a single layout node. */
+export function resolvePhysicalPlan(input: ResolvePlanInput): PhysicalLayoutPlan {
+  const { node, item, viewport, state } = input;
+  const narrow = isNarrow(viewport.breakpoint);
+  const bpRank = breakpointRank(viewport.breakpoint);
+
+  const regions: PhysicalRegion[] = item.slots.map((slot) => {
+    const present = node.slots[slot.name] !== undefined;
+    const persisted = state?.panels?.[slot.name];
+    const placement = placementFor(slot);
+
+    let visible = present;
+    let collapsed = persisted?.collapsed ?? false;
+    let layer: PhysicalRegion["layer"] | undefined;
+    let regionPlacement = placement;
+
+    // Apply responsive slot policy.
+    if (slot.responsive?.hideBelow && bpRank < breakpointRank(slot.responsive.hideBelow)) {
+      visible = false;
+    }
+    if (slot.responsive?.collapseBelow && bpRank < breakpointRank(slot.responsive.collapseBelow)) {
+      collapsed = true;
+    }
+
+    // Apply narrow-screen behavior from slot priority (never drop a required
+    // primary/content slot — demote supporting panes to drawers/sheets instead).
+    if (narrow && slot.priority) {
+      switch (slot.priority.behaviorOnNarrow) {
+        case "collapse":
+          collapsed = true;
+          break;
+        case "hide":
+          if (!slot.required) visible = false;
+          break;
+        case "move-to-drawer":
+          regionPlacement = "overlay";
+          layer = "drawer";
+          break;
+        case "move-to-bottom-sheet":
+          regionPlacement = "overlay";
+          layer = "sheet";
+          break;
+        case "route-stack":
+        case "tabs":
+        case "keep":
+        default:
+          break;
+      }
+    }
+
+    return {
+      slot: slot.name,
+      placement: regionPlacement,
+      visible,
+      collapsed,
+      mounted: present,
+      layer,
+      size: persisted?.width
+        ? { width: persisted.width }
+        : persisted?.height
+          ? { height: persisted.height }
+          : undefined,
+    };
+  });
+
+  const mode: PhysicalLayoutPlan["mode"] = narrow
+    ? regions.some((r) => r.layer === "drawer" || r.layer === "sheet")
+      ? "drawer-assisted"
+      : "single-pane"
+    : "multi-pane";
+
+  return { layoutId: node.id, mode, regions };
+}
+
+/** Convenience: get the region for a slot from a plan. */
+export function regionFor(
+  plan: PhysicalLayoutPlan,
+  slot: string,
+): PhysicalRegion | undefined {
+  return plan.regions.find((r) => r.slot === slot);
+}