ziex 0.0.1-dev.1 → 0.0.1-dev.3

package/README.md

@@ -27,7 +27,7 @@ winget install -e --id zig.zig # Windows
 
 ## Quick Example
 
-```tsx site/pages/docs/example/overview.zx
+```tsx site/pages/examples/overview.zx
 pub fn QuickExample(allocator: zx.Allocator) zx.Component {
     const is_loading = true;
     const chars = "Hello, ZX Dev!";
@@ -84,10 +84,10 @@ const zx = @import("zx");
 - [x] Routing
     - [x] File-system Routing
     - [x] Search Parameters
-    - [ ] Path Segments
+    - [x] Path Segments
 - [x] Components
 - [x] Control Flow
-    - [ ] `if`
+    - [x] `if`
     - [ ] `if` nested
     - [x] `if/else`
     - [x] `if/else` nested
@@ -95,8 +95,8 @@ const zx = @import("zx");
     - [x] `for` nested
     - [x] `switch`
     - [x] `switch` nested
-    - [ ] `while`
-    - [ ] `while` nested
+    - [x] `while`
+    - [x] `while` nested
 - [x] Assets
     - [x] Copying
     - [x] Serving
@@ -108,14 +108,14 @@ const zx = @import("zx");
 - [ ] Middleware
 - [ ] API Endpoints
 - [ ] Server Actions
-- [ ] CLI
+- [x] CLI
     - [x] `init` Project Template
     - [x] `transpile` Transpile .zx files to Zig source code
     - [x] `serve` Serve the project
     - [x] `dev` HMR or Rebuild on Change
     - [x] `fmt` Format the ZX source code (_Alpha_)
     - [x] `export` Generate static site assets
-    - [ ] `bundle` Bundle the ZX executable with public/assets and exe
+    - [x] `bundle` Bundle the ZX executable with public/assets and exe
     - [x] `version` Show the version of the ZX CLI
     - [x] `update` Update the version of ZX dependency
     - [x] `upgrade` Upgrade the version of ZX CLI

package/index.d.ts

@@ -1,2 +1,9 @@
-export type { ComponentMetadata } from './types';
-export { prepareComponent } from './dom';
+export declare const zx: BuildZon;
+type BuildZon = {
+    version: string;
+    description: string;
+    repository: string;
+    fingerprint: number;
+    minimum_zig_version: string;
+};
+export {};

package/index.js

@@ -1 +1 @@
-async function k(y){let x=document.getElementById(y.id);if(!x)throw Error(`Root element ${y.id} not found`);let f=JSON.parse(x.getAttribute("data-props")||"{}"),b=x.getAttribute("data-children")??void 0;if(b)f.dangerouslySetInnerHTML={__html:b};let j=await y.import();return{domNode:x,props:f,Component:j}}export{k as prepareComponent};
+var i={name:"zx",version:"0.0.1-dev.228",description:"ZX is a framework for building web applications with Zig.",repository:"https://github.com/nurulhudaapon/zx",fingerprint:14616285862371232000,minimum_zig_version:"0.15.2",dependencies:{httpz:{url:"git+https://github.com/nurulhudaapon/httpz.git#7268154f43f5827bf78668e8e79a00f2ebe4db13",hash:"httpz-0.0.0-PNVzrBgtBwCVkSJyophIX6WHwDR0r8XhBGQr96Kk-1El"},zli:{url:"git+https://github.com/nurulhudaapon/cliz.git#aff3b54879e7514afaf8c87f1abe22121b8992d4",hash:"zli-4.3.0-LeUjpu_fAABOSVASSCW2fFh8SFVNHrxQGDXGPNzcSE_i"}},paths:["build.zig","build.zig.zon","src"]};export{i as zx};

package/package.json

@@ -3,6 +3,12 @@
   "description": "ZX is a framework for building web applications with Zig.",
   "main": "index.js",
   "type": "module",
+  "version": "0.0.1-dev.3",
+  "exports": {
+    ".": "./index.js",
+    "./react": "./react/index.js",
+    "./wasm": "./wasm/index.js"
+  },
   "homepage": "https://github.com/nurulhudaapon/zx",
   "repository": {
     "type": "git",
@@ -23,6 +29,5 @@
   "author": "Nurul Huda (Apon) <me@nurulhudaapon.com>",
   "license": "MIT",
   "module": "index.js",
-  "types": "index.d.ts",
-  "version": "0.0.1-dev.1"
+  "types": "index.d.ts"
 }

package/react/dom.d.ts

@@ -0,0 +1,135 @@
+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>;
+export declare function filterComponents(components: ComponentMetadata[]): ComponentMetadata[];

package/react/index.d.ts

@@ -0,0 +1,2 @@
+export { prepareComponent, filterComponents, type PreparedComponent } from "./dom";
+export type { ComponentMetadata } from "./types";

package/react/index.js

@@ -0,0 +1 @@
+async function S(k){let G=document.getElementById(k.id);if(!G)throw Error(`Root element ${k.id} not found`,{cause:k});let J=JSON.parse(G.getAttribute("data-props")||"{}"),K=G.getAttribute("data-children")??void 0;if(K)J.dangerouslySetInnerHTML={__html:K};let Q=await k.import();return{domNode:G,props:J,Component:Q}}function U(k){let G=window.location.pathname;return k.filter((J)=>J.route===G||!J.route)}export{S as prepareComponent,U as filterComponents};

package/react/types.d.ts

@@ -0,0 +1,193 @@
+/**
+ * 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;
+    /**
+     * The route of of the component in which page the component was used,
+     * null in case the component was used in other non-page/layout context.
+     * ```
+     */
+    route: string | null;
+    /**
+     * 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>;
+};

package/wasm/dom.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentMetadata } from "./types";
+export type PreparedComponent = {};
+export declare function prepareComponent(component: ComponentMetadata): Promise<PreparedComponent>;
+export declare function filterComponents(components: ComponentMetadata[]): ComponentMetadata[];

package/wasm/index.d.ts

@@ -0,0 +1,2 @@
+export { prepareComponent, filterComponents, type PreparedComponent } from "./dom";
+export type { ComponentMetadata } from "./types";

package/wasm/index.js

@@ -0,0 +1 @@
+async function o(e){throw Error("Not implemented")}function t(e){throw Error("Not implemented")}export{o as prepareComponent,t as filterComponents};

package/wasm/types.d.ts

@@ -0,0 +1 @@
+export type ComponentMetadata = {};

package/dom.d.ts

@@ -1,11 +0,0 @@
-import type { ComponentMetadata } from "./types";
-/**
- * Prepare a component for rendering
- * @param component - The component to prepare
- * @returns The component, props, and DOM node
- */
-export declare function prepareComponent(component: ComponentMetadata): Promise<{
-    domNode: HTMLElement;
-    props: any;
-    Component: (props: unknown) => React.ReactElement;
-}>;

package/types.d.ts

@@ -1,25 +0,0 @@
-/**
- * The metadata for a component that was used within ZX file
- */
-export type ComponentMetadata = {
-    /**
-     * The name of the component, this is what name was used in the component declaration
-     * e.g. <CounterComponent />
-     */
-    name: string;
-    /**
-     * The path to the component, this is the path to the component file
-     * e.g. ./components/CounterComponent.tsx
-     */
-    path: string;
-    /**
-     * The id of the component, this is a unique identifier for the component and an additinal index in case the same component is used multiple times
-     * e.g. zx-1234567890 or zx-1234567890-1
-     */
-    id: string;
-    /**
-     * The import function for the component, this is the function that will be used to import the component
-     * e.g. () => import('./components/CounterComponent.tsx')
-     */
-    import: () => Promise<(props: unknown) => React.ReactElement>;
-};