### Run Formbox Docs Locally

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/site/docs/README.md

Use this command to start a local development server for the Formbox documentation site. Ensure pnpm is installed and the project dependencies are set up.

```bash
pnpm --filter @formbox/docs dev
```

--------------------------------

### Run SWM Locally

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/site/swm/README.md

Use this command to start the development server for the SWM package. Ensure pnpm is installed and the package is correctly filtered.

```bash
pnpm --filter @formbox/swm dev
```

--------------------------------

### Install @formbox/strings

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/strings/README.md

Install the package using pnpm or npm.

```bash
pnpm add @formbox/strings
# or
npm install @formbox/strings
```

--------------------------------

### Install Formbox Renderer and Theme

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/renderer/doc/index.md

Install the renderer and a theme package using pnpm or npm.

```bash
pnpm add @formbox/renderer @formbox/hs-theme
# or
npm install @formbox/renderer @formbox/hs-theme
```

--------------------------------

### Install Theme as Dependency

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/theme/doc/index.md

Install the theme package as a regular dependency when you are publishing a theme package.

```bash
pnpm add @formbox/theme
```

--------------------------------

### Install Aidbox Theme and Formbox Renderer

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/af-theme/README.md

Install the necessary packages for the Formbox Renderer and the Aidbox theme using pnpm or npm.

```bash
pnpm add @formbox/renderer @formbox/af-theme
```

```bash
npm install @formbox/renderer @formbox/af-theme
```

--------------------------------

### Install @formbox/fhir

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/fhir/README.md

Install the package using pnpm or npm.

```bash
pnpm add @formbox/fhir
# or
npm install @formbox/fhir
```

--------------------------------

### Install @formbox/theme Package

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/theme/README.md

Install the theme package as a development dependency using pnpm or npm.

```bash
pnpm add -D @formbox/theme
```

```bash
npm install -D @formbox/theme
```

--------------------------------

### Install Aidbox Forms Theme

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/af-theme/doc/index.md

Install the Aidbox Forms Theme package using pnpm.

```bash
pnpm add @formbox/af-theme
```

--------------------------------

### Install NHS Design Theme

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/nshuk-theme/doc/index.md

Install the NHS Design theme package using pnpm.

```bash
pnpm add @formbox/nshuk-theme
```

--------------------------------

### Install Mantine Theme Package

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/mantine-theme/doc/index.md

Install the Mantine theme package using pnpm.

```bash
pnpm add @formbox/mantine-theme
```

--------------------------------

### Install Ant Design Theme Package

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/antd-theme/doc/index.md

Install the Ant Design theme package using pnpm.

```bash
pnpm add @formbox/antd-theme
```

--------------------------------

### Install Formbox Renderer and NHS Theme

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/nshuk-theme/README.md

Install the necessary packages for the Formbox Renderer and the NHS theme using either pnpm or npm.

```bash
pnpm add @formbox/renderer @formbox/nshuk-theme
# or
npm install @formbox/renderer @formbox/nshuk-theme
```

--------------------------------

### Install Ant Design Theme Package

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/antd-theme/README.md

Install the Ant Design theme package along with the Formbox Renderer using pnpm or npm.

```bash
pnpm add @formbox/renderer @formbox/antd-theme
# or
npm install @formbox/renderer @formbox/antd-theme
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/AGENTS.md

Installs project dependencies using pnpm. For CI environments, use the --frozen-lockfile flag to ensure reproducible builds.

```bash
pnpm install
```

```bash
pnpm install --frozen-lockfile
```

--------------------------------

### Install Theme as Dev Dependency

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/theme/doc/index.md

Install the theme package as a development dependency if you only need type definitions in your application.

```bash
pnpm add -D @formbox/theme
```

--------------------------------

### Install Mantine Theme for Formbox Renderer

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/mantine-theme/README.md

Add the necessary packages to your project using pnpm or npm.

```bash
pnpm add @formbox/renderer @formbox/mantine-theme
# or
npm install @formbox/renderer @formbox/mantine-theme
```

--------------------------------

### Install Health Samurai Theme

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/hs-theme/doc/index.md

Install the Health Samurai theme package using pnpm. This command adds the theme to your project dependencies.

```bash
pnpm add @formbox/hs-theme
```

--------------------------------

### Run Storybook Locally

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/site/storybook/README.md

Use this command to run the Storybook package for Formbox Renderer locally. Ensure pnpm is installed and configured.

```bash
pnpm --filter @formbox/storybook dev
```

--------------------------------

### Quick Start with Formbox Renderer

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/renderer/doc/index.md

Basic usage of the Renderer component with a FHIR questionnaire and theme.

```tsx
import Renderer from "@formbox/renderer";
import { theme } from "@formbox/hs-theme";
import "@formbox/hs-theme/style.css";

