@creact-labs/creact 0.1.8 → 0.2.1

package/dist/hooks/useState.d.ts

@@ -1,120 +0,0 @@
-/**
-
- * Licensed under the Apache License, Version 2.0 (the "License");
-
- * you may not use this file except in compliance with the License.
-
- * You may obtain a copy of the License at
-
- *
-
- *     http://www.apache.org/licenses/LICENSE-2.0
-
- *
-
- * Unless required by applicable law or agreed to in writing, software
-
- * distributed under the License is distributed on an "AS IS" BASIS,
-
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-
- * See the License for the specific language governing permissions and
-
- * limitations under the License.
-
- *
-
- * Copyright 2025 Daniel Coutinho Ribeiro
-
- */
-import { StateBindingManager } from '../core/StateBindingManager';
-import { FiberNode } from '../core/types';
-/**
- * Set the StateBindingManager instance (for testing/injection)
- * @internal
- */
-export declare function setStateBindingManager(manager: StateBindingManager): void;
-/**
- * Get the StateBindingManager instance (for external access)
- * @internal
- */
-export declare function getStateBindingManagerInstance(): StateBindingManager;
-/**
- * Set the current rendering context for useState
- * Called by Renderer before executing a component
- *
- * @internal
- */
-export declare function setStateRenderContext(fiber: FiberNode, path?: string[]): void;
-/**
- * Clear the current rendering context for useState
- * Called by Renderer after component execution
- *
- * @internal
- */
-export declare function clearStateRenderContext(): void;
-/**
- * useState hook - Declare component outputs (NOT reactive state)
- *
- * This hook declares outputs that will be persisted across build/deploy cycles.
- * Unlike React's useState, this does NOT trigger re-renders.
- *
- * Mimics React's useState API with hooks array pattern for multiple calls.
- *
- * REQ-02: Stack Context (declarative outputs)
- *
- * Semantics:
- * - `useState(initialValue)` - Declares a single output value
- * - `setState(value)` during build - Updates the output value for build-time enrichment
- * - `setState(value)` during deploy - Updates persisted output after provider materialization
- * - NOT a render trigger - it's a persistent output update mechanism
- * - Supports multiple useState calls per component (like React)
- *
- * Key difference from React:
- * - React: `setState()` causes re-render in memory
- * - CReact: `setState()` updates persisted outputs for next cycle
- *
- * @param initialValue - Initial output value to declare
- * @returns Tuple of [state, setState] where setState updates the output value
- *
- * @example
- * ```tsx
- * function CDNStack({ children }) {
- *   const distribution = useInstance('cdn', CloudFrontDistribution, { ... });
- *
- *   // Multiple useState calls (like React)
- *   const [distributionId, setDistributionId] = useState<string>();
- *   const [distributionDomain, setDistributionDomain] = useState<string>();
- *   const [distributionArn, setDistributionArn] = useState<string>();
- *
- *   // Optional: Enrich outputs after async materialization
- *   useEffect(async () => {
- *     const actualDomain = await distribution.getDomain();
- *     setDistributionDomain(actualDomain);
- *   }, [distribution]);
- *
- *   // Aggregate outputs for StackContext
- *   const outputs = {
- *     distributionId,
- *     distributionDomain,
- *     distributionArn,
- *   };
- *
- *   return <StackContext.Provider value={outputs}>{children}</StackContext.Provider>;
- * }
- * ```
- */
-export declare function useState<T = undefined>(initialValue?: T): [T, (value: T | ((prev: T) => T)) => void];
-/**
- * Check if useState context is available
- * Useful for validation and testing
- *
- * @internal
- */
-export declare function hasStateContext(): boolean;
-/**
- * Get the current state from Fiber (for testing)
- *
- * @internal
- */
-export declare function getCurrentState(): Record<string, any> | undefined;

package/dist/hooks/useState.js

