@punkestu/react-html 0.1.0 → 1.0.0

package/src/cli/tui-docs.ts

@@ -1,214 +0,0 @@
-import readline from 'node:readline';
-import { DOC_SECTIONS, DocSection } from './docs-content.js';
-
-// ANSI escape sequences
-const CLEAR = '\x1b[2J\x1b[H';
-const HIDE_CURSOR = '\x1b[?25l';
-const SHOW_CURSOR = '\x1b[?25h';
-const BOLD = '\x1b[1m';
-const DIM = '\x1b[2m';
-const RESET = '\x1b[0m';
-const CYAN = '\x1b[36m';
-const GREEN = '\x1b[32m';
-const YELLOW = '\x1b[33m';
-const BLUE = '\x1b[34m';
-const MAGENTA = '\x1b[35m';
-const INVERT = '\x1b[7m';
-
-function formatLine(line: string): string {
-  if (line.startsWith('# ')) {
-    return `${BOLD}${CYAN}${line}${RESET}`;
-  }
-  if (line.startsWith('* ')) {
-    return `${BOLD}${GREEN}${line}${RESET}`;
-  }
-  if (line.startsWith('//') || line.startsWith('  $ ')) {
-    return `${YELLOW}${line}${RESET}`;
-  }
-  if (line.includes('├──') || line.includes('└──') || line.includes('│')) {
-    return `${DIM}${line}${RESET}`;
-  }
-  return line;
-}
-
-export function printSectionDirect(section: DocSection): void {
-  console.log(`\n${BOLD}${CYAN}=== ${section.title} ===${RESET}\n`);
-  for (const line of section.content) {
-    console.log(formatLine(line));
-  }
-  console.log('');
-}
-
-export function printAllDocs(): void {
-  console.log(`\n${BOLD}${CYAN}====================================================${RESET}`);
-  console.log(`${BOLD}${CYAN}          ⚛️  REACT-HTML COMPLETE MANUAL           ${RESET}`);
-  console.log(`${BOLD}${CYAN}====================================================${RESET}\n`);
-  for (const sec of DOC_SECTIONS) {
-    printSectionDirect(sec);
-    console.log(`${DIM}${'─'.repeat(60)}${RESET}\n`);
-  }
-}
-
-export async function launchDocsTui(initialArg?: string): Promise<void> {
-  // If specific section or --all requested non-interactively
-  if (initialArg === '--all' || initialArg === '-a') {
-    printAllDocs();
-    return;
-  }
-
-  if (initialArg) {
-    const match = DOC_SECTIONS.find(
-      (s, idx) =>
-        s.id.toLowerCase() === initialArg.toLowerCase() ||
-        String(idx + 1) === initialArg ||
-        s.title.toLowerCase().includes(initialArg.toLowerCase())
-    );
-    if (match) {
-      printSectionDirect(match);
-      return;
-    }
-  }
-
-  // Non-TTY fallback
-  if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    printAllDocs();
-    return;
-  }
-
-  let selectedIndex = 0;
-  let viewMode: 'menu' | 'reader' = 'menu';
-  let scrollOffset = 0;
-
-  readline.emitKeypressEvents(process.stdin);
-  process.stdin.setRawMode(true);
-  process.stdout.write(HIDE_CURSOR);
-
-  function cleanup() {
-    process.stdout.write(SHOW_CURSOR);
-    if (process.stdin.isTTY) {
-      process.stdin.setRawMode(false);
-    }
-    process.stdin.pause();
-    console.clear();
-  }
-
-  function renderMenu() {
-    const termWidth = Math.max(process.stdout.columns || 80, 60);
-    const border = '═'.repeat(Math.min(termWidth - 2, 70));
-
-    let out = CLEAR;
-    out += `${CYAN}╔${border}╗${RESET}\n`;
-    out += `${CYAN}║${BOLD}          ⚛️  REACT-HTML TERMINAL DOCUMENTATION (TUI)           ${RESET}${CYAN}║${RESET}\n`;
-    out += `${CYAN}║${DIM}   Modular pure HTML with selective reactive islands compilation   ${RESET}${CYAN}║${RESET}\n`;
-    out += `${CYAN}╚${border}╝${RESET}\n\n`;
-
-    out += `${BOLD}Select a topic using arrow keys and press [Enter]:${RESET}\n\n`;
-
-    DOC_SECTIONS.forEach((sec, idx) => {
-      const isSelected = idx === selectedIndex;
-      if (isSelected) {
-        out += `  ${BOLD}${CYAN}▶ ${INVERT} ${sec.title} ${RESET}\n`;
-        out += `    ${DIM}${sec.summary}${RESET}\n\n`;
-      } else {
-        out += `    ${BOLD}${sec.title}${RESET}\n`;
-        out += `    ${DIM}${sec.summary}${RESET}\n\n`;
-      }
-    });
-
-    out += `\n${DIM}${'─'.repeat(Math.min(termWidth - 2, 70))}${RESET}\n`;
-    out += `${BOLD}[↑/↓ or j/k]${RESET} Navigate   ${BOLD}[Enter]${RESET} Read   ${BOLD}[q / Ctrl+C]${RESET} Exit\n`;
-
-    process.stdout.write(out);
-  }
-
-  function renderReader() {
-    const sec = DOC_SECTIONS[selectedIndex];
-    const termHeight = Math.max(process.stdout.rows || 24, 15);
-    const termWidth = Math.max(process.stdout.columns || 80, 60);
-    const contentRows = termHeight - 8;
-
-    const visibleLines = sec.content.slice(scrollOffset, scrollOffset + contentRows);
-
-    let out = CLEAR;
-    out += `${CYAN}${BOLD}⚛️  react-html :: ${sec.title}${RESET}\n`;
-    out += `${DIM}${'═'.repeat(Math.min(termWidth - 2, 70))}${RESET}\n\n`;
-
-    for (const line of visibleLines) {
-      out += formatLine(line) + '\n';
-    }
-
-    // Fill blank lines if content is short
-    for (let i = visibleLines.length; i < contentRows; i++) {
-      out += '\n';
-    }
-
-    const maxScroll = Math.max(0, sec.content.length - contentRows);
-    const scrollInfo = maxScroll > 0 ? ` [Line ${scrollOffset + 1}/${sec.content.length}]` : '';
-
-    out += `\n${DIM}${'─'.repeat(Math.min(termWidth - 2, 70))}${RESET}\n`;
-    out += `${BOLD}[↑/↓ or j/k]${RESET} Scroll${scrollInfo}   ${BOLD}[b / Esc]${RESET} Back to Menu   ${BOLD}[q]${RESET} Quit\n`;
-
-    process.stdout.write(out);
-  }
-
-  function draw() {
-    if (viewMode === 'menu') {
-      renderMenu();
-    } else {
-      renderReader();
-    }
-  }
-
-  draw();
-
-  return new Promise((resolve) => {
-    process.stdin.on('keypress', (str, key) => {
-      if ((key.ctrl && key.name === 'c') || key.name === 'q') {
-        cleanup();
-        resolve();
-        return;
-      }
-
-      if (viewMode === 'menu') {
-        if (key.name === 'up' || key.name === 'k') {
-          selectedIndex = (selectedIndex - 1 + DOC_SECTIONS.length) % DOC_SECTIONS.length;
-          draw();
-        } else if (key.name === 'down' || key.name === 'j') {
-          selectedIndex = (selectedIndex + 1) % DOC_SECTIONS.length;
-          draw();
-        } else if (key.name === 'return' || key.name === 'space') {
-          viewMode = 'reader';
-          scrollOffset = 0;
-          draw();
-        }
-      } else if (viewMode === 'reader') {
-        const sec = DOC_SECTIONS[selectedIndex];
-        const termHeight = Math.max(process.stdout.rows || 24, 15);
-        const contentRows = termHeight - 8;
-        const maxScroll = Math.max(0, sec.content.length - contentRows);
-
-        if (key.name === 'escape' || key.name === 'b' || key.name === 'backspace') {
-          viewMode = 'menu';
-          draw();
-        } else if (key.name === 'up' || key.name === 'k') {
-          if (scrollOffset > 0) {
-            scrollOffset--;
-            draw();
-          }
-        } else if (key.name === 'down' || key.name === 'j') {
-          if (scrollOffset < maxScroll) {
-            scrollOffset++;
-            draw();
-          }
-        } else if (key.name === 'pageup') {
-          scrollOffset = Math.max(0, scrollOffset - 5);
-          draw();
-        } else if (key.name === 'pagedown') {
-          scrollOffset = Math.min(maxScroll, scrollOffset + 5);
-          draw();
-        }
-      }
-    });
-  });
-}
-