const questionnaire = {
  resourceType: "Questionnaire",
  item: [
    { linkId: "first", text: "First name", type: "string", required: true },
    { linkId: "consent", text: "Consent to treatment", type: "boolean" },
  ],
};

<Renderer fhirVersion="r5" questionnaire={questionnaire} theme={theme} />;
```

--------------------------------

### Install @types/fhir for Versioned Types

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/fhir/README.md

Install the @types/fhir package as a dev dependency if you plan to use versioned type helpers like QuestionnaireOf.

```bash
pnpm add -D @types/fhir
# or
npm install -D @types/fhir
```

--------------------------------

### Quick Start: Custom Theme Integration

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/theme/README.md

Integrate a custom theme with the Formbox Renderer by extending a base theme and providing custom components. Ensure the Theme type is imported.

```tsx
import type { Theme } from "@formbox/theme";
import Renderer from "@formbox/renderer";
import { theme as baseTheme } from "@formbox/hs-theme";

const theme: Theme = {
  ...baseTheme,
  Label: MyLabel,
};

<Renderer fhirVersion="r5" questionnaire={questionnaire} theme={theme} />;
```

--------------------------------

### EnableWhen Operator AGENTS Example

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-behave/questionnaire/item/enableWhen/operator/AGENTS.md

This JSON snippet demonstrates the structure for defining an enableWhen condition using the AGENTS operator. It specifies that an item should be enabled when a specific agent is present.

```json
{
  "id": "Questionnaire.item.enableWhen.operator",
  "path": "Questionnaire.item.enableWhen.operator",
  "mustSupport": true
}
```

--------------------------------

### Basic Formbox Renderer Usage

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/README.md

Render a FHIR Questionnaire using the Health Samurai theme. Ensure peer dependencies like React, MobX, and fhirpath are installed.

```tsx
import Renderer from "@formbox/renderer";
import { theme } from "@formbox/hs-theme";
import "@formbox/hs-theme/style.css";

const questionnaire = {
  resourceType: "Questionnaire",
  item: [
    { linkId: "first", text: "First name", type: "string", required: true },
    { linkId: "consent", text: "Consent to treatment", type: "boolean" },
  ],
};

export function IntakeForm() {
  return (
    <Renderer fhirVersion="r5" questionnaire={questionnaire} theme={theme} />
  );
}
```

--------------------------------

### Preview Formbox Docs Build

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/site/docs/README.md

After building the documentation site, use this command to preview the static build locally. This helps in verifying the production output before deployment.

```bash
pnpm --filter @formbox/docs preview
```

--------------------------------

### Build Formbox Docs

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/site/docs/README.md

Execute this command to build the static assets for the Formbox documentation site. This is typically used before deployment.

```bash
pnpm --filter @formbox/docs build
```

--------------------------------

### Build SWM Package

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/site/swm/README.md

Execute this command to build the SWM package. This is typically used for production deployments or distribution.

```bash
pnpm --filter @formbox/swm build
```

--------------------------------

### Running Single Tests from Package Directory

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/AGENTS.md

An alternative method to run specific tests by navigating to the package directory first.

```bash
pnpm -C packages/renderer test -- lib/__tests__/utilities.test.ts
```

--------------------------------

### Build Storybook Package

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/site/storybook/README.md

Execute this command to build the Storybook package for Formbox Renderer. This is typically used for production deployment or distribution.

```bash
pnpm --filter @formbox/storybook build
```

--------------------------------

### Using Built-in Theme Packages

Source: https://context7.com/healthsamurai/formbox-renderer/llms.txt

Shows how to import and apply different pre-built themes (Health Samurai, NHS UK, Ant Design, Mantine) to the Formbox Renderer. Note that the Mantine theme requires a Provider wrapper.

```tsx
// Health Samurai theme
import Renderer from "@formbox/renderer";
import { theme as hsTheme } from "@formbox/hs-theme";
import "@formbox/hs-theme/style.css";

// NHS UK Design System theme
import { theme as nhsTheme } from "@formbox/nshuk-theme";
import "@formbox/nshuk-theme/style.css";

// Ant Design theme
import { theme as antdTheme } from "@formbox/antd-theme";
import "@formbox/antd-theme/style.css";

// Mantine theme (requires Provider)
import { Provider, theme as mantineTheme } from "@formbox/mantine-theme";
import "@formbox/mantine-theme/style.css";

