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

npm install @ape-egg/codie

Usage

Basic Syntax Highlighting

<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

import codie from '@ape-egg/codie';

const editor = codie('[codie]');
editor.editable = true;
editor.numberedRows = true;

Live Preview with onEdit

const outputRef = document.querySelector('output');

const editor = codie('[codie]');
editor.editable = true;
editor.onEdit = ({ formatted, raw }) => {
  outputRef.innerHTML = formatted;
};

Language-Specific Highlighting

<!-- 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

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

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:

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;
};

<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