@m3e/core 1.0.0-rc.1 → 1.0.0-rc.2

package/src/shared/primitives/RippleElement.ts

@@ -1,289 +0,0 @@
-import { css, CSSResultGroup, LitElement, PropertyValues } from "lit";
-import { customElement, property } from "lit/decorators.js";
-
-import { PressedController } from "../controllers";
-import { HtmlFor, Role } from "../mixins";
-
-import { RippleToken } from "./RippleToken";
-import { DesignToken } from "../tokens";
-
-/**
- * @summary
- * Connects user input to screen reactions using ripples.
- *
- * @description
- * The `m3e-ripple` component is an absolute positioned element used to depict a ripple.
- * The parenting element must be a relative positioned element.
- *
- * The component can be attached to an interactive element using the `for` attribute or programmatically using the `attach` method.
- * The ripple is displayed when the interactive element is pressed and hidden when released.  This can be disabled using the `disabled` attribute.
- *
- * The pressed state actives either using both pointer and keyboard events. For keyboard events, `SPACE` and `ENTER` activate a ripple.
- * You can disabled whether the `ENTER` key actives a ripple using the `disable-enter` attribute.
- *
- * Alternately, you can use the `show` and `hide` methods to programmatically control the ripple.
- *
- * @example
- * The following example illustrates attaching a ripple to an interactive element. In this example, the parenting div
- * has relative positioning and is given an `id` referenced by `m3e-ripple` using the `for` attribute.  Note that `#myDiv`
- * is not used when specifying the attached element's identifier.  The `#` is inferred.
- *
- * ```html
- * <div id="myDiv" tabindex="0" style="position: relative;">
- *  <m3e-ripple for="myDiv"></m3e-ripple>
- * <div>
- * ```
- *
- * @tag m3e-ripple
- *
- * @attr centered - Whether the ripple always originates from the center of the element's bounds, rather than originating from the location of the click event.
- * @attr disable-enter - Whether the ripple is disabled when the enter key is pressed.
- * @attr disabled - Whether click events will not trigger the ripple.  Ripples can be still controlled manually by using the `show` and 'hide' methods.
- * @attr for - The identifier of the interactive control to which this element is attached.
- * @attr radius - The radius, in pixels, of the ripple.
- * @attr unbounded - Whether the ripple is visible outside the element's bounds.
- *
- * @cssprop --m3e-ripple-color - The color of the ripple.
- * @cssprop --m3e-ripple-enter-duration - The duration for the enter animation (expansion from point of contact).
- * @cssprop --m3e-ripple-exit-duration - The duration for the exit animation (fade-out).
- * @cssprop --m3e-ripple-opacity - The opacity of the ripple.
- * @cssprop --m3e-ripple-scale-factor - The factor by which to scale the ripple.
- * @cssprop --m3e-ripple-shape - The shape of the ripple.
- */
-@customElement("m3e-ripple")
-export class M3eRippleElement extends HtmlFor(Role(LitElement, "none")) {
-  /** The styles of the element. */
-  static override styles: CSSResultGroup = css`
-    :host {
-      display: block;
-      position: absolute;
-      left: 0;
-      top: 0;
-      right: 0;
-      bottom: 0;
-      pointer-events: none;
-      border-radius: inherit;
-    }
-    :host(:not([unbounded])) {
-      overflow: hidden;
-    }
-    .ripple {
-      display: block;
-      position: absolute;
-      left: 0;
-      top: 0;
-      right: 0;
-      bottom: 0;
-      pointer-events: none;
-      transform: scale(0);
-      border-radius: ${DesignToken.shape.corner.full};
-      background-color: color-mix(in srgb, ${RippleToken.color} ${RippleToken.opacity}, transparent);
-      will-change: background-color, opacity;
-    }
-    .ripple:not(.persistent) {
-      animation: ripple ${RippleToken.enterDuration} linear;
-    }
-    .ripple.persistent {
-      animation: persistent-ripple ${RippleToken.enterDuration} linear;
-    }
-    .ripple.persistent.pressed {
-      transform: scale(${RippleToken.scaleFactor});
-    }
-    .ripple.exit {
-      transition: opacity ${RippleToken.exitDuration} cubic-bezier(0, 0, 0.2, 0.1);
-      opacity: 0;
-    }
-    @keyframes persistent-ripple {
-      to {
-        transform: scale(${RippleToken.scaleFactor});
-      }
-    }
-    @keyframes ripple {
-      to {
-        transform: scale(${RippleToken.scaleFactor});
-      }
-    }
-    @media (prefers-reduced-motion) {
-      .ripple {
-        transform: scale(${RippleToken.scaleFactor});
-      }
-      .ripple:not(.persistent),
-      .ripple.persistent {
-        animation-duration: 90ms;
-      }
-      .ripple.exit {
-        transition-duration: 10ms;
-      }
-    }
-    @media (forced-colors: active) {
-      .ripple {
-        display: none;
-      }
-    }
-  `;
-
-  /** @private */ #ripple: HTMLElement | null = null;
-  /** @private */ readonly #pressedController = new PressedController(this, {
-    target: null,
-    isPressedKey: (key) => key === " " || (!this.disableEnter && key === "Enter"),
-    callback: (pressed, { x, y }) => this.#handlePressedChange(pressed, x, y),
-  });
-
-  /**
-   * Whether click events will not trigger the ripple.
-   * Ripples can be still controlled manually by using the `show` and 'hide' methods.
-   * @default false
-   */
-  @property({ type: Boolean, reflect: true }) disabled = false;
-
-  /**
-   * Whether the ripple is disabled when the enter key is pressed.
-   * @default false
-   */
-  @property({ attribute: "disable-enter", type: Boolean, reflect: true }) disableEnter = false;
-
-  /**
-   * Whether the ripple always originates from the center of the element's bounds, rather
-   * than originating from the location of the click event.
-   * @default false
-   */
-  @property({ type: Boolean, reflect: true }) centered = false;
-
-  /**
-   * Whether the ripple is visible outside the element's bounds.
-   * @default false
-   */
-  @property({ type: Boolean, reflect: true }) unbounded = false;
-
-  /**
-   * The radius, in pixels, of the ripple.
-   * @default null
-   */
-  @property({ type: Number }) radius: number | null = null;
-
-  /**
-   * The element that triggers the ripple when click events are received.
-   * @default null
-   */
-  @property() trigger: string | HTMLElement | null = null;
-
-  /** Whether the ripple is currently visible to the user. */
-  get visible() {
-    return this.#ripple !== null;
-  }
-
-  /**
-   * Launches a manual ripple.
-   * @param {number} x The x-coordinate, relative to the viewport, at which to present the ripple.
-   * @param {number} y The y-coordinate, relative to the viewport, at which to present the ripple.
-   * @param {boolean} [persistent=false] Whether the ripple will persist until hidden.
-   */
-  show(x: number, y: number, persistent: boolean = false): void {
-    this.#destroyRipple();
-
-    const bounds = this.getBoundingClientRect();
-    if (this.centered) {
-      x = bounds.left + bounds.width / 2;
-      y = bounds.top + bounds.height / 2;
-    }
-
-    let radius = this.radius;
-
-    if (!radius || isNaN(radius)) {
-      const distX = Math.max(Math.abs(x - bounds.left), Math.abs(x - bounds.right));
-      const distY = Math.max(Math.abs(y - bounds.top), Math.abs(y - bounds.bottom));
-      radius = Math.sqrt(distX * distX + distY * distY);
-    }
-
-    const offsetX = x - bounds.left;
-    const offsetY = y - bounds.top;
-
-    this.#ripple = document.createElement("div");
-    this.#ripple.classList.add("ripple");
-    if (persistent) {
-      this.#ripple.classList.add("persistent");
-    }
-
-    this.#ripple.style.left = `${offsetX - radius}px`;
-    this.#ripple.style.top = `${offsetY - radius}px`;
-    this.#ripple.style.width = `${radius * 2}px`;
-    this.#ripple.style.height = `${radius * 2}px`;
-
-    this.#ripple.addEventListener("animationend", () => this.#handleAnimationEnd(persistent), { once: true });
-    this.#ripple.addEventListener("transitionend", () => this.#destroyRipple(), { once: true });
-
-    this.shadowRoot?.appendChild(this.#ripple);
-  }
-
-  /** Manually hides the ripple. */
-  hide(): void {
-    this.#ripple?.classList.add("exit");
-  }
-
-  /** @inheritdoc */
-  override attach(control: HTMLElement): void {
-    super.attach(control);
-    this.#pressedController.observe(control);
-  }
-
-  /** @inheritdoc */
-  override detach(): void {
-    if (this.control) {
-      this.#pressedController.unobserve(this.control);
-    }
-    super.detach();
-  }
-
-  /** @inheritdoc */
-  override connectedCallback(): void {
-    this.ariaHidden = "true";
-    super.connectedCallback();
-  }
-
-  /** @inheritdoc */
-  override disconnectedCallback(): void {
-    super.disconnectedCallback();
-    this.#destroyRipple();
-  }
-
-  /** @inheritdoc */
-  protected override updated(_changedProperties: PropertyValues<this>): void {
-    super.updated(_changedProperties);
-
-    if (_changedProperties.has("disabled") && this.disabled) {
-      this.hide();
-    }
-  }
-
-  /** @private */
-  #destroyRipple(): void {
-    this.#ripple?.remove();
-    this.#ripple = null;
-  }
-
-  /** @private */
-  #handleAnimationEnd(persistent: boolean): void {
-    if (persistent) {
-      this.#ripple?.classList.add("pressed");
-    } else {
-      this.hide();
-    }
-  }
-
-  /** @private */
-  #handlePressedChange(pressed: boolean, x: number, y: number): void {
-    if (!this.disabled) {
-      if (pressed) {
-        this.show(x, y, true);
-      } else {
-        this.hide();
-      }
-    }
-  }
-}
-
-declare global {
-  interface HTMLElementTagNameMap {
-    "m3e-ripple": M3eRippleElement;
-  }
-}