const questionnaire = {
  resourceType: "Questionnaire",
  status: "active",
  item: [{ linkId: "q1", text: "How are you?", type: "string" }],
};

// HS theme — no wrapper needed
export const HsForm = () => (
  <Renderer fhirVersion="r5" questionnaire={questionnaire} theme={hsTheme} />
);

// Mantine theme — must wrap with Provider
export const MantineForm = () => (
  <Provider>
    <Renderer fhirVersion="r5" questionnaire={questionnaire} theme={mantineTheme} />
  </Provider>
);
```

--------------------------------

### ValueSet Expansion with Terminology Server

Source: https://context7.com/healthsamurai/formbox-renderer/llms.txt

Demonstrates how the renderer automatically expands ValueSets using a configured terminology server. Per-item preferred servers can be specified using an extension.

```tsx
import Renderer from "@formbox/renderer";
import { theme } from "@formbox/hs-theme";
import "@formbox/hs-theme/style.css";

const questionnaire = {
  resourceType: "Questionnaire",
  status: "active",
  item: [
    {
      linkId: "country",
      text: "Country of birth",
      type: "coding",
      answerValueSet: "http://hl7.org/fhir/ValueSet/iso3166-1-2", // expanded at runtime
    },
    {
      linkId: "condition",
      text: "Primary condition",
      type: "coding",
      answerValueSet: "http://snomed.info/sct?fhir_vs=isa/404684003",
      extension: [
        {
          // Per-item preferred server overrides the global one
          url: "http://hl7.org/fhir/StructureDefinition/questionnaire-preferredTerminologyServer",
          valueUrl: "https://snowstorm.example.org/fhir",
        },
      ],
    },
  ],
};

function ClinicalForm() {
  return (
    <Renderer
      fhirVersion="r5"
      questionnaire={questionnaire}
      theme={theme}
      terminologyServerUrl="https://terminology.example.org/fhir"
    />
  );
}
```

--------------------------------

### Development Commands for @formbox/strings

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/strings/README.md

Run linting, type checking, or build commands for the @formbox/strings package from the repository root.

```bash
pnpm --filter @formbox/strings lint
pnpm --filter @formbox/strings typecheck
pnpm --filter @formbox/strings build
```

--------------------------------

### Linting and Formatting Single Files

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/AGENTS.md

Apply linting rules or format a specific file using pnpm with the renderer package filter.

```bash
pnpm --filter @formbox/renderer lint -- lib/store/form/form-store.ts
```

```bash
pnpm --filter @formbox/renderer format -- lib/store/form/form-store.ts
```

--------------------------------

### OptionsLoading Component

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/theme/doc/reference.md

Loading UI for option-backed controls while options are fetching. Use it to show a spinner or skeleton where options would appear.

```APIDOC
## OptionsLoading

### Description
Loading UI for option-backed controls while options are fetching. Use it to show a spinner or skeleton where options
would appear.

### Props

| Prop        | Type      | Optional | Description                                             |
| ----------- | --------- | -------- | ------------------------------------------------------- |
| `isLoading` | `boolean` | No       | When true, show a loading indicator instead of options. |

The renderer may render `OptionsLoading` in the question scaffold or selection table while options are loading. Option
controls also receive `isLoading`, so avoid duplicating spinners if you render both.
```

--------------------------------

### Use Ant Design Theme with Formbox Renderer

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/antd-theme/README.md

Import the theme and CSS, then apply it to the Renderer component. Ensure the questionnaire object is defined elsewhere.

```tsx
import Renderer from "@formbox/renderer";
import { theme } from "@formbox/antd-theme";
import "@formbox/antd-theme/style.css";

<Renderer fhirVersion="r5" questionnaire={questionnaire} theme={theme} />;
```

--------------------------------

### Common Workspace Commands

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/AGENTS.md

Execute common development and build tasks across all packages in the workspace using pnpm.

```bash
pnpm dev
```

```bash
pnpm build
```

```bash
pnpm lint
```

```bash
pnpm typecheck
```

```bash
pnpm test
```

```bash
pnpm format
```

--------------------------------

### Run Contributor Workflow Commands

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/fhir/README.md

Execute lint, typecheck, test, and build commands for the @formbox/fhir package from the repository root.

```bash
pnpm --filter @formbox/fhir lint
pnpm --filter @formbox/fhir typecheck
pnpm --filter @formbox/fhir test
pnpm --filter @formbox/fhir build
```

--------------------------------

### Pass Launch Context to Renderer

Source: https://context7.com/healthsamurai/formbox-renderer/llms.txt

Make external resources like a Patient or Practitioner available to FHIRPath expressions in the questionnaire by passing a `launchContext` record. Keys map to SDC `launchContext` names defined in the questionnaire's extensions.

```tsx
import Renderer from "@formbox/renderer";
import { theme } from "@formbox/hs-theme";
import "@formbox/hs-theme/style.css";

