@pine-ds/core 4.10.0 → 4.12.0

package/dist/types/components.d.ts

@@ -5,13 +5,14 @@
  * It contains typing information for all components that exist in this project.
  */
 import { HTMLStencilElement, JSXBase } from "./stencil-public-runtime";
-import { BoxColumnType, BoxShadowSizeType, BoxSpacingType, TextSizeType } from "./utils/types";
+import { BoxColumnType, BoxContainerType, BoxMarginType, BoxShadowSizeType, BoxSpacingType, TextSizeType } from "./utils/types";
 import { Event } from "./stencil-public-runtime";
 import { CheckboxChangeEventDetail } from "./components/pds-checkbox/checkbox-interface";
-import { ChipSentimentType, ChipSizeType, ChipVariantType, ModalSizeType, PlacementType, PopoverPaddingType } from "./utils/types";
+import { ChipSentimentType, ChipSizeType, ChipVariantType, ImageRatioType, ModalSizeType, PlacementType, PopoverPaddingType } from "./utils/types";
 import { ComboboxLoadOptionsEventDetail, ComboboxOption, ComboboxSearchEventDetail } from "./components/pds-combobox/combobox-interface";
 import { DatepickerChangeEventDetail, DatepickerPreset } from "./components/pds-datepicker/datepicker-interface";
 import { PdsFilterClearEventDetail, PdsFilterCloseEventDetail, PdsFilterOpenEventDetail, PdsFilterVariant } from "./components/pds-filters/pds-filter/filter-interface";
+import { ImageErrorEventDetail, ImageLoadEventDetail } from "./components/pds-image/image-interface";
 import { InputChangeEventDetail, InputInputEventDetail } from "./components/pds-input/input-interface";
 import { PluralForms } from "./i18n";
 import { MultiselectChangeEventDetail, MultiselectCreateEventDetail, MultiselectLoadOptionsEventDetail, MultiselectOption, MultiselectOptionActionEventDetail, MultiselectSearchEventDetail } from "./components/pds-multiselect/multiselect-interface";
@@ -19,13 +20,14 @@ import { PdsPopoverEventDetail } from "./components/pds-popover/popover-interfac
 import { RadioGroupChangeEventDetail } from "./components/pds-radio-group/radio-group-interface";
 import { SortableEvent } from "sortablejs";
 import { TextareaChangeEventDetail, TextareaInputEventDetail } from "./components/pds-textarea/textarea-interface";
-export { BoxColumnType, BoxShadowSizeType, BoxSpacingType, TextSizeType } from "./utils/types";
+export { BoxColumnType, BoxContainerType, BoxMarginType, BoxShadowSizeType, BoxSpacingType, TextSizeType } from "./utils/types";
 export { Event } from "./stencil-public-runtime";
 export { CheckboxChangeEventDetail } from "./components/pds-checkbox/checkbox-interface";
-export { ChipSentimentType, ChipSizeType, ChipVariantType, ModalSizeType, PlacementType, PopoverPaddingType } from "./utils/types";
+export { ChipSentimentType, ChipSizeType, ChipVariantType, ImageRatioType, ModalSizeType, PlacementType, PopoverPaddingType } from "./utils/types";
 export { ComboboxLoadOptionsEventDetail, ComboboxOption, ComboboxSearchEventDetail } from "./components/pds-combobox/combobox-interface";
 export { DatepickerChangeEventDetail, DatepickerPreset } from "./components/pds-datepicker/datepicker-interface";
 export { PdsFilterClearEventDetail, PdsFilterCloseEventDetail, PdsFilterOpenEventDetail, PdsFilterVariant } from "./components/pds-filters/pds-filter/filter-interface";
+export { ImageErrorEventDetail, ImageLoadEventDetail } from "./components/pds-image/image-interface";
 export { InputChangeEventDetail, InputInputEventDetail } from "./components/pds-input/input-interface";
 export { PluralForms } from "./i18n";
 export { MultiselectChangeEventDetail, MultiselectCreateEventDetail, MultiselectLoadOptionsEventDetail, MultiselectOption, MultiselectOptionActionEventDetail, MultiselectSearchEventDetail } from "./components/pds-multiselect/multiselect-interface";
