@alfadocs/ui-kit 1.4.17 → 1.6.0

package/dist/agent-catalog.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "packageVersion": "1.4.17",
+  "packageVersion": "1.6.0",
   "components": [
     {
       "kind": "component",
@@ -10081,6 +10081,38 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "practice-profile-hero",
+      "capabilities": [],
+      "state": [
+        {
+          "name": "name",
+          "type": "string",
+          "description": "Practice display name currently rendered.",
+          "descriptionKey": "ui.agent.practiceProfileHero.state.name"
+        },
+        {
+          "name": "hasCover",
+          "type": "boolean",
+          "description": "Whether a cover-image strip is rendered. Structural flag only — never the image URL or any PHI.",
+          "descriptionKey": "ui.agent.practiceProfileHero.state.hasCover"
+        }
+      ],
+      "actions": [],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "practice-profile-hero",
+          "description": "Marks the PracticeProfileHero root region."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "practice-results",
@@ -14120,20 +14152,155 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "tooth-finding-palette",
+      "capabilities": [
+        "pick",
+        "select_single",
+        "set_value"
+      ],
+      "state": [
+        {
+          "name": "activeFinding",
+          "type": "string | null",
+          "description": "Id of the armed finding tool, or null when no tool is selected. Identifies a finding TYPE — never a patient, and never a charted finding.",
+          "descriptionKey": "ui.agent.toothFindingPalette.state.activeFinding"
+        },
+        {
+          "name": "status",
+          "type": "string",
+          "description": "Execution status the next charted finding takes — 'planned' or 'executed'.",
+          "descriptionKey": "ui.agent.toothFindingPalette.state.status"
+        },
+        {
+          "name": "tools",
+          "type": "string[]",
+          "description": "Every finding id the palette currently offers, in render order — built-ins plus any practice-defined ids. The authoritative vocabulary for select_finding.",
+          "descriptionKey": "ui.agent.toothFindingPalette.state.tools"
+        }
+      ],
+      "actions": [
+        {
+          "name": "select_finding",
+          "safety": "read",
+          "argsType": "{ condition: ConditionId }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "condition": {
+                "type": "string",
+                "description": "Finding id — either a built-in condition (the enum on tooth-scheme's set_finding: caries, filled, crowned, rootCanal, implant, …) or a practice-defined id supplied through the conditionRegistry prop. Read the live list from the `tools` state slot rather than guessing."
+              }
+            },
+            "required": [
+              "condition"
+            ]
+          },
+          "idempotent": true,
+          "errors": [
+            "The condition is not among the palette's tools — read the \"tools\" state slot for the live list."
+          ],
+          "examples": [
+            {
+              "args": {
+                "condition": "caries"
+              },
+              "note": "Arm the caries tool before marking a decayed surface."
+            }
+          ],
+          "description": "Arm a finding tool, so the next tooth (or surface, or root) picked on the paired dental chart records that finding.",
+          "descriptionKey": "ui.agent.toothFindingPalette.actions.selectFinding"
+        },
+        {
+          "name": "clear_selection",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Disarm the palette so clicks on the chart stop recording a finding. Charted findings are untouched.",
+          "descriptionKey": "ui.agent.toothFindingPalette.actions.clearSelection"
+        },
+        {
+          "name": "set_status",
+          "safety": "write",
+          "argsType": "{ status: SymbolStatus }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "status": {
+                "enum": [
+                  "planned",
+                  "executed"
+                ],
+                "description": "Execution status the next charted finding takes — 'planned' (proposed treatment) or 'executed' (work already carried out)."
+              }
+            },
+            "required": [
+              "status"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "status": "executed"
+              },
+              "note": "Record the next finding as work already carried out."
+            }
+          ],
+          "description": "Choose whether the next charted finding is recorded as planned or executed.",
+          "descriptionKey": "ui.agent.toothFindingPalette.actions.setStatus"
+        },
+        {
+          "name": "focus_tool",
+          "safety": "read",
+          "argsType": "{ condition: ConditionId }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "condition": {
+                "type": "string",
+                "description": "Finding id — either a built-in condition (the enum on tooth-scheme's set_finding: caries, filled, crowned, rootCanal, implant, …) or a practice-defined id supplied through the conditionRegistry prop. Read the live list from the `tools` state slot rather than guessing."
+              }
+            },
+            "required": [
+              "condition"
+            ]
+          },
+          "idempotent": true,
+          "description": "Move keyboard focus to a tool without arming it — relocates the toolbar's single roving tab stop.",
+          "descriptionKey": "ui.agent.toothFindingPalette.actions.focusTool"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "tooth-finding-palette",
+          "description": "Marks the palette toolbar wrapper."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop. Required to address a specific palette from the agent."
+        },
+        "item": {
+          "attr": "data-condition",
+          "description": "Each tool button emits its finding id as data-condition, and the armed tool also carries data-active=\"true\". Group wrappers carry data-group with the group id; the planned/executed pills carry data-status."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "tooth-scheme",
       "capabilities": [
         "pick",
         "set_value",
-        "edit_inline",
-        "view_change"
+        "edit_inline"
       ],
       "state": [
         {
           "name": "chart",
-          "type": "object",
-          "description": "Current dental chart — findings (and marked surfaces) keyed by FDI id, or by a special-element id (quadrant / sextant / arch / general) for region-spanning findings.",
+          "type": "Record<FdiId, { conditions: ToothCondition[]; surfaces: Surface[]; symbols: { id?: string; condition: ConditionId; part?: SymbolPart; surfaces?: Surface[]; roots?: Root[]; status?: SymbolStatus; color?: string }[] }>",
+          "description": "Current dental chart keyed by FDI id, or by a special-element id (quadrant / sextant / arch / general) for region-spanning findings. Each entry carries the flat `conditions` + `surfaces` pair AND the normalised per-symbol list, where every finding scopes its own surfaces, roots, planned/executed status and colour. Free-text clinical notes are PHI and omitted — read them per tooth via get_symbols / get_notes.",
           "descriptionKey": "ui.agent.toothScheme.state.chart"
         },
         {
@@ -14173,6 +14340,9 @@
             ]
           },
           "idempotent": true,
+          "errors": [
+            "In the `both` view the registered instance renders no SVG of its own (the four sub-charts do, and deliberately do not register), so this action has no effect there."
+          ],
           "description": "Move focus to a specific tooth by FDI id.",
           "descriptionKey": "ui.agent.toothScheme.actions.focusTooth"
         },
