@netlisian/softconfig 0.1.8 → 0.1.10

package/dist/puck/index.d.mts

@@ -1,7 +1,7 @@
+import * as _measured_puck from '@measured/puck';
+import { Field, Fields, Config, DefaultComponentProps, History, AppState, PuckApi, ComponentData, ComponentConfig, RootData, AsFieldProps, WithChildren, Metadata, ResolveDataTrigger, PuckAction, OnAction, Data, Overrides as Overrides$1 } from '@measured/puck';
 import * as zustand from 'zustand';
 import { StoreApi } from 'zustand';
-import * as _measured_puck from '@measured/puck';
-import { Field, Fields, Config, DefaultComponentProps, History, AppState, PuckApi, ComponentData, ComponentConfig, RootData, AsFieldProps, WithChildren, Metadata, ResolveDataTrigger, PuckAction, Data, Overrides as Overrides$1 } 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';
@@ -153,89 +153,177 @@ type VersionedSoftComponent = {
 type SoftComponents = Record<string, VersionedSoftComponent>;
 
 type CompletedComponentResult = {
+    /**
+     * The generated unique registry key/identifier of the completed soft component.
+     */
     id: string;
+    /**
+     * The resolved semantic version string of the completed soft component version.
+     */
     version: string;
+    /**
+     * The compiled underlying JSON definition representing the soft component structure.
+     */
     softComponent: VersionedSoftComponent["versions"][string];
 };
 type BuildersSlice = {
     /**
-     * Build a new soft component based on the selected item in history.
+     * Initializes the "build" mode to package standard component tree elements into a
+     * brand-new, unified, and reusable soft component.
+     *
+     * @param history - The current Puck workspace history timeline stack. Used to store
+     *                  the undo/redo states so they can be restored if the session is canceled.
+     * @param selectedItem - The component instance selected in the workspace that will
+     *                       serve as the seed/root of the building sandbox.
+     * @param itemSelector - Placement and index metadata of the selected item in the editor.
+     * @param puckDispatch - The Puck API dispatch function to apply state modifications.
+     * @param name - Optional initial user-facing label/display name for the new soft component.
      *
-     * Steps:
-     * 1. Data Modifications:
-     *    - Store History
-     *    - Set currently selected item to the root
-     * 2. Soft Config Modifications:
-     *    - Update root to include: name, fields, fieldSettings, for soft component
-     *    - Update each component config to map the soft fields to component fields
-     *    - Update each component for slot settings (Dropzone enable/disable)
+     * @throws {Error} If no item is selected or the item selector is null.
+     *
+     * Lifecycle & Side Effects:
+     * 1. Clones and caches the current core soft configuration and history to the store.
+     * 2. Scans the workspace sub-tree to collect all descendent element IDs.
+     * 3. Schedules edit visibility highlights to visual-lock edits within the builder boundaries.
+     * 4. Transitions the builder workflow state to "building".
      */
     build: (history: History<AppState>[], selectedItem: PuckApi["selectedItem"], itemSelector: {
         index: number;
         zone?: string;
     } | null, puckDispatch: PuckApi["dispatch"], name?: string) => void | null;
     /**
-     * Remodel the selected soft component by decomposing it and resetting as root.
+     * Enters "remodel" mode for an existing soft component, decomposing its compiled structure back
+     * into constituent discrete components inside the builder workspace.
+     *
+     * @param history - The current Puck history list to cache for later restoration.
+     * @param selectedItem - The compiled soft component instance selected in the editor.
+     * @param itemSelector - Workspace index and droppable zone metadata of the selected component.
+     * @param puckDispatch - The Puck API dispatch function.
+     * @param refreshPermission - Callback function to refresh access permissions (currently unused).
      *
-     * Steps:
-     * 1. Data Modifications:
-     *    - Store History
-     *    - Decompose and set selected soft component to root
-     * 2. Soft Config Modifications:
-     *    - Update root with name, fields, fieldSettings for soft component
-     *    - Update each component config to map soft fields to component fields
-     *    - Update each component for slot settings (Dropzone enable/disable)
-     *    - Remove selected component or dependencies to avoid circular dependencies
+     * @throws {Error} If the selection parameters are missing, or if the target soft component
+     *                 definition cannot be resolved from the cache.
+     *
+     * Lifecycle & Side Effects:
+     * 1. Fetches the soft component version schema from the Zustand store.
+     * 2. Evaluates the reverse dependency graph to identify components depending on this soft component.
+     *    This locks editing on dependent elements to avoid creating circular dependencies.
+     * 3. Explodes the soft component into its constituent raw components in-place within the document data.
+     * 4. Updates visual iframe overlays to confine editing to the decomposed sub-tree.
+     * 5. Transitions the builder workspace state to "remodeling".
      */
     remodel: (history: History<AppState>[], selectedItem: PuckApi["selectedItem"], itemSelector: {
         index: number;
         zone?: string;
-    } | null, puckDispatch: PuckApi["dispatch"], refreshPermission: () => void) => void;
+    } | null, puckDispatch: PuckApi["dispatch"], refreshPermissions: () => void) => void;
     /**
-     * Switch to a different version of the soft component being remodeled.
+     * Switches the active soft component inside the remodeling session to a different
+     * registered semantic version.
+     *
+     * @param componentName - The unique registry key of the soft component.
+     * @param newVersion - The target version to activate.
+     * @param currentProps - The current top-level properties configured for this element instance.
+     * @param puckDispatch - The Puck API dispatch function.
+     *
+     * @throws {Error} If the store is not currently in the 'remodeling' state, or if the
+     *                 requested version is missing.
      *
-     * Steps:
-     * 1. Get the soft component for the selected version
-     * 2. Convert it back to AppState format
-     * 3. Update the puck data with the new version's content
+     * Lifecycle & Side Effects:
+     * 1. Resolves the target version's raw layout structure from the store.
+     * 2. Re-runs soft component-to-AppState conversions for the target version.
+     * 3. Replaces the active remodeling workspace content in-place with the selected version's elements.
      */
