@flikk/ui 1.0.0-beta.31 → 1.0.0-beta.33

package/dist/tools.json

@@ -43,7 +43,7 @@
                   "DotSeparator",
                   "Empty",
                   "Feed",
-                  "FunnelChart",
+                  "Form",
                   "GanttChart",
                   "Grid",
                   "Heatmap",
@@ -69,7 +69,6 @@
                   "Progress",
                   "RadarChart",
                   "Rating",
-                  "ScatterPlot",
                   "ScrollArea",
                   "Section",
                   "Select",
@@ -500,8 +499,8 @@
                 "outline",
                 "soft"
               ],
-              "default": "filled",
-              "description": "The visual style variant of the badge (filled, outline, soft)"
+              "default": "soft",
+              "description": "The visual style variant of the badge."
             },
             "color": {
               "kind": "enum",
@@ -537,11 +536,6 @@
             "iconStart": {
               "kind": "icon",
               "description": "Icon element at the start (before content)"
-            },
-            "disabled": {
-              "kind": "boolean",
-              "default": false,
-              "description": "Whether the badge is disabled"
             }
           }
         },
@@ -729,27 +723,8 @@
             },
             "enableRipple": {
               "kind": "boolean",
-              "description": "Whether to enable ripple effect on click"
-            },
-            "rippleEffect": {
-              "kind": "enum",
-              "options": [
-                "default",
-                "neon",
-                "aurora",
-                "particle",
-                "glass",
-                "echo"
-              ],
-              "description": "Type of ripple effect: 'default' | 'aurora' | 'particle' | 'glass' | 'neon' | 'echo'"
-            },
-            "rippleClassName": {
-              "kind": "string",
-              "description": "Custom class name for ripple styling"
-            },
-            "rippleScale": {
-              "kind": "number",
-              "description": "Scale multiplier for ripple expansion (default: 10)"
+              "default": true,
+              "description": "Whether to show the press ripple."
             },
             "showReflection": {
               "kind": "boolean",
@@ -881,6 +856,14 @@
             "disabled": {
               "kind": "boolean",
               "description": "Whether the checkbox is disabled"
+            },
+            "required": {
+              "kind": "boolean",
+              "description": "Marks this field as required. A parent Form refuses to submit while it is empty, and lists it in the form's error summary."
+            },
+            "name": {
+              "kind": "string",
+              "description": "Field name. Required for this control's value to be included when a parent Form is submitted. Must match /^[A-Za-z_][A-Za-z0-9_-]*$/."
             }
           }
         },
@@ -950,7 +933,7 @@
             },
             "name": {
               "kind": "string",
-              "description": "Form field name"
+              "description": "Field name. Required for this control's value to be included when a parent Form is submitted. Must match /^[A-Za-z_][A-Za-z0-9_-]*$/."
             },
             "value": {
               "kind": "string",
@@ -1270,113 +1253,27 @@
             }
           }
         },
