@echothink-ui/layout 0.2.0

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

@@ -0,0 +1,706 @@
+/**
+ * Typed Layout AST — the type system from `layout-spec.md` §4–§6, §9, §10, §16.
+ *
+ * A layout is a TYPED STRUCTURE, not a CSS fragment. These types describe the
+ * logical layout tree (the AST); the physical plan (placement/visibility per
+ * viewport) is derived separately by the responsive resolver. Component style
+ * params are INFERRED from the runtime context, never hard-coded by components.
+ */
+import type {
+  EthDensityMode,
+  EthPalette,
+  EthStylePreset,
+  EthTypeScale,
+} from "@echothink-ui/style";
+
+/* ------------------------------------------------------------------ *
+ * 4.1 Base enums
+ * ------------------------------------------------------------------ */
+
+export type LayoutTier = "primitive" | "region" | "page" | "workspace" | "route";
+
+export type NodeKind = "layout" | "component" | "template" | "fragment" | "empty";
+
+export type CompositionKind =
+  | "parallel"
+  | "stack"
+  | "embed"
+  | "overlay"
+  | "switch"
+  | "stepper"
+  | "portal"
+  | "conditional"
+  | "responsive";
+
+export type Axis = "x" | "y" | "z";
+
+export type SurfaceRole =
+  | "app"
+  | "page"
+  | "workspace"
+  | "region"
+  | "panel"
+  | "card"
+  | "sheet"
+  | "drawer"
+  | "modal"
+  | "popover"
+  | "floating"
+  | "console"
+  | "canvas";
+
+export type SlotRole =
+  | "navigation"
+  | "primary"
+  | "secondary"
+  | "inspector"
+  | "toolbar"
+  | "filter"
+  | "search"
+  | "content"
+  | "canvas"
+  | "console"
+  | "timeline"
+  | "stepper"
+  | "form"
+  | "preview"
+  | "summary"
+  | "drawer"
+  | "modal"
+  | "overlay"
+  | "footer"
+  | "status"
+  | "emptyState";
+
+/* ------------------------------------------------------------------ *
+ * 4.2 Component style params (the layout system's final output protocol).
+ * Re-uses the real `@echothink-ui/style` axes verbatim.
+ * ------------------------------------------------------------------ */
+
+export type ComponentStylePreset = EthStylePreset;
+export type ComponentPalette = EthPalette;
+export type ComponentDensity = EthDensityMode;
+export type ComponentTypeScale = EthTypeScale;
+
+export interface ComponentStyleParams {
+  preset: ComponentStylePreset;
+  palette: ComponentPalette;
+  density: ComponentDensity;
+  typeScale: ComponentTypeScale;
+}
+
+/* ------------------------------------------------------------------ *
+ * Layout style intent + task semantics
+ * ------------------------------------------------------------------ */
+
+export type LayoutTaskMode =
+  | "navigation"
+  | "crud"
+  | "analytics"
+  | "monitoring"
+  | "authoring"
+  | "review"
+  | "wizard"
+  | "playground"
+  | "copilot"
+  | "spatial";
+
+export type DataIntensity = "low" | "medium" | "high" | "realtime";
+export type InteractionMode = "read" | "edit" | "operate" | "debug" | "review";
+export type VisualEmphasis = "quiet" | "balanced" | "expressive" | "immersive";
+
+export interface LayoutStyleIntent {
+  preset?: ComponentStylePreset;
+  density?: ComponentDensity;
+  typeScale?: ComponentTypeScale;
+  surface?: SurfaceRole;
+  taskMode?: LayoutTaskMode;
+  dataIntensity?: DataIntensity;
+  interactionMode?: InteractionMode;
+  visualEmphasis?: VisualEmphasis;
+}
+
+/* ------------------------------------------------------------------ *
+ * 4.3 LayoutNode
+ * ------------------------------------------------------------------ */
+
+export interface LayoutNode {
+  kind: "layout";
+  id: string;
+  type: string;
+  tier?: LayoutTier;
+  variant?: string;
+
+  slots: Record<string, SlotContent>;
+  props?: Record<string, unknown>;
+
+  composition?: CompositionSpec;
+  constraints?: LayoutConstraints;
+  responsive?: ResponsiveRule[];
+  state?: LayoutStateSpec;
+  permissions?: PermissionSpec;
+
+  /** Explicit style intent; NOT the final `ComponentStyleParams`. */
+  styleIntent?: Partial<LayoutStyleIntent>;
+  /** Context-propagation policy toward children. */
+  contextPolicy?: Partial<ContextPolicy>;
+  /** Debug / observability / AI-generation explanation. */
+  meta?: LayoutNodeMeta;
+}
+
+export interface LayoutNodeMeta {
+  label?: string;
+  description?: string;
+  generatedBy?: "human" | "ai" | "template";
+  notes?: string;
+  [key: string]: unknown;
+}
+
+export interface LayoutConstraints {
+  minWidth?: number | string;
+  maxWidth?: number | string;
+  minHeight?: number | string;
+  maxHeight?: number | string;
+  maxDepth?: number;
+}
+
+export interface LayoutStateSpec {
+  scope?: LayoutStateScope;
+  key?: string;
+}
+
+export interface PermissionSpec {
+  require?: string[];
+  anyOf?: string[];
+}
+
+/* ------------------------------------------------------------------ *
+ * 4.4 SlotDefinition
+ * ------------------------------------------------------------------ */
+
+export interface SlotDefinition {
+  name: string;
+  role: SlotRole;
+
+  accepts: NodeAcceptSpec[];
+  cardinality?: { min?: number; max?: number | "unbounded" };
+
+  required?: boolean;
+  multiple?: boolean;
+
+  constraints?: SlotConstraints;
+  priority?: SlotPriority;
+  responsive?: SlotResponsivePolicy;
+
+  /** How this slot transforms the child component style context. */
+  contextTransform?: SlotContextTransform;
+  /** Empty/loading/error fallback. */
+  fallback?: SlotFallbackSpec;
+}
+
+export type NodeAcceptSpec =
+  | { kind: "component"; componentTypes?: string[]; componentTags?: string[] }
+  | {
+      kind: "layout";
+      layoutTypes?: string[];
+      tiers?: LayoutTier[];
+      surfaces?: SurfaceRole[];
+    }
+  | { kind: "template"; templateTypes?: string[] }
+  | { kind: "fragment" }
+  | { kind: "empty" };
+
+export interface SlotConstraints {
+  minWidth?: number | string;
+  maxWidth?: number | string;
+  minHeight?: number | string;
+}
+
+export interface SlotContextTransform {
+  surface?: SurfaceRole;
+  styleIntent?: Partial<LayoutStyleIntent>;
+  densityHint?: ComponentDensity;
+  typeScaleHint?: ComponentTypeScale;
+}
+
+export interface SlotFallbackSpec {
+  empty?: SlotContent;
+  loading?: SlotContent;
+  error?: SlotContent;
+}
+
+export interface SlotPriority {
+  value: number;
+  behaviorOnNarrow:
+    | "keep"
+    | "collapse"
+    | "move-to-drawer"
+    | "move-to-bottom-sheet"
+    | "hide"
+    | "route-stack"
+    | "tabs";
+}
+
+export interface SlotResponsivePolicy {
+  collapseBelow?: Breakpoint;
+  hideBelow?: Breakpoint;
+}
+
+/* ------------------------------------------------------------------ *
+ * 4.5 SlotContent
+ * ------------------------------------------------------------------ */
+
+export type SlotContent =
+  | ComponentSlotContent
+  | LayoutSlotContent
+  | TemplateSlotContent
+  | FragmentSlotContent
+  | EmptySlotContent;
+
+export interface ComponentSlotContent {
+  kind: "component";
+  component: string;
+  props?: Record<string, unknown>;
+  /** Discouraged long-term; special cases only. */
+  styleOverride?: Partial<ComponentStyleParams>;
+}
+
+export interface LayoutSlotContent {
+  kind: "layout";
+  layout: LayoutNode;
+}
+
+export interface TemplateSlotContent {
+  kind: "template";
+  template: string;
+  props?: Record<string, unknown>;
+}
+
+export interface FragmentSlotContent {
+  kind: "fragment";
+  items: SlotContent[];
+  composition?: CompositionSpec;
+}
+
+export interface EmptySlotContent {
+  kind: "empty";
+  reason?: "not-configured" | "no-data" | "permission-denied" | "loading" | "error";
+}
+
+/* ------------------------------------------------------------------ *
+ * 5. Container composition algebra
+ * ------------------------------------------------------------------ */
+
+export type CompositionSpec =
+  | ParallelComposition
+  | StackComposition
+  | EmbedComposition
+  | OverlayComposition
+  | SwitchComposition
+  | StepperComposition
+  | PortalComposition
+  | ConditionalComposition
+  | ResponsiveComposition;
+
+export interface ParallelSizing {
+  basis?: number | string;
+  min?: number | string;
+  max?: number | string;
+  grow?: number;
+  shrink?: number;
+  resizable?: boolean;
+  collapsible?: boolean;
+}
+
+export interface ParallelComposition {
+  op: "parallel";
+  axis: "x" | "y";
+  slots: string[];
+  sizing?: Record<string, ParallelSizing>;
+  gapToken?: string;
+  align?: "start" | "center" | "end" | "stretch";
+}
+
+export interface StackComposition {
+  op: "stack";
+  direction: "vertical" | "horizontal";
+  slots: string[];
+  gapToken?: string;
+  divider?: boolean;
+  sticky?: Partial<Record<string, "start" | "end">>;
+}
+
+export interface EmbedComposition {
+  op: "embed";
+  host: { layoutId: string; slot: string };
+  child: { nodeId: string };
+  adapter?: EmbedAdapter;
+}
+
+export interface EmbedAdapter {
+  surfaceDemotion?: { from: SurfaceRole; to: SurfaceRole };
+  inheritContext?: boolean;
+  isolateScroll?: boolean;
+  isolateState?: boolean;
+  densityAdjustment?: "inherit" | "compact-one-step" | "comfortable-one-step";
+}
+
+export interface OverlayComposition {
+  op: "overlay";
+  baseSlot: string;
+  overlays: Array<{
+    slot: string;
+    layer: "floating" | "popover" | "drawer" | "modal" | "toast";
+    anchor?: string;
+    placement?: "top" | "right" | "bottom" | "left" | "center";
+    dismissible?: boolean;
+    modal?: boolean;
+  }>;
+}
+
+export interface SwitchComposition {
+  op: "switch";
+  mode: "tabs" | "segmented" | "route-stack" | "accordion";
+  activeKey?: string;
+  items: Array<{
+    key: string;
+    label: string;
+    content: SlotContent;
+    lazy?: boolean;
+    keepMounted?: boolean;
+  }>;
+}
+
+export interface StepperComposition {
+  op: "stepper";
+  orientation: "horizontal" | "vertical";
+  stepSlot: string;
+  contentSlot: string;
+  steps: Array<{
+    id: string;
+    label: string;
+    optional?: boolean;
+    status?: "pending" | "active" | "valid" | "invalid" | "complete";
+    content: SlotContent;
+    validation?: string;
+  }>;
+  navigation?: {
+    allowSkip?: boolean;
+    allowBack?: boolean;
+    requireValidBeforeNext?: boolean;
+  };
+}
+
+export interface PortalComposition {
+  op: "portal";
+  slot: string;
+  target?: string;
+}
+
+export interface ConditionalComposition {
+  op: "conditional";
+  branches: Array<{ when: ConditionExpr; content: SlotContent }>;
+  fallback?: SlotContent;
+}
+
+export type ConditionExpr =
+  | { kind: "permission"; require: string[] }
+  | { kind: "featureFlag"; flag: string }
+  | { kind: "dataState"; state: "loading" | "error" | "empty" | "ready" }
+  | { kind: "viewport"; atLeast?: Breakpoint; atMost?: Breakpoint };
+
+export interface ResponsiveComposition {
+  op: "responsive";
+  rules: ResponsiveRule[];
+}
+
+export interface ResponsiveRule {
+  when: ResponsiveCondition;
+  transform: ResponsiveTransform;
+}
+
+export interface ResponsiveCondition {
+  breakpoint?: Breakpoint;
+  maxBreakpoint?: Breakpoint;
+  containerMaxWidth?: number;
+  pointer?: "coarse" | "fine";
+}
+
+export interface ResponsiveTransform {
+  mode?: PhysicalLayoutPlan["mode"];
+  collapse?: string[];
+  moveToDrawer?: string[];
+  hide?: string[];
+  stack?: boolean;
+}
+
+/* ------------------------------------------------------------------ *
+ * 6. Layout context
+ * ------------------------------------------------------------------ */
+
+export type Breakpoint =
+  | "mobile"
+  | "tablet"
+  | "laptop"
+  | "desktop"
+  | "wide"
+  | "ultra";
+
+export interface LayoutViewport {
+  breakpoint: Breakpoint;
+  width: number;
+  height: number;
+  pointer: "coarse" | "fine";
+  colorScheme: "light" | "dark";
+}
+
+export interface LayoutRuntimeContext {
+  path: string[];
+  depth: number;
+  ancestry: Array<{
+    id: string;
+    type: string;
+    tier?: LayoutTier;
+    surface?: SurfaceRole;
+    slotRole?: SlotRole;
+  }>;
+
+  viewport: LayoutViewport;
+  container: { width?: number; height?: number; queryName?: string };
+  route?: {
+    routeId?: string;
+    routePattern?: string;
+    workspaceId?: string;
+    entityType?: string;
+    entityId?: string;
+  };
+
+  slot?: {
+    name: string;
+    role: SlotRole;
+    priority?: number;
+    surface?: SurfaceRole;
+  };
+
+  surface: SurfaceRole;
+  taskMode?: LayoutTaskMode;
+  dataIntensity?: DataIntensity;
+  interactionMode?: InteractionMode;
+  visualEmphasis?: VisualEmphasis;
+
+  /** Final style params handed to components. */
+  componentStyle: ComponentStyleParams;
+  tokens: ResolvedLayoutTokens;
+  stateScope: LayoutStateScope;
+  permissions?: ResolvedPermissionContext;
+  telemetry?: Record<string, unknown>;
+}
+
+export interface ContextPolicy {
+  inheritStyle: boolean;
+  inheritDensity: boolean;
+  inheritTypeScale: boolean;
+  inheritSurface: boolean;
+  isolateState: boolean;
+  isolateScroll: boolean;
+  allowComponentOverride: boolean;
+  maxDepth: number;
+}
+
+export interface ResolvedPermissionContext {
+  granted: Set<string>;
+}
+
+/* ------------------------------------------------------------------ *
+ * 7.1 Style inference input
+ * ------------------------------------------------------------------ */
+
+export interface StyleInferenceInput {
+  parent?: ComponentStyleParams;
+  explicit?: Partial<ComponentStyleParams>;
+  layoutType: string;
+  layoutTier?: LayoutTier;
+  layoutVariant?: string;
+  surface: SurfaceRole;
+  slotRole?: SlotRole;
+  taskMode?: LayoutTaskMode;
+  dataIntensity?: DataIntensity;
+  interactionMode?: InteractionMode;
+  visualEmphasis?: VisualEmphasis;
+  depth: number;
+  breakpoint: Breakpoint;
+  containerWidth?: number;
+  userPreference?: Partial<ComponentStyleParams>;
+  productDefault?: Partial<ComponentStyleParams>;
+}
+
+/* ------------------------------------------------------------------ *
+ * 13. Tokens
+ * ------------------------------------------------------------------ */
+
+export interface PresetTokenSet {
+  surface: string;
+  surfaceMuted: string;
+  border: string;
+  text: string;
+  textMuted: string;
+  accent: string;
+  radius: string;
+  shadow: string;
+  backdrop?: string;
+}
+
+export type StylePresetTokenMap = Record<ComponentStylePreset, PresetTokenSet>;
+
+export interface ResolvedLayoutTokens extends PresetTokenSet {
+  gap: string;
+}
+
+/* ------------------------------------------------------------------ *
+ * 10. Physical layout plan
+ * ------------------------------------------------------------------ */
+
+export interface PhysicalLayoutPlan {
+  layoutId: string;
+  mode:
+    | "multi-pane"
+    | "single-pane"
+    | "drawer-assisted"
+    | "sheet-assisted"
+    | "route-stack";
+  regions: PhysicalRegion[];
+}
+
+export interface PhysicalRegion {
+  slot: string;
+  placement:
+    | "inline-start"
+    | "inline-end"
+    | "block-start"
+    | "block-end"
+    | "center"
+    | "overlay";
+  visible: boolean;
+  collapsed?: boolean;
+  mounted?: boolean;
+  layer?: SurfaceRole;
+  size?: { width?: number | string; height?: number | string };
+}
+
+/* ------------------------------------------------------------------ *
+ * 11. State persistence
+ * ------------------------------------------------------------------ */
+
+export type LayoutStateScope =
+  | "global"
+  | "workspace"
+  | "project"
+  | "route"
+  | "user"
+  | "session";
+
+export interface PersistedLayoutState {
+  schemaVersion: 2;
+  layoutId: string;
+  userId?: string;
+  workspaceId?: string;
+  projectId?: string;
+  routePattern?: string;
+  panels: Record<
+    string,
+    {
+      width?: number;
+      height?: number;
+      collapsed?: boolean;
+      pinned?: boolean;
+      activeTab?: string;
+      splitRatio?: number;
+    }
+  >;
+  stylePreference?: Partial<ComponentStyleParams>;
+  updatedAt: string;
+}
+
+/* ------------------------------------------------------------------ *
+ * 16. Validation diagnostics
+ * ------------------------------------------------------------------ */
+
+export type LayoutDiagnosticCode =
+  | "UNKNOWN_LAYOUT_TYPE"
+  | "UNKNOWN_SLOT"
+  | "SLOT_REQUIRED"
+  | "SLOT_CARDINALITY_VIOLATION"
+  | "SLOT_ACCEPTS_VIOLATION"
+  | "SURFACE_INCOMPATIBLE"
+  | "CYCLE_DETECTED"
+  | "MAX_DEPTH_EXCEEDED"
+  | "RESPONSIVE_FALLBACK_MISSING"
+  | "A11Y_SEMANTICS_MISSING"
+  | "STYLE_OVERRIDE_REJECTED";
+
+export interface LayoutDiagnostic {
+  level: "error" | "warning" | "info";
+  code: LayoutDiagnosticCode;
+  path: string[];
+  message: string;
+  suggestion?: string;
+}
+
+/* ------------------------------------------------------------------ *
+ * 9. Registry item
+ * ------------------------------------------------------------------ */
+
+export interface LayoutVariant {
+  id: string;
+  label?: string;
+  description?: string;
+}
+
+export interface LayoutAcceptRule {
+  layoutTypes?: string[];
+  tiers?: LayoutTier[];
+  surfaces?: SurfaceRole[];
+}
+
+export type LayoutCategory =
+  | "app-shell"
+  | "page"
+  | "workspace"
+  | "region"
+  | "primitive";
+
+/**
+ * Props handed to a registry item's `renderer`. The engine has already resolved
+ * each slot's `SlotContent` into a React node (wrapped in the child context),
+ * so renderers just arrange the pre-rendered `slots` map into boxes.
+ */
+export interface LayoutRendererProps {
+  node: LayoutNode;
+  variant?: string;
+  props?: Record<string, unknown>;
+  /** Pre-rendered slot content, keyed by slot name. */
+  slots: Record<string, import("react").ReactNode>;
+  /** This node's own runtime context (parent of the slots' contexts). */
+  context: LayoutRuntimeContext;
+  composition?: CompositionSpec;
+  /** Physical plan for this node (placement/visibility per slot). */
+  plan: PhysicalLayoutPlan;
+}
+
+export interface LayoutRegistryItem {
+  type: string;
+  displayName: string;
+  tier: LayoutTier;
+  category: LayoutCategory;
+  description: string;
+  slots: SlotDefinition[];
+  variants?: LayoutVariant[];
+  defaultProps?: Record<string, unknown>;
+  defaultComposition?: CompositionSpec;
+  defaultStyleIntent?: Partial<LayoutStyleIntent>;
+  contextPolicy?: Partial<ContextPolicy>;
+  allowedParents?: LayoutAcceptRule[];
+  allowedChildren?: LayoutAcceptRule[];
+  /** The React renderer for this layout type. */
+  renderer: import("react").ComponentType<LayoutRendererProps>;
+}