@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

package/dist/collection/components/wm-action-menu/wm-action-menu.js

@@ -1,5 +1,93 @@
 import { h, Host } from "@stencil/core";
 import { debounce, getTextDir, hideTooltip, showTooltip, findAllScrollableParents } from "../../global/functions";
+/**
+ * Dropdown interface that displays a list of action items. When closed it shows a text
+ * button, icon button, or selector box depending on action-menu-type. Selecting an item
+ * executes an action and closes the menu. Composed of a parent wm-action-menu element and
+ * one or more wm-menuitem children.
+ *
+ * @slot - One or more wm-menuitem elements.
+ *
+ * @keyboardInteraction
+ * - **Trigger button (closed)**: Down Arrow / Space / Enter opens the menu and focuses the first item; Up Arrow opens and focuses the last item.
+ * - **Open menu**: Up/Down Arrow navigates items (wraps around); Home/End jumps to first/last; Enter activates the focused item and closes the menu; Escape closes the menu and returns focus to the trigger; Tab closes the menu; typing a character focuses the next item starting with that letter.
+ *
+ * @accessibility
+ * - For `icon` menus, `tooltip` is required and serves as the accessible name announced by screen readers.
+ * - When multiple action menus share identical tooltips or button text, use `label-for-identical-buttons` to give each a unique `aria-label`.
+ * - Focus returns automatically to the trigger button after an item is activated, unless the action removes the trigger from the DOM — in that case, manage focus explicitly in your action handler.
+ *
+ * @usageNotes
+ * - The default type is `icon` (three-dot "more options" button). Use `text` for a labelled trigger, `selector` or `selector-primary` for a select-box appearance.
+ * - `button-text` is required when `action-menu-type` is `text`, `selector`, or `selector-primary`.
+ * - `tooltip` is required when `action-menu-type` is `icon`.
+ *
+ * @example {html} Icon action menu (default)
+ * <wm-action-menu tooltip="More options">
+ *   <wm-menuitem>Edit</wm-menuitem>
+ *   <wm-menuitem>Delete</wm-menuitem>
+ * </wm-action-menu>
+ *
+ * @example {react} Icon action menu
+ * <WmActionMenu tooltip="More options">
+ *   <WmMenuitem>Edit</WmMenuitem>
+ *   <WmMenuitem>Delete</WmMenuitem>
+ * </WmActionMenu>
+ *
+ * @example {html} Text action menu
+ * <wm-action-menu action-menu-type="text" button-text="Actions">
+ *   <wm-menuitem>Edit</wm-menuitem>
+ *   <wm-menuitem>Delete</wm-menuitem>
+ * </wm-action-menu>
+ *
+ * @example {react} Text action menu
+ * <WmActionMenu actionMenuType="text" buttonText="Actions">
+ *   <WmMenuitem>Edit</WmMenuitem>
+ *   <WmMenuitem>Delete</WmMenuitem>
+ * </WmActionMenu>
+ *
+ * @example {html} Selector action menu
+ * <wm-action-menu action-menu-type="selector" button-text="Sort by">
+ *   <wm-menuitem>Name</wm-menuitem>
+ *   <wm-menuitem>Date</wm-menuitem>
+ * </wm-action-menu>
+ *
+ * @example {react} Selector action menu
+ * <WmActionMenu actionMenuType="selector" buttonText="Sort by">
+ *   <WmMenuitem>Name</WmMenuitem>
+ *   <WmMenuitem>Date</WmMenuitem>
+ * </WmActionMenu>
+ *
+ * @example {html} Menu items with icons
+ * <wm-action-menu tooltip="File actions">
+ *   <wm-menuitem icon="#edit">Edit</wm-menuitem>
+ *   <wm-menuitem icon="#delete">Delete</wm-menuitem>
+ * </wm-action-menu>
+ *
+ * @example {react} Menu items with icons
+ * <WmActionMenu tooltip="File actions">
+ *   <WmMenuitem icon="#edit">Edit</WmMenuitem>
+ *   <WmMenuitem icon="#delete">Delete</WmMenuitem>
+ * </WmActionMenu>
+ *
+ * @example {html} Identical menus — disambiguate for screen readers with label-for-identical-buttons
+ * <wm-action-menu tooltip="Actions" label-for-identical-buttons="Actions for Introduction to Biology">
+ *   <wm-menuitem>Edit</wm-menuitem>
+ * </wm-action-menu>
+ * <wm-action-menu tooltip="Actions" label-for-identical-buttons="Actions for Advanced Chemistry">
+ *   <wm-menuitem>Edit</wm-menuitem>
+ * </wm-action-menu>
+ *
+ * @example {react} Identical menus
+ * <WmActionMenu tooltip="Actions" labelForIdenticalButtons="Actions for Introduction to Biology">
+ *   <WmMenuitem>Edit</WmMenuitem>
+ * </WmActionMenu>
+ * <WmActionMenu tooltip="Actions" labelForIdenticalButtons="Actions for Advanced Chemistry">
+ *   <WmMenuitem>Edit</WmMenuitem>
+ * </WmActionMenu>
+ *
+ * @category Basic Controls
+ */
 export class ActionMenu {
     constructor() {
         this.openUp = false;
@@ -335,7 +423,7 @@ export class ActionMenu {
         return null;
     }
     render() {
-        return (h(Host, { key: '089e41398162bb653228788b4317049cde90677a', onBlur: () => this.close(false) }, h("div", { key: '8bf71c94ed904f5c4308b30aaba78910622918ec', class: getTextDir() }, h("button", { key: 'e907d5dbb4c76d9c1dcc4099b3f79faec27f4bdd', ref: (el) => (this.menubtnEl = el), id: "menubtn", class: `wm-button -${this.internalButtonType}${this.darkMode ? " dark" : ""}${this.isTabbing ? " user-is-tabbing" : ""}`, disabled: this.disabled, "aria-label": this.internalButtonType === "icononly"
+        return (h(Host, { key: '19a7b9bbd017ed6100d605c56d497f99084bdadc', onBlur: () => this.close(false) }, h("div", { key: '02352c77a57c3811d5bc66be6eeed8ebdf413aa9', class: getTextDir() }, h("button", { key: '070cea3ac5da73352e952b87d342d4b98716346b', ref: (el) => (this.menubtnEl = el), id: "menubtn", class: `wm-button -${this.internalButtonType}${this.darkMode ? " dark" : ""}${this.isTabbing ? " user-is-tabbing" : ""}`, disabled: this.disabled, "aria-label": this.internalButtonType === "icononly"
                 ? this.labelForIdenticalButtons || this.tooltip
                 : this.labelForIdenticalButtons || undefined, "aria-expanded": this.isExpanded ? "true" : "false", "aria-haspopup": "menu", popoverTarget: "menu", popoverTargetAction: "toggle", onMouseEnter: () => this.actionMenuType === "icon" &&
                 showTooltip(this.tooltipPosition || this.horizontalPosition, this.menubtnEl, this.tooltip), onMouseLeave: () => hideTooltip(), onFocus: () => this.isTabbing &&
@@ -343,9 +431,9 @@ export class ActionMenu {
                 showTooltip(this.tooltipPosition || this.horizontalPosition, this.menubtnEl, this.tooltip), onBlur: (ev) => {
                 hideTooltip();
                 this.handleButtonBlur(ev);
-            } }, this.actionMenuType === "icon" && (h("span", { key: 'bd615c986c40863c73a2ec9f060fc5b596e7d64f', class: "svg-icon svg-more-options", style: { "--icon-size": "24px" } })), this.actionMenuType !== "icon" && h("span", { key: '27ad43a2bc951784d313f08b210c1092f2adda55', class: "button-text" }, this.buttonText), (this.actionMenuType === "selector" || this.actionMenuType === "selector-primary") && (h("div", { key: '54184d0f5faa1bd80eddc76127d4173f3dacb7ca', class: "selector-icon svg-icon svg-expand-more" }))), h("div", { key: '7f34d1d1527b5b65f512fe636aa243ef06c2ae61', class: `dropdown ${this.isExpanded ? "is-open" : ""} ${this.isHidden ? "hidden" : ""} ${this.openUp ? "open-up" : ""} ${this.horizontalPosition}`, id: "menu", popover: "auto", tabindex: -1, role: "menu", ref: (el) => (this.dropdownEl = el),
+            } }, this.actionMenuType === "icon" && (h("span", { key: '24f876ff7aba8a8f0628c768fd7a3cae4c6b13c1', class: "svg-icon svg-more-options", style: { "--icon-size": "24px" } })), this.actionMenuType !== "icon" && h("span", { key: 'dfe646329373fe5839fba003ec15f3345982097e', class: "button-text" }, this.buttonText), (this.actionMenuType === "selector" || this.actionMenuType === "selector-primary") && (h("div", { key: '8872e66a185503cd1f6fc298e3fb2e28e67d1ae6', class: "selector-icon svg-icon svg-expand-more" }))), h("div", { key: 'a6b8ecffdf3c9886e0b01d4783b22403b2d7c724', class: `dropdown ${this.isExpanded ? "is-open" : ""} ${this.isHidden ? "hidden" : ""} ${this.openUp ? "open-up" : ""} ${this.horizontalPosition}`, id: "menu", popover: "auto", tabindex: -1, role: "menu", ref: (el) => (this.dropdownEl = el),
             // @ts-ignore -- don't tell typescript but we're in the future
-            onToggle: (ev) => this.handleToggle(ev) }, h("slot", { key: 'de4af1e89a98621b4093089e70f7b0c02b759cb2' })))));
+            onToggle: (ev) => this.handleToggle(ev) }, h("slot", { key: '3d0b49daa3f5c2c62edb3582a0de2f53888ff2e8' })))));
     }
     static get is() { return "wm-action-menu"; }
     static get encapsulation() { return "shadow"; }
@@ -373,7 +461,13 @@ export class ActionMenu {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Position of the tooltip relative to the trigger button. Repositions automatically when there is insufficient space at the specified position."
+                        }, {
+                            "name": "default",
+                            "text": "\"left\""
+                        }],
                     "text": ""
                 },
                 "attribute": "tooltip-position",
