@farm.js/react 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/compiler-runtime.d.mts

@@ -1,12 +1,15 @@
 import React from 'react';
 
 type CompilerStateUpdater = unknown | ((previous: unknown) => unknown);
+type CompilerRuntimeReactivity = "static" | "hybrid";
 interface CompilerCell {
     get(): unknown;
     set(next: CompilerStateUpdater): void;
 }
 interface CompilerTextBinding<Props> {
     kind: "text";
+    /** Runtime tracking is useful only for compiler-proven short-circuiting readers. */
+    tracking?: "dynamic";
     path: readonly number[];
     /** Stable ref target emitted by newer compiler versions. */
     target?: number;
@@ -15,6 +18,8 @@ interface CompilerTextBinding<Props> {
 }
 interface CompilerAttributeBinding<Props> {
     kind: "attribute";
+    /** Runtime tracking is useful only for compiler-proven short-circuiting readers. */
+    tracking?: "dynamic";
     path: readonly number[];
     /** Stable ref target emitted by newer compiler versions. */
     target?: number;
@@ -24,6 +29,8 @@ interface CompilerAttributeBinding<Props> {
 }
 interface CompilerStyleBinding<Props> {
     kind: "style";
+    /** Runtime tracking is useful only for compiler-proven short-circuiting readers. */
+    tracking?: "dynamic";
     path: readonly number[];
     /** Stable ref target emitted by newer compiler versions. */
     target?: number;
@@ -58,10 +65,14 @@ interface CompilerHostElement {
         value: unknown;
     }[];
     children: readonly (CompilerHostElement | unknown)[];
+    /** Direct-child structure owned without creating another React fiber. */
+    block?: CompilerHostBlock;
 }
 type CompilerKeyedRowElement = CompilerHostElement;
 interface CompilerKeyedRowEvent {
     name: string;
+    /** Host-element path relative to the keyed row root. */
+    path?: readonly number[];
     invoke(item: unknown, index: number, event: React.SyntheticEvent): unknown;
 }
 interface CompilerKeyedRowConditionalBranch {
@@ -82,10 +93,45 @@ interface CompilerHostConditionalBinding {
     name?: string;
     read(): unknown;
 }
+interface CompilerStaticRangeBinding {
+    kind: "text" | "attribute" | "style";
+    /** Static segment before range N, or the trailing segment at ranges.length. */
+    segment: number;
+    /** Direct host sibling inside that static segment. */
+    sibling: number;
+    /** Host-element path relative to the selected static sibling. */
+    path: readonly number[];
+    name?: string;
+    read(): unknown;
+}
 interface CompilerHostConditionalBranch {
     create(): CompilerHostElement;
     bindings: readonly CompilerHostConditionalBinding[];
 }
+interface CompilerHostConditionalRanges {
+    kind: "conditional-ranges";
+    id: number;
+    ranges: readonly CompilerConditionalRange[];
+    trailing: number;
+    bindings?: readonly CompilerStaticRangeBinding[];
+}
+interface CompilerHostKeyedRanges {
+    kind: "keyed-ranges";
+    id: number;
+    ranges: readonly CompilerKeyedRange[];
+    trailing: number;
+    bindings?: readonly CompilerStaticRangeBinding[];
+    /** Compiler output may store only static direct children and materialize rows from the ranges. */
+    staticChildrenOnly?: boolean;
+}
+interface CompilerHostMixedRanges {
+    kind: "mixed-ranges";
+    id: number;
+    ranges: readonly CompilerMixedRange[];
+    trailing: number;
+    bindings?: readonly CompilerStaticRangeBinding[];
+}
+type CompilerHostBlock = CompilerHostConditionalRanges | CompilerHostKeyedRanges | CompilerHostMixedRanges;
 interface CompilerHostConditionalBlockProps {
     id: number;
     render(): React.ReactElement;
@@ -95,21 +141,47 @@ interface CompilerHostConditionalBlockProps {
     truthy?: CompilerHostConditionalBranch;
     falsy?: CompilerHostConditionalBranch;
 }
+interface CompilerConditionalRange {
+    /** Number of static direct host siblings between this slot and the previous slot. */
+    before: number;
+    test(): unknown;
+    /** Logical && can produce a visible number instead of an empty branch. */
+    logical?: boolean;
+    truthy?: CompilerHostConditionalBranch;
+    falsy?: CompilerHostConditionalBranch;
+}
+interface CompilerConditionalRangesBlockProps {
+    id: number;
+    render(): React.ReactElement;
+    rootRef?: React.RefCallback<Element>;
+    ranges: readonly CompilerConditionalRange[];
+    /** Number of static direct host siblings after the final conditional slot. */
+    trailing: number;
+    bindings?: readonly CompilerStaticRangeBinding[];
+}
 interface CompilerKeyedRowBinding {
     kind: "text" | "attribute" | "style";
     path: readonly number[];
     name?: string;
+    /** Component state cells read by this binding, when emitted by the compiler. */
+    dependencies?: readonly number[];
     read(item: unknown, index: number): unknown;
 }
 interface CompilerKeyedRowsBlockProps {
     id: number;
     render(event: (item: unknown, index: number, eventId: number) => React.EventHandler<React.SyntheticEvent>, conditional: (item: unknown, index: number, conditionalId: number, render: (item: unknown, index: number) => React.ReactNode) => React.ReactNode): React.ReactElement;
     items(): Iterable<unknown> | null | undefined;
+    /** State cells that can change the row collection or its key projection. */
+    structureDependencies?: readonly number[];
     rowKey(item: unknown, index: number): React.Key;
     create(item: unknown, index: number): CompilerKeyedRowElement;
     bindings: readonly CompilerKeyedRowBinding[];
     events?: readonly CompilerKeyedRowEvent[];
+    /** Route compiler-proven bubbling row events through the stable React container. */
+    delegateEvents?: boolean;
     conditionals?: readonly CompilerKeyedRowConditional[];
+    /** Row descriptors contain compiler-owned nested host scopes. */
+    hostBlocks?: boolean;
 }
 interface CompilerKeyedRange {
     /** Number of static direct host siblings between this range and the previous range. */
@@ -119,6 +191,17 @@ interface CompilerKeyedRange {
     create(item: unknown, index: number): CompilerKeyedRowElement;
     bindings: readonly CompilerKeyedRowBinding[];
 }
+type CompilerMixedRange = ({
+    kind: "conditional";
+} & CompilerConditionalRange) | ({
+    kind: "keyed";
+} & CompilerKeyedRange);
+interface CompilerMixedRangesBlockProps {
+    id: number;
+    render(): React.ReactElement;
+    create(): CompilerHostElement;
+    rootRef?: React.RefCallback<Element>;
+}
 interface CompilerKeyedRangesBlockProps {
     id: number;
     render(): React.ReactElement;
@@ -126,6 +209,7 @@ interface CompilerKeyedRangesBlockProps {
     ranges: readonly CompilerKeyedRange[];
     /** Number of static direct host siblings after the final keyed range. */
     trailing: number;
+    bindings?: readonly CompilerStaticRangeBinding[];
 }
 interface CompilerComponentBlockProps {
     id: number;
@@ -134,20 +218,29 @@ interface CompilerComponentBlockProps {
 interface CompilerBlockRuntime {
     Conditional: React.ComponentType<CompilerConditionalBlockProps>;
     HostConditional: React.ComponentType<CompilerHostConditionalBlockProps>;
+    ConditionalRanges: React.ComponentType<CompilerConditionalRangesBlockProps>;
     KeyedList: React.ComponentType<CompilerKeyedListBlockProps>;
     KeyedRows: React.ComponentType<CompilerKeyedRowsBlockProps>;
     KeyedRanges: React.ComponentType<CompilerKeyedRangesBlockProps>;
+    MixedRanges: React.ComponentType<CompilerMixedRangesBlockProps>;
     Component: React.ComponentType<CompilerComponentBlockProps>;
     target(id: number): React.RefCallback<Element>;
 }
 type CompilerBinding<Props> = CompilerTextBinding<Props> | CompilerAttributeBinding<Props> | CompilerStyleBinding<Props> | CompilerConditionalBlockBinding;
 interface CompiledComponentDefinition<Props> {
     displayName: string;
+    /** Scheduler selected by the compiler. Hand-authored definitions default to `static`. */
+    reactivity?: CompilerRuntimeReactivity;
     /** Stable development-only identity used to preserve state across compatible refreshes. */
     hmrId?: string;
     /** Changes when the compiler-owned state layout is no longer refresh-compatible. */
     stateSignature?: string;
     initialize(props: Props): readonly unknown[];
+    /**
+     * Compiler-emitted flat prop reads. Primitive values can share the local
+     * dependency graph; identity-bearing values retain normal React rendering.
+     */
+    readProps?(props: Props): readonly unknown[];
     render(props: Props, state: readonly CompilerCell[], blocks: CompilerBlockRuntime): React.ReactElement;
     bindings: readonly CompilerBinding<Props>[];
 }
@@ -160,4 +253,4 @@ interface CompiledComponentDefinition<Props> {
  */
 declare function createCompiledComponent<Props>(definition: CompiledComponentDefinition<Props>): React.ComponentType<Props>;
 
-export { type CompiledComponentDefinition, type CompilerAttributeBinding, type CompilerBinding, type CompilerBlockRuntime, type CompilerCell, type CompilerComponentBlockProps, type CompilerConditionalBlockBinding, type CompilerConditionalBlockProps, type CompilerHostConditionalBinding, type CompilerHostConditionalBlockProps, type CompilerHostConditionalBranch, type CompilerHostElement, type CompilerKeyedListBlockProps, type CompilerKeyedRange, type CompilerKeyedRangesBlockProps, type CompilerKeyedRowBinding, type CompilerKeyedRowConditional, type CompilerKeyedRowConditionalBranch, type CompilerKeyedRowElement, type CompilerKeyedRowEvent, type CompilerKeyedRowsBlockProps, type CompilerStateUpdater, type CompilerStyleBinding, type CompilerTextBinding, createCompiledComponent };
+export { type CompiledComponentDefinition, type CompilerAttributeBinding, type CompilerBinding, type CompilerBlockRuntime, type CompilerCell, type CompilerComponentBlockProps, type CompilerConditionalBlockBinding, type CompilerConditionalBlockProps, type CompilerConditionalRange, type CompilerConditionalRangesBlockProps, type CompilerHostBlock, type CompilerHostConditionalBinding, type CompilerHostConditionalBlockProps, type CompilerHostConditionalBranch, type CompilerHostConditionalRanges, type CompilerHostElement, type CompilerHostKeyedRanges, type CompilerHostMixedRanges, type CompilerKeyedListBlockProps, type CompilerKeyedRange, type CompilerKeyedRangesBlockProps, type CompilerKeyedRowBinding, type CompilerKeyedRowConditional, type CompilerKeyedRowConditionalBranch, type CompilerKeyedRowElement, type CompilerKeyedRowEvent, type CompilerKeyedRowsBlockProps, type CompilerMixedRange, type CompilerMixedRangesBlockProps, type CompilerRuntimeReactivity, type CompilerStateUpdater, type CompilerStaticRangeBinding, type CompilerStyleBinding, type CompilerTextBinding, createCompiledComponent };

package/dist/compiler-runtime.d.ts

@@ -1,12 +1,15 @@
 import React from 'react';
 
 type CompilerStateUpdater = unknown | ((previous: unknown) => unknown);
+type CompilerRuntimeReactivity = "static" | "hybrid";
 interface CompilerCell {
     get(): unknown;
     set(next: CompilerStateUpdater): void;
 }
 interface CompilerTextBinding<Props> {
     kind: "text";
+    /** Runtime tracking is useful only for compiler-proven short-circuiting readers. */
+    tracking?: "dynamic";
     path: readonly number[];
     /** Stable ref target emitted by newer compiler versions. */
     target?: number;
@@ -15,6 +18,8 @@ interface CompilerTextBinding<Props> {
 }
 interface CompilerAttributeBinding<Props> {
     kind: "attribute";
+    /** Runtime tracking is useful only for compiler-proven short-circuiting readers. */
+    tracking?: "dynamic";
     path: readonly number[];
     /** Stable ref target emitted by newer compiler versions. */
     target?: number;
@@ -24,6 +29,8 @@ interface CompilerAttributeBinding<Props> {
 }
 interface CompilerStyleBinding<Props> {
     kind: "style";
+    /** Runtime tracking is useful only for compiler-proven short-circuiting readers. */
+    tracking?: "dynamic";
     path: readonly number[];
     /** Stable ref target emitted by newer compiler versions. */
     target?: number;
@@ -58,10 +65,14 @@ interface CompilerHostElement {
         value: unknown;
     }[];
     children: readonly (CompilerHostElement | unknown)[];
+    /** Direct-child structure owned without creating another React fiber. */
+    block?: CompilerHostBlock;
 }
 type CompilerKeyedRowElement = CompilerHostElement;
 interface CompilerKeyedRowEvent {
     name: string;
+    /** Host-element path relative to the keyed row root. */
+    path?: readonly number[];
     invoke(item: unknown, index: number, event: React.SyntheticEvent): unknown;
 }
 interface CompilerKeyedRowConditionalBranch {
@@ -82,10 +93,45 @@ interface CompilerHostConditionalBinding {
     name?: string;
     read(): unknown;
 }
+interface CompilerStaticRangeBinding {
+    kind: "text" | "attribute" | "style";
+    /** Static segment before range N, or the trailing segment at ranges.length. */
+    segment: number;
+    /** Direct host sibling inside that static segment. */
+    sibling: number;
+    /** Host-element path relative to the selected static sibling. */
+    path: readonly number[];
+    name?: string;
+    read(): unknown;
+}
 interface CompilerHostConditionalBranch {
     create(): CompilerHostElement;
     bindings: readonly CompilerHostConditionalBinding[];
 }
+interface CompilerHostConditionalRanges {
+    kind: "conditional-ranges";
+    id: number;
+    ranges: readonly CompilerConditionalRange[];
+    trailing: number;
+    bindings?: readonly CompilerStaticRangeBinding[];
+}
+interface CompilerHostKeyedRanges {
+    kind: "keyed-ranges";
+    id: number;
+    ranges: readonly CompilerKeyedRange[];
+    trailing: number;
+    bindings?: readonly CompilerStaticRangeBinding[];
+    /** Compiler output may store only static direct children and materialize rows from the ranges. */
+    staticChildrenOnly?: boolean;
+}
+interface CompilerHostMixedRanges {
+    kind: "mixed-ranges";
+    id: number;
+    ranges: readonly CompilerMixedRange[];
+    trailing: number;
+    bindings?: readonly CompilerStaticRangeBinding[];
+}
+type CompilerHostBlock = CompilerHostConditionalRanges | CompilerHostKeyedRanges | CompilerHostMixedRanges;
 interface CompilerHostConditionalBlockProps {
     id: number;
     render(): React.ReactElement;
@@ -95,21 +141,47 @@ interface CompilerHostConditionalBlockProps {
     truthy?: CompilerHostConditionalBranch;
     falsy?: CompilerHostConditionalBranch;
 }
+interface CompilerConditionalRange {
+    /** Number of static direct host siblings between this slot and the previous slot. */
+    before: number;
+    test(): unknown;
+    /** Logical && can produce a visible number instead of an empty branch. */
+    logical?: boolean;
+    truthy?: CompilerHostConditionalBranch;
+    falsy?: CompilerHostConditionalBranch;
+}
+interface CompilerConditionalRangesBlockProps {
+    id: number;
+    render(): React.ReactElement;
+    rootRef?: React.RefCallback<Element>;
+    ranges: readonly CompilerConditionalRange[];
+    /** Number of static direct host siblings after the final conditional slot. */
+    trailing: number;
+    bindings?: readonly CompilerStaticRangeBinding[];
+}
 interface CompilerKeyedRowBinding {
     kind: "text" | "attribute" | "style";
     path: readonly number[];
     name?: string;
+    /** Component state cells read by this binding, when emitted by the compiler. */
+    dependencies?: readonly number[];
     read(item: unknown, index: number): unknown;
 }
 interface CompilerKeyedRowsBlockProps {
     id: number;
     render(event: (item: unknown, index: number, eventId: number) => React.EventHandler<React.SyntheticEvent>, conditional: (item: unknown, index: number, conditionalId: number, render: (item: unknown, index: number) => React.ReactNode) => React.ReactNode): React.ReactElement;
     items(): Iterable<unknown> | null | undefined;
+    /** State cells that can change the row collection or its key projection. */
+    structureDependencies?: readonly number[];
     rowKey(item: unknown, index: number): React.Key;
     create(item: unknown, index: number): CompilerKeyedRowElement;
     bindings: readonly CompilerKeyedRowBinding[];
     events?: readonly CompilerKeyedRowEvent[];
+    /** Route compiler-proven bubbling row events through the stable React container. */
+    delegateEvents?: boolean;
     conditionals?: readonly CompilerKeyedRowConditional[];
+    /** Row descriptors contain compiler-owned nested host scopes. */
+    hostBlocks?: boolean;
 }
 interface CompilerKeyedRange {
     /** Number of static direct host siblings between this range and the previous range. */
@@ -119,6 +191,17 @@ interface CompilerKeyedRange {
     create(item: unknown, index: number): CompilerKeyedRowElement;
     bindings: readonly CompilerKeyedRowBinding[];
 }
+type CompilerMixedRange = ({
+    kind: "conditional";
+} & CompilerConditionalRange) | ({
+    kind: "keyed";
+} & CompilerKeyedRange);
+interface CompilerMixedRangesBlockProps {
+    id: number;
+    render(): React.ReactElement;
+    create(): CompilerHostElement;
+    rootRef?: React.RefCallback<Element>;
+}
 interface CompilerKeyedRangesBlockProps {
     id: number;
     render(): React.ReactElement;
@@ -126,6 +209,7 @@ interface CompilerKeyedRangesBlockProps {
     ranges: readonly CompilerKeyedRange[];
     /** Number of static direct host siblings after the final keyed range. */
     trailing: number;
+    bindings?: readonly CompilerStaticRangeBinding[];
 }
 interface CompilerComponentBlockProps {
     id: number;
@@ -134,20 +218,29 @@ interface CompilerComponentBlockProps {
 interface CompilerBlockRuntime {
     Conditional: React.ComponentType<CompilerConditionalBlockProps>;
     HostConditional: React.ComponentType<CompilerHostConditionalBlockProps>;
+    ConditionalRanges: React.ComponentType<CompilerConditionalRangesBlockProps>;
     KeyedList: React.ComponentType<CompilerKeyedListBlockProps>;
     KeyedRows: React.ComponentType<CompilerKeyedRowsBlockProps>;
     KeyedRanges: React.ComponentType<CompilerKeyedRangesBlockProps>;
+    MixedRanges: React.ComponentType<CompilerMixedRangesBlockProps>;
     Component: React.ComponentType<CompilerComponentBlockProps>;
     target(id: number): React.RefCallback<Element>;
 }
 type CompilerBinding<Props> = CompilerTextBinding<Props> | CompilerAttributeBinding<Props> | CompilerStyleBinding<Props> | CompilerConditionalBlockBinding;
 interface CompiledComponentDefinition<Props> {
     displayName: string;
+    /** Scheduler selected by the compiler. Hand-authored definitions default to `static`. */
+    reactivity?: CompilerRuntimeReactivity;
     /** Stable development-only identity used to preserve state across compatible refreshes. */
     hmrId?: string;
     /** Changes when the compiler-owned state layout is no longer refresh-compatible. */
     stateSignature?: string;
     initialize(props: Props): readonly unknown[];
+    /**
+     * Compiler-emitted flat prop reads. Primitive values can share the local
+     * dependency graph; identity-bearing values retain normal React rendering.
+     */
+    readProps?(props: Props): readonly unknown[];
     render(props: Props, state: readonly CompilerCell[], blocks: CompilerBlockRuntime): React.ReactElement;
     bindings: readonly CompilerBinding<Props>[];
 }
@@ -160,4 +253,4 @@ interface CompiledComponentDefinition<Props> {
  */
 declare function createCompiledComponent<Props>(definition: CompiledComponentDefinition<Props>): React.ComponentType<Props>;
 
-export { type CompiledComponentDefinition, type CompilerAttributeBinding, type CompilerBinding, type CompilerBlockRuntime, type CompilerCell, type CompilerComponentBlockProps, type CompilerConditionalBlockBinding, type CompilerConditionalBlockProps, type CompilerHostConditionalBinding, type CompilerHostConditionalBlockProps, type CompilerHostConditionalBranch, type CompilerHostElement, type CompilerKeyedListBlockProps, type CompilerKeyedRange, type CompilerKeyedRangesBlockProps, type CompilerKeyedRowBinding, type CompilerKeyedRowConditional, type CompilerKeyedRowConditionalBranch, type CompilerKeyedRowElement, type CompilerKeyedRowEvent, type CompilerKeyedRowsBlockProps, type CompilerStateUpdater, type CompilerStyleBinding, type CompilerTextBinding, createCompiledComponent };
+export { type CompiledComponentDefinition, type CompilerAttributeBinding, type CompilerBinding, type CompilerBlockRuntime, type CompilerCell, type CompilerComponentBlockProps, type CompilerConditionalBlockBinding, type CompilerConditionalBlockProps, type CompilerConditionalRange, type CompilerConditionalRangesBlockProps, type CompilerHostBlock, type CompilerHostConditionalBinding, type CompilerHostConditionalBlockProps, type CompilerHostConditionalBranch, type CompilerHostConditionalRanges, type CompilerHostElement, type CompilerHostKeyedRanges, type CompilerHostMixedRanges, type CompilerKeyedListBlockProps, type CompilerKeyedRange, type CompilerKeyedRangesBlockProps, type CompilerKeyedRowBinding, type CompilerKeyedRowConditional, type CompilerKeyedRowConditionalBranch, type CompilerKeyedRowElement, type CompilerKeyedRowEvent, type CompilerKeyedRowsBlockProps, type CompilerMixedRange, type CompilerMixedRangesBlockProps, type CompilerRuntimeReactivity, type CompilerStateUpdater, type CompilerStaticRangeBinding, type CompilerStyleBinding, type CompilerTextBinding, createCompiledComponent };