-    setVersion: (componentName: string, newVersion: string, currentProps: Record<string, any>, puckDispatch: PuckApi["dispatch"]) => void;
+    setVersion: (componentName: string, newVersion: string, currentProps: Record<string, any>, puckDispatch: PuckApi["dispatch"], getItemBySelector: PuckApi["getItemBySelector"], getSelectorForId: PuckApi["getSelectorForId"]) => void;
     /**
-     * Mark the current build/remodel as complete.
+     * Finalizes the current build or remodel session, packaging all active workspace components
+     * into a compiled, versioned, reusable soft component configuration.
      *
-     * Steps:
-     * 1. Config Modifications:
-     *    - Compose the build settings into soft component
-     *    - Set the component to the config
-     *    - Restore permissions, resolve fields and resolve data of all components
-     * 2. Data Modifications:
-     *    - Transform the last item of history to replace the source components into composed soft component
-     *    - Strip the build settings fields
-     *    - Apply modified history to puck data.
+     * @param appState - The current state of the builder editor workspace containing the composed elements.
+     * @param setHistories - Puck API callback to restore the original builder history timeline.
+     * @param getItemBySelector - Puck API utility to resolve a workspace item using its selector.
+     * @returns An object containing the generated component ID, version, and compiled soft component structure.
+     *
+     * @throws {Error} If the store is not in building/remodeling state, the root component is unnamed,
+     *                 or if the selected item cannot be resolved in the workspace.
+     *
+     * Lifecycle & Side Effects:
+     * 1. Converts display labels into safe, unique PascalCase configuration registration keys.
+     * 2. Packages workspace child items into a JSON-serializable versioned schema.
+     * 3. Re-registers the component with the core configuration components registry.
+     * 4. Categorizes the component within layout groups.
+     * 5. Restores original history timelines and transitions store state to "inspecting".
+     * 6. Rebuilds all other registered soft components that depend on this updated component.
      */
     complete: (appState: AppState<any>, setHistories: PuckApi["history"]["setHistories"], getItemBySelector: PuckApi["getItemBySelector"]) => CompletedComponentResult;
