@netlisian/softconfig 0.1.5 → 0.1.7

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/puck/index.css

@@ -1,4 +1,4 @@
-/* css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/components/error-boundary/styles.module.css/#css-module-data */
+/* css-module:/home/osamu/Documents/netlisian-soft/packages/soft-config/src/puck/components/error-boundary/styles.module.css/#css-module-data */
 ._ErrorBoundary_1xl05_5 {
   padding: 20px;
   border: 1px solid #ff5858;
@@ -26,7 +26,7 @@
   background-color: #b71c1c;
 }
 
-/* css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/overrides/Header.module.css/#css-module-data */
+/* css-module:/home/osamu/Documents/netlisian-soft/packages/soft-config/src/puck/overrides/Header.module.css/#css-module-data */
 ._Header_19oj9_1 {
   display: flex;
   justify-content: space-between;
@@ -35,7 +35,7 @@
   flex-wrap: wrap;
 }
 
-/* css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/overrides/ActionBar.module.css/#css-module-data */
+/* css-module:/home/osamu/Documents/netlisian-soft/packages/soft-config/src/puck/overrides/ActionBar.module.css/#css-module-data */
 ._ActionBar_pvuie_5 {
   align-items: center;
   cursor: default;
@@ -119,7 +119,7 @@
   margin: 0;
 }
 
-/* css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/overrides/DrawerItem.module.css/#css-module-data */
+/* css-module:/home/osamu/Documents/netlisian-soft/packages/soft-config/src/puck/overrides/DrawerItem.module.css/#css-module-data */
 ._DrawerItem_182aj_1 {
   background: var(--puck-color-white);
   cursor: grab;
@@ -343,7 +343,7 @@
   gap: 12px;
 }
 
-/* css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/components/modal/styles.module.css/#css-module-data */
+/* css-module:/home/osamu/Documents/netlisian-soft/packages/soft-config/src/puck/components/modal/styles.module.css/#css-module-data */
 ._Modal_1t9ot_1 {
   background: color-mix(in srgb, var(--puck-color-black) 75%, transparent);
   display: none;
@@ -372,7 +372,7 @@
   min-height: 0;
 }
 
-/* css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/overrides/Drawer.module.css/#css-module-data */
+/* css-module:/home/osamu/Documents/netlisian-soft/packages/soft-config/src/puck/overrides/Drawer.module.css/#css-module-data */
 ._Drawer_12zq5_1 {
   display: flex;
   flex-direction: column;

package/dist/puck/index.d.mts

@@ -1,7 +1,7 @@
 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 } 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';
