ember-primitives 0.49.0 → 0.50.0

package/src/components/progress.gts

@@ -0,0 +1,154 @@
+import Component from "@glimmer/component";
+import { hash } from "@ember/helper";
+
+import type { TOC } from "@ember/component/template-only";
+import type { WithBoundArgs } from "@glint/template";
+
+export interface Signature {
+  Element: HTMLDivElement;
+  Args: {
+    /**
+     * The current progress
+     * This may be less than 0 or more than `max`,
+     * but the resolved value (managed internally, and yielded out)
+     * does not exceed the range [0, max]
+     */
+    value: number;
+    /**
+     * The max value, defaults to 100
+     */
+    max?: number;
+  };
+  Blocks: {
+    default: [
+      {
+        /**
+         * The indicator element with some state applied.
+         * This can be used to style the progress of bar.
+         */
+        Indicator: WithBoundArgs<typeof Indicator, "value" | "max" | "percent">;
+        /**
+         * The value as a percent of how far along the indicator should be
+         * positioned, between 0 and 100.
+         * Will be rounded to two decimal places.
+         */
+        percent: number;
+        /**
+         * The value as a percent of how far along the indicator should be positioned,
+         * between 0 and 1
+         */
+        decimal: number;
+        /**
+         * The resolved value within the limits of the progress bar.
+         */
+        value: number;
+      },
+    ];
+  };
+}
+
+type ProgressState = "indeterminate" | "complete" | "loading";
+
+const DEFAULT_MAX = 100;
+
+/**
+ * Non-negative, non-NaN, non-Infinite, positive, rational
+ */
+function isValidProgressNumber(value: number | undefined | null): value is number {
+  if (typeof value !== "number") return false;
+  if (!Number.isFinite(value)) return false;
+
+  return value >= 0;
+}
+
+function progressState(value: number | undefined | null, maxValue: number): ProgressState {
+  return value == null ? "indeterminate" : value === maxValue ? "complete" : "loading";
+}
+
+function getMax(userMax: number | undefined | null): number {
+  return isValidProgressNumber(userMax) ? userMax : DEFAULT_MAX;
+}
+
+function getValue(userValue: number | undefined | null, maxValue: number): number {
+  const max = getMax(maxValue);
+
+  if (!isValidProgressNumber(userValue)) {
+    return 0;
+  }
+
+  if (userValue > max) {
+    return max;
+  }
+
+  return userValue;
+}
+
+function getValueLabel(value: number, max: number) {
+  return `${Math.round((value / max) * 100)}%`;
+}
+
+const Indicator: TOC<{
+  Element: HTMLDivElement;
+  Args: { max: number; value: number; percent: number };
+  Blocks: { default: [] };
+}> = <template>
+  <div
+    ...attributes
+    data-max={{@max}}
+    data-value={{@value}}
+    data-state={{progressState @value @max}}
+    data-percent={{@percent}}
+  >
+    {{yield}}
+  </div>
+</template>;
+
+export class Progress extends Component<Signature> {
+  get max() {
+    return getMax(this.args.max);
+  }
+
+  get value() {
+    return getValue(this.args.value, this.max);
+  }
+
+  get valueLabel() {
+    return getValueLabel(this.value, this.max);
+  }
+
+  get decimal() {
+    return this.value / this.max;
+  }
+
+  get percent() {
+    return Math.round(this.decimal * 100 * 100) / 100;
+  }
+
+  <template>
+    <div
+      ...attributes
+      aria-valuemax={{this.max}}
+      aria-valuemin="0"
+      aria-valuenow={{this.value}}
+      aria-valuetext={{this.valueLabel}}
+      role="progressbar"
+      data-value={{this.value}}
+      data-state={{progressState this.value this.max}}
+      data-max={{this.max}}
+      data-min="0"
+      data-percent={{this.percent}}
+    >
+
+      {{yield
+        (hash
+          Indicator=(component Indicator value=this.value max=this.max percent=this.percent)
+          value=this.value
+          percent=this.percent
+          decimal=this.decimal
+        )
+      }}
+    </div>
+  </template>
+}
+
+export default Progress;

package/src/components/rating/public-types.ts

@@ -0,0 +1,44 @@
+import type { ComponentLike } from '@glint/template';
+
+/**
+ * @public
+ */
+export interface ComponentIcons {
+  /**
+   * It's possible to completely manage the state of an individual Icon yourself
+   * by passing a component that has ...attributes on its outer element and receives
+   * a @isSelected argument which is true for selected and false for unselected.
+   *
+   * There is also argument passed which is the percent-amount of selection if you want fractional ratings, @selectedPercent
+   */
+  icon: ComponentLike<{
+    Element: HTMLElement;
+    Args: {
+      /**
+       * Is this item selected?
+       */
+      isSelected: boolean;
+      /**
+       * Which number of item is this item within the overall rating group.
+       */
+      value: number;
+      /**
+       * Should this be marked as readonly
+       */
+      readonly: boolean;
+    };
+  }>;
+}
+
+/**
+ * @public
+ */
+export interface StringIcons {
+  /**
+   * The symbol to use for an unselected variant of the icon
+   *
+   * Defaults to "★";
+   *  Can change color when selected.
+   */
+  icon?: string;
+}

package/src/components/rating/range.gts

@@ -0,0 +1,22 @@
+import { on } from "@ember/modifier";
+
+import type { TOC } from "@ember/component/template-only";
+
+export const RatingRange: TOC<{
+  Element: HTMLInputElement;
+  Args: {
+    name: string;
+    max: number;
+    value: number;
+    handleChange: (event: Event) => void;
+  };
+}> = <template>
+  <input
+    ...attributes
+    name={{@name}}
+    type="range"
+    max={{@max}}
+    value={{@value}}
+    {{on "change" @handleChange}}
+  />
+</template>;

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"];