ember-primitives 0.49.0 → 0.50.1

package/src/index.ts

@@ -0,0 +1,43 @@
+/**
+ * DANGER: this is a *barrel file*
+ *
+ * It forces the whole library to be loaded and all dependencies.
+ *
+ * If you have a small app, you probably don't want to import from here -- instead import from each sub-path.
+ */
+import { importSync, isDevelopingApp, macroCondition } from '@embroider/macros';
+
+if (macroCondition(isDevelopingApp())) {
+  importSync('./components/violations.css');
+}
+
+export { Accordion } from './components/accordion.gts';
+export type {
+  AccordionContentExternalSignature,
+  AccordionHeaderExternalSignature,
+  AccordionItemExternalSignature,
+  AccordionTriggerExternalSignature,
+} from './components/accordion/public.ts';
+export { Avatar } from './components/avatar.gts';
+export { Dialog, Dialog as Modal } from './components/dialog.gts';
+export { ExternalLink } from './components/external-link.gts';
+export { Form } from './components/form.gts';
+export { Key, KeyCombo } from './components/keys.gts';
+export { StickyFooter } from './components/layout/sticky-footer.gts';
+export { Link } from './components/link.gts';
+export { Menu } from './components/menu.gts';
+export { OTP, OTPInput } from './components/one-time-password.gts';
+export { Popover } from './components/popover.gts';
+export { Portal } from './components/portal.gts';
+export { PortalTargets } from './components/portal-targets.gts';
+export { TARGETS as PORTALS } from './components/portal-targets.gts';
+export { Progress } from './components/progress.gts';
+export { Rating } from './components/rating.gts';
+export { Scroller } from './components/scroller.gts';
+export { Shadowed } from './components/shadowed.gts';
+export { Switch } from './components/switch.gts';
+export { Toggle } from './components/toggle.gts';
+export { ToggleGroup } from './components/toggle-group.gts';
+export { VisuallyHidden } from './components/visually-hidden.gts';
+export { Zoetrope } from './components/zoetrope.ts';
+export * from './helpers.ts';

package/src/load.gts

@@ -0,0 +1,77 @@
+import { setComponentTemplate } from "@ember/component";
+import templateOnly from "@ember/component/template-only";
+// Have to use these until min ember version is like 6.3 or something
+import { precompileTemplate } from "@ember/template-compilation";
+
+import { getPromiseState } from "reactiveweb/get-promise-state";
+
+import type { ComponentLike } from "@glint/template";
+
+interface LoadSignature<
+  Expected = {
+    Args: any;
+  },
+> {
+  Blocks: {
+    loading: [];
+    error: [
+      {
+        original: unknown;
+        reason: string;
+      },
+    ];
+    success?: [component: ComponentLike<Expected>];
+  };
+}
+
+/**
+ * Loads a value / promise / function providing state for the lifetime of that value / promise / function.
+ *
+ * Can be used for manual bundle splitting via await importing components.
+ *
+ * @example
+ * ```gjs
+ * import { load } from 'ember-primitives/load';
+ *
+ * const Loader = load(() => import('./routes/sub-route.gts'));
+ *
+ * <template>
+ *   <Loader>
+ *     <:loading> ... loading ... </:loading>
+ *     <:error as |error|> ... error! {{error.reason}} </:error>
+ *     <:success as |component|> <component /> </:success>
+ *   </Loader>
+ * </template>
+ * ```
+ */
+export function load<ExpectedSignature, Value>(
+  fn: Value | Promise<Value> | (() => Promise<Value>) | (() => Value),
+): ComponentLike<LoadSignature<ExpectedSignature>> {
+  return setComponentTemplate(
+    precompileTemplate(
+      `{{#let (getPromiseState fn) as |state|}}
+  {{#if state.isLoading}}
+    {{yield to="loading"}}
+  {{else if state.error}}
+    {{yield state.error to="error"}}
+  {{else if state.resolved}}
+    {{#if (has-block "success")}}
+      {{yield state.resolved to="success"}}
+    {{else}}
+      <state.component />
+    {{/if}}
+  {{/if}}
+{{/let}}`,
+      {
+        strictMode: true,
+        /**
+         * The old setComponentTemplate + precompileTemplate combo
+         * does not allow defining things in this scope object,
+         * we _have_ to use the shorthand.
+         */
+        scope: () => ({ fn, getPromiseState }),
+      },
+    ),
+    templateOnly(),
+  ) as ComponentLike<LoadSignature<ExpectedSignature>>;
+}