const questionnaire = {
  resourceType: "Questionnaire",
  status: "active",
  extension: [
    {
      url: "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-launchContext",
      extension: [
        { url: "name", valueCoding: { code: "patient" } },
        { url: "type", valueCode: "Patient" },
      ],
    },
  ],
  item: [
    {
      linkId: "patient-name",
      text: "Patient name",
      type: "string",
      extension: [
        {
          url: "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-initialExpression",
          valueExpression: {
            language: "text/fhirpath",
            expression: "%patient.name.first().text",
          },
        },
      ],
    },
  ],
};

const patient = {
  resourceType: "Patient",
  id: "p1",
  name: [{ text: "Jane Doe" }],
};

function PrePopulatedForm() {
  return (
    <Renderer
      fhirVersion="r5"
      questionnaire={questionnaire}
      theme={theme}
      launchContext={{ patient }}
      onSubmit={(response) => console.log("Submitted:", response)}
    />
  );
}

```

--------------------------------

### Enable Behavior Configuration

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-behave/questionnaire/item/enableBehavior/AGENTS.md

Defines the enable behavior for a questionnaire item, including its ID, path, and support status.

```json
{
  "id": "Questionnaire.item.enableBehavior",
  "path": "Questionnaire.item.enableBehavior",
  "mustSupport": true
}
```

--------------------------------

### EnableWhen Answer Configuration

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-behave/questionnaire/item/enableWhen/answer_x_/AGENTS.md

Defines the configuration for an enableWhen answer, including its ID, path, support status, and mapping.

```json
{
  "id": "Questionnaire.item.enableWhen.answer[x]",
  "path": "Questionnaire.item.enableWhen.answer[x]",
  "mustSupport": true,
  "mapping": [{ "identity": "ihe-sdc", "map": "parent::list_item" }]
}
```

--------------------------------

### Use HS Theme with Formbox Renderer

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/hs-theme/README.md

Import the theme and its styles, then apply it to the Renderer component.

```tsx
import Renderer from "@formbox/renderer";
import { theme } from "@formbox/hs-theme";
import "@formbox/hs-theme/style.css";

<Renderer fhirVersion="r5" questionnaire={questionnaire} theme={theme} />;
```

--------------------------------

### Help Component

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/theme/doc/reference.md

Short help text associated with a node label. Usually rendered near the label and referenced by the control via aria-describedby.

```APIDOC
## Help

### Description
Short help text associated with a node label. Usually rendered near the label and referenced by the control via
aria-describedby.

### Props

| Prop       | Type        | Optional | Description                                              |
| ---------- | ----------- | -------- | -------------------------------------------------------- |
| `id`       | `string`    | No       | Apply as the element id so the control can reference it. |
| `children` | `ReactNode` | No       | Render this help content near the label or input.        |

**Recommended translation strings**

| Path        | Text                                                |
| ----------- | --------------------------------------------------- |
| `aria.help` | Accessible label for help trigger/content controls. |
```

--------------------------------

### Use Aidbox Theme with Formbox Renderer

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/af-theme/README.md

Import the Renderer, the Aidbox theme, and its styles, then pass the theme to the Renderer component.

```tsx
import Renderer from "@formbox/renderer";
import { theme } from "@formbox/af-theme";
import "@formbox/af-theme/style.css";

<Renderer fhirVersion="r5" questionnaire={questionnaire} theme={theme} />;
```

--------------------------------

### GroupScaffold

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/theme/doc/reference.md

Layout shell for a group instance, supporting optional remove actions and error display.

```APIDOC
## GroupScaffold

### Description
Layout shell for a group instance (repeating or not). It can also render an optional remove action and errors.

### Props
- `header` (ReactNode) - Optional - Render the group header (label, help, legal, flyover).
- `children` (ReactNode) - Optional - Render the group body content and nested nodes.
- `errors` (ReactNode) - Optional - Render per-instance validation errors.
- `isExpanded` (boolean) - Required - Current expanded state for collapsible groups.
- `onRemove` (() => void) - Optional - When provided, render a remove action for this instance.
- `canRemove` (boolean) - Optional - When false, render the remove action disabled.

