@justeattakeaway/pie-select 0.1.0 → 0.3.0

package/custom-elements.json

@@ -34,7 +34,7 @@
           "type": {
             "text": "DefaultProps"
           },
-          "default": "{\n    size: 'medium',\n    status: 'default',\n    disabled: false,\n}"
+          "default": "{\n    size: 'medium',\n    status: 'default',\n    disabled: false,\n    options: [],\n}"
         }
       ],
       "exports": [
@@ -118,14 +118,31 @@
               "privacy": "public",
               "attribute": "name"
             },
+            {
+              "kind": "field",
+              "name": "options",
+              "type": {
+                "text": "SelectProps['options']"
+              },
+              "privacy": "public",
+              "attribute": "options"
+            },
             {
               "kind": "field",
               "name": "focusTarget",
               "type": {
-                "text": "HTMLElement"
+                "text": "HTMLSelectElement"
               },
               "privacy": "public"
             },
+            {
+              "kind": "field",
+              "name": "_select",
+              "type": {
+                "text": "HTMLSelectElement"
+              },
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "_leadingIconSlot",
@@ -143,15 +160,103 @@
               "privacy": "private",
               "default": "false"
             },
+            {
+              "kind": "field",
+              "name": "validity",
+              "type": {
+                "text": "ValidityState"
+              },
+              "privacy": "public",
+              "description": "(Read-only) returns a ValidityState with the validity states that this element is in.\nhttps://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validity",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "formDisabledCallback",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "disabled",
+                  "type": {
+                    "text": "boolean"
+                  },
+                  "description": "The latest disabled state of the select."
+                }
+              ],
+              "description": "Called after the disabled state of the element changes,\neither because the disabled attribute of this element was added or removed;\nor because the disabled state changed on a <fieldset> that's an ancestor of this element."
+            },
+            {
+              "kind": "method",
+              "name": "formResetCallback",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Called when the form that owns this component is reset.\nResets the value to the default select value."
+            },
+            {
+              "kind": "field",
+              "name": "_handleChange",
+              "privacy": "private",
+              "description": "Captures the native change event and wraps it in a custom event.",
+              "parameters": [
+                {
+                  "description": "The change event.",
+                  "name": "event"
+                }
+              ]
+            },
             {
               "kind": "method",
               "name": "_handleLeadingIconSlotchange",
               "privacy": "private"
             },
+            {
+              "kind": "method",
+              "name": "renderChildren",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": ""
+                }
+              },
+              "parameters": [
+                {
+                  "name": "options",
+                  "type": {
+                    "text": "SelectProps['options']"
+                  },
+                  "description": "The options to render"
+                }
+              ],
+              "description": "Renders the options from the options property"
+            },
             {
               "kind": "method",
               "name": "renderAssistiveText",
-              "privacy": "private"
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": ""
+                }
+              },
+              "description": "Renders the assistive text if available."
+            }
+          ],
+          "events": [
+            {
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "when the selected option is changed.",
+              "name": "change"
             }
           ],
           "attributes": [
@@ -180,9 +285,20 @@
                 "text": "SelectProps['name']"
               },
               "fieldName": "name"
