@openg2p/registry-widgets 0.2.1 → 1.0.0

package/README.md

@@ -16,9 +16,14 @@ The Registry UI Widget Library is a layered, extensible system that enables you
 - ✅ **Data Sources** (static, API, schema reference)
 - ✅ **Formatting** (dates, currency, phone numbers, numbers)
 - ✅ **Widget Registry** system for extensible plugin architecture
-- ✅ **19+ Pre-built Widgets** ready to use
+- ✅ **20 Pre-built Widgets** ready to use (including HeaderSection)
 - ✅ **Internationalization** support via i18next
 - ✅ **Tailwind CSS** ready (unstyled base, you provide styles)
+- ✅ **Multi-mode Section Rendering** (RegistryView, CRView, IntakeForm)
+- ✅ **Geo Hierarchy Cascading Dropdowns** for location-based fields
+- ✅ **Section Builder** with visual and JSON editor for UI schemas
+- ✅ **Form Handle API** for host-driven validation and submission
+- ✅ **Dirty Tracking** with unsaved changes detection per section
 
 ## Installation
 
@@ -77,7 +82,7 @@ The library follows a layered architecture that separates concerns and enables e
               ↓
 ┌─────────────────────────────────────────┐
 │     Widget Components Layer              │
-│  (19+ Pre-built Widgets)                 │
+│  (20 Pre-built Widgets)                  │
 └─────────────────────────────────────────┘
               ↓
 ┌─────────────────────────────────────────┐
@@ -102,7 +107,7 @@ The library follows a layered architecture that separates concerns and enables e
 
 **Widget Registry Layer** - A plugin system that maintains a catalog of available widgets. When a widget is requested by name, the registry looks it up and returns the corresponding React component. This enables dynamic widget loading and easy extensibility - new widgets can be registered without modifying core library code.
 
-**Widget Components Layer** - The actual React components that render UI elements (text inputs, selects, tables, etc.). These are the 19+ pre-built widgets that come with the library. Each widget is a React component that receives configuration and renders the appropriate UI. Custom widgets can be added by registering them in the registry.
+**Widget Components Layer** - The actual React components that render UI elements (text inputs, selects, tables, etc.). These are the 20 pre-built widgets that come with the library. Each widget is a React component that receives configuration and renders the appropriate UI. Custom widgets can be added by registering them in the registry.
 
 **Core Hooks Layer** - React hooks that provide all the business logic for widgets. The `useBaseWidget` hook handles state management, validation, conditional logic, data source loading, and formatting. The `useWidgetTranslation` hook provides internationalization support. Widget components use these hooks to get values, errors, visibility states, and change handlers without directly interacting with Redux or utilities.
 
@@ -224,25 +229,92 @@ Support for multiple validation strategies:
 
 ## Available Widgets
 
-The library includes 19+ pre-built widgets:
+The library includes 20 pre-built widgets:
 
 - **Input Widgets**: TextInput, TextArea, NumberInput, CurrencyInput, DateInput, DateTimeInput, PhoneInput, FileInput
 - **Selection Widgets**: Select, Radio, Checkbox, Boolean
 - **Layout Widgets**: Array, IterableAccordion
 - **Display Widgets**: Display, Profile
 - **Table Widgets**: Table, SimpleTable
+- **Section Widgets**: HeaderSection
 
-> 📚 **Widget documentation coming soon!** Detailed guides for each widget will be available in our tutorial pages.
+### HeaderSection Widget
+
+A full-width header card designed for registry record views. Displays a profile image, record name, functional ID, status badge, and audit metadata (created by / approved by) in a responsive two-column layout. Supports editable status and status-reason fields with data source-driven dropdowns, customisable label overrides via i18n, and configurable status-colour mapping.
+
+```json
+{
+  "widget": "header-section",
+  "widget-type": "group",
+  "widget-id": "registry-header",
+  "widget-data-path": {
+    "image": "record_image_storage_id",
+    "name": "record_name",
+    "functionalId": "functional_record_id",
+    "status": "record_status"
+  }
+}
+```
+
+## Section Modes
+
+`SectionsContainer` supports three display modes via the `mode` prop:
+
+### RegistryView (default)
+
+Standard registry display. Sections render in a CSS Grid layout with an inline **Edit Details** button. Only one section can be in edit mode at a time; editing a section opens it as a portal-based overlay with save/cancel controls.
+
+### CRView (Change Request View)
+
+Read-only comparison view for change requests. Sections display **Created by** / **Approved by** metadata and support `changeRequestType` labels (`"new"` / `"old"`) for side-by-side comparison.
+
+### IntakeForm
+
+Accordion-based registration form. Sections expand and collapse, with **Prev** / **Next** navigation buttons. Supports `isDraft` mode (editable vs read-only), per-section validation on save, and status badges (**Saved** / **Modified and not saved**).
+
+## Form Handle API
+
+`SectionsContainer` exposes a `SectionsFormHandle` via the `onFormReady` callback, enabling host applications to drive form submission externally:
+
+```tsx
+<SectionsContainer
+  sections={sections}
+  mode="IntakeForm"
+  onFormReady={(handle) => {
+    // handle.validate()            – validate all sections, returns boolean
+    // handle.getFormData()         – raw store data (no validation)
+    // handle.validateAndGetData()  – validate then return SectionChanges[]
+    // handle.getStructuredData()   – get records and files without validation
+  }}
+/>
+```
+
+## Geo Hierarchy Cascading Dropdowns
+
+The `useGeoWidgetCascade` hook and `geoHierarchyBuilder` utility provide cascading dropdown functionality for geographic location fields (e.g. Country > State > City). Changes in a parent level automatically reload and reset child dropdowns via the widget event bus.
+
+## Section Builder
+
+A visual UI schema editor shipped as `SectionBuilder`, with sub-components:
+
+- **JSONEditorPanel** — Live JSON editor (powered by `json-edit-react`) for direct schema manipulation
+- **VisualBuilderPanel** — Drag-and-drop visual layout editor
+- **SectionTree** — Tree view of the section/panel/widget hierarchy
+- **PropertyEditor** — Contextual property panel for the selected node
 
 ## Examples
 
 See the `examples/` directory for comprehensive examples demonstrating:
 