@@ -390,7 +484,13 @@ export class ActionMenu {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Visual style of the trigger button. `'icon'` shows an icon-only button (requires `tooltip`). `'text'` shows a labelled button (requires `button-text`). `'selector'` shows a selector box that visually mimics a select control (requires `button-text`). `'selector-primary'` is a primary-styled variant of selector."
+                        }, {
+                            "name": "default",
+                            "text": "\"icon\""
+                        }],
                     "text": ""
                 },
                 "attribute": "action-menu-type",
@@ -408,7 +508,13 @@ export class ActionMenu {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Label displayed on the trigger button."
+                        }, {
+                            "name": "conditionallyRequired",
+                            "text": "when action-menu-type is 'text', 'selector', or 'selector-primary'"
+                        }],
                     "text": ""
                 },
                 "attribute": "button-text",
@@ -425,7 +531,13 @@ export class ActionMenu {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Disables the entire menu, preventing the trigger from being activated."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "disabled",
@@ -443,7 +555,13 @@ export class ActionMenu {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Tooltip text shown on hover. For `icon` menus, also serves as the accessible name announced by screen readers."
+                        }, {
+                            "name": "conditionallyRequired",
+                            "text": "when action-menu-type is 'icon'"
+                        }],
                     "text": ""
                 },
                 "attribute": "tooltip",
