@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

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

Initialization

To ensure Soft Components have access to Puck's internal state (for resolving mapping configurations and handling dispatch events), you must pass getPuck and setPuckDispatch into the Soft Config store from within your custom Puck overrides (e.g., HeaderActions or Document).

import { createUsePuck, useGetPuck } from "@puckeditor/core";
import { useSoftConfig } from "@netlisian/soft-config";
import React, { useEffect } from "react";

const useCustomPuck = createUsePuck();

export const HeaderActions = ({ children }) => {
  const dispatch = useCustomPuck((s) => s.dispatch);
  const getPuck = useGetPuck();

  const setPuckDispatch = useSoftConfig((s) => s.setPuckDispatch);
  const setGetPuck = useSoftConfig((s) => s.setGetPuck);

  useEffect(() => {
    setPuckDispatch(dispatch);
    setGetPuck(getPuck);
  }, [dispatch, getPuck, setPuckDispatch, setGetPuck]);

  return <>{children}</>;
};

Soft Component Definitions

A Soft Component consists of fields, default props, and typed components.

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).

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).

Soft Action Handler

To easily integrate soft configuration behavior inside Puck without manually managing undo guards or state validations, wrap your actions using useSoftPuckAction:

import { useSoftPuckAction } from "@netlisian/soft-config/puck";

const onAction = useSoftPuckAction((action, appState, previousState) => {
  // your custom intercept logic here
});

<Puck onAction={onAction} />

Documentation

For detailed guides and API references, check the Netlisian Docs.

License

MIT