@pega/sdk 0.0.5 → 0.0.6

package/templates/react-sdk-reference/.ai-common/skills/field-skills/TextArea.md

@@ -2,7 +2,7 @@
 
 Multi-line text input field that binds to a Pega case property.
 
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,123 +14,70 @@ Renders an editable multi-line text area. Used for long-form text input such as
 
 - **Pega Name:** `TextArea`
 - **Type / Subtype:** `Field` / `Text` (multi-line)
-- **Registration key:** `TextArea` (in `component-map.ts`)
+- **Registration key:** `TextArea` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-| Prop            | Type             | Description                                                |
+| Name            | Type             | Description                                                |
 | --------------- | ---------------- | ---------------------------------------------------------- |
 | `fieldMetadata` | `any` (optional) | Metadata object; used to read `maxLength` for the textarea |
 
-All other props come from `PConnFieldProps`. Import type as:
+All other inputs come from the project's field input contract (see prerequisite skill).
 
-```typescript
-import type { PConnFieldProps } from '@pega/sdk-react';
-```
-
-## Component Skeleton
+## Implementation Structure
 
 Similar to TextInput but multiline with fixed rows. Does NOT delegate to TextInput in read-only mode.
 
-```typescript
-import { useEffect, useState } from 'react';
-import handleEvent from '../../helpers/event-utils';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnFieldProps } from '@pega/sdk-react';
-
-interface TextAreaProps extends PConnFieldProps {
-  fieldMetadata?: any;
-}
-
-export default function TextArea(props: TextAreaProps) {
-  // 1. Registry lookup
-  const FieldValueList = getComponentFromRegistry('FieldValueList');
-
-  // 2. Destructure props
-  const {
-    getPConnect, label, required, disabled, value = '',
-    validatemessage, status, readOnly, testId, fieldMetadata,
-    helperText, displayMode, hideLabel, placeholder,
-  } = props;
-  const helperTextToDisplay = validatemessage || helperText;
-  const pConn = getPConnect();
-  const actions = pConn.getActionsApi();
-  const propName = (pConn.getStateProps() as any).value;
-  const maxLength = fieldMetadata?.maxLength;
-
-  // 3. State
-  const [inputValue, setInputValue] = useState('');
-  let readOnlyProp = {};
-
-  // 4. useEffect: sync from store — deps: [value]
-  useEffect(() => { setInputValue(value); }, [value]);
-
-  // 5. Display mode returns
-  if (displayMode === 'DISPLAY_ONLY') {
-    return <FieldValueList name={hideLabel ? '' : label} value={value} />;
-  }
-  if (displayMode === 'STACKED_LARGE_VAL') {
-    return <FieldValueList name={hideLabel ? '' : label} value={value} variant="stacked" />;
-  }
-
-  // 6. Read-only: set readOnlyProp (do NOT delegate to TextInput — preserve multiline)
-  if (readOnly) readOnlyProp = { readOnly: true };
-
-  // 7. Test ID + handlers
-  const testProps: any = { 'data-test-id': testId };
-  function handleChange(event) { setInputValue(event?.target?.value); }
-  function handleBlur() { handleEvent(actions, 'changeNblur', propName, inputValue); }
-
-  // 8. Main render — multiline text input
-  //    Key props:
-  //    - multiline: true, minRows: 5, maxRows: 5
-  //    - fullWidth, variant: readOnly ? 'standard' : 'outlined', size: 'small'
-  //    - value: inputValue, onChange: handleChange
-  //    - onBlur: !readOnly ? handleBlur : undefined
-  //    - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
-  //    - required, disabled, error: status === 'error'
-  //    - slotProps: { input: { ...readOnlyProp, inputProps: { maxLength, ...testProps } } }
-  return <TextAreaWidget ... />;
-}
-```
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList`) and the project's event-commit utility (for committing value changes to the store). Define the input contract as an extension of the project's field input contract, adding an optional `fieldMetadata` field.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookup** — resolve `FieldValueList` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `testId`, `fieldMetadata`, `helperText`, `displayMode`, `hideLabel`, `placeholder`. Compute `helperTextToDisplay = validatemessage || helperText`, set up the PConnect instance, actions API, and bound property name, and derive `maxLength = fieldMetadata?.maxLength`.
+3. **Local state** — `inputValue` initialized to `''`; declare a read-only configuration object.
+4. **Sync from store** — a lifecycle effect watching `value` updates `inputValue` whenever it changes.
+5. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the raw `value`, the latter with a stacked variant.
+6. **Read-only** — set the read-only configuration to mark the textarea read-only when `readOnly` is true. Unlike TextInput, do NOT delegate to `TextInput` — preserve the multiline rendering even when read-only.
+7. **Test ID and handlers** — build a test-id attribute from `testId`; the change handler updates `inputValue` from the event's textarea value; the blur handler commits the value via the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+8. **Render** — a multiline text input configured with: multiline mode enabled, minimum rows `5`, maximum rows `5`, full width, an outlined style when editable or flat/borderless style when read-only, small size, current `inputValue`, the change handler, the blur handler wired only when not read-only, `label`, `helperText: helperTextToDisplay`, `placeholder: placeholder ?? ''`, `required`, `disabled`, an error state when `status === 'error'`, and `maxLength` plus the read-only/test-id attributes applied to the underlying textarea element.
 
 ## Behavioral Contract
 
 1. **Local state:** Maintain `inputValue` in local state (string). Initialize to `''`.
-2. **Sync from store:** `useEffect` watching `value` prop — call `setInputValue(value)` whenever `value` changes.
+2. **Sync from store:** A lifecycle effect watching the `value` input updates `inputValue` whenever `value` changes.
 3. **On change:** Update local `inputValue` state only (do NOT commit to store on every keystroke).
-4. **On blur:** Commit to store by calling `handleEvent(actions, 'changeNblur', propName, inputValue)`.
-5. **Read-only:** Set `readOnly` attribute on the textarea; use visually borderless ("standard") variant. Omit `onBlur` handler: `onBlur={!readOnly ? handleBlur : undefined}`.
+4. **On blur:** Commit to store via the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+5. **Read-only:** Set the read-only attribute on the textarea; use a visually flat/borderless style. Omit the blur handler when read-only.
 6. **maxLength:** Read from `fieldMetadata?.maxLength`; pass to the textarea's `maxLength` attribute.
-7. **Row sizing:** Fixed at `minRows={5}` and `maxRows={5}` — the textarea does not auto-expand; it shows a scrollbar if content exceeds 5 rows.
+7. **Row sizing:** Fixed at minimum rows `5` and maximum rows `5` — the textarea does not auto-expand; it shows a scrollbar if content exceeds 5 rows.
 
 ## Display Mode Rendering
 
-- **`DISPLAY_ONLY`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} />`.
-- **`STACKED_LARGE_VAL`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw `value`.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
 - Both modes short-circuit before interactive rendering.
 
 ## Read-Only Rendering
 
