docs(runtime): finish the useWindowSize rename in docs; tidy contract guards (#164)
Follow-up cleanup for the 7 confirmed findings from a review of #163. The dominant theme: #163 hard-renamed the public composable useTerminalSize -> useWindowSize (no alias) but left stale references to the dead name in user-facing docs. - README.md + packages/runtime/README.md: the composable tables named the removed `useTerminalSize()` (root README even framed the sole real export `useWindowSize` as an "Ink-compat alias" — now inverted). Point both at `useWindowSize()`. - .agents/docs/ink-divergences.md: two vue-tui-side references to `useTerminalSize` (the shallowRef "object of refs" example and the "composables throw outside a render tree" list) -> `useWindowSize`. The Ink-side `useWindowSize -> WindowSize` naming example is left unchanged. - .agents/docs/accessibility-api.md: the intro cited three "blessed entries" but only aria-camelCase is one; `renderToString` layout-only and the `useWindowSize` name are now Ink parity, not divergences. Reword. - .agents/docs/api-contract.md: tighten the `/internal` wording — the test does assert one tripwire on `/internal`, so "not covered by public-api.test.ts" was imprecise. - public-api.test.ts / render-to-string.test.tsx: the public renderToString dropped the `isScreenReaderEnabled` option but (unlike the sibling `ScreenReaderOptions` type) had no compile-time guard. Replace an obscure, fmt-fragile type-indexing guard with a readable call-site `@ts-expect-error` in render-to-string.test.tsx; re-adding the option to the public RenderToStringOptions makes the directive unused and fails `tsc --noEmit`. - Rename terminal-size.test.tsx / .sequential.test.tsx -> window-size.test.tsx / .sequential.test.tsx to match the migrated symbol. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,10 +1,11 @@
|
||||
# Accessibility (ARIA + screen-reader) API
|
||||
|
||||
How vue-tui exposes ARIA and renders screen-reader (SR) output, and why. Companion to the terse
|
||||
blessed entries in [[ink-divergences]] (aria props are camelCase; `renderToString` is layout-only;
|
||||
`useWindowSize`); this file keeps the _why_ and the researched / run-verified findings the ledger
|
||||
entries deliberately omit, so they are not re-derived expensively. The exported aria types are
|
||||
part of the public contract — see [[api-contract]].
|
||||
How vue-tui exposes ARIA and renders screen-reader (SR) output, and why. Companion to the
|
||||
aria-camelCase blessed entry in [[ink-divergences]]; `renderToString` being layout-only and the
|
||||
`useWindowSize` name are now Ink parity (not divergences), and the reactive-refs return shape is
|
||||
covered by the shallowRef entry there. This file keeps the _why_ and the researched / run-verified
|
||||
findings those entries deliberately omit, so they are not re-derived expensively. The exported aria
|
||||
types are part of the public contract — see [[api-contract]].
|
||||
|
||||
## The constraint that shapes everything
|
||||
|
||||
|
||||
@@ -31,8 +31,9 @@ Because it is contract, it is **tested, not merely shipped**:
|
||||
|
||||
`@vue-tui/runtime/internal` is an explicitly internal / advanced surface — host-node types
|
||||
(`TuiNode`, …), test-only helpers (`renderToStringWithScreenReader`), dev/HMR types (`DevState`,
|
||||
`DevErrorInfo`), kitty-controller internals, etc. It carries **no stability guarantee**, is not
|
||||
covered by `public-api.test.ts`, and may change freely between releases.
|
||||
`DevErrorInfo`), kitty-controller internals, etc. It carries **no stability guarantee**: its
|
||||
surface is not snapshotted by `public-api.test.ts` (a member may be tripwired there to prove it is
|
||||
internal, but the surface itself carries no contract), and may change freely between releases.
|
||||
|
||||
Placement rule for any export:
|
||||
|
||||
|
||||
@@ -182,7 +182,7 @@ current-props model, or API conventions.
|
||||
snapshot: it would freeze at setup time. vue-tui returns a **`shallowRef`** whose `.value`
|
||||
updates and re-renders the template; read these as `.value`. Every stateful composable
|
||||
follows this — `useFocusManager().activeId` is a single ref read as `.value`, while a
|
||||
composable may instead return an **object of refs** (`useTerminalSize()` returns
|
||||
composable may instead return an **object of refs** (`useWindowSize()` returns
|
||||
`{ columns, rows }`, read as `.columns.value` / `.rows.value`). An empty single-ref state
|
||||
holds `null` (Vue's convention for an empty ref: a template ref is `ref<T | null>(null)`),
|
||||
where Ink's plain value is `undefined`.
|
||||
@@ -611,7 +611,7 @@ different runtime behavior, ownership rule, or out-of-contract handling.
|
||||
|
||||
- **Ink:** the hooks read a React context whose **default** value is a no-op object, so
|
||||
calling e.g. `useStdin()` outside an Ink tree returns inert defaults without an error.
|
||||
- **vue-tui:** `useApp`, `useStdout`, `useStderr`, `useStdin`, `useTerminalSize`,
|
||||
- **vue-tui:** `useApp`, `useStdout`, `useStderr`, `useStdin`, `useWindowSize`,
|
||||
`useFocus`, `useFocusManager`, `useInput`, `usePaste`, `useCursor`, and
|
||||
`useIsScreenReaderEnabled` **throw** when their context is absent ("... must be called
|
||||
inside a vue-tui render tree"). `useBoxMetrics` and `useAnimation` do **not** throw:
|
||||
|
||||
Reference in New Issue
Block a user