@echothink-ui/layout 0.2.0

package/src/layout-system/schema/validate.ts

@@ -0,0 +1,168 @@
+/**
+ * Layout validation (`layout-spec.md` §16, §20).
+ *
+ * Hand-written structural + semantic validation that walks a `LayoutNode`
+ * against a registry and emits `LayoutDiagnostic[]`. (zod can be layered on top
+ * later for untrusted JSON; kept dependency-free here.)
+ */
+import type {
+  LayoutDiagnostic,
+  LayoutNode,
+  NodeAcceptSpec,
+  SlotContent,
+  SlotDefinition,
+} from "./types.js";
+import type { LayoutRegistry } from "../registry/registry.js";
+
+const DEFAULT_MAX_DEPTH = 8;
+
+function acceptsContent(accepts: NodeAcceptSpec[], content: SlotContent): boolean {
+  return accepts.some((spec) => {
+    switch (content.kind) {
+      case "component":
+        return (
+          spec.kind === "component" &&
+          (!spec.componentTypes || spec.componentTypes.includes(content.component))
+        );
+      case "layout":
+        return (
+          spec.kind === "layout" &&
+          (!spec.layoutTypes || spec.layoutTypes.includes(content.layout.type))
+        );
+      case "template":
+        return (
+          spec.kind === "template" &&
+          (!spec.templateTypes || spec.templateTypes.includes(content.template))
+        );
+      case "fragment":
+        return spec.kind === "fragment";
+      case "empty":
+        return spec.kind === "empty";
+      default:
+        return false;
+    }
+  });
+}
+
+function* childLayouts(content: SlotContent): Generator<LayoutNode> {
+  if (content.kind === "layout") {
+    yield content.layout;
+  } else if (content.kind === "fragment") {
+    for (const item of content.items) yield* childLayouts(item);
+  }
+}
+
+export interface ValidateOptions {
+  maxDepth?: number;
+}
+
+/** Validate a layout tree, returning diagnostics (empty ⇒ valid). */
+export function validateLayout(
+  root: LayoutNode,
+  registry: LayoutRegistry,
+  opts: ValidateOptions = {},
+): LayoutDiagnostic[] {
+  const diagnostics: LayoutDiagnostic[] = [];
+  const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const visiting = new Set<string>();
+
+  function walk(node: LayoutNode, path: string[], depth: number): void {
+    const nodePath = [...path, node.id];
+
+    if (depth > maxDepth) {
+      diagnostics.push({
+        level: "error",
+        code: "MAX_DEPTH_EXCEEDED",
+        path: nodePath,
+        message: `Layout nesting exceeds maxDepth=${maxDepth}.`,
+      });
+      return;
+    }
+
+    if (visiting.has(node.id)) {
+      diagnostics.push({
+        level: "error",
+        code: "CYCLE_DETECTED",
+        path: nodePath,
+        message: `Cycle detected at node "${node.id}".`,
+      });
+      return;
+    }
+    visiting.add(node.id);
+
+    const item = registry.get(node.type);
+    if (!item) {
+      diagnostics.push({
+        level: "error",
+        code: "UNKNOWN_LAYOUT_TYPE",
+        path: nodePath,
+        message: `Unknown layout type "${node.type}".`,
+        suggestion: `Register "${node.type}" or use one of: ${registry.types().slice(0, 8).join(", ")}…`,
+      });
+      visiting.delete(node.id);
+      return;
+    }
+
+    const slotByName = new Map<string, SlotDefinition>(
+      item.slots.map((s) => [s.name, s]),
+    );
+
+    // Unknown slots present on the node.
+    for (const slotName of Object.keys(node.slots)) {
+      if (!slotByName.has(slotName)) {
+        diagnostics.push({
+          level: "warning",
+          code: "UNKNOWN_SLOT",
+          path: [...nodePath, slotName],
+          message: `Slot "${slotName}" is not declared by "${node.type}".`,
+        });
+      }
+    }
+
+    // Required slots + accepts + cardinality.
+    for (const slot of item.slots) {
+      const content = node.slots[slot.name];
+      if (content === undefined) {
+        if (slot.required && !slot.fallback?.empty) {
+          diagnostics.push({
+            level: "error",
+            code: "SLOT_REQUIRED",
+            path: [...nodePath, slot.name],
+            message: `Required slot "${slot.name}" of "${node.type}" has no content or fallback.`,
+          });
+        }
+        continue;
+      }
+      if (!acceptsContent(slot.accepts, content)) {
+        diagnostics.push({
+          level: "error",
+          code: "SLOT_ACCEPTS_VIOLATION",
+          path: [...nodePath, slot.name],
+          message: `Slot "${slot.name}" of "${node.type}" does not accept ${content.kind} content.`,
+        });
+      }
+      if (content.kind === "fragment" && slot.cardinality?.max && slot.cardinality.max !== "unbounded") {
+        if (content.items.length > slot.cardinality.max) {
+          diagnostics.push({
+            level: "error",
+            code: "SLOT_CARDINALITY_VIOLATION",
+            path: [...nodePath, slot.name],
+            message: `Slot "${slot.name}" allows at most ${slot.cardinality.max} items.`,
+          });
+        }
+      }
+      for (const child of childLayouts(content)) {
+        walk(child, [...nodePath, slot.name], depth + 1);
+      }
+    }
+
+    visiting.delete(node.id);
+  }
+
+  walk(root, [], 0);
+  return diagnostics;
+}
+
+export function hasErrors(diagnostics: LayoutDiagnostic[]): boolean {
+  return diagnostics.some((d) => d.level === "error");
+}

