@kerfjs/ui 5.0.0-beta.54 → 5.0.0-beta.55

package/README.md

@@ -184,6 +184,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `ToolbarControlGroup`, `ToolbarActionLink`                          | `@kerfjs/ui/toolbar-control-group`      | `@kerfjs/ui/toolbar-control-group.css` |
 | `DialogSurface`, `PopupSurface`                                     | `@kerfjs/ui/surface-scaffold`           | `@kerfjs/ui/surface-scaffold.css`      |
 | `FloatingToolbar`                                                   | `@kerfjs/ui/floating-toolbar`           | `@kerfjs/ui/floating-toolbar.css`      |
+| `PopupMenu` (register with `@kerfjs/ui/popup-menu/register`)        | `@kerfjs/ui/popup-menu`                 | `@kerfjs/ui/popup-menu.css`            |
 | `ToolbarText`                                                       | `@kerfjs/ui/toolbar-text`               | `@kerfjs/ui/toolbar-text.css`          |
 | `Text`                                                              | `@kerfjs/ui/text`                       | `@kerfjs/ui/text.css`                  |
 | `List`                                                              | `@kerfjs/ui/list`                       | `@kerfjs/ui/list.css`                  |
@@ -246,7 +247,7 @@ onto another trailing-aligned row under every `responsive` policy, and a
 same way. Wrapping keeps every command visible at its full 44px target without
 moving focus or DOM identity. When a product wants fewer visible commands at
 narrow widths, it chooses them: render a lower-priority command inside an
-app-owned "More" popup menu (a `single` group around a `wa-dropdown`).
+app-owned "More" `PopupMenu` (in a `single` group with `nestedDropdown`).
 
 `DisclosureArrow` defaults to an 18px root-scaled decorative visual. Override
 `--kui-disclosure-arrow-size` at the narrowest useful scope when a consumer
