@pine-ds/core 4.10.0 → 4.12.0

package/dist/collection/components/pds-image/pds-image.css

@@ -1,8 +1,10 @@
 :host {
   /**
    * @prop --dimension-aspect-ratio: The image's aspect ratio.
+   * @prop --dimension-object-fit: How the image fills the shape its aspect ratio gives it.
   */
   --dimension-aspect-ratio: auto;
+  --dimension-object-fit: cover;
   display: inline-block;
 }
 
@@ -11,4 +13,13 @@ img {
   display: block;
   height: auto;
   max-width: 100%;
+  object-fit: var(--dimension-object-fit);
+}
+
+:host(.pds-image--has-ratio) {
+  display: block;
+}
+
+:host(.pds-image--has-ratio) img {
+  width: 100%;
 }

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

@@ -2,22 +2,154 @@ import { Host, h } from "@stencil/core";
 export class PdsImage {
     constructor() {
         /**
-         * 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 ''
          */
         this.alt = '';
+        /**
+         * Determines how the image fills the shape set by `ratio`.
+         * Has no effect if `ratio` is not set.
+         * @defaultValue cover
+         */
+        this.fit = 'cover';
         /**
          * Indicates how the browser should load the image.
          * @defaultValue eager
          */
         this.loading = 'eager';
+        /**
+         * The source and event last emitted. A cached image can report `complete` on first
+         * render and still fire its own `load` event afterwards, so this keeps one source
+         * from emitting twice. A `load` still replaces an `error` for the same source, in
+         * case `decode()` misjudged an image that did load.
+         */
+        this.settled = null;
+        this.emitLoad = () => {
+            var _a;
+            if (!this.hasSource())
+                return;
+            const { currentSrc, naturalHeight, naturalWidth } = this.imageEl;
+            if (!this.showsCurrentSource())
+                return;
+            if (((_a = this.settled) === null || _a === void 0 ? void 0 : _a.src) === currentSrc && this.settled.type === 'load')
+                return;
+            this.settled = { src: currentSrc, type: 'load' };
+            this.pdsImageLoad.emit({ currentSrc, naturalHeight, naturalWidth });
+        };
+        this.emitError = () => {
+            var _a;
+            if (!this.hasSource())
+                return;
+            const { currentSrc } = this.imageEl;
+            if (!this.showsCurrentSource())
+                return;
+            if (((_a = this.settled) === null || _a === void 0 ? void 0 : _a.src) === currentSrc)
+                return;
+            this.settled = { src: currentSrc, type: 'error' };
+            this.pdsImageError.emit({ currentSrc });
+        };
+    }
+    handleSourceChange() {
+        this.settled = null;
+    }
+    componentDidLoad() {
+        const img = this.imageEl;
+        // With no `src` or `srcset` there is nothing to load and no event to emit. An empty
+        // `src` still counts: the browser treats it as a failed load.
+        if (!(img === null || img === void 0 ? void 0 : img.complete) || !this.hasSource())
+            return;
+        if (img.naturalWidth > 0) {
+            this.emitLoad();
+            return;
+        }
+        // `complete` with no intrinsic width is either a broken image or an SVG with no
+        // intrinsic size, and only decoding tells them apart. Without `decode()`, leave it
+        // to the native events.
+        if (typeof img.decode !== 'function')
+            return;
+        const src = img.currentSrc;
+        img.decode().then(() => img.currentSrc === src && this.emitLoad(), () => img.currentSrc === src && this.emitError());
+    }
+    // With no `src` or `srcset` attribute at all there is nothing to load and no event to
+    // emit. Clearing `src` can leave a brief window where Stencil has removed the attribute
+    // but a native `error` for the old, momentarily-empty `src` is still in flight (Firefox,
+    // Safari) — this check, read live at emit time, is what catches that window.
+    hasSource() {
+        const img = this.imageEl;
+        return img.hasAttribute('src') || img.hasAttribute('srcset');
+    }
+    /**
+     * The resolved absolute URL `src` would become once applied, or `undefined` for no
+     * `src`. Resolving it (rather than comparing raw attribute text) matches `img.src`
+     * even when Stencil skipped writing the attribute because the resolved value already
+     * equaled it, such as a `src` change from a relative to an equivalent absolute URL.
+     */
+    resolvedSrc() {
+        if (this.src == null)
+            return undefined;
+        try {
+            return new URL(this.src, document.baseURI).href;
+        }
+        catch (_a) {
+            return this.src;
+        }
+    }
+    /**
+     * Whether the inner image is showing the current `src` and `srcset`. Right after
+     * either changes, and before the next render applies it, an event can still arrive
+     * for the old source, and it shouldn't be emitted for the new one.
+     */
+    showsCurrentSource() {
+        var _a, _b;
+        const img = this.imageEl;
+        if (((_a = img.getAttribute('srcset')) !== null && _a !== void 0 ? _a : undefined) !== ((_b = this.srcset) !== null && _b !== void 0 ? _b : undefined))
+            return false;
+        const expectedSrc = this.resolvedSrc();
+        const srcMatches = expectedSrc === undefined ? !img.hasAttribute('src') : img.src === expectedSrc;
+        if (!srcMatches)
+            return false;
+        // Without `srcset`, a `load`/`error` for the right `src` should already be reflected in
+        // `currentSrc`. If it isn't yet, a stale native event from the previous source is still in
+        // flight — such as a cached image's `load` arriving just after a same-tick re-render
+        // already applied the new `src`. Skipped for an empty `src`: an empty attribute resolves
+        // `img.src` to the document's own URL, which `currentSrc` never settles to. `currentSrc` is
+        // already an absolute URL in a real browser, so resolving it here is a no-op there; it only
+        // matters in test environments whose mocked `currentSrc` isn't resolved the way `img.src` is.
+        if (!this.srcset && this.src) {
+            try {
+                return new URL(img.currentSrc, document.baseURI).href === img.src;
+            }
+            catch (_c) {
+                return img.currentSrc === img.src;
+            }
+        }
+        return true;
+    }
+    imageRatio() {
+        var _a;
+        const ratios = {
+            square: '1 / 1',
+            landscape: '4 / 3',
+            wide: '16 / 9',
+            portrait: '3 / 4',
+            tall: '9 / 16',
+        };
+        return (_a = ratios[this.ratio]) !== null && _a !== void 0 ? _a : this.ratio;
     }
     render() {
-        return (h(Host, { key: '6d2d48c468c39f53d67e63999dd83f3ad61053b5', class: {
+        // `!= null`, not `!== undefined`: removing the attribute sets the prop to `null`, not `undefined`.
+        const hasRatio = this.ratio != null && this.ratio !== '';
+        // `fit` only means something once a ratio gives the image a shape to
+        // overflow, so neither is applied until `ratio` is set.
+        const ratioStyle = hasRatio
+            ? { aspectRatio: this.imageRatio(), objectFit: this.fit }
+            : undefined;
+        return (h(Host, { key: 'cbc53c10c1ace7c37e3210f2a9f94043d6cd6e0c', class: {
                 'pds-image': true,
-            }, id: this.componentId }, h("img", { key: '393cc584586e37e8d5b602fbdcda1783bf80cf9b', alt: this.alt, height: this.height, loading: this.loading, sizes: this.sizes, src: this.src, srcset: this.srcset, width: this.width })));
+                'pds-image--has-ratio': hasRatio,
+            }, id: this.componentId }, h("img", { key: '139dbcebc7a71aa237deb8e2d7281abd40488096', alt: this.alt, height: this.height, loading: this.loading, sizes: this.sizes, src: this.src, srcset: this.srcset, style: ratioStyle, width: this.width, onLoad: this.emitLoad, onError: this.emitError, ref: (el) => (this.imageEl = el) })));
     }
     static get is() { return "pds-image"; }
     static get encapsulation() { return "shadow"; }
@@ -48,7 +180,7 @@ export class PdsImage {
                             "name": "defaultValue",
                             "text": "''"
                         }],
