ember-primitives 0.48.2 → 0.50.0

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;

package/src/components/progress.gts

@@ -0,0 +1,154 @@
+import Component from "@glimmer/component";
+import { hash } from "@ember/helper";
+
+import type { TOC } from "@ember/component/template-only";
+import type { WithBoundArgs } from "@glint/template";
+
+export interface Signature {
+  Element: HTMLDivElement;
+  Args: {
+    /**
+     * The current progress
+     * This may be less than 0 or more than `max`,
+     * but the resolved value (managed internally, and yielded out)
+     * does not exceed the range [0, max]
+     */
+    value: number;
+    /**
+     * The max value, defaults to 100
+     */
+    max?: number;
+  };
+  Blocks: {
+    default: [
+      {
+        /**
+         * The indicator element with some state applied.
+         * This can be used to style the progress of bar.
+         */
+        Indicator: WithBoundArgs<typeof Indicator, "value" | "max" | "percent">;
+        /**
+         * The value as a percent of how far along the indicator should be
+         * positioned, between 0 and 100.
+         * Will be rounded to two decimal places.
+         */
+        percent: number;
+        /**
+         * The value as a percent of how far along the indicator should be positioned,
+         * between 0 and 1
+         */
+        decimal: number;
+        /**
+         * The resolved value within the limits of the progress bar.
+         */
+        value: number;
+      },
+    ];
+  };
+}
+
+type ProgressState = "indeterminate" | "complete" | "loading";
+
+const DEFAULT_MAX = 100;
+
+/**
+ * Non-negative, non-NaN, non-Infinite, positive, rational
+ */
+function isValidProgressNumber(value: number | undefined | null): value is number {
+  if (typeof value !== "number") return false;
+  if (!Number.isFinite(value)) return false;
+
+  return value >= 0;
+}
+
+function progressState(value: number | undefined | null, maxValue: number): ProgressState {
+  return value == null ? "indeterminate" : value === maxValue ? "complete" : "loading";
+}
+
+function getMax(userMax: number | undefined | null): number {
+  return isValidProgressNumber(userMax) ? userMax : DEFAULT_MAX;
+}
+
+function getValue(userValue: number | undefined | null, maxValue: number): number {
+  const max = getMax(maxValue);
+
+  if (!isValidProgressNumber(userValue)) {
+    return 0;
+  }
+
+  if (userValue > max) {
+    return max;
+  }
+
+  return userValue;
+}
+
+function getValueLabel(value: number, max: number) {
+  return `${Math.round((value / max) * 100)}%`;
+}
+
+const Indicator: TOC<{
+  Element: HTMLDivElement;
+  Args: { max: number; value: number; percent: number };
+  Blocks: { default: [] };
+}> = <template>
+  <div
+    ...attributes
+    data-max={{@max}}
+    data-value={{@value}}
+    data-state={{progressState @value @max}}
+    data-percent={{@percent}}
+  >
+    {{yield}}
+  </div>
+</template>;
+
+export class Progress extends Component<Signature> {
+  get max() {
+    return getMax(this.args.max);
+  }
+
+  get value() {
+    return getValue(this.args.value, this.max);
+  }
+
+  get valueLabel() {
+    return getValueLabel(this.value, this.max);
+  }
+
+  get decimal() {
+    return this.value / this.max;
+  }
+
+  get percent() {
+    return Math.round(this.decimal * 100 * 100) / 100;
+  }
+
+  <template>
+    <div
+      ...attributes
+      aria-valuemax={{this.max}}
+      aria-valuemin="0"
+      aria-valuenow={{this.value}}
+      aria-valuetext={{this.valueLabel}}
+      role="progressbar"
+      data-value={{this.value}}
+      data-state={{progressState this.value this.max}}
+      data-max={{this.max}}
+      data-min="0"
+      data-percent={{this.percent}}
+    >
+
+      {{yield
+        (hash
+          Indicator=(component Indicator value=this.value max=this.max percent=this.percent)
+          value=this.value
+          percent=this.percent
+          decimal=this.decimal
+        )
+      }}
+    </div>
+  </template>
+}
+
+export default Progress;

package/src/components/rating/public-types.ts

@@ -0,0 +1,44 @@
+import type { ComponentLike } from '@glint/template';
+
+/**
+ * @public
+ */
+export interface ComponentIcons {
+  /**
+   * It's possible to completely manage the state of an individual Icon yourself
+   * by passing a component that has ...attributes on its outer element and receives
+   * a @isSelected argument which is true for selected and false for unselected.
+   *
+   * There is also argument passed which is the percent-amount of selection if you want fractional ratings, @selectedPercent
+   */
+  icon: ComponentLike<{
+    Element: HTMLElement;
+    Args: {
+      /**
+       * Is this item selected?
+       */
+      isSelected: boolean;
+      /**
+       * Which number of item is this item within the overall rating group.
+       */
+      value: number;
+      /**
+       * Should this be marked as readonly
+       */
+      readonly: boolean;
+    };
+  }>;
+}
+
+/**
+ * @public
+ */
+export interface StringIcons {
+  /**
+   * The symbol to use for an unselected variant of the icon
+   *
+   * Defaults to "★";
+   *  Can change color when selected.
+   */
+  icon?: string;
+}

package/src/components/rating/range.gts

@@ -0,0 +1,22 @@
+import { on } from "@ember/modifier";
+
+import type { TOC } from "@ember/component/template-only";
+
+export const RatingRange: TOC<{
+  Element: HTMLInputElement;
+  Args: {
+    name: string;
+    max: number;
+    value: number;
+    handleChange: (event: Event) => void;
+  };
+}> = <template>
+  <input
+    ...attributes
+    name={{@name}}
+    type="range"
+    max={{@max}}
+    value={{@value}}
+    {{on "change" @handleChange}}
+  />
+</template>;