@pine-ds/core 4.10.0 → 4.12.0

package/dist/collection/components/pds-switch/pds-switch.js

@@ -2,6 +2,7 @@ import { Host, h } from "@stencil/core";
 import { assignDescription, isSpecTest, messageId, exposeTypeProperty } from "../../utils/form";
 import { danger } from "@pine-ds/icons/icons";
 import { inheritAriaAttributes, HostStylingKeeper } from "../../utils/attributes";
+import { referencedElements } from "../../utils/aria-references";
 /**
  * @slot label - Content displayed as the switch label in place of the `label` text. Clicking it toggles the switch.
  */
@@ -9,8 +10,11 @@ export class PdsSwitch {
     constructor() {
         this.inheritedAttributes = {};
         this._type = 'checkbox';
+        this.forwardsDescription = false;
         this.hostKeeper = new HostStylingKeeper();
         this.hasLabelSlot = false;
+        // Kept apart from the `disabled` prop so a fieldset never overwrites what the consumer set.
+        this.fieldsetDisabled = false;
         /**
          * Determines the input 'checked' state.
          */
@@ -28,7 +32,7 @@ export class PdsSwitch {
          */
         this.required = false;
         this.onSwitchUpdate = (e) => {
-            if (this.disabled)
+            if (this.isDisabled())
                 return;
             const input = e.target;
             this.checked = input.checked;
@@ -48,10 +52,40 @@ export class PdsSwitch {
             }
             return switchClasses;
         };
+        // An ID on the host can't reach into the shadow root, so the input is pointed at the elements the host's
+        // aria-describedby names, followed by its own helper or error message. A browser without ARIA element
+        // reflection keeps the input's own message only.
+        this.forwardDescription = () => {
+            var _a;
+            const input = this.inputEl;
+            if (input === undefined || !('ariaDescribedByElements' in input))
+                return;
+            const ownId = this.ownDescriptionId();
+            const referenced = referencedElements(this.el, 'aria-describedby');
+            if (referenced.length === 0) {
+                if (!this.forwardsDescription)
+                    return;
+                this.forwardsDescription = false;
+                // Setting the element property cleared the attribute render wrote, so put that back.
+                if (ownId !== undefined) {
+                    input.setAttribute('aria-describedby', ownId);
+                }
+                else {
+                    input.removeAttribute('aria-describedby');
+                }
+                return;
+            }
+            const own = ownId === undefined ? null : (_a = this.el.shadowRoot) === null || _a === void 0 ? void 0 : _a.getElementById(ownId);
+            input.ariaDescribedByElements = own == null ? referenced : [...referenced, own];
+            this.forwardsDescription = true;
+        };
         this.updateHasLabelSlot = () => {
             this.hasLabelSlot = Array.from(this.el.children).some((child) => child.getAttribute('slot') === 'label');
         };
     }
+    isDisabled() {
+        return this.disabled || this.fieldsetDisabled;
+    }
     connectedCallback() {
         this.hostKeeper.connect(this.el);
         // Initialize ElementInternals for form association (only once per element instance)
@@ -60,28 +94,58 @@ export class PdsSwitch {
         }
         // Expose type property on the element instance to match native form element behavior
         exposeTypeProperty(this.el, () => this._type);
+        // A reconnected switch may sit in a different tree, where its description IDs name other elements.
+        this.forwardDescription();
+        if (typeof MutationObserver === 'undefined')
+            return;
+        // Consumers set aria-describedby on the host, sometimes after render, but only the inner input is announced.
+        this.hostDescriptionObserver = new MutationObserver(this.forwardDescription);
+        this.hostDescriptionObserver.observe(this.el, { attributeFilter: ['aria-describedby'] });
     }
     disconnectedCallback() {
+        var _a;
         this.hostKeeper.disconnect();
+        (_a = this.hostDescriptionObserver) === null || _a === void 0 ? void 0 : _a.disconnect();
+        this.hostDescriptionObserver = undefined;
+    }
+    componentDidRender() {
+        this.forwardDescription();
     }
     componentDidLoad() {
         this.updateFormValue();
     }
-    checkedChanged() {
+    syncFormValue() {
         this.updateFormValue();
     }
     updateFormValue() {
         if (isSpecTest())
             return;
         if (this.internals && this.internals.setFormValue) {
-            // For switches, only send the value when checked, otherwise send null
-            const formValue = this.checked ? (this.value || 'on') : null;
-            this.internals.setFormValue(formValue);
+            // The restoration state always carries the checked value, even while disabled, so a bfcache or
+            // back-forward restore can bring back a checked-then-disabled switch instead of losing it to a null state.
+            this.internals.setFormValue(this.formValue(), this.checkedValue());
         }
         if (this.internals && this.internals.setValidity) {
             this.internals.setValidity({});
         }
     }
+    // Unchecked sends uncheckedValue when set, even an empty string, otherwise nothing. Disabled sends nothing, like a
+    // native checkbox: the platform only leaves out a host with the disabled attribute present, which is also how
+    // React's own custom-element attribute serialization writes it.
+    formValue() {
+        if (this.isDisabled())
+            return null;
+        return this.checkedValue();
+    }
+    checkedValue() {
+        var _a;
+        if (this.checked)
+            return this.value || 'on';
+        return (_a = this.uncheckedValue) !== null && _a !== void 0 ? _a : null;
+    }
+    ownDescriptionId() {
+        return assignDescription(this.componentId, this.invalid, this.helperMessage, this.errorMessage);
+    }
     formStateRestoreCallback(state) {
         if (state instanceof FormData) {
             // For switches, restore if the value exists in FormData
@@ -101,21 +165,22 @@ export class PdsSwitch {
         // literal string "false" (a consumer's or React's attribute serialization can write that) —
         // the platform treats any value as disabled, independent of fieldset state. A real disabled
         // fieldset ancestor confirms this is genuinely that, not this element's own attribute.
-        if (disabled && !this.el.closest('fieldset[disabled]'))
-            return;
-        this.disabled = disabled;
+        this.fieldsetDisabled = disabled && this.el.closest('fieldset[disabled]') !== null;
     }
     componentWillLoad() {
-        this.inheritedAttributes = Object.assign({}, inheritAriaAttributes(this.el));
+        this.inheritedAttributes = Object.assign({}, inheritAriaAttributes(this.el, ['aria-describedby']));
         this.updateHasLabelSlot();
     }
     render() {
         const hostClass = this.switchClassNames();
-        const ariaDisabled = this.disabled ? 'true' : null;
+        const ariaDisabled = this.isDisabled() ? 'true' : null;
         this.hostKeeper.record(hostClass, {}, { 'aria-disabled': ariaDisabled });
-        return (h(Host, { key: '0fa5beb83232b381ea5cdfa82d143afcb69eb4e1', class: hostClass, "aria-disabled": ariaDisabled }, h("label", { key: 'df5d08344d11cb334ef69a432d1c02557caacc96', htmlFor: this.componentId }, h("input", Object.assign({ key: '6908b328f0e2da2085ffbffe0d1e4d09f2c6fd86', "aria-describedby": assignDescription(this.componentId, this.invalid, this.helperMessage, this.errorMessage), "aria-invalid": this.invalid ? "true" : undefined, checked: this.checked, class: "pds-switch__input", disabled: this.disabled, id: this.componentId, name: this.name ? this.name : this.componentId, onChange: this.onSwitchUpdate, required: this.required, type: "checkbox", value: this.value }, this.inheritedAttributes)), h("span", { key: '1108ab3eae63a371f9e9b80f011211cba8287b67', class: this.hideLabel ? 'visually-hidden' : '' }, h("slot", { key: '8aac1d9b81deab92e1e27c06debf2b87bc697874', name: "label", onSlotchange: this.updateHasLabelSlot }), !this.hasLabelSlot && this.label)), this.helperMessage &&
-            h("div", { key: 'ef829fb6bc66060805a144995f60e2bebb915615', class: `pds-switch__message`, id: messageId(this.componentId, 'helper') }, this.helperMessage), this.errorMessage &&
-            h("div", { key: '42ad678cc2179b4a26ed09151de41c2293b98011', class: `pds-switch__message pds-switch__message--error`, id: messageId(this.componentId, 'error'), "aria-live": "assertive" }, h("pds-icon", { key: '8dc0b29b522247762010edb3b1e8e5fc8c8788fa', "aria-hidden": "true", icon: danger, size: "small" }), this.errorMessage)));
+        return (h(Host, { key: 'e5100ae3ecfac3bb556582507cc628b2455ae6cc', class: hostClass, "aria-disabled": ariaDisabled }, h("label", { key: 'c337b8c4dc381c3a745100c707792c11711c01a1', htmlFor: this.componentId }, h("input", Object.assign({ key: 'f18ae27e7c91ef4d54b0192a04130420b991c9ff', "aria-describedby": this.ownDescriptionId(), "aria-invalid": this.invalid ? "true" : undefined, checked: this.checked, class: "pds-switch__input", disabled: this.isDisabled(), id: this.componentId, name: this.name ? this.name : this.componentId, onChange: this.onSwitchUpdate,
+            // A description added after the switch, or replaced by a framework or a DOM morph, is picked up by the
+            // time focus reaches the switch and it's announced.
+            onFocus: this.forwardDescription, ref: (el) => (this.inputEl = el), required: this.required, type: "checkbox", value: this.value }, this.inheritedAttributes)), h("span", { key: '4bddfc080db7fee6fa8080e890918757dacde3fb', class: this.hideLabel ? 'visually-hidden' : '' }, h("slot", { key: 'c9302409719113e12f6debb426c78dd0caaee88a', name: "label", onSlotchange: this.updateHasLabelSlot }), !this.hasLabelSlot && this.label)), this.helperMessage &&
+            h("div", { key: '60785b9779cb2d50e6f0f2b32179106256f55ebf', class: `pds-switch__message`, id: messageId(this.componentId, 'helper') }, this.helperMessage), this.errorMessage &&
+            h("div", { key: '9b258e9302c5ef959e8c06bee780d7d43144359b', class: `pds-switch__message pds-switch__message--error`, id: messageId(this.componentId, 'error'), "aria-live": "assertive" }, h("pds-icon", { key: 'f8df779a8c65a6f0b6ea139ff3c31cca76eb48fa', "aria-hidden": "true", icon: danger, size: "small" }), this.errorMessage)));
     }
     static get is() { return "pds-switch"; }
     static get encapsulation() { return "shadow"; }
@@ -299,11 +364,11 @@ export class PdsSwitch {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Identifies form data and unifies a group of radio inputs for toggling a single property/value."
+                    "text": "Specifies the name. Submitted with the form name/value pair when checked, or with `unchecked-value` while unchecked."
                 },
                 "getter": false,
                 "setter": false,
-                "reflect": false,
+                "reflect": true,
                 "attribute": "name"
             },
             "required": {
@@ -344,12 +409,32 @@ export class PdsSwitch {
                 "setter": false,
                 "reflect": false,
                 "attribute": "value"
+            },
+            "uncheckedValue": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Provides a string submitted in form data under `name` while the switch is unchecked.\nWhen unset, an unchecked switch submits nothing, like a native checkbox."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "unchecked-value"
             }
         };
     }
     static get states() {
         return {
-            "hasLabelSlot": {}
+            "hasLabelSlot": {},
+            "fieldsetDisabled": {}
         };
     }
     static get events() {
@@ -379,7 +464,19 @@ export class PdsSwitch {
     static get watchers() {
         return [{
                 "propName": "checked",
-                "methodName": "checkedChanged"
+                "methodName": "syncFormValue"
+            }, {
+                "propName": "disabled",
+                "methodName": "syncFormValue"
+            }, {
+                "propName": "fieldsetDisabled",
+                "methodName": "syncFormValue"
+            }, {
+                "propName": "uncheckedValue",
+                "methodName": "syncFormValue"
+            }, {
+                "propName": "value",
+                "methodName": "syncFormValue"
             }];
     }
 }

package/dist/collection/components/pds-switch/stories/pds-switch.stories.js

@@ -1,4 +1,5 @@
 import { html } from 'lit';
+import { ifDefined } from 'lit/directives/if-defined.js';
 
 
 export default {
@@ -27,6 +28,8 @@ const BaseTemplate = (args) => html`
     onChange=${args.onChange}
     ?required=${args.required}
     type=${args.type}
+    unchecked-value=${ifDefined(args.uncheckedValue)}
+    value=${ifDefined(args.value)}
   />
 `;
 
@@ -83,3 +86,79 @@ Invalid.args = {
   required: true,
   type: 'checkbox',
 };
+
+export const DisabledWithReason = BaseTemplate.bind({});
+
+DisabledWithReason.args = {
+  checked: false,
+  disabled: true,
+  componentId: 'pds-switch-disabled-reason-example',
+  helperMessage: 'Free offers can\'t have affiliate commissions.',
+  invalid: false,
+  label: 'Affiliate commissions',
+  name: 'pds-switch-disabled-reason',
+  required: false,
+  type: 'checkbox',
+};
+
+export const Described = (args) => html`
+  <pds-box direction="column" gap="xs">
+    <pds-text id="pds-switch-described-text" tag="p">Send customers a receipt after each purchase.</pds-text>
+    <pds-switch
+      aria-describedby="pds-switch-described-text"
+      ?checked=${args.checked}
+      component-id=${args.componentId}
+      ?disabled=${args.disabled}
+      label=${args.label}
+      name=${args.name}
+    ></pds-switch>
+  </pds-box>
+`;
+
+Described.args = {
+  checked: false,
+  disabled: false,
+  componentId: 'pds-switch-described-example',
+  label: 'Purchase receipts',
+  name: 'pds-switch-described',
+};
+
+// Shows what the form submits, since an unchecked value isn't visible on the switch itself.
+const showFormData = (event) => {
+  const form = event.target.closest('form');
+  const output = form?.querySelector('output');
+  if (!form || !output) return;
+  // The switch sets its form value before it emits pdsSwitchChange, so FormData is already current here.
+  const entries = Array.from(new FormData(form).entries());
+  output.textContent = entries.length > 0 ? entries.map(([key, value]) => `${key}=${value}`).join('&') : '(nothing)';
+};
+
+const submitted = ({ checked, name, uncheckedValue, value }) => {
+  if (checked) return `${name}=${value || 'on'}`;
+  return uncheckedValue === undefined ? '(nothing)' : `${name}=${uncheckedValue}`;
+};
+
+export const UncheckedValue = (args) => html`
+  <form @pdsSwitchChange=${showFormData}>
+    <pds-box direction="column" gap="sm">
+      <pds-switch
+        ?checked=${args.checked}
+        component-id=${args.componentId}
+        label=${args.label}
+        name=${args.name}
+        unchecked-value=${ifDefined(args.uncheckedValue)}
+        value=${ifDefined(args.value)}
+      ></pds-switch>
+      <pds-text tag="p">Submits: <output>${submitted(args)}</output></pds-text>
+    </pds-box>
+  </form>
+`;
+
+UncheckedValue.args = {
+  checked: false,
+  componentId: 'pds-switch-unchecked-value-example',
+  label: 'Email notifications',
+  name: 'notify',
+  uncheckedValue: '0',
+  value: '1',
+};

package/dist/collection/components/pds-table/pds-table-body/pds-table-body.js

@@ -1,7 +1,10 @@
 import { Host, h } from "@stencil/core";
+/**
+ * @part body - Set on the `pds-table-body` element itself, so `::part(body)` matches it only from a shadow root that contains it. Style `pds-table-body` directly instead.
+ */
 export class PdsTableBody {
     render() {
-        return (h(Host, { key: '4f1cba9505f56ff1ab0a19f9a88318d66a02eacc', role: "rowgroup", part: "body" }, h("slot", { key: 'ea0c620a15fcbe2915189e870d0815c5cbffdf8c' })));
+        return (h(Host, { key: '4b4da65979e3d3557d05cb9aff8d257d29e2c0a5', role: "rowgroup", part: "body" }, h("slot", { key: '70dcd401a705a430c54c57bf994a410a636c4a53' })));
     }
     static get is() { return "pds-table-body"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/components/pds-table/pds-table-cell/pds-table-cell.js

@@ -1,6 +1,10 @@
 import { Host, h } from "@stencil/core";
+import { closest } from "../../../utils/closest";
 import { isScrolledFromInlineStart } from "../../../utils/scroll";
 import { setupTruncationTooltip } from "../../../utils/truncation-tooltip";
+/**
+ * @part cell - Set on the `pds-table-cell` element itself, so `::part(cell)` matches it only from a shadow root that contains it. Style `pds-table-cell` directly instead. In a `selectable` table, each row's selection cell sits in the row's shadow root: it has the `checkbox-cell` part when first rendered and `cell` after any re-render, so target both with `pds-table-row::part(checkbox-cell), pds-table-row::part(cell)`.
+ */
 export class PdsTableCell {
     constructor() {
         this.scrollContainer = null;
@@ -30,14 +34,16 @@ export class PdsTableCell {
         };
     }
     componentWillRender() {
-        this.tableRef = this.hostElement.closest('pds-table');
+        // The shadow-crossing `closest` util, not the native one -- a selectable row's checkbox
+        // cell lives inside pds-table-row's own shadow root, which native `closest` can't see past.
+        this.tableRef = closest('pds-table', this.hostElement);
     }
     // Fires again each time the cell is moved (a sort re-appends every row), unlike componentDidLoad,
     // so it re-binds what disconnectedCallback tore down. The tooltip binds to the host, which exists before load.
     connectedCallback() {
         if (!this.hasLoaded)
             return;
-        this.tableRef = this.hostElement.closest('pds-table');
+        this.tableRef = closest('pds-table', this.hostElement);
         this.cleanupScrollListener();
         if (this.needsScrollShadow) {
             this.setupScrollListener();
@@ -103,6 +109,22 @@ export class PdsTableCell {
             this.setupTimer = undefined;
         }
         this.setupRetries = 0; // Reset retry counter
+        // Without a listener there's no way to know the scroll position any more, so the shadow
+        // this drove shouldn't linger -- matters when a rebind tears this down without setting it
+        // back up (responsive turned off while scrolled), not just on disconnect.
+        this.tableScrolling = false;
+    }
+    /**
+     * Re-binds the scroll listener to the table's current responsive container. Called by
+     * `pds-table` after a live `responsive` toggle: the cell stays in light DOM across that change,
+     * so it never reconnects on its own and would otherwise keep listening to a container the
+     * table already replaced or removed.
+     */
+    async rebindScrollListener() {
+        this.cleanupScrollListener();
+        if (this.needsScrollShadow) {
+            this.setupScrollListener();
+        }
     }
     handleTruncateChange(newValue) {
         if (newValue) {
@@ -143,11 +165,11 @@ export class PdsTableCell {
         return classNames.join(' ');
     }
     render() {
-        return (h(Host, { key: 'fd84150bcb9bd5d2029624394d4f69b0a7234bc0', class: this.classNames(), role: "gridcell", part: "cell", style: this.tableRef &&
+        return (h(Host, { key: 'bc40b70bcb8f1df7307df6c00e3b73427c8d5ff2', class: this.classNames(), role: "gridcell", part: "cell", style: this.tableRef &&
                 this.tableRef.fixedColumn &&
                 this.tableRef.selectable
                 ? { '--fixed-cell-position': '40px' }
-                : {} }, h("slot", { key: '9256f033ec58b9cb2acc74d705acc9726507668b' })));
+                : {} }, h("slot", { key: '418219bf8b870557f5f39ae6553db78fe7037389' })));
     }
     static get is() { return "pds-table-cell"; }
     static get encapsulation() { return "shadow"; }
@@ -208,6 +230,27 @@ export class PdsTableCell {
             "tableScrolling": {}
         };
     }
+    static get methods() {
+        return {
+            "rebindScrollListener": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Re-binds the scroll listener to the table's current responsive container. Called by\n`pds-table` after a live `responsive` toggle: the cell stays in light DOM across that change,\nso it never reconnects on its own and would otherwise keep listening to a container the\ntable already replaced or removed.",
+                    "tags": []
+                }
+            }
+        };
+    }
     static get elementRef() { return "hostElement"; }
     static get watchers() {
         return [{

package/dist/collection/components/pds-table/pds-table-head/pds-table-head.js

@@ -1,5 +1,9 @@
 import { Host, h } from "@stencil/core";
 import { closest } from "../../../utils/closest";
+/**
+ * @part head - Set on the `pds-table-head` element itself, so `::part(head)` matches it only from a shadow root that contains it. Style `pds-table-head` directly instead.
+ * @part select-all-checkbox - Exposes the select-all checkbox for styling. Appears only when the table is `selectable` and `disableSelectAll` isn't set.
+ */
 export class PdsTableHead {
     constructor() {
         /**
@@ -42,7 +46,7 @@ export class PdsTableHead {
         }
     }
     render() {
-        return (h(Host, { key: '4fb8d7bf4a9b0bce672208651c0600fbc94214af', role: "row", part: "head" }, this.tableRef && this.tableRef.selectable && (h("pds-table-head-cell", { key: '20b86146540208178bd63bd136e14e5534c7ec76', part: this.tableRef.selectable ? 'checkbox-cell' : '' }, !this.tableRef.disableSelectAll && (h("pds-checkbox", { key: 'fa8054dd7ee36c6401e9eeb9c962a820d3a02558', componentId: this.generateUniqueId(), indeterminate: this.indeterminate, onInput: this.handleInput, label: "Select All Rows", hideLabel: true, checked: this.isSelected, part: "select-all-checkbox" })))), h("slot", { key: 'a0000270ae6ed1cab1c6e802ccc53ba0de3e54c9' })));
+        return (h(Host, { key: 'ba81f3a9655b49cf01311c697a8aae3e69de0e81', role: "row", part: "head" }, this.tableRef && this.tableRef.selectable && (h("pds-table-head-cell", { key: '4f182b3053469afbaff81c4918bf66376fc7ade4', part: this.tableRef.selectable ? 'checkbox-cell' : '', width: this.tableRef.tableLayout === 'fixed' ? 'var(--pine-dimension-2xl)' : undefined }, !this.tableRef.disableSelectAll && (h("pds-checkbox", { key: 'b26c7e8c26b3cc837f180431dc53a17ae0d84f1f', componentId: this.generateUniqueId(), indeterminate: this.indeterminate, onInput: this.handleInput, label: "Select All Rows", hideLabel: true, checked: this.isSelected, part: "select-all-checkbox" })))), h("slot", { key: 'e9eef43af95340fcce2d9f2f60800d897ee423f1' })));
     }
     static get is() { return "pds-table-head"; }
     static get encapsulation() { return "shadow"; }
@@ -92,7 +96,7 @@ export class PdsTableHead {
                             "name": "defaultValue",
                             "text": "false"
                         }],
-                    "text": "Determines if the table row is currently selected."
+                    "text": "Determines if the select all checkbox is checked."
                 },
                 "getter": false,
                 "setter": false,

package/dist/collection/components/pds-table/pds-table-head-cell/pds-table-head-cell.css

@@ -16,6 +16,17 @@
   vertical-align: inherit;
 }
 
+:host(.has-width) {
+  box-sizing: border-box;
+  min-width: var(--pds-table-head-cell-width);
+  width: var(--pds-table-head-cell-width);
+}
+
+:host(.has-auto-width) {
+  box-sizing: border-box;
+  width: var(--pds-table-head-cell-auto-floor-width, auto);
+}
+
 :host(.is-compact) {
   padding-block: var(--pine-dimension-2xs);
 }

package/dist/collection/components/pds-table/pds-table-head-cell/pds-table-head-cell.js

@@ -1,10 +1,16 @@
 import { Host, h } from "@stencil/core";
 import { downSmall, upSmall } from "@pine-ds/icons/icons";
+import { closest } from "../../../utils/closest";
 import { isScrolledFromInlineStart } from "../../../utils/scroll";
+/**
+ * @part head-cell - Set on the `pds-table-head-cell` element itself, so `::part(head-cell)` matches it only from a shadow root that contains it. Style `pds-table-head-cell` directly instead. In a `selectable` table, the select-all cell sits in `pds-table-head`'s shadow root: it has the `checkbox-cell` part when first rendered and `head-cell` after any re-render, so target both with `pds-table-head::part(checkbox-cell), pds-table-head::part(head-cell)`.
+ * @part sort-icon - Exposes the sort direction icon for styling. Appears only on a `sortable` column while it's the active sort.
+ */
 export class PdsTableHeadCell {
     constructor() {
         this.scrollContainer = null;
         this.setupRetries = 0;
+        this.hasLoaded = false;
         /**
          * The direction of sorting.
          */
@@ -96,22 +102,39 @@ export class PdsTableHeadCell {
         this.hostElement.classList.remove('is-active');
     }
     componentWillLoad() {
-        // Set initial references and state before first render
-        this.tableRef = this.hostElement.closest('pds-table');
-        const tableHead = this.hostElement.closest('pds-table-head');
+        // Set initial references and state before first render. The shadow-crossing `closest`
+        // util, not the native one -- the select-all cell lives inside pds-table-head's own shadow
+        // root, which native `closest` can't see past.
+        this.tableRef = closest('pds-table', this.hostElement);
+        const tableHead = closest('pds-table-head', this.hostElement);
         if (tableHead) {
             this.hasHeadBorder = tableHead.hasAttribute('border');
             this.hasHeadBackground = tableHead.hasAttribute('background');
         }
     }
+    // Fires again each time the cell is moved (such as a reparent or DOM morph), unlike
+    // componentDidLoad, so it re-binds what disconnectedCallback tore down.
+    connectedCallback() {
+        if (!this.hasLoaded)
+            return;
+        this.tableRef = closest('pds-table', this.hostElement);
+        if (this.tableRef && this.tableRef.responsive && this.tableRef.fixedColumn) {
+            this.setupScrollListener();
+        }
+        this.setupHeadObserver();
+    }
     componentDidLoad() {
+        this.hasLoaded = true;
         if (this.tableRef && this.tableRef.responsive && this.tableRef.fixedColumn) {
             // For responsive tables with fixed columns, set up scroll detection
             // This enables the first column header to show a shadow when the table is scrolled horizontally
             this.setupScrollListener();
         }
-        // Watch for changes to the parent table-head's border and background attributes
-        const tableHead = this.hostElement.closest('pds-table-head');
+        this.setupHeadObserver();
+    }
+    // Watches the parent table-head's border and background attributes.
+    setupHeadObserver() {
+        const tableHead = closest('pds-table-head', this.hostElement);
         if (tableHead && typeof MutationObserver !== 'undefined') {
             // Defensive guard: disconnect existing observer before creating a new one
             if (this.headObserver) {
@@ -172,6 +195,22 @@ export class PdsTableHeadCell {
             this.setupTimer = undefined;
         }
         this.setupRetries = 0; // Reset retry counter
+        // Without a listener there's no way to know the scroll position any more, so the shadow
+        // this drove shouldn't linger -- matters when a rebind tears this down without setting it
+        // back up (responsive turned off while scrolled), not just on disconnect.
+        this.tableScrolling = false;
+    }
+    /**
+     * Re-binds the scroll listener to the table's current responsive container. Called by
+     * `pds-table` after a live `responsive` toggle: the cell stays in light DOM across that
+     * change, so it never reconnects on its own and would otherwise keep listening to a container
+     * the table already replaced or removed.
+     */
+    async rebindScrollListener() {
+        this.cleanupScrollListener();
+        if (this.tableRef && this.tableRef.responsive && this.tableRef.fixedColumn) {
+            this.setupScrollListener();
+        }
     }
     classNames() {
         const classNames = [];
@@ -196,14 +235,27 @@ export class PdsTableHeadCell {
         if (this.hasHeadBorder) {
             classNames.push('has-head-border');
         }
+        if (this.width) {
+            classNames.push('has-width');
+        }
+        else if (this.tableRef && this.tableRef.tableLayout === 'fixed') {
+            classNames.push('has-auto-width');
+        }
         return classNames.join(' ');
     }
+    hostStyles() {
+        const styles = {};
+        if (this.tableRef && this.tableRef.fixedColumn && this.tableRef.selectable) {
+            styles['--fixed-cell-position'] = '40px';
+        }
+        // Hand the width to the stylesheet as a custom property rather than an inline width.
+        if (this.width) {
+            styles['--pds-table-head-cell-width'] = this.width;
+        }
+        return styles;
+    }
     render() {
-        return (h(Host, { key: 'd609309180968913315c1428d0403c3974a4bfc0', class: this.classNames(), role: "columnheader", onClick: this.toggleSort, part: "head-cell", style: this.tableRef &&
-                this.tableRef.fixedColumn &&
-                this.tableRef.selectable
-                ? { '--fixed-cell-position': '40px' }
-                : {} }, h("slot", { key: '7aff5994fe4c5250ce83516960183dbd9ffa9c69' }), this.sortable && this.isActive && (h("pds-icon", { key: '0a7b99ab2c56ea0cfb3aa6f810bf802422a29bef', icon: this.sortingDirection === 'asc' ? upSmall : downSmall, part: "sort-icon", "aria-hidden": "true" }))));
+        return (h(Host, { key: '353a05a4026064d05a4b924bec3fa2f17f1902ce', class: this.classNames(), role: "columnheader", onClick: this.toggleSort, part: "head-cell", style: this.hostStyles() }, h("slot", { key: '51ead68fc052805d60bbfc6e626f6aedcc5671fc' }), this.sortable && this.isActive && (h("pds-icon", { key: '9a5c27232f06a15dc8329c329f01b08cb6d836b8', icon: this.sortingDirection === 'asc' ? upSmall : downSmall, part: "sort-icon", "aria-hidden": "true" }))));
     }
     static get is() { return "pds-table-head-cell"; }
     static get encapsulation() { return "shadow"; }
@@ -256,6 +308,25 @@ export class PdsTableHeadCell {
                 "setter": false,
                 "reflect": false,
                 "attribute": "sortable"
+            },
+            "width": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Sets the width of the column. Accepts any CSS length (e.g. '148px', '12rem', '20%').\nWhen the table's `tableLayout` is `fixed`, the column keeps this width whatever its content.\nOtherwise the column is at least this wide and can grow to fit its content."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "width"
             }
         };
     }
@@ -329,6 +400,23 @@ export class PdsTableHeadCell {
                     "text": "Clears the active sort state from this column.\nUsed internally when another column becomes active.",
                     "tags": []
                 }
+            },
+            "rebindScrollListener": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Re-binds the scroll listener to the table's current responsive container. Called by\n`pds-table` after a live `responsive` toggle: the cell stays in light DOM across that\nchange, so it never reconnects on its own and would otherwise keep listening to a container\nthe table already replaced or removed.",
+                    "tags": []
+                }
             }
         };
     }