ember-primitives 0.49.0 → 0.50.0

package/src/components/one-time-password/input.gts

@@ -0,0 +1,198 @@
+import Component from "@glimmer/component";
+import { warn } from "@ember/debug";
+import { isDestroyed, isDestroying } from "@ember/destroyable";
+import { on } from "@ember/modifier";
+import { buildWaiter } from "@ember/test-waiters";
+
+import {
+  autoAdvance,
+  getCollectiveValue,
+  handleNavigation,
+  handlePaste,
+  selectAll,
+} from "./utils.ts";
+
+import type { TOC } from "@ember/component/template-only";
+import type { WithBoundArgs } from "@glint/template";
+
+const DEFAULT_LENGTH = 6;
+
+function labelFor(inputIndex: number, labelFn: undefined | ((index: number) => string)) {
+  if (labelFn) {
+    return labelFn(inputIndex);
+  }
+
+  return `Please enter OTP character ${inputIndex + 1}`;
+}
+
+const waiter = buildWaiter("ember-primitives:OTPInput:handleChange");
+
+const Fields: TOC<{
+  /**
+   * Any attributes passed to this component will be applied to each input.
+   */
+  Element: HTMLInputElement;
+  Args: {
+    fields: unknown[];
+    labelFn: (index: number) => string;
+    handleChange: (event: Event) => void;
+  };
+}> = <template>
+  {{#each @fields as |_field i|}}
+    <label>
+      <span class="ember-primitives__sr-only">{{labelFor i @labelFn}}</span>
+      <input
+        name="code{{i}}"
+        type="text"
+        inputmode="numeric"
+        autocomplete="off"
+        ...attributes
+        {{on "click" selectAll}}
+        {{on "paste" handlePaste}}
+        {{on "input" autoAdvance}}
+        {{on "input" @handleChange}}
+        {{on "keydown" handleNavigation}}
+      />
+    </label>
+  {{/each}}
+</template>;
+
+export class OTPInput extends Component<{
+  /**
+   * The collection of individual OTP inputs are contained by a fieldset.
+   * Applying the `disabled` attribute to this fieldset will disable
+   * all of the inputs, if that's desired.
+   */
+  Element: HTMLFieldSetElement;
+  Args: {
+    /**
+     * How many characters the one-time-password field should be
+     * Defaults to 6
+     */
+    length?: number;
+
+    /**
+     * To Customize the label of the input fields, you may pass a function.
+     * By default, this is `Please enter OTP character ${index + 1}`.
+     */
+    labelFn?: (index: number) => string;
+
+    /**
+     * If passed, this function will be called when the <Input> changes.
+     * All fields are considered one input.
+     */
+    onChange?: (
+      data: {
+        /**
+         * The text from the collective `<Input>`
+         *
+         * `code` _may_ be shorter than `length`
+         * if the user has not finished typing / pasting their code
+         */
+        code: string;
+        /**
+         * will be `true` if `code`'s length matches the passed `@length` or the default of 6
+         */
+        complete: boolean;
+      },
+      /**
+       * The last input event received
+       */
+      event: Event,
+    ) => void;
+  };
+  Blocks: {
+    /**
+     * Optionally, you may control how the Fields are rendered, with proceeding text,
+     * additional attributes added, etc.
+     *
+     * This is how you can add custom validation to each input field.
+     */
+    default?: [fields: WithBoundArgs<typeof Fields, "fields" | "handleChange" | "labelFn">];
+  };
+}> {
+  /**
+   * This is debounced, because we bind to each input,
+   * but only want to emit one change event if someone pastes
+   * multiple characters
+   */
+  handleChange = (event: Event) => {
+    if (!this.args.onChange) return;
+
+    if (!this.#token) {
+      this.#token = waiter.beginAsync();
+    }
+
+    if (this.#frame) {
+      cancelAnimationFrame(this.#frame);
+    }
+
+    // We  use requestAnimationFrame to be friendly to rendering.
+    // We don't know if onChange is going to want to cause paints
+    // (it's also how we debounce, under the assumption that "paste" behavior
+    //  would be fast enough to be quicker than individual frames
+    //   (see logic in autoAdvance)
+    //  )
+    this.#frame = requestAnimationFrame(() => {
+      waiter.endAsync(this.#token);
+
+      if (isDestroyed(this) || isDestroying(this)) return;
+      if (!this.args.onChange) return;
+
+      const value = getCollectiveValue(event.target, this.length);
+
+      if (value === undefined) {
+        warn(`Value could not be determined for the OTP field. was it removed from the DOM?`, {
+          id: "ember-primitives.OTPInput.missing-value",
+        });
+
+        return;
+      }
+
+      this.args.onChange({ code: value, complete: value.length === this.length }, event);
+    });
+  };
+
+  #token: unknown;
+  #frame: number | undefined;
+
+  get length() {
+    return this.args.length ?? DEFAULT_LENGTH;
+  }
+
+  get fields() {
+    // We only need to iterate a number of times,
+    // so we don't care about the actual value or
+    // referential integrity here
+    return new Array<undefined>(this.length);
+  }
+
+  <template>
+    <fieldset ...attributes>
+      {{#let
+        (component Fields fields=this.fields handleChange=this.handleChange labelFn=@labelFn)
+        as |CurriedFields|
+      }}
+        {{#if (has-block)}}
+          {{yield CurriedFields}}
+        {{else}}
+          <CurriedFields />
+        {{/if}}
+      {{/let}}
+
+      <style>
+        .ember-primitives__sr-only {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          padding: 0;
+          margin: -1px;
+          overflow: hidden;
+          clip: rect(0, 0, 0, 0);
+          white-space: nowrap;
+          border-width: 0;
+        }
+      </style>
+    </fieldset>
+  </template>
+}

package/src/components/one-time-password/otp.gts

@@ -0,0 +1,130 @@
+import { assert } from "@ember/debug";
+import { fn, hash } from "@ember/helper";
+import { on } from "@ember/modifier";
+import { buildWaiter } from "@ember/test-waiters";
+
+import { Reset, Submit } from "./buttons.gts";
+import { OTPInput } from "./input.gts";
+
+import type { TOC } from "@ember/component/template-only";
+import type { WithBoundArgs } from "@glint/template";
+
+const waiter = buildWaiter("ember-primitives:OTP:handleAutoSubmitAttempt");
+
+const handleFormSubmit = (submit: (data: { code: string }) => void, event: SubmitEvent) => {
+  event.preventDefault();
+
+  assert(
+    "[BUG]: handleFormSubmit was not attached to a form. Please open an issue.",
+    event.currentTarget instanceof HTMLFormElement,
+  );
+
+  const formData = new FormData(event.currentTarget);
+
+  let code = "";
+
+  for (const [key, value] of formData.entries()) {
+    if (key.startsWith("code")) {
+      // eslint-disable-next-line @typescript-eslint/restrict-plus-operands, @typescript-eslint/no-base-to-string
+      code += value;
+    }
+  }
+
+  submit({
+    code,
+  });
+};
+
+function handleChange(
+  autoSubmit: boolean | undefined,
+  data: { code: string; complete: boolean },
+  event: Event,
+) {
+  if (!autoSubmit) return;
+  if (!data.complete) return;
+
+  assert(
+    "[BUG]: event target is not a known element type",
+    event.target instanceof HTMLElement || event.target instanceof SVGElement,
+  );
+
+  const form = event.target.closest("form");
+
+  assert("[BUG]: Cannot handle event when <OTP> Inputs are not rendered within their <form>", form);
+
+  const token = waiter.beginAsync();
+  const finished = () => {
+    waiter.endAsync(token);
+    form.removeEventListener("submit", finished);
+  };
+
+  form.addEventListener("submit", finished);
+
+  // NOTE: when calling .submit() the submit event handlers are not run
+  form.requestSubmit();
+}
+
+export const OTP: TOC<{
+  /**
+   * The overall OTP Input is in its own form.
+   * Modern UI/UX Patterns usually have this sort of field
+   * as its own page, thus within its own form.
+   *
+   * By default, only the 'submit' event is bound, and is
+   * what calls the `@onSubmit` argument.
+   */
+  Element: HTMLFormElement;
+  Args: {
+    /**
+     * How many characters the one-time-password field should be
+     * Defaults to 6
+     */
+    length?: number;
+
+    /**
+     * The on submit callback will give you the entered
+     * one-time-password code.
+     *
+     * It will be called when the user manually clicks the 'submit'
+     * button or when the full code is pasted and meats the validation
+     * criteria.
+     */
+    onSubmit: (data: { code: string }) => void;
+
+    /**
+     * Whether or not to auto-submit after the code has been pasted
+     * in to the collective "field".  Default is true
+     */
+    autoSubmit?: boolean;
+  };
+  Blocks: {
+    default: [
+      {
+        /**
+         * The collective input field that the OTP code will be typed/pasted in to
+         */
+        Input: WithBoundArgs<typeof OTPInput, "length" | "onChange">;
+        /**
+         * Button with `type="submit"` to submit the form
+         */
+        Submit: typeof Submit;
+        /**
+         * Pre-wired button to reset the form
+         */
+        Reset: typeof Reset;
+      },
+    ];
+  };
+}> = <template>
+  <form {{on "submit" (fn handleFormSubmit @onSubmit)}} ...attributes>
+    {{yield
+      (hash
+        Input=(component
+          OTPInput length=@length onChange=(if @autoSubmit (fn handleChange @autoSubmit))
+        )
+        Submit=Submit
+        Reset=Reset
+      )
+    }}
+  </form>
+</template>;

package/src/components/one-time-password/utils.ts

@@ -0,0 +1,201 @@
+import { assert } from '@ember/debug';
+
+function getInputs(current: HTMLInputElement) {
+  const fieldset = current.closest('fieldset');
+
+  assert('[BUG]: fieldset went missing', fieldset);
+
+  return [...fieldset.querySelectorAll('input')];
+}
+
+function nextInput(current: HTMLInputElement) {
+  const inputs = getInputs(current);
+  const currentIndex = inputs.indexOf(current);
+
+  return inputs[currentIndex + 1];
+}
+
+export function selectAll(event: Event) {
+  const target = event.target;
+
+  assert(`selectAll is only meant for use with input elements`, target instanceof HTMLInputElement);
+
+  target.select();
+}
+
+export function handlePaste(event: Event) {
+  const target = event.target;
+
+  assert(
+    `handlePaste is only meant for use with input elements`,
+    target instanceof HTMLInputElement
+  );
+
+  const clipboardData = (event as ClipboardEvent).clipboardData;
+
+  assert(
+    `Could not get clipboardData while handling the paste event on OTP. Please report this issue on the ember-primitives repo with a reproduction. Thanks!`,
+    clipboardData
+  );
+
+  // This is typically not good to prevent paste.
+  // But because of the UX we're implementing,
+  // we want to split the pasted value across
+  // multiple text fields
+  event.preventDefault();
+
+  const value = clipboardData.getData('Text');
+  const digits = value;
+  let i = 0;
+  let currElement: HTMLInputElement | null = target;
+
+  while (currElement) {
+    currElement.value = digits[i++] || '';
+
+    const next = nextInput(currElement);
+
+    if (next instanceof HTMLInputElement) {
+      currElement = next;
+    } else {
+      break;
+    }
+  }
+
+  // We want to select the first field again
+  // so that if someone holds paste, or
+  // pastes again, they get the same result.
+  target.select();
+}
+
+export function handleNavigation(event: KeyboardEvent) {
+  switch (event.key) {
+    case 'Backspace':
+      return handleBackspace(event);
+    case 'ArrowLeft':
+      return focusLeft(event);
+    case 'ArrowRight':
+      return focusRight(event);
+  }
+}
+
+function focusLeft(event: Pick<Event, 'target'>) {
+  const target = event.target;
+
+  assert(`only allowed on input elements`, target instanceof HTMLInputElement);
+
+  const input = previousInput(target);
+
+  input?.focus();
+  requestAnimationFrame(() => {
+    input?.select();
+  });
+}
+
+function focusRight(event: Pick<Event, 'target'>) {
+  const target = event.target;
+
+  assert(`only allowed on input elements`, target instanceof HTMLInputElement);
+
+  const input = nextInput(target);
+
+  input?.focus();
+  requestAnimationFrame(() => {
+    input?.select();
+  });
+}
+
+const syntheticEvent = new InputEvent('input');
+
+function handleBackspace(event: KeyboardEvent) {
+  if (event.key !== 'Backspace') return;
+
+  /**
+   * We have to prevent default because we
+   * - want to clear the whole field
+   * - have the focus behavior keep up with the key-repeat
+   *   speed of the user's computer
+   */
+  event.preventDefault();
+
+  const target = event.target;
+
+  if (target && 'value' in target) {
+    if (target.value === '') {
+      focusLeft({ target });
+    } else {
+      target.value = '';
+    }
+  }
+
+  target?.dispatchEvent(syntheticEvent);
+}
+
+function previousInput(current: HTMLInputElement) {
+  const inputs = getInputs(current);
+  const currentIndex = inputs.indexOf(current);
+
+  return inputs[currentIndex - 1];
+}
+
+export const autoAdvance = (event: Event) => {
+  assert(
+    '[BUG]: autoAdvance called on non-input element',
+    event.target instanceof HTMLInputElement
+  );
+
+  const value = event.target.value;
+
+  if (value.length === 0) return;
+
+  if (value.length > 0) {
+    if ('data' in event && event.data && typeof event.data === 'string') {
+      event.target.value = event.data;
+    }
+
+    return focusRight(event);
+  }
+};
+
+export function getCollectiveValue(elementTarget: EventTarget | null, length: number) {
+  if (!elementTarget) return;
+
+  assert(
+    `[BUG]: somehow the element target is not HTMLElement`,
+    elementTarget instanceof HTMLElement
+  );
+
+  let parent: null | HTMLElement | ShadowRoot;
+
+  // TODO: should this logic be extracted?
+  //       why is getting the target element within a shadow root hard?
+  if (!(elementTarget instanceof HTMLInputElement)) {
+    if (elementTarget.shadowRoot) {
+      parent = elementTarget.shadowRoot;
+    } else {
+      parent = elementTarget.closest('fieldset');
+    }
+  } else {
+    parent = elementTarget.closest('fieldset');
+  }
+
+  assert(`[BUG]: somehow the input fields were rendered without a parent element`, parent);
+
+  const elements = parent.querySelectorAll('input');
+
+  let value = '';
+
+  assert(
+    `found elements (${elements.length}) do not match length (${length}). Was the same OTP input rendered more than once?`,
+    elements.length === length
+  );
+
+  for (const element of elements) {
+    assert(
+      '[BUG]: how did the queried elements become a non-input element?',
+      element instanceof HTMLInputElement
+    );
+    value += element.value;
+  }
+
+  return value;
+}

package/src/components/one-time-password.gts

@@ -0,0 +1,2 @@
+export { OTPInput } from "./one-time-password/input.gts";
+export { OTP } from "./one-time-password/otp.gts";