@@ -304,12 +304,12 @@ type RenderFunc<Props extends Record<string, unknown> = {
     children: ReactNode;
 }> = (props: Props) => ReactElement;
 type Overrides = {
-    componentNameToKey?: (displayName: string, context: Partial<BuilderRootConfig> & {
+    componentLabelToName?: (label: string, context: Partial<BuilderRootConfig> & {
         existingKeys: string[];
         state: "building" | "remodeling" | "ready" | "inspecting";
     }) => string;
-    componentKeyToName?: (key: string) => string;
-    onRemodel?: (key: string) => Record<string, unknown>;
+    componentNameToLabel?: (name: string) => string;
+    onRemodel?: (name: string) => Record<string, unknown>;
     additionalRootFields?: Record<string, Field>;
     map?: RenderFunc<{
         rootProps: BuilderRootConfig;
@@ -342,89 +342,164 @@ type Overrides = {
         props: RootData<AsFieldProps<WithChildren<BuilderRootConfig>>> | Promise<RootData<AsFieldProps<WithChildren<BuilderRootConfig>>>>;
         readOnly: Readonly<Record<string, boolean>> | undefined;
     };
+    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 AppStore = {
+    /** The current merged Puck config (hard + soft components). Rebuilt on soft component changes. */
     softConfig: Config;
+    /** Flat map of all registered soft components, keyed by component name. */
     softComponents: SoftComponents;
+    /**
+     * Soft components after `hydrateMapTransform` has been applied.
+     * Only populated when `overrides.hydrateMapTransform` is provided.
+     */
     hydratedSoftComponents?: SoftComponents;
+    /** The current editing mode. Controls which components can be mutated. */
     state: Status;
+    /** Snapshot of Puck history entries saved before an editing session starts. */
     originalHistory: History[];
+    /** A stored copy of the Puck config, used for rollback scenarios. */
     storedConfig?: Config;
+    /** Lifecycle and rendering overrides forwarded from the SoftConfigProvider. */
     overrides: Overrides;
+    /** Custom field definitions to extend the built-in Puck field types. */
     customFields: CustomFields;
+    /**
+     * Callback fired on every Puck action dispatch.
+     * Gives consumers a hook to react to drag-and-drop, insert, remove, etc.
+     */
     onActions?: OnActionsCallback;
+    /** The currently selected component in the Puck canvas, or null if none. */
     itemSelector: {
         index: number;
         zone: string;
     } | null;
+    /** Update or clear the active item selection. */
     setItemSelector: (selector: {
         index: number;
         zone: string;
     } | null) => void;
+    /** Snapshot of the selected component's props before any edits began. Used for cancel/rollback. */
     originalItem: DefaultComponentProps | null;
+    /** Persist the pre-edit props snapshot for the active item. */
     setOriginalItem: (item: DefaultComponentProps | null) => void;
+    /** Persist the full Puck history stack (called when entering an editing session). */
     storeHistory: (history: History[]) => void;
+    /** Clear the stored history (called when an editing session completes or cancels). */
     removeHistory: () => void;
+    /**
+     * Register or update a single soft component's Puck config.
+     * Optionally assigns the component to a Puck category.
+     */
     setSoftComponentConfig: (key: string, config: ComponentConfig, category?: string) => void;
+    /** Remove a soft component's Puck config entry by key. */
     removeSoftComponentConfig: (key: string) => void;
+    /**
+     * Delete a specific version of a soft component.
+     * If the deleted version was the default, promotes the most recent remaining version.
+     */
     removeSoftComponentVersion: (key: string, version: string) => void;
+    /** Register or update a Puck category (visibility, expansion, membership). */
     setSoftCategoryConfig: (key: string, category: {
         components?: string[];
         visible?: boolean;
         defaultExpanded?: boolean;
         title?: string;
     }) => void;
+    /** Remove a Puck category entry by key. */
     removeSoftCategoryConfig: (key: string) => void;
+    /** Builder sub-slice — handles multi-step build/remodel workflows. */
     builder: BuildersSlice;
+    /**
+     * Upsert a single version of a soft component.
+     * Creates the component entry if it doesn't already exist.
+     */
     setSoftComponent: (key: string, version: string, component: SoftComponent) => void;
+    /**
+     * Batch-upsert multiple soft components at once.
+     * Merges incoming versions with any existing versions for each component.
+     */
     setSoftComponents: (components: SoftComponents) => void;
+    /**
+     * Re-apply `overrides.hydrateMapTransform` to the current soft components.
+     * Call this when the transform function or its dependencies change at runtime.
+     */
     hydrateTransforms: () => void;
+    /**
+     * Promote a specific version of a soft component to be the active/default version.
+     * Rebuilds the Puck config entry for that component.
+     */
     setSoftComponentDefaultVersion: (key: string, version: string) => void;
+    /** Completely remove a soft component and all its versions from the store. */
     removeSoftComponent: (key: string) => void;
+    /** Name of the component type currently being edited (e.g. "Hero"), or null. */
     editingComponent: string | null;
+    /** Instance ID of the component currently being edited in the Puck canvas, or null. */
     editingComponentId: string | null;
+    /**
+     * Set of component instance IDs the user is allowed to mutate in the current session.
+     * Populated when entering "building" or "remodeling" state.
+     */
     editableComponentIds: Set<string>;
+    /** Overwrite the entire set of editable component IDs. */
     setEditableComponentIds: (ids: Set<string>) => void;
+    /** Append a single component instance ID to the editable set. */
     addEditableComponentId: (id: string) => void;
+    /** Reset editing state: clears editingComponentId and editableComponentIds. */
     clearEditingState: () => void;
     /**
-     * Reverse dependency graph: componentName -> Set of components that depend on it
-     * Used to efficiently rebuild dependent components when a soft component is updated
+     * Reverse dependency graph: componentName → Set of component names that depend on it.
+     * Built once on store creation and updated when components change.
+     * Used to efficiently cascade Puck config rebuilds to affected dependents.
      */
     dependencyGraph: Map<string, Set<string>>;
     /**
-     * Rebuild all dependent components after a soft component is updated
-     * Only rebuilds components that depend on the changed component
+     * Rebuild the Puck config entries for every component that depends on the given one.
+     * Should be called after a soft component's render or schema changes.
      *
-     * @param componentName - The component that was updated
-     * @param version - The version that was updated
+     * @param componentName - The component that was updated.
+     * @param version - The version that changed (for future granular diffing).
      */
     rebuildDependents: (componentName: string, version: string) => void;
     /**
-     * Iframe document reference for applying styling and edit visibility
-     * Stored as a mutable ref to avoid triggering store updates.
+     * Mutable ref holding the Puck iframe's Document.
+     * Stored as a ref object to mutate without triggering Zustand subscribers.
      */
-    iframeDocRef: {
-        current: Document | null;
-    };
+    iframeDoc: Document | null;
     /**
-     * Get the current iframe document reference
-     */
-    getIframeDoc: () => Document | null;
-    /**
-     * Set the iframe document reference without causing re-renders
+     * Point the store at a new iframe Document.
+     * Immediately applies or clears edit-visibility CSS based on the current state.
      */
     setIframeDoc: (doc: Document | null) => void;
     /**
-     * Flag to control visibility of version config fields
+     * When true, version-selection fields are shown in the Puck sidebar.
+     * Defaults to true; set to false to hide version controls from end users.
      */
     showVersionFields: boolean;
+    /** Toggle the visibility of version-selection fields in the Puck sidebar. */
+    setShowVersionFields: (show: boolean) => void;
     /**
-     * Toggle the visibility of version config fields
+     * Reference to Puck's `history.back` function, injected by the UndoSync
+     * component that lives inside the ActionBar override.
+     * Null until the Puck editor mounts and ActionBar renders.
      */
-    setShowVersionFields: (show: boolean) => void;
+    undoFn: (() => void) | null;
+    /**
+     * Called by UndoSync (inside the Puck tree) to register the live undo function.
+     * Must be called once per editor mount so `validateAction` can trigger rollbacks.
+     */
+    setUndoFn: (fn: () => void) => void;
+    /**
+     * Guard function passed to Puck's `onAction` via `createActionCallback`.
+     * Returns false for any action that targets a component outside the current
+     * editable set, which causes `createActionCallback` to immediately undo it.
+     *
+     * Always returns true when `state === "ready"` (no restrictions apply).
+     */
+    validateAction: (action: PuckAction, previousAction?: PuckAction) => boolean;
 };
 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"> & {
@@ -437,10 +512,27 @@ declare const createSoftConfigStore: (hardConfig?: Config, softComponents?: Soft
     };
 }>;
 
+/**
+ * SoftConfigProvider is responsible for providing the soft config context to the Puck editor.
+ *
+ * @param props - The component props.
+ * @param props.children - A render prop that receives the following arguments:
+ * - `softConfig`: The current soft configuration object.
+ * - `softComponents`: The current mapping of soft components.
+ * - `setIframeDoc`: Function to set the iframe document reference in the store. Used to apply edit visibility styles on the iframe.
+ * - `validateAction`: Function to validate actions based on current state and editable component IDs. Used to disallow editing components that are not in the editable list during "building" or "remodeling" states.
+ * @param props.hardConfig - Initial Puck Config.
+ * @param props.softComponents - Initial soft components.
+ * @param props.customFields - Custom field to allow additional field types.
+ * @param props.overrides - Soft Config overrides.
+ * @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).
+ */
 declare const SoftConfigProvider: ({ children, hardConfig, softComponents, customFields, overrides, value, onActions, useVersioning, }: {
-    children: (softConfig: Config, softComponents: SoftComponents, iframeDoc: AppStore["setIframeDoc"], validateAction: (action: PuckAction) => boolean) => ReactNode;
+    children: (softConfig: Config, softComponents: SoftComponents, actionGuard: (action: PuckAction) => void) => ReactNode;
     hardConfig: Config;
-    softComponents: SoftComponents;
+    softComponents?: SoftComponents;
     customFields?: CustomFields;
     overrides?: Overrides;
     value?: StoreApi<AppStore>;
@@ -490,6 +582,10 @@ declare const useCancel: () => {
     canCancel: boolean;
 };
 
+/** * Custom hook to handle inspecting a completed component in the Puck editor.
+ * @deprecated This hook is deprecated
+ * @param component - The completed component result to inspect. Should be set after completing a component.
+ */
 declare const useInspect: (component: CompletedComponentResult | null) => void;
 
 declare const useDecompose: () => {
@@ -549,6 +645,8 @@ declare const Drawer: (_props: {
     children?: React__default.ReactNode;
 }) => react_jsx_runtime.JSX.Element;
 
+declare const HeaderActions: Overrides$1["headerActions"];
+
 type NotificationHandler = (message: string, type: "error" | "success") => void;
 declare const setNotificationHandler: (handler: NotificationHandler) => void;
 declare const notify: {
@@ -576,7 +674,7 @@ declare const confirm: (message: string) => Promise<boolean>;
  * @param undo Function to undo the last action (from Puck's history)
  * @returns Action handler function
  */
-declare const createActionCallback: (validateAction: (action: PuckAction) => boolean, undo: PuckApi["history"]["back"]) => (action: PuckAction) => void;
+declare const createActionCallback: (validateAction: (action: PuckAction) => boolean, undo: PuckApi["history"]["back"] | null) => (action: PuckAction) => void;
 
 /**
  * Resolves soft components in data by dissolving them to hard components only.
@@ -644,4 +742,4 @@ 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 };
+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 };