package/src/layout-system/tokens/preset-tokens.ts

@@ -0,0 +1,77 @@
+/**
+ * Preset → Tier-2 token map (`layout-spec.md` §13.2).
+ *
+ * Per TOKEN_CONTRACT.md every value is a Tier-2 `--eth-*` CSS variable; presets
+ * override Tier-2, layout never reads raw `--cds-*`. These resolve through the
+ * `@echothink-ui/style` preset stylesheets that are already on the page.
+ */
+import type {
+  ComponentStyleParams,
+  ResolvedLayoutTokens,
+  StylePresetTokenMap,
+} from "../schema/types.js";
+
+export const presetTokenMap: StylePresetTokenMap = {
+  "carbon-like": {
+    surface: "var(--eth-surface, var(--eth-color-surface))",
+    surfaceMuted: "var(--eth-surface-muted, var(--eth-color-surface-muted))",
+    border: "var(--eth-border-subtle, var(--eth-color-border))",
+    text: "var(--eth-text-primary, var(--eth-color-text))",
+    textMuted: "var(--eth-text-secondary, var(--eth-color-text-secondary))",
+    accent: "var(--eth-accent, var(--eth-color-accent))",
+    radius: "var(--eth-radius-sm, 0.125rem)",
+    shadow: "var(--eth-shadow-none, none)",
+  },
+  "soft-card": {
+    surface: "var(--eth-surface, var(--eth-color-surface))",
+    surfaceMuted: "var(--eth-surface-muted, var(--eth-color-surface-muted))",
+    border: "var(--eth-border-soft, var(--eth-color-border))",
+    text: "var(--eth-text-primary, var(--eth-color-text))",
+    textMuted: "var(--eth-text-secondary, var(--eth-color-text-secondary))",
+    accent: "var(--eth-accent, var(--eth-color-accent))",
+    radius: "var(--eth-radius-lg, 0.75rem)",
+    shadow: "var(--eth-shadow-card, 0 1px 2px rgba(15,23,42,0.08))",
+  },
+  glass: {
+    surface: "var(--eth-surface-glass, var(--eth-color-surface))",
+    surfaceMuted: "var(--eth-surface-glass-muted, var(--eth-color-surface-muted))",
+    border: "var(--eth-border-glass, var(--eth-color-border))",
+    text: "var(--eth-text-on-glass, var(--eth-color-text))",
+    textMuted: "var(--eth-text-on-glass-muted, var(--eth-color-text-secondary))",
+    accent: "var(--eth-accent, var(--eth-color-accent))",
+    radius: "var(--eth-radius-xl, 1rem)",
+    shadow: "var(--eth-shadow-floating, 0 8px 32px rgba(15,23,42,0.18))",
+    backdrop: "blur(16px)",
+  },
+  bright: {
+    surface: "var(--eth-surface, var(--eth-color-surface))",
+    surfaceMuted: "var(--eth-surface-muted, var(--eth-color-surface-muted))",
+    border: "var(--eth-border-bright, var(--eth-color-border))",
+    text: "var(--eth-text-primary, var(--eth-color-text))",
+    textMuted: "var(--eth-text-secondary, var(--eth-color-text-secondary))",
+    accent: "var(--eth-accent, var(--eth-color-accent))",
+    radius: "var(--eth-radius-md, 0.5rem)",
+    shadow: "var(--eth-shadow-sm, 0 1px 2px rgba(15,23,42,0.06))",
+  },
+  "studio-dark": {
+    surface: "var(--eth-surface-studio, var(--eth-color-surface))",
+    surfaceMuted: "var(--eth-surface-studio-muted, var(--eth-color-surface-muted))",
+    border: "var(--eth-border-studio, var(--eth-color-border))",
+    text: "var(--eth-text-on-dark, var(--eth-color-text))",
+    textMuted: "var(--eth-text-on-dark-muted, var(--eth-color-text-secondary))",
+    accent: "var(--eth-accent, var(--eth-color-accent))",
+    radius: "var(--eth-radius-sm, 0.125rem)",
+    shadow: "var(--eth-shadow-none, none)",
+  },
+};
+
+const densityGap: Record<ComponentStyleParams["density"], string> = {
+  compact: "var(--eth-space-sm, 0.5rem)",
+  standard: "var(--eth-space-md, 0.75rem)",
+  comfortable: "var(--eth-space-lg, 1rem)",
+};
+
+/** Resolve the token set for a final `ComponentStyleParams`. */
+export function resolveTokens(style: ComponentStyleParams): ResolvedLayoutTokens {
+  return { ...presetTokenMap[style.preset], gap: densityGap[style.density] };
+}