Use `isExpanded` to decide whether to render or visually hide group body content.

### Recommended translation strings
- `group.removeSection`: Label for remove-group-instance action.
```

--------------------------------

### Configure Questionnaire.useContext Element

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-modular-library/questionnaire/useContext/AGENTS.md

Defines the useContext element with slicing rules and a minimum cardinality of 1. This configuration is used to specify context for the questionnaire.

```json
{
  "id": "Questionnaire.useContext",
  "path": "Questionnaire.useContext",
  "slicing": {
    "discriminator": [{ "type": "profile", "path": "$this" }],
    "rules": "open"
  },
  "min": 1
}
```

--------------------------------

### GroupList

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/theme/doc/reference.md

A wrapper for repeating groups, managing instances and the add control.

```APIDOC
## GroupList

### Description
Wrapper around a repeating group that holds the collection of instances and the add control.

### Props
- `linkId` (string) - Required - Use for debugging; typically render as a `data-linkId` attribute and feel free to ignore it.
- `header` (ReactNode) - Optional - Render the header for the repeating group list.
- `children` (ReactNode) - Required - Render each group instance inside the list.
- `onAdd` (() => void) - Optional - When provided, render an add‑group control.
- `canAdd` (boolean) - Optional - When false, render the add control disabled.

### Recommended translation strings
- `group.addSection`: Label for add-group-instance action.
```

--------------------------------

### Package-Scoped Commands with pnpm

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/AGENTS.md

Run scripts for a specific package using the --filter flag. This is preferred for faster execution.

```bash
pnpm --filter @formbox/renderer dev
```

```bash
pnpm --filter @formbox/renderer build
```

```bash
pnpm --filter @formbox/renderer lint
```

```bash
pnpm --filter @formbox/renderer typecheck
```

```bash
pnpm --filter @formbox/renderer test
```

```bash
pnpm --filter @formbox/renderer format
```

```bash
pnpm --filter @formbox/docs dev
```

```bash
pnpm --filter @formbox/docs build
```

```bash
pnpm --filter @formbox/storybook dev
```

```bash
pnpm --filter @formbox/storybook build
```

```bash
pnpm --filter @formbox/swm dev
```

```bash
pnpm --filter @formbox/swm build
```

```bash
pnpm --filter @formbox/hs-theme build
```

```bash
pnpm --filter @formbox/nshuk-theme build
```

```bash
pnpm --filter @formbox/antd-theme build
```

```bash
pnpm --filter @formbox/mantine-theme build
```

--------------------------------

### AssembleDefinitionRoot Extension Definition

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-behave/questionnaire/extension/assembleDefinitionRoot/AGENTS.md

This JSON defines the structure and constraints for the assembleDefinitionRoot extension. It specifies the ID, path, slice name, cardinality, and type, including the profile it must conform to.

```json
{
  "id": "Questionnaire.extension:assembleDefinitionRoot",
  "path": "Questionnaire.extension",
  "sliceName": "assembleDefinitionRoot",
  "min": 0,
  "max": "*",
  "type": [
    {
      "code": "Extension",
      "profile": [
        "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-assembleDefinitionRoot"
      ]
    }
  ],
  "mustSupport": true
}
```

--------------------------------

### Use NHS Theme with Formbox Renderer

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/nshuk-theme/README.md

Import the Renderer, the theme, and its styles, then apply the theme to the Renderer component.

```tsx
import Renderer from "@formbox/renderer";
import { theme } from "@formbox/nshuk-theme";
import "@formbox/nshuk-theme/style.css";

<Renderer fhirVersion="r5" questionnaire={questionnaire} theme={theme} />;
```

--------------------------------

### Use Mantine Provider with Formbox Renderer

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/mantine-theme/README.md

Wrap your Renderer component with the Provider and import the theme and styles. Ensure Mantine components are correctly themed.

```tsx
import Renderer from "@formbox/renderer";
import { Provider, theme } from "@formbox/mantine-theme";
import "@formbox/mantine-theme/style.css";

<Provider>
  <Renderer fhirVersion="r5" questionnaire={questionnaire} theme={theme} />
</Provider>
```

--------------------------------

### AnswerScaffold Component

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/theme/doc/reference.md

The AnswerScaffold component provides the layout for a single answer row, integrating the main control, an optional remove action, and nested content like child nodes and errors.

```APIDOC
## AnswerScaffold

Layout for a single answer row, combining the main control, an optional remove action, and nested content such as child nodes and errors.

### Props

