@netlisian/softconfig 0.1.5 → 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/puck/index.d.mts

@@ -342,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";

package/dist/puck/index.d.ts

@@ -342,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";

package/dist/puck/index.js

@@ -1644,21 +1644,29 @@ var import_uuid = require("uuid");
 var generateId = (type) => type ? `${type}-${(0, import_uuid.v4)()}` : (0, import_uuid.v4)();
 
 // src/puck/lib/component-key.ts
-var defaultToCamelCase = (value) => {
-  const tokens = value.trim().replace(/[^a-zA-Z0-9\s_-]/g, " ").split(/[\s_-]+/).filter(Boolean);
-  if (tokens.length === 0) return "";
-  const [first, ...rest] = tokens;
-  return `${first.toLowerCase()}${rest.map((token) => token.charAt(0).toUpperCase() + token.slice(1).toLowerCase()).join("")}`;
+var toSlug = (value) => {
+  return value.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+};
+var defaultComponentNameToKey = (displayName, context) => {
+  var _a, _b;
+  const registry = (_b = (_a = context.registryName) != null ? _a : context.registry) != null ? _b : "default";
+  return `${toSlug(registry)}/${toSlug(displayName)}`;
+};
+var defaultComponentKeyToName = (key) => {
+  const slashIndex = key.indexOf("/");
+  const componentPart = slashIndex === -1 ? key : key.slice(slashIndex + 1);
+  if (!componentPart) return "";
+  return componentPart.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 };
 var createComponentKeyFromName = (displayName, overrides, context) => {
-  const key = overrides.componentNameToKey ? overrides.componentNameToKey(displayName, context) : defaultToCamelCase(displayName);
+  const key = overrides.componentNameToKey ? overrides.componentNameToKey(displayName, context) : defaultComponentNameToKey(displayName, context);
   return key.trim();
 };
 var getComponentNameFromKey = (key, overrides) => {
   if (overrides == null ? void 0 : overrides.componentKeyToName) {
     return overrides.componentKeyToName(key);
   }
-  return key;
+  return defaultComponentKeyToName(key);
 };
 
 // src/puck/lib/soft-component-to-appstate.ts
@@ -2057,10 +2065,9 @@ var hydrateCustomField = (fieldName, field, fieldSettings, customFields) => {
     label: field.label || customField.field.label || fieldName
   });
 };