@@ -1,298 +0,0 @@
-"use strict";
-/**
-
- * Licensed under the Apache License, Version 2.0 (the "License");
-
- * you may not use this file except in compliance with the License.
-
- * You may obtain a copy of the License at
-
- *
-
- *     http://www.apache.org/licenses/LICENSE-2.0
-
- *
-
- * Unless required by applicable law or agreed to in writing, software
-
- * distributed under the License is distributed on an "AS IS" BASIS,
-
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-
- * See the License for the specific language governing permissions and
-
- * limitations under the License.
-
- *
-
- * Copyright 2025 Daniel Coutinho Ribeiro
-
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.setStateBindingManager = setStateBindingManager;
-exports.getStateBindingManagerInstance = getStateBindingManagerInstance;
-exports.setStateRenderContext = setStateRenderContext;
-exports.clearStateRenderContext = clearStateRenderContext;
-exports.useState = useState;
-exports.hasStateContext = hasStateContext;
-exports.getCurrentState = getCurrentState;
-// REQ-02: useState hook for declarative output binding
-// This hook declares component outputs that persist across build/deploy cycles
-const context_1 = require("./context");
-const StateBindingManager_1 = require("../core/StateBindingManager");
-const naming_1 = require("../utils/naming");
-const ReactiveUpdateQueue_1 = require("../core/ReactiveUpdateQueue");
-const Logger_1 = require("../utils/Logger");
-const logger = Logger_1.LoggerFactory.getLogger('hooks');
-const CReact_1 = require("../core/CReact");
-// Global StateBindingManager instance
-let stateBindingManager = null;
-/**
- * Get or create the global StateBindingManager instance
- * @internal
- */
-function getStateBindingManager() {
-    if (!stateBindingManager) {
-        stateBindingManager = new StateBindingManager_1.StateBindingManager();
-    }
-    return stateBindingManager;
-}
-/**
- * Set the StateBindingManager instance (for testing/injection)
- * @internal
- */
-function setStateBindingManager(manager) {
-    stateBindingManager = manager;
-}
-/**
- * Get the StateBindingManager instance (for external access)
- * @internal
- */
-function getStateBindingManagerInstance() {
-    return getStateBindingManager();
-}
-/**
- * Set the current rendering context for useState
- * Called by Renderer before executing a component
- *
- * @internal
- */
-function setStateRenderContext(fiber, path) {
-    (0, context_1.setRenderContext)(fiber, path);
-}
-/**
- * Clear the current rendering context for useState
- * Called by Renderer after component execution
- *
- * @internal
- */
-function clearStateRenderContext() {
-    (0, context_1.clearRenderContext)();
-}
-/**
- * useState hook - Declare component outputs (NOT reactive state)
- *
- * This hook declares outputs that will be persisted across build/deploy cycles.
- * Unlike React's useState, this does NOT trigger re-renders.
- *
- * Mimics React's useState API with hooks array pattern for multiple calls.
- *
- * REQ-02: Stack Context (declarative outputs)
- *
- * Semantics:
- * - `useState(initialValue)` - Declares a single output value
- * - `setState(value)` during build - Updates the output value for build-time enrichment
- * - `setState(value)` during deploy - Updates persisted output after provider materialization
- * - NOT a render trigger - it's a persistent output update mechanism
- * - Supports multiple useState calls per component (like React)
- *
- * Key difference from React:
- * - React: `setState()` causes re-render in memory
- * - CReact: `setState()` updates persisted outputs for next cycle
- *
- * @param initialValue - Initial output value to declare
- * @returns Tuple of [state, setState] where setState updates the output value
- *
- * @example
- * ```tsx
- * function CDNStack({ children }) {
- *   const distribution = useInstance('cdn', CloudFrontDistribution, { ... });
- *
- *   // Multiple useState calls (like React)
- *   const [distributionId, setDistributionId] = useState<string>();
- *   const [distributionDomain, setDistributionDomain] = useState<string>();
- *   const [distributionArn, setDistributionArn] = useState<string>();
- *
- *   // Optional: Enrich outputs after async materialization
- *   useEffect(async () => {
- *     const actualDomain = await distribution.getDomain();
- *     setDistributionDomain(actualDomain);
- *   }, [distribution]);
- *
- *   // Aggregate outputs for StackContext
- *   const outputs = {
- *     distributionId,
- *     distributionDomain,
- *     distributionArn,
- *   };
- *
- *   return <StackContext.Provider value={outputs}>{children}</StackContext.Provider>;
- * }
- * ```
- */
-function useState(initialValue) {
-    // Use consolidated hook context
-    const context = (0, context_1.requireHookContext)();
-    const currentFiber = context.currentFiber; // Non-null assertion safe due to requireHookContext validation
-    // Initialize hooks array in Fiber node if not already present
-    if (!currentFiber.hooks) {
-        currentFiber.hooks = [];
-    }
-    // Get current hook index and increment for next call (state-specific)
-    const currentHookIndex = (0, context_1.incrementHookIndex)('state');
-    // Initialize this hook's state if first render
-    if (currentFiber.hooks[currentHookIndex] === undefined) {
-        // CRITICAL: Check for hydrated value first (hot reload state restoration)
-        // This allows useState to restore persisted state instead of using initial value
-        let hydratedValue = undefined;
-        // Try to get CReact instance to check for hydration data
-        try {
-            const creactInstance = (0, CReact_1.getCReactInstance)?.();
-            if (creactInstance && creactInstance.hasHydrationData()) {
-                // CRITICAL: The fiber path is the component path (e.g., 'web-app-stack')
-                const fiberPath = currentFiber.path?.join('.') || '';
-                logger.debug(`🔍 Looking for hydration: component="${fiberPath}", hookIndex=${currentHookIndex}`);
-                // Try to get hydration from component path
-                hydratedValue = creactInstance.getHydratedValueForComponent(fiberPath, currentHookIndex);
-                if (hydratedValue !== undefined) {
-                    logger.debug(`✅ HYDRATION SUCCESS for ${fiberPath}[${currentHookIndex}]:`, hydratedValue);
-                }
-                else {
-                    logger.debug(`❌ HYDRATION FAILED for ${fiberPath}[${currentHookIndex}]`);
-                    logger.debug(`   Available hydration keys:`, creactInstance.getHydrationMapKeys?.() || 'N/A');
-                }
-            }
-            else {
-                logger.debug(`⚠️  No hydration data available (instance=${!!creactInstance}, hasData=${creactInstance?.hasHydrationData()})`);
-            }
-        }
-        catch (error) {
-            // Hydration is optional, continue with initial value if it fails
-            logger.warn('⚠️  Hydration check failed:', error);
-            logger.debug('Stack:', error.stack);
-        }
-        // Use hydrated value if available, otherwise use initial value
-        const finalValue = hydratedValue !== undefined ? hydratedValue : initialValue;
-        currentFiber.hooks[currentHookIndex] = finalValue;
-        logger.debug(`📝 Initialized hook[${currentHookIndex}] = ${JSON.stringify(finalValue)} (hydrated=${hydratedValue !== undefined})`);
-    }
-    // Store the fiber and hook index for later access
-    const fiber = currentFiber;
-    const hookIdx = currentHookIndex;
-    /**
-     * setState function - Updates the output value with reactive capabilities
-     *
-     * This function updates the persisted output in the Fiber node's hooks array.
-     * It now includes:
-     * - Change detection to avoid unnecessary updates
-     * - Automatic binding detection for provider outputs
-     * - Integration with StateBindingManager for reactive updates
-     * - REQ-4.1, 4.2, 4.3: Internal update mechanism to prevent circular dependencies
-     *
-     * During build: Collects values known at build-time
-     * During deploy: Patches in async resources (queue URLs, ARNs)
-     *
-     * @param value - New value or updater function
-     * @param isInternalUpdate - If true, skip binding creation (prevents loops)
-     */
-    const setState = (value, isInternalUpdate = false) => {
-        // Resolve value (handle both direct value and function forms)
-        const newValue = typeof value === 'function' ? value(fiber.hooks?.[hookIdx]) : value;
-        const oldValue = fiber.hooks?.[hookIdx];
-        // Debug logging (before change check for better visibility)
-        if (process.env.CREACT_DEBUG === 'true') {
-            const safeStringify = (value) => {
-                try {
-                    return JSON.stringify(value);
-                }
-                catch {
-                    return String(value);
-                }
-            };
-            logger.debug(`setState called: hookIdx=${hookIdx}, oldValue=${safeStringify(oldValue)}, newValue=${safeStringify(newValue)}, isInternal=${isInternalUpdate}, fiber.id=${fiber.path?.join('.')}`);
-        }
-        // Only proceed if value actually changed
-        if (oldValue === newValue) {
-            logger.debug(`No change detected, skipping update`);
-            return; // No change, skip update
-        }
-        // Update this hook's state
-        if (fiber.hooks) {
-            fiber.hooks[hookIdx] = newValue;
-        }
-        // REQ-4.2: Only create bindings for user updates, not internal ones
-        // This prevents infinite binding loops when StateBindingManager updates state
-        if (!isInternalUpdate) {
-            // Check if the new value is a provider output and create automatic binding
-            const bindingManager = getStateBindingManager();
-            const outputInfo = bindingManager.isProviderOutput(newValue);
-            if (outputInfo) {
-                // REQ-4.1, 4.3: Prevent infinite binding loops during reactivity
-                // Only bind if this state is not already bound to this output
-                if (!bindingManager.isStateBoundToOutput(fiber, hookIdx)) {
-                    // Automatically bind this state to the provider output
-                    bindingManager.bindStateToOutput(fiber, hookIdx, outputInfo.nodeId, outputInfo.outputKey, newValue);
-                    const bindingKey = (0, naming_1.generateBindingKey)(outputInfo.nodeId, outputInfo.outputKey);
-                    logger.debug(`Auto-bound state to output: ${bindingKey}`);
-                }
-                else {
-                    const bindingKey = (0, naming_1.generateBindingKey)(outputInfo.nodeId, outputInfo.outputKey);
-                    logger.debug(`Skipped re-binding already bound state: ${bindingKey}`);
-                }
-            }
-        }
-        else {
-            logger.debug(`Skipped binding check for internal update`);
-        }
-        // REQ-4.4: Mark fiber as dirty and enqueue for re-render
-        // This is critical for initial deployment where outputs go from undefined → value
-        // The fiber will be collected by the reactivity phase and re-rendered
-        if (!isInternalUpdate && oldValue !== newValue) {
-            // Mark this fiber as having state changes
-            if (!fiber.__stateChanged) {
-                fiber.__stateChanged = true;
-            }
-            // Enqueue fiber for re-rendering in reactivity phase
-            const queue = (0, ReactiveUpdateQueue_1.getReactiveUpdateQueue)();
-            queue.enqueue(fiber);
-            logger.debug(`Enqueued fiber ${fiber.path?.join('.')} for re-render (queue size: ${queue.size()})`);
-        }
-    };
-    // REQ-4.1, 4.2: Store setState callback in fiber for internal updates
-    // This allows StateBindingManager to update state without creating new bindings
-    if (!fiber.setStateCallbacks) {
-        fiber.setStateCallbacks = [];
-    }
-    fiber.setStateCallbacks[hookIdx] = setState;
-    // Get current state for this hook - read it fresh each time
-    // This ensures synchronous setState calls during render are reflected
-    const state = (fiber.hooks && fiber.hooks[hookIdx]);
-    return [state, setState];
-}
-/**
- * Check if useState context is available
- * Useful for validation and testing
- *
- * @internal
- */
-function hasStateContext() {
-    return (0, context_1.hasRenderContext)();
-}
-/**
- * Get the current state from Fiber (for testing)
- *
- * @internal
- */
-function getCurrentState() {
-    return (0, context_1.getCurrentState)();
-}

