Skip to content

docs: ui component accuracy + expose helpers on FocusScopeHandle + enforce FocusScope pairing#60

Merged
zion-off merged 5 commits intomainfrom
update-ui-component-docs
Feb 26, 2026
Merged

docs: ui component accuracy + expose helpers on FocusScopeHandle + enforce FocusScope pairing#60
zion-off merged 5 commits intomainfrom
update-ui-component-docs

Conversation

@zion-off
Copy link
Owner

Summary

  • UI docs audit: fixed inaccurate keybindings tables, wrong default values, nonexistent API references, and redundant prose across select, multi-select, text-input, autocomplete, codeblock, modal, spinner, command-palette, viewport, and terminal docs
  • FocusScopeHandle: navigation helpers (next, prev, nextShallow, prevShallow, escape, drillIn) are now returned directly on the handle — previously only accessible via the keybindings factory. FocusScopeHelpers is now a Pick<> of the handle to avoid duplication
  • <FocusScope> pairing enforcement: calling useFocusScope() without a corresponding <FocusScope handle={scope}> in the render output now throws a GigglesError — previously silently broke navigation
  • File tree example: fixed focus not entering the Select when opening a directory; drillIn() now called directly in the key handler, relying on FocusStore's pending focus queue
  • ShellOutHandle type: corrected run return type from Promise<void> to Promise<{ exitCode: number }>; exported from src/terminal/index.ts
  • Agentic coding context: updated agentic-coding.mdx to reflect helpers on handle, GigglesError enforcement, and accurate Autocomplete keybindings

…ocusScope pairing

- Add next/prev/nextShallow/prevShallow/escape/drillIn to FocusScopeHandle
  return value — helpers were already stable useCallback refs, now accessible
  imperatively from effects and event handlers without a ref workaround
- FocusScopeHelpers becomes Pick<FocusScopeHandle, ...> to avoid duplication
- FocusStore tracks rendered <FocusScope> components via renderedScopes Set;
  useFocusScope throws GigglesError if no corresponding <FocusScope> was rendered
…ee example

- FocusScopeHandle TypeTable expanded with all six navigation helpers
- FocusScopeHelpers section simplified to a Pick<> type reference
- FocusScope section gets a Callout noting the GigglesError on missing wrapper
- File tree example updated to call drillIn() on open, with explanation of
  the pending-focus queue mechanism
@zion-off zion-off merged commit cfb009d into main Feb 26, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant