@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

package/dist/docs/skill/wm-select.md

@@ -0,0 +1,169 @@
+### Select
+- **Element:** `<wm-select>`
+
+**Purpose:** Dropdown list of options that allows single or multi-select. Functionally similar to the
+native HTML `<select>` element but with Ripple styling and richer features including
+multiselect, search filtering, and a Select All control. Composed of a parent wm-select
+element and wm-option children.
+
+**When to use:**
+
+- **Choosing a single value from a known, bounded list** -- when a user needs to pick exactly one option from a fixed set (e.g., selecting a term, role, or status), use the default single-select variant to record that choice as a form value.
+- **Selecting multiple values from a flat list** -- when a user can choose more than one option from an unstructured set, use the multiple property, optionally with select-all for bulk selection convenience.
+- **Filtering a manageable option set by typing** -- when the list has up to 50 options and scanning is impractical, use the search property to let users narrow options by typing rather than scrolling.
+- **Displaying supplementary context alongside options** -- when each option benefits from a short secondary label (e.g., a code, count, or category hint), use the subinfo property on wm-option to show italicized supporting text inline.
+
+**Do not use for:**
+
+- **Categorized options** -- if the option set has a meaningful group structure, use wm-nested-select instead; Select only supports a single flat list.
+- **Selecting an option that triggers an action** -- if selecting an item should immediately execute something, use wm-action-menu's selector variant, not Select.
+- **More than 50 options in search mode** -- the search variant is intended for 50 or fewer options; beyond that, it creates usability and potential performance problems.
+- **Single Select with no pre-selected option** -- single Select must always have a selected value; if no default exists, the first option must explicitly represent a null state using only approved language ("None", "Select an option", or "--").
+
+**Variants / types:**
+
+_None documented_
+
+**Usage notes:**
+
+- Single-select: has no `placeholder` prop -- a selection must always be present, and the
+  component warns in the console if no option is initially selected. Since there's no way
+  to distinguish "the user selected the first option" from "no selection was made," use a
+  null-value first option to represent the unselected state and keep the component
+  revertible to "no option chosen." That option must not be disabled, and for
+  accessibility/consistency its label should be limited to "None", "Select an option", or
+  "--".
+- Multi-select: all options deselected on load is valid; use `placeholder` for that state.
+- `search` is best with 50 or fewer options -- it filters by visible label text only.
+- `select-all` requires `multiple` to be set.
+- Selection state is maintained via the `selected` prop on each wm-option child.
+- To respond to selection changes, listen for `wmOptionSelected` (declared on wm-option but
+  bubbles to wm-select). `event.detail` is the `HTMLWmOptionElement`; read `.value` or
+  `.textContent` to get the selected value.
+
+**Props:**
+- `all-selected-message` -- Text displayed in the trigger button in multiselect mode when every option
+is selected. _(default: `selectMessages.allSelected`)_
+- `disabled` -- Disables the entire select component, preventing all interaction. _(default: `false`)_
+- `error-message` -- Puts the component in an error state and displays this message beneath the
+trigger button. Use for form validation feedback.
+- `info` -- Informational hint text rendered beneath the dropdown button. Use for
+supporting instructions or constraints.
+- `label` -- Accessible label for the dropdown. Required even when `label-position` is
+`"none"` -- used as the ARIA accessible name. _(required)_
+- `label-position` -- Position of the label relative to the dropdown button. `"none"` hides the
+label visually but keeps it accessible via ARIA. _(type: `"left" | "none" | "top"`; default: `"top"`)_
+- `max-height` -- Overrides the maximum height of the options list. Accepts any valid CSS
+length value (e.g. `"20rem"`, `"300px"`). _(default: `"200px"`)_
+- `multiple` -- Enables multiselect mode, allowing more than one option to be selected
+simultaneously. _(default: `false`)_
+- `placeholder` -- Text displayed in the trigger button in multiselect mode when no options are
+selected. Not applicable in single-select mode -- use a null-value first option instead. _(default: `selectMessages.multiPlaceholder`)_
+- `required-field` -- Displays a required-field asterisk (*) next to the label. _(default: `false`)_
+- `search` -- Adds a search input inside the dropdown that filters visible options by label
+text. Compatible with both single and multiselect modes. Best with 50 or fewer options. _(default: `false`)_
+- `search-placeholder` -- Placeholder text displayed inside the search input when `search` is enabled. _(default: `selectMessages.searchPlaceholder`)_
+- `select-all` -- Adds a "Select All" / "Deselect All" toggle at the top of the dropdown.
+Has no effect unless `multiple` is also set. _(default: `false`)_
+
+**Events:**
+- `wmSelectAllDeselected` -- Fires when the user clicks "Deselect All" in multiselect mode and all
+options become deselected.
+- `wmSelectAllSelected` -- Fires when the user clicks "Select All" in multiselect mode and all options
+become selected.
+- `wmSelectBlurred` -- Fires when focus leaves the component entirely (not when moving between
+the trigger and an option within the dropdown).
+- `wmSelectDidLoad` -- Fires after the component has finished loading and is ready for interaction.
+Use this to read initial selection state or call methods.
+
+**Accessibility:**
+
+- `label` is required even when `label-position` is `"none"` -- it is used as the dropdown's
+  ARIA accessible name.
+- The dropdown renders with `role="listbox"`. Each wm-option renders with `role="option"`.
+- `required-field` renders a visible asterisk; the ARIA required constraint is communicated
+  via the label rather than `aria-required` because the listbox is in a sub-component.
+- Validation errors are announced via an `aria-live` region when `error-message` changes.
+- **Keyboard:**
+  - **Closed button**: Space / Enter / Arrow Down opens the dropdown and focuses the first
+  option; Arrow Up opens and focuses the last option.
+  - **Open dropdown**: Arrow Up / Down navigate options; Home / End jump to first / last;
+  typing a letter jumps to the first matching option.
+  - **Single-select**: Enter / Space / click selects and closes.
+  - **Multi-select**: Enter / Space / click toggles selection; Tab or Escape closes.
+  - **Shift+Tab** (from options): Closes and returns focus to the trigger button.
+
+**Related components:**
+
+- `<wm-nested-select>` -- if the options have a two-level category structure, use Nested Select; if they are a single flat list, use Select.
+- `<wm-action-menu>` (selector type) -- if picking an option should immediately execute an action rather than record a value, use Action Menu's selector type, not Select.
+- `<wm-tag-input>` -- if the user needs to select or create values displayed as removable tags (e.g., adding people or labels), Tag Input is likely the better fit over multi-select Select.
+
+**Code example:**
+
+_Single-select_
+
+```html
+<wm-select label="Program">
+<wm-option selected>Select a program</wm-option>
+<wm-option>Biology</wm-option>
+<wm-option>English</wm-option>
+</wm-select>
+```
+
+_Single-select_
+
+```react
+const [program, setProgram] = useState('');
+
+// event.detail is the selected HTMLWmOptionElement
+const handleSelect = (event) => {
+setProgram(event.detail.value ?? event.detail.textContent);
+};
+
+<WmSelect label="Program" onWmOptionSelected={handleSelect}>
+<WmOption selected>Select a program</WmOption>
+<WmOption value="bio">Biology</WmOption>
+<WmOption value="eng">English</WmOption>
+</WmSelect>
+```
+
+_Multi-select with search and Select All_
+
+```html
+<wm-select label="Programs" multiple search select-all
+placeholder="Select programs">
+<wm-option value="bio">Biology</wm-option>
+<wm-option value="eng">English</wm-option>
+</wm-select>
+```
+
+_Multi-select with search and Select All_
+
+```react
+const [selected, setSelected] = useState([]);
+
+// event.detail is the HTMLWmOptionElement that was selected or deselected
+const handleSelect = (event) => {
+const value = event.detail.value ?? event.detail.textContent;
+setSelected((prev) => [...prev, value]);
+};
+
+const handleDeselect = (event) => {
+const value = event.detail.value ?? event.detail.textContent;
+setSelected((prev) => prev.filter((v) => v !== value));
+};
+
+<WmSelect
+label="Programs"
+multiple={true}
+search={true}
+selectAll={true}
+placeholder="Select programs"
+onWmOptionSelected={handleSelect}
+onWmOptionDeselected={handleDeselect}
+>
+<WmOption value="bio">Biology</WmOption>
+<WmOption value="eng">English</WmOption>
+</WmSelect>
+```

