@luzmo/lucero 2.3.0-beta.0 → 2.4.1

package/components/progress-steps/progress-steps.d.ts

@@ -1,148 +1,134 @@
-import { TemplateResult } from 'lit';
+import { CSSResultArray, nothing, PropertyValues, TemplateResult } from 'lit';
 import { LuzmoElement } from '../../utils/base';
-import type { ProgressStepsDisplayMode, ProgressStepsLabels, ProgressTreeNode } from './types';
+import { type ProgressStepsDisplayMode, type ProgressStepsLabels, type ProgressTreeNode } from './types';
 declare const LuzmoProgressSteps_base: typeof LuzmoElement & {
     new (...args: any[]): import("../..").SizedElementInterface;
     prototype: import("../..").SizedElementInterface;
 };
 /**
  * @element luzmo-progress-steps
- * @summary A component for displaying real-time Progress status steps with substeps
+ * @summary Shows the progress of a multi-step process, such as an AI response,
+ * as a single line that expands into the full step history.
+ *
+ * While a run is in progress, the line shows the newest running step and its
+ * newest running substep. Once the run finishes, it shows how many steps ran.
+ * Activating the line opens the history.
  *
  * @attr size - The size of the component: s, m, l or xl
  * @attr locale - Locale for resolving localized strings (default: 'en')
- * @attr collapsed - When true, collapses all auto-expanded steps
- * @attr condensed - When true, hides all steps behind a single "{n} steps completed" toggle line
- * @attr display-mode - Display mode: 'detailed' (default) shows substeps and descriptions, 'compact' shows only step names
+ * @attr collapsed - Signals the run has finished, so the line settles into its summary as soon as no step runs
+ * @attr condensed - Deprecated, no effect: every state is condensed into one line
+ * @attr display-mode - 'detailed' (default) lists substeps in the history, 'compact' lists main steps only
+ * @attr no-animate - Disables the shimmer and transitions
+ * @attr open - Whether the step history is shown
+ *
+ * @fires luzmo-step-expanded - The user opened the step history. `detail.nodeId` is the progress root id.
+ * @fires luzmo-step-collapsed - The user closed the step history. `detail.nodeId` is the progress root id.
  *
- * @fires luzmo-step-expanded - Fired when a step is expanded
- * @fires luzmo-step-collapsed - Fired when a step is collapsed
+ * @cssprop --luzmo-progress-steps-font-size - Font size of the summary line
+ * @cssprop --luzmo-progress-steps-font-size-small - Font size of the step history
+ * @cssprop --luzmo-progress-steps-font-color - Color of emphasized text
+ * @cssprop --luzmo-progress-steps-font-color-dimmed - Color of the summary line and substeps
+ * @cssprop --luzmo-progress-steps-error-color - Color of failed steps
+ * @cssprop --luzmo-progress-steps-warning-color - Color of the failure icon in the summary line
+ * @cssprop --luzmo-progress-steps-success-color - Color of the checkmark in the summary line once a run finishes without failures
+ * @cssprop --luzmo-progress-steps-substep-connector-color - Color of the timeline rail in the history and the spinner track
  */
 export declare class LuzmoProgressSteps extends LuzmoProgressSteps_base {
-    static styles: import("lit").CSSResult[];
+    static get styles(): CSSResultArray;
     /**
-     * The progress tree from the backend.
-     * The root node's children are rendered as main steps.
+     * The progress tree. The root's children are the main steps.
+     * Replace the whole tree on every update; keep the root `id` for the same run.
      */
     progress: ProgressTreeNode | null;
     /**
      * Locale for resolving localized strings in description metadata.
-     * Defaults to 'en'.
      */
     locale: string;
     /**
-     * When true, collapses all auto-expanded steps.
-     * Manually expanded steps remain open.
+     * Signals that the run has finished. The summary line then settles as soon
+     * as no step is running, instead of after a short quiet period.
      */
     collapsed: boolean;
     /**
-     * Display mode for the progress steps.
-     * - 'detailed' (default): Shows full descriptions and substeps with expand/collapse
-     * - 'compact': Shows only step names without substeps or expand/collapse
+     * - 'detailed' (default): the history lists main steps with their substeps
+     * - 'compact': the history lists main steps only
      */
     displayMode: ProgressStepsDisplayMode;
     /**
-     * When true, hides all steps behind a single "{n} steps completed" toggle line.
-     * Clicking the toggle expands/collapses the full step list.
+     * @deprecated Has no effect. Every state is condensed into one line.
      */
     condensed: boolean;
     /**
-     * Labels used for visible text and screen readers.
-     * The default values are in English and can be overridden to localize the content.
-     * Use `{{count}}` in `stepCompleted` / `stepsCompleted` as a placeholder for the step count.
+     * Visible and announced copy. Partial overrides are merged over the
+     * English defaults. `{{count}}` is replaced in the count labels.
      */
-    labels: ProgressStepsLabels;
+    labels: Partial<ProgressStepsLabels>;
     /**
-     * When true, disables all entry animations (stepFadeIn, substepFadeIn).
-     * @default false
+     * Disables the shimmer and transitions.
      */
     noAnimate: boolean;
     /**
-     * Whether the condensed toggle has been expanded by the user.
-     * @internal
-     */
-    private _condensedExpanded;
-    /**
-     * Set of node IDs that are manually expanded by the user
-     * @internal
-     */
-    private _expandedNodes;
-    /**
-     * Nodes that were auto-expanded because they were in-progress.
-     * @internal
-     */
-    private _autoExpandedNodes;
-    /**
-     * Nodes explicitly expanded by the user.
-     * @internal
-     */
-    private _manuallyExpandedNodes;
-    willUpdate(changedProperties: Map<string, unknown>): void;
-    /**
-     * Handles progress changes, clearing state when progress is reset or root changes
-     * @internal
-     */
-    private _handleProgressChange;
-    /**
-     * Clears all expansion state for a fresh progress tree
-     * @internal
-     */
-    private _clearExpansionState;
-    /**
-     * Handle auto-expand for in-progress nodes
-     * @internal
-     */
-    private _handleAutoExpandCollapse;
-    /**
-     * Collapse all auto-expanded nodes that weren't manually expanded
-     * @internal
-     */
-    private _collapseAutoExpandedNodes;
-    /**
-     * Re-expand in-progress nodes when collapsed changes to false
-     * @internal
-     */
-    private _reExpandInProgressNodes;
-    /** @internal */
-    private _reExpandInProgressNodesRecursive;
-    /**
-     * Map backend status to CSS-friendly status
-     * @internal
-     */
-    private _mapStatus;
-    /**
-     * Resolve a localized string to the current locale
-     * @internal
-     */
-    private _resolveLocalizedString;
-    /**
-     * Interpolate description with metadata values
-     * Replaces {{key}} placeholders with values from descriptionMetadata
-     * @internal
-     */
-    private _interpolateDescription;
-    /** @internal */
-    private _toggleNodeExpansion;
-    /** @internal */
-    private _isNodeExpanded;
-    /** @internal */
-    private _renderStepIcon;
-    /** @internal */
-    private _renderChevron;
-    /** @internal */
-    private _renderSubsteps;
-    /** @internal */
+     * Whether the step history is shown. Closes when a run with another root
+     * `id` starts.
+     */
+    open: boolean;
+    private _phase;
+    private _current;
+    private _leaving;
+    private _subStepTransition;
+    private _announcement;
+    private _languageResolver;
+    private _numberFormatter?;
+    private _pending;
+    private _shownAt;
+    private _dwellTimer?;
+    private _settleTimer?;
+    private _leaveTimer?;
+    private _announceTimer?;
+    private _resizeObserver?;
+    /** Whether the shown line shows its substep alone. */
+    private _subStepOnly;
+    /** Whether the leaving line showed its substep alone. */
+    private _leavingSubStepOnly;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changes: PropertyValues): void;
+    protected updated(changes: PropertyValues): void;
+    /**
+     * Shows the substep alone when the main step and substep don't both fit
+     * whole. The main step stays in the accessible name. Runs before paint, so
+     * the measuring layout is never shown.
+     */
+    private _fitLine;
+    private get _labels();
+    /** Moves between running and finished based on the latest tree. */
+    private _syncPhase;
+    private _queue;
+    private _showPending;
+    private _finish;
+    private _show;
+    private _announce;
+    private _resetRun;
+    private _clearDwellTimer;
+    private _clearSettleTimer;
+    private _clearTimers;
+    private _formatCount;
+    /** Formats counts for the resolved page language; cached until it changes. */
+    private get _numberFormat();
+    private _summaryText;
+    private _setOpen;
+    private handleToggle;
+    private handleKeydown;
+    private _statusLabel;
+    private _renderStatusIcon;
+    private _renderContent;
+    /** A dot on the timeline rail; only a failed step gets an icon. */
+    private _renderStepMarker;
     private _renderSubstep;
