ember-primitives 0.49.0 → 0.50.1

package/src/components/popover.gts

@@ -0,0 +1,248 @@
+import { hash } from "@ember/helper";
+
+import { arrow } from "@floating-ui/dom";
+import { element } from "ember-element-helper";
+import { modifier as eModifier } from "ember-modifier";
+import { cell } from "ember-resources";
+
+import { FloatingUI } from "../floating-ui.ts";
+import { Portal } from "./portal.gts";
+import { TARGETS } from "./portal-targets.gts";
+
+import type { Signature as FloatingUiComponentSignature } from "../floating-ui/component.ts";
+import type { Signature as HookSignature } from "../floating-ui/modifier.ts";
+import type { TOC } from "@ember/component/template-only";
+import type { ElementContext, Middleware } from "@floating-ui/dom";
+import type { ModifierLike, WithBoundArgs } from "@glint/template";
+
+export interface Signature {
+  Args: {
+    /**
+     * See the Floating UI's [flip docs](https://floating-ui.com/docs/flip) for possible values.
+     *
+     * This argument is forwarded to the `<FloatingUI>` component.
+     */
+    flipOptions?: HookSignature["Args"]["Named"]["flipOptions"];
+    /**
+     * Array of one or more objects to add to Floating UI's list of [middleware](https://floating-ui.com/docs/middleware)
+     *
+     * This argument is forwarded to the `<FloatingUI>` component.
+     */
+    middleware?: HookSignature["Args"]["Named"]["middleware"];
+    /**
+     * See the Floating UI's [offset docs](https://floating-ui.com/docs/offset) for possible values.
+     *
+     * This argument is forwarded to the `<FloatingUI>` component.
+     */
+    offsetOptions?: HookSignature["Args"]["Named"]["offsetOptions"];
+    /**
+     * One of the possible [`placements`](https://floating-ui.com/docs/computeposition#placement). The default is 'bottom'.
+     *
+     * Possible values are
+     * - top
+     * - bottom
+     * - right
+     * - left
+     *
+     * And may optionally have `-start` or `-end` added to adjust position along the side.
+     *
+     * This argument is forwarded to the `<FloatingUI>` component.
+     */
+    placement?: `${"top" | "bottom" | "left" | "right"}${"" | "-start" | "-end"}`;
+    /**
+     * See the Floating UI's [shift docs](https://floating-ui.com/docs/shift) for possible values.
+     *
+     * This argument is forwarded to the `<FloatingUI>` component.
+     */
+    shiftOptions?: HookSignature["Args"]["Named"]["shiftOptions"];
+    /**
+     * CSS position property, either `fixed` or `absolute`.
+     *
+     * Pros and cons of each strategy are explained on [Floating UI's Docs](https://floating-ui.com/docs/computePosition#strategy)
+     *
+     * This argument is forwarded to the `<FloatingUI>` component.
+     */
+    strategy?: HookSignature["Args"]["Named"]["strategy"];
+
+    /**
+     * By default, the popover is portaled.
+     * If you don't control your CSS, and the positioning of the popover content
+     * is misbehaving, you may pass "@inline={{true}}" to opt out of portalling.
+     *
+     * Inline may also be useful in nested menus, where you know exactly how the nesting occurs
+     */
+    inline?: boolean;
+  };
+  Blocks: {
+    default: [
+      {
+        reference: FloatingUiComponentSignature["Blocks"]["default"][0];
+        setReference: FloatingUiComponentSignature["Blocks"]["default"][2]["setReference"];
+        Content: WithBoundArgs<typeof Content, "floating">;
+        data: FloatingUiComponentSignature["Blocks"]["default"][2]["data"];
+        arrow: ModifierLike<{ Element: HTMLElement }>;
+      },
+    ];
+  };
+}
+
+function getElementTag(tagName: undefined | string) {
+  return tagName || "div";
+}
+
+/**
+ * Allows lazy evaluation of the portal target (do nothing until rendered)
+ * This is useful because the algorithm for finding the portal target isn't cheap.
+ */
+const Content: TOC<{
+  Element: HTMLDivElement;
+  Args: {
+    floating: ModifierLike<{ Element: HTMLElement }>;
+    inline?: boolean;
+    /**
+     * By default the popover content is wrapped in a div.
+     * You may change this by supplying the name of an element here.
+     *
+     * For example:
+     * ```gjs
+     * <Popover as |p|>
+     *  <p.Content @as="dialog">
+     *    this is now focus trapped
+     *  </p.Content>
+     * </Popover>
+     * ```
+     */
+    as?: string;
+  };
+  Blocks: { default: [] };
+}> = <template>
+  {{#let (element (getElementTag @as)) as |El|}}
+    {{#if @inline}}
+      {{! @glint-ignore
+            https://github.com/tildeio/ember-element-helper/issues/91
+            https://github.com/typed-ember/glint/issues/610
+      }}
+      <El {{@floating}} ...attributes>
+        {{yield}}
+      </El>
+    {{else}}
+      <Portal @to={{TARGETS.popover}}>
+        {{! @glint-ignore
+              https://github.com/tildeio/ember-element-helper/issues/91
+              https://github.com/typed-ember/glint/issues/610
+        }}
+        <El {{@floating}} ...attributes>
+          {{yield}}
+        </El>
+      </Portal>
+    {{/if}}
+  {{/let}}
+</template>;
+
+interface AttachArrowSignature {
+  Element: HTMLElement;
+  Args: {
+    Named: {
+      arrowElement: ReturnType<typeof ArrowElement>;
+      data:
+        | undefined
+        | {
+            placement: string;
+            middlewareData?: {
+              arrow?: { x?: number; y?: number };
+            };
+          };
+    };
+  };
+}
+
+const arrowSides = {
+  top: "bottom",
+  right: "left",
+  bottom: "top",
+  left: "right",
+};
+
+type Direction = "top" | "bottom" | "left" | "right";
+type Placement = `${Direction}${"" | "-start" | "-end"}`;
+
+const attachArrow: ModifierLike<AttachArrowSignature> = eModifier<AttachArrowSignature>(
+  (element, _: [], named) => {
+    if (element === named.arrowElement.current) {
+      if (!named.data) return;
+      if (!named.data.middlewareData) return;
+
+      const { arrow } = named.data.middlewareData;
+      const { placement } = named.data;
+
+      if (!arrow) return;
+      if (!placement) return;
+
+      const { x: arrowX, y: arrowY } = arrow;
+      const otherSide = (placement as Placement).split("-")[0] as Direction;
+      const staticSide = arrowSides[otherSide];
+
+      Object.assign(named.arrowElement.current.style, {
+        left: arrowX != null ? `${arrowX}px` : "",
+        top: arrowY != null ? `${arrowY}px` : "",
+        right: "",
+        bottom: "",
+        [staticSide]: "-4px",
+      });
+
+      return;
+    }
+
+    void (async () => {
+      await Promise.resolve();
+      named.arrowElement.set(element);
+    })();
+  },
+);
+
+const ArrowElement: () => ReturnType<typeof cell<HTMLElement>> = () => cell<HTMLElement>();
+
+function maybeAddArrow(middleware: Middleware[] | undefined, element: Element | undefined) {
+  const result = [...(middleware || [])];
+
+  if (element) {
+    result.push(arrow({ element }));
+  }
+
+  return result;
+}
+
+function flipOptions(options: HookSignature["Args"]["Named"]["flipOptions"]) {
+  return {
+    elementContext: "reference" as ElementContext,
+    ...options,
+  };
+}
+
+export const Popover: TOC<Signature> = <template>
+  {{#let (ArrowElement) as |arrowElement|}}
+    <FloatingUI
+      @placement={{@placement}}
+      @strategy={{@strategy}}
+      @middleware={{maybeAddArrow @middleware arrowElement.current}}
+      @flipOptions={{flipOptions @flipOptions}}
+      @shiftOptions={{@shiftOptions}}
+      @offsetOptions={{@offsetOptions}}
+      as |reference floating extra|
+    >
+      {{#let (modifier attachArrow arrowElement=arrowElement data=extra.data) as |arrow|}}
+        {{yield
+          (hash
+            reference=reference
+            setReference=extra.setReference
+            Content=(component Content floating=floating inline=@inline)
+            data=extra.data
+            arrow=arrow
+          )
+        }}
+      {{/let}}
+    </FloatingUI>
+  {{/let}}
+</template>;
+
+export default Popover;

package/src/components/portal-targets.gts

@@ -0,0 +1,136 @@
+import { assert } from "@ember/debug";
+import { isDevelopingApp, macroCondition } from "@embroider/macros";
+
+import { modifier } from "ember-modifier";
+import { TrackedMap, TrackedSet } from "tracked-built-ins";
+
+import type { TOC } from "@ember/component/template-only";
+
+const cache = new TrackedMap<string, Set<Element>>();
+
+export const TARGETS = Object.freeze({
+  popover: "ember-primitives__portal-targets__popover",
+  tooltip: "ember-primitives__portal-targets__tooltip",
+  modal: "ember-primitives__portal-targets__modal",
+});
+
+export function findNearestTarget(origin: Element, name: string): Element | undefined {
+  assert(`first argument to \`findNearestTarget\` must be an element`, origin instanceof Element);
+  assert(`second argument to \`findNearestTarget\` must be a string`, typeof name === `string`);
+
+  let element: Element | undefined | null = null;
+
+  let parent = origin.parentNode;
+
+  const manuallyRegisteredSet = cache.get(name);
+  const manuallyRegistered: Element[] | null = manuallyRegisteredSet?.size
+    ? [...manuallyRegisteredSet]
+    : null;
+
+  /**
+   * For use with <PortalTarget @name="hi" />
+   */
+  function findRegistered(host: ParentNode): Element | undefined {
+    return manuallyRegistered?.find((element) => {
+      if (host.contains(element)) {
+        return element;
+      }
+    });
+  }
+
+  const selector = Object.values(TARGETS as Record<string, string>).includes(name)
+    ? `[data-portal-name=${name}]`
+    : name;
+
+  /**
+   * Default portals / non-registered -- here we match a query selector instead of an element
+   */
+  function findDefault(host: ParentNode): Element | undefined {
+    return host.querySelector(selector) as Element;
+  }
+
+  const finder = manuallyRegistered ? findRegistered : findDefault;
+
+  /**
+   * Crawl up the ancestry looking for our portal target
+   */
+  while (!element && parent) {
+    element = finder(parent);
+    if (element) break;
+    parent = parent.parentNode;
+  }
+
+  if (macroCondition(isDevelopingApp())) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    (window as any).prime0 = origin;
+  }
+
+  if (name.startsWith("ember-primitives")) {
+    assert(
+      `Could not find element by the given name: \`${name}\`.` +
+        ` The known names are ` +
+        `${Object.values(TARGETS).join(", ")} ` +
+        `-- but any name will work as long as it is set to the \`data-portal-name\` attribute ` +
+        `(or if the name has been specifically registered via the <PortalTarget /> component). ` +
+        `Double check that the element you're wanting to portal to is rendered. ` +
+        `The element passed to \`findNearestTarget\` is stored on \`window.prime0\` ` +
+        `You can debug in your browser's console via ` +
+        `\`document.querySelector('[data-portal-name="${name}"]')\``,
+      element,
+    );
+  }
+
+  return element ?? undefined;
+}
+
+const register = modifier((element: Element, [name]: [name: string]) => {
+  assert(`@name is required when using <PortalTarget>`, name);
+
+  void (async () => {
+    // Bad TypeScript lint.
+    // eslint-disable-next-line @typescript-eslint/await-thenable
+    await 0;
+
+    let existing = cache.get(name);
+
+    if (!existing) {
+      existing = new TrackedSet<Element>();
+      cache.set(name, existing);
+    }
+
+    existing.add(element);
+  })();
+
+  return () => {
+    cache.delete(name);
+  };
+});
+
+export interface Signature {
+  Element: null;
+}
+
+export const PortalTargets: TOC<Signature> = <template>
+  <div data-portal-name={{TARGETS.popover}}></div>
+  <div data-portal-name={{TARGETS.tooltip}}></div>
+  <div data-portal-name={{TARGETS.modal}}></div>
+</template>;
+
+/**
+ * For manually registering a PortalTarget for use with Portal
+ */
+export const PortalTarget: TOC<{
+  Element: HTMLDivElement;
+  Args: {
+    /**
+     * The name of the PortalTarget
+     *
+     * This exact string may be passed to `Portal`'s `@to` argument.
+     */
+    name: string;
+  };
+}> = <template>
+  <div {{register @name}} ...attributes></div>
+</template>;
+
+export default PortalTargets;

package/src/components/portal.gts

@@ -0,0 +1,194 @@
+import { assert } from "@ember/debug";
+import { schedule } from "@ember/runloop";
+import { buildWaiter } from "@ember/test-waiters";
+
+import { modifier } from "ember-modifier";
+import { cell, resource, resourceFactory } from "ember-resources";
+
+import { isElement } from "../narrowing.ts";
+import { findNearestTarget, type TARGETS } from "./portal-targets.gts";
+
+import type { TOC } from "@ember/component/template-only";
+
+type Targets = (typeof TARGETS)[keyof typeof TARGETS];
+
+interface ToSignature {
+  Args: {
+    to: string;
+    append?: boolean;
+  };
+  Blocks: {
+    default: [];
+  };
+}
+interface ElementSignature {
+  Args: {
+    to: Element;
+    append?: boolean;
+  };
+  Blocks: {
+    default: [];
+  };
+}
+
+export interface Signature {
+  Args: {
+    /**
+     * The name of the PortalTarget to render in to.
+     * This is the value of the `data-portal-name` attribute
+     * of the element you wish to render in to.
+     *
+     * This can also be an Element which pairs nicely with query-utilities such as the platform-native `querySelector`
+     */
+    to?: (Targets | (string & {})) | Element;
+
+    /**
+     * Set to true to append to the portal instead of replace
+     *
+     * Default: false
+     */
+    append?: boolean;
+    /**
+     * For ember-wormhole style behavior, this argument may be an id,
+     * or a selector.
+     * This can also be an element, in which case the behavior is identical to `@to`
+     */
+    wormhole?: string | Element;
+  };
+  Blocks: {
+    /**
+     * The portaled content
+     */
+    default: [];
+  };
+}
+
+/**
+ * Polyfill for ember-wormhole behavior
+ *
+ * Example usage:
+ * ```gjs
+ * import { wormhole, Portal } from 'ember-primitives/components/portal';
+ *
+ * <template>
+ *   <div id="the-portal"></div>
+ *
+ *   <Portal @to={{wormhole "the-portal"}}>
+ *     content renders in the above div
+ *   </Portal>
+ * </template>
+ *
+ * ```
+ */
+export function wormhole(query: string | null | undefined | Element) {
+  assert(`Expected query/element to be truthy.`, query);
+
+  if (isElement(query)) {
+    return query;
+  }
+
+  let found = document.getElementById(query);
+
+  found ??= document.querySelector(query);
+
+  return found;
+}
+
+const anchor = modifier(
+  (element: Element, [to, update]: [string, ReturnType<typeof ElementValue>["set"]]) => {
+    const found = findNearestTarget(element, to);
+
+    update(found);
+  },
+);
+
+const ElementValue = () => cell<Element | ShadowRoot | null | undefined>();
+
+const waiter = buildWaiter("ember-primitives:portal");
+
+function wormholeCompat(selector: string | Element) {
+  const target = wormhole(selector);
+
+  if (target) return target;
+
+  return resource(() => {
+    const target = cell<Element | undefined | null>();
+
+    const token = waiter.beginAsync();
+
+    // eslint-disable-next-line ember/no-runloop
+    schedule("afterRender", () => {
+      const result = wormhole(selector);
+
+      waiter.endAsync(token);
+      target.current = result;
+      assert(
+        `Could not find element with id/selector \`${typeof selector === "string" ? selector : "<Element>"}\``,
+        result,
+      );
+    });
+
+    return () => target.current;
+  });
+}
+
+resourceFactory(wormholeCompat);
+
+export const Portal: TOC<Signature> = <template>
+  {{#if (isElement @to)}}
+    <ToElement @to={{@to}} @append={{@append}}>
+      {{yield}}
+    </ToElement>
+  {{else if @wormhole}}
+    {{#let (wormholeCompat @wormhole) as |target|}}
+      {{#if target}}
+        {{#in-element target insertBefore=null}}
+          {{yield}}
+        {{/in-element}}
+      {{/if}}
+    {{/let}}
+  {{else if @to}}
+    <Nestable @to={{@to}} @append={{@append}}>
+      {{yield}}
+    </Nestable>
+  {{else}}
+    {{assert "either @to or @wormhole is required. Received neither"}}
+  {{/if}}
+</template>;
+
+const ToElement: TOC<ElementSignature> = <template>
+  {{#if @append}}
+    {{#in-element @to insertBefore=null}}
+      {{yield}}
+    {{/in-element}}
+  {{else}}
+    {{#in-element @to}}
+      {{yield}}
+    {{/in-element}}
+  {{/if}}
+</template>;
+
+const Nestable: TOC<ToSignature> = <template>
+  {{#let (ElementValue) as |target|}}
+    {{! This div is always going to be empty,
+          because it'll either find the portal and render content elsewhere,
+          it it won't find the portal and won't render anything.
+      }}
+    {{! template-lint-disable no-inline-styles }}
+    <div style="display:contents;" {{anchor @to target.set}}>
+      {{#if target.current}}
+        {{#if @append}}
+          {{#in-element target.current insertBefore=null}}
+            {{yield}}
+          {{/in-element}}
+        {{else}}
+          {{#in-element target.current}}
+            {{yield}}
+          {{/in-element}}
+        {{/if}}
+      {{/if}}
+    </div>
+  {{/let}}
+</template>;
+
+export default Portal;