IS-11008 HAAPI React SDK documentation

[aleixsuau]

IS-11008 — HAAPI React SDK documentation

Adds a documentation website (built with Docusaurus) that lives inside the SDK at src/haapi-react-sdk/docs. See it live in https://curityio.github.io/ui-kit/haapi-react-sdk/docs or locally running npm ci, then npm run docs -w @curity/haapi-react-sdk-docs (opens at http://localhost:3220).

The pages are built automatically from the SDK's own code, so the docs stay in sync:

• The text on each page comes from the comments written above the SDK components.
• The code examples on each page are real, runnable mini-apps — the actual <HaapiStepper> running against fake (mocked) login data, so readers can try them in the browser.

The docs site extends and overlaps with the current Previewer. Should we keep both?

What's included

• The documentation website and a component that turns an example file into a runnable in-browser demo.
• Scripts that build the pages from the source (run automatically before the site starts):
  • The Overview pages are built from the SDK's README.md (one page per section).
  • The API Reference pages are built from each component's code comments.
  • The Examples section is built from the example files.
  • (All these built pages are git-ignored — only the source is committed.)
• A set of runnable example files, linked from both the code comments and the written docs so the same demo appears next to the relevant text.
• Cleaned-up SDK code comments and README.md (the README is also the source of the Overview pages) — clearer component descriptions and a clearer guide to customizing the UI.
• Setup: registers the docs as its own package, adds a StackBlitz preview, and adjusts the CI/lint/format config so the SDK checks don't run over the docs folder (the docs are a separate project).