@@ -14207,14 +14377,141 @@
                 "implantExtraction",
                 "stub",
                 "destroyed",
-                "rootCanal"
-              ]
+                "rootCanal",
+                "pin",
+                "rootAmputation",
+                "anchorage",
+                "hook",
+                "attachment",
+                "mucogingivalSurgery",
+                "periodontalSurgery",
+                "curettage",
+                "medication",
+                "xray"
+              ],
+              "description": "Built-in finding id. 'destroyed' is the retained root (*radice persistente*); 'xray' is the chartable radiograph SYMBOL, distinct from the image archive reached via get_radiographs."
             }
           },
           "idempotent": true,
-          "description": "Read the findings recorded on one tooth (FDI id).",
+          "description": "Read the BUILT-IN findings recorded on one tooth (FDI id), as a flat list of condition ids. Practice-defined findings, per-finding surfaces, roots and status are not included — use get_symbols for the tooth's full record.",
           "descriptionKey": "ui.agent.toothScheme.actions.getTooth"
         },
+        {
+          "name": "get_symbols",
+          "safety": "phi",
+          "argsType": "{ id: FdiId }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary) or a special-element id ('Q1'–'Q4' quadrants, 'S1'–'S6' sextants, 'AS'/'AI' arches, 'general'; primary mirrors with an 'm' prefix)."
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "returns": "ToothSymbol[]",
+          "returnsSchema": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "Provenance id — the host's care-plan / finding entry this symbol came from. Present on symbols the host seeded; supply it to update that exact entry."
+                },
+                "condition": {
+                  "type": "string",
+                  "description": "Finding id — either a built-in (the enum on set_finding) or a practice-defined id from the host's `conditionRegistry`."
+                },
+                "part": {
+                  "enum": [
+                    "element",
+                    "surface",
+                    "root"
+                  ],
+                  "description": "Anatomical layer the finding marks. Omit to take the condition's natural part (caries and fillings are 'surface', root canals are 'root', crowns and implants are 'element')."
+                },
+                "surfaces": {
+                  "type": "array",
+                  "items": {
+                    "enum": [
+                      "mesial",
+                      "distal",
+                      "occlusal",
+                      "buccal",
+                      "lingual"
+                    ],
+                    "description": "Tooth surface, named anatomically."
+                  }
+                },
+                "roots": {
+                  "type": "array",
+                  "items": {
+                    "enum": [
+                      "mesial",
+                      "distal",
+                      "palatal",
+                      "buccal",
+                      "single"
+                    ],
+                    "description": "Root, named ANATOMICALLY (not by screen side) — 'palatal' exists only on upper molars, 'single' covers every one-rooted tooth. On flank-mounted markers (anchorage, hook) 'mesial' / 'distal' select the side of the tooth instead."
+                  }
+                },
+                "status": {
+                  "enum": [
+                    "planned",
+                    "executed"
+                  ],
+                  "description": "Execution status — 'planned' (proposed treatment) vs 'executed' (already done). Omit when the finding carries no plan/executed distinction."
+                },
+                "color": {
+                  "type": "string",
+                  "description": "Per-practice colour override — a CSS colour or `var(--token)`. Omit to take the condition's own colour."
+                },
+                "note": {
+                  "type": "string",
+                  "description": "Free-text clinical note. PHI — never in a state snapshot."
+                }
+              },
+              "required": [
+                "condition"
+              ]
+            }
+          },
+          "idempotent": true,
+          "description": "Read one tooth's full finding record (incl. notes) — one entry per symbol, each with its own surfaces, roots, planned/executed status, colour override, provenance id and free-text note. Normalised, so a tooth charted with the flat conditions/surfaces pair reports the same shape.",
+          "descriptionKey": "ui.agent.toothScheme.actions.getSymbols"
+        },
+        {
+          "name": "get_notes",
+          "safety": "phi",
+          "argsType": "{ id: FdiId }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary) or a special-element id ('Q1'–'Q4' quadrants, 'S1'–'S6' sextants, 'AS'/'AI' arches, 'general'; primary mirrors with an 'm' prefix)."
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "returns": "string | null",
+          "returnsSchema": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "idempotent": true,
+          "description": "Read the tooth-level free-text clinical note, or null when there is none. Per-finding notes are separate — they come back from get_symbols.",
+          "descriptionKey": "ui.agent.toothScheme.actions.getNotes"
+        },
         {
           "name": "teeth_with",
           "safety": "read",
@@ -14234,8 +14531,19 @@
                   "implantExtraction",
                   "stub",
                   "destroyed",
-                  "rootCanal"
-                ]
+                  "rootCanal",
+                  "pin",
+                  "rootAmputation",
+                  "anchorage",
+                  "hook",
+                  "attachment",
+                  "mucogingivalSurgery",
+                  "periodontalSurgery",
+                  "curettage",
+                  "medication",
+                  "xray"
+                ],
+                "description": "Built-in finding id. 'destroyed' is the retained root (*radice persistente*); 'xray' is the chartable radiograph SYMBOL, distinct from the image archive reached via get_radiographs."
               }
             },
             "required": [
@@ -14251,12 +14559,40 @@
             }
           },
           "idempotent": true,
