@netlisian/softconfig 0.1.4 → 0.1.6

package/README.md

@@ -1,122 +1,62 @@
-# Puck Soft Config
-
-Enhanced configuration and UI utilities for Puck that add “soft components” (composable, versioned, and remodelable components) plus ready-to-use UI chrome.
-
-## Packages & Exports
-
-- `@netlisian/softconfig` → bundled CJS/ESM + types (`./dist/index.{js,mjs,d.ts}`)
-- `@netlisian/softconfig/puck` → Puck-focused entry (`./dist/puck/index.*`)
-- Styles: `@netlisian/softconfig/styles.css` (alias `./dist/index.css`) and `@netlisian/softconfig/puck/index.css`
-
-Peer dependencies: `react@^18`, `@measured/puck@0.20.x`.
-
-## Install
-
-```bash
-pnpm add @netlisian/softconfig @measured/puck react
-```
-
-## Quick Start
-
-```tsx
-import { SoftConfigProvider } from "@netlisian/softconfig/puck";
-import "@netlisian/softconfig/styles.css";
-
-const hardConfig = { components: {/* your hard Puck components */} };
-const softComponents = {/* optional persisted soft components */};
-const overrides = {/* optional UI overrides like map/action bar/etc. */};
-
-export default function App({ children }: { children: React.ReactNode }) {
-  return (
-    <SoftConfigProvider
-      hardConfig={hardConfig}
-      softComponents={softComponents}
-      overrides={overrides}
-    >
-      {(softConfig, softComponentsRegistry) => (
-        /* render Puck with the soft-config-driven config */
-        <YourPuckHost config={softConfig} softComponents={softComponentsRegistry} />
-      )}
-    </SoftConfigProvider>
-  );
-}
-```
-
-`SoftConfigProvider` accepts an optional `value` prop if you want to bring your own Zustand store (see `src/puck/context/storeProvider.tsx`). Children are rendered via a render-prop to give you the hydrated `softConfig` and `softComponents` to pass directly to Puck.
-
-## Field Mapping & Transforms
-
-- Soft components support `_map` entries with optional transforms or CVA-like configs. Because functions are not persisted, the library regenerates missing transforms at runtime (including during remodel/decompose) using the stored CVA config.
-- Field defaults are read from `_fieldSettings` when resolving mappings, so mapped props fall back to configured defaults when source data is absent.
-
-## Styles
-
-Import once in your app root:
-
-```ts
-import "@netlisian/softconfig/styles.css";
-```
-
-## Overrides
-
-You can supply custom overrides (action bar, headers, map UI, etc.) through the `overrides` prop. See `src/puck/types/Overrides.ts` for the full surface.
-
-## Action Lifecycle Events
-
-`SoftConfigProvider` supports `onActions` for lifecycle callbacks:
-
-- `build` → when build mode starts
-- `remodel` → when remodel mode starts
-- `complete` → when a build/remodel is finalized
-- `inspect` → when inspect is requested
-- `demolish` → when a soft component is deleted
-- `setDefaultVersion`, `decompose`, `cancel`, `publish`
-
-Version-aware payloads are included for build finalization and inspection flows:
-
-```ts
-type ActionEventPayload =
-  | {
-      type: "remodel";
-      payload: {
-        id: string;
-        version?: string;
-        softComponent?: VersionedSoftComponent["versions"][string];
-      };
-    }
-  | {
-      type: "complete";
-      payload: {
-        id: string;
-        version: string;
-        componentData: Record<string, any>;
-        softComponent: VersionedSoftComponent["versions"][string];
-      };
-    }
-  | {
-      type: "inspect";
-      payload: {
-        id: string;
-        version?: string;
-        softComponent?: VersionedSoftComponent["versions"][string];
-      };
-    }
-  | {
-      type: "demolish";
-      payload: {
-        id: string;
-      };
-    };
-```
-
-This contract allows downstream consumers (for example, save/sync bridges) to persist using exact version metadata without relying on inferred/default versions.
-
-## Development
-
-- Build: `pnpm --filter @netlisian/softconfig build`
-- Dev (watch): `pnpm --filter @netlisian/softconfig dev`
-- Lint: `pnpm --filter @netlisian/softconfig lint`
-
-## License
-
-MIT
+# @netlisian/soft-config
+
+The core library for building and managing **Soft Components** within the Netlisian ecosystem. It provides type-safe field definitions, recursive mapping logic, and state management for the Puck editor.
+
+## Installation
+
+```bash
+npm install @netlisian/soft-config
+```
+
+## Features
+
+- **Soft Component Builder**: Easy-to-use interface for creating versioned components.
+- **Dynamic Field Options**: Automatically generates dot-notated mapping paths for nested objects and arrays.
+- **Custom Field Support**: Extend the editor with custom UI while maintaining return type safety.
+- **Puck Overrides**: Pre-built component overrides (ActionBar, Header, ComponentList) to seamlessly integrate Soft Components into the Puck editor.
+
+## Key Concepts
+
+### Soft Component Definitions
+
+A Soft Component consists of fields, default props, and typed components.
+
+```typescript
+import { SoftFieldDefinition } from "@netlisian/soft-config";
+
+const galleryField: SoftFieldDefinition = {
+  name: "gallery",
+  type: "array",
+  subFields: [
+    { name: "src", type: "text" },
+    { name: "alt", type: "text" }
+  ]
+};
+```
+
+### Custom Field Extensibility
+
+Define custom field types with specified return types (`string`, `number`, `boolean`, `object`, `array`).
+
+```typescript
+import { CustomFields } from "@netlisian/soft-config";
+
+export const myCustomFields: CustomFields = {
+  "my-color": {
+    field: { type: "custom", render: () => <div>Color Picker</div> },
+    returnType: "string"
+  }
+};
+```
+
+### Field Mapping
+
+The library handles the logic for mapping configuration data to component props, including recursive array iteration using `[]` syntax (e.g., `features[].title`).
+
+## Documentation
+
+For detailed guides and API references, check the [Netlisian Docs](https://docs.netlisian.com).
+
+## License
+
+MIT

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/puck/index.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/components/error-boundary/styles.module.css/#css-module-data","css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/overrides/Header.module.css/#css-module-data","css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/overrides/ActionBar.module.css/#css-module-data","css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/overrides/DrawerItem.module.css/#css-module-data","css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/components/modal/styles.module.css/#css-module-data","css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/overrides/Drawer.module.css/#css-module-data"],"sourcesContent":["/* ErrorBoundary - Following SUIT CSS naming convention */\r\n\r\n._ErrorBoundary_1xl05_5 {\r\n  padding: 20px;\r\n  border: 1px solid #ff5858;\r\n  border-radius: 4px;\r\n  background-color: #fff0f0;\r\n  margin: 10px 0;\r\n}\r\n\r\n._ErrorBoundary-title_1xl05_21 {\r\n  color: #d32f2f;\r\n  margin: 0 0 10px 0;\r\n}\r\n\r\n._ErrorBoundary-details_1xl05_31 {\r\n  white-space: pre-wrap;\r\n}\r\n\r\n._ErrorBoundary-button_1xl05_39 {\r\n  margin-top: 10px;\r\n  padding: 5px 10px;\r\n  background-color: #d32f2f;\r\n  color: white;\r\n  border: none;\r\n  border-radius: 4px;\r\n  cursor: pointer;\r\n}\r\n\r\n._ErrorBoundary-button_1xl05_39:hover {\r\n  background-color: #b71c1c;\r\n}\r\n","._Header_19oj9_1 {\r\n  display: flex;\r\n  justify-content: space-between;\r\n  align-items: center;\r\n  gap: 0.5rem;\r\n  flex-wrap: wrap;\r\n}\r\n","/* ActionBar - SUIT CSS naming convention (renamed from CustomActionBar) */\r\n\r\n._ActionBar_pvuie_5 {\r\n  align-items: center;\r\n  cursor: default;\r\n  display: flex;\r\n  width: auto;\r\n  padding: 4px;\r\n  padding-inline-start: 0;\r\n  padding-inline-end: 0;\r\n  border-top-left-radius: 8px;\r\n  border-top-right-radius: 8px;\r\n  border-radius: 8px;\r\n  background: var(--puck-color-grey-01);\r\n  color: var(--puck-color-white);\r\n  font-family: var(--puck-font-family);\r\n  min-height: 26px;\r\n}\r\n\r\n._ActionBar-label_pvuie_39 {\r\n  color: var(--puck-color-grey-08);\r\n  font-size: var(--puck-font-size-xxxs);\r\n  font-weight: 500;\r\n  padding-inline-start: 8px;\r\n  padding-inline-end: 8px;\r\n  margin-inline-start: 4px;\r\n  margin-inline-end: 4px;\r\n  text-overflow: ellipsis;\r\n  white-space: nowrap;\r\n}\r\n\r\n._ActionBar-action_pvuie_63 + ._ActionBar-label_pvuie_39 {\r\n  padding-inline-start: 0;\r\n}\r\n\r\n._ActionBar-label_pvuie_39 + ._ActionBar-action_pvuie_63 {\r\n  margin-inline-start: -4px;\r\n}\r\n\r\n._ActionBar-group_pvuie_79 {\r\n  align-items: center;\r\n  border-inline-start: 0.5px solid var(--puck-color-grey-05);\r\n  display: flex;\r\n  height: 100%;\r\n  padding-inline-start: 4px;\r\n  padding-inline-end: 4px;\r\n}\r\n\r\n._ActionBar-group_pvuie_79:first-of-type {\r\n  border-inline-start: 0;\r\n}\r\n\r\n._ActionBar-group_pvuie_79:empty {\r\n  display: none;\r\n}\r\n\r\n._ActionBar-action_pvuie_63 {\r\n  background: transparent;\r\n  border: none;\r\n  color: var(--puck-color-grey-08);\r\n  cursor: pointer;\r\n  padding: 6px 8px;\r\n  margin-inline-start: 4px;\r\n  margin-inline-end: 4px;\r\n  border-radius: 4px;\r\n  overflow: hidden;\r\n  display: flex;\r\n  align-items: center;\r\n  justify-content: center;\r\n  transition: color 50ms ease-in;\r\n}\r\n\r\n._ActionBar-action_pvuie_63 svg {\r\n  max-width: none !important;\r\n}\r\n\r\n._ActionBar-action_pvuie_63:focus-visible {\r\n  outline: 2px solid var(--puck-color-azure-05);\r\n  outline-offset: -2px;\r\n}\r\n\r\n@media (hover: hover) and (pointer: fine) {\r\n  ._ActionBar-action_pvuie_63:hover {\r\n    color: var(--puck-color-azure-06);\r\n    transition: none;\r\n  }\r\n}\r\n\r\n._ActionBar-action_pvuie_63:active {\r\n  color: var(--puck-color-azure-07);\r\n  transition: none;\r\n}\r\n\r\n._ActionBar-group_pvuie_79 * {\r\n  margin: 0;\r\n}\r\n","._DrawerItem_182aj_1 {\n  background: var(--puck-color-white);\n  cursor: grab;\n  border: 1px solid var(--puck-color-grey-09);\n  font-size: var(--puck-font-size-xxs);\n  border-radius: 4px;\n  justify-content: space-between;\n  align-items: center;\n  padding: 12px;\n  transition: background-color 50ms ease-in, color 50ms ease-in;\n  display: flex;\n}\n\n._DrawerItem--insertDisabled_182aj_14 {\n  cursor: not-allowed;\n  color: var(--puck-color-grey-5);\n  background: var(--puck-color-grey-11);\n  pointer-events: none; /* Optional: prevents all interactions including settings */\n}\n\n._DrawerItem-content_182aj_21 {\n  flex: 1;\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n  overflow-x: hidden;\n}\n\n._DrawerItem-name_182aj_31 {\n  font-weight: 400;\n}\n\n._DrawerItem-version_182aj_35 {\n  font-size: 10px;\n  color: var(--puck-color-grey-05);\n}\n\n._DrawerItem-actions_182aj_40 {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n}\n\n._DrawerItem-settingsButton_182aj_46 {\n  opacity: 0;\n  transition: opacity 120ms ease;\n  color: var(--puck-color-grey-05);\n}\n\n._DrawerItem_182aj_1:hover ._DrawerItem-settingsButton_182aj_46 {\n  opacity: 1;\n}\n\n._DrawerItem-grip_182aj_56 {\n  color: var(--puck-color-grey-05);\n  display: flex;\n  align-items: center;\n}\n\n/* Modal styles */\n._DrawerItem-modal_182aj_63 {\n  background: var(--puck-color-white);\n  display: flex;\n  flex-direction: column;\n  height: min(90dvh, 100%);\n  min-height: 0;\n}\n\n._DrawerItem-modalHeader_182aj_71 {\n  padding: 24px 32px;\n  border-bottom: 1px solid var(--puck-color-grey-09);\n  flex-shrink: 0;\n}\n\n._DrawerItem-modalTitle_182aj_77 {\n  margin: 0 0 4px 0;\n  font-size: 24px;\n  font-weight: 600;\n  color: var(--puck-color-black);\n}\n\n._DrawerItem-modalSubtitle_182aj_84 {\n  margin: 0;\n  font-size: 14px;\n  color: var(--puck-color-grey-04);\n}\n\n._DrawerItem-modalBody_182aj_90 {\n  flex: 1;\n  min-height: 0;\n  padding: 32px;\n  overflow-y: auto;\n  display: flex;\n  flex-direction: column;\n  gap: 32px;\n}\n\n._DrawerItem-section_182aj_100 {\n  display: flex;\n  flex-direction: column;\n  gap: 16px;\n}\n\n._DrawerItem-sectionTitle_182aj_106 {\n  margin: 0;\n  font-size: 16px;\n  font-weight: 600;\n  color: var(--puck-color-black);\n}\n\n._DrawerItem-sectionDescription_182aj_113 {\n  margin: 0;\n  font-size: 14px;\n  color: var(--puck-color-grey-04);\n}\n\n._DrawerItem-versionList_182aj_119 {\n  display: flex;\n  flex-direction: column;\n  gap: 8px;\n}\n\n._DrawerItem-versionRow_182aj_125 {\n  display: flex;\n  justify-content: space-between;\n  align-items: center;\n  padding: 16px;\n  border-radius: 6px;\n  border: 1px solid var(--puck-color-grey-09);\n  background: var(--puck-color-white);\n  transition: all 150ms ease;\n}\n\n._DrawerItem-versionRow--isDefault_182aj_136 {\n  border-color: var(--puck-color-azure-07);\n  background: var(--puck-color-azure-10);\n}\n\n._DrawerItem-versionRow--isMarkedForDeletion_182aj_141 {\n  opacity: 0.6;\n  background: var(--puck-color-grey-11);\n}\n\n._DrawerItem-versionInfo_182aj_146 {\n  display: flex;\n  align-items: center;\n  gap: 12px;\n  flex: 1;\n}\n\n._DrawerItem-versionNumber_182aj_153 {\n  font-size: 14px;\n  font-weight: 500;\n  color: var(--puck-color-black);\n}\n\n._DrawerItem-defaultBadge_182aj_159 {\n  font-size: 11px;\n  padding: 3px 8px;\n  border-radius: 4px;\n  background: var(--puck-color-azure-07);\n  color: var(--puck-color-white);\n  font-weight: 500;\n  text-transform: uppercase;\n  letter-spacing: 0.5px;\n}\n\n._DrawerItem-deleteBadge_182aj_170 {\n  font-size: 11px;\n  padding: 3px 8px;\n  border-radius: 4px;\n  background: var(--puck-color-grey-07);\n  color: var(--puck-color-white);\n  font-weight: 500;\n  text-transform: uppercase;\n  letter-spacing: 0.5px;\n}\n\n._DrawerItem-versionActions_182aj_181 {\n  display: flex;\n  gap: 8px;\n  align-items: center;\n}\n\n._DrawerItem-migrationOptions_182aj_187 {\n  width: 100%;\n}\n\n._DrawerItem-migrationList_182aj_191 {\n  display: flex;\n  flex-direction: column;\n  gap: 8px;\n  max-height: 180px;\n  overflow-y: auto;\n  padding: 8px;\n  border: 1px solid var(--puck-color-grey-09);\n  border-radius: 6px;\n  background: var(--puck-color-white);\n}\n\n._DrawerItem-migrationOption_182aj_187 {\n  width: 100%;\n  padding: 10px 12px;\n  border: 1px solid var(--puck-color-grey-09);\n  border-radius: 6px;\n  font-size: 14px;\n  background: var(--puck-color-white);\n  color: var(--puck-color-black);\n  cursor: pointer;\n  transition: border-color 150ms ease;\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  gap: 8px;\n  text-align: start;\n}\n\n._DrawerItem-migrationOption_182aj_187:hover {\n  border-color: var(--puck-color-grey-07);\n}\n\n._DrawerItem-migrationOption_182aj_187:focus {\n  outline: none;\n  border-color: var(--puck-color-azure-07);\n}\n\n._DrawerItem-migrationOption--isSelected_182aj_229 {\n  border-color: var(--puck-color-azure-07);\n  background: var(--puck-color-azure-10);\n}\n\n._DrawerItem-migrationOptionLabel_182aj_234 {\n  white-space: nowrap;\n  overflow: hidden;\n  text-overflow: ellipsis;\n}\n\n._DrawerItem-modalFooter_182aj_240 {\n  padding: 20px 32px;\n  border-top: 1px solid var(--puck-color-grey-09);\n  display: flex;\n  justify-content: space-between;\n  align-items: center;\n  background: var(--puck-color-grey-11);\n  flex-shrink: 0;\n}\n\n._DrawerItem-footerLeft_182aj_250 {\n  display: flex;\n  gap: 12px;\n}\n\n._DrawerItem-footerRight_182aj_255 {\n  display: flex;\n  gap: 12px;\n}\n","._Modal_1t9ot_1 {\r\n  background: color-mix(in srgb, var(--puck-color-black) 75%, transparent);\r\n  display: none;\r\n  justify-content: center;\r\n  align-items: center;\r\n  position: fixed;\r\n  top: 0;\r\n  left: 0;\r\n  bottom: 0;\r\n  right: 0;\r\n  z-index: 1000;\r\n  padding: 32px;\r\n}\r\n\r\n._Modal--isOpen_1t9ot_29 {\r\n  display: flex;\r\n}\r\n\r\n._Modal-inner_1t9ot_37 {\r\n  width: 100%;\r\n  max-width: 1024px;\r\n  border-radius: 8px;\r\n  overflow: visible;\r\n  background: var(--puck-color-white);\r\n  display: flex;\r\n  flex-direction: column;\r\n  max-height: 90dvh;\r\n  min-height: 0;\r\n}\r\n","._Drawer_12zq5_1 {\n  display: flex;\n  flex-direction: column;\n  gap: 0;\n}\n\n._Drawer-category_12zq5_7 {\n  max-width: 100%;\n}\n\n._Drawer-category_12zq5_7 + ._Drawer-category_12zq5_7 {\n  margin-top: 4px;\n}\n\n._Drawer-category--isExpanded_12zq5_15 + ._Drawer-category_12zq5_7 {\n  margin-top: 12px;\n}\n\n._Drawer-categoryContent_12zq5_19 {\n  display: none;\n}\n\n._Drawer-category--isExpanded_12zq5_15 > ._Drawer-categoryContent_12zq5_19 {\n  display: block;\n}\n\n._Drawer-categoryTitle_12zq5_27 {\n  background-color: transparent;\n  border: 0;\n  color: var(--puck-color-grey-05);\n  cursor: pointer;\n  display: flex;\n  font: inherit;\n  font-size: var(--puck-font-size-xxxs);\n  list-style: none;\n  margin-bottom: 6px;\n  padding: 8px;\n  text-transform: uppercase;\n  transition: background-color 50ms ease-in, color 50ms ease-in;\n  gap: 4px;\n  border-radius: 4px;\n  width: 100%;\n}\n\n._Drawer-categoryTitle_12zq5_27:focus-visible {\n  outline: 2px solid var(--puck-color-azure-05);\n  outline-offset: 2px;\n}\n\n@media (hover: hover) and (pointer: fine) {\n  ._Drawer-categoryTitle_12zq5_27:hover {\n    background-color: var(--puck-color-azure-11);\n    color: var(--puck-color-azure-04);\n    transition: none;\n  }\n}\n\n._Drawer-categoryTitle_12zq5_27:active {\n  background-color: var(--puck-color-azure-10);\n  transition: none;\n}\n\n._Drawer-categoryTitleIcon_12zq5_63 {\n  margin-inline-start: auto;\n}\n"],"mappings":"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","names":[]}

package/dist/puck/index.d.mts

@@ -1,36 +1,104 @@
 import * as zustand from 'zustand';
 import { StoreApi } from 'zustand';
 import * as _measured_puck from '@measured/puck';
-import { DefaultComponentProps, Field, Config, Fields, History, AppState, PuckApi, ComponentData, ComponentConfig, RootData, AsFieldProps, WithChildren, Metadata, ResolveDataTrigger, PuckAction, Data } from '@measured/puck';
+import { Field, Fields, Config, DefaultComponentProps, History, AppState, PuckApi, ComponentData, ComponentConfig, RootData, AsFieldProps, WithChildren, Metadata, ResolveDataTrigger, PuckAction, Data } from '@measured/puck';
 import * as React$1 from 'react';
 import React__default, { ReactNode, ReactElement } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
+type BuiltInSoftFieldType = "text" | "textarea" | "number" | "select" | "radio" | "array" | "object" | "reference";
+type SoftFieldType = BuiltInSoftFieldType | string;
+type CustomFieldReturnType = "string" | "number" | "boolean" | "object" | "array";
+type SoftFieldDefinition = {
+    name: string;
+    type: SoftFieldType;
+};
+type FieldOption = {
+    label: string;
+    value: string | number | boolean | object | null | undefined;
+};
+interface SharedFieldSettings<TSubFieldSettings> {
+    defaultValue?: unknown;
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: FieldOption[];
+    summary?: string;
+    summaryField?: string;
+    summaryExpression?: string;
+    subFields?: SoftFieldDefinition[];
+    subFieldSettings?: TSubFieldSettings;
+    customFieldType?: string;
+    customFieldReturnType?: CustomFieldReturnType;
+}
+interface SoftFieldSettingsEntry extends SharedFieldSettings<SoftFieldSettings> {
+}
+type SoftFieldSettings = Record<string, SoftFieldSettingsEntry>;
+interface FieldSettingsEntry extends SharedFieldSettings<FieldSettings> {
+    label: string;
+}
+type FieldSettings = Record<string, FieldSettingsEntry>;
+type CustomFieldSettingsOverrideProps = {
+    fieldName: string;
+    fieldType: string;
+    fieldSettings?: SoftFieldSettingsEntry;
+    originalFieldSettings: Fields;
+};
+type CustomFieldDefinition = {
+    field: Field;
+    returnType: CustomFieldReturnType;
+    subFields?: SoftFieldDefinition[];
+    subFieldSettings?: SoftFieldSettings;
+    fieldSettingsOverride?: (props: CustomFieldSettingsOverrideProps) => Fields;
+};
+type CustomFields = Record<string, CustomFieldDefinition>;
+
+type MapEntry = {
+    mode?: "simple" | "cva";
+    from?: string | string[];
+    to?: string | string[];
+    cva?: {
+        base?: string;
+        variants?: Array<{
+            fieldId?: string;
+            classes?: Record<string, string>;
+        }>;
+    };
+    transform?: (values: unknown[], props: Record<string, unknown>) => unknown;
+    unmappedArrayItemDefaultValues?: Record<string, unknown>;
+    /** @deprecated in favour of unmappedArrayItemDefaultValues – kept for back-compat */
+    defaultOverrides?: Record<string, unknown>;
+};
+type ApplyMappingResult = {
+    newProps: Record<string, unknown>;
+    mappedArrayPaths: Set<string>;
+    changed: boolean;
+};
+type ApplyMappingOptions = {
+    sourceProps?: Record<string, unknown>;
+    arrayDefaults?: Record<string, unknown[]>;
+};
+type MappingOption = {
+    label: string;
+    value: string;
+    type: Field["type"] | "reference";
+};
+
 type BuilderRootConfig = {
     _name: string;
     _category?: string;
     _version?: string;
     _versions?: string[];
-    _fields?: {
-        name: string;
-        type: Field["type"];
-    }[];
-    _fieldSettings?: {
-        [key: string]: any;
-    };
-    [key: string]: any;
+    _fields?: SoftFieldDefinition[];
+    _fieldSettings?: SoftFieldSettings;
+    [key: string]: unknown;
 };
 type BuilderComponentConfig = {
     _slot?: {
         slot: string;
     }[];
-    _map?: {
-        to: string | string[];
-        from: string | string[];
-        transform?: (inputs: any[], props: DefaultComponentProps) => any;
-        [key: string]: any;
-    }[];
-    [key: string]: any;
+    _map?: MapEntry[];
+    [key: string]: unknown;
 };
 type BuilderConfig = Config<any, BuilderRootConfig>;
 
@@ -50,9 +118,9 @@ type SoftComponent = {
     name: string;
     category?: string;
     fields: Fields;
-    fieldSettings?: Record<string, any>;
+    fieldSettings?: SoftFieldSettings;
     defaultProps: DefaultComponentProps;
-    rootProps?: Record<string, any>;
+    rootProps?: Record<string, unknown>;
     components: SoftSubComponent;
     slots: {
         [slot: string]: DefaultComponentProps;
@@ -65,9 +133,9 @@ type VersionedSoftComponent = {
     versions: {
         [version: string]: {
             fields: Fields;
-            fieldSettings?: Record<string, any>;
+            fieldSettings?: SoftFieldSettings;
             defaultProps: DefaultComponentProps;
-            rootProps?: Record<string, any>;
+            rootProps?: Record<string, unknown>;
             components: SoftSubComponent;
             slots: {
                 [slot: string]: DefaultComponentProps;
@@ -232,9 +300,7 @@ type ActionEventPayload = {
 };
 type OnActionsCallback = (event: ActionEventPayload) => void | Promise<void>;
 
-type RenderFunc<Props extends {
-    [key: string]: any;
-} = {
+type RenderFunc<Props extends Record<string, unknown> = {
     children: ReactNode;
 }> = (props: Props) => ReactElement;
 type Overrides = {
@@ -243,20 +309,12 @@ type Overrides = {
         state: "building" | "remodeling" | "ready" | "inspecting";
     }) => string;
     componentKeyToName?: (key: string) => string;
-    onRemodel?: (key: string) => Record<string, any>;
+    onRemodel?: (key: string) => Record<string, unknown>;
     additionalRootFields?: Record<string, Field>;
     map?: RenderFunc<{
         rootProps: BuilderRootConfig;
-        toOptions: {
-            label: string;
-            value: string;
-            type: Field["type"] | "reference";
-        }[];
-        fromOptions: {
-            label: string;
-            value: string;
-            type: Field["type"] | "reference";
-        }[];
+        toOptions: MappingOption[];
+        fromOptions: MappingOption[];
         props: DefaultComponentProps;
         value: BuilderComponentConfig["_map"];
         onChange: (value: BuilderComponentConfig["_map"]) => void;
@@ -267,7 +325,7 @@ type Overrides = {
         version: string;
         subComponentPath: string[];
         softComponent: VersionedSoftComponent["versions"][string];
-    }) => ((inputs: any[], props: DefaultComponentProps) => any) | undefined;
+    }) => ((inputs: unknown[], props: Record<string, unknown>) => unknown) | undefined;
     onActions?: OnActionsCallback;
     name?: Field<string>;
     categories?: Field<string | undefined>;
@@ -284,6 +342,7 @@ type Overrides = {
         props: RootData<AsFieldProps<WithChildren<BuilderRootConfig>>> | Promise<RootData<AsFieldProps<WithChildren<BuilderRootConfig>>>>;
         readOnly: Readonly<Record<string, boolean>> | undefined;
     };
+    mapComponentConfig?: (componentName: string, defaultConfig: ComponentConfig) => Partial<ComponentConfig>;
 };
 
 type Status = "building" | "remodeling" | "ready" | "inspecting";
@@ -295,6 +354,7 @@ type AppStore = {
     originalHistory: History[];
     storedConfig?: Config;
     overrides: Overrides;
+    customFields: CustomFields;
     onActions?: OnActionsCallback;
     itemSelector: {
         index: number;
@@ -368,7 +428,7 @@ type AppStore = {
     setShowVersionFields: (show: boolean) => void;
 };
 type AppStoreApi = StoreApi<AppStore>;
-declare const createSoftConfigStore: (hardConfig?: Config, softComponents?: SoftComponents, overrides?: Overrides, onActions?: OnActionsCallback, showVersionFields?: boolean) => zustand.UseBoundStore<Omit<StoreApi<AppStore>, "subscribe"> & {
+declare const createSoftConfigStore: (hardConfig?: Config, softComponents?: SoftComponents, overrides?: Overrides, onActions?: OnActionsCallback, showVersionFields?: boolean, customFields?: CustomFields) => zustand.UseBoundStore<Omit<StoreApi<AppStore>, "subscribe"> & {
     subscribe: {
         (listener: (selectedState: AppStore, previousSelectedState: AppStore) => void): () => void;
         <U>(selector: (state: AppStore) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
@@ -378,10 +438,11 @@ declare const createSoftConfigStore: (hardConfig?: Config, softComponents?: Soft
     };
 }>;
 
-declare const SoftConfigProvider: ({ children, hardConfig, softComponents, overrides, value, onActions, useVersioning, }: {
+declare const SoftConfigProvider: ({ children, hardConfig, softComponents, customFields, overrides, value, onActions, useVersioning, }: {
     children: (softConfig: Config, softComponents: SoftComponents, iframeDoc: AppStore["setIframeDoc"], validateAction: (action: PuckAction) => boolean) => ReactNode;
     hardConfig: Config;
     softComponents: SoftComponents;
+    customFields?: CustomFields;
     overrides?: Overrides;
     value?: StoreApi<AppStore>;
     onActions?: OnActionsCallback;
@@ -402,9 +463,9 @@ declare const useRemodel: () => {
         version: string;
         softComponent: {
             fields: _measured_puck.Fields;
-            fieldSettings?: Record<string, any>;
+            fieldSettings?: SoftFieldSettings;
             defaultProps: DefaultComponentProps;
-            rootProps?: Record<string, any>;
+            rootProps?: Record<string, unknown>;
             components: SoftSubComponent;
             slots: {
                 [slot: string]: DefaultComponentProps;
@@ -462,11 +523,13 @@ declare const ActionBarOverride: (props: {
 
 declare const DrawerItem: (props: {
     name: string;
+    label?: string;
     children: React.ReactNode;
 }) => React.ReactElement;
 /** @deprecated Use DrawerItem instead */
 declare const ComponentItem: (props: {
     name: string;
+    label?: string;
     children: React.ReactNode;
 }) => React.ReactElement;
 
@@ -541,4 +604,45 @@ declare const Modal: ({ children, onClose, isOpen, }: {
     isOpen: boolean;
 }) => react_jsx_runtime.JSX.Element;
 
-export { ActionBarOverride as ActionBar, type ActionEventPayload, type AppStore, type AppStoreApi, type BuilderComponentConfig, type BuilderConfig, type BuilderRootConfig, ComponentItem, Drawer as ComponentList, Drawer, DrawerItem, Header, Modal, type OnActionsCallback, type Overrides, type SoftComponent, type SoftComponents, SoftConfigProvider, type VersionedSoftComponent, confirm, createActionCallback, createSoftConfigStore, createUseSoftConfig, notify, resolveSoftConfig, setConfirmHandler, setNotificationHandler, useBuild, useCancel, useComplete, useDecompose, useDemolish, useInspect, useRemodel, useSetDefaultVersion, useSoftConfig };
+/**
+ * Filters toOptions based on the selected fromPath.
+ * - If fromPath contains an array segment, only return array-path to-options.
+ * - If fromPath is a bare array, only return bare array to-options.
+ * - Otherwise, hide array-path to-options (prevent array-to-scalar mismatches).
+ */
+declare function filterToOptionsForFrom(fromPath: string | undefined, toOptions: MappingOption[]): MappingOption[];
+
+/**
+ * Shared helper: evaluates `_map` entries and applies mapped values to component props.
+ *
+ * Used by both the live builder effect (root-config.tsx) and the runtime
+ * resolver (resolve-soft-component-data.ts) so the logic stays in one place.
+ *
+ * Array construction order (for array targets like `items[].imageUrl`):
+ *   1. Start from `unmappedArrayItemDefaultValues` on the map entry (initially populated
+ *      from the component's `defaultItemProps`). These are the single source of
+ *      truth for the item "template".
+ *   2. Overlay the mapped value for each array index.
+ *   The result is a freshly-constructed array whose length equals the mapped
+ *   source array and whose unmapped props come from the defaults above.
+ */
+
+declare const resolveValueByPath: (source: any, path: string) => any;
+/**
+ * Evaluate every `_map` entry and apply the results to `props`.
+ *
+ * @param props         The component props to mutate (caller should pass a shallow copy).
+ * @param fieldSettings Root-level `_fieldSettings` for resolving `from` paths.
+ * @param map           The `_map` array from the component.
+ * @param resolveInput  Strategy for resolving `from` values. Two modes:
+ * - `"fieldSettings"` (builder): read from `fieldSettings` only.
+ * - `"propsFirst"` (runtime): prefer live prop values, fall back
+ * to fieldSettings `defaultValue`.
+ */
+declare function applyMapping(props: Record<string, any>, fieldSettings: Record<string, any>, map: MapEntry[], resolveInput?: "fieldSettings" | "propsFirst", options?: ApplyMappingOptions): ApplyMappingResult;
+
+declare const isArrayMappingPath: (path: string) => boolean;
+declare const getArrayBasePath: (arrayPath: string) => string | null;
+declare const getArrayItemSubPath: (arrayPath: string) => string | null;
+
+export { ActionBarOverride as ActionBar, type ActionEventPayload, type AppStore, type AppStoreApi, type ApplyMappingOptions, type ApplyMappingResult, type BuilderComponentConfig, type BuilderConfig, type BuilderRootConfig, ComponentItem, Drawer as ComponentList, type CustomFieldDefinition, type CustomFieldReturnType, type CustomFields, Drawer, DrawerItem, type FieldSettings, Header, type MapEntry, Modal, type OnActionsCallback, type Overrides, type SoftComponent, type SoftComponents, SoftConfigProvider, type SoftFieldDefinition, type SoftFieldSettings, type VersionedSoftComponent, applyMapping, confirm, createActionCallback, createSoftConfigStore, createUseSoftConfig, filterToOptionsForFrom, getArrayBasePath, getArrayItemSubPath, isArrayMappingPath, notify, resolveSoftConfig, resolveValueByPath, setConfirmHandler, setNotificationHandler, useBuild, useCancel, useComplete, useDecompose, useDemolish, useInspect, useRemodel, useSetDefaultVersion, useSoftConfig };