ember-primitives 0.48.2 → 0.50.0

package/src/utils.ts

@@ -0,0 +1,75 @@
+import { getOwner } from '@ember/owner';
+
+import type Owner from '@ember/owner';
+
+// this is copy pasted from https://github.com/emberjs/ember.js/blob/60d2e0cddb353aea0d6e36a72fda971010d92355/packages/%40ember/-internals/glimmer/lib/helpers/unique-id.ts
+// Unfortunately due to https://github.com/emberjs/ember.js/issues/20165 we cannot use the built-in version in template tags
+export function uniqueId(): string {
+  // @ts-expect-error this one-liner abuses weird JavaScript semantics that
+  // TypeScript (legitimately) doesn't like, but they're nonetheless valid and
+  // specced.
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call, @typescript-eslint/restrict-plus-operands, @typescript-eslint/no-unsafe-member-access
+  return ([3e7] + -1e3 + -4e3 + -2e3 + -1e11).replace(/[0-3]/g, (a) =>
+    ((a * 4) ^ ((Math.random() * 16) >> (a & 2))).toString(16)
+  );
+}
+
+export function isNewable(x: any): x is new (...args: unknown[]) => NonNullable<object> {
+  // TypeScript has really bad prototype support -- they don't really
+  // want folks using this sort of stuff -- but it's handy for perf and all that.
+  //
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+  return x.prototype?.constructor === x;
+}
+
+/**
+ * Loose check for an "ownerish" API.
+ * only the ".lookup" method is required.
+ *
+ * The requirements for what an "owner" is are sort of undefined,
+ * as the actual owner in ember applications has too much on it,
+ * and the long term purpose of the owner will be questioned once we
+ * eliminate the need to have a registry (what lookup looks in to),
+ * but we'll still need "Something" to represent the lifetime of the application.
+ *
+ * Technically, the owner could be any object, including `{}`
+ */
+export function isOwner(x: unknown): x is Owner {
+  if (!isNonNullableObject(x)) return false;
+
+  return 'lookup' in x && typeof x.lookup === 'function';
+}
+
+export function isNonNullableObject(x: unknown): x is NonNullable<object> {
+  if (typeof x !== 'object') return false;
+  if (x === null) return false;
+
+  return true;
+}
+
+/**
+ * Can receive the class instance or the owner itself, and will always return return the owner.
+ *
+ * undefined will be returned if the Owner does not exist on the passed object
+ *
+ * Can be useful when combined with `createStore` to then create "services",
+ * which don't require string lookup.
+ */
+export function findOwner(contextOrOwner: unknown): Owner | undefined {
+  if (isOwner(contextOrOwner)) return contextOrOwner;
+
+  // _ENSURE_ that we have an object, else getOwner makes no sense to call
+  if (!isNonNullableObject(contextOrOwner)) return;
+
+  const maybeOwner = getOwner(contextOrOwner);
+
+  if (isOwner(maybeOwner)) return maybeOwner;
+
+  if ('owner' in contextOrOwner) {
+    const maybeOwner = contextOrOwner.owner;
+
+    if (isOwner(maybeOwner)) return maybeOwner;
+  }
+
+  return;
+}

package/src/viewport/in-viewport.gts

