@ape-egg/codie 0.1.0

package/README.md

@@ -0,0 +1,232 @@
+# Codie
+
+Modular code display and editing package for the web.
+
+## Overview
+
+**Codie** is a lightweight, modular code highlighter and editor that bridges the gap between static code display and full in-browser IDEs. Built with vanilla JavaScript, it provides syntax highlighting, live editing, and seamless integration with reactive frameworks like Vibe.
+
+**Vision:** Codie is a spectrum from static highlighter to full in-browser IDE:
+
+```
+Minimal (vanilla)     →     Editor     →     Full REPL (vibe-powered)
+highlight + format    +editable             +live output, inspect,
+                      +numberedRows          visual editing, zero-build HMR
+```
+
+## Features
+
+### Core Features
+
+- **Syntax Highlighting**: HTML, CSS, and JavaScript with language-aware highlighting
+- **Editable Mode**: Transform static code into a live editor with textarea overlay
+- **Line Numbers**: Optional numbered rows for code reference
+- **Template Support**: Use `<template codie>` to preserve HTML without browser parsing
+- **Language Modes**: Granular control via attributes (`highlight-html`, `highlight-css`, `highlight-js`)
+- **Dark/Light Themes**: Toggle with `[dark]` attribute
+- **Runtime State Toggle**: Change features dynamically via `codieRef.editable`, `codieRef.numberedRows`
+
+### Editing Features
+
+- **Tab Handling**: Tab key inserts 2 spaces
+- **Multi-line Indent**: Select multiple lines + Tab indents all
+- **Outdent**: Shift+Tab removes indentation
+- **Live Preview**: `onEdit` callback fires on every change
+- **Error Handling**: `onError` callback for execution failures
+
+## Installation
+
+```bash
+npm install @ape-egg/codie
+```
+
+## Usage
+
+### Basic Syntax Highlighting
+
+```html
+<link rel="stylesheet" href="@ape-egg/codie/codie.css" />
+<script type="module">
+  import codie from '@ape-egg/codie';
+
+  codie('[codie]');
+</script>
+
+<template codie>
+  <div>
+    <p>Hello, world!</p>
+  </div>
+</template>
+```
+
+### Editable Code with Line Numbers
+
+```js
+import codie from '@ape-egg/codie';
+
+const editor = codie('[codie]');
+editor.editable = true;
+editor.numberedRows = true;
+```
+
+### Live Preview with onEdit
+
+```js
+const outputRef = document.querySelector('output');
+
+const editor = codie('[codie]');
+editor.editable = true;
+editor.onEdit = ({ formatted, raw }) => {
+  outputRef.innerHTML = formatted;
+};
+```
+
+### Language-Specific Highlighting
+
+```html
+<!-- Only highlight HTML -->
+<template codie highlight-html>...</template>
+
+<!-- Only highlight CSS -->
+<template codie highlight-css>...</template>
+
+<!-- Only highlight JavaScript -->
+<template codie highlight-js>...</template>
+
+<!-- Highlight all languages (default) -->
+<template codie>...</template>
+```
+
+## API
+
+### `codie(selector | element | config)`
+
+Initialize a codie instance.
+
+**Parameters:**
+- `selector` (string): Query selector for codie element
+- `element` (Element): DOM element reference
+- `config` (object): Configuration object with optional `editable`, `numberedRows`, `foldable` properties
+
+**Returns:** Codie instance proxy
+
+### Instance Properties
+
+```js
+const editor = codie('[codie]');
+
+// Get/set code content
+editor.code; // Get current code
+editor.code = '<div>New code</div>'; // Set code (updates display + textarea)
+
+// Toggle features
+editor.editable = true; // Enable editing
+editor.numberedRows = true; // Show line numbers
+editor.foldable = false; // Disable code folding (experimental)
+
+// Callbacks
+editor.onEdit = ({ formatted, raw }) => {
+  // formatted: cleaned up for display
+  // raw: exact code content
+};
+
+editor.onError = (error) => {
+  // Handle errors during editing
+};
+```
+
+### Exported Utilities
+
+```js
+import {
+  highlightHTML,
+  highlightJS,
+  highlightCSS,
+  highlightJSRaw,
+  escapeHTML,
+  unescapeHTML,
+  formatDocument,
+  normalizeInlineWhitespace,
+  ATTR,
+  CLASS,
+} from '@ape-egg/codie';
+```
+
+## Attributes
+
+### Container Attributes
+
+- `codie` - Marks element as codie instance
+- `dehydrate` - Skip initialization (for documentation)
+- `highlight-html` - Enable HTML highlighting only
+- `highlight-css` - Enable CSS highlighting only
+- `highlight-js` - Enable JavaScript highlighting only
+- `dark` - Apply dark theme
+
+### Runtime Attributes (applied by codie)
+
+- `codie-editable` - Applied when editable mode is active
+- `codie-numbered` - Applied when line numbers are shown
+- `codie-foldable` - Applied when folding is enabled (experimental)
+
+## Architecture
+
+Codie uses a **layered approach** with CSS Grid:
+
+1. **Display Layer** (`<pre>`) - Syntax-highlighted code
+2. **Textarea Layer** (optional) - Editable overlay when `editable = true`
+3. **Line Numbers** (optional) - Positioned overlay when `numberedRows = true`
+
+All layers are synchronized via a reactive proxy that updates the DOM when properties change.
+
+## Vibe Integration
+
+Codie pairs naturally with Vibe for live, reactive code editing:
+
+```js
+import { init } from '@ape-egg/vibe';
+import codie from '@ape-egg/codie';
+
+init({ output: '' });
+
+const editor = codie('[codie]');
+editor.editable = true;
+editor.onEdit = ({ formatted }) => {
+  $.output = formatted;
+};
+```
+
+```html
+<template codie>
+  <p>Edit me!</p>
+</template>
+
+<output>@[output]</output>
+```
+
+## Roadmap
+
+### Implemented
+
+- ✓ Syntax highlighting (HTML, CSS, JS)
+- ✓ Editable mode with textarea overlay
+- ✓ Line numbers
+- ✓ Tab handling (insert spaces, multi-line indent, outdent)
+- ✓ onEdit/onError callbacks
+- ✓ Template support
+- ✓ Language modes
+- ✓ Dark/light themes
+
+### Planned
+
+- Self-documenting REPL (execute code from editor)
+- Smart script execution (only re-run when changed)
+- Vibe exclusion zones (prevent parent vibe from watching preview)
+- Hot state preservation (preserve state across re-execution)
+- Code folding (deferred due to complexity with editable mode)
+- Inspect mode (click preview element to highlight code)
+- Visual editing (drag-drop reorder in preview)
+
+## License
+
+MIT