| Prop       | Type         | Optional | Description                                             |
| ---------- | ------------ | -------- | ------------------------------------------------------- |
| `control`  | `ReactNode`  | No       | Render the main input control for this answer instance. |
| `onRemove` | `() => void` | Yes      | When provided, render a remove action for this answer.  |
| `canRemove`| `boolean`    | Yes      | When false, render the remove action disabled.          |
| `errors`   | `ReactNode`  | Yes      | Render per-answer validation errors (Errors).           |
| `children` | `ReactNode`  | Yes      | Render nested content such as child nodes.              |
```

--------------------------------

### Register Custom Question and Group Renderers

Source: https://context7.com/healthsamurai/formbox-renderer/llms.txt

Define custom renderers for specific question or group types by providing `renderers` to the renderer. Each definition includes a `name`, `priority`, `matcher` predicate, and `renderer` component. Higher priority wins; the first matching definition is used.

```tsx
import Renderer from "@formbox/renderer";
import { theme } from "@formbox/hs-theme";
import "@formbox/hs-theme/style.css";
import type {
  QuestionRendererDefinition,
  GroupRendererDefinition,
  IQuestionNode,
  IGroupNode,
} from "@formbox/renderer/types";

// Custom renderer for "coding" type questions with a specific extension
const MyAutocompleteRenderer = ({ node }: { node: IQuestionNode<"coding"> }) => {
  const { answers, answerOption } = node;
  const options = answerOption.select.filteredOptions;

  return (
    <div className="my-autocomplete">
      {options.map((opt) => (
        <button key={opt.token} onClick={() => answerOption.select.selectOption(opt.token)}>
          {/* opt.label is ReactNode */}
          {opt.label}
        </button>
      ))}
    </div>
  );
};

const customQuestionRenderers: QuestionRendererDefinition[] = [
  {
    name: "custom-coding-autocomplete",
    priority: 200, // higher than built-in (max ~121), so it takes precedence
    matcher: (node: IQuestionNode) =>
      node.type === "coding" &&
      node.control === "autocomplete",
    renderer: MyAutocompleteRenderer,
  },
];

// Custom group renderer that adds a colored border to "grid" groups
const MyGridRenderer = ({ node }: { node: IGroupNode }) => (
  <fieldset style={{ border: "2px solid blue" }}>
    <legend>{node.text}</legend>
    {node.visibleNodes.map((child) => (
      <div key={child.linkId}>{/* render child nodes */}</div>
    ))}
  </fieldset>
);

const customGroupRenderers: GroupRendererDefinition[] = [
  {
    name: "colored-grid",
    priority: 50,
    matcher: (node: IGroupNode) => node.control === "grid",
    renderer: MyGridRenderer,
  },
];

function App({ questionnaire }) {
  return (
    <Renderer
      fhirVersion="r5"
      questionnaire={questionnaire}
      theme={theme}
      questionRenderers={customQuestionRenderers}
      groupRenderers={customGroupRenderers}
    />
  );
}

```

--------------------------------

### Questionnaire Item Extension: initialExpression Structure

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-behave/questionnaire/item/extension/initialExpression/AGENTS.md

Defines the structure for the `initialExpression` extension, specifying its ID, path, slice name, cardinality, and type, including the profile for SDC initial expressions.

```json
{
  "id": "Questionnaire.item.extension:initialExpression",
  "path": "Questionnaire.item.extension",
  "sliceName": "initialExpression",
  "min": 0,
  "max": "1",
  "type": [
    {
      "code": "Extension",
      "profile": [
        "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-initialExpression"
      ]
    }
  ]
}
```

--------------------------------

### Running Single Tests with Vitest

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/AGENTS.md

Execute specific tests within the renderer package using pnpm and Vitest. You can target a single file or a test by its name.

```bash
pnpm --filter @formbox/renderer test -- lib/store/form/__tests__/validation.test.ts
```

```bash
pnpm --filter @formbox/renderer test -- -t "filters options by search query"
```

```bash
pnpm --filter @formbox/renderer test -- --run
```

--------------------------------

### Assemble Definition Root Extension Element

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-behave/questionnaire/item/extension/assembleDefinitionRoot/AGENTS.md

This JSON defines the structure for the assembleDefinitionRoot extension, specifying its ID, path, slice name, cardinality, and type, including the profile for SDC questionnaire assemble definition.

```json
{
  "id": "Questionnaire.item.extension:assembleDefinitionRoot",
  "path": "Questionnaire.item.extension",
  "sliceName": "assembleDefinitionRoot",
  "min": 0,
  "max": "*",
  "type": [
    {
      "code": "Extension",
      "profile": [
        "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-assembleDefinitionRoot"
      ]
    }
  ],
  "mustSupport": true
}
```

--------------------------------

### Basic Renderer Usage

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/renderer/README.md

Import and use the Renderer component with a specified FHIR version, questionnaire, and theme.

```tsx
import Renderer from "@formbox/renderer";
import { theme } from "@formbox/hs-theme";
import "@formbox/hs-theme/style.css";

