@pwfabric/runtime 0.0.0-stage → 1.0.0-rc.1

package/dist/blocks/component-types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Block Component Types
+ *
+ * Minimal type definitions for block React components.
+ * These types are structurally compatible with @pwfabric/runtime's
+ * BlockComponent and BlockComponentRegistry types.
+ *
+ * @module @pwfabric/runtime/blocks/component-types
+ */
+import type { ReactNode } from 'react';
+import type { Block } from '@pwfabric/contracts';
+import type { BreakpointName } from '@pwfabric/core';
+/**
+ * Surface event types emitted by block components
+ */
+export type BlockSurfaceEventType = 'click' | 'submit' | 'change' | 'navigate' | 'custom';
+/**
+ * Surface event emitted by block components
+ */
+export interface BlockSurfaceEvent {
+    /** Event type */
+    readonly type: BlockSurfaceEventType;
+    /** Block ID that triggered the event */
+    readonly blockId: string;
+    /** Event payload */
+    readonly payload?: unknown;
+    /** Original DOM event (if applicable) */
+    readonly originalEvent?: Event;
+}
+/**
+ * Minimal block rendering context available to block components.
+ * Structurally compatible with @pwfabric/runtime's BlockContext.
+ */
+export interface BlockComponentContext {
+    /** Event handler for block events */
+    readonly onEvent?: ((event: BlockSurfaceEvent) => void) | undefined;
+    /** Current viewport breakpoint */
+    readonly viewport?: BreakpointName;
+    /** Image adapter (optional, runtime-provided) */
+    readonly imageAdapter?: unknown;
+    /** Capabilities (optional, runtime-provided) */
+    readonly capabilities?: Map<string, unknown>;
+}
+/**
+ * Props passed to block components
+ */
+export interface BlockComponentProps<T = Record<string, unknown>> {
+    /** Block instance */
+    readonly block: Block;
+    /** Resolved props (validated and defaulted) */
+    readonly props: T;
+    /** Rendered children (for container blocks) */
+    readonly children?: ReactNode;
+    /** Block context */
+    readonly context: BlockComponentContext;
+}
+/**
+ * Block component type
+ */
+export type BlockComponent<T = Record<string, unknown>> = ((props: BlockComponentProps<T>) => ReactNode) & {
+    /**
+     * How the block wants to be sized when it sits in a flex ROW.
+     *
+     * The engine's default for a row child is an equal share (`flex: 1 1 0`) —
+     * right for two content columns, wrong for an avatar, a badge, a button: an
+     * intrinsic thing stretched to half a row is the single most measured layout
+     * defect of the 2026-09 surface audit (127 hand-written `flex: 0 0 auto`
+     * overrides across 14 receipts). A block whose natural width is its content
+     * declares `sizing: 'intrinsic'` — as a static on the component, the same
+     * way `displayName` travels — and the engine gives it `flex: 0 0 auto`.
+     * An authored flex hint on the instance still wins. The engine memorises no
+     * block names: the block declares, the engine obeys.
+     */
+    sizing?: BlockSizing;
+};
+/** The only sizing word the engine knows besides its default (fluid share). */
+export type BlockSizing = 'intrinsic';
+/**
+ * Block component registry — maps block type strings to React component implementations
+ */
+export type BlockComponentRegistry = Record<string, BlockComponent>;

package/dist/blocks/component-types.js

@@ -0,0 +1,11 @@
+/**
+ * Block Component Types
+ *
+ * Minimal type definitions for block React components.
+ * These types are structurally compatible with @pwfabric/runtime's
+ * BlockComponent and BlockComponentRegistry types.
+ *
+ * @module @pwfabric/runtime/blocks/component-types
+ */
+export {};
+//# sourceMappingURL=component-types.js.map