@@ -645,7 +646,7 @@ import "@kerfjs/ui/webawesome.css";
 import "@kerfjs/ui/select/register";
 ```
 
-That boundary keeps Web Awesome and its custom-element side effects out of bundles that use unrelated components. Automated consumer-bundle tests enforce it.
+That boundary keeps Web Awesome and its custom-element side effects out of bundles that use unrelated components. Automated consumer-bundle tests enforce it. `PopupMenu` follows the same rule: import `@kerfjs/ui/popup-menu/register` once to register the dropdown, item, button, and divider elements it renders.
 Use `label` for a visible label or `ariaLabel` for a visually hidden name. A
 nonempty visible label takes precedence when both are supplied. Kerf names the
 actual shadow combobox without adding visible label spacing; this also works

package/ai/component-catalog-v2.json

@@ -1007,7 +1007,8 @@
           "--kui-workbench-overlay-max-width",
           "--kui-workbench-overlay-max-height",
           "--kui-workbench-restore-inset",
-          "--kui-workbench-restore-z"
+          "--kui-workbench-restore-z",
+          "--kui-workbench-overlay-dismiss-margin"
         ]
       },
       "diagnostics": [],
@@ -3055,6 +3056,62 @@
         "composition": "README.md#web-awesome-theme"
       }
     },
+    {
+      "key": "@kerfjs/ui:popup-menu",
+      "package": "@kerfjs/ui",
+      "id": "popup-menu",
+      "name": "PopupMenu",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "commands and their delegated actions",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "which items are enabled",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "reactions to the menu opening or closing",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["controls"],
+        "geometry": { "margin": "none", "border": "child", "padding": "child" }
+      },
+      "accessibility": {
+        "obligations": [
+          "An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. Web Awesome provides menu roles, arrow-key navigation, typeahead, and Escape."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": "kui-popup-menu",
+        "publicClasses": ["kui-popup-menu", "kui-popup-menu__label"],
+        "publicTokens": []
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:feedback",
       "package": "@kerfjs/ui",

package/ai/component-catalog.json

@@ -917,8 +917,14 @@
       "purpose": "Arrange a complex tool or editor as a stable central work area with optional peripheral rails and a bottom drawer.",
       "publicExports": [
         "Workbench",
+        "WorkbenchChromePlacement",
+        "WorkbenchCompactOverlay",
+        "WorkbenchMainBottomToolbar",
+        "WorkbenchMainToolbar",
         "WorkbenchPanel",
         "WorkbenchPanelResizable",
+        "WorkbenchPanelToggle",
+        "WorkbenchPanelToolbar",
         "WorkbenchProps",
         "WorkbenchResponsiveOverlayAt"
       ],
@@ -1025,7 +1031,8 @@
         "--kui-workbench-overlay-max-width",
         "--kui-workbench-overlay-max-height",
         "--kui-workbench-restore-inset",
-        "--kui-workbench-restore-z"
+        "--kui-workbench-restore-z",
+        "--kui-workbench-overlay-dismiss-margin"
       ],
       "links": {
         "catalogRoute": "?component=workbench",
@@ -1047,10 +1054,14 @@
       "publicExports": [
         "CollapsiblePanelSide",
         "collapsiblePanelToggleIcon",
+        "CollapsiblePanelToolbarToggle",
+        "CollapsiblePanelToolbar",
         "CollapsiblePanelToggleProps",
         "CollapsiblePanelToggle",
         "CollapsiblePanelProps",
-        "CollapsiblePanel"
+        "CollapsiblePanel",
+        "CollapsiblePanelRelocatedProps",
+        "CollapsiblePanelRelocated"
       ],
       "useWhen": [
         "An application needs one collapsible side rail or bottom drawer outside a full Workbench.",
@@ -3333,6 +3344,7 @@
         "tokens",
         "query execution",
         "results",
+        "the revision that rebuilds the DOM-owned editor for a programmatic text replacement",
         "optional override of the collapsible expand/collapse/focus, which wireTokenSearchFields manages by default (adopt an app expanded signal, opt out per behavior, or drive it via the returned handle)"
       ],
       "variants": [
@@ -3678,6 +3690,85 @@
         "recipe": "docs/component-selection.md#web-awesome-overlap-policy"
       }
     },
+    {
+      "id": "popup-menu",
+      "name": "PopupMenu",
+      "category": "Controls",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A trigger button that opens a typed list of commands, built on the Web Awesome dropdown.",
+      "uses": [
+        "wa-dropdown",
+        "wa-dropdown-item",
+        "wa-button",
+        "wa-divider"
+      ],
+      "purpose": "A trigger button that opens a typed list of commands, built on the Web Awesome dropdown.",
+      "publicExports": [
+        "PopupMenu"
+      ],
+      "useWhen": [
+        "Offer a short list of commands behind one trigger, such as a toolbar sort or More menu.",
+        "Group related commands under headings and dividers in one popup."
+      ],
+      "avoidWhen": [
+        "Do not use it to choose a persistent value (use Select) or for navigation rows (use ListItem).",
+        "Do not hand-write wa-dropdown / wa-dropdown-item markup for an action menu; use PopupMenu."
+      ],
+      "alternatives": [
+        {
+          "id": "select",
+          "relationship": "nearest"
+        },
+        {
+          "id": "wa-dropdown",
+          "relationship": "prefer-over"
+        }
+      ],
+      "appOwns": [
+        "commands and their delegated actions",
+        "which items are enabled",
+        "reactions to the menu opening or closing"
+      ],
+      "variants": [
+        "icon trigger",
+        "text trigger",
+        "icon and text trigger",
+        "headings and dividers",
+        "item icons",
+        "disabled items",
+        "placement"
+      ],
+      "accessibility": [
+        "An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. Web Awesome provides menu roles, arrow-key navigation, typeahead, and Escape."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "child",
+        "padding": "child"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/popup-menu",
+        "manualCssImport": "@kerfjs/ui/popup-menu.css",
+        "registrationImport": "@kerfjs/ui/popup-menu/register",
+        "themeCssImport": "@kerfjs/ui/webawesome.css",
+        "sideEffects": [
+          "browser-condition-css",
+          "custom-element-registration"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-popup-menu",
+        "kui-popup-menu__label"
+      ],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=popup-menu",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#web-awesome-overlap-policy"
+      }
+    },
     {
       "id": "feedback",
       "name": "Feedback",
@@ -4330,6 +4421,10 @@
       ],
       "recommendation": "conditional",
       "alternatives": [
+        {
+          "id": "popup-menu",
+          "relationship": "prefer-kerf"
+        },
         {
           "id": "select",
           "relationship": "prefer-kerf"
@@ -4373,6 +4468,10 @@
       ],
       "recommendation": "conditional",
       "alternatives": [
+        {
+          "id": "popup-menu",
+          "relationship": "prefer-kerf"
+        },
         {
           "id": "select",
           "relationship": "prefer-kerf"
@@ -6941,16 +7040,14 @@
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
-      "purpose": "Toolbar, navigation, content, and inspector shell with controlled resizing and explicit pane scroll owners.",
+      "purpose": "App bar above a Workbench with resizable navigation and inspector rails, relocated rail toggles, narrow-container overlays, and explicit pane scroll owners.",
       "uses": [
         "pane",
         "toolbar",
         "toolbar-text",
         "toolbar-control-group",
-        "row",
-        "grid",
-        "resize",
-        "list-header",
+        "workbench",
+        "list",
         "list-item",
         "value-table",
         "lucide-icon",
@@ -7075,7 +7172,7 @@
       "category": "Recipes",
       "kind": "recipe",
       "source": "kerf",
-      "purpose": "Production modal whose labeled Web Awesome header frames a SplitView record list and ValueTable detail, becoming a full-screen drill-down on compact devices.",
+      "purpose": "Production modal laid out as a workbench: a full-height SplitView list sidebar with its own toolbar beside a full-height detail column that carries the primary title, close control, and record actions; a full-screen drill-down on compact devices.",
       "uses": [
         "surface-scaffold",
         "split-view",