-Set `readOnly` on the textarea element (NOT a read-only version via `TextInput` — preserves the multiline appearance). Switch to a flat/borderless visual style. The `minRows`/`maxRows` constraint is still applied in read-only.
+Set the read-only attribute on the textarea element (NOT a read-only version via `TextInput` — preserves the multiline appearance). Switch to a flat/borderless visual style. The min/max rows constraint is still applied in read-only.
 
 ## Visual Specifications
 
-Derived from the reference component's MUI props:
-
-| Property      | Standard (editable)                      | Read-only            |
-| ------------- | ---------------------------------------- | -------------------- |
-| Width         | 100%                                     | 100%                 |
-| Min rows      | 5                                        | 5                    |
-| Max rows      | 5 (scrollable beyond)                    | 5                    |
-| Border        | 1px solid (outlined)                     | None (standard/flat) |
-| Border radius | 4px                                      | —                    |
-| Label         | Floating label                           | Floating label       |
-| Helper text   | Below textarea                           | Below textarea       |
-| Error state   | Red border + red helper text             | —                    |
-| Resize        | Vertical resize handle (browser default) | Same                 |
-| Font size     | 0.875rem                                 | 0.875rem             |
-| Padding       | 8px 14px                                 | —                    |
+Derived from the reference component's styling:
+
+| Property      | Standard (editable)                      | Read-only         |
+| ------------- | ---------------------------------------- | ----------------- |
+| Width         | 100%                                     | 100%              |
+| Min rows      | 5                                        | 5                 |
+| Max rows      | 5 (scrollable beyond)                    | 5                 |
+| Border        | 1px solid (outlined)                     | None (flat style) |
+| Border radius | 4px                                      | —                 |
+| Label         | Floating label                           | Floating label    |
+| Helper text   | Below textarea                           | Below textarea    |
+| Error state   | Red border + red helper text             | —                 |
+| Resize        | Vertical resize handle (browser default) | Same              |
+| Font size     | 0.875rem                                 | 0.875rem          |
+| Padding       | 8px 14px                                 | —                 |
 
 **CSS-only implementation notes:**
 
