@redvars/peacock 3.8.1 → 3.8.2

package/src/__internal/events/dispatch-hooks.ts

@@ -0,0 +1,182 @@
+/**
+ * A symbol used to access dispatch hooks on an event.
+ */
+const dispatchHooks = Symbol('dispatchHooks');
+
+/**
+ * An `Event` with additional symbols for dispatch hooks.
+ */
+interface EventWithDispatchHooks extends Event {
+  [dispatchHooks]: EventTarget;
+}
+
+/**
+ * Add a hook for an event that is called after the event is dispatched and
+ * propagates to other event listeners.
+ *
+ * This is useful for behaviors that need to check if an event is canceled.
+ *
+ * The callback is invoked synchronously, which allows for better integration
+ * with synchronous platform APIs (like `<form>` or `<label>` clicking).
+ *
+ * Note: `setupDispatchHooks()` must be called on the element before adding any
+ * other event listeners. Call it in the constructor of an element or
+ * controller.
+ *
+ * @example
+ * ```ts
+ * class MyControl extends LitElement {
+ *   constructor() {
+ *     super();
+ *     setupDispatchHooks(this, 'click');
+ *     this.addEventListener('click', event => {
+ *       afterDispatch(event, () => {
+ *         if (event.defaultPrevented) {
+ *           return
+ *         }
+ *
+ *         // ... perform logic
+ *       });
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * class MyController implements ReactiveController {
+ *   constructor(host: ReactiveElement) {
+ *     // setupDispatchHooks() may be called multiple times for the same
+ *     // element and events, making it safe for multiple controllers to use it.
+ *     setupDispatchHooks(host, 'click');
+ *     host.addEventListener('click', event => {
+ *       afterDispatch(event, () => {
+ *         if (event.defaultPrevented) {
+ *           return;
+ *         }
+ *
+ *         // ... perform logic
+ *       });
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @param event The event to add a hook to.
+ * @param callback A hook that is called after the event finishes dispatching.
+ */
+export function afterDispatch(event: Event, callback: () => void) {
+  const hooks = (event as EventWithDispatchHooks)[dispatchHooks];
+  if (!hooks) {
+    throw new Error(`'${event.type}' event needs setupDispatchHooks().`);
+  }
+
+  hooks.addEventListener('after', callback, { once: true });
+}
+
+/**
+ * A lookup map of elements and event types that have a dispatch hook listener
+ * set up. Used to ensure we don't set up multiple hook listeners on the same
+ * element for the same event.
+ */
+const ELEMENT_DISPATCH_HOOK_TYPES = new WeakMap<Element, Set<string>>();
+
+/**
+ * Sets up an element to add dispatch hooks to given event types. This must be
+ * called before adding any event listeners that need to use dispatch hooks
+ * like `afterDispatch()`.
+ *
+ * This function is safe to call multiple times with the same element or event
+ * types. Call it in the constructor of elements, mixins, and controllers to
+ * ensure it is set up before external listeners.
+ *
+ * @example
+ * ```ts
+ * class MyControl extends LitElement {
+ *   constructor() {
+ *     super();
+ *     setupDispatchHooks(this, 'click');
+ *     this.addEventListener('click', this.listenerUsingAfterDispatch);
+ *   }
+ * }
+ * ```
+ *
+ * @param element The element to set up event dispatch hooks for.
+ * @param eventTypes The event types to add dispatch hooks to.
+ */
+export function setupDispatchHooks(
+  element: Element,
+  ...eventTypes: [string, ...string[]]
+) {
+  let typesAlreadySetUp = ELEMENT_DISPATCH_HOOK_TYPES.get(element);
+  if (!typesAlreadySetUp) {
+    typesAlreadySetUp = new Set();
+    ELEMENT_DISPATCH_HOOK_TYPES.set(element, typesAlreadySetUp);
+  }
+
+  for (const eventType of eventTypes) {
+    // Don't register multiple dispatch hook listeners. A second registration
+    // would lead to the second listener calling `afterDispatch()` hooks twice.
+    if (typesAlreadySetUp.has(eventType)) {
+      continue;
+    }
+
+    element.addEventListener(
+      eventType,
+      (event: Event) => {
+        // Add hooks onto the event.
+        const hooks = new EventTarget();
+        (event as EventWithDispatchHooks)[dispatchHooks] = hooks;
+
+        const cleanupLastNodeListener = new AbortController();
+        const callAfterDispatch = () => {
+          cleanupLastNodeListener.abort();
+          hooks.dispatchEvent(new Event('after'));
+        };
+
+        const patchStopPropagation = (
+          superMethod: Event['stopPropagation'],
+        ) => {
+          return function (this: Event) {
+            superMethod.call(this);
+            // Synchronously call afterDispatch() hooks when interrupted.
+            callAfterDispatch();
+          };
+        };
+
+        event.stopPropagation = patchStopPropagation(event.stopPropagation);
+        event.stopImmediatePropagation = patchStopPropagation(
+          event.stopImmediatePropagation,
+        );
+
+        // Add an event listener to detect the end of the event's propagation.
+        const composedPath = event.composedPath();
+        let lastNodeForEvent: EventTarget;
+        if (event.composed && event.bubbles) {
+          lastNodeForEvent = composedPath[composedPath.length - 1];
+        } else if (!event.bubbles) {
+          lastNodeForEvent = composedPath[0];
+        } else {
+          lastNodeForEvent = (composedPath[0] as Element).getRootNode();
+        }
+
+        lastNodeForEvent.addEventListener(
+          eventType,
+          () => {
+            // Synchronously call afterDispatch() hooks.
+            callAfterDispatch();
+          },
+          { once: true, signal: cleanupLastNodeListener.signal },
+        );
+      },
+      {
+        // Ensure this listener runs before other listeners.
+        // `setupDispatchHooks()` should be called in constructors to also
+        // ensure they run before any other externally-added capture listeners.
+        capture: true,
+      },
+    );
+
+    typesAlreadySetUp.add(eventType);
+  }
+}