-        "FunnelChart": {
-          "role": "leaf",
-          "description": "Conversion funnel chart (auto Card shell). Bind node.actions.stageClick to onStageClick (fires with the clicked stage's data).",
+        "Form": {
+          "role": "container",
+          "description": "A form that collects structured input from the user. Children with a `name` prop become fields; submitting delivers all field values at once in a single action. Use this whenever you need information from the user rather than free text.",
           "props": {
-            "data": {
-              "kind": "shape",
-              "shape": "funnelStages",
-              "required": true,
-              "description": "Funnel stages data"
-            },
-            "height": {
-              "kind": "union",
-              "types": [
-                "number",
-                "string"
-              ],
-              "description": "Height of the chart"
-            },
-            "width": {
-              "kind": "union",
-              "types": [
-                "number",
-                "string"
-              ],
-              "description": "Width of the chart"
-            },
-            "showPercentages": {
-              "kind": "boolean",
-              "description": "Whether to show percentages"
-            },
-            "showValues": {
-              "kind": "boolean",
-              "description": "Whether to show values"
-            },
-            "showLabels": {
-              "kind": "boolean",
-              "description": "Whether to show stage labels (name)"
-            },
-            "showDropoff": {
-              "kind": "boolean",
-              "description": "Whether to show dropoff percentages between stages"
-            },
-            "showConversionRate": {
-              "kind": "boolean",
-              "description": "Whether to show conversion rates between stages"
-            },
-            "showSummary": {
-              "kind": "boolean",
-              "description": "Whether to show summary statistics"
-            },
-            "colors": {
-              "kind": "shape",
-              "shape": "colorList",
-              "description": "Custom colors"
-            },
-            "orientation": {
-              "kind": "enum",
-              "options": [
-                "horizontal",
-                "vertical"
-              ],
-              "description": "Orientation of the funnel"
-            },
-            "curved": {
-              "kind": "boolean",
-              "description": "Whether to curve segment edges (horizontal only)"
-            },
-            "useGradient": {
-              "kind": "boolean",
-              "description": "Whether to use gradient fills"
-            },
-            "fillOpacity": {
-              "kind": "number",
-              "description": "Fill opacity when gradients are disabled or for gradient stops"
-            },
-            "labelPosition": {
-              "kind": "enum",
-              "options": [
-                "top",
-                "bottom",
-                "inside",
-                "tooltip-only"
-              ],
-              "description": "Position of stage labels"
-            },
-            "summaryPosition": {
-              "kind": "enum",
-              "options": [
-                "none",
-                "top-right",
-                "top-left",
-                "bottom-right",
-                "bottom-left"
-              ],
-              "description": "Position of summary statistics box"
-            },
-            "animate": {
-              "kind": "boolean",
-              "description": "Whether to animate on mount"
-            },
             "title": {
               "kind": "text",
-              "description": "Card header title (the auto shell)"
+              "description": "Heading for the form. Also becomes its accessible name."
             },
-            "subtitle": {
+            "description": {
               "kind": "text",
-              "description": "Card header subtitle (the auto shell)"
+              "description": "Optional helper text shown above the fields."
+            },
+            "submitLabel": {
+              "kind": "string",
+              "default": "Submit",
+              "description": "Label for the submit button. A button is rendered automatically when the form's children do not include one."
+            },
+            "errorSummaryTitle": {
+              "kind": "text",
+              "default": "Please fix the following before continuing:",
+              "description": "Heading for the error summary shown when submit is blocked because a required field is empty. Set it to match the spec's language."
             }
           }
         },
@@ -1410,8 +1307,8 @@
               "kind": "enum",
               "options": [
                 "none",
-                "inside",
                 "auto",
+                "inside",
                 "outside"
               ]
             },
@@ -1557,29 +1454,66 @@
           "role": "leaf",
           "description": "Calendar/matrix heatmap (auto Card shell). Bind node.actions.cellClick to onCellClick (fires with the clicked cell's data).",
           "props": {
+            "legend": {
+              "kind": "enum",
+              "options": [
+                "top",
+                "bottom",
+                "none"
+              ],
+              "default": "bottom",
+              "description": "Colour-ramp legend position — Heatmap draws its own gradient ramp, not per-series swatches from `config`. Always defaults to 'bottom' when omitted."
+            },
             "data": {
               "kind": "shape",
               "shape": "heatmapPoints",
-              "description": "Heatmap data array - optional when using ChartContainer context"
+              "description": "Heatmap data array — optional when using ChartContainer context"
             },
             "color": {
               "kind": "enum",
               "options": [
+                "mono",
                 "primary",
                 "success",
                 "warning",
                 "danger"
               ],
-              "description": "Semantic color for heatmap cells (primary, success, warning, danger)"
+              "default": "primary",
+              "description": "Semantic colour for heatmap cells"
             },
             "variant": {
               "kind": "enum",
               "options": [
                 "default",
-                "minimal",
-                "bordered"
+                "minimal"
               ],
-              "description": "Chart variant"
+              "default": "default",
+              "description": "Visual variant"
+            },
+            "legendLabels": {
+              "kind": "shape",
+              "shape": "heatmapLegendLabels",
+              "default": "{ min: 'Low activity', max: 'High activity' }",
+              "description": "Captions at each end of the colour ramp."
+            },
+            "cellGap": {
+              "kind": "union",
+              "types": [
+                "number",
+                "string"
+              ],
+              "default": 6,
+              "description": "Gap between cells"
+            },
+            "minOpacity": {
+              "kind": "number",
+              "default": 0.1,
+              "description": "Opacity floor for zero/lowest-intensity cells"
+            },
+            "showTooltip": {
+              "kind": "boolean",
+              "default": true,
+              "description": "Show the hover tooltip"
             },
             "height": {
               "kind": "union",
@@ -1595,9 +1529,18 @@
                 "string"
               ]
             },
-            "enableKeyboardNavigation": {
+            "showXAxis": {
+              "kind": "boolean"
+            },
+            "showYAxis": {
               "kind": "boolean"
             },
+            "minValue": {
+              "kind": "number"
+            },
+            "maxValue": {
+              "kind": "number"
+            },
             "title": {
               "kind": "text",
               "description": "Card header title (the auto shell)"
@@ -1711,15 +1654,21 @@
             "enableKeyboardNavigation": {
               "kind": "boolean"
             },
-            "showGrid": {
-              "kind": "boolean"
-            },
             "showXAxis": {
               "kind": "boolean"
             },
             "showYAxis": {
               "kind": "boolean"
             },
+            "minValue": {
+              "kind": "number"
+            },
+            "maxValue": {
+              "kind": "number"
+            },
+            "showGrid": {
+              "kind": "boolean"
+            },
             "legend": {
               "kind": "enum",
               "options": [
@@ -1729,12 +1678,6 @@
               ],
               "description": "Always-visible legend position, rendered from `config`'s labels/colors."
             },
-            "minValue": {
-              "kind": "number"
-            },
-            "maxValue": {
-              "kind": "number"
-            },
             "barRadius": {
               "kind": "number"
             },
@@ -1913,7 +1856,7 @@
             },
             "name": {
               "kind": "string",
-              "description": "Form field name"
+              "description": "Field name. Required for this control's value to be included when a parent Form is submitted. Must match /^[A-Za-z_][A-Za-z0-9_-]*$/."
             },
             "min": {
               "kind": "number",
@@ -1938,6 +1881,21 @@
               "required": true,
               "description": "Current counter value (controlled)"
             },
+            "size": {
+              "kind": "enum",
+              "options": [
+                "sm",
+                "md",
+                "lg"
+              ],
+              "default": "md",
+              "description": "Control size, drawn from the shared `--form-*` scale so a counter lines up"
+            },
+            "editable": {
+              "kind": "boolean",
+              "default": true,
+              "description": "Whether clicking the number swaps it for a text field so the value can be"
+            },
             "state": {
               "kind": "enum",
               "options": [
@@ -1978,6 +1936,14 @@
             "decimalPlaces": {
               "kind": "number",
               "description": "Number of decimal places to display (auto-detected from step if not specified)"
+            },
+            "required": {
+              "kind": "boolean",
+              "description": "Marks this field as required. A parent Form refuses to submit while it is empty, and lists it in the form's error summary."
+            },
+            "name": {
+              "kind": "string",
+              "description": "Field name. Required for this control's value to be included when a parent Form is submitted. Must match /^[A-Za-z_][A-Za-z0-9_-]*$/."
             }
           }
         },
@@ -2055,6 +2021,10 @@
             "maxDate": {
               "kind": "string",
               "description": "Maximum selectable date, ISO format"
+            },
+            "name": {
+              "kind": "string",
+              "description": "Field name. Required for this control's value to be included when a parent Form is submitted. Must match /^[A-Za-z_][A-Za-z0-9_-]*$/."
             }
           }
         },