-var createVersionedComponentConfig = (componentName, displayName, version, allVersions, config, softComponents, defaultProps, showVersioning = true, customFields) => {
+var createVersionedComponentConfig = (componentName, displayName, version, allVersions, config, softComponents, defaultProps, showVersioning = true, customFields, overrides) => {
   var _a, _b;
-  const softConfig = config;
-  return {
+  const baseConfig = {
     label: displayName,
     fields: Object.fromEntries(
       (Object.entries(
@@ -2104,12 +2111,16 @@ var createVersionedComponentConfig = (componentName, displayName, version, allVe
           softComponentFields: versionedComponent.fields,
           softComponentFieldSettings: versionedComponent.fieldSettings,
           softSubComponent: versionedComponent.components,
-          configComponents: softConfig.components,
+          configComponents: config.components,
           props
         }
       );
     }
   };
+  if (overrides == null ? void 0 : overrides.mapComponentConfig) {
+    return __spreadValues(__spreadValues({}, baseConfig), overrides.mapComponentConfig(componentName, baseConfig));
+  }
+  return baseConfig;
 };
 
 // src/puck/lib/builder/sub-component-decomposer.tsx
@@ -2838,7 +2849,8 @@ function buildInitialSoftComponents(hardConfig, softComponents, overrides, showV
         hydratedSoftComponents,
         versionedComponent.defaultProps,
         showVersioning,
-        customFields
+        customFields,
+        overrides
       );
       componentConfigs[name] = newSoftComponentConfig;
       buildingConfig.components[name] = newSoftComponentConfig;
@@ -2867,7 +2879,8 @@ function buildInitialSoftComponents(hardConfig, softComponents, overrides, showV
         hydratedSoftComponents,
         versionedComponent.defaultProps,
         showVersioning,
-        customFields
+        customFields,
+        overrides
       );
       componentConfigs[name] = newSoftComponentConfig;
     }

package/dist/puck/index.mjs

@@ -1586,21 +1586,29 @@ import { v4 as uuidv4 } from "uuid";
 var generateId = (type) => type ? `${type}-${uuidv4()}` : uuidv4();
 
 // src/puck/lib/component-key.ts
-var defaultToCamelCase = (value) => {
-  const tokens = value.trim().replace(/[^a-zA-Z0-9\s_-]/g, " ").split(/[\s_-]+/).filter(Boolean);
-  if (tokens.length === 0) return "";
-  const [first, ...rest] = tokens;
-  return `${first.toLowerCase()}${rest.map((token) => token.charAt(0).toUpperCase() + token.slice(1).toLowerCase()).join("")}`;
+var toSlug = (value) => {
+  return value.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+};
+var defaultComponentNameToKey = (displayName, context) => {
+  var _a, _b;
+  const registry = (_b = (_a = context.registryName) != null ? _a : context.registry) != null ? _b : "default";
+  return `${toSlug(registry)}/${toSlug(displayName)}`;
+};
+var defaultComponentKeyToName = (key) => {
+  const slashIndex = key.indexOf("/");
+  const componentPart = slashIndex === -1 ? key : key.slice(slashIndex + 1);
+  if (!componentPart) return "";
+  return componentPart.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 };
 var createComponentKeyFromName = (displayName, overrides, context) => {
-  const key = overrides.componentNameToKey ? overrides.componentNameToKey(displayName, context) : defaultToCamelCase(displayName);
+  const key = overrides.componentNameToKey ? overrides.componentNameToKey(displayName, context) : defaultComponentNameToKey(displayName, context);
   return key.trim();
 };
 var getComponentNameFromKey = (key, overrides) => {
   if (overrides == null ? void 0 : overrides.componentKeyToName) {
     return overrides.componentKeyToName(key);
   }
-  return key;
+  return defaultComponentKeyToName(key);
 };
 
 // src/puck/lib/soft-component-to-appstate.ts
@@ -1999,10 +2007,9 @@ var hydrateCustomField = (fieldName, field, fieldSettings, customFields) => {
     label: field.label || customField.field.label || fieldName
   });
 };
-var createVersionedComponentConfig = (componentName, displayName, version, allVersions, config, softComponents, defaultProps, showVersioning = true, customFields) => {
+var createVersionedComponentConfig = (componentName, displayName, version, allVersions, config, softComponents, defaultProps, showVersioning = true, customFields, overrides) => {
   var _a, _b;
-  const softConfig = config;
-  return {
+  const baseConfig = {
     label: displayName,
     fields: Object.fromEntries(
       (Object.entries(
@@ -2046,12 +2053,16 @@ var createVersionedComponentConfig = (componentName, displayName, version, allVe
           softComponentFields: versionedComponent.fields,
           softComponentFieldSettings: versionedComponent.fieldSettings,
           softSubComponent: versionedComponent.components,
-          configComponents: softConfig.components,
+          configComponents: config.components,
           props
         }
       );
     }
   };
+  if (overrides == null ? void 0 : overrides.mapComponentConfig) {
+    return __spreadValues(__spreadValues({}, baseConfig), overrides.mapComponentConfig(componentName, baseConfig));
+  }
+  return baseConfig;
 };
 
 // src/puck/lib/builder/sub-component-decomposer.tsx
@@ -2780,7 +2791,8 @@ function buildInitialSoftComponents(hardConfig, softComponents, overrides, showV
         hydratedSoftComponents,
         versionedComponent.defaultProps,
         showVersioning,
-        customFields
+        customFields,
+        overrides
       );
       componentConfigs[name] = newSoftComponentConfig;
       buildingConfig.components[name] = newSoftComponentConfig;
@@ -2809,7 +2821,8 @@ function buildInitialSoftComponents(hardConfig, softComponents, overrides, showV
         hydratedSoftComponents,
         versionedComponent.defaultProps,
         showVersioning,
-        customFields
+        customFields,
+        overrides
       );
       componentConfigs[name] = newSoftComponentConfig;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netlisian/softconfig",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",