@flikk/ui 1.0.0-beta.29 → 1.0.0-beta.30

package/dist/tools.json

@@ -20,27 +20,35 @@
               "component": {
                 "type": "string",
                 "enum": [
+                  "Accordion",
                   "Alert",
                   "AreaChart",
                   "Avatar",
+                  "AvatarGroup",
                   "Badge",
                   "BarChart",
+                  "Breadcrumbs",
                   "Button",
                   "Card",
                   "ComboChart",
                   "DescriptionList",
                   "DonutChart",
+                  "Empty",
                   "Feed",
                   "Grid",
                   "KPI",
                   "LineChart",
                   "Metric",
+                  "PageHeading",
+                  "Pill",
                   "Progress",
+                  "Rating",
                   "Section",
                   "Separator",
                   "Stack",
                   "StackedBarChart",
                   "Table",
+                  "Tag",
                   "Timeline"
                 ]
               },
@@ -93,24 +101,46 @@
         }
       },
       "contracts": {
-        "Alert": {
+        "Accordion": {
           "role": "leaf",
-          "description": "Inline callout with semantic color.",
+          "description": "Collapsible sections driven by a serializable items array.",
           "props": {
+            "type": {
+              "kind": "enum",
+              "options": [
+                "single",
+                "multiple"
+              ],
+              "description": "Accordion type - single allows only one item open, multiple allows many"
+            },
             "variant": {
               "kind": "enum",
               "options": [
-                "default",
-                "glass"
+                "separated",
+                "stacked"
               ],
-              "description": "Visual variant"
+              "description": "Visual variant - separated (card-like with spacing) or stacked (unified borders)"
             },
+            "collapsible": {
+              "kind": "boolean",
+              "description": "Whether accordion can be collapsed after being opened (for type=\"single\")"
+            },
+            "items": {
+              "kind": "shape",
+              "shape": "accordionItems",
+              "description": "Data-driven items. When provided, the accordion renders from this array and"
+            }
+          }
+        },
+        "Alert": {
+          "role": "leaf",
+          "description": "Inline callout with semantic color.",
+          "props": {
             "color": {
               "kind": "enum",
               "options": [
                 "neutral",
                 "primary",
-                "secondary",
                 "success",
                 "warning",
                 "danger"
@@ -199,6 +229,15 @@
             "showYAxis": {
               "kind": "boolean"
             },
+            "legend": {
+              "kind": "enum",
+              "options": [
+                "top",
+                "bottom",
+                "none"
+              ],
+              "description": "Always-visible legend position, rendered from `config`'s labels/colors."
+            },
             "minValue": {
               "kind": "number"
             },
@@ -255,13 +294,10 @@
               "description": "The name of the person or entity represented by the avatar."
             },
             "size": {
-              "kind": "enum",
-              "options": [
-                "xs",
-                "sm",
-                "md",
-                "lg",
-                "xl"
+              "kind": "union",
+              "types": [
+                "number",
+                "string"
               ],
               "default": "md",
               "description": "The size of the avatar"
@@ -269,15 +305,36 @@
             "status": {
               "kind": "enum",
               "options": [
+                "none",
                 "online",
                 "offline",
                 "busy",
-                "away",
-                "none"
+                "away"
               ],
               "default": "none",
               "description": "Optional status indicator"
             },
+            "gradient": {
+              "kind": "union",
+              "types": [
+                "boolean",
+                "string"
+              ],
+              "default": false,
+              "description": "Render a deterministic mesh-gradient as the avatar's background layer. The"
+            },
+            "gradientVariant": {
+              "kind": "enum",
+              "options": [
+                "marble",
+                "terra",
+                "spectrum",
+                "mint",
+                "neon"
+              ],
+              "default": "marble",
+              "description": "Curated color palette for the gradient background. Only applies when"
+            },
             "title": {
               "kind": "string",
               "description": "Title text displayed next to the avatar."
@@ -285,6 +342,65 @@
             "subtitle": {
               "kind": "string",
               "description": "Subtitle text displayed below the title (e.g., email, role)."
+            },
+            "verified": {
+              "kind": "boolean",
+              "description": "Whether to show a verification badge overlay at the bottom right."
+            }
+          }
+        },
+        "AvatarGroup": {
+          "role": "leaf",
+          "description": "Overlapping stack of avatars driven by a serializable list.",
+          "props": {
+            "avatars": {
+              "kind": "shape",
+              "shape": "avatarList",
+              "required": true,
+              "description": "Array of avatar props to render in the group"
+            },
+            "max": {
+              "kind": "number",
+              "default": 5,
+              "description": "Maximum number of avatars to display before showing a count"
+            },
+            "size": {
+              "kind": "union",
+              "types": [
+                "number",
+                "string"
+              ],
+              "default": "md",
+              "description": "Size for all avatars in the group"
+            },
+            "spacing": {
+              "kind": "enum",
+              "options": [
+                "tight",
+                "normal",
+                "loose"
+              ],
+              "default": "normal",
+              "description": "Amount of overlap between avatars (higher value = more overlap)"
+            },
+            "direction": {
+              "kind": "enum",
+              "options": [
+                "row",
+                "row-reverse"
+              ],
+              "default": "row",
+              "description": "Direction of the avatar stack"
+            },
+            "ariaLabel": {
+              "kind": "string",
+              "default": "Group of users",
+              "description": "ARIA label for the avatar group for accessibility"
+            },
+            "shouldAnimate": {
+              "kind": "boolean",
+              "default": true,
+              "description": "Enable motion animations for hover effects"
             }
           }
         },
@@ -312,12 +428,11 @@
               "options": [
                 "neutral",
                 "primary",
-                "secondary",
                 "success",
                 "warning",
                 "danger"
               ],
-              "default": "default",
+              "default": "primary",
               "description": "The semantic color of the badge (primary, success, danger, etc.)"
             },
             "size": {
@@ -410,6 +525,15 @@
             "showYAxis": {
               "kind": "boolean"
             },
+            "legend": {
+              "kind": "enum",
+              "options": [
+                "top",
+                "bottom",
+                "none"
+              ],
+              "description": "Always-visible legend position, rendered from `config`'s labels/colors."
+            },
             "minValue": {
               "kind": "number"
             },
@@ -475,6 +599,34 @@
             }
           }
         },
+        "Breadcrumbs": {
+          "role": "leaf",
+          "description": "Navigation breadcrumb trail driven by a serializable items array.",
+          "props": {
+            "items": {
+              "kind": "shape",
+              "shape": "breadcrumbItems",
+              "required": true,
+              "description": "Array of breadcrumb items"
+            },
+            "maxItems": {
+              "kind": "number",
+              "description": "Maximum number of items to display before collapsing. Defaults to 4"
+            },
+            "variant": {
+              "kind": "enum",
+              "options": [
+                "default",
+                "muted"
+              ],
+              "description": "Visual variant of the breadcrumbs"
+            },
+            "showIcons": {
+              "kind": "boolean",
+              "description": "Whether to show icons if provided in items"
+            }
+          }
+        },
         "Button": {
           "role": "leaf",
           "description": "Action button — pair with node.actions.click ({ type, payload }).",
@@ -484,9 +636,6 @@
               "options": [
                 "neutral",
                 "primary",
-                "secondary",
-                "success",
-                "warning",
                 "danger"
               ],
               "description": "The semantic color/intent of the button"
@@ -497,8 +646,7 @@
                 "filled",
                 "outline",
                 "soft",
-                "ghost",
-                "link"
+                "ghost"
               ],
               "description": "The visual style variant of the button"
             },
@@ -516,10 +664,9 @@
               "options": [
                 "default",
                 "disabled",
-                "error",
                 "loading"
               ],
-              "description": "The state of the button (normal, disabled, error)"
+              "description": "The state of the button (default, loading, disabled)"
             },
             "iconOnly": {
               "kind": "boolean",
@@ -541,10 +688,10 @@
               "kind": "enum",
               "options": [
                 "default",
-                "glass",
+                "neon",
                 "aurora",
                 "particle",
-                "neon",
+                "glass",
                 "echo"
               ],
               "description": "Type of ripple effect: 'default' | 'aurora' | 'particle' | 'glass' | 'neon' | 'echo'"
@@ -639,6 +786,15 @@
             "showYAxis": {
               "kind": "boolean"
             },
+            "legend": {
+              "kind": "enum",
+              "options": [
+                "top",
+                "bottom",
+                "none"
+              ],
+              "description": "Always-visible legend position, rendered from `config`'s labels/colors."
+            },
             "minValue": {
               "kind": "number"
             },
@@ -653,6 +809,9 @@
                 "gradient"
               ]
             },
