ember-primitives 0.48.2 → 0.50.0

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;

package/src/components/link.gts

@@ -0,0 +1,172 @@
+/**
+ * TODO: make template-only component,
+ * and use class-based modifier?
+ *
+ * This would require that modifiers could run pre-render
+ */
+import { hash } from '@ember/helper';
+import { on } from '@ember/modifier';
+
+import { link } from '../helpers/link.ts';
+import { ExternalLink } from './external-link.gts';
+
+import type { TOC } from '@ember/component/template-only';
+
+export interface Signature {
+  Element: HTMLAnchorElement;
+  Args: {
+    /**
+     * the `href` string value to set on the anchor element.
+     */
+    href: string;
+    /**
+     * When calculating the "active" state of the link, you may decide
+     * whether or not you want to _require_ that all query params be considered (true)
+     * or specify individual query params, ignoring anything not specified.
+     *
+     * For example:
+     *
+     * ```gjs live preview
+     * import { Link } from 'ember-primitives';
+     *
+     * <template>
+     *   <Link @href="/" @includeActiveQueryParams={{true}} as |a|>
+     *     ...
+     *   </Link>
+     * </template>
+     * ```
+     *
+     * the data-active state here will only be "true" on
+     * - `/`
+     * - `/?foo=2`
+     * - `/?foo=&bar=`
+     *
+     */
+    includeActiveQueryParams?: true | string[];
+    /**
+     * When calculating the "active" state of the link, you may decide
+     * whether or not you want to consider sub paths to be active when
+     * child routes/urls are active.
+     *
+     * For example:
+     *
+     * ```gjs live preview
+     * import { Link } from 'ember-primitives';
+     *
+     * <template>
+     *   <Link @href="/forum/1" @activeOnSubPaths={{true}} as |a|>
+     *     ...
+     *   </Link>
+     * </template>
+     * ```
+     *
+     * the data-active state here will be "true" on
+     * - `/forum/1`
+     * - `/forum/1/posts`
+     * - `/forum/1/posts/comments`
+     * - `/forum/1/*etc*`
+     *
+     * if `@activeOnSubPaths` is set to false or left off
+     * the data-active state here will only be "true" on
+     * - `/forum/1`
+     *
+     */
+    activeOnSubPaths?: true;
+  };
+  Blocks: {
+    default: [
+      {
+        /**
+         * Indicates if the passed `href` is pointing to an external site.
+         * Useful if you want your links to have additional context for when
+         * a user is about to leave your site.
+         *
+         * For example:
+         *
+         * ```gjs live preview
+         * import { Link } from 'ember-primitives';
+         *
+         * const MyLink = <template>
+         *   <Link @href={{@href}} as |a|>
+         *     {{yield}}
+         *     {{#if a.isExternal}}
+         *       ➚
+         *     {{/if}}
+         *   </Link>
+         * </template>;
+         *
+         * <template>
+         *   <MyLink @href="https://developer.mozilla.org">MDN</MyLink> &nbsp;&nbsp;
+         *   <MyLink @href="/">Home</MyLink>
+         *  </template>
+         * ```
+         */
+        isExternal: boolean;
+        /**
+         * Indicates if the passed `href` is *active*, or the user is on the same basepath.
+         * This allows consumers to style their link if they wish or style their text.
+         * The active state will also be present on a `data-active` attribute on the generated anchor tag.
+         *
+         *
+         * For example
+         * ```gjs
+         * import { Link, service } from 'ember-primitives';
+         *
+         * const MyLink = <template>
+         *   <Link @href="..."> as |a|>
+         *     <span class="{{if a.isActive 'underline'}}">
+         *     {{yield}}
+         *     </span>
+         *   </Link>
+         * </template>
+         *
+         * <template>
+         * {{#let (service 'router') as |router|}}
+         *     <MyLink @href={{router.currentURL}}>Ths page</MyLink> &nbsp;&nbsp;
+         *     <MyLink @href="/">Home</MyLink>
+         *   {{/let}}
+         *  </template>
+         * ```
+         *
+         * By default, the query params are omitted from `isActive` calculation, but you may
+         * configure the query params to be included if you wish
+         * See: `@includeActiveQueryParams`
+         *
+         * By default, only the exact route/url is considered for the `isActive` calculation,
+         * but you may configure sub routes/paths to also be considered active
+         * See: `@activeOnSubPaths`
+         *
+         * Note that external links are never active.
+         */
+        isActive: boolean;
+      },
+    ];
+  };
+}
+
+/**
+ * A light wrapper around the [Anchor element][mdn-a], which will appropriately make your link an external link if the passed `@href` is not on the same domain.
+ *
+ *
+ * [mdn-a]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a
+ */
+export const Link: TOC<Signature> = <template>
+  {{#let (link @href includeActiveQueryParams=@includeActiveQueryParams activeOnSubPaths=@activeOnSubPaths) as |l|}}
+    {{#if l.isExternal}}
+      <ExternalLink href={{@href}} ...attributes>
+        {{yield (hash isExternal=true isActive=false)}}
+      </ExternalLink>
+    {{else}}
+      <a
+        data-active={{l.isActive}}
+        href={{if @href @href "##missing##"}}
+        {{on "click" l.handleClick}}
+        ...attributes
+      >
+        {{yield (hash isExternal=false isActive=l.isActive)}}
+      </a>
+    {{/if}}
+  {{/let}}
+</template>;
+
+export default Link;