ember-primitives 0.48.2 → 0.50.0

package/src/store.ts

@@ -0,0 +1,72 @@
+import { link } from 'reactiveweb/link';
+
+import { isNewable } from './utils.ts';
+
+import type { Newable } from './type-utils.ts';
+
+/**
+ * context => { class => instance }
+ */
+const contextCache = new WeakMap<object, Map<object, object>>();
+
+/**
+ * Creates a singleton for the given context and links the lifetime of the created class to the passed context
+ *
+ * Note that this function is _not_ lazy. Calling `createStore` will create an instance of the passed class.
+ * When combined with a getter though, creation becomes lazy.
+ *
+ * In this example, `MyState` is created once per instance of the component.
+ * repeat accesses to `this.foo` return a stable reference _as if_ `@cached` were used.
+ * ```js
+ * class MyState {}
+ *
+ * class Demo extends Component {
+ *   // this is a stable reference
+ *   get foo() {
+ *     return createStore(this, MyState);
+ *   }
+ *
+ *   // or
+ *   bar = createStore(this, MyState);
+ *
+ *  // or
+ *  three = createStore(this, () => new MyState(1, 2));
+ * }
+ * ```
+ *
+ * If arguments need to be configured during construction, the second argument may also be a function
+ * ```js
+ * class MyState {}
+ *
+ * class Demo extends Component {
+ *   // this is a stable reference
+ *   get foo() {
+ *     return createStore(this, MyState);
+ *   }
+ * }
+ * ```
+ */
+export function createStore<Instance extends object>(
+  context: object,
+  theClass: Newable<Instance> | (() => Instance)
+): Instance {
+  let cache = contextCache.get(context);
+
+  if (!cache) {
+    cache = new Map();
+    contextCache.set(context, cache);
+  }
+
+  let existing = cache.get(theClass);
+
+  if (!existing) {
+    const instance = isNewable(theClass) ? new theClass() : theClass();
+
+    link(instance, context);
+
+    cache.set(theClass, instance);
+    existing = instance;
+  }
+
+  return existing as Instance;
+}

package/src/styles.css.ts

@@ -0,0 +1,5 @@
+/**
+ * Styles that are always needed, but their components
+ * may not be are included here.
+ */
+import './components/visually-hidden.css';

package/src/tabster.ts

@@ -0,0 +1,54 @@
+import { registerDestructor } from '@ember/destroyable';
+
+export async function setupTabster(
+  /**
+   * A destroyable object.
+   * This is needed so that when the app (or tests) or unmounted or ending,
+   * the tabster instance can be disposed of.
+   */
+  context: object,
+  {
+    tabster,
+    setTabsterRoot,
+  }: {
+    /**
+     * Let this setup function initalize tabster.
+     * https://tabster.io/docs/core
+     *
+     * This should be done only once per application as we don't want
+     * focus managers fighting with each other.
+     *
+     * Defaults to `true`,
+     *
+     * Will fallback to an existing tabster instance automatically if `getTabster` returns a value.
+     *
+     * If `false` is explicitly passed here, you'll also be in charge of teardown.
+     */
+    tabster?: boolean;
+    setTabsterRoot?: boolean;
+  } = {}
+) {
+  const { createTabster, getDeloser, getMover, getTabster, disposeTabster } =
+    await import('tabster');
+
+  tabster ??= true;
+  setTabsterRoot ??= true;
+
+  if (!tabster) {
+    return;
+  }
+
+  const existing = getTabster(window);
+  const primitivesTabster = existing ?? createTabster(window);
+
+  getMover(primitivesTabster);
+  getDeloser(primitivesTabster);
+
+  if (setTabsterRoot) {
+    document.body.setAttribute('data-tabster', '{ "root": {} }');
+  }
+
+  registerDestructor(context, () => {
+    disposeTabster(primitivesTabster);
+  });
+}

package/src/template-registry.ts