package/src/narrowing.ts

@@ -0,0 +1,7 @@
+export function isString(x: unknown): x is string {
+  return typeof x === 'string';
+}
+
+export function isElement(x: unknown): x is Element {
+  return x instanceof Element;
+}

package/src/on-resize.ts

@@ -0,0 +1,64 @@
+import { assert } from '@ember/debug';
+import { registerDestructor } from '@ember/destroyable';
+
+import Modifier, { type ArgsFor } from 'ember-modifier';
+
+import { resizeObserver } from './resize-observer.ts';
+
+import type Owner from '@ember/owner';
+
+// re-export provided for convenience
+export { ignoreROError } from './resize-observer.ts';
+
+export interface Signature {
+  /**
+   * Any element that is resizable can have onResize attached
+   */
+  Element: Element;
+  Args: {
+    Positional: [
+      /**
+       * The ResizeObserver callback will only receive
+       * one entry per resize event.
+       *
+       * See: [ResizeObserverEntry](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry)
+       */
+      callback: (entry: ResizeObserverEntry) => void,
+    ];
+  };
+}
+
+class OnResize extends Modifier<Signature> {
+  #callback: ((entry: ResizeObserverEntry) => void) | null = null;
+  #element: Element | null = null;
+
+  #resizeObserver = resizeObserver(this);
+
+  constructor(owner: Owner, args: ArgsFor<Signature>) {
+    super(owner, args);
+
+    registerDestructor(this, () => {
+      if (this.#element && this.#callback) {
+        this.#resizeObserver.unobserve(this.#element, this.#callback);
+      }
+    });
+  }
+
+  modify(element: Element, [callback]: [callback: (entry: ResizeObserverEntry) => void]) {
+    assert(
+      `{{onResize}}: callback must be a function, but was ${callback as unknown as string}`,
+      typeof callback === 'function'
+    );
+
+    if (this.#element && this.#callback) {
+      this.#resizeObserver.unobserve(this.#element, this.#callback);
+    }
+
+    this.#resizeObserver.observe(element, callback);
+
+    this.#callback = callback;
+    this.#element = element;
+  }
+}
+
+export const onResize = OnResize;

package/src/proper-links.ts