-          "description": "List the ids carrying a given finding — FDI tooth ids and/or special-element ids (e.g. all teeth with caries).",
+          "description": "List the ids carrying a given built-in finding — FDI tooth ids and/or special-element ids (e.g. all teeth with caries). For a practice-defined finding use teeth_with_symbol.",
           "descriptionKey": "ui.agent.toothScheme.actions.teethWith"
         },
         {
-          "name": "get_radiographs",
+          "name": "teeth_with_symbol",
           "safety": "read",
+          "argsType": "{ condition: ConditionId }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "condition": {
+                "type": "string",
+                "description": "Finding id — either a built-in (the enum on set_finding) or a practice-defined id from the host's `conditionRegistry`."
+              }
+            },
+            "required": [
+              "condition"
+            ]
+          },
+          "returns": "FdiId[]",
+          "returnsSchema": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary) or a special-element id ('Q1'–'Q4' quadrants, 'S1'–'S6' sextants, 'AS'/'AI' arches, 'general'; primary mirrors with an 'm' prefix)."
+            }
+          },
+          "idempotent": true,
+          "description": "As teeth_with, but open to the practice-defined ids in the host's `conditionRegistry` as well as the built-ins.",
+          "descriptionKey": "ui.agent.toothScheme.actions.teethWithSymbol"
+        },
+        {
+          "name": "get_radiographs",
+          "safety": "phi",
           "argsType": "{ id: FdiId }",
           "argsSchema": {
             "type": "object",
@@ -14311,7 +14647,7 @@
             }
           },
           "idempotent": true,