@@ -160,7 +162,7 @@ export namespace Components {
          */
         "initials"?: string | null;
         /**
-          * Size of the avatar. Value can be preset or custom.
+          * Sets the size of the avatar: `xs` (24px), `sm` (32px), `md` (40px), `lg` (56px), `xl` (64px), or a custom CSS length such as `128px`.
           * @defaultValue lg
          */
         "size"?: | 'xl' // 64px
@@ -312,6 +314,10 @@ export namespace Components {
           * @defaultValue none
          */
         "borderRadius"?: `none` | `xs`| `sm` | `md` | `lg` | `circle`;
+        /**
+          * Makes the box a size container by setting `container-type`. `inline-size` stops the box's content from setting its width, so long unwrapped text truncates instead of widening it, and lets children use container query units. `size` does the same for both axes, so the box needs a height from somewhere else. Either way the box still needs its width from its parent, such as the default `flex-grow`, `flex="grow"` or `fit`; with `flex="none"` or `flex="shrink"`, or the `auto` prop, it collapses.
+         */
+        "container"?: BoxContainerType;
         /**
           * Defines the orientation of the box items.
           * @defaultValue row
@@ -323,32 +329,31 @@ export namespace Components {
          */
         "display"?: `flex` | `inline-flex` | `block` | `inline-block`;
         /**
-          * If `true`, sets the box `max-width` to `100%`.
+          * If `true`, sets the box `width`, `min-width` and `max-width` to `100%`, so it fills its parent's width. A box in a `direction="column"` parent needs it when the parent sets `align-items`, and a box that isn't a flex item needs it to fill its container.
          */
         "fit"?: boolean;
         /**
-          * If `true`, sets the box `max-width` to `100%` at the LG breakpoint.
+          * If `true`, sets the box `width`, `min-width` and `max-width` to `100%` at the LG breakpoint.
          */
         "fitLg"?: boolean;
         /**
-          * If `true`, sets the box `max-width` to `100%` at the MD breakpoint.
+          * If `true`, sets the box `width`, `min-width` and `max-width` to `100%` at the MD breakpoint.
          */
         "fitMd"?: boolean;
         /**
-          * If `true`, sets the box `max-width` to `100%` at the SM breakpoint.
+          * If `true`, sets the box `width`, `min-width` and `max-width` to `100%` at the SM breakpoint.
          */
         "fitSm"?: boolean;
         /**
-          * If `true`, sets the box `max-width` to `100%` at the XL breakpoint.
+          * If `true`, sets the box `width`, `min-width` and `max-width` to `100%` at the XL breakpoint.
          */
         "fitXl"?: boolean;
         /**
-          * If `true`, sets the box `max-width` to `100%` at the XS breakpoint.
+          * If `true`, sets the box `width`, `min-width` and `max-width` to `100%` at the XS breakpoint.
          */
         "fitXs"?: boolean;
         /**
-          * Defines how a box will grow or shrink to fit the space available in its container. Can be a predefined value ('none', 'grow', 'shrink') or a custom flex value (e.g., '1', '0 1 auto').
-          * @defaultValue none
+          * Defines how a box will grow or shrink to fit the space available in its container. Can be a predefined value or a custom flex value (e.g., '1', '0 1 auto'). The predefined values are `none` (`flex: 0 0 auto`), `grow` (`flex: 1 1 auto`) and `shrink` (`flex: 0 1 auto`). Without it, a box grows to share its row with its siblings (`flex-grow: 1; flex-basis: 0`).
          */
         "flex"?: `none` | `grow` | `shrink` | string;
         /**
@@ -412,125 +417,125 @@ export namespace Components {
          */
         "justifyContentXs"?: `start` | `center` | `end` | `space-between` | `space-around` | `space-evenly`;
         /**
-          * Defines the box's outer bottom spacing.
+          * Defines the box's outer bottom spacing. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockEnd"?: BoxSpacingType;
+        "marginBlockEnd"?: BoxMarginType;
         /**
-          * Defines the box's outer bottom spacing at the LG breakpoint.
+          * Defines the box's outer bottom spacing at the LG breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockEndLg"?: BoxSpacingType;
+        "marginBlockEndLg"?: BoxMarginType;
         /**
-          * Defines the box's outer bottom spacing at the MD breakpoint.
+          * Defines the box's outer bottom spacing at the MD breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockEndMd"?: BoxSpacingType;
+        "marginBlockEndMd"?: BoxMarginType;
         /**
-          * Defines the box's outer bottom spacing at the SM breakpoint.
+          * Defines the box's outer bottom spacing at the SM breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockEndSm"?: BoxSpacingType;
+        "marginBlockEndSm"?: BoxMarginType;
         /**
-          * Defines the box's outer bottom spacing at the XL breakpoint.
+          * Defines the box's outer bottom spacing at the XL breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockEndXl"?: BoxSpacingType;
+        "marginBlockEndXl"?: BoxMarginType;
         /**
-          * Defines the box's outer bottom spacing at the XS breakpoint.
+          * Defines the box's outer bottom spacing at the XS breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockEndXs"?: BoxSpacingType;
+        "marginBlockEndXs"?: BoxMarginType;
         /**
-          * Defines the box's outer top spacing.
+          * Defines the box's outer top spacing. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockStart"?: BoxSpacingType;
+        "marginBlockStart"?: BoxMarginType;
         /**
-          * Defines the box's outer top spacing at the LG breakpoint.
+          * Defines the box's outer top spacing at the LG breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockStartLg"?: BoxSpacingType;
+        "marginBlockStartLg"?: BoxMarginType;
         /**
-          * Defines the box's outer top spacing at the MD breakpoint.
+          * Defines the box's outer top spacing at the MD breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockStartMd"?: BoxSpacingType;
+        "marginBlockStartMd"?: BoxMarginType;
         /**
-          * Defines the box's outer top spacing at the SM breakpoint.
+          * Defines the box's outer top spacing at the SM breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockStartSm"?: BoxSpacingType;
+        "marginBlockStartSm"?: BoxMarginType;
         /**
-          * Defines the box's outer top spacing at the XL breakpoint.
+          * Defines the box's outer top spacing at the XL breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockStartXl"?: BoxSpacingType;
+        "marginBlockStartXl"?: BoxMarginType;
         /**
-          * Defines the box's outer top spacing at the XS breakpoint.
+          * Defines the box's outer top spacing at the XS breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockStartXs"?: BoxSpacingType;
+        "marginBlockStartXs"?: BoxMarginType;
         /**
-          * Defines the box's outer right spacing.
+          * Defines the box's outer right spacing. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineEnd"?: BoxSpacingType;
+        "marginInlineEnd"?: BoxMarginType;
         /**
-          * Defines the box's outer right spacing at the LG breakpoint.
+          * Defines the box's outer right spacing at the LG breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineEndLg"?: BoxSpacingType;
+        "marginInlineEndLg"?: BoxMarginType;
         /**
-          * Defines the box's outer right spacing at the MD breakpoint.
+          * Defines the box's outer right spacing at the MD breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineEndMd"?: BoxSpacingType;
+        "marginInlineEndMd"?: BoxMarginType;
         /**
-          * Defines the box's outer right spacing at the SM breakpoint.
+          * Defines the box's outer right spacing at the SM breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineEndSm"?: BoxSpacingType;
+        "marginInlineEndSm"?: BoxMarginType;
         /**
-          * Defines the box's outer right spacing at the XL breakpoint.
+          * Defines the box's outer right spacing at the XL breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineEndXl"?: BoxSpacingType;
+        "marginInlineEndXl"?: BoxMarginType;
         /**
-          * Defines the box's outer right spacing at the XS breakpoint.
+          * Defines the box's outer right spacing at the XS breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineEndXs"?: BoxSpacingType;
+        "marginInlineEndXs"?: BoxMarginType;
         /**
-          * Defines the box's outer left spacing.
+          * Defines the box's outer left spacing. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineStart"?: BoxSpacingType;
+        "marginInlineStart"?: BoxMarginType;
         /**
-          * Defines the box's outer left spacing at the LG breakpoint.
+          * Defines the box's outer left spacing at the LG breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineStartLg"?: BoxSpacingType;
+        "marginInlineStartLg"?: BoxMarginType;
         /**
-          * Defines the box's outer left spacing at the MD breakpoint.
+          * Defines the box's outer left spacing at the MD breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineStartMd"?: BoxSpacingType;
+        "marginInlineStartMd"?: BoxMarginType;
         /**
-          * Defines the box's outer left spacing at the SM breakpoint.
+          * Defines the box's outer left spacing at the SM breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineStartSm"?: BoxSpacingType;
+        "marginInlineStartSm"?: BoxMarginType;
         /**
-          * Defines the box's outer left spacing at the XL breakpoint.
+          * Defines the box's outer left spacing at the XL breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineStartXl"?: BoxSpacingType;
+        "marginInlineStartXl"?: BoxMarginType;
         /**
-          * Defines the box's outer left spacing at the XS breakpoint.
+          * Defines the box's outer left spacing at the XS breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineStartXs"?: BoxSpacingType;
+        "marginInlineStartXs"?: BoxMarginType;
         /**
           * The minimum height of the row. Used in conjunction with alignment props
          */
@@ -793,7 +798,7 @@ export namespace Components {
          */
         "fullWidth"?: boolean;
         /**
-          * If provided, renders the component as an anchor (`<a>`) element instead of a button. When using href, button-specific props (type, name, value, loading) will be ignored.
+          * If provided, renders the component as an anchor (`<a>`) element instead of a button. When using href, `type`, `name` and `value` are ignored, `loading` blocks navigation, and `disabled` removes the link's `href`.
          */
         "href"?: string;
         /**
@@ -813,7 +818,7 @@ export namespace Components {
          */
         "loading"?: boolean;
         /**
-          * Provides the button with a submittable name.
+          * Sets the `name` attribute of the inner button. Not included in submitted form data, because the form is submitted through a hidden button that carries only the `type`.
          */
         "name"?: string;
         /**
@@ -831,7 +836,7 @@ export namespace Components {
          */
         "type"?: 'button' | 'reset' | 'submit';
         /**
-          * Provides button with a submittable value
+          * Sets the `value` attribute of the inner button. Not included in submitted form data, because the form is submitted through a hidden button that carries only the `type`.
          */
         "value"?: string;
         /**
@@ -855,11 +860,11 @@ export namespace Components {
          */
         "disabled": boolean;
         /**
-          * Displays message text describing an invalid state.
+          * Displays an error message below the checkbox. It becomes the checkbox's accessible description only while `invalid` is set.
          */
         "errorMessage": string;
         /**
-          * String used for helper message below checkbox.
+          * Displays a message or hint below the checkbox.
          */
         "helperMessage": string;
         /**
@@ -867,15 +872,15 @@ export namespace Components {
          */
         "hideLabel": boolean;
         /**
-          * If `true`, the checkbox will visually appear as indeterminate. Only JavaScript can set the objects `indeterminate` property. See [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes). Has no visual style when `variant` is `pill`.
+          * Shows the checkbox as indeterminate, for a checkbox whose group is only partly selected. It's exposed to screen readers as mixed. Changing `checked` clears it. Has no visual style when `variant` is `pill`.
          */
         "indeterminate": boolean;
         /**
-          * It determines whether or not the checkbox is invalid.
+          * Determines whether or not the checkbox is invalid.
          */
         "invalid": boolean;
         /**
-          * String used for label text next to checkbox.
+          * Text to be displayed as the checkbox label.
          */
         "label": string;
         /**
@@ -928,7 +933,7 @@ export namespace Components {
          */
         "maxWidth"?: string;
         /**
-          * HTTP method to use for the remove action. Adds data-method and data-turbo-method attributes for Rails/Turbo compatibility. Only applies when removeUrl is provided.
+          * HTTP method to use for the remove action. Maps to the `data-method` and `data-turbo-method` attributes on the remove link, for frameworks that read link methods from them. Only applies when removeUrl is provided.
          */
         "removeHttpMethod"?: 'get' | 'post' | 'put' | 'patch' | 'delete';
         /**
@@ -1028,10 +1033,9 @@ export namespace Components {
          */
         "dropdownPlacement": 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
         /**
-          * Width of the dropdown. Any valid CSS width value.
-          * @default '236px'
+          * Width of the dropdown, including its padding. Any valid CSS width value. Without it, the dropdown is 252px wide, 244px with grouped options and 236px with a panel search.
          */
-        "dropdownWidth": string;
+        "dropdownWidth"?: string;
         /**
           * Error message to display.
          */
@@ -1042,13 +1046,13 @@ export namespace Components {
          */
         "fetchTimeout": number;
         /**
-          * Maximum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value.
-          * @default '380px'
+          * Maximum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value, including its padding.
+          * @default '388px'
          */
         "flyoutMaxWidth": string;
         /**
-          * Minimum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value. The flyout is as wide as its options, between this and `flyout-max-width`.
-          * @default '280px'
+          * Minimum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value, including its padding. The flyout is as wide as its options, between this and `flyout-max-width`.
+          * @default '288px'
          */
         "flyoutMinWidth": string;
         /**
@@ -1157,7 +1161,7 @@ export namespace Components {
          */
         "truncate": boolean;
         /**
-          * The value of the combobox input.
+          * The `value` of the selected option.
           * @default ''
          */
         "value": string;
@@ -1206,7 +1210,8 @@ export namespace Components {
     /**
      * A field for one date, or in range mode a start and end date, with a calendar to pick from.
      * The value is `YYYY-MM-DD`, or `YYYY-MM-DD/YYYY-MM-DD` for a range; with the time picker, each
-     * date carries a time, as `YYYY-MM-DDTHH:mm`.
+     * date carries a time, as `YYYY-MM-DDTHH:mm`. In month-day mode, for a date that comes round every
+     * year such as a birthday, it's a month and day with no year, as `--MM-DD`.
      */
     interface PdsDatepicker {
         /**
@@ -1265,7 +1270,7 @@ export namespace Components {
          */
         "firstDayOfWeek"?: number;
         /**
-          * How the field shows dates and reads typed ones, as tokens: `YYYY`, `MMMM` or `MMM` (month name, in the locale), `MM` or `M` (month), `DD` or `D` (day), and with the time picker `HH` or `H` (24-hour), `hh` or `h` (12-hour), `mm` and `A` (AM/PM, in the locale), as `MM/DD/YYYY`, `MMM D, YYYY` or `D.M.YYYY h:mm A`. Put literal text in brackets, as `[Due] D/M/YYYY`. The value and the change event stay ISO (`YYYY-MM-DD`), whatever the format. Typed ISO dates are always accepted too.
+          * How the field shows dates and reads typed ones, as tokens: `YYYY`, `MMMM` or `MMM` (month name, in the locale), `MM` or `M` (month), `DD` or `D` (day), and with the time picker `HH` or `H` (24-hour), `hh` or `h` (12-hour), `mm` and `A` (AM/PM, in the locale), as `MM/DD/YYYY`, `MMM D, YYYY` or `D.M.YYYY h:mm A`. Put literal text in brackets, as `[Due] D/M/YYYY`. The value and the change event stay ISO (`YYYY-MM-DD`; `--MM-DD` with `month-day`), whatever the format. Typed ISO dates are always accepted too. With `month-day`, a format without `YYYY` is taken as a month-and-day format and used as given, rather than reordered for the locale; leave it unset to follow the locale instead.
           * @default 'YYYY-MM-DD'
          */
         "format": string;
@@ -1331,6 +1336,11 @@ export namespace Components {
           * @default 'Minute'
          */
         "minuteLabel": string;
+        /**
+          * Picks a month and day with no year, for a date that comes round every year, such as a birthday. The value is `--MM-DD` (ISO 8601 without a year), the field shows the date as the locale writes a month and day, and the calendar shows each month without a year or weekdays, with February always having its 29th. Turns off `range`, `time-picker`, `show-dropdowns`, `min` and `max`, and has no effect with `auto-apply`, `presets`, `first-day-of-week`, `min-date-message` or `max-date-message`, which all depend on them.
+          * @default false
+         */
+        "monthDay": boolean;
         /**
           * Accessible label for the month dropdown, when `show-dropdowns` is set.
           * @default 'Month'
@@ -1355,7 +1365,7 @@ export namespace Components {
          */
         "periodLabel": string;
         /**
-          * Specifies a short hint that describes the expected value of the field. Defaults to the format the field takes, such as `YYYY-MM-DD`.
+          * Specifies a short hint that describes the expected value of the field. Defaults to the format the field takes, such as `YYYY-MM-DD`; with `month-day`, to an example date instead, such as `December 31`.
          */
         "placeholder"?: string;
         /**
@@ -1364,7 +1374,7 @@ export namespace Components {
          */
         "placement": PlacementType;
         /**
-          * Ranges listed beside the calendar in range mode. A comma-separated list of built-in keys (`today`, `yesterday`, `last-7-days`, `last-30-days`, `last-90-days`, `this-month`, `last-month`, `this-quarter`, `last-quarter`, `this-year`, `last-year`, `year-to-date`, `last-12-months`), or an array of `{ key, label?, start?, end? }` to relabel built-ins or add your own.
+          * Ranges listed beside the calendar in range mode. A comma-separated list of built-in keys (`today`, `yesterday`, `last-7-days`, `last-30-days`, `last-90-days`, `this-month`, `last-month`, `this-quarter`, `last-quarter`, `this-year`, `last-year`, `year-to-date`, `last-12-months`), or an array of `{ key, label?, startOffset?, endOffset?, start?, end? }` to relabel built-ins or add your own: `startOffset` and `endOffset` follow today, `start` and `end` are fixed days.
          */
         "presets"?: string | DatepickerPreset[];
         /**
@@ -1420,7 +1430,7 @@ export namespace Components {
          */
         "triggerLabel": string;
         /**
-          * The selected date as `YYYY-MM-DD`, or in range mode the range as `YYYY-MM-DD/YYYY-MM-DD`; with the time picker, each date as `YYYY-MM-DDTHH:mm`. An empty string when nothing is selected.
+          * The selected date as `YYYY-MM-DD`, or in range mode the range as `YYYY-MM-DD/YYYY-MM-DD`; with the time picker, each date as `YYYY-MM-DDTHH:mm`; with `month-day`, the month and day with no year, as `--MM-DD` (a full date is read too, as that month and day, and rewritten to it). An empty string when nothing is selected.
           * @default ''
          */
         "value"?: string;
@@ -1452,7 +1462,7 @@ export namespace Components {
     /**
      * A side panel composed from `pds-modal`, non-modal by default.
      * By default, unlike `pds-modal`, the page stays interactive while a drawer
-     * is open: no dimming, no blur, no scroll lock, no click blocking.
+     * is open: no dimming, no blur, no click blocking.
      * `pds-drawer` renders a `pds-modal` internally with `disableTopLayer` on and
      * its backdrop suppressed, and adds the edge, width and dismiss behavior a
      * side panel needs on top. With `modal`, it opens that `pds-modal` in the top
@@ -1471,7 +1481,7 @@ export namespace Components {
          */
         "initialFocus": 'auto' | 'none';
         /**
-          * Whether the drawer can be dismissed with a pointerdown outside it (in a `modal` drawer, a click on its backdrop). Replaces `pds-modal`'s `backdropDismiss`. This also gates Escape, matching how `backdropDismiss` gates Escape on `pds-modal` today: setting this to `false` means the close button is the only way out.  A trigger outside the drawer should only ever set `open` to `true` and leave closing to the drawer itself. A toggle-style trigger (`open = !open`) fights light dismiss: clicking it while open closes the drawer on `pointerdown`, then the trigger's own click handler re-opens it.
+          * Whether the drawer can be dismissed with a pointerdown outside it (in a `modal` drawer, a click on its backdrop). Setting it to `false` also turns off Escape, so the close button is the only way out.  A trigger outside the drawer should only ever set `open` to `true` and leave closing to the drawer itself. A toggle-style trigger (`open = !open`) fights light dismiss: clicking it while open closes the drawer on `pointerdown`, then the trigger's own click handler re-opens it.
           * @default true
          */
         "lightDismiss": boolean;
@@ -1491,7 +1501,7 @@ export namespace Components {
          */
         "scrollable": boolean;
         /**
-          * Which edge of the viewport the drawer is docked to. Logical, so this is free under RTL — `end` is the inline-end edge regardless of direction.
+          * Which edge of the viewport the drawer is docked to. Logical: `end` is the inline-end edge, so an `end` drawer docks on the left in right-to-left layouts.
           * @default 'end'
          */
         "side": 'start' | 'end';
@@ -1502,20 +1512,19 @@ export namespace Components {
         "size": 'sm' | 'md';
     }
     /**
-     * Fills the drawer panel's height by default — unlike `pds-modal-content`,
-     * which caps itself against the viewport for a centered, possibly-shorter
-     * modal, a drawer panel is already edge-to-edge, so its content can simply
-     * flex to fill whatever space the header and footer leave.
+     * Fills the space between the drawer header and footer.
      * @lightDom renders-markup
      */
     interface PdsDrawerContent {
     }
     /**
+     * Holds the drawer's actions in a padded row aligned to the end, with a divider above.
      * @lightDom renders-markup
      */
     interface PdsDrawerFooter {
     }
     /**
+     * Holds the drawer's title and close control in a padded row, spaced apart, with a divider below.
      * @lightDom renders-markup
      */
     interface PdsDrawerHeader {
@@ -1533,7 +1542,7 @@ export namespace Components {
     }
     interface PdsDropdownMenuItem {
         /**
-          * Trigger the click event
+          * Trigger the click event. Does nothing when the item is disabled or informational.
          */
         "clickItem": () => Promise<void>;
         /**
@@ -1541,12 +1550,12 @@ export namespace Components {
          */
         "componentId": string;
         /**
-          * It determines whether or not the dropdown-item is destructive.
+          * Determines whether or not the dropdown menu item is destructive.
           * @defaultValue false
          */
         "destructive": boolean;
         /**
-          * It determines whether or not the dropdown-item is disabled.
+          * Determines whether or not the dropdown menu item is disabled.
           * @defaultValue false
          */
         "disabled": boolean;
@@ -1555,26 +1564,26 @@ export namespace Components {
          */
         "download"?: string;
         /**
-          * Determines whether the link should open in a new tab and display an external icon. This is a simpler alternative to using `target="_blank"` for the common case. Ignored when `informational` is set.
+          * Shows the external-link (launch) icon. Opens in a new tab unless `target` says otherwise. Only applies when href is set. Ignored when `informational` is set.
           * @defaultValue false
          */
         "external": boolean;
         /**
-          * Accessible label for the external-link icon, passed to the inner `pds-link`. Pass a translated string to localize it; defaults to English. Pass an empty string to make the icon decorative.
+          * Accessible label for the icon that `external` shows, passed to the inner `pds-link` and appended to the item's name. It isn't announced when `target` is anything other than `_blank`. Pass a translated string to localize it; defaults to English. Pass an empty string to make the icon decorative.
           * @defaultValue '(opens in a new tab)'
          */
         "externalLabel"?: string;
         /**
-          * If provided, renders the dropdown-item as an anchor (`<a>`) element instead of a button. Ignored when `informational` is set.
+          * If provided, renders the dropdown menu item as an anchor (`<a>`) element instead of a button. Ignored when `informational` is set.
          */
         "href": string | undefined;
         /**
-          * It determines whether or not the dropdown-item is informational: text that the arrow keys reach but that can't be activated. Takes precedence over `href` and `destructive`. Screen readers announce it as dimmed or unavailable, the same way as a disabled item.
+          * Determines whether or not the dropdown menu item is informational: text that the arrow keys reach but that can't be activated. Takes precedence over `href` and `destructive`. Screen readers announce it as dimmed or unavailable, the same way as a disabled item.
           * @defaultValue false
          */
         "informational": boolean;
         /**
-          * Specifies where to open the linked document when href is provided. Takes precedence over the `external` prop if both are set. Only applies when href is set. Ignored when `informational` is set.
+          * Specifies where to open the linked document when href is provided. Overrides the new-tab default of `external`; the icon still shows. Only applies when href is set. Ignored when `informational` is set.
           * @defaultValue undefined
          */
         "target"?: '_blank' | '_self' | '_parent' | '_top';
@@ -1585,16 +1594,14 @@ export namespace Components {
          */
         "componentId": string;
         /**
-          * It determines whether or not the dropdown-item is disabled.
+          * Has no effect. A separator can't be focused or activated.
           * @defaultValue false
          */
         "disabled": boolean;
     }
     /**
-     * Individual filter component with cross-browser popover positioning.
-     * Uses a hybrid approach for optimal cross-browser compatibility:
-     * - Modern browsers: CSS anchor positioning + JavaScript flip classes
-     * - Fallback browsers: JavaScript positioning with viewport boundary detection
+     * A single filter in `pds-filters`: a trigger button that opens a popover holding the filter controls.
+     * The `clear` variant has no popover and emits `pdsFilterClear` instead.
      */
     interface PdsFilter {
         /**
@@ -1614,7 +1621,7 @@ export namespace Components {
          */
         "showFilter": () => Promise<void>;
         /**
-          * The text content displayed in the trigger button.
+          * The text content displayed in the trigger button. When text overflows, a tooltip showing the full text will appear on hover/focus.
          */
         "text"?: string;
         /**
@@ -1631,7 +1638,7 @@ export namespace Components {
     }
     interface PdsImage {
         /**
-          * The image's alt tag. If none is provided, it will default to an empty string, which is desired for decorative images.
+          * The image's alt text. Defaults to an empty string, which marks the image as decorative and hides it from screen readers, so set it on any image that carries information.
           * @defaultValue ''
          */
         "alt"?: string;
@@ -1640,7 +1647,12 @@ export namespace Components {
          */
         "componentId": string;
         /**
-          * The height of the image in pixels. Setting this will devote space in the layout to prevent layout shifts when the image is loaded.
+          * Determines how the image fills the shape set by `ratio`. Has no effect if `ratio` is not set.
+          * @defaultValue cover
+         */
+        "fit"?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+        /**
+          * The height of the image in pixels. `height: auto` lets the loaded image's own proportions decide its rendered height, so unlike `width` this does not reserve space before the image loads.
          */
         "height"?: number;
         /**
@@ -1648,6 +1660,10 @@ export namespace Components {
           * @defaultValue eager
          */
         "loading"?: 'eager' | 'lazy';
+        /**
+          * The aspect ratio the image is sized to, cropping whatever overflows the shape. A preset (`square` 1/1, `landscape` 4/3, `wide` 16/9, `portrait` 3/4, `tall` 9/16) or any custom CSS ratio, such as `21 / 9`. Use this, not `height` and `width`, to crop: those only reserve space, and only `width` reliably does even that.
+         */
+        "ratio"?: ImageRatioType | (string & Record<never, never>);
         /**
           * Determines the intended display size of an image within certain breakpoints. Has no effect if `srcset` is not set or value has no width descriptor.
          */
@@ -1661,7 +1677,7 @@ export namespace Components {
          */
         "srcset"?: string;
         /**
-          * The width of the image in pixels. Setting this will devote space in the layout to prevent layout shifts when the image is loaded.
+          * The width of the image in pixels. This reserves the image's width before it loads, but not its height: to reserve the height too, set `--dimension-aspect-ratio` to the image's own proportions.
          */
         "width"?: number;
     }
@@ -1675,7 +1691,7 @@ export namespace Components {
          */
         "componentId": string;
         /**
-          * Sets the number of milliseconds to wait before updating the value.
+          * Sets the number of milliseconds to wait after each input event before emitting `pdsInput`.
          */
         "debounce"?: number;
         /**
@@ -1683,7 +1699,7 @@ export namespace Components {
          */
         "disabled"?: boolean;
         /**
-          * Specifies the error message and provides an error-themed treatment to the field.
+          * Displays an error message below the input and gives the field error styling. It becomes the input's accessible description only while `invalid` is set.
          */
         "errorMessage"?: string;
         /**
@@ -1703,7 +1719,7 @@ export namespace Components {
          */
         "highlight"?: boolean;
         /**
-          * Determines whether or not the input field is invalid or throws an error.
+          * Determines whether or not the input is invalid.
          */
         "invalid"?: boolean;
         /**
@@ -1755,7 +1771,7 @@ export namespace Components {
          */
         "step"?: string;
         /**
-          * Determines the type of control that will be displayed `'email'`, `'number'`, `'password'`, `'tel'`, `'text'`, `'url'`
+          * Determines the type of control that will be displayed `'email'`, `'number'`, `'password'`, `'search'`, `'tel'`, `'text'`, `'url'`
           * @defaultValue "text"
          */
         "type": string;
@@ -1784,13 +1800,12 @@ export namespace Components {
          */
         "download"?: string;
         /**
-          * Determines whether the link should open in a new tab.
+          * Shows the external-link (launch) icon. Opens in a new tab unless `target` says otherwise.
           * @defaultValue false
-          * @deprecated Consider using the `target` prop for more control. This prop will be maintained for backward compatibility.
          */
         "external": boolean;
         /**
-          * Accessible label for the icon that `external` shows, appended to the link's name. It isn't announced when `target` keeps the link in the same tab. Pass a translated string to localize it; defaults to English. Pass an empty string to make the icon decorative.
+          * Accessible label for the icon that `external` shows, appended to the link's name. It isn't announced when `target` is anything other than `_blank`. Pass a translated string to localize it; defaults to English. Pass an empty string to make the icon decorative.
           * @defaultValue '(opens in a new tab)'
          */
         "externalLabel"?: string;
@@ -1800,13 +1815,13 @@ export namespace Components {
          */
         "fontSize": 'sm' | 'md' | 'lg';
         /**
-          * The hyperlink's destination URL. If no text is provided in the custom slot, the href will be used.
+          * The hyperlink's destination URL. If the default slot is empty (whitespace counts as content), the href will be used as the link text.
          */
         "href": string;
         /**
-          * Specifies where to open the linked document.
+          * Specifies where to open the linked document. Overrides the new-tab default of `external`; the icon still shows.
           * @defaultValue undefined
-          * @example <pds-link href="https://example.com" target="_blank">Opens in new tab</pds-link>
+          * @example <pds-link href="/dashboard" target="_top">Opens in the top-level frame</pds-link>
          */
         "target"?: '_blank' | '_self' | '_parent' | '_top';
         /**
@@ -1859,7 +1874,7 @@ export namespace Components {
          */
         "showLabel"?: boolean;
         /**
-          * Sets the size of the spinner loader. Value can be preset or custom.
+          * Sets the size of the spinner loader: `xs` (24px), `sm` (32px), `md` (48px), `lg` (64px), `xl` (80px), or a custom CSS length such as `128px`. The `typing` variant ignores it.
           * @default 'md'
          */
         "size"?: | 'xs' // 24px
@@ -1888,7 +1903,7 @@ export namespace Components {
          */
         "componentId": string;
         /**
-          * Whether to skip moving focus into the modal when it opens — both our own `setInitialFocus()` and the browser's native "dialog focusing steps", which move focus into the dialog as soon as `show()`/`showModal()` is called regardless of application code. Focus return on close is unaffected either way. For a modal opened by something other than a direct user click — a redirect, a deep link, a background event — stealing focus on open can interrupt whatever the user was already doing. Default `false` preserves today's behavior for every existing consumer.
+          * Whether to skip moving focus into the modal when it opens. Set it for a modal that can open from a background event while the user is mid-task elsewhere on the page, where moving focus would interrupt them. Pair it with `disableTopLayer`: in the top layer the rest of the page is inert, so focus can't stay there. On close, focus moves back only if nothing outside the modal has taken it.
           * @default false
          */
         "disableInitialFocus": boolean;
@@ -1932,11 +1947,13 @@ export namespace Components {
         "border": 'none' | 'both' | 'top' | 'bottom';
     }
     /**
+     * Holds the modal's actions. It adds no padding or layout, so wrap its content in a `pds-box` with `padding="md"`.
      * @lightDom renders-markup
      */
     interface PdsModalFooter {
     }
     /**
+     * Holds the modal's title and close control. It adds no padding or layout, so wrap its content in a `pds-box` with `padding="md"`.
      * @lightDom renders-markup
      */
     interface PdsModalHeader {
@@ -2187,8 +2204,8 @@ export namespace Components {
          */
         "hide": () => Promise<void>;
         /**
-          * Sets the maximum width of the popover content
-          * @defaultValue 352
+          * Sets the maximum width of the popover, in pixels, including its padding.
+          * @defaultValue 400
          */
         "maxWidth"?: number;
         /**
@@ -2237,7 +2254,7 @@ export namespace Components {
         "componentId": string;
         /**
           * Sets the progress fill color. Accepts a color token or a [valid color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
-          * @defaultValue 'var(--pine-color-blue-300)'
+          * @defaultValue 'var(--pine-color-primary)'
          */
         "fillColor": string;
         /**
@@ -2245,7 +2262,7 @@ export namespace Components {
          */
         "label": string;
         /**
-          * Sets the progress fill pecentage and visually displayed when `show-percentage=true`.
+          * Sets the progress fill percentage (0–100). Shown as text when `show-percent` is set.
           * @defaultValue 0
          */
         "percent": number;
@@ -2271,7 +2288,7 @@ export namespace Components {
      */
     interface PdsRadio {
         /**
-          * 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
          */
         "checked": boolean;
@@ -2285,7 +2302,7 @@ export namespace Components {
          */
         "disabled": boolean;
         /**
-          * Displays error message text describing an invalid state.
+          * Displays an error message below the radio. It becomes the radio's accessible description only while `invalid` is set.
          */
         "errorMessage": string;
         /**
@@ -2294,7 +2311,7 @@ export namespace Components {
          */
         "hasBorder": boolean;
         /**
-          * Displays helper message text below radio.
+          * Displays a message or hint below the radio.
          */
         "helperMessage": string;
         /**
@@ -2307,7 +2324,7 @@ export namespace Components {
          */
         "invalid": boolean;
         /**
-          * String used for label text next to radio.
+          * Text to be displayed as the radio label.
          */
         "label": string;
         /**
@@ -2348,7 +2365,7 @@ export namespace Components {
          */
         "disabled": boolean;
         /**
-          * Displays error message text describing an invalid state for the entire group.
+          * Displays an error message below the radio group. It's part of the group's accessible description, with or without `invalid`.
          */
         "errorMessage": string;
         /**
@@ -2357,11 +2374,11 @@ export namespace Components {
          */
         "gap": string;
         /**
-          * String used for group label/heading.
+          * Text to be displayed as the radio group label. It also names the group, unless you set `aria-label` or `aria-labelledby` on it.
          */
         "groupLabel": string;
         /**
-          * Displays helper message text below the radio group.
+          * Displays a message or hint below the radio group.
          */
         "helperMessage": string;
         /**
@@ -2439,11 +2456,11 @@ export namespace Components {
          */
         "disabled": boolean;
         /**
-          * Displays error message text describing an invalid state.
+          * Displays an error message below the select and marks the select as invalid, with or without `invalid`.
          */
         "errorMessage": string;
         /**
-          * Displays helper message text below select.
+          * Displays a message or hint below the select.
          */
         "helperMessage": string;
         /**
@@ -2504,11 +2521,36 @@ export namespace Components {
           * @default false
          */
         "dividers": boolean;
+        /**
+          * Accessible label for each item's reorder handle, the button the keyboard reorders with. Pass a translated string to localize it; `{item}` is interpolated.
+          * @defaultValue 'Reorder {item}'
+         */
+        "handleLabel": string;
         /**
           * Determines the grabbable area for the `pds-sortable-item`.
           * @default 'row'
          */
         "handleType": 'handle' | 'row';
+        /**
+          * Screen-reader announcement when a picked-up item is dropped. Pass a translated string to localize it; `{item}`, `{position}` and `{total}` are interpolated.
+          * @defaultValue '{item}, dropped at position {position} of {total}'
+         */
+        "itemDroppedLabel": string;
+        /**
+          * Screen-reader announcement when a picked-up item is moved. Pass a translated string to localize it; `{item}`, `{position}` and `{total}` are interpolated.
+          * @defaultValue '{item}, moved to position {position} of {total}'
+         */
+        "itemMovedLabel": string;
+        /**
+          * Screen-reader announcement when an item is picked up from the keyboard. Pass a translated string to localize it; `{item}`, `{position}` and `{total}` are interpolated.
+          * @defaultValue '{item}, picked up. Position {position} of {total}. Press the arrow keys to move, Space or Enter to drop, Escape to cancel.'
+         */
+        "itemPickedUpLabel": string;
+        /**
+          * Screen-reader announcement when a keyboard reorder is canceled and the item goes back. Pass a translated string to localize it; `{item}`, `{position}` and `{total}` are interpolated.
+          * @defaultValue 'Reorder canceled. {item} returned to position {position} of {total}'
+         */
+        "reorderCanceledLabel": string;
     }
     /**
      * @lightDom renders-markup
@@ -2524,7 +2566,11 @@ export namespace Components {
          */
         "enableActions": boolean;
         /**
-          * Determines whether `sortable-item` should have a handle.
+          * 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.
+         */
+        "itemLabel"?: string;
+        /**
+          * 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
          */
         "showHandle": boolean;
@@ -2566,7 +2612,7 @@ export namespace Components {
          */
         "label": string;
         /**
-          * Identifies form data and unifies a group of radio inputs for toggling a single property/value.
+          * Specifies the name. Submitted with the form name/value pair when checked, or with `unchecked-value` while unchecked.
          */
         "name": string;
         /**
@@ -2574,6 +2620,10 @@ export namespace Components {
           * @default false
          */
         "required"?: boolean;
+        /**
+          * Provides a string submitted in form data under `name` while the switch is unchecked. When unset, an unchecked switch submits nothing, like a native checkbox.
+         */
+        "uncheckedValue"?: string;
         /**
           * Provides input with a string submitted in form data.
          */
@@ -2646,7 +2696,7 @@ export namespace Components {
          */
         "disableSelectAll": boolean;
         /**
-          * Determines if the should display a fixed first column.
+          * Determines if the table displays a fixed first column.
          */
         "fixedColumn": boolean;
         /**
@@ -2662,6 +2712,11 @@ export namespace Components {
           * Determines if the table displays checkboxes for selectable rows.
          */
         "selectable": boolean;
+        /**
+          * Sets how the table sizes its columns. With `auto`, each column is sized from its content, so columns can change width when the rows change (for example after a sort). With `fixed`, columns take the `width` set on their `pds-table-head-cell` and ignore their content; columns without a `width` share the remaining space. Under `responsive`, that remaining share keeps a 120px floor on narrow viewports where the other columns' widths already fill it, growing the table instead (scrollable) -- without `responsive` there's no floor, since there would be nothing to scroll the overflow it would create. Content longer than its column overflows, so add `truncate` to cells whose content may not fit.
+          * @defaultValue 'auto'
+         */
+        "tableLayout": 'auto' | 'fixed';
     }
     interface PdsTableBody {
     }
@@ -2670,6 +2725,10 @@ export namespace Components {
           * Sets the text alignment within the cell.
          */
         "cellAlign"?: 'start' | 'center' | 'end' | 'justify';
+        /**
+          * 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.
+         */
+        "rebindScrollListener": () => Promise<void>;
         /**
           * Truncates content to a max width and adds an ellipsis. When text overflows, a tooltip showing the full text will appear on hover/focus. Note: While the content is overflowing, the cell receives tabindex="0" so the tooltip can be reached by keyboard. Content that fits is left out of the tab order.
          */
@@ -2691,7 +2750,7 @@ export namespace Components {
          */
         "indeterminate"?: boolean;
         /**
-          * Determines if the table row is currently selected.
+          * Determines if the select all checkbox is checked.
           * @defaultValue false
          */
         "isSelected": boolean;
@@ -2705,6 +2764,10 @@ export namespace Components {
           * Clears the active sort state from this column. Used internally when another column becomes active.
          */
         "clearActiveSort": () => Promise<void>;
+        /**
+          * 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.
+         */
+        "rebindScrollListener": () => Promise<void>;
         /**
           * Programmatically sets this column as the active sort column with the specified direction. Used by pds-table to apply a default sort on initial load.
           * @param direction - The sort direction to apply ('asc' or 'desc')
@@ -2714,6 +2777,10 @@ export namespace Components {
           * Determines whether the table column is sortable when set to `true`.
          */
         "sortable": boolean;
+        /**
+          * Sets the width of the column. Accepts any CSS length (e.g. '148px', '12rem', '20%'). When the table's `tableLayout` is `fixed`, the column keeps this width whatever its content. Otherwise the column is at least this wide and can grow to fit its content.
+         */
+        "width"?: string;
     }
     interface PdsTableRow {
         /**
@@ -2765,7 +2832,7 @@ export namespace Components {
          */
         "nav"?: boolean;
         /**
-          * Stretches the component so the active tab panel fills the remaining height. Requires the component to have a constrained height (e.g. a flex parent).
+          * Stretches the component to fill its container's height. The active tab panel keeps the height of its content. Requires the component to have a constrained height (e.g. a flex parent).
           * @defaultValue false
          */
         "stretch"?: boolean;
@@ -2848,7 +2915,7 @@ export namespace Components {
          */
         "componentId": string;
         /**
-          * The amount of time, in milliseconds, to wait to trigger the event after each keystroke.
+          * Sets the number of milliseconds to wait after each input event before emitting `pdsInput`.
          */
         "debounce"?: number;
         /**
@@ -2857,7 +2924,7 @@ export namespace Components {
          */
         "disabled": boolean;
         /**
-          * Displays an error message below the textarea field.
+          * Displays an error message below the textarea while `invalid` is set.
          */
         "errorMessage"?: string;
         /**
@@ -2873,7 +2940,7 @@ export namespace Components {
          */
         "highlight"?: boolean;
         /**
-          * Determines whether or not the textarea is invalid or throws an error.
+          * Determines whether or not the textarea is invalid. When `required` is set, the textarea sets it itself each time `pdsTextareaChange` fires, replacing a value you set.
           * @defaultValue false
          */
         "invalid": boolean;
@@ -2886,7 +2953,7 @@ export namespace Components {
          */
         "maxLength"?: number;
         /**
-          * Specifies the name. Submitted with the form name/value pair. This value will mirror the componentId.
+          * Specifies the name. Submitted with the form name/value pair.
           * @default this.componentId
          */
         "name": string;
@@ -2923,6 +2990,9 @@ export namespace Components {
           * A unique identifier used for the underlying component `id` attribute.
          */
         "componentId": string;
+        /**
+          * Dismisses the toast, as the dismiss button and `duration` do: plays the exit animation and emits `pdsToastDismissed`, and the toast gets `hidden` on the next render, after the event. Works even when `dismissible` is `false`. The toast stays in the DOM.
+         */
         "dismiss": () => Promise<void>;
         /**
           * Accessible label for the dismiss button. Pass a translated string to localize it; defaults to English.
@@ -3049,6 +3119,10 @@ export interface PdsFilterCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLPdsFilterElement;
 }
+export interface PdsImageCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLPdsImageElement;
+}
 export interface PdsInputCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLPdsInputElement;
@@ -3288,7 +3362,8 @@ declare global {
     /**
      * A field for one date, or in range mode a start and end date, with a calendar to pick from.
      * The value is `YYYY-MM-DD`, or `YYYY-MM-DD/YYYY-MM-DD` for a range; with the time picker, each
-     * date carries a time, as `YYYY-MM-DDTHH:mm`.
+     * date carries a time, as `YYYY-MM-DDTHH:mm`. In month-day mode, for a date that comes round every
+     * year such as a birthday, it's a month and day with no year, as `--MM-DD`.
      */
     interface HTMLPdsDatepickerElement extends Components.PdsDatepicker, HTMLStencilElement {
         addEventListener<K extends keyof HTMLPdsDatepickerElementEventMap>(type: K, listener: (this: HTMLPdsDatepickerElement, ev: PdsDatepickerCustomEvent<HTMLPdsDatepickerElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -3317,7 +3392,7 @@ declare global {
     /**
      * A side panel composed from `pds-modal`, non-modal by default.
      * By default, unlike `pds-modal`, the page stays interactive while a drawer
-     * is open: no dimming, no blur, no scroll lock, no click blocking.
+     * is open: no dimming, no blur, no click blocking.
      * `pds-drawer` renders a `pds-modal` internally with `disableTopLayer` on and
      * its backdrop suppressed, and adds the edge, width and dismiss behavior a
      * side panel needs on top. With `modal`, it opens that `pds-modal` in the top
@@ -3340,10 +3415,7 @@ declare global {
         new (): HTMLPdsDrawerElement;
     };
     /**
-     * Fills the drawer panel's height by default — unlike `pds-modal-content`,
-     * which caps itself against the viewport for a centered, possibly-shorter
-     * modal, a drawer panel is already edge-to-edge, so its content can simply
-     * flex to fill whatever space the header and footer leave.
+     * Fills the space between the drawer header and footer.
      * @lightDom renders-markup
      */
     interface HTMLPdsDrawerContentElement extends Components.PdsDrawerContent, HTMLStencilElement {
@@ -3353,6 +3425,7 @@ declare global {
         new (): HTMLPdsDrawerContentElement;
     };
     /**
+     * Holds the drawer's actions in a padded row aligned to the end, with a divider above.
      * @lightDom renders-markup
      */
     interface HTMLPdsDrawerFooterElement extends Components.PdsDrawerFooter, HTMLStencilElement {
@@ -3362,6 +3435,7 @@ declare global {
         new (): HTMLPdsDrawerFooterElement;
     };
     /**
+     * Holds the drawer's title and close control in a padded row, spaced apart, with a divider below.
      * @lightDom renders-markup
      */
     interface HTMLPdsDrawerHeaderElement extends Components.PdsDrawerHeader, HTMLStencilElement {
@@ -3405,10 +3479,8 @@ declare global {
         "pdsFilterClear": PdsFilterClearEventDetail;
     }
     /**
-     * Individual filter component with cross-browser popover positioning.
-     * Uses a hybrid approach for optimal cross-browser compatibility:
-     * - Modern browsers: CSS anchor positioning + JavaScript flip classes
-     * - Fallback browsers: JavaScript positioning with viewport boundary detection
+     * A single filter in `pds-filters`: a trigger button that opens a popover holding the filter controls.
+     * The `clear` variant has no popover and emits `pdsFilterClear` instead.
      */
     interface HTMLPdsFilterElement extends Components.PdsFilter, HTMLStencilElement {
         addEventListener<K extends keyof HTMLPdsFilterElementEventMap>(type: K, listener: (this: HTMLPdsFilterElement, ev: PdsFilterCustomEvent<HTMLPdsFilterElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -3430,7 +3502,19 @@ declare global {
         prototype: HTMLPdsFiltersElement;
         new (): HTMLPdsFiltersElement;
     };
+    interface HTMLPdsImageElementEventMap {
+        "pdsImageLoad": ImageLoadEventDetail;
+        "pdsImageError": ImageErrorEventDetail;
+    }
     interface HTMLPdsImageElement extends Components.PdsImage, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLPdsImageElementEventMap>(type: K, listener: (this: HTMLPdsImageElement, ev: PdsImageCustomEvent<HTMLPdsImageElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLPdsImageElementEventMap>(type: K, listener: (this: HTMLPdsImageElement, ev: PdsImageCustomEvent<HTMLPdsImageElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
     }
     var HTMLPdsImageElement: {
         prototype: HTMLPdsImageElement;
@@ -3500,6 +3584,7 @@ declare global {
         new (): HTMLPdsModalContentElement;
     };
     /**
+     * Holds the modal's actions. It adds no padding or layout, so wrap its content in a `pds-box` with `padding="md"`.
      * @lightDom renders-markup
      */
     interface HTMLPdsModalFooterElement extends Components.PdsModalFooter, HTMLStencilElement {
@@ -3509,6 +3594,7 @@ declare global {
         new (): HTMLPdsModalFooterElement;
     };
     /**
+     * Holds the modal's title and close control. It adds no padding or layout, so wrap its content in a `pds-box` with `padding="md"`.
      * @lightDom renders-markup
      */
     interface HTMLPdsModalHeaderElement extends Components.PdsModalHeader, HTMLStencilElement {
@@ -4050,7 +4136,7 @@ declare namespace LocalJSX {
          */
         "initials"?: string | null;
         /**
-          * Size of the avatar. Value can be preset or custom.
+          * Sets the size of the avatar: `xs` (24px), `sm` (32px), `md` (40px), `lg` (56px), `xl` (64px), or a custom CSS length such as `128px`.
           * @defaultValue lg
          */
         "size"?: | 'xl' // 64px
@@ -4202,6 +4288,10 @@ declare namespace LocalJSX {
           * @defaultValue none
          */
         "borderRadius"?: `none` | `xs`| `sm` | `md` | `lg` | `circle`;
+        /**
+          * Makes the box a size container by setting `container-type`. `inline-size` stops the box's content from setting its width, so long unwrapped text truncates instead of widening it, and lets children use container query units. `size` does the same for both axes, so the box needs a height from somewhere else. Either way the box still needs its width from its parent, such as the default `flex-grow`, `flex="grow"` or `fit`; with `flex="none"` or `flex="shrink"`, or the `auto` prop, it collapses.
+         */
+        "container"?: BoxContainerType;
         /**
           * Defines the orientation of the box items.
           * @defaultValue row
@@ -4213,32 +4303,31 @@ declare namespace LocalJSX {
          */
         "display"?: `flex` | `inline-flex` | `block` | `inline-block`;
         /**
-          * If `true`, sets the box `max-width` to `100%`.
+          * If `true`, sets the box `width`, `min-width` and `max-width` to `100%`, so it fills its parent's width. A box in a `direction="column"` parent needs it when the parent sets `align-items`, and a box that isn't a flex item needs it to fill its container.
          */
         "fit"?: boolean;
         /**
-          * If `true`, sets the box `max-width` to `100%` at the LG breakpoint.
+          * If `true`, sets the box `width`, `min-width` and `max-width` to `100%` at the LG breakpoint.
          */
         "fitLg"?: boolean;
         /**
-          * If `true`, sets the box `max-width` to `100%` at the MD breakpoint.
+          * If `true`, sets the box `width`, `min-width` and `max-width` to `100%` at the MD breakpoint.
          */
         "fitMd"?: boolean;
         /**
-          * If `true`, sets the box `max-width` to `100%` at the SM breakpoint.
+          * If `true`, sets the box `width`, `min-width` and `max-width` to `100%` at the SM breakpoint.
          */
         "fitSm"?: boolean;
         /**
-          * If `true`, sets the box `max-width` to `100%` at the XL breakpoint.
+          * If `true`, sets the box `width`, `min-width` and `max-width` to `100%` at the XL breakpoint.
          */
         "fitXl"?: boolean;
         /**
-          * If `true`, sets the box `max-width` to `100%` at the XS breakpoint.
+          * If `true`, sets the box `width`, `min-width` and `max-width` to `100%` at the XS breakpoint.
          */
         "fitXs"?: boolean;
         /**
-          * Defines how a box will grow or shrink to fit the space available in its container. Can be a predefined value ('none', 'grow', 'shrink') or a custom flex value (e.g., '1', '0 1 auto').
-          * @defaultValue none
+          * Defines how a box will grow or shrink to fit the space available in its container. Can be a predefined value or a custom flex value (e.g., '1', '0 1 auto'). The predefined values are `none` (`flex: 0 0 auto`), `grow` (`flex: 1 1 auto`) and `shrink` (`flex: 0 1 auto`). Without it, a box grows to share its row with its siblings (`flex-grow: 1; flex-basis: 0`).
          */
         "flex"?: `none` | `grow` | `shrink` | string;
         /**
@@ -4302,125 +4391,125 @@ declare namespace LocalJSX {
          */
         "justifyContentXs"?: `start` | `center` | `end` | `space-between` | `space-around` | `space-evenly`;
         /**
-          * Defines the box's outer bottom spacing.
+          * Defines the box's outer bottom spacing. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockEnd"?: BoxSpacingType;
+        "marginBlockEnd"?: BoxMarginType;
         /**
-          * Defines the box's outer bottom spacing at the LG breakpoint.
+          * Defines the box's outer bottom spacing at the LG breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockEndLg"?: BoxSpacingType;
+        "marginBlockEndLg"?: BoxMarginType;
         /**
-          * Defines the box's outer bottom spacing at the MD breakpoint.
+          * Defines the box's outer bottom spacing at the MD breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockEndMd"?: BoxSpacingType;
+        "marginBlockEndMd"?: BoxMarginType;
         /**
-          * Defines the box's outer bottom spacing at the SM breakpoint.
+          * Defines the box's outer bottom spacing at the SM breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockEndSm"?: BoxSpacingType;
+        "marginBlockEndSm"?: BoxMarginType;
         /**
-          * Defines the box's outer bottom spacing at the XL breakpoint.
+          * Defines the box's outer bottom spacing at the XL breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockEndXl"?: BoxSpacingType;
+        "marginBlockEndXl"?: BoxMarginType;
         /**
-          * Defines the box's outer bottom spacing at the XS breakpoint.
+          * Defines the box's outer bottom spacing at the XS breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockEndXs"?: BoxSpacingType;
+        "marginBlockEndXs"?: BoxMarginType;
         /**
-          * Defines the box's outer top spacing.
+          * Defines the box's outer top spacing. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockStart"?: BoxSpacingType;
+        "marginBlockStart"?: BoxMarginType;
         /**
-          * Defines the box's outer top spacing at the LG breakpoint.
+          * Defines the box's outer top spacing at the LG breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockStartLg"?: BoxSpacingType;
+        "marginBlockStartLg"?: BoxMarginType;
         /**
-          * Defines the box's outer top spacing at the MD breakpoint.
+          * Defines the box's outer top spacing at the MD breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockStartMd"?: BoxSpacingType;
+        "marginBlockStartMd"?: BoxMarginType;
         /**
-          * Defines the box's outer top spacing at the SM breakpoint.
+          * Defines the box's outer top spacing at the SM breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockStartSm"?: BoxSpacingType;
+        "marginBlockStartSm"?: BoxMarginType;
         /**
-          * Defines the box's outer top spacing at the XL breakpoint.
+          * Defines the box's outer top spacing at the XL breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockStartXl"?: BoxSpacingType;
+        "marginBlockStartXl"?: BoxMarginType;
         /**
-          * Defines the box's outer top spacing at the XS breakpoint.
+          * Defines the box's outer top spacing at the XS breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginBlockStartXs"?: BoxSpacingType;
+        "marginBlockStartXs"?: BoxMarginType;
         /**
-          * Defines the box's outer right spacing.
+          * Defines the box's outer right spacing. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineEnd"?: BoxSpacingType;
+        "marginInlineEnd"?: BoxMarginType;
         /**
-          * Defines the box's outer right spacing at the LG breakpoint.
+          * Defines the box's outer right spacing at the LG breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineEndLg"?: BoxSpacingType;
+        "marginInlineEndLg"?: BoxMarginType;
         /**
-          * Defines the box's outer right spacing at the MD breakpoint.
+          * Defines the box's outer right spacing at the MD breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineEndMd"?: BoxSpacingType;
+        "marginInlineEndMd"?: BoxMarginType;
         /**
-          * Defines the box's outer right spacing at the SM breakpoint.
+          * Defines the box's outer right spacing at the SM breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineEndSm"?: BoxSpacingType;
+        "marginInlineEndSm"?: BoxMarginType;
         /**
-          * Defines the box's outer right spacing at the XL breakpoint.
+          * Defines the box's outer right spacing at the XL breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineEndXl"?: BoxSpacingType;
+        "marginInlineEndXl"?: BoxMarginType;
         /**
-          * Defines the box's outer right spacing at the XS breakpoint.
+          * Defines the box's outer right spacing at the XS breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineEndXs"?: BoxSpacingType;
+        "marginInlineEndXs"?: BoxMarginType;
         /**
-          * Defines the box's outer left spacing.
+          * Defines the box's outer left spacing. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineStart"?: BoxSpacingType;
+        "marginInlineStart"?: BoxMarginType;
         /**
-          * Defines the box's outer left spacing at the LG breakpoint.
+          * Defines the box's outer left spacing at the LG breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineStartLg"?: BoxSpacingType;
+        "marginInlineStartLg"?: BoxMarginType;
         /**
-          * Defines the box's outer left spacing at the MD breakpoint.
+          * Defines the box's outer left spacing at the MD breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineStartMd"?: BoxSpacingType;
+        "marginInlineStartMd"?: BoxMarginType;
         /**
-          * Defines the box's outer left spacing at the SM breakpoint.
+          * Defines the box's outer left spacing at the SM breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineStartSm"?: BoxSpacingType;
+        "marginInlineStartSm"?: BoxMarginType;
         /**
-          * Defines the box's outer left spacing at the XL breakpoint.
+          * Defines the box's outer left spacing at the XL breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineStartXl"?: BoxSpacingType;
+        "marginInlineStartXl"?: BoxMarginType;
         /**
-          * Defines the box's outer left spacing at the XS breakpoint.
+          * Defines the box's outer left spacing at the XS breakpoint. Accepts a spacing token or `auto`.
           * @defaultValue none
          */
-        "marginInlineStartXs"?: BoxSpacingType;
+        "marginInlineStartXs"?: BoxMarginType;
         /**
           * The minimum height of the row. Used in conjunction with alignment props
          */
@@ -4683,7 +4772,7 @@ declare namespace LocalJSX {
          */
         "fullWidth"?: boolean;
         /**
-          * If provided, renders the component as an anchor (`<a>`) element instead of a button. When using href, button-specific props (type, name, value, loading) will be ignored.
+          * If provided, renders the component as an anchor (`<a>`) element instead of a button. When using href, `type`, `name` and `value` are ignored, `loading` blocks navigation, and `disabled` removes the link's `href`.
          */
         "href"?: string;
         /**
@@ -4703,9 +4792,12 @@ declare namespace LocalJSX {
          */
         "loading"?: boolean;
         /**
-          * Provides the button with a submittable name.
+          * Sets the `name` attribute of the inner button. Not included in submitted form data, because the form is submitted through a hidden button that carries only the `type`.
          */
         "name"?: string;
+        /**
+          * Emitted when the button is clicked, including from the keyboard, carrying the native click event. Not emitted while the button is `disabled` or `loading`. In a form, a `submit` or `reset` button's `submit` or `reset` event fires before this one. A form that fails validation fires no `submit` event.
+         */
         "onPdsClick"?: (event: PdsButtonCustomEvent<Event>) => void;
         /**
           * Sets the size of the button.
@@ -4722,7 +4814,7 @@ declare namespace LocalJSX {
          */
         "type"?: 'button' | 'reset' | 'submit';
         /**
-          * Provides button with a submittable value
+          * Sets the `value` attribute of the inner button. Not included in submitted form data, because the form is submitted through a hidden button that carries only the `type`.
          */
         "value"?: string;
         /**
@@ -4746,7 +4838,7 @@ declare namespace LocalJSX {
          */
         "disabled"?: boolean;
         /**
-          * Displays message text describing an invalid state.
+          * Displays an error message below the checkbox. It becomes the checkbox's accessible description only while `invalid` is set.
          */
         "errorMessage"?: string;
         /**
@@ -4754,7 +4846,7 @@ declare namespace LocalJSX {
          */
         "form"?: string;
         /**
-          * String used for helper message below checkbox.
+          * Displays a message or hint below the checkbox.
          */
         "helperMessage"?: string;
         /**
@@ -4762,15 +4854,15 @@ declare namespace LocalJSX {
          */
         "hideLabel"?: boolean;
         /**
-          * If `true`, the checkbox will visually appear as indeterminate. Only JavaScript can set the objects `indeterminate` property. See [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes). Has no visual style when `variant` is `pill`.
+          * Shows the checkbox as indeterminate, for a checkbox whose group is only partly selected. It's exposed to screen readers as mixed. Changing `checked` clears it. Has no visual style when `variant` is `pill`.
          */
         "indeterminate"?: boolean;
         /**
-          * It determines whether or not the checkbox is invalid.
+          * Determines whether or not the checkbox is invalid.
          */
         "invalid"?: boolean;
         /**
-          * String used for label text next to checkbox.
+          * Text to be displayed as the checkbox label.
          */
         "label"?: string;
         /**
@@ -4778,9 +4870,12 @@ declare namespace LocalJSX {
          */
         "name"?: string;
         /**
-          * Event emitted that contains the `value` and `checked`.
+          * Emitted when the user toggles the checkbox, by a click or `Space`, carrying the `value` and the new `checked` state.  This event will not emit when programmatically setting the `checked` property.
          */
         "onPdsCheckboxChange"?: (event: PdsCheckboxCustomEvent<CheckboxChangeEventDetail>) => void;
+        /**
+          * Emitted when the user toggles the checkbox, just before `pdsCheckboxChange`, carrying the `value` and `checked`. `checked` is still the state from before the toggle, so read the new state from `pdsCheckboxChange`.  This event will not emit when programmatically setting the `checked` property.
+         */
         "onPdsCheckboxInput"?: (event: PdsCheckboxCustomEvent<CheckboxChangeEventDetail>) => void;
         /**
           * It determines whether or not the checkbox is required.
@@ -4832,7 +4927,7 @@ declare namespace LocalJSX {
          */
         "onPdsTagCloseClick"?: (event: PdsChipCustomEvent<void>) => void;
         /**
-          * HTTP method to use for the remove action. Adds data-method and data-turbo-method attributes for Rails/Turbo compatibility. Only applies when removeUrl is provided.
+          * HTTP method to use for the remove action. Maps to the `data-method` and `data-turbo-method` attributes on the remove link, for frameworks that read link methods from them. Only applies when removeUrl is provided.
          */
         "removeHttpMethod"?: 'get' | 'post' | 'put' | 'patch' | 'delete';
         /**
@@ -4928,8 +5023,7 @@ declare namespace LocalJSX {
          */
         "dropdownPlacement"?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
         /**
-          * Width of the dropdown. Any valid CSS width value.
-          * @default '236px'
+          * Width of the dropdown, including its padding. Any valid CSS width value. Without it, the dropdown is 252px wide, 244px with grouped options and 236px with a panel search.
          */
         "dropdownWidth"?: string;
         /**
@@ -4942,13 +5036,13 @@ declare namespace LocalJSX {
          */
         "fetchTimeout"?: number;
         /**
-          * Maximum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value.
-          * @default '380px'
+          * Maximum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value, including its padding.
+          * @default '388px'
          */
         "flyoutMaxWidth"?: string;
         /**
-          * Minimum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value. The flyout is as wide as its options, between this and `flyout-max-width`.
-          * @default '280px'
+          * Minimum width of a group's flyout when `group-display` is `flyout`. Any valid CSS width value, including its padding. The flyout is as wide as its options, between this and `flyout-max-width`.
+          * @default '288px'
          */
         "flyoutMinWidth"?: string;
         /**
@@ -5065,7 +5159,7 @@ declare namespace LocalJSX {
          */
         "truncate"?: boolean;
         /**
-          * The value of the combobox input.
+          * The `value` of the selected option.
           * @default ''
          */
         "value"?: string;
@@ -5102,7 +5196,7 @@ declare namespace LocalJSX {
          */
         "fullWidth"?: boolean;
         /**
-          * Event fired when copyText button is clicked.
+          * Emitted after a click, once the copy to the clipboard succeeds or fails. `detail` is `Copied to clipboard` on success, or `Error writing text to clipboard: ` followed by the error on failure. Not emitted when `navigator.clipboard` is undefined, as it is outside a secure context.
          */
         "onPdsCopyTextClick"?: (event: PdsCopytextCustomEvent<string>) => void;
         /**
@@ -5118,7 +5212,8 @@ declare namespace LocalJSX {
     /**
      * A field for one date, or in range mode a start and end date, with a calendar to pick from.
      * The value is `YYYY-MM-DD`, or `YYYY-MM-DD/YYYY-MM-DD` for a range; with the time picker, each
-     * date carries a time, as `YYYY-MM-DDTHH:mm`.
+     * date carries a time, as `YYYY-MM-DDTHH:mm`. In month-day mode, for a date that comes round every
+     * year such as a birthday, it's a month and day with no year, as `--MM-DD`.
      */
     interface PdsDatepicker {
         /**
@@ -5177,7 +5272,7 @@ declare namespace LocalJSX {
          */
         "form"?: string;
         /**
-          * How the field shows dates and reads typed ones, as tokens: `YYYY`, `MMMM` or `MMM` (month name, in the locale), `MM` or `M` (month), `DD` or `D` (day), and with the time picker `HH` or `H` (24-hour), `hh` or `h` (12-hour), `mm` and `A` (AM/PM, in the locale), as `MM/DD/YYYY`, `MMM D, YYYY` or `D.M.YYYY h:mm A`. Put literal text in brackets, as `[Due] D/M/YYYY`. The value and the change event stay ISO (`YYYY-MM-DD`), whatever the format. Typed ISO dates are always accepted too.
+          * How the field shows dates and reads typed ones, as tokens: `YYYY`, `MMMM` or `MMM` (month name, in the locale), `MM` or `M` (month), `DD` or `D` (day), and with the time picker `HH` or `H` (24-hour), `hh` or `h` (12-hour), `mm` and `A` (AM/PM, in the locale), as `MM/DD/YYYY`, `MMM D, YYYY` or `D.M.YYYY h:mm A`. Put literal text in brackets, as `[Due] D/M/YYYY`. The value and the change event stay ISO (`YYYY-MM-DD`; `--MM-DD` with `month-day`), whatever the format. Typed ISO dates are always accepted too. With `month-day`, a format without `YYYY` is taken as a month-and-day format and used as given, rather than reordered for the locale; leave it unset to follow the locale instead.
           * @default 'YYYY-MM-DD'
          */
         "format"?: string;
@@ -5243,6 +5338,11 @@ declare namespace LocalJSX {
           * @default 'Minute'
          */
         "minuteLabel"?: string;
+        /**
+          * Picks a month and day with no year, for a date that comes round every year, such as a birthday. The value is `--MM-DD` (ISO 8601 without a year), the field shows the date as the locale writes a month and day, and the calendar shows each month without a year or weekdays, with February always having its 29th. Turns off `range`, `time-picker`, `show-dropdowns`, `min` and `max`, and has no effect with `auto-apply`, `presets`, `first-day-of-week`, `min-date-message` or `max-date-message`, which all depend on them.
+          * @default false
+         */
+        "monthDay"?: boolean;
         /**
           * Accessible label for the month dropdown, when `show-dropdowns` is set.
           * @default 'Month'
@@ -5275,7 +5375,7 @@ declare namespace LocalJSX {
          */
         "periodLabel"?: string;
         /**
-          * Specifies a short hint that describes the expected value of the field. Defaults to the format the field takes, such as `YYYY-MM-DD`.
+          * Specifies a short hint that describes the expected value of the field. Defaults to the format the field takes, such as `YYYY-MM-DD`; with `month-day`, to an example date instead, such as `December 31`.
          */
         "placeholder"?: string;
         /**
@@ -5284,7 +5384,7 @@ declare namespace LocalJSX {
          */
         "placement"?: PlacementType;
         /**
-          * Ranges listed beside the calendar in range mode. A comma-separated list of built-in keys (`today`, `yesterday`, `last-7-days`, `last-30-days`, `last-90-days`, `this-month`, `last-month`, `this-quarter`, `last-quarter`, `this-year`, `last-year`, `year-to-date`, `last-12-months`), or an array of `{ key, label?, start?, end? }` to relabel built-ins or add your own.
+          * Ranges listed beside the calendar in range mode. A comma-separated list of built-in keys (`today`, `yesterday`, `last-7-days`, `last-30-days`, `last-90-days`, `this-month`, `last-month`, `this-quarter`, `last-quarter`, `this-year`, `last-year`, `year-to-date`, `last-12-months`), or an array of `{ key, label?, startOffset?, endOffset?, start?, end? }` to relabel built-ins or add your own: `startOffset` and `endOffset` follow today, `start` and `end` are fixed days.
          */
         "presets"?: string | DatepickerPreset[];
         /**
@@ -5336,7 +5436,7 @@ declare namespace LocalJSX {
          */
         "triggerLabel"?: string;
         /**
-          * The selected date as `YYYY-MM-DD`, or in range mode the range as `YYYY-MM-DD/YYYY-MM-DD`; with the time picker, each date as `YYYY-MM-DDTHH:mm`. An empty string when nothing is selected.
+          * The selected date as `YYYY-MM-DD`, or in range mode the range as `YYYY-MM-DD/YYYY-MM-DD`; with the time picker, each date as `YYYY-MM-DDTHH:mm`; with `month-day`, the month and day with no year, as `--MM-DD` (a full date is read too, as that month and day, and rewritten to it). An empty string when nothing is selected.
           * @default ''
          */
         "value"?: string;
@@ -5368,7 +5468,7 @@ declare namespace LocalJSX {
     /**
      * A side panel composed from `pds-modal`, non-modal by default.
      * By default, unlike `pds-modal`, the page stays interactive while a drawer
-     * is open: no dimming, no blur, no scroll lock, no click blocking.
+     * is open: no dimming, no blur, no click blocking.
      * `pds-drawer` renders a `pds-modal` internally with `disableTopLayer` on and
      * its backdrop suppressed, and adds the edge, width and dismiss behavior a
      * side panel needs on top. With `modal`, it opens that `pds-modal` in the top
@@ -5387,7 +5487,7 @@ declare namespace LocalJSX {
          */
         "initialFocus"?: 'auto' | 'none';
         /**
-          * Whether the drawer can be dismissed with a pointerdown outside it (in a `modal` drawer, a click on its backdrop). Replaces `pds-modal`'s `backdropDismiss`. This also gates Escape, matching how `backdropDismiss` gates Escape on `pds-modal` today: setting this to `false` means the close button is the only way out.  A trigger outside the drawer should only ever set `open` to `true` and leave closing to the drawer itself. A toggle-style trigger (`open = !open`) fights light dismiss: clicking it while open closes the drawer on `pointerdown`, then the trigger's own click handler re-opens it.
+          * Whether the drawer can be dismissed with a pointerdown outside it (in a `modal` drawer, a click on its backdrop). Setting it to `false` also turns off Escape, so the close button is the only way out.  A trigger outside the drawer should only ever set `open` to `true` and leave closing to the drawer itself. A toggle-style trigger (`open = !open`) fights light dismiss: clicking it while open closes the drawer on `pointerdown`, then the trigger's own click handler re-opens it.
           * @default true
          */
         "lightDismiss"?: boolean;
@@ -5415,7 +5515,7 @@ declare namespace LocalJSX {
          */
         "scrollable"?: boolean;
         /**
-          * Which edge of the viewport the drawer is docked to. Logical, so this is free under RTL — `end` is the inline-end edge regardless of direction.
+          * Which edge of the viewport the drawer is docked to. Logical: `end` is the inline-end edge, so an `end` drawer docks on the left in right-to-left layouts.
           * @default 'end'
          */
         "side"?: 'start' | 'end';
@@ -5426,20 +5526,19 @@ declare namespace LocalJSX {
         "size"?: 'sm' | 'md';
     }
     /**
-     * Fills the drawer panel's height by default — unlike `pds-modal-content`,
-     * which caps itself against the viewport for a centered, possibly-shorter
-     * modal, a drawer panel is already edge-to-edge, so its content can simply
-     * flex to fill whatever space the header and footer leave.
+     * Fills the space between the drawer header and footer.
      * @lightDom renders-markup
      */
     interface PdsDrawerContent {
     }
     /**
+     * Holds the drawer's actions in a padded row aligned to the end, with a divider above.
      * @lightDom renders-markup
      */
     interface PdsDrawerFooter {
     }
     /**
+     * Holds the drawer's title and close control in a padded row, spaced apart, with a divider below.
      * @lightDom renders-markup
      */
     interface PdsDrawerHeader {
@@ -5461,12 +5560,12 @@ declare namespace LocalJSX {
          */
         "componentId"?: string;
         /**
-          * It determines whether or not the dropdown-item is destructive.
+          * Determines whether or not the dropdown menu item is destructive.
           * @defaultValue false
          */
         "destructive"?: boolean;
         /**
-          * It determines whether or not the dropdown-item is disabled.
+          * Determines whether or not the dropdown menu item is disabled.
           * @defaultValue false
          */
         "disabled"?: boolean;
@@ -5475,30 +5574,30 @@ declare namespace LocalJSX {
          */
         "download"?: string;
         /**
-          * Determines whether the link should open in a new tab and display an external icon. This is a simpler alternative to using `target="_blank"` for the common case. Ignored when `informational` is set.
+          * Shows the external-link (launch) icon. Opens in a new tab unless `target` says otherwise. Only applies when href is set. Ignored when `informational` is set.
           * @defaultValue false
          */
         "external"?: boolean;
         /**
-          * Accessible label for the external-link icon, passed to the inner `pds-link`. Pass a translated string to localize it; defaults to English. Pass an empty string to make the icon decorative.
+          * Accessible label for the icon that `external` shows, passed to the inner `pds-link` and appended to the item's name. It isn't announced when `target` is anything other than `_blank`. Pass a translated string to localize it; defaults to English. Pass an empty string to make the icon decorative.
           * @defaultValue '(opens in a new tab)'
          */
         "externalLabel"?: string;
         /**
-          * If provided, renders the dropdown-item as an anchor (`<a>`) element instead of a button. Ignored when `informational` is set.
+          * If provided, renders the dropdown menu item as an anchor (`<a>`) element instead of a button. Ignored when `informational` is set.
          */
         "href"?: string | undefined;
         /**
-          * It determines whether or not the dropdown-item is informational: text that the arrow keys reach but that can't be activated. Takes precedence over `href` and `destructive`. Screen readers announce it as dimmed or unavailable, the same way as a disabled item.
+          * Determines whether or not the dropdown menu item is informational: text that the arrow keys reach but that can't be activated. Takes precedence over `href` and `destructive`. Screen readers announce it as dimmed or unavailable, the same way as a disabled item.
           * @defaultValue false
          */
         "informational"?: boolean;
         /**
-          * Emitted when the dropdown-item is clicked.
+          * Emitted when the dropdown menu item is clicked.
          */
         "onPdsClick"?: (event: PdsDropdownMenuItemCustomEvent<{itemIndex: number, item: HTMLPdsDropdownMenuItemElement, content: string}>) => void;
         /**
-          * Specifies where to open the linked document when href is provided. Takes precedence over the `external` prop if both are set. Only applies when href is set. Ignored when `informational` is set.
+          * Specifies where to open the linked document when href is provided. Overrides the new-tab default of `external`; the icon still shows. Only applies when href is set. Ignored when `informational` is set.
           * @defaultValue undefined
          */
         "target"?: '_blank' | '_self' | '_parent' | '_top';
@@ -5509,16 +5608,14 @@ declare namespace LocalJSX {
          */
         "componentId"?: string;
         /**
-          * It determines whether or not the dropdown-item is disabled.
+          * Has no effect. A separator can't be focused or activated.
           * @defaultValue false
          */
         "disabled"?: boolean;
     }
     /**
-     * Individual filter component with cross-browser popover positioning.
-     * Uses a hybrid approach for optimal cross-browser compatibility:
-     * - Modern browsers: CSS anchor positioning + JavaScript flip classes
-     * - Fallback browsers: JavaScript positioning with viewport boundary detection
+     * A single filter in `pds-filters`: a trigger button that opens a popover holding the filter controls.
+     * The `clear` variant has no popover and emits `pdsFilterClear` instead.
      */
     interface PdsFilter {
         /**
@@ -5542,7 +5639,7 @@ declare namespace LocalJSX {
          */
         "onPdsFilterOpen"?: (event: PdsFilterCustomEvent<PdsFilterOpenEventDetail>) => void;
         /**
-          * The text content displayed in the trigger button.
+          * The text content displayed in the trigger button. When text overflows, a tooltip showing the full text will appear on hover/focus.
          */
         "text"?: string;
         /**
@@ -5559,7 +5656,7 @@ declare namespace LocalJSX {
     }
     interface PdsImage {
         /**
-          * The image's alt tag. If none is provided, it will default to an empty string, which is desired for decorative images.
+          * The image's alt text. Defaults to an empty string, which marks the image as decorative and hides it from screen readers, so set it on any image that carries information.
           * @defaultValue ''
          */
         "alt"?: string;
@@ -5568,7 +5665,12 @@ declare namespace LocalJSX {
          */
         "componentId"?: string;
         /**
-          * The height of the image in pixels. Setting this will devote space in the layout to prevent layout shifts when the image is loaded.
+          * Determines how the image fills the shape set by `ratio`. Has no effect if `ratio` is not set.
+          * @defaultValue cover
+         */
+        "fit"?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+        /**
+          * The height of the image in pixels. `height: auto` lets the loaded image's own proportions decide its rendered height, so unlike `width` this does not reserve space before the image loads.
          */
         "height"?: number;
         /**
@@ -5576,6 +5678,18 @@ declare namespace LocalJSX {
           * @defaultValue eager
          */
         "loading"?: 'eager' | 'lazy';
+        /**
+          * Emitted when the image fails to load, such as for a broken or empty `src`. An image with no `src` or `srcset` at all emits neither event, since it has nothing to load. Emitted again after `src` or `srcset` changes and the new image fails. Bubbles and is composed, so a listener on an ancestor gets every `pds-image`'s events — check `event.target` when more than one is in scope.
+         */
+        "onPdsImageError"?: (event: PdsImageCustomEvent<ImageErrorEventDetail>) => void;
+        /**
+          * Emitted when the image loads. Also emitted on first render for an image that finished loading before the component could listen, such as a server-rendered image. Emitted again after `src` or `srcset` changes and the new image loads, or when the browser picks a different `srcset` candidate, such as on a resize. Bubbles and is composed, so a listener on an ancestor gets every `pds-image`'s events — check `event.target` when more than one is in scope.
+         */
+        "onPdsImageLoad"?: (event: PdsImageCustomEvent<ImageLoadEventDetail>) => void;
+        /**
+          * The aspect ratio the image is sized to, cropping whatever overflows the shape. A preset (`square` 1/1, `landscape` 4/3, `wide` 16/9, `portrait` 3/4, `tall` 9/16) or any custom CSS ratio, such as `21 / 9`. Use this, not `height` and `width`, to crop: those only reserve space, and only `width` reliably does even that.
+         */
+        "ratio"?: ImageRatioType | (string & Record<never, never>);
         /**
           * Determines the intended display size of an image within certain breakpoints. Has no effect if `srcset` is not set or value has no width descriptor.
          */
@@ -5589,7 +5703,7 @@ declare namespace LocalJSX {
          */
         "srcset"?: string;
         /**
-          * The width of the image in pixels. Setting this will devote space in the layout to prevent layout shifts when the image is loaded.
+          * The width of the image in pixels. This reserves the image's width before it loads, but not its height: to reserve the height too, set `--dimension-aspect-ratio` to the image's own proportions.
          */
         "width"?: number;
     }
@@ -5603,7 +5717,7 @@ declare namespace LocalJSX {
          */
         "componentId": string;
         /**
-          * Sets the number of milliseconds to wait before updating the value.
+          * Sets the number of milliseconds to wait after each input event before emitting `pdsInput`.
          */
         "debounce"?: number;
         /**
@@ -5611,7 +5725,7 @@ declare namespace LocalJSX {
          */
         "disabled"?: boolean;
         /**
-          * Specifies the error message and provides an error-themed treatment to the field.
+          * Displays an error message below the input and gives the field error styling. It becomes the input's accessible description only while `invalid` is set.
          */
         "errorMessage"?: string;
         /**
@@ -5635,7 +5749,7 @@ declare namespace LocalJSX {
          */
         "highlight"?: boolean;
         /**
-          * Determines whether or not the input field is invalid or throws an error.
+          * Determines whether or not the input is invalid.
          */
         "invalid"?: boolean;
         /**
@@ -5667,7 +5781,7 @@ declare namespace LocalJSX {
          */
         "onPdsBlur"?: (event: PdsInputCustomEvent<FocusEvent>) => void;
         /**
-          * Emitted when the value has changed.  This event will not emit when programmatically setting the `value` property.
+          * Emitted when the user changes the value and then presses `Enter` or leaves the field. `detail` has `value`, as a string, and `event`, the native event behind it, usually `change`.  This event will not emit when programmatically setting the `value` property, unless the field has focus at the time; then it emits when the field loses focus.
          */
         "onPdsChange"?: (event: PdsInputCustomEvent<InputChangeEventDetail>) => void;
         /**
@@ -5675,7 +5789,7 @@ declare namespace LocalJSX {
          */
         "onPdsFocus"?: (event: PdsInputCustomEvent<FocusEvent>) => void;
         /**
-          * Emitted when a keyboard input occurs.
+          * Emitted after each `input` event, such as typing or pasting. With `debounce`, it waits until that many milliseconds have passed since the last one. `detail` has `value`, the current value as a string, and `event`, the native `input` event.  This event will not emit when programmatically setting the `value` property.
          */
         "onPdsInput"?: (event: PdsInputCustomEvent<InputInputEventDetail>) => void;
         /**
@@ -5703,7 +5817,7 @@ declare namespace LocalJSX {
          */
         "step"?: string;
         /**
-          * Determines the type of control that will be displayed `'email'`, `'number'`, `'password'`, `'tel'`, `'text'`, `'url'`
+          * Determines the type of control that will be displayed `'email'`, `'number'`, `'password'`, `'search'`, `'tel'`, `'text'`, `'url'`
           * @defaultValue "text"
          */
         "type"?: string;
@@ -5732,13 +5846,12 @@ declare namespace LocalJSX {
          */
         "download"?: string;
         /**
-          * Determines whether the link should open in a new tab.
+          * Shows the external-link (launch) icon. Opens in a new tab unless `target` says otherwise.
           * @defaultValue false
-          * @deprecated Consider using the `target` prop for more control. This prop will be maintained for backward compatibility.
          */
         "external"?: boolean;
         /**
-          * Accessible label for the icon that `external` shows, appended to the link's name. It isn't announced when `target` keeps the link in the same tab. Pass a translated string to localize it; defaults to English. Pass an empty string to make the icon decorative.
+          * Accessible label for the icon that `external` shows, appended to the link's name. It isn't announced when `target` is anything other than `_blank`. Pass a translated string to localize it; defaults to English. Pass an empty string to make the icon decorative.
           * @defaultValue '(opens in a new tab)'
          */
         "externalLabel"?: string;
@@ -5748,13 +5861,13 @@ declare namespace LocalJSX {
          */
         "fontSize"?: 'sm' | 'md' | 'lg';
         /**
-          * The hyperlink's destination URL. If no text is provided in the custom slot, the href will be used.
+          * The hyperlink's destination URL. If the default slot is empty (whitespace counts as content), the href will be used as the link text.
          */
         "href": string;
         /**
-          * Specifies where to open the linked document.
+          * Specifies where to open the linked document. Overrides the new-tab default of `external`; the icon still shows.
           * @defaultValue undefined
-          * @example <pds-link href="https://example.com" target="_blank">Opens in new tab</pds-link>
+          * @example <pds-link href="/dashboard" target="_top">Opens in the top-level frame</pds-link>
          */
         "target"?: '_blank' | '_self' | '_parent' | '_top';
         /**
@@ -5807,7 +5920,7 @@ declare namespace LocalJSX {
          */
         "showLabel"?: boolean;
         /**
-          * Sets the size of the spinner loader. Value can be preset or custom.
+          * Sets the size of the spinner loader: `xs` (24px), `sm` (32px), `md` (48px), `lg` (64px), `xl` (80px), or a custom CSS length such as `128px`. The `typing` variant ignores it.
           * @default 'md'
          */
         "size"?: | 'xs' // 24px
@@ -5836,7 +5949,7 @@ declare namespace LocalJSX {
          */
         "componentId"?: string;
         /**
-          * Whether to skip moving focus into the modal when it opens — both our own `setInitialFocus()` and the browser's native "dialog focusing steps", which move focus into the dialog as soon as `show()`/`showModal()` is called regardless of application code. Focus return on close is unaffected either way. For a modal opened by something other than a direct user click — a redirect, a deep link, a background event — stealing focus on open can interrupt whatever the user was already doing. Default `false` preserves today's behavior for every existing consumer.
+          * Whether to skip moving focus into the modal when it opens. Set it for a modal that can open from a background event while the user is mid-task elsewhere on the page, where moving focus would interrupt them. Pair it with `disableTopLayer`: in the top layer the rest of the page is inert, so focus can't stay there. On close, focus moves back only if nothing outside the modal has taken it.
           * @default false
          */
         "disableInitialFocus"?: boolean;
@@ -5880,11 +5993,13 @@ declare namespace LocalJSX {
         "border"?: 'none' | 'both' | 'top' | 'bottom';
     }
     /**
+     * Holds the modal's actions. It adds no padding or layout, so wrap its content in a `pds-box` with `padding="md"`.
      * @lightDom renders-markup
      */
     interface PdsModalFooter {
     }
     /**
+     * Holds the modal's title and close control. It adds no padding or layout, so wrap its content in a `pds-box` with `padding="md"`.
      * @lightDom renders-markup
      */
     interface PdsModalHeader {
@@ -6027,7 +6142,7 @@ declare namespace LocalJSX {
          */
         "onPdsMultiselectCreate"?: (event: PdsMultiselectCustomEvent<MultiselectCreateEventDetail>) => void;
         /**
-          * Emitted when the dropdown is dismissed via Escape key or click outside.  This event fires only when the user explicitly dismisses the panel without making a selection: - ✅ Fires: Pressing Escape key while dropdown is open - ✅ Fires: Clicking outside the component while dropdown is open - ❌ Does NOT fire: When panel closes due to selection (including when `closePanelOnSelect` is true) - ❌ Does NOT fire: When panel closes programmatically via `closeDropdown()`  Equivalent to Sage's `onEscapeHook`. Use this to restore parent UI state or run cleanup when the user cancels their interaction.
+          * Emitted when the dropdown is dismissed with the Escape key, or by focus moving outside the component, such as with a click elsewhere on the page.  It doesn't fire when the panel closes any other way: from a selection (including with `closePanelOnSelect`) or an option action, a click on the trigger, Tab, or the multiselect becoming disabled. Safari doesn't focus a clicked button, so there a click on the trigger while the panel is open fires this event, and the panel opens again. Use it to restore parent UI state or run cleanup when the user cancels.
          */
         "onPdsMultiselectDismiss"?: (event: PdsMultiselectCustomEvent<void>) => void;
         /**
@@ -6147,8 +6262,8 @@ declare namespace LocalJSX {
          */
         "componentId"?: string;
         /**
-          * Sets the maximum width of the popover content
-          * @defaultValue 352
+          * Sets the maximum width of the popover, in pixels, including its padding.
+          * @defaultValue 400
          */
         "maxWidth"?: number;
         /**
@@ -6197,7 +6312,7 @@ declare namespace LocalJSX {
         "componentId": string;
         /**
           * Sets the progress fill color. Accepts a color token or a [valid color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
-          * @defaultValue 'var(--pine-color-blue-300)'
+          * @defaultValue 'var(--pine-color-primary)'
          */
         "fillColor"?: string;
         /**
@@ -6205,7 +6320,7 @@ declare namespace LocalJSX {
          */
         "label": string;
         /**
-          * Sets the progress fill pecentage and visually displayed when `show-percentage=true`.
+          * Sets the progress fill percentage (0–100). Shown as text when `show-percent` is set.
           * @defaultValue 0
          */
         "percent"?: number;
@@ -6231,7 +6346,7 @@ declare namespace LocalJSX {
      */
     interface PdsRadio {
         /**
-          * 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
          */
         "checked"?: boolean;
@@ -6245,7 +6360,7 @@ declare namespace LocalJSX {
          */
         "disabled"?: boolean;
         /**
-          * Displays error message text describing an invalid state.
+          * Displays an error message below the radio. It becomes the radio's accessible description only while `invalid` is set.
          */
         "errorMessage"?: string;
         /**
@@ -6254,7 +6369,7 @@ declare namespace LocalJSX {
          */
         "hasBorder"?: boolean;
         /**
-          * Displays helper message text below radio.
+          * Displays a message or hint below the radio.
          */
         "helperMessage"?: string;
         /**
@@ -6267,7 +6382,7 @@ declare namespace LocalJSX {
          */
         "invalid"?: boolean;
         /**
-          * String used for label text next to radio.
+          * Text to be displayed as the radio label.
          */
         "label"?: string;
         /**
@@ -6275,7 +6390,7 @@ declare namespace LocalJSX {
          */
         "name"?: string;
         /**
-          * Emits a boolean indicating whether the radio is currently checked or unchecked.
+          * 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. Not emitted when picking another radio unchecks this one. Not emitted inside `pds-radio-group` either; listen for `pdsRadioGroupChange` there.
          */
         "onPdsRadioChange"?: (event: PdsRadioCustomEvent<boolean>) => void;
         /**
@@ -6312,7 +6427,7 @@ declare namespace LocalJSX {
          */
         "disabled"?: boolean;
         /**
-          * Displays error message text describing an invalid state for the entire group.
+          * Displays an error message below the radio group. It's part of the group's accessible description, with or without `invalid`.
          */
         "errorMessage"?: string;
         /**
@@ -6321,11 +6436,11 @@ declare namespace LocalJSX {
          */
         "gap"?: string;
         /**
-          * String used for group label/heading.
+          * Text to be displayed as the radio group label. It also names the group, unless you set `aria-label` or `aria-labelledby` on it.
          */
         "groupLabel"?: string;
         /**
-          * Displays helper message text below the radio group.
+          * Displays a message or hint below the radio group.
          */
         "helperMessage"?: string;
         /**
@@ -6338,7 +6453,7 @@ declare namespace LocalJSX {
          */
         "name"?: string;
         /**
-          * Emits when a radio in the group is selected, providing the selected value and component ID.
+          * Emitted when the user checks a radio in the group, by a click or an arrow key. `detail` has that radio's `value` and `componentId`, and `checked`, which is always `true`.
          */
         "onPdsRadioGroupChange"?: (event: PdsRadioGroupCustomEvent<RadioGroupChangeEventDetail>) => void;
         /**
@@ -6407,7 +6522,7 @@ declare namespace LocalJSX {
          */
         "disabled"?: boolean;
         /**
-          * Displays error message text describing an invalid state.
+          * Displays an error message below the select and marks the select as invalid, with or without `invalid`.
          */
         "errorMessage"?: string;
         /**
@@ -6415,7 +6530,7 @@ declare namespace LocalJSX {
          */
         "form"?: string;
         /**
-          * Displays helper message text below select.
+          * Displays a message or hint below the select.
          */
         "helperMessage"?: string;
         /**
@@ -6456,7 +6571,7 @@ declare namespace LocalJSX {
          */
         "onPdsKeyDown"?: (event: PdsSelectCustomEvent<KeyboardEvent>) => void;
         /**
-          * Emitted when the select value changes.
+          * Emitted when the user changes the selection. `detail` is the native `change` event, so read the new value from the select's `value`: a string, or an array with `multiple`.  This event will not emit when programmatically setting the `value` property.
          */
         "onPdsSelectChange"?: (event: PdsSelectCustomEvent<InputEvent>) => void;
         /**
@@ -6492,15 +6607,40 @@ declare namespace LocalJSX {
           * @default false
          */
         "dividers"?: boolean;
+        /**
+          * Accessible label for each item's reorder handle, the button the keyboard reorders with. Pass a translated string to localize it; `{item}` is interpolated.
+          * @defaultValue 'Reorder {item}'
+         */
+        "handleLabel"?: string;
         /**
           * Determines the grabbable area for the `pds-sortable-item`.
           * @default 'row'
          */
         "handleType"?: 'handle' | 'row';
         /**
-          * Event emitted when a sortable item is moved.
+          * Screen-reader announcement when a picked-up item is dropped. Pass a translated string to localize it; `{item}`, `{position}` and `{total}` are interpolated.
+          * @defaultValue '{item}, dropped at position {position} of {total}'
+         */
+        "itemDroppedLabel"?: string;
+        /**
+          * Screen-reader announcement when a picked-up item is moved. Pass a translated string to localize it; `{item}`, `{position}` and `{total}` are interpolated.
+          * @defaultValue '{item}, moved to position {position} of {total}'
+         */
+        "itemMovedLabel"?: string;
+        /**
+          * Screen-reader announcement when an item is picked up from the keyboard. Pass a translated string to localize it; `{item}`, `{position}` and `{total}` are interpolated.
+          * @defaultValue '{item}, picked up. Position {position} of {total}. Press the arrow keys to move, Space or Enter to drop, Escape to cancel.'
+         */
+        "itemPickedUpLabel"?: string;
+        /**
+          * Event emitted when a sortable item is moved, by dragging or from the keyboard. A keyboard move carries the same fields as a drag (`item`, `from`, `to`, `oldIndex`, `newIndex`, `oldDraggableIndex`, `newDraggableIndex`), with the event that ended the move as `originalEvent` -- a `KeyboardEvent` for Space or Enter, but a `FocusEvent`, `PointerEvent` or `MouseEvent` when the drop instead comes from focus leaving the row, a drag taking over, or a screen reader's browse-mode click.
          */
         "onPdsSortableItemMoved"?: (event: PdsSortableCustomEvent<SortableEvent>) => void;
+        /**
+          * Screen-reader announcement when a keyboard reorder is canceled and the item goes back. Pass a translated string to localize it; `{item}`, `{position}` and `{total}` are interpolated.
+          * @defaultValue 'Reorder canceled. {item} returned to position {position} of {total}'
+         */
+        "reorderCanceledLabel"?: string;
     }
     /**
      * @lightDom renders-markup
@@ -6516,7 +6656,11 @@ declare namespace LocalJSX {
          */
         "enableActions"?: boolean;
         /**
-          * Determines whether `sortable-item` should have a handle.
+          * 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.
+         */
+        "itemLabel"?: string;
+        /**
+          * 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
          */
         "showHandle"?: boolean;
@@ -6562,7 +6706,7 @@ declare namespace LocalJSX {
          */
         "label"?: string;
         /**
-          * Identifies form data and unifies a group of radio inputs for toggling a single property/value.
+          * Specifies the name. Submitted with the form name/value pair when checked, or with `unchecked-value` while unchecked.
          */
         "name"?: string;
         /**
@@ -6574,6 +6718,10 @@ declare namespace LocalJSX {
           * @default false
          */
         "required"?: boolean;
+        /**
+          * Provides a string submitted in form data under `name` while the switch is unchecked. When unset, an unchecked switch submits nothing, like a native checkbox.
+         */
+        "uncheckedValue"?: string;
         /**
           * Provides input with a string submitted in form data.
          */
@@ -6638,11 +6786,11 @@ declare namespace LocalJSX {
          */
         "disableSelectAll"?: boolean;
         /**
-          * Determines if the should display a fixed first column.
+          * Determines if the table displays a fixed first column.
          */
         "fixedColumn"?: boolean;
         /**
-          * Event that is emitted when the select all checkbox is clicked, carrying the selected value.
+          * Event that is emitted by `pds-table-head` when the select all checkbox is clicked, carrying the selected value. It bubbles through the table; the table doesn't emit it itself.
          */
         "onPdsTableSelectAll"?: (event: PdsTableCustomEvent<{ isSelected: boolean }>) => void;
         /**
@@ -6658,6 +6806,11 @@ declare namespace LocalJSX {
           * Determines if the table displays checkboxes for selectable rows.
          */
         "selectable"?: boolean;
+        /**
+          * Sets how the table sizes its columns. With `auto`, each column is sized from its content, so columns can change width when the rows change (for example after a sort). With `fixed`, columns take the `width` set on their `pds-table-head-cell` and ignore their content; columns without a `width` share the remaining space. Under `responsive`, that remaining share keeps a 120px floor on narrow viewports where the other columns' widths already fill it, growing the table instead (scrollable) -- without `responsive` there's no floor, since there would be nothing to scroll the overflow it would create. Content longer than its column overflows, so add `truncate` to cells whose content may not fit.
+          * @defaultValue 'auto'
+         */
+        "tableLayout"?: 'auto' | 'fixed';
     }
     interface PdsTableBody {
     }
@@ -6687,7 +6840,7 @@ declare namespace LocalJSX {
          */
         "indeterminate"?: boolean;
         /**
-          * Determines if the table row is currently selected.
+          * Determines if the select all checkbox is checked.
           * @defaultValue false
          */
         "isSelected"?: boolean;
@@ -6709,6 +6862,10 @@ declare namespace LocalJSX {
           * Determines whether the table column is sortable when set to `true`.
          */
         "sortable"?: boolean;
+        /**
+          * Sets the width of the column. Accepts any CSS length (e.g. '148px', '12rem', '20%'). When the table's `tableLayout` is `fixed`, the column keeps this width whatever its content. Otherwise the column is at least this wide and can grow to fit its content.
+         */
+        "width"?: string;
     }
     interface PdsTableRow {
         /**
@@ -6753,7 +6910,7 @@ declare namespace LocalJSX {
          */
         "nav"?: boolean;
         /**
-          * Stretches the component so the active tab panel fills the remaining height. Requires the component to have a constrained height (e.g. a flex parent).
+          * Stretches the component to fill its container's height. The active tab panel keeps the height of its content. Requires the component to have a constrained height (e.g. a flex parent).
           * @defaultValue false
          */
         "stretch"?: boolean;
@@ -6836,7 +6993,7 @@ declare namespace LocalJSX {
          */
         "componentId": string;
         /**
-          * The amount of time, in milliseconds, to wait to trigger the event after each keystroke.
+          * Sets the number of milliseconds to wait after each input event before emitting `pdsInput`.
          */
         "debounce"?: number;
         /**
@@ -6845,7 +7002,7 @@ declare namespace LocalJSX {
          */
         "disabled"?: boolean;
         /**
-          * Displays an error message below the textarea field.
+          * Displays an error message below the textarea while `invalid` is set.
          */
         "errorMessage"?: string;
         /**
@@ -6865,7 +7022,7 @@ declare namespace LocalJSX {
          */
         "highlight"?: boolean;
         /**
-          * Determines whether or not the textarea is invalid or throws an error.
+          * Determines whether or not the textarea is invalid. When `required` is set, the textarea sets it itself each time `pdsTextareaChange` fires, replacing a value you set.
           * @defaultValue false
          */
         "invalid"?: boolean;
@@ -6878,20 +7035,20 @@ declare namespace LocalJSX {
          */
         "maxLength"?: number;
         /**
-          * Specifies the name. Submitted with the form name/value pair. This value will mirror the componentId.
+          * Specifies the name. Submitted with the form name/value pair.
           * @default this.componentId
          */
         "name"?: string;
         /**
-          * Emitted when the input loses focus.
+          * Emitted when the textarea loses focus.
          */
         "onPdsBlur"?: (event: PdsTextareaCustomEvent<FocusEvent>) => void;
         /**
-          * Emitted when the input has focus.
+          * Emitted when the textarea has focus.
          */
         "onPdsFocus"?: (event: PdsTextareaCustomEvent<FocusEvent>) => void;
         /**
-          * Emitted when a keyboard input occurs.  For elements that accept text input (`type=text`, `type=tel`, etc.), the interface is [`InputEvent`](https://developer.mozilla.org/en-US/docs/Web/API/InputEvent); for others, the interface is [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event). If the input is cleared on edit, the type is `null`.
+          * Emitted after each `input` event, such as typing or pasting. With `debounce`, it waits until that many milliseconds have passed since the last one. `detail` has `value`, the current text, and `event`, the native `input` event.  This event will not emit when programmatically setting the `value` property.
          */
         "onPdsInput"?: (event: PdsTextareaCustomEvent<TextareaInputEventDetail>) => void;
         /**
@@ -6899,7 +7056,7 @@ declare namespace LocalJSX {
          */
         "onPdsKeyDown"?: (event: PdsTextareaCustomEvent<KeyboardEvent>) => void;
         /**
-          * Event emitted whenever the value of the textarea changes.  This event will not emit when programmatically setting the `value` property.
+          * Emitted when the user changes the value and then leaves the textarea. `Enter` adds a new line, so it doesn't emit this event. `detail` has `value`, the text, and `event`, the native event behind it, usually `change`.  This event will not emit when programmatically setting the `value` property, unless the field has focus at the time; then it emits when the field loses focus.
          */
         "onPdsTextareaChange"?: (event: PdsTextareaCustomEvent<TextareaChangeEventDetail>) => void;
         /**
@@ -7072,6 +7229,7 @@ declare namespace LocalJSX {
         "borderInlineEnd": boolean;
         "borderInlineStart": boolean;
         "borderRadius": `none` | `xs`| `sm` | `md` | `lg` | `circle`;
+        "container": BoxContainerType;
         "direction": `row` | `column`;
         "display": `flex` | `inline-flex` | `block` | `inline-block`;
         "fit": boolean;
@@ -7099,30 +7257,30 @@ declare namespace LocalJSX {
         "justifyContentMd": `start` | `center` | `end` | `space-between` | `space-around` | `space-evenly`;
         "justifyContentLg": `start` | `center` | `end` | `space-between` | `space-around` | `space-evenly`;
         "justifyContentXl": `start` | `center` | `end` | `space-between` | `space-around` | `space-evenly`;
-        "marginBlockStart": BoxSpacingType;
-        "marginBlockStartXs": BoxSpacingType;
-        "marginBlockStartSm": BoxSpacingType;
-        "marginBlockStartMd": BoxSpacingType;
-        "marginBlockStartLg": BoxSpacingType;
-        "marginBlockStartXl": BoxSpacingType;
-        "marginInlineStart": BoxSpacingType;
-        "marginInlineStartXs": BoxSpacingType;
-        "marginInlineStartSm": BoxSpacingType;
-        "marginInlineStartMd": BoxSpacingType;
-        "marginInlineStartLg": BoxSpacingType;
-        "marginInlineStartXl": BoxSpacingType;
-        "marginInlineEnd": BoxSpacingType;
-        "marginInlineEndXs": BoxSpacingType;
-        "marginInlineEndSm": BoxSpacingType;
-        "marginInlineEndMd": BoxSpacingType;
-        "marginInlineEndLg": BoxSpacingType;
-        "marginInlineEndXl": BoxSpacingType;
-        "marginBlockEnd": BoxSpacingType;
-        "marginBlockEndXs": BoxSpacingType;
-        "marginBlockEndSm": BoxSpacingType;
-        "marginBlockEndMd": BoxSpacingType;
-        "marginBlockEndLg": BoxSpacingType;
-        "marginBlockEndXl": BoxSpacingType;
+        "marginBlockStart": BoxMarginType;
+        "marginBlockStartXs": BoxMarginType;
+        "marginBlockStartSm": BoxMarginType;
+        "marginBlockStartMd": BoxMarginType;
+        "marginBlockStartLg": BoxMarginType;
+        "marginBlockStartXl": BoxMarginType;
+        "marginInlineStart": BoxMarginType;
+        "marginInlineStartXs": BoxMarginType;
+        "marginInlineStartSm": BoxMarginType;
+        "marginInlineStartMd": BoxMarginType;
+        "marginInlineStartLg": BoxMarginType;
+        "marginInlineStartXl": BoxMarginType;
+        "marginInlineEnd": BoxMarginType;
+        "marginInlineEndXs": BoxMarginType;
+        "marginInlineEndSm": BoxMarginType;
+        "marginInlineEndMd": BoxMarginType;
+        "marginInlineEndLg": BoxMarginType;
+        "marginInlineEndXl": BoxMarginType;
+        "marginBlockEnd": BoxMarginType;
+        "marginBlockEndXs": BoxMarginType;
+        "marginBlockEndSm": BoxMarginType;
+        "marginBlockEndMd": BoxMarginType;
+        "marginBlockEndLg": BoxMarginType;
+        "marginBlockEndXl": BoxMarginType;
         "minHeight": string;
         "minWidth": string;
         "offset": BoxColumnType;
@@ -7296,6 +7454,7 @@ declare namespace LocalJSX {
         "minuteIncrement": number;
         "minuteLabel": string;
         "monthLabel": string;
+        "monthDay": boolean;
         "name": string;
         "nextMonthLabel": string;
         "periodLabel": string;
@@ -7362,8 +7521,10 @@ declare namespace LocalJSX {
     interface PdsImageAttributes {
         "alt": string;
         "componentId": string;
+        "fit": 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
         "height": number;
         "loading": 'eager' | 'lazy';
+        "ratio": ImageRatioType | (string & Record<never, never>);
         "sizes": string;
         "src": string;
         "srcset": string;
@@ -7563,11 +7724,17 @@ declare namespace LocalJSX {
         "componentId": string;
         "dividers": boolean;
         "handleType": 'handle' | 'row';
+        "handleLabel": string;
+        "itemPickedUpLabel": string;
+        "itemMovedLabel": string;
+        "itemDroppedLabel": string;
+        "reorderCanceledLabel": string;
     }
     interface PdsSortableItemAttributes {
         "enableActions": boolean;
         "componentId": string;
         "showHandle": boolean;
+        "itemLabel": string;
     }
     interface PdsSwitchAttributes {
         "componentId": string;
@@ -7581,6 +7748,7 @@ declare namespace LocalJSX {
         "name": string;
         "required": boolean;
         "value": string;
+        "uncheckedValue": string;
     }
     interface PdsTabAttributes {
         "disabled": boolean;
@@ -7599,6 +7767,7 @@ declare namespace LocalJSX {
         "selectable": boolean;
         "disableSelectAll": boolean;
         "rowDividers": boolean;
+        "tableLayout": 'auto' | 'fixed';
         "defaultSortColumn": string;
         "defaultSortDirection": 'asc' | 'desc';
     }
@@ -7615,6 +7784,7 @@ declare namespace LocalJSX {
     interface PdsTableHeadCellAttributes {
         "cellAlign": 'start' | 'center' | 'end' | 'justify';
         "sortable": boolean;
+        "width": string;
     }
     interface PdsTableRowAttributes {
         "indeterminate": boolean;
@@ -7780,14 +7950,15 @@ declare module "@stencil/core" {
             /**
              * A field for one date, or in range mode a start and end date, with a calendar to pick from.
              * The value is `YYYY-MM-DD`, or `YYYY-MM-DD/YYYY-MM-DD` for a range; with the time picker, each
-             * date carries a time, as `YYYY-MM-DDTHH:mm`.
+             * date carries a time, as `YYYY-MM-DDTHH:mm`. In month-day mode, for a date that comes round every
+             * year such as a birthday, it's a month and day with no year, as `--MM-DD`.
              */
             "pds-datepicker": LocalJSX.IntrinsicElements["pds-datepicker"] & JSXBase.HTMLAttributes<HTMLPdsDatepickerElement>;
             "pds-divider": LocalJSX.IntrinsicElements["pds-divider"] & JSXBase.HTMLAttributes<HTMLPdsDividerElement>;
             /**
              * A side panel composed from `pds-modal`, non-modal by default.
              * By default, unlike `pds-modal`, the page stays interactive while a drawer
-             * is open: no dimming, no blur, no scroll lock, no click blocking.
+             * is open: no dimming, no blur, no click blocking.
              * `pds-drawer` renders a `pds-modal` internally with `disableTopLayer` on and
              * its backdrop suppressed, and adds the edge, width and dismiss behavior a
              * side panel needs on top. With `modal`, it opens that `pds-modal` in the top
@@ -7797,18 +7968,17 @@ declare module "@stencil/core" {
              */
             "pds-drawer": LocalJSX.IntrinsicElements["pds-drawer"] & JSXBase.HTMLAttributes<HTMLPdsDrawerElement>;
             /**
-             * Fills the drawer panel's height by default — unlike `pds-modal-content`,
-             * which caps itself against the viewport for a centered, possibly-shorter
-             * modal, a drawer panel is already edge-to-edge, so its content can simply
-             * flex to fill whatever space the header and footer leave.
+             * Fills the space between the drawer header and footer.
              * @lightDom renders-markup
              */
             "pds-drawer-content": LocalJSX.IntrinsicElements["pds-drawer-content"] & JSXBase.HTMLAttributes<HTMLPdsDrawerContentElement>;
             /**
+             * Holds the drawer's actions in a padded row aligned to the end, with a divider above.
              * @lightDom renders-markup
              */
             "pds-drawer-footer": LocalJSX.IntrinsicElements["pds-drawer-footer"] & JSXBase.HTMLAttributes<HTMLPdsDrawerFooterElement>;
             /**
+             * Holds the drawer's title and close control in a padded row, spaced apart, with a divider below.
              * @lightDom renders-markup
              */
             "pds-drawer-header": LocalJSX.IntrinsicElements["pds-drawer-header"] & JSXBase.HTMLAttributes<HTMLPdsDrawerHeaderElement>;
@@ -7816,10 +7986,8 @@ declare module "@stencil/core" {
             "pds-dropdown-menu-item": LocalJSX.IntrinsicElements["pds-dropdown-menu-item"] & JSXBase.HTMLAttributes<HTMLPdsDropdownMenuItemElement>;
             "pds-dropdown-menu-separator": LocalJSX.IntrinsicElements["pds-dropdown-menu-separator"] & JSXBase.HTMLAttributes<HTMLPdsDropdownMenuSeparatorElement>;
             /**
-             * Individual filter component with cross-browser popover positioning.
-             * Uses a hybrid approach for optimal cross-browser compatibility:
-             * - Modern browsers: CSS anchor positioning + JavaScript flip classes
-             * - Fallback browsers: JavaScript positioning with viewport boundary detection
+             * A single filter in `pds-filters`: a trigger button that opens a popover holding the filter controls.
+             * The `clear` variant has no popover and emits `pdsFilterClear` instead.
              */
             "pds-filter": LocalJSX.IntrinsicElements["pds-filter"] & JSXBase.HTMLAttributes<HTMLPdsFilterElement>;
             "pds-filters": LocalJSX.IntrinsicElements["pds-filters"] & JSXBase.HTMLAttributes<HTMLPdsFiltersElement>;
@@ -7836,10 +8004,12 @@ declare module "@stencil/core" {
              */
             "pds-modal-content": LocalJSX.IntrinsicElements["pds-modal-content"] & JSXBase.HTMLAttributes<HTMLPdsModalContentElement>;
             /**
+             * Holds the modal's actions. It adds no padding or layout, so wrap its content in a `pds-box` with `padding="md"`.
              * @lightDom renders-markup
              */
             "pds-modal-footer": LocalJSX.IntrinsicElements["pds-modal-footer"] & JSXBase.HTMLAttributes<HTMLPdsModalFooterElement>;
             /**
+             * Holds the modal's title and close control. It adds no padding or layout, so wrap its content in a `pds-box` with `padding="md"`.
              * @lightDom renders-markup
              */
             "pds-modal-header": LocalJSX.IntrinsicElements["pds-modal-header"] & JSXBase.HTMLAttributes<HTMLPdsModalHeaderElement>;