package/src/client/hydrate.ts

@@ -1,84 +0,0 @@
-import React, { ComponentType } from 'react';
-import { hydrateRoot, createRoot } from 'react-dom/client';
-
-export type ClientDirective = 'load' | 'idle' | 'visible';
-
-export function hydrateIsland(
-  islandName: string,
-  Component: ComponentType<any>
-): void {
-  if (typeof window === 'undefined') return;
-
-  const mountElements = document.querySelectorAll<HTMLElement>(`[data-island="${islandName}"]`);
-
-  mountElements.forEach((el) => {
-    // Prevent double hydration
-    if (el.hasAttribute('data-hydrated')) return;
-
-    const rawProps = el.getAttribute('data-props');
-    let props: Record<string, unknown> = {};
-    if (rawProps) {
-      try {
-        props = JSON.parse(rawProps);
-      } catch (err) {
-        console.error(`[react-html] Failed to parse props for island "${islandName}":`, err);
-      }
-    }
-
-    const directive = (el.getAttribute('data-client') || 'load') as ClientDirective;
-
-    const doHydrate = () => {
-      if (el.hasAttribute('data-hydrated')) return;
-      el.setAttribute('data-hydrated', 'true');
-
-      try {
-        hydrateRoot(el, React.createElement(Component, props), {
-          onRecoverableError(error) {
-            // Suppress non-breaking hydration difference warnings
-            console.debug(`[react-html] Island "${islandName}" hydration note:`, error);
-          }
-        });
-      } catch (err) {
-        console.warn(`[react-html] Hydration error on island "${islandName}", recovering with client mount:`, err);
-        const root = createRoot(el);
-        root.render(React.createElement(Component, props));
-      }
-    };
-
-    switch (directive) {
-      case 'idle': {
-        if ('requestIdleCallback' in window) {
-          (window as any).requestIdleCallback(doHydrate);
-        } else {
-          setTimeout(doHydrate, 200);
-        }
-        break;
-      }
-      case 'visible': {
-        if ('IntersectionObserver' in window) {
-          const observer = new IntersectionObserver((entries, obs) => {
-            entries.forEach((entry) => {
-              if (entry.isIntersecting) {
-                obs.disconnect();
-                doHydrate();
-              }
-            });
-          });
-          observer.observe(el);
-        } else {
-          doHydrate();
-        }
-        break;
-      }
-      case 'load':
-      default: {
-        if (document.readyState === 'loading') {
-          window.addEventListener('DOMContentLoaded', doHydrate, { once: true });
-        } else {
-          doHydrate();
-        }
-        break;
-      }
-    }
-  });
-}

