@brandsync/wc 1.8.0 → 1.9.0

package/dist/collection/components/bs-data-table/bs-data-table.stories.js

@@ -44,11 +44,18 @@ export const WithCustomCellRenderer = {
         const table = document.createElement('bs-data-table');
         table.columns = [...columns, { key: 'actions', label: 'Actions' }];
         table.rows = rows;
+        // cellRenderer renders EVERY cell and its output is not escaped, so plain columns are escaped
+        // here too -- copying `String(row[column.key])` unescaped would make untrusted row data HTML.
+        const escapeHtml = (value) => String(value ?? '').replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
         table.cellRenderer = (row, column) => {
             if (column.key === 'actions') {
                 return `<button type="button">Edit</button>`;
             }
-            return String(row[column.key] ?? '');
+            if (column.key === 'status') {
+                // Rich content: a web component in the cell.
+                return `<bs-badge variant="${row.status === 'Active' ? 'success' : 'neutral'}">${escapeHtml(row.status)}</bs-badge>`;
+            }
+            return escapeHtml(row[column.key]);
         };
         return table;
     },

package/dist/collection/components/bs-logo/bs-logo.cmp.test.js

@@ -1,4 +1,5 @@
 import { render, h, describe, it, expect } from "@stencil/vitest";
+import { vi } from "vitest";
 describe('bs-logo', () => {
     it('renders role="img" and aria-label="BrandSync"', async () => {
         const { root } = await render(h("bs-logo", null));
@@ -37,9 +38,9 @@ describe('bs-logo', () => {
             expect(getComputedStyle(darkAsset).display).toBe('none');
         });
         it('shows the dark asset and hides the light one when an ambient dark theme sets --bs-logo-asset-*-display', async () => {
-            // Simulates what src/global/base.css's [data-theme="dark"] rule sets on <html> in a real
-            // app -- setting the same custom properties directly on the render stage container here,
-            // since this isolated component test doesn't load that global stylesheet. CSS custom
+            // Simulates what src/global/base.css's [data-theme="dark"] rule sets, by setting the same
+            // custom properties directly on the render stage container. (The real selector is exercised
+            // in the "follows the real [data-theme="dark"] attribute" tests below.) CSS custom
             // properties inherit through the shadow boundary regardless of where they're defined.
             const { root } = await render(h("bs-logo", null), {
                 stageAttrs: { style: '--bs-logo-asset-light-display: none; --bs-logo-asset-dark-display: block;' },
@@ -50,6 +51,54 @@ describe('bs-logo', () => {
             expect(getComputedStyle(darkAsset).display).not.toBe('none');
         });
     });
+    // The tests above set the --bs-logo-asset-*-display variables by hand. These exercise the real
+    // `[data-theme="dark"]` rule from src/global/base.css (loaded by vitest-setup.ts), i.e. what a
+    // consuming app actually does -- including WHERE the attribute may sit (issue: dark logo on a dark
+    // theme).
+    describe('background="auto" follows the real [data-theme="dark"] attribute', () => {
+        const shown = (root) => ({
+            light: getComputedStyle(root.shadowRoot.querySelector('.bs-logo__asset--light')).display !== 'none',
+            dark: getComputedStyle(root.shadowRoot.querySelector('.bs-logo__asset--dark')).display !== 'none',
+        });
+        it('flips to the dark asset when data-theme="dark" is on <html>', async () => {
+            document.documentElement.setAttribute('data-theme', 'dark');
+            try {
+                const { root } = await render(h("bs-logo", null));
+                expect(shown(root)).toEqual({ light: false, dark: true });
+            }
+            finally {
+                document.documentElement.removeAttribute('data-theme');
+            }
+        });
+        it('flips to the dark asset when data-theme="dark" is on <body>', async () => {
+            document.body.setAttribute('data-theme', 'dark');
+            try {
+                const { root } = await render(h("bs-logo", null));
+                expect(shown(root)).toEqual({ light: false, dark: true });
+            }
+            finally {
+                document.body.removeAttribute('data-theme');
+            }
+        });
+        it('flips to the dark asset when data-theme="dark" is on any ancestor wrapper', async () => {
+            const { root } = await render(h("div", { "data-theme": "dark" }, h("bs-logo", null)));
+            expect(shown(root.querySelector('bs-logo'))).toEqual({ light: false, dark: true });
+        });
+        it('does NOT flip for a logo outside the data-theme="dark" element', async () => {
+            const { root } = await render(h("div", null, h("div", { "data-theme": "dark" }), h("bs-logo", null)));
+            expect(shown(root.querySelector('bs-logo'))).toEqual({ light: true, dark: false });
+        });
+        it('does not follow prefers-color-scheme (only the data-theme attribute)', async () => {
+            const spy = vi.spyOn(window, 'matchMedia').mockImplementation((q) => ({ matches: q.includes('prefers-color-scheme: dark'), media: q, addEventListener: () => undefined, removeEventListener: () => undefined, addListener: () => undefined, removeListener: () => undefined, onchange: null, dispatchEvent: () => false }));
+            try {
+                const { root } = await render(h("bs-logo", null));
+                expect(shown(root)).toEqual({ light: true, dark: false });
+            }
+            finally {
+                spy.mockRestore();
+            }
+        });
+    });
     describe('background="light"/"dark" (explicit)', () => {
         it('pins the light asset even when an ambient dark theme is set', async () => {
             const { root } = await render(h("bs-logo", { background: "light" }), {

package/dist/collection/components/bs-menu/bs-menu.stories.js

@@ -13,3 +13,57 @@ const meta = {
 };
 export default meta;
 export const Default = {};
+// `bs-menu` is only the popup surface: it does not open, close or position itself. This story is the
+// recipe for turning it into a dropdown with the pieces the library already has (a button, the menu,
+// and ~25 lines of wiring). The same code is shown in bs-menu.mdx.
+export const DropdownRecipe = {
+    name: 'Dropdown (recipe)',
+    render: () => {
+        const host = document.createElement('div');
+        host.style.minHeight = '220px';
+        host.innerHTML = `
+      <div class="dropdown" style="position: relative; display: inline-block;">
+        <bs-button aria-haspopup="menu" aria-expanded="false">Actions</bs-button>
+        <bs-menu style="display: none; position: absolute; top: calc(100% + var(--bs-spacing-50)); inset-inline-start: 0; z-index: var(--bs-z-index-popover); width: 210px;">
+          <bs-menu-item>Edit</bs-menu-item>
+          <bs-menu-item>Duplicate</bs-menu-item>
+          <bs-menu-item disabled>Archive</bs-menu-item>
+          <bs-menu-item>Delete</bs-menu-item>
+        </bs-menu>
+      </div>`;
+        const wrapper = host.querySelector('.dropdown');
+        const trigger = wrapper.querySelector('bs-button');
+        const menu = wrapper.querySelector('bs-menu');
+        const onDocumentClick = (ev) => {
+            // composedPath() so a click inside the shadow DOM of the button / menu items counts as inside
+            if (!ev.composedPath().includes(wrapper))
+                setOpen(false);
+        };
+        function setOpen(open, restoreFocus = false) {
+            menu.style.display = open ? 'block' : 'none';
+            trigger.setAttribute('aria-expanded', String(open));
+            if (open) {
+                document.addEventListener('click', onDocumentClick);
+                // bs-menu handles Up/Down/Home/End once focus is inside; put it on the first enabled item
+                menu.querySelector('bs-menu-item:not([disabled])')?.shadowRoot?.querySelector('button')?.focus();
+            }
+            else {
+                document.removeEventListener('click', onDocumentClick);
+                if (restoreFocus)
+                    trigger.focus();
+            }
+        }
+        trigger.addEventListener('click', () => setOpen(menu.style.display === 'none'));
+        wrapper.addEventListener('keydown', (ev) => {
+            if (ev.key === 'Escape')
+                setOpen(false, true);
+        });
+        wrapper.addEventListener('focusout', (ev) => {
+            // Tab (or anything else) moving focus out of the whole dropdown closes it
+            if (menu.style.display !== 'none' && !wrapper.contains(ev.relatedTarget))
+                setOpen(false);
+        });
+        menu.addEventListener('bsSelect', () => setOpen(false, true));
+        return host;
+    },
+};

package/dist/collection/components/bs-tab/bs-inline-tab/bs-inline-tab.js

@@ -48,6 +48,10 @@ export class BsInlineTab {
      * violation). Stencil reflects this camelCase prop to the `aria-label` HTML attribute
      * automatically, same as `bs-tab`'s identical prop. */
     ariaLabel = null;
+    /** Identifies this tab within a parent `bs-tabs`: the group's `value` is the selected tab's
+     * `value`, and `bsChange` reports it. Optional -- a tab without one is identified by its
+     * zero-based position in the group (`"0"`, `"1"`...). */
+    value;
     /** Set by a parent `bs-tabs` to implement roving tabindex (only one tab in the group is in the
      * Tab order; arrow keys move between them). Left `undefined` for a standalone tab, which stays
      * a normal tab stop. */
@@ -90,7 +94,7 @@ export class BsInlineTab {
     };
     render() {
         const iconOnly = this.hasIcon && !this.hasLabel;
-        return (h("button", { key: '72a2298b0dff31e192dc679ee153d1d87e6a8723', type: "button", part: "tab", role: "tab", class: `bs-inline-tab ${this.selected ? 'bs-inline-tab--selected' : ''} ${this.disabled ? 'bs-inline-tab--disabled' : ''} ${iconOnly ? 'bs-inline-tab--icon-only' : ''} ${this.hasIcon ? 'bs-inline-tab--has-icon' : ''}`, disabled: this.disabled, "aria-selected": String(this.selected), "aria-disabled": this.disabled ? 'true' : undefined, "aria-label": this.ariaLabel, tabIndex: this.tabbable === undefined ? undefined : this.tabbable ? 0 : -1, onClick: this.onClick }, h("span", { key: '25679b5cfc3bfec29f91b12f6180048429706b86', part: "icon", class: `bs-inline-tab__icon ${this.hasIcon ? 'bs-inline-tab__icon--has-content' : ''}` }, h("slot", { key: 'f5c996ae38a4e5ace60c8b1145dfb64114097600', name: "icon", onSlotchange: this.onIconSlotchange })), h("span", { key: '101ac663fa1b05e3f4f2faaaff865e02ecbd4e90', part: "label", class: `bs-inline-tab__label ${this.hasLabel ? 'bs-inline-tab__label--has-content' : ''}` }, h("slot", { key: 'a705183b26ad7d7ad3e286939b256cfbafb78580', onSlotchange: this.onLabelSlotchange }))));
+        return (h("button", { key: '0d6927b0b39a7d84add287e6473681e5052b5f2d', type: "button", part: "tab", role: "tab", class: `bs-inline-tab ${this.selected ? 'bs-inline-tab--selected' : ''} ${this.disabled ? 'bs-inline-tab--disabled' : ''} ${iconOnly ? 'bs-inline-tab--icon-only' : ''} ${this.hasIcon ? 'bs-inline-tab--has-icon' : ''}`, disabled: this.disabled, "aria-selected": String(this.selected), "aria-disabled": this.disabled ? 'true' : undefined, "aria-label": this.ariaLabel, tabIndex: this.tabbable === undefined ? undefined : this.tabbable ? 0 : -1, onClick: this.onClick }, h("span", { key: '866660f0f79927cd018df42286719f2f48262cbb', part: "icon", class: `bs-inline-tab__icon ${this.hasIcon ? 'bs-inline-tab__icon--has-content' : ''}` }, h("slot", { key: '58e11c8a0a57646644cb0b7c950d73f5cee52310', name: "icon", onSlotchange: this.onIconSlotchange })), h("span", { key: '38d2e1df2b4e494f68d3c4b9ea34d7a317401953', part: "label", class: `bs-inline-tab__label ${this.hasLabel ? 'bs-inline-tab__label--has-content' : ''}` }, h("slot", { key: '51fb6ec04479b18af787bca4e64f8105a0b19311', onSlotchange: this.onLabelSlotchange }))));
     }
     static get is() { return "bs-inline-tab"; }
     static get encapsulation() { return "shadow"; }
@@ -166,6 +170,25 @@ export class BsInlineTab {
                 "attribute": "aria-label",
                 "defaultValue": "null"
             },
+            "value": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Identifies this tab within a parent `bs-tabs`: the group's `value` is the selected tab's\n`value`, and `bsChange` reports it. Optional -- a tab without one is identified by its\nzero-based position in the group (`\"0\"`, `\"1\"`...)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "value"
+            },
             "tabbable": {
                 "type": "boolean",
                 "mutable": false,

package/dist/collection/components/bs-tab/bs-tab/bs-tab.js

@@ -53,6 +53,10 @@ export class BsTab {
      * violation). Stencil reflects this camelCase prop to the `aria-label` HTML attribute
      * automatically, same as `bs-button`'s identical prop. */
     ariaLabel = null;
+    /** Identifies this tab within a parent `bs-tabs`: the group's `value` is the selected tab's
+     * `value`, and `bsChange` reports it. Optional -- a tab without one is identified by its
+     * zero-based position in the group (`"0"`, `"1"`...). */
+    value;
     /** Set by a parent `bs-tabs` to implement roving tabindex (only one tab in the group is in the
      * Tab order; arrow keys move between them). Left `undefined` for a standalone tab, which stays
      * a normal tab stop. */
@@ -103,7 +107,7 @@ export class BsTab {
         const iconOnly = this.hasIcon && !this.hasLabel;
         const vertical = this.hasIcon && this.hasLabel && this.iconPosition === 'top';
         const showBadge = this.hasBadge && !iconOnly && !vertical;
-        return (h("button", { key: '368a2f20536d169e06e47500dcca4d6a54f17dde', type: "button", part: "tab", role: "tab", class: `bs-tab ${this.selected ? 'bs-tab--selected' : ''} ${this.disabled ? 'bs-tab--disabled' : ''} ${iconOnly ? 'bs-tab--icon-only' : ''} ${vertical ? 'bs-tab--vertical' : ''}`, disabled: this.disabled, "aria-selected": String(this.selected), "aria-disabled": this.disabled ? 'true' : undefined, "aria-label": this.ariaLabel, tabIndex: this.tabbable === undefined ? undefined : this.tabbable ? 0 : -1, onClick: this.onClick }, h("span", { key: '3b22e92a5d6bca27c0b12b6f80ef29af06bcc564', part: "icon", class: `bs-tab__icon ${this.hasIcon ? 'bs-tab__icon--has-content' : ''}` }, h("slot", { key: 'd75cb8cc85547a8c6a8be3bca3fc82a61d3cfa38', name: "icon", onSlotchange: this.onIconSlotchange })), h("span", { key: '43ff4feb2425f1b0dd9485f323b1886b42e10a32', part: "label", class: `bs-tab__label ${this.hasLabel ? 'bs-tab__label--has-content' : ''}` }, h("slot", { key: '74a0af9a35043faa3baa2415c3b4a204f5745155', onSlotchange: this.onLabelSlotchange })), h("span", { key: '22b5c4671b7a7c93abffae5a34a4e3bb600d8ed3', part: "badge", class: `bs-tab__badge ${showBadge ? 'bs-tab__badge--has-content' : ''}` }, h("slot", { key: '17b123826ca4b78ff00b89d3a0944e1d805ad4fe', name: "badge", onSlotchange: this.onBadgeSlotchange })), h("span", { key: 'd51f23caa9d0fd0abddd37c7394994e1ffef0586', part: "indicator", class: "bs-tab__indicator" })));
+        return (h("button", { key: '383cf44dfcf1feb5404e6a392318c8ce5a8a1178', type: "button", part: "tab", role: "tab", class: `bs-tab ${this.selected ? 'bs-tab--selected' : ''} ${this.disabled ? 'bs-tab--disabled' : ''} ${iconOnly ? 'bs-tab--icon-only' : ''} ${vertical ? 'bs-tab--vertical' : ''}`, disabled: this.disabled, "aria-selected": String(this.selected), "aria-disabled": this.disabled ? 'true' : undefined, "aria-label": this.ariaLabel, tabIndex: this.tabbable === undefined ? undefined : this.tabbable ? 0 : -1, onClick: this.onClick }, h("span", { key: '8b3a6b9ee663c2957c206024478ee76abf4fb905', part: "icon", class: `bs-tab__icon ${this.hasIcon ? 'bs-tab__icon--has-content' : ''}` }, h("slot", { key: 'b46fd73bac532345e747bb214f8c91f32b04810c', name: "icon", onSlotchange: this.onIconSlotchange })), h("span", { key: '9d3e69f4dc96e20a327ebccdbdf934f07a4892c0', part: "label", class: `bs-tab__label ${this.hasLabel ? 'bs-tab__label--has-content' : ''}` }, h("slot", { key: 'e724d44bec76845b64e8e0ebb5c883dc47ff11a3', onSlotchange: this.onLabelSlotchange })), h("span", { key: '1cb4e5a8056ebac8b1b098c350c4a5d89bd2968a', part: "badge", class: `bs-tab__badge ${showBadge ? 'bs-tab__badge--has-content' : ''}` }, h("slot", { key: '46a6bbf2c8702645b85062012294eedf3facceac', name: "badge", onSlotchange: this.onBadgeSlotchange })), h("span", { key: '38845ccafeddfe79af64c3e291197e88bbced150', part: "indicator", class: "bs-tab__indicator" })));
     }
     static get is() { return "bs-tab"; }
     static get encapsulation() { return "shadow"; }
@@ -205,6 +209,25 @@ export class BsTab {
                 "attribute": "aria-label",
                 "defaultValue": "null"
             },
+            "value": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Identifies this tab within a parent `bs-tabs`: the group's `value` is the selected tab's\n`value`, and `bsChange` reports it. Optional -- a tab without one is identified by its\nzero-based position in the group (`\"0\"`, `\"1\"`...)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "value"
+            },
             "tabbable": {
                 "type": "boolean",
                 "mutable": false,

package/dist/collection/components/bs-tab/bs-tabs/bs-tabs.cmp.test.js

@@ -58,4 +58,92 @@ describe('bs-tabs', () => {
         expect(first.selected).toBe(true);
         expect(second.selected).toBe(false);
     });
+    describe('value and bsChange', () => {
+        const btn = (el) => el.shadowRoot.querySelector('button');
+        const key = (el, k) => el.dispatchEvent(new KeyboardEvent('keydown', { key: k, bubbles: true, composed: true, cancelable: true }));
+        const group = () => (h("bs-tabs", null, h("bs-tab", { value: "overview" }, "Overview"), h("bs-tab", { value: "details" }, "Details"), h("bs-tab", { value: "history" }, "History")));
+        it('a click selects the tab, updates the group value and emits bsChange with it', async () => {
+            const { root, waitForChanges, spyOnEvent } = await render(group());
+            const spy = spyOnEvent('bsChange');
+            const tabs = Array.from(root.querySelectorAll('bs-tab'));
+            btn(tabs[1]).click();
+            await waitForChanges();
+            expect(root.value).toBe('details');
+            expect(root.getAttribute('value')).toBe('details'); // reflected
+            expect(tabs[1].selected).toBe(true);
+            expect(spy).toHaveReceivedEventTimes(1);
+            expect(spy).toHaveReceivedEventDetail({ value: 'details' });
+        });
+        it('does not emit again when the already-selected tab is clicked', async () => {
+            const { root, waitForChanges, spyOnEvent } = await render(group());
+            const spy = spyOnEvent('bsChange');
+            const tabs = Array.from(root.querySelectorAll('bs-tab'));
+            btn(tabs[1]).click();
+            await waitForChanges();
+            btn(tabs[1]).click();
+            await waitForChanges();
+            expect(spy).toHaveReceivedEventTimes(1);
+        });
+        it('a tab without a value is identified by its zero-based index as a string', async () => {
+            const { root, waitForChanges, spyOnEvent } = await render(h("bs-tabs", null, h("bs-tab", null, "One"), h("bs-tab", null, "Two")));
+            const spy = spyOnEvent('bsChange');
+            btn(root.querySelectorAll('bs-tab')[1]).click();
+            await waitForChanges();
+            expect(spy).toHaveReceivedEventDetail({ value: '1' });
+            expect(root.value).toBe('1');
+        });
+        it('an initial value selects the matching tab on load', async () => {
+            const { root, waitForChanges } = await render(h("bs-tabs", { value: "history" }, h("bs-tab", { value: "overview" }, "Overview"), h("bs-tab", { value: "details" }, "Details"), h("bs-tab", { value: "history" }, "History")));
+            await waitForChanges();
+            const tabs = Array.from(root.querySelectorAll('bs-tab'));
+            expect(tabs.map(t => t.selected)).toEqual([false, false, true]);
+            // roving tabindex follows the selection
+            expect(btn(tabs[2]).tabIndex).toBe(0);
+            expect(btn(tabs[0]).tabIndex).toBe(-1);
+        });
+        it('setting value from outside selects the matching tab and does NOT emit bsChange', async () => {
+            const { root, waitForChanges, spyOnEvent } = await render(group());
+            const spy = spyOnEvent('bsChange');
+            root.value = 'details';
+            await waitForChanges();
+            const tabs = Array.from(root.querySelectorAll('bs-tab'));
+            expect(tabs.map(t => t.selected)).toEqual([false, true, false]);
+            expect(spy).not.toHaveReceivedEvent();
+        });
+        it('with no value set, reports the tab the consumer already marked selected (without emitting)', async () => {
+            const { root, waitForChanges, spyOnEvent } = await render(h("bs-tabs", null, h("bs-tab", { value: "a" }, "A"), h("bs-tab", { value: "b", selected: true }, "B")));
+            const spy = spyOnEvent('bsChange');
+            await waitForChanges();
+            expect(root.value).toBe('b');
+            expect(spy).not.toHaveReceivedEvent();
+        });
+        it('keyboard navigation emits bsChange too (arrow keys select the next tab)', async () => {
+            const { root, waitForChanges, spyOnEvent } = await render(group());
+            const spy = spyOnEvent('bsChange');
+            const tabs = Array.from(root.querySelectorAll('bs-tab'));
+            btn(tabs[0]).click();
+            await waitForChanges();
+            key(btn(tabs[0]), 'ArrowRight');
+            await waitForChanges();
+            expect(spy).toHaveReceivedEventDetail({ value: 'details' });
+        });
+        it('still emits bsSelect on the tab itself', async () => {
+            const { root, waitForChanges, spyOnEvent } = await render(group());
+            const spy = spyOnEvent('bsSelect');
+            btn(root.querySelectorAll('bs-tab')[2]).click();
+            await waitForChanges();
+            expect(spy).toHaveReceivedEventTimes(1);
+        });
+        it('works for bs-inline-tab groups', async () => {
+            const { root, waitForChanges, spyOnEvent } = await render(h("bs-tabs", { type: "bs-inline-tab" }, h("bs-inline-tab", { value: "x" }, "X"), h("bs-inline-tab", { value: "y" }, "Y")));
+            const spy = spyOnEvent('bsChange');
+            btn(root.querySelectorAll('bs-inline-tab')[1]).click();
+            await waitForChanges();
+            expect(spy).toHaveReceivedEventDetail({ value: 'y' });
+        });
+        it('a tab\'s value prop is reflected as an attribute', async () => {
+            const { root } = await render(group());
+            expect(root.querySelector('bs-tab').getAttribute('value')).toBe('overview');
+        });
+    });
 });

package/dist/collection/components/bs-tab/bs-tabs/bs-tabs.js

@@ -35,6 +35,16 @@ export class BsTabs {
     /** Layout direction of the tab bar itself. Sets `aria-orientation` on the internal wrapper and
      * switches `flex-direction`. */
     orientation = 'horizontal';
+    /** The selected tab's `value`. Mutable and reflected: it follows the user's selection, and
+     * setting it from outside (attribute or property) selects the matching tab -- without emitting
+     * `bsChange`, which only fires for user-driven changes. A tab's value is its own `value` prop,
+     * or, for a tab without one, its zero-based position in the group as a string (`"0"`, `"1"`...).
+     * If unset, it is read from whichever tab is already `selected` once the group loads. */
+    value;
+    /** Fires when the user selects a different tab (click, or arrow/Home/End), with the new
+     * `value`. Does not fire when `value` is set programmatically. `bsSelect` on the individual tab
+     * still fires as before. */
+    bsChange;
     /**
      * Catches `bsSelect` bubbling up from any slotted `<bs-tab>`/`<bs-inline-tab>` (Stencil's
      * `@Event()` defaults to `bubbles: true, composed: true`, and `@Listen` without a target listens
@@ -43,15 +53,46 @@ export class BsTabs {
      * `if (this.disabled) return;`), so no special-casing is needed here.
      */
     onTabSelect(ev) {
-        const tabs = this.el.querySelectorAll(':scope > bs-tab, :scope > bs-inline-tab');
+        const tabs = this.tabs();
         tabs.forEach(tab => {
             tab.selected = tab === ev.target;
         });
         this.syncRovingTabindex();
+        const index = tabs.findIndex(tab => tab === ev.target);
+        if (index === -1)
+            return;
+        const value = this.tabValue(tabs[index], index);
+        if (value !== this.value) {
+            this.value = value;
+            this.bsChange.emit({ value });
+        }
     }
     componentDidLoad() {
+        if (this.value !== undefined) {
+            this.applyValue();
+        }
+        else {
+            // Uncontrolled: report whichever tab the consumer already marked `selected`.
+            const tabs = this.tabs();
+            const index = tabs.findIndex(t => t.selected);
+            if (index !== -1)
+                this.value = this.tabValue(tabs[index], index);
+        }
         this.syncRovingTabindex();
     }
+    tabValue(tab, index) {
+        return tab.value ?? String(index);
+    }
+    /** Selects the tab whose value matches `this.value` (and deselects the rest). */
+    applyValue() {
+        this.tabs().forEach((tab, i) => {
+            tab.selected = this.tabValue(tab, i) === this.value;
+        });
+        this.syncRovingTabindex();
+    }
+    onValueChange() {
+        this.applyValue();
+    }
     syncRovingTabindex() {
         const tabs = this.tabs();
         const anySelected = tabs.some(t => t.selected);
@@ -94,7 +135,7 @@ export class BsTabs {
     }
     render() {
         const vertical = this.orientation === 'vertical';
-        return (h("div", { key: '81b3b46d54d4acc074b0c59d0da5e3e971e7b62e', part: "tablist", role: "tablist", "aria-orientation": this.orientation, class: `bs-tabs bs-tabs--${this.type} ${vertical ? 'bs-tabs--vertical' : ''}` }, h("slot", { key: 'ba296a99062629de3e331cd7de1ebc41548c77f9', onSlotchange: () => this.syncRovingTabindex() })));
+        return (h("div", { key: '251521d36dcf4d6960df344285bc9a060ff87abb', part: "tablist", role: "tablist", "aria-orientation": this.orientation, class: `bs-tabs bs-tabs--${this.type} ${vertical ? 'bs-tabs--vertical' : ''}` }, h("slot", { key: '02216f048eaedb13f00891c30e1c49d15a509c1d', onSlotchange: () => this.syncRovingTabindex() })));
     }
     static get is() { return "bs-tabs"; }
     static get encapsulation() { return "shadow"; }
@@ -161,12 +202,52 @@ export class BsTabs {
                 "reflect": false,
                 "attribute": "orientation",
                 "defaultValue": "'horizontal'"
+            },
+            "value": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "The selected tab's `value`. Mutable and reflected: it follows the user's selection, and\nsetting it from outside (attribute or property) selects the matching tab -- without emitting\n`bsChange`, which only fires for user-driven changes. A tab's value is its own `value` prop,\nor, for a tab without one, its zero-based position in the group as a string (`\"0\"`, `\"1\"`...).\nIf unset, it is read from whichever tab is already `selected` once the group loads."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "value"
             }
         };
     }
+    static get events() {
+        return [{
+                "method": "bsChange",
+                "name": "bsChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Fires when the user selects a different tab (click, or arrow/Home/End), with the new\n`value`. Does not fire when `value` is set programmatically. `bsSelect` on the individual tab\nstill fires as before."
+                },
+                "complexType": {
+                    "original": "{ value: string }",
+                    "resolved": "{ value: string; }",
+                    "references": {}
+                }
+            }];
+    }
     static get elementRef() { return "el"; }
     static get watchers() {
         return [{
+                "propName": "value",
+                "methodName": "onValueChange"
+            }, {
                 "propName": "orientation",
                 "methodName": "syncRovingTabindex"
             }];

package/dist/collection/components/bs-tab/bs-tabs/bs-tabs.stories.js

@@ -37,3 +37,27 @@ export const InlineTabGroup = {
 export const Vertical = {
     args: { orientation: 'vertical' },
 };
+// The group's `value` follows the selection, and `bsChange` reports user-driven changes: the panel
+// below switches in response to it, with no per-tab selection wiring.
+export const WithValueAndPanels = {
+    name: 'With value and panels',
+    render: () => {
+        const panels = {
+            overview: 'Overview content',
+            details: 'Details content',
+            history: 'History content',
+        };
+        const onChange = (ev) => {
+            const panel = ev.currentTarget.nextElementSibling;
+            panel.textContent = panels[ev.detail.value];
+        };
+        return html `
+      <bs-tabs value="overview" @bsChange=${onChange}>
+        <bs-tab value="overview">Overview</bs-tab>
+        <bs-tab value="details">Details</bs-tab>
+        <bs-tab value="history">History</bs-tab>
+      </bs-tabs>
+      <p role="tabpanel" style="margin: 16px 0 0;">Overview content</p>
+    `;
+    },
+};