How shibu-narayanan/openg2p-registry-ui-widgets works
1. What this repo is
This is a TypeScript/React component library, not a standalone app. Its primary purpose is to render configurable form widgets from JSON-like UI schema, with a second major subsystem for building/editing those schemas visually.
2. Public surface and package boundaries
The main library entry point is src/index.ts, which exposes the provider, renderer, store helpers, registry, and widget components. A separate entry for the schema editor exists under src/components/SectionBuilder/index.ts. The repo also contains examples/ for demo apps and dist-examples/ for built static example output.
3. Runtime rendering pipeline
The core runtime flow is: schema/config in → widget lookup → React widget render → state updates back to store. WidgetRenderer is the main dynamic entry, while SectionRenderer, PanelRenderer, and SectionsContainer support higher-level hierarchical layouts such as sections and panels.
4. Widget registry as the extensibility boundary
src/registry/WidgetRegistry.ts and defaultWidgets.ts define the plugin-like registry that maps widget names to React components. This is the key boundary for customization: consumers can register new widgets without changing the core renderer. The concrete widget implementations live in src/widgets/.
5. Widget implementations
The src/widgets/ folder contains the built-in field and layout widgets: text, select, radio, checkbox, boolean, number/currency/date/datetime/phone/file inputs, display/profile widgets, and table/array layout widgets. These components are intentionally thin and rely on shared hooks and store state rather than owning business logic themselves.
6. Shared widget logic lives in hooks
useBaseWidget is the central orchestration hook for value access, change handling, validation, visibility/enabled state, formatting, and data-source hydration. Supporting hooks add specialized behavior: widget cascades, geo cascades, translation, and event-bus integration. This keeps widget components mostly presentational.
7. Centralized state management
src/store/widgetSlice.ts and src/store/index.ts provide the Redux-based state layer. The store tracks widget values, errors, touched state, loading state, and option lists, giving the library a single source of truth for all widgets. WidgetProvider wraps this store and also injects shared runtime context like API adapters and schema data.
8. Cross-cutting utilities
Most non-UI behavior is in src/utils/: validation, conditional logic, path resolution, formatting, data-source loading, file serialization/preview helpers, date/number/text input helpers, schema translation, and section validation. These utilities are pure-ish boundaries that isolate domain rules from React components.
9. Internationalization and schema translation
i18n is wired through src/i18n/ with an i18next config and locale files, while useWidgetTranslation and schema translation utilities adapt labels/messages from schema-driven configs. This makes the rendering layer language-aware without hard-coding strings into widgets.
10. Section Builder subsystem
src/components/SectionBuilder/ is a distinct authoring tool for building UI schemas. It is split into JSONEditorPanel, VisualBuilderPanel, SectionTree, and PropertyEditor, which suggests a dual-mode editor: direct JSON editing plus a visual tree/property workflow. schemas.ts and the design docs indicate it manages schema structure, editing rules, and host integration.
11. Data dependencies and external integration
The library depends materially on React, Redux Toolkit/react-redux, Zod, and i18next. WidgetProvider accepts an apiAdapter and schemaData, so widgets can pull dynamic options from external APIs or schema references rather than only static config. Validation and conditional visibility therefore depend on both local state and external data sources.
12. Build, examples, and distribution
rollup.config.js is used for library packaging, while vite.config.ts supports the example apps. The examples/ directory demonstrates different integration modes: standalone widget rendering, section rendering, i18n, comparison views, intake forms, and builder usage. docs/, QUICKSTART.md, and TUTORIAL.md are documentation/support layers rather than runtime dependencies.
Main entry points: useBaseWidget.ts useBaseWidget · index.ts Library entry · SectionBuilder.tsx SectionBuilder · WidgetRenderer.tsx WidgetRenderer
Components 30
Public API
Library entry points exposed to consumers.
- Library entry · Main package export surface for provider, renderer, registry, store, and widgets.
src/index.ts - Builder entry · Dedicated entry for the schema editor subsystem.
src/components/SectionBuilder/index.ts
Rendering Runtime
Schema-to-widget rendering pipeline and shared runtime state.
- WidgetProvider · Wraps the Redux store and injects API adapter and schema context.
src/components/WidgetProvider.tsx - WidgetRenderer · Main dynamic widget lookup and render entry point.
src/components/WidgetRenderer.tsx - SectionRenderer · Renders section-level structures above individual widgets.
src/components/SectionRenderer.tsx - PanelRenderer · Renders panel-level containers within hierarchical layouts.
src/components/PanelRenderer.tsx - SectionsContainer · Top-level container for sectioned UI schema composition.
src/components/SectionsContainer.tsx
Built-in Widgets
Default field and layout widgets used by the runtime.
- Text input · Representative built-in text entry widget implementation.
src/widgets/TextInputWidget.tsx - Select widget · Representative built-in choice widget implementation.
src/widgets/SelectWidget.tsx - Array widget · Representative built-in repeated-item and collection widget implementation.
src/widgets/ArrayWidget.tsx - Table widget · Representative built-in tabular collection widget implementation.
src/widgets/TableWidget.tsx
Section Builder
Schema authoring subsystem for JSON and visual editing.
- SectionBuilder · Main schema authoring component that combines JSON and visual editing.
src/components/SectionBuilder/SectionBuilder.tsx - JSON editor · Direct schema editing panel for raw JSON input.
src/components/SectionBuilder/JSONEditorPanel.tsx - Visual builder · Graphical schema editing panel for section and field structure.
src/components/SectionBuilder/VisualBuilderPanel.tsx - Section tree · Navigation and structural outline for editable sections.
src/components/SectionBuilder/SectionTree.tsx - Property editor · Edits selected node properties and schema attributes.
src/components/SectionBuilder/PropertyEditor.tsx - Builder schemas · Schema definitions and editing constraints for the builder UI.
src/components/SectionBuilder/schemas.ts
Shared Logic
Hooks, utilities, registry, store, events, and i18n.
- WidgetRegistry · Maps widget names to React components and serves as the extensibility boundary.
src/registry/WidgetRegistry.ts - Default widgets · Built-in widget registrations used by default by the renderer.
src/registry/defaultWidgets.ts - widgetSlice · Central state for values, errors, touched state, loading, and options.
src/store/widgetSlice.ts - Store setup · Configures and exposes the Redux-based widget store.
src/store/index.ts - useBaseWidget · Central hook for value access, validation, visibility, formatting, and data hydration.
src/hooks/useBaseWidget.ts - useWidgetCascade · Supports dependent value cascades between widgets.
src/hooks/useWidgetCascade.ts - useGeoWidgetCascade · Specialized cascade behavior for geo/hierarchy-driven widgets.
src/hooks/useGeoWidgetCascade.ts - useWidgetTranslation · Adapts widget labels and messages to locale-aware schema text.
src/hooks/useWidgetTranslation.ts - WidgetEventBus · Shared event channel for widget-level cross-cutting interactions.
src/events/WidgetEventBus.ts - Widget types · Shared TypeScript type definitions for widgets, schema, and runtime contracts.
src/types/index.ts - Validation utils · Cross-cutting validation and conditional logic helpers.
src/utils/validation.ts - Schema translation · Transforms schema-driven labels and messages for localization.
src/utils/schemaTranslation.ts - Data source · Loads and adapts external option and schema data sources.
src/utils/dataSource.ts
Connections 33
- Library entry → WidgetProvider: exports · Public package surface exposes the provider.
- Library entry → WidgetRenderer: exports · Public package surface exposes the main renderer.
- Library entry → WidgetRegistry: exports · Consumers can access registry customization.
- Library entry → Store setup: exports · Store helpers are part of the public API.
- Library entry → Widget types: exports · Shared types are exported for consumer integration.
- Builder entry → SectionBuilder: exports · Dedicated builder entry exposes the editor subsystem.
- WidgetProvider → Store setup: creates · Provider wraps and initializes the central store.
- WidgetProvider → WidgetRenderer: hosts · Provides runtime context to widget rendering.
- WidgetRenderer → WidgetRegistry: looks up · Resolves widget names to component implementations.
- WidgetRegistry → Default widgets: loads · Default registration set seeds the registry.
- WidgetRenderer → SectionRenderer: delegates · Higher-level section structures are rendered by section components.
- SectionRenderer → PanelRenderer: nests · Section rendering composes panel-level containers.
- PanelRenderer → SectionsContainer: contains · Panels are organized within the top-level sections container.
- WidgetRenderer → widgetSlice: reads/writes · Renderer interacts with central widget state.
- widgetSlice → Store setup: configured by · Slice becomes part of the Redux store.
- Text input → useBaseWidget: uses · Built-in widgets rely on shared orchestration logic.
- Select widget → useBaseWidget: uses · Built-in widgets rely on shared orchestration logic.
- Array widget → useBaseWidget: uses · Collection widgets rely on shared orchestration logic.
- Table widget → useBaseWidget: uses · Tabular widgets rely on shared orchestration logic.
- useBaseWidget → Validation utils: applies · Validation and conditional behavior are centralized.
- useBaseWidget → Data source: hydrates · Option and schema data can be pulled from external sources.
- useBaseWidget → Schema translation: translates · Widget labels and messages are localized from schema.
- useBaseWidget → WidgetEventBus: subscribes · Widgets can coordinate via shared events.
- useBaseWidget → useWidgetCascade: composes · Dependent field behavior is factored into cascade hooks.
- useBaseWidget → useGeoWidgetCascade: composes · Geo-specific dependent behavior is isolated in a specialized hook.
- useBaseWidget → widgetSlice: uses state · Reads and updates widget values and meta state.
- SectionBuilder → JSON editor: contains · Builder includes a direct JSON editing mode.
- SectionBuilder → Visual builder: contains · Builder includes a visual schema editing mode.
- Visual builder → Section tree: uses · Visual editing is organized around the section tree.
- Visual builder → Property editor: uses · Node properties are edited through the property panel.
- SectionBuilder → Builder schemas: driven by · Editing rules and schema definitions shape the builder.
- SectionBuilder → Widget types: depends on · Builder and runtime share schema contracts and types.
- Schema translation → Widget types: depends on · Translation helpers use shared type contracts.