package/src/core/bundler.ts

@@ -1,122 +0,0 @@
-import * as esbuild from 'esbuild';
-import fs from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { IslandInstance } from './island-registry.js';
-
-export interface BundlerOptions {
-  outDir: string;
-  minify?: boolean;
-}
-
-export async function bundleIslands(
-  islands: IslandInstance[],
-  options: BundlerOptions
-): Promise<string[]> {
-  const { outDir, minify = true } = options;
-  const islandsOutputDir = path.join(outDir, 'assets', 'islands');
-  await fs.mkdir(islandsOutputDir, { recursive: true });
-
-  const tempDir = path.resolve(process.cwd(), '.react-html/temp-islands');
-  await fs.mkdir(tempDir, { recursive: true });
-
-  const uniqueIslandsMap = new Map<string, IslandInstance>();
-  for (const island of islands) {
-    if (!uniqueIslandsMap.has(island.name)) {
-      uniqueIslandsMap.set(island.name, island);
-    }
-  }
-
-  const bundledFiles: string[] = [];
-
-  // Locate hydrate module
-  const currentDir = import.meta.dirname || path.dirname(fileURLToPath(import.meta.url));
-  let hydratePath = path.resolve(currentDir, '../client/hydrate.js');
-  if (!existsSync(hydratePath)) {
-    hydratePath = path.resolve(currentDir, '../client/hydrate.ts');
-  }
-
-  let islandClientPath = path.resolve(currentDir, './island-client.js');
-  if (!existsSync(islandClientPath)) {
-    islandClientPath = path.resolve(currentDir, './island-client.ts');
-  }
-
-  for (const [name, island] of uniqueIslandsMap.entries()) {
-    let resolvedEntry = island.entryPath;
-    if (resolvedEntry.startsWith('file://')) {
-      resolvedEntry = fileURLToPath(resolvedEntry);
-    } else {
-      resolvedEntry = path.resolve(resolvedEntry);
-    }
-
-    try {
-      await fs.access(resolvedEntry);
-    } catch {
-      console.warn(`[react-html] Warning: Island source file not found for "${name}" at "${resolvedEntry}". Skipping client bundle.`);
-      continue;
-    }
-
-    // Create a virtual client entrypoint for this island
-    const virtualEntryFile = path.join(tempDir, `${name}.entry.ts`);
-    const virtualEntryCode = `
-import React from 'react';
-import { hydrateIsland } from ${JSON.stringify(hydratePath)};
-import * as Module from ${JSON.stringify(resolvedEntry)};
-
-const raw = Module.default || Module[${JSON.stringify(name)}] || Module;
-const Component = (raw && raw.__rawComponent) ? raw.__rawComponent : raw;
-
-hydrateIsland(${JSON.stringify(name)}, Component);
-`;
-    await fs.writeFile(virtualEntryFile, virtualEntryCode, 'utf8');
-
-    const outfile = path.join(islandsOutputDir, `${name}.js`);
-
-    await esbuild.build({
-      entryPoints: [virtualEntryFile],
-      outfile,
-      bundle: true,
-      format: 'esm',
-      platform: 'browser',
-      target: ['es2022'],
-      minify,
-      treeShaking: true,
-      define: {
-        'process.env.NODE_ENV': '"production"'
-      },
-      alias: {
-        'react-html': islandClientPath
-      },
-      plugins: [
-        {
-          name: 'redirect-react-html-imports',
-          setup(build) {
-            // Redirect any import of react-html or root index to island-client
-            build.onResolve({ filter: /(react-html|(\/|\\)(src|dist)(\/|\\)index(\.js|\.mjs|\.ts)?)$/ }, () => {
-              return { path: islandClientPath };
-            });
-          }
-        }
-      ],
-      loader: {
-        '.tsx': 'tsx',
-        '.ts': 'ts',
-        '.jsx': 'jsx',
-        '.js': 'js',
-        '.css': 'empty'
-      }
-    });
-
-    bundledFiles.push(outfile);
-  }
-
-  // Cleanup virtual entry files
-  try {
-    await fs.rm(tempDir, { recursive: true, force: true });
-  } catch {
-    // Ignore cleanup error
-  }
-
-  return bundledFiles;
-}