-                    "text": "The image's alt tag. If none is provided,\nit will default to an empty string, which is desired for\ndecorative images."
+                    "text": "The image's alt text. Defaults to an empty string, which marks the image\nas decorative and hides it from screen readers, so set it on any image\nthat carries information."
                 },
                 "getter": false,
                 "setter": false,
@@ -75,6 +207,29 @@ export class PdsImage {
                 "reflect": false,
                 "attribute": "component-id"
             },
+            "fit": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'contain' | 'cover' | 'fill' | 'none' | 'scale-down'",
+                    "resolved": "\"contain\" | \"cover\" | \"fill\" | \"none\" | \"scale-down\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "cover"
+                        }],
+                    "text": "Determines how the image fills the shape set by `ratio`.\nHas no effect if `ratio` is not set."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "fit",
+                "defaultValue": "'cover'"
+            },
             "height": {
                 "type": "number",
                 "mutable": false,
@@ -87,7 +242,7 @@ export class PdsImage {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "The height of the image in pixels. Setting this will\ndevote space in the layout to prevent layout\nshifts when the image is loaded."
+                    "text": "The height of the image in pixels. `height: auto` lets the loaded image's own\nproportions decide its rendered height, so unlike `width` this does not reserve\nspace before the image loads."
                 },
                 "getter": false,
                 "setter": false,
@@ -117,6 +272,36 @@ export class PdsImage {
                 "attribute": "loading",
                 "defaultValue": "'eager'"
             },
+            "ratio": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ImageRatioType | (string & Record<never, never>)",
+                    "resolved": "\"landscape\" | \"portrait\" | \"square\" | \"tall\" | \"wide\" | string & Record<never, never>",
+                    "references": {
+                        "ImageRatioType": {
+                            "location": "import",
+                            "path": "@utils/types",
+                            "id": "src/utils/types.ts::ImageRatioType",
+                            "referenceLocation": "ImageRatioType"
+                        },
+                        "Record": {
+                            "location": "global",
+                            "id": "global::Record"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "The aspect ratio the image is sized to, cropping whatever overflows the shape. A preset\n(`square` 1/1, `landscape` 4/3, `wide` 16/9, `portrait` 3/4, `tall` 9/16) or any custom\nCSS ratio, such as `21 / 9`. Use this, not `height` and `width`, to crop: those only\nreserve space, and only `width` reliably does even that."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "ratio"
+            },
             "sizes": {
                 "type": "string",
                 "mutable": false,
@@ -186,7 +371,7 @@ export class PdsImage {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "The width of the image in pixels. Setting this will\ndevote space in the layout to prevent layout\nshifts when the image is loaded."
+                    "text": "The width of the image in pixels. This reserves the image's width before it\nloads, but not its height: to reserve the height too, set\n`--dimension-aspect-ratio` to the image's own proportions."
                 },
                 "getter": false,
                 "setter": false,
@@ -195,4 +380,60 @@ export class PdsImage {
             }
         };
     }
+    static get events() {
+        return [{
+                "method": "pdsImageLoad",
+                "name": "pdsImageLoad",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when the image loads. Also emitted on first render for an image that\nfinished loading before the component could listen, such as a server-rendered\nimage. Emitted again after `src` or `srcset` changes and the new image loads, or\nwhen the browser picks a different `srcset` candidate, such as on a resize. Bubbles\nand is composed, so a listener on an ancestor gets every `pds-image`'s events \u2014\ncheck `event.target` when more than one is in scope."
+                },
+                "complexType": {
+                    "original": "ImageLoadEventDetail",
+                    "resolved": "ImageLoadEventDetail",
+                    "references": {
+                        "ImageLoadEventDetail": {
+                            "location": "import",
+                            "path": "./image-interface",
+                            "id": "src/components/pds-image/image-interface.ts::ImageLoadEventDetail",
+                            "referenceLocation": "ImageLoadEventDetail"
+                        }
+                    }
+                }
+            }, {
+                "method": "pdsImageError",
+                "name": "pdsImageError",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when the image fails to load, such as for a broken or empty `src`. An image\nwith no `src` or `srcset` at all emits neither event, since it has nothing to load.\nEmitted again after `src` or `srcset` changes and the new image fails. Bubbles and is\ncomposed, so a listener on an ancestor gets every `pds-image`'s events \u2014 check\n`event.target` when more than one is in scope."
+                },
+                "complexType": {
+                    "original": "ImageErrorEventDetail",
+                    "resolved": "ImageErrorEventDetail",
+                    "references": {
+                        "ImageErrorEventDetail": {
+                            "location": "import",
+                            "path": "./image-interface",
+                            "id": "src/components/pds-image/image-interface.ts::ImageErrorEventDetail",
+                            "referenceLocation": "ImageErrorEventDetail"
+                        }
+                    }
+                }
+            }];
+    }
+    static get watchers() {
+        return [{
+                "propName": "src",
+                "methodName": "handleSourceChange"
+            }, {
+                "propName": "srcset",
+                "methodName": "handleSourceChange"
+            }];
+    }
 }

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