How to run: npm ci, then npm run docs -w @curity/haapi-react-sdk-docs (opens at http://localhost:3220).

Verified: the site builds with broken-link checking on; SDK CI passes (formatting, lint, type-check, 282 tests).

Reviewer note — testing the source-code links: the docs link to the SDK source on GitHub using the main branch won't work until merged (so the links 404 until then). To test a link now, replace main in the URL with this branch — feature/IS-11008/haapi-react-sdk-docs.

[Copilot]

Pull request overview

This PR improves the HAAPI React SDK’s documentation experience by restructuring the stepper README into an interactive docs source, enhancing SDK component TSDoc/JSDoc (including example embedding via {@see_example ...} markers), and introducing a dedicated Docusaurus-based documentation workspace with Sandpack-powered live examples.

Changes:

• Refactors haapi-stepper/README.md into an “Overview / actors / customization paths” doc structure with richer guidance and example links.
• Updates many UI components’ TSDoc/JSDoc: normalizes headings, removes @example tags where needed, and adds {@see_example ...} markers to mount live Sandpack examples in generated docs.
• Adds a standalone docs workspace (src/haapi-react-sdk/docs) with generators (split long docs, emit API reference + examples) and Sandpack infrastructure for runnable snippets.

Reviewed changes

Copilot reviewed 88 out of 89 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/haapi-react-sdk/haapi-stepper/ui/messages/HaapiStepperMessageUI.tsx	Adds detailed component TSDoc for single-message rendering semantics.
src/haapi-react-sdk/haapi-stepper/ui/messages/HaapiStepperMessagesUI.tsx	Normalizes doc headings and replaces @example with {@see_example ...} reference.
src/haapi-react-sdk/haapi-stepper/ui/links/HaapiStepperLinkUI.tsx	Adds component TSDoc describing link rendering (regular vs QR code).
src/haapi-react-sdk/haapi-stepper/ui/links/HaapiStepperLinksUI.tsx	Normalizes doc headings, fixes example JSX, and adds {@see_example ...} reference.
src/haapi-react-sdk/haapi-stepper/ui/index.ts	Adds an overview TSDoc block for UI components + exports a doc anchor symbol.
src/haapi-react-sdk/haapi-stepper/ui/actions/HaapiStepperActionsUI.tsx	Adds TSDoc for actions collection component and its interceptor hooks.
src/haapi-react-sdk/haapi-stepper/README.md	Restructures the README into interactive-docs-friendly overview sections and links.
src/haapi-react-sdk/haapi-stepper/feature/steps/HaapiStepperStepUI.tsx	Rewrites/normalizes Step UI TSDoc and adds {@see_example ...} markers for docs.
src/haapi-react-sdk/haapi-stepper/feature/stepper/HaapiStepperHook.ts	Replaces @example with {@see_example ...} marker for generated docs.
src/haapi-react-sdk/haapi-stepper/feature/stepper/HaapiStepperErrorNotifier.tsx	Adds TSDoc and example marker for the error notifier component.
src/haapi-react-sdk/haapi-stepper/feature/stepper/HaapiStepper.tsx	Refreshes stepper TSDoc (config modes, API, error-handling docs) + example markers.
src/haapi-react-sdk/haapi-stepper/feature/actions/selector/HaapiStepperSelectorUI.tsx	Normalizes docs and adds {@see_example ...} marker.
src/haapi-react-sdk/haapi-stepper/feature/actions/form/HaapiStepperFormValidationErrorInputWrapper.tsx	Adds TSDoc and {@see_example ...} marker for validation wrapper usage.
src/haapi-react-sdk/haapi-stepper/feature/actions/form/HaapiStepperFormUI.tsx	Updates docs structure, adds example markers, and clarifies customization approaches.
src/haapi-react-sdk/haapi-stepper/feature/actions/form/fields/HaapiStepperTextFormFieldUI.tsx	Adds TSDoc and example marker for direct text-field placement in custom layouts.
src/haapi-react-sdk/haapi-stepper/feature/actions/form/fields/HaapiStepperSelectFormFieldUI.tsx	Adds TSDoc and example marker for direct select-field placement in custom layouts.
src/haapi-react-sdk/haapi-stepper/feature/actions/form/fields/HaapiStepperPasswordFormFieldUI.tsx	Adds TSDoc and example marker for direct password-field placement in custom layouts.
src/haapi-react-sdk/haapi-stepper/feature/actions/form/fields/HaapiStepperFormFieldUI.tsx	Adds TSDoc and example marker for default field rendering in composed forms.
src/haapi-react-sdk/haapi-stepper/feature/actions/form/fields/HaapiStepperCheckboxFormFieldUI.tsx	Adds TSDoc and example marker for direct checkbox placement in custom layouts.
src/haapi-react-sdk/haapi-stepper/feature/actions/client-operation/HaapiStepperClientOperationUI.tsx	Normalizes docs and adds {@see_example ...} marker.
src/haapi-react-sdk/eslint.config.js	Excludes docs/ from SDK linting (docs is its own workspace/toolchain).
src/haapi-react-sdk/docs/src/sandpack/snippets.ts	Introduces Sandpack snippet file maps (example App.tsx + shared closure).
src/haapi-react-sdk/docs/src/sandpack/closure.ts	Adds Sandpack “closure” providing virtual SDK source, CSS/icons, mocks, and catalog data.
src/haapi-react-sdk/docs/src/components/SandpackPlayer.tsx	Adds a BrowserOnly Sandpack renderer with sensible defaults and sizing heuristics.
src/haapi-react-sdk/docs/src/components/DocExample.tsx	Adds a component to mount generated examples as live Sandpack playgrounds.
src/haapi-react-sdk/docs/sidebars.ts	Adds an autogenerated sidebar configuration for the docs site.
src/haapi-react-sdk/docs/scripts/split-docs.mjs	Adds generator to split long authored MDX into per-section pages.
src/haapi-react-sdk/docs/scripts/extract-tsdoc.mjs	Adds generator to extract/transform TSDoc into MDX blocks + mount examples.
src/haapi-react-sdk/docs/scripts/emit-examples.mjs	Adds generator to build the “Examples” docs tree from a single layout file.
src/haapi-react-sdk/docs/scripts/emit-api-reference.mjs	Adds generator to emit API reference pages from SDK exports’ TSDoc.
src/haapi-react-sdk/docs/scripts/check-tsdoc-headings.mjs	Adds a sentence-case heading checker/fixer for README/TSDoc markdown headings.
src/haapi-react-sdk/docs/scripts/build-sandpack-sdk.mjs	Adds generator to bundle SDK source + examples + CSS into Sandpack-consumable JSON.
src/haapi-react-sdk/docs/README.md	Documents the docs site architecture and how generators map sources → pages.
src/haapi-react-sdk/docs/package.json	Adds the docs workspace package and scripts for generation + Docusaurus.
src/haapi-react-sdk/docs/examples/UseHaapiStepperHook.tsx	Adds runnable docs example for useHaapiStepper.
src/haapi-react-sdk/docs/examples/UiComponentsCompositionUsage.tsx	Adds runnable docs example demonstrating composing UI building blocks.
src/haapi-react-sdk/docs/examples/TextFieldRendering.tsx	Adds runnable docs example for custom placement of the text/username field.
src/haapi-react-sdk/docs/examples/TabbedAuthenticatorUICompositionExample.tsx	Adds advanced runnable docs example (tabbed authenticator selector).
src/haapi-react-sdk/docs/examples/StylesButtonCustomization.tsx	Adds runnable docs example showing CSS-only customization.
src/haapi-react-sdk/docs/examples/StepSelect.tsx	Adds docs preview “step picker” component for browsing mocked step catalog.
src/haapi-react-sdk/docs/examples/StepRenderInterceptorExample.tsx	Adds runnable docs example for full step UI override via interceptor.
src/haapi-react-sdk/docs/examples/StepDataRenderInterceptorExample.tsx	Adds runnable docs example for data-only step customization.
src/haapi-react-sdk/docs/examples/StepDataDetails.tsx	Adds docs panel that renders the raw step JSON (syntax-highlighted) in preview.
src/haapi-react-sdk/docs/examples/StepBuildingBlocks.tsx	Adds runnable docs example for rendering a step via collection building blocks.
src/haapi-react-sdk/docs/examples/StepBehaviorRenderInterceptorExample.tsx	Adds runnable docs example for behavior customization by wrapping nextStep.
src/haapi-react-sdk/docs/examples/SelectorUiUsage.tsx	Adds runnable docs example for selector action UI building block usage.
src/haapi-react-sdk/docs/examples/SelectorReorderRenderInterceptorExample.tsx	Adds runnable docs example for reordering selector options (data customization).
src/haapi-react-sdk/docs/examples/SelectorRenderInterceptorExample.tsx	Adds runnable docs example swapping selector UI for Ant Design Select.
src/haapi-react-sdk/docs/examples/SelectFieldRendering.tsx	Adds runnable docs example for direct placement of select field + hint.
src/haapi-react-sdk/docs/examples/PasswordFieldRendering.tsx	Adds runnable docs example for password field + “forgot password” link.
src/haapi-react-sdk/docs/examples/MessagesRendering.tsx	Adds runnable docs example for messages collection rendering.
src/haapi-react-sdk/docs/examples/MessageRenderInterceptorExample.tsx	Adds runnable docs example for message render interception.
src/haapi-react-sdk/docs/examples/LoadingRenderInterceptorExample.tsx	Adds runnable docs example for loading UI override.
src/haapi-react-sdk/docs/examples/LoadingDataRenderInterceptorExample.tsx	Adds runnable docs example for loading data interception.
src/haapi-react-sdk/docs/examples/LoadingBehaviorRenderInterceptorExample.tsx	Adds runnable docs example for loading “behavior” interception.
src/haapi-react-sdk/docs/examples/LinkUiUsage.tsx	Adds runnable docs example for links collection rendering.
src/haapi-react-sdk/docs/examples/LinkRenderInterceptorExample.tsx	Adds runnable docs example rendering links as buttons via interceptor.
src/haapi-react-sdk/docs/examples/HaapiStepperPreview.tsx	Adds runnable docs “catalog” entry to browse default UI across step examples.
src/haapi-react-sdk/docs/examples/FullCustomizationUICompositionExample.tsx	Adds runnable docs example for full UI composition (Ant Design) + history display.
src/haapi-react-sdk/docs/examples/FormValidationErrorWrapper.tsx	Adds runnable docs example for field-level validation error wrapper.
src/haapi-react-sdk/docs/examples/FormUICompositionExample.tsx	Adds runnable docs example composing a custom form layout (fieldset).
src/haapi-react-sdk/docs/examples/FormSubmitBehavior.tsx	Adds runnable docs example for wrapping submit behavior with custom logic.
src/haapi-react-sdk/docs/examples/FormFieldRenderInterceptorExample.tsx	Adds runnable docs example for per-field form interception.
src/haapi-react-sdk/docs/examples/ExamplePreviewer.tsx	Adds preview chrome wrapper that supplies served-mode config + optional autosubmit.
src/haapi-react-sdk/docs/examples/ErrorPositioningRenderInterceptorExample.tsx	Adds runnable docs example demonstrating different error-banner positioning strategies.
src/haapi-react-sdk/docs/examples/ErrorNotifierExample.tsx	Adds runnable docs example for the toast-based error notifier.
src/haapi-react-sdk/docs/examples/DefaultRendering.tsx	Adds runnable docs example for out-of-the-box default step UI rendering.
src/haapi-react-sdk/docs/examples/config.ts	Adds shared mock bootstrap config used by Sandpack examples.
src/haapi-react-sdk/docs/examples/ConditionalCustomization.tsx	Adds runnable docs example showing conditional custom step replacement.
src/haapi-react-sdk/docs/examples/ComposedLayoutRenderInterceptorExample.tsx	Adds runnable docs example mixing interceptors + building blocks for custom layout.
src/haapi-react-sdk/docs/examples/ClientOperationUiUsage.tsx	Adds runnable docs example for client-operation action UI building block.
src/haapi-react-sdk/docs/examples/ClientOperationRenderInterceptorExample.tsx	Adds runnable docs example customizing client-operation UI with Ant Design.
src/haapi-react-sdk/docs/examples/CheckboxFieldRendering.tsx	Adds runnable docs example for checkbox field placement + extra content.
src/haapi-react-sdk/docs/examples/CaptchaRenderInterceptorExample.tsx	Adds runnable docs example gating login submit behind reCAPTCHA.
src/haapi-react-sdk/docs/examples/BuildingBlocksUICompositionExample.tsx	Adds runnable docs example composing full flow UI from building blocks.
src/haapi-react-sdk/docs/examples/AutoSubmitForm.tsx	Adds preview helper that auto-submits forms so error states are shown by default.
src/haapi-react-sdk/docs/examples/ActionsRenderInterceptorExample.tsx	Adds runnable docs example wrapping the full actions block via interceptor.
src/haapi-react-sdk/docs/examples.entries.mjs	Defines the curated Examples section structure driving page generation.
src/haapi-react-sdk/docs/docusaurus.config.ts	Adds Docusaurus config with strict broken-link checks and ToC tuning.
src/haapi-react-sdk/docs/api-reference.entries.mjs	Defines API Reference sidebar structure and export→page mapping.
src/haapi-react-sdk/docs/.prettierignore	Excludes generated docs outputs and tool artifacts from formatting.
src/haapi-react-sdk/docs/.gitignore	Ignores generated docs output directories and build artifacts.
src/haapi-react-sdk/.prettierignore	Excludes docs/ from SDK workspace Prettier (docs has its own formatting script).
src/haapi-react-app/README.md	Updates app setup docs and adds pointers to the new SDK interactive docs site.
package.json	Adds the docs workspace to repo workspaces.
.stackblitzrc	Adds StackBlitz runtime commands to install deps and run the docs dev server.
.github/workflows/lwa-github-ci-workflow.yml	Updates workspace references for SDK formatting/lint/typecheck/test steps.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[urre]

Living docs are nice!

A few things

1. Product Docs. We should probably create links from product docs also: https://curity.io/docs/identity-server/developer-guide/front-end-development/api-driven/ for example.
2. HAAPI React App is missing from the root README in the UI Kit repo. Can you add that? Also the welcome page that is opened up when you run npm start from the root might need some more instructions and links.
3. When you run npm start the index.html page is the only that that should open, from there you get all the useful links you. Currently also the HAAPI React App previewer opens. No biggie but could if customers see the welcome page so they know what to do.
4. Some Curity brand identifiers are missing from the Docs page, also favicon is missing. Can be added later also.
5. Resources how-tos should be updated. Gary has an open PR on this.

[luisgoncalves]

The end result looks nice overall!

One thing to note is that we already have tooling for product docs, SDK docs, etc, namely from MDX sources. We are pulling in yet another thing - perhaps something to consider in the big picture.

Regarding generating "intermediate content" from examples and SDK code, the amount of manual processing of MD and API docs strings worries me a bit, wrt to future maintenance and robusteness.

About tooling and dependencies, it wasn't clear to me what are dependencies vs devDependencies. For example, GithubSlugger seems to only be used to build the docs site but it's in dependencies. If we consider the docs site the output artifact of this module, then I guess dependencies should only contain what's really needed to run the site (probably bundled after building the final HTML)? Maybe that's already the case and I got it wrong.

About using the SDK README as the entry point for docs: is this a recommended approach? I'm asking because it seems more common to have minimalistic readme's which link to docs sites (e.g. https://github.com/codesandbox/sandpack).
As it is now, some things look a bit weird when seeing the README on GitHub:

• "Browse the HAAPI step catalog" links to an example code file which isn't very helpful without the live preview.
• Same for the link in "the building blocks"
• "Read more" links are broken, because they are defined as relative to the docs root

Regarding the built docs site itself:

• The side-by-side of code and live render is a bit cramped - perhaps it can be made wider.
• The colors on the render preview seem a bit off from the production look & feel (the existing previewer seems closer).
• On the HAAPI response selector, there's no grouping of responses related to the same authenticator or authentication action, so the list becomes confusing. If grouping is not possible, then we may need to prefix labels
• The existing previewer allows live editing HAAPI responses and seeing the result, which isn't the case here. Perhaps that's not the goal of a docs site. But in that case there's no strong benefit in a customer running this locally, since they can access it online and do the same things.

[aleixsuau]

Hey @urre 👋

Thanks for your review!

1. Product Docs. We should probably create links from product docs also: https://curity.io/docs/identity-server/developer-guide/front-end-development/api-driven/ for example.

Ready, I created a separate PR

2. HAAPI React App is missing from the root README in the UI Kit repo. Can you add that?

Luis already added it in https://bitbucket.org/curity/curity-web-ui/pull-requests/3235/overview

2.1. Also the welcome page that is opened up when you run npm start from the root might need some more instructions and links.

I added a button/link to the docs there:

3. When you run npm start the index.html page is the only that that should open, from there you get all the useful links you. Currently also the HAAPI React App previewer opens. No biggie but could if customers see the welcome page so they know what to do.

Done ✅

4. Some Curity brand identifiers are missing from the Docs page, also favicon is missing. Can be added later also.

Added logo, favicon and footer.