+    /**
+     * Permanently deletes a soft component registration and purges all of its active
+     * occurrences/instances from the active workspace document data.
+     *
+     * @param componentName - The unique registry name of the soft component to delete.
+     * @param data - The active workspace document data to scan and clean.
+     * @param puckDispatch - The Puck API dispatch function to apply document cleanups.
+     *
+     * @throws {Error} If the store is not currently in the stable 'ready' state.
+     */
     demolish: (componentName: string, data: AppState["data"], puckDispatch: PuckApi["dispatch"]) => void;
-    inspect: (componentName: string, puckDispatch: PuckApi["dispatch"]) => void;
     /**
-     * Mark the current build/remodel as complete.
+     * Concludes the inspection workflow, replacing the temporary seed item within the
+     * editor workspace document with the newly compiled soft component instance.
+     *
+     * @param componentName - The final compiled component registry name.
+     * @param puckDispatch - The Puck API dispatch function.
+     *
+     * @throws {Error} If the store is not currently in the 'inspecting' state.
+     *
+     * Lifecycle & Side Effects:
+     * 1. Walk the workspace tree to locate the temporary component being built/remodeled.
+     * 2. Replace it with the compiled component type and default versioned props.
+     * 3. Flushes layout restriction overlays on the iframe.
+     * 4. Resets active builder metadata and transitions state back to "ready".
+     */
+    inspect: (componentName: string, puckDispatch: PuckApi["dispatch"], selectedItemSelector: {
+        index: number;
+        zone?: string;
+    } | null) => void;
+    /**
+     * Discards all modifications made during the current build or remodel session,
+     * reverting the editor config, workspace elements, and histories back to their original state.
+     *
+     * @param setHistories - Puck API callback to restore the original history list.
      *
-     * Steps:
-     * 1. Config Modifications:
-     *    - Restore permissions, resolve fields and resolve data of all components
-     * 2. Data Modifications:
-     *    - Restore history to puck data.
+     * Lifecycle & Side Effects:
+     * 1. Transitions store state to "cancelling" to suppress conflicting updates.
+     * 2. Re-applies the original workspace config and timeline histories.
+     * 3. Clears visual iframe constraints and resets active builder metadata back to normal.
      */
-    cancel: (setHistories: PuckApi["history"]["setHistories"]) => void;
-    /** Compose multiple components into a soft component.
-     * 1. SoftComponent: Get soft fields + default values from the appState.root + sub-component maps + fixedProps
+    cancel: (setHistories: PuckApi["history"]["setHistories"], puckDispatch: PuckApi["dispatch"], selectedItemSelector: {
+        index: number;
+        zone?: string;
+    } | null) => void;
+    /**
+     * Internal compiler hook that converts builder editor workspace states (root props, children)
+     * into a unified `SoftComponent` schema and creates a versioned config.
+     *
+     * @param appState - The current builder editor state.
+     * @param componentName - The unique registry key for the soft component.
+     * @param editedItem - The original seed component that initiated the build session.
+     * @param displayName - The user-facing display name of the soft component.
+     * @param category - Optional layout category placement inside the component toolbox.
+     * @returns A tuple containing the `ComponentConfig` and its resolved version string, or undefined if failed.
+     *
+     * @throws {Error} If the component name is empty or collides with existing configs during a new build.
      */
     compose: (appState: AppState, componentName: string, editedItem: ComponentData, displayName: string, category?: string) => [ComponentConfig, string] | undefined;