package/src/__internal/mixins/element-internals.ts

@@ -0,0 +1,73 @@
+import { LitElement } from 'lit';
+
+import { MixinBase, MixinReturn } from './mixin.js';
+
+/**
+ * A unique symbol used for protected access to an instance's
+ * `ElementInternals`.
+ *
+ * @example
+ * ```ts
+ * class MyElement extends mixinElementInternals(LitElement) {
+ *   constructor() {
+ *     super();
+ *     this[internals].role = 'button';
+ *   }
+ * }
+ * ```
+ */
+export const internals = Symbol('internals');
+
+/**
+ * An instance with an `internals` symbol property for the component's
+ * `ElementInternals`.
+ *
+ * Use this when protected access is needed for an instance's `ElementInternals`
+ * from other files. A unique symbol is used to access the internals.
+ */
+export interface WithElementInternals {
+  /**
+   * An instance's `ElementInternals`.
+   */
+  [internals]: ElementInternals;
+}
+
+// Private symbols
+const privateInternals = Symbol('privateInternals');
+
+/**
+ * Mixes in an attached `ElementInternals` instance.
+ *
+ * This mixin is only needed when other shared code needs access to a
+ * component's `ElementInternals`, such as form-associated mixins.
+ *
+ * @param base The class to mix functionality into.
+ * @return The provided class with `WithElementInternals` mixed in.
+ */
+export function mixinElementInternals<T extends MixinBase<LitElement>>(
+  base: T,
+): MixinReturn<T, WithElementInternals> {
+  abstract class WithElementInternalsElement
+    extends base
+    implements WithElementInternals
+  {
+    get [internals]() {
+      // Create internals in getter so that it can be used in methods called on
+      // construction in `ReactiveElement`, such as `requestUpdate()`.
+      if (!this[privateInternals]) {
+        // Cast needed for closure
+        this[privateInternals] = (this as HTMLElement).attachInternals();
+      }
+
+      return this[privateInternals];
+    }
+
+    // In preparation for ES2022, we need to declare this property to guard
+    // against the base class calling [internals] in its constructor prematurely
+    // setting this field. Without declare, once this field is defined, it would
+    // initialize to undefined and `attachInternals()` could be called again.
+    declare [privateInternals]?: ElementInternals;
+  }
+
+  return WithElementInternalsElement;
+}

package/src/__internal/mixins/form-associated.ts

