@pine-ds/core 4.10.0 → 4.12.0

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

@@ -13,7 +13,7 @@ export class PdsRadio {
         this.hostKeeper = new HostStylingKeeper();
         this._hasImage = false;
         /**
-         * Determines whether or not the radio is checked.
+         * Determines whether or not the radio is checked. It keeps the value you set and doesn't change when the user picks a radio.
          * @defaultValue false
          */
         this.checked = false;
@@ -111,14 +111,14 @@ export class PdsRadio {
     }
     render() {
         const renderLabelAndMessages = () => [
-            h("label", { htmlFor: this.componentId, key: `${this.componentId}-label` }, h("input", { key: 'fdd83248666907fa25c5406cdedcd0e6f8d45f50', "aria-describedby": assignDescription(this.componentId, this.invalid, this.helperMessage, this.errorMessage), "aria-invalid": this.invalid ? "true" : undefined, type: "radio", id: this.componentId, name: this.name, value: this.value, checked: this.checked, required: this.required, disabled: this.disabled, onChange: this.handleRadioChange, class: this.hasImage() || this.isPill() ? 'visually-hidden' : '' }), h("span", { key: '73166ffd57cdb1f3b9e2b61fe880216b23a6510b', class: this.hideLabel && !this.isPill() ? 'visually-hidden' : '' }, this.label)),
+            h("label", { htmlFor: this.componentId, key: `${this.componentId}-label` }, h("input", { key: '245464683e5944a26a94509f487deb10ed4e8f05', "aria-describedby": assignDescription(this.componentId, this.invalid, this.helperMessage, this.errorMessage), "aria-invalid": this.invalid ? "true" : undefined, type: "radio", id: this.componentId, name: this.name, value: this.value, checked: this.checked, required: this.required, disabled: this.disabled, onChange: this.handleRadioChange, class: this.hasImage() || this.isPill() ? 'visually-hidden' : '' }), h("span", { key: '4d21fa0984501adc8ffc5fd7328b5dbd9cdfb98a', class: this.hideLabel && !this.isPill() ? 'visually-hidden' : '' }, this.label)),
             this.helperMessage && (h("div", { key: `${this.componentId}-helper`, class: 'pds-radio__message', id: messageId(this.componentId, 'helper') }, this.helperMessage)),
-            this.errorMessage && (h("div", { key: `${this.componentId}-error`, class: `pds-radio__message pds-radio__message--error`, id: messageId(this.componentId, 'error'), "aria-live": "assertive" }, h("pds-icon", { key: 'e5bca81578382181b6fce61fa6830fd60e54234a', "aria-hidden": "true", icon: danger, size: "small" }), this.errorMessage))
+            this.errorMessage && (h("div", { key: `${this.componentId}-error`, class: `pds-radio__message pds-radio__message--error`, id: messageId(this.componentId, 'error'), "aria-live": "assertive" }, h("pds-icon", { key: 'ed7bc193c25165d38a227887acda90675fe318f2', "aria-hidden": "true", icon: danger, size: "small" }), this.errorMessage))
         ];
         const hostClass = this.classNames();
         this.hostKeeper.record(hostClass);
         const showImage = this.hasImage() && !this.isPill();
-        return (h(Host, { key: '4cf39a988cc7642234ff62e7fa2f0d08b09e7d25', class: hostClass }, showImage && (h("div", { key: '7a88d32f896ad4696ea46b13f9ef01e7df0a1c3e', class: "pds-radio__image-container", part: "image-container" }, h("slot", { key: 'eb8399263443d36ab91c0875602d0dc31f036058', name: "image", onSlotchange: () => (this._hasImage = this.hasImageSlot()) }))), showImage ? (h("div", { class: "pds-radio__content-wrapper" }, renderLabelAndMessages())) : (renderLabelAndMessages())));
+        return (h(Host, { key: 'b8d059bab47b36b7e7b89172e54c57b8df4ce9c7', class: hostClass }, showImage && (h("div", { key: 'bea622fc1afdaacd91f2e89aa7529e54c22c88da', class: "pds-radio__image-container", part: "image-container" }, h("slot", { key: '3eca85a2457b25fa51509b28543ba897e3d99ab6', name: "image", onSlotchange: () => (this._hasImage = this.hasImageSlot()) }))), showImage ? (h("div", { class: "pds-radio__content-wrapper" }, renderLabelAndMessages())) : (renderLabelAndMessages())));
     }
     static get is() { return "pds-radio"; }
     static get encapsulation() { return "scoped"; }
@@ -149,7 +149,7 @@ export class PdsRadio {
                             "name": "defaultValue",
                             "text": "false"
                         }],