function Form() {
  return (
    <Renderer fhirVersion="r5" questionnaire={questionnaire} theme={theme} />
  );
}
```

--------------------------------

### Apply Health Samurai Theme to Renderer

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/hs-theme/doc/index.md

Use the Health Samurai theme with the Formbox Renderer component. Import the Renderer and the theme, then pass the theme object to the Renderer's theme prop.

```tsx
import Renderer from "@formbox/renderer";
import { theme } from "@formbox/hs-theme";

<Renderer fhirVersion="r5" questionnaire={questionnaire} theme={theme} />;
```

--------------------------------

### Import Compiled CSS

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/themes/mantine-theme/doc/index.md

Import the compiled CSS file for the Mantine theme.

```typescript
import "@formbox/mantine-theme/style.css";
```

--------------------------------

### QuestionScaffold Component

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/theme/doc/reference.md

The QuestionScaffold component serves as a wrapper around a question, organizing its header, control, and validation feedback. It's intended as the outer shell for question nodes.

```APIDOC
## QuestionScaffold

Wrapper around a question that organizes header, control, and validation feedback. Use it as the outer shell for question nodes.

### Props

| Prop         | Type        | Optional | Description                                                                                  |
| ------------ | ----------- | -------- | -------------------------------------------------------------------------------------------- |
| `linkId`     | `string`    | No       | Use for debugging; typically render as a `data-linkId` attribute and feel free to ignore it. |
| `header`     | `ReactNode` | Yes      | Render the question header (label, help, legal, flyover).                                    |
| `children`   | `ReactNode` | No       | Render the question body content, including controls and answer-level errors.                |
| `errors`     | `ReactNode` | Yes      | Render question-level validation errors.                                                     |
| `isExpanded` | `boolean`   | No       | Current expanded state for collapsible questions.                                            |

Use `isExpanded` to decide whether to render or visually hide question body content.
```

--------------------------------

### Questionnaire Launch Context Extension Definition

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-behave/questionnaire/extension/launchContext/AGENTS.md

Defines the structure for the launch context extension within an SDC Questionnaire. This JSON object specifies the metadata for the extension, including its ID, path, slice name, cardinality, and the FHIR profile it adheres to.

```json
{
  "id": "Questionnaire.extension:launchContext",
  "path": "Questionnaire.extension",
  "sliceName": "launchContext",
  "min": 0,
  "max": "*",
  "type": [
    {
      "code": "Extension",
      "profile": [
        "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-launchContext"
      ]
    }
  ]
}
```

--------------------------------

### OptionDisplay

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/theme/doc/reference.md

A wrapper for option labels used in list, dropdown, and table selection controls. It receives already-rendered content and optional option-level adornments.

```APIDOC
## OptionDisplay

### Description
Wrapper for option labels used in list, dropdown, and table selection controls. It receives already-rendered content and optional option-level adornments.

### Props

- **`children`** (ReactNode) - Required - Render the main option label content.
- **`prefix`** (string) - Optional - Optional prefix text for the option (for example, `A.`).
- **`media`** (Attachment) - Optional - Optional media attachment associated with the option label.
```

--------------------------------

### Item Media Extension Definition

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-render/questionnaire/item/extension/itemMedia/AGENTS.md

Defines the structure for the itemMedia extension, specifying its ID, path, slice name, cardinality, and type, including the profile for SDC questionnaire item media.

```json
{
  "id": "Questionnaire.item.extension:itemMedia",
  "path": "Questionnaire.item.extension",
  "sliceName": "itemMedia",
  "min": 0,
  "max": "1",
  "type": [
    {
      "code": "Extension",
      "profile": [
        "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-itemMedia"
      ]
    }
  ]
}
```

--------------------------------

### Assemble Context Extension Definition

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-modular/questionnaire/extension/assembleContext/AGENTS.md

Defines the 'assembleContext' extension for Questionnaire resources. This extension is used to specify how context should be assembled for a questionnaire.

```json
{
  "id": "Questionnaire.extension:assembleContext",
  "path": "Questionnaire.extension",
  "sliceName": "assembleContext",
  "min": 0,
  "max": "*",
  "type": [
    {
      "code": "Extension",
      "profile": [
        "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-assembleContext"
      ]
    }
  ],
  "mustSupport": true
}
```

--------------------------------

### Link Component

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/theme/doc/reference.md

General-purpose link for references and related actions. Render as an anchor or equivalent control with standard link behavior.

```APIDOC
## Link

