xonecas.io
70160
Ce

cel-tui / commit b0fe6fc

docs: review pass — fix spec example, update package metadata, add TODOs

- spec.md: update text editor onScroll example to use named param
- AGENTS.md: document scroll clamping in paint.ts description
- TODO.md: add scrollbar padding bug, duplicate maxOffset code
- TODO.md: add Markdown inline styling as not-yet-implemented
- TODO.md: update chat UI example as completed
- package.json: update components description and keywords

xonecas2026-04-04 b0fe6fc9285e92715b48e89767d9b3172874878e parent c7eeb07

4 files changed

AGENTS.md+1−1
@@ -205,7 +205,7 @@ chore: scaffold monorepo with types, core, components packages
205205
206206 - `cel.ts` — Framework entrypoint. Owns render loop, input dispatch, focus management. `cel.init(terminal)` starts, `cel.viewport(fn)` sets render function, `cel.render()` requests re-render, `cel.stop()` restores terminal. Mouse input handles batched SGR events (terminals often send multiple events in a single data chunk).
207207 - `layout.ts` — Flexbox engine. `layout(root, width, height)` → `LayoutNode` tree with absolute screen rects.
208-- `paint.ts` — Paints `LayoutNode` tree into `CellBuffer`. Handles clip rects, scroll offsets, scrollbars, grapheme-aware text rendering, TextInput cursor/scroll state, container bgColor fill, style inheritance threading, focusStyle resolution.
208+- `paint.ts` — Paints `LayoutNode` tree into `CellBuffer`. Handles clip rects, scroll offsets (clamped to max — apps can pass `Infinity` to mean "scroll to end"), scrollbars, grapheme-aware text rendering, TextInput cursor/scroll state, container bgColor fill, style inheritance threading, focusStyle resolution.
209209 - `emitter.ts` — `emitBuffer()` for full renders, `emitDiff()` for differential. Both wrap in CSI 2026 synchronized output.
210210 - `hit-test.ts` — `hitTest(root, x, y)` → path from root to deepest node. `findClickHandler`, `findScrollTarget`, `collectKeyPressHandlers`, `collectFocusable` walk paths.
211211 - `keys.ts` — Kitty keyboard protocol parser. `parseKey(data)` handles CSI u sequences (special keys, modifier combos), CSI letter sequences (arrows, Home/End with modifiers), CSI tilde sequences (Delete, PageUp/Down, F-keys with modifiers), and raw printable bytes. Maps `" "` → `"space"`, `"+"` → `"plus"` as named keys. `isEditingKey()` identifies keys consumed by TextInput. `normalizeKey()` reorders modifiers to canonical `ctrl+alt+shift+<key>` order.
TODO.md+7−1
@@ -16,6 +16,10 @@ Remaining work, known bugs, and planned improvements.
1616
1717 - 🔧 **Controlled-focus TextInput traps Tab traversal** — When a controlled-focus TextInput (`focused` prop provided) is the first focusable element, Tab from unfocused state always focuses it. Once focused, Tab is consumed as an editing key. Escape unfocuses it, but the next Tab re-focuses it again — the user can never Tab past it to reach subsequent focusable elements. Visible in `examples/pet.ts` on the create screen: the name TextInput prevents keyboard access to the Create Pet button. …
1818
19+- 🔧 **Scrollbar thumb position ignores padding** — `paintScrollbar` in `paint.ts` computes `maxOffset = contentHeight - rect.height` without accounting for container padding, while the scroll clamping logic uses `contentHeight + padY - rect.height`. For padded scrollable containers the thumb position is slightly off.
20+
21+- 🔧 **Duplicate max scroll offset calculation** — `getMaxScrollOffset` in `cel.ts` and `computeMaxScrollOffset` in `paint.ts` implement the same logic. Should be extracted to a shared function.
22+
1923 ---
2024
2125 ## API Improvements
@@ -26,8 +30,10 @@ Remaining work, known bugs, and planned improvements.
2630
2731 - ❌ Bracketed paste mode support
2832
33+- ❌ **Markdown inline styling** — The `Markdown` component renders block-level styling (headings, code blocks, lists, blockquotes, HR) but strips inline formatting (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`) to plain text. Rendering inline styles requires either framework support for styled spans within `Text` content (e.g., ANSI-in-content parsing in paint.ts) or pre-computed line breaking with width knowledge. See `packages/components/src/markdown.ts`.
34+
2935 ## Future Enhancements
3036
31-- 💡 Additional example apps (chat UI, text editor from spec reference examples)
37+- 💡 Additional example apps (text editor from spec reference example)
3238 - 💡 `overflow: "hidden"` as explicit prop (currently all containers clip by default, which matches the spec's default behavior, but the prop value is not checked)
3339 - 💡 Higher Kitty protocol levels — key-release events (level 2), associated text (level 3), and full event types (level 4) for advanced input patterns (games, physical key layout awareness)
packages/components/package.json+2−1
@@ -1,7 +1,7 @@
11 {
22 "name": "@cel-tui/components",
33 "version": "0.1.0",
4- "description": "Pre-made components for cel-tui — Button, Spacer, Divider",
4+ "description": "Pre-made components for cel-tui — Button, Spacer, Divider, VDivider, Select, Markdown",
55 "type": "module",
66 "module": "src/index.ts",
77 "types": "./src/index.ts",
@@ -27,6 +27,7 @@
2727 "terminal",
2828 "components",
2929 "button",
30+ "markdown",
3031 "typescript"
3132 ],
3233 "dependencies": {
spec.md+2−2
@@ -810,8 +810,8 @@ cel.viewport(() =>
810810 width: 20,
811811 overflow: "scroll",
812812 scrollOffset: sidebarScroll,
813- onScroll: (o) => {
814- sidebarScroll = o;
813+ onScroll: (newOffset) => {
814+ sidebarScroll = newOffset;
815815 },
816816 },
817817 [