@@ -0,0 +1,295 @@
+import { LitElement, PropertyDeclaration } from 'lit';
+import { property } from 'lit/decorators.js';
+
+import { internals, WithElementInternals } from './element-internals.js';
+import { MixinBase, MixinReturn } from './mixin.js';
+
+/**
+ * A form-associated element.
+ */
+export interface FormAssociated {
+  /**
+   * The associated form element with which this element's value will submit.
+   */
+  readonly form: HTMLFormElement | null;
+
+  /**
+   * The labels this element is associated with.
+   */
+  readonly labels: NodeList;
+
+  /**
+   * The HTML name to use in form submission.
+   */
+  name: string;
+
+  /**
+   * Whether or not the element is disabled.
+   */
+  disabled: boolean;
+
+  /**
+   * Gets the current form value of a component. Defaults to the component's
+   * `value` attribute.
+   *
+   * @return The current form value.
+   */
+  [getFormValue](): FormValue | null;
+
+  /**
+   * Gets the current form state of a component. Defaults to the component's
+   * `[getFormValue]()` result.
+   *
+   * Use this when the state of an element is different from its value, such as
+   * checkboxes (internal boolean state and a user string value).
+   *
+   * @return The current form state, defaults to the form value.
+   */
+  [getFormState](): FormValue | null;
+
+  /**
+   * A callback for when a form component should be disabled or enabled. This
+   * can be called in a variety of situations, such as disabled `<fieldset>`s.
+   *
+   * @param disabled Whether or not the form control should be disabled.
+   */
+  formDisabledCallback(disabled: boolean): void;
+
+  /**
+   * An optional callback for when the form requests to reset its value.
+   * Typically, the default value that is reset is represented in the attribute
+   * of an element.
+   *
+   * This means the attribute used for the value should not update as the value
+   * changes. For example, a checkbox should not change its default `checked`
+   * attribute when selected. Ensure form values do not reflect.
+   */
+  formResetCallback?(): void;
+
+  /**
+   * An optional callback for when the form restores the state of a component.
+   * For example, when a page is reloaded or forms are autofilled.
+   *
+   * @param state The state to restore, or null to reset the form control's
+   *     value.
+   * @param reason The reason state was restored, either `'restore'` or
+   *   `'autocomplete'`.
+   */
+  formStateRestoreCallback?(
+    state: FormRestoreState | null,
+    reason: FormRestoreReason,
+  ): void;
+
+  /**
+   * An optional callback for when the associated form changes.
+   *
+   * @param form The new associated form, or `null` if there is none.
+   */
+  formAssociatedCallback?(form: HTMLFormElement | null): void;
+}
+
+/**
+ * The constructor of a `FormAssociated` element.
+ */
+export interface FormAssociatedConstructor {
+  /**
+   * Indicates that an element is participating in form association.
+   */
+  readonly formAssociated: true;
+}
+
+/**
+ * A symbol property to retrieve the form value for an element.
+ */
+export const getFormValue = Symbol('getFormValue');
+
+/**
+ * A symbol property to retrieve the form state for an element.
+ */
+export const getFormState = Symbol('getFormState');
+
+/**
+ * Mixes in form-associated behavior for a class. This allows an element to add
+ * values to `<form>` elements.
+ *
+ * Implementing classes should provide a `[formValue]` to return the current
+ * value of the element, as well as reset and restore callbacks.
+ *
+ * @example
+ * ```ts
+ * const base = mixinFormAssociated(mixinElementInternals(LitElement));
+ *
+ * class MyControl extends base {
+ *   \@property()
+ *   value = '';
+ *
+ *   override [getFormValue]() {
+ *     return this.value;
+ *   }
+ *
+ *   override formResetCallback() {
+ *     const defaultValue = this.getAttribute('value');
+ *     this.value = defaultValue;
+ *   }
+ *
+ *   override formStateRestoreCallback(state: string) {
+ *     this.value = state;
+ *   }
+ * }
+ * ```
+ *
+ * Elements may optionally provide a `[formState]` if their values do not
+ * represent the state of the component.
+ *
+ * @example
+ * ```ts
+ * const base = mixinFormAssociated(mixinElementInternals(LitElement));
+ *
+ * class MyCheckbox extends base {
+ *   \@property()
+ *   value = 'on';
+ *
+ *   \@property({type: Boolean})
+ *   checked = false;
+ *
+ *   override [getFormValue]() {
+ *     return this.checked ? this.value : null;
+ *   }
+ *
+ *   override [getFormState]() {
+ *     return String(this.checked);
+ *   }
+ *
+ *   override formResetCallback() {
+ *     const defaultValue = this.hasAttribute('checked');
+ *     this.checked = defaultValue;
+ *   }
+ *
+ *   override formStateRestoreCallback(state: string) {
+ *     this.checked = Boolean(state);
+ *   }
+ * }
+ * ```
+ *
+ * @param base The class to mix functionality into. The base class must use
+ *     `mixinElementInternals()`.
+ * @return The provided class with `FormAssociated` mixed in.
+ */
+export function mixinFormAssociated<
+  T extends MixinBase<LitElement & WithElementInternals>,
+>(base: T): MixinReturn<T & FormAssociatedConstructor, FormAssociated> {
+  abstract class FormAssociatedElement extends base implements FormAssociated {
+    /** @nocollapse */
+    static readonly formAssociated = true;
+
+    get form() {
+      return this[internals].form;
+    }
+
+    get labels() {
+      return this[internals].labels;
+    }
+
+    // Use @property for the `name` and `disabled` properties to add them to the
+    // `observedAttributes` array and trigger `attributeChangedCallback()`.
+    //
+    // We don't use Lit's default getter/setter (`noAccessor: true`) because
+    // the attributes need to be updated synchronously to work with synchronous
+    // form APIs, and Lit updates attributes async by default.
+    @property({ noAccessor: true })
+    get name() {
+      return this.getAttribute('name') ?? '';
+    }
+    set name(name: string) {
+      // Note: setting name to null or empty does not remove the attribute.
+      this.setAttribute('name', name);
+      // We don't need to call `requestUpdate()` since it's called synchronously
+      // in `attributeChangedCallback()`.
+    }
+
+    @property({ type: Boolean, noAccessor: true })
+    get disabled() {
+      return this.hasAttribute('disabled');
+    }
+    set disabled(disabled: boolean) {
+      // Coerce `disabled` in `Boolean()` to ensure that setting to `null` or
+      // `undefined` sets the attribute to `false`.
+      this.toggleAttribute('disabled', Boolean(disabled));
+      // We don't need to call `requestUpdate()` since it's called synchronously
+      // in `attributeChangedCallback()`.
+    }
+
+    override attributeChangedCallback(
+      name: string,
+      old: string | null,
+      value: string | null,
+    ) {
+      // Manually `requestUpdate()` for `name` and `disabled` when their
+      // attribute or property changes.
+      // The properties update their attributes, so this callback is invoked
+      // immediately when the properties are set. We call `requestUpdate()` here
+      // instead of letting Lit set the properties from the attribute change.
+      // That would cause the properties to re-set the attribute and invoke this
+      // callback again in a loop. This leads to stale state when Lit tries to
+      // determine if a property changed or not.
+      if (name === 'name' || name === 'disabled') {
+        // Disabled's value is only false if the attribute is missing and null.
+        const oldValue = name === 'disabled' ? old !== null : old;
+        // Trigger a lit update when the attribute changes.
+        this.requestUpdate(name, oldValue);
+        return;
+      }
+
+      super.attributeChangedCallback(name, old, value);
+    }
+
+    override requestUpdate(
+      name?: PropertyKey,
+      oldValue?: unknown,
+      options?: PropertyDeclaration,
+    ) {
+      super.requestUpdate(name, oldValue, options);
+      // If any properties change, update the form value, which may have changed
+      // as well.
+      // Update the form value synchronously in `requestUpdate()` rather than
+      // `update()` or `updated()`, which are async. This is necessary to ensure
+      // that form data is updated in time for synchronous event listeners.
+      this[internals].setFormValue(this[getFormValue](), this[getFormState]());
+    }
+
+    [getFormValue](): FormValue | null {
+      return this.getAttribute('value');
+    }
+
+    [getFormState](): FormValue | null {
+      return this[getFormValue]();
+    }
+
+    formDisabledCallback(disabled: boolean) {
+      this.disabled = disabled;
+    }
+  }
+
+  return FormAssociatedElement;
+}
+
+/**
+ * A value that can be provided for form submission and state.
+ */
+export type FormValue = File | string | FormData;
+
+/**
+ * A value to be restored for a component's form value. If a component's form
+ * state is a `FormData` object, its entry list of name and values will be
+ * provided.
+ */
+export type FormRestoreState =
+  | File
+  | string
+  | Array<[string, FormDataEntryValue]>;
+
+/**
+ * The reason a form component is being restored for, either `'restore'` for
+ * browser restoration or `'autocomplete'` for restoring user values.
+ */
+export type FormRestoreReason = 'restore' | 'autocomplete';