package/src/styles.css

@@ -0,0 +1,178 @@
+/**
+ * @echothink-ui/layout — layout system styles.
+ *
+ * Structural CSS for the recursive renderer's primitives/regions/page-layouts.
+ * Colors/spacing/radius come from Tier-2 `--eth-*` tokens (TOKEN_CONTRACT.md);
+ * preset stylesheets (`@echothink-ui/style`) supply the values.
+ */
+
+:where(.eth-ls-unknown) {
+  padding: var(--eth-space-md, 0.75rem);
+  border: 1px dashed var(--eth-color-border, #cbd5e1);
+  border-radius: var(--eth-radius-sm, 0.25rem);
+  color: var(--eth-color-text-secondary, #64748b);
+  font: var(--eth-type-body-sm, 0.8125rem/1.4 system-ui, sans-serif);
+}
+:where(.eth-ls-empty) {
+  min-height: 1.5rem;
+}
+:where(.eth-ls-component) {
+  display: contents;
+}
+:where(.eth-ls-fragment) {
+  min-width: 0;
+}
+
+/* ----------------------------- Panel ----------------------------- */
+:where(.eth-ls-panel) {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  overflow: hidden;
+}
+:where(.eth-ls-panel__header) {
+  padding: var(--eth-space-sm, 0.5rem) var(--eth-space-md, 0.75rem);
+  border-bottom: 1px solid var(--eth-color-border, #e2e8f0);
+  font-weight: 600;
+}
+:where(.eth-ls-panel__body) {
+  padding: var(--eth-space-md, 0.75rem);
+  overflow: auto;
+  flex: 1;
+  min-height: 0;
+}
+:where(.eth-ls-panel__footer) {
+  padding: var(--eth-space-sm, 0.5rem) var(--eth-space-md, 0.75rem);
+  border-top: 1px solid var(--eth-color-border, #e2e8f0);
+}
+
+/* --------------------------- SplitPane --------------------------- */
+:where(.eth-ls-split) {
+  width: 100%;
+}
+:where(.eth-ls-split__pane) {
+  overflow: auto;
+}
+
+/* ----------------------------- Tabs ------------------------------ */
+:where(.eth-ls-tabs) {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+:where(.eth-ls-tabs__list) {
+  display: flex;
+  gap: var(--eth-space-xs, 0.25rem);
+  border-bottom: 1px solid var(--eth-color-border, #e2e8f0);
+}
+:where(.eth-ls-tabs__tab) {
+  appearance: none;
+  background: transparent;
+  border: 0;
+  border-bottom: 2px solid transparent;
+  padding: var(--eth-space-sm, 0.5rem) var(--eth-space-md, 0.75rem);
+  color: var(--eth-color-text-secondary, #64748b);
+  cursor: pointer;
+  font: inherit;
+}
+:where(.eth-ls-tabs__tab--active) {
+  color: var(--eth-color-text, #0f172a);
+  border-bottom-color: var(--eth-color-accent, #2563eb);
+}
+:where(.eth-ls-tabs__panel) {
+  padding: var(--eth-space-md, 0.75rem) 0;
+  min-height: 0;
+}
+
+/* ---------------------------- Stepper ---------------------------- */
+:where(.eth-ls-stepper__steps) {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  gap: var(--eth-space-md, 0.75rem);
+}
+:where(.eth-ls-stepper--vertical) .eth-ls-stepper__steps {
+  flex-direction: column;
+}
+:where(.eth-ls-stepper__step-button) {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--eth-space-sm, 0.5rem);
+  appearance: none;
+  background: transparent;
+  border: 0;
+  cursor: pointer;
+  color: var(--eth-color-text-secondary, #64748b);
+  font: inherit;
+}
+:where(.eth-ls-stepper__step--current) .eth-ls-stepper__step-button,
+:where(.eth-ls-stepper__step--active) .eth-ls-stepper__step-button {
+  color: var(--eth-color-text, #0f172a);
+  font-weight: 600;
+}
+:where(.eth-ls-stepper__index) {
+  display: inline-grid;
+  place-items: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  border-radius: 999px;
+  border: 1px solid var(--eth-color-border, #cbd5e1);
+}
+:where(.eth-ls-stepper__step--valid) .eth-ls-stepper__index,
+:where(.eth-ls-stepper__step--complete) .eth-ls-stepper__index {
+  background: var(--eth-color-success, #16a34a);
+  color: #fff;
+  border-color: transparent;
+}
+:where(.eth-ls-stepper__step--invalid) .eth-ls-stepper__index {
+  background: var(--eth-color-danger, #dc2626);
+  color: #fff;
+  border-color: transparent;
+}
+:where(.eth-ls-stepper__content) {
+  flex: 1;
+  min-width: 0;
+}
+
+/* ---------------------------- Toolbar ---------------------------- */
+:where(.eth-ls-toolbar) {
+  padding: var(--eth-space-sm, 0.5rem) var(--eth-space-md, 0.75rem);
+  min-height: 3rem;
+}
+
+/* --------------------------- Inspector --------------------------- */
+:where(.eth-ls-inspector__header) {
+  padding: var(--eth-space-sm, 0.5rem) var(--eth-space-md, 0.75rem);
+  border-bottom: 1px solid var(--eth-color-border, #e2e8f0);
+  font-weight: 600;
+}
+:where(.eth-ls-inspector__body) {
+  padding: var(--eth-space-md, 0.75rem);
+}
+:where(.eth-ls-inspector__footer) {
+  padding: var(--eth-space-sm, 0.5rem) var(--eth-space-md, 0.75rem);
+  border-top: 1px solid var(--eth-color-border, #e2e8f0);
+}
+
+/* ------------------------- Page layouts -------------------------- */
+:where(
+  .eth-ls-admin-shell,
+  .eth-ls-datagrid,
+  .eth-ls-workbench,
+  .eth-ls-wizard,
+  .eth-ls-monitoring,
+  .eth-ls-canvas
+) {
+  width: 100%;
+}
+:where(.eth-ls-monitoring__metrics) {
+  padding: var(--eth-space-md, 0.75rem);
+}
+
+/* Narrow screens: collapse multi-pane page grids to a single column. */
+@media (max-width: 48rem) {
+  :where(.eth-ls-datagrid, .eth-ls-workbench, .eth-ls-wizard, .eth-ls-canvas) {
+    grid-template-columns: 1fr !important;
+  }
+}