linecraft 0.1.0 → 0.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 EchoKit Contributors
+Copyright (c) 2025 Linecraft Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,111 +1,384 @@
-# EchoKit
+# Linecraft
 
-High-performance terminal UI library for Node.js with Zig backend.
-
-EchoKit provides a friendly TypeScript API while leveraging Zig's speed and efficiency for terminal operations like diffing, ANSI cursor movement, buffering, and throttling.
-
-## Features
-
-- **High Performance**: Zig backend handles all performance-critical operations
-- **Automatic Batching**: Updates are automatically batched and throttled
-- **Dynamic Regions**: Regions expand automatically as you add lines
-- **Simple API**: Clean, intuitive TypeScript interface
-- **Components**: Built-in progress bars and spinners
+Build terminal UIs with components. Create progress bars, spinners, code error displays, and responsive layouts without the hassle.
 
 ## Installation
 
 ```bash
-pnpm install echokit
+npm install linecraft
+# or
+pnpm add linecraft
 ```
 
 ## Quick Start
 
-### Basic Progress Bar
-
 ```typescript
-import { createRegion, createProgressBar } from 'echokit';
+import { Region, Styled, Spinner, Section, Grid } from 'linecraft';
+
+const r = Region();
+
+// Set some content
+r.set(
+  Section({ title: 'Hello' },
+    Grid({ template: [20, '1*'], columnGap: 2 },
+      Styled({ color: 'cyan' }, 'Status:'),
+      Styled({ color: 'green' }, 'Ready')
+    )
+  )
+);
+
+// Add a spinner
+r.set(
+  Section({ title: 'Loading' },
+    Grid({ template: [3, '1*'], columnGap: 1 },
+      Spinner({ style: 'classic-dots', color: 'green' }),
+      Styled({ color: 'white' }, 'Installing packages...')
+    )
+  )
+);
+
+// Clean up when done
+r.destroy(true);
+```
+
+## Performance
+
+Linecraft is built for high-performance terminal rendering from Node.js. The renderer includes several optimizations to minimize terminal updates and CPU usage:
+
+### Frame Diffing
+Only updates lines that actually changed. Unchanged lines are skipped entirely, reducing terminal writes by up to 90% for static content.
+
+### Render Throttling
+Uses high-resolution timing (`process.hrtime.bigint()`) to limit frame rate (default: 30 FPS). Prevents excessive rendering during rapid updates while maintaining smooth animations.
+
+### Batched ANSI Operations
+All ANSI escape sequences are batched into a single `stdout.write()` call per frame, minimizing syscalls and improving throughput.
+
+### Efficient Cursor Movement
+Optimized ANSI cursor positioning that only moves when necessary. The renderer tracks viewport state to avoid redundant cursor movements.
+
+### Viewport Management
+Only renders visible lines within the terminal viewport. Content that extends beyond the viewport is efficiently managed without unnecessary rendering.
 
