linecraft 0.2.3 → 0.2.5

package/README.md

@@ -41,6 +41,49 @@ r.set(
 r.destroy(true);
 ```
 
+## Terminal Management Features
+
+Linecraft provides advanced terminal management capabilities that go beyond basic terminal logging:
+
+### Color-Aware Line Wrapping
+
+Unlike basic terminal output, Linecraft's text wrapping is **fully ANSI-aware**. When text wraps across multiple lines, ANSI color codes are preserved and correctly re-applied to each wrapped line. This means:
+
+- **Color preservation**: Colored text maintains its styling across line breaks
+- **Accurate width calculation**: Wrapping is based on visible character width, not raw string length
+- **Smart word breaking**: Text never breaks mid-word, ensuring readability
+- **Multi-line styling**: Complex styled text (like error codes with underlines) wraps correctly
+
+This is especially important for components like `CodeDebug`, where error messages with colored error codes need to wrap across multiple lines while maintaining their visual styling.
+
+### ANSI Code Handling
+
+Linecraft correctly handles ANSI escape sequences throughout the rendering pipeline:
+
+- **Width measurement**: All width calculations account for ANSI codes (colors, styles, cursor movements)
+- **Text splitting**: When truncating or splitting text, ANSI codes are preserved and re-applied
+- **Grid layouts**: Grid components correctly measure and align ANSI-styled content
+- **Text alignment**: Alignment operations work correctly with styled text
+
+### Terminal State Management
+
+Linecraft manages terminal state to prevent common terminal UI issues:
+
+- **Auto-wrap disabled**: Prevents unwanted line breaks from terminal auto-wrapping
+- **Cursor positioning**: Precise cursor control using absolute positioning
+- **Viewport awareness**: Only renders visible content within the terminal viewport
+- **Clean restoration**: Properly restores terminal state on cleanup
+
+### Responsive Layouts
+
+Components automatically adapt to terminal size changes:
+
+- **Grid layouts**: Flex columns adjust to available width
+- **Text wrapping**: Wraps at appropriate boundaries based on terminal width
+- **Component sizing**: Components receive updated `availableWidth` context on resize
+
+These features make Linecraft suitable for building complex, interactive terminal UIs that work reliably across different terminal sizes and configurations.
+
 ## Performance
 
 Linecraft is built for high-performance terminal rendering from Node.js. The renderer includes several optimizations to minimize terminal updates and CPU usage:
@@ -99,6 +142,36 @@ ref.delete(); // Remove it
 r.destroy(true); // Clean up and restore terminal (true = clear first)
 ```
 
+## Semantic Themes
+
+Linecraft includes a built-in semantic theme system that automatically adapts colors based on whether the terminal is in light or dark mode. Instead of hardcoding ANSI colors, you can use semantic tokens:
+
+- `base`: The default text color (gray in both themes)
+- `muted`: Dimmed text for line numbers or separators (dimmed white on dark, dimmed gray on light)
+- `highlight`: Emphasized text (white on dark, bold black on light)
+- `accent`: Primary accent color (bold blue in both themes)
+- `location`: For file paths and locations (magenta in both themes)
+- `success`: Success messages (bright green on dark, green on light)
+- `warning`: Warning messages (bright yellow on dark, bright magenta on light)
+- `error`: Error messages (bright red on dark, red on light)
+- `info`: Informational messages (blue in both themes)
+
+You can use these tokens anywhere a `Color` is expected:
+
+```typescript
+import { Styled } from 'linecraft';
+
+// Automatically uses appropriate color based on terminal theme
+const text = Styled({ color: 'base' }, 'Auto-themed text');
+const error = Styled({ color: 'error' }, 'Error message');
+const path = Styled({ color: 'location' }, '/path/to/file.ts');
+
+// You can also resolve them manually if needed
+import { autoColor, autoStyle } from 'linecraft';
+const color = autoColor('warning'); // Returns just the color
+const style = autoStyle('accent'); // Returns full TextStyle (color, bold, etc.)
+```
+
 ## Components
 
 ### Styled
@@ -150,7 +223,7 @@ r.set(Section(
 
 ### CodeDebug
 
-Display code errors and warnings with line numbers, context, and clickable file paths.
+Display code errors and warnings with line numbers, context, and clickable file paths. Perfect for linters, compilers, and development tools that need to show diagnostic information.
 
 ![CodeDebug Example](https://raw.githubusercontent.com/matthew-dean/linecraft/main/docs/examples/code-debug.gif)
 
@@ -166,6 +239,8 @@ r.set(CodeDebug({
   lineBefore: '  async function load() {',
   lineAfter: '    return process(result);',
   message: 'Type error: fetchData is not defined',
+  errorCode: 'typescript(2304)', // Optional: error code with underline
+  shortMessage: 'not defined', // Optional: short message connected to underline
   filePath: 'src/loaders/data.ts',
   fullPath: '/absolute/path/to/src/loaders/data.ts',
   baseDir: process.cwd(),
@@ -174,12 +249,14 @@ r.set(CodeDebug({
 ```
 
 **Features:**
-- Automatic line number coloring (adapts to dark/light terminals)
-- Responsive truncation with ellipsis
-- Curved underlines for error ranges
-- Message wrapping
-- Clickable file paths (OSC 8 links)
-- Context lines (before/after)
+- **OSC 8 Hyperlinks**: File paths are clickable in modern terminals (VS Code, iTerm2, etc.). Ctrl+Click (or Cmd+Click) opens the file at the correct line and column.
+- **Smart Line Overflow**: Long code lines automatically truncate with ellipsis while keeping the error range visible. Supports ellipsis at start, end, or both sides.
+- **Error Range Highlighting**: The error range (startColumn to endColumn) is highlighted with a brighter color for easy identification.
+- **Context Lines**: Show lines before and after the error for better context (slightly dimmed for visual hierarchy).
+- **Message Wrapping**: Long error messages wrap across multiple lines while preserving ANSI styling and color codes.
+- **Terminal Theme Adaptation**: Line numbers and colors adapt to dark/light terminal themes automatically.
+- **Curved Underlines**: Visual indicators with curved edges (┖─┚) point to the exact error location, with optional T-bar for short messages.
+- **Responsive Layout**: Automatically adjusts to terminal width, truncating paths and code as needed.
 
 ### Spinner
 

package/lib/components/code-debug.d.ts

@@ -15,8 +15,14 @@ export interface CodeDebugOptions {
     errorLine: string;
     /** Source code line after the error line (optional) */
     lineAfter?: string | null;
-    /** Error or warning message */
+    /** Error or warning message (long message shown at top) */
     message: string;
+    /** Error code/preamble to show before message (e.g., "eslint-plugin-unicorn(no-useless-length-check)") (optional) */
+    errorCode?: string;
+    /** Short message to show connected to underline (optional) */
+    shortMessage?: string;
+    /** Placement of short message: 'left' or 'right' (default: 'right', auto: 'left' when target is near end of long line) */
+    shortMessagePlacement?: 'left' | 'right' | 'auto';
     /** Short file path to display */
     filePath: string;
     /** Full resolved file path for clickable link */

package/lib/components/code-debug.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-debug.d.ts","sourceRoot":"","sources":["../../src/components/code-debug.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAShE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiID;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA+O9D"}
+{"version":3,"file":"code-debug.d.ts","sourceRoot":"","sources":["../../src/components/code-debug.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAWhE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,qHAAqH;IACrH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0HAA0H;IAC1H,qBAAqB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IAClD,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA8Y9D"}