+            },
+            {
+              "name": "options",
+              "type": {
+                "text": "SelectProps['options']"
+              },
+              "fieldName": "options"
             }
           ],
           "mixins": [
+            {
+              "name": "FormControlMixin",
+              "package": "@justeattakeaway/pie-webc-core"
+            },
             {
               "name": "RtlMixin",
               "package": "@justeattakeaway/pie-webc-core"

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
 import type { CSSResult } from 'lit';
+import type { FormControlInterface } from '@justeattakeaway/pie-webc-core';
 import type { GenericConstructor } from '@justeattakeaway/pie-webc-core';
 import type { LitElement } from 'lit';
 import type { RTLInterface } from '@justeattakeaway/pie-webc-core';
-import type { TemplateResult } from 'lit-html';
+import type { TemplateResult } from 'lit';
 
 declare type DefaultProps = ComponentDefaultProps<SelectProps, keyof Omit<SelectProps, 'name' | 'assistiveText'>>;
 
@@ -11,6 +12,7 @@ export declare const defaultProps: DefaultProps;
 
 /**
  * @tagname pie-select
+ * @event {CustomEvent} change - when the selected option is changed.
  */
 export declare class PieSelect extends PieSelect_base implements SelectProps {
     static shadowRootOptions: {
@@ -23,16 +25,93 @@ export declare class PieSelect extends PieSelect_base implements SelectProps {
     status: "default" | "error";
     assistiveText: SelectProps['assistiveText'];
     name: SelectProps['name'];
-    focusTarget: HTMLElement;
+    options: SelectProps['options'];
+    focusTarget: HTMLSelectElement;
+    private _select;
     private _leadingIconSlot;
     private _hasLeadingIcon;
+    protected firstUpdated(): void;
+    /**
+     * (Read-only) returns a ValidityState with the validity states that this element is in.
+     * https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validity
+     */
+    get validity(): ValidityState;
+    /**
+     * Called after the disabled state of the element changes,
+     * either because the disabled attribute of this element was added or removed;
+     * or because the disabled state changed on a <fieldset> that's an ancestor of this element.
+     * @param disabled - The latest disabled state of the select.
+     */
+    formDisabledCallback(disabled: boolean): void;
+    /**
+     * Called when the form that owns this component is reset.
+     * Resets the value to the default select value.
+     */
+    formResetCallback(): void;
+    /**
+     * Captures the native change event and wraps it in a custom event.
+     * @param event - The change event.
+     */
+    private _handleChange;
     private _handleLeadingIconSlotchange;
+    /**
+     * Renders the options from the options property
+     * @param options - The options to render
+     * @returns A template result with the rendered options
+     */
+    private renderChildren;
+    /**
+     * Renders the assistive text if available.
+     * @returns A template result with the assistive text
+     */
     private renderAssistiveText;
     render(): TemplateResult<1>;
     static styles: CSSResult;
 }
 
-declare const PieSelect_base: GenericConstructor<RTLInterface> & typeof LitElement;
+declare const PieSelect_base: GenericConstructor<FormControlInterface> & GenericConstructor<RTLInterface> & typeof LitElement;
+
+declare interface SelectOptionGroupProps {
+    /**
+     * What HTML element the option should be such option or optgroup.
+     */
+    tag: 'optgroup';
+    /**
+     * The label for the select option group.
+     */
+    label?: string;
+    /**
+     * The options within the select option group.
+     */
+    options: SelectOptionProps[];
+    /**
+     * Same as the HTML disabled attribute - indicates whether the select option group is disabled.
+     */
+    disabled?: boolean;
+}
+
+declare interface SelectOptionProps {
+    /**
+     * What HTML element the option should be such option or optgroup.
+     */
+    tag: 'option';
+    /**
+     * The text content to display for the select option.
+     */
+    text: string;
+    /**
+     * The value of the select option (used as a key/value pair in HTML forms with `name`).
+     */
+    value?: string;
+    /**
+     * Same as the HTML disabled attribute - indicates whether the select option is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Same as the HTML selected attribute - indicates whether the select option is selected by default when the page first loads.
+     */
+    selected?: boolean;
+}
 
 export declare interface SelectProps {
     /**
@@ -44,7 +123,7 @@ export declare interface SelectProps {
      */
     disabled?: boolean;
     /**
-     * An optional assistive text to display below the select element. Must be provided when the status is success or error.
+     * An optional assistive text to display below the select element. Must be provided when the status is error.
      */
     assistiveText?: string;
     /**
@@ -55,6 +134,10 @@ export declare interface SelectProps {
      * The name of the select (used as a key/value pair with `value`). This is required in order to work properly with forms.
      */
     name?: string;
+    /**
+     * The options to display in the select. Can be an array of option objects or option group objects.
+     */
+    options: (SelectOptionProps | SelectOptionGroupProps)[];
 }
 
 export declare const sizes: readonly ["small", "medium", "large"];

package/dist/index.js

@@ -1,104 +1,171 @@
-import { LitElement as u, nothing as x, html as b, unsafeCSS as y } from "lit";
-import { RtlMixin as I, validPropertyValues as f, defineCustomElement as k } from "@justeattakeaway/pie-webc-core";
-import { property as c, query as z, queryAssignedElements as $, state as w } from "lit/decorators.js";
-import { ifDefined as d } from "lit/directives/if-defined.js";
-import { classMap as _ } from "lit/directives/class-map.js";
+import { LitElement as b, html as c, nothing as _, unsafeCSS as $ } from "lit";
+import { FormControlMixin as I, RtlMixin as k, wrapNativeEvent as z, validPropertyValues as f, defineCustomElement as w } from "@justeattakeaway/pie-webc-core";
+import { property as l, query as m, queryAssignedElements as C, state as L } from "lit/decorators.js";
+import { ifDefined as n } from "lit/directives/if-defined.js";
+import { classMap as S } from "lit/directives/class-map.js";
+import { live as T } from "lit/directives/live.js";
 import "@justeattakeaway/pie-icons-webc/dist/IconChevronDown.js";
-const L = "*,*:after,*:before{box-sizing:inherit}.c-select{--select-padding-block: var(--dt-spacing-c);--select-padding-inline-start: var(--dt-spacing-d);--select-padding-inline-end: var(--dt-spacing-h);--select-background-color: var(--dt-color-container-default);--select-text-color: var(--dt-color-content-default);--select-border-color: var(--dt-color-border-form);--select-font-size: calc(var(--dt-font-body-l-size) * 1px);--select-line-height: calc(var(--dt-font-body-l-line-height) * 1px);--select-height: 48px;--select-cursor: pointer;position:relative;color:var(--select-text-color);font-size:var(--select-font-size);line-height:var(--select-line-height)}.c-select select{height:var(--select-height);width:100%;border:1px solid var(--select-border-color);border-radius:var(--dt-radius-rounded-c);padding-inline-start:var(--select-padding-inline-start);padding-inline-end:var(--select-padding-inline-end);padding-block-start:var(--select-padding-block);padding-block-end:var(--select-padding-block);background-color:var(--select-background-color);font-size:inherit;line-height:inherit;color:inherit;outline:0;-webkit-appearance:none;-moz-appearance:none;appearance:none;cursor:var(--select-cursor)}.c-select select:focus-within{box-shadow:0 0 0 2px var(--dt-color-focus-inner),0 0 0 4px var(--dt-color-focus-outer);outline:none}.c-select.c-select--small{--select-padding-block: var(--dt-spacing-b);--select-height: 40px}.c-select.c-select--large{--select-padding-block: var(--dt-spacing-d);--select-height: 56px}.c-select.c-select--error{--select-border-color: var(--dt-color-support-error)}.c-select.c-select--withLeadingIcon{--select-padding-inline-start: calc(var(--dt-spacing-h) - var(--dt-spacing-a))}.c-select ::slotted([slot=leadingIcon]),.c-select .c-select-trailingIcon{position:absolute;top:50%;transform:translateY(-50%);pointer-events:none}.c-select:not(.is-disabled) ::slotted([slot=leadingIcon]),.c-select:not(.is-disabled) .c-select-trailingIcon{color:var(--dt-color-content-subdued)}.c-select ::slotted([slot=leadingIcon]){--icon-display-override: block;--icon-size-override: 24px;inset-inline-start:var(--dt-spacing-d)}.c-select .c-select-trailingIcon{inset-inline-end:var(--dt-spacing-d)}@media (hover: hover){.c-select:hover{--select-background-color: hsl(var(--dt-color-container-default-h), var(--dt-color-container-default-s), calc(var(--dt-color-container-default-l) + calc(-1 * var(--dt-color-hover-01))))}@supports (background-color: color-mix(in srgb,black,white)){.c-select:hover{--select-background-color: color-mix(in srgb, var(--dt-color-hover-01-bg) var(--dt-color-hover-01), var(--dt-color-container-default))}}}.c-select.is-disabled{--select-background-color: var(--dt-color-disabled-01);--select-border-color: var(--dt-color-disabled-01);--select-text-color: var(--dt-color-content-disabled);--select-cursor: auto}", T = ["small", "medium", "large"], S = ["default", "error"], i = {
+import "@justeattakeaway/pie-assistive-text";
+const E = "*,*:after,*:before{box-sizing:inherit}.c-select{--select-padding-block: var(--dt-spacing-c);--select-padding-inline-start: var(--dt-spacing-d);--select-padding-inline-end: var(--dt-spacing-h);--select-background-color: var(--dt-color-container-default);--select-text-color: var(--dt-color-content-default);--select-border-color: var(--dt-color-border-form);--select-font-size: calc(var(--dt-font-body-l-size) * 1px);--select-line-height: calc(var(--dt-font-body-l-line-height) * 1px);--select-height: 48px;--select-cursor: pointer;position:relative;color:var(--select-text-color);font-size:var(--select-font-size);line-height:var(--select-line-height)}.c-select select{height:var(--select-height);width:100%;border:1px solid var(--select-border-color);border-radius:var(--dt-radius-rounded-c);padding-inline-start:var(--select-padding-inline-start);padding-inline-end:var(--select-padding-inline-end);padding-block-start:var(--select-padding-block);padding-block-end:var(--select-padding-block);background-color:var(--select-background-color);font-size:inherit;line-height:inherit;color:inherit;outline:0;-webkit-appearance:none;-moz-appearance:none;appearance:none;cursor:var(--select-cursor)}.c-select select:focus-within{box-shadow:0 0 0 2px var(--dt-color-focus-inner),0 0 0 4px var(--dt-color-focus-outer);outline:none}.c-select.c-select--small{--select-padding-block: var(--dt-spacing-b);--select-height: 40px}.c-select.c-select--large{--select-padding-block: var(--dt-spacing-d);--select-height: 56px}.c-select.c-select--error{--select-border-color: var(--dt-color-support-error)}.c-select.c-select--withLeadingIcon{--select-padding-inline-start: calc(var(--dt-spacing-h) - var(--dt-spacing-a))}.c-select ::slotted([slot=leadingIcon]),.c-select .c-select-trailingIcon{position:absolute;top:50%;transform:translateY(-50%);pointer-events:none}.c-select:not(.is-disabled) ::slotted([slot=leadingIcon]),.c-select:not(.is-disabled) .c-select-trailingIcon{color:var(--dt-color-content-subdued)}.c-select ::slotted([slot=leadingIcon]){--icon-display-override: block;--icon-size-override: 24px;inset-inline-start:var(--dt-spacing-d)}.c-select .c-select-trailingIcon{inset-inline-end:var(--dt-spacing-d)}@media (hover: hover){.c-select:hover{--select-background-color: hsl(var(--dt-color-container-default-h), var(--dt-color-container-default-s), calc(var(--dt-color-container-default-l) + calc(-1 * var(--dt-color-hover-01))))}@supports (background-color: color-mix(in srgb,black,white)){.c-select:hover{--select-background-color: color-mix(in srgb, var(--dt-color-hover-01-bg) var(--dt-color-hover-01), var(--dt-color-container-default))}}}.c-select.is-disabled{--select-background-color: var(--dt-color-disabled-01);--select-border-color: var(--dt-color-disabled-01);--select-text-color: var(--dt-color-content-disabled);--select-cursor: auto}", A = ["small", "medium", "large"], F = ["default", "error"], r = {
   size: "medium",
   status: "default",
-  disabled: !1
+  disabled: !1,
+  options: []
 };
-var C = Object.defineProperty, s = (h, a, o, n) => {
-  for (var t = void 0, r = h.length - 1, l; r >= 0; r--)
-    (l = h[r]) && (t = l(a, o, t) || t);
-  return t && C(a, o, t), t;
+var V = Object.defineProperty, o = (v, t, e, d) => {
+  for (var i = void 0, a = v.length - 1, p; a >= 0; a--)
+    (p = v[a]) && (i = p(t, e, i) || i);
+  return i && V(t, e, i), i;
 };
-const v = "pie-select", g = "assistive-text", p = class p extends I(u) {
+const g = "pie-select", u = "assistive-text", h = class h extends I(k(b)) {
   constructor() {
-    super(...arguments), this.size = i.size, this.disabled = i.disabled, this.status = i.status, this._hasLeadingIcon = !1;
+    super(...arguments), this.size = r.size, this.disabled = r.disabled, this.status = r.status, this.options = r.options, this._hasLeadingIcon = !1, this._handleChange = (t) => {
+      const e = z(t);
+      this.dispatchEvent(e), this._internals.setFormValue(this._select.value);
+    };
+  }
+  firstUpdated() {
+    this._internals.setFormValue(this._select.value);
+  }
+  /**
+   * (Read-only) returns a ValidityState with the validity states that this element is in.
+   * https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validity
+   */
+  get validity() {
+    return this._select.validity;
+  }
+  /**
+   * Called after the disabled state of the element changes,
+   * either because the disabled attribute of this element was added or removed;
+   * or because the disabled state changed on a <fieldset> that's an ancestor of this element.
+   * @param disabled - The latest disabled state of the select.
+   */
+  formDisabledCallback(t) {
+    this.disabled = t;
+  }
+  /**
+   * Called when the form that owns this component is reset.
+   * Resets the value to the default select value.
+   */
+  formResetCallback() {
+    const t = this._select.querySelector("option[selected]");
+    this._select.value = (t == null ? void 0 : t.getAttribute("value")) ?? "", this._select.selectedIndex = t ? this._select.selectedIndex : 0, this._internals.setFormValue(this._select.value);
   }
   _handleLeadingIconSlotchange() {
     this._hasLeadingIcon = !!this._leadingIconSlot.length;
   }
+  /**
+   * Renders the options from the options property
+   * @param options - The options to render
+   * @returns A template result with the rendered options
+   */
+  renderChildren(t) {
+    return c`
+            ${t.map((e) => e.tag === "optgroup" ? c`
+                        <optgroup
+                            ?disabled="${e.disabled}"
+                            label="${n(e.label)}">
+                            ${this.renderChildren(e.options)}
+                        </optgroup>
+                    ` : c`
+                    <option
+                        .value="${T(e.value)}"
+                        ?disabled="${e.disabled}"
+                        ?selected="${e.selected}">
+                        ${e.text}
+                    </option>
+                `)}
+        `;
+  }
+  /**
+   * Renders the assistive text if available.
+   * @returns A template result with the assistive text
+   */
   renderAssistiveText() {
-    return this.assistiveText ? b`
+    return this.assistiveText ? c`
             <pie-assistive-text
-                id="${g}"
-                variant=${d(this.status)}
-                data-test-id="pie-textarea-assistive-text">
+                id="${u}"
+                variant="${n(this.status)}"
+                data-test-id="pie-select-assistive-text">
                 ${this.assistiveText}
             </pie-assistive-text>
-        ` : x;
+        ` : _;
   }
   render() {
     const {
-      assistiveText: a,
-      disabled: o,
-      status: n,
-      size: t,
-      name: r,
-      _hasLeadingIcon: l
-    } = this, m = {
+      assistiveText: t,
+      disabled: e,
+      status: d,
+      size: i,
+      name: a,
+      options: p,
+      _hasLeadingIcon: x
+    } = this, y = {
       "c-select": !0,
-      [`c-select--${t}`]: !0,
-      [`c-select--${n}`]: !0,
-      "c-select--withLeadingIcon": l,
-      "is-disabled": o
+      [`c-select--${i}`]: !0,
+      [`c-select--${d}`]: !0,
+      "c-select--withLeadingIcon": x,
+      "is-disabled": e
     };
-    return b`
+    return c`
             <div
-                class="${_(m)}"
+                class="${S(y)}"
                 data-test-id="pie-select-shell">
-                    <slot name="leadingIcon" @slotchange=${this._handleLeadingIconSlotchange}></slot>
-                    <select
-                        name=${d(r)}
-                        ?disabled=${o}
-                        aria-describedby=${d(a ? g : void 0)}
-                        aria-invalid=${n === "error" ? "true" : "false"}
-                        aria-errormessage="${d(n === "error" ? g : void 0)}">
-                        <option value="dog">Dog</option>
-                        <option value="cat">Cat</option>
-                        <option value="hamster">Hamster</option>
-                    </select>
-                    <icon-chevron-down size='s' class='c-select-trailingIcon'></icon-chevron-down>
+                <slot name="leadingIcon" @slotchange=${this._handleLeadingIconSlotchange}></slot>
+                <select
+                    data-test-id="pie-select-element"
+                    name="${n(a)}"
+                    ?disabled="${e}"
+                    aria-describedby="${n(t ? u : void 0)}"
+                    aria-invalid="${d === "error" ? "true" : "false"}"
+                    aria-errormessage="${n(d === "error" ? u : void 0)}"
+                    @change=${this._handleChange}>
+                    ${this.renderChildren(p)}
+                </select>
+                <icon-chevron-down size='s' class='c-select-trailingIcon'></icon-chevron-down>
             </div>
             ${this.renderAssistiveText()}
         `;
   }
 };
-p.shadowRootOptions = { ...u.shadowRootOptions, delegatesFocus: !0 }, p.styles = y(L);
-let e = p;
-s([
-  c({ type: String }),
-  f(v, T, i.size)
-], e.prototype, "size");
-s([
-  c({ type: Boolean })
-], e.prototype, "disabled");
-s([
-  c({ type: String }),
-  f(v, S, i.status)
-], e.prototype, "status");
-s([
-  c({ type: String })
-], e.prototype, "assistiveText");
-s([
-  c({ type: String })
-], e.prototype, "name");
-s([
-  z("select")
-], e.prototype, "focusTarget");
-s([
-  $({ slot: "leadingIcon", flatten: !0 })
-], e.prototype, "_leadingIconSlot");
-s([
-  w()
-], e.prototype, "_hasLeadingIcon");
-k(v, e);
+h.shadowRootOptions = { ...b.shadowRootOptions, delegatesFocus: !0 }, h.styles = $(E);
+let s = h;
+o([
+  l({ type: String }),
+  f(g, A, r.size)
+], s.prototype, "size");
+o([
+  l({ type: Boolean })
+], s.prototype, "disabled");
+o([
+  l({ type: String }),
+  f(g, F, r.status)
+], s.prototype, "status");
+o([
+  l({ type: String })
+], s.prototype, "assistiveText");
+o([
+  l({ type: String })
+], s.prototype, "name");
+o([
+  l({ type: Array })
+], s.prototype, "options");
+o([
+  m("select")
+], s.prototype, "focusTarget");
+o([
+  m("select")
+], s.prototype, "_select");
+o([
+  C({ slot: "leadingIcon", flatten: !0 })
+], s.prototype, "_leadingIconSlot");
+o([
+  L()
+], s.prototype, "_hasLeadingIcon");
+w(g, s);
 export {
-  e as PieSelect,
-  i as defaultProps,
-  T as sizes,
-  S as statusTypes
+  s as PieSelect,
+  r as defaultProps,
+  A as sizes,
+  F as statusTypes
 };

package/dist/react.d.ts

@@ -1,19 +1,21 @@
 import { ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
 import type { CSSResult } from 'lit';
+import type { FormControlInterface } from '@justeattakeaway/pie-webc-core';
 import type { GenericConstructor } from '@justeattakeaway/pie-webc-core';
 import type { LitElement } from 'lit';
 import * as React_2 from 'react';
 import type { RTLInterface } from '@justeattakeaway/pie-webc-core';
-import type { TemplateResult } from 'lit-html';
+import type { TemplateResult } from 'lit';
 
 declare type DefaultProps = ComponentDefaultProps<SelectProps, keyof Omit<SelectProps, 'name' | 'assistiveText'>>;
 
 export declare const defaultProps: DefaultProps;
 
-export declare const PieSelect: React_2.ForwardRefExoticComponent<SelectProps & React_2.RefAttributes<PieSelect_2> & ReactBaseType>;
+export declare const PieSelect: React_2.ForwardRefExoticComponent<SelectProps & React_2.RefAttributes<PieSelect_2> & PieSelectEvents & ReactBaseType>;
 
 /**
  * @tagname pie-select
+ * @event {CustomEvent} change - when the selected option is changed.
  */
 declare class PieSelect_2 extends PieSelect_base implements SelectProps {
     static shadowRootOptions: {
@@ -26,19 +28,100 @@ declare class PieSelect_2 extends PieSelect_base implements SelectProps {
     status: "default" | "error";
     assistiveText: SelectProps['assistiveText'];
     name: SelectProps['name'];
-    focusTarget: HTMLElement;
+    options: SelectProps['options'];
+    focusTarget: HTMLSelectElement;
+    private _select;
     private _leadingIconSlot;
     private _hasLeadingIcon;
+    protected firstUpdated(): void;
+    /**
+     * (Read-only) returns a ValidityState with the validity states that this element is in.
+     * https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validity
+     */
+    get validity(): ValidityState;
+    /**
+     * Called after the disabled state of the element changes,
+     * either because the disabled attribute of this element was added or removed;
+     * or because the disabled state changed on a <fieldset> that's an ancestor of this element.
+     * @param disabled - The latest disabled state of the select.
+     */
+    formDisabledCallback(disabled: boolean): void;
+    /**
+     * Called when the form that owns this component is reset.
+     * Resets the value to the default select value.
+     */
+    formResetCallback(): void;
+    /**
+     * Captures the native change event and wraps it in a custom event.
+     * @param event - The change event.
+     */
+    private _handleChange;
     private _handleLeadingIconSlotchange;
+    /**
+     * Renders the options from the options property
+     * @param options - The options to render
+     * @returns A template result with the rendered options
+     */
+    private renderChildren;
+    /**
+     * Renders the assistive text if available.
+     * @returns A template result with the assistive text
+     */
     private renderAssistiveText;
     render(): TemplateResult<1>;
     static styles: CSSResult;
 }
 
-declare const PieSelect_base: GenericConstructor<RTLInterface> & typeof LitElement;
+declare const PieSelect_base: GenericConstructor<FormControlInterface> & GenericConstructor<RTLInterface> & typeof LitElement;
+
+declare type PieSelectEvents = {
+    onChange?: (event: CustomEvent) => void;
+};
 
 declare type ReactBaseType = React_2.HTMLAttributes<HTMLSelectElement>;
 
+declare interface SelectOptionGroupProps {
+    /**
+     * What HTML element the option should be such option or optgroup.
+     */
+    tag: 'optgroup';
+    /**
+     * The label for the select option group.
+     */
+    label?: string;
+    /**
+     * The options within the select option group.
+     */
+    options: SelectOptionProps[];
+    /**
+     * Same as the HTML disabled attribute - indicates whether the select option group is disabled.
+     */
+    disabled?: boolean;
+}
+
+declare interface SelectOptionProps {
+    /**
+     * What HTML element the option should be such option or optgroup.
+     */
+    tag: 'option';
+    /**
+     * The text content to display for the select option.
+     */
+    text: string;
+    /**
+     * The value of the select option (used as a key/value pair in HTML forms with `name`).
+     */
+    value?: string;
+    /**
+     * Same as the HTML disabled attribute - indicates whether the select option is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Same as the HTML selected attribute - indicates whether the select option is selected by default when the page first loads.
+     */
+    selected?: boolean;
+}
+
 export declare interface SelectProps {
     /**
      * The size of the select component. Can be `small`, `medium` or `large`. Defaults to `medium`.
@@ -49,7 +132,7 @@ export declare interface SelectProps {
      */
     disabled?: boolean;
     /**
-     * An optional assistive text to display below the select element. Must be provided when the status is success or error.
+     * An optional assistive text to display below the select element. Must be provided when the status is error.
      */
     assistiveText?: string;
     /**
@@ -60,6 +143,10 @@ export declare interface SelectProps {
      * The name of the select (used as a key/value pair with `value`). This is required in order to work properly with forms.
      */
     name?: string;
+    /**
+     * The options to display in the select. Can be an array of option objects or option group objects.
+     */
+    options: (SelectOptionProps | SelectOptionGroupProps)[];
 }
 
 export declare const sizes: readonly ["small", "medium", "large"];

package/dist/react.js

@@ -1,13 +1,16 @@
 import * as e from "react";
 import { createComponent as t } from "@lit/react";
-import { PieSelect as s } from "./index.js";
+import { PieSelect as a } from "./index.js";
 import { defaultProps as l, sizes as p, statusTypes as n } from "./index.js";
 const o = t({
   displayName: "PieSelect",
-  elementClass: s,
+  elementClass: a,
   react: e,
   tagName: "pie-select",
-  events: {}
+  events: {
+    onChange: "change"
+    // when the selected option is changed.
+  }
 }), r = o;
 export {
   r as PieSelect,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justeattakeaway/pie-select",
   "description": "PIE Design System Select built using Web Components",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -33,11 +33,12 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "0.9.0",
-    "@justeattakeaway/pie-components-config": "0.18.0",
+    "@justeattakeaway/pie-components-config": "0.18.1",
     "@justeattakeaway/pie-css": "0.16.0",
     "cem-plugin-module-file-extensions": "0.0.5"
   },
   "dependencies": {
+    "@justeattakeaway/pie-assistive-text": "0.8.5",
     "@justeattakeaway/pie-webc-core": "0.24.2"
   },
   "volta": {

package/src/defs.ts

@@ -4,6 +4,55 @@ export const sizes = ['small', 'medium', 'large'] as const;
 
 export const statusTypes = ['default', 'error'] as const;
 
+interface SelectOptionProps {
+   /**
+     * What HTML element the option should be such option or optgroup.
+     */
+    tag: 'option';
+
+    /**
+     * The text content to display for the select option.
+     */
+    text: string;
+
+    /**
+     * The value of the select option (used as a key/value pair in HTML forms with `name`).
+     */
+    value?: string;
+
+    /**
+     * Same as the HTML disabled attribute - indicates whether the select option is disabled.
+     */
+    disabled?: boolean;
+
+    /**
+     * Same as the HTML selected attribute - indicates whether the select option is selected by default when the page first loads.
+     */
+    selected?: boolean;
+}
+
+interface SelectOptionGroupProps {
+    /**
+     * What HTML element the option should be such option or optgroup.
+     */
+    tag: 'optgroup';
+
+    /**
+     * The label for the select option group.
+     */
+    label?: string;
+
+    /**
+     * The options within the select option group.
+     */
+    options: SelectOptionProps[];
+
+    /**
+     * Same as the HTML disabled attribute - indicates whether the select option group is disabled.
+     */
+    disabled?: boolean;
+}
+
 export interface SelectProps {
     /**
      * The size of the select component. Can be `small`, `medium` or `large`. Defaults to `medium`.
@@ -16,7 +65,7 @@ export interface SelectProps {
     disabled?: boolean;
 
     /**
-     * An optional assistive text to display below the select element. Must be provided when the status is success or error.
+     * An optional assistive text to display below the select element. Must be provided when the status is error.
      */
     assistiveText?: string;
 
@@ -29,12 +78,18 @@ export interface SelectProps {
      * The name of the select (used as a key/value pair with `value`). This is required in order to work properly with forms.
      */
     name?: string;
+
+    /**
+     * The options to display in the select. Can be an array of option objects or option group objects.
+     */
+    options: (SelectOptionProps | SelectOptionGroupProps)[];
 }
 
-type DefaultProps = ComponentDefaultProps<SelectProps, keyof Omit<SelectProps, 'name' | 'assistiveText' >>;
+type DefaultProps = ComponentDefaultProps<SelectProps, keyof Omit<SelectProps, 'name' | 'assistiveText'>>;
 
 export const defaultProps: DefaultProps = {
     size: 'medium',
     status: 'default',
     disabled: false,
+    options: [],
 };

package/src/index.ts

@@ -3,11 +3,14 @@ import {
     html,
     nothing,
     unsafeCSS,
+    type TemplateResult,
 } from 'lit';
 import {
+    FormControlMixin,
     RtlMixin,
     defineCustomElement,
     validPropertyValues,
+    wrapNativeEvent,
 } from '@justeattakeaway/pie-webc-core';
 import {
     property,
@@ -17,7 +20,9 @@ import {
 } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import { classMap, type ClassInfo } from 'lit/directives/class-map.js';
+import { live } from 'lit/directives/live.js';
 import '@justeattakeaway/pie-icons-webc/dist/IconChevronDown.js';
+import '@justeattakeaway/pie-assistive-text';
 
 import styles from './select.scss?inline';
 import {
@@ -35,8 +40,9 @@ const assistiveTextIdValue = 'assistive-text';
 
 /**
  * @tagname pie-select
+ * @event {CustomEvent} change - when the selected option is changed.
  */
-export class PieSelect extends RtlMixin(LitElement) implements SelectProps {
+export class PieSelect extends FormControlMixin(RtlMixin(LitElement)) implements SelectProps {
     static shadowRootOptions = { ...LitElement.shadowRootOptions, delegatesFocus: true };
 
     @property({ type: String })
@@ -56,8 +62,14 @@ export class PieSelect extends RtlMixin(LitElement) implements SelectProps {
     @property({ type: String })
     public name: SelectProps['name'];
 
+    @property({ type: Array })
+    public options: SelectProps['options'] = defaultProps.options;
+
+    @query('select')
+    public focusTarget!: HTMLSelectElement;
+
     @query('select')
-    public focusTarget!: HTMLElement;
+    private _select!: HTMLSelectElement;
 
     @queryAssignedElements({ slot: 'leadingIcon', flatten: true })
     private _leadingIconSlot!: Array<HTMLElement>;
@@ -65,11 +77,94 @@ export class PieSelect extends RtlMixin(LitElement) implements SelectProps {
     @state()
     private _hasLeadingIcon = false;
 
+    protected firstUpdated (): void {
+        this._internals.setFormValue(this._select.value);
+    }
+
+    /**
+     * (Read-only) returns a ValidityState with the validity states that this element is in.
+     * https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validity
+     */
+    public get validity (): ValidityState {
+        return this._select.validity;
+    }
+
+    /**
+     * Called after the disabled state of the element changes,
+     * either because the disabled attribute of this element was added or removed;
+     * or because the disabled state changed on a <fieldset> that's an ancestor of this element.
+     * @param disabled - The latest disabled state of the select.
+     */
+    public formDisabledCallback (disabled: boolean): void {
+        this.disabled = disabled;
+    }
+
+    /**
+     * Called when the form that owns this component is reset.
+     * Resets the value to the default select value.
+     */
+    public formResetCallback (): void {
+        const selected = this._select.querySelector('option[selected]');
+        this._select.value = selected?.getAttribute('value') ?? '';
+        this._select.selectedIndex = selected ? this._select.selectedIndex : 0;
+        this._internals.setFormValue(this._select.value);
+    }
+
+    /**
+     * Captures the native change event and wraps it in a custom event.
+     * @param event - The change event.
+     */
+    private _handleChange = (event: Event) => {
+        // We have to create our own change event because the native one
+        // does not penetrate the shadow boundary.
+
+        // This is because some events set `composed` to `false`.
+        // Reference: https://javascript.info/shadow-dom-events#event-composed
+        const customChangeEvent = wrapNativeEvent(event);
+        this.dispatchEvent(customChangeEvent);
+
+        this._internals.setFormValue(this._select.value);
+    };
+
     private _handleLeadingIconSlotchange () {
         this._hasLeadingIcon = Boolean(this._leadingIconSlot.length);
     }
 
-    private renderAssistiveText () {
+    /**
+     * Renders the options from the options property
+     * @param options - The options to render
+     * @returns A template result with the rendered options
+     */
+    private renderChildren (options: SelectProps['options']): TemplateResult {
+        return html`
+            ${options.map((option) => {
+            if (option.tag === 'optgroup') {
+                return html`
+                        <optgroup
+                            ?disabled="${option.disabled}"
+                            label="${ifDefined(option.label)}">
+                            ${this.renderChildren(option.options)}
+                        </optgroup>
+                    `;
+            }
+
+            return html`
+                    <option
+                        .value="${live(option.value)}"
+                        ?disabled="${option.disabled}"
+                        ?selected="${option.selected}">
+                        ${option.text}
+                    </option>
+                `;
+        })}
+        `;
+    }
+
+    /**
+     * Renders the assistive text if available.
+     * @returns A template result with the assistive text
+     */
+    private renderAssistiveText (): TemplateResult | typeof nothing {
         if (!this.assistiveText) {
             return nothing;
         }
@@ -77,8 +172,8 @@ export class PieSelect extends RtlMixin(LitElement) implements SelectProps {
         return html`
             <pie-assistive-text
                 id="${assistiveTextIdValue}"
-                variant=${ifDefined(this.status)}
-                data-test-id="pie-textarea-assistive-text">
+                variant="${ifDefined(this.status)}"
+                data-test-id="pie-select-assistive-text">
                 ${this.assistiveText}
             </pie-assistive-text>
         `;
@@ -91,6 +186,7 @@ export class PieSelect extends RtlMixin(LitElement) implements SelectProps {
             status,
             size,
             name,
+            options,
             _hasLeadingIcon,
         } = this;
 
@@ -106,18 +202,18 @@ export class PieSelect extends RtlMixin(LitElement) implements SelectProps {
             <div
                 class="${classMap(classes)}"
                 data-test-id="pie-select-shell">
-                    <slot name="leadingIcon" @slotchange=${this._handleLeadingIconSlotchange}></slot>
-                    <select
-                        name=${ifDefined(name)}
-                        ?disabled=${disabled}
-                        aria-describedby=${ifDefined(assistiveText ? assistiveTextIdValue : undefined)}
-                        aria-invalid=${status === 'error' ? 'true' : 'false'}
-                        aria-errormessage="${ifDefined(status === 'error' ? assistiveTextIdValue : undefined)}">
-                        <option value="dog">Dog</option>
-                        <option value="cat">Cat</option>
-                        <option value="hamster">Hamster</option>
-                    </select>
-                    <icon-chevron-down size='s' class='c-select-trailingIcon'></icon-chevron-down>
+                <slot name="leadingIcon" @slotchange=${this._handleLeadingIconSlotchange}></slot>
+                <select
+                    data-test-id="pie-select-element"
+                    name="${ifDefined(name)}"
+                    ?disabled="${disabled}"
+                    aria-describedby="${ifDefined(assistiveText ? assistiveTextIdValue : undefined)}"
+                    aria-invalid="${status === 'error' ? 'true' : 'false'}"
+                    aria-errormessage="${ifDefined(status === 'error' ? assistiveTextIdValue : undefined)}"
+                    @change=${this._handleChange}>
+                    ${this.renderChildren(options)}
+                </select>
+                <icon-chevron-down size='s' class='c-select-trailingIcon'></icon-chevron-down>
             </div>
             ${this.renderAssistiveText()}
         `;

package/src/react.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { createComponent } from '@lit/react';
+import { createComponent, type EventName } from '@lit/react';
 import { PieSelect as PieSelectLit } from './index';
 import { type SelectProps } from './defs';
 
@@ -10,10 +10,16 @@ const PieSelectReact = createComponent({
     elementClass: PieSelectLit,
     react: React,
     tagName: 'pie-select',
-    events: {},
+    events: {
+        onChange: 'change' as EventName<CustomEvent>, // when the selected option is changed.
+    },
 });
 
 type ReactBaseType = React.HTMLAttributes<HTMLSelectElement>
 
+type PieSelectEvents = {
+    onChange?: (event: CustomEvent) => void;
+};
+
 export const PieSelect = PieSelectReact as React.ForwardRefExoticComponent<React.PropsWithoutRef<SelectProps>
-    & React.RefAttributes<PieSelectLit> & ReactBaseType>;
+    & React.RefAttributes<PieSelectLit> & PieSelectEvents & ReactBaseType>;