@@ -0,0 +1,128 @@
+import Component from "@glimmer/component";
+import { tracked } from "@glimmer/tracking";
+import { assert } from "@ember/debug";
+
+import { element } from "ember-element-helper";
+import { modifier } from "ember-modifier";
+
+import { viewport } from "./viewport.ts";
+
+export type InViewportMode = "replace" | "contain";
+
+/**
+ * Configuration for the InViewport component
+ */
+export interface InViewportSignature {
+  Element: HTMLElement;
+  Args: {
+    /**
+     * The tag name for the placeholder element.
+     * Can be any valid HTML tag name.
+     * Default: 'div'
+     */
+    tagName?: string;
+
+    /**
+     * The mode determines how yielded content is rendered:
+     * - 'replace': yielded content replaces the placeholder element
+     * - 'contain': yielded content is rendered within the placeholder
+     * Default: 'contain'
+     */
+    mode?: InViewportMode;
+  };
+  Blocks: {
+    /**
+     * Default block - rendered when the element is in the viewport
+     */
+    default: [];
+  };
+}
+
+/**
+ * A component that only renders its content when the element is near the viewport.
+ *
+ * This is useful for deferring the rendering of heavy components until they're
+ * actually needed, improving performance for pages with many components.
+ *
+ * Example usage:
+ * ```gjs
+ * import { InViewport } from 'ember-primitives';
+ *
+ * <template>
+ *   <InViewport>
+ *     <ExpensiveComponent />
+ *   </InViewport>
+ * </template>
+ * ```
+ *
+ * The component uses the Intersection Observer API to detect when the element
+ * is near the viewport. Once detected, the observer is destroyed and the content
+ * is rendered permanently.
+ */
+export class InViewport extends Component<InViewportSignature> {
+  /**
+   * Whether the element has been detected as in/near the viewport
+   */
+  @tracked hasIntersected = false;
+
+  get #viewport() {
+    return viewport(this);
+  }
+
+  setupObserver = modifier((element: Element) => {
+    if (this.hasIntersected) {
+      return;
+    }
+
+    this.#viewport.observe(element, this.handle);
+
+    return () => this.#viewport.unobserve(element, this.handle);
+  });
+
+  handle = (entry: IntersectionObserverEntry) => {
+    if (entry?.isIntersecting) {
+      this.hasIntersected = true;
+
+      this.#viewport.unobserve(entry.target, this.handle);
+    }
+  };
+
+  get mode(): InViewportMode {
+    assert(
+      'InViewport mode must be either "replace" or "contain"',
+      !this.args.mode || this.args.mode === "replace" || this.args.mode === "contain",
+    );
+
+    return this.args.mode ?? "contain";
+  }
+
+  get tagName(): string {
+    return this.args.tagName ?? "div";
+  }
+
+  get hasReachedViewport(): boolean {
+    return this.hasIntersected;
+  }
+
+  get isReplacing(): boolean {
+    return this.mode === "replace";
+  }
+
+  <template>
+    {{#let (element this.tagName) as |El|}}
+      {{#if this.isReplacing}}
+        {{#if this.hasReachedViewport}}
+          {{yield}}
+        {{else}}
+          <El {{this.setupObserver}} ...attributes />
+        {{/if}}
+      {{else}}
+        <El {{this.setupObserver}} ...attributes>
+          {{#if this.hasReachedViewport}}
+            {{yield}}
+          {{/if}}
+        </El>
+      {{/if}}
+    {{/let}}
+  </template>
+}

package/src/viewport/viewport.ts

@@ -0,0 +1,122 @@
+import { registerDestructor } from '@ember/destroyable';
+
+import { createService } from '../service.ts';
+
+/**
+ * Creates or returns the ViewportObserverManager.
+ *
+ * Only one of these will exist per owner.
+ *
+ * Has only two methods:
+ * - observe(element, callback: (intersectionObserverEntry) => void, options?)
+ * - unobserve(element, callback: (intersectionObserverEntry) => void)
+ *
+ * Like with the underlying IntersectionObserver API (and all event listeners),
+ * the callback passed to unobserve must be the same reference as the one
+ * passed to observe.
+ */
+export function viewport(context: object) {
+  return createService(context, ViewportObserverManager);
+}
+
+export interface ViewportOptions {
+  /**
+   * A margin around the root. Can have values similar to the CSS margin property.
+   * The values can be percentages. This set of values serves to grow or shrink each
+   * side of the root element's bounding box before computing intersections.
+   * Defaults to all zeros.
+   */
+  rootMargin?: string;
+  /**
+   * Either a single number or an array of numbers which indicate at what percentage
+   * of the target's visibility the observer's callback should be executed. If you only
+   * want to detect when visibility passes the 50% mark, you can use a value of 0.5.
+   * If you want the callback to run every time visibility passes another 25%, you would
+   * specify the array [0, 0.25, 0.5, 0.75, 1]. The default is 0 (meaning as soon as
+   * even one pixel is visible, the callback will be run).
+   */
+  threshold?: number | number[];
+}
+
+class ViewportObserverManager {
+  #callbacks = new WeakMap<Element, Set<(entries: IntersectionObserverEntry) => unknown>>();
+
+  #handleIntersection = (entries: IntersectionObserverEntry[]) => {
+    for (const entry of entries) {
+      const callbacks = this.#callbacks.get(entry.target);
+
+      if (callbacks) {
+        for (const callback of callbacks) {
+          callback(entry);
+        }
+      }
+    }
+  };
+
+  #observer = new IntersectionObserver(this.#handleIntersection, {
+    /**
+     * NOTE: clipping is unaffected by rootMargin if the intersection is with anything
+     *       other than the specified "root".
+     *       And since we don't specify the "root", this effectively means the window viewport.
+     *       (hence the utility name: "viewport")
+     */
+  });
+
+  constructor() {
+    registerDestructor(this, () => {
+      this.#observer?.disconnect();
+    });
+  }
+
+  /**
+   * Initiate the observing of the `element` or add an additional `callback`
+   * if the `element` is already observed.
+   *
+   * @param {object} element
+   * @param {function} callback The `callback` is called whenever the `element`
+   *    intersects with the viewport. It is called with an `IntersectionObserverEntry`
+   *    object for the particular `element`.
+   */
+  observe(element: Element, callback: (entry: IntersectionObserverEntry) => unknown) {
+    const callbacks = this.#callbacks.get(element);
+
+    if (callbacks) {
+      callbacks.add(callback);
+    } else {
+      this.#callbacks.set(element, new Set([callback]));
+      this.#observer.observe(element);
+    }
+  }
+
+  /**
+   * End the observing of the `element` or just remove the provided `callback`.
+   *
+   * It will unobserve the `element` if the `callback` is not provided
+   * or there are no more callbacks left for this `element`.
+   *
+   * @param {Element | undefined | null} element
+   * @param {function?} callback - The `callback` to remove from the listeners
+   *   of the `element` intersection changes.
+   */
+  unobserve(
+    element: Element | undefined | null,
+    callback: (entry: IntersectionObserverEntry) => unknown
+  ) {
+    if (!element) {
+      return;
+    }
+
+    const callbacks = this.#callbacks.get(element);
+
+    if (!callbacks) {
+      return;
+    }
+
+    callbacks.delete(callback);
+
+    if (!callback || !callbacks.size) {
+      this.#callbacks.delete(element);
+      this.#observer.unobserve(element);
+    }
+  }
+}

package/src/viewport.ts

@@ -0,0 +1,2 @@
+export { InViewport, type InViewportSignature } from './viewport/in-viewport.gts';
+export { viewport, type ViewportOptions } from './viewport/viewport.ts';

package/dist/component-Bs3N-G9z.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"component-Bs3N-G9z.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/index-DKE67I8L.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-DKE67I8L.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/otp-C6hCCXKx.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"otp-C6hCCXKx.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/rating-D052JWRa.js

@@ -1,149 +0,0 @@
-
-import Component from '@glimmer/component';
-import { hash } from '@ember/helper';
-import { on } from '@ember/modifier';
-import { uniqueId } from './utils.js';
-import { precompileTemplate } from '@ember/template-compilation';
-import { setComponentTemplate } from '@ember/component';
-import templateOnly from '@ember/component/template-only';
-import { cached } from '@glimmer/tracking';
-import { assert } from '@ember/debug';
-import { localCopy } from 'tracked-toolbox';
-import { g, i, n } from 'decorator-transforms/runtime';
-
-const RatingRange = setComponentTemplate(precompileTemplate("\n  <input ...attributes name={{@name}} type=\"range\" max={{@max}} value={{@value}} {{on \"change\" @handleChange}} />\n", {
-  strictMode: true,
-  scope: () => ({
-    on
-  })
-}), templateOnly());
-
-function isString(x) {
-  return typeof x === 'string';
-}
-function lte(a, b) {
-  return a <= b;
-}
-function percentSelected(a, b) {
-  const diff = b + 1 - a;
-  if (diff < 0) return 0;
-  if (diff > 1) return 100;
-  if (a === b) return 100;
-  const percent = diff * 100;
-  return percent;
-}
-
-const Stars = setComponentTemplate(precompileTemplate("\n  <div class=\"ember-primitives__rating__items\">\n    {{#each @stars as |star|}}\n      {{#let (uniqueId) as |id|}}\n        <span class=\"ember-primitives__rating__item\" data-number={{star}} data-percent-selected={{percentSelected star @currentValue}} data-selected={{lte star @currentValue}} data-readonly={{@isReadonly}}>\n          <label for=\"input-{{id}}\">\n            <span visually-hidden>{{star}} star</span>\n            <span aria-hidden=\"true\">\n              {{#if (isString @icon)}}\n                {{@icon}}\n              {{else}}\n                <@icon @value={{star}} @isSelected={{lte star @currentValue}} @percentSelected={{percentSelected star @currentValue}} @readonly={{@isReadonly}} />\n              {{/if}}\n            </span>\n          </label>\n\n          <input id=\"input-{{id}}\" type=\"radio\" name={{@name}} value={{star}} readonly={{@isReadonly}} checked={{lte star @currentValue}} />\n        </span>\n      {{/let}}\n    {{/each}}\n  </div>\n", {
-  strictMode: true,
-  scope: () => ({
-    uniqueId,
-    percentSelected,
-    lte,
-    isString
-  })
-}), templateOnly());
-
-class RatingState extends Component {
-  static {
-    g(this.prototype, "_value", [localCopy("args.value")]);
-  }
-  #_value = (i(this, "_value"), void 0); // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-  get value() {
-    return this._value ?? 0;
-  }
-  get stars() {
-    return Array.from({
-      length: this.args.max ?? 5
-    }, (_, index) => index + 1);
-  }
-  static {
-    n(this.prototype, "stars", [cached]);
-  }
-  setRating = value => {
-    if (this.args.readonly) {
-      return;
-    }
-    if (value === this._value) {
-      this._value = 0;
-    } else {
-      this._value = value;
-    }
-    this.args.onChange?.(value);
-  };
-  setFromString = value => {
-    assert("[BUG]: value from input must be a string.", typeof value === "string");
-    const num = parseFloat(value);
-    if (isNaN(num)) {
-      // something went wrong.
-      // Since we're using event delegation,
-      // this could be from an unrelated input
-      return;
-    }
-    this.setRating(num);
-  };
-  /**
-  * Click events are captured by
-  * - radio changes (mouse and keyboard)
-  *   - but only range clicks
-  */
-  handleClick = event => {
-    // Since we're doing event delegation on a click, we want to make sure
-    // we don't do anything on other elements
-    const isValid = event.target instanceof HTMLInputElement && event.target.name === this.args.name && event.target.type === "radio";
-    if (!isValid) return;
-    const selected = event.target?.value;
-    this.setFromString(selected);
-  };
-  /**
-  * Only attached to a range element, if present.
-  * Range elements don't fire click events on keyboard usage, like radios do
-  */
-  handleChange = event => {
-    const isValid = event.target !== null && "value" in event.target;
-    if (!isValid) return;
-    this.setFromString(event.target.value);
-  };
-  static {
-    setComponentTemplate(precompileTemplate("\n    {{yield (hash stars=this.stars total=this.stars.length handleClick=this.handleClick handleChange=this.handleChange setRating=this.setRating value=this.value) (hash total=this.stars.length value=this.value)}}\n  ", {
-      strictMode: true,
-      scope: () => ({
-        hash
-      })
-    }), this);
-  }
-}
-
-class Rating extends Component {
-  name = `rating-${uniqueId()}`;
-  get icon() {
-    return this.args.icon ?? "★";
-  }
-  get isInteractive() {
-    return this.args.interactive ?? true;
-  }
-  get isChangeable() {
-    const readonly = this.args.readonly ?? false;
-    return !readonly && this.isInteractive;
-  }
-  get isReadonly() {
-    return !this.isChangeable;
-  }
-  get needsDescription() {
-    return !this.isInteractive;
-  }
-  static {
-    setComponentTemplate(precompileTemplate("\n    <RatingState @max={{@max}} @value={{@value}} @name={{this.name}} @readonly={{this.isReadonly}} @onChange={{@onChange}} as |r publicState|>\n      <fieldset class=\"ember-primitives__rating\" data-total={{r.total}} data-value={{r.value}} data-readonly={{this.isReadonly}} {{!-- We use event delegation, this isn't a primary interactive -- we're capturing events from inputs --}} {{!-- template-lint-disable no-invalid-interactive --}} {{on \"click\" r.handleClick}} ...attributes>\n        {{#let (component Stars stars=r.stars icon=this.icon isReadonly=this.isReadonly name=this.name total=r.total currentValue=r.value) as |RatingStars|}}\n\n          {{#if (has-block)}}\n            {{yield (hash max=r.total total=r.total value=r.value name=this.name isReadonly=this.isReadonly isChangeable=this.isChangeable Stars=RatingStars Range=(component RatingRange max=r.total value=r.value name=this.name handleChange=r.handleChange))}}\n          {{else}}\n            {{#if this.needsDescription}}\n              {{#if (has-block \"label\")}}\n                {{yield publicState to=\"label\"}}\n              {{else}}\n                <span visually-hidden class=\"ember-primitives__rating__label\">Rated\n                  {{r.value}}\n                  out of\n                  {{r.total}}</span>\n              {{/if}}\n            {{else}}\n              {{#if (has-block \"label\")}}\n                <legend>\n                  {{yield publicState to=\"label\"}}\n                </legend>\n              {{/if}}\n            {{/if}}\n\n            <RatingStars />\n          {{/if}}\n        {{/let}}\n\n      </fieldset>\n    </RatingState>\n  ", {
-      strictMode: true,
-      scope: () => ({
-        RatingState,
-        on,
-        Stars,
-        hash,
-        RatingRange
-      })
-    }), this);
-  }
-}
-
-export { Rating as R };
-//# sourceMappingURL=rating-D052JWRa.js.map

package/dist/rating-D052JWRa.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"rating-D052JWRa.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/utils-C5796IKA.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils-C5796IKA.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}