package/src/shared/primitives/RippleToken.ts

@@ -1,15 +0,0 @@
-import { unsafeCSS } from "lit";
-
-import { DesignToken } from "../tokens";
-
-/**
- * Component design tokens that control the `M3eRippleElement`.
- * @internal
- */
-export const RippleToken = {
-  color: unsafeCSS(`var(--m3e-ripple-color, ${DesignToken.color.onSurface})`),
-  opacity: unsafeCSS(`var(--m3e-ripple-opacity, ${DesignToken.state.pressedStateLayerOpacity})`),
-  enterDuration: unsafeCSS(`var(--m3e-ripple-enter-duration, ${DesignToken.motion.duration.long4})`),
-  exitDuration: unsafeCSS(`var(--m3e-ripple-exit-duration, ${DesignToken.motion.duration.short2})`),
-  scaleFactor: unsafeCSS(`var(--m3e-ripple-scale-factor, 2.5)`),
-} as const;

package/src/shared/primitives/ScrollContainerElement.ts

@@ -1,151 +0,0 @@
-import { css, CSSResultGroup, html, LitElement, PropertyValues } from "lit";
-import { customElement, property } from "lit/decorators.js";
-
-import { Role } from "../mixins";
-import { debounce } from "../decorators";
-import { DesignToken } from "../tokens";
-
-import { ScrollDividers } from "./ScrollDividers";
-
-/**
- * @summary
- * A vertically oriented content container which presents dividers above and below content when scrolled.
- *
- * @description
- * The `m3e-scroll-container` component provides a vertically oriented scrollable container with dynamic
- * dividers above and below content. Designed according to Material 3 principles, it supports custom scrollbar
- * thickness, divider styling, and focus ring theming via CSS custom properties.
- *
- * @example
- * This example shows a scrollable container with dividers above and below the content, and thin scrollbars enabled.
- * ```html
- * <m3e-scroll-container dividers="above-below" thin>
- *   <div>Scrollable content goes here</div>
- * </m3e-scroll-container>
- * ```
- *
- * @tag m3e-scroll-container
- *
- * @slot - Renders the scrollable content.
- *
- * @attr dividers - The dividers used to separate scrollable content.
- * @attr thin - Whether to present thin scrollbars.
- *
- * @cssprop --m3e-divider-thickness - Thickness of the divider lines above and below content.
- * @cssprop --m3e-divider-color - Color of the divider lines when visible.
- * @cssprop --m3e-focus-ring-color - Color of the focus ring outline.
- * @cssprop --m3e-focus-ring-thickness - Thickness of the focus ring outline.
- * @cssprop --m3e-focus-ring-factor - Animation factor for focus ring thickness.
- * @cssprop --m3e-focus-ring-duration - Duration of the focus ring animation.
- */
-@customElement("m3e-scroll-container")
-export class M3eScrollContainerElement extends Role(LitElement, "none") {
-  /** The styles of the element. */
-  static override styles: CSSResultGroup = css`
-    :host {
-      display: block;
-      overflow-y: auto;
-      position: relative;
-      box-sizing: border-box;
-      scrollbar-color: ${DesignToken.scrollbar.color};
-      border-top: var(--m3e-divider-thickness, 1px) solid transparent;
-      border-bottom: var(--m3e-divider-thickness, 1px) solid transparent;
-      outline: var(--m3e-focus-ring-color, ${DesignToken.color.secondary});
-      outline-width: var(--m3e-focus-ring-thickness, 0.25rem);
-      outline-offset: calc(var(--m3e-focus-ring-thickness, 0.25rem) / 2);
-    }
-    :host([thin]) {
-      scrollbar-width: ${DesignToken.scrollbar.thinWidth};
-    }
-    :host(:not([thin])) {
-      scrollbar-width: ${DesignToken.scrollbar.width};
-    }
-    :host(:not(:focus-visible).-above) {
-      border-top-color: var(--m3e-divider-color, ${DesignToken.color.outlineVariant});
-    }
-    :host(:not(:focus-visible).-below) {
-      border-bottom-color: var(--m3e-divider-color, ${DesignToken.color.outlineVariant});
-    }
-    :host(:focus-visible) {
-      outline-style: solid;
-      animation: grow-shrink var(--m3e-focus-ring-duration, ${DesignToken.motion.duration.long2});
-    }
-    @keyframes grow-shrink {
-      50% {
-        outline-width: calc(var(--m3e-focus-ring-thickness, 0.25rem) * var(--m3e-focus-ring-factor, 2));
-      }
-    }
-    @media (forced-colors: active) {
-      :host {
-        border-top: var(--m3e-divider-thickness, 1px) solid Canvas;
-        border-bottom: var(--m3e-divider-thickness, 1px) solid Canvas;
-      }
-      :host(:not(:focus-visible).-above) {
-        border-top-color: GrayText;
-      }
-      :host(:not(:focus-visible).-below) {
-        border-bottom-color: GrayText;
-      }
-    }
-    @media (prefers-reduced-motion) {
-      :host(:focus-visible) {
-        animation: none;
-      }
-    }
-  `;
-
-  /** @private */ readonly #scrollHandler = () => this._updateScroll();
-
-  /**
-   * The dividers used to separate scrollable content.
-   * @default "above-below"
-   */
-  @property() dividers: ScrollDividers = "above-below";
-
-  /**
-   * Whether to present thin scrollbars.
-   * @default false
-   */
-  @property({ type: Boolean, reflect: true }) thin = false;
-
-  /** @inheritdoc */
-  override disconnectedCallback(): void {
-    super.disconnectedCallback();
-    this.removeEventListener("scroll", this.#scrollHandler);
-  }
-
-  /** @inheritdoc */
-  protected override update(changedProperties: PropertyValues<this>): void {
-    super.update(changedProperties);
-
-    if (changedProperties.has("dividers")) {
-      this.removeEventListener("scroll", this.#scrollHandler);
-      if (this.dividers !== "none") {
-        this.addEventListener("scroll", this.#scrollHandler);
-      }
-    }
-  }
-
-  /** @inheritdoc */
-  protected override render(): unknown {
-    return html`<slot @slotchange="${this._updateScroll}"></slot>`;
-  }
-
-  /** @private */
-  @debounce(40)
-  private _updateScroll(): void {
-    const before = (this.dividers === "above" || this.dividers === "above-below") && this.scrollTop > 0;
-    const after =
-      (this.dividers === "below" || this.dividers === "above-below") &&
-      this.scrollHeight - this.scrollTop - this.clientHeight > 1;
-
-    this.classList.toggle("-above", before);
-    this.classList.toggle("-below", after);
-  }
-}
-
-declare global {
-  interface HTMLElementTagNameMap {
-    "m3e-scroll-container": M3eScrollContainerElement;
-  }
-}

package/src/shared/primitives/ScrollDividers.ts

@@ -1,2 +0,0 @@
-/** Specifies the possible dividers used to separate scrollable content. */
-export type ScrollDividers = "above" | "below" | "above-below" | "none";

package/src/shared/primitives/SlideElement.ts

@@ -1,128 +0,0 @@
-import { css, CSSResultGroup, html, LitElement, PropertyValues, unsafeCSS } from "lit";
-import { customElement, property, queryAssignedElements } from "lit/decorators.js";
-
-import { DesignToken } from "../tokens";
-import { Role } from "../mixins";
-
-/**
- * A carousel-like container used to horizontally cycle through slotted items.
- *
- * @example
- * The following example illustrates the use of `m3e-slide` to cycle through content.
- * In this example, `selected-index` is set to `1` so that "Content at index 1" is presented
- * by the component.
- * ```html
- * <m3e-slide selected-index="1">
- *  <div>Content at index 0</div>
- *  <div>Content at index 1</div>
- *  <div>Content at index 2</div>
- *  <div>Content at index 3</div>
- * </m3e-slide>
- * ```
- *
- * @tag m3e-slide
- *
- * @attr selected-index - The zero-based index of the visible item.
- *
- * @cssprop --m3e-slide-animation-duration - The duration of transitions between slotted items.
- */
-@customElement("m3e-slide")
-export class M3eSlide extends Role(LitElement, "none") {
-  /** The styles of the element. */
-  static override styles: CSSResultGroup = css`
-    :host {
-      display: flex;
-      position: relative;
-      overflow: hidden;
-    }
-    ::slotted(*) {
-      width: 100%;
-      top: 0;
-      transition: ${unsafeCSS(
-        `left var(--m3e-slide-animation-duration, ${DesignToken.motion.duration.long2}) ${DesignToken.motion.easing.standard},
-        visibility var(--m3e-slide-animation-duration, ${DesignToken.motion.duration.long2}) ${DesignToken.motion.easing.standard} allow-discrete`
-      )};
-    }
-    ::slotted(.-before),
-    ::slotted(.-after) {
-      visibility: hidden;
-      position: absolute;
-    }
-    ::slotted(.-before) {
-      left: -100%;
-    }
-    ::slotted(.-after) {
-      left: 100%;
-    }
-    ::slotted(:not(.-before):not(.-after)) {
-      visibility: visible;
-      position: relative;
-      left: 0;
-    }
-    :host(.-no-animate) ::slotted(*) {
-      transition: none;
-    }
-    @media (prefers-reduced-motion) {
-      ::slotted(*) {
-        transition: none;
-      }
-    }
-  `;
-
-  /** @private */ @queryAssignedElements({ flatten: true }) private readonly _items!: Element[];
-
-  /**
-   * The zero-based index of the visible item.
-   * @default null
-   */
-  @property({ attribute: "selected-index", type: Number, reflect: true }) selectedIndex: number | null = null;
-
-  /** @inheritdoc */
-  override connectedCallback(): void {
-    super.connectedCallback();
-    this.classList.toggle("-no-animate", true);
-  }
-
-  /** @inheritdoc */
-  protected override update(changedProperties: PropertyValues<this>): void {
-    super.update(changedProperties);
-
-    if (changedProperties.has("selectedIndex")) {
-      if (this.selectedIndex === null) {
-        this.classList.toggle("-no-animate", true);
-      }
-
-      this.#updateItems();
-
-      if (this.selectedIndex !== null && this.classList.contains("-no-animate")) {
-        requestAnimationFrame(() => {
-          if (this.selectedIndex !== null) {
-            this.classList.toggle("-no-animate", false);
-          }
-        });
-      }
-    }
-  }
-
-  /** @inheritdoc */
-  protected override render(): unknown {
-    return html`<slot @slotchange="${this.#updateItems}"></slot>`;
-  }
-
-  /** @private */
-  #updateItems(): void {
-    const selectedIndex = this.selectedIndex ?? this._items.length;
-    for (let i = 0; i < this._items.length; i++) {
-      const item = this._items[i];
-      item.classList.toggle("-before", i < selectedIndex);
-      item.classList.toggle("-after", i > selectedIndex);
-      item.toggleAttribute("inert", i !== selectedIndex);
-    }
-  }
-}
-
-declare global {
-  interface HTMLElementTagNameMap {
-    "m3e-slide": M3eSlide;
-  }
-}