@@ -7,9 +7,11 @@ export default {
 
 const BaseTemplate = (args) => html` <pds-image
   alt="${args.alt}"
+  fit="${args.fit}"
   height="${args.height}"
   component-id="${args.componentId}"
   ?loading=${args.loading}
+  ratio="${args.ratio}"
   sizes="${args.sizes}"
   src="${args.src}"
   srcset="${args.srcset}"
@@ -18,6 +20,98 @@ const BaseTemplate = (args) => html` <pds-image
 
 const SizesAndSrcsetTemplate = (args) => html`<pds-image alt="${args.alt}" sizes="${args.sizes}" src="${args.src}" srcset="${args.srcset}" />`;
 
+const RatioTemplate = (args) => html`<div style="width: 320px">
+  <pds-image alt="${args.alt}" fit="${args.fit}" ratio="${args.ratio}" src="${args.src}" />
+</div>`;
+
+// The source is portrait while every shape below is not, so each one shows what
+// the component does with the overflow.
+const FitTemplate = (args) => html`<div style="display: flex; gap: 1rem;">
+  ${['cover', 'contain', 'fill'].map(
+    (fit) => html`<figure style="margin: 0; width: 160px;">
+      <pds-image alt="${args.alt}" fit="${fit}" ratio="${args.ratio}" src="${args.src}"></pds-image>
+      <figcaption><code>fit="${fit}"</code></figcaption>
+    </figure>`,
+  )}
+</div>`;
+
+// Each frame covers its image with a placeholder until `pdsImageLoad` removes it, or shows
+// an error message on `pdsImageError`. The placeholder sits over the image rather than
+// hiding it, since a hidden image with `loading="lazy"` never loads. The loading placeholder
+// is hidden from screen readers, which already announce the image's alt. The error message's
+// `role="status"` region stays rendered the whole time, faded out by opacity rather than
+// `hidden`, so only its text changes when the error arrives — a region that goes from hidden
+// to visible with its text already set often isn't announced.
+const showState = (event, state) => {
+  const frame = event.target.closest('[data-image-frame]');
+  const error = frame.querySelector('[data-image-error]');
+  frame.querySelector('[data-image-placeholder]').hidden = state !== 'loading';
+  error.style.opacity = state === 'error' ? '1' : '0';
+  error.querySelector('pds-text').textContent = state === 'error' ? "This image couldn't load" : '';
+};
+
+const overlayStyle = 'position: absolute; inset: 0;';
+
+const EventsTemplate = (args) => {
+  // Reloading changes `src`, which emits the events again for the new image.
+  const reload = (event) => {
+    event.target.closest('[data-image-events]').querySelectorAll('[data-image-frame]').forEach((frame) => {
+      const image = frame.querySelector('pds-image');
+      const url = new URL(image.getAttribute('src'), window.location.href);
+      url.searchParams.set('reload', Date.now());
+      frame.querySelector('[data-image-placeholder]').hidden = false;
+      frame.querySelector('[data-image-error]').style.opacity = '0';
+      frame.querySelector('[data-image-error] pds-text').textContent = '';
+      image.setAttribute('src', url.href);
+    });
+  };
+
+  return html`<pds-box data-image-events direction="column" gap="md">
+    <pds-box gap="md" wrap>
+      ${[
+        { label: 'Loads', src: args.src },
+        { label: 'Fails to load', src: args.brokenSrc },
+      ].map(
+        ({ label, src }) => html`<div data-image-frame style="width: 240px;">
+          <div style="position: relative;">
+            <pds-image
+              alt="${args.alt}"
+              ratio="landscape"
+              src="${src}"
+              @pdsImageLoad=${(event) => showState(event, 'loaded')}
+              @pdsImageError=${(event) => showState(event, 'error')}
+            ></pds-image>
+            <pds-box
+              data-image-placeholder
+              aria-hidden="true"
+              align-items="center"
+              background-color="var(--pine-color-background-muted)"
+              justify-content="center"
+              style="${overlayStyle}"
+            >
+              <pds-text color="secondary" size="sm">Loading image…</pds-text>
+            </pds-box>
+            <pds-box
+              data-image-error
+              role="status"
+              align-items="center"
+              background-color="var(--pine-color-background-inset)"
+              justify-content="center"
+              style="${overlayStyle} opacity: 0; pointer-events: none;"
+            >
+              <pds-text color="secondary" size="sm"></pds-text>
+            </pds-box>
+          </div>
+          <pds-text size="sm">${label}</pds-text>
+        </div>`,
+      )}
+    </pds-box>
+    <div>
+      <pds-button variant="secondary" @pdsClick=${reload}>Reload images</pds-button>
+    </div>
+  </pds-box>`;
+};
+
 export const Default = BaseTemplate.bind();
 Default.args = {
   alt: 'Random Bear',
@@ -31,5 +125,27 @@ SizesAndSrcset.args = {
   alt: 'Random Bear',
   sizes: '(max-width: 450px) 150px, 600px',
   src: 'https://placebear.com/600/200',
-  srcset: 'https://placebear.com/150/150 400w, https://placebear.com/600/200',
+  srcset: 'https://placebear.com/150/50 150w, https://placebear.com/600/200 600w',
+}
+
+export const Ratio = RatioTemplate.bind();
+Ratio.args = {
+  alt: 'Random Bear',
+  fit: 'cover',
+  ratio: 'wide',
+  src: 'https://placebear.com/200/300',
+}
+
+export const Fit = FitTemplate.bind();
+Fit.args = {
+  alt: 'Random Bear',
+  ratio: 'wide',
+  src: 'https://placebear.com/200/300',
+}
+
+export const Events = EventsTemplate.bind();
+Events.args = {
+  alt: 'Random Bear',
+  brokenSrc: 'https://placebear.com/does-not-exist.png',
+  src: 'https://placebear.com/400/300',
 }

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

@@ -9,6 +9,11 @@ import { danger } from "@pine-ds/icons/icons";
  * @slot prepend - Content to be displayed before the input field
  * @slot suffix - Content that is displayed visually within the input field after the input field
  * @slot action - Content to be displayed in the label area, typically for help icons or links
+ * @part action - Exposes the wrapper around the `action` slot for styling. Appears only when the `action` slot has content.
+ * @part append - Exposes the wrapper around the `append` slot for styling. Appears only when the `append` slot has content.
+ * @part prefix - Exposes the wrapper around the `prefix` slot for styling. Appears only when the `prefix` slot has content.
+ * @part prepend - Exposes the wrapper around the `prepend` slot for styling. Appears only when the `prepend` slot has content.
+ * @part suffix - Exposes the wrapper around the `suffix` slot for styling. Appears only when the `suffix` slot has content.
  */
 export class PdsInput {
     constructor() {
@@ -37,7 +42,7 @@ export class PdsInput {
         this.hasAction = false;
         /**
          * Determines the type of control that will be displayed
-         * `'email'`, `'number'`, `'password'`, `'tel'`, `'text'`, `'url'`
+         * `'email'`, `'number'`, `'password'`, `'search'`, `'tel'`, `'text'`, `'url'`
          * @defaultValue "text"
          */
         this.type = 'text';
@@ -289,10 +294,10 @@ export class PdsInput {
             'has-prepend': this.hasPrepend,
             'has-append': this.hasAppend,
         };
-        return (h(Host, { key: '1706e29a68d25a8bb83c36d6bddace04a448f6f5', "aria-disabled": this.disabled ? 'true' : null, "aria-readonly": this.readonly ? 'true' : null, "has-prefix": this.hasPrefix ? 'true' : null, "has-suffix": this.hasSuffix ? 'true' : null, "has-prepend": this.hasPrepend ? 'true' : null, "has-append": this.hasAppend ? 'true' : null, "has-action": this.hasAction && !this.hideLabel ? 'true' : null, "full-width": this.fullWidth ? 'true' : null }, h("div", { key: '1488b6ea995c4ffc4068757f566494c0ac073950', class: "pds-input" }, label && (h("div", { key: 'e2fe4e461e626648ec51882e92e02fea179e3e13', class: {
+        return (h(Host, { key: '12dd9f60e5b7401fdad3d81aacf174d1465dfdd6', "aria-disabled": this.disabled ? 'true' : null, "aria-readonly": this.readonly ? 'true' : null, "has-prefix": this.hasPrefix ? 'true' : null, "has-suffix": this.hasSuffix ? 'true' : null, "has-prepend": this.hasPrepend ? 'true' : null, "has-append": this.hasAppend ? 'true' : null, "has-action": this.hasAction && !this.hideLabel ? 'true' : null, "full-width": this.fullWidth ? 'true' : null }, h("div", { key: '5c8c1488cd9041333cf22e5ef36c367d8bddcc21', class: "pds-input" }, label && (h("div", { key: '2fd1d0a71714e11ff7675f3ab376c859b717122e', class: {
                 'pds-input__label-wrapper': true,
                 'visually-hidden': this.hideLabel,
-            } }, h("label", { key: 'c926a6fbb3130afdc6c86d509b92fb6650391c4b', htmlFor: componentId, class: "pds-input__label" }, h("span", { key: 'dbbaf9d0db49f949f69f1faf848e7c6193e32793' }, label, this.required && h("span", { key: '42e6325a0f5ee276ed92cf2eb71942c268c3d1aa', class: "pds-input__required-indicator" }, " *"))), !this.hideLabel && this.renderAction())), h("div", { key: '4715743733f2d7d3e4edf9ac4ab6d69ffde04d00', class: inputWrapperClasses }, this.renderPrepend(), this.renderPrefix(), h("input", Object.assign({ key: '438ac0fc6d497a8227c83e628d29d4633ffc208a', ref: (input) => (this.nativeInput = input), class: "pds-input__field", "aria-describedby": assignDescription(componentId, invalid, helperMessage, errorMessage), "aria-invalid": invalid ? "true" : undefined, autocomplete: this.autocomplete, disabled: disabled, id: componentId, max: this.max, maxlength: this.maxlength, min: this.min, minlength: this.minlength, name: this.name, pattern: this.pattern, placeholder: this.placeholder, readOnly: this.readonly, required: this.required, step: this.step, type: this.type, value: value, onInput: this.onInputEvent, onChange: this.onChangeEvent, onBlur: this.onBlurEvent, onFocus: this.onFocusEvent, onKeyDown: this.onKeyDownEvent, onCompositionstart: this.onCompositionStart, onCompositionend: this.onCompositionEnd }, this.inheritedAttributes)), this.renderSuffix(), this.renderAppend()), helperMessage && (h("p", { key: '43b5c3a332072f19a38be316565602932c61504d', class: "pds-input__helper-message", id: messageId(componentId, 'helper') }, helperMessage)), errorMessage && (h("p", { key: '54fd4fc2dcbc645377edbe4d04cfd82c7d1591e8', class: "pds-input__error-message", id: messageId(componentId, 'error') }, h("pds-icon", { key: '2bd509a575ec5c7a548955dd7f706d7c1d42557e', "aria-hidden": "true", icon: danger, size: "small" }), errorMessage)))));
+            } }, h("label", { key: '82623092a61b5158daa39937a8c8e01081cb6fa3', htmlFor: componentId, class: "pds-input__label" }, h("span", { key: '10a973c6191458f1133c34ccfdfd5342d330829d' }, label, this.required && h("span", { key: '413deb83a0c8b7f0ab0e5648a7bde19166477a1c', class: "pds-input__required-indicator" }, " *"))), !this.hideLabel && this.renderAction())), h("div", { key: 'c90ff99e08ab480453015fa293d38077204ea07c', class: inputWrapperClasses }, this.renderPrepend(), this.renderPrefix(), h("input", Object.assign({ key: 'd558ffc9369bd19c454f88c48acde45a4a992122', ref: (input) => (this.nativeInput = input), class: "pds-input__field", "aria-describedby": assignDescription(componentId, invalid, helperMessage, errorMessage), "aria-invalid": invalid ? "true" : undefined, autocomplete: this.autocomplete, disabled: disabled, id: componentId, max: this.max, maxlength: this.maxlength, min: this.min, minlength: this.minlength, name: this.name, pattern: this.pattern, placeholder: this.placeholder, readOnly: this.readonly, required: this.required, step: this.step, type: this.type, value: value, onInput: this.onInputEvent, onChange: this.onChangeEvent, onBlur: this.onBlurEvent, onFocus: this.onFocusEvent, onKeyDown: this.onKeyDownEvent, onCompositionstart: this.onCompositionStart, onCompositionend: this.onCompositionEnd }, this.inheritedAttributes)), this.renderSuffix(), this.renderAppend()), helperMessage && (h("p", { key: '747fd78b735924efb0a0e074ef20eac011c8887b', class: "pds-input__helper-message", id: messageId(componentId, 'helper') }, helperMessage)), errorMessage && (h("p", { key: '1a1ce87923e24bd70fc85f410c1eb3e69f16171f', class: "pds-input__error-message", id: messageId(componentId, 'error') }, h("pds-icon", { key: 'be6bb7c6e24b379afd7cd6977b5555f680b41f6b', "aria-hidden": "true", icon: danger, size: "small" }), errorMessage)))));
     }
     static get is() { return "pds-input"; }
     static get encapsulation() { return "shadow"; }
@@ -359,7 +364,7 @@ export class PdsInput {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "Sets the number of milliseconds to wait before updating the value."
+                    "text": "Sets the number of milliseconds to wait after each input event before emitting `pdsInput`."
                 },
                 "getter": false,
                 "setter": false,
@@ -397,7 +402,7 @@ export class PdsInput {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "Specifies the error message and provides an error-themed treatment to the field."
+                    "text": "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."
                 },
                 "getter": false,
                 "setter": false,
@@ -435,7 +440,7 @@ export class PdsInput {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "Determines whether or not the input field is invalid or throws an error."
+                    "text": "Determines whether or not the input is invalid."
                 },
                 "getter": false,
                 "setter": false,
@@ -685,7 +690,7 @@ export class PdsInput {
                             "name": "defaultValue",
                             "text": "\"text\""
                         }],
-                    "text": "Determines the type of control that will be displayed\n`'email'`, `'number'`, `'password'`, `'tel'`, `'text'`, `'url'`"
+                    "text": "Determines the type of control that will be displayed\n`'email'`, `'number'`, `'password'`, `'search'`, `'tel'`, `'text'`, `'url'`"
                 },
                 "getter": false,
                 "setter": false,
@@ -792,7 +797,7 @@ export class PdsInput {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": "Emitted when the value has changed.\n\nThis event will not emit when programmatically setting the `value` property."
+                    "text": "Emitted when the user changes the value and then presses `Enter` or leaves the field.\n`detail` has `value`, as a string, and `event`, the native event behind it, usually `change`.\n\nThis event will not emit when programmatically setting the `value` property, unless the field has focus at the time;\nthen it emits when the field loses focus."
                 },
                 "complexType": {
                     "original": "InputChangeEventDetail",
@@ -834,7 +839,7 @@ export class PdsInput {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": "Emitted when a keyboard input occurs."
+                    "text": "Emitted after each `input` event, such as typing or pasting. With `debounce`, it waits until that many milliseconds have passed since the last one.\n`detail` has `value`, the current value as a string, and `event`, the native `input` event.\n\nThis event will not emit when programmatically setting the `value` property."
                 },
                 "complexType": {
                     "original": "InputInputEventDetail",