@@ -2121,6 +2091,14 @@
               "kind": "boolean",
               "default": true,
               "description": "Auto-focus the first input on mount"
+            },
+            "required": {
+              "kind": "boolean",
+              "description": "Marks this field as required. A parent Form refuses to submit while it is empty, and lists it in the form's error summary."
+            },
+            "name": {
+              "kind": "string",
+              "description": "Field name. Required for this control's value to be included when a parent Form is submitted. Must match /^[A-Za-z_][A-Za-z0-9_-]*$/."
             }
           }
         },
@@ -2190,6 +2168,14 @@
             "emptyMessage": {
               "kind": "string",
               "description": "Message shown when no suggestions match (default: \"No suggestions\")"
+            },
+            "required": {
+              "kind": "boolean",
+              "description": "Marks this field as required. A parent Form refuses to submit while it is empty, and lists it in the form's error summary."
+            },
+            "name": {
+              "kind": "string",
+              "description": "Field name. Required for this control's value to be included when a parent Form is submitted. Must match /^[A-Za-z_][A-Za-z0-9_-]*$/."
             }
           }
         },
@@ -2341,15 +2327,21 @@
             "enableKeyboardNavigation": {
               "kind": "boolean"
             },
-            "showGrid": {
-              "kind": "boolean"
-            },
             "showXAxis": {
               "kind": "boolean"
             },
             "showYAxis": {
               "kind": "boolean"
             },