package/dist/blocks/component-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-types.js","sourceRoot":"","sources":["../../src/blocks/component-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * Block Component Types\n *\n * Minimal type definitions for block React components.\n * These types are structurally compatible with @pwfabric/runtime's\n * BlockComponent and BlockComponentRegistry types.\n *\n * @module @pwfabric/runtime/blocks/component-types\n */\n\nimport type { ReactNode } from 'react'\nimport type { Block } from '@pwfabric/contracts'\nimport type { BreakpointName } from '@pwfabric/core'\n\n// ============================================================\n// SURFACE EVENTS (minimal subset used by block components)\n// ============================================================\n\n/**\n * Surface event types emitted by block components\n */\nexport type BlockSurfaceEventType = 'click' | 'submit' | 'change' | 'navigate' | 'custom'\n\n/**\n * Surface event emitted by block components\n */\nexport interface BlockSurfaceEvent {\n  /** Event type */\n  readonly type: BlockSurfaceEventType\n  /** Block ID that triggered the event */\n  readonly blockId: string\n  /** Event payload */\n  readonly payload?: unknown\n  /** Original DOM event (if applicable) */\n  readonly originalEvent?: Event\n}\n\n// ============================================================\n// BLOCK CONTEXT (minimal subset needed by block components)\n// ============================================================\n\n/**\n * Minimal block rendering context available to block components.\n * Structurally compatible with @pwfabric/runtime's BlockContext.\n */\nexport interface BlockComponentContext {\n  /** Event handler for block events */\n  readonly onEvent?: ((event: BlockSurfaceEvent) => void) | undefined\n  /** Current viewport breakpoint */\n  readonly viewport?: BreakpointName\n  /** Image adapter (optional, runtime-provided) */\n  readonly imageAdapter?: unknown\n  /** Capabilities (optional, runtime-provided) */\n  readonly capabilities?: Map<string, unknown>\n}\n\n// ============================================================\n// BLOCK COMPONENT TYPES\n// ============================================================\n\n/**\n * Props passed to block components\n */\nexport interface BlockComponentProps<T = Record<string, unknown>> {\n  /** Block instance */\n  readonly block: Block\n  /** Resolved props (validated and defaulted) */\n  readonly props: T\n  /** Rendered children (for container blocks) */\n  readonly children?: ReactNode\n  /** Block context */\n  readonly context: BlockComponentContext\n}\n\n/**\n * Block component type\n */\nexport type BlockComponent<T = Record<string, unknown>> = ((\n  props: BlockComponentProps<T>\n) => ReactNode) & {\n  /**\n   * How the block wants to be sized when it sits in a flex ROW.\n   *\n   * The engine's default for a row child is an equal share (`flex: 1 1 0`) —\n   * right for two content columns, wrong for an avatar, a badge, a button: an\n   * intrinsic thing stretched to half a row is the single most measured layout\n   * defect of the 2026-09 surface audit (127 hand-written `flex: 0 0 auto`\n   * overrides across 14 receipts). A block whose natural width is its content\n   * declares `sizing: 'intrinsic'` — as a static on the component, the same\n   * way `displayName` travels — and the engine gives it `flex: 0 0 auto`.\n   * An authored flex hint on the instance still wins. The engine memorises no\n   * block names: the block declares, the engine obeys.\n   */\n  sizing?: BlockSizing\n}\n\n/** The only sizing word the engine knows besides its default (fluid share). */\nexport type BlockSizing = 'intrinsic'\n\n/**\n * Block component registry — maps block type strings to React component implementations\n */\nexport type BlockComponentRegistry = Record<string, BlockComponent>\n"]}