-    /** Break down a composed component into its parts.
-     * 1. Get softComponentProps
-     * 2. Create a virtual component with all the props from soft-component.
-     * 3. Replace the softComponent with hardComponent
+    /**
+     * Utility to break down a composed soft component's props and children back into
+     * their discrete, uncompiled constituent elements.
+     *
+     * @param componentData - The compiled component data instance.
+     * @returns An array of unpacked standard child component data objects.
+     *
+     * @throws {Error} If the input component data lacks type or ID.
      */
-    decompose: (componentData: ComponentData) => ComponentData[];
+    decompose: (componentData: ComponentData, keepMapField?: boolean) => ComponentData[];
 };
 
 type ActionEventPayload = {
@@ -306,7 +394,7 @@ type RenderFunc<Props extends Record<string, unknown> = {
 type Overrides = {
     componentLabelToName?: (label: string, context: Partial<BuilderRootConfig> & {
         existingKeys: string[];
-        state: "building" | "remodeling" | "ready" | "inspecting";
+        state: Status;
     }) => string;
     componentNameToLabel?: (name: string) => string;
     onRemodel?: (name: string) => Record<string, unknown>;
@@ -339,14 +427,17 @@ type Overrides = {
     }, context: {
         editingComponent?: string;
     }) => {
-        props: RootData<AsFieldProps<WithChildren<BuilderRootConfig>>> | Promise<RootData<AsFieldProps<WithChildren<BuilderRootConfig>>>>;
-        readOnly: Readonly<Record<string, boolean>> | undefined;
-    };
+        props?: Partial<AsFieldProps<WithChildren<BuilderRootConfig>>>;
+        readOnly?: Readonly<Record<string, boolean>>;
+    } | Promise<{
+        props?: Partial<AsFieldProps<WithChildren<BuilderRootConfig>>>;
+        readOnly?: Readonly<Record<string, boolean>>;
+    }>;
     mapComponentConfig?: (componentName: string, defaultConfig: ComponentConfig, rootProps: BuilderRootConfig & RootData) => ComponentConfig;
 };
 
 /** Represents the current editing mode of the Puck editor. */