+            "minValue": {
+              "kind": "number"
+            },
+            "maxValue": {
+              "kind": "number"
+            },
+            "showGrid": {
+              "kind": "boolean"
+            },
             "legend": {
               "kind": "enum",
               "options": [
@@ -2359,12 +2351,6 @@
               ],
               "description": "Always-visible legend position, rendered from `config`'s labels/colors."
             },
-            "minValue": {
-              "kind": "number"
-            },
-            "maxValue": {
-              "kind": "number"
-            },
             "title": {
               "kind": "text",
               "description": "Card header title (the auto shell)"
@@ -2696,7 +2682,12 @@
             },
             "selected": {
               "kind": "boolean",
-              "description": "Whether the pill is selected (controlled state)"
+              "description": "Whether the pill is selected — CONTROLLED. Passing it makes the prop"
+            },
+            "defaultSelected": {
+              "kind": "boolean",
+              "default": false,
+              "description": "Initial selection for an UNCONTROLLED pill, which then owns its own state."
             },
             "readOnly": {
               "kind": "boolean",
@@ -2711,7 +2702,21 @@
           "props": {
             "value": {
               "kind": "number",
-              "description": "Progress value from 0 to 100."
+              "description": "Progress value, from 0 to `max`."
+            },
+            "max": {
+              "kind": "number",
+              "default": 100,
+              "description": "Upper bound of the range `value` is measured against."
+            },
+            "segments": {
+              "kind": "number",
+              "description": "Number of cells to render the bar as an LED-style segmented meter."
+            },
+            "segmentFade": {
+              "kind": "boolean",
+              "default": false,
+              "description": "Fade the meter out across its last few lit cells (segmented form only)."
             },
             "size": {
               "kind": "enum",
@@ -2875,88 +2880,14 @@
               "kind": "boolean",
               "default": false,
               "description": "Enable half-step rating increments"
-            }
-          }
-        },
-        "ScatterPlot": {
-          "role": "leaf",
-          "description": "Scatter/bubble chart (auto Card shell).",
-          "props": {
-            "data": {
-              "kind": "shape",
-              "shape": "scatterPoints",
-              "required": true,
-              "description": "Data points"
-            },
-            "xLabel": {
-              "kind": "string",
-              "description": "X-axis label"
-            },
-            "yLabel": {
-              "kind": "string",
-              "description": "Y-axis label"
             },
-            "dotRadius": {
-              "kind": "number",
-              "description": "Point size (if not using data.size)"
-            },
-            "colors": {
-              "kind": "shape",
-              "shape": "colorList",
-              "description": "Custom colors for categories (using CSS variables)"
-            },
-            "showTooltip": {
+            "required": {
               "kind": "boolean",
-              "description": "Enable tooltip on hover"
+              "description": "Marks this field as required. A parent Form refuses to submit while it is empty, and lists it in the form's error summary."
             },
-            "showGrid": {
-              "kind": "boolean"
-            },
-            "showXAxis": {
-              "kind": "boolean"
-            },
-            "showYAxis": {
-              "kind": "boolean"
-            },
-            "legend": {
-              "kind": "enum",
-              "options": [
-                "top",
-                "bottom",
-                "none"
-              ],
-              "description": "Always-visible legend position, rendered from `config`'s labels/colors."
-            },
-            "minValue": {
-              "kind": "number"
-            },
-            "maxValue": {
-              "kind": "number"
-            },
-            "height": {
-              "kind": "union",
-              "types": [
-                "number",
-                "string"
-              ]
-            },
-            "width": {
-              "kind": "union",
-              "types": [
-                "number",
-                "string"
-              ]
-            },
-            "enableKeyboardNavigation": {
-              "kind": "boolean"
-            },
-            "title": {
-              "kind": "text",
-              "description": "Card header title (the auto shell)"
-            },
-            "subtitle": {
-              "kind": "text",
-              "description": "Card header subtitle (the auto shell)"
+            "name": {
+              "kind": "string",
+              "description": "Field name. Required for this control's value to be included when a parent Form is submitted. Must match /^[A-Za-z_][A-Za-z0-9_-]*$/."
             }
           }
         },
@@ -3063,7 +2994,7 @@
           "props": {
             "name": {
               "kind": "string",
-              "description": "Name for the select component"
+              "description": "Field name. Required for this control's value to be included when a parent Form is submitted. Must match /^[A-Za-z_][A-Za-z0-9_-]*$/."
             },
             "size": {
               "kind": "enum",
@@ -3130,6 +3061,10 @@
               "kind": "boolean",
               "description": "Whether to enable typeahead functionality (default: true)"
             },
+            "aria-label": {
+              "kind": "string",
+              "description": "Accessible name for a Select with no visible `label` — e.g. a control sitting"
+            },
             "value": {
               "kind": "string",
               "description": "Currently selected option's value (controlled)"
@@ -3266,7 +3201,7 @@
             },
             "name": {
               "kind": "string",
-              "description": "Name attribute for form submission"
+              "description": "Field name. Required for this control's value to be included when a parent Form is submitted. Must match /^[A-Za-z_][A-Za-z0-9_-]*$/."
             },
             "value": {
               "kind": "number",
@@ -3517,7 +3452,7 @@
             },
             "name": {
               "kind": "string",
-              "description": "HTML name attribute for the hidden input"
+              "description": "Field name. Required for this control's value to be included when a parent Form is submitted. Must match /^[A-Za-z_][A-Za-z0-9_-]*$/."
             },
             "value": {
               "kind": "string",
@@ -3547,8 +3482,8 @@
               "kind": "enum",
               "options": [
                 "default",
-                "bordered",
                 "striped",
+                "bordered",
                 "compact"
               ],
               "description": "Visual variant for different table styles"
@@ -3720,7 +3655,7 @@
             },
             "name": {
               "kind": "string",
-              "description": "Form field name"
+              "description": "Field name. Required for this control's value to be included when a parent Form is submitted. Must match /^[A-Za-z_][A-Za-z0-9_-]*$/."
             }
           }
         },
@@ -3821,6 +3756,14 @@
             "iconEnd": {
               "kind": "icon",
               "description": "Icon to display at the end (right side)"
+            },
+            "required": {
+              "kind": "boolean",
+              "description": "Marks this field as required. A parent Form refuses to submit while it is empty, and lists it in the form's error summary."
+            },
+            "name": {
+              "kind": "string",
+              "description": "Field name. Required for this control's value to be included when a parent Form is submitted. Must match /^[A-Za-z_][A-Za-z0-9_-]*$/."
             }
           }
         },
