@punkestu/react-html 0.1.0 → 1.0.0

package/DOCS.md

@@ -1,317 +0,0 @@
-# 📖 react-html Complete Manual & Documentation
-
-A high-performance static engine to compile React/JSX to **pure, semantic HTML** with selective reactive compilation for interactive components via an **Islands Architecture**.
-
-> 💡 **Terminal UI Access**: You can also browse this documentation interactively in your terminal by running:
-> ```bash
-> npx react-html docs
-> # Or print a specific section:
-> npx react-html docs islands
-> ```
-
----
-
-## Table of Contents
-
-1. [Overview & Philosophy](#1-overview--philosophy)
-2. [Getting Started & Setup](#2-getting-started--setup)
-3. [Modular HTML with React](#3-modular-html-with-react)
-4. [Reactive Islands Architecture](#4-reactive-islands-architecture)
-5. [Hydration Directives](#5-hydration-directives)
-6. [CLI Commands & Options](#6-cli-commands--options)
-7. [Programmatic API Reference](#7-programmatic-api-reference)
-8. [Server App Integration (Express, Fastify, Node HTTP)](#8-server-app-integration-express-fastify-node-http)
-9. [Best Practices & Troubleshooting](#9-best-practices--troubleshooting)
-
----
-
-## 1. Overview & Philosophy
-
-Modern web development often forces a painful choice:
-- **Write raw HTML/handlebars/nunjucks**: You lose type safety, component modularity, and rich JSX composition.
-- **Use modern React frameworks (Next.js, CRA, Remix)**: You inadvertently ship massive megabytes of JavaScript, client routers, and heavy hydration runtimes even for mostly static pages.
-
-**`react-html` gives you the best of both worlds**:
-1. **Zero JavaScript by Default**:
-   Pages without interactive islands output 100% pure, clean HTML5. No client-side React runtime, no `data-reactroot` attributes, and 0 KB JavaScript sent to visitors.
-2. **Modular & DRY Components**:
-   Compose your pages with `<Layout>`, `<Header>`, `<Card>`, `<Footer>`, loops, and conditionals using standard React and TypeScript.
-3. **Selective Reactivity**:
-   Interactive components (counters, carousels, modals, filters) are marked as **Islands**. The engine pre-renders their initial markup for instant paint and bundles only that component into a standalone client script using `esbuild`.
-
----
-
-## 2. Getting Started & Setup
-
-### Prerequisites
-- Standard **Node.js v20.0.0 or higher** with `npm` (no Bun dependencies).
-
-### Installation
-```bash
-npm install react-html
-```
-
-Or clone and link locally:
-```bash
-git clone https://github.com/microapes/react-html.git
-cd react-html
-npm install
-npm run build
-npm link
-```
-
-### Recommended Directory Structure
-
-```text
-my-project/
-├── package.json
-├── public/                     # Static files copied to dist/ verbatim
-│   ├── favicon.ico
-│   └── styles.css
-└── src/
-    ├── components/             # Reusable modular UI components
-    │   ├── Layout.tsx          # Master HTML wrapper (<head>, <body>)
-    │   ├── Header.tsx          # Navigation header
-    │   ├── Footer.tsx          # Footer component
-    │   └── Counter.island.tsx  # Interactive island component
-    └── pages/                  # Page entrypoints
-        ├── index.tsx           # -> dist/index.html
-        ├── about.tsx           # -> dist/about.html
-        └── docs/
-            └── guide.tsx       # -> dist/docs/guide.html
-```
-
----
-
-## 3. Modular HTML with React
-
-Eliminate repetitive HTML across your project by creating reusable layout components:
-
-```tsx
-// src/components/Layout.tsx
-import React, { ReactNode } from 'react';
-import { Header } from './Header.js';
-import { Footer } from './Footer.js';
-
-export interface LayoutProps {
-  title?: string;
-  description?: string;
-  children: ReactNode;
-}
-
-export function Layout({
-  title = 'Default Title',
-  description = 'My static site',
-  children
-}: LayoutProps) {
-  return (
-    <html lang="en">
-      <head>
-        <meta charSet="UTF-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <title>{title}</title>
-        <meta name="description" content={description} />
-        <link rel="stylesheet" href="/styles.css" />
-      </head>
-      <body>
-        <Header />
-        <main className="container">{children}</main>
-        <Footer />
-      </body>
-    </html>
-  );
-}
-```
-
-Now, every page simply wraps its content without repeating `<head>`, stylesheets, or `<header>`/`<footer>`:
-
-```tsx
-// src/pages/about.tsx
-import React from 'react';
-import { Layout } from '../components/Layout.js';
-
-export const title = 'About Us';
-
-export default function AboutPage() {
-  return (
-    <Layout title={title}>
-      <h1>About Our Project</h1>
-      <p>This entire page compiles into pure static HTML with 0 KB JavaScript!</p>
-    </Layout>
-  );
-}
-```
-
----
-
-## 4. Reactive Islands Architecture
-
-When a component needs client-side state (`useState`, `useEffect`, event listeners):
-
-### Step 1: Wrap Component with `island()`
-
-```tsx
-// src/components/Counter.island.tsx
-import React, { useState } from 'react';
-import { island } from 'react-html';
-
-export interface CounterProps {
-  initialCount?: number;
-  step?: number;
-}
-
-function CounterComponent({ initialCount = 0, step = 1 }: CounterProps) {
-  const [count, setCount] = useState(initialCount);
-
-  return (
-    <div className="counter">
-      <p>Current: {count}</p>
-      <button onClick={() => setCount(c => c - step)}>- {step}</button>
-      <button onClick={() => setCount(c => c + step)}>+ {step}</button>
-    </div>
-  );
-}
-
-// Wrap with island helper providing Component, source path, and identifier
-export const Counter = island(CounterComponent, import.meta.url, 'Counter');
-export default Counter;
-```
-
-### Step 2: Use in Any Page
-
-```tsx
-// src/pages/index.tsx
-import React from 'react';
-import { Layout } from '../components/Layout.js';
-import { Counter } from '../components/Counter.island.js';
-
-export default function HomePage() {
-  return (
-    <Layout title="Home">
-      <h1>Interactive Page</h1>
-      {/* Pre-rendered to HTML for instant paint, then hydrated with tiny JS */}
-      <Counter initialCount={10} step={2} />
-    </Layout>
-  );
-}
-```
-
-### What Happens Behind the Scenes:
-1. **Server Phase**: The island is pre-rendered with `renderToString` and placed inside a container `<div data-island="Counter" data-props="...">`.
-2. **Bundler Phase**: `esbuild` extracts and bundles only `CounterComponent` into `dist/assets/islands/Counter.js`.
-3. **Injection Phase**: `<script type="module" src="/assets/islands/Counter.js"></script>` is injected right before `</body>`.
-4. **Client Hydration**: The script queries `[data-island="Counter"]` and attaches listeners using React 19's `hydrateRoot`.
-
----
-
-## 5. Hydration Directives
-
-Fine-tune client performance using the `client` prop:
-
-| Directive | Code Example | When It Hydrates |
-| :--- | :--- | :--- |
-| `load` *(default)* | `<Counter client="load" />` | Immediately upon `DOMContentLoaded`. Ideal for primary UI. |
-| `idle` | `<Counter client="idle" />` | During browser idle time via `requestIdleCallback`. Ideal for background widgets. |
-| `visible` | `<Counter client="visible" />` | When scrolled into view via `IntersectionObserver`. Ideal for below-the-fold content. |
-
----
-
-## 6. CLI Commands & Options
-
-```bash
-# Build static site to dist/
-react-html build
-
-# Customize directories
-react-html build --pages src/pages --out dist --root .
-
-# Start local preview server with auto-rebuild on file changes
-react-html dev --port 3000 --host localhost
-
-# Terminal UI documentation viewer
-react-html docs
-react-html docs --all
-react-html docs islands
-```
-
----
-
-## 7. Programmatic API Reference
-
-You can import and trigger `react-html` within custom build scripts or Node.js services:
-
-```ts
-import { build, renderPageToHtml, createDevServer } from 'react-html';
-
-// 1. Run static build
-const result = await build({
-  root: process.cwd(),
-  pagesDir: 'src/pages',
-  outDir: 'dist',
-  minify: true
-});
-console.log(`Generated ${result.pages.length} pages.`);
-
-// 2. Programmatic dev server
-const server = await createDevServer({
-  port: 8080,
-  host: '127.0.0.1'
-});
-```
-
----
-
-## 8. Server App Integration (Express, Fastify, Node HTTP)
-
-You can import and use `react-html` directly inside your backend server application:
-
-```ts
-import express from 'express';
-import { createEngine } from 'react-html';
-// or: import { createEngine } from 'react-html/server';
-
-const app = express();
-
-const engine = createEngine({
-  pagesDir: 'src/pages',
-  distDir: 'dist',
-  // Automatically detects process.env.NODE_ENV === 'production'
-});
-
-// 1. Connect / Express Middleware
-// In Production: finds and serves pre-built static HTML from dist/
-// In Development: dynamically rebuilds TSX on the fly and returns the fresh HTML string!
-app.use(engine.middleware);
-
-// 2. Programmatic Route Rendering
-app.get('/dashboard', async (req, res) => {
-  const html = await engine.render('dashboard', { user: req.user });
-  res.setHeader('Content-Type', 'text/html; charset=utf-8');
-  res.send(html);
-});
-
-// 3. Native Node HTTP Server
-import http from 'node:http';
-const server = http.createServer(engine.handle);
-server.listen(3000);
-```
-
-### Environment Behavior:
-- **`process.env.NODE_ENV === 'production'`**:
-  - Automatically searches for pre-built `.html` files in `distDir` (`dist/index.html`, `dist/about.html`).
-  - Streams them immediately to clients with 0 rebuild overhead.
-  - Serves static assets (`dist/assets/islands/*.js`, `dist/styles.css`).
-- **`process.env.NODE_ENV !== 'production'` (Development)**:
-  - Dynamically rebuilds the corresponding `.tsx` page on each request.
-  - Bundles any reactive islands on-the-fly.
-  - Returns the fresh HTML string directly in the response—code edits in `src/pages` or `src/components` are reflected instantly on reload without server restarts!
-
----
-
-## 9. Best Practices & Troubleshooting
-
-### Preventing Hydration Mismatches (React Error #418)
-- **Do not read browser globals during initial render**: Avoid `window.innerWidth` or `localStorage.getItem()` directly in the component body. Read them inside a `useEffect()`.
-- **Props consistency**: Ensure initial props passed from the page match what the component expects.
-- **Protected formatting**: `react-html` automatically preserves the exact inner markup of islands so whitespace insertion does not invalidate React's DOM reconciliation.
-

package/example/public/styles.css

@@ -1,184 +0,0 @@
-:root {
-  --bg-color: #0f172a;
-  --card-bg: #1e293b;
-  --text-main: #f8fafc;
-  --text-muted: #94a3b8;
-  --primary: #38bdf8;
-  --primary-hover: #0ea5e9;
-  --border: #334155;
-  --font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-}
-
-* {
-  box-sizing: border-box;
-  margin: 0;
-  padding: 0;
-}
-
-body {
-  background-color: var(--bg-color);
-  color: var(--text-main);
-  font-family: var(--font);
-  line-height: 1.6;
-  min-height: 100vh;
-  display: flex;
-  flex-direction: column;
-}
-
-.container {
-  max-width: 900px;
-  margin: 0 auto;
-  padding: 0 1.5rem;
-  width: 100%;
-}
-
-header {
-  border-bottom: 1px solid var(--border);
-  padding: 1.25rem 0;
-  background: rgba(15, 23, 42, 0.8);
-  backdrop-filter: blur(8px);
-}
-
-header .header-inner {
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-}
-
-.logo {
-  font-size: 1.25rem;
-  font-weight: 700;
-  color: var(--primary);
-  text-decoration: none;
-}
-
-nav a {
-  color: var(--text-muted);
-  text-decoration: none;
-  margin-left: 1.5rem;
-  transition: color 0.2s;
-}
-
-nav a:hover, nav a.active {
-  color: var(--text-main);
-}
-
-main {
-  flex: 1;
-  padding: 3rem 0;
-}
-
-h1 {
-  font-size: 2.25rem;
-  margin-bottom: 1rem;
-}
-
-p.subtitle {
-  color: var(--text-muted);
-  font-size: 1.15rem;
-  margin-bottom: 2rem;
-}
-
-.grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
-  gap: 1.5rem;
-  margin-bottom: 2.5rem;
-}
-
-.card {
-  background: var(--card-bg);
-  border: 1px solid var(--border);
-  border-radius: 0.75rem;
-  padding: 1.5rem;
-}
-
-.card h3 {
-  margin-bottom: 0.5rem;
-  color: var(--primary);
-}
-
-.card p {
-  color: var(--text-muted);
-  font-size: 0.95rem;
-}
-
-/* Island interactive counter styling */
-.counter-box {
-  background: var(--card-bg);
-  border: 1px solid var(--border);
-  border-radius: 0.75rem;
-  padding: 2rem;
-  text-align: center;
-  margin: 1.5rem 0;
-}
-
-.counter-value {
-  font-size: 3rem;
-  font-weight: 700;
-  color: var(--primary);
-  margin: 1rem 0;
-}
-
-.btn-group {
-  display: flex;
-  justify-content: center;
-  gap: 1rem;
-}
-
-button {
-  background: var(--primary);
-  color: #0f172a;
-  border: none;
-  border-radius: 0.5rem;
-  padding: 0.6rem 1.25rem;
-  font-weight: 600;
-  cursor: pointer;
-  transition: background 0.2s;
-}
-
-button:hover {
-  background: var(--primary-hover);
-}
-
-/* Tabs Island */
-.tabs-container {
-  background: var(--card-bg);
-  border: 1px solid var(--border);
-  border-radius: 0.75rem;
-  overflow: hidden;
-  margin: 1.5rem 0;
-}
-
-.tabs-header {
-  display: flex;
-  background: #0b1120;
-  border-bottom: 1px solid var(--border);
-}
-
-.tab-btn {
-  background: transparent;
-  color: var(--text-muted);
-  padding: 0.75rem 1.5rem;
-  border-radius: 0;
-  border-bottom: 2px solid transparent;
-}
-
-.tab-btn.active {
-  color: var(--primary);
-  border-bottom: 2px solid var(--primary);
-  background: rgba(56, 189, 248, 0.05);
-}
-
-.tab-content {
-  padding: 1.5rem;
-}
-
-footer {
-  border-top: 1px solid var(--border);
-  padding: 2rem 0;
-  text-align: center;
-  color: var(--text-muted);
-  font-size: 0.875rem;
-}
-

package/example/src/components/Card.tsx

@@ -1,17 +0,0 @@
-import React, { ReactNode } from 'react';
-
-export interface CardProps {
-  title: string;
-  children: ReactNode;
-  icon?: string;
-}
-
-export function Card({ title, children, icon }: CardProps) {
-  return (
-    <div className="card">
-      <h3>{icon ? `${icon} ` : ''}{title}</h3>
-      <div>{children}</div>
-    </div>
-  );
-}
-

package/example/src/components/Counter.island.tsx

@@ -1,35 +0,0 @@
-import React, { useState } from 'react';
-import { island } from '../../../src/index.js';
-
-export interface CounterProps {
-  initialCount?: number;
-  step?: number;
-}
-
-function CounterComponent({ initialCount = 0, step = 1 }: CounterProps) {
-  const [count, setCount] = useState(initialCount);
-
-  return (
-    <div className="counter-box">
-      <h3>⚡ Interactive Counter Island</h3>
-      <p style={{ color: '#94a3b8', fontSize: '0.9rem' }}>
-        This component is rendered statically on the server, then hydrated with tiny JavaScript.
-      </p>
-      <div className="counter-value">{count}</div>
-      <div className="btn-group">
-        <button type="button" onClick={() => setCount((c) => c - step)}>
-          - {step}
-        </button>
-        <button type="button" onClick={() => setCount(0)}>
-          Reset
-        </button>
-        <button type="button" onClick={() => setCount((c) => c + step)}>
-          + {step}
-        </button>
-      </div>
-    </div>
-  );
-}
-
-export const Counter = island(CounterComponent, import.meta.url, 'Counter');
-export default Counter;

package/example/src/components/Footer.tsx

@@ -1,13 +0,0 @@
-import React from 'react';
-
-export function Footer() {
-  const currentYear = new Date().getFullYear();
-  return (
-    <footer>
-      <div className="container">
-        <p>&copy; {currentYear} react-html. Modular pure HTML engine with selective reactive islands.</p>
-      </div>
-    </footer>
-  );
-}
-

package/example/src/components/Header.tsx

@@ -1,20 +0,0 @@
-import React from 'react';
-
-export interface HeaderProps {
-  currentPath?: string;
-}
-
-export function Header({ currentPath = '/' }: HeaderProps) {
-  return (
-    <header>
-      <div className="container header-inner">
-        <a href="/" className="logo">⚛️ react-html</a>
-        <nav>
-          <a href="/" className={currentPath === '/' ? 'active' : ''}>Home (Interactive)</a>
-          <a href="/pure.html" className={currentPath === '/pure' ? 'active' : ''}>Pure HTML (0 KB JS)</a>
-        </nav>
-      </div>
-    </header>
-  );
-}
-

package/example/src/components/Layout.tsx

@@ -1,39 +0,0 @@
-import React, { ReactNode } from 'react';
-import { Header } from './Header.js';
-import { Footer } from './Footer.js';
-
-export interface LayoutProps {
-  title?: string;
-  description?: string;
-  currentPath?: string;
-  children: ReactNode;
-}
-
-export function Layout({
-  title = 'react-html Demo',
-  description = 'Modular pure HTML generated with React',
-  currentPath = '/',
-  children
-}: LayoutProps) {
-  return (
-    <html lang="en">
-      <head>
-        <meta charSet="UTF-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <title>{title}</title>
-        <meta name="description" content={description} />
-        <link rel="stylesheet" href="/styles.css" />
-      </head>
-      <body>
-        <Header currentPath={currentPath} />
-        <main>
-          <div className="container">
-            {children}
-          </div>
-        </main>
-        <Footer />
-      </body>
-    </html>
-  );
-}
-

package/example/src/components/Tabs.island.tsx

@@ -1,59 +0,0 @@
-import React, { useState } from 'react';
-import { island } from '../../../src/index.js';
-
-export interface TabItem {
-  id: string;
-  label: string;
-  content: string;
-}
-
-export interface TabsProps {
-  tabs?: TabItem[];
-  defaultTab?: string;
-}
-
-const defaultTabs: TabItem[] = [
-  {
-    id: 'features',
-    label: '✨ Features',
-    content: 'Write modular React components with standard JSX. Reusable layouts, cards, buttons, with 0 repetitive boilerplate.'
-  },
-  {
-    id: 'islands',
-    label: '🏝️ Islands',
-    content: 'Only reactive components compile to client-side JavaScript. Everything else is rendered to pure, clean, zero-JS HTML.'
-  },
-  {
-    id: 'speed',
-    label: '⚡ Speed',
-    content: 'Ultra-fast builds powered by esbuild. Instant page loads for users because the browser only receives semantic HTML.'
-  }
-];
-
-function TabsComponent({ tabs = defaultTabs, defaultTab = 'features' }: TabsProps) {
-  const [activeTab, setActiveTab] = useState(defaultTab);
-  const currentTab = tabs.find((t) => t.id === activeTab) || tabs[0];
-
-  return (
-    <div className="tabs-container">
-      <div className="tabs-header">
-        {tabs.map((tab) => (
-          <button
-            key={tab.id}
-            type="button"
-            className={`tab-btn ${activeTab === tab.id ? 'active' : ''}`}
-            onClick={() => setActiveTab(tab.id)}
-          >
-            {tab.label}
-          </button>
-        ))}
-      </div>
-      <div className="tab-content">
-        <p>{currentTab.content}</p>
-      </div>
-    </div>
-  );
-}
-
-export const Tabs = island(TabsComponent, import.meta.url, 'Tabs');
-export default Tabs;