@dialob/composer-material 0.0.13 → 0.0.15

package/README.md

@@ -101,6 +101,263 @@ pnpm run preview
 
 Starts preview server for built application from `/dist` (No hot-reload!). Run `pnpm build` first to build the package
 
+### Item type configuration
+
+Item type configuration defines the structure of the "Add Item" menu and available item types with their properties and behavior.
+
+**See full example:** [`src/defaults/itemTypes.ts`](src/defaults/itemTypes.ts)
+
+**TypeScript types:** [`src/defaults/types.ts`](src/defaults/types.ts)
+
+#### Menu Structure
+
+The configuration supports **flexible menu nesting** with three options:
+
+1. **Flat structure** - Direct items in a category
+2. **Nested structure** - Items organized in subcategories
+3. **Mixed mode** - Both direct items AND subcategories in the same category
+
+#### Basic Example
+
+```typescript
+export const DEFAULT_ITEMTYPE_CONFIG: ItemTypeConfig = {
+  categories: [
+    {
+      title: 'Structure',
+      type: 'structure',
+      items: [
+        {
+          title: 'Group',
+          convertible: ['rowgroup'],
+          optionEditors: [
+            { name: 'Additional option', editor: PropEditors.InputProp }
+          ],
+          propEditors: {
+            columns: {
+              component: PropEditors.InputProp,
+              props: {
+                type: 'number',
+                min: 1,
+                max: 20
+              }
+            }
+          },
+          config: {
+            type: 'group',
+            props: {
+              columns: 1
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+#### Nested Structure with Subcategories
+
+```typescript
+{
+  title: 'Inputs',
+  type: 'input',
+  subcategories: [
+    {
+      title: 'Text fields',
+      items: [
+        {
+          title: 'Text',
+          convertible: ['textBox', 'address'],
+          config: {
+            type: 'text',
+            view: 'text'
+          }
+        },
+        {
+          title: 'Text box',
+          convertible: ['text', 'address'],
+          config: {
+            type: 'text',
+            view: 'textBox'
+          }
+        }
+      ]
+    },
+    {
+      title: 'Numbers',
+      items: [
+        {
+          title: 'Decimal',
+          config: { type: 'decimal' }
+        },
+        {
+          title: 'Integer',
+          config: { type: 'number' }
+        }
+      ]
+    }
+  ]
+}
+```
+
+This creates a menu hierarchy:
+```
+Inputs →
+  ├─ Text fields →
+  │    ├─ Text
+  │    └─ Text box
+  └─ Numbers →
+       ├─ Decimal
+       └─ Integer
+```
+
+#### Mixed Mode (Direct Items + Subcategories)
+
+You can combine both approaches in the same category:
+
+```typescript
+{
+  title: 'Inputs',
+  type: 'input',
+  items: [
+    // Direct items (no submenu)
+    { title: 'Boolean', config: { type: 'boolean' } },
+    { title: 'Date', config: { type: 'date' } }
+  ],
+  subcategories: [
+    // Nested items (with submenu)
+    {
+      title: 'Text fields',
+      items: [
+        { title: 'Text', config: { type: 'text', view: 'text' } },
+        { title: 'Text box', config: { type: 'text', view: 'textBox' } }
+      ]
+    }
+  ]
+}
+```
+
+Renders as:
+```
+Inputs →
+  ├─ Boolean (clickable)
+  ├─ Date (clickable)
+  ├─── (separator) ───
+  └─ Text fields →
+       ├─ Text
+       └─ Text box
+```
+
+#### Configuration Reference
+
+**Category attributes:**
+* **`title`** - Label displayed in the menu
+* **`type`** - Category type: `'structure'`, `'input'`, or `'output'`. Used to filter which items can be added in different contexts
+* **`items`** - (Optional) Array of item configurations for direct menu items
+* **`subcategories`** - (Optional) Array of subcategory objects for nested menu structure
+
+**Subcategory attributes:**
+* **`title`** - Label displayed in the submenu
+* **`items`** - Array of item configurations
+
+**Item attributes:**
+* **`title`** - Label displayed in the menu
+* **`convertible`** - (Optional) Array of type identifiers this item can be converted to. Matched by `view` first, then `type`. If omitted, item cannot be converted
+* **`optionEditors`** - (Optional) Additional option pages for the item dialog: `{name: 'Title', editor: Component}`
+* **`propEditors`** - (Optional) Custom property editors (see below). If not defined, falls back to plain text input
+* **`config`** - Dialob form item configuration snippet. Required field: `type`. The item's default ID is based on `view` (if present) or `type`
+
+**Note:** `props` in the config are item-specific properties available at form filling time, not to be confused with React component props.
+
+#### Prop Editor Configurations
+
+Built in editors:
+
+* `PropEditors.InputProp` - Plain input component, supports HTML `<input>` attributes as props for defining input type etc.
+
+* `PropEditors.ChoiceProp` - Dropdown selection list, `options` prop having an array of `{key: '', label: ''},` entries, where `key` is value stored in prop and `label` is text displayed in UI.
+
+* `PropEditors.BoolProp` - Boolean switch.
+
+* `PropEditors.MultiChoiceProp` - Dropdown selection list, allows multiple selections (Array of string value). `options` prop as in `ChoiceProp`, `allowAdditions` true/false -- Allow adding arbitrary strings to list.
+
+Custom editing component template
+```typescript
+const CustomProp = ({ onChange, value, name, item, ...props }) => {
+  // onChange(value) - callback function for setting the prop's value
+  // value - current value of the prop
+  // name - prop name
+  // item - item data for current item. (Immutable.Map)
+  // props - additional editor component props passed on from configuration
+
+  // Return react component here that renders UI for prop editor
+  return (<Input onChange={(e) => onChange(e.target.value)} value={value || ''} {...props} />);
+};
+```
+
+
+### Item editor configuration
+
+For example: `src/defaults/itemConfig.js`
+
+Item editor configuration defines which kind of item editing components are used in which conditions.
+
+```typescript
+export const DEFAULT_ITEM_CONFIG: ItemConfig = {
+  defaultIcon: Circle,
+  items: [
+    {
+      matcher: item => item.type === 'group',
+      component: Group,
+      props: {
+        icon: CropSquare,
+        placeholder: 'placeholders.group',
+        treeCollapsible: true,
+      }
+    },
+    ...
+  ]
+} 
+```
+
+Where:
+
+- **mathcer** Function that receives item data and returns true if this configuration is applied to the item
+- **component** React component used for rendering the item in the form editor
+- **props** Additional properties passed to the component
+  - **icon** MUI Icon component used for representing the item in tree view
+  - **placeholder** Placeholder text identifier shown when item has no title
+  - **treeCollapsible** (Group items only) true/false - Allow collapsing/expanding the group in tree view
+
+### Valueset property configuration
+
+This is for controlling additional metadata properties for value set entries that are stored with form data, but *not communicated to filling side*.
+
+For example: `src/defaults/valueSetProps.js`
+
+```javascript
+export const DEFAULT_VALUESET_PROPS: ValueSetProp[] = [
+  {
+    title: 'Custom attribute',
+    name: 'attr',
+    editor: Box,
+  }
+];
+```
+
+* `title` Title shown in table column header
+* `attr` attribute name
+* `editor` React component for editing the value
+
+Valueset entry metadata prop editor React component template
+```javascript
+const CustomValueSetProp = ({ onChange, value }) => {
+  // onChange(value) - callback function for setting the prop's value
+  // value - current value of the prop
+
+  // Return react component here that renders UI for prop editor
+};
+```
 ---
 
 ### Customixing Markdown components

package/dist-lib/index.d.ts

@@ -227,6 +227,7 @@ declare namespace DefaultTypes {
         ConfigItemProps,
         ItemTypeConfig,
         ItemTypeCategory,
+        Subcategory,
         CategoryItem,
         OptionEditor,
         PropEditorsType
@@ -353,6 +354,7 @@ declare interface FlattenedItem extends TreeItem {
     parentId: UniqueIdentifier | null;
     depth: number;
     index: number;
+    isFallbackLabel?: boolean;
 }
 
 declare type FormMetadata = {
@@ -438,7 +440,8 @@ declare interface ItemProp {
 declare interface ItemTypeCategory {
     title: string;
     type: DialobCategoryType;
-    items: CategoryItem[];
+    items?: CategoryItem[];
+    subcategories?: Subcategory[];
 }
 
 declare interface ItemTypeConfig {
@@ -563,6 +566,11 @@ export declare const SimpleField: default_2.FC<{
 
 export { StyledTable }
 
+declare interface Subcategory {
+    title: string;
+    items: CategoryItem[];
+}
+
 export declare const TranslationDialog: default_2.FC<{
     open: boolean;
     onClose: () => void;
@@ -587,6 +595,7 @@ declare interface TreeItem {
     title: string;
     collapsible?: boolean;
     collapsed?: boolean;
+    isFallbackLabel?: boolean;
 }
 
 export declare const UploadValuesetDialog: default_2.FC<{