@@ -0,0 +1,44 @@
+// Easily allow apps, which are not yet using strict mode templates, to consume your Glint types, by importing this file.
+// Add all your components, helpers and modifiers to the template registry here, so apps don't have to do this.
+// See https://typed-ember.gitbook.io/glint/using-glint/ember/authoring-addons
+
+import type { Accordion } from './components/accordion';
+import type { AccordionContent } from './components/accordion/content';
+import type { AccordionHeader } from './components/accordion/header';
+import type { AccordionItem } from './components/accordion/item';
+import type { AccordionTrigger } from './components/accordion/trigger';
+import type { Dialog } from './components/dialog';
+import type { ExternalLink } from './components/external-link';
+import type { Link } from './components/link';
+import type { Popover } from './components/popover';
+import type { Portal } from './components/portal';
+import type { PortalTargets } from './components/portal-targets';
+import type { Shadowed } from './components/shadowed';
+import type { Switch } from './components/switch';
+import type { Toggle } from './components/toggle';
+import type { service } from './helpers/service';
+
+// import type MyComponent from './components/my-component';
+
+// Remove this once entries have been added! 👇
+
+export default interface Registry {
+  // components
+  Accordion: typeof Accordion;
+  AccordionItem: typeof AccordionItem;
+  AccordionHeader: typeof AccordionHeader;
+  AccordionContent: typeof AccordionContent;
+  AccordionTrigger: typeof AccordionTrigger;
+  Dialog: typeof Dialog;
+  ExternalLink: typeof ExternalLink;
+  Link: typeof Link;
+  Popover: typeof Popover;
+  PortalTargets: typeof PortalTargets;
+  Portal: typeof Portal;
+  Shadowed: typeof Shadowed;
+  Switch: typeof Switch;
+  Toggle: typeof Toggle;
+
+  // helpers
+  service: typeof service;
+}

package/src/test-support/a11y.ts

@@ -0,0 +1,50 @@
+import { assert } from '@ember/debug';
+
+import { setupTabster as _setupTabster } from '../tabster.ts';
+
+import type Owner from '@ember/owner';
+
+/**
+ * Sets up all support utilities for primitive components.
+ * Including the tabster root.
+ */
+async function setup(owner: Owner) {
+  await _setupTabster(owner, { setTabsterRoot: false });
+
+  document.querySelector('#ember-testing')?.setAttribute('data-tabster', '{ "root": {} }');
+}
+
+/**
+ * A QUnit test utility for setting up the tabbing utility that a few of the components in ember-primitive use for providing enhanced keyboard support.
+ *
+ * ```gjs
+ * import { module, test } from 'qunit';
+ * import { setupRenderingTest } from 'ember-qunit';
+ * import { setupTabster } from 'ember-primitives/test-support';
+ *
+ * module('your suite', function (hooks) {
+ *   setupRenderingTest(hooks);
+ *   setupTabster(hooks);
+ *
+ *   test('your test', async function (assert) {
+ *      // ...
+ *   });
+ * });
+ * ```
+ *
+ * This utility takes no options.
+ */
+export function setupTabster(hooks: {
+  beforeEach: (callback: () => void | Promise<void>) => unknown;
+}) {
+  hooks.beforeEach(async function (this: { owner: object }) {
+    const owner = this.owner;
+
+    assert(
+      `Test does not have an owner, be sure to use setupRenderingTest, setupTest, or setupApplicationTest (from ember-qunit (or similar))`,
+      owner
+    );
+
+    await setup(this.owner as Owner);
+  });
+}

package/src/test-support/dom.ts