@@ -460,7 +578,10 @@ export class ActionMenu {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Use only when multiple action menus on the same page share identical tooltips or button text. Set this to a more descriptive label for screen readers; the visible label stays unchanged. Sets aria-label to this value."
+                        }],
                     "text": ""
                 },
                 "attribute": "label-for-identical-buttons",
@@ -477,7 +598,13 @@ export class ActionMenu {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Applies dark styling to `selector` and `selector-primary` variants. Has no effect on `icon` or `text` types."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "dark-mode",
@@ -500,7 +627,10 @@ export class ActionMenu {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the component finishes loading and child wm-menuitem elements are ready."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -515,7 +645,13 @@ export class ActionMenu {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the component finishes loading."
+                        }, {
+                            "name": "deprecated",
+                            "text": "Use wmActionMenuLoaded instead."
+                        }],
                     "text": ""
                 },
                 "complexType": {

package/dist/collection/components/wm-button/wm-button.js

@@ -1,6 +1,125 @@
 import { h, Host } from "@stencil/core";
 import { getIconCodeFromName } from "../../global/interfaces";
 import { generateId, hideTooltip, handleDisabledAttribute, showTooltip, toBool, triggerFormSubmit, } from "../../global/functions";
+/**
+ * Interactive button element that triggers actions and workflows. Has seven visual
+ * types plus AI variants.
+ *
+ * @slot - Button label text. Required for all types. For `icononly` and `navigational`
+ *   buttons, slotted text is not rendered visually but is used as the accessible name
+ *   when no `tooltip` or `label-for-identical-buttons` is provided.
+ *
+ * @keyboardInteraction Enter - Fires a click event on the button (mirrors native button behavior).
+ *
+ * @accessibility
+ * `aria-label` resolution order (highest priority first):
+ * 1. `aria-label-passthrough`
+ * 2. `label-for-identical-buttons` (or `tooltip` for icononly/navigational types)
+ * 3. Nothing set — browser derives the label from visible text or slotted content
+ *
+ * `aria-expanded` — set via `aria-expanded-passthrough` (not directly on `<wm-button>`).
+ * `aria-haspopup="menu"` — applied automatically when the host element has an `aria-haspopup` attribute.
+ *
+ * @usageNotes
+ * - **primary**: Use sparingly — ideally once per page or section — for the single most
+ *   important action.
+ * - **pairpositive / pairnegative**: Must always be used together for binary choices where
+ *   neither option is preferred (e.g. Approve / Reject). Do not use one without the other.
+ * - **AI variants** (`primary-ai`, `secondary-ai`, etc.): Do not set the `icon` prop —
+ *   the AI icon is applied automatically.
+ * - **icononly / navigational**: Both `icon` and `tooltip` are required.
+ *
+ * @example {html} Primary button — the preferred action on a page or section. Use once per context.
+ * <wm-button button-type="primary">Save changes</wm-button>
+ *
+ * @example {react} Primary button
+ * <WmButton buttonType="primary" onClick={handleSave}>Save changes</WmButton>
+ *
+ * @example {html} Primary and secondary pair — the most common pattern.
+ * <wm-button button-type="secondary">Cancel</wm-button>
+ * <wm-button button-type="primary">Save changes</wm-button>
+ *
+ * @example {react} Primary and secondary pair
+ * <WmButton buttonType="secondary" onClick={handleCancel}>Cancel</WmButton>
+ * <WmButton buttonType="primary" onClick={handleSave}>Save changes</WmButton>
+ *
+ * @example {html} Text-only button with icon
+ * <wm-button button-type="textonly" icon="#edit">Edit</wm-button>
+ *
+ * @example {react} Text-only button with icon
+ * <WmButton buttonType="textonly" icon="#edit">Edit</WmButton>
+ *
+ * @example {html} Icon-only button — icon, tooltip, and slot text are all required.
+ * <wm-button button-type="icononly" icon="#edit" tooltip="Edit record">Edit record</wm-button>
+ *
+ * @example {react} Icon-only button
+ * <WmButton buttonType="icononly" icon="#edit" tooltip="Edit record">Edit record</WmButton>
+ *
+ * @example {html} Icon-only button with local SVG sprite
+ * <wm-button button-type="icononly" icon="/assets/icons.svg#pencil" tooltip="Edit">Edit</wm-button>
+ *
+ * @example {html} Navigational button — for back/forward navigation in flyout panels.
+ * <wm-button button-type="navigational" icon="#arrow-back" tooltip="Back">Back</wm-button>
+ *
+ * @example {react} Navigational button
+ * <WmButton buttonType="navigational" icon="#arrow-back" tooltip="Back">Back</WmButton>
+ *
+ * @example {html} Positive/negative pair — binary choice, neither option preferred. Must be used as a pair.
+ * <wm-button button-type="pairnegative">Reject</wm-button>
+ * <wm-button button-type="pairpositive">Approve</wm-button>
+ *
+ * @example {react} Positive/negative pair
+ * <WmButton buttonType="pairnegative" onClick={handleReject}>Reject</WmButton>
+ * <WmButton buttonType="pairpositive" onClick={handleApprove}>Approve</WmButton>
+ *
+ * @example {html} Permanently delete — danger styling for irreversible destructive actions only.
+ * <wm-button button-type="primary" permanently-delete="true">Delete account</wm-button>
+ *
+ * @example {react} Permanently delete
+ * <WmButton buttonType="primary" permanentlyDelete={true}>Delete account</WmButton>
+ *
+ * @example {html} Disabled button
+ * <wm-button button-type="primary" disabled="true">Save</wm-button>
+ *
+ * @example {react} Disabled button
+ * <WmButton buttonType="primary" disabled={true}>Save</WmButton>
+ *
+ * @example {html} Form submit button — use is-submit instead of a native type=submit button.
+ * <form>
+ *   <wm-button button-type="primary" is-submit="true">Submit</wm-button>
+ * </form>
+ *
+ * @example {react} Form submit button
+ * <WmButton buttonType="primary" isSubmit={true}>Submit</WmButton>
+ *
+ * @example {html} Button on dark background
+ * <wm-button button-type="secondary" custom-background="dark">Continue</wm-button>
+ *
+ * @example {react} Button on dark background
+ * <WmButton buttonType="secondary" customBackground="dark">Continue</WmButton>
+ *
+ * @example {html} AI primary button — icon is applied automatically, do not set icon prop.
+ * <wm-button button-type="primary-ai">Generate summary</wm-button>
+ *
+ * @example {react} AI primary button
+ * <WmButton buttonType="primary-ai">Generate summary</WmButton>
+ *
+ * @example {html} Rotated icon — reuse directional icons with icon-rotate.
+ * <wm-button button-type="icononly" icon="#arrow-back" icon-rotate="180" tooltip="Forward">Forward</wm-button>
+ *
+ * @example {react} Rotated icon
+ * <WmButton buttonType="icononly" icon="#arrow-back" iconRotate={180} tooltip="Forward">Forward</WmButton>
+ *
+ * @example {html} Identical buttons — use label-for-identical-buttons to disambiguate for screen readers.
+ * <wm-button button-type="secondary" label-for-identical-buttons="Edit course: Introduction to Biology">Edit</wm-button>
+ * <wm-button button-type="secondary" label-for-identical-buttons="Edit course: Advanced Chemistry">Edit</wm-button>
+ *
+ * @example {react} Identical buttons
+ * <WmButton buttonType="secondary" labelForIdenticalButtons="Edit course: Introduction to Biology">Edit</WmButton>
+ * <WmButton buttonType="secondary" labelForIdenticalButtons="Edit course: Advanced Chemistry">Edit</WmButton>
+ *
+ * @category Basic Controls
+ */
 export class Button {
     constructor() {
         this.id = generateId();
@@ -256,7 +375,7 @@ export class Button {
         }
     }
     render() {
-        return (h(Host, { key: 'bfc5c1c1b69619258f1a15003de34a9884f5b09e', class: `${this.isDisabled ? "button-disabled" : ""} -${this.buttonType}` }, h("button", { key: '647328418473ec98db1fff54403a5915a8354668', id: this.id, class: `${this.buttonClasses}`, disabled: this.isDisabled, ref: (el) => (this.buttonEl = el), "aria-label": this.getAriaLabel(), "aria-expanded": this.isAriaExpanded !== undefined ? this.isAriaExpanded.toString() : undefined, "aria-hasPopup": this.ariaPopup ? "menu" : null, onMouseEnter: (ev) => this.handleMouseEnter(ev), onMouseLeave: () => hideTooltip(), onFocus: (ev) => this.handleFocus(ev), onBlur: () => hideTooltip(), onClick: () => hideTooltip() }, this.icon && this.renderIcon(), !this.buttonType.startsWith("navigational") && !this.buttonType.startsWith("icononly") && (h("span", { key: '1f27aeed2c3e7f87d326c6da318f08be083c873e', class: "button-text" }, h("slot", { key: '6cce46f476c7d20aa3c48fa1e87edd495398d5c3' }))), (this.buttonType == "selector" || this.buttonType == "selector-primary") && (h("div", { key: '305255c0423d2971932f3f8ccc2170075aa4dd53', class: "selector-icon svg-icon svg-expand-more" })))));
+        return (h(Host, { key: '76a5421d00532673476644aae829a5e4c1705b1f', class: `${this.isDisabled ? "button-disabled" : ""} -${this.buttonType}` }, h("button", { key: '576012f5b0262fb6ca7dd435e869c4276cc0da06', id: this.id, class: `${this.buttonClasses}`, disabled: this.isDisabled, ref: (el) => (this.buttonEl = el), "aria-label": this.getAriaLabel(), "aria-expanded": this.isAriaExpanded !== undefined ? this.isAriaExpanded.toString() : undefined, "aria-hasPopup": this.ariaPopup ? "menu" : null, onMouseEnter: (ev) => this.handleMouseEnter(ev), onMouseLeave: () => hideTooltip(), onFocus: (ev) => this.handleFocus(ev), onBlur: () => hideTooltip(), onClick: () => hideTooltip() }, this.icon && this.renderIcon(), !this.buttonType.startsWith("navigational") && !this.buttonType.startsWith("icononly") && (h("span", { key: '2c6548c3708dc18fec38d43dbf75583a0e254cf0', class: "button-text" }, h("slot", { key: '07f076ee9011eb1294315b29cdbb350e8e55270f' }))), (this.buttonType == "selector" || this.buttonType == "selector-primary") && (h("div", { key: '0332bc4f94a44c5b973cee95da7065a05803d0b7', class: "selector-icon svg-icon svg-expand-more" })))));
     }
     static get is() { return "wm-button"; }
     static get encapsulation() { return "shadow"; }
@@ -284,7 +403,13 @@ export class Button {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Disables the button, preventing interaction and applying disabled styling."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "disabled",
@@ -308,7 +433,13 @@ export class Button {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Visual style of the button. 'primary' for the single preferred action (use sparingly, ideally once per page/section). 'secondary' for other actions, often alongside a primary. 'textonly' for low-emphasis actions. 'icononly' requires icon and tooltip. 'navigational' for icon-only back/forward navigation (e.g. flyout back button). 'pairpositive' and 'pairnegative' must be used together for binary choices (neither is preferred, e.g. Approve/Reject). AI variants apply AI styling automatically \u2014 do not set the icon property on AI types. 'selector' and 'selector-primary' are internal types used by wm-select \u2014 do not use directly."
+                        }, {
+                            "name": "default",
+                            "text": "\"secondary\""
+                        }],
                     "text": ""
                 },
                 "attribute": "button-type",
@@ -326,7 +457,13 @@ export class Button {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Icon to display. Required when button-type is 'icononly' or 'navigational'. Formats: '#icon-name' for a commonly-used Ripple icon (e.g. '#edit', '#add-person'), '/path/to/file.svg#symbol-id' for a local SVG sprite symbol, or an MDI character code like 'f3eb' (deprecated). Do not set on AI button types \u2014 their icon is applied automatically."
+                        }, {
+                            "name": "conditionallyRequired",
+                            "text": "when button-type is 'icononly' or 'navigational' (conditionallyRequired means that the prop is required, but only if the button-type is 'icononly' or 'navigational')"
+                        }],
                     "text": ""
                 },
                 "attribute": "icon",