-                    "text": "Determines whether or not the radio is checked."
+                    "text": "Determines whether or not the radio is checked. It keeps the value you set and doesn't change when the user picks a radio."
                 },
                 "getter": false,
                 "setter": false,
@@ -211,7 +211,7 @@ export class PdsRadio {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Displays error message text describing an invalid state."
+                    "text": "Displays an error message below the radio. It becomes the radio's accessible description only while `invalid` is set."
                 },
                 "getter": false,
                 "setter": false,
@@ -230,7 +230,7 @@ export class PdsRadio {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Displays helper message text below radio."
+                    "text": "Displays a message or hint below the radio."
                 },
                 "getter": false,
                 "setter": false,
@@ -295,7 +295,7 @@ export class PdsRadio {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "String used for label text next to radio."
+                    "text": "Text to be displayed as the radio label."
                 },
                 "getter": false,
                 "setter": false,
@@ -421,7 +421,7 @@ export class PdsRadio {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": "Emits a boolean indicating whether the radio is currently checked or unchecked."
+                    "text": "Emitted with `true` when the user checks the radio, by a click or an arrow key. The radio is `event.target`, so read its `value` there.\nNot emitted when picking another radio unchecks this one. Not emitted inside `pds-radio-group` either; listen for `pdsRadioGroupChange` there."
                 },
                 "complexType": {
                     "original": "boolean",

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

@@ -42,34 +42,34 @@ const BaseTemplate = (args) =>
 
 export const Default = BaseTemplate.bind();
 Default.args = {
-  componentId: 'default',
+  componentId: 'radio-default',
   label: 'Label text',
 };
 
 export const Checked = BaseTemplate.bind();
 Checked.args = {
-  componentId: 'checked',
+  componentId: 'radio-checked',
   label: 'Label text',
   checked: true,
 };
 
 export const Disabled = BaseTemplate.bind();
 Disabled.args = {
-  componentId: 'disabled',
+  componentId: 'radio-disabled',
   label: 'Label text',
   disabled: true,
 };
 
 export const withMessage = BaseTemplate.bind();
 withMessage.args = {
-  componentId: 'with-message',
+  componentId: 'radio-with-message',
   label: 'Label text',
   helperMessage: 'This is short message text',
 };
 
 export const Invalid = BaseTemplate.bind();
 Invalid.args = {
-  componentId: 'invalid',
+  componentId: 'radio-invalid',
   errorMessage: 'This is a short error message',
   label: 'Label text',
   invalid: true,
@@ -77,7 +77,7 @@ Invalid.args = {
 
 export const WithBorder = BaseTemplate.bind();
 WithBorder.args = {
-  componentId: 'with-border',
+  componentId: 'radio-with-border',
   label: 'Label text',
   hasBorder: true,
   helperMessage: 'This radio has a border for better visual separation',
@@ -98,21 +98,21 @@ const ImageTemplate = (args) =>
     value=${args.value}
     ?invalid=${args.invalid}
   >
-    <pds-box slot="image" background-color="var(--pine-color-accent)" border-radius="full" padding="sm">
+    <pds-box slot="image" background-color="var(--pine-color-accent)" border-radius="circle" padding="sm">
       <pds-icon icon="danger" size="medium" color="var(--pine-color-white)" />
     </pds-box>
   </pds-radio>`;
 
 export const WithImage = ImageTemplate.bind();
 WithImage.args = {
-  componentId: 'with-image',
+  componentId: 'radio-with-image',
   label: 'Option with image',
   helperMessage: 'This radio includes an image using the image slot',
 };
 
 export const Pill = BaseTemplate.bind();
 Pill.args = {
-  componentId: 'pill',
+  componentId: 'radio-pill',
   label: 'Label text',
   variant: 'pill',
 };

package/dist/collection/components/pds-radio-group/pds-radio-group.js

@@ -222,13 +222,13 @@ export class PdsRadioGroup {
             'aria-describedby': ariaDescribedBy,
             'aria-labelledby': ariaLabelledBy === this.labelId ? ariaLabelledBy : undefined,
         });
-        return (h(Host, { key: '0fe381f99dddae0aeb9189a13b0e2195f1c79886', class: hostClass, id: this._groupId, role: "radiogroup", "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, style: {
+        return (h(Host, { key: 'c0d30ada4c215a2a316e55e0c564eb2d74f811be', class: hostClass, id: this._groupId, role: "radiogroup", "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, style: {
                 '--pds-radio-group-gap': gapValue,
-            } }, this.groupLabel && (h("div", { key: '4967dc22fa0265dbfbabf94a49b182b8c06d0bd5', class: "pds-radio-group__label", id: this.labelId }, this.groupLabel)), h("div", { key: '7a782a6920de7eda76ab0060c7512f093671ad41', class: {
+            } }, this.groupLabel && (h("div", { key: 'c237d7907b458131fd248b50b36f45df3c49f084', class: "pds-radio-group__label", id: this.labelId }, this.groupLabel)), h("div", { key: 'd31f36e69c4ee2fc9f9c86f0a25d56a4a5272372', class: {
                 'pds-radio-group__radios': true,
                 'pds-radio-group__radios--row': this.direction === 'row',
                 'pds-radio-group__radios--column': this.direction === 'column',
-            } }, h("slot", { key: '48a8d2d74961a402e3a1b053b2f0314e74b4b289', onSlotchange: () => this.updateChildRadios() })), this.helperMessage && (h("div", { key: '58db96d62b8d89f03ab245990d2d6bbd3b1b5f85', class: "pds-radio-group__message", id: messageId(this._groupId, 'helper') }, this.helperMessage)), this.errorMessage && (h("div", { key: 'ad3aafe5f7ed45853c36b537525a8fff68452f55', class: "pds-radio-group__message pds-radio-group__message--error", id: messageId(this._groupId, 'error'), "aria-live": "assertive" }, h("pds-icon", { key: '80ce92868703c5e01434e7e83a7668e320bcbee1', "aria-hidden": "true", icon: danger, size: "small" }), this.errorMessage))));
+            } }, h("slot", { key: '20153277b51dfe816596d7c4d7d1d12eaf08362a', onSlotchange: () => this.updateChildRadios() })), this.helperMessage && (h("div", { key: '1d48f78e3c3c56c949868a868bf9d73bdff81beb', class: "pds-radio-group__message", id: messageId(this._groupId, 'helper') }, this.helperMessage)), this.errorMessage && (h("div", { key: 'c2d0d3f60b9a598d60b372945852f0a7e512abbf', class: "pds-radio-group__message pds-radio-group__message--error", id: messageId(this._groupId, 'error'), "aria-live": "assertive" }, h("pds-icon", { key: '2f187a2fea00871f9980cc0fe799c758723174fe', "aria-hidden": "true", icon: danger, size: "small" }), this.errorMessage))));
     }
     static get is() { return "pds-radio-group"; }
     static get encapsulation() { return "scoped"; }
@@ -298,7 +298,7 @@ export class PdsRadioGroup {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Displays error message text describing an invalid state for the entire group."
+                    "text": "Displays an error message below the radio group. It's part of the group's accessible description, with or without `invalid`."
                 },
                 "getter": false,
                 "setter": false,
@@ -317,7 +317,7 @@ export class PdsRadioGroup {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Displays helper message text below the radio group."
+                    "text": "Displays a message or hint below the radio group."
                 },
                 "getter": false,
                 "setter": false,
@@ -405,7 +405,7 @@ export class PdsRadioGroup {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "String used for group label/heading."
+                    "text": "Text to be displayed as the radio group label. It also names the group, unless you set `aria-label` or `aria-labelledby` on it."
                 },
                 "getter": false,
                 "setter": false,
@@ -465,7 +465,7 @@ export class PdsRadioGroup {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": "Emits when a radio in the group is selected, providing the selected value and component ID."
+                    "text": "Emitted when the user checks a radio in the group, by a click or an arrow key. `detail` has that radio's `value`\nand `componentId`, and `checked`, which is always `true`."
                 },
                 "complexType": {
                     "original": "RadioGroupChangeEventDetail",

package/dist/collection/components/pds-radio-group/stories/pds-radio-group.stories.js

@@ -101,17 +101,17 @@ const ImageTemplate = (args) =>
     ?required=${args.required}
   >
     <pds-radio component-id="radio1" label="John Doe" value="john" helper-message="Senior Developer">
-      <pds-box slot="image" background-color="var(--pine-color-accent)" border-radius="full" padding="sm">
+      <pds-box slot="image" background-color="var(--pine-color-accent)" border-radius="circle" padding="sm">
         <pds-icon icon="danger" size="medium" color="var(--pine-color-white)"></pds-icon>
       </pds-box>
     </pds-radio>
     <pds-radio component-id="radio2" label="Jane Smith" value="jane" helper-message="Product Manager">
-      <pds-box slot="image" background-color="var(--pine-color-accent)" border-radius="full" padding="sm">
+      <pds-box slot="image" background-color="var(--pine-color-accent)" border-radius="circle" padding="sm">
         <pds-icon icon="danger" size="medium" color="var(--pine-color-white)"></pds-icon>
       </pds-box>
     </pds-radio>
     <pds-radio component-id="radio3" label="Mike Johnson" value="mike" helper-message="UX Designer">
-      <pds-box slot="image" background-color="var(--pine-color-accent)" border-radius="full" padding="sm">
+      <pds-box slot="image" background-color="var(--pine-color-accent)" border-radius="circle" padding="sm">
         <pds-icon icon="danger" size="medium" color="var(--pine-color-white)"></pds-icon>
       </pds-box>
     </pds-radio>

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

@@ -1,4 +1,5 @@
 import { html } from 'lit-html';
+import { ifDefined } from 'lit-html/directives/if-defined.js';
 
 export default {
   component: 'pds-row',
@@ -7,13 +8,13 @@ export default {
 
 const BaseTemplate = (args) => html`
 <pds-row
-  align-items="${args.alignItems}"
+  align-items="${ifDefined(args.alignItems)}"
   ?border=${args.border}
-  component-id="${args.componentId}"
-  col-gap="${args.colGap}"
-  justify-content="${args.justifyContent}"
-  min-height="${args.minHeight}"
-  no-wrap="${args.noWrap}"
+  component-id="${ifDefined(args.componentId)}"
+  col-gap="${ifDefined(args.colGap)}"
+  justify-content="${ifDefined(args.justifyContent)}"
+  min-height="${ifDefined(args.minHeight)}"
+  ?no-wrap=${args.noWrap}
 >
   <pds-box>
     <pds-box border>Item 1</pds-box>
@@ -31,24 +32,24 @@ export const Default = BaseTemplate.bind();
 Default.args = {
   border: true,
   componentId: 'opt0',
-  colGap: '8px',
+  colGap: 'sm',
 };
 
 const GapTemplate = (args) => html`
 <pds-row
-  align-items="${args.alignItems}"
+  align-items="${ifDefined(args.alignItems)}"
   ?border=${args.border}
-  component-id="${args.componentId}"
-  col-gap="${args.colGap}"
-  justify-content="${args.justifyContent}"
-  min-height="${args.minHeight}"
+  component-id="${ifDefined(args.componentId)}"
+  col-gap="${ifDefined(args.colGap)}"
+  justify-content="${ifDefined(args.justifyContent)}"
+  min-height="${ifDefined(args.minHeight)}"
 >
   <pds-box size="4">
     <pds-box
       border="true"
       border-radius="sm"
       padding="sm"
-      shadow="sm"
+      shadow="100"
     >
       Item 1
     </pds-box>
@@ -58,7 +59,7 @@ const GapTemplate = (args) => html`
       border="true"
       border-radius="sm"
       padding="sm"
-      shadow="sm"
+      shadow="100"
     >
       Item 2
     </pds-box>

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

@@ -22,7 +22,10 @@ const patchInPlace = (target, copy) => {
     }
 };
 /**
+ * @slot (default) - The `option` and `optgroup` elements to choose from. Other elements are ignored.
  * @slot action - Content to be displayed in the label area, typically for help icons or links
+ * @part action - Exposes the wrapper around the `action` slot for styling. Appears only when the `action` slot has content.
+ * @part select - Exposes the native `select` element for styling.
  */
 export class PdsSelect {
     constructor() {
@@ -351,7 +354,7 @@ export class PdsSelect {
             'has-action': hasAction && !this.hideLabel ? 'true' : null,
         };
         this.hostKeeper.record(hostClass, {}, hostAttributes);
-        return (h(Host, Object.assign({ key: '37c2c3b72c13c3c4e3d81da29ddddc86a7300d70', class: hostClass }, hostAttributes), h("div", { key: 'ff1c311dca6fc25813e5473d0e8daff4dc12e807', class: "pds-select" }, !this.hideLabel && (h("div", { key: '77db17b0beb1fefabb26ffe1df0e5f03a0515996', class: "pds-select__label-wrapper" }, h("label", { key: 'c4dcba3bc148aada4a3afcca0a30c64a630e441f', htmlFor: this.componentId }, h("span", { key: '0fc3424ec1961d3b216c0fabb80cb8acee37f1a2', class: this.hideLabel ? 'visually-hidden' : '' }, this.label)), hasAction && this.renderAction())), h("select", { key: 'ff343a6653ccd081021cb669a428c780d0162e8b', "aria-describedby": assignDescription(this.componentId, this.isInvalid(), this.helperMessage, this.errorMessage), "aria-invalid": this.isInvalid() ? 'true' : undefined, "aria-label": this.hideLabel ? this.label : undefined, autocomplete: this.autocomplete || undefined, class: "pds-select__field", disabled: this.disabled, id: this.componentId, multiple: this.multiple, name: this.name, onBlur: this.onBlur, onChange: this.onSelectUpdate, onFocus: this.onFocus, onKeyDown: this.onKeyDown, part: "select", required: this.required, ref: (el) => (this.selectEl = el) }), h("div", { key: '86fed1916c3b13d079492581a7c6bb621012a4a5', "aria-hidden": "true", class: "hidden", ref: (el) => (this.slotContainer = el) }, h("slot", { key: 'abe06eeef5be13b716573c8a806d6b7795edc65f', onSlotchange: this.handleSlotChange })), this.renderMessages(), !this.multiple && h("pds-icon", { key: '68c958666828f77114f2edeedb667070106046fa', "aria-hidden": "true", class: "pds-select__select-icon", icon: enlarge }))));
+        return (h(Host, Object.assign({ key: '6ffb35c5166a0759fbe7b3daa0b674c5f10458fa', class: hostClass }, hostAttributes), h("div", { key: '1e2d73b3a65189c29a34c1ce4473cce190f052c0', class: "pds-select" }, !this.hideLabel && (h("div", { key: '467c75d7232e4667975419a0dcad28231ca240a1', class: "pds-select__label-wrapper" }, h("label", { key: '9dd08c5c71a23c762f9d38fcec525a05ced7d48b', htmlFor: this.componentId }, h("span", { key: '94e5f054aa6e75e458f24c02ba9a6cda81f112d7', class: this.hideLabel ? 'visually-hidden' : '' }, this.label)), hasAction && this.renderAction())), h("select", { key: '18c626e10851041042ab4d6dfe700d49a9b3312b', "aria-describedby": assignDescription(this.componentId, this.isInvalid(), this.helperMessage, this.errorMessage), "aria-invalid": this.isInvalid() ? 'true' : undefined, "aria-label": this.hideLabel ? this.label : undefined, autocomplete: this.autocomplete || undefined, class: "pds-select__field", disabled: this.disabled, id: this.componentId, multiple: this.multiple, name: this.name, onBlur: this.onBlur, onChange: this.onSelectUpdate, onFocus: this.onFocus, onKeyDown: this.onKeyDown, part: "select", required: this.required, ref: (el) => (this.selectEl = el) }), h("div", { key: '08c6cee6b009d22b0ed70cc8231d3c2c8637099d', "aria-hidden": "true", class: "hidden", ref: (el) => (this.slotContainer = el) }, h("slot", { key: '2ebcb906f8816e3bf26d5e4f82f8ea2d9ca2256a', onSlotchange: this.handleSlotChange })), this.renderMessages(), !this.multiple && h("pds-icon", { key: '191f489efb78fc7066fc0b5a1f5da1f7cda446e8', "aria-hidden": "true", class: "pds-select__select-icon", icon: enlarge }))));
     }
     static get is() { return "pds-select"; }
     static get encapsulation() { return "shadow"; }
@@ -441,7 +444,7 @@ export class PdsSelect {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Displays error message text describing an invalid state."
+                    "text": "Displays an error message below the select and marks the select as invalid, with or without `invalid`."
                 },
                 "getter": false,
                 "setter": false,
@@ -479,7 +482,7 @@ export class PdsSelect {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Displays helper message text below select."
+                    "text": "Displays a message or hint below the select."
                 },
                 "getter": false,
                 "setter": false,
@@ -638,7 +641,7 @@ export class PdsSelect {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": "Emitted when the select value changes."
+                    "text": "Emitted when the user changes the selection. `detail` is the native `change` event, so read the new value\nfrom the select's `value`: a string, or an array with `multiple`.\n\nThis event will not emit when programmatically setting the `value` property."
                 },
                 "complexType": {
                     "original": "InputEvent",

package/dist/collection/components/pds-sortable/pds-sortable-item/pds-sortable-item.css

@@ -3,15 +3,34 @@
   display: flex;
   padding-block: var(--pine-dimension-xs);
   padding-inline: var(--pine-dimension-md);
+  position: relative;
+  transition: box-shadow var(--pine-motion-duration-fast) var(--pine-motion-easing-out);
 }
 :host(.pds-sortable-item) .pds-sortable-item__actions {
   margin-inline-start: auto;
   padding-inline-start: var(--pine-dimension-md);
 }
 :host(.pds-sortable-item) .pds-sortable-item__handle {
+  border-radius: var(--pine-border-radius-sm);
   line-height: 1;
   margin-inline-end: var(--pine-dimension-md);
 }
+:host(.pds-sortable-item) .pds-sortable-item__handle:focus-visible {
+  outline: var(--pine-outline-focus);
+  outline-offset: var(--pine-border-width);
+}
+:host(.pds-sortable-item) .pds-sortable-item__handle--hidden {
+  clip-path: inset(50%);
+  height: 1px;
+  margin: 0;
+  overflow: hidden;
+  position: absolute;
+  white-space: nowrap;
+  width: 1px;
+}
+:host(.pds-sortable-item) .pds-sortable-item__handle--hidden:focus-visible {
+  outline: 0;
+}
 .pds-sortable--bordered :host(.pds-sortable-item):first-child {
   border-start-end-radius: calc(var(--pine-dimension-xs) * 1.25);
   border-start-start-radius: calc(var(--pine-dimension-xs) * 1.25);
@@ -50,6 +69,25 @@
   color: var(--pine-color-info);
 }
 
+:host(.pds-sortable-item:has(> .pds-sortable-item__handle--hidden:focus-visible)) {
+  outline: var(--pine-outline-focus);
+  outline-offset: calc(var(--pine-border-width-thick) * -1);
+}
+
+:host(.pds-sortable-item--grabbed) {
+  background-color: var(--pine-color-background-container-hover);
+  box-shadow: var(--pine-box-shadow-400), inset 0 0 0 var(--pine-border-width-thick) var(--pine-color-border-active);
+  position: relative;
+  z-index: 1;
+}
+@media (forced-colors: active) {
+  :host(.pds-sortable-item--grabbed) {
+    border: var(--pine-border-width-thick) solid Highlight;
+    padding-block: calc(var(--pine-dimension-xs) - var(--pine-border-width-thick));
+    padding-inline: calc(var(--pine-dimension-md) - var(--pine-border-width-thick));
+  }
+}
+
 :host(.pds-sortable-item--drag) {
   background-color: var(--pine-color-background-container);
   border-radius: 0;

package/dist/collection/components/pds-sortable/pds-sortable-item/pds-sortable-item.js

@@ -1,8 +1,11 @@
 import { Host, h } from "@stencil/core";
 import { HostStylingKeeper } from "../../../utils/attributes";
+import { formatMessage } from "../../../i18n";
+import { sortableItemLabel } from "../sortable-label";
 import { handle as handleIcon } from "@pine-ds/icons/icons";
+const GRABBED_CLASS = 'pds-sortable-item--grabbed';
 /**
- * @slot sortable-item-actions - Content is placed within the `pds-sortable-item__actions` element as children. This slot is only rendered if `actions` is set to `true`.
+ * @slot sortable-item-actions - Content is placed within the `pds-sortable-item__actions` element as children. This slot is only rendered when `enable-actions` is set.
  * @lightDom renders-markup
  */
 export class PdsSortableItem {
@@ -14,7 +17,9 @@ export class PdsSortableItem {
          */
         this.enableActions = false;
         /**
-         * Determines whether `sortable-item` should have a handle.
+         * Determines whether the reorder handle is shown. The handle itself renders whenever the list
+         * is reorderable, regardless of this prop; without it, the handle is visually hidden but still
+         * reachable from the keyboard.
          * @defaultValue false
          */
         this.showHandle = false;
@@ -47,8 +52,26 @@ export class PdsSortableItem {
         }
     }
     render() {
-        this.hostKeeper.record('pds-sortable-item');
-        return (h(Host, { key: 'c6b5402a54179d4e7caed3cc81874977d2d6c677', class: "pds-sortable-item", id: this.componentId }, this.showHandle && (h("div", { key: 'cd2d85286bcb3e47f76e4571d609d91f932b717b', class: "pds-sortable-item__handle" }, h("pds-icon", { key: '97e2e155283d86921f40198637abf596d6cc86e0', "aria-hidden": "true", icon: handleIcon }))), h("slot", { key: '99743c8e5be45ca76f276b47688843a621c8ded5' }), this.enableActions && (h("div", { key: '7cb1a8b99658d72067ccae036b2bc0276b8cf02e', class: "pds-sortable-item__actions" }, h("slot", { key: 'f9b3b7d1cc10ac077f65ec2cafac7a372deae511', name: "sortable-item-actions" })))));
+        const sortable = this.sortableRef;
+        // In a list that can be reordered, the handle is what the keyboard reorders with. It's always
+        // rendered, and only hidden visually when `show-handle` is off, so every row has a named button.
+        const reorderable = typeof (sortable === null || sortable === void 0 ? void 0 : sortable.handleLabel) === 'string' && !sortable.disabled;
+        // `pds-sortable` sets the grabbed class and `aria-pressed` directly on this element and its
+        // handle, not through a prop -- read back whatever's there now rather than hardcoding the
+        // rest state, so a re-render for an unrelated reason (`handleLabel` changing, for one,
+        // `forceUpdate`s every row) carries the current grabbed state forward instead of resetting it.
+        const wasGrabbed = this.el.classList.contains(GRABBED_CLASS);
+        const hostClasses = {
+            'pds-sortable-item': true,
+            [GRABBED_CLASS]: wasGrabbed,
+        };
+        this.hostKeeper.record(hostClasses);
+        const existingHandle = this.el.querySelector('.pds-sortable-item__handle');
+        const wasPressed = (existingHandle === null || existingHandle === void 0 ? void 0 : existingHandle.getAttribute('aria-pressed')) === 'true';
+        return (h(Host, { key: '5fdef76101ce86c7769bb49bff9869246c3bdb32', class: hostClasses, id: this.componentId }, (this.showHandle || reorderable) && (h("div", { key: 'e54b5a0006b395dc67ff78c6a115e4e498cae096', class: {
+                'pds-sortable-item__handle': true,
+                'pds-sortable-item__handle--hidden': !this.showHandle,
+            }, role: reorderable ? 'button' : undefined, tabindex: reorderable ? '0' : undefined, "aria-label": reorderable ? formatMessage(sortable.handleLabel, { item: sortableItemLabel(this.el) }) : undefined, "aria-pressed": reorderable ? String(wasPressed) : undefined }, h("pds-icon", { key: 'e7099e03ea68c9f48c50d20868835081c4fdbc75', "aria-hidden": "true", icon: handleIcon }))), h("slot", { key: 'c75d20569c150da8d0698657db787aa6d27e3408' }), this.enableActions && (h("div", { key: '14281b2eaedfa57ff90342fb1dcbff48cd656242', class: "pds-sortable-item__actions" }, h("slot", { key: 'ec1f75b331d136a00fc39db9ab2cadd86a416e8d', name: "sortable-item-actions" })))));
     }
     static get is() { return "pds-sortable-item"; }
     static get encapsulation() { return "scoped"; }
@@ -121,13 +144,32 @@ export class PdsSortableItem {
                             "name": "defaultValue",
                             "text": "false"
                         }],
-                    "text": "Determines whether `sortable-item` should have a handle."
+                    "text": "Determines whether the reorder handle is shown. The handle itself renders whenever the list\nis reorderable, regardless of this prop; without it, the handle is visually hidden but still\nreachable from the keyboard."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": false,
                 "attribute": "show-handle",
                 "defaultValue": "false"
+            },
+            "itemLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Name of the item in its reorder handle's label and in the reorder announcements. Pass a translated string to localize it; defaults to the item's text content."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "item-label"
             }
         };
     }