### Description
General-purpose link for references and related actions surfaced by the renderer. Render as an anchor or equivalent
control with standard link behavior.

### Props

| Prop       | Type        | Optional | Description                                                                           |
| ---------- | ----------- | -------- | ------------------------------------------------------------------------------------- |
| `href`     | `string`    | No       | Set as the anchor destination; the renderer passes a fully qualified or relative URL. |
| `children` | `ReactNode` | No       | Render this content inside the link; it may be plain text or richer markup.           |
| `target`   | `string`    | Yes      | Set the anchor target when provided, for example `_blank` for a new tab.              |
| `rel`      | `string`    | Yes      | Set the anchor rel attribute; when using `_blank`, prefer `noopener noreferrer`.      |

Use standard link behavior; avoid preventing default unless you provide equivalent navigation.
```

--------------------------------

### EnableWhenExpression Extension Definition

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-behave/questionnaire/item/extension/enableWhenExpression/AGENTS.md

This JSON defines the structure for the enableWhenExpression extension, specifying its ID, path, slice name, cardinality, and type, including the profile for SDC.

```json
{
  "id": "Questionnaire.item.extension:enableWhenExpression",
  "path": "Questionnaire.item.extension",
  "sliceName": "enableWhenExpression",
  "min": 0,
  "max": "1",
  "type": [
    {
      "code": "Extension",
      "profile": [
        "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-enableWhenExpression"
      ]
    }
  ],
  "mustSupport": true
}
```

--------------------------------

### Entry Mode Extension Definition

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-behave/questionnaire/extension/entryMode/AGENTS.md

This JSON defines the StructureDefinition for the entryMode extension used in SDC Questionnaires. It specifies the path, slicing, and type information for the extension.

```json
{
  "id": "Questionnaire.extension:entryMode",
  "path": "Questionnaire.extension",
  "sliceName": "entryMode",
  "min": 0,
  "max": "*",
  "type": [
    {
      "code": "Extension",
      "profile": [
        "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-entryMode"
      ]
    }
  ],
  "mustSupport": true
}
```

--------------------------------

### Initial Element JSON Structure

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/abstract-profiles/sdc-questionnairecommon/questionnaire/item/initial/AGENTS.md

Defines the basic structure for an initial element in an SDC questionnaire, including its ID, path, and support status.

```json
{
  "id": "Questionnaire.item.initial",
  "path": "Questionnaire.item.initial",
  "mustSupport": true
}
```

--------------------------------

### Item Optional Display Extension Definition

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-render/questionnaire/item/extension/itemOptionalDisplay/AGENTS.md

Defines the `itemOptionalDisplay` extension for SDC Questionnaire items. This extension is used to control the optional display of an item.

```json
{
  "id": "Questionnaire.item.extension:itemOptionalDisplay",
  "path": "Questionnaire.item.extension",
  "sliceName": "itemOptionalDisplay",
  "mapping": [{ "identity": "ihe-sdc", "map": "N/A (new requirement)" }]
}
```

--------------------------------

### Strong Typing with Renderer

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/packages/renderer/doc/index.md

Utilize versioned type helpers for strong typing of FHIR Questionnaires.

```ts
import type { QuestionnaireOf } from "@formbox/renderer";

const questionnaire: QuestionnaireOf<"r5"> = {
  resourceType: "Questionnaire",
  status: "active",
  item: [{ linkId: "first", text: "First name", type: "string" }],
};
```

--------------------------------

### UnitOpen Extension Structure

Source: https://github.com/healthsamurai/formbox-renderer/blob/master/spec/test/resource-profiles/sdc-questionnaire-behave/questionnaire/item/extension/unitOpen/AGENTS.md

Defines the structure for the UnitOpen extension within an SDC Questionnaire item. This JSON object specifies the extension's ID, path, slice name, cardinality, and type, including its profile.

```json
{
  "id": "Questionnaire.item.extension:unitOpen",
  "path": "Questionnaire.item.extension",
  "sliceName": "unitOpen",
  "min": 0,
  "max": "1",
  "type": [
    {
      "code": "Extension",
      "profile": [
        "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-unitOpen"
      ]
    }
  ]
}
```