@@ -140,25 +87,23 @@ Derived from the reference component's MUI props:
 
 ## Edge Cases & Special Logic
 
-- Unlike `TextInput`, do NOT delegate to `TextInput` in read-only mode — render the textarea directly with `readOnly` set, so the multi-line appearance is preserved.
+- Unlike `TextInput`, do NOT delegate to `TextInput` in read-only mode — render the textarea directly with the read-only attribute set, so the multi-line appearance is preserved.
 - `maxLength` is optional; only apply the attribute if `fieldMetadata?.maxLength` is defined.
 
 ## Dependencies
 
-- `handleEvent` from `../../helpers/event-utils`
-- `getComponentFromRegistry('FieldValueList')` for display modes
-- No third-party UI libraries required
+- The project's event-commit utility.
+- The project's component registry, resolving `FieldValueList` — for display modes.
+- No third-party UI libraries required.
 
 ## Design System Mapping
 
-**UI control type:** Multi-line text input (`<textarea>`).
+**UI control type:** Multi-line text input (textarea).
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Recommended Component                             |
-| ------------------ | ------------------------------------------------- |
-| Default (CSS only) | `<textarea rows="5">` with floating label         |
-| MUI                | `<TextField multiline minRows={5} maxRows={5} />` |
-| Ant Design         | `<Input.TextArea rows={5} />`                     |
-| Chakra UI          | `<Textarea />`                                    |
-| Shadcn/ui          | `<Textarea />`                                    |
+- **Multiline input** → use the DS's textarea or multi-line text field component
+- **Row sizing** → configure minimum and maximum rows to `5`
+- **Read-only mode** → set the read-only attribute directly on the textarea (do NOT delegate to TextInput)
+- **Error state** → the DS's error/danger visual state
+- **maxLength** → pass to the textarea's `maxLength` attribute

package/templates/react-sdk-reference/.ai-common/skills/field-skills/TextContent.md

@@ -2,65 +2,40 @@
 
 Static text display component that renders formatted text content (paragraph or heading). Non-interactive — no form binding.
 
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
 ## Component Purpose
 
-Displays static, read-only text content. Used to embed headings or descriptive paragraph text within forms or views. Not an input field — does NOT bind to a case property value and does NOT use `PConnFieldProps`. It renders purely based on static configuration props.
+Displays static, read-only text content. Used to embed headings or descriptive paragraph text within forms or views. Not an input field — does NOT bind to a case property value and does NOT use the project's field input contract. It renders purely based on static configuration inputs.
 
 ## Pega Metadata
 
 - **Pega Name:** `TextContent`
 - **Type / Subtype:** `Field` / `Text`
-- **Registration key:** `TextContent` (in `component-map.ts`)
+- **Registration key:** `TextContent` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-Extends `PConnProps` (NOT `PConnFieldProps` — there is no form value binding):
+The input contract extends the project's base component interface (NOT the field input contract — there is no form value binding), adding two required fields: `content` and `displayAs`.
 
