@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

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

@@ -1,6 +1,79 @@
 import { h, Host } from "@stencil/core";
 import { generateId, hideTooltip, intl, showTooltip } from "../../global/functions";
 import { globalMessages } from "../../global/intl";
+/**
+ * Toast notification stack that renders transient messages at the bottom of the page.
+ * Notifications auto-dismiss after 6 seconds unless they include a `link` or `action`, in
+ * which case they persist until explicitly dismissed or the user tabs past them.
+ *
+ * @keyboardInteraction
+ * - **Tab**: Moves focus from the action link/button to the close button; tabbing past the
+ *   close button dismisses the notification and returns focus to the previously active element.
+ * - **Shift+Tab**: Dismisses the notification from the action link and returns focus; moves
+ *   from the close button back to the action link.
+ * - **Enter**: Activates the focused close button or action link/button.
+ *
+ * @accessibility
+ * - Renders an `aria-live` region that announces new notification messages to screen readers.
+ * - When a notification includes a `link` or `action` and the user is navigating by keyboard,
+ *   focus moves automatically to the action element when the notification appears.
+ * - Focus returns to the previously active element when the notification is dismissed.
+ *
+ * @usageNotes
+ * - `notifications` is typed as a string — always pass `JSON.stringify(array)` in both HTML
+ *   and React. Passing an array directly causes a "[object Object] is not valid JSON" error.
+ * - Each notification object requires a unique `id` (string) and a `message` (string).
+ *   Optional fields: `link` (string, renders a navigation anchor), `action` (string, renders
+ *   a button), `newWindow` (boolean, adds an "opens in new window" indicator to the link).
+ * - Use `link` for navigation actions and `action` for in-page triggers such as "Undo" —
+ *   both emit `wmSnackbarActionTriggered` when clicked.
+ * - Listen to `wmSnackbarSnackFinished` and remove the matching notification from your array
+ *   to keep state in sync. The 6-second auto-dismiss timer is disabled for notifications
+ *   with a `link` or `action` — remove them manually after the action is handled.
+ * - `wmSnackbarSnackFinished` detail: `{ id: string }`.
+ * - `wmSnackbarActionTriggered` detail: `{ id: string, message: string, action?: string, link?: string }`.
+ *
+ * @example {html} Simple notification
+ * <wm-snackbar notifications='[{"id":"1","message":"Changes saved."}]'></wm-snackbar>
+ *
+ * @example {react} Notification stack with action and link variants
+ * // notifications is typed as string — always pass JSON.stringify(array), never the array directly.
+ * // wmSnackbarSnackFinished fires when a notification auto-dismisses or is closed.
+ * // wmSnackbarActionTriggered fires when the action button or link is clicked;
+ * // remove the notification manually after handling the action.
+ * let nextId = 1;
+ * const [notifications, setNotifications] = useState([]);
+ *
+ * const addNotification = (notification) =>
+ *   setNotifications((prev) => [...prev, { id: String(nextId++), ...notification }]);
+ *
+ * const removeNotification = (id) =>
+ *   setNotifications((prev) => prev.filter((n) => n.id !== id));
+ *
+ * const handleActionTriggered = (e) => {
+ *   const { id, action } = e.detail;
+ *   if (action === "Undo") { handleUndo(); }
+ *   removeNotification(id);
+ * };
+ *
+ * <WmButton buttonType="secondary" onClick={() => addNotification({ message: "Changes saved." })}>
+ *   Simple notification
+ * </WmButton>
+ * <WmButton buttonType="secondary" onClick={() => addNotification({ message: "Item deleted.", action: "Undo" })}>
+ *   With action
+ * </WmButton>
+ * <WmButton buttonType="secondary" onClick={() => addNotification({ message: "Report ready.", link: "#report" })}>
+ *   With link
+ * </WmButton>
+ *
+ * <WmSnackbar
+ *   notifications={JSON.stringify(notifications)}
+ *   onWmSnackbarSnackFinished={(e) => removeNotification(e.detail.id)}
+ *   onWmSnackbarActionTriggered={handleActionTriggered}
+ * />
+ *
+ * @category Communication
+ */
 export class Snackbar {
     constructor() {
         this.parsedNotifications = [];
@@ -149,11 +222,11 @@ export class Snackbar {
             }, onKeyDown: (ev) => ev.key === "Enter" && this.snackLinkClicked(notification) }, h("span", { "aria-hidden": "true" }, notification.link), notification.newWindow && h("div", { class: "svg-icon svg-open-in-new" }))), (!notification.link && notification.action) && (h("button", { id: `action-${notification.id}`, class: "link", onClick: () => this.snackLinkClicked(notification), onKeyDown: (ev) => ev.key === "Enter" && this.snackLinkClicked(notification) }, notification.action))), h("button", { id: `close-button-${notification.id}`, "aria-label": this.closeSnackMessage, class: "closesnack", tabindex: notification.link || notification.action ? 0 : -1, onClick: () => this.snackDismissed(notification), onMouseEnter: (ev) => showTooltip("bottom", ev.target, globalMessages.close), onMouseLeave: () => hideTooltip(), onFocus: (ev) => this.isTabbing && showTooltip("bottom", ev.target, globalMessages.close), onBlur: () => hideTooltip() }, h("div", { class: "svg-icon svg-close" }))), h("div", { class: "sr-only", tabindex: notification.link || notification.action ? 0 : -1, onFocus: () => (notification.link || notification.action) && this.snackDismissed(notification) })))));
     }
     render() {
-        return (h(Host, { key: '93b6fe6527a434f9639d914c5c835530144c60be' }, h("div", { key: '143acfd90a277c949e9ffbacbe5fc520572be1a7', ref: (el) => (this.snackAreaEl = el), class: {
+        return (h(Host, { key: 'f07da5e5b3f84c3204052cf37faa118c64ecfd45' }, h("div", { key: '9c76ca586e69af5035b086f023faa76aab39b239', ref: (el) => (this.snackAreaEl = el), class: {
                 "list-wrapper": true,
                 "user-is-tabbing": this.isTabbing,
                 empty: this.parsedNotifications.length == 0,
-            } }, this.renderSnackbars()), h("div", { key: '44196aa826573f4515efbf23735a1e5f7d663aa6', class: "sr-only", "aria-live": "polite", "aria-atomic": "false", id: `wm-live-region-${this.uid}`, ref: (el) => (this.liveRegionEl = el) }, this.announcement)));
+            } }, this.renderSnackbars()), h("div", { key: '6cc4cb95390ffccbd6e1f4ec535aed7774184c3a', class: "sr-only", "aria-live": "polite", "aria-atomic": "false", id: `wm-live-region-${this.uid}`, ref: (el) => (this.liveRegionEl = el) }, this.announcement)));
     }
     static get is() { return "wm-snackbar"; }
     static get encapsulation() { return "shadow"; }
