Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/preact-integration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@clack/ui': minor
---

Export DOM classes and UI types for direct integration with frameworks such as Preact.
1 change: 1 addition & 0 deletions .github/workflows/check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ jobs:
persist-credentials: false
- uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0
- run: pnpm install --frozen-lockfile
- run: pnpm --filter @bomb.sh/web-platform-tests build
- run: pnpm test

dom-wpt:
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/preview.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,4 @@ jobs:
secrets: inherit
with:
publish: './packages/*'
template: './examples/*'
5 changes: 3 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,16 @@ You need the exact Node and pnpm versions listed under `devEngines` in the root

Any version manager works. If you use [mise](https://mise.jdx.dev), which is what our lint, format, and test checks use, export `MISE_IDIOMATIC_VERSION_FILE_ENABLE_TOOLS=node,pnpm` and run `mise install` so it reads those versions from `package.json`.

Then install the dependencies:
Then install the dependencies and build the workspace packages, including WPT:

```sh
pnpm install
pnpm build
```

## Commands you'll use

Run these from the repo root. You don't need to build before you run the tests.
Run these from the repo root. Rebuild after changing shared WPT sources; `pnpm --filter @bomb.sh/web-platform-tests build` rebuilds just that package. Repeated test runs reuse the existing build.

| Command | What it does |
| ------------------------------------------ | ----------------------------------------- |
Expand Down
6 changes: 0 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,6 @@ UI provides web-based bindings, which allows us to support any JavaScript framew
npm install @clack/ui
```

## Bindings

| binding | version | changelog |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| [`@clack/ui-preact`](./packages/preact) | [![npm](https://img.shields.io/npm/v/@clack/ui-preact?style=for-the-badge)](https://www.npmx.dev/package/@clack/ui-preact) | [./packages/preact/CHANGELOG.md](./packages/preact/CHANGELOG.md) |

## Documentation

Coming soon 🙈
Expand Down
16 changes: 16 additions & 0 deletions examples/hello-world-preact/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Hello Preact

A Preact component mounted directly with Preact's `render()` on a nested Clack element,
without styles or a global `document`. It keeps `Hello ` on screen while erasing and
typing `World!`, `DOM!`, `Preact!`, and `Clack!` in a repeating loop.

From the workspace root:

```sh
pnpm install
pnpm build
pnpm --filter @examples/hello-world-preact start
```

Press Ctrl+C to exit. Unmounting cancels the animation timer, and disposing the UI
restores the terminal buffer and cursor.
19 changes: 19 additions & 0 deletions examples/hello-world-preact/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
{
"name": "@examples/hello-world-preact",
"version": "0.0.0",
"private": true,
"type": "module",
"scripts": {
"start": "node --import tsx src/main.tsx",
"dev": "tsx watch src/main.tsx",
"lint": "bsh lint"
},
"dependencies": {
"@clack/ui": "workspace:*",
"preact": "11.0.1"
},
"devDependencies": {
"@types/node": "^22.20.0",
"tsx": "^4.19.0"
}
}
34 changes: 34 additions & 0 deletions examples/hello-world-preact/src/animation.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
export interface GreetingFrame {
text: string;
delay: number;
}

const prefix = 'Hello ';
const greetings = ['World!', 'DOM!', 'Preact!', 'Clack!'];
const pause = 900;
const erase = 60;
const type = 100;

/** Each frame says what to show and how long to leave it on screen. */
export function* greetingFrames(): Generator<GreetingFrame, never, void> {
let index = 0;
const suffix = [...greetings[index]!];
yield { text: prefix + suffix.join(''), delay: pause };

while (true) {
while (suffix.length > 0) {
suffix.pop();
yield { text: prefix + suffix.join(''), delay: erase };
}

index = (index + 1) % greetings.length;
const next = [...greetings[index]!];
for (const character of next) {
suffix.push(character);
yield {
text: prefix + suffix.join(''),
delay: suffix.length === next.length ? pause : type,
};
}
}
}
22 changes: 22 additions & 0 deletions examples/hello-world-preact/src/greeting.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
import { useEffect, useState } from 'preact/hooks';
import { greetingFrames } from './animation.ts';

export function Greeting() {
const [text, setText] = useState('Hello World!');

useEffect(() => {
const animation = greetingFrames();
let timer: ReturnType<typeof setTimeout>;

function advance() {
const frame = animation.next().value;
setText(frame.text);
timer = setTimeout(advance, frame.delay);
}

advance();
return () => clearTimeout(timer);
}, []);

return <span>{text}</span>;
}
30 changes: 30 additions & 0 deletions examples/hello-world-preact/src/main.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
import { createUI } from '@clack/ui';
import { render } from 'preact';

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh shit! It just dawned on me that we don't even need adapters anymore. Siiiiiiick

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Batteries included!

import { Greeting } from './greeting.tsx';

const shutdown = Promise.withResolvers<void>();
const stop = () => shutdown.resolve();
process.once('SIGINT', stop);
process.once('SIGTERM', stop);

try {
await using ui = await createUI({
input: process.stdin,
output: process.stdout,
width: process.stdout.columns ?? 80,
height: process.stdout.rows ?? 24,
});

// A root can be mounted on any Clack element, not just the document root.
const mount = ui.document.createElement('div');
ui.document.documentElement.appendChild(mount);
try {
render(<Greeting />, mount);
await Promise.race([ui.main(), shutdown.promise]);
} finally {
render(null, mount);
}
} finally {
process.off('SIGINT', stop);
process.off('SIGTERM', stop);
}
9 changes: 9 additions & 0 deletions examples/hello-world-preact/tsconfig.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"extends": "../../tsconfig.json",
"compilerOptions": {
"types": ["node"],
"jsx": "react-jsx",
"jsxImportSource": "preact"
},
"include": ["src"]
}
6 changes: 3 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,12 @@
},
"scripts": {
"dev": "bsh dev",
"build": "pnpm --filter @bomb.sh/web-platform-tests build && pnpm --filter \"@clack/*\" run build",
"build": "pnpm -r build",
"bench": "vitest bench --reporter=verbose",
"format": "bsh format",
"format:check": "bsh format --check",
"lint": "bsh lint .",
"test": "pnpm --filter @bomb.sh/web-platform-tests build && bsh test"
"lint": "pnpm build && bsh lint && pnpm -r lint",
"test": "bsh test"
},
"devDependencies": {
"@bomb.sh/tools": "^0.8.0",
Expand Down
5 changes: 3 additions & 2 deletions packages/ui/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@
"build": "bsh build --dts",
"format": "bsh format",
"lint": "bsh lint",
"test": "pnpm --filter @bomb.sh/web-platform-tests build && bsh test"
"test": "bsh test"
},
"dependencies": {
"@bomb.sh/tty": "catalog:"
Expand All @@ -51,6 +51,7 @@
}
},
"devDependencies": {
"@bomb.sh/web-platform-tests": "workspace:*"
"@bomb.sh/web-platform-tests": "workspace:*",
"preact": "11.0.1"
}
}
3 changes: 2 additions & 1 deletion packages/ui/src/index.ts
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
export { createUI } from './ui.ts';
export { createUI, type UI, type UIOptions } from './ui.ts';
export { Document, Element, Node, Text } from './dom.ts';
14 changes: 10 additions & 4 deletions packages/ui/test/README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,20 @@
# UI tests

Tests live alongside the implementation in `src/`; this directory contains their shared fixtures and WPT configuration. Run the UI tests from the workspace root:
Tests live alongside the implementation in `src/`; this directory contains their shared fixtures and WPT configuration. Before the first test run, or after changing the shared WPT sources, build the test package from the workspace root:

```sh
pnpm --filter @bomb.sh/web-platform-tests build
```

Then run the UI tests:

```sh
pnpm --filter @clack/ui test
```

The test script builds the private `@bomb.sh/web-platform-tests` package before running Vitest. Use `pnpm test` from the workspace root to run the workspace tests.
Test runs reuse that build. Use `pnpm test` from the workspace root to run the workspace tests.

[`preact.test.tsx`](preact.test.tsx) checks Preact's `render()` directly against the UI DOM, including updates, keyed reorders, events, portals, effect cleanup, and terminal repainting. Preact is a development dependency; the test selects its JSX runtime with a file-level pragma.

## Terminal fixtures

Expand All @@ -32,8 +40,6 @@ Include the source or case in the configuration while implementing it. Vitest's
pnpm --filter @clack/ui test src/dom.compatibility.test.ts -t 'Document-createElement.html.*createElement\(foo\)'
```

If the shared package is already built, avoid rebuilding by using `pnpm --filter @clack/ui exec bsh test src/dom.compatibility.test.ts` with the same name filter.

When implementing behavior, read the source-named file under [`src/wpt`](../../web-platform-tests/src/wpt), implement its operations, and update the configuration once its cases pass. Extend the fixture when cases need document parsing, host input, or cleanup. Implementation-specific rendering, notification, and lifecycle checks remain in the UI tests.

## Host input
Expand Down
Loading
Loading