-```typescript
-import type { PConnProps } from '@pega/sdk-react';
-
-interface TextContentProps extends PConnProps {
-  content: string;
-  displayAs: 'Paragraph' | 'Heading 1' | 'Heading 2' | 'Heading 3' | 'Heading 4';
-}
-```
-
-| Prop        | Type                                                                      | Description                                       |
+| Name        | Type                                                                      | Description                                       |
 | ----------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
 | `content`   | `string`                                                                  | The text string to render                         |
 | `displayAs` | `'Paragraph' \| 'Heading 1' \| 'Heading 2' \| 'Heading 3' \| 'Heading 4'` | How to render the text — maps to typography level |
 
-## Component Skeleton
-
-Simplest possible component — no state, no effects, just a switch on `displayAs`.
+## Implementation Structure
 
-```typescript
-import type { PConnProps } from '@pega/sdk-react';
+Simplest possible component — no state, no lifecycle effects, just a switch on `displayAs`.
 
-interface TextContentProps extends PConnProps {
-  content: string;
-  displayAs: 'Paragraph' | 'Heading 1' | 'Heading 2' | 'Heading 3' | 'Heading 4';
-}
+**Module Setup:** Define the input contract as an extension of the project's base component interface (not the field input contract) with `content: string` and the `displayAs` union type.
 
-export default function TextContent(props: TextContentProps) {
-  const { content, displayAs } = props;
+**Main Component Logic:**
 
-  switch (displayAs) {
-    case 'Paragraph': return <p>{content}</p>;
-    case 'Heading 1': return <h1>{content}</h1>;
-    case 'Heading 2': return <h2>{content}</h2>;
-    case 'Heading 3': return <h3>{content}</h3>;
-    case 'Heading 4': return <h4>{content}</h4>;
-    default:
-      console.error(`TextContent got unexpected displayAs: ${displayAs}`);
-      return <p>{content}</p>;
-  }
-}
-```
+1. Receive `content` and `displayAs` from inputs.
+2. Switch on `displayAs` and render the matching element wrapping `content`: `'Paragraph'` → `<p>`, `'Heading 1'` → `<h1>`, `'Heading 2'` → `<h2>`, `'Heading 3'` → `<h3>`, `'Heading 4'` → `<h4>`.
+3. For any unrecognized `displayAs` value, log an error describing the unexpected value, then fall back to rendering `content` in a `<p>`.
 
 ## Behavioral Contract
 