@@ -0,0 +1,112 @@
+import { assert } from '@ember/debug';
+import { find } from '@ember/test-helpers';
+
+type Findable = Parameters<typeof find>[0] | Element;
+
+/**
+ * Find an element within a given element that has a shadow-root.
+ *
+ * If the `root` can't be found, or if there actually is no shadow root,
+ * nothing will be returned.
+ *
+ * ```gjs
+ * import { findInShadow } from 'ember-primitives/test-support';
+ *
+ * // ...
+ *
+ * test('...', async function (assert) {
+ *    // ...
+ *    const root = find('div.with-shadowdom');
+ *    assert.dom(findInShadow(root, 'h1')).containsText('welcome');
+ * });
+ * ```
+ */
+export function findInShadow(root: Findable, query: string) {
+  const rootElement = root instanceof Element ? root : find(root);
+
+  return rootElement?.shadowRoot?.querySelector(query);
+}
+
+/**
+ * Does the element have a shadow root?
+ *
+ * Using this utility function will only save a few characters over using its implementation directly.
+ *
+ * ```gjs
+ * import { hasShadowRoot } from 'ember-primitives/test-support';
+ *
+ * // ...
+ *
+ * test('...', async function (assert) {
+ *    // ...
+ *    const el = find('div.with-shadowdom');
+ *    assert.ok(hasShadowRoot(el), 'expecting el to have a shadow root');
+ * });
+ * ```
+ */
+export function hasShadowRoot(el: Element) {
+  return Boolean(el.shadowRoot);
+}
+
+/**
+ * Find an element within `root`, that has a shadow root.
+ * The `root` param is optional, and if not provided, all of `#ember-testing` will be searched.
+ *
+ * This only returns the first-found shadow, so if you want a specifc shadow root,
+ * you'll need to narrow down the search by specifying a `root`.
+ *
+ * ```gjs
+ * import { findShadow } from 'ember-primitives/test-support';
+ *
+ * // ...
+ *
+ * test('...', async function (assert) {
+ *    // ...
+ *    const el = findShadow('div.with-shadowdom');
+ *    // ...
+ * });
+ * ```
+ */
+export function findShadow(root?: Findable) {
+  const rootElement = root
+    ? root instanceof Element
+      ? root
+      : find(root)
+    : document.getElementById('ember-testing');
+
+  if (!rootElement) return;
+
+  for (const element of rootElement.querySelectorAll('*')) {
+    if (element.shadowRoot) {
+      return element;
+    }
+  }
+}
+
+/**
+ * For the first available shadow root on the page, query in to it, like you would with `querySelector`.
+ *
+ *
+ * ```gjs
+ * import { findInFirstShadow } from 'ember-primitives/test-support';
+ *
+ * // ...
+ *
+ * test('...', async function (assert) {
+ *    // ...
+ *    assert.dom(findInFirstShadow('h1')).containsText('welcome');
+ * });
+ * ```
+ *
+ * If there are multiple shadow roots on the page / test-render,
+ * this is not the utility for you.
+ *
+ * For querying in specific shadow roots, you'll want to use `findInShadow`
+ */
+export function findInFirstShadow(query: string) {
+  const host = findShadow();
+
+  assert(`No element with a shadow root could be found`, host);
+
+  return findInShadow(host, query);
+}

package/src/test-support/otp.ts

@@ -0,0 +1,64 @@
+import { assert } from '@ember/debug';
+import { fillIn, find, settled } from '@ember/test-helpers';
+
+/**
+ * Fill the OTP input
+ *
+ * ```gjs
+ * import { fillOTP } from 'ember-primitives/test-support';
+ *
+ * test('...', async function(assert) {
+ *   // ...
+ *   await fillOTP('123456');
+ *   // ...
+ * })
+ *
+ * ```
+ *
+ * @param {string} code the code to fill the input(s) with.
+ * @param {string} [ selector ] if there are multiple OTP components on a page, this can be used to select one of them.
+ */
+export async function fillOTP(code: string, selector?: string) {
+  const ancestor = selector ? find(selector) : document;
+
+  assert(
+    `Could not find ancestor element, does your selector match an existing element?`,
+    ancestor
+  );
+
+  const fieldset =
+    ancestor instanceof HTMLFieldSetElement ? ancestor : ancestor.querySelector('fieldset');
+
+  assert(
+    `Could not find containing fieldset element (this holds the OTP Input fields). Was the OTP component rendered?`,
+    fieldset
+  );
+
+  const inputs = fieldset.querySelectorAll('input');
+
+  assert(
+    `code cannot be longer than the available inputs. code is of length ${code.length} but there are ${inputs.length}`,
+    code.length <= inputs.length
+  );
+
+  const chars = code.split('');
+
+  assert(`OTP Input for index 0 is missing!`, inputs[0]);
+  assert(`Character at index 0 is missing`, chars[0]);
+
+  for (let i = 0; i < chars.length; i++) {
+    const input = inputs[i];
+    const char = chars[i];
+
+    assert(`Input at index ${i} is missing`, input);
+    assert(`Character at index ${i} is missing`, char);
+
+    input.value = char;
+  }
+
+  await fillIn(inputs[0], chars[0]);
+
+  // Account for out-of-settled-system delay due to RAF debounce.
+  await new Promise((resolve) => requestAnimationFrame(resolve));
+  await settled();
+}