-          "description": "Read the radiographs (x-rays) attached to one tooth.",
+          "description": "Read the radiographs (x-rays) attached to one tooth, including their notes, dates and image urls.",
           "descriptionKey": "ui.agent.toothScheme.actions.getRadiographs"
         },
         {
@@ -14331,6 +14667,9 @@
             ]
           },
           "idempotent": true,
+          "errors": [
+            "In the `both` view the registered instance renders no SVG of its own (the four sub-charts do, and deliberately do not register), so this action has no effect there."
+          ],
           "description": "Focus a tooth and open its radiograph archive (fires the host's onOpenRadiographs).",
           "descriptionKey": "ui.agent.toothScheme.actions.openRadiographs"
         },
@@ -14357,8 +14696,19 @@
                   "implantExtraction",
                   "stub",
                   "destroyed",
-                  "rootCanal"
-                ]
+                  "rootCanal",
+                  "pin",
+                  "rootAmputation",
+                  "anchorage",
+                  "hook",
+                  "attachment",
+                  "mucogingivalSurgery",
+                  "periodontalSurgery",
+                  "curettage",
+                  "medication",
+                  "xray"
+                ],
+                "description": "Built-in finding id. 'destroyed' is the retained root (*radice persistente*); 'xray' is the chartable radiograph SYMBOL, distinct from the image archive reached via get_radiographs."
               },
               "surfaces": {
                 "type": "array",
@@ -14369,7 +14719,8 @@
                     "occlusal",
                     "buccal",
                     "lingual"
-                  ]
+                  ],
+                  "description": "Tooth surface, named anatomically."
                 }
               }
             },
@@ -14379,9 +14730,123 @@
             ]
           },
           "idempotent": true,
-          "description": "Record a finding on a tooth or region element (crown, implant, root canal, caries, …). Optionally mark the affected surfaces for a surface finding.",
+          "description": "Record a built-in finding on a tooth or region element (crown, implant, root canal, caries, …). Optionally mark the affected surfaces for a surface finding. Structural only — to set a finding’s roots, planned/executed status, colour or note, or to chart a practice-defined finding, use set_symbol.",
           "descriptionKey": "ui.agent.toothScheme.actions.setFinding"
         },