-type Status = "building" | "remodeling" | "ready" | "inspecting";
+type Status = "building" | "remodeling" | "ready" | "cancelling" | "assessing" | "inspecting";
 type AppStore = {
     /** The current merged Puck config (hard + soft components). Rebuilt on soft component changes. */
     softConfig: Config;
@@ -500,9 +591,21 @@ type AppStore = {
      * Always returns true when `state === "ready"` (no restrictions apply).
      */
     validateAction: (action: PuckAction, previousAction?: PuckAction) => boolean;
+    /** Names of the content areas where soft components can be built. */
+    contentAreaNames?: string[];
+    /** Setter for the content area names */
+    setContentAreaNames: (names?: string[]) => void;
+    /** Access to the puck dispatch function, stored during edits. */
+    puckDispatch?: ((action: PuckAction) => void) | null;
+    /** Setter for the puck dispatch function */
+    setPuckDispatch: (dispatch: ((action: PuckAction) => void) | null) => void;
+    /**
+     * Optional root action handler injected via the store creation.
+     */
+    rootActionHandler?: OnAction;
 };
 type AppStoreApi = StoreApi<AppStore>;
-declare const createSoftConfigStore: (hardConfig?: Config, softComponents?: SoftComponents, overrides?: Overrides, onActions?: OnActionsCallback, showVersionFields?: boolean, customFields?: CustomFields) => zustand.UseBoundStore<Omit<StoreApi<AppStore>, "subscribe"> & {
+declare const createSoftConfigStore: (hardConfig?: Config, softComponents?: SoftComponents, overrides?: Overrides, onActions?: OnActionsCallback, showVersionFields?: boolean, customFields?: CustomFields, contentAreaNames?: string[]) => 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?: {
@@ -528,8 +631,9 @@ declare const createSoftConfigStore: (hardConfig?: Config, softComponents?: Soft
  * @param props.value - Optional external store API.
  * @param props.onActions - Callback triggered on Puck actions.
  * @param props.useVersioning - Flag to enable or disable versioning (defaults to false).
+ * @param props.contentAreaNames - Optional list of data paths mapping where soft components can be built or remodeled.
  */
-declare const SoftConfigProvider: ({ children, hardConfig, softComponents, customFields, overrides, value, onActions, useVersioning, }: {
+declare const SoftConfigProvider: ({ children, hardConfig, softComponents, customFields, overrides, value, onActions, useVersioning, contentAreaNames, }: {
     children: (softConfig: Config) => ReactNode;
     hardConfig: Config;
     softComponents?: SoftComponents;
@@ -538,6 +642,7 @@ declare const SoftConfigProvider: ({ children, hardConfig, softComponents, custo
     value?: StoreApi<AppStore>;
     onActions?: OnActionsCallback;
     useVersioning?: boolean;
+    contentAreaNames?: string[];
 }) => react_jsx_runtime.JSX.Element;
 
 declare const createUseSoftConfig: () => <T>(selector: (state: AppStore) => T, equalityFn?: (a: T, b: T) => boolean) => T;
@@ -625,12 +730,6 @@ declare const DrawerItem: (props: {
     label?: string;
     children: React.ReactNode;
 }) => React.ReactElement;
-/** @deprecated Use DrawerItem instead */
-declare const ComponentItem: (props: {
-    name: string;
-    label?: string;
-    children: React.ReactNode;
-}) => React.ReactElement;
 
 /**
  * Drawer — custom drawer override for the Puck editor.
@@ -713,22 +812,7 @@ declare const Modal: ({ children, onClose, isOpen, }: {
  */
 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;
+declare const resolveValueByPath: (source: unknown, path: string) => unknown;
 /**
  * Evaluate every `_map` entry and apply the results to `props`.
  *
@@ -740,10 +824,25 @@ declare const resolveValueByPath: (source: any, path: string) => any;
  * - `"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 function applyMapping(props: DefaultComponentProps, fieldSettings: DefaultComponentProps, 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, HeaderActions, 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, useSoftConfigStore };
+type ZoneType = "root" | "dropzone" | "slot";
+type PuckNodeData = {
+    data: ComponentData;
+    flatData: ComponentData;
+    parentId: string | null;
+    zone: string;
+    path: string[];
+};
+type PuckZoneData = {
+    contentIds: string[];
+    type: ZoneType;
+};
+type NodeIndex = Record<string, PuckNodeData>;
+type ZoneIndex = Record<string, PuckZoneData>;
+
+export { ActionBarOverride as ActionBar, type ActionEventPayload, type AppStore, type AppStoreApi, type ApplyMappingOptions, type ApplyMappingResult, type BuilderComponentConfig, type BuilderConfig, type BuilderRootConfig, Drawer as ComponentList, type CustomFieldDefinition, type CustomFieldReturnType, type CustomFields, Drawer, DrawerItem, type FieldSettings, Header, HeaderActions, type MapEntry, Modal, type NodeIndex, type OnActionsCallback, type Overrides, type PuckNodeData, type PuckZoneData, type SoftComponent, type SoftComponents, SoftConfigProvider, type SoftFieldDefinition, type SoftFieldSettings, type Status, type VersionedSoftComponent, type ZoneIndex, type ZoneType, applyMapping, confirm, createActionCallback, createSoftConfigStore, createUseSoftConfig, filterToOptionsForFrom, getArrayBasePath, getArrayItemSubPath, isArrayMappingPath, notify, resolveSoftConfig, resolveValueByPath, setConfirmHandler, setNotificationHandler, useBuild, useCancel, useComplete, useDecompose, useDemolish, useInspect, useRemodel, useSetDefaultVersion, useSoftConfig, useSoftConfigStore };