package/src/test-support/rating.ts

@@ -0,0 +1,144 @@
+import { assert } from '@ember/debug';
+import { click, fillIn, find, findAll } from '@ember/test-helpers';
+
+const selectors = {
+  root: '.ember-primitives__rating',
+  item: '.ember-primitives__rating__item',
+  label: '.ember-primitives__rating__label',
+
+  rootData: {
+    total: '[data-total]',
+    value: '[data-value]',
+  },
+
+  itemData: {
+    number: '[data-number]',
+    readonly: '[data-readonly]',
+    selected: '[data-selected]',
+    itemPercent: '[data-percent-selected]',
+  },
+};
+
+const stars = {
+  selected: '★',
+  unselected: '☆',
+};
+
+/**
+ * Test utility for interacting with the
+ * Rating component.
+ *
+ * Simulates user behavior and provides high level functions so you don't need to worry about the DOM.
+ *
+ * Actual elements are not exposed, as the elements are private API.
+ * Even as you build a design system, the DOM should not be exposed to your consumers.
+ */
+export function rating(selector?: string) {
+  const root = `${selector ?? ''}${selectors.root}`;
+
+  return new RatingPageObject(root);
+}
+
+class RatingPageObject {
+  #root: string;
+
+  constructor(root: string) {
+    this.#root = root;
+  }
+
+  get #rootElement() {
+    const element = find(this.#root);
+
+    assert(
+      `Could not find the root element for the <Rating> component. Used the selector \`${this.#root}\`. Was it rendered?`,
+      element
+    );
+
+    return element;
+  }
+
+  get #labelElement() {
+    const element = find(`${this.#root} ${selectors.label}`);
+
+    assert(`Could not find the label for the <Rating> component. Was it rendered?`, element);
+
+    return element;
+  }
+
+  get label() {
+    return this.#labelElement.textContent?.replaceAll(/\s+/g, ' ').trim();
+  }
+
+  get #starElements() {
+    const elements = findAll(`${this.#root} ${selectors.item}`);
+
+    assert(
+      `There are no stars/items. Is the <Rating> component misconfigured?`,
+      elements.length > 0
+    );
+
+    return elements as HTMLElement[];
+  }
+
+  get stars() {
+    const elements = this.#starElements;
+
+    return elements
+      .map((x) => (x.hasAttribute('data-selected') ? stars.selected : stars.unselected))
+      .join(' ');
+  }
+
+  get starTexts() {
+    const elements = this.#starElements;
+
+    return elements.map((x) => x.querySelector('[aria-hidden]')?.textContent?.trim()).join(' ');
+  }
+
+  get value() {
+    const value = this.#rootElement.getAttribute(`data-value`);
+
+    assert(`data-value attribute is missing on element '${this.#root}'`, value);
+
+    const number = parseFloat(value);
+
+    return number;
+  }
+
+  get isReadonly() {
+    return this.#starElements.every((x) => x.hasAttribute('data-readonly'));
+  }
+
+  async select(stars: number) {
+    const root = this.#rootElement;
+
+    const star = root.querySelector(`[data-number="${stars}"] input`);
+
+    if (star) {
+      await click(star);
+
+      return;
+    }
+
+    /**
+     * When we don't have an input, we require an input --
+     * which is also the only way we can choose non-integer values.
+     *
+     * Should be able to be a number input or range input.
+     */
+    const input = root.querySelector('input[type="number"], input[type="range"]');
+
+    if (input) {
+      await fillIn(input, `${stars}`);
+
+      return;
+    }
+
+    const available = [...root.querySelectorAll('[data-number]')].map((x) =>
+      x.getAttribute('data-number')
+    );
+
+    assert(
+      `Could not find item/star in <Rating> with value '${stars}' (or a number or range input with the same "name" value). Is the number (${stars}) correct and in-range for this component? The found available values are ${available.join(', ')}.`
+    );
+  }
+}

package/src/test-support/routing.ts