@@ -4284,56 +4227,6 @@
             }
           }
         },
-        "scatterPoints": {
-          "description": "Array of points: { x, y } (numbers, required) plus optional size (number), label (string), category (string, for color grouping).",
-          "type": "array",
-          "items": {
-            "type": "object",
-            "required": [
-              "x",
-              "y"
-            ],
-            "properties": {
-              "x": {
-                "type": "number"
-              },
-              "y": {
-                "type": "number"
-              },
-              "size": {
-                "type": "number"
-              },
-              "label": {
-                "type": "string"
-              },
-              "category": {
-                "type": "string"
-              }
-            }
-          }
-        },
-        "funnelStages": {
-          "description": "Array of funnel stages: { name, value } (required) plus optional color (CSS string).",
-          "type": "array",
-          "items": {
-            "type": "object",
-            "required": [
-              "name",
-              "value"
-            ],
-            "properties": {
-              "name": {
-                "type": "string"
-              },
-              "value": {
-                "type": "number"
-              },
-              "color": {
-                "type": "string"
-              }
-            }
-          }
-        },
         "activityRings": {
           "description": "Array of rings, ordered outer to inner: { value } (number 0-100, required) plus optional label (string) and color (CSS/hex string).",
           "type": "array",
@@ -4398,6 +4291,18 @@
               }
             }
           }
+        },
+        "heatmapLegendLabels": {
+          "description": "Captions at each end of the colour ramp, both optional: { min, max }.",
+          "type": "object",
+          "properties": {
+            "min": {
+              "type": "string"
+            },
+            "max": {
+              "type": "string"
+            }
+          }
         }
       },
       "examples": [