package/dist/docs/skill/wm-snackbar.md

@@ -0,0 +1,130 @@
+### Snackbar
+- **Element:** `<wm-snackbar>`
+
+**Purpose:** 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.
+
+**When to use:**
+
+- **Confirming the successful completion of a user action** -- when a user submits a form, uploads a file, adds or removes an item, or saves changes and the result is not immediately visible on screen, use a Snackbar to close the feedback loop with a brief confirmation message.
+- **Providing a link to the result of a completed action** -- when the action produces something the user might want to navigate to immediately (e.g., a newly created record), use a Snackbar with a link to offer that shortcut without forcing navigation.
+- **Offering a quick undo after an action** -- when a reversible action has just been taken, use a Snackbar with an action button (e.g., "Undo") to give the user a brief window to reverse it without a confirmation step.
+- **Consolidating rapid successive notifications** -- when multiple similar actions fire in quick succession (under 6 seconds), use a single Snackbar summarizing them (e.g., "3 items updated") rather than stacking individual notifications per action.
+
+**Do not use for:**
+
+- **Actions whose result is immediately visible** -- if the outcome is already visible in the interface (an item appears in a list, a field updates inline), a Snackbar adds noise without adding information; skip it.
+- **Every minor or intuitive action** -- routine, low-stakes interactions do not warrant a notification and will overwhelm users over time if over-triggered.
+- **Essential information or links the user must act on** -- because Snackbars auto-dismiss after 6 seconds, any message or action the user genuinely needs to see should be in a Dialog or banner instead; Snackbar content must always be findable elsewhere in the interface.
+- **Triggering other containers or including more than one link** -- Snackbars should not launch other layout containers or inputs, and are limited to a single link; it is a terminal notification, not a launching point.
+
+**Variants / types:**
+
+_None documented_
+
+**Usage notes:**
+
+- `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 }`.
+
+**Props:**
+- `notifications` -- JSON-encoded array of notification objects to display. Each object must
+include `id` (string) and `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). Always pass as `JSON.stringify(array)` --
+passing an array directly causes a "[object Object] is not valid JSON" error. _(required; default: `"[]"`)_
+
+**Events:**
+- `wmSnackbarActionTriggered` -- Fires when the user clicks the `link` anchor or `action` button. The host
+application should remove the notification and navigate (for links) or execute the action
+(for buttons). Detail: `{{ id: string, message: string, link?: string, newWindow?: boolean, action?: string }}`
+- `wmSnackbarSnackFinished` -- Fires when a notification should be removed -- after the 6-second
+auto-dismiss timer expires or when the user clicks the close button. The host application
+should remove the matching notification from its array. The timer is disabled for
+notifications with a `link` or `action`. Detail: `{{ id: string, message: string, link?: string, newWindow?: boolean, action?: string }}`
+
+**Required setup:**
+
+- Show a snack by adding an entry to `notifications`, and pass the stringified array rather than
+  the array itself.
+- Handle `wmSnackbarSnackFinished` (`event.detail` is `{ id }`) by removing that entry from the
+  array you pass to `notifications`; the component does not remove it for you.
+- Handle `wmSnackbarActionTriggered` for entries carrying `link` or `action`, and remove the entry
+  yourself once handled -- the 6-second auto-dismiss does not apply to those.
+
+**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.
+- **Keyboard:**
+  - **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.
+
+**Related components:**
+
+- Dialog -- if the message requires the user to make a decision or acknowledge something before continuing, use Dialog; Snackbar is for passive confirmations that do not require a response.
+- Banner -- if the message is tied to a persistent system status, an error the user must fix, or information that needs to stay visible until resolved, use a banner; Snackbar is for transient, action-completion feedback only.
+- `<wm-toggletip>` -- if contextual information needs to be available on demand near a specific element rather than as a system notification, use Toggletip; Snackbar is not a help or hint mechanism.
+
+**Code example:**
+
+_Simple notification_
+
+```html
+<wm-snackbar notifications='[{"id":"1","message":"Changes saved."}]'></wm-snackbar>
+```
+
+_Notification stack with action and link variants_
+
+```react
+// 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}
+/>
+```

package/dist/docs/skill/wm-tab-item.md

@@ -0,0 +1,45 @@
+### Tab Item
+- **Element:** `<wm-tab-item>`
+
+**Purpose:** 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.
+
+**Usage notes:**
+
+- `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.
+
+**Props:**
+- `tab-id` -- Unique identifier linking this tab to its associated wm-tab-panel. Must
+match the `tab-id` on the corresponding wm-tab-panel. _(required; default: `""`)_
+
+**Slots:**
+- _(default)_ -- The visible label text for the tab.
+
+**Events:**
+- `wmTabSelected` -- Fires when this tab is clicked or activated by keyboard. Listen to this
+event and update the `selected-tab` prop on the parent wm-tab-list to switch the active
+tab. Detail: `{{ tabId: string }} tabId -- the `tab-id` of the activated tab.`
+
+**Required setup:**
+
+- Render it as a direct child of wm-tab-list, and slot the tab label into it.
+- Give it a `tab-id` matching the `tab-id` of its wm-tab-panel. A mismatch fails silently: the tab
+  highlights and no panel appears.
+- Handle `wmTabSelected` (`event.detail` is `{ tabId }`), which bubbles to wm-tab-list, and write
+  the id to the list's `selected-tab`.
+
+**Code example:**
+
+_Tab item_
+
+```html
+<wm-tab-item tab-id="overview">Overview</wm-tab-item>
+```
+
+_Tab item_
+
+```react
+<WmTabItem tabId="overview">Overview</WmTabItem>
+```

