@echothink-ui/layout 0.2.0

package/src/layout-system/primitives/index.tsx

@@ -0,0 +1,266 @@
+/**
+ * Layout primitives (`layout-spec.md` §14, §19): Panel, SplitPane, Tabs, Stepper.
+ *
+ * Each is a `LayoutRegistryItem` whose renderer arranges the engine-rendered
+ * `slots` map. Tabs/Stepper read their `composition` and render inline content
+ * via `SlotContentRenderer`, carrying a11y semantics (§12).
+ */
+import * as React from "react";
+import type {
+  LayoutRegistryItem,
+  LayoutRendererProps,
+  ParallelComposition,
+  StepperComposition,
+  SwitchComposition,
+} from "../schema/types.js";
+import { SlotContentRenderer } from "../renderer/renderer.js";
+import { inlineSlot } from "../renderer/region.js";
+
+/* ----------------------------- Panel ----------------------------- */
+
+function PanelRenderer({ slots, context }: LayoutRendererProps) {
+  return (
+    <section
+      className="eth-ls-panel"
+      style={{
+        background: context.tokens.surface,
+        border: `1px solid ${context.tokens.border}`,
+        borderRadius: context.tokens.radius,
+        boxShadow: context.tokens.shadow,
+        color: context.tokens.text,
+      }}
+    >
+      {slots.header ? <header className="eth-ls-panel__header">{slots.header}</header> : null}
+      <div className="eth-ls-panel__body">{slots.body}</div>
+      {slots.footer ? <footer className="eth-ls-panel__footer">{slots.footer}</footer> : null}
+    </section>
+  );
+}
+
+export const PanelLayout: LayoutRegistryItem = {
+  type: "Primitive.Panel",
+  displayName: "Panel",
+  tier: "primitive",
+  category: "primitive",
+  description: "A bounded surface with optional header/body/footer.",
+  slots: [
+    { name: "header", role: "toolbar", accepts: [{ kind: "component" }, { kind: "fragment" }] },
+    {
+      name: "body",
+      role: "content",
+      required: true,
+      accepts: [{ kind: "component" }, { kind: "layout" }, { kind: "fragment" }],
+    },
+    { name: "footer", role: "footer", accepts: [{ kind: "component" }, { kind: "fragment" }] },
+  ],
+  defaultStyleIntent: { surface: "panel" },
+  renderer: PanelRenderer,
+};
+
+/* --------------------------- SplitPane --------------------------- */
+
+function SplitPaneRenderer({ slots, context, composition, variant }: LayoutRendererProps) {
+  const orientation = variant === "vertical" ? "vertical" : "horizontal";
+  const parallel = composition?.op === "parallel" ? (composition as ParallelComposition) : undefined;
+  const primaryBasis = parallel?.sizing?.primary?.basis;
+  return (
+    <div
+      className={`eth-ls-split eth-ls-split--${orientation}`}
+      style={{
+        display: "grid",
+        gap: parallel?.gapToken ? `var(${parallel.gapToken})` : context.tokens.gap,
+        gridTemplateColumns:
+          orientation === "horizontal"
+            ? `${primaryBasis ? cssSize(primaryBasis) : "1fr"} 1fr`
+            : undefined,
+        gridTemplateRows: orientation === "vertical" ? `${primaryBasis ? cssSize(primaryBasis) : "1fr"} 1fr` : undefined,
+        height: "100%",
+        minHeight: 0,
+      }}
+    >
+      <div className="eth-ls-split__pane eth-ls-split__pane--primary" style={{ minWidth: 0, minHeight: 0 }}>
+        {slots.primary}
+      </div>
+      <div
+        className="eth-ls-split__pane eth-ls-split__pane--secondary"
+        role="separator"
+        aria-orientation={orientation}
+        style={{ minWidth: 0, minHeight: 0 }}
+      >
+        {slots.secondary}
+      </div>
+    </div>
+  );
+}
+
+function cssSize(value: number | string): string {
+  return typeof value === "number" ? `${value}px` : value;
+}
+
+export const SplitPaneLayout: LayoutRegistryItem = {
+  type: "Primitive.SplitPane",
+  displayName: "Split Pane",
+  tier: "primitive",
+  category: "primitive",
+  description: "Two resizable panes split horizontally or vertically.",
+  variants: [
+    { id: "horizontal", label: "Left / Right" },
+    { id: "vertical", label: "Top / Bottom" },
+  ],
+  slots: [
+    {
+      name: "primary",
+      role: "primary",
+      required: true,
+      accepts: [{ kind: "component" }, { kind: "layout" }, { kind: "template" }, { kind: "fragment" }],
+    },
+    {
+      name: "secondary",
+      role: "secondary",
+      required: true,
+      accepts: [{ kind: "component" }, { kind: "layout" }, { kind: "template" }, { kind: "fragment" }],
+    },
+  ],
+  defaultComposition: {
+    op: "parallel",
+    axis: "x",
+    slots: ["primary", "secondary"],
+    sizing: { primary: { basis: "1fr", resizable: true }, secondary: { grow: 1 } },
+  },
+  renderer: SplitPaneRenderer,
+};
+
+/* ----------------------------- Tabs ------------------------------ */
+
+function TabsRenderer({ node, context, composition }: LayoutRendererProps) {
+  const switchSpec =
+    composition?.op === "switch" ? (composition as SwitchComposition) : undefined;
+  const items = switchSpec?.items ?? [];
+  const initial = switchSpec?.activeKey ?? items[0]?.key;
+  const [active, setActive] = React.useState<string | undefined>(initial);
+  const activeItem = items.find((i) => i.key === active) ?? items[0];
+
+  return (
+    <div className="eth-ls-tabs" style={{ color: context.tokens.text }}>
+      <div className="eth-ls-tabs__list" role="tablist">
+        {items.map((item) => {
+          const selected = item.key === activeItem?.key;
+          return (
+            <button
+              key={item.key}
+              type="button"
+              role="tab"
+              id={`tab-${node.id}-${item.key}`}
+              aria-selected={selected}
+              aria-controls={`tabpanel-${node.id}-${item.key}`}
+              tabIndex={selected ? 0 : -1}
+              className={`eth-ls-tabs__tab${selected ? " eth-ls-tabs__tab--active" : ""}`}
+              onClick={() => setActive(item.key)}
+            >
+              {item.label}
+            </button>
+          );
+        })}
+      </div>
+      {activeItem ? (
+        <div
+          className="eth-ls-tabs__panel"
+          role="tabpanel"
+          id={`tabpanel-${node.id}-${activeItem.key}`}
+          aria-labelledby={`tab-${node.id}-${activeItem.key}`}
+        >
+          <SlotContentRenderer
+            node={node}
+            slot={inlineSlot(`tab:${activeItem.key}`, "content")}
+            content={activeItem.content}
+            parentContext={context}
+          />
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export const TabsLayout: LayoutRegistryItem = {
+  type: "Primitive.Tabs",
+  displayName: "Tabs",
+  tier: "primitive",
+  category: "primitive",
+  description: "Switch composition rendering one panel at a time with tablist semantics.",
+  slots: [],
+  defaultComposition: { op: "switch", mode: "tabs", items: [] },
+  renderer: TabsRenderer,
+};
+
+/* ---------------------------- Stepper ---------------------------- */
+
+function StepperRenderer({ node, context, composition }: LayoutRendererProps) {
+  const stepper =
+    composition?.op === "stepper" ? (composition as StepperComposition) : undefined;
+  const steps = stepper?.steps ?? [];
+  const firstActive = steps.findIndex((s) => s.status === "active");
+  const [activeIndex, setActiveIndex] = React.useState<number>(firstActive >= 0 ? firstActive : 0);
+  const orientation = stepper?.orientation ?? "horizontal";
+  const activeStep = steps[activeIndex];
+
+  return (
+    <div
+      className={`eth-ls-stepper eth-ls-stepper--${orientation}`}
+      style={{ display: "flex", flexDirection: orientation === "vertical" ? "row" : "column", gap: context.tokens.gap, color: context.tokens.text }}
+    >
+      <ol className="eth-ls-stepper__steps" aria-label="Steps">
+        {steps.map((step, index) => {
+          const current = index === activeIndex;
+          return (
+            <li
+              key={step.id}
+              className={`eth-ls-stepper__step eth-ls-stepper__step--${step.status ?? "pending"}${current ? " eth-ls-stepper__step--current" : ""}`}
+              aria-current={current ? "step" : undefined}
+            >
+              <button type="button" className="eth-ls-stepper__step-button" onClick={() => setActiveIndex(index)}>
+                <span className="eth-ls-stepper__index">{index + 1}</span>
+                <span className="eth-ls-stepper__label">{step.label}</span>
+              </button>
+            </li>
+          );
+        })}
+      </ol>
+      {activeStep ? (
+        <div className="eth-ls-stepper__content">
+          <SlotContentRenderer
+            node={node}
+            slot={inlineSlot(`step:${activeStep.id}`, "form")}
+            content={activeStep.content}
+            parentContext={context}
+          />
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export const StepperLayout: LayoutRegistryItem = {
+  type: "Primitive.Stepper",
+  displayName: "Stepper",
+  tier: "primitive",
+  category: "primitive",
+  description: "Flow-oriented step container with validation/navigation semantics.",
+  variants: [{ id: "horizontal" }, { id: "vertical" }, { id: "with-preview" }],
+  slots: [],
+  defaultComposition: {
+    op: "stepper",
+    orientation: "horizontal",
+    stepSlot: "stepper",
+    contentSlot: "content",
+    steps: [],
+  },
+  defaultStyleIntent: { taskMode: "wizard", visualEmphasis: "balanced" },
+  renderer: StepperRenderer,
+};
+
+export const primitiveLayouts: LayoutRegistryItem[] = [
+  PanelLayout,
+  SplitPaneLayout,
+  TabsLayout,
+  StepperLayout,
+];

package/src/layout-system/regions/index.tsx

@@ -0,0 +1,90 @@
+/**
+ * Region layouts (`layout-spec.md` §14, §19): Toolbar, Inspector.
+ */
+import * as React from "react";
+import type { LayoutRegistryItem, LayoutRendererProps } from "../schema/types.js";
+
+/* ---------------------------- Toolbar ---------------------------- */
+
+function ToolbarRenderer({ slots, context }: LayoutRendererProps) {
+  return (
+    <div
+      className="eth-ls-toolbar"
+      role="toolbar"
+      style={{
+        display: "flex",
+        alignItems: "center",
+        gap: context.tokens.gap,
+        background: context.tokens.surfaceMuted,
+        borderBottom: `1px solid ${context.tokens.border}`,
+        color: context.tokens.text,
+      }}
+    >
+      {slots.start ? <div className="eth-ls-toolbar__start">{slots.start}</div> : null}
+      {slots.center ? <div className="eth-ls-toolbar__center" style={{ flex: 1, minWidth: 0 }}>{slots.center}</div> : <div style={{ flex: 1 }} />}
+      {slots.end ? <div className="eth-ls-toolbar__end">{slots.end}</div> : null}
+    </div>
+  );
+}
+
+export const ToolbarLayout: LayoutRegistryItem = {
+  type: "Region.Toolbar",
+  displayName: "Toolbar",
+  tier: "region",
+  category: "region",
+  description: "Horizontal toolbar with start/center/end groups and roving focus.",
+  slots: [
+    { name: "start", role: "toolbar", accepts: [{ kind: "component" }, { kind: "fragment" }] },
+    { name: "center", role: "toolbar", accepts: [{ kind: "component" }, { kind: "fragment" }] },
+    { name: "end", role: "toolbar", accepts: [{ kind: "component" }, { kind: "fragment" }] },
+  ],
+  defaultStyleIntent: { surface: "region" },
+  renderer: ToolbarRenderer,
+};
+
+/* --------------------------- Inspector --------------------------- */
+
+function InspectorRenderer({ slots, context }: LayoutRendererProps) {
+  return (
+    <aside
+      className="eth-ls-inspector"
+      aria-label="Inspector"
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        minHeight: 0,
+        background: context.tokens.surface,
+        borderInlineStart: `1px solid ${context.tokens.border}`,
+        color: context.tokens.text,
+      }}
+    >
+      {slots.header ? <header className="eth-ls-inspector__header">{slots.header}</header> : null}
+      <div className="eth-ls-inspector__body" style={{ overflow: "auto", flex: 1, minHeight: 0 }}>
+        {slots.body}
+      </div>
+      {slots.footer ? <footer className="eth-ls-inspector__footer">{slots.footer}</footer> : null}
+    </aside>
+  );
+}
+
+export const InspectorLayout: LayoutRegistryItem = {
+  type: "Region.Inspector",
+  displayName: "Inspector",
+  tier: "region",
+  category: "region",
+  description: "An inline-end inspector panel with header/body/footer.",
+  slots: [
+    { name: "header", role: "toolbar", accepts: [{ kind: "component" }, { kind: "fragment" }] },
+    {
+      name: "body",
+      role: "inspector",
+      required: true,
+      accepts: [{ kind: "component" }, { kind: "layout" }, { kind: "fragment" }],
+    },
+    { name: "footer", role: "footer", accepts: [{ kind: "component" }, { kind: "fragment" }] },
+  ],
+  defaultStyleIntent: { surface: "panel", interactionMode: "edit" },
+  renderer: InspectorRenderer,
+};
+
+export const regionLayouts: LayoutRegistryItem[] = [ToolbarLayout, InspectorLayout];

package/src/layout-system/registry/builtins.ts

@@ -0,0 +1,19 @@
+/**
+ * Builtin layout catalog + default registry factory (`layout-spec.md` §19).
+ */
+import type { LayoutRegistryItem } from "../schema/types.js";
+import { LayoutRegistry } from "./registry.js";
+import { primitiveLayouts } from "../primitives/index.js";
+import { regionLayouts } from "../regions/index.js";
+import { pageLayouts } from "../page-layouts/index.js";
+
+export const builtinLayouts: LayoutRegistryItem[] = [
+  ...primitiveLayouts,
+  ...regionLayouts,
+  ...pageLayouts,
+];
+
+/** A registry preloaded with the MVP builtin layouts. */
+export function createDefaultLayoutRegistry(): LayoutRegistry {
+  return new LayoutRegistry().registerAll(builtinLayouts);
+}

package/src/layout-system/registry/registry.ts

@@ -0,0 +1,47 @@
+/**
+ * Layout registry (`layout-spec.md` §9).
+ *
+ * Maps a layout `type` (e.g. "PageLayout.Workbench") to its `LayoutRegistryItem`
+ * (slots, renderer, default composition/style intent). The recursive renderer
+ * and the validator consult it; it is also the source the builder/copilot read
+ * to discover available layouts and their slot contracts.
+ */
+import type { LayoutRegistryItem } from "../schema/types.js";
+
+export class LayoutRegistry {
+  private readonly items = new Map<string, LayoutRegistryItem>();
+
+  register(item: LayoutRegistryItem): this {
+    this.items.set(item.type, item);
+    return this;
+  }
+
+  registerAll(items: readonly LayoutRegistryItem[]): this {
+    for (const item of items) this.register(item);
+    return this;
+  }
+
+  get(type: string): LayoutRegistryItem | undefined {
+    return this.items.get(type);
+  }
+
+  has(type: string): boolean {
+    return this.items.has(type);
+  }
+
+  list(): LayoutRegistryItem[] {
+    return [...this.items.values()];
+  }
+
+  types(): string[] {
+    return [...this.items.keys()];
+  }
+
+  byTier(tier: LayoutRegistryItem["tier"]): LayoutRegistryItem[] {
+    return this.list().filter((i) => i.tier === tier);
+  }
+
+  byCategory(category: LayoutRegistryItem["category"]): LayoutRegistryItem[] {
+    return this.list().filter((i) => i.category === category);
+  }
+}

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

@@ -0,0 +1,89 @@
+/**
+ * React contexts for the layout engine.
+ *
+ * Two contexts:
+ *  - `LayoutRuntimeContext` — the per-node runtime context (style/surface/depth/
+ *    tokens) that flows down and is recomposed at each slot boundary.
+ *  - `LayoutEngine` — the engine config (registry + resolvers + state store +
+ *    diagnostics sink). Decoupled from any component catalog: the host injects a
+ *    `componentResolver` and optional `templateResolver`.
+ */
+import * as React from "react";
+import type {
+  LayoutDiagnostic,
+  LayoutNode,
+  LayoutRuntimeContext,
+} from "../schema/types.js";
+import { createRootContext } from "../inference/context.js";
+import { LayoutRegistry } from "../registry/registry.js";
+import type { LayoutStateStore } from "../runtime/state.js";
+import { createMemoryLayoutStateStore } from "../runtime/state.js";
+
+export type ComponentResolver = (
+  name: string,
+) => React.ComponentType<Record<string, unknown>> | undefined;
+
+export type TemplateResolver = (name: string) => LayoutNode | undefined;
+
+export interface LayoutEngine {
+  registry: LayoutRegistry;
+  componentResolver: ComponentResolver;
+  templateResolver?: TemplateResolver;
+  stateStore: LayoutStateStore;
+  onDiagnostics?: (diagnostics: LayoutDiagnostic[]) => void;
+}
+
+const RuntimeContext = React.createContext<LayoutRuntimeContext>(createRootContext());
+const EngineContext = React.createContext<LayoutEngine | null>(null);
+
+export function LayoutContextProvider({
+  value,
+  children,
+}: {
+  value: LayoutRuntimeContext;
+  children: React.ReactNode;
+}) {
+  return <RuntimeContext.Provider value={value}>{children}</RuntimeContext.Provider>;
+}
+
+export function useLayoutContext(): LayoutRuntimeContext {
+  return React.useContext(RuntimeContext);
+}
+
+export function LayoutEngineProvider({
+  value,
+  children,
+}: {
+  value: LayoutEngine;
+  children: React.ReactNode;
+}) {
+  return <EngineContext.Provider value={value}>{children}</EngineContext.Provider>;
+}
+
+export function useLayoutEngine(): LayoutEngine {
+  const engine = React.useContext(EngineContext);
+  if (!engine) {
+    throw new Error(
+      "useLayoutEngine must be used within <LayoutRoot> / <LayoutEngineProvider>.",
+    );
+  }
+  return engine;
+}
+
+export interface BuildEngineInput {
+  registry: LayoutRegistry;
+  componentResolver: ComponentResolver;
+  templateResolver?: TemplateResolver;
+  stateStore?: LayoutStateStore;
+  onDiagnostics?: (diagnostics: LayoutDiagnostic[]) => void;
+}
+
+export function buildEngine(input: BuildEngineInput): LayoutEngine {
+  return {
+    registry: input.registry,
+    componentResolver: input.componentResolver,
+    templateResolver: input.templateResolver,
+    stateStore: input.stateStore ?? createMemoryLayoutStateStore(),
+    onDiagnostics: input.onDiagnostics,
+  };
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Renderer helpers shared by primitive/region/page-layout renderers.
+ */
+import type {
+  NodeAcceptSpec,
+  PhysicalLayoutPlan,
+  SlotDefinition,
+  SlotRole,
+} from "../schema/types.js";
+import { regionFor } from "../inference/responsive.js";
+
+const ANY_ACCEPTS: NodeAcceptSpec[] = [
+  { kind: "component" },
+  { kind: "layout" },
+  { kind: "template" },
+  { kind: "fragment" },
+  { kind: "empty" },
+];
+
+/** Synthesize a slot definition for composition-embedded content (tabs/steps). */
+export function inlineSlot(name: string, role: SlotRole = "content"): SlotDefinition {
+  return { name, role, accepts: ANY_ACCEPTS };
+}
+
+/** Whether a slot's physical region is visible (default true when absent). */
+export function isVisible(plan: PhysicalLayoutPlan, slot: string): boolean {
+  const region = regionFor(plan, slot);
+  return region ? region.visible : true;
+}
+
+/** Whether a slot's physical region is collapsed. */
+export function isCollapsed(plan: PhysicalLayoutPlan, slot: string): boolean {
+  return regionFor(plan, slot)?.collapsed ?? false;
+}