@@ -0,0 +1,140 @@
+import { assert } from '@ember/debug';
+import { registerDestructor } from '@ember/destroyable';
+import { getOwner } from '@ember/owner';
+
+import { getAnchor, shouldHandle } from 'should-handle-link';
+
+import type { Newable } from './type-utils.ts';
+import type EmberRouter from '@ember/routing/router';
+import type RouterService from '@ember/routing/router-service';
+
+export { shouldHandle } from 'should-handle-link';
+
+export interface Options {
+  ignore?: string[];
+}
+
+export function properLinks(
+  options: Options
+): <Instance extends object, Klass = { new (...args: any[]): Instance }>(klass: Klass) => Klass;
+
+export function properLinks<Instance extends object, Klass = { new (...args: any[]): Instance }>(
+  klass: Klass
+): Klass;
+/**
+ * @internal
+ */
+export function properLinks<Instance extends object, Klass = { new (...args: any[]): Instance }>(
+  options: Options,
+  klass: Klass
+): Klass;
+
+export function properLinks<Instance extends object, Klass = { new (...args: any[]): Instance }>(
+  ...args: [Options] | [Klass] | [Options, Klass]
+): Klass | ((klass: Klass) => Klass) {
+  let options: Options = {};
+
+  let klass: undefined | Klass = undefined;
+
+  if (args.length === 2) {
+    options = args[0];
+    klass = args[1];
+  } else if (args.length === 1) {
+    if (typeof args[0] === 'object') {
+      // TODO: how to get first arg type correct?
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      return (klass: Klass) => properLinks(args[0] as any, klass);
+    } else {
+      klass = args[0];
+    }
+  }
+
+  const ignore = options.ignore || [];
+
+  assert(`klass was not defined. possibile incorrect arity given to properLinks`, klass);
+
+  return class RouterWithProperLinks extends (klass as unknown as Newable<EmberRouter>) {
+    // SAFETY: we literally do not care about the args' type here,
+    //         because we just call super
+    constructor(...args: any[]) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      super(...args);
+
+      setup(this, ignore);
+    }
+  } as unknown as Klass;
+}
+
+/**
+ * Setup proper links without a decorator.
+ * This function only requires that a framework object with an owner is passed.
+ */
+export function setup(parent: object, ignore?: string[]) {
+  const handler = (event: MouseEvent) => {
+    /**
+     * event.target may not be an anchor,
+     * it may be a span, svg, img, or any number of elements nested in <a>...</a>
+     */
+    const interactive = getAnchor(event);
+
+    if (!interactive) return;
+
+    const owner = getOwner(parent);
+
+    assert('owner is not present', owner);
+
+    const routerService = owner.lookup('service:router');
+
+    handle(routerService, interactive, ignore ?? [], event);
+  };
+
+  document.body.addEventListener('click', handler, false);
+
+  registerDestructor(parent, () => document.body.removeEventListener('click', handler));
+}
+
+export function handle(
+  router: RouterService,
+  element: HTMLAnchorElement,
+  ignore: string[],
+  event: MouseEvent
+) {
+  if (!shouldHandle(location.href, element, event, ignore)) {
+    return;
+  }
+
+  const url = new URL(element.href);
+
+  const fullHref = `${url.pathname}${url.search}${url.hash}`;
+
+  const rootURL = router.rootURL;
+
+  let withoutRootURL = fullHref.slice(rootURL.length);
+
+  // re-add the "root" sigil
+  // we removed it when we chopped off the rootURL,
+  // because the rootURL often has this attached to it as well
+  if (!withoutRootURL.startsWith('/')) {
+    withoutRootURL = `/${withoutRootURL}`;
+  }
+
+  try {
+    const routeInfo = router.recognize(fullHref);
+
+    if (routeInfo) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      event.stopPropagation();
+
+      router.transitionTo(withoutRootURL);
+
+      return false;
+    }
+  } catch (e) {
+    if (e instanceof Error && e.name === 'UnrecognizedURLError') {
+      return;
+    }
+
+    throw e;
+  }
+}

package/src/qp.ts

@@ -0,0 +1,107 @@
+import Helper from '@ember/component/helper';
+import { assert } from '@ember/debug';
+import { service } from '@ember/service';
+
+import type RouterService from '@ember/routing/router-service';
+
+interface Signature {
+  Args: {
+    Positional: [string];
+  };
+  Return: string | undefined;
+}
+
+/**
+ * Grabs a query-param off the current route from the router service.
+ *
+ * ```gjs
+ * import { qp } from 'ember-primitives/qp';
+ *
+ * <template>
+ *  {{qp "query-param"}}
+ * </template>
+ * ```
+ */
+export class qp extends Helper<Signature> {
+  @service declare router: RouterService;
+
+  compute([name]: [string]): string | undefined {
+    assert('A queryParam name is required', name);
+
+    return this.router.currentRoute?.queryParams?.[name] as string | undefined;
+  }
+}
+
+/**
+ * Returns a string for use as an `href` on `<a>` tags, updated with the passed query param
+ *
+ * ```gjs
+ * import { withQP } from 'ember-primitives/qp';
+ *
+ * <template>
+ *   <a href={{withQP "foo" "2"}}>
+ *     ...
+ *   </a>
+ * </template>
+ * ```
+ */
+export class withQP extends Helper<{ Args: { Positional: [string, string] }; Return: string }> {
+  @service declare router: RouterService;
+
+  compute([qpName, nextValue]: [string, string]) {
+    const existing = this.router.currentURL;
+
+    assert('A queryParam name is required', qpName);
+    assert('There is no currentURL', existing);
+
+    const url = new URL(existing, location.origin);
+
+    url.searchParams.set(qpName, nextValue);
+
+    return url.href;
+  }
+}
+
+/**
+ * Cast a query-param string value to a boolean
+ *
+ * ```gjs
+ * import { castToBoolean, qp } from 'ember-primitives/qp';
+ *
+ * <template>
+ *  {{#if (castToBoolean (qp 'the-qp'))}}
+ *    ...
+ *  {{/if}}
+ * </template>
+ * ```
+ *
+ * The following values are considered "false"
+ * - undefined
+ * - ""
+ * - "0"
+ * - false
+ * - "f"
+ * - "off"
+ * - "no"
+ * - "null"
+ * - "undefined"
+ *
+ * All other values are considered truthy
+ */
+export function castToBoolean(x: string | undefined) {
+  if (!x) return false;
+
+  const isFalsey =
+    x === '0' ||
+    x === 'false' ||
+    x === 'f' ||
+    x === 'null' ||
+    x === 'off' ||
+    x === 'undefined' ||
+    x === 'no';
+
+  if (isFalsey) return false;
+
+  // All other values are considered truthy
+  return true;
+}

