ember-primitives 0.49.0 → 0.50.1

package/src/components/avatar.gts

@@ -0,0 +1,108 @@
+import { hash } from "@ember/helper";
+
+import { ReactiveImage } from "reactiveweb/image";
+import { WaitUntil } from "reactiveweb/wait-until";
+
+import type { TOC } from "@ember/component/template-only";
+import type { WithBoundArgs } from "@glint/template";
+
+const Fallback: TOC<{
+  Blocks: { default: [] };
+  Args: {
+    /**
+     * The number of milliseconds to wait for the image to load
+     * before displaying the fallback
+     */
+    delayMs?: number;
+    /**
+     * @private
+     * Bound internally by ember-primitives
+     */
+    isLoaded: boolean;
+  };
+}> = <template>
+  {{#unless @isLoaded}}
+    {{#let (WaitUntil @delayMs) as |delayFinished|}}
+      {{#if delayFinished}}
+        {{yield}}
+      {{/if}}
+    {{/let}}
+  {{/unless}}
+</template>;
+
+const Image: TOC<{
+  Element: HTMLImageElement;
+  Args: {
+    /**
+     * @private
+     * The `src` value for the image.
+     *
+     * Bound internally by ember-primitives
+     */
+    src: string;
+    /**
+     * @private
+     * Bound internally by ember-primitives
+     */
+    isLoaded: boolean;
+  };
+}> = <template>
+  {{#if @isLoaded}}
+    <img alt="__missing__" ...attributes src={{@src}} />
+  {{/if}}
+</template>;
+
+export const Avatar: TOC<{
+  Element: HTMLSpanElement;
+  Args: {
+    /**
+     * The `src` value for the image.
+     */
+    src: string;
+  };
+  Blocks: {
+    default: [
+      avatar: {
+        /**
+         * The image to render. It will only render when it has loaded.
+         */
+        Image: WithBoundArgs<typeof Image, "src" | "isLoaded">;
+        /**
+         * An element that renders when the image hasn't loaded.
+         * This means whilst it's loading, or if there was an error.
+         * If you notice a flash during loading,
+         * you can provide a delayMs prop to delay its rendering so it only renders for those with slower connections.
+         */
+        Fallback: WithBoundArgs<typeof Fallback, "isLoaded">;
+        /**
+         * true while the image is loading
+         */
+        isLoading: boolean;
+        /**
+         * If the image fails to load, this will be `true`
+         */
+        isError: boolean;
+      },
+    ];
+  };
+}> = <template>
+  {{#let (ReactiveImage @src) as |imgState|}}
+    <span
+      data-prim-avatar
+      ...attributes
+      data-loading={{imgState.isLoading}}
+      data-error={{imgState.isError}}
+    >
+      {{yield
+        (hash
+          Image=(component Image src=@src isLoaded=imgState.isResolved)
+          Fallback=(component Fallback isLoaded=imgState.isResolved)
+          isLoading=imgState.isLoading
+          isError=imgState.isError
+        )
+      }}
+    </span>
+  {{/let}}
+</template>;
+
+export default Avatar;

package/src/components/dialog.gts

@@ -0,0 +1,234 @@
+import Component from "@glimmer/component";
+import { tracked } from "@glimmer/tracking";
+import { assert } from "@ember/debug";
+import { hash } from "@ember/helper";
+import { on } from "@ember/modifier";
+
+import { modifier as eModifier } from "ember-modifier";
+// temp
+//  https://github.com/tracked-tools/tracked-toolbox/issues/38
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-expect-error
+import { localCopy } from "tracked-toolbox";
+
+import type { TOC } from "@ember/component/template-only";
+import type { ModifierLike, WithBoundArgs } from "@glint/template";
+
+const DialogElement: TOC<{
+  Element: HTMLDialogElement;
+  Args: {
+    /**
+     * @internal
+     */
+    open: boolean | undefined;
+    /**
+     * @internal
+     */
+    onClose: () => void;
+
+    /**
+     * @internal
+     */
+    register: ModifierLike<{ Element: HTMLDialogElement }>;
+  };
+  Blocks: { default: [] };
+}> = <template>
+  <dialog ...attributes open={{@open}} {{on "close" @onClose}} {{@register}}>
+    {{yield}}
+  </dialog>
+</template>;
+
+export interface Signature {
+  Args: {
+    /**
+     * Optionally set the open state of the `<dialog>`
+     * The state will still be managed internally,
+     * so this does not need to be a maintained value, but whenever it changes,
+     * the dialog element will reflect that change accordingly.
+     */
+    open?: boolean;
+    /**
+     * When the `<dialog>` is closed, this function will be called
+     * and the `<dialog>`'s `returnValue` will be passed.
+     *
+     * This can be used to determine which button was clicked to close the modal
+     *
+     * Note though that this value is only populated when using
+     * `<form method='dialog'>`
+     */
+    onClose?: (returnValue: string) => void;
+  };
+  Blocks: {
+    default: [
+      {
+        /**
+         * Represents the open state of the `<dialog>` element.
+         */
+        isOpen: boolean;
+
+        /**
+         * Closes the `<dialog>` element
+         * Will throw an error if `Dialog` is not rendered.
+         */
+        close: () => void;
+
+        /**
+         * Opens the `<dialog>` element.
+         * Will throw an error if `Dialog` is not rendered.
+         */
+        open: () => void;
+
+        /**
+         * This modifier should be applied to the button that opens the Dialog so that it can be re-focused when the dialog closes.
+         *
+         * Example:
+         *
+         * ```gjs
+         * <template>
+         *   <Modal as |m|>
+         *     <button {{m.focusOnClose}} {{on "click" m.open}}>Open</button>
+         *
+         *     <m.Dialog>...</m.Dialog>
+         *   </Modal>
+         * </template>
+         * ```
+         */
+        focusOnClose: ModifierLike<{ Element: HTMLElement }>;
+
+        /**
+         * This is the `<dialog>` element (with some defaults pre-wired).
+         * This is required to be rendered.
+         */
+        Dialog: WithBoundArgs<typeof DialogElement, "onClose" | "register" | "open">;
+      },
+    ];
+  };
+}
+
+class ModalDialog extends Component<Signature> {
+  <template>
+    {{yield
+      (hash
+        isOpen=this.isOpen
+        open=this.open
+        close=this.close
+        focusOnClose=this.refocus
+        Dialog=(component DialogElement open=@open onClose=this.handleClose register=this.register)
+      )
+    }}
+  </template>
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+  @localCopy("args.open") declare _isOpen: boolean;
+
+  get isOpen() {
+    /**
+     * Always fallback to false (closed)
+     */
+    return this._isOpen ?? false;
+  }
+  set isOpen(val: boolean) {
+    this._isOpen = val;
+  }
+
+  #lastIsOpen = false;
+  refocus = eModifier((element) => {
+    assert(`focusOnClose is only valid on a HTMLElement`, element instanceof HTMLElement);
+
+    if (!this.isOpen && this.#lastIsOpen) {
+      element.focus();
+    }
+
+    this.#lastIsOpen = this.isOpen;
+  });
+
+  @tracked declare dialogElement: HTMLDialogElement | undefined;
+
+  register = eModifier((element: HTMLDialogElement) => {
+    /**
+     * This is very sad.
+     *
+     * But we need the element to be 'root state'
+     * so that when we read things like "isOpen",
+     * when the dialog is finally rendered, all the
+     * downstream properties render.
+     *
+     * This has to be an async / delayed a bit, so that
+     * the tracking frame can exit, and we don't infinite loop
+     */
+    void (async () => {
+      await Promise.resolve();
+
+      this.dialogElement = element;
+    })();
+  });
+
+  /**
+   * Closes the dialog -- this will throw an error in development if the dialog element was not rendered
+   */
+  close = () => {
+    assert(
+      "Cannot call `close` on <Dialog> without rendering the dialog element.",
+      this.dialogElement,
+    );
+
+    /**
+     * If the element is already closed, don't run all this again
+     */
+    if (!this.dialogElement.hasAttribute("open")) {
+      return;
+    }
+
+    /**
+     * removes the `open` attribute
+     * handleClose will be called because the dialog has bound the `close` event.
+     */
+    this.dialogElement.close();
+  };
+
+  /**
+   * @internal
+   *
+   * handles the <dialog> element's native close behavior.
+   * listened to via addEventListener('close', ...);
+   */
+  handleClose = () => {
+    assert(
+      "Cannot call `handleDialogClose` on <Dialog> without rendering the dialog element. This is likely a bug in ember-primitives. Please open an issue <3",
+      this.dialogElement,
+    );
+
+    this.isOpen = false;
+    this.args.onClose?.(this.dialogElement.returnValue);
+    // the return value ends up staying... which is annoying
+    this.dialogElement.returnValue = "";
+  };
+
+  /**
+   * Opens the dialog -- this will throw an error in development if the dialog element was not rendered
+   */
+  open = () => {
+    assert(
+      "Cannot call `open` on <Dialog> without rendering the dialog element.",
+      this.dialogElement,
+    );
+
+    /**
+     * If the element is already open, don't run all this again
+     */
+    if (this.dialogElement.hasAttribute("open")) {
+      return;
+    }
+
+    /**
+     * adds the `open` attribute
+     */
+    this.dialogElement.showModal();
+    this.isOpen = true;
+  };
+}
+
+export const Modal = ModalDialog;
+export const Dialog = ModalDialog;
+
+export default ModalDialog;

package/src/components/external-link.gts

@@ -0,0 +1,14 @@
+import type { TOC } from "@ember/component/template-only";
+
+export const ExternalLink: TOC<{
+  Element: HTMLAnchorElement;
+  Blocks: {
+    default: [];
+  };
+}> = <template>
+  <a target="_blank" rel="noreferrer noopener" href="##missing##" ...attributes>
+    {{yield}}
+  </a>
+</template>;
+
+export default ExternalLink;

package/src/components/form.gts

@@ -0,0 +1,75 @@
+import { fn } from "@ember/helper";
+import { on } from "@ember/modifier";
+
+import { dataFrom } from "form-data-utils";
+
+import type { TOC } from "@ember/component/template-only";
+
+type Data = ReturnType<typeof dataFrom>;
+
+export const dataFromEvent = dataFrom;
+
+const handleInput = (
+  onChange: (data: Data, eventType: "input" | "submit", event: Event) => void,
+  event: Event | SubmitEvent,
+  eventType: "input" | "submit" = "input",
+) => {
+  const data = dataFrom(event);
+
+  onChange(data, eventType, event);
+};
+
+const handleSubmit = (
+  onChange: (data: Data, eventType: "input" | "submit", event: Event | SubmitEvent) => void,
+  event: SubmitEvent,
+) => {
+  event.preventDefault();
+  handleInput(onChange, event, "submit");
+};
+
+export interface Signature {
+  Element: HTMLFormElement;
+  Args: {
+    /**
+     *  Any time the value of any field is changed this function will be called.
+     */
+    onChange: (
+      /**
+       * The data from the form as an Object of `{ [field name] => value }` pairs.
+       * This is generated from the native [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
+       *
+       * Additional fields/inputs/controls can be added to this data by specifying a
+       * "name" attribute.
+       */
+      data: Data,
+      /**
+       * Indicates whether the `onChange` function was called from the `input` or `submit` event handlers.
+       */
+      eventType: "input" | "submit",
+      /**
+       * The raw event, if needed.
+       */
+      event: Event | SubmitEvent,
+    ) => void;
+  };
+  Blocks: {
+    /**
+     * The main content for the form. This is where inputs / fields / controls would go.
+     * Within the `<form>` content, `<button type="submit">` will submit the form, which
+     * triggers the `@onChange` event.
+     */
+    default: [];
+  };
+}
+
+export const Form: TOC<Signature> = <template>
+  <form
+    {{on "input" (fn handleInput @onChange)}}
+    {{on "submit" (fn handleSubmit @onChange)}}
+    ...attributes
+  >
+    {{yield}}
+  </form>
+</template>;
+
+export default Form;

package/src/components/heading.gts

@@ -0,0 +1,36 @@
+import Component from "@glimmer/component";
+
+import { element } from "ember-element-helper";
+import { getSectionHeadingLevel } from "which-heading-do-i-need";
+
+import type Owner from "@ember/owner";
+
+export class Heading extends Component<{
+  Element: HTMLElement;
+  Blocks: { default: [] };
+}> {
+  headingScopeAnchor: Text;
+  constructor(owner: Owner, args: object) {
+    super(owner, args);
+
+    this.headingScopeAnchor = document.createTextNode("");
+  }
+
+  get level() {
+    return getSectionHeadingLevel(this.headingScopeAnchor);
+  }
+
+  get hLevel() {
+    return `h${this.level}`;
+  }
+
+  <template>
+    {{this.headingScopeAnchor}}
+
+    {{#let (element this.hLevel) as |El|}}
+      <El ...attributes>
+        {{yield}}
+      </El>
+    {{/let}}
+  </template>
+}

package/src/components/keys.gts

@@ -0,0 +1,53 @@
+import type { TOC } from "@ember/component/template-only";
+
+const isLast = (collection: unknown[], index: number) => index === collection.length - 1;
+const isNotLast = (collection: unknown[], index: number) => !isLast(collection, index);
+const isMac = navigator.userAgent.indexOf("Mac OS") >= 0;
+
+function split(str: string) {
+  const keys = str.split("+").map((x) => x.trim());
+
+  return keys;
+}
+
+function getKeys(keys: string[] | string, mac?: string[] | string) {
+  const normalKeys = Array.isArray(keys) ? keys : split(keys);
+
+  if (!mac) {
+    return normalKeys;
+  }
+
+  const normalMac = Array.isArray(mac) ? mac : split(mac);
+
+  return isMac ? normalMac : normalKeys;
+}
+
+export interface KeyComboSignature {
+  Element: HTMLElement;
+  Args: {
+    keys: string[] | string;
+    mac?: string[] | string;
+  };
+}
+
+export const KeyCombo: TOC<KeyComboSignature> = <template>
+  <span class="ember-primitives__key-combination" ...attributes>
+    {{#let (getKeys @keys @mac) as |keys|}}
+      {{#each keys as |key i|}}
+        <Key>{{key}}</Key>
+        {{#if (isNotLast keys i)}}
+          <span class="ember-primitives__key-combination__separator">+</span>
+        {{/if}}
+      {{/each}}
+    {{/let}}
+  </span>
+</template>;
+
+export interface KeySignature {
+  Element: HTMLElement;
+  Blocks: { default?: [] };
+}
+
+export const Key: TOC<KeySignature> = <template>
+  <kbd class="ember-primitives__key" ...attributes>{{yield}}</kbd>
+</template>;

package/src/components/layout/hero.css

@@ -0,0 +1,5 @@
+.ember-primitives__hero__wrapper {
+  width: 100dvw;
+  height: 100dvh;
+  position: relative;
+}

package/src/components/layout/hero.gts

@@ -0,0 +1,17 @@
+import "./hero.css";
+
+import type { TOC } from "@ember/component/template-only";
+
+export const Hero: TOC<{
+  /**
+   * The wrapper element of the whole layout.
+   */
+  Element: HTMLDivElement;
+  Blocks: {
+    default: [];
+  };
+}> = <template>
+  <div class="ember-primitives__hero__wrapper" ...attributes>
+    {{yield}}
+  </div>
+</template>;

package/src/components/layout/sticky-footer.css

@@ -0,0 +1,9 @@
+.ember-primitives__sticky-footer__wrapper {
+  height: 100%;
+  overflow: auto;
+}
+.ember-primitives__sticky-footer__container {
+  min-height: 100%;
+  display: grid;
+  grid-template-rows: 1fr auto;
+}

package/src/components/layout/sticky-footer.gts

@@ -0,0 +1,40 @@
+import "./sticky-footer.css";
+
+import type { TOC } from "@ember/component/template-only";
+
+export const StickyFooter: TOC<{
+  /**
+   * The wrapper element of the whole layout.
+   * Valid parents for this element must have either a set height,
+   * or a set max-height.
+   */
+  Element: HTMLDivElement;
+  Blocks: {
+    /**
+     * This is the scrollable content, contained within a `<div>` element for positioning.
+     * If this component is used as the main layout on a page,
+     * the `<main>` element would be appropriate within here.
+     */
+    content: [];
+    /**
+     * This is the footer content, contained within a `<div>` element for positioning.
+     * A `<footer>` element would be appropriate within here.
+     *
+     * This element will be at the bottom of the page if the content does not overflow the containing element and this element will be at the bottom of the content if there is overflow.
+     */
+    footer: [];
+  };
+}> = <template>
+  <div class="ember-primitives__sticky-footer__wrapper" ...attributes>
+    <div class="ember-primitives__sticky-footer__container">
+      <div class="ember-primitives__sticky-footer__content">
+        {{yield to="content"}}
+      </div>
+      <div class="ember-primitives__sticky-footer__footer">
+        {{yield to="footer"}}
+      </div>
+    </div>
+  </div>
+</template>;
+
+export default StickyFooter;