package/src/core/formatter.ts

@@ -1,92 +0,0 @@
-/**
- * Robust HTML formatter to output clean, readable HTML
- * Preserves exact inner markup inside reactive islands to ensure seamless React hydration.
- */
-export function formatHtml(html: string): string {
-  // Extract and preserve island contents verbatim
-  const preservedIslands: string[] = [];
-  let clean = html.replace(
-    /<!--__ISLAND_START__-->([\s\S]*?)<!--__ISLAND_END__-->/g,
-    (_, inner) => {
-      const idx = preservedIslands.length;
-      preservedIslands.push(inner);
-      return `%%REACT_HTML_ISLAND_${idx}%%`;
-    }
-  );
-
-  // Strip React comment artifacts outside islands if any
-  clean = clean.replace(/<!-- -->/g, '');
-
-  const tokens = clean.split(/(<[^>]+>)/g).filter((t) => t.trim().length > 0);
-  let formatted = '';
-  let indent = 0;
-  const indentStr = '  ';
-
-  // Void tags that don't need closing or indentation changes
-  const voidTags = new Set([
-    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
-    'link', 'meta', 'param', 'source', 'track', 'wbr', '!doctype'
-  ]);
-
-  // Tags where content is typically kept on the same line if brief
-  const inlineTags = new Set([
-    'title', 'span', 'strong', 'em', 'b', 'i', 'code', 'small', 'sub', 'sup'
-  ]);
-
-  for (let i = 0; i < tokens.length; i++) {
-    const token = tokens[i].trim();
-
-    if (token.startsWith('<!DOCTYPE') || token.startsWith('<!doctype')) {
-      formatted += token + '\n';
-      continue;
-    }
-
-    if (token.startsWith('</')) {
-      // Closing tag
-      const match = token.match(/<\/([a-zA-Z0-9\-]+)/);
-      const tagName = match ? match[1].toLowerCase() : '';
-
-      indent = Math.max(0, indent - 1);
-      formatted += indentStr.repeat(indent) + token + '\n';
-    } else if (token.startsWith('<') && !token.startsWith('<!--')) {
-      // Opening or self-closing tag
-      const match = token.match(/<([a-zA-Z0-9\-]+)/);
-      const tagName = match ? match[1].toLowerCase() : '';
-      const isSelfClosing = token.endsWith('/>') || voidTags.has(tagName);
-
-      // Check if next token is text and next-next token is closing tag
-      if (
-        inlineTags.has(tagName) &&
-        i + 2 < tokens.length &&
-        !tokens[i + 1].trim().startsWith('<') &&
-        tokens[i + 2].trim().toLowerCase() === `</${tagName}>`
-      ) {
-        const text = tokens[i + 1].trim();
-        const closeTag = tokens[i + 2].trim();
-        formatted += indentStr.repeat(indent) + `${token}${text}${closeTag}\n`;
-        i += 2;
-        continue;
-      }
-
-      formatted += indentStr.repeat(indent) + token + '\n';
-
-      if (!isSelfClosing) {
-        indent++;
-      }
-    } else {
-      // Standalone text content
-      formatted += indentStr.repeat(indent) + token + '\n';
-    }
-  }
-
-  // Restore preserved island markup untouched
-  let finalHtml = formatted.replace(
-    /%%REACT_HTML_ISLAND_(\d+)%%/g,
-    (_, idxStr) => {
-      const idx = parseInt(idxStr, 10);
-      return preservedIslands[idx] ?? '';
-    }
-  );
-
-  return finalHtml.trim() + '\n';
-}