@@ -0,0 +1,62 @@
+import { assert } from '@ember/debug';
+import Router from '@ember/routing/router';
+
+import { properLinks } from '../proper-links.ts';
+
+import type Owner from '@ember/owner';
+import type { DSLCallback } from '@ember/routing/lib/dsl';
+import type RouterService from '@ember/routing/router-service';
+
+/**
+ * Allows setting up routes in tests without the need to scaffold routes in the actual app,
+ * allowing for iterating on many different routing scenario / configurations rapidly.
+ *
+ * Example:
+ * ```js
+ * import { setupRouting } from 'ember-primitives/test-support';
+ *
+ *  ...
+ *
+ * test('my test', async function (assert) {
+ *   setupRouting(this.owner, function () {
+ *     this.route('foo');
+ *     this.route('bar', function () {
+ *       this.route('a');
+ *       this.route('b');
+ *     })
+ *   });
+ *
+ *   await visit('/bar/b');
+ * });
+ * ```
+ *
+ */
+export function setupRouting(owner: Owner, map: DSLCallback, options?: { rootURL: string }) {
+  if (options?.rootURL) {
+    assert('rootURL must begin with a forward slash ("/")', options?.rootURL?.startsWith('/'));
+  }
+
+  @properLinks
+  class TestRouter extends Router {
+    rootURL = options?.rootURL ?? '/';
+  }
+
+  TestRouter.map(map);
+
+  owner.register('router:main', TestRouter);
+
+  // eslint-disable-next-line ember/no-private-routing-service
+  const iKnowWhatIMDoing = owner.lookup('router:main');
+
+  // We need a public testing API for this sort of stuff
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+  (iKnowWhatIMDoing as any).setupRouter();
+}
+
+/**
+ * A small utility that only gives you a _typed_ router service.
+ */
+export function getRouter(owner: Owner): RouterService {
+  return owner.lookup('service:router');
+}

package/src/test-support/zoetrope.ts

@@ -0,0 +1,51 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import { click } from '@ember/test-helpers';
+
+export class ZoetropeHelper {
+  parentSelector = '.ember-primitives__zoetrope';
+
+  constructor(parentSelector?: string) {
+    if (parentSelector) {
+      this.parentSelector = parentSelector;
+    }
+  }
+
+  async scrollLeft() {
+    await click(`${this.parentSelector} .ember-primitives__zoetrope__controls button:first-child`);
+  }
+
+  async scrollRight() {
+    await click(`${this.parentSelector} .ember-primitives__zoetrope__controls button:last-child`);
+  }
+
+  visibleItems() {
+    const zoetropeContent = document.querySelectorAll(
+      `${this.parentSelector} .ember-primitives__zoetrope__scroller > *`
+    );
+
+    let firstVisibleItemIndex = -1;
+    let lastVisibleItemIndex = -1;
+
+    for (let i = 0; i < zoetropeContent.length; i++) {
+      const item = zoetropeContent[i]!;
+      const rect = item.getBoundingClientRect();
+      const parentRect = item.parentElement!.getBoundingClientRect();
+
+      if (rect.right >= parentRect?.left && rect.left <= parentRect?.right) {
+        if (firstVisibleItemIndex === -1) {
+          firstVisibleItemIndex = i;
+        }
+
+        lastVisibleItemIndex = i;
+      } else if (firstVisibleItemIndex !== -1) {
+        break;
+      }
+    }
+
+    return Array.from(zoetropeContent).slice(firstVisibleItemIndex, lastVisibleItemIndex + 1);
+  }
+
+  visibleItemCount() {
+    return this.visibleItems().length;
+  }
+}

package/src/test-support.gts

@@ -0,0 +1,6 @@
+export { setupTabster } from "./test-support/a11y.ts";
+export { findInFirstShadow, findInShadow, findShadow, hasShadowRoot } from "./test-support/dom.ts";
+export { fillOTP } from "./test-support/otp.ts";
+export { rating } from "./test-support/rating.ts";
+export { getRouter, setupRouting } from "./test-support/routing.ts";
+export { ZoetropeHelper } from "./test-support/zoetrope.ts";

package/src/type-utils.ts

@@ -0,0 +1 @@
+export type Newable<T extends object = object> = { new (...args: any[]): T };