@@ -343,7 +480,10 @@ export class Button {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Overrides the default icon size. Accepts any valid CSS size value, e.g. '22px' or '1.3rem'."
+                        }],
                     "text": ""
                 },
                 "attribute": "icon-size",
@@ -360,7 +500,10 @@ export class Button {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Rotates the icon by the given number of degrees. For use with the icon property."
+                        }],
                     "text": ""
                 },
                 "attribute": "icon-rotate",
@@ -377,7 +520,10 @@ export class Button {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Flips the icon along the specified axis. For use with the icon property."
+                        }],
                     "text": ""
                 },
                 "attribute": "icon-flip",
@@ -394,7 +540,13 @@ export class Button {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Tooltip text displayed on hover."
+                        }, {
+                            "name": "conditionallyRequired",
+                            "text": "when button-type is 'icononly' or 'navigational' (conditionallyRequired means that the prop is required, but only if the button-type is 'icononly' or 'navigational')"
+                        }],
                     "text": ""
                 },
                 "attribute": "tooltip",
@@ -411,7 +563,13 @@ export class Button {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Accessibility prop. Use ONLY when multiple buttons on the same page share identical visible text or identical tooltips. Set this to a more descriptive label for screen readers; leave the visible button text or tooltip unchanged. Sets aria-label to this value."
+                        }, {
+                            "name": "conditionallyRequired",
+                            "text": "when multiple buttons on the same page share identical visible text or identical tooltips (conditionallyRequired means that the prop is required, but only if multiple buttons on the same page share identical visible text or identical tooltips)"
+                        }],
                     "text": ""
                 },
                 "attribute": "label-for-identical-buttons",