package/src/__internal/mixins/form-submitter.ts

@@ -0,0 +1,133 @@
+import { isServer, LitElement } from 'lit';
+import { property } from 'lit/decorators.js';
+
+import { afterDispatch, setupDispatchHooks } from '../events/dispatch-hooks.js';
+import { internals, WithElementInternals } from './element-internals.js';
+import { MixinBase, MixinReturn } from './mixin.js';
+
+/**
+ * A string indicating the form submission behavior of the element.
+ *
+ * - submit: The element submits the form. This is the default value if the
+ * attribute is not specified, or if it is dynamically changed to an empty or
+ * invalid value.
+ * - reset: The element resets the form.
+ * - button: The element does nothing.
+ */
+export type FormSubmitterType = 'button' | 'submit' | 'reset';
+
+/**
+ * An element that can submit or reset a `<form>`, similar to
+ * `<button type="submit">`.
+ */
+export interface FormSubmitter {
+  /**
+   * A string indicating the form submission behavior of the element.
+   *
+   * - submit: The element submits the form. This is the default value if the
+   * attribute is not specified, or if it is dynamically changed to an empty or
+   * invalid value.
+   * - reset: The element resets the form.
+   * - button: The element does nothing.
+   */
+  type: string;
+
+  /**
+   * The HTML name to use in form submission. When combined with a `value`, the
+   * submitting button's name/value will be added to the form.
+   *
+   * Names must reflect to a `name` attribute for form integration.
+   */
+  name: string;
+
+  /**
+   * The value of the button. When combined with a `name`, the submitting
+   * button's name/value will be added to the form.
+   */
+  value: string;
+}
+
+/**
+ * Mixes in form submitter behavior for a class.
+ *
+ * A click listener is added to each element instance. If the click is not
+ * default prevented, it will submit the element's form, if any.
+ *
+ * @example
+ * ```ts
+ * const base = mixinFormSubmitter(mixinElementInternals(LitElement));
+ * class MyButton extends base {
+ *   static formAssociated = true;
+ * }
+ * ```
+ *
+ * @param base The class to mix functionality into.
+ * @return The provided class with `FormSubmitter` mixed in.
+ */
+export function mixinFormSubmitter<
+  T extends MixinBase<LitElement & WithElementInternals>,
+>(base: T): MixinReturn<T, FormSubmitter> {
+  abstract class FormSubmitterElement extends base implements FormSubmitter {
+    @property() type = 'submit';
+
+    @property({ reflect: true }) value = '';
+
+    // Name attribute must reflect synchronously for form integration.
+    get name() {
+      return this.getAttribute('name') ?? '';
+    }
+
+    set name(name: string) {
+      this.setAttribute('name', name);
+    }
+
+    // Mixins must have a constructor with `...args: any[]`
+    // tslint:disable-next-line:no-any
+    constructor(...args: any[]) {
+      super(...args);
+      if (isServer) return;
+      setupDispatchHooks(this, 'click');
+      this.addEventListener('click', async (event: Event) => {
+        const isReset = this.type === 'reset';
+        const isSubmit = this.type === 'submit';
+        const elementInternals = this[internals];
+        const { form } = elementInternals;
+        if (!form || !(isSubmit || isReset)) {
+          return;
+        }
+
+        afterDispatch(event, () => {
+          if (event.defaultPrevented) {
+            return;
+          }
+
+          if (isReset) {
+            form.reset();
+            return;
+          }
+
+          // form.requestSubmit(submitter) does not work with form associated custom
+          // elements. This patches the dispatched submit event to add the correct
+          // `submitter`.
+          // See https://github.com/WICG/webcomponents/issues/814
+          form.addEventListener(
+            'submit',
+            (submitEvent: Event) => {
+              Object.defineProperty(submitEvent, 'submitter', {
+                configurable: true,
+                enumerable: true,
+                get: () => this,
+              });
+            },
+            { capture: true, once: true },
+          );
+
+          elementInternals.setFormValue(this.value);
+          form.requestSubmit();
+        });
+      });
+    }
+  }
+
+  return FormSubmitterElement;
+}