-const region = createRegion({ width: 80 });
-const progress = createProgressBar(region, 1, {
-  label: 'Installing packages',
-  width: 50,
+### Auto-Wrap Disabled
+Disables terminal auto-wrap to prevent unwanted line breaks, ensuring precise control over terminal output layout.
+
+These optimizations make Linecraft suitable for real-time terminal UIs, progress displays, and animated components without overwhelming the terminal or consuming excessive CPU.
+
+## Core API
+
+### Region
+
+A region is a managed area of your terminal. It handles rendering, resizing, and component updates.
+
+```typescript
+const r = Region({
+  width: 80,        // Optional: auto-detects if not set
+  height: 1,        // Optional: expands as needed
+  debugLog: 'debug.log' // Optional: log rendering for debugging
 });
+```
+
+### Setting Content
+
+```typescript
+// Replace all content
+r.set('Hello, world!');
 
-for (let i = 0; i <= 100; i++) {
-  progress.update(i, 100);
-  await new Promise(resolve => setTimeout(resolve, 50));
-}
+// Or use components
+r.set(Styled({ color: 'green' }, 'Success!'));
 
-progress.finish();
-region.destroy();
+// Append content (returns a reference you can use to delete later)
+const ref = r.add('Line 2');
+ref.delete(); // Remove it
 ```
 
-### Spinner
+### Cleanup
 
 ```typescript
-import { createRegion, createSpinner } from 'echokit';
+r.destroy(true); // Clean up and restore terminal (true = clear first)
+```
 
-const region = createRegion({ width: 80 });
-const spinner = createSpinner(region, 1);
+## Components
 
-spinner.setText('Processing...');
-spinner.start();
+### Styled
 
-// Do work...
-await doWork();
+Apply colors and styling to text.
 
-spinner.stop();
-region.destroy();
+```typescript
+import { Styled } from 'linecraft';
+
+r.set(Styled({ 
+  color: 'brightGreen', 
+  bold: true
+}, 'Bold green text'));
 ```
 
-### Custom Layout
+**Options:**
+- `color?: Color` - Text color
+- `backgroundColor?: Color` - Background color
+- `bold?: boolean` - Bold text
+- `italic?: boolean` - Italic text
+- `underline?: boolean` - Underlined text
+- `overflow?: 'none' | 'ellipsis-end' | 'ellipsis-start' | 'ellipsis-middle' | 'wrap'` - Text overflow handling
+- `align?: 'left' | 'right' | 'center'` - Text alignment
+
+### Section
+
+Wrap content in a bordered box with an optional title.
+
+![Section Example](https://raw.githubusercontent.com/matthew-dean/linecraft/main/docs/examples/section.gif)
 
 ```typescript
-import { createRegion } from 'echokit';
+import { Section } from 'linecraft';
 
-const region = createRegion({ width: 80 });
+r.set(Section(
+  { title: 'My Section' },
+  'Content goes here'
+));
+```
+
+**Options:**
+- `title?: string` - Title shown in a tab at the top
+- `titleColor?: Color` - Color of the title
+- `borderColor?: Color` - Color of borders
+- `padding?: number` - Internal padding (default: 1)
+- `left?: boolean` - Show left border (default: true)
+- `right?: boolean` - Show right border (default: true)
+- `top?: boolean` - Show top border (default: true)
+- `bottom?: boolean` - Show bottom border (default: true)
 
-// Set individual lines (1-based)
-region.setLine(1, { text: 'Status:', style: { bold: true } });
-region.setLine(2, '  ✓ Connected');
-region.setLine(3, '  ⏳ Processing...');
+### CodeDebug
 
-// Or set entire content at once
-region.set(`Status:
-  ✓ Connected
-  ⏳ Processing...
-  ✗ Error`);
+Display code errors and warnings with line numbers, context, and clickable file paths.
+
+![CodeDebug Example](https://raw.githubusercontent.com/matthew-dean/linecraft/main/docs/examples/code-debug.gif)
+
+```typescript
+import { CodeDebug } from 'linecraft';
+
+r.set(CodeDebug({
+  startLine: 42,
+  startColumn: 10,
+  endLine: 42,
+  endColumn: 20,
+  errorLine: '    const result = fetchData();',
+  lineBefore: '  async function load() {',
+  lineAfter: '    return process(result);',
+  message: 'Type error: fetchData is not defined',
+  filePath: 'src/loaders/data.ts',
+  fullPath: '/absolute/path/to/src/loaders/data.ts',
+  baseDir: process.cwd(),
+  type: 'error' // 'error' | 'warning' | 'info'
+}));
 ```
 
-## API
+**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)
 
-### `createRegion(options?)`
+### Spinner
+
+Animated spinners for loading states. Includes built-in styles or use custom frames.
+
+![Spinner Example](https://raw.githubusercontent.com/matthew-dean/linecraft/main/docs/examples/spinner.gif)
 
-Creates a new terminal region.
+```typescript
+import { Spinner } from 'linecraft';
+
+// Built-in styles
+r.set(Spinner({
+  style: 'classic-dots', // or 'bouncing-bar'
+  color: 'green',
+  interval: 100
+}));
+
+// Custom frames
+r.set(Spinner({
+  frames: ['⠋', '⠙', '⠹', '⠸'],
+  color: 'yellow',
+  interval: 80
+}));
+```
 
 **Options:**
-- `x?: number` - X position (default: 0)
-- `y?: number` - Y position (default: 0)
-- `width?: number` - Width (default: terminal width)
-- `height?: number` - Initial height (default: 1, expands as needed)
+- `style?: 'classic-dots' | 'bouncing-bar'` - Built-in animation style
+- `frames?: string[]` - Custom frames (overrides style if provided)
+- `interval?: number` - Milliseconds between frames (default: 80)
+- `color?: Color` - Spinner color
+- `autoStart?: boolean` - Start automatically (default: true)
 
-### `region.setLine(lineNumber, content)`
+Spinners automatically stop when components are replaced or the region is destroyed.
 
-Set a single line (1-based). Region expands automatically if needed.
+### ProgressBar
 
-### `region.set(content)`
+Progress bars with customizable colors and styling.
 
-Set entire content. Can be a string with `\n` separators or an array of `LineContent`.
+![ProgressBar Example](https://raw.githubusercontent.com/matthew-dean/linecraft/main/docs/examples/progressbar.gif)
 
-### `region.flush()`
+```typescript
+import { progressBar } from 'linecraft';
+
+r.set(progressBar({
+  current: 75,
+  total: 100,
+  barColor: 'green',
+  bracketColor: 'brightBlack',
+  percentColor: 'yellow'
+}));
+```
+
+**Options:**
+- `current: number` - Current progress value
+- `total: number` - Total/max value
+- `barColor?: Color` - Color of the filled bar
+- `bracketColor?: Color` - Color of brackets
+- `percentColor?: Color` - Color of percentage text
 
-Force immediate render of pending updates (bypasses throttle).
+### Segments
 
-### `region.setThrottle(fps)`
+Create segmented displays (like oh-my-zsh style prompts).
 
-Set maximum render rate (default: 60 FPS).
+![Segments Example](https://raw.githubusercontent.com/matthew-dean/linecraft/main/docs/examples/segments.gif)
+
+```typescript
+import { Segments } from 'linecraft';
+
+r.set(Segments({
+  segments: [
+    { content: 'user@host', color: 'brightGreen', backgroundColor: 'blue' },
+    { content: '~/projects', color: 'white', backgroundColor: 'brightBlue' },
+    { content: 'main', color: 'black', backgroundColor: 'white' }
+  ],
+  borderStyle: 'cap' // 'cap' | 'brace' | 'round' | 'square' | 'none'
+}));
+```
+
+**Options:**
+- `segments: Array<{ content: string, color?: Color, backgroundColor?: Color, borderStyle?: BorderStyle }>` - Array of segments
+- `borderStyle?: BorderStyle` - Style for segment borders ('cap', 'brace', 'round', 'square', 'none')
+
+### Grid
+
+Create responsive grid layouts. Children automatically wrap to new rows when they exceed the number of explicit columns.
+
+![Grid Example](https://raw.githubusercontent.com/matthew-dean/linecraft/main/docs/examples/grid.gif)
+
+```typescript
+import { Grid } from 'linecraft';
+
+// Basic grid
+r.set(Grid({ template: [20, '1*'], columnGap: 2 },
+  Styled({ color: 'cyan' }, 'Label:'),
+  Styled({ color: 'yellow' }, 'Value')
+));
+
+// Multiple rows (children wrap automatically)
+r.set(Grid({ 
+  columns: [20, 20],  // 2 columns per row
+  autoColumns: 20,     // Size for extra columns
+  columnGap: 2,
+  rowGap: 1
+},
+  Styled({ color: 'cyan' }, 'Left'),
+  Styled({ color: 'cyan' }, 'Right'),
+  fill({ char: '─', color: 'brightCyan' }),
+  fill({ char: '─', color: 'brightCyan' })
+));
+```
+
+**Options:**
+- `columns?: GridTemplateEntry[]` - Explicit column definitions (like CSS `grid-template-columns`)
+- `autoColumns?: GridTemplateEntry` - Size for implicitly created columns (like CSS `grid-auto-columns`)
+- `columnGap?: number` - Spaces between columns (default: 0)
+- `rowGap?: number` - Spaces between rows (default: 0)
+- `spaceBetween?: FillChar | FillChar[]` - Characters to draw between columns
+- `justify?: 'start' | 'end' | 'center' | 'space-between'` - Justify content
+
+**Template entries:**
+- Fixed width: `20`, `30`
+- Flex units: `'1*'`, `'2*'` (like CSS `1fr`, `2fr`)
+- Minmax: `{ min: 40, width: '2*' }`
+- Auto: `'auto'` (content-based sizing)
+
+### Fill
+
+Fill available space with a character. Typically used within grids.
+
+![Fill Example](https://raw.githubusercontent.com/matthew-dean/linecraft/main/docs/examples/fill.gif)
+
+```typescript
+import { fill } from 'linecraft';
+
+r.set(fill({ char: '─', color: 'brightBlack' }));
+```
+
+## Utilities
+
+### Prompt
+
+Wait for user input before continuing.
+
+```typescript
+import { prompt } from 'linecraft';
+
+await prompt(r, {
+  message: 'continue',
+  key: 'spacebar', // 'spacebar' | 'enter' | 'q' | 'any'
+  color: 'brightBlack'
+});
+```
+
+## Colors
+
+Available colors:
+- `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
+- `brightBlack`, `brightRed`, `brightGreen`, `brightYellow`, `brightBlue`, `brightMagenta`, `brightCyan`, `brightWhite`
+
+## Examples
+
+Check out the `examples/` directory:
+
+- `progress.ts` - Progress bars (basic and multi-lane)
+- `spinner.ts` - Animated spinners
+- `code-debug.ts` - Code error display
+- `grid-all-features.ts` - Grid layout examples
+- `segments.ts` - Segmented displays
+
+Run examples with:
+```bash
+pnpm example <name>
+```
+
+## API Reference
+
+### Region Methods
+
+- `set(content)` - Replace all content
+- `add(content)` - Append content, returns `ComponentReference` or `SectionReference`
+- `destroy(clearFirst?)` - Clean up and restore terminal
+- `width` - Current region width (read-only)
+- `height` - Current region height (read-only)
+
+### ComponentReference
+
+- `delete()` - Remove the component from the region
+
+### SectionReference
+
+- `update(content)` - Update the section content
+- `delete()` - Remove the section from the region
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.
+
+**Creating example recordings?** See [docs/creating-recordings.md](docs/creating-recordings.md) for a guide on using vhs to create animated GIFs.
 
 ## License
 
 MIT
-

package/lib/api/color.d.ts

@@ -0,0 +1,6 @@
+import type { Color } from '../types';
+/**
+ * Apply color to text
+ */
+export declare function color(colorName: Color, text: string): string;
+//# sourceMappingURL=color.d.ts.map

package/lib/api/color.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/api/color.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEtC;;GAEG;AACH,wBAAgB,KAAK,CAAC,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/lib/api/color.js

@@ -0,0 +1,9 @@
+// Color function for text styling
+import { applyStyle } from '../utils/colors';
+/**
+ * Apply color to text
+ */
+export function color(colorName, text) {
+    return applyStyle(text, { color: colorName });
+}
+//# sourceMappingURL=color.js.map

package/lib/api/color.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.js","sourceRoot":"","sources":["../../src/api/color.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAElC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG7C;;GAEG;AACH,MAAM,UAAU,KAAK,CAAC,SAAgB,EAAE,IAAY;IAClD,OAAO,UAAU,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;AAChD,CAAC"}

package/lib/api/color.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=color.test.d.ts.map

package/lib/api/color.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.test.d.ts","sourceRoot":"","sources":["../../src/api/color.test.ts"],"names":[],"mappings":""}

package/lib/api/color.test.js

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { color } from './color';
+describe('color', () => {
+    it('should apply red color', () => {
+        const result = color('red', 'Hello');
+        expect(result).toContain('\x1b[');
+        expect(result).toContain('31'); // Red ANSI code
+        expect(result).toContain('Hello');
+    });
+    it('should apply green color', () => {
+        const result = color('green', 'Hello');
+        expect(result).toContain('32'); // Green ANSI code
+    });
+    it('should apply blue color', () => {
+        const result = color('blue', 'Hello');
+        expect(result).toContain('34'); // Blue ANSI code
+    });
+    it('should reset color at end', () => {
+        const result = color('red', 'Hello');
+        expect(result).toMatch(/\x1b\[0m$/); // Reset code at end
+    });
+});
+//# sourceMappingURL=color.test.js.map

package/lib/api/color.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.test.js","sourceRoot":"","sources":["../../src/api/color.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE;IACrB,EAAE,CAAC,wBAAwB,EAAE,GAAG,EAAE;QAChC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACrC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB;QAChD,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,kBAAkB;IACpD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yBAAyB,EAAE,GAAG,EAAE;QACjC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACtC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,iBAAiB;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACrC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,oBAAoB;IAC3D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/lib/api/flex.d.ts

@@ -0,0 +1,55 @@
+import { Flex } from '../layout/flex.js';
+import { Col } from '../components/col.js';
+import type { TerminalRegion } from '../region.js';
+import type { FlexOptions } from '../layout/flex.js';
+import type { ColOptions } from '../components/col.js';
+import type { FlexChild } from '../components/renderable.js';
+export type { FlexChild };
+export type FlexChildWithDescriptors = FlexChild | ColDescriptor | FlexDescriptor;
+/**
+ * Descriptor for a flex container (resolved later with region)
+ */
+export interface FlexDescriptor {
+    type: 'flex';
+    options: FlexOptions;
+    children: FlexChild[];
+}
+/**
+ * Descriptor for a column (resolved later with region)
+ */
+export interface ColDescriptor {
+    type: 'col';
+    options: ColOptions;
+    content: string;
+}
+/**
+ * Create a flex container with children
+ * Accepts strings, Renderables, arrays (for functional components), or descriptors
+ */
+export declare function flex(options: FlexOptions, ...children: FlexChildWithDescriptors[]): FlexDescriptor;
+/**
+ * Create a column (flex item) with options and content
+ */
+export declare function col(options: ColOptions, content: string): ColDescriptor;
+/**
+ * Resolve a flex descriptor tree into actual components
+ * Handles strings, arrays (for functional components), and descriptors
+ */
+export declare function resolveFlexTree(region: TerminalRegion, descriptor: FlexDescriptor | ColDescriptor | FlexChild): Flex | Col;
+/**
+ * Helper for functional components that return arrays
+ * Example:
+ * ```ts
+ * function myComponent(options, ...children) {
+ *   return component([
+ *     'Label:',
+ *     ...children
+ *   ]);
+ * }
+ * ```
+ *
+ * Actually, you don't need this helper - just return the array directly!
+ * Flex will automatically flatten arrays.
+ */
+export declare function component(children: FlexChild[]): FlexChild[];
+//# sourceMappingURL=flex.d.ts.map

package/lib/api/flex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flex.d.ts","sourceRoot":"","sources":["../../src/ts/api/flex.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAG7D,YAAY,EAAE,SAAS,EAAE,CAAC;AAG1B,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,aAAa,GAAG,cAAc,CAAC;AAElF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,SAAS,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,KAAK,CAAC;IACZ,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAClB,OAAO,EAAE,WAAW,EACpB,GAAG,QAAQ,EAAE,wBAAwB,EAAE,GACtC,cAAc,CAMhB;AAED;;GAEG;AACH,wBAAgB,GAAG,CACjB,OAAO,EAAE,UAAU,EACnB,OAAO,EAAE,MAAM,GACd,aAAa,CAMf;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,cAAc,GAAG,aAAa,GAAG,SAAS,GACrD,IAAI,GAAG,GAAG,CAwCZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAE5D"}

package/lib/api/flex.js

@@ -0,0 +1,86 @@
+// Function-based API for flex layouts
+import { Flex } from '../layout/flex.js';
+import { Col } from '../components/col.js';
+/**
+ * Create a flex container with children
+ * Accepts strings, Renderables, arrays (for functional components), or descriptors
+ */
+export function flex(options, ...children) {
+    return {
+        type: 'flex',
+        options,
+        children: children,
+    };
+}
+/**
+ * Create a column (flex item) with options and content
+ */
+export function col(options, content) {
+    return {
+        type: 'col',
+        options,
+        content,
+    };
+}
+/**
+ * Resolve a flex descriptor tree into actual components
+ * Handles strings, arrays (for functional components), and descriptors
+ */
+export function resolveFlexTree(region, descriptor) {
+    if (typeof descriptor === 'string') {
+        // Plain string - wrap in col
+        return new Col(region, descriptor, {});
+    }
+    // Check if it's a descriptor object
+    if (typeof descriptor === 'object' && descriptor !== null && 'type' in descriptor) {
+        if (descriptor.type === 'col') {
+            return new Col(region, descriptor.content, descriptor.options);
+        }
+        if (descriptor.type === 'flex') {
+            const flexComponent = new Flex(region, descriptor.options);
+            // Resolve children - Flex.addChild now handles strings, arrays, and Renderables
+            for (const child of descriptor.children) {
+                if (typeof child === 'string') {
+                    // Plain string - Flex.addChild will handle it
+                    flexComponent.addChild(child);
+                }
+                else if (typeof child === 'object' && child !== null && 'type' in child) {
+                    // Check if it's a descriptor
+                    if (child.type === 'col' || child.type === 'flex') {
+                        const resolved = resolveFlexTree(region, child);
+                        flexComponent.addChild(resolved);
+                    }
+                    else {
+                        // Not a descriptor, pass through as-is
+                        flexComponent.addChild(child);
+                    }
+                }
+                else {
+                    // Already a Renderable or array - pass through
+                    flexComponent.addChild(child);
+                }
+            }
+            return flexComponent;
+        }
+    }
+    throw new Error(`Unknown descriptor type: ${descriptor.type || typeof descriptor}`);
+}
+/**
+ * Helper for functional components that return arrays
+ * Example:
+ * ```ts
+ * function myComponent(options, ...children) {
+ *   return component([
+ *     'Label:',
+ *     ...children
+ *   ]);
+ * }
+ * ```
+ *
+ * Actually, you don't need this helper - just return the array directly!
+ * Flex will automatically flatten arrays.
+ */
+export function component(children) {
+    return children;
+}
+//# sourceMappingURL=flex.js.map

package/lib/api/flex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flex.js","sourceRoot":"","sources":["../../src/ts/api/flex.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AA8B3C;;;GAGG;AACH,MAAM,UAAU,IAAI,CAClB,OAAoB,EACpB,GAAG,QAAoC;IAEvC,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO;QACP,QAAQ,EAAE,QAAuB;KAClC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,GAAG,CACjB,OAAmB,EACnB,OAAe;IAEf,OAAO;QACL,IAAI,EAAE,KAAK;QACX,OAAO;QACP,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAsB,EACtB,UAAsD;IAEtD,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;QACnC,6BAA6B;QAC7B,OAAO,IAAI,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,oCAAoC;IACpC,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,IAAI,IAAI,MAAM,IAAI,UAAU,EAAE,CAAC;QAClF,IAAI,UAAU,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YAC9B,OAAO,IAAI,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;QACjE,CAAC;QAED,IAAI,UAAU,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC/B,MAAM,aAAa,GAAG,IAAI,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;YAE3D,gFAAgF;YAChF,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC;gBACxC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC9B,8CAA8C;oBAC9C,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAChC,CAAC;qBAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;oBAC1E,6BAA6B;oBAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;wBAClD,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,EAAE,KAAkD,CAAC,CAAC;wBAC7F,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;oBACnC,CAAC;yBAAM,CAAC;wBACN,uCAAuC;wBACvC,aAAa,CAAC,QAAQ,CAAC,KAAY,CAAC,CAAC;oBACvC,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,+CAA+C;oBAC/C,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAChC,CAAC;YACH,CAAC;YAED,OAAO,aAAa,CAAC;QACvB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,4BAA6B,UAAkB,CAAC,IAAI,IAAI,OAAO,UAAU,EAAE,CAAC,CAAC;AAC/F,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CAAC,QAAqB;IAC7C,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/lib/api/flex.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=flex.test.d.ts.map