package/dist/docs/skill/wm-tab-list.md

@@ -0,0 +1,139 @@
+### Tab List
+- **Element:** `<wm-tab-list>`
+
+**Purpose:** 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.
+
+**When to use:**
+
+- **Organizing related content into parallel sections within a page** -- when a page or container holds distinct but related content areas that do not all need to be visible at once (e.g., Overview, Details, History on a record page), use Tabs to present them as switchable views with short, clear labels.
+- **Breaking up content within a layout container** -- Tabs are usable inside primary pages, immersive layouts, Flyouts, and side panels; use them whenever a container has enough content variety to warrant sub-sections without adding navigation overhead.
+
+**Do not use for:**
+
+- **Primary navigation between pages** -- Tabs should not be used as primary navigation; they are for switching sections within a single page or container. Cross-page navigation belongs in wm-navigation.
+- **More tabs than fit in a single row** -- all tabs should be visible on one row; if there are too many, the content should be simplified or a different pattern considered.
+- **Sequential steps that must be completed in order** -- Tabs imply free switching between any section at any time; if the user must complete steps in sequence, a stepper pattern is more appropriate.
+
+**Variants / types:**
+
+- `customBackground="dark" (on wm-tab-list)` -- applies a dark background variant to the tab bar
+
+**Usage notes:**
+
+- 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.
+- At least one wm-tab-panel is required -- wm-tab-list only renders the tab strip, not the
+  content area. A wm-tab-item's `tab-id` must exactly match its wm-tab-panel's `tab-id`
+  (or the shared panel's `tab-id`, for the single-panel pattern). A missing or mismatched
+  `tab-id` fails silently: no console warning, the tab's `aria-controls`/`href` never get
+  set, and its panel never activates.
+- 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`.
+
+**Props:**
+- `custom-background` -- Sets the visual theme. Pass `"dark"` for the dark theme; omit for the
+default light theme. _(type: `"" | "dark"`)_
+- `selected-tab` -- The `tab-id` of the currently active tab. Update this prop in response to
+`wmTabSelected` to switch tabs. Defaults to the first tab if not set.
+
+**Slots:**
+- _(default)_ -- One or more wm-tab-item elements.
+
+**Required setup:**
+
+- Handle `wmTabSelected` on the list -- it is declared on wm-tab-item and bubbles -- and write
+  `event.detail.tabId` to `selected-tab`.
+- Slot a wm-tab-item per tab, and render a wm-tab-panel for each one as its content container.
+- Give each wm-tab-item `tab-id` the same value as its wm-tab-panel `tab-id`. A mismatch fails
+  silently: the tab highlights and no panel appears.
+
+**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.
+- **Keyboard:**
+  - **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.
+
+**Related components:**
+
+- `<wm-navigation>` -- if the purpose is navigating between separate pages or top-level product areas, use Navigation; Tabs are strictly for switching views within a single page or container context.
+- `<wm-pagination>` -- if the user is moving through pages of a dataset rather than switching between content sections, use Pagination; Tabs are not a data paging mechanism.
+- Stepper pattern -- if the content sections represent sequential steps that must be completed in order, use a stepper; Tabs allow unrestricted movement between sections and carry no sense of progress or completion state.
+
+**Code example:**
+
+_Basic tabs (discrete panels)_
+
+```html
+<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>
+```
+
+_Basic tabs (discrete panels)_
+
+```react
+// 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>
+```
+
+_Single shared panel (content rendered conditionally)_
+
+```html
+<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>
+```
+
+_Single shared panel (content rendered conditionally)_
+
+```react
+// 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>
+```

package/dist/docs/skill/wm-tab-panel.md

@@ -0,0 +1,39 @@
+### Tab Panel
+- **Element:** `<wm-tab-panel>`
+
+**Purpose:** 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.
+
+**Usage notes:**
+
+- `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.
+
+**Props:**
+- `tab-id` -- Unique identifier linking this panel to its associated wm-tab-item. Must
+match the `tab-id` on the corresponding wm-tab-item. _(required; default: `""`)_
+
+**Slots:**
+- _(default)_ -- The panel content to display when this tab is active.
+
+**Required setup:**
+
+- Render one panel per wm-tab-item alongside the wm-tab-list, and slot the panel content into it.
+- Give it a `tab-id` matching its wm-tab-item's `tab-id`. A mismatch fails silently: the tab
+  highlights and no panel appears.
+
+**Code example:**
+
+_Tab panel_
+
+```html
+<wm-tab-panel tab-id="overview">Overview content here.</wm-tab-panel>
+```
+
+_Tab panel_
+
+```react
+<WmTabPanel tabId="overview">Overview content here.</WmTabPanel>
+```