diff --git a/.changeset/dom-public-elements.md b/.changeset/dom-public-elements.md new file mode 100644 index 0000000..93321de --- /dev/null +++ b/.changeset/dom-public-elements.md @@ -0,0 +1,5 @@ +--- +'@clack/ui': patch +--- + +Export Document, Element, and Text for applications that build terminal UI trees directly. diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index 4330045..c7e833d 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -11,3 +11,4 @@ jobs: secrets: inherit with: publish: './packages/*' + template: './examples/*' diff --git a/examples/basic/README.md b/examples/basic/README.md new file mode 100644 index 0000000..0ef305e --- /dev/null +++ b/examples/basic/README.md @@ -0,0 +1,40 @@ +# Basic example + +A DOM version of the original basic panel, using `div`, `span`, text nodes, and +direct `element.style` assignments. + +From the repository root: + +```sh +pnpm install +pnpm build +pnpm --filter @examples/basic start +``` + +The panel appears in the terminal's alternate screen while the example runs. +Press Enter or Ctrl+C to finish and restore the previous screen: + +```text +┌──────────────────────┐ +│ @clack/ui │ +│ │ +│ status ● ready │ +│ version 0.0.0 │ +│ render @bomb.sh/tty │ +└──────────────────────┘ +``` + +The title is cyan, labels are gray, status is green, remaining values inherit +white from the panel, and borders are blue. Each label and value is a separate +`span` in a flex row; this does not need mixed-color runs inside one text flow. + +Borders occupy their own cells in the CSS box model, so the panel has one cell +of horizontal padding and zero vertical padding. Together with its one-cell +border, this preserves the original example's 24-column, 7-row appearance. + +The tests render the same `createApp()` tree through the UI source, checking +layout and colors. Run them with: + +```sh +pnpm test examples/basic/src/app.test.ts +``` diff --git a/examples/basic/package.json b/examples/basic/package.json new file mode 100644 index 0000000..8711a77 --- /dev/null +++ b/examples/basic/package.json @@ -0,0 +1,12 @@ +{ + "name": "@examples/basic", + "private": true, + "type": "module", + "scripts": { + "start": "node --experimental-strip-types src/index.ts", + "lint": "bsh lint" + }, + "dependencies": { + "@clack/ui": "workspace:*" + } +} diff --git a/examples/basic/src/app.test.ts b/examples/basic/src/app.test.ts new file mode 100644 index 0000000..904d08b --- /dev/null +++ b/examples/basic/src/app.test.ts @@ -0,0 +1,50 @@ +import { describe, expect, it } from 'vitest'; +import { createTestUI } from '../../../packages/ui/test/ui.ts'; +import { createApp } from './app.ts'; + +const panel = [ + '┌──────────────────────┐', + '│ @clack/ui │', + '│ │', + '│ status ● ready │', + '│ version 0.0.0 │', + '│ render @bomb.sh/tty │', + '└──────────────────────┘', +]; + +describe('basic example', () => { + it('renders the original panel with styled labels and inherited value colors', async () => { + await using ui = await createTestUI({ cols: 32, rows: 9 }); + const { document, terminal } = ui; + document.documentElement.appendChild(createApp(document)); + + await expect + .poll(() => terminal.screen.getLines().map((line) => line.trimEnd()), { timeout: 2000 }) + .toEqual([...panel, '', '']); + + const runs = [ + { row: 1, col: 2, content: '@clack/ui', color: { r: 0, g: 255, b: 255 } }, + { row: 3, col: 2, content: 'status ', color: { r: 128, g: 128, b: 128 } }, + { row: 3, col: 10, content: '● ready', color: { r: 0, g: 128, b: 0 } }, + { row: 4, col: 2, content: 'version', color: { r: 128, g: 128, b: 128 } }, + { row: 4, col: 10, content: '0.0.0', color: { r: 255, g: 255, b: 255 } }, + { row: 5, col: 2, content: 'render ', color: { r: 128, g: 128, b: 128 } }, + { row: 5, col: 10, content: '@bomb.sh/tty', color: { r: 255, g: 255, b: 255 } }, + ]; + for (const run of runs) { + for (const [offset, char] of [...run.content].entries()) { + const cell = terminal.getCell(run.row, run.col + offset); + expect(cell.char).toBe(char); + expect(cell.fg).toMatchObject(run.color); + } + } + + for (const [row, line] of panel.entries()) { + for (const [col, char] of [...line].entries()) { + if ('┌┐└┘─│'.includes(char)) { + expect(terminal.getCell(row, col).fg).toMatchObject({ r: 0, g: 0, b: 255 }); + } + } + } + }); +}); diff --git a/examples/basic/src/app.ts b/examples/basic/src/app.ts new file mode 100644 index 0000000..b293d00 --- /dev/null +++ b/examples/basic/src/app.ts @@ -0,0 +1,45 @@ +import type { Document, Element, ColorValue } from '@clack/ui'; + +/* oxlint-disable bombshell-dev/exported-function-async -- Builds a detached DOM tree synchronously. */ +/** Build the basic panel using elements, text nodes, and inline declarations. */ +export function createApp(document: Document): Element { + const panel = document.createElement('div'); + panel.style.flexDirection = 'column'; + panel.style.gap = '1px'; + panel.style.paddingLeft = '1px'; + panel.style.paddingRight = '1px'; + panel.style.color = 'white'; + panel.style.borderStyle = 'solid'; + panel.style.borderColor = 'blue'; + panel.style.borderTopWidth = '1px'; + panel.style.borderRightWidth = '1px'; + panel.style.borderBottomWidth = '1px'; + panel.style.borderLeftWidth = '1px'; + panel.appendChild(span('@clack/ui', 'cyan')); + + const details = document.createElement('div'); + details.style.flexDirection = 'column'; + details.appendChild(row('status ', span('● ready', 'green'))); + details.appendChild(row('version', span('0.0.0'))); + details.appendChild(row('render ', span('@bomb.sh/tty'))); + panel.appendChild(details); + + return panel; + + function span(content: string, color?: ColorValue): Element { + const element = document.createElement('span'); + if (color !== undefined) { + element.style.color = color; + } + element.appendChild(document.createTextNode(content)); + return element; + } + + function row(label: string, value: Element): Element { + const element = document.createElement('div'); + element.style.gap = '1px'; + element.appendChild(span(label, 'gray')); + element.appendChild(value); + return element; + } +} diff --git a/examples/basic/src/index.ts b/examples/basic/src/index.ts new file mode 100644 index 0000000..f01fb57 --- /dev/null +++ b/examples/basic/src/index.ts @@ -0,0 +1,25 @@ +import { createUI } from '@clack/ui'; +import { createApp } from './app.ts'; + +const ui = await createUI({ + height: 7, + input: process.stdin, + output: process.stdout, +}); + +const { promise: stopped, resolve: stop } = Promise.withResolvers(); + +try { + ui.document.documentElement.appendChild(createApp(ui.document)); + process.stdin.once('data', stop); + process.stdin.once('end', stop); + process.once('SIGINT', stop); + process.stdin.resume(); + await Promise.race([ui.main(), stopped]); +} finally { + process.stdin.off('data', stop); + process.stdin.off('end', stop); + process.off('SIGINT', stop); + process.stdin.pause(); + await ui[Symbol.asyncDispose](); +} diff --git a/examples/basic/tsconfig.json b/examples/basic/tsconfig.json new file mode 100644 index 0000000..d9b4436 --- /dev/null +++ b/examples/basic/tsconfig.json @@ -0,0 +1,16 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "paths": { + "@clack/ui": ["../../packages/ui/src/index.ts"] + }, + "composite": false, + "declaration": false, + "declarationMap": false, + "noEmit": true, + "types": [ + "node" + ] + }, + "include": ["src"] +} diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts index f8c0e77..50d9847 100644 --- a/packages/ui/src/index.ts +++ b/packages/ui/src/index.ts @@ -1,4 +1,5 @@ export { createUI } from './ui.ts'; +export { Document, Element, Text } from './dom.ts'; export type { ColorValue, BorderWidthValue, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 979a399..586ea6c 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -39,6 +39,12 @@ importers: specifier: 5.0.5 version: 5.0.5(@types/node@22.20.0)(vite@8.3.5(@types/node@22.20.0)(jiti@2.7.0)(yaml@2.9.1)) + examples/basic: + dependencies: + '@clack/ui': + specifier: workspace:* + version: link:../../packages/ui + packages/ui: dependencies: '@bomb.sh/tty':