diff --git a/.changeset/silly-loops-act.md b/.changeset/silly-loops-act.md new file mode 100644 index 000000000..a845151cc --- /dev/null +++ b/.changeset/silly-loops-act.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/README.md b/README.md index ddaf6c024..bc54c8655 100644 --- a/README.md +++ b/README.md @@ -230,9 +230,9 @@ export default function (hunk: HunkExtensionAPI) { ``` See [docs/extensions.md](docs/extensions.md) for the full API, the trust model, -and the `[extensions]` / `[extension.]` config reference. Installable examples -include [review triage](examples/extensions/review-triage/) and an optional -[rendered Markdown file view](examples/extensions/rendered-markdown/). +and the `[extensions]` / `[extension.]` config reference. The +[extension example gallery](examples/extensions/) includes review triage, +rendered Markdown, a minimal JSX file view, and three realistic file-view demos. ### OpenTUI component diff --git a/docs/extensions.md b/docs/extensions.md index 4b7dad9fd..c549c906b 100644 --- a/docs/extensions.md +++ b/docs/extensions.md @@ -1332,21 +1332,18 @@ raised before the UI has mounted are buffered and flushed once it does, so a Record a diagnostic line. Logs are collected per extension rather than written to the terminal, because the TUI owns the screen. -## A complete example +## Complete examples -The examples directory contains two user-installable folder extensions: +The [extension example gallery](../examples/extensions/) contains four opt-in folder extensions: -- [`examples/extensions/review-triage/`](../examples/extensions/review-triage/) - is a session-local hunk triage board combining a sidebar, commands, dialogs, - lifecycle listeners, and the extension event bus. Its API evaluation and - follow-up opportunities are recorded in - [Extension API field notes](extension-api-evaluation.md). -- [`examples/extensions/rendered-markdown/`](../examples/extensions/rendered-markdown/) - parses Markdown into generic host-owned file-view rows. Its README shows how - to run it from the checkout or copy it into the global extensions directory. +- [`review-triage`](../examples/extensions/review-triage/) combines a React sidebar, commands, dialogs, navigation, lifecycle listeners, and the extension event bus. +- [`rendered-markdown`](../examples/extensions/rendered-markdown/) parses Markdown into host-owned file-view rows with source bindings and inline notes. +- [`jsx-file-view`](../examples/extensions/jsx-file-view/) is the smallest hook-using fixed-row React/OpenTUI file view. +- [`jsx-file-view-gallery`](../examples/extensions/jsx-file-view-gallery/) adds TypeScript change-atlas cards, CSS color swatches, dependency-version deltas, and a mixed raw/custom review. -Collapse lockfiles and generated output out of every review, and say how many -files were hidden. +The gallery also points to Hunk's bundled sidebar and VCS backends as production reference implementations. Review triage's API evaluation and follow-up opportunities are recorded in [Extension API field notes](extension-api-evaluation.md). + +For a small single-file extension, collapse generated output out of every review and report how many files were hidden. ```ts // ~/.config/hunk/extensions/collapse-generated.ts diff --git a/examples/README.md b/examples/README.md index 27f879adb..2fef672d2 100644 --- a/examples/README.md +++ b/examples/README.md @@ -20,6 +20,8 @@ Each folder tells a small review story and includes the exact command to run fro ## Installable extension examples +Browse the [extension example gallery](extensions/) for API coverage, exact run commands, and reference implementations. + - [`extensions/review-triage/`](extensions/review-triage/) adds a session-local hunk triage sidebar. - [`extensions/rendered-markdown/`](extensions/rendered-markdown/) adds an optional parsed Markdown file presentation. - [`extensions/jsx-file-view/`](extensions/jsx-file-view/) is the smallest hook-using fixed-row JSX proof of concept. diff --git a/examples/extensions/README.md b/examples/extensions/README.md new file mode 100644 index 000000000..e436b1bfb --- /dev/null +++ b/examples/extensions/README.md @@ -0,0 +1,25 @@ +# Extension examples + +Ready-to-run, opt-in examples for Hunk's experimental TypeScript extension API. None of these folders are bundled or loaded automatically. + +| Example | What it demonstrates | Best starting point for | +| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | +| [`review-triage/`](review-triage/) | A session-local hunk review board built from a React sidebar, commands, dialogs, navigation, lifecycle events, and the extension event bus | Stateful review workflows and custom sidebars | +| [`rendered-markdown/`](rendered-markdown/) | A parsed Markdown presentation using symbolic rows, exact-source bindings, inline notes, and raw-diff fallback | Host-rendered file previews | +| [`jsx-file-view/`](jsx-file-view/) | The smallest fixed-height React/OpenTUI file-view proof of concept, including hooks, semantic theme props, and row fallback | Custom JSX rows | +| [`jsx-file-view-gallery/`](jsx-file-view-gallery/) | TypeScript change-atlas cards, CSS color swatches, dependency-version deltas, and a mixed raw/custom five-file review | Realistic file-view layouts and fallback behavior | + +Each folder has its own README with an exact command and notes on the API contract it exercises. Run an example directly from this checkout with `--extension` while developing. To install one, copy its complete folder into `~/.config/hunk/extensions/` and install any dependency its `package.json` declares. + +## Reference implementations + +Hunk also exercises the public API in its bundled extensions: + +- [`src/extensions/default/ui/sidebar/`](../../src/extensions/default/ui/sidebar/) implements Hunk's built-in file navigation as a registered React sidebar. +- [`src/extensions/default/vcs/`](../../src/extensions/default/vcs/) implements the Git, Jujutsu, and Sapling backends as registered VCS adapters. + +These are production reference implementations rather than installable examples. They remain loaded when user extensions are disabled. + +## Learn the API + +Start with the [extension authoring guide](../../docs/extensions.md), then use the focused website guides for [custom sidebars](https://hunkdiff.dev/docs/extend/custom-sidebars/), [file previews](https://hunkdiff.dev/docs/extend/file-previews/), and [VCS adapters](https://hunkdiff.dev/docs/extend/vcs-adapters/). diff --git a/website/src/content/docs/docs/extend/custom-sidebars.md b/website/src/content/docs/docs/extend/custom-sidebars.md index 09d17eca0..afe6c2128 100644 --- a/website/src/content/docs/docs/extend/custom-sidebars.md +++ b/website/src/content/docs/docs/extend/custom-sidebars.md @@ -3,7 +3,9 @@ title: Custom sidebars description: Render your own React sidebar view inside Hunk, with selection, scrolling, and event-driven state. --- -`hunk.registerSidebarView(view)` contributes a sidebar view — your own React component, rendered inside Hunk's OpenTUI tree. Registration is additive: your view exists beside the built-in file navigation, on either side of the review stream, and any number of views can be open at once. Pair it with [`registerCommand`](/docs/extend/extension-api/#hunkregistercommandcommand-handler) so a key opens it: +`hunk.registerSidebarView(view)` contributes a sidebar view — your own React component, rendered inside Hunk's OpenTUI tree. Registration is additive: your view exists beside the built-in file navigation, on either side of the review stream, and any number of views can be open at once. Pair it with [`registerCommand`](/docs/extend/extension-api/#hunkregistercommandcommand-handler) so a key opens it. + +For a complete installable example, [review triage](https://github.com/modem-dev/hunk/tree/main/examples/extensions/review-triage) combines a right sidebar with hunk navigation, commands, dialogs, lifecycle events, and session-local state. The smallest standalone sidebar looks like this: ```tsx // ~/.config/hunk/extensions/flat-sidebar.tsx diff --git a/website/src/content/docs/docs/extend/extensions.md b/website/src/content/docs/docs/extend/extensions.md index 3f6200aca..b022edadd 100644 --- a/website/src/content/docs/docs/extend/extensions.md +++ b/website/src/content/docs/docs/extend/extensions.md @@ -115,7 +115,18 @@ some_key = "some value" `[extensions] enabled` layers like every other option (repo config overrides user config); `--no-extensions` is a hard off switch no config layer can re-enable. `[extension.]` tables pass through to the extension uninterpreted — see [`hunk.config`](/docs/extend/extension-api/#hunkconfig) for the merge rules and their caveats. -## A complete example +## Example gallery + +The repository's [extension example gallery](https://github.com/modem-dev/hunk/tree/main/examples/extensions) collects four opt-in folder extensions: + +- [Review triage](https://github.com/modem-dev/hunk/tree/main/examples/extensions/review-triage) combines a React sidebar, commands, dialogs, navigation, lifecycle events, and the extension event bus. +- [Rendered Markdown](https://github.com/modem-dev/hunk/tree/main/examples/extensions/rendered-markdown) builds a host-rendered file preview with exact-source bindings and inline notes. +- [JSX file view](https://github.com/modem-dev/hunk/tree/main/examples/extensions/jsx-file-view) is the smallest fixed-height React/OpenTUI row example. +- [JSX file-view gallery](https://github.com/modem-dev/hunk/tree/main/examples/extensions/jsx-file-view-gallery) includes TypeScript, CSS color, dependency-version, and mixed-review demos. + +Each README includes an exact command. The examples are not bundled or loaded automatically. + +## A single-file example Collapse lockfiles and generated output out of every review, and say how many files were hidden. diff --git a/website/src/content/docs/docs/extend/file-previews.md b/website/src/content/docs/docs/extend/file-previews.md index d3594fea3..f7fec776f 100644 --- a/website/src/content/docs/docs/extend/file-previews.md +++ b/website/src/content/docs/docs/extend/file-previews.md @@ -213,6 +213,8 @@ A `null`, invalid, oversized, cancelled, timed-out, or throwing layout produces ## Examples +Browse the complete [extension example gallery](https://github.com/modem-dev/hunk/tree/main/examples/extensions), or jump directly to a file-view example: + - [Rendered Markdown](https://github.com/modem-dev/hunk/tree/main/examples/extensions/rendered-markdown) is an installable symbolic-row preview with exact-source bindings and inline notes. - [JSX file view](https://github.com/modem-dev/hunk/tree/main/examples/extensions/jsx-file-view) demonstrates fixed-height React/OpenTUI rows. - [JSX file-view gallery](https://github.com/modem-dev/hunk/tree/main/examples/extensions/jsx-file-view-gallery) includes TypeScript, CSS color, package dependency, and mixed raw/custom review examples.