@netlisian/softconfig 0.1.4 → 0.1.6

package/dist/puck/index.d.ts

@@ -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 };