@lowdefy/blocks-antd 5.2.0 → 5.4.0

package/dist/blocks/ListSelector/meta.js

@@ -0,0 +1,215 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ export default {
+    category: 'input',
+    icons: [],
+    valueType: 'any',
+    cssKeys: {
+        element: 'The list container.',
+        card: 'Each Card element.',
+        body: 'Each Card body.',
+        selected: 'The selected card.',
+        search: 'The search bar wrapper above the list.',
+        noResults: 'The "no results" placeholder shown when the search filter matches zero items.',
+        noData: 'The "no data" placeholder shown when the data array is empty.'
+    },
+    events: {
+        onChange: {
+            description: 'Triggered when the selection changes (only fires when `selectable` is true).',
+            event: {
+                value: 'The newly selected value — the `valueKey` field when set, otherwise the whole data item; null when the selection is cleared.',
+                index: 'Zero-based index of the clicked card.',
+                item: 'The data item bound to the clicked card.'
+            }
+        },
+        onClick: {
+            description: 'Triggered when a card is clicked.',
+            event: {
+                index: 'Zero-based index of the clicked card.',
+                item: 'The data item bound to the clicked card.'
+            }
+        },
+        onSearch: {
+            description: 'Triggered when the debounced search query changes (only fires when the `search` property is set).',
+            event: {
+                value: 'The current debounced search query string.',
+                resultCount: 'Number of items currently visible. Equals data.length when the query is empty or below `minLength`.'
+            }
+        }
+    },
+    properties: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            data: {
+                type: 'array',
+                default: [],
+                description: 'Array of items. Each item is rendered as one card by passing it to the html Nunjucks template as `item`.'
+            },
+            html: {
+                type: 'string',
+                description: 'Nunjucks template used to render the body of each card. The context exposes `item` (the current data row) and `index` (the zero-based row index).'
+            },
+            selectable: {
+                type: 'boolean',
+                default: true,
+                description: 'Enable selecting a card. When true, clicking a card sets the block value to that data item and highlights it. When false, the block is a read-only card list that stores no value.'
+            },
+            allowDeselect: {
+                type: 'boolean',
+                default: true,
+                description: 'Allow clicking the selected card again to clear the selection (sets the value to null). Ignored when `selectable` is false.'
+            },
+            valueKey: {
+                type: 'string',
+                description: 'Field of each data item stored as the block value when a card is selected (e.g. "id"). Omit to store the whole item. Lets the selection be driven with SetState using a simple key. Supports dotted paths.'
+            },
+            primaryKey: {
+                type: 'string',
+                description: 'Field used to match the current value (e.g. set with SetState) back to a card for highlighting. Defaults to `valueKey`. Set this when the stored value is the whole item but a single field (e.g. "id") uniquely identifies it. Supports dotted paths.'
+            },
+            bordered: {
+                type: 'boolean',
+                default: true,
+                description: 'Toggles the border around each card.'
+            },
+            hoverable: {
+                type: 'boolean',
+                default: false,
+                description: 'Lift each card up when hovered.'
+            },
+            size: {
+                type: 'string',
+                enum: [
+                    'default',
+                    'small'
+                ],
+                default: 'default',
+                description: 'Card size.'
+            },
+            gap: {
+                type: 'number',
+                default: 8,
+                description: 'Pixel gap between cards.'
+            },
+            height: {
+                type: [
+                    'number',
+                    'string'
+                ],
+                description: 'Optional pixel height (number) or CSS height string of the scroll container. When omitted, the list scrolls with the page.'
+            },
+            overscan: {
+                type: 'number',
+                default: 400,
+                description: 'Pixels of off-screen rows to render above and below the viewport. Increase for smoother fast-scroll, decrease to reduce DOM cost.'
+            },
+            noData: {
+                type: 'string',
+                description: 'Text shown in place of the list when the `data` array is empty. Defaults to the `blocks.listSelector.noData` message ("No data").'
+            },
+            search: {
+                type: 'object',
+                additionalProperties: false,
+                description: 'Optional client-side search bar above the list. When this property is set, a debounced search input filters rows by text. Omit to hide the bar.',
+                properties: {
+                    placeholder: {
+                        type: 'string',
+                        default: 'Search…',
+                        description: 'Placeholder text in the input.'
+                    },
+                    fields: {
+                        type: 'array',
+                        items: {
+                            type: 'string'
+                        },
+                        description: 'Dotted field paths to match against (e.g. "user.name"). When omitted, every field path is searched (whole-item stringify).'
+                    },
+                    caseSensitive: {
+                        type: 'boolean',
+                        default: false,
+                        description: 'Match case exactly.'
+                    },
+                    debounce: {
+                        type: 'number',
+                        default: 150,
+                        description: 'Milliseconds to wait after the last keystroke before filtering.'
+                    },
+                    sticky: {
+                        type: 'boolean',
+                        default: true,
+                        description: 'Stick the search bar to the top while scrolling.'
+                    },
+                    allowClear: {
+                        type: 'boolean',
+                        default: true,
+                        description: 'Show a clear (×) icon in the input.'
+                    },
+                    minLength: {
+                        type: 'number',
+                        default: 0,
+                        description: 'Skip filtering until the query is at least this many characters.'
+                    },
+                    noResultsText: {
+                        type: 'string',
+                        default: 'No results',
+                        description: 'Text shown when the filter matches zero items.'
+                    }
+                }
+            },
+            theme: {
+                type: 'object',
+                description: 'Antd design token overrides for the cards. See <a href="https://ant.design/components/overview#design-token">antd design tokens</a>.',
+                docs: {
+                    displayType: 'yaml',
+                    link: 'https://ant.design/components/card#design-token'
+                },
+                properties: {
+                    bodyPadding: {
+                        type: 'number',
+                        default: 24,
+                        description: 'Padding of each card body.'
+                    },
+                    bodyPaddingSM: {
+                        type: 'number',
+                        default: 12,
+                        description: 'Padding of each card body for small cards.'
+                    },
+                    borderRadiusLG: {
+                        type: 'number',
+                        default: 8,
+                        description: 'Border radius of each card.'
+                    },
+                    colorBorderSecondary: {
+                        type: 'string',
+                        description: 'Border color of each card.'
+                    },
+                    colorBgContainer: {
+                        type: 'string',
+                        description: 'Background color of each card body.'
+                    },
+                    colorText: {
+                        type: 'string',
+                        description: 'Text color inside each card.'
+                    },
+                    boxShadowTertiary: {
+                        type: 'string',
+                        description: 'Shadow applied to each card on hover when hoverable is true.'
+                    }
+                }
+            }
+        }
+    }
+};

