ember-primitives 0.48.2 → 0.50.0

package/src/components/rating/rating.gts

@@ -0,0 +1,228 @@
+import Component from "@glimmer/component";
+import { hash } from "@ember/helper";
+import { on } from "@ember/modifier";
+
+import { uniqueId } from "../../utils.ts";
+import { RatingRange } from "./range.gts";
+import { Stars } from "./stars.gts";
+import { RatingState } from "./state.gts";
+
+import type { ComponentIcons, StringIcons } from "./public-types.ts";
+import type { WithBoundArgs } from "@glint/template";
+
+export interface Signature {
+  /*
+   * The element all passed attributes / modifiers are applied to.
+   *
+   * This is a `<fieldset>`, becaues the rating elements are
+   * powered by a group of radio buttons.
+   */
+  Element: HTMLFieldSetElement;
+  Args: (ComponentIcons | StringIcons) & {
+    /**
+     * The number of stars/whichever-icon to show
+     *
+     * Defaults to 5
+     */
+    max?: number;
+
+    /**
+     * The current number of stars/whichever-icon to show as selected
+     *
+     * Defaults to 0
+     */
+    value?: number;
+
+    /**
+     * When generating the radio inputs, this changes what value of rating each radio
+     * input will be incremented by.
+     *
+     * e.g.: Set to 0.5 for half-star ratings.
+     *
+     * Defaults to 1
+     */
+    step?: number;
+
+    /**
+     * Prevents click events on the icons and sets aria-readonly.
+     *
+     * Also sets data-readonly=true on the wrapping element
+     */
+    readonly?: boolean;
+
+    /**
+     * Toggles the ability to interact with the rating component.
+     * When `true` (the default), the Rating component can be as a form input
+     * to gather user feedback.
+     *
+     * When false, only the `@value` will be shown, and it cannot be changed.
+     */
+    interactive?: boolean;
+
+    /**
+     * Callback when the selected rating changes.
+     * Can include half-ratings if the iconHalf argument is passed.
+     */
+    onChange?: (value: number) => void;
+  };
+
+  Blocks: {
+    default: [
+      rating: {
+        /**
+         * The maximum rating
+         */
+        max: number;
+        /**
+         * The maxium rating
+         */
+        total: number;
+        /**
+         * The current rating
+         */
+        value: number;
+        /**
+         * The name shared by the field group
+         */
+        name: string;
+        /**
+         * If the rating can be changed
+         */
+        isReadonly: boolean;
+        /**
+         * If the rating can be changed
+         */
+        isChangeable: boolean;
+        /**
+         * The stars / items radio group
+         */
+        Stars: WithBoundArgs<
+          typeof Stars,
+          "stars" | "icon" | "isReadonly" | "name" | "total" | "currentValue"
+        >;
+        /**
+         * Input range for adjusting the rating via fractional means
+         */
+        Range: WithBoundArgs<typeof RatingRange, "max" | "value" | "name" | "handleChange">;
+      },
+    ];
+    label: [
+      state: {
+        /**
+         * The current rating
+         */
+        value: number;
+
+        /**
+         * The maximum rating
+         */
+        total: number;
+      },
+    ];
+  };
+}
+
+export class Rating extends Component<Signature> {
+  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;
+  }
+
+  <template>
+    <RatingState
+      @max={{@max}}
+      @step={{@step}}
+      @value={{@value}}
+      @name={{this.name}}
+      @readonly={{this.isReadonly}}
+      @onChange={{@onChange}}
+      as |r publicState|
+    >
+      <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
+      >
+        {{#let
+          (component
+            Stars
+            stars=r.stars
+            icon=this.icon
+            isReadonly=this.isReadonly
+            name=this.name
+            total=r.total
+            currentValue=r.value
+          )
+          as |RatingStars|
+        }}
+
+          {{#if (has-block)}}
+            {{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
+                  step=r.step
+                  max=r.total
+                  value=r.value
+                  name=this.name
+                  handleChange=r.handleChange
+                )
+              )
+            }}
+          {{else}}
+            {{#if this.needsDescription}}
+              {{#if (has-block "label")}}
+                {{yield publicState to="label"}}
+              {{else}}
+                <span visually-hidden class="ember-primitives__rating__label">Rated
+                  {{r.value}}
+                  out of
+                  {{r.total}}</span>
+              {{/if}}
+            {{else}}
+              {{#if (has-block "label")}}
+                <legend>
+                  {{yield publicState to="label"}}
+                </legend>
+              {{/if}}
+            {{/if}}
+
+            <RatingStars />
+          {{/if}}
+        {{/let}}
+
+      </fieldset>
+    </RatingState>
+  </template>
+}

package/src/components/rating/stars.gts

@@ -0,0 +1,60 @@
+import { uniqueId } from "../../utils.ts";
+import { isString, lte } from "./utils.ts";
+
+import type { ComponentIcons, StringIcons } from "./public-types.ts";
+import type { TOC } from "@ember/component/template-only";
+
+export const Stars: TOC<{
+  Args: {
+    // Configuration
+    stars: number[];
+    icon: StringIcons["icon"] | ComponentIcons["icon"];
+    isReadonly: boolean;
+
+    // HTML Boilerplate
+    name: string;
+
+    // State
+    currentValue: number;
+    total: number;
+  };
+}> = <template>
+  <div class="ember-primitives__rating__items">
+    {{#each @stars as |star|}}
+      {{#let (uniqueId) as |id|}}
+        <span
+          class="ember-primitives__rating__item"
+          data-number={{star}}
+          data-selected={{lte star @currentValue}}
+          data-readonly={{@isReadonly}}
+        >
+          <label for="input-{{id}}">
+            <span visually-hidden>{{star}} star</span>
+            {{#if @icon}}
+              <span aria-hidden="true">
+                {{#if (isString @icon)}}
+                  {{@icon}}
+                {{else}}
+                  <@icon
+                    @value={{star}}
+                    @isSelected={{lte star @currentValue}}
+                    @readonly={{@isReadonly}}
+                  />
+                {{/if}}
+              </span>
+            {{/if}}
+          </label>
+
+          <input
+            id="input-{{id}}"
+            type="radio"
+            name={{@name}}
+            value={{star}}
+            readonly={{@isReadonly}}
+            checked={{Object.is star @currentValue}}
+          />
+        </span>
+      {{/let}}
+    {{/each}}
+  </div>
+</template>;

package/src/components/rating/state.gts

@@ -0,0 +1,144 @@
+import Component from "@glimmer/component";
+import { cached } from "@glimmer/tracking";
+import { assert } from "@ember/debug";
+import { hash } from "@ember/helper";
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-expect-error
+import { localCopy } from "tracked-toolbox";
+
+export class RatingState extends Component<{
+  Args: {
+    max: number | undefined;
+    value: number | undefined;
+    step: number | undefined;
+    readonly: boolean | undefined;
+    name: string;
+    onChange?: (value: number) => void;
+  };
+  Blocks: {
+    default: [
+      internalApi: {
+        stars: number[];
+        step: number;
+        value: number;
+        total: number;
+        handleClick: (event: Event) => void;
+        handleChange: (event: Event) => void;
+        setRating: (num: number) => void;
+      },
+      publicApi: {
+        value: number;
+        total: number;
+      },
+    ];
+  };
+}> {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+  @localCopy("args.value") declare _value: number;
+
+  get value() {
+    return this._value ?? 0;
+  }
+
+  get step() {
+    return this.args.step ?? 1;
+  }
+
+  get max() {
+    return this.args.max ?? 5;
+  }
+
+  @cached
+  get stars() {
+    const result = [];
+
+    // 0 is "none selected"
+    let current = 0;
+
+    current += this.step;
+
+    while (current <= this.max) {
+      result.push(current);
+      current += this.step;
+    }
+
+    return result;
+  }
+
+  setRating = (value: number) => {
+    if (this.args.readonly) {
+      return;
+    }
+
+    if (value === this._value) {
+      this._value = 0;
+    } else {
+      this._value = value;
+    }
+
+    this.args.onChange?.(value);
+  };
+
+  setFromString = (value: unknown) => {
+    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: 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: Event) => {
+    const isValid = event.target !== null && "value" in event.target;
+
+    if (!isValid) return;
+
+    this.setFromString(event.target.value);
+  };
+
+  <template>
+    {{yield
+      (hash
+        stars=this.stars
+        total=this.stars.length
+        handleClick=this.handleClick
+        handleChange=this.handleChange
+        setRating=this.setRating
+        value=this.value
+        step=this.step
+      )
+      (hash total=this.stars.length value=this.value)
+    }}
+  </template>
+}

package/src/components/rating/utils.ts

@@ -0,0 +1,7 @@
+export function isString(x: unknown) {
+  return typeof x === 'string';
+}
+
+export function lte(a: number, b: number) {
+  return a <= b;
+}

package/src/components/rating.gts

@@ -0,0 +1,5 @@
+export { Rating } from "./rating/rating.gts";
+
+import type { ComponentIcons } from "./rating/public-types.ts";
+
+export type IconType = ComponentIcons["icon"];

package/src/components/scroller.gts

@@ -0,0 +1,179 @@
+import Component from "@glimmer/component";
+import { isDestroyed, isDestroying } from "@ember/destroyable";
+import { hash } from "@ember/helper";
+
+import { modifier } from "ember-modifier";
+
+/**
+ * Utility component for helping with scrolling in any direction within
+ * any of the 4 directions: up, down, left, right.
+ *
+ * This can be used to auto-scroll content as new content is inserted into the scrollable area, or possibly to bring focus to something on the page.
+ */
+export class Scroller extends Component<{
+  /**
+   * A containing element is required - in this case, a div.
+   * It must be scrollable for this component to work, but can be customized.
+   *
+   * By default, this element will have some styling applied:
+   *   overflow: auto;
+   *
+   * By default, this element will have tabindex="0" to support keyboard usage.
+   *
+   * The scroll-behavior is "auto", which can be controlled via CSS
+   * https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior
+   *
+   */
+  Element: HTMLDivElement;
+  Blocks: {
+    default: [
+      {
+        /**
+         * Scroll the content to the bottom
+         *
+         * ```gjs
+         * import { Scroller } from 'ember-primitives';
+         *
+         * <template>
+         *   <Scroller as |s|>
+         *      ...
+         *
+         *      {{ (s.scrollToBottom) }}
+         *   </Scroller>
+         * </template>
+         * ```
+         */
+        scrollToBottom: () => void;
+        /**
+         * Scroll the content to the top
+         *
+         * ```gjs
+         * import { Scroller } from 'ember-primitives';
+         *
+         * <template>
+         *   <Scroller as |s|>
+         *      ...
+         *
+         *      {{ (s.scrollToTop) }}
+         *   </Scroller>
+         * </template>
+         * ```
+         */
+        scrollToTop: () => void;
+        /**
+         * Scroll the content to the left
+         *
+         * ```gjs
+         * import { Scroller } from 'ember-primitives';
+         *
+         * <template>
+         *   <Scroller as |s|>
+         *      ...
+         *
+         *      {{ (s.scrollToLeft) }}
+         *   </Scroller>
+         * </template>
+         * ```
+         */
+        scrollToLeft: () => void;
+        /**
+         * Scroll the content to the right
+         *
+         * ```gjs
+         * import { Scroller } from 'ember-primitives';
+         *
+         * <template>
+         *   <Scroller as |s|>
+         *      ...
+         *
+         *      {{ (s.scrollToRight) }}
+         *   </Scroller>
+         * </template>
+         * ```
+         */
+        scrollToRight: () => void;
+      },
+    ];
+  };
+}> {
+  declare withinElement: HTMLDivElement;
+
+  ref = modifier((el: HTMLDivElement) => {
+    this.withinElement = el;
+  });
+
+  #frame?: number;
+
+  scrollToBottom = () => {
+    if (this.#frame) {
+      cancelAnimationFrame(this.#frame);
+    }
+
+    this.#frame = requestAnimationFrame(() => {
+      if (isDestroyed(this) || isDestroying(this)) return;
+
+      this.withinElement.scrollTo({
+        top: this.withinElement.scrollHeight,
+        behavior: "auto",
+      });
+    });
+  };
+
+  scrollToTop = () => {
+    if (this.#frame) {
+      cancelAnimationFrame(this.#frame);
+    }
+
+    this.#frame = requestAnimationFrame(() => {
+      if (isDestroyed(this) || isDestroying(this)) return;
+
+      this.withinElement.scrollTo({
+        top: 0,
+        behavior: "auto",
+      });
+    });
+  };
+
+  scrollToLeft = () => {
+    if (this.#frame) {
+      cancelAnimationFrame(this.#frame);
+    }
+
+    this.#frame = requestAnimationFrame(() => {
+      if (isDestroyed(this) || isDestroying(this)) return;
+
+      this.withinElement.scrollTo({
+        left: 0,
+        behavior: "auto",
+      });
+    });
+  };
+
+  scrollToRight = () => {
+    if (this.#frame) {
+      cancelAnimationFrame(this.#frame);
+    }
+
+    this.#frame = requestAnimationFrame(() => {
+      if (isDestroyed(this) || isDestroying(this)) return;
+
+      this.withinElement.scrollTo({
+        left: this.withinElement.scrollWidth,
+        behavior: "auto",
+      });
+    });
+  };
+
+  <template>
+    <div tabindex="0" ...attributes {{this.ref}}>
+      {{yield
+        (hash
+          scrollToBottom=this.scrollToBottom
+          scrollToTop=this.scrollToTop
+          scrollToLeft=this.scrollToLeft
+          scrollToRight=this.scrollToRight
+        )
+      }}
+    </div>
+  </template>
+}