@punkestu/react-html 0.1.0 → 0.1.1

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;

package/example/src/pages/index.tsx

@@ -1,49 +0,0 @@
-import React from 'react';
-import { Layout } from '../components/Layout.js';
-import { Card } from '../components/Card.js';
-import { Counter } from '../components/Counter.island.js';
-import { Tabs } from '../components/Tabs.island.js';
-
-export const title = 'react-html Demo - Pure HTML + Reactive Islands';
-export const description = 'Modular HTML with React and selective reactive island compilation';
-
-export default function HomePage() {
-  return (
-    <Layout title={title} description={description} currentPath="/">
-      <h1>React to Pure HTML Engine</h1>
-      <p className="subtitle">
-        Write modular React components for static HTML, and compile only reactive components to minimal JavaScript.
-      </p>
-
-      <div className="grid">
-        <Card title="Modular Components" icon="📦">
-          <p>
-            Build reusable UI parts like headers, navigation, cards, and footers with React. No repetitive HTML code.
-          </p>
-        </Card>
-        <Card title="Zero-JS by Default" icon="🚀">
-          <p>
-            Static components render to 100% pure HTML. No client bundle is generated unless reactive islands are used.
-          </p>
-        </Card>
-        <Card title="Selective Reactivity" icon="🏝️">
-          <p>
-            Interactive components are isolated as islands and bundled into tiny, dedicated client scripts using esbuild.
-          </p>
-        </Card>
-      </div>
-
-      <h2 style={{ marginBottom: '1rem' }}>Interactive Island Demos</h2>
-      <p style={{ color: '#94a3b8', marginBottom: '1.5rem' }}>
-        Below are two reactive islands embedded in pure static HTML:
-      </p>
-
-      {/* Reactive Counter Island */}
-      <Counter initialCount={10} step={2} />
-
-      {/* Reactive Tabs Island */}
-      <Tabs defaultTab="islands" />
-    </Layout>
-  );
-}
-

package/example/src/pages/pure.tsx

@@ -1,56 +0,0 @@
-import React from 'react';
-import { Layout } from '../components/Layout.js';
-import { Card } from '../components/Card.js';
-
-export const title = '100% Pure HTML - react-html';
-export const description = 'Demonstration of zero JavaScript pure HTML output';
-
-export default function PurePage() {
-  const features = [
-    {
-      title: 'Zero Runtime JS',
-      icon: '🛡️',
-      desc: 'This entire page is compiled to semantic HTML. There are no <script> tags, no React runtime, and no client-side JavaScript sent over the wire.'
-    },
-    {
-      title: 'Modular & DRY',
-      icon: '🧩',
-      desc: 'Built using React components like <Layout />, <Header />, <Card />, and <Footer />. No copy-pasting HTML boilerplate!'
-    },
-    {
-      title: 'Fast TTFB & Paint',
-      icon: '⚡',
-      desc: 'Browsers parse pure HTML almost instantly. Perfect for documentation, blogs, landing pages, and marketing sites.'
-    }
-  ];
-
-  return (
-    <Layout title={title} description={description} currentPath="/pure">
-      <h1>Pure Static HTML</h1>
-      <p className="subtitle">
-        Compiled from React JSX with <strong>0 KB client JavaScript</strong>.
-      </p>
-
-      <div className="grid">
-        {features.map((item, idx) => (
-          <Card key={idx} title={item.title} icon={item.icon}>
-            <p>{item.desc}</p>
-          </Card>
-        ))}
-      </div>
-
-      <div className="card">
-        <h3>Inspect the Source Code</h3>
-        <p>
-          Right-click and select "View Page Source". You will notice:
-        </p>
-        <ul style={{ paddingLeft: '1.5rem', marginTop: '0.75rem', color: '#94a3b8' }}>
-          <li>Clean, indented, semantic HTML5 markup.</li>
-          <li>No <code>data-reactroot</code> or React internal comments.</li>
-          <li>Zero <code>&lt;script&gt;</code> tags.</li>
-        </ul>
-      </div>
-    </Layout>
-  );
-}
-

package/src/cli/docs-content.ts