package/dist/blocks/Menu/Menu.js

@@ -19,13 +19,13 @@ const SiderContext = Layout._InternalSiderContext;
 import { withBlockDefaults } from '@lowdefy/block-utils';
 import withTheme from '../withTheme.js';
 import useItemShortcuts from '../useItemShortcuts.js';
+import { buildMenuItems } from '../buildMenuItems.js';
 const getDefaultMenu = (menus, menuId = 'default', links)=>{
     if (type.isArray(links)) return links;
     if (!type.isArray(menus)) return [];
     const menu = menus.find((item)=>item.menuId === menuId) ?? menus[0] ?? {};
     return menu.links ?? [];
 };
-const getTitle = ({ id, properties, pageId, url })=>properties?.title ?? pageId ?? url ?? id;
 function collectLinkShortcuts(links) {
     const result = [];
     (links ?? []).forEach((link)=>{
@@ -43,83 +43,16 @@ function collectLinkShortcuts(links) {
     });
     return result;
 }
-function buildMenuItems({ links, events, components: { Icon, Link, ShortcutBadge }, classNames, styles, isTopLevel = true }) {
-    return (links ?? []).map((link, i)=>{
-        if (link.type === 'MenuDivider') {
-            return {
-                type: 'divider',
-                key: link.id ?? i,
-                dashed: link.properties?.dashed,
-                style: link.style
-            };
-        }
-        if (link.type === 'MenuGroup') {
-            const groupItem = {
-                key: link.pageId ?? link.id,
-                label: /*#__PURE__*/ React.createElement(Link, {
-                    id: link.pageId ?? link.id ?? i,
-                    style: link.style,
-                    ...link
-                }, getTitle(link)),
-                children: buildMenuItems({
-                    links: link.links,
-                    events,
-                    components: {
-                        Icon,
-                        Link,
-                        ShortcutBadge
-                    },
-                    classNames,
-                    styles,
-                    isTopLevel: false
-                })
-            };
-            if (isTopLevel) {
-                // Top-level MenuGroup → collapsible submenu (with icon)
-                groupItem.icon = link.properties?.icon ? /*#__PURE__*/ React.createElement(Icon, {
-                    blockId: `${link.id}_icon`,
-                    classNames: {
-                        element: classNames.icon
-                    },
-                    events: events,
-                    properties: link.properties.icon,
-                    styles: {
-                        element: styles.icon
-                    }
-                }) : undefined;
-            } else {
-                // Nested MenuGroup → non-collapsible group header
-                groupItem.type = 'group';
-            }
-            return groupItem;
-        }
-        // MenuLink (default)
-        return {
-            key: link.pageId ?? link.id,
-            danger: link.properties?.danger,
-            className: classNames.item,
-            icon: link.properties?.icon ? /*#__PURE__*/ React.createElement(Icon, {
-                blockId: `${link.id}_icon`,
-                classNames: {
-                    element: classNames.icon
-                },
-                events: events,
-                properties: link.properties.icon,
-                styles: {
-                    element: styles.icon
-                }
-            }) : undefined,
-            label: /*#__PURE__*/ React.createElement(Link, {
-                id: link.pageId ?? link.id ?? i,
-                style: link.style,
-                url: link.url ?? link.properties?.url,
-                newTab: link.newTab ?? link.properties?.newTab,
-                ...link
-            }, getTitle(link), /*#__PURE__*/ React.createElement(ShortcutBadge, {
-                shortcut: link.properties?.shortcut
-            }))
-        };
-    });
+function makeWrapGroupLabel(Link) {
+    return function wrapGroupLabel({ link, labelText, classNames: labelClass, styles: labelStyle }) {
+        const { class: _omitClass, style: _omitStyle, ...linkRest } = link;
+        return /*#__PURE__*/ React.createElement(Link, {
+            ...linkRest,
+            id: link.pageId ?? link.id,
+            className: labelClass || undefined,
+            style: labelStyle
+        }, labelText);
+    };
 }
 function MenuComp({ blockId, classNames = {}, components: { Icon, Link, ShortcutBadge }, events, menus, methods, pageId, properties, rename, styles = {} }) {
     const horizontalStyles = {
@@ -136,6 +69,16 @@ function MenuComp({ blockId, classNames = {}, components: { Icon, Link, Shortcut
     const theme = properties.theme;
     const { siderCollapsed } = useContext(SiderContext) ?? {};
     const isCollapsed = properties.collapsed === true || siderCollapsed === true;
+    // Back-compat: the prior cssKey for the menu item icon was `icon`; the shared helper
+    // standardises on `itemIcon`. Map either through so existing YAML keeps working.
+    const itemsClassNames = {
+        ...classNames,
+        itemIcon: classNames.itemIcon ?? classNames.icon
+    };
+    const itemsStyles = {
+        ...styles,
+        itemIcon: styles.itemIcon ?? styles.icon
+    };
     const items = buildMenuItems({
         links: menu,
         events,
@@ -144,8 +87,11 @@ function MenuComp({ blockId, classNames = {}, components: { Icon, Link, Shortcut
             Link,
             ShortcutBadge
         },
-        classNames,
-        styles
+        classNames: itemsClassNames,
+        styles: itemsStyles,
+        wrapGroupLabel: makeWrapGroupLabel(Link),
+        nestedGroupAsGroup: true,
+        getKey: (link)=>link.pageId ?? link.id
     });
     const shortcutItems = collectLinkShortcuts(menu);
     const onShortcutMatch = useCallback((key)=>{

package/dist/blocks/Menu/meta.js

@@ -19,8 +19,9 @@
     cssKeys: {
         element: 'The Menu element.',
         expandIcon: 'The expand icon in the Menu.',
-        icon: 'The icon in the Menu.',
-        item: 'The Menu item.'
+        icon: 'Deprecated alias for `itemIcon`.',
+        itemIcon: 'The icon shown in each menu item.',
+        item: 'The Menu item wrapper (li).'
     },
     events: {
         onSelect: {
@@ -375,12 +376,24 @@
                             description: 'Page to link to.'
                         },
                         style: {
-                            type: 'object',
-                            description: 'Css style to applied to link.',
+                            type: [
+                                'object',
+                                'string',
+                                'array'
+                            ],
+                            description: 'CSS styles for the menu item. Use a flat object for the item wrapper, or use dot-prefixed slot keys (`.element`, `.icon`, `.label`) to target specific parts.',
                             docs: {
                                 displayType: 'yaml'
                             }
                         },
+                        class: {
+                            type: [
+                                'string',
+                                'array',
+                                'object'
+                            ],
+                            description: 'CSS classes for the menu item (including Tailwind utilities). Flat string/array applies to the item wrapper. Use an object with dot-prefixed slot keys (`.element`, `.icon`, `.label`, `.popup` — popup only on MenuGroup) to target specific parts.'
+                        },
                         properties: {
                             type: 'object',
                             description: 'properties from menu item.',
@@ -402,16 +415,29 @@
                                 danger: {
                                     type: 'boolean',
                                     default: false,
-                                    description: 'Apply danger style to menu item.'
+                                    description: 'Apply danger style (MenuLink only). Switches the item onto the `dangerItem*` token set — theme via `properties.theme.dangerItemColor` etc.'
+                                },
+                                disabled: {
+                                    type: 'boolean',
+                                    default: false,
+                                    description: 'Disable the menu item (blocks clicks and applies a greyed style).'
+                                },
+                                tooltip: {
+                                    type: 'string',
+                                    description: 'Tooltip text shown on hover when the menu is collapsed. Maps to antd item `title`.'
+                                },
+                                extra: {
+                                    type: 'string',
+                                    description: 'Free-form right-aligned label on a MenuLink (e.g. a status hint like "beta" or "soon"). For real keyboard shortcuts use `shortcut` instead — it renders a kbd badge AND wires the key handler. When both are set, `shortcut` sits to the far right of `extra`.'
                                 },
                                 dashed: {
                                     type: 'boolean',
                                     default: false,
-                                    description: 'Whether the divider line is dashed.'
+                                    description: 'Whether the divider line is dashed (MenuDivider only).'
                                 },
                                 shortcut: {
                                     type: 'string',
-                                    description: 'Keyboard shortcut to select this menu item. Renders a shortcut badge next to the label. Use "mod" for Cmd/Ctrl.'
+                                    description: 'Keyboard shortcut for this menu item. Renders a kbd badge floated to the far right of the item AND wires the key handler (fires onSelect when pressed). Use "mod" for Cmd/Ctrl.'
                                 }
                             }
                         },
@@ -439,12 +465,24 @@
                                         description: 'Menu item type.'
                                     },
                                     style: {
-                                        type: 'object',
-                                        description: 'Css style to applied to sub-link.',
+                                        type: [
+                                            'object',
+                                            'string',
+                                            'array'
+                                        ],
+                                        description: 'CSS styles for the menu item. Use a flat object for the item wrapper, or dot-prefixed slot keys (`.element`, `.icon`, `.label`).',
                                         docs: {
                                             displayType: 'yaml'
                                         }
                                     },
+                                    class: {
+                                        type: [
+                                            'string',
+                                            'array',
+                                            'object'
+                                        ],
+                                        description: 'CSS classes for the menu item. Flat applies to the item wrapper; use dot-prefixed slot keys to target parts.'
+                                    },
                                     pageId: {
                                         type: 'string',
                                         description: 'Page to link to.'
@@ -457,10 +495,33 @@
                                                 type: 'string',
                                                 description: 'Menu item title.'
                                             },
+                                            icon: {
+                                                type: [
+                                                    'string',
+                                                    'object'
+                                                ],
+                                                description: 'Icon name or Icon block properties.',
+                                                docs: {
+                                                    displayType: 'icon'
+                                                }
+                                            },
                                             danger: {
                                                 type: 'boolean',
                                                 default: false,
-                                                description: 'Apply danger style to menu item.'
+                                                description: 'Apply danger style (MenuLink only).'
+                                            },
+                                            disabled: {
+                                                type: 'boolean',
+                                                default: false,
+                                                description: 'Disable the menu item.'
+                                            },
+                                            tooltip: {
+                                                type: 'string',
+                                                description: 'Tooltip text shown when the menu is collapsed.'
+                                            },
+                                            extra: {
+                                                type: 'string',
+                                                description: 'Free-form right-aligned label on a MenuLink. For real keybindings use `shortcut`; when both are set, `shortcut` sits to the right of `extra`.'
                                             },
                                             dashed: {
                                                 type: 'boolean',
@@ -469,64 +530,99 @@
                                             },
                                             shortcut: {
                                                 type: 'string',
-                                                description: 'Keyboard shortcut to select this menu item. Renders a shortcut badge next to the label. Use "mod" for Cmd/Ctrl.'
+                                                description: 'Keyboard shortcut for this menu item. Renders a kbd badge floated to the far right of the item AND wires the key handler (fires onSelect when pressed). Use "mod" for Cmd/Ctrl.'
                                             }
-                                        },
-                                        links: {
-                                            type: 'array',
-                                            items: {
-                                                type: 'object',
-                                                required: [
-                                                    'id',
-                                                    'type'
-                                                ],
+                                        }
+                                    },
+                                    links: {
+                                        type: 'array',
+                                        items: {
+                                            type: 'object',
+                                            required: [
+                                                'id',
+                                                'type'
+                                            ],
+                                            properties: {
+                                                id: {
+                                                    type: 'string',
+                                                    description: 'Menu item id.'
+                                                },
+                                                type: {
+                                                    type: 'string',
+                                                    enum: [
+                                                        'MenuDivider',
+                                                        'MenuLink'
+                                                    ],
+                                                    default: 'MenuLink',
+                                                    description: 'Menu item type.'
+                                                },
+                                                style: {
+                                                    type: [
+                                                        'object',
+                                                        'string',
+                                                        'array'
+                                                    ],
+                                                    description: 'CSS styles for the menu item. Use a flat object or dot-prefixed slot keys.',
+                                                    docs: {
+                                                        displayType: 'yaml'
+                                                    }
+                                                },
+                                                class: {
+                                                    type: [
+                                                        'string',
+                                                        'array',
+                                                        'object'
+                                                    ],
+                                                    description: 'CSS classes for the menu item.'
+                                                },
+                                                pageId: {
+                                                    type: 'string',
+                                                    description: 'Page to link to.'
+                                                },
                                                 properties: {
-                                                    id: {
-                                                        type: 'string',
-                                                        description: 'Menu item id.'
-                                                    },
-                                                    type: {
-                                                        type: 'string',
-                                                        enum: [
-                                                            'MenuDivider',
-                                                            'MenuLink'
-                                                        ],
-                                                        default: 'MenuLink',
-                                                        description: 'Menu item type.'
-                                                    },
-                                                    style: {
-                                                        type: 'object',
-                                                        description: 'Css style to applied to sub-link.',
-                                                        docs: {
-                                                            displayType: 'yaml'
-                                                        }
-                                                    },
-                                                    pageId: {
-                                                        type: 'string',
-                                                        description: 'Page to link to.'
-                                                    },
+                                                    type: 'object',
+                                                    description: 'properties from menu item.',
                                                     properties: {
-                                                        type: 'object',
-                                                        description: 'properties from menu item.',
-                                                        properties: {
-                                                            title: {
-                                                                type: 'string',
-                                                                description: 'Menu item title.'
-                                                            },
-                                                            danger: {
-                                                                type: 'boolean',
-                                                                default: false,
-                                                                description: 'Apply danger style to menu item.'
-                                                            },
-                                                            dashed: {
-                                                                type: 'boolean',
-                                                                default: false,
-                                                                description: 'Whether the divider line is dashed.'
-                                                            },
-                                                            shortcut: {
-                                                                type: 'string',
-                                                                description: 'Keyboard shortcut to select this menu item. Renders a shortcut badge next to the label. Use "mod" for Cmd/Ctrl.'
+                                                        title: {
+                                                            type: 'string',
+                                                            description: 'Menu item title.'
+                                                        },
+                                                        icon: {
+                                                            type: [
+                                                                'string',
+                                                                'object'
+                                                            ],
+                                                            description: 'Icon name or Icon block properties.',
+                                                            docs: {
+                                                                displayType: 'icon'
                                                             }
+                                                        },
+                                                        danger: {
+                                                            type: 'boolean',
+                                                            default: false,
+                                                            description: 'Apply danger style (MenuLink only).'
+                                                        },
+                                                        disabled: {
+                                                            type: 'boolean',
+                                                            default: false,
+                                                            description: 'Disable the menu item.'
+                                                        },
+                                                        tooltip: {
+                                                            type: 'string',
+                                                            description: 'Tooltip text shown when the menu is collapsed.'
+                                                        },
+                                                        extra: {
+                                                            type: 'string',
+                                                            description: 'Free-form right-aligned label on a MenuLink. For real keybindings use `shortcut`.'
+                                                        },
+                                                        dashed: {
+                                                            type: 'boolean',
+                                                            default: false,
+                                                            description: 'Whether the divider line is dashed.'
+                                                        },
+                                                        shortcut: {
+                                                            type: 'string',
+                                                            description: 'Keyboard shortcut. Renders a kbd badge floated to the far right and wires the key handler. Use "mod" for Cmd/Ctrl.'
                                                         }
                                                     }
                                                 }