-    /** @internal */
+    private _renderSubsteps;
     private _renderStep;
-    /** @internal */
-    private _toggleCondensed;
-    /** @internal */
-    private _handleCondensedKeydown;
-    /** @internal */
-    private _renderCondensed;
-    /** @internal */
-    private _renderSteps;
-    render(): TemplateResult;
+    private _renderDetails;
+    render(): TemplateResult | typeof nothing;
 }
 export {};

package/components/progress-steps/types.d.ts

@@ -1,16 +1,26 @@
+/**
+ * Visible and announced copy. `{{count}}` is replaced in the count labels.
+ */
 export interface ProgressStepsLabels {
+    /** Summary once a run with one main step has finished. */
     condensedSingular: string;
+    /** Summary once a run with several main steps has finished. */
     condensedPlural: string;
+    /** Failure count when exactly one step failed. */
+    failedSingular: string;
+    /** Failure count when several steps failed. */
+    failedPlural: string;
     stepInProgress: string;
     stepPending: string;
     stepCompleted: string;
     stepFailed: string;
 }
+export declare const DEFAULT_PROGRESS_STEPS_LABELS: ProgressStepsLabels;
 export type ProgressStepsStatuses = 'pending' | 'inProgress' | 'success' | 'error';
 /**
- * Display mode for progress steps
- * - 'detailed': Shows full descriptions and substeps with expand/collapse
- * - 'compact': Shows only step names without substeps
+ * Display mode for the step history
+ * - 'detailed': Lists main steps with their substeps
+ * - 'compact': Lists main steps only
  */
 export type ProgressStepsDisplayMode = 'detailed' | 'compact';
 export type LocalizedString = Record<string, string>;
@@ -30,3 +40,8 @@ export type ProgressTreeNode = {
     description?: string;
     descriptionMetadata?: ProgressTreeNodeDescriptionMetadata;
 };
+/** Detail of `luzmo-step-expanded` and `luzmo-step-collapsed`. */
+export type ProgressStepsToggleDetail = {
+    /** Id of the progress tree root. */
+    nodeId: string;
+};