-- Basic widget usage
-- Layout widgets
-- Schema internationalization
-- Comparison views
-- And more...
+- Basic widget usage (`usage-example.tsx`)
+- Layout widgets (`LayoutWidgets.tsx`)
+- Schema internationalization (`schema-i18n-example.tsx`)
+- Comparison views (`comparison-view-example.tsx`)
+- Section rendering modes (`section-renderer-example.tsx`)
+- Intake form flow (`intake-form-example.tsx`)
+- Header section widget (`header-section-example.tsx`)
+- Section builder (`section-builder-example.tsx`)
+- JSON editor standalone (`jsoneditor-standalone-example.tsx`)
 
 ## API Reference
 
@@ -280,10 +352,36 @@ Registry for managing widget components.
 
 ### Components
 
-- `SectionsContainer` - Container for rendering sections
-- `SectionRenderer` - Renders individual sections
+- `SectionsContainer` - Container for rendering sections with mode support (RegistryView, CRView, IntakeForm)
+- `SectionRenderer` - Renders individual sections with edit mode, dirty tracking, and accordion support
 - `PanelRenderer` - Renders panels within sections
 - `FilePreviewModal` - Modal for file preview
+- `SectionBuilder` - Visual UI schema editor
+- `JSONEditorPanel` - JSON editor for UI schemas
+- `VisualBuilderPanel` - Visual layout builder
+- `SectionTree` - Tree view of section hierarchy
+- `PropertyEditor` - Property editor for selected nodes
+
+### Hooks
+
+- `useBaseWidget` - Core hook for widget state, validation, conditional logic, and formatting
+- `useWidgetTranslation` - i18n hook for widget labels and messages
+- `useWidgetEventBus` - Pub/sub event bus for inter-widget communication
+- `useWidgetCascade` - Cascading dropdown behaviour between linked widgets
+- `useGeoWidgetCascade` - Geo hierarchy cascading for location-based dropdowns
+
+### Utilities
+
+- `pathUtils` - Dot-notation path read/write for nested data structures
+- `validation` - Built-in, regex, and Zod validation
+- `formatting` - Date, currency, phone, number, and text formatting
+- `conditions` - Conditional show/hide and enable/disable evaluation
+- `dataSource` - Static, API, and schema reference data loading
+- `geoHierarchy` - Geo hierarchy builder for location cascades
+- `sectionValidate` - Section-level validation across all widgets
+- `buildSectionChanges` - Build change payloads from section data
+- `schemaNamespace` - Namespace section configs for multi-instance rendering
+- `schemaTranslation` - Translate UI schemas, widget configs, and panel configs
 
 ## Contributing
 

package/dist/hooks/useWidgetTheme.d.ts

@@ -0,0 +1,19 @@
+import { resolveTheme } from '../theme';
+export type ResolvedTheme = ReturnType<typeof resolveTheme>;
+export declare const ThemeContext: import("react").Context<Required<{
+    colors: Required<import("../theme").WidgetThemeColors>;
+    section: Required<import("../theme").WidgetThemeSection>;
+    panel: Required<import("../theme").WidgetThemePanel>;
+    button: Required<import("../theme").WidgetThemeButton>;
+    widget: Required<import("../theme").WidgetThemeWidget>;
+}>>;
+/**
+ * Access the resolved widget theme from any component inside `<WidgetProvider>`.
+ *
+ * ```tsx
+ * const theme = useWidgetTheme();
+ * // theme.colors.primary, theme.section.dividerColor, etc.
+ * ```
+ */
+export declare function useWidgetTheme(): ResolvedTheme;
+//# sourceMappingURL=useWidgetTheme.d.ts.map

