ziex 0.0.1-dev.0 → 0.0.1-dev.2

package/dom.d.ts

@@ -0,0 +1,134 @@
+import type { ComponentMetadata } from "./types";
+/**
+ * Result of preparing a component for hydration.
+ *
+ * Contains all the necessary data to render a React component into its server-rendered container.
+ */
+export type PreparedComponent = {
+    /**
+     * The HTML element where the component should be rendered.
+     *
+     * This is the DOM node that was server-rendered by ZX with the component's unique ID.
+     * The element already exists in the DOM and contains the server-rendered fallback content.
+     * React will hydrate this element, replacing its contents with the interactive component.
+     *
+     * @example
+     * ```tsx
+     * // The DOM node corresponds to HTML like:
+     * // <div id="zx-dcde04c415da9d1b15ca2690d8b497ae" data-props="...">...</div>
+     *
+     * const { domNode } = await prepareComponent(component);
+     * createRoot(domNode).render(<Component {...props} />);
+     * ```
+     */
+    domNode: HTMLElement;
+    /**
+     * Component props parsed from the server-rendered HTML.
+     *
+     * Props are extracted from the `data-props` attribute (JSON-encoded) on the component's
+     * container element. If the component has children from server side then they are automatically converted to
+     * `dangerouslySetInnerHTML` for React compatibility.
+     *
+     * @example
+     * ```tsx
+     * // Server-rendered HTML:
+     * // <div data-props='{"max_count":10,"label":"Counter"}' data-children="<span>0</span>">...</div>
+     *
+     * const { props } = await prepareComponent(component);
+     * // props = {
+     * //   max_count: 10,
+     * //   label: "Counter",
+     * //   dangerouslySetInnerHTML: { __html: "<span>0</span>" }
+     * // }
+     * ```
+     */
+    props: Record<string, any> & {
+        /**
+         * React's special prop for setting inner HTML directly.
+         *
+         * Automatically added when the component has children in the ZX file. The HTML string
+         * is extracted from the `data-children` attribute on the server-rendered element.
+         *
+         * @example
+         * ```tsx
+         * // In ZX file:
+         * <MyComponent @rendering={.csr}>
+         *   <p>Child content</p>
+         * </MyComponent>
+         *
+         * // Results in:
+         * // props.dangerouslySetInnerHTML = { __html: "<p>Child content</p>" }
+         * ```
+         */
+        dangerouslySetInnerHTML?: {
+            __html: string;
+        };
+    };
+    /**
+     * The loaded React component function ready to render.
+     *
+     * This is the default export from the component module, lazy-loaded via the component's
+     * import function. The component is ready to be rendered with React's `createRoot().render()`.
+     *
+     * @example
+     * ```tsx
+     * const { Component, props, domNode } = await prepareComponent(component);
+     *
+     * // Component is the default export from the component file:
+     * // export default function CounterComponent({ max_count }: { max_count: number }) {
+     * //   return <div>Count: {max_count}</div>;
+     * // }
+     *
+     * createRoot(domNode).render(<Component {...props} />);
+     * ```
+     */
+    Component: (props: any) => React.ReactElement;
+};
+/**
+ * Prepares a client-side component for hydration by locating its DOM container, extracting
+ * props and children from server-rendered HTML attributes, and lazy-loading the component module.
+ *
+ * This function bridges server-rendered HTML (from ZX's Zig transpiler) and client-side React
+ * components. It reads data attributes (`data-props`, `data-children`) from the DOM element
+ * with the component's unique ID, then lazy-loads the component module for rendering.
+ *
+ * @param component - The component metadata containing ID, import function, and other metadata
+ *                    needed to locate and load the component
+ *
+ * @returns A Promise that resolves to a `PreparedComponent` object containing the DOM node,
+ *          parsed props, and the loaded React component function
+ *
+ * @throws {Error} If the component's container element cannot be found in the DOM. This typically
+ *                 happens if the component ID doesn't match any element, the script runs before
+ *                 the HTML is loaded, or there's a mismatch between server and client metadata
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with React:
+ * import { createRoot } from "react-dom/client";
+ * import { prepareComponent } from "ziex";
+ * import { components } from "@ziex/components";
+ *
+ * for (const component of components) {
+ *   prepareComponent(component).then(({ domNode, Component, props }) => {
+ *     createRoot(domNode).render(<Component {...props} />);
+ *   }).catch(console.error);
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With async/await:
+ * async function hydrateComponent(component: ComponentMetadata) {
+ *   try {
+ *     const { domNode, Component, props } = await prepareComponent(component);
+ *     createRoot(domNode).render(<Component {...props} />);
+ *   } catch (error) {
+ *     console.error(`Failed to hydrate ${component.name}:`, error);
+ *   }
+ * }
+ *
+ * Promise.all(components.map(hydrateComponent));
+ * ```
+ */
+export declare function prepareComponent(component: ComponentMetadata): Promise<PreparedComponent>;