package/dist/blocks/composition-rules.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Composition Rules
+ *
+ * CP7: Rules defining valid block compositions
+ *
+ * @module @pwfabric/core/blocks/composition-rules
+ */
+import type { CompositionRule } from '@pwfabric/core';
+/**
+ * Maximum nesting depth rule
+ *
+ * Prevents blocks from being nested too deeply.
+ */
+export declare const maxDepthRule: CompositionRule;
+/**
+ * Form children rule
+ *
+ * Forms can contain all form input elements plus structural/content blocks.
+ */
+export declare const formChildrenRule: CompositionRule;
+/**
+ * Grid children rule
+ *
+ * Grids cannot have nested grids as direct children.
+ */
+export declare const gridChildrenRule: CompositionRule;
+/**
+ * Button no children rule
+ *
+ * Buttons cannot have children.
+ */
+export declare const buttonNoChildrenRule: CompositionRule;
+/**
+ * Text no children rule
+ *
+ * Text blocks cannot have children.
+ */
+export declare const textNoChildrenRule: CompositionRule;
+/**
+ * Heading no children rule
+ *
+ * Heading blocks cannot have children.
+ */
+export declare const headingNoChildrenRule: CompositionRule;
+/**
+ * Image no children rule
+ *
+ * Image blocks cannot have children.
+ */
+export declare const imageNoChildrenRule: CompositionRule;
+/**
+ * Input no children rule
+ *
+ * Input blocks cannot have children.
+ */
+export declare const inputNoChildrenRule: CompositionRule;
+/**
+ * Input required parent rule
+ *
+ * Inputs should be inside forms or containers.
+ */
+export declare const inputParentRule: CompositionRule;
+/**
+ * Link no children rule
+ *
+ * Link blocks cannot have children.
+ */
+export declare const linkNoChildrenRule: CompositionRule;
+/**
+ * Icon no children rule
+ *
+ * Icon blocks cannot have children.
+ */
+export declare const iconNoChildrenRule: CompositionRule;
+/**
+ * Badge no children rule
+ *
+ * Badge blocks cannot have children.
+ */
+export declare const badgeNoChildrenRule: CompositionRule;
+/**
+ * Code no children rule
+ *
+ * Code blocks cannot have children.
+ */
+export declare const codeNoChildrenRule: CompositionRule;
+/**
+ * Divider no children rule
+ *
+ * Divider blocks cannot have children.
+ */
+export declare const dividerNoChildrenRule: CompositionRule;
+/**
+ * List no children rule
+ *
+ * List blocks cannot have children.
+ */
+export declare const listNoChildrenRule: CompositionRule;
+/**
+ * Table no children rule
+ *
+ * Table blocks cannot have children.
+ */
+export declare const tableNoChildrenRule: CompositionRule;
+/**
+ * Accordion no children rule
+ *
+ * Accordion items are defined via props, not children.
+ */
+export declare const accordionNoChildrenRule: CompositionRule;
+/**
+ * Dropdown no children rule
+ *
+ * Dropdown items are defined via props, not children.
+ */
+export declare const dropdownNoChildrenRule: CompositionRule;
+/**
+ * Avatar no children rule
+ *
+ * Avatar is a leaf block with no children.
+ */
+export declare const avatarNoChildrenRule: CompositionRule;
+/**
+ * Tooltip children rule
+ *
+ * Tooltip can wrap specific inline/interactive blocks.
+ */
+export declare const tooltipChildrenRule: CompositionRule;
+/**
+ * Tabs children rule
+ *
+ * Tabs can contain containers as tab panels.
+ */
+export declare const tabsChildrenRule: CompositionRule;
+/**
+ * Modal children rule
+ *
+ * Modal can contain layout and content blocks.
+ */
+export declare const modalChildrenRule: CompositionRule;
+/**
+ * No self nesting rule
+ *
+ * Blocks cannot be nested inside themselves.
+ */
+export declare const noSelfNestingRule: CompositionRule;
+/**
+ * All composition rules
+ */
+export declare const compositionRules: readonly CompositionRule[];
+/**
+ * Get rules that apply to a specific block type
+ *
+ * @param blockType - Block type to get rules for
+ * @returns Array of applicable rules
+ */
+export declare function getRulesForBlockType(blockType: string): readonly CompositionRule[];
+/**
+ * Get rules by type
+ *
+ * @param ruleType - Rule type to filter by
+ * @returns Array of matching rules
+ */
+export declare function getRulesByType(ruleType: CompositionRule['type']): readonly CompositionRule[];
+/** Allowed direct children of a tabs block */
+export declare const TABS_ALLOWED_CHILDREN: Set<string>;
+/** Allowed direct children of a form block */
+export declare const FORM_ALLOWED_CHILDREN: Set<string>;

package/dist/blocks/composition-rules.js