package/dist/jsx.d.ts

@@ -1,143 +0,0 @@
-/**
-
- * Licensed under the Apache License, Version 2.0 (the "License");
-
- * you may not use this file except in compliance with the License.
-
- * You may obtain a copy of the License at
-
- *
-
- *     http://www.apache.org/licenses/LICENSE-2.0
-
- *
-
- * Unless required by applicable law or agreed to in writing, software
-
- * distributed under the License is distributed on an "AS IS" BASIS,
-
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-
- * See the License for the specific language governing permissions and
-
- * limitations under the License.
-
- *
-
- * Copyright 2025 Daniel Coutinho Ribeiro
-
- */
-/**
- * JSX factory for CReact
- *
- * This module provides the createElement factory function that TypeScript
- * uses to transform JSX syntax into function calls.
- *
- * Example transformation:
- *   <Component prop="value" />
- *   → CReact.createElement(Component, { prop: "value" })
- */
-export interface JSXElement {
-    type: any;
-    props: Record<string, any>;
-    key?: string | number;
-}
-export declare namespace CReact {
-    /**
-     * JSX factory function called by TypeScript when transforming JSX
-     *
-     * @param type - Component function or string (for intrinsic elements)
-     * @param props - Props object (may include key and children)
-     * @param children - Child elements (variadic)
-     * @returns JSXElement object with normalized props
-     */
-    function createElement(type: any, props: Record<string, any> | null, ...children: any[]): JSXElement;
-    /**
-     * Fragment symbol for <>...</> syntax
-     * Fragments allow grouping multiple children without adding extra nodes
-     *
-     * Note: Fragment is a Symbol at runtime, but typed as a function for JSX compatibility
-     */
-    const Fragment: (props: {
-        children?: any;
-    }) => JSXElement;
-}
-/**
- * Global JSX namespace declarations
- *
- * These declarations tell TypeScript how to validate JSX syntax and component props.
- * By including them in this file (not a separate .d.ts), they are automatically
- * included in the compiled output and available to package consumers.
- */
-declare global {
-    namespace JSX {
-        /**
-         * The type returned by JSX expressions
-         */
-        interface Element extends JSXElement {
-        }
-        /**
-         * Intrinsic elements (HTML-like elements)
-         * Empty for CReact - we only support component elements
-         */
-        interface IntrinsicElements {
-        }
-        /**
-         * Defines which prop contains children
-         * This allows TypeScript to understand the children prop
-         */
-        interface ElementChildrenAttribute {
-            children: {};
-        }
-        /**
-         * Base attributes available on all elements (including key)
-         * This applies to all JSX elements, both intrinsic and component-based
-         *
-         * IMPORTANT: This makes 'key' available on ALL JSX elements,
-         * including function components, without needing to add it to props
-         */
-        interface IntrinsicAttributes {
-            key?: string | number;
-        }
-        /**
-         * Attributes available on class components
-         */
-        interface IntrinsicClassAttributes<T> {
-            key?: string | number;
-        }
-        /**
-         * Tell TypeScript how to extract props from a component type
-         * This is critical for making LibraryManagedAttributes work
-         */
-        interface ElementAttributesProperty {
-            props: {};
-        }
-        /**
-         * Augment LibraryManagedAttributes to properly handle key prop
-         *
-         * This tells TypeScript that when checking JSX element props:
-         * 1. Take the component's declared props (P)
-         * 2. Make key optional (it's in IntrinsicAttributes but shouldn't be required)
-         * 3. Allow key to be passed even if not in component props
-         *
-         * We use Omit to remove 'key' from P if it exists, then add it back as optional
-         */
-        type LibraryManagedAttributes<C, P> = Omit<P, 'key'> & IntrinsicAttributes;
-    }
-}
-/**
- * Type helper for component props with children
- */
-export interface PropsWithChildren {
-    children?: JSX.Element | JSX.Element[];
-}
-/**
- * Type helper for functional components
- * Note: key is handled by JSX.IntrinsicAttributes and doesn't need to be in props
- */
-export type FC<P = Record<string, unknown>> = (props: P & PropsWithChildren) => JSX.Element | null;
-/**
- * Type helper for component props that includes JSX attributes (like key)
- * Use this when defining component prop types to allow key prop
- */
-export type ComponentProps<P = Record<string, unknown>> = P & JSX.IntrinsicAttributes;