@@ -75,7 +50,7 @@ export default function TextContent(props: TextContentProps) {
 
 ## Display Mode Rendering
 
-Not applicable — this component is display-only by nature. It does not accept a `displayMode` prop.
+Not applicable — this component is display-only by nature. It does not accept a `displayMode` input.
 
 ## Read-Only Rendering
 
@@ -93,53 +68,25 @@ Derived from standard HTML typography:
 | `Heading 3` | `<h3>`          | 1.75rem     | 400         |
 | `Heading 4` | `<h4>`          | 1.5rem      | 400         |
 
-Color inherits from the surrounding text color. No padding, margin, border, or background beyond what the browser/design-system applies to the heading element.
-
-**CSS-only implementation notes:**
-
-```css
-.text-content-h1 {
-  font-size: 2.5rem;
-  font-weight: 300;
-}
-.text-content-h2 {
-  font-size: 2rem;
-  font-weight: 300;
-}
-.text-content-h3 {
-  font-size: 1.75rem;
-  font-weight: 400;
-}
-.text-content-h4 {
-  font-size: 1.5rem;
-  font-weight: 400;
-}
-.text-content-body {
-  font-size: 1rem;
-  font-weight: 400;
-}
-```
+Color inherits from the surrounding text color. No padding, margin, border, or background beyond what the browser/design-system applies to the heading element. Each heading level (and the paragraph/body style) uses only `font-size` and `font-weight` to differentiate visual hierarchy, per the table above — no other styling is applied.
 
 ## Edge Cases & Special Logic
 
-- Unrecognized `displayAs` values should trigger a `console.error` and fall back to body text.
-- No `handleEvent`, no store interaction, no `useEffect`.
+- Unrecognized `displayAs` values should trigger an error log and fall back to body text.
+- No event-commit utility, no store interaction, no lifecycle effects.
 
 ## Dependencies
 
 - No event utilities needed
 - No `FieldValueList` needed
-- Only a typography rendering element
+- Only a typography rendering element (native HTML or the DS's typography component)
 
 ## Design System Mapping
 
 **UI control type:** Static typography / text block.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Recommended Component                                          |
-| ------------------ | -------------------------------------------------------------- |
-| Default (CSS only) | Native `<h1>`–`<h4>` or `<p>`                                  |
-| MUI                | `<Typography variant='h1' \| 'h2' \| 'h3' \| 'h4' \| 'body1'>` |
-| Ant Design         | `<Typography.Title level={1-4}>` or `<Typography.Text>`        |
-| Chakra UI          | `<Heading as='h1'-'h4'>` or `<Text>`                           |
+- **Paragraph** → use the DS's body text component or a `<p>` element
+- **Heading 1–4** → use the DS's heading component at the matching level, or native `<h1>`–`<h4>` elements
+- **No interaction** → this component has no event handling, state, or store binding

package/templates/react-sdk-reference/.ai-common/skills/field-skills/TextInput.md

@@ -2,7 +2,7 @@
 
 Single-line text input field that binds to a Pega case property.
 
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,124 +14,71 @@ Renders a single-line editable text field. It is the simplest and most foundatio
 
 - **Pega Name:** `TextInput`
 - **Type / Subtype:** `Field` / `Text`
-- **Registration key:** `TextInput` (in `component-map.ts`)
+- **Registration key:** `TextInput` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-| Prop            | Type             | Description                                             |
+| Name            | Type             | Description                                             |
 | --------------- | ---------------- | ------------------------------------------------------- |
 | `fieldMetadata` | `any` (optional) | Metadata object; used to read `maxLength` for the input |
 
-All other props come from `PConnFieldProps`. Import type as:
+All other inputs come from the project's field input contract (see prerequisite skill).
 
-```typescript
-import type { PConnFieldProps } from '@pega/sdk-react';
-```
-
-## Component Skeleton
+## Implementation Structure
 
 The foundational field component — simplest pattern. All text-like fields (Email, URL, Integer, Phone) follow this structure with minor variations.
 
-```typescript
-import { useState, useEffect } from 'react';
-import handleEvent from '../../helpers/event-utils';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnFieldProps } from '@pega/sdk-react';
-
-interface TextInputProps extends PConnFieldProps {
-  fieldMetadata?: any;
-}
-
-export default function TextInput(props: TextInputProps) {
-  // 1. Registry lookup
-  const FieldValueList = getComponentFromRegistry('FieldValueList');
-
-  // 2. Destructure props
-  const {
-    getPConnect, label, required, disabled, value = '',
-    validatemessage, status, readOnly, testId, fieldMetadata,
-    helperText, displayMode, hideLabel, placeholder,
-  } = props;
-
-  // 3. PConnect setup
-  const pConn = getPConnect();
-  const actions = pConn.getActionsApi();
-  const propName = (pConn.getStateProps() as any).value;
-  const helperTextToDisplay = validatemessage || helperText;
-  const maxLength = fieldMetadata?.maxLength;
-
-  // 4. State + readOnly prop
-  const [inputValue, setInputValue] = useState('');
-  let readOnlyProp = {};
-
-  // 5. useEffect: sync from store — deps: [value]
-  useEffect(() => { setInputValue(value); }, [value]);
-
-  // 6. Display mode returns
-  if (displayMode === 'DISPLAY_ONLY') {
-    return <FieldValueList name={hideLabel ? '' : label} value={value} />;
-  }
-  if (displayMode === 'STACKED_LARGE_VAL') {
-    return <FieldValueList name={hideLabel ? '' : label} value={value} variant="stacked" />;
-  }
-
-  // 7. Read-only prop
-  if (readOnly) readOnlyProp = { readOnly: true };
-
-  // 8. Test ID + handlers
-  const testProps: any = { 'data-test-id': testId };
-  function handleChange(event) { setInputValue(event?.target?.value); }
-  function handleBlur() { handleEvent(actions, 'changeNblur', propName, inputValue); }
-
-  // 9. Main render — single-line text input
-  //    Key props:
-  //    - fullWidth, variant: readOnly ? 'standard' : 'outlined', size: 'small'
-  //    - value: inputValue, onChange: handleChange
-  //    - onBlur: !readOnly ? handleBlur : undefined
-  //    - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
-  //    - required, disabled, error: status === 'error'
-  //    - slotProps: { input: { ...readOnlyProp, inputProps: { maxLength, ...testProps } } }
-  return <TextFieldWidget ... />;
-}
-```
+**Module Setup:** The component depends on the project's event-commit utility (for committing value changes to the store) and the project's component registry (to resolve the `FieldValueList` display component). Define the input contract as an extension of the project's field input contract, adding an optional `fieldMetadata` field.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookup** — resolve `FieldValueList` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `testId`, `fieldMetadata`, `helperText`, `displayMode`, `hideLabel`, `placeholder`.
+3. **PConnect setup** — obtain the PConnect instance, its actions API, and the bound property name; compute `helperTextToDisplay = validatemessage || helperText`, and `maxLength = fieldMetadata?.maxLength`.
+4. **Local state and read-only flag** — `inputValue` initialized to `''`; declare a read-only configuration object (populated conditionally later).
+5. **Sync from store** — a lifecycle effect watching `value` updates `inputValue` whenever `value` changes.
+6. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the raw `value`, the latter with a stacked variant.
+7. **Read-only flag** — set the read-only configuration to mark the input read-only only when `readOnly` is true.
+8. **Test ID and handlers** — build a test-id attribute from `testId`; the change handler updates `inputValue` from the event's input value; the blur handler commits the value via the project's event-commit utility, passing the actions API, event type `'changeNblur'`, the property name, and `inputValue`.
+9. **Render** — a single-line text input configured with: full width, a visually outlined style when editable and a flat/borderless style when read-only, small size, current `inputValue`, the change handler wired to update local state, the blur handler wired only when not read-only, `label`, `helperText: helperTextToDisplay`, `placeholder: placeholder ?? ''`, `required`, `disabled`, an error state when `status === 'error'`, and `maxLength` plus the read-only/test-id attributes applied to the underlying input element.
 
 ## Behavioral Contract
 
-1. **Local state:** Maintain `inputValue` in local state (string). Initialize to `value` prop (`''` default).
-2. **Sync from store:** `useEffect` watching `value` prop — call `setInputValue(value)` whenever `value` changes.
+1. **Local state:** Maintain `inputValue` in local state (string). Initialize to the `value` input (`''` default).
+2. **Sync from store:** A lifecycle effect watching the `value` input updates `inputValue` whenever `value` changes.
 3. **On change:** Update local `inputValue` state only (do NOT commit to store on every keystroke).
-4. **On blur:** Commit to store by calling `handleEvent(actions, 'changeNblur', propName, inputValue)`.
-5. **Read-only:** Render input with `readOnly` attribute set; use a visually borderless ("standard") variant. Do NOT skip the blur handler when readOnly — simply omit it (`onBlur={!readOnly ? handleBlur : undefined}`).
+4. **On blur:** Commit to store by invoking the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+5. **Read-only:** Render input with a read-only attribute set; use a visually borderless ("standard") style. Do NOT skip the blur handler unconditionally — only omit it when the field is read-only.
 6. **maxLength:** Read from `fieldMetadata?.maxLength`; pass to the underlying input's `maxLength` attribute.
-7. **testId:** Pass as `data-test-id` attribute on the underlying `<input>` element.
+7. **testId:** Pass as a test-identifier attribute on the underlying input element.
 
 ## Display Mode Rendering
 
-- **`DISPLAY_ONLY`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} />` — display raw string value, no formatting.
-- **`STACKED_LARGE_VAL`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
-- Both modes use `value` prop directly (not local state).
+- **`DISPLAY_ONLY`:** Render the `FieldValueList` display component with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw `value` — display raw string value, no formatting.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
+- Both modes use the `value` input directly (not local state).
 - Both modes short-circuit before any interactive rendering.
 
 ## Read-Only Rendering
 
-Set the `readOnly` attribute on the underlying input element. Use a visually flat/borderless style (no border box). The editable `outlined` variant switches to a `standard` (no outline) variant when read-only.
+Set a read-only attribute on the underlying input element. Use a visually flat/borderless style (no border box). The editable outlined style switches to a flat (no outline) style when read-only.
 
 ## Visual Specifications
 
-Derived from the reference component's MUI props and styles:
-
-| Property        | Standard (editable)                              | Read-only               |
-| --------------- | ------------------------------------------------ | ----------------------- |
-| Width           | 100% of container                                | 100% of container       |
-| Height / size   | Small (`height ~40px`)                           | Small                   |
-| Border          | 1px solid (outlined)                             | None (standard variant) |
-| Border radius   | 4px                                              | —                       |
-| Label           | Floating label (above input when focused/filled) | Floating label          |
-| Helper text     | Shown below input                                | Shown below input       |
-| Error state     | Red border + red helper text                     | —                       |
-| Disabled        | Reduced opacity (~0.38), not-allowed cursor      | —                       |
-| Padding (input) | 8px 14px                                         | —                       |
-| Font size       | 0.875rem (14px)                                  | 0.875rem                |
+Derived from the reference component's styling:
+
+| Property        | Standard (editable)                              | Read-only         |
+| --------------- | ------------------------------------------------ | ----------------- |
+| Width           | 100% of container                                | 100% of container |
+| Height / size   | Small (`height ~40px`)                           | Small             |
+| Border          | 1px solid (outlined)                             | None (flat style) |
+| Border radius   | 4px                                              | —                 |
+| Label           | Floating label (above input when focused/filled) | Floating label    |
+| Helper text     | Shown below input                                | Shown below input |
+| Error state     | Red border + red helper text                     | —                 |
+| Disabled        | Reduced opacity (~0.38), not-allowed cursor      | —                 |
+| Padding (input) | 8px 14px                                         | —                 |
+| Font size       | 0.875rem (14px)                                  | 0.875rem          |
 
 **CSS-only implementation notes:**
 
@@ -141,34 +88,25 @@ Derived from the reference component's MUI props and styles:
 
 ## Edge Cases & Special Logic
 
-- If `value` prop is `undefined`, default to `''` to keep the input controlled.
-- If `readOnly` is true, the `onBlur` handler must be omitted — do not commit on blur for read-only.
+- If the `value` input is `undefined`, default to `''` to keep the input controlled.
+- If `readOnly` is true, the blur handler must be omitted — do not commit on blur for read-only.
 - `maxLength` is optional; only apply the attribute if `fieldMetadata?.maxLength` is defined.
 
 ## Dependencies
 
-- `handleEvent` from `../../helpers/event-utils` — for committing value to store.
-- `getComponentFromRegistry('FieldValueList')` — for display modes.
+- The project's event-commit utility — for committing value to store.
+- The project's component registry, resolving `FieldValueList` — for display modes.
 - No third-party UI libraries required beyond a basic text input element.
 
 ## Design System Mapping
 
-**UI control type:** Single-line text input (`<input type="text">`).
-
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                     |
-| ------------------ | --------------------------------------------------------- |
-| Default (CSS only) | `<input type="text">` with floating label pattern         |
-| MUI                | `<TextField variant='outlined' size='small' fullWidth />` |
-| Ant Design         | `<Input />`                                               |
-| Chakra UI          | `<Input />`                                               |
-| Shadcn/ui          | `<Input />`                                               |
+**UI control type:** Single-line text input.
 
-When implementing in a specific design system, map the following behaviors:
+When implementing in a specific design system, map the following:
 
-- `error={status === 'error'}` → error/danger variant
-- `helperText` → helper/description slot below the input
-- `label` → field label (floating or static depending on design system)
-- `disabled` → disabled prop
-- `required` → required/asterisk indicator
+- **Text input** → use the DS's basic text input component
+- **`status === 'error'`** → the DS's error/danger visual state
+- **`helperText`** → the DS's helper/description text slot below the input
+- **`label`** → the DS's field label (floating or static depending on the design system)
+- **`disabled`** → the DS's disabled state
+- **`required`** → the DS's required/asterisk indicator