@@ -180,7 +253,13 @@ export class Snackbar {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "JSON-encoded array of notification objects to display. Each object must\ninclude `id` (string) and `message` (string). Optional fields: `link` (string, renders\na navigation anchor), `action` (string, renders a button), `newWindow` (boolean, adds an\n\"opens in new window\" indicator to the link). Always pass as `JSON.stringify(array)` \u2014\npassing an array directly causes a \"[object Object] is not valid JSON\" error."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "notifications",
@@ -203,7 +282,13 @@ export class Snackbar {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when a notification should be removed \u2014 after the 6-second\nauto-dismiss timer expires or when the user clicks the close button. The host application\nshould remove the matching notification from its array. The timer is disabled for\nnotifications with a `link` or `action`."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ id: string, message: string, link?: string, newWindow?: boolean, action?: string }}"
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -223,7 +308,13 @@ export class Snackbar {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user clicks the `link` anchor or `action` button. The host\napplication should remove the notification and navigate (for links) or execute the action\n(for buttons)."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ id: string, message: string, link?: string, newWindow?: boolean, action?: string }}"
+                        }],
                     "text": ""
                 },
                 "complexType": {

package/dist/collection/components/wm-tabs/wm-tab-item/wm-tab-item.js

@@ -1,4 +1,21 @@
 import { h, Host } from "@stencil/core";
+/**
+ * Individual tab button inside a wm-tab-list. Renders as a link with `role="tab"` and
+ * manages selection state. Always used as a direct child of wm-tab-list.
+ *
+ * @slot - The visible label text for the tab.
+ *
+ * @usageNotes
+ * - `tab-id` is required and must match the `tab-id` of the corresponding wm-tab-panel.
+ * - Listen to `wmTabSelected` and update the `selected-tab` prop on the parent wm-tab-list
+ *   to switch the active tab and show the associated panel.
+ *
+ * @example {html} Tab item
+ * <wm-tab-item tab-id="overview">Overview</wm-tab-item>
+ *
+ * @example {react} Tab item
+ * <WmTabItem tabId="overview">Overview</WmTabItem>
+ */
 export class TabItem {
     constructor() {
         this.tabClicked = (ev) => {
@@ -27,9 +44,9 @@ export class TabItem {
     }
     render() {
         const isDark = this.parentTabList && this.parentTabList.customBackground == "dark";
-        return (h(Host, { key: '71b3f6dac339c5ece826133f01d6d5f05089456a', role: "presentation" }, h("li", { key: '0823dff1b7394d6bbc34a7d0d932fd19d7c6c8d0', class: `tab-item ${isDark ? "dark" : ""}`, role: "presentation" }, h("a", { key: '9ad3118a0f6bf6741e73e18a3a12d435c4676619', class: `tab`, role: "tab", ref: (el) => (this.linkEl = el), id: `tab-link-${this.tabId}`, onKeyDown: (ev) => this.tabPressed(ev), "aria-selected": this.selected ? "true" : "false", tabindex: this.selected ? 0 : -1, onClick: this.tabClicked, onFocus: () => {
+        return (h(Host, { key: '09406067cd1ae000a78ddff45e3db8041d599477', role: "presentation" }, h("li", { key: 'f0206a113c2604be1922316c8447622adac13009', class: `tab-item ${isDark ? "dark" : ""}`, role: "presentation" }, h("a", { key: 'a30638675f1e75fd13bc552c0a46589e7bf37b09', class: `tab`, role: "tab", ref: (el) => (this.linkEl = el), id: `tab-link-${this.tabId}`, onKeyDown: (ev) => this.tabPressed(ev), "aria-selected": this.selected ? "true" : "false", tabindex: this.selected ? 0 : -1, onClick: this.tabClicked, onFocus: () => {
                 this.wmIntTabFocused.emit({ tabItem: this.el });
-            } }, h("slot", { key: '64e9b75227c4294294635d49da0ad49b3c91d541' })))));
+            } }, h("slot", { key: '05aed02e5c3472ea6a19ff066225992e495572ad' })))));
     }
     static get is() { return "wm-tab-item"; }
     static get encapsulation() { return "shadow"; }
@@ -57,8 +74,14 @@ export class TabItem {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Indicates whether the tab is currently active"
+                    "tags": [{
+                            "name": "description",
+                            "text": "Whether this tab is currently active. Managed by the parent wm-tab-list \u2014\ndo not set manually."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
                 },
                 "attribute": "selected",
                 "reflect": false,
@@ -75,8 +98,14 @@ export class TabItem {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "The id of the tab, linked to a tab panel."
+                    "tags": [{
+                            "name": "description",
+                            "text": "Unique identifier linking this tab to its associated wm-tab-panel. Must\nmatch the `tab-id` on the corresponding wm-tab-panel."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
                 },
                 "attribute": "tab-id",
                 "reflect": false,
@@ -92,7 +121,13 @@ export class TabItem {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when this tab is clicked or activated by keyboard. Listen to this\nevent and update the `selected-tab` prop on the parent wm-tab-list to switch the active\ntab."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ tabId: string }} tabId \u2014 the `tab-id` of the activated tab."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -107,7 +142,13 @@ export class TabItem {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Internal signals consumed by wm-tab-list \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -127,7 +168,16 @@ export class TabItem {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Internal signals consumed by wm-tab-list \u2014 not for application use."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ tabItem: HTMLWmTabItemElement, key: string }} tabItem \u2014 the tab item that was focused.\nkey \u2014 the key that was pressed."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -147,7 +197,13 @@ export class TabItem {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Internal signals consumed by wm-tab-list \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {

package/dist/collection/components/wm-tabs/wm-tab-list/wm-tab-list.js

@@ -1,5 +1,90 @@
 import { h, Host } from "@stencil/core";
 import { debounce, intl } from "../../../global/functions";
+/**
+ * Tab list container that manages a group of wm-tab-item children and their associated
+ * wm-tab-panel elements. Handles keyboard navigation, ARIA wiring between tabs and panels,
+ * horizontal scroll with arrow buttons on overflow, and optional dark theme.
+ *
+ * @slot - One or more wm-tab-item elements.
+ *
+ * @keyboardInteraction
+ * - **Arrow Left / Arrow Right**: Cycles focus to the previous/next tab item; wraps at both ends.
+ * - **Arrow Down**: Moves focus to the content area of the active tab panel.
+ * - **Enter / Space**: Activates the focused tab and shows its panel.
+ * - **Tab**: Moves focus from the selected tab to the first focusable element inside the
+ *   active panel.
+ * - **Shift+Tab**: Moves focus back to the selected tab item from within the panel.
+ *
+ * @accessibility
+ * - Sets `aria-controls` on each wm-tab-item link pointing to its associated wm-tab-panel.
+ * - Sets `aria-labelledby` on each wm-tab-panel pointing back to its wm-tab-item link.
+ * - ARIA attributes are updated dynamically when tab content is conditionally rendered in a
+ *   single shared panel.
+ *
+ * @usageNotes
+ * - Set the container's width to 100% in most cases.
+ * - Two usage patterns:
+ *   1. **Discrete panels** — each wm-tab-item has a paired wm-tab-panel with the same `tab-id`.
+ *   2. **Single panel** — one wm-tab-panel; content is rendered conditionally based on the
+ *      selected tab; ARIA attributes are updated automatically.
+ * - Listen to `wmTabSelected` on wm-tab-item (or on the wm-tab-list, as the event bubbles) and
+ *   update `selected-tab` to switch the active tab.
+ * - Use `selected-tab` to control which tab is initially active by its `tab-id`.
+ *
+ * @example {html} Basic tabs (discrete panels)
+ * <wm-tab-list>
+ *   <wm-tab-item tab-id="overview">Overview</wm-tab-item>
+ *   <wm-tab-item tab-id="details">Details</wm-tab-item>
+ *   <wm-tab-item tab-id="history">History</wm-tab-item>
+ * </wm-tab-list>
+ * <wm-tab-panel tab-id="overview"><p>Overview content</p></wm-tab-panel>
+ * <wm-tab-panel tab-id="details"><p>Details content</p></wm-tab-panel>
+ * <wm-tab-panel tab-id="history"><p>History content</p></wm-tab-panel>
+ *
+ * @example {react} Basic tabs (discrete panels)
+ * // wmTabSelected fires when a tab is clicked or activated via keyboard.
+ * // event.detail is { tabId: string } -- the tab-id of the newly selected tab.
+ * const [selectedTab, setSelectedTab] = useState("overview");
+ *
+ * <WmTabList selectedTab={selectedTab} onWmTabSelected={(e) => setSelectedTab(e.detail.tabId)}>
+ *   <WmTabItem tabId="overview">Overview</WmTabItem>
+ *   <WmTabItem tabId="details">Details</WmTabItem>
+ *   <WmTabItem tabId="history">History</WmTabItem>
+ * </WmTabList>
+ * <WmTabPanel tabId="overview"><p>Overview content</p></WmTabPanel>
+ * <WmTabPanel tabId="details"><p>Details content</p></WmTabPanel>
+ * <WmTabPanel tabId="history"><p>History content</p></WmTabPanel>
+ *
+ * @example {html} Single shared panel (content rendered conditionally)
+ * <wm-tab-list custom-background="dark">
+ *   <wm-tab-item tab-id="summary">Summary</wm-tab-item>
+ *   <wm-tab-item tab-id="activity">Activity</wm-tab-item>
+ * </wm-tab-list>
+ * <wm-tab-panel tab-id="summary">
+ *   <!-- app renders content here based on the active tab -->
+ * </wm-tab-panel>
+ *
+ * @example {react} Single shared panel (content rendered conditionally)
+ * // One wm-tab-panel shared by all tabs -- ARIA attributes update automatically.
+ * // Render content conditionally based on selectedTab.
+ * const [selectedTab, setSelectedTab] = useState("summary");
+ *
+ * <WmTabList
+ *   customBackground="dark"
+ *   selectedTab={selectedTab}
+ *   onWmTabSelected={(e) => setSelectedTab(e.detail.tabId)}
+ * >
+ *   <WmTabItem tabId="summary">Summary</WmTabItem>
+ *   <WmTabItem tabId="activity">Activity</WmTabItem>
+ * </WmTabList>
+ * <WmTabPanel tabId="summary">
+ *   {selectedTab === "summary" && <p>Summary content</p>}
+ *   {selectedTab === "activity" && <p>Activity content</p>}
+ * </WmTabPanel>
+ *
+ * @category Navigation
+ * @displayName Tabs
+ */
 export class TabList {
     constructor() {
         this.debouncedUpdateContainerState = debounce(() => {
@@ -257,15 +342,15 @@ export class TabList {
         this.announcement = message;
     }
     render() {
-        return (h(Host, { key: 'e5437df047efe61428f2116cbcc9f94042dd84bc' }, h("div", { key: 'd933cd096869ca9d0808cbfcbacca30dfd89a1fc', class: "component-wrapper" }, h("wm-button", { key: '224781b9a7c43fa49ef403484416a6037190bb10', class: `left-arrow ${this.scrollArrowsVisible ? "visible" : ""}`, "aria-controls": "tablist", customBackground: this.customBackground, buttonType: "navigational", icon: "#previous", tooltip: intl.formatMessage({
+        return (h(Host, { key: '7c219aa329454ee23c71fb9190d86fd393e60c97' }, h("div", { key: '87caaf180bb566e91b1c27c42db0d2a63027f23f', class: "component-wrapper" }, h("wm-button", { key: 'cf22c79e116485ca31b7d1053296f504c5807b62', class: `left-arrow ${this.scrollArrowsVisible ? "visible" : ""}`, "aria-controls": "tablist", customBackground: this.customBackground, buttonType: "navigational", icon: "#previous", tooltip: intl.formatMessage({
                 id: "tabs.showPreviousTabs",
                 defaultMessage: "Show previous tabs",
                 description: "Tooltip for button scrolling tab group.",
-            }), onClick: (ev) => this.handleLeftArrowClick(ev) }), h("ul", { key: '8e826993aa2b0387587357b43250e20bda02acdf', id: "tablist", ref: (el) => (this.tabContainerEl = el), class: `tabcontainer ${this.customBackground || ""} ${this.containerFadeLeft ? "fade-left" : ""} ${this.containerFadeRight ? "fade-right" : ""}`, role: "tablist", tabIndex: -1 }, h("slot", { key: 'c17a7bc0e8fa17e9142de78713cfffa5b340dbb1' })), h("wm-button", { key: '651170ba9e2b4cd4d91256386032a780bfa3cdf2', class: `right-arrow ${this.scrollArrowsVisible ? "visible" : ""}`, "aria-controls": "tablist", customBackground: this.customBackground, buttonType: "navigational", icon: "#next", tooltip: intl.formatMessage({
+            }), onClick: (ev) => this.handleLeftArrowClick(ev) }), h("ul", { key: '4c7b517327719497737fc4d36ae1b53288524d53', id: "tablist", ref: (el) => (this.tabContainerEl = el), class: `tabcontainer ${this.customBackground || ""} ${this.containerFadeLeft ? "fade-left" : ""} ${this.containerFadeRight ? "fade-right" : ""}`, role: "tablist", tabIndex: -1 }, h("slot", { key: '7b0ff4de54e705b4296a1e48ccba999143840bac' })), h("wm-button", { key: '77655a0882a65a2cd71f4a7fc8f1f866da8c3c40', class: `right-arrow ${this.scrollArrowsVisible ? "visible" : ""}`, "aria-controls": "tablist", customBackground: this.customBackground, buttonType: "navigational", icon: "#next", tooltip: intl.formatMessage({
                 id: "tabs.showNextTabs",
                 defaultMessage: "Show next tabs",
                 description: "Tooltip for button scrolling tab group.",
-            }), onClick: (ev) => this.handleRightArrowClick(ev) }), h("span", { key: '83f0f5c60bb02b59e0e163a626be41ac18f1c4e2', "aria-live": "assertive", class: "sr-only", ref: (el) => (this.liveRegionEl = el) }, this.announcement))));
+            }), onClick: (ev) => this.handleRightArrowClick(ev) }), h("span", { key: 'c8b221bda334dcf40c28a4a1e3134de72a868018', "aria-live": "assertive", class: "sr-only", ref: (el) => (this.liveRegionEl = el) }, this.announcement))));
     }
     static get is() { return "wm-tab-list"; }
     static get encapsulation() { return "shadow"; }
@@ -293,7 +378,10 @@ export class TabList {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Sets the visual theme. Pass `\"dark\"` for the dark theme; omit for the\ndefault light theme."
+                        }],
                     "text": ""
                 },
                 "attribute": "custom-background",
@@ -310,7 +398,10 @@ export class TabList {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "The `tab-id` of the currently active tab. Update this prop in response to\n`wmTabSelected` to switch tabs. Defaults to the first tab if not set."
+                        }],
                     "text": ""
                 },
                 "attribute": "selected-tab",

package/dist/collection/components/wm-tabs/wm-tab-panel/wm-tab-panel.js

@@ -1,5 +1,23 @@
 import { Host, h } from "@stencil/core";
 import { generateId } from "../../../global/functions";
+/**
+ * Content panel associated with a wm-tab-item. Shows or hides based on whether its
+ * `tab-id` matches the selected tab in the parent wm-tab-list. Rendered with
+ * `role="tabpanel"`. Always used alongside a wm-tab-list.
+ *
+ * @slot - The panel content to display when this tab is active.
+ *
+ * @usageNotes
+ * - `tab-id` is required and must match the `tab-id` of the corresponding wm-tab-item.
+ * - For the single-panel conditional-content pattern, use one wm-tab-panel without a
+ *   `tab-id` — the parent wm-tab-list updates its ARIA attributes automatically.
+ *
+ * @example {html} Tab panel
+ * <wm-tab-panel tab-id="overview">Overview content here.</wm-tab-panel>
+ *
+ * @example {react} Tab panel
+ * <WmTabPanel tabId="overview">Overview content here.</WmTabPanel>
+ */
 export class TabPanel {
     constructor() {
         this.active = false;
@@ -12,7 +30,7 @@ export class TabPanel {
         this.tabPanelLoaded.emit({ tabId: this.tabId });
     }
     render() {
-        return h(Host, { key: 'd1c5920b5b91b671adb2f1e503a5b6f676fcca5e', role: "tabpanel", tabIndex: "-1", class: { "tab-hidden": !this.active } });
+        return h(Host, { key: '1e812485c6cc7a99b916a3aff9e105dee4f29522', role: "tabpanel", tabIndex: "-1", class: { "tab-hidden": !this.active } });
     }
     static get is() { return "wm-tab-panel"; }
     static get originalStyleUrls() {
@@ -38,8 +56,14 @@ export class TabPanel {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "Indicates whether the panel should be displayed or not."
+                    "tags": [{
+                            "name": "description",
+                            "text": "Whether this panel is currently visible. Managed by the parent wm-tab-list \u2014\ndo not set manually."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
                 },
                 "attribute": "active",
                 "reflect": false,
@@ -56,8 +80,14 @@ export class TabPanel {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
-                    "text": "The id of the panel, linked to a tabItem in the tablist."
+                    "tags": [{
+                            "name": "description",
+                            "text": "Unique identifier linking this panel to its associated wm-tab-item. Must\nmatch the `tab-id` on the corresponding wm-tab-item."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
                 },
                 "attribute": "tab-id",
                 "reflect": false,
@@ -73,7 +103,13 @@ export class TabPanel {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Internal signal consumed by wm-tab-list for ARIA wiring \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {