npm - @cloudwerk/ui - Versions diffs - 0.1.0 - Mend

@cloudwerk/ui 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Squirrelsoft Dev Tools
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,270 @@
+/**
+ * @cloudwerk/ui - Type Definitions
+ *
+ * Core types for the renderer abstraction layer.
+ */
+/**
+ * Renderer implementation interface.
+ *
+ * Each renderer (hono-jsx, react, preact) implements this interface.
+ * The renderer is responsible for converting JSX elements to HTML responses.
+ */
+interface Renderer {
+    /**
+     * Render a JSX element to an HTML Response.
+     *
+     * @param element - JSX element to render (type is unknown to support any JSX implementation)
+     * @param options - Render options
+     * @returns Response object (may be a Promise for async rendering)
+     */
+    render(element: unknown, options?: RenderOptions): Response | Promise<Response>;
+    /**
+     * Create an HTML Response from a raw string.
+     *
+     * Useful for static HTML, templates, or pre-rendered content.
+     *
+     * @param content - Raw HTML string
+     * @param options - HTML response options
+     * @returns Response object
+     */
+    html(content: string, options?: HtmlOptions): Response;
+    /**
+     * Hydrate a JSX element on the client.
+     *
+     * Only used for Client Components marked with 'use client'.
+     * This attaches event handlers to server-rendered HTML.
+     *
+     * @param element - JSX element to hydrate
+     * @param root - DOM element to hydrate into
+     */
+    hydrate(element: unknown, root: Element): void;
+}
+/**
+ * Options for rendering JSX elements.
+ */
+interface RenderOptions {
+    /**
+     * HTTP status code for the response.
+     * @default 200
+     */
+    status?: number;
+    /**
+     * Additional response headers.
+     * These are merged with the default Content-Type header.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Whether to include the <!DOCTYPE html> declaration.
+     * @default true
+     */
+    doctype?: boolean;
+}
+/**
+ * Options for creating HTML responses from raw strings.
+ */
+interface HtmlOptions {
+    /**
+     * HTTP status code for the response.
+     * @default 200
+     */
+    status?: number;
+    /**
+     * Additional response headers.
+     * These are merged with the default Content-Type header.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Props for components that receive children.
+ *
+ * Works with any JSX implementation (Hono JSX, React, Preact).
+ * The children type is `unknown` to allow any JSX element type.
+ *
+ * @example
+ * function Layout({ children }: PropsWithChildren) {
+ *   return (
+ *     <html>
+ *       <body>{children}</body>
+ *     </html>
+ *   )
+ * }
+ */
+interface PropsWithChildren<_P = unknown> {
+    children?: unknown;
+}
+/**
+ * @cloudwerk/ui - Renderer Selection
+ *
+ * Manages the active renderer and provides registration functionality.
+ */
+/**
+ * Get the currently active renderer instance.
+ *
+ * @returns The active Renderer implementation
+ *
+ * @example
+ * const renderer = getActiveRenderer()
+ * const response = renderer.render(<App />)
+ */
+declare function getActiveRenderer(): Renderer;
+/**
+ * Get the name of the currently active renderer.
+ *
+ * @returns The renderer name (e.g., 'hono-jsx', 'react', 'preact')
+ *
+ * @example
+ * console.log(`Using ${getActiveRendererName()} renderer`)
+ */
+declare function getActiveRendererName(): string;
+/**
+ * Set the active renderer by name.
+ *
+ * Called during app initialization based on the `ui.renderer` config option.
+ * The renderer must be registered (either built-in or via registerRenderer).
+ *
+ * @param name - Renderer name from config (e.g., 'hono-jsx', 'react')
+ * @throws Error if renderer is not found
+ *
+ * @example
+ * // Initialize from config
+ * setActiveRenderer(config.ui?.renderer ?? 'hono-jsx')
+ */
+declare function setActiveRenderer(name: string): void;
+/**
+ * Register a custom renderer.
+ *
+ * Allows third-party renderer implementations to be used.
+ * The renderer must implement the Renderer interface.
+ *
+ * @param name - Unique name for the renderer
+ * @param renderer - Renderer implementation
+ * @throws Error if a renderer with that name is already registered
+ *
+ * @example
+ * // Register a custom renderer
+ * registerRenderer('solid', solidRenderer)
+ *
+ * // Then use it in config
+ * // ui: { renderer: 'solid' }
+ */
+declare function registerRenderer(name: string, renderer: Renderer): void;
+/**
+ * Get a list of all available renderer names.
+ *
+ * Useful for validation and error messages.
+ *
+ * @returns Array of registered renderer names
+ *
+ * @example
+ * const available = getAvailableRenderers()
+ * // ['hono-jsx']
+ */
+declare function getAvailableRenderers(): string[];
+/**
+ * @cloudwerk/ui - Hono JSX Renderer
+ *
+ * Default renderer implementation using Hono JSX.
+ * Hono JSX elements have a toString() method that renders them to HTML.
+ */
+/**
+ * Hono JSX renderer implementation.
+ *
+ * Uses hono/jsx for server-side rendering. This is the default renderer
+ * for Cloudwerk applications.
+ *
+ * Features:
+ * - Synchronous rendering via toString()
+ * - Automatic doctype handling
+ * - Proper Content-Type headers
+ *
+ * Note: Streaming support via renderToReadableStream will be added in issue #38.
+ */
+declare const honoJsxRenderer: Renderer;
+/**
+ * @cloudwerk/ui
+ *
+ * UI rendering abstraction for Cloudwerk.
+ *
+ * This package provides a renderer-agnostic API for rendering JSX components
+ * to HTML responses. The default renderer uses Hono JSX, but custom renderers
+ * (React, Preact, etc.) can be registered and selected via configuration.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Render a JSX element to an HTML Response.
+ *
+ * Uses the currently active renderer (default: hono-jsx).
+ * Supports streaming for async components (via renderer implementation).
+ *
+ * @param element - JSX element to render
+ * @param options - Render options
+ * @returns Response object (may be Promise for async rendering)
+ *
+ * @example
+ * import { render } from '@cloudwerk/ui'
+ *
+ * // In a route handler
+ * app.get('/', (c) => {
+ *   return render(<HomePage />)
+ * })
+ *
+ * @example
+ * // With options
+ * return render(<NotFoundPage />, { status: 404 })
+ *
+ * @example
+ * // With custom headers
+ * return render(<App />, {
+ *   headers: { 'X-Custom-Header': 'value' }
+ * })
+ */
+declare function render(element: unknown, options?: RenderOptions): Response | Promise<Response>;
+/**
+ * Create an HTML Response from a raw string.
+ *
+ * Useful for static HTML, templates, or pre-rendered content
+ * that doesn't need to go through JSX rendering.
+ *
+ * @param content - Raw HTML string
+ * @param options - HTML response options
+ * @returns Response object
+ *
+ * @example
+ * import { html } from '@cloudwerk/ui'
+ *
+ * // Return static HTML
+ * return html('<!DOCTYPE html><html><body>Hello</body></html>')
+ *
+ * @example
+ * // With custom status
+ * return html('<html><body>Not Found</body></html>', { status: 404 })
+ */
+declare function html(content: string, options?: HtmlOptions): Response;
+/**
+ * Hydrate a JSX element on the client.
+ *
+ * Only used for Client Components marked with 'use client'.
+ * This attaches event handlers to server-rendered HTML.
+ *
+ * Note: This feature requires issue #39 to be implemented.
+ * Currently throws an informative error.
+ *
+ * @param element - JSX element to hydrate
+ * @param root - DOM element to hydrate into
+ *
+ * @example
+ * import { hydrate } from '@cloudwerk/ui'
+ *
+ * // Client-side entry point
+ * hydrate(<App />, document.getElementById('root')!)
+ */
+declare function hydrate(element: unknown, root: Element): void;
+export { type HtmlOptions, type PropsWithChildren, type RenderOptions, type Renderer, getActiveRenderer, getActiveRendererName, getAvailableRenderers, honoJsxRenderer, html, hydrate, registerRenderer, render, setActiveRenderer };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,115 @@
+// src/renderers/hono-jsx.ts
+var honoJsxRenderer = {
+  /**
+   * Render a JSX element to an HTML Response.
+   *
+   * Hono JSX elements implement toString() for rendering to HTML strings.
+   * This method wraps the output in a proper Response object with headers.
+   *
+   * @param element - Hono JSX element (has toString() method)
+   * @param options - Render options
+   * @returns Response object with HTML content
+   */
+  render(element, options = {}) {
+    const { status = 200, headers = {}, doctype = true } = options;
+    const htmlString = String(element);
+    const body = doctype ? `<!DOCTYPE html>${htmlString}` : htmlString;
+    return new Response(body, {
+      status,
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        ...headers
+      }
+    });
+  },
+  /**
+   * Create an HTML Response from a raw string.
+   *
+   * Useful for static HTML, templates, or pre-rendered content
+   * that doesn't need to go through JSX rendering.
+   *
+   * @param content - Raw HTML string
+   * @param options - HTML response options
+   * @returns Response object with HTML content
+   */
+  html(content, options = {}) {
+    const { status = 200, headers = {} } = options;
+    return new Response(content, {
+      status,
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        ...headers
+      }
+    });
+  },
+  /**
+   * Hydrate a JSX element on the client.
+   *
+   * This is a placeholder that throws an informative error.
+   * Client-side hydration will be implemented in issue #39.
+   *
+   * @param _element - JSX element (unused)
+   * @param _root - DOM element (unused)
+   * @throws Error with information about when this feature will be available
+   */
+  hydrate(_element, _root) {
+    throw new Error(
+      "Client hydration requires hono/jsx/dom. This feature will be available after issue #39 is implemented."
+    );
+  }
+};
+// src/renderer.ts
+var renderers = {
+  "hono-jsx": honoJsxRenderer
+};
+var activeRenderer = honoJsxRenderer;
+var activeRendererName = "hono-jsx";
+function getActiveRenderer() {
+  return activeRenderer;
+}
+function getActiveRendererName() {
+  return activeRendererName;
+}
+function setActiveRenderer(name) {
+  const renderer = renderers[name];
+  if (!renderer) {
+    const available = Object.keys(renderers).join(", ");
+    throw new Error(`Unknown renderer "${name}". Available renderers: ${available}`);
+  }
+  activeRenderer = renderer;
+  activeRendererName = name;
+}
+function registerRenderer(name, renderer) {
+  if (renderers[name]) {
+    throw new Error(
+      `Renderer "${name}" is already registered. Use a different name.`
+    );
+  }
+  renderers[name] = renderer;
+}
+function getAvailableRenderers() {
+  return Object.keys(renderers);
+}
+// src/index.ts
+function render(element, options) {
+  return getActiveRenderer().render(element, options);
+}
+function html(content, options) {
+  return getActiveRenderer().html(content, options);
+}
+function hydrate(element, root) {
+  return getActiveRenderer().hydrate(element, root);
+}
+export {
+  getActiveRenderer,
+  getActiveRendererName,
+  getAvailableRenderers,
+  honoJsxRenderer,
+  html,
+  hydrate,
+  registerRenderer,
+  render,
+  setActiveRenderer
+};

package/package.json ADDED Viewed

@@ -0,0 +1,39 @@
+{
+  "name": "@cloudwerk/ui",
+  "version": "0.1.0",
+  "description": "UI rendering abstraction for Cloudwerk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/squirrelsoft-dev/cloudwerk.git",
+    "directory": "packages/ui"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {},
+  "peerDependencies": {
+    "hono": "^4.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^1.0.0",
+    "hono": "^4.7.4",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest --run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}