Files
kandev/docs/plans/resizable-markdown-tables/plan.md
T
2026-08-24 11:09:03 +00:00

182 lines
7.9 KiB
Markdown

---
spec: docs/specs/ui/requirements/resizable-markdown-tables.md
created: 2026-08-05
status: complete
---
# Implementation Plan: Resizable Markdown Table Columns
## Overview
Add ephemeral, accessible column resizing to the shared Markdown table renderer
without weakening the wrapping repair already covered by chat browser tests.
Desktop fine-pointer users receive full-height inline separators; phone and
coarse-pointer layouts retain automatic wrapping and local scrolling with no
resize controls.
## Frontend design
### Width geometry
Add a small pure geometry module under `apps/web/lib/markdown/` that adjusts an
adjacent width pair while preserving its sum and enforcing the 64-pixel minimum.
Use the same function for pointer and keyboard input so clamping behavior has one
testable source of truth. If the pair totals less than 128 pixels, leave both
widths unchanged because the total-width and dual-minimum constraints cannot
otherwise both hold.
### Resizable table component
Extract the shared renderer's current table wrapper into a client component,
likely `apps/web/components/shared/resizable-markdown-table.tsx`.
- Render the semantic `<table>` unchanged in automatic mode.
- Measure the table and its header cells after layout. A `ResizeObserver` keeps
separator positions aligned while automatic content or container geometry
changes, and controlled column-width updates explicitly trigger another
measurement even when the table's outer box is unchanged. Observe character
data as well as child-list mutations so streamed text updates also remeasure.
- Place focusable `role="separator"` controls in an overlay within the table's
scroll content. Each control is centered on an internal boundary, spans the
full table height, and scrolls with the table. Omit a boundary while either
adjacent measured column is below the 64-pixel minimum.
- Give each separator an adjacent-column accessible name, vertical orientation,
a 64-pixel minimum, the rounded current left-column width, and a maximum equal
to the pair total minus the right-column minimum. Verify those rendered ARIA
semantics in Playwright alongside keyboard behavior.
- On first adjustment, snapshot measured widths and apply them through a
`<colgroup>` with fixed table layout. Keep the measured table width constant so
one adjacent column grows exactly as the other shrinks. Do not activate fixed
widths until pointer movement has a non-zero delta.
- Use pointer capture for dragging. Restore the drag-start snapshot on
`pointercancel`, and clean up cursor and selection overrides on every exit
path.
- Double-click or `Enter` clears the custom width state and returns the table to
CSS automatic layout. A changed column count does the same.
- Render controls only when the responsive capability is non-phone and
fine-pointer. Tables that cannot provide valid multi-column geometry stay
automatic. A capability change during a drag also clears the active drag and
document-level cursor and selection overrides.
### Styling and localization
Add narrowly scoped Markdown-table classes in `apps/web/app/globals.css` for the
relative stage, separator hit area, and hover/focus/active line. Preserve the
existing `overflow-x-auto` wrapper and the two-/three-column wrapping and
four-plus-column minimum-width policies.
Add the separator's accessible name to the shared English locale and access it
through `t()`; no visible copy or public documentation is added.
## Responsive and mobile implementation
The nearest mobile exemplar is the current task-chat Markdown table tested by
`mobile-markdown-wrap.spec.ts`. The component shares parsing, measurement-safe
markup, wrapping, and the local scroll owner at every viewport. It suppresses
the separator overlay on phones and coarse pointers because a usable touch hit
target would obstruct narrow table content. Mobile capability remains complete
for reading and scrolling; only the optional precision adjustment is desktop
specific.
## Tests
### Unit tests
- RED: adjacent-pair resizing grows and shrinks by equal amounts.
- RED: both drag directions clamp at 64 pixels without changing the pair total.
- RED: keyboard deltas use the same geometry behavior.
- Cover the resize hook's keyboard branches, capability-disable reset, and
column-count-change reset in a focused hook test.
- GREEN: implement the geometry module and table component, then wire it into
`markdown-components.tsx`.
- The repository does not add isolated React component tests for pure UI.
Playwright covers separator semantics, rendered geometry, reset behavior, and
responsive capability gating through the real shared renderer.
Likely files:
- `apps/web/lib/markdown/table-resize.ts`
- `apps/web/lib/markdown/table-resize.test.ts`
- `apps/web/components/shared/resizable-markdown-table.tsx`
- `apps/web/components/shared/use-markdown-table-resize.ts`
- `apps/web/components/shared/use-markdown-table-resize.test.ts`
- `apps/web/components/shared/markdown-components.tsx`
- `apps/web/app/globals.css`
- `apps/web/src/locales/en/common.json`
### Browser tests
Extend the existing chat Markdown wrapping suites rather than creating a second
fixture path.
- Desktop: render a three-column table, start a drag at a body-row point on the
full-height boundary, and assert adjacent widths change, the untouched column
and total width remain stable, and minimum-width clamping works.
- Desktop: assert double-click returns near the initial automatic proportions;
assert arrow keys resize and `Enter` resets.
- Desktop wide table: scroll its local wrapper and assert separators remain
aligned and no chat/document overflow appears.
- Mobile Chrome: assert no separators are exposed while the existing ordinary
wrapping and wide-table local scrolling checks still pass.
Likely files:
- `apps/web/e2e/tests/chat/markdown-wrap.spec.ts`
- `apps/web/e2e/tests/chat/mobile-markdown-wrap.spec.ts`
## Implementation waves
Execution is sequential in the primary conversation. The E2E work depends on
the renderer contract, and this package does not authorize subagent use.
- [x] [Task 01: Build the ephemeral resize renderer](task-01-build-resize-renderer.md)
- [x] [Task 02: Prove desktop interaction and mobile parity](task-02-prove-resize-interaction.md)
## Verification
```bash
(cd apps && pnpm install --frozen-lockfile)
(cd apps && pnpm --filter @kandev/web exec vitest run \
lib/markdown/table-resize.test.ts \
components/shared/use-markdown-table-resize.test.ts \
components/shared/markdown-components.test.tsx)
(cd apps/web && pnpm run typecheck)
(cd apps && pnpm --filter @kandev/web lint)
make build-web
(cd apps/web && pnpm e2e:run tests/chat/markdown-wrap.spec.ts)
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/chat/mobile-markdown-wrap.spec.ts)
```
## Documentation impact
The durable UI spec and plan cover the new behavior. No public CLI, config, API,
or workflow documentation changes are required.
## Risks
- Separator geometry must use the scroll content's coordinate system; viewport
coordinates would drift after horizontal scrolling.
- Streaming updates can change row height or column count after initial render.
Observation must update positions, while structure changes must discard custom
widths.
- Fixed widths must activate only after user adjustment. Applying them on first
render would regress responsive automatic wrapping.
- Pointer cancellation and unmount must restore global cursor and text-selection
state to avoid a sticky resize cursor elsewhere in the app.
- Component tests run in jsdom, so deterministic width math belongs in a pure
helper and real geometry assertions belong in Playwright.
## Open questions
None.
## Verification results
- `vitest`: 42 focused geometry/hook/shared-renderer tests passed.
- `pnpm run typecheck`: passed.
- `pnpm --filter @kandev/web lint`: passed with zero warnings.
- `make build-web`: passed.
- Desktop `markdown-wrap.spec.ts`: 8 tests passed.
- Mobile Chrome `mobile-markdown-wrap.spec.ts`: 2 tests passed.
- `git diff --check`: passed.