chore: refactor to indeterminate default

Author: caseyisonit

2nd-gen/packages/core/components/progress-circle/ProgressCircle.base.ts

@@ -9,6 +9,7 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
+
 import { PropertyValues } from 'lit';
 import { property } from 'lit/decorators.js';
 
@@ -24,6 +25,14 @@ import {
   ProgressCircleStaticColor,
 } from './ProgressCircle.types.js';
 
+/**
+ * @todo SWC-1891 Extract shared progress logic (ARIA, label, clamping, formatting,
+ * indeterminate derivation) into a `ProgressBase` mixin or abstract class in
+ * `core/components/progress/` so that both `ProgressCircleBase` and a future
+ * `ProgressBarBase` can extend it. Also add `formatOptions` support for
+ * progress-bar's custom value labels (e.g. "3 of 10", "45 MB / 100 MB").
+ */
+
 /**
  * A progress circle component that visually represents the completion progress of a task.
  * Can be used in both determinate (with specific progress value) and indeterminate (loading) states.
@@ -68,39 +77,44 @@ export abstract class ProgressCircleBase extends SizedMixin(SpectrumElement, {
   //     SHARED API
   // ──────────────────
 
-  /**
-   * @todo Revisit the default API for `indeterminate` and `progress`. SWC-1891
-   *
-   * Whether the progress circle shows indeterminate progress (loading state).
-   *
-   * When true, displays an animated loading indicator instead of a specific progress value.
-   */
-  @property({ type: Boolean, reflect: true })
-  public indeterminate = false;
-
   /**
    * Accessible label for the progress circle.
    *
    * Used to provide context about what is loading or progressing.
+   * When no accessible name is provided (no label, aria-label, or
+   * aria-labelledby), a default "Loading" label is applied.
+   *
+   * @todo Localize the default "Loading" fallback via LanguageResolutionController
+   * once a runtime i18n system for static strings is available.
    */
   @property({ type: String })
   public label = '';
 
   /**
    * Progress value from 0 to 100.
    *
-   * Only relevant when indeterminate is false. Values outside that range or
-   * non-finite numbers are clamped to 0–100 (non-finite becomes 0).
+   * When `null` (indeterminate), the component shows a loading animation.
+   * Setting a number switches to determinate mode. Removing the `progress`
+   * attribute or setting this property to `null` returns to indeterminate.
+   * Values outside 0–100 or non-finite numbers are clamped (non-finite becomes 0).
+   *
+   * Reflected to the `progress` attribute when set; the attribute is omitted when indeterminate.
    */
-  @property({ type: Number })
-  public progress = 0;
+  @property({ type: Number, reflect: true })
+  public progress: number | null = null;
 
   private languageResolver = new LanguageResolutionController(this);
 
   // ──────────────────────
   //     IMPLEMENTATION
   // ──────────────────────
 