package/src/resize-observer.ts

@@ -0,0 +1,132 @@
+import { assert } from '@ember/debug';
+import { registerDestructor } from '@ember/destroyable';
+
+import { createStore } from './store.ts';
+import { findOwner } from './utils.ts';
+
+/**
+ * Creates or returns the ResizeObserverManager.
+ *
+ * Only one of these will exist per owner.
+ *
+ * Has only two methods:
+ * - observe(element, callback: (resizeObserverEntry) => void)
+ * - unobserve(element, callback: (resizeObserverEntry) => void)
+ *
+ * Like with the underlying ResizeObserver API (and all event listeners),
+ * the callback passed to unobserved must be the same reference as the one
+ * passed to observe.
+ */
+export function resizeObserver(context: object) {
+  const owner = findOwner(context);
+
+  assert(
+    `Could not find owner on the passed context (to resizeObserver). resizeObserver can only be used on an object whos lifetime is in someone entangled with the application (which incidentally has an "owner").`,
+    owner
+  );
+
+  return createStore(owner, ResizeObserverManager);
+}
+
+class ResizeObserverManager {
+  #callbacks = new WeakMap<Element, Set<(entry: ResizeObserverEntry) => unknown>>();
+
+  #handleResize = (entries: ResizeObserverEntry[]) => {
+    for (const entry of entries) {
+      const callbacks = this.#callbacks.get(entry.target);
+
+      if (callbacks) {
+        for (const callback of callbacks) {
+          callback(entry);
+        }
+      }
+    }
+  };
+  #observer = new ResizeObserver(this.#handleResize);
+
+  constructor() {
+    ignoreROError();
+
+    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 size of
+   *    the `element` changes. It is called with `ResizeObserverEntry` object
+   *    for the particular `element`.
+   */
+  observe(element: Element, callback: (entry: ResizeObserverEntry) => 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 {object} element
+   * @param {function?} callback - The `callback` to remove from the listeners
+   *   of the `element` size changes.
+   */
+  unobserve(element: Element, callback: (entry: ResizeObserverEntry) => unknown) {
+    const callbacks = this.#callbacks.get(element);
+
+    if (!callbacks) {
+      return;
+    }
+
+    callbacks.delete(callback);
+
+    if (!callback || !callbacks.size) {
+      this.#callbacks.delete(element);
+      this.#observer.unobserve(element);
+    }
+  }
+}
+
+const errorMessages = [
+  'ResizeObserver loop limit exceeded',
+  'ResizeObserver loop completed with undelivered notifications.',
+];
+
+/**
+ * Ignores "ResizeObserver loop limit exceeded" error in Ember tests.
+ *
+ * This "error" is safe to ignore as it is just a warning message,
+ * telling that the "looping" observation will be skipped in the current frame,
+ * and will be delivered in the next one.
+ *
+ * For some reason, it is fired as an `error` event at `window` failing Ember
+ * tests and exploding Sentry with errors that must be ignored.
+ */
+export function ignoreROError() {
+  if (typeof window.onerror !== 'function') {
+    return;
+  }
+
+  const onError = window.onerror;
+
+  window.onerror = (...args) => {
+    const [message] = args;
+
+    if (typeof message === 'string') {
+      if (errorMessages.includes(message)) return true;
+    }
+
+    onError(...args);
+  };
+}

package/src/service.ts

@@ -0,0 +1,103 @@
+import { assert } from '@ember/debug';
+
+import { getPromiseState } from 'reactiveweb/get-promise-state';
+
+import { createStore } from './store.ts';
+import { findOwner } from './utils.ts';
+
+import type { Newable } from './type-utils.ts';
+
+/*
+import type { Newable } from './type-utils.ts';
+import type { Registry } from '@ember/service';
+import type Service from '@ember/service';
+
+type Decorator = ReturnType<typeof emberService>;
+
+// export function service<Key extends keyof Registry>(
+//   context: object,
+//   serviceName: Key
+// ): Registry[Key] & Service;
+export function service<Class extends object>(
+  context: object,
+  serviceDefinition: Newable<Class>
+): Class;
+export function service<Class extends object>(serviceDefinition: Newable<Class>): Decorator;
+export function service<Key extends keyof Registry>(serviceName: Key): Decorator;
+export function service(prototype: object, name: string | symbol, descriptor: unknown): void;
+export function service<Value, Result>(
+  context: object,
+  fn: Parameters<typeof getPromiseState<Value, Result>>[0]
+): ReturnType<typeof getPromiseState<Value, Result>>;
+export function service<Value, Result>(
+  fn: Parameters<typeof getPromiseState<Value, Result>>[0]
+): Decorator;
+*/
+
+/**
+ * Instantiates a class once per application instance.
+ *
+ *
+ */
+export function createService<Instance extends object>(
+  context: object,
+  theClass: Newable<Instance> | (() => Instance)
+): Instance {
+  const owner = findOwner(context);
+
+  assert(
+    `Could not find owner / application instance. Cannot create a instance tied to the application lifetime without the application`,
+    owner
+  );
+
+  return createStore(owner, theClass);
+}
+
+const promiseCache = new WeakMap<() => any, unknown>();
+
+/**
+ * Lazily instantiate a service.
+ *
+ * This is a replacement / alternative API for ember's `@service` decorator from `@ember/service`.
+ *
+ * For example
+ * ```js
+ * import { service } from 'ember-primitives/service';
+ *
+ * const loader = () => {
+ *   let module = await import('./foo/file/with/class.js');
+ *   return () => new module.MyState();
+ * }
+ *
+ * class Demo extends Component {
+ *   state = createAsyncService(this, loader);
+ * }
+ * ```
+ *
+ * The important thing is for repeat usage of `createAsyncService` the second parameter,
+ * (loader in this case), must be shared between all usages.
+ *
+ * This is an alternative to using `createStore` inside an await'd component,
+ * or a component rendered with [`getPromiseState`](https://reactive.nullvoxpopuli.com/functions/get-promise-state.getPromiseState.html)
+ * ```
+ */
+export function createAsyncService<Instance extends object>(
+  context: object,
+  theClass: () => Promise<Newable<Instance> | (() => Instance)>
+): ReturnType<typeof getPromiseState<unknown, Instance>> {
+  let existing = promiseCache.get(theClass);
+
+  if (!existing) {
+    existing = async () => {
+      const result = await theClass();
+
+      // Pay no attention to the lies, I don't know what the right type is here
+      return createStore(context, result as Newable<Instance>);
+    };
+
+    promiseCache.set(theClass, existing);
+  }
+
+  // Pay no attention to the TS inference crime here
+  return getPromiseState<unknown, Instance>(existing);
+}