@@ -0,0 +1,391 @@
+/**
+ * Composition Rules
+ *
+ * CP7: Rules defining valid block compositions
+ *
+ * @module @pwfabric/core/blocks/composition-rules
+ */
+import { MAX_NESTING_DEPTH } from '@pwfabric/core';
+// ============================================================
+// BUILT-IN RULES
+// ============================================================
+/**
+ * Maximum nesting depth rule
+ *
+ * Prevents blocks from being nested too deeply.
+ */
+export const maxDepthRule = {
+    type: 'max_depth',
+    description: `Blocks cannot be nested more than ${MAX_NESTING_DEPTH} levels deep`,
+    appliesTo: '*',
+    config: {
+        maxDepth: MAX_NESTING_DEPTH,
+    },
+};
+/**
+ * Form children rule
+ *
+ * Forms can contain all form input elements plus structural/content blocks.
+ */
+export const formChildrenRule = {
+    type: 'allowed_children',
+    description: 'Forms can contain form input elements and structural/content blocks (text, heading, container, divider, button)',
+    appliesTo: 'form',
+    config: {
+        allowedChildren: [
+            // Form input elements — the form family of the first-party base pack as
+            // shipped, so every field a form pattern uses passes validation.
+            'input',
+            'textarea',
+            'select',
+            'checkbox',
+            'radio',
+            'toggle',
+            'slider',
+            'combobox',
+            'date-input',
+            'file-dropzone',
+            'number-stepper',
+            'otp-input',
+            'rich-text-editor',
+            'segmented-control',
+            'tag-input',
+            // legacy names kept so older documents keep validating
+            'switch',
+            'file-upload',
+            // Structural / content blocks valid inside forms
+            'button',
+            'text',
+            'heading',
+            'container',
+            'divider',
+            'badge',
+            'icon',
+            'link',
+            'alert',
+        ],
+    },
+};
+/**
+ * Grid children rule
+ *
+ * Grids cannot have nested grids as direct children.
+ */
+export const gridChildrenRule = {
+    type: 'allowed_children',
+    description: 'Grids cannot contain other grids as direct children',
+    appliesTo: 'grid',
+    config: {
+        disallowedChildren: ['grid'],
+    },
+};
+/**
+ * Button no children rule
+ *
+ * Buttons cannot have children.
+ */
+export const buttonNoChildrenRule = {
+    type: 'no_children',
+    description: 'Buttons cannot have children',
+    appliesTo: 'button',
+    config: {},
+};
+/**
+ * Text no children rule
+ *
+ * Text blocks cannot have children.
+ */
+export const textNoChildrenRule = {
+    type: 'no_children',
+    description: 'Text blocks cannot have children',
+    appliesTo: 'text',
+    config: {},
+};
+/**
+ * Heading no children rule
+ *
+ * Heading blocks cannot have children.
+ */
+export const headingNoChildrenRule = {
+    type: 'no_children',
+    description: 'Heading blocks cannot have children',
+    appliesTo: 'heading',
+    config: {},
+};
+/**
+ * Image no children rule
+ *
+ * Image blocks cannot have children.
+ */
+export const imageNoChildrenRule = {
+    type: 'no_children',
+    description: 'Image blocks cannot have children',
+    appliesTo: 'image',
+    config: {},
+};
+/**
+ * Input no children rule
+ *
+ * Input blocks cannot have children.
+ */
+export const inputNoChildrenRule = {
+    type: 'no_children',
+    description: 'Input blocks cannot have children',
+    appliesTo: 'input',
+    config: {},
+};
+/**
+ * Input required parent rule
+ *
+ * Inputs should be inside forms or containers.
+ */
+export const inputParentRule = {
+    type: 'allowed_parents',
+    description: 'Inputs should be placed inside forms or containers',
+    appliesTo: 'input',
+    config: {
+        allowedParents: ['form', 'container'],
+        severity: 'warning',
+    },
+};
+/**
+ * Link no children rule
+ *
+ * Link blocks cannot have children.
+ */
+export const linkNoChildrenRule = {
+    type: 'no_children',
+    description: 'Link blocks cannot have children',
+    appliesTo: 'link',
+    config: {},
+};
+/**
+ * Icon no children rule
+ *
+ * Icon blocks cannot have children.
+ */
+export const iconNoChildrenRule = {
+    type: 'no_children',
+    description: 'Icon blocks cannot have children',
+    appliesTo: 'icon',
+    config: {},
+};
+/**
+ * Badge no children rule
+ *
+ * Badge blocks cannot have children.
+ */
+export const badgeNoChildrenRule = {
+    type: 'no_children',
+    description: 'Badge blocks cannot have children',
+    appliesTo: 'badge',
+    config: {},
+};
+/**
+ * Code no children rule
+ *
+ * Code blocks cannot have children.
+ */
+export const codeNoChildrenRule = {
+    type: 'no_children',
+    description: 'Code blocks cannot have children',
+    appliesTo: 'code',
+    config: {},
+};
+/**
+ * Divider no children rule
+ *
+ * Divider blocks cannot have children.
+ */
+export const dividerNoChildrenRule = {
+    type: 'no_children',
+    description: 'Divider blocks cannot have children',
+    appliesTo: 'divider',
+    config: {},
+};
+/**
+ * List no children rule
+ *
+ * List blocks cannot have children.
+ */
+export const listNoChildrenRule = {
+    type: 'no_children',
+    description: 'List blocks cannot have children',
+    appliesTo: 'list',
+    config: {},
+};
+/**
+ * Table no children rule
+ *
+ * Table blocks cannot have children.
+ */
+export const tableNoChildrenRule = {
+    type: 'no_children',
+    description: 'Table blocks cannot have children',
+    appliesTo: 'table',
+    config: {},
+};
+// ============================================================
+// INTERACTIVE BLOCK RULES
+// ============================================================
+/**
+ * Accordion no children rule
+ *
+ * Accordion items are defined via props, not children.
+ */
+export const accordionNoChildrenRule = {
+    type: 'no_children',
+    description: 'Accordion items are defined via props, not as children blocks',
+    appliesTo: 'accordion',
+    config: {},
+};
+/**
+ * Dropdown no children rule
+ *
+ * Dropdown items are defined via props, not children.
+ */
+export const dropdownNoChildrenRule = {
+    type: 'no_children',
+    description: 'Dropdown items are defined via props, not as children blocks',
+    appliesTo: 'dropdown',
+    config: {},
+};
+/**
+ * Avatar no children rule
+ *
+ * Avatar is a leaf block with no children.
+ */
+export const avatarNoChildrenRule = {
+    type: 'no_children',
+    description: 'Avatar blocks cannot have children',
+    appliesTo: 'avatar',
+    config: {},
+};
+/**
+ * Tooltip children rule
+ *
+ * Tooltip can wrap specific inline/interactive blocks.
+ */
+export const tooltipChildrenRule = {
+    type: 'allowed_children',
+    description: 'Tooltips can only wrap text, buttons, icons, badges, and links',
+    appliesTo: 'tooltip',
+    config: {
+        allowedChildren: ['text', 'button', 'icon', 'badge', 'link'],
+    },
+};
+/**
+ * Tabs children rule
+ *
+ * Tabs can contain containers as tab panels.
+ */
+export const tabsChildrenRule = {
+    type: 'allowed_children',
+    description: 'Tabs can only contain containers as tab panel content',
+    appliesTo: 'tabs',
+    config: {
+        allowedChildren: ['container'],
+    },
+};
+/**
+ * Modal children rule
+ *
+ * Modal can contain layout and content blocks.
+ */
+export const modalChildrenRule = {
+    type: 'allowed_children',
+    description: 'Modals can contain layout and content blocks',
+    appliesTo: 'modal',
+    config: {
+        allowedChildren: [
+            'container',
+            'grid',
+            'text',
+            'heading',
+            'button',
+            'image',
+            'form',
+            'input',
+            'list',
+            'table',
+            'divider',
+            'icon',
+            'badge',
+        ],
+    },
+};
+/**
+ * No self nesting rule
+ *
+ * Blocks cannot be nested inside themselves.
+ */
+export const noSelfNestingRule = {
+    type: 'no_self_nesting',
+    description: 'Blocks cannot be nested inside themselves',
+    appliesTo: '*',
+    config: {},
+};
+// ============================================================
+// ALL RULES
+// ============================================================
+/**
+ * All composition rules
+ */
+export const compositionRules = [
+    maxDepthRule,
+    formChildrenRule,
+    gridChildrenRule,
+    // Content blocks - no children
+    buttonNoChildrenRule,
+    textNoChildrenRule,
+    headingNoChildrenRule,
+    linkNoChildrenRule,
+    iconNoChildrenRule,
+    badgeNoChildrenRule,
+    codeNoChildrenRule,
+    dividerNoChildrenRule,
+    // Layout blocks - no children (leaf)
+    listNoChildrenRule,
+    tableNoChildrenRule,
+    // Media blocks - no children
+    imageNoChildrenRule,
+    // Form blocks - no children
+    inputNoChildrenRule,
+    inputParentRule,
+    // Interactive blocks
+    accordionNoChildrenRule,
+    dropdownNoChildrenRule,
+    avatarNoChildrenRule,
+    tooltipChildrenRule,
+    tabsChildrenRule,
+    modalChildrenRule,
+    // Universal rules
+    noSelfNestingRule,
+];
+/**
+ * Get rules that apply to a specific block type
+ *
+ * @param blockType - Block type to get rules for
+ * @returns Array of applicable rules
+ */
+export function getRulesForBlockType(blockType) {
+    return compositionRules.filter((rule) => rule.appliesTo === '*' || rule.appliesTo === blockType);
+}
+/**
+ * Get rules by type
+ *
+ * @param ruleType - Rule type to filter by
+ * @returns Array of matching rules
+ */
+export function getRulesByType(ruleType) {
+    return compositionRules.filter((rule) => rule.type === ruleType);
+}
+// ============================================================
+// CANONICAL CHILD SETS (single source of truth)
+// Import these in API validator instead of redeclaring.
+// ============================================================
+/** Allowed direct children of a tabs block */
+export const TABS_ALLOWED_CHILDREN = new Set(tabsChildrenRule.config.allowedChildren);
+/** Allowed direct children of a form block */
+export const FORM_ALLOWED_CHILDREN = new Set(formChildrenRule.config.allowedChildren);
+//# sourceMappingURL=composition-rules.js.map