package/src/core/island-client.ts

@@ -1,23 +0,0 @@
-import React, { ComponentType, ReactNode } from 'react';
-
-export function Island<P extends Record<string, unknown>>({
-  component: Component,
-  props = {} as P,
-  children
-}: {
-  component: ComponentType<P>;
-  props?: P;
-  children?: ReactNode;
-  [key: string]: unknown;
-}): React.ReactElement {
-  return React.createElement(Component, props, children);
-}
-
-export function island<P extends Record<string, unknown>>(
-  Component: ComponentType<P>,
-  _sourcePath?: string,
-  _customName?: string
-): ComponentType<P> {
-  return Component;
-}
-

package/src/core/island-registry.ts

@@ -1,35 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-
-export interface IslandInstance {
-  id: string;
-  name: string;
-  entryPath: string;
-  props: Record<string, unknown>;
-  clientDirective?: 'load' | 'idle' | 'visible';
-}
-
-export interface RenderContext {
-  pagePath: string;
-  islands: IslandInstance[];
-}
-
-const GLOBAL_STORAGE_KEY = Symbol.for('__react_html_render_context__');
-
-const storage: AsyncLocalStorage<RenderContext> =
-  (globalThis as any)[GLOBAL_STORAGE_KEY] ||
-  ((globalThis as any)[GLOBAL_STORAGE_KEY] = new AsyncLocalStorage<RenderContext>());
-
-export function runWithRenderContext<T>(context: RenderContext, fn: () => T): T {
-  return storage.run(context, fn);
-}
-
-export function getCurrentRenderContext(): RenderContext | undefined {
-  return storage.getStore();
-}
-
-export function registerIslandInContext(island: IslandInstance): void {
-  const ctx = storage.getStore();
-  if (ctx) {
-    ctx.islands.push(island);
-  }
-}