+        {
+          "name": "set_symbol",
+          "safety": "phi",
+          "argsType": "{ id: FdiId; symbol: ToothSymbol }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary) or a special-element id ('Q1'–'Q4' quadrants, 'S1'–'S6' sextants, 'AS'/'AI' arches, 'general'; primary mirrors with an 'm' prefix)."
+              },
+              "symbol": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "description": "Provenance id — the host's care-plan / finding entry this symbol came from. Present on symbols the host seeded; supply it to update that exact entry."
+                  },
+                  "condition": {
+                    "type": "string",
+                    "description": "Finding id — either a built-in (the enum on set_finding) or a practice-defined id from the host's `conditionRegistry`."
+                  },
+                  "part": {
+                    "enum": [
+                      "element",
+                      "surface",
+                      "root"
+                    ],
+                    "description": "Anatomical layer the finding marks. Omit to take the condition's natural part (caries and fillings are 'surface', root canals are 'root', crowns and implants are 'element')."
+                  },
+                  "surfaces": {
+                    "type": "array",
+                    "items": {
+                      "enum": [
+                        "mesial",
+                        "distal",
+                        "occlusal",
+                        "buccal",
+                        "lingual"
+                      ],
+                      "description": "Tooth surface, named anatomically."
+                    }
+                  },
+                  "roots": {
+                    "type": "array",
+                    "items": {
+                      "enum": [
+                        "mesial",
+                        "distal",
+                        "palatal",
+                        "buccal",
+                        "single"
+                      ],
+                      "description": "Root, named ANATOMICALLY (not by screen side) — 'palatal' exists only on upper molars, 'single' covers every one-rooted tooth. On flank-mounted markers (anchorage, hook) 'mesial' / 'distal' select the side of the tooth instead."
+                    }
+                  },
+                  "status": {
+                    "enum": [
+                      "planned",
+                      "executed"
+                    ],
+                    "description": "Execution status — 'planned' (proposed treatment) vs 'executed' (already done). Omit when the finding carries no plan/executed distinction."
+                  },
+                  "color": {
+                    "type": "string",
+                    "description": "Per-practice colour override — a CSS colour or `var(--token)`. Omit to take the condition's own colour."
+                  },
+                  "note": {
+                    "type": "string",
+                    "description": "Free-text clinical note. PHI — never in a state snapshot."
+                  }
+                },
+                "required": [
+                  "condition"
+                ]
+              }
+            },
+            "required": [
+              "id",
+              "symbol"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "id": "16",
+                "symbol": {
+                  "condition": "filled",
+                  "surfaces": [
+                    "mesial"
+                  ],
+                  "status": "executed"
+                }
+              },
+              "note": "Record an executed mesial filling on tooth 16, leaving any other finding on that tooth untouched."
+            },
+            {
+              "args": {
+                "id": "26",
+                "symbol": {
+                  "condition": "rootCanal",
+                  "roots": [
+                    "palatal"
+                  ],
+                  "status": "planned"
+                }
+              },
+              "note": "Plan a root canal on the palatal root of tooth 26 ('palatal' is the anatomical root, not a screen side)."
+            }
+          ],
+          "description": "Add or replace one finding on a tooth or region element, with its own part, surfaces, roots, planned/executed status, colour override and note. Matched by `symbol.id` when the symbol carries provenance, otherwise by its condition; appended when nothing matches. Accepts practice-defined `conditionRegistry` ids as well as the built-ins.",
+          "descriptionKey": "ui.agent.toothScheme.actions.setSymbol"
+        },
         {
           "name": "remove_finding",
           "safety": "write",
@@ -14405,8 +14870,19 @@
                   "implantExtraction",
                   "stub",
                   "destroyed",
-                  "rootCanal"
-                ]
+                  "rootCanal",
+                  "pin",
+                  "rootAmputation",
+                  "anchorage",
+                  "hook",
+                  "attachment",
+                  "mucogingivalSurgery",
+                  "periodontalSurgery",
+                  "curettage",
+                  "medication",
+                  "xray"
+                ],
+                "description": "Built-in finding id. 'destroyed' is the retained root (*radice persistente*); 'xray' is the chartable radiograph SYMBOL, distinct from the image archive reached via get_radiographs."
               }
             },
             "required": [
@@ -14415,7 +14891,7 @@
             ]
           },
           "idempotent": true,
-          "description": "Remove a single finding from a tooth.",
+          "description": "Remove a finding from a tooth — every symbol carrying that condition goes, whatever its surfaces or roots. Built-in ids only.",
           "descriptionKey": "ui.agent.toothScheme.actions.removeFinding"
         },
         {
@@ -14451,7 +14927,7 @@
         },
         "item": {
           "attr": "data-fdi",
-          "description": "Each rendered tooth `<g>` carries its FDI id as `data-fdi`; selectable special-element slots carry their id there too (plus `data-special` naming the kind). The `data-projection` / `data-view-mode` attributes on the root expose the side/plan/both view."
+          "description": "Each rendered tooth `<g>` carries its FDI id as `data-fdi`, its first finding as `data-condition`, the full space-separated list as `data-conditions`, the finding count as `data-symbol-count` and the first finding's status as `data-status`; selectable special-element slots carry their id in `data-fdi` too (plus `data-special` naming the kind). Per-surface pick targets carry `data-zone`, per-root pick targets `data-root` (the anatomical root name). The `data-projection` / `data-view-mode` attributes on the root expose the side/plan/both view."
         }
       }
     },
@@ -19120,41 +19596,6 @@
         }
       ]
     },
-    {
-      "kind": "pattern",
-      "id": "practice-profile-hero",
-      "composes": [
-        {
-          "component": "card",
-          "as": "heroCard"
-        },
-        {
-          "component": "avatar",
-          "as": "practiceAvatar"
-        },
-        {
-          "component": "rating",
-          "as": "reviewSummary"
-        },
-        {
-          "component": "badge",
-          "as": "trustBadge",
-          "entity": "practice"
-        }
-      ],
-      "workflows": [
-        {
-          "name": "view_profile",
-          "safety": "read",
-          "description": "Read the practice's public profile summary — name, tagline, average rating, review count, and trust badges.",
-          "descriptionKey": "ui.agent.practiceProfileHero.workflows.viewProfile",
-          "uiActions": [],
-          "apiActions": [
-            "practice.getProfile"
-          ]
-        }
-      ]
-    },
     {
       "kind": "pattern",
       "id": "prenota",