package/dist/hooks/useWidgetTheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWidgetTheme.d.ts","sourceRoot":"","sources":["../../src/hooks/useWidgetTheme.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,YAAY,EAAE,MAAM,UAAU,CAAC;AAEtD,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AAE5D,eAAO,MAAM,YAAY;;;;;;GAA6C,CAAC;AAEvE;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,aAAa,CAE9C"}

package/dist/theme/index.d.ts

@@ -0,0 +1,101 @@
+import React from 'react';
+/**
+ * Theme color tokens for the widget library.
+ * All properties are optional — omitted values fall back to built-in defaults.
+ */
+export interface WidgetThemeColors {
+    /** Main brand colour (default: #F2BA1A — gold) */
+    primary?: string;
+    /** Darker brand accent (default: #ED7C22 — orange) */
+    primaryDark?: string;
+    /** Light brand tint for backgrounds (default: #F3E6BC) */
+    primaryLight?: string;
+    /** Secondary accent used in edit-mode borders (default: #FD8C3E) */
+    primaryAccent?: string;
+    /** Standard border colour (default: #D1D5DB) */
+    border?: string;
+    /** Lighter border colour (default: #E5E7EB) */
+    borderLight?: string;
+    /** Default background (default: #FFFFFF) */
+    background?: string;
+    /** Alternate/muted background (default: #F3F4F6) */
+    backgroundAlt?: string;
+    /** Primary text colour (default: #000000) */
+    text?: string;
+    /** Secondary / muted text colour (default: #6B7280) */
+    textMuted?: string;
+    /** Success green (default: #16A34A) */
+    success?: string;
+    /** Success dark green (default: #047857) */
+    successDark?: string;
+    /** Error / danger red (default: #B91C1C) */
+    error?: string;
+    /** Warning amber (default: #F59E0B) */
+    warning?: string;
+    /** Info / link blue (default: #2563EB) */
+    info?: string;
+}
+export interface WidgetThemeSection {
+    borderRadius?: string;
+    borderColor?: string;
+    backgroundColor?: string;
+    titleColor?: string;
+    /** Horizontal-rule / divider colour between panels (default: primary) */
+    dividerColor?: string;
+}
+export interface WidgetThemePanel {
+    /** Vertical divider colour between side-by-side panels */
+    dividerColor?: string;
+    backgroundColor?: string;
+}
+export interface WidgetThemeButton {
+    primaryBg?: string;
+    primaryColor?: string;
+    primaryBorder?: string;
+    secondaryBg?: string;
+    secondaryColor?: string;
+    secondaryBorder?: string;
+    borderRadius?: string;
+}
+export interface WidgetThemeWidget {
+    labelColor?: string;
+    inputBorderColor?: string;
+    inputFocusBorderColor?: string;
+    inputBackground?: string;
+    errorColor?: string;
+    helpTextColor?: string;
+}
+/**
+ * Top-level theme object accepted by `<WidgetProvider theme={…}>`.
+ * Every field is optional — only supply what you want to override.
+ */
+export interface WidgetTheme {
+    colors?: WidgetThemeColors;
+    section?: WidgetThemeSection;
+    panel?: WidgetThemePanel;
+    button?: WidgetThemeButton;
+    widget?: WidgetThemeWidget;
+}
+/**
+ * Built-in default values (matches the original hardcoded colours).
+ */
+export declare const defaultTheme: Required<{
+    colors: Required<WidgetThemeColors>;
+    section: Required<WidgetThemeSection>;
+    panel: Required<WidgetThemePanel>;
+    button: Required<WidgetThemeButton>;
+    widget: Required<WidgetThemeWidget>;
+}>;
+/**
+ * Merge a user-supplied (partial) theme with the built-in defaults.
+ */
+export declare function resolveTheme(theme?: WidgetTheme): typeof defaultTheme;
+/**
+ * Convert a resolved theme into a flat Record of CSS custom properties.
+ * These are set on the provider wrapper element so every descendant can
+ * reference them with `var(--owt-…)`.
+ *
+ * Prefix: `--owt-` (OpenG2P Widget Theme).
+ */
+export declare function themeToCSSVariables(resolved: ReturnType<typeof resolveTheme>): React.CSSProperties;
+//# sourceMappingURL=index.d.ts.map

package/dist/theme/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openg2p/registry-widgets",
-  "version": "0.2.1",
+  "version": "1.0.0",
   "type": "module",
   "description": "Complete React widget library with generic form widgets, data binding, validation, and conditional logic",
   "main": "dist/index.js",