@@ -1,268 +0,0 @@
-export interface DocSection {
-  id: string;
-  title: string;
-  summary: string;
-  content: string[];
-}
-
-export const DOC_SECTIONS: DocSection[] = [
-  {
-    id: 'intro',
-    title: '1. Overview & Philosophy',
-    summary: 'Core concepts: pure HTML output, zero-JS by default, and modular JSX.',
-    content: [
-      '# 1. Overview & Philosophy',
-      '',
-      'react-html bridges the gap between modern component-based developer experience',
-      'and lightweight, blazing-fast static websites.',
-      '',
-      '* ZERO JAVASCRIPT BY DEFAULT:',
-      '  Standard components (layouts, navigation, typography, cards, footers) render into',
-      '  100% clean, semantic HTML5. No React runtime, no data-reactroot attributes,',
-      '  and 0 KB JavaScript sent to the browser.',
-      '',
-      '* MODULAR & DRY (DON\'T REPEAT YOURSELF):',
-      '  Eliminate copy-pasting HTML boilerplate. Compose pages with reusable React',
-      '  components (<Layout>, <Header>, <Card>, <Footer>) with typed props.',
-      '',
-      '* SELECTIVE REACTIVITY (ISLANDS ARCHITECTURE):',
-      '  Only components that explicitly require client-side interactivity are bundled',
-      '  into isolated, tiny JavaScript files. Everything around them remains pure HTML.'
-    ]
-  },
-  {
-    id: 'quickstart',
-    title: '2. Getting Started & Setup',
-    summary: 'Installation, Node.js environment, and initial directory structure.',
-    content: [
-      '# 2. Getting Started & Setup',
-      '',
-      '* PREREQUISITES:',
-      '  - Node.js v20.0.0 or higher (runs natively on standard Node.js & npm)',
-      '',
-      '* INSTALLATION:',
-      '  $ npm install react-html',
-      '',
-      '* RECOMMENDED PROJECT STRUCTURE:',
-      '  my-project/',
-      '  ├── package.json',
-      '  ├── public/                  # Static assets (CSS, images, icons)',
-      '  │   └── styles.css',
-      '  └── src/',
-      '      ├── components/          # Reusable UI components',
-      '      │   ├── Layout.tsx       # Master HTML shell',
-      '      │   ├── Header.tsx       # Navigation bar',
-      '      │   └── Counter.island.tsx # Interactive island component',
-      '      └── pages/               # Multi-page entries',
-      '          ├── index.tsx        # -> dist/index.html',
-      '          ├── about.tsx        # -> dist/about.html',
-      '          └── blog/',
-      '              └── first.tsx    # -> dist/blog/first.html'
-    ]
-  },
-  {
-    id: 'modular-html',
-    title: '3. Modular HTML with React',
-    summary: 'Creating reusable layouts, header partials, and nested components.',
-    content: [
-      '# 3. Modular HTML with React',
-      '',
-      'Stop repeating HTML boilerplate. Create a single Layout component:',
-      '',
-      '// src/components/Layout.tsx',
-      'import React, { ReactNode } from "react";',
-      'import { Header } from "./Header.js";',
-      'import { Footer } from "./Footer.js";',
-      '',
-      'export function Layout({ title, children }: { title: string; children: ReactNode }) {',
-      '  return (',
-      '    <html lang="en">',
-      '      <head>',
-      '        <meta charSet="UTF-8" />',
-      '        <meta name="viewport" content="width=device-width, initial-scale=1.0" />',
-      '        <title>{title}</title>',
-      '        <link rel="stylesheet" href="/styles.css" />',
-      '      </head>',
-      '      <body>',
-      '        <Header />',
-      '        <main>{children}</main>',
-      '        <Footer />',
-      '      </body>',
-      '    </html>',
-      '  );',
-      '}',
-      '',
-      'Every page simply wraps its content in <Layout>: no copy-pasting required!'
-    ]
-  },
-  {
-    id: 'islands',
-    title: '4. Reactive Islands Architecture',
-    summary: 'Compiling interactive React components to tiny client-side JavaScript.',
-    content: [
-      '# 4. Reactive Islands Architecture',
-      '',
-      'When you need client-side state (useState, useEffect, event listeners):',
-      '',
-      '1. Create the component and wrap it using island():',
-      '// src/components/Counter.island.tsx',
-      'import React, { useState } from "react";',
-      'import { island } from "react-html";',
-      '',
-      'function CounterComponent({ initial = 0 }) {',
-      '  const [count, setCount] = useState(initial);',
-      '  return (',
-      '    <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>',
-      '  );',
-      '}',
-      '',
-      'export const Counter = island(CounterComponent, import.meta.url, "Counter");',
-      'export default Counter;',
-      '',
-      '2. Use it in any page just like a normal React component:',
-      '// src/pages/index.tsx',
-      '<Counter initial={10} />',
-      '',
-      '* HOW THE ENGINE COMPILES IT:',
-      '  - Initial HTML is pre-rendered for instant paint and SEO.',
-      '  - esbuild bundles ONLY CounterComponent into dist/assets/islands/Counter.js.',
-      '  - Only pages containing <Counter> will have the <script> tag injected.'
-    ]
-  },
-  {
-    id: 'directives',
-    title: '5. Hydration Directives (Performance)',
-    summary: 'Controlling client hydration timing with load, idle, and visible.',
-    content: [
-      '# 5. Hydration Directives (Performance)',
-      '',
-      'Control when JavaScript executes on the user\'s device with the `client` prop:',
-      '',
-      '* client="load" (Default):',
-      '  <Counter client="load" />',
-      '  Hydrates as soon as DOMContentLoaded fires. Use for critical UI above the fold.',
-      '',
-      '* client="idle":',
-      '  <Counter client="idle" />',
-      '  Hydrates during browser idle time via requestIdleCallback. Perfect for widgets',
-      '  or floating elements that do not block immediate interaction.',
-      '',
-      '* client="visible":',
-      '  <Counter client="visible" />',
-      '  Hydrates only when scrolled into the viewport using IntersectionObserver.',
-      '  Ideal for carousels, comment sections, or widgets further down the page.'
-    ]
-  },
-  {
-    id: 'cli',
-    title: '6. CLI Commands & Options',
-    summary: 'Full guide for build, dev, and docs commands.',
-    content: [
-      '# 6. CLI Commands & Options',
-      '',
-      '* BUILD PRODUCTION STATIC SITE:',
-      '  $ react-html build [options]',
-      '  Flags:',
-      '    --pages <dir>     Directory containing pages (default: src/pages or pages)',
-      '    --out <dir>       Output directory (default: dist)',
-      '    --root <dir>      Root directory of the project (default: cwd)',
-      '    --no-minify       Disable JS minification for debugging',
-      '',
-      '* START DEV SERVER (LIVE PREVIEW & WATCH):',
-      '  $ react-html dev [options]',
-      '  Flags:',
-      '    --port <number>   Port to listen on (default: 3000)',
-      '    --host <string>   Host to bind to (default: localhost)',
-      '',
-      '* TERMINAL UI DOCUMENTATION (TUI):',
-      '  $ react-html docs               # Interactive TUI navigator',
-      '  $ react-html docs --all         # Print entire manual to stdout',
-      '  $ react-html docs <section-id>  # Print specific section'
-    ]
-  },
-  {
-    id: 'api',
-    title: '7. Programmatic API Reference',
-    summary: 'Using build(), renderPageToHtml(), and createDevServer() in Node.js.',
-    content: [
-      '# 7. Programmatic API Reference',
-      '',
-      'import { build, renderPageToHtml, island, Island } from "react-html";',
-      '',
-      '* build(config):',
-      '  const result = await build({',
-      '    root: process.cwd(),',
-      '    pagesDir: "src/pages",',
-      '    outDir: "dist",',
-      '    minify: true',
-      '  });',
-      '  // Returns: { pages: [...], islands: [...], outDir: string }',
-      '',
-      '* renderPageToHtml({ pagePath, Component, props, metadata }):',
-      '  const { html, islands } = renderPageToHtml({',
-      '    pagePath: "/path/to/page.tsx",',
-      '    Component: MyPage,',
-      '    metadata: { title: "Custom Title" }',
-      '  });',
-      '  // Returns pure HTML string and list of detected islands.'
-    ]
-  },
-  {
-    id: 'server',
-    title: '8. Server App Integration (Express, Fastify, Node HTTP)',
-    summary: 'Using createEngine() for production static hosting and development live rebuilds.',
-    content: [
-      '# 8. Server App Integration (Express, Fastify, Node HTTP)',
-      '',
-      'You can import and use react-html directly inside your backend server application:',
-      '',
-      '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 checks process.env.NODE_ENV === "production"',
-      '});',
-      '',
-      '* 1. CONNECT / EXPRESS MIDDLEWARE:',
-      '  app.use(engine.middleware);',
-      '  // In production: finds and streams pre-built static HTML from dist/.',
-      '  // In development: dynamically rebuilds TSX on the fly and returns fresh HTML.',
-      '',
-      '* 2. PROGRAMMATIC ROUTE RENDERING:',
-      '  app.get("/custom", async (req, res) => {',
-      '    const html = await engine.render("index", { 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);'
-    ]
-  },
-  {
-    id: 'troubleshooting',
-    title: '9. Best Practices & Troubleshooting',
-    summary: 'Avoiding hydration mismatch, React error #418, and styling rules.',
-    content: [
-      '# 8. Best Practices & Troubleshooting',
-      '',
-      '* PREVENTING HYDRATION MISMATCH (React Error #418):',
-      '  - Ensure server and initial client props match.',
-      '  - Do not use client-only objects (window.innerWidth, localStorage) in initial render.',
-      '    Instead, read them inside useEffect() or an event handler.',
-      '  - react-html automatically protects island markup during formatting and uses',
-      '    renderToString for interactive inner trees to guarantee matching text nodes.',
-      '',
-      '* ISOLATE STATEFUL LOGIC:',
-      '  Keep non-interactive parts (headers, card shells, footers) pure React components.',
-      '  Only place state hooks (useState, useReducer) inside *.island.tsx files.'
-    ]
-  }
-];
-

