ember-primitives 0.49.0 → 0.50.0

package/src/components/zoetrope/index.gts

@@ -0,0 +1,358 @@
+import "./styles.css";
+
+import Component from "@glimmer/component";
+import { tracked } from "@glimmer/tracking";
+import { hash } from "@ember/helper";
+import { on } from "@ember/modifier";
+import { buildWaiter, waitForPromise } from "@ember/test-waiters";
+import { isTesting, macroCondition } from "@embroider/macros";
+
+import { modifier } from "ember-modifier";
+
+import type { ScrollBehavior, Signature } from "./types.ts";
+
+const testWaiter = buildWaiter("ember-primitive:zoetrope-waiter");
+const DEFAULT_GAP = 8;
+const DEFAULT_OFFSET = 0;
+
+export class Zoetrope extends Component<Signature> {
+  @tracked scrollerElement: HTMLElement | null = null;
+  @tracked currentlyScrolled = 0;
+  @tracked scrollWidth = 0;
+  @tracked offsetWidth = 0;
+
+  private setCSSVariables = modifier(
+    (element: HTMLElement, _: unknown, { gap, offset }: { gap: number; offset: number }) => {
+      if (gap) element.style.setProperty("--zoetrope-gap", `${gap}px`);
+      if (offset) element.style.setProperty("--zoetrope-offset", `${offset}px`);
+    },
+  );
+
+  scrollerWaiter = testWaiter.beginAsync();
+  noScrollWaiter = () => {
+    testWaiter.endAsync(this.scrollerWaiter);
+  };
+
+  private configureScroller = modifier((element: HTMLElement) => {
+    this.scrollerElement = element;
+    this.currentlyScrolled = element.scrollLeft;
+
+    const zoetropeResizeObserver = new ResizeObserver(() => {
+      this.scrollWidth = element.scrollWidth;
+      this.offsetWidth = element.offsetWidth;
+    });
+
+    zoetropeResizeObserver.observe(element);
+
+    element.addEventListener("scroll", this.scrollListener, { passive: true });
+    element.addEventListener("keydown", this.tabListener);
+
+    requestAnimationFrame(() => {
+      testWaiter.endAsync(this.scrollerWaiter);
+    });
+
+    return () => {
+      element.removeEventListener("scroll", this.scrollListener);
+      element.removeEventListener("keydown", this.tabListener);
+
+      zoetropeResizeObserver.unobserve(element);
+    };
+  });
+
+  private tabListener = (event: KeyboardEvent) => {
+    const target = event.target as HTMLElement;
+    const { key, shiftKey } = event;
+
+    if (!this.scrollerElement || this.scrollerElement === target) {
+      return;
+    }
+
+    if (key !== "Tab") {
+      return;
+    }
+
+    const nextElement = target.nextElementSibling;
+    const previousElement = target.previousElementSibling;
+
+    if ((!shiftKey && !nextElement) || (shiftKey && !previousElement)) {
+      return;
+    }
+
+    event.preventDefault();
+
+    let newTarget: HTMLElement | null = null;
+
+    if (shiftKey) {
+      newTarget = previousElement as HTMLElement;
+    } else {
+      newTarget = nextElement as HTMLElement;
+    }
+
+    if (!newTarget) {
+      return;
+    }
+
+    newTarget?.focus({ preventScroll: true });
+
+    const rect = getRelativeBoundingClientRect(newTarget, this.scrollerElement);
+
+    this.scrollerElement?.scrollBy({
+      left: rect.left,
+      behavior: this.scrollBehavior,
+    });
+  };
+
+  private scrollListener = () => {
+    this.currentlyScrolled = this.scrollerElement?.scrollLeft || 0;
+  };
+
+  get offset() {
+    return this.args.offset ?? DEFAULT_OFFSET;
+  }
+
+  get gap() {
+    return this.args.gap ?? DEFAULT_GAP;
+  }
+
+  get canScroll() {
+    return this.scrollWidth > this.offsetWidth + this.offset;
+  }
+
+  get cannotScrollLeft() {
+    return this.currentlyScrolled <= this.offset;
+  }
+
+  get cannotScrollRight() {
+    return this.scrollWidth - this.offsetWidth - this.offset < this.currentlyScrolled;
+  }
+
+  get scrollBehavior(): ScrollBehavior {
+    if (macroCondition(isTesting())) {
+      return "instant";
+    }
+
+    return this.args.scrollBehavior || "smooth";
+  }
+
+  scrollLeft = () => {
+    if (!(this.scrollerElement instanceof HTMLElement)) {
+      return;
+    }
+
+    const { firstChild } = this.findOverflowingElement();
+
+    if (!firstChild) {
+      return;
+    }
+
+    const children = [...this.scrollerElement.children];
+
+    const firstChildIndex = children.indexOf(firstChild);
+
+    let targetElement = firstChild;
+    let accumalatedWidth = 0;
+
+    for (let i = firstChildIndex; i >= 0; i--) {
+      const child = children[i];
+
+      if (!(child instanceof HTMLElement)) {
+        continue;
+      }
+
+      accumalatedWidth += child.offsetWidth + this.gap;
+
+      if (accumalatedWidth >= this.offsetWidth) {
+        break;
+      }
+
+      targetElement = child;
+    }
+
+    const rect = getRelativeBoundingClientRect(targetElement, this.scrollerElement);
+
+    this.scrollerElement.scrollBy({
+      left: rect.left,
+      behavior: this.scrollBehavior,
+    });
+
+    void waitForPromise(new Promise(requestAnimationFrame));
+  };
+
+  scrollRight = () => {
+    if (!(this.scrollerElement instanceof HTMLElement)) {
+      return;
+    }
+
+    const { activeSlide, lastChild } = this.findOverflowingElement();
+
+    if (!lastChild) {
+      return;
+    }
+
+    let rect = getRelativeBoundingClientRect(lastChild, this.scrollerElement);
+
+    // If the card is larger than the container then skip to the next card
+    if (rect.width > this.offsetWidth && activeSlide === lastChild) {
+      const children = [...this.scrollerElement.children];
+      const lastChildIndex = children.indexOf(lastChild);
+      const targetElement = children[lastChildIndex + 1];
+
+      if (!targetElement) {
+        return;
+      }
+
+      rect = getRelativeBoundingClientRect(targetElement, this.scrollerElement);
+    }
+
+    this.scrollerElement?.scrollBy({
+      left: rect.left,
+      behavior: this.scrollBehavior,
+    });
+
+    void waitForPromise(new Promise(requestAnimationFrame));
+  };
+
+  private findOverflowingElement() {
+    const returnObj: {
+      activeSlide?: Element;
+      firstChild?: Element;
+      lastChild?: Element;
+    } = {
+      firstChild: undefined,
+      lastChild: undefined,
+      activeSlide: undefined,
+    };
+
+    if (!this.scrollerElement) {
+      return returnObj;
+    }
+
+    const parentElement = this.scrollerElement.parentElement;
+
+    if (!parentElement) {
+      return returnObj;
+    }
+
+    const containerRect = getRelativeBoundingClientRect(this.scrollerElement, parentElement);
+
+    const children = [...this.scrollerElement.children];
+
+    // Find the first child that is overflowing the left edge of the container
+    // and the last child that is overflowing the right edge of the container
+    for (const child of children) {
+      const rect = getRelativeBoundingClientRect(child, this.scrollerElement);
+
+      if (rect.right + this.gap >= containerRect.left && !returnObj.firstChild) {
+        returnObj.firstChild = child;
+      }
+
+      if (rect.left >= this.offset && !returnObj.activeSlide) {
+        returnObj.activeSlide = child;
+      }
+
+      if (rect.right >= containerRect.width && !returnObj.lastChild) {
+        returnObj.lastChild = child;
+
+        break;
+      }
+    }
+
+    if (!returnObj.firstChild) {
+      returnObj.firstChild = children[0];
+    }
+
+    if (!returnObj.lastChild) {
+      returnObj.lastChild = children[children.length - 1];
+    }
+
+    return returnObj;
+  }
+
+  <template>
+    <section
+      class="ember-primitives__zoetrope"
+      {{this.setCSSVariables gap=this.gap offset=this.offset}}
+      ...attributes
+    >
+      {{#if (has-block "header")}}
+        <div class="ember-primitives__zoetrope__header">
+          {{yield to="header"}}
+        </div>
+      {{/if}}
+
+      {{#if (has-block "controls")}}
+        {{yield
+          (hash
+            cannotScrollLeft=this.cannotScrollLeft
+            cannotScrollRight=this.cannotScrollRight
+            canScroll=this.canScroll
+            scrollLeft=this.scrollLeft
+            scrollRight=this.scrollRight
+          )
+          to="controls"
+        }}
+      {{else}}
+        {{#if this.canScroll}}
+          <div class="ember-primitives__zoetrope__controls">
+            <button
+              type="button"
+              {{on "click" this.scrollLeft}}
+              disabled={{this.cannotScrollLeft}}
+            >Left</button>
+
+            <button
+              type="button"
+              {{on "click" this.scrollRight}}
+              disabled={{this.cannotScrollRight}}
+            >Right</button>
+          </div>
+        {{/if}}
+      {{/if}}
+      {{#if (has-block "content")}}
+        <div class="ember-primitives__zoetrope__scroller" {{this.configureScroller}}>
+          {{yield to="content"}}
+        </div>
+      {{else}}
+        {{(this.noScrollWaiter)}}
+      {{/if}}
+    </section>
+  </template>
+}
+
+export default Zoetrope;
+
+function getRelativeBoundingClientRect(childElement: Element, parentElement: Element) {
+  if (!childElement || !parentElement) {
+    throw new Error("Both childElement and parentElement must be provided");
+  }
+
+  // Get the bounding rect of the child and parent elements
+  const childRect = childElement.getBoundingClientRect();
+  const parentRect = parentElement.getBoundingClientRect();
+
+  // Get computed styles of the parent element
+  const parentStyles = window.getComputedStyle(parentElement);
+
+  // Extract and parse parent's padding, and border, for all sides
+  const parentPaddingTop = parseFloat(parentStyles.paddingTop);
+  const parentPaddingLeft = parseFloat(parentStyles.paddingLeft);
+
+  const parentBorderTopWidth = parseFloat(parentStyles.borderTopWidth);
+  const parentBorderLeftWidth = parseFloat(parentStyles.borderLeftWidth);
+
+  // Calculate child's position relative to parent's content area (including padding and borders)
+  return {
+    width: childRect.width,
+    height: childRect.height,
+    top: childRect.top - parentRect.top - parentBorderTopWidth - parentPaddingTop,
+    left: childRect.left - parentRect.left - parentBorderLeftWidth - parentPaddingLeft,
+    bottom:
+      childRect.top - parentRect.top - parentBorderTopWidth - parentPaddingTop + childRect.height,
+    right:
+      childRect.left -
+      parentRect.left -
+      parentBorderLeftWidth -
+      parentPaddingLeft +
+      childRect.width,
+  };
+}

package/src/components/zoetrope/styles.css

@@ -0,0 +1,40 @@
+.ember-primitives__zoetrope {
+  display: flex;
+  flex-wrap: wrap;
+  position: relative;
+  width: 100%;
+}
+
+.ember-primitives__zoetrope__header {
+  align-items: center;
+  display: flex;
+  flex: 1;
+  justify-content: space-between;
+  padding-left: var(--zoetrope-offset, 0);
+}
+
+.ember-primitives__zoetrope__controls {
+  align-items: center;
+  display: flex;
+  padding-right: var(--zoetrope-offset, 0);
+  gap: 4px;
+}
+
+.ember-primitives__zoetrope__scroller {
+  display: flex;
+  flex-flow: row nowrap;
+  gap: var(--zoetrope-gap, 8px);
+  overflow: scroll visible;
+  padding: 8px var(--zoetrope-offset, 0);
+  scroll-behavior: smooth;
+  scroll-padding-left: var(--zoetrope-offset, 0);
+  scroll-snap-type: x mandatory;
+  scrollbar-color: transparent transparent;
+  scrollbar-width: none;
+  width: 100%;
+
+  & > * {
+    flex-shrink: 0;
+    scroll-snap-align: start;
+  }
+}

package/src/components/zoetrope/types.ts

@@ -0,0 +1,65 @@
+export type ScrollBehavior = 'auto' | 'smooth' | 'instant';
+
+export interface Signature {
+  Args: {
+    /**
+     * The distance in pixels between each item in the slider.
+     */
+    gap?: number;
+
+    /**
+     * The distance from the edge of the container to the first and last item, this allows
+     * the contents to visually overflow the container
+     */
+    offset?: number;
+
+    /**
+     * The scroll behavior to use when scrolling the slider. Defaults to smooth.
+     */
+    scrollBehavior?: ScrollBehavior;
+  };
+  Blocks: {
+    /**
+     * The header block is where the header content is placed.
+     */
+    header: [];
+
+    /**
+     * The content block is where the items that will be scrolled are placed.
+     */
+    content: [];
+
+    /**
+     * The controls block is where the left and right buttons are placed.
+     */
+    controls: [
+      {
+        /**
+         * Whether the slider can scroll.
+         */
+        canScroll: boolean;
+
+        /**
+         * Whether the slider cannot scroll left.
+         */
+        cannotScrollLeft: boolean;
+
+        /**
+         * Whether the slider cannot scroll right.
+         */
+        cannotScrollRight: boolean;
+
+        /**
+         * The function to scroll the slider left.
+         */
+        scrollLeft: () => void;
+
+        /**
+         * The function to scroll the slider right.
+         */
+        scrollRight: () => void;
+      },
+    ];
+  };
+  Element: HTMLElement;
+}

package/src/components/zoetrope.ts

@@ -0,0 +1,3 @@
+export { Zoetrope } from './zoetrope/index.gts';
+export { default } from './zoetrope/index.gts';
+export type { Signature } from './zoetrope/types.ts';

package/src/dom-context.gts

@@ -0,0 +1,245 @@
+import Component from "@glimmer/component";
+import { cached, tracked } from "@glimmer/tracking";
+import { assert } from "@ember/debug";
+
+import { isElement } from "./narrowing.ts";
+import { createStore } from "./store.ts";
+
+import type { Newable } from "./type-utils";
+import type Owner from "@ember/owner";
+
+/**
+ * IMPLEMENTATION NOTE:
+ *   we don't use https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md
+ *   because it is not inherently reactive.
+ *
+ *   Its *event* based, which opts you out of fine-grained reactivity.
+ *   We want minimal effort fine-grained reactivity.
+ *
+ * This Technique follows the DOM tree, and is synchronous,
+ * allowing correct fine-grained signals-based reactivity.
+ *
+ * We *could* do less work to find Providers,
+ * but only if we forgoe DOM-tree scoping.
+ * We must traverse the DOM hierarchy to validate that we aren't accessing providers from different subtrees.
+ */
+const LOOKUP = new WeakMap<Text | Element, [unknown, () => unknown]>();
+
+export class Provide<Data extends object> extends Component<{
+  /**
+   * The Element is not customizable
+   * (and also sometimes doesn't exist (depending on the `@element` value))
+   */
+  Element: null;
+  Args: {
+    /**
+     * What data do you want to provide to the DOM subtree?
+     *
+     * If this is a function or class, it will be instantiated and given an
+     * owner + destroyable linkage via `createStore`
+     */
+    data: Data | (() => Data) | Newable<Data>;
+
+    /**
+     * Optionally, you may use string-based keys to reference the data in the Provide.
+     *
+     * This is not recommended though, because when using a class or other object-like structure,
+     * the type in the `<Consume>` component can be derived from that class or object-like structure.
+     * With string keys, the `<Consume>` type will be unknown.
+     */
+    key?: string;
+
+    /**
+     * Can be used to either customize the element tag ( defaults to div )
+     * If set to `false`, we won't use an element for the Provider boundary.
+     *
+     * Setting this to `false` changes the DOM Node containing the Provider's data to be a text node -- which can be useful when certain CSS situations are needed.
+     *
+     * But setting to `false` has a hazard: it allows subsequent sibling subtrees to access adjacent providers.
+     *
+     * There is no way around caveat in library land, and in a framework implementation of context,
+     * it can only be solved by having render-tree context implemented, and ignoring DOM
+     *  (which then makes the only difference between DOM-Context and Context be whether or not
+     *    the context punches through Portals)
+     */
+    element?: keyof HTMLElementTagNameMap | false | undefined;
+  };
+  Blocks: {
+    /**
+     * The content that this component will _provide_ data to the entire hierarchy.
+     */
+    default: [];
+  };
+}> {
+  get data() {
+    assert(`@data is missing in <Provide>. Please pass @data.`, "data" in this.args);
+
+    /**
+     * This covers both classes and functions
+     */
+    if (typeof this.args.data === "function") {
+      return createStore<Data>(this, this.args.data);
+    }
+
+    /**
+     * Non-instantiable value
+     */
+    return this.args.data;
+  }
+
+  element: Text | HTMLElement;
+
+  constructor(
+    owner: Owner,
+    args: {
+      data: Data | (() => Data) | Newable<Data>;
+      key?: string;
+    },
+  ) {
+    super(owner, args);
+
+    assert(
+      `@element may only be \`false\` or a string (or undefined (default when not set))`,
+      this.args.element === undefined ||
+        this.args.element === false ||
+        typeof this.args.element === "string",
+    );
+
+    if (this.useElementProvider) {
+      this.element = document.createElement(this.args.element || "div");
+
+      // This tells the browser to ignore everything about this element when it comes to styling
+      this.element.style.display = "contents";
+    } else {
+      this.element = document.createTextNode("");
+    }
+
+    const key = this.args.key ?? this.args.data;
+
+    LOOKUP.set(this.element, [key, () => this.data]);
+  }
+
+  get useElementProvider() {
+    return this.args.element !== false;
+  }
+
+  <template>
+    {{#if (isElement this.element)}}
+      {{this.element}}
+
+      {{#in-element this.element}}
+        {{yield}}
+      {{/in-element}}
+
+    {{else}}
+      {{! NOTE! This type of provider will _allow_ non-descendents using the same key to find the provider and use it.
+
+        For example:
+          Provider
+            Consumer
+
+          Consumer (finds Provider)
+      }}
+
+      {{this.element}}
+      {{yield}}
+
+    {{/if}}
+  </template>
+}
+
+/**
+ * How this works:
+ * - starting at some deep node (Text, Element, whatever),
+ *   start crawling up the ancenstry graph (of DOM Nodes).
+ *
+ * - This algo "tops out" (since we traverse upwards (otherwise this would be "bottoming out")) at the HTMLDocument (parent of the HTML Tag)
+ *
+ */
+function findForKey<Data>(startElement: Text, key: string | object): undefined | (() => Data) {
+  let parent: ParentNode | Text | null | undefined = startElement;
+
+  while (parent) {
+    let target: ParentNode | ChildNode | Text | null | undefined = parent;
+
+    while (target) {
+      if (!(target instanceof Element) && !(target instanceof Text)) {
+        target = target?.previousSibling;
+        continue;
+      }
+
+      const maybe = LOOKUP.get(target);
+
+      target = target?.previousSibling;
+
+      if (!maybe) {
+        continue;
+      }
+
+      if (maybe[0] === key) {
+        return maybe[1] as () => Data;
+      }
+    }
+
+    parent = parent.parentElement;
+  }
+}
+
+type DataForKey<Key> = Key extends string
+  ? unknown
+  : Key extends Newable<infer T>
+    ? T
+    : Key extends () => infer T
+      ? T
+      : Key;
+
+export class Consume<Key extends object | string> extends Component<{
+  Args: {
+    key: Key;
+  };
+  Blocks: {
+    default: [
+      context: {
+        data: DataForKey<Key>;
+      },
+    ];
+  };
+}> {
+  // SAFETY: We do a runtime assert in the getter below.
+  @tracked getData!: () => DataForKey<Key>;
+
+  element: Text;
+
+  constructor(owner: Owner, args: { key: Key }) {
+    super(owner, args);
+
+    this.element = document.createTextNode("");
+  }
+
+  @cached
+  get context() {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const self = this;
+
+    return {
+      get data(): DataForKey<Key> {
+        const getData = findForKey<Key>(self.element, self.args.key);
+
+        assert(
+          `Could not find provided context in <Consume>. Please assure that there is a corresponding <Provide> component before using this <Consume> component`,
+          getData,
+        );
+
+        // SAFETY: return type handled by getter's signature
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return getData() as any;
+      },
+    };
+  }
+
+  <template>
+    {{this.element}}
+
+    {{yield this.context}}
+  </template>
+}