package/src/core/island.tsx

@@ -1,110 +0,0 @@
-import React, { ComponentType, ReactNode } from 'react';
-import { renderToString } from 'react-dom/server';
-import { registerIslandInContext } from './island-registry.js';
-
-let islandCounter = 0;
-
-export interface IslandProps<P = Record<string, unknown>> {
-  /** Explicit island name (optional) */
-  name?: string;
-  /** Path to the island component file (relative or absolute) */
-  src?: string;
-  /** The React component to render */
-  component: ComponentType<P>;
-  /** Props passed to the component */
-  props?: P;
-  /** Client hydration directive (default: 'load') */
-  client?: 'load' | 'idle' | 'visible';
-  /** Optional wrapper tag, default: 'div' */
-  as?: string;
-  className?: string;
-  style?: React.CSSProperties;
-  children?: ReactNode;
-}
-
-export function Island<P extends Record<string, unknown>>({
-  name,
-  src,
-  component: Component,
-  props = {} as P,
-  client = 'load',
-  as: Tag = 'div',
-  className,
-  style,
-  children
-}: IslandProps<P>): React.ReactElement {
-  const componentName =
-    name ||
-    (Component as any).__islandName ||
-    Component.displayName ||
-    Component.name ||
-    'AnonymousIsland';
-
-  const islandId = `island-${++islandCounter}`;
-
-  // If src is specified or attached to component
-  const entryPath = src || (Component as any).__islandPath || '';
-
-  registerIslandInContext({
-    id: islandId,
-    name: componentName,
-    entryPath,
-    props,
-    clientDirective: client
-  });
-
-  const Wrapper = Tag as any;
-
-  // Use renderToString for the island's inner tree to produce hydration-compatible SSR markup
-  const innerHtml = renderToString(React.createElement(Component, props, children));
-
-  return (
-    <Wrapper
-      data-island={componentName}
-      data-island-id={islandId}
-      data-props={JSON.stringify(props)}
-      data-client={client}
-      className={className}
-      style={style}
-      dangerouslySetInnerHTML={{ __html: `<!--__ISLAND_START__-->${innerHtml}<!--__ISLAND_END__-->` }}
-    />
-  );
-}
-
-/**
- * Helper to wrap any React component into a ready-to-use Island component
- * Example:
- *   export const Counter = island(CounterComponent, import.meta.url, 'Counter');
- *   // In page: <Counter initialCount={5} />
- */
-export function island<P extends Record<string, unknown>>(
-  Component: ComponentType<P>,
-  sourcePath: string,
-  customName?: string
-): ComponentType<P & { client?: 'load' | 'idle' | 'visible'; as?: string; className?: string; style?: React.CSSProperties }> {
-  const resolvedName = customName || Component.displayName || Component.name || 'AnonymousIsland';
-  (Component as any).__islandPath = sourcePath;
-  (Component as any).__islandName = resolvedName;
-
-  const IslandWrapper = (props: P & { client?: 'load' | 'idle' | 'visible'; as?: string; className?: string; style?: React.CSSProperties }) => {
-    const { client, as, className, style, ...componentProps } = props;
-    return (
-      <Island
-        name={resolvedName}
-        src={sourcePath}
-        component={Component}
-        props={componentProps as P}
-        client={client}
-        as={as}
-        className={className}
-        style={style}
-      />
-    );
-  };
-
-  IslandWrapper.displayName = `Island(${resolvedName})`;
-  (IslandWrapper as any).__islandPath = sourcePath;
-  (IslandWrapper as any).__islandName = resolvedName;
-  (IslandWrapper as any).__rawComponent = Component;
-  return IslandWrapper;
-}