@alfadocs/ui-kit 1.54.3 → 1.55.0

package/dist/agent-catalog.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "packageVersion": "1.54.3",
+  "packageVersion": "1.55.0",
   "components": [
     {
       "kind": "component",
@@ -4914,6 +4914,26 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "error-summary",
+      "capabilities": [
+        "navigate"
+      ],
+      "state": [],
+      "actions": [],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "error-summary",
+          "description": "Marks the ErrorSummary. Present only while the form has problems to list; its heading names it and each list item is one problem."
+        },
+        "item": {
+          "attr": "data-error-field",
+          "description": "Each problem emits its field's name (`errors[].field`) as data-error-field: not data-field, which a form puts on the field itself. Its link (`data-action=\"go-to-field\"`) points at the field by id and moves focus to the field's control. An item without a link belongs to no single field."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "face-scheme",
@@ -6516,6 +6536,412 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "heatmap",
+      "capabilities": [
+        "select_single",
+        "select_multiple",
+        "range_pick",
+        "expand",
+        "sort",
+        "view_change"
+      ],
+      "state": [
+        {
+          "name": "selection",
+          "type": "Array<{ rowId, columnId }>",
+          "description": "Row and column ids of the selected cells.",
+          "descriptionKey": "ui.agent.heatmap.state.selection"
+        },
+        {
+          "name": "selectionMode",
+          "type": "'none' | 'single' | 'multiple' | 'range'",
+          "description": "How cells can be selected in this heatmap.",
+          "descriptionKey": "ui.agent.heatmap.state.selectionMode"
+        },
+        {
+          "name": "view",
+          "type": "'heatmap' | 'table'",
+          "description": "Whether the heatmap or its table view is showing.",
+          "descriptionKey": "ui.agent.heatmap.state.view"
+        },
+        {
+          "name": "sortRows",
+          "type": "'none' | 'label' | 'total-asc' | 'total-desc'",
+          "description": "Current row order.",
+          "descriptionKey": "ui.agent.heatmap.state.sortRows"
+        },
+        {
+          "name": "rowIds",
+          "type": "string[]",
+          "description": "Row ids in display order, every group expanded. Opaque, never a label.",
+          "descriptionKey": "ui.agent.heatmap.state.rowIds"
+        },
+        {
+          "name": "columnIds",
+          "type": "Array<string | number>",
+          "description": "Column ids in order. Opaque, never a label.",
+          "descriptionKey": "ui.agent.heatmap.state.columnIds"
+        },
+        {
+          "name": "groupIds",
+          "type": "string[]",
+          "description": "Group ids in display order, empty unless rows are grouped. A group not listed in `groups` shows as group-1, group-2 and so on.",
+          "descriptionKey": "ui.agent.heatmap.state.groupIds"
+        },
+        {
+          "name": "collapsedGroups",
+          "type": "string[]",
+          "description": "Ids (as in groupIds) of the row groups that are collapsed.",
+          "descriptionKey": "ui.agent.heatmap.state.collapsedGroups"
+        }
+      ],
+      "actions": [
+        {
+          "name": "select_cell",
+          "safety": "read",
+          "argsType": "{ rowId: string, columnId: string | number }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "rowId": {
+                "type": "string",
+                "description": "Row id, from rowIds."
+              },
+              "columnId": {
+                "type": [
+                  "string",
+                  "number"
+                ],
+                "description": "Column id, from columnIds."
+              }
+            },
+            "required": [
+              "rowId",
+              "columnId"
+            ]
+          },
+          "idempotent": true,
+          "errors": [
+            "Selection is off (selection=\"none\").",
+            "The row or column id does not exist."
+          ],
+          "examples": [
+            {
+              "args": {
+                "rowId": "chair-1",
+                "columnId": 10
+              },
+              "note": "Select chair 1 at 10:00."
+            }
+          ],
+          "description": "Make one cell the whole selection.",
+          "descriptionKey": "ui.agent.heatmap.actions.selectCell"
+        },
+        {
+          "name": "select_cells",
+          "safety": "read",
+          "argsType": "{ cells: Array<{ rowId, columnId }> }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "cells": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "rowId": {
+                      "type": "string",
+                      "description": "Row id, from rowIds."
+                    },
+                    "columnId": {
+                      "type": [
+                        "string",
+                        "number"
+                      ],
+                      "description": "Column id, from columnIds."
+                    }
+                  },
+                  "required": [
+                    "rowId",
+                    "columnId"
+                  ]
+                },
+                "description": "Cells to select; replaces the selection. Single mode keeps the first."
+              }
+            },
+            "required": [
+              "cells"
+            ]
+          },
+          "idempotent": true,
+          "errors": [
+            "Selection is off (selection=\"none\").",
+            "A row or column id does not exist; nothing is selected."
+          ],
+          "description": "Replace the selection with the given cells.",
+          "descriptionKey": "ui.agent.heatmap.actions.selectCells"
+        },
+        {
+          "name": "select_range",
+          "safety": "read",
+          "argsType": "{ from: { rowId, columnId }, to: { rowId, columnId } }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "from": {
+                "type": "object",
+                "properties": {
+                  "rowId": {
+                    "type": "string",
+                    "description": "Row id, from rowIds."
+                  },
+                  "columnId": {
+                    "type": [
+                      "string",
+                      "number"
+                    ],
+                    "description": "Column id, from columnIds."
+                  }
+                },
+                "required": [
+                  "rowId",
+                  "columnId"
+                ],
+                "description": "One corner, inclusive."
+              },
+              "to": {
+                "type": "object",
+                "properties": {
+                  "rowId": {
+                    "type": "string",
+                    "description": "Row id, from rowIds."
+                  },
+                  "columnId": {
+                    "type": [
+                      "string",
+                      "number"
+                    ],
+                    "description": "Column id, from columnIds."
+                  }
+                },
+                "required": [
+                  "rowId",
+                  "columnId"
+                ],
+                "description": "The opposite corner, inclusive."
+              }
+            },
+            "required": [
+              "from",
+              "to"
+            ]
+          },
+          "idempotent": true,
+          "errors": [
+            "Needs selection=\"range\" or \"multiple\".",
+            "A corner names a row or column that does not exist."
+          ],
+          "description": "Select the rectangle of cells between two corners, in the rows as shown.",
+          "descriptionKey": "ui.agent.heatmap.actions.selectRange"
+        },
+        {
+          "name": "clear_selection",
+          "safety": "read",
+          "idempotent": true,
+          "errors": [
+            "Selection is off (selection=\"none\")."
+          ],
+          "description": "Deselect every cell.",
+          "descriptionKey": "ui.agent.heatmap.actions.clearSelection"
+        },
+        {
+          "name": "read_cell",
+          "safety": "read",
+          "argsType": "{ rowId: string, columnId: string | number }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "rowId": {
+                "type": "string",
+                "description": "Row id, from rowIds."
+              },
+              "columnId": {
+                "type": [
+                  "string",
+                  "number"
+                ],
+                "description": "Column id, from columnIds."
+              }
+            },
+            "required": [
+              "rowId",
+              "columnId"
+            ]
+          },
+          "returns": "{ value, count, status, step } | null",
+          "returnsSchema": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "properties": {
+              "value": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "count": {
+                "type": "number"
+              },
+              "status": {
+                "enum": [
+                  "value",
+                  "empty",
+                  "low-sample"
+                ]
+              },
+              "step": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              }
+            }
+          },
+          "idempotent": true,
+          "description": "Read a cell's value, count, status and colour step (no labels).",
+          "descriptionKey": "ui.agent.heatmap.actions.readCell"
+        },
+        {
+          "name": "toggle_table_view",
+          "safety": "read",
+          "returns": "'heatmap' | 'table'",
+          "returnsSchema": {
+            "enum": [
+              "heatmap",
+              "table"
+            ]
+          },
+          "description": "Switch between the heatmap and its table view.",
+          "descriptionKey": "ui.agent.heatmap.actions.toggleTableView"
+        },
+        {
+          "name": "set_view",
+          "safety": "read",
+          "argsType": "{ view: 'heatmap' | 'table' }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "view": {
+                "enum": [
+                  "heatmap",
+                  "table"
+                ],
+                "description": "The coloured grid, or the same data as a table."
+              }
+            },
+            "required": [
+              "view"
+            ]
+          },
+          "idempotent": true,
+          "description": "Show the heatmap or its table view.",
+          "descriptionKey": "ui.agent.heatmap.actions.setView"
+        },
+        {
+          "name": "sort_rows",
+          "safety": "read",
+          "argsType": "{ sort: 'none' | 'label' | 'total-asc' | 'total-desc' }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "sort": {
+                "enum": [
+                  "none",
+                  "label",
+                  "total-asc",
+                  "total-desc"
+                ],
+                "description": "Row order within each group: as given, by label, or by row total."
+              }
+            },
+            "required": [
+              "sort"
+            ]
+          },
+          "idempotent": true,
+          "description": "Reorder the rows.",
+          "descriptionKey": "ui.agent.heatmap.actions.sortRows"
+        },
+        {
+          "name": "expand_group",
+          "safety": "read",
+          "argsType": "{ groupId: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "groupId": {
+                "type": "string",
+                "description": "Group id, from groupIds."
+              }
+            },
+            "required": [
+              "groupId"
+            ]
+          },
+          "idempotent": true,
+          "errors": [
+            "Rows are not grouped (groupRows is off).",
+            "The group id does not exist (see groupIds)."
+          ],
+          "description": "Show a group's rows.",
+          "descriptionKey": "ui.agent.heatmap.actions.expandGroup"
+        },
+        {
+          "name": "collapse_group",
+          "safety": "read",
+          "argsType": "{ groupId: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "groupId": {
+                "type": "string",
+                "description": "Group id, from groupIds."
+              }
+            },
+            "required": [
+              "groupId"
+            ]
+          },
+          "idempotent": true,
+          "errors": [
+            "Rows are not grouped (groupRows is off).",
+            "The group id does not exist (see groupIds)."
+          ],
+          "description": "Hide a group's rows, leaving its totals row.",
+          "descriptionKey": "ui.agent.heatmap.actions.collapseGroup"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "heatmap",
+          "description": "Marks the Heatmap root."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop on Heatmap."
+        },
+        "item": {
+          "attr": "data-heatmap-cell-id",
+          "description": "On every data cell: \"<rowId>:<columnId>\", built from the opaque ids, never from labels. A group header row and its cells carry data-heatmap-group-id, the group id as in groupIds."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "hover-card",
@@ -9467,7 +9893,7 @@
         {
           "name": "focus_site",
           "safety": "read",
-          "argsType": "{ fdi: string; site: PeriodontalSiteId; field: \"pocketDepthMm\" | \"recessionMm\" }",
+          "argsType": "{ fdi: string; site: PeriodontalSiteId; field: \"pocketDepthMm\" | \"recessionMm\" | \"bleeding\" | \"plaque\" }",
           "argsSchema": {
             "type": "object",
             "properties": {
@@ -9489,7 +9915,9 @@
               "field": {
                 "enum": [
                   "pocketDepthMm",
-                  "recessionMm"
+                  "recessionMm",
+                  "bleeding",
+                  "plaque"
                 ]
               }
             },
@@ -9500,7 +9928,7 @@
             ]
           },
           "idempotent": true,
-          "description": "Move focus to a specific probing-measurement input.",
+          "description": "Move focus to one per-site input: a probing measurement (pocket depth, recession) or the bleeding or plaque checkbox.",
           "descriptionKey": "ui.agent.periodontalChart.actions.focusSite"
         },
         {
@@ -14400,7 +14828,7 @@
         {
           "name": "isOpen",
           "type": "boolean",
-          "description": "Whether the time popover is open. TimePicker has no popover of its own; always false.",
+          "description": "Whether the time dropdown is open. Always false unless the picker has the dropdown prop.",
           "descriptionKey": "ui.agent.timePicker.state.isOpen"
         }
       ],