+            "stacked": {
+              "kind": "boolean"
+            },
             "barRadius": {
               "kind": "number"
             },
@@ -677,9 +836,6 @@
             "showStroke": {
               "kind": "boolean"
             },
-            "stacked": {
-              "kind": "boolean"
-            },
             "title": {
               "kind": "text",
               "description": "Card header title (the auto shell)"
@@ -783,6 +939,32 @@
             }
           }
         },
+        "Empty": {
+          "role": "leaf",
+          "description": "Empty-state placeholder with icon, title and subtitle.",
+          "props": {
+            "title": {
+              "kind": "text",
+              "description": "Primary title/heading text"
+            },
+            "subtitle": {
+              "kind": "text",
+              "description": "Subtitle text explaining the empty state"
+            },
+            "image": {
+              "kind": "string",
+              "description": "Optional image source for illustration "
+            },
+            "imageAlt": {
+              "kind": "string",
+              "description": "Alt text for the image (required if image is provided)"
+            },
+            "icon": {
+              "kind": "icon",
+              "description": "Optional icon component (displayed only when no image is provided)"
+            }
+          }
+        },
         "Feed": {
           "role": "leaf",
           "description": "Activity feed driven by a serializable items array.",
@@ -802,6 +984,23 @@
           "role": "container",
           "description": "Responsive CSS-grid container. Children are spec nodes.",
           "props": {
+            "as": {
+              "kind": "enum",
+              "options": [
+                "div",
+                "ul",
+                "ol",
+                "nav",
+                "section",
+                "header",
+                "footer",
+                "aside",
+                "form",
+                "fieldset"
+              ],
+              "default": "div",
+              "description": "Render as a different tag — e.g. `as=\"ul\"` for a card grid that should be"
+            },
             "cols": {
               "kind": "shape",
               "shape": "gridCols",
@@ -909,7 +1108,6 @@
               "options": [
                 "neutral",
                 "primary",
-                "secondary",
                 "success",
                 "warning",
                 "danger"
@@ -927,7 +1125,6 @@
               "kind": "enum",
               "options": [
                 "primary",
-                "secondary",
                 "success",
                 "warning",
                 "danger"
@@ -991,6 +1188,15 @@
             "showYAxis": {
               "kind": "boolean"
             },
+            "legend": {
+              "kind": "enum",
+              "options": [
+                "top",
+                "bottom",
+                "none"
+              ],
+              "description": "Always-visible legend position, rendered from `config`'s labels/colors."
+            },
             "minValue": {
               "kind": "number"
             },
@@ -1055,7 +1261,6 @@
             "variant": {
               "kind": "enum",
               "options": [
-                "glass",
                 "filled",
                 "ghost"
               ],
@@ -1067,7 +1272,6 @@
               "options": [
                 "neutral",
                 "primary",
-                "secondary",
                 "success",
                 "warning",
                 "danger"
@@ -1081,6 +1285,58 @@
             }
           }
         },
+        "PageHeading": {
+          "role": "leaf",
+          "description": "Page header with title/subtitle (managed slot form — header only).",
+          "props": {
+            "title": {
+              "kind": "text",
+              "description": "Heading title (serializable slot). Setting any slot-prop"
+            },
+            "subtitle": {
+              "kind": "text",
+              "description": "Secondary line under the title (serializable slot)."
+            },
+            "separator": {
+              "kind": "boolean",
+              "default": true,
+              "description": "Show bottom separator."
+            }
+          }
+        },
+        "Pill": {
+          "role": "leaf",
+          "description": "Filter/tag chip with optional selected state.",
+          "props": {
+            "children": {
+              "kind": "text",
+              "required": true,
+              "description": "Content to display inside the pill"
+            },
+            "size": {
+              "kind": "enum",
+              "options": [
+                "sm",
+                "md",
+                "lg"
+              ],
+              "description": "Size of the pill"
+            },
+            "iconStart": {
+              "kind": "icon",
+              "description": "Icon element to display at the start (before the content)"
+            },
+            "selected": {
+              "kind": "boolean",
+              "description": "Whether the pill is selected (controlled state)"
+            },
+            "readOnly": {
+              "kind": "boolean",
+              "default": false,
+              "description": "Whether the pill is read-only (non-interactive)"
+            }
+          }
+        },
         "Progress": {
           "role": "leaf",
           "description": "Progress bar (0–100).",
@@ -1107,9 +1363,9 @@
             "labelPosition": {
               "kind": "enum",
               "options": [
-                "right",
                 "top",
                 "bottom",
+                "right",
                 "inside"
               ],
               "default": "right",
@@ -1122,6 +1378,62 @@
             }
           }
         },
+        "Rating": {
+          "role": "leaf",
+          "description": "Read-only star rating display.",
+          "props": {
+            "value": {
+              "kind": "number",
+              "description": "Controlled rating value (0 to max)"
+            },
+            "defaultValue": {
+              "kind": "number",
+              "default": 0,
+              "description": "Default rating value for uncontrolled mode (0 to max)"
+            },
+            "max": {
+              "kind": "number",
+              "default": 5,
+              "description": "Maximum number of stars"
+            },
+            "size": {
+              "kind": "enum",
+              "options": [
+                "sm",
+                "md",
+                "lg"
+              ],
+              "default": "md",
+              "description": "The size of the rating stars"
+            },
+            "color": {
+              "kind": "enum",
+              "options": [
+                "primary",
+                "success",
+                "warning",
+                "danger"
+              ],
+              "default": "warning",
+              "description": "The semantic color of the filled stars"
+            },
+            "readOnly": {
+              "kind": "boolean",
+              "default": false,
+              "description": "Whether the rating is read-only (display only, no interaction)"
+            },
+            "disabled": {
+              "kind": "boolean",
+              "default": false,
+              "description": "Whether the rating is disabled"
+            },
+            "allowHalf": {
+              "kind": "boolean",
+              "default": false,
+              "description": "Enable half-step rating increments"
+            }
+          }
+        },
         "Section": {
           "role": "container",
           "description": "Titled page region without card chrome. Children are spec nodes.",
@@ -1178,6 +1490,23 @@
           "role": "container",
           "description": "Flex container (column by default). Children are spec nodes.",
           "props": {
+            "as": {
+              "kind": "enum",
+              "options": [
+                "div",
+                "ul",
+                "ol",
+                "nav",
+                "section",
+                "header",
+                "footer",
+                "aside",
+                "form",
+                "fieldset"
+              ],
+              "default": "div",
+              "description": "Render as a different tag — e.g. `as=\"nav\"` for a stack of nav links, or"
+            },
             "direction": {
               "kind": "enum",
               "options": [
@@ -1294,6 +1623,15 @@
             "showYAxis": {
               "kind": "boolean"
             },
+            "legend": {
+              "kind": "enum",
+              "options": [
+                "top",
+                "bottom",
+                "none"
+              ],
+              "description": "Always-visible legend position, rendered from `config`'s labels/colors."
+            },
             "minValue": {
               "kind": "number"
             },
@@ -1462,6 +1800,37 @@
             }
           }
         },
+        "Tag": {
+          "role": "leaf",
+          "description": "Compact label chip.",
+          "props": {
+            "children": {
+              "kind": "text",
+              "required": true,
+              "description": "The content of the tag"
+            },
+            "size": {
+              "kind": "enum",
+              "options": [
+                "sm",
+                "md"
+              ],
+              "description": "The size of the tag"
+            },
+            "removable": {
+              "kind": "boolean",
+              "description": "Whether to show the remove button (default: true)"
+            },
+            "disabled": {
+              "kind": "boolean",
+              "description": "Whether the tag is disabled"
+            },
+            "animated": {
+              "kind": "boolean",
+              "description": "Whether to render with motion (layout + enter/exit animation). Default true."
+            }
+          }
+        },
         "Timeline": {
           "role": "leaf",
           "description": "Event timeline driven by a serializable items array.",
@@ -1595,7 +1964,6 @@
                 "additionalProperties": {
                   "enum": [
                     "primary",
-                    "secondary",
                     "success",
                     "warning",
                     "danger",
@@ -1631,6 +1999,61 @@
           "items": {
             "type": "object"
           }
+        },
+        "breadcrumbItems": {
+          "description": "Array of { label } (required string) plus optional href (string). The last item with no href is the current page. Per-item icons are not supported.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "label"
+            ],
+            "properties": {
+              "label": {
+                "type": "string"
+              },
+              "href": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "avatarList": {
+          "description": "Array of { src?, name? } — both strings (serializable AvatarProps subset). name drives the initials fallback.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "src": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "accordionItems": {
+          "description": "Array of { value, title } (both required strings) plus optional content (string).",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "value",
+              "title"
+            ],
+            "properties": {
+              "value": {
+                "type": "string"
+              },
+              "title": {
+                "type": "string"
+              },
+              "content": {
+                "type": "string"
+              }
+            }
+          }
         }
       },
       "examples": [