@@ -434,7 +592,13 @@ export class Button {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Position of the tooltip relative to the button. If there is insufficient space at the specified position, the component repositions automatically."
+                        }, {
+                            "name": "default",
+                            "text": "\"bottom-right\""
+                        }],
                     "text": ""
                 },
                 "attribute": "tooltip-position",
@@ -452,7 +616,13 @@ export class Button {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Applies danger/destructive styling to the button. Use sparingly and only for irreversible destructive actions (e.g. permanently deleting an account or record). Applied as a modifier \u2014 not a separate button-type."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "permanently-delete",
@@ -470,7 +640,13 @@ export class Button {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "For 'textonly' buttons only. When false, text is truncated with an ellipsis and a tooltip reveals the full text on hover."
+                        }, {
+                            "name": "default",
+                            "text": "true"
+                        }],
                     "text": ""
                 },
                 "attribute": "text-wrap",
@@ -488,7 +664,10 @@ export class Button {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Set to 'dark' to render button styles appropriate for a dark background surface."
+                        }],
                     "text": ""
                 },
                 "attribute": "custom-background",
@@ -505,7 +684,13 @@ export class Button {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "When true, the button submits its containing form. Equivalent to type=\"submit\" on a native button element."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "is-submit",
@@ -523,8 +708,11 @@ export class Button {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the button's `aria-label`. Takes priority over `label-for-identical-buttons` and over\nthe label automatically derived from `tooltip` for `icononly` and `navigational` buttons. Use\nthis prop instead of setting `aria-label` directly on `<wm-button>`."
+                    "tags": [{
+                            "name": "description",
+                            "text": "Sets the button's `aria-label`. Takes priority over `label-for-identical-buttons` and over\nthe label automatically derived from `tooltip` for `icononly` and `navigational` buttons. Use\nthis prop instead of setting `aria-label` directly on `<wm-button>`."
+                        }],
+                    "text": ""
                 },
                 "attribute": "aria-label-passthrough",
                 "reflect": false
@@ -540,8 +728,14 @@ export class Button {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
-                    "text": "Sets the button's `aria-expanded` attribute. Use on buttons that toggle a disclosure region,\nmenu, popover, or dialog. Use this prop instead of setting `aria-expanded` directly on\n`<wm-button>`."
+                    "tags": [{
+                            "name": "description",
+                            "text": "Sets the button's `aria-expanded` attribute. Use on buttons that toggle a disclosure region,\nmenu, popover, or dialog. Use this prop instead of setting `aria-expanded` directly on\n`<wm-button>`."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
                 },
                 "attribute": "aria-expanded-passthrough",
                 "reflect": false