@@ -14443,13 +14871,13 @@
         {
           "name": "open",
           "safety": "read",
-          "description": "No-op: TimePicker has no popover of its own.",
+          "description": "Open the time dropdown without moving focus. A no-op unless the picker has the dropdown prop and is enabled.",
           "descriptionKey": "ui.agent.timePicker.actions.open"
         },
         {
           "name": "close",
           "safety": "read",
-          "description": "No-op: TimePicker has no popover of its own.",
+          "description": "Close the time dropdown. A no-op unless the picker has the dropdown prop.",
           "descriptionKey": "ui.agent.timePicker.actions.close"
         }
       ],
@@ -15890,6 +16318,136 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "voice-control-panel",
+      "capabilities": [
+        "capture",
+        "pick",
+        "expand",
+        "open",
+        "close"
+      ],
+      "state": [
+        {
+          "name": "status",
+          "type": "'idle' | 'starting' | 'listening' | 'paused' | 'error'",
+          "description": "Where the host voice session is: idle, starting, listening, paused or error.",
+          "descriptionKey": "ui.agent.voiceControlPanel.state.status"
+        },
+        {
+          "name": "candidateIds",
+          "type": "string[]",
+          "description": "Ids of the matches currently offered, in spoken order (option 1 first). Empty when there is nothing to choose.",
+          "descriptionKey": "ui.agent.voiceControlPanel.state.candidateIds"
+        },
+        {
+          "name": "commandsOpen",
+          "type": "boolean",
+          "description": "True when the voice commands list is expanded.",
+          "descriptionKey": "ui.agent.voiceControlPanel.state.commandsOpen"
+        },
+        {
+          "name": "panelOpen",
+          "type": "boolean",
+          "description": "Floating layout: true when the panel above the pill is open. Always false inline.",
+          "descriptionKey": "ui.agent.voiceControlPanel.state.panelOpen"
+        }
+      ],
+      "actions": [
+        {
+          "name": "start_listening",
+          "safety": "write",
+          "idempotent": true,
+          "openWorld": true,
+          "errors": [
+            "Microphone permission denied",
+            "Speech service unavailable"
+          ],
+          "description": "Ask the host to start listening (it opens the microphone). Does nothing when already starting or listening, or while the panel is disabled.",
+          "descriptionKey": "ui.agent.voiceControlPanel.actions.startListening"
+        },
+        {
+          "name": "stop_listening",
+          "safety": "write",
+          "idempotent": true,
+          "description": "Ask the host to stop listening, or to cancel a start. Does nothing when not starting or listening.",
+          "descriptionKey": "ui.agent.voiceControlPanel.actions.stopListening"
+        },
+        {
+          "name": "pick_candidate",
+          "safety": "phi",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "One of the ids in the candidateIds state slot."
+              }
+            },
+            "required": [
+              "id"
+            ],
+            "additionalProperties": false
+          },
+          "examples": [
+            {
+              "args": {
+                "id": "otve"
+              },
+              "note": "Pick the match with id otve."
+            }
+          ],
+          "description": "Pick one of the offered matches by id, the same as saying its option number or pressing it. Unknown ids are ignored.",
+          "descriptionKey": "ui.agent.voiceControlPanel.actions.pickCandidate"
+        },
+        {
+          "name": "open_commands",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Expand the voice commands list.",
+          "descriptionKey": "ui.agent.voiceControlPanel.actions.openCommands"
+        },
+        {
+          "name": "close_commands",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Collapse the voice commands list.",
+          "descriptionKey": "ui.agent.voiceControlPanel.actions.closeCommands"
+        },
+        {
+          "name": "open_panel",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Floating layout: open the panel above the pill. Does nothing inline.",
+          "descriptionKey": "ui.agent.voiceControlPanel.actions.openPanel"
+        },
+        {
+          "name": "close_panel",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Floating layout: close the panel above the pill. Listening carries on. Does nothing inline.",
+          "descriptionKey": "ui.agent.voiceControlPanel.actions.closePanel"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "voice-control-panel",
+          "description": "Marks the VoiceControlPanel root."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop on VoiceControlPanel."
+        },
+        "item": {
+          "attr": "data-candidate-id",
+          "description": "On each match button, the candidate id that pick_candidate takes."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "wallet-pay-button",
@@ -19036,8 +19594,8 @@
         },
         {
           "name": "retry",
-          "safety": "read",
-          "description": "Try the failed page again (`data-action=\"retry\"`). By default this reloads the page.",
+          "safety": "write",
+          "description": "Try again (`data-action=\"retry\"`). By default this reloads the page. Inside an app the host may handle it instead and send the failed request again, such as a booking confirmation, so it counts as a write.",
           "descriptionKey": "ui.agent.errorPage.workflows.retry",
           "uiActions": [],
           "apiActions": []
@@ -19056,6 +19614,10 @@
           "component": "alert",
           "as": "formError"
         },
