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.