ember-primitives 0.49.0 → 0.50.0

package/src/floating-ui/component.gts

@@ -0,0 +1,186 @@
+import Component from "@glimmer/component";
+import { tracked } from "@glimmer/tracking";
+import { hash } from "@ember/helper";
+
+import { modifier as eModifier } from "ember-modifier";
+
+import { anchorTo } from "./modifier.ts";
+
+import type { Signature as ModifierSignature } from "./modifier.ts";
+import type { MiddlewareState } from "@floating-ui/dom";
+import type { ModifierLike } from "@glint/template";
+
+type ModifierArgs = ModifierSignature["Args"]["Named"];
+
+interface ReferenceSignature {
+  Element: HTMLElement | SVGElement;
+}
+
+export interface Signature {
+  Args: {
+    /**
+     * Additional middleware to pass to FloatingUI.
+     *
+     * See: [The middleware docs](https://floating-ui.com/docs/middleware)
+     */
+    middleware?: ModifierArgs["middleware"];
+    /**
+     * Where to place the floating element relative to its reference element.
+     * The default is 'bottom'.
+     *
+     * See: [The placement docs](https://floating-ui.com/docs/computePosition#placement)
+     */
+    placement?: ModifierArgs["placement"];
+    /**
+     * This is the type of CSS position property to use.
+     * By default this is 'fixed', but can also be 'absolute'.
+     *
+     * See: [The strategy docs](https://floating-ui.com/docs/computePosition#strategy)
+     */
+    strategy?: ModifierArgs["strategy"];
+    /**
+     * Options to pass to the [flip middleware](https://floating-ui.com/docs/flip)
+     */
+    flipOptions?: ModifierArgs["flipOptions"];
+    /**
+     * Options to pass to the [hide middleware](https://floating-ui.com/docs/hide)
+     */
+    hideOptions?: ModifierArgs["hideOptions"];
+    /**
+     * Options to pass to the [shift middleware](https://floating-ui.com/docs/shift)
+     */
+    shiftOptions?: ModifierArgs["shiftOptions"];
+    /**
+     * Options to pass to the [offset middleware](https://floating-ui.com/docs/offset)
+     */
+    offsetOptions?: ModifierArgs["offsetOptions"];
+  };
+  Blocks: {
+    default: [
+      /**
+       * A modifier to apply to the _reference_ element.
+       * This is what the floating element will use to anchor to.
+       *
+       * Example
+       * ```gjs
+       * import { FloatingUI } from 'ember-primitives/floating-ui';
+       *
+       * <template>
+       *   <FloatingUI as |reference floating|>
+       *     <button {{reference}}> ... </button>
+       *     ...
+       *   </FloatingUI>
+       * </template>
+       * ```
+       */
+      reference: ModifierLike<ReferenceSignature>,
+      /**
+       * A modifier to apply to the _floating_ element.
+       * This is what will anchor to the reference element.
+       *
+       * Example
+       * ```gjs
+       * import { FloatingUI } from 'ember-primitives/floating-ui';
+       *
+       * <template>
+       *   <FloatingUI as |reference floating|>
+       *     <button {{reference}}> ... </button>
+       *     <menu {{floating}}> ... </menu>
+       *   </FloatingUI>
+       * </template>
+       * ```
+       */
+      floating:
+        | undefined
+        | ModifierLike<{
+            Element: HTMLElement;
+            Args: {
+              Named: ModifierArgs;
+            };
+          }>,
+      /**
+       * Special utilities for advanced usage
+       */
+      util: {
+        /**
+         * If you want to have a single modifier with custom behavior
+         * on your reference element, you may use this `setReference`
+         * function to set the reference, rather than having multiple modifiers
+         * on that element.
+         */
+        setReference: (element: HTMLElement | SVGElement) => void;
+        /**
+         * Metadata exposed from floating-ui.
+         * Gives you x, y position, among other things.
+         */
+        data?: MiddlewareState;
+      },
+    ];
+  };
+}
+
+const ref = eModifier<{
+  Element: HTMLElement | SVGElement;
+  Args: {
+    Positional: [setRef: (element: HTMLElement | SVGElement) => void];
+  };
+}>((element: HTMLElement | SVGElement, positional) => {
+  const fn = positional[0];
+
+  fn(element);
+});
+
+/**
+ * A component that provides no DOM and yields two modifiers for creating
+ * creating floating uis, such as menus, popovers, tooltips, etc.
+ * This component currently uses [Floating UI](https://floating-ui.com/)
+ * but will be switching to [CSS Anchor Positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning) when that lands.
+ *
+ * Example usage:
+ * ```gjs
+ * import { FloatingUI } from 'ember-primitives/floating-ui';
+ *
+ * <template>
+ *   <FloatingUI as |reference floating|>
+ *     <button {{reference}}> ... </button>
+ *     <menu {{floating}}> ... </menu>
+ *   </FloatingUI>
+ * </template>
+ * ```
+ */
+export class FloatingUI extends Component<Signature> {
+  @tracked reference?: HTMLElement | SVGElement = undefined;
+  @tracked data?: MiddlewareState = undefined;
+
+  setData: ModifierArgs["setData"] = (data) => (this.data = data);
+
+  setReference = (element: HTMLElement | SVGElement) => {
+    this.reference = element;
+  };
+
+  <template>
+    {{#let
+      (modifier
+        anchorTo
+        flipOptions=@flipOptions
+        hideOptions=@hideOptions
+        middleware=@middleware
+        offsetOptions=@offsetOptions
+        placement=@placement
+        shiftOptions=@shiftOptions
+        strategy=@strategy
+        setData=this.setData
+      )
+      as |prewiredAnchorTo|
+    }}
+      {{#let (if this.reference (modifier prewiredAnchorTo this.reference)) as |floating|}}
+        {{! @glint-nocheck -- Excessively deep, possibly infinite }}
+        {{yield
+          (modifier ref this.setReference)
+          floating
+          (hash setReference=this.setReference data=this.data)
+        }}
+      {{/let}}
+    {{/let}}
+  </template>
+}

package/src/floating-ui/middleware.ts

@@ -0,0 +1,13 @@
+import type { Middleware } from '@floating-ui/dom';
+
+export function exposeMetadata(): Middleware {
+  return {
+    name: 'metadata',
+    fn: (data) => {
+      // https://floating-ui.com/docs/middleware#always-return-an-object
+      return {
+        data,
+      };
+    },
+  };
+}

package/src/floating-ui/modifier.ts

@@ -0,0 +1,183 @@
+import { assert } from '@ember/debug';
+
+import { autoUpdate, computePosition, flip, hide, offset, shift } from '@floating-ui/dom';
+import { modifier as eModifier } from 'ember-modifier';
+
+import { exposeMetadata } from './middleware.ts';
+
+import type {
+  FlipOptions,
+  HideOptions,
+  Middleware,
+  OffsetOptions,
+  Placement,
+  ShiftOptions,
+  Strategy,
+} from '@floating-ui/dom';
+
+export interface Signature {
+  /**
+   *
+   */
+  Element: HTMLElement;
+  Args: {
+    Positional: [
+      /**
+       * What do use as the reference element.
+       * Can be a selector or element instance.
+       *
+       * Example:
+       * ```gjs
+       * import { anchorTo } from 'ember-primitives/floating-ui';
+       *
+       * <template>
+       *   <div id="reference">...</div>
+       *   <div {{anchorTo "#reference"}}> ... </div>
+       * </template>
+       * ```
+       */
+      referenceElement: string | HTMLElement | SVGElement,
+    ];
+    Named: {
+      /**
+       * This is the type of CSS position property to use.
+       * By default this is 'fixed', but can also be 'absolute'.
+       *
+       * See: [The strategy docs](https://floating-ui.com/docs/computePosition#strategy)
+       */
+      strategy?: Strategy;
+      /**
+       * Options to pass to the [offset middleware](https://floating-ui.com/docs/offset)
+       */
+      offsetOptions?: OffsetOptions;
+      /**
+       * Where to place the floating element relative to its reference element.
+       * The default is 'bottom'.
+       *
+       * See: [The placement docs](https://floating-ui.com/docs/computePosition#placement)
+       */
+      placement?: Placement;
+      /**
+       * Options to pass to the [flip middleware](https://floating-ui.com/docs/flip)
+       */
+      flipOptions?: FlipOptions;
+      /**
+       * Options to pass to the [shift middleware](https://floating-ui.com/docs/shift)
+       */
+      shiftOptions?: ShiftOptions;
+      /**
+       * Options to pass to the [hide middleware](https://floating-ui.com/docs/hide)
+       */
+      hideOptions?: HideOptions;
+      /**
+       * Additional middleware to pass to FloatingUI.
+       *
+       * See: [The middleware docs](https://floating-ui.com/docs/middleware)
+       */
+      middleware?: Middleware[];
+      /**
+       * A callback for when data changes about the position / placement / etc
+       * of the floating element.
+       */
+      setData?: Middleware['fn'];
+    };
+  };
+}
+
+/**
+ * A modifier to apply to the _floating_ element.
+ * This is what will anchor to the reference element.
+ *
+ * Example
+ * ```gjs
+ * import { anchorTo } from 'ember-primitives/floating-ui';
+ *
+ * <template>
+ *   <button id="my-button"> ... </button>
+ *   <menu {{anchorTo "#my-button"}}> ... </menu>
+ * </template>
+ * ```
+ */
+export const anchorTo = eModifier<Signature>(
+  (
+    floatingElement,
+    [_referenceElement],
+    {
+      strategy = 'fixed',
+      offsetOptions = 0,
+      placement = 'bottom',
+      flipOptions,
+      shiftOptions,
+      middleware = [],
+      setData,
+    }
+  ) => {
+    const referenceElement: null | HTMLElement | SVGElement =
+      typeof _referenceElement === 'string'
+        ? document.querySelector(_referenceElement)
+        : _referenceElement;
+
+    assert(
+      'no reference element defined',
+      referenceElement instanceof HTMLElement || referenceElement instanceof SVGElement
+    );
+
+    assert(
+      'no floating element defined',
+      floatingElement instanceof HTMLElement || _referenceElement instanceof SVGElement
+    );
+
+    assert(
+      'reference and floating elements cannot be the same element',
+      floatingElement !== _referenceElement
+    );
+
+    assert('@middleware must be an array of one or more objects', Array.isArray(middleware));
+
+    Object.assign(floatingElement.style, {
+      position: strategy,
+      top: '0',
+      left: '0',
+    });
+
+    const update = async () => {
+      const { middlewareData, x, y } = await computePosition(referenceElement, floatingElement, {
+        middleware: [
+          offset(offsetOptions),
+          flip(flipOptions),
+          shift(shiftOptions),
+          ...middleware,
+          hide({ strategy: 'referenceHidden' }),
+          hide({ strategy: 'escaped' }),
+          exposeMetadata(),
+        ],
+        placement,
+        strategy,
+      });
+
+      const referenceHidden = middlewareData.hide?.referenceHidden;
+
+      Object.assign(floatingElement.style, {
+        top: `${y}px`,
+        left: `${x}px`,
+        margin: 0,
+        visibility: referenceHidden ? 'hidden' : 'visible',
+      });
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      void setData?.(middlewareData['metadata']);
+    };
+
+    void update();
+
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises
+    const cleanup = autoUpdate(referenceElement, floatingElement, update);
+
+    /**
+     * in the function-modifier manager, teardown of the previous modifier
+     * occurs before setup of the next
+     * https://github.com/ember-modifier/ember-modifier/blob/main/ember-modifier/src/-private/function-based/modifier-manager.ts#L58
+     */
+    return cleanup;
+  }
+);

package/src/floating-ui.ts

@@ -0,0 +1,2 @@
+export { FloatingUI } from './floating-ui/component.gts';
+export { anchorTo } from './floating-ui/modifier.ts';

package/src/head.gts

@@ -0,0 +1,37 @@
+import type { TOC } from "@ember/component/template-only";
+
+export interface Signature {
+  Blocks: {
+    /**
+     * Content to render in to the `<head>` element
+     */
+    default: [];
+  };
+}
+
+function getHead() {
+  return document.head;
+}
+
+/**
+ * Utility component to place elements in the document `<head>`
+ *
+ * When this component is unrendered, its contents will be removed as well.
+ *
+ * @example
+ * ```js
+ * import { InHead } from 'ember-primitives/head';
+ *
+ * <template>
+ *   {{#if @useBootstrap}}
+ *     <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.7/dist/js/bootstrap.bundle.min.js"></script>
+ *     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.7/dist/css/bootstrap.min.css">
+ *   {{/if}}
+ * </template>
+ * ```
+ */
+export const InHead: TOC<Signature> = <template>
+  {{#in-element (getHead) insertBefore=null}}
+    {{yield}}
+  {{/in-element}}
+</template>;

package/src/helpers/body-class.ts

@@ -0,0 +1,94 @@
+/**
+ * Initial inspo:
+ * - https://github.com/ef4/ember-set-body-class/blob/master/addon/services/body-class.js
+ * - https://github.com/ef4/ember-set-body-class/blob/master/addon/helpers/set-body-class.js
+ */
+import Helper from '@ember/component/helper';
+import { buildWaiter } from '@ember/test-waiters';
+
+const waiter = buildWaiter('ember-primitives:body-class:raf');
+
+let id = 0;
+const registrations = new Map<number, string[]>();
+let previousRegistrations: string[] = [];
+
+function classNames(): string[] {
+  const allNames = new Set<string>();
+
+  for (const classNames of registrations.values()) {
+    for (const className of classNames) {
+      allNames.add(className);
+    }
+  }
+
+  return [...allNames];
+}
+
+let frame: number;
+let waiterToken: unknown;
+
+function queueUpdate() {
+  waiterToken ||= waiter.beginAsync();
+
+  cancelAnimationFrame(frame);
+  frame = requestAnimationFrame(() => {
+    updateBodyClass();
+    waiter.endAsync(waiterToken);
+    waiterToken = undefined;
+  });
+}
+
+/**
+ * This should only add/remove classes that we tried to maintain via the body-class helper.
+ *
+ * Folks can set classes in their html and we don't want to mess with those
+ */
+function updateBodyClass() {
+  const toAdd = classNames();
+
+  for (const name of previousRegistrations) {
+    document.body.classList.remove(name);
+  }
+
+  for (const name of toAdd) {
+    document.body.classList.add(name);
+  }
+
+  previousRegistrations = toAdd;
+}
+
+export interface Signature {
+  Args: {
+    Positional: [
+      /**
+       * a space-delimited list of classes to apply when this helper is called.
+       *
+       * When the helper is removed from rendering, the clasess will be removed as well.
+       */
+      classes: string,
+    ];
+  };
+  /**
+   * This helper returns nothing, as it is a side-effect that mutates and manages external state.
+   */
+  Return: undefined;
+}
+
+export default class BodyClass extends Helper<Signature> {
+  localId = id++;
+
+  compute([classes]: [string]): undefined {
+    const classNames = classes ? classes.split(/\s+/) : [];
+
+    registrations.set(this.localId, classNames);
+
+    queueUpdate();
+  }
+
+  willDestroy() {
+    registrations.delete(this.localId);
+    queueUpdate();
+  }
+}
+
+export const bodyClass = BodyClass;

package/src/helpers/link.ts

@@ -0,0 +1,125 @@
+import Helper from '@ember/component/helper';
+import { assert } from '@ember/debug';
+import { service } from '@ember/service';
+
+import { handle } from '../proper-links.ts';
+
+import type RouterService from '@ember/routing/router-service';
+
+export interface Signature {
+  Args: {
+    Positional: [href: string];
+    Named: {
+      includeActiveQueryParams?: boolean | string[];
+      activeOnSubPaths?: boolean;
+    };
+  };
+  Return: {
+    isExternal: boolean;
+    isActive: boolean;
+    handleClick: (event: MouseEvent) => void;
+  };
+}
+
+export default class Link extends Helper<Signature> {
+  @service declare router: RouterService;
+
+  compute(
+    [href]: [href: string],
+    {
+      includeActiveQueryParams = false,
+      activeOnSubPaths = false,
+    }: { includeActiveQueryParams?: boolean | string[]; activeOnSubPaths?: boolean }
+  ) {
+    assert('href was not passed in', href);
+
+    const router = this.router;
+    const handleClick = (event: MouseEvent) => {
+      assert('[BUG]', event.currentTarget instanceof HTMLAnchorElement);
+
+      handle(router, event.currentTarget, [], event);
+    };
+
+    return {
+      isExternal: isExternal(href),
+      get isActive() {
+        return isActive(router, href, includeActiveQueryParams, activeOnSubPaths);
+      },
+      handleClick,
+    };
+  }
+}
+
+export const link = Link;
+
+export function isExternal(href: string) {
+  if (!href) return false;
+  if (href.startsWith('#')) return false;
+  if (href.startsWith('/')) return false;
+
+  return location.origin !== new URL(href).origin;
+}
+
+export function isActive(
+  router: RouterService,
+  href: string,
+  includeQueryParams?: boolean | string[],
+  activeOnSubPaths?: boolean
+) {
+  if (!includeQueryParams) {
+    /**
+     * is Active doesn't understand `href`, so we have to convert to RouteInfo-esque
+     */
+    const info = router.recognize(href);
+
+    if (info) {
+      const dynamicSegments = getParams(info);
+      const routeName = activeOnSubPaths ? info.name.replace(/\.index$/, '') : info.name;
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      return router.isActive(routeName, ...dynamicSegments);
+    }
+
+    return false;
+  }
+
+  const url = new URL(href, location.origin);
+  const hrefQueryParams = new URLSearchParams(url.searchParams);
+  const hrefPath = url.pathname;
+
+  const currentPath = router.currentURL?.split('?')[0];
+
+  if (!currentPath) return false;
+
+  if (activeOnSubPaths ? !currentPath.startsWith(hrefPath) : hrefPath !== currentPath) return false;
+
+  const currentQueryParams = router.currentRoute?.queryParams;
+
+  if (!currentQueryParams) return false;
+
+  if (includeQueryParams === true) {
+    return Object.entries(currentQueryParams).every(([key, value]) => {
+      return hrefQueryParams.get(key) === value;
+    });
+  }
+
+  return includeQueryParams.every((key) => {
+    return hrefQueryParams.get(key) === currentQueryParams[key];
+  });
+}
+
+type RouteInfo = ReturnType<RouterService['recognize']>;
+
+export function getParams(currentRouteInfo: RouteInfo) {
+  let params: Record<string, unknown>[] = [];
+
+  while (currentRouteInfo?.parent) {
+    const currentParams = currentRouteInfo.params;
+
+    params = currentParams ? [currentParams, ...params] : params;
+    currentRouteInfo = currentRouteInfo.parent;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+  return params.map(Object.values).flat();
+}

package/src/helpers/service.ts

@@ -0,0 +1,25 @@
+import Helper from '@ember/component/helper';
+import { assert } from '@ember/debug';
+import { getOwner } from '@ember/owner';
+
+import type { Registry } from '@ember/service';
+import type Service from '@ember/service';
+
+export interface Signature<Key extends keyof Registry> {
+  Args: {
+    Positional: [Key];
+  };
+  Return: Registry[Key] & Service;
+}
+
+export default class GetService<Key extends keyof Registry> extends Helper<Signature<Key>> {
+  compute(positional: [Key]): Registry[Key] & Service {
+    const owner = getOwner(this);
+
+    assert(`Could not get owner.`, owner);
+
+    return owner.lookup(`service:${positional[0]}`) as Registry[Key] & Service;
+  }
+}
+
+export const service = GetService;

package/src/helpers.ts

@@ -0,0 +1,2 @@
+export { link } from './helpers/link.ts';
+export { service } from './helpers/service.ts';

package/src/iframe.ts

@@ -0,0 +1,31 @@
+/**
+ * Returns true if the current frame is within an iframe.
+ *
+ * ```gjs
+ * import { inIframe } from 'ember-primitives/iframe';
+ *
+ * <template>
+ *   {{#if (inFrame)}}
+ *     only show content in an iframe
+ *   {{/if}}
+ * </template>
+ * ```
+ */
+export const inIframe = () => window.self !== window.top;
+
+/**
+ * Returns true if the current frame is not within an iframe.
+ *
+ * ```gjs
+ * import { notInIframe } from 'ember-primitives/iframe';
+ *
+ * <template>
+ *   {{#if (notInIframe)}}
+ *     only show content when not in an iframe
+ *     This is also the default if your site/app
+ *     does not use iframes
+ *   {{/if}}
+ * </template>
+ * ```
+ */
+export const notInIframe = () => !inIframe();