feat(labs): add aria progress component

labs/aria/progress/demo/demo.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import './material-collection.js';
+import './index.js';
+
+import {
+  KnobTypesToKnobs,
+  MaterialCollection,
+  materialInitsToStoryInits,
+  setUpDemo,
+} from './material-collection.js';
+import {boolInput, Knob, numberInput} from './index.js';
+
+import {stories, StoryKnobs} from './stories.js';
+
+const collection = new MaterialCollection<KnobTypesToKnobs<StoryKnobs>>(
+  'ARIA Progress',
+  [
+    new Knob('indeterminate', {ui: boolInput(), defaultValue: false}),
+    new Knob('value', {ui: numberInput({step: 0.1}), defaultValue: 0.5}),
+    new Knob('max', {ui: numberInput(), defaultValue: 1}),
+  ],
+);
+
+collection.addStories(...materialInitsToStoryInits(stories));
+
+setUpDemo(collection);

labs/aria/progress/demo/stories.ts

@@ -0,0 +1,133 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import '@material/web/labs/aria/progress/md-aria-progress.js';
+
+import {MaterialStoryInit} from './material-collection.js';
+import {css, html, nothing} from 'lit';
+
+/** Knob types for ARIA Progress stories. */
+export interface StoryKnobs {
+  indeterminate?: boolean;
+  value?: number;
+  max?: number;
+}
+
+const progress: MaterialStoryInit<StoryKnobs> = {
+  name: 'progress',
+  render(knobs) {
+    return html`
+      <md-aria-progress
+        value=${knobs.indeterminate ? nothing : (knobs.value ?? nothing)}
+        max=${knobs.indeterminate
+          ? nothing
+          : (knobs.max ?? nothing)}></md-aria-progress>
+    `;
+  },
+};
+
+const progressCustom: MaterialStoryInit<StoryKnobs> = {
+  name: 'custom progress',
+  styles: css`
+    /* |@property| would be nice here... */
+    @keyframes --linear-time {
+      0% {
+        --time: 0;
+      }
+      10% {
+        --time: 0.1;
+      }
+      20% {
+        --time: 0.2;
+      }
+      30% {
+        --time: 0.3;
+      }
+      40% {
+        --time: 0.4;
+      }
+      50% {
+        --time: 0.5;
+      }
+      60% {
+        --time: 0.6;
+      }
+      70% {
+        --time: 0.7;
+      }
+      80% {
+        --time: 0.8;
+      }
+      90% {
+        --time: 0.9;
+      }
+      100% {
+        --time: 1;
+      }
+    }
+
+    #track,
+    #bar {
+      --track-border-width: 1px;
+      position: absolute;
+      inset: 0px;
+      border-radius: 10000px;
+      --bg: peachpuff;
+      --fg: coral;
+      background-color: var(--bg);
+
+      @media (forced-colors: active) {
+        --fg: CanvasText;
+      }
+    }
+
+    #track {
+      border: var(--track-border-width) solid var(--fg);
+    }
+
+    #bar {
+      --bar-inset: calc(var(--track-border-width) + 1px);
+      inset: var(--bar-inset);
+      background-color: var(--fg);
+
+      md-aria-progress:state(indeterminate) & {
+        forced-color-adjust: none;
+        background-color: transparent;
+        background-image: repeating-linear-gradient(
+          to right,
+          transparent 0px,
+          transparent clamp(0px, calc(-5px + 10px * var(--time)), 10px),
+          var(--fg) clamp(0px, calc(-5px + 10px * var(--time)), 10px),
+          var(--fg) clamp(0px, calc(0px + 10px * var(--time)), 10px),
+          transparent clamp(0px, calc(0px + 10px * var(--time)), 10px),
+          transparent clamp(0px, calc(5px + 10px * var(--time)), 10px),
+          var(--fg) clamp(0px, calc(5px + 10px * var(--time)), 10px),
+          var(--fg) 10px
+        );
+        animation: --linear-time 1s infinite linear;
+      }
+
+      md-aria-progress:not(:state(indeterminate)) & {
+        width: calc(
+          100% * var(--md-aria-progress-position) - 2 * var(--bar-inset)
+        );
+      }
+    }
+  `,
+  render(knobs) {
+    return html`
+      <md-aria-progress
+        value=${knobs.indeterminate ? nothing : (knobs.value ?? nothing)}
+        max=${knobs.indeterminate ? nothing : (knobs.max ?? nothing)}>
+        <div id="track"></div>
+        <div id="bar"></div>
+      </md-aria-progress>
+    `;
+  },
+};
+
+/** ARIA Progress stories. */
+export const stories = [progress, progressCustom];

labs/aria/progress/md-aria-progress.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {AriaProgressElement} from './progress.js';
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'md-aria-progress': AriaProgressElement;
+  }
+}
+
+customElements.define('md-aria-progress', AriaProgressElement);

labs/aria/progress/progress.ts