package/codie.css

@@ -0,0 +1,7 @@
+/* Codie CSS Registry */
+@import "./theme.css";
+@import "./structure.css";
+@import "./highlight-html.css";
+@import "./highlight-css.css";
+@import "./highlight-js.css";
+@import "./highlight-json.css";

package/codie.js

@@ -0,0 +1,252 @@
+// Codie - Modular Code Display & Editing
+import { ATTR, CLASS } from './constants.js';
+import {
+  highlightHTML,
+  highlightJS,
+  highlightCSS,
+  highlightJSON,
+  highlightJSRaw,
+  highlightCSSOnly,
+  highlightJSOnly,
+} from './highlight.js';
+import {
+  escapeHTML,
+  unescapeHTML,
+  formatDocument,
+  dedent,
+  normalizeInlineWhitespace,
+  cleanupBooleanAttrs,
+} from './format.js';
+import { initNumberRows, updateNumberRows } from './numberRows.js';
+import { initEditable, destroyEditable } from './editable.js';
+import { initFoldable, destroyFoldable } from './foldable.js';
+
+// Detect which languages to highlight from element attributes
+const getHighlightModes = (el) => {
+  const hasHTML = el.hasAttribute(ATTR.HIGHLIGHT_HTML);
+  const hasCSS = el.hasAttribute(ATTR.HIGHLIGHT_CSS);
+  const hasJS = el.hasAttribute(ATTR.HIGHLIGHT_JS);
+  const hasJSON = el.hasAttribute(ATTR.HIGHLIGHT_JSON);
+  const explicit = hasHTML || hasCSS || hasJS || hasJSON;
+
+  return {
+    html: !explicit || hasHTML,
+    css: !explicit || hasCSS,
+    js: !explicit || hasJS,
+    json: !explicit || hasJSON,
+  };
+};
+
+// Highlight code content based on enabled modes
+const highlight = (code, modes, options = {}) => {
+  const escaped = escapeHTML(code);
+
+  // When all modes are enabled (no explicit attribute), detect JSON by content
+  const looksLikeJSON = /^\s*[{\[]/.test(code);
+
+  // JSON takes priority over HTML when content looks like JSON
+  if (modes.json && looksLikeJSON) {
+    return highlightJSON(escaped);
+  }
+
+  if (modes.html && !looksLikeJSON) {
+    return highlightHTML(escaped, {
+      ...options,
+      highlightJS: modes.js,
+      highlightCSS: modes.css,
+    });
+  }
+
+  // Fallback: explicit mode selected or no HTML detected
+  if (modes.json && !modes.html) {
+    return highlightJSON(escaped);
+  }
+
+  let result = escaped;
+  if (modes.js) result = highlightJSOnly(result);
+  if (modes.css) result = highlightCSSOnly(result);
+  return result;
+};
+
+// Toggle a feature on the instance
+const toggleFeature = (instance, feature, enabled) => {
+  const { el, display, modes } = instance;
+
+  switch (feature) {
+    case 'numberedRows':
+      if (enabled && !instance.lineNumbers) {
+        instance.lineNumbers = initNumberRows(el, instance._code);
+        el.setAttribute(ATTR.NUMBERED, '');
+      } else if (!enabled && instance.lineNumbers) {
+        instance.lineNumbers.remove();
+        instance.lineNumbers = null;
+        el.removeAttribute(ATTR.NUMBERED);
+      }
+      break;
+
+    case 'editable':
+      if (enabled && !instance.textarea) {
+        instance.textarea = initEditable(el, instance, instance._config);
+        el.setAttribute(ATTR.EDITABLE, '');
+      } else if (!enabled && instance.textarea) {
+        destroyEditable(instance);
+        el.removeAttribute(ATTR.EDITABLE);
+      }
+      break;
+
+    case 'foldable':
+      if (enabled && !el.hasAttribute(ATTR.FOLDABLE)) {
+        initFoldable(el, display, modes);
+        el.setAttribute(ATTR.FOLDABLE, '');
+      } else if (!enabled && el.hasAttribute(ATTR.FOLDABLE)) {
+        destroyFoldable(el, display);
+        el.removeAttribute(ATTR.FOLDABLE);
+      }
+      break;
+  }
+};
+
+// Main init function - one call per codie element
+const codie = (elOrConfig = {}) => {
+  // Determine element and config
+  let el, config;
+
+  if (elOrConfig instanceof Element) {
+    el = elOrConfig;
+    config = {};
+  } else if (typeof elOrConfig === 'string') {
+    el = document.querySelector(elOrConfig);
+    config = {};
+  } else {
+    config = elOrConfig;
+    el = document.querySelector(`[${ATTR.CODIE}]`);
+  }
+
+  if (!el) {
+    console.info('[codie] No element found');
+    return null;
+  }
+
+  // Skip dehydrated elements
+  if (el.hasAttribute(ATTR.DEHYDRATE)) {
+    return null;
+  }
+
+  const modes = getHighlightModes(el);
+  let raw = el.tagName === 'TEMPLATE' ? el.innerHTML : el.textContent;
+
+  // Decode HTML entities from template innerHTML
+  raw = unescapeHTML(raw);
+
+  // Strip empty values from boolean attributes
+  raw = cleanupBooleanAttrs(raw);
+
+  const code = dedent(raw);
+
+  // Create display layer
+  const display = document.createElement('pre');
+  display.className = `${CLASS.CODE_LAYER} ${CLASS.DISPLAY}`;
+  display.innerHTML = highlight(code, modes, {
+    preserveWhitespace: !config.foldable,
+  });
+
+  // Clear and setup element
+  el.textContent = '';
+  el.appendChild(display);
+
+  // Internal state
+  const internal = {
+    el,
+    display,
+    modes,
+    _code: code,
+    _config: { ...config },
+    textarea: null,
+    lineNumbers: null,
+    onEdit: null,
+    onError: null,
+    _editable: config.editable || false,
+    _numberedRows: config.numberedRows || false,
+    _foldable: config.foldable || false,
+    _proxy: null, // Will hold reference to proxy for editable.js
+  };
+
+  // Create reactive proxy
+  const instance = new Proxy(internal, {
+    get(target, prop) {
+      if (prop === 'code') return target._code;
+      if (prop === 'editable') return target._editable;
+      if (prop === 'numberedRows') return target._numberedRows;
+      if (prop === 'foldable') return target._foldable;
+      return target[prop];
+    },
+    set(target, prop, value) {
+      if (prop === 'code') {
+        // Decode HTML entities when setting code (same as initialization)
+        const decoded = unescapeHTML(value);
+        target._code = decoded;
+        target.display.innerHTML = highlight(decoded, target.modes, {
+          preserveWhitespace: !target._foldable,
+        });
+        if (target.lineNumbers) {
+          updateNumberRows(target.lineNumbers, decoded);
+        }
+        if (target.textarea) {
+          target.textarea.value = decoded;
+        }
+        return true;
+      }
+
+      if (prop === 'editable' && value !== target._editable) {
+        target._editable = value;
+        toggleFeature(target, 'editable', value);
+        return true;
+      }
+
+      if (prop === 'numberedRows' && value !== target._numberedRows) {
+        target._numberedRows = value;
+        toggleFeature(target, 'numberedRows', value);
+        return true;
+      }
+
+      if (prop === 'foldable' && value !== target._foldable) {
+        target._foldable = value;
+        toggleFeature(target, 'foldable', value);
+        return true;
+      }
+
+      // Fire onEdit immediately when callback is set
+      if (prop === 'onEdit' && typeof value === 'function') {
+        target.onEdit = value;
+        value({ formatted: normalizeInlineWhitespace(cleanupBooleanAttrs(target._code)), raw: target._code });
+        return true;
+      }
+
+      target[prop] = value;
+      return true;
+    },
+  });
+
+  // Store proxy reference for editable.js to access callbacks
+  internal._proxy = instance;
+
+  // Initialize features based on config
+  if (config.numberedRows) {
+    toggleFeature(internal, 'numberedRows', true);
+  }
+  if (config.editable) {
+    toggleFeature(internal, 'editable', true);
+  }
+  if (config.foldable) {
+    toggleFeature(internal, 'foldable', true);
+  }
+
+  return instance;
+};
+
+export default codie;
+
+// Export utilities for direct use
+export { highlightHTML, highlightJS, highlightCSS, highlightJSRaw };
+export { escapeHTML, unescapeHTML, formatDocument, normalizeInlineWhitespace };
+export { ATTR, CLASS };

package/constants.js

@@ -0,0 +1,228 @@
+// Codie constants - DRY naming foundation
+
+// Attribute names for codie elements
+export const ATTR = {
+  CODIE: 'codie',
+  HIGHLIGHT_HTML: 'highlight-html',
+  HIGHLIGHT_CSS: 'highlight-css',
+  HIGHLIGHT_JS: 'highlight-js',
+  HIGHLIGHT_JSON: 'highlight-json',
+  NUMBERED: 'numbered',
+  EDITABLE: 'editable',
+  FOLDABLE: 'foldable',
+  DEHYDRATE: 'dehydrate',
+}
+
+// CSS class names
+export const CLASS = {
+  // Layout layers
+  CODE_LAYER: 'codie-layer',
+  TEXTAREA: 'codie-textarea',
+  DISPLAY: 'codie-display',
+  LINE_NUMBERS: 'codie-line-numbers',
+
+  // States
+  DARK: 'codie-dark',
+  HAS_SELECTION: 'codie-has-selection',
+  FOCUSED: 'codie-focused',
+
+  // Line highlighting
+  LINE: 'codie-line',
+  LINE_HIGHLIGHT: 'codie-line-highlight',
+
+  // Folding
+  FOLD_WRAPPER: 'codie-fold-wrapper',
+  FOLD_HEADER: 'codie-fold-header',
+  FOLD_TOGGLE: 'codie-fold-toggle',
+  FOLD_LINE: 'codie-fold-line',
+  FOLD_CONTENT: 'codie-fold-content',
+  FOLD_PREVIEW: 'codie-fold-preview',
+  FOLD_OPEN: 'codie-fold-open',
+
+  // Syntax tokens - HTML
+  TAG: 'codie-tag',
+  ATTR_NAME: 'codie-attr-name',
+  ATTR_VALUE: 'codie-attr-value',
+  PUNCTUATION: 'codie-punct',
+  COMMENT: 'codie-comment',
+  TEXT: 'codie-text',
+
+  // Syntax tokens - CSS
+  CSS_SELECTOR: 'codie-css-selector',
+  CSS_PROPERTY: 'codie-css-property',
+  CSS_VALUE: 'codie-css-value',
+
+  // Syntax tokens - JS
+  JS_KEYWORD: 'codie-js-keyword',
+  JS_IMPORT: 'codie-js-import',
+  JS_STRING: 'codie-js-string',
+  JS_FUNCTION: 'codie-js-function',
+  JS_NUMBER: 'codie-js-number',
+  JS_IDENT: 'codie-js-ident',
+
+  // Syntax tokens - JSON
+  JSON_KEY: 'codie-json-key',
+  JSON_STRING: 'codie-json-string',
+  JSON_NUMBER: 'codie-json-number',
+  JSON_BOOLEAN: 'codie-json-boolean',
+  JSON_NULL: 'codie-json-null',
+
+  // Vibe-specific tokens
+  VIBE_COLOR: 'codie-vibe',
+  VIBE_VARIABLE: 'codie-vibe-var',
+}
+
+// CSS variable prefix
+export const VAR_PREFIX = '--codie-'
+
+// Void HTML elements (self-closing)
+export const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr',
+])
+
+// Attributes where the string value is meaningful (should keep empty values like attr="")
+// All other attributes are boolean-like (should be stripped to just attr when empty)
+export const VALUE_ATTRS = new Set([
+  // Global attributes
+  'class',
+  'style',
+  'id',
+  'title',
+  'lang',
+  'dir',
+  'tabindex',
+  'accesskey',
+  'slot',
+  'part',
+  'is',
+  'nonce',
+  'popover',
+  'anchor',
+
+  // Enumerated (take specific string values, not truly boolean)
+  'contenteditable',
+  'draggable',
+  'spellcheck',
+  'translate',
+  'autocapitalize',
+  'inputmode',
+  'enterkeyhint',
+  'virtualkeyboardpolicy',
+
+  // URLs and sources
+  'href',
+  'src',
+  'action',
+  'cite',
+  'data',
+  'poster',
+  'srcset',
+  'imagesrcset',
+  'formaction',
+  'ping',
+  'usemap',
+  'manifest',
+  'codebase',
+
+  // Form attributes
+  'name',
+  'type',
+  'value',
+  'placeholder',
+  'pattern',
+  'min',
+  'max',
+  'step',
+  'minlength',
+  'maxlength',
+  'size',
+  'accept',
+  'autocomplete',
+  'list',
+  'form',
+  'formmethod',
+  'formtarget',
+  'formenctype',
+  'wrap',
+  'method',
+  'enctype',
+  'for',
+  'dirname',
+
+  // Text/accessibility
+  'alt',
+  'label',
+  'summary',
+  'abbr',
+
+  // Dimensions and layout
+  'width',
+  'height',
+  'cols',
+  'rows',
+  'span',
+  'rowspan',
+  'colspan',
+  'low',
+  'high',
+  'optimum',
+
+  // Link/resource hints
+  'target',
+  'rel',
+  'hreflang',
+  'download',
+  'as',
+  'media',
+  'charset',
+  'crossorigin',
+  'integrity',
+  'loading',
+  'decoding',
+  'fetchpriority',
+  'referrerpolicy',
+  'blocking',
+  'imagesizes',
+  'sizes',
+
+  // Media
+  'preload',
+  'kind',
+  'srclang',
+
+  // Meta
+  'content',
+  'http-equiv',
+
+  // iframe/embed
+  'sandbox',
+  'allow',
+  'srcdoc',
+  'credentialless',
+
+  // Table
+  'headers',
+  'scope',
+
+  // Datetime
+  'datetime',
+
+  // Object/embed legacy
+  'coords',
+  'shape',
+])
+
+// JavaScript keywords for syntax highlighting
+export const JS_KEYWORDS = new Set([
+  'const', 'let', 'var', 'function', 'return', 'if', 'else', 'for', 'while', 'do',
+  'switch', 'case', 'break', 'continue', 'try', 'catch', 'finally', 'throw', 'new',
+  'typeof', 'instanceof', 'class', 'extends', 'default', 'async', 'await', 'yield',
+  'this', 'super', 'null', 'undefined', 'true', 'false',
+])
+
+// JavaScript import/export keywords
+export const JS_IMPORT_KEYWORDS = new Set(['import', 'export', 'from'])
+
+// JavaScript bracket characters
+export const JS_BRACKETS = new Set(['{', '}', '(', ')', '[', ']'])