package/src/cli/index.ts

@@ -1,113 +0,0 @@
-import path from 'node:path';
-import { build } from '../index.js';
-import { createDevServer } from '../server/dev-server.js';
-import { launchDocsTui } from './tui-docs.js';
-
-export async function runCli(args: string[] = process.argv.slice(2)): Promise<void> {
-  const command = args[0] || 'help';
-
-  function getArgValue(flag: string): string | undefined {
-    const idx = args.indexOf(flag);
-    return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
-  }
-
-  const hasFlag = (flag: string) => args.includes(flag);
-
-  if (hasFlag('--help') || hasFlag('-h') || command === 'help') {
-    console.log(`
-react-html - Engine to convert React to pure HTML with reactive islands
-
-Usage:
-  react-html <command> [options]
-
-Commands:
-  build         Compile pages into pure HTML & bundle reactive islands
-  dev           Start live preview development server with auto-rebuild
-  docs          Browse interactive documentation in Terminal UI (TUI)
-  help          Show this help message
-
-Options:
-  --pages <dir>     Pages directory (default: src/pages or pages)
-  --out <dir>       Output directory (default: dist)
-  --port <number>   Dev server port (default: 3000)
-  --host <string>   Dev server host (default: localhost)
-  --no-minify       Disable minification for island bundles
-  --root <path>     Project root directory (default: cwd)
-
-Docs Options:
-  react-html docs              Launch interactive Terminal UI
-  react-html docs --all        Print complete manual to terminal
-  react-html docs <section>    Print a specific section (e.g. islands, api, cli)
-`);
-    return;
-  }
-
-  if (hasFlag('--version') || hasFlag('-v')) {
-    console.log(`react-html v0.1.0`);
-    return;
-  }
-
-  const root = getArgValue('--root') || process.cwd();
-  const pagesDir = getArgValue('--pages');
-  const outDir = getArgValue('--out') || 'dist';
-  const minify = !hasFlag('--no-minify');
-
-  if (command === 'build') {
-    console.log(`\n🚀 [react-html] Building static site...`);
-    const startTime = Date.now();
-    try {
-      const result = await build({
-        root,
-        pagesDir,
-        outDir,
-        minify
-      });
-      console.log(`✅ [react-html] Build successful in ${Date.now() - startTime}ms`);
-      console.log(`📄 Pages compiled (${result.pages.length}):`);
-      result.pages.forEach(p => {
-        console.log(`   - ${path.relative(root, p.output)}`);
-      });
-      if (result.islands.length > 0) {
-        console.log(`🏝️  Reactive islands bundled (${result.islands.length}):`);
-        result.islands.forEach(isl => {
-          console.log(`   - ${path.relative(root, isl)}`);
-        });
-      } else {
-        console.log(`✨ Pure 100% HTML generated (0 KB JavaScript overhead)`);
-      }
-    } catch (err: any) {
-      console.error(`❌ [react-html] Build failed:`, err?.message || err);
-      process.exit(1);
-    }
-  } else if (command === 'dev') {
-    const port = parseInt(getArgValue('--port') || '3000', 10);
-    const host = getArgValue('--host') || 'localhost';
-    try {
-      await createDevServer({
-        root,
-        pagesDir,
-        outDir,
-        port,
-        host
-      });
-    } catch (err: any) {
-      console.error(`❌ [react-html] Dev server failed:`, err?.message || err);
-      process.exit(1);
-    }
-  } else if (command === 'docs') {
-    try {
-      await launchDocsTui(args[1]);
-    } catch (err: any) {
-      console.error(`❌ [react-html] Docs error:`, err?.message || err);
-      process.exit(1);
-    }
-  } else {
-    console.error(`Unknown command "${command}". Run "react-html --help" for available commands.`);
-    process.exit(1);
-  }
-}
-
-// Direct invocation check
-if (import.meta.url === `file://${process.argv[1]}`) {
-  runCli();
-}