@boba-cli/dsl 0.1.0-alpha.1 → 1.0.0-alpha.2

package/README.md

@@ -19,7 +19,7 @@ const app = createApp()
   .onKey(['q', 'ctrl+c'], ({ quit }) => quit())
   .view(({ state, components }) =>
     vstack(
-      text('🧼 My App').bold().foreground('#ff79c6'),
+      text('🧋 My App').bold().foreground('#ff79c6'),
       spacer(),
       hstack(components.loading, text('  ' + state.message)),
       spacer(),
@@ -223,12 +223,208 @@ vstack(
 
 ### Component Builders
 
+The DSL provides 17 component builders for common CLI patterns. All components integrate seamlessly with the App builder pattern and provide declarative configuration.
+
+#### `code(options: CodeBuilderOptions): ComponentBuilder<CodeModel>`
+
+Displays syntax-highlighted source code from files with scrolling support.
+
+```typescript
+import { NodeFileSystemAdapter, NodePathAdapter } from '@boba-cli/machine/node'
+
+.component('viewer', code({
+  filesystem: new NodeFileSystemAdapter(),
+  path: new NodePathAdapter(),
+  active: true,
+  theme: 'dracula',
+  width: 80,
+  height: 24
+}))
+```
+
+**Options:**
+- `filesystem` - Filesystem adapter (required, use `NodeFileSystemAdapter` for Node.js)
+- `path` - Path adapter (required, use `NodePathAdapter` for Node.js)
+- `active` - Whether component receives keyboard input (default: `false`)
+- `theme` - Syntax theme like `"dracula"`, `"monokai"`, `"github-light"` (default: `"dracula"`)
+- `width` - Viewer width in characters (default: `0`)
+- `height` - Viewer height in lines (default: `0`)
+
+#### `filepicker(options: FilepickerBuilderOptions): ComponentBuilder<FilepickerModel>`
+
+Interactive file system browser with selection support.
+
+```typescript
+import { NodeFileSystemAdapter, NodePathAdapter } from '@boba-cli/machine/node'
+
+.component('picker', filepicker({
+  filesystem: new NodeFileSystemAdapter(),
+  path: new NodePathAdapter(),
+  currentPath: process.cwd(),
+  height: 15,
+  width: 60
+}))
+```
+
+**Options:**
+- `filesystem` - Filesystem adapter (required)
+- `path` - Path adapter (required)
+- `currentPath` - Initial directory path
+- `height` - Picker height in lines
+- `width` - Picker width in characters
+- Additional styling and behavior options available
+
+#### `filetree(options: FiletreeBuilderOptions): ComponentBuilder<FiletreeModel>`
+
+Directory tree viewer with expandable folders.
+
+```typescript
+.component('tree', filetree({
+  root: { name: 'src', isDirectory: true, children: [...] }
+}))
+```
+
+**Options:**
+- `root` - Root directory item (required, must be a `DirectoryItem`)
+- `showFiles` - Whether to show files or only directories (default: `true`)
+- Custom styling options available
+
+#### `help(options?: HelpBuilderOptions): ComponentBuilder<HelpModel>`
+
+Full-screen key binding help display.
+
+```typescript
+.component('help', help({
+  keyBindings: [
+    { key: 'q', description: 'Quit application' },
+    { key: '↑/↓', description: 'Navigate list' }
+  ],
+  showHelp: true
+}))
+```
+
+**Options:**
+- `keyBindings` - Array of key binding descriptions
+- `showHelp` - Whether help is visible (default: `false`)
+- Custom styling options available
+
+#### `helpBubble(options?: HelpBubbleBuilderOptions): ComponentBuilder<HelpBubbleModel>`
+
+Compact inline help bubble with keyboard shortcuts.
+
+```typescript
+.component('shortcuts', helpBubble({
+  entries: [
+    { key: 'enter', description: 'Select' },
+    { key: 'q', description: 'Quit' }
+  ]
+}))
+```
+
+**Options:**
+- `entries` - Array of shortcut entries with `key` and `description`
+- Custom styling options available
+
+#### `list<T>(options: ListBuilderOptions<T>): ComponentBuilder<ListModel<T>>`
+
+Filterable, paginated list with keyboard navigation. Items must implement the `Item` interface.
+
+```typescript
+import { list, type Item } from '@boba-cli/dsl'
+
+interface TodoItem extends Item {
+  filterValue: () => string
+  title: () => string
+  description: () => string
+}
+
+const items: TodoItem[] = [
+  { filterValue: () => 'Buy milk', title: () => 'Buy milk', description: () => 'From the store' }
+]
+
+.component('todos', list({ items, title: 'Tasks', height: 20 }))
+```
+
+**Options:**
+- `items` - Array of items implementing `Item` interface (required)
+- `title` - List title
+- `height` - List height in lines
+- `width` - List width in characters
+- `showTitle`, `showFilter`, `showPagination`, `showHelp`, `showStatusBar` - Toggle UI elements
+- `filteringEnabled` - Enable/disable filtering (default: `true`)
+- `styles` - Custom styles for list components
+- `keyMap` - Custom key bindings
+- `delegate` - Custom item rendering
+
+#### `markdown(options?: MarkdownBuilderOptions): ComponentBuilder<MarkdownModel>`
+
+Renders markdown with syntax highlighting.
+
+```typescript
+.component('docs', markdown({
+  content: '# Hello\n\nThis is **markdown**.',
+  width: 80
+}))
+```
+
+**Options:**
+- `content` - Markdown content to render
+- `width` - Rendering width in characters
+- Custom styling options available
+
+#### `paginator(options?: PaginatorBuilderOptions): ComponentBuilder<PaginatorModel>`
+
+Dot-style page indicator (e.g., `● ○ ○`).
+
+```typescript
+.component('pages', paginator({
+  totalPages: 5,
+  currentPage: 0
+}))
+```
+
+**Options:**
+- `totalPages` - Total number of pages (default: `3`)
+- `currentPage` - Current page index (default: `0`)
+- Custom styling options available
+
+#### `progress(options?: ProgressBuilderOptions): ComponentBuilder<ProgressModel>`
+
+Animated progress bar with gradient support and spring physics.
+
+```typescript
+.component('progress', progress({
+  width: 40,
+  gradient: {
+    start: '#5A56E0',
+    end: '#EE6FF8',
+    scaleGradientToProgress: false
+  },
+  showPercentage: true,
+  spring: {
+    frequency: 18,
+    damping: 1
+  }
+}))
+```
+
+**Options:**
+- `width` - Progress bar width in characters (default: `40`)
+- `full` - Character for filled portion (default: `'█'`)
+- `empty` - Character for empty portion (default: `'░'`)
+- `fullColor` - Color for filled portion (default: `'#7571F9'`)
+- `emptyColor` - Color for empty portion (default: `'#606060'`)
+- `showPercentage` - Display percentage value (default: `true`)
+- `percentFormat` - Printf-style format string (default: `' %3.0f%%'`)
+- `gradient` - Gradient configuration with `start`, `end`, `scaleGradientToProgress`
+- `spring` - Spring physics with `frequency`, `damping`
+- `percentageStyle` - Style for percentage text
+
 #### `spinner(options?: SpinnerBuilderOptions): ComponentBuilder<SpinnerModel>`
 
-Creates an animated spinner component.
+Animated loading spinner.
 
 ```typescript
-.component('loading', spinner())
 .component('loading', spinner({
   spinner: dot,
   style: new Style().foreground('#50fa7b')
@@ -244,9 +440,149 @@ Creates an animated spinner component.
 import { line, dot, miniDot, pulse, points, moon, meter, ellipsis } from '@boba-cli/dsl'
 ```
 
+#### `statusBar(options?: StatusBarBuilderOptions): ComponentBuilder<StatusBarModel>`
+
+Multi-column status bar for displaying key-value pairs.
+
+```typescript
+.component('status', statusBar({
+  columns: [
+    { key: 'mode', value: 'NORMAL' },
+    { key: 'line', value: '42' }
+  ]
+}))
+```
+
+**Options:**
+- `columns` - Array of column definitions with `key` and `value`
+- Custom styling options available
+
+#### `stopwatch(options?: StopwatchBuilderOptions): ComponentBuilder<StopwatchModel>`
+
+Displays elapsed time since start.
+
+```typescript
+.component('elapsed', stopwatch({
+  format: 'mm:ss.SSS',
+  running: true
+}))
+```
+
+**Options:**
+- `format` - Time format string (default: `'mm:ss.SSS'`)
+- `running` - Whether stopwatch is running (default: `false`)
+- Custom styling options available
+
+#### `table(options?: TableBuilderOptions): ComponentBuilder<TableModel>`
+
+Scrollable data table with headers and rows.
+
+```typescript
+.component('data', table({
+  headers: ['Name', 'Age', 'City'],
+  rows: [
+    ['Alice', '30', 'NYC'],
+    ['Bob', '25', 'SF']
+  ],
+  height: 10
+}))
+```
+
+**Options:**
+- `headers` - Column headers
+- `rows` - Data rows
+- `height` - Table height in lines
+- `width` - Table width in characters
+- Custom styling and scrolling options available
+
+#### `textArea(options?: TextAreaBuilderOptions): ComponentBuilder<TextAreaModel>`
+
+Multi-line text editor with scrolling and editing.
+
+```typescript
+.component('editor', textArea({
+  value: 'Initial text',
+  width: 80,
+  height: 20,
+  active: true
+}))
+```
+
+**Options:**
+- `value` - Initial text content
+- `width` - Editor width in characters
+- `height` - Editor height in lines
+- `active` - Whether editor receives keyboard input (default: `false`)
+- Custom styling options available
+
+#### `textInput(options?: TextInputBuilderOptions): ComponentBuilder<TextInputModel>`
+
+Single-line text input with validation, placeholders, and echo modes.
+
+```typescript
+.component('input', textInput({
+  placeholder: 'Enter your name...',
+  value: '',
+  active: true,
+  validate: (value) => value.length > 0 ? null : 'Required'
+}))
+```
+
+**Options:**
+- `value` - Initial input value
+- `placeholder` - Placeholder text
+- `active` - Whether input receives keyboard input (default: `false`)
+- `validate` - Validation function returning error message or `null`
+- `echoMode` - Input display mode (normal, password, none)
+- `cursorMode` - Cursor style
+- Custom styling options available
+
+**Re-exported types:**
+```typescript
+import { EchoMode, CursorMode, type ValidateFunc } from '@boba-cli/dsl'
+```
+
+#### `timer(options?: TimerBuilderOptions): ComponentBuilder<TimerModel>`
+
+Countdown timer display.
+
+```typescript
+.component('countdown', timer({
+  duration: 60000, // 60 seconds in milliseconds
+  format: 'mm:ss',
+  running: true
+}))
+```
+
+**Options:**
+- `duration` - Total duration in milliseconds
+- `format` - Time format string (default: `'mm:ss'`)
+- `running` - Whether timer is running (default: `false`)
+- Custom styling options available
+
+#### `viewport(options?: ViewportBuilderOptions): ComponentBuilder<ViewportModel>`
+
+Scrollable content viewport for displaying large content.
+
+```typescript
+.component('content', viewport({
+  content: longTextContent,
+  width: 80,
+  height: 20,
+  active: true
+}))
+```
+
+**Options:**
+- `content` - Content to display (string or array of strings)
+- `width` - Viewport width in characters
+- `height` - Viewport height in lines
+- `active` - Whether viewport receives keyboard input for scrolling (default: `false`)
+- Custom styling options available
+
 ### Re-exported Types
 
-For convenience, the DSL re-exports commonly used types:
+For convenience, the DSL re-exports commonly used types from underlying packages:
 
 ```typescript
 // From @boba-cli/chapstick
@@ -254,6 +590,18 @@ import { Style } from '@boba-cli/dsl'
 
 // From @boba-cli/spinner
 import { type Spinner, line, dot, miniDot, pulse, points, moon, meter, ellipsis } from '@boba-cli/dsl'
+
+// From @boba-cli/textinput
+import { type TextInputModel, EchoMode, CursorMode, type ValidateFunc } from '@boba-cli/dsl'
+
+// From @boba-cli/list
+import { type Item } from '@boba-cli/dsl'
+
+// From @boba-cli/filetree
+import { type DirectoryItem } from '@boba-cli/dsl'
+
+// From @boba-cli/help-bubble
+import { type Entry } from '@boba-cli/dsl'
 ```
 
 ## Type Safety