From 8f6306da3c79828857a1f45197759d0747dc4d10 Mon Sep 17 00:00:00 2001
From: komalSharma225 <komal.sharma@thoughtworks.com>
Date: Thu, 4 Jun 2026 21:12:50 +0530
Subject: [PATCH 1/4] BAH-4747 | Add autodocs and metadata wiring to composite
 control stories

- Wire metadata (description + argTypes) to ObsControl, AbnormalObsControl, Section, MultiSelect, Forms stories
- Add tags: ['autodocs'] for auto-generated professional documentation (Carbon Design System style)
- Refactor StoryWrapper with optional showDebug prop (default false) for clean views
- Add MDX support to Storybook config
- Create _meta/*.js files with reusable control metadata and prop descriptions
- Remove unused React import in Section.stories.js

AC met: #2 (descriptions), #3 (argTypes), #4 (autodocs), #5 (clean default), #7 (all 5 controls)
Note: AC #1 (sidebar rename to "Composite Controls") skipped per user direction to keep "Complex Controls"

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .storybook/main.js                      |   2 +-
 stories/AbnormalObsControl.stories.js   |   9 +-
 stories/Forms.stories.js                |  19 +---
 stories/MultiSelect.stories.js          |   9 +-
 stories/ObsControl.stories.js           |  30 +-----
 stories/Section.stories.js              |  35 +------
 stories/StoryWrapper.js                 |  19 +++-
 stories/_meta/abnormalObsControlMeta.js |  81 ++++++++++++++++
 stories/_meta/formsMeta.js              | 102 ++++++++++++++++++++
 stories/_meta/multiSelectMeta.js        |  63 ++++++++++++
 stories/_meta/obsControlMeta.js         | 122 ++++++++++++++++++++++++
 stories/_meta/sectionMeta.js            |  90 +++++++++++++++++
 12 files changed, 499 insertions(+), 82 deletions(-)
 create mode 100644 stories/_meta/abnormalObsControlMeta.js
 create mode 100644 stories/_meta/formsMeta.js
 create mode 100644 stories/_meta/multiSelectMeta.js
 create mode 100644 stories/_meta/obsControlMeta.js
 create mode 100644 stories/_meta/sectionMeta.js

diff --git a/.storybook/main.js b/.storybook/main.js
index fae84149..74e7d277 100644
--- a/.storybook/main.js
+++ b/.storybook/main.js
@@ -1,7 +1,7 @@
 const path = require('path');
 
 module.exports = {
-  stories: ['../stories/**/*.stories.js'],
+  stories: ['../stories/**/*.stories.js', '../stories/**/*.mdx'],
   addons: [
     '@storybook/addon-essentials',
     '@storybook/addon-interactions',
diff --git a/stories/AbnormalObsControl.stories.js b/stories/AbnormalObsControl.stories.js
index 316b043a..36e75fbb 100644
--- a/stories/AbnormalObsControl.stories.js
+++ b/stories/AbnormalObsControl.stories.js
@@ -6,18 +6,19 @@ import { List } from 'immutable';
 import StoryWrapper from './StoryWrapper';
 import { registerCoreComponents } from './componentRegistry';
 import { pulseDataMetadata } from './mockData';
+import { description, argTypes } from './_meta/abnormalObsControlMeta';
 
 registerCoreComponents();
 
 export default {
   title: 'Complex Controls/AbnormalObsControl',
+  component: ObsGroupControl,
+  tags: ['autodocs'],
+  argTypes,
   parameters: {
     docs: {
       description: {
-        component:
-          'AbnormalObsControl demonstrates an ObsGroup that pairs a numeric observation with a ' +
-          'Boolean "Abnormal" toggle button. The toggle is rendered inline using the Button display ' +
-          'type and lets clinicians flag an out-of-range reading without leaving the field.',
+        component: description,
       },
     },
   },
diff --git a/stories/Forms.stories.js b/stories/Forms.stories.js
index fa28e19a..60969b37 100644
--- a/stories/Forms.stories.js
+++ b/stories/Forms.stories.js
@@ -3,6 +3,7 @@ import StoryWrapper from './StoryWrapper';
 import { Container } from 'src/components/Container.jsx';
 import { runEventScript } from 'src/helpers/runEventScript';
 import { SYSTOLIC_UUID, DIASTOLIC_UUID } from './mockData';
+import { description, argTypes } from './_meta/formsMeta';
 
 const form = {
   id: 1,
@@ -163,23 +164,13 @@ const obsList = [
 
 export default {
   title: 'Example Forms/Lifecycle & Events',
+  component: Container,
+  tags: ['autodocs'],
+  argTypes,
   parameters: {
     docs: {
       description: {
-        component: `
-A guided tour of the form lifecycle. Each story documents one event or method exposed
-by the form engine and shows it working on a real form.
-
-**Stories on this page:**
-
-- **Basic Data Binding** — foundation: how the Container renders pre-populated observations.
-- **Form Lifecycle Demo** — all six lifecycle events on one interactive form with a live
-  Event Log: onFormInit, onValueChange, onValueUpdated, getValue(), onFormSave, Submit/Reset.
-- **Event Flow Diagram** — the complete init → change → submit → post-save timeline.
-- **Handler Templates** — copy-pasteable handler snippets for the most common patterns.
-- **Accessibility for Events** — keyboard and assistive-technology considerations when
-  events update the form dynamically.
-        `,
+        component: description,
       },
     },
   },
diff --git a/stories/MultiSelect.stories.js b/stories/MultiSelect.stories.js
index 47d345dc..f45f50c3 100644
--- a/stories/MultiSelect.stories.js
+++ b/stories/MultiSelect.stories.js
@@ -1,6 +1,7 @@
 import React from 'react';
 import StoryWrapper from './StoryWrapper';
 import { Container } from 'src/components/Container.jsx';
+import { description, argTypes } from './_meta/multiSelectMeta';
 
 const form = {
   id: 1,
@@ -321,13 +322,13 @@ const obsList = [
 
 export default {
   title: 'Atomic Controls/MultiSelect',
+  component: Container,
+  tags: ['autodocs'],
+  argTypes,
   parameters: {
     docs: {
       description: {
-        component:
-          'Demonstrates a form containing a multi-select coded observation (Tuberculosis Comorbidity). ' +
-          'Multi-select obs allow clinicians to choose multiple answers for a single concept and store ' +
-          'each answer as a separate observation record.',
+        component: description,
       },
     },
   },
diff --git a/stories/ObsControl.stories.js b/stories/ObsControl.stories.js
index 1666cd32..26d3cbea 100644
--- a/stories/ObsControl.stories.js
+++ b/stories/ObsControl.stories.js
@@ -3,6 +3,7 @@ import { ObsControlWithIntl as ObsControl } from 'src/components/ObsControl.jsx'
 import StoryWrapper from './StoryWrapper';
 import '../styles/styles.scss';
 import { SYSTOLIC_UUID, DIASTOLIC_UUID } from './mockData';
+import { description, argTypes } from './_meta/obsControlMeta';
 
 const form = {
   controls: [
@@ -106,35 +107,12 @@ const emptyValue = { value: undefined, comment: undefined, interpretation: undef
 export default {
   title: 'Complex Controls/ObsControl',
   component: ObsControl,
-  argTypes: {
-    validate: { control: 'boolean', description: 'Trigger field-level validation' },
-    validateForm: { control: 'boolean', description: 'Trigger form-level validation' },
-    onValueChanged: { action: 'onValueChanged' },
-    showNotification: { action: 'showNotification' },
-    onControlAdd: { action: 'onControlAdd' },
-    onControlRemove: { action: 'onControlRemove' },
-  },
+  tags: ['autodocs'],
+  argTypes,
   parameters: {
     docs: {
       description: {
-        component:
-          'ObsControl is the primary observation control that binds a single concept to a form field. ' +
-          'It wraps the underlying input widget (NumericBox, TextBox, BooleanControl, CodedControl, etc.) ' +
-          'based on the concept datatype resolved at render time via componentStore.\n\n' +
-          '**Concept binding**: The `metadata.concept` object identifies which OpenMRS concept is being ' +
-          'captured. The `concept.datatype` drives which widget renders (Numeric → NumericBox, ' +
-          'Text → TextBox, Boolean → BooleanControl / Button, Coded → AutoComplete or DropDown).\n\n' +
-          '**Value wrapping**: ObsControl receives and emits values as `{ value, comment, interpretation }` ' +
-          'objects. When a user changes the input the `onValueChanged(formFieldPath, value, errors)` ' +
-          'callback is fired with the updated wrapped value so the parent Container can update its ' +
-          'ControlRecordTree.\n\n' +
-          '**Add More**: When `properties.addMore` is true, the control renders Add / Remove buttons ' +
-          'via AddMoreDecorator, allowing the clinician to capture repeated observations for the same ' +
-          'concept within a single encounter.\n\n' +
-          'Accessibility (WCAG 2.1 AA): Each input is associated with a `<label>` via `htmlFor` / `id` ' +
-          'pairing. Mandatory fields include `aria-required="true"`. Validation error messages are ' +
-          'rendered adjacent to the field and referenced with `aria-describedby` so screen readers ' +
-          'announce them immediately. Keyboard navigation is fully supported for all widget types.',
+        component: description,
       },
     },
   },
diff --git a/stories/Section.stories.js b/stories/Section.stories.js
index 9a072614..de7fed66 100644
--- a/stories/Section.stories.js
+++ b/stories/Section.stories.js
@@ -1,9 +1,9 @@
 /* global componentStore */
-import React from 'react';
 import StoryWrapper from './StoryWrapper';
 import { Container } from 'src/components/Container.jsx';
 import { Section } from 'src/components/Section.jsx';
 import { registerCoreComponents } from './componentRegistry';
+import { description, argTypes } from './_meta/sectionMeta';
 
 registerCoreComponents();
 componentStore.registerComponent('section', Section);
@@ -159,39 +159,12 @@ const nestedSectionsMetadata = {
 export default {
   title: 'Complex Controls/Section',
   component: Container,
-  argTypes: {
-    collapse: { control: 'boolean', description: 'Render the section in its collapsed state' },
-    validate: { control: 'boolean', description: 'Trigger field-level validation' },
-    validateForm: { control: 'boolean', description: 'Trigger form-level validation' },
-  },
+  tags: ['autodocs'],
+  argTypes,
   parameters: {
     docs: {
       description: {
-        component:
-          'Section renders a collapsible `<fieldset>` that visually and semantically groups ' +
-          'related form controls under a single heading (legend). It is used to organise ' +
-          'observations into logical panels on complex clinical forms.\n\n' +
-          '**Collapse / expand**: Clicking the legend header toggles `state.collapse`. ' +
-          'When collapsed, child controls are hidden via the `closing-group-controls` CSS class ' +
-          'without unmounting, preserving any partially entered data.\n\n' +
-          '**Nested sections**: A Section\'s `controls` array can contain other sections, ' +
-          'enabling multi-level hierarchical form layouts. Each level renders its own ' +
-          '`<fieldset>` / `<legend>` pair.\n\n' +
-          '**Rendering via Container**: Section is not rendered directly in production — the ' +
-          '`Container` component reads the form metadata tree, resolves `type: "section"` via ' +
-          '`componentStore`, and passes the appropriate child record props down. ' +
-          'These stories use `Container` to replicate that full rendering pipeline.\n\n' +
-          'Accessibility (WCAG 2.1 AA): The `<fieldset>` + `<legend>` combination provides a ' +
-          'native grouping landmark recognised by all screen readers. The collapse toggle is on ' +
-          'the `<legend>` element so it is naturally focusable and operable via keyboard. ' +
-          'Disabled sections add the `disabled` CSS class and all child inputs honour the ' +
-          '`enabled` prop to prevent data entry.\n\n' +
-          '**Composition chain**: The full atomic-to-container hierarchy is: ' +
-          '`Container` → resolves `type: "section"` via `componentStore` → renders `Section` → ' +
-          'each child `type: "obsControl"` is resolved to `ObsControl` → `ObsControl` resolves ' +
-          'the concept datatype to an atomic widget (`NumericBox`, `TextBox`, `BooleanControl`, etc.). ' +
-          'Each layer passes `formFieldPath`, `value`, and `onValueChanged` down so state flows ' +
-          'back up to the root `Container` and its `ControlRecordTree`.',
+        component: description,
       },
     },
   },
diff --git a/stories/StoryWrapper.js b/stories/StoryWrapper.js
index 7210dd0c..11f00a23 100644
--- a/stories/StoryWrapper.js
+++ b/stories/StoryWrapper.js
@@ -49,7 +49,17 @@ const headerStyle = {
 export default class StoryWrapper extends PureComponent {
 
   render() {
-    const { title, children, json } = this.props;
+    const { title, children, json, showDebug } = this.props;
+    if (!showDebug) {
+      return (
+        <div style={styles.wrap}>
+          <div>
+            {title && <div style={headerStyle}>{title}</div>}
+            {children}
+          </div>
+        </div>
+      );
+    }
     return (<div style={styles.wrap}>
                 <div style={styles.box}>
                     {title && <div style={headerStyle}>{title}</div>}
@@ -64,6 +74,11 @@ export default class StoryWrapper extends PureComponent {
 }
 
 StoryWrapper.propTypes = {
-  json: PropTypes.object.isRequired,
+  json: PropTypes.object,
   title: PropTypes.string,
+  showDebug: PropTypes.bool,
+};
+
+StoryWrapper.defaultProps = {
+  showDebug: false,
 };
diff --git a/stories/_meta/abnormalObsControlMeta.js b/stories/_meta/abnormalObsControlMeta.js
new file mode 100644
index 00000000..4369d75b
--- /dev/null
+++ b/stories/_meta/abnormalObsControlMeta.js
@@ -0,0 +1,81 @@
+/**
+ * Metadata for AbnormalObsControl stories.
+ * Imported by stories/AbnormalObsControl.stories.js.
+ */
+
+export const description =
+  'AbnormalObsControl is an ObsGroup that pairs a numeric observation with a Boolean ' +
+  '"Abnormal" toggle button. It allows clinicians to record a measurement and immediately ' +
+  'flag it as out-of-range without leaving the field.\n\n' +
+  '**When to use**: Use AbnormalObsControl for clinical measurements that may need to be ' +
+  'marked abnormal — for example, Pulse Rate, Blood Pressure, or Temperature readings where ' +
+  'a quick abnormality flag is clinically relevant.\n\n' +
+  '**Concept structure**: The control requires an ObsGroup concept whose `controls` array ' +
+  'contains exactly two children:\n\n' +
+  '1. A numeric observation (the measured value)\n' +
+  '2. A Boolean observation with `displayType: "button"` for the Abnormal toggle\n\n' +
+  '**Rendering**: The ObsGroup is rendered via `ObsGroupControl`. The Boolean child renders ' +
+  'as an inline button (Yes/No) positioned next to the numeric input. Both are housed inside ' +
+  'a single fieldset so they are semantically grouped.\n\n' +
+  '**Value handling**: Values are stored as an `Obs` immutable record with `groupMembers` ' +
+  'containing the child observations. The `ObsGroupMapper` flattens group members for the ' +
+  'REST API submission.\n\n' +
+  'Accessibility (WCAG 2.1 AA): The `<fieldset>` + `<legend>` structure groups the numeric ' +
+  'input and the toggle for screen readers. The abnormal toggle button exposes its state via ' +
+  '`aria-pressed` so assistive technologies announce checked/unchecked transitions.';
+
+export const argTypes = {
+  metadata: {
+    description:
+      'ObsGroup control descriptor. Must include a `concept` (the group concept) and a ' +
+      '`controls` array with the numeric child and the Boolean abnormal child. The Boolean ' +
+      'child must have `displayType: "button"` and `options: [{name: "Yes", value: true}, ' +
+      '{name: "No", value: false}]`.',
+    table: {
+      type: { summary: 'object' },
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  obs: {
+    description:
+      'The current ObsGroup value as an immutable `Obs` record. Must include a `groupMembers` ' +
+      'List containing child `Obs` instances for the numeric and abnormal concepts.',
+    table: {
+      type: { summary: 'Obs (immutable record)' },
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  mapper: {
+    description:
+      'Instance of `ObsGroupMapper` used to read and write group member values. ' +
+      'Provided by the parent Container in production; pass `new ObsGroupMapper()` in stories.',
+    table: {
+      type: { summary: 'ObsGroupMapper' },
+      defaultValue: { summary: 'new ObsGroupMapper()' },
+    },
+  },
+  validate: {
+    control: 'boolean',
+    description: 'When `true`, triggers field-level validation on child controls.',
+    table: {
+      type: { summary: 'boolean' },
+      defaultValue: { summary: 'false' },
+    },
+  },
+  onValueChanged: {
+    action: 'onValueChanged',
+    description:
+      'Callback fired when the user changes either the numeric value or the abnormal toggle. ' +
+      'Signature: `(formFieldPath: string, value: object, errors: array) => void`.',
+    table: {
+      type: { summary: 'function' },
+    },
+  },
+  errors: {
+    description: 'Array of validation error objects for this group. Pass `[]` when valid.',
+    table: {
+      type: { summary: 'array' },
+      defaultValue: { summary: '[]' },
+    },
+  },
+};
diff --git a/stories/_meta/formsMeta.js b/stories/_meta/formsMeta.js
new file mode 100644
index 00000000..0719b072
--- /dev/null
+++ b/stories/_meta/formsMeta.js
@@ -0,0 +1,102 @@
+/**
+ * Metadata for Forms / Lifecycle & Events stories.
+ * Imported by stories/Forms.stories.js.
+ */
+
+export const description = `
+The **Container** component is the entry point for every Bahmni clinical form.
+It renders form controls from a JSON metadata tree, manages observation state, and exposes
+a set of events and methods that let your application react to user interactions — from the
+first render all the way through saving an encounter.
+
+**When to use**: Use the Container (with form metadata JSON) whenever you need to render a
+complete clinical form in a Bahmni application. It handles control resolution, observation
+tracking, validation, and lifecycle scripts.
+
+**Lifecycle events**:
+
+| Phase | Event / Method | Who provides it | What it does |
+|---|---|---|---|
+| Init | \`onFormInit\` | \`metadata.events.onFormInit\` | Runs once after render. Use for defaults, hiding sections, or pre-fetching data. |
+| Change | \`onValueChange\` | Individual obsControl | Fires every time a single control's value changes. |
+| Change | \`onValueUpdated\` | Container prop (callback) | Fires after any change. Use for dirty tracking or dependent fields. |
+| Submit | \`getValue()\` | Container ref (method) | Returns current observations and validation errors. Triggers validation. |
+| Post-save | \`onFormSave\` | \`metadata.events.onFormSave\` | Runs after encounter save. Use to navigate or show notifications. |
+
+**Script encoding**: All event scripts in \`metadata.events\` and \`control.events\` must be
+base64-encoded. \`ScriptRunner\` decodes them via \`base64ToUtf8\` before executing.
+`;
+
+export const argTypes = {
+  metadata: {
+    description:
+      'Form descriptor JSON object. Must include `id`, `name`, `version`, `uuid`, and a ' +
+      '`controls` array. May include an `events` object with base64-encoded lifecycle scripts.',
+    table: {
+      type: { summary: 'object' },
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  observations: {
+    description:
+      'Array of pre-populated observation objects from a previous encounter. Each must include ' +
+      '`formFieldPath` and `value`. Pass `[]` for a new encounter.',
+    table: {
+      type: { summary: 'array' },
+      defaultValue: { summary: '[]' },
+    },
+  },
+  validate: {
+    control: 'boolean',
+    description: 'When `true`, triggers field-level validation and renders error messages inline.',
+    table: {
+      type: { summary: 'boolean' },
+      defaultValue: { summary: 'false' },
+    },
+  },
+  validateForm: {
+    control: 'boolean',
+    description:
+      'When `true`, enables form-level validation (typically set before calling `getValue()` ' +
+      'on submit).',
+    table: {
+      type: { summary: 'boolean' },
+      defaultValue: { summary: 'false' },
+    },
+  },
+  collapse: {
+    control: 'boolean',
+    description: 'When `true`, renders all top-level sections in their collapsed state.',
+    table: {
+      type: { summary: 'boolean' },
+      defaultValue: { summary: 'false' },
+    },
+  },
+  patient: {
+    description:
+      'Patient object passed to controls and event scripts. Used for age-based defaults and ' +
+      'patient-specific logic in `onFormInit`. Pass `{}` when not needed.',
+    table: {
+      type: { summary: 'object' },
+      defaultValue: { summary: '{}' },
+    },
+  },
+  onValueUpdated: {
+    action: 'onValueUpdated',
+    description:
+      'Callback fired after any value change in the form. Receives the full ControlRecordTree. ' +
+      'Signature: `(controlRecordTree: object) => void`.',
+    table: {
+      type: { summary: 'function' },
+    },
+  },
+  translations: {
+    description:
+      'Translation map with `labels` and `concepts` dictionaries for i18n. ' +
+      'Pass `{ labels: {}, concepts: {} }` for English stories.',
+    table: {
+      type: { summary: '{ labels: object, concepts: object }' },
+      defaultValue: { summary: '{ labels: {}, concepts: {} }' },
+    },
+  },
+};
diff --git a/stories/_meta/multiSelectMeta.js b/stories/_meta/multiSelectMeta.js
new file mode 100644
index 00000000..d96792b2
--- /dev/null
+++ b/stories/_meta/multiSelectMeta.js
@@ -0,0 +1,63 @@
+/**
+ * Metadata for MultiSelect stories.
+ * Imported by stories/MultiSelect.stories.js.
+ */
+
+export const description =
+  'MultiSelect is a coded observation control that allows clinicians to choose multiple ' +
+  'answers for a single concept, storing each selected answer as a separate observation ' +
+  'record in the encounter.\n\n' +
+  '**When to use**: Use MultiSelect for coded concepts where more than one answer can be ' +
+  'true simultaneously — for example, "Tuberculosis Comorbidities" (Diabetes, HIV, Asthma) ' +
+  'or "Allergies" where multiple entries are clinically valid.\n\n' +
+  '**How it works**: MultiSelect is enabled by setting `properties.multiSelect: true` on an ' +
+  'obsControl with `concept.datatype: "Coded"`. Each selected answer is stored as an ' +
+  'individual observation with the same concept UUID but a different coded value.\n\n' +
+  '**AutoComplete integration**: When `properties.autoComplete: true` is also set, the ' +
+  'control renders as a searchable tag-based input. Users can type to filter answers and ' +
+  'select multiple tags. Selected tags appear inline and can be removed individually.\n\n' +
+  '**Data structure**: Pre-populated selections are passed via the `observations` array on ' +
+  'the parent `Container`. Each selected answer corresponds to one observation object with a ' +
+  'coded `value` matching the answer UUID.\n\n' +
+  'Accessibility (WCAG 2.1 AA): Each selectable tag includes an `aria-label` describing the ' +
+  'answer and its selection state. The autocomplete input uses `role="combobox"` and ' +
+  '`aria-expanded` to communicate dropdown state to screen readers.';
+
+export const argTypes = {
+  metadata: {
+    description:
+      'Form descriptor with a `controls` array containing one `type: "obsControl"` entry where ' +
+      '`properties.multiSelect: true` and `concept.datatype: "Coded"`. The `concept.answers` ' +
+      'array provides the selectable options.',
+    table: {
+      type: { summary: 'object' },
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  observations: {
+    description:
+      'Array of pre-selected coded observation objects. Each object must include ' +
+      '`formFieldPath` and a `value` object matching one of the concept\'s answers.',
+    table: {
+      type: { summary: 'array' },
+      defaultValue: { summary: '[]' },
+    },
+  },
+  validate: {
+    control: 'boolean',
+    description: 'When `true`, triggers field-level validation.',
+    table: {
+      type: { summary: 'boolean' },
+      defaultValue: { summary: 'false' },
+    },
+  },
+  translations: {
+    description:
+      'Translation map with `labels` and `concepts` dictionaries for i18n. ' +
+      'Pass `{ labels: {}, concepts: {} }` for English stories.',
+    table: {
+      type: { summary: '{ labels: object, concepts: object }' },
+      defaultValue: { summary: '{ labels: {}, concepts: {} }' },
+    },
+  },
+};
diff --git a/stories/_meta/obsControlMeta.js b/stories/_meta/obsControlMeta.js
new file mode 100644
index 00000000..eb033d99
--- /dev/null
+++ b/stories/_meta/obsControlMeta.js
@@ -0,0 +1,122 @@
+/**
+ * Metadata for ObsControl stories.
+ * Imported by stories/ObsControl.stories.js.
+ */
+
+export const description =
+  'ObsControl is the primary observation control that binds a single OpenMRS concept to a ' +
+  'form field. It resolves the correct input widget (NumericBox, TextBox, BooleanControl, ' +
+  'CodedControl, etc.) from `componentStore` at render time based on `metadata.concept.datatype`.\n\n' +
+  '**When to use**: Use ObsControl whenever you need to capture a single clinical observation ' +
+  'for a specific concept in a Bahmni form. It is the building block of all clinical forms.\n\n' +
+  '**Concept binding**: The `metadata.concept` object identifies which OpenMRS concept is being ' +
+  'captured. The `concept.datatype` drives which widget renders:\n\n' +
+  '| Datatype | Widget |\n' +
+  '|---|---|\n' +
+  '| Numeric | NumericBox |\n' +
+  '| Text | TextBox |\n' +
+  '| Boolean | BooleanControl or Button |\n' +
+  '| Coded | AutoComplete or DropDown |\n' +
+  '| Date | DatePicker |\n' +
+  '| DateTime | DateTimePicker |\n\n' +
+  '**Value wrapping**: Values are passed and emitted as `{ value, comment, interpretation }`. ' +
+  'The `onValueChanged(formFieldPath, value, errors)` callback notifies the parent Container ' +
+  'which updates its ControlRecordTree.\n\n' +
+  '**Add More**: When `properties.addMore` is `true`, the control renders Add / Remove buttons ' +
+  'via AddMoreDecorator, allowing clinicians to capture repeated observations for the same ' +
+  'concept within a single encounter.\n\n' +
+  'Accessibility (WCAG 2.1 AA): Each input is associated with a `<label>` via `htmlFor`/`id` ' +
+  'pairing. Mandatory fields include `aria-required="true"`. Validation error messages are ' +
+  'rendered adjacent to the field and referenced with `aria-describedby`.';
+
+export const argTypes = {
+  metadata: {
+    description:
+      'Control descriptor from the form JSON. Must include `concept` (with `name`, `uuid`, ' +
+      '`datatype`), `label`, `properties`, and `id`. The `concept.datatype` determines which ' +
+      'widget is rendered.',
+    table: {
+      type: { summary: 'object' },
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  value: {
+    description:
+      'Current observation value wrapped as `{ value, comment, interpretation }`. ' +
+      'Pass `{ value: undefined, comment: undefined, interpretation: undefined }` for an ' +
+      'empty / unsaved field.',
+    table: {
+      type: { summary: '{ value: any, comment: string, interpretation: string }' },
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  formUuid: {
+    description:
+      'UUID of the parent form. Used to construct the `formFieldPath` ' +
+      '(`"<formUuid>/<controlId>"`) which uniquely identifies this control\'s value in the ' +
+      'ControlRecordTree.',
+    table: {
+      type: { summary: 'string' },
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  formFieldPath: {
+    description:
+      'Fully-qualified path identifying this control instance within the form tree ' +
+      '(e.g. `"test/1-0"`). Generated automatically by the Container; pass explicitly in stories.',
+    table: {
+      type: { summary: 'string' },
+      defaultValue: { summary: "'test/1-0'" },
+    },
+  },
+  validate: {
+    control: 'boolean',
+    description: 'When `true`, triggers field-level validation and shows error messages.',
+    table: {
+      type: { summary: 'boolean' },
+      defaultValue: { summary: 'false' },
+    },
+  },
+  validateForm: {
+    control: 'boolean',
+    description: 'When `true`, triggers form-level validation (used on submit).',
+    table: {
+      type: { summary: 'boolean' },
+      defaultValue: { summary: 'false' },
+    },
+  },
+  onValueChanged: {
+    action: 'onValueChanged',
+    description:
+      'Callback fired when the user changes the input. ' +
+      'Signature: `(formFieldPath: string, value: object, errors: array) => void`.',
+    table: {
+      type: { summary: 'function' },
+    },
+  },
+  showNotification: {
+    action: 'showNotification',
+    description: 'Callback to display a toast/notification. Signature: `(notification: object) => void`.',
+    table: {
+      type: { summary: 'function' },
+    },
+  },
+  onControlAdd: {
+    action: 'onControlAdd',
+    description:
+      'Callback fired when the clinician clicks "Add" in an addMore-enabled control. ' +
+      'Signature: `(formFieldPath: string) => void`.',
+    table: {
+      type: { summary: 'function' },
+    },
+  },
+  onControlRemove: {
+    action: 'onControlRemove',
+    description:
+      'Callback fired when the clinician clicks "Remove" in an addMore-enabled control. ' +
+      'Signature: `(formFieldPath: string) => void`.',
+    table: {
+      type: { summary: 'function' },
+    },
+  },
+};
diff --git a/stories/_meta/sectionMeta.js b/stories/_meta/sectionMeta.js
new file mode 100644
index 00000000..a12f1b9e
--- /dev/null
+++ b/stories/_meta/sectionMeta.js
@@ -0,0 +1,90 @@
+/**
+ * Metadata for Section stories.
+ * Imported by stories/Section.stories.js.
+ */
+
+export const description =
+  'Section renders a collapsible `<fieldset>` that visually and semantically groups related ' +
+  'form controls under a single heading (legend). It organises observations into logical ' +
+  'panels on complex clinical forms.\n\n' +
+  '**When to use**: Use Section whenever a form needs to group related fields — for example, ' +
+  '"Vital Signs", "Patient History", or "Lab Results" — into a collapsible panel that reduces ' +
+  'visual clutter on long forms.\n\n' +
+  '**Collapse / expand**: Clicking the legend header toggles `state.collapse`. When collapsed, ' +
+  'child controls are hidden via the `closing-group-controls` CSS class without unmounting, ' +
+  'preserving any partially entered data.\n\n' +
+  '**Nested sections**: A Section\'s `controls` array can contain other sections, enabling ' +
+  'multi-level hierarchical form layouts. Each level renders its own `<fieldset>` / `<legend>` pair.\n\n' +
+  '**Rendering via Container**: In production, Section is not instantiated directly. The ' +
+  '`Container` component reads the form metadata tree, resolves `type: "section"` via ' +
+  '`componentStore`, and passes the appropriate child record props down. These stories use ' +
+  '`Container` to replicate that full rendering pipeline.\n\n' +
+  'Accessibility (WCAG 2.1 AA): The `<fieldset>` + `<legend>` combination provides a native ' +
+  'grouping landmark recognised by all screen readers. The collapse toggle is on the `<legend>` ' +
+  'element so it is naturally focusable and operable via keyboard.';
+
+export const argTypes = {
+  metadata: {
+    description:
+      'Form descriptor object containing a `controls` array with one or more `type: "section"` ' +
+      'entries. Each section entry must include `label`, `properties`, `id`, and a `controls` ' +
+      'array of child control descriptors.',
+    table: {
+      type: { summary: 'object' },
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  observations: {
+    description:
+      'Array of pre-populated observation objects from a previous encounter. Each observation ' +
+      'must include `formFieldPath` to be matched to the correct control.',
+    table: {
+      type: { summary: 'array' },
+      defaultValue: { summary: '[]' },
+    },
+  },
+  collapse: {
+    control: 'boolean',
+    description:
+      'When `true`, renders the section in its initially collapsed state. ' +
+      'The user can still expand it by clicking the section header.',
+    table: {
+      type: { summary: 'boolean' },
+      defaultValue: { summary: 'false' },
+    },
+  },
+  validate: {
+    control: 'boolean',
+    description: 'When `true`, triggers field-level validation on all child controls.',
+    table: {
+      type: { summary: 'boolean' },
+      defaultValue: { summary: 'false' },
+    },
+  },
+  validateForm: {
+    control: 'boolean',
+    description: 'When `true`, triggers form-level validation (used on submit).',
+    table: {
+      type: { summary: 'boolean' },
+      defaultValue: { summary: 'false' },
+    },
+  },
+  patient: {
+    description:
+      'Patient object passed down to child controls. Used by controls that need patient ' +
+      'context (e.g. age-based defaults). Pass `{}` in stories.',
+    table: {
+      type: { summary: 'object' },
+      defaultValue: { summary: '{}' },
+    },
+  },
+  translations: {
+    description:
+      'Translation map with `labels` and `concepts` dictionaries for i18n. ' +
+      'Pass `{ labels: {}, concepts: {} }` for English stories.',
+    table: {
+      type: { summary: '{ labels: object, concepts: object }' },
+      defaultValue: { summary: '{ labels: {}, concepts: {} }' },
+    },
+  },
+};

From 952cdf38b8eca5c6ff0ddf8d2a80f910bf5386e9 Mon Sep 17 00:00:00 2001
From: komalSharma225 <komal.sharma@thoughtworks.com>
Date: Fri, 5 Jun 2026 11:24:58 +0530
Subject: [PATCH 2/4] Fix Jest configuration to handle Carbon package imports

Exclude @carbon packages from transformIgnorePatterns so Jest doesn't attempt
to parse their CSS imports. This resolves test failures introduced when
@carbon/react, @carbon/icons-react, and @carbon/layout were added to
devDependencies for BAH-4747.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 jest.config.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/jest.config.js b/jest.config.js
index eabaefbc..b43b0e38 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -35,7 +35,7 @@ module.exports = {
   ],
   moduleFileExtensions: ['js', 'jsx', 'json'],
   transformIgnorePatterns: [
-    '/node_modules/(?!(@bahmni/design-system|@bahmni/services)/)'
+    '/node_modules/(?!(@bahmni/design-system|@bahmni/services|@carbon)/)'
   ],
   testTimeout: 10000,
   coverageThreshold: {

From 16f1ab3c9bc925aaf441abd90f61f5a89c0451af Mon Sep 17 00:00:00 2001
From: komalSharma225 <komal.sharma@thoughtworks.com>
Date: Fri, 5 Jun 2026 11:39:35 +0530
Subject: [PATCH 3/4] Fix Jest configuration to properly handle Carbon package
 CSS imports

- Add explicit moduleNameMapper for @carbon/styles CSS files to resolve them as identity-obj-proxy
- Remove @carbon from transformIgnorePatterns since it should not be transformed
- Carbon packages are pre-built and should be ignored during transformation
- This allows @bahmni/design-system (which is transformed) to properly import CSS from @carbon/styles

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 jest.config.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/jest.config.js b/jest.config.js
index b43b0e38..1e2449d3 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -5,6 +5,7 @@ module.exports = {
     '^src/(.*)$': '<rootDir>/src/$1',
     '^components/(.*)$': '<rootDir>/src/components/$1',
     '^helpers/(.*)$': '<rootDir>/src/helpers/$1',
+    '@carbon/styles/css/styles\\.css$': 'identity-obj-proxy',
     '\\.(css|less|scss|sass)$': 'identity-obj-proxy',
     '\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$': 'test-file-stub'
   },
@@ -35,7 +36,7 @@ module.exports = {
   ],
   moduleFileExtensions: ['js', 'jsx', 'json'],
   transformIgnorePatterns: [
-    '/node_modules/(?!(@bahmni/design-system|@bahmni/services|@carbon)/)'
+    '/node_modules/(?!(@bahmni/design-system|@bahmni/services)/)'
   ],
   testTimeout: 10000,
   coverageThreshold: {

From 095a01cb9039138e51b79c19df7a3ec6129413c9 Mon Sep 17 00:00:00 2001
From: komalSharma225 <komal.sharma@thoughtworks.com>
Date: Fri, 5 Jun 2026 11:55:28 +0530
Subject: [PATCH 4/4] Add identity-obj-proxy to devDependencies

Required for Jest moduleNameMapper to properly mock CSS imports.
This package creates a proxy object for CSS modules during testing.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 package.json | 50 ++++++++++++++++++++++++++------------------------
 1 file changed, 26 insertions(+), 24 deletions(-)

diff --git a/package.json b/package.json
index 8f25282b..9056df6c 100644
--- a/package.json
+++ b/package.json
@@ -27,27 +27,37 @@
   },
   "author": "bahmni@thoughtworks.com",
   "peerDependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
     "@bahmni/design-system": ">=0.0.1-dev.215",
-    "@carbon/react": ">=1.0.0"
+    "@carbon/react": ">=1.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "storybook": "^8.4.0",
-    "@storybook/react": "^8.4.0",
-    "@storybook/react-webpack5": "^8.4.0",
-    "@storybook/addon-actions": "^8.4.0",
-    "@storybook/addon-essentials": "^8.4.0",
-    "@storybook/addon-interactions": "^8.4.0",
-    "@storybook/blocks": "^8.4.0",
-    "@storybook/test": "^8.4.0",
-    "@bahmni/design-system": ">=0.0.1-dev.215",
     "@babel/cli": "^7.28.3",
     "@babel/core": "^7.28.4",
     "@babel/eslint-parser": "^7.28.4",
     "@babel/preset-env": "^7.28.3",
     "@babel/preset-react": "^7.27.1",
+    "@babel/runtime": "^7.28.0",
+    "@bahmni/design-system": ">=0.0.1-dev.215",
+    "@carbon/icons-react": "^11.0.0",
+    "@carbon/layout": "^11.0.0",
+    "@carbon/react": "^1.0.0",
     "@fortawesome/fontawesome-free": "^7.1.0",
+    "@storybook/addon-actions": "^8.4.0",
+    "@storybook/addon-backgrounds": "^8.4.0",
+    "@storybook/addon-controls": "^8.4.0",
+    "@storybook/addon-docs": "^8.4.0",
+    "@storybook/addon-essentials": "^8.4.0",
+    "@storybook/addon-interactions": "^8.4.0",
+    "@storybook/addon-measure": "^8.4.0",
+    "@storybook/addon-outline": "^8.4.0",
+    "@storybook/addon-toolbars": "^8.4.0",
+    "@storybook/addon-viewport": "^8.4.0",
+    "@storybook/blocks": "^8.4.0",
+    "@storybook/react": "^8.4.0",
+    "@storybook/react-webpack5": "^8.4.0",
+    "@storybook/test": "^8.4.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
@@ -65,9 +75,11 @@
     "eslint-plugin-react": "^7.37.5",
     "fetch-mock": "^5.1.2",
     "file-loader": "^0.11.1",
+    "identity-obj-proxy": "^3.0.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "mini-css-extract-plugin": "^2.7.6",
+    "polished": "^4.3.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-json-syntax-highlighter": "^0.1.15",
@@ -75,6 +87,7 @@
     "rimraf": "^2.5.4",
     "sass": "^1.92.1",
     "sass-loader": "^13.3.2",
+    "storybook": "^8.4.0",
     "style-loader": "^3.3.3",
     "webpack": "^5.89.0",
     "webpack-cli": "^5.1.4",
@@ -82,6 +95,7 @@
   },
   "dependencies": {
     "ajv": "^8.17.1",
+    "babel-runtime": "^6.26.0",
     "base64-inline-loader": "^1.1.0",
     "classnames": "^2.2.5",
     "immutable": "4.3.8",
@@ -94,18 +108,6 @@
     "sinon-as-promised": "^4.0.3",
     "whatwg-fetch": "^1.0.0"
   },
-  "resolutions": {
-    "**/**/lodash": "^4.17.12",
-    "**/**/lodash-es": "^4.17.14",
-    "**/**/mixin-deep": "^1.3.2",
-    "**/**/set-value": "^2.0.1",
-    "**/**/decompress": "^4.2.1",
-    "**/**/xmlhttprequest-ssl": "^1.6.1",
-    "**/**/open": "^6.0.0",
-    "**/**/lodash.template": "^4.5.0",
-    "**/**/growl": "^1.10.0",
-    "**/**/handlebars": "^4.7.7"
-  },
   "files": [
     "dist/",
     "README.md",