package/index.d.ts

@@ -1,8 +1,2 @@
-export declare const components: ComponentMetadata[];
-type ComponentMetadata = {
-    name: string;
-    path: string;
-    id: string;
-    import: () => Promise<(props: unknown) => React.ReactElement>;
-};
-export {};
+export type { ComponentMetadata } from "./types";
+export { prepareComponent, type PreparedComponent } from "./dom";

package/index.js

@@ -1 +1 @@
-var n="{[ZX_COMPONENTS]s}";export{n as components};
+async function S(G){let k=document.getElementById(G.id);if(!k)throw Error(`Root element ${G.id} not found`);let J=JSON.parse(k.getAttribute("data-props")||"{}"),K=k.getAttribute("data-children")??void 0;if(K)J.dangerouslySetInnerHTML={__html:K};let Q=await G.import();return{domNode:k,props:J,Component:Q}}export{S as prepareComponent};

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "ziex",
+  "version": "0.0.1-dev.2",
   "description": "ZX is a framework for building web applications with Zig.",
   "main": "index.js",
   "type": "module",
-  "version": "0.0.1-dev.0",
   "homepage": "https://github.com/nurulhudaapon/zx",
   "repository": {
     "type": "git",

package/types.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Metadata for a client-side component used within a ZX file.
+ *
+ * This type represents the metadata for components that are marked with the `@rendering` attribute
+ * in ZX files. When a component is declared with `@rendering={.csr}` or `@rendering={.csz}` in a
+ * `.zx` file, the ZX transpiler generates a `ComponentMetadata` entry that is included in the
+ * generated `components` array.
+ *
+ * @example
+ * ```tsx
+ * // In a ZX file (page.zx):
+ * <CounterComponent @rendering={.csr} max_count={10} />
+ *
+ * // Generated components array (components.ts):
+ * export const components: ComponentMetadata[] = [
+ *   {
+ *     name: "CounterComponent",
+ *     path: "./components/CounterComponent.tsx",
+ *     id: "zx-dcde04c415da9d1b15ca2690d8b497ae",
+ *     type: "csr",
+ *     import: () => import('./components/CounterComponent.tsx')
+ *   }
+ * ];
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using ComponentMetadata with prepareComponent:
+ * import { prepareComponent, type ComponentMetadata } from "ziex";
+ *
+ * for (const component of components) {
+ *   const { domNode, props, Component } = await prepareComponent(component);
+ *   // Render component to DOM node
+ * }
+ * ```
+ */
+export type ComponentMetadata = {
+    /**
+     * The name of the component as declared in the ZX file.
+     *
+     * This is the tag name used in JSX syntax within `.zx` files. It corresponds to the component
+     * identifier used in the component declaration (e.g., `<CounterComponent />`).
+     *
+     * @example
+     * ```tsx
+     * // In ZX file:
+     * <CounterComponent @rendering={.csr} />
+     *
+     * // name will be: "CounterComponent"
+     * ```
+     */
+    name: string;
+    /**
+     * The file path to the component module.
+     *
+     * This is the relative or absolute path to the component file that will be dynamically imported
+     * at runtime. For CSR components, this typically points to a `.tsx` or `.jsx` file. For CSZ
+     * components, this points to a Zig component file.
+     *
+     * The path is determined from the `@jsImport` directive in the ZX file, or defaults to
+     * `./{componentName}.tsx` if not explicitly specified.
+     *
+     * @example
+     * ```tsx
+     * // In ZX file:
+     * const CounterComponent = @jsImport("components/Counter.tsx");
+     * <CounterComponent @rendering={.csr} />
+     *
+     * // path will be: "components/Counter.tsx"
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // Without explicit @jsImport:
+     * <MyComponent @rendering={.csr} />
+     *
+     * // path will default to: "./MyComponent.tsx"
+     * ```
+     */
+    path: string;
+    /**
+     * A unique HTML element identifier for the component's root DOM node.
+     *
+     * This ID is generated by hashing the component's path and name using MD5, then formatting it
+     * as a hex string with the "zx-" prefix. The ID is used to locate the component's container
+     * element in the DOM during client-side hydration.
+     *
+     * The ID format is: `zx-{32 hex characters}` (e.g., `zx-dcde04c415da9d1b15ca2690d8b497ae`)
+     *
+     * When the same component is used multiple times on a page, each instance gets the same base ID
+     * since they share the same path and name. The ZX runtime uses this ID along with `data-props`
+     * and `data-children` attributes to hydrate the component with the correct props and children.
+     *
+     * @example
+     * ```tsx
+     * // Component metadata:
+     * {
+     *   name: "CounterComponent",
+     *   path: "./components/Counter.tsx",
+     *   id: "zx-dcde04c415da9d1b15ca2690d8b497ae"
+     * }
+     *
+     * // Generated HTML:
+     * <div id="zx-dcde04c415da9d1b15ca2690d8b497ae"
+     *      data-props='{"max_count":10}'
+     *      data-children="...">
+     *   <!-- Server-rendered content -->
+     * </div>
+     * ```
+     */
+    id: string;
+    /**
+     * The rendering type of the component, determining how it will be rendered on the client.
+     *
+     * - **"csr"** (Client Side React): The component is a React component that will be rendered
+     *   using React's client-side rendering. The component file should export a default React
+     *   component function. This is the most common type for interactive UI components.
+     *
+     * - **"csz"** (Client Side Zig): The component is a Zig component that will be compiled to
+     *   WebAssembly and rendered on the client side. This allows you to use Zig's performance
+     *   and type safety for client-side components.
+     *
+     * The type is determined by the `@rendering` attribute value in the ZX file (`.csr` or `.csz`).
+     *
+     * @example
+     * ```tsx
+     * // CSR component (React):
+     * <CounterComponent @rendering={.csr} max_count={10} />
+     * // type: "csr"
+     *
+     * // Component file (CounterComponent.tsx):
+     * export default function CounterComponent({ max_count }: { max_count: number }) {
+     *   return <div>Count: {max_count}</div>;
+     * }
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // CSZ component (Zig/WASM):
+     * <CounterComponent @rendering={.csz} />
+     * // type: "csz"
+     *
+     * // Component file (CounterComponent.zig):
+     * pub fn CounterComponent(allocator: zx.Allocator) zx.Component {
+     *   return (<div @allocator={allocator}>Counter</div>);
+     * }
+     * ```
+     */
+    type: "csr" | "csz";
+    /**
+     * A lazy-loading function that dynamically imports the component module.
+     *
+     * This function returns a Promise that resolves to the component function. It enables
+     * code-splitting and lazy loading of components, improving initial page load performance
+     * by only loading components when they are needed.
+     *
+     * For CSR components, the imported module should export a default React component.
+     * For CSZ components, the import mechanism depends on the WASM module structure.
+     *
+     * The function is called during client-side hydration to load and render the component
+     * into its corresponding DOM container element.
+     *
+     * @returns A Promise that resolves to a component function that accepts props and returns a React element.
+     *
+     * @example
+     * ```tsx
+     * // Component metadata:
+     * {
+     *   import: () => import('./components/CounterComponent.tsx')
+     * }
+     *
+     * // Usage:
+     * const Component = await component.import();
+     * // Component is now the default export from CounterComponent.tsx
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // With prepareComponent helper:
+     * import { prepareComponent } from "ziex";
+     *
+     * const { Component, props, domNode } = await prepareComponent(component);
+     * // Component is loaded and ready to render with props
+     * ```
+     */
+    import: () => Promise<(props: any) => React.ReactElement>;
+};