+  /**
+   * @todo Localize via LanguageResolutionController once a runtime i18n
+   * system for static strings is available.
+   */
+  private static readonly DEFAULT_LABEL = 'Loading';
+
   /** True when light DOM has element nodes or non-whitespace text (no default slot). */
   private static hasMeaningfulLightDomChildren(host: HTMLElement): boolean {
     for (const node of host.childNodes) {
@@ -114,6 +128,28 @@ export abstract class ProgressCircleBase extends SizedMixin(SpectrumElement, {
     return false;
   }
 
+  private hasAccessibleName(): boolean {
+    return Boolean(
+      this.label ||
+      this.getAttribute('aria-label') ||
+      this.getAttribute('aria-labelledby')
+    );
+  }
+
+  private static clampProgress(value: number): number {
+    if (!Number.isFinite(value)) {
+      return 0;
+    }
+    return Math.min(100, Math.max(0, value));
+  }
+
+  private formatProgress(): string {
+    return new Intl.NumberFormat(this.languageResolver.language, {
+      style: 'percent',
+      unitDisplay: 'narrow',
+    }).format((this.progress ?? 0) / 100);
+  }
+
   private warnDeprecatedLightDomChildren(): void {
     if (!window.__swc?.DEBUG) {
       return;
@@ -129,15 +165,27 @@ export abstract class ProgressCircleBase extends SizedMixin(SpectrumElement, {
     );
   }
 
-  private static clampProgress(value: number): number {
-    if (!Number.isFinite(value)) {
-      return 0;
+  private warnMissingAccessibleName(): void {
+    if (!window.__swc?.DEBUG) {
+      return;
     }
-    return Math.min(100, Math.max(0, value));
+    window.__swc?.warn(
+      this,
+      `<${this.localName}> requires an accessible name. A default label of "${ProgressCircleBase.DEFAULT_LABEL}" has been applied, but a more specific label should be provided via:`,
+      'https://opensource.adobe.com/spectrum-web-components/second-gen/?path=/docs/components-progress-circle--docs',
+      {
+        type: 'accessibility',
+        issues: [
+          'value supplied to the "label" attribute, which will be displayed visually as part of the element, or',
+          'value supplied to the "aria-label" attribute, which will only be provided to screen readers, or',
+          'an element ID reference supplied to the "aria-labelledby" attribute, which will be provided by screen readers and will need to be managed manually by the parent application.',
+        ],
+      }
+    );
   }
 
   protected override willUpdate(changes: PropertyValues): void {
-    if (changes.has('progress')) {
+    if (changes.has('progress') && this.progress !== null) {
       const clamped = ProgressCircleBase.clampProgress(this.progress);
       if (clamped !== this.progress) {
         this.progress = clamped;
@@ -148,22 +196,14 @@ export abstract class ProgressCircleBase extends SizedMixin(SpectrumElement, {
 
   protected override firstUpdated(changes: PropertyValues): void {
     super.firstUpdated(changes);
-    if (!this.hasAttribute('role')) {
-      this.setAttribute('role', 'progressbar');
-    }
-  }
-
-  private formatProgress(): string {
-    return new Intl.NumberFormat(this.languageResolver.language, {
-      style: 'percent',
-      unitDisplay: 'narrow',
-    }).format(this.progress / 100);
+    this.setAttribute('role', 'progressbar');
   }
 
   protected override updated(changes: PropertyValues): void {
     super.updated(changes);
-    if (changes.has('indeterminate')) {
-      if (this.indeterminate) {
+
+    if (changes.has('progress')) {
+      if (this.progress === null) {
         this.removeAttribute('aria-valuemin');
         this.removeAttribute('aria-valuemax');
         this.removeAttribute('aria-valuenow');
@@ -175,13 +215,11 @@ export abstract class ProgressCircleBase extends SizedMixin(SpectrumElement, {
         this.setAttribute('aria-valuetext', this.formatProgress());
       }
     }
-    if (!this.indeterminate && changes.has('progress')) {
-      this.setAttribute('aria-valuenow', String(this.progress));
-      this.setAttribute('aria-valuetext', this.formatProgress());
-    }
-    if (!this.indeterminate && changes.has(languageResolverUpdatedSymbol)) {
+
+    if (this.progress !== null && changes.has(languageResolverUpdatedSymbol)) {
       this.setAttribute('aria-valuetext', this.formatProgress());
     }
+
     if (changes.has('label')) {
       if (this.label.length) {
         this.setAttribute('aria-label', this.label);
@@ -190,31 +228,14 @@ export abstract class ProgressCircleBase extends SizedMixin(SpectrumElement, {
       }
     }
 
-    const hasAccessibleName = (): boolean => {
-      return Boolean(
-        this.label ||
-        this.getAttribute('aria-label') ||
-        this.getAttribute('aria-labelledby')
-      );
-    };
+    // Apply default accessible name fallback after handling explicit label changes.
+    if (changes.has('label') && !this.hasAccessibleName()) {
+      this.setAttribute('aria-label', ProgressCircleBase.DEFAULT_LABEL);
+      this.warnMissingAccessibleName();
+    }
 
     if (window.__swc?.DEBUG) {
       this.warnDeprecatedLightDomChildren();
-      if (!hasAccessibleName() && this.getAttribute('role') === 'progressbar') {
-        window.__swc?.warn(
-          this,
-          `<${this.localName}> elements need one of the following to be accessible:`,
-          'https://opensource.adobe.com/spectrum-web-components/second-gen/?path=/docs/components-progress-circle--docs',
-          {
-            type: 'accessibility',
-            issues: [
-              'value supplied to the "label" attribute, which will be displayed visually as part of the element, or',
-              'value supplied to the "aria-label" attribute, which will only be provided to screen readers, or',
-              'an element ID reference supplied to the "aria-labelledby" attribute, which will be provided by screen readers and will need to be managed manually by the parent application.',
-            ],
-          }
-        );
-      }
     }
   }
 }

2nd-gen/packages/core/components/progress-circle/ProgressCircle.types.ts

@@ -16,8 +16,9 @@ export const PROGRESS_CIRCLE_VALID_SIZES = [
   's',
   'm',
   'l',
-] as const satisfies ElementSize[];
+] as const satisfies readonly ElementSize[];
 export const PROGRESS_CIRCLE_STATIC_COLORS = ['white', 'black'] as const;
 
 export type ProgressCircleStaticColor =
   (typeof PROGRESS_CIRCLE_STATIC_COLORS)[number];
+export type ProgressCircleSize = (typeof PROGRESS_CIRCLE_VALID_SIZES)[number];

2nd-gen/packages/swc/.storybook/preview.ts

@@ -179,7 +179,7 @@ const preview = {
       },
       source: {
         excludeDecorators: true,
-        type: 'auto',
+        type: 'dynamic',
         language: 'html',
         transform: async (source: string) => {
           try {

2nd-gen/packages/swc/components/progress-circle/ProgressCircle.ts

@@ -13,6 +13,7 @@
 import { CSSResultArray, html, TemplateResult } from 'lit';
 import { property } from 'lit/decorators.js';
 import { classMap } from 'lit/directives/class-map.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
 
 import {
   PROGRESS_CIRCLE_STATIC_COLORS,
@@ -25,25 +26,23 @@ import styles from './progress-circle.css';
 
 /**
  * Progress circles show the progression of a system operation such as downloading, uploading, processing, etc. in a visual way.
+ *
  * They can represent determinate (with a specific progress value) or indeterminate (loading) progress.
  *
  * @element swc-progress-circle
  * @status preview
  * @since 0.0.1
  *
  * @property {string} staticColor - Reflected as the `static-color` attribute. Static color variant for use on different backgrounds.
- * @property {number} progress - Progress value between 0 and 100.
- * @property {boolean} indeterminate - Indeterminate state for loading.
+ * @property {number | null} progress - Progress between 0 and 100, reflected as the `progress` attribute when set. When `null` (indeterminate), the attribute is omitted.
  * @property {string} size - Size of the component.
  * @property {string} label - Label for the component.
  *
  * @example
  * <swc-progress-circle progress="75" label="Loading progress"></swc-progress-circle>
  *
  * @example
- * <swc-progress-circle indeterminate label="Loading..."></swc-progress-circle>
- *
- * Light DOM children are not projected into the shadow tree. Use the `label` attribute or property, or `aria-label` / `aria-labelledby` on the host, for an accessible name.
+ * <swc-progress-circle label="Loading..."></swc-progress-circle>
  */
 export class ProgressCircle extends ProgressCircleBase {
   // ────────────────────
@@ -73,26 +72,37 @@ export class ProgressCircle extends ProgressCircleBase {
     return [styles];
   }
 
+  /**
+   * Compute the SVG stroke-dashoffset for the fill circle.
+   *
+   * - **Indeterminate** (`progress` is `null`): returns `undefined` so CSS
+   *   animation keyframes fully control the offset.
+   * - **0%**: returns 98 instead of 100. A dashoffset of 100 hides the fill
+   *   entirely, which fails WCAG 1.4.11 non-text contrast (the track alone
+   *   may not meet 3:1 against the background). The 2-unit fill keeps the
+   *   graphical element perceivable. `aria-valuenow` stays at 0.
+   * - **1–100%**: returns `100 - progress`.
+   */
+  private computeDashOffset(): number | undefined {
+    if (this.progress === null) {
+      return undefined;
+    }
+    if (this.progress === 0) {
+      return 98;
+    }
+    return 100 - this.progress;
+  }
+
   protected override render(): TemplateResult {
     const strokeWidth = this.size === 's' ? 2 : this.size === 'l' ? 6 : 4;
     // SVG strokes are centered, so subtract half the stroke width from the radius to create an inner stroke.
     const radius = `calc(50% - ${strokeWidth / 2}px)`;
 
-    // At progress=0, a dashoffset of 100 makes the fill fully invisible, which fails WCAG 1.4.11
-    // non-text contrast (the track alone may not meet 3:1 against the background).
-    // Clamp to 98 to show a minimum 2-unit fill so the graphical element remains perceivable.
-    // aria-valuenow stays at 0 — this is a visual-only adjustment.
-    const dashOffset = this.indeterminate
-      ? 100 - this.progress
-      : this.progress === 0
-        ? 98
-        : 100 - this.progress;
-
     return html`
       <div
         class=${classMap({
           ['swc-ProgressCircle']: true,
-          ['swc-ProgressCircle--indeterminate']: this.indeterminate,
+          ['swc-ProgressCircle--indeterminate']: this.progress === null,
           [`swc-ProgressCircle--static${capitalize(this.staticColor)}`]:
             typeof this.staticColor !== 'undefined',
         })}
@@ -117,7 +127,7 @@ export class ProgressCircle extends ProgressCircleBase {
             class="swc-ProgressCircle-fill"
             pathLength="100"
             stroke-dasharray="100 200"
-            stroke-dashoffset=${dashOffset}
+            stroke-dashoffset=${ifDefined(this.computeDashOffset())}
             stroke-linecap="round"
           />
         </svg>