@@ -0,0 +1,216 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {LitElement, PropertyValues, css, html, isServer} from 'lit';
+import {state} from 'lit/decorators.js';
+import {
+  mixinCustomStateSet,
+  toggleState,
+} from '../../behaviors/custom-state-set.js';
+import {
+  internals,
+  mixinElementInternals,
+} from '../../behaviors/element-internals.js';
+
+const baseClass = mixinCustomStateSet(mixinElementInternals(LitElement));
+
+/**
+ * An ARIA progress element.
+ *
+ * @cssstate indeterminate - True when the progress has no `value`.
+ * @slot - Use this slot to replace the default rendered content of this
+ *     component. These CSS properties are available to slotted content:
+ *
+ *   - `--md-aria-progress-value` - The current value, or `indeterminate`.
+ *   - `--md-aria-progress-max` - The maximum value.
+ *   - `--md-aria-progress-position` - The current position (value / max,
+ *       clamped to [0, 1]), or `indeterminate`.
+ */
+export class AriaProgressElement extends baseClass {
+  static override styles = css`
+    @keyframes --_indeterminate {
+      from {
+        inset-inline-start: 0%;
+      }
+      to {
+        inset-inline-start: 80%;
+      }
+    }
+
+    :host {
+      display: inline-block;
+      position: relative;
+      block-size: 1em;
+      inline-size: 10em;
+      vertical-align: -0.2em;
+      overflow: hidden;
+
+      /* These defaults are immediately overridden by inline styles. */
+      --md-aria-progress-value: indeterminate;
+      --md-aria-progress-max: 1;
+      --md-aria-progress-position: indeterminate;
+    }
+
+    :host(:not(:state(indeterminate))) {
+      --md-aria-progress-position: clamp(
+        0,
+        calc(var(--md-aria-progress-value) / var(--md-aria-progress-max)),
+        1
+      );
+    }
+
+    #track,
+    #bar {
+      display: block;
+      position: absolute;
+
+      inset: 0.25em 0px;
+      border-radius: 10000px;
+
+      background: lightgray;
+    }
+
+    #track {
+      @media (forced-colors: active) {
+        border: 1px solid transparent;
+      }
+    }
+
+    #bar {
+      background: AccentColor;
+
+      @media (forced-colors: active) {
+        background: CanvasText;
+      }
+
+      :host(:state(indeterminate)) & {
+        inset-inline: unset;
+        inline-size: 20%;
+        animation: --_indeterminate 2s ease-in-out infinite alternate;
+      }
+
+      :host(:not(:state(indeterminate))) & {
+        inline-size: calc(100% * var(--md-aria-progress-position));
+      }
+    }
+  `;
+
+  static override get observedAttributes() {
+    return [...super.observedAttributes, 'value', 'max'];
+  }
+
+  @state()
+  private internalValue: number | null = null;
+
+  @state()
+  private internalMax = 1;
+
+  constructor() {
+    super();
+    if (isServer) return;
+
+    this[internals].role = 'progressbar';
+    this[toggleState]('indeterminate', true);
+  }
+
+  /**
+   * The current value of the progress bar. Must be non-negative and is clamped
+   * between 0 and `max`.
+   */
+  get value(): number {
+    const {internalValue, internalMax} = this;
+    if (internalValue === null) {
+      return 0;
+    }
+
+    return Math.max(0, Math.min(internalValue, internalMax));
+  }
+  set value(value: number) {
+    if (value < 0) {
+      value = 0;
+    }
+
+    this.setAttribute('value', String(value));
+  }
+
+  /** The maximum value of the progress bar. Must be positive. */
+  get max(): number {
+    return this.internalMax;
+  }
+  set max(value: number) {
+    if (value <= 0) {
+      return;
+    }
+
+    this.setAttribute('max', String(value));
+  }
+
+  /** The ratio of the current to maximum values. */
+  get position(): number {
+    const {internalValue, internalMax} = this;
+
+    if (internalValue === null) {
+      return -1;
+    }
+
+    return Math.min(internalValue, internalMax) / internalMax;
+  }
+
+  override attributeChangedCallback(
+    name: string,
+    oldValue: string | null,
+    newValue: string | null,
+  ) {
+    super.attributeChangedCallback(name, oldValue, newValue);
+
+    if (name === 'value') {
+      if (newValue === null) {
+        this.internalValue = null;
+      } else {
+        const parsed = Number(newValue);
+        this.internalValue = isNaN(parsed) || parsed < 0 ? 0 : parsed;
+      }
+    }
+
+    if (name === 'max') {
+      if (newValue === null) {
+        this.internalMax = 1;
+      } else {
+        const parsed = Number(newValue);
+        this.internalMax = isNaN(parsed) || parsed <= 0 ? 1 : parsed;
+      }
+    }
+  }
+
+  protected override updated(changedProperties: PropertyValues<this>) {
+    super.updated(changedProperties);
+
+    const {internalValue, internalMax} = this;
+
+    if (internalValue === null) {
+      this[internals].ariaValueNow = null;
+      this[toggleState]('indeterminate', true);
+      this.style.setProperty('--md-aria-progress-value', 'indeterminate');
+    } else {
+      const usedValue = Math.min(internalValue, internalMax);
+      this[internals].ariaValueNow = String(usedValue);
+      this[toggleState]('indeterminate', false);
+      this.style.setProperty('--md-aria-progress-value', String(usedValue));
+    }
+
+    this[internals].ariaValueMax = String(internalMax);
+    this.style.setProperty('--md-aria-progress-max', String(internalMax));
+  }
+
+  protected override render() {
+    return html`
+      <slot>
+        <div id="track"></div>
+        <div id="bar"></div>
+      </slot>
+    `;
+  }
+}