xonecas.io
70160
Ce

cel-tui / files

cel-tui / MIGRATION.md

4.1 KB
1# Migrating from 0.8.x to 0.9.0
2
3`0.9.0` is a breaking minor release while cel-tui is pre-1.0. Upgrade every
4installed `@cel-tui/*` package together:
5
6```bash
7bun add @cel-tui/core@0.9.0 @cel-tui/components@0.9.0 @cel-tui/clew@0.9.0 @cel-tui/types@0.9.0
8```
9
10## Required changes
11
12### Use only supported `TextInput` props
13
14`TextInputProps` now uses an explicit `TextInputBaseProps` allowlist. It no
15longer accepts child-layout props (`gap`, `justifyContent`, `alignItems`,
16`flexWrap`), container scroll props (`overflow`, `scrollOffset`, `scrollbar`,
17`scrollbarStyle`, `onScroll`), or `onClick`.
18
19Move child layout and click handling to a wrapping `VStack` or `HStack`.
20TextInput scrolling remains framework-managed; use `scrollStep` to customize
21mouse-wheel movement.
22
23### Make controlled scrolling explicit
24
25Scroll ownership is now determined only by `scrollOffset`. An `onScroll`
26callback without `scrollOffset` observes an uncontrolled container; after the
27callback accepts the event, the framework updates its own offset.
28
29```ts
30let offset = 0;
31
32VStack(
33  {
34    overflow: "scroll",
35    scrollOffset: offset,
36    onScroll: (nextOffset) => {
37      offset = nextOffset;
38      cel.render();
39    },
40  },
41  children,
42);
43```
44
45Return exactly `false` from `onScroll` to reject that target and bubble to the
46next scrollable ancestor.
47
48### Replace cell mutation with `CellBuffer.set()`
49
50`Cell` fields and `EMPTY_CELL` are readonly. Replace in-place mutation:
51
52```ts
53const cell = buffer.get(x, y);
54buffer.set(x, y, { ...cell, char: "X" });
55```
56
57### Stop using private `cel` test hooks
58
59The public `cel` value is now typed as `Cel`; `_getBuffer()` and `_flush()` are
60no longer part of the package API. Test through `MockTerminal`, `CellBuffer`,
61and the public emitter functions. Use `cel.redraw()` for a forced full frame
62and `cel.setTheme()` for runtime palette changes.
63
64## Behavior to review
65
66- `onKeyPress` now receives `(key, event)`. Existing one-argument handlers are
67  valid. If Kitty event-type reporting is enabled, release events reach handlers
68  but never trigger framework editing, focus, activation, or blur actions.
69- If enabling `kittyKeyboard.reportAllKeys`, also enable
70  `reportAssociatedText` when TextInputs must insert typed text. Associated-text
71  reporting implies all-key reporting.
72- `FocusChangeReason` includes `"auto"`. Add it to exhaustive switches when
73  using `autoFocus`.
74- `TextInput({ focusable: false })` now prevents both Tab traversal and mouse
75  focus. Remove the prop if the previous ignored behavior was intentional.
76- Focus belongs to the active topmost layer. Add a unique `stateKey` to
77  stateful nodes that can reorder or recreate callbacks so focus, scroll, and
78  TextInput state follow the logical node.
79- `Select` is now backed by `TextInput`: queries preserve exact case and spaces,
80  cursor editing is grapheme-aware, and Home/End move the query cursor instead
81  of jumping through results. The callable `select()` form and one-argument
82  `onSelect(value)` callbacks remain valid; the callback may also receive the
83  normalized item.
84- Syntax theme registrations are readonly values. Replace a theme object to
85  change it rather than mutating it. Direct `SyntaxHighlight()` calls remain
86  valid; use one `createSyntaxHighlight()` instance per append-heavy snippet
87  and call `.dispose()` when it is no longer needed.
88- `ClewToken.start` and `.end` are UTF-16 code-unit offsets. They can be passed
89  directly to JavaScript `slice()` and `substring()`. Corrected stable patches
90  and Bash tokenization may also update exact token snapshots.
91- Low-level ANSI and layout snapshots may change: full frames establish an SGR
92  reset baseline, and corrected wrapping, clipping, and wide-cell handling can
93  alter previously invalid output. Rebaseline only after checking the rendered
94  result.
95
96Custom `Terminal` adapters may accept the new optional third argument to
97`start(onInput, onResize, options)` and forward `options.kittyKeyboard` when
98they support Kitty progressive-enhancement flags. `ProcessTerminal` now cleans
99up and then terminates normally on SIGINT/SIGTERM; use an app-owned shutdown
100path with `cel.stop()` when graceful work must finish first.