package/dist/jsx.js

@@ -1,76 +0,0 @@
-"use strict";
-/**
-
- * Licensed under the Apache License, Version 2.0 (the "License");
-
- * you may not use this file except in compliance with the License.
-
- * You may obtain a copy of the License at
-
- *
-
- *     http://www.apache.org/licenses/LICENSE-2.0
-
- *
-
- * Unless required by applicable law or agreed to in writing, software
-
- * distributed under the License is distributed on an "AS IS" BASIS,
-
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-
- * See the License for the specific language governing permissions and
-
- * limitations under the License.
-
- *
-
- * Copyright 2025 Daniel Coutinho Ribeiro
-
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CReact = void 0;
-var CReact;
-(function (CReact) {
-    /**
-     * JSX factory function called by TypeScript when transforming JSX
-     *
-     * @param type - Component function or string (for intrinsic elements)
-     * @param props - Props object (may include key and children)
-     * @param children - Child elements (variadic)
-     * @returns JSXElement object with normalized props
-     */
-    function createElement(type, props, ...children) {
-        // Normalize props (handle null case)
-        const normalizedProps = props ? { ...props } : {};
-        // Extract key from props if present
-        const key = normalizedProps.key;
-        delete normalizedProps.key;
-        // Handle children normalization
-        if (children.length > 0) {
-            // Flatten children array and filter out null/undefined
-            const flattenedChildren = children.flat().filter((child) => child != null);
-            // Single child: store as-is
-            // Multiple children: store as array
-            if (flattenedChildren.length === 1) {
-                normalizedProps.children = flattenedChildren[0];
-            }
-            else if (flattenedChildren.length > 1) {
-                normalizedProps.children = flattenedChildren;
-            }
-        }
-        return {
-            type,
-            props: normalizedProps,
-            key,
-        };
-    }
-    CReact.createElement = createElement;
-    /**
-     * Fragment symbol for <>...</> syntax
-     * Fragments allow grouping multiple children without adding extra nodes
-     *
-     * Note: Fragment is a Symbol at runtime, but typed as a function for JSX compatibility
-     */
-    CReact.Fragment = Symbol.for('CReact.Fragment');
-})(CReact || (exports.CReact = CReact = {}));