+        {
+          "component": "error-summary",
+          "as": "errorSummary"
+        },
         {
           "component": "alert",
           "as": "confirmation"
@@ -19077,7 +19639,7 @@
         {
           "name": "read_form",
           "safety": "read",
-          "description": "Read where the request stands. The root carries `data-state`: `asking` while the form shows, `sent` once the confirmation has taken its place (`data-slot=\"confirmation\"`). While asking, the email sits in `data-field=\"email\"`, with `aria-invalid=\"true\"` on its control and its message in a `role=\"alert\"` element when it has a problem; a message about the whole request is in `data-field=\"form\"`. The confirmation is the same for every address: it does not say whether an account exists.",
+          "description": "Read where the request stands. The root carries `data-state`: `asking` while the form shows, `sent` once the confirmation has taken its place (`data-slot=\"confirmation\"`). While asking, the email sits in `data-field=\"email\"`, with `aria-invalid=\"true\"` on its control and its message in a `data-slot=\"error\"` element when it has a problem, also listed in `data-component=\"error-summary\"` after a refused submit; a message about the whole request is in `data-field=\"form\"`. The confirmation is the same for every address: it does not say whether an account exists.",
           "descriptionKey": "ui.agent.forgotPasswordForm.workflows.readForm",
           "uiActions": [],
           "apiActions": []
@@ -19341,6 +19903,10 @@
           "component": "alert",
           "as": "formError"
         },
+        {
+          "component": "error-summary",
+          "as": "errorSummary"
+        },
         {
           "component": "form-field",
           "as": "field"
@@ -19366,7 +19932,7 @@
         {
           "name": "read_form",
           "safety": "read",
-          "description": "Read the sign-in form and what is wrong with it. Each field sits in a wrapper with `data-field` (`email`, `password`). A field with a problem has `aria-invalid=\"true\"` on its control and its message in a `role=\"alert\"` element inside the wrapper. A message about the whole form, such as a refused sign-in, is in `data-field=\"form\"`; it never says which of the two values was wrong. Never read or repeat the password.",
+          "description": "Read the sign-in form and what is wrong with it. Each field sits in a wrapper with `data-field` (`email`, `password`). A field with a problem has `aria-invalid=\"true\"` on its control and its message in a `data-slot=\"error\"` element inside the wrapper. After a refused submit the fields with a problem are also listed in `data-component=\"error-summary\"` at the top of the form, one item per field (`data-error-field`). A message about the whole form, such as a refused sign-in, is in `data-field=\"form\"`; it never says which of the two values was wrong. Never read or repeat the password.",
           "descriptionKey": "ui.agent.loginForm.workflows.readForm",
           "uiActions": [],
           "apiActions": []
@@ -19374,7 +19940,7 @@
         {
           "name": "sign_in",
           "safety": "write",
-          "description": "Sign in (`data-action=\"submit\"`). The person types the email and the password themselves; the form does not submit until the email is a valid address and the password is not empty, and moves focus to the first field that is not. The host then signs the person in: through its `onSubmit` handler, or as a native form post to its own field names.",
+          "description": "Sign in (`data-action=\"submit\"`). The person types the email and the password themselves; the form does not submit until the email is a valid address and the password is not empty; it lists what is wrong in its error summary and moves focus there. The host then signs the person in: through its `onSubmit` handler, or as a native form post to its own field names.",
           "descriptionKey": "ui.agent.loginForm.workflows.signIn",
           "uiActions": [],
           "apiActions": [
@@ -21396,6 +21962,10 @@
           "component": "alert",
           "as": "formError"
         },
+        {
+          "component": "error-summary",
+          "as": "errorSummary"
+        },
         {
           "component": "form-field",
           "as": "field"
@@ -21453,7 +22023,7 @@
         {
           "name": "read_form",
           "safety": "read",
-          "description": "Read which fields the form asks for and which have a problem. The host picks the fields, so read them from the page: each one that shows sits in a wrapper with `data-field`. A field with a problem has `aria-invalid=\"true\"` on its control and its message in a `role=\"alert\"` element inside the wrapper. A message about the whole form is in `data-field=\"form\"`. An email the person cannot change is marked `readonly`. Never read or repeat the password fields.",
+          "description": "Read which fields the form asks for and which have a problem. The host picks the fields, so read them from the page: each one that shows sits in a wrapper with `data-field`. A field with a problem has `aria-invalid=\"true\"` on its control and its message in a `data-slot=\"error\"` element inside the wrapper. After a refused submit the fields with a problem are also listed in `data-component=\"error-summary\"` at the top of the form, one item per field (`data-error-field`). A message about the whole form is in `data-field=\"form\"`. An email the person cannot change is marked `readonly`. Never read or repeat the password fields.",
           "descriptionKey": "ui.agent.registrationForm.workflows.readForm",
           "uiActions": [],
           "apiActions": []
@@ -21461,7 +22031,7 @@
         {
           "name": "register",
           "safety": "write",
-          "description": "Create the account (`data-action=\"submit\"`). The person fills in the fields and accepts the terms themselves; the form does not submit until every field is valid, and moves focus to the first one that is not. The host then registers the account: through its `onSubmit` handler, or as a native form post to its own field names.",
+          "description": "Create the account (`data-action=\"submit\"`). The person fills in the fields and accepts the terms themselves; the form does not submit until every field is valid; it lists what is wrong in its error summary and moves focus there. The host then registers the account: through its `onSubmit` handler, or as a native form post to its own field names.",
           "descriptionKey": "ui.agent.registrationForm.workflows.register",
           "uiActions": [],
           "apiActions": [