@lostgradient/cinder 0.9.0 → 0.12.0

package/dist/components/run-step-timeline/run-step-timeline.svelte.d.ts

@@ -1,18 +1,4 @@
-/**
- * @cinder
- * @category data-display
- * @status stable
- * @purpose Ordered step-by-step execution rail that visualizes async run state with per-step status, durations, retries, optional progress, and expandable detail panels.
- * @tag timeline
- * @tag progress
- * @tag execution
- * @useWhen Displaying the live or completed state of a multi-step async operation: CI jobs, workflow runs, import pipelines, or deployments.
- * @useWhen Showing a sequence where one step is currently active and prior steps have streamed in over time.
- * @avoidWhen Guiding users through an interactive wizard where they choose what to do next — use steps instead.
- * @avoidWhen Showing a flat timestamp-first event log without structured step state — use timeline instead.
- * @related timeline, steps, status-dot, progress, badge, collapsible
- */
-export type { RunStep, RunStepDetail, RunStepLink, RunStepStatus, RunStepTimelineProps, } from './run-step-timeline.types.ts';
+export type { RunStep, RunStepBranchGroup, RunStepBranchLane, RunStepBranchLaneOutcome, RunStepDetail, RunStepLink, RunStepStatus, RunStepTimelineEntry, RunStepTimelineProps, } from './run-step-timeline.types.ts';
 import type { RunStepTimelineProps } from './run-step-timeline.types.ts';
 declare const RunStepTimeline: import("svelte").Component<RunStepTimelineProps, {}, "">;
 type RunStepTimeline = ReturnType<typeof RunStepTimeline>;

package/dist/components/run-step-timeline/run-step-timeline.types.d.ts

@@ -91,11 +91,91 @@ export type RunStep = {
      * Optional link to logs, traces, or a step detail route.
      */
     link?: RunStepLink | undefined;
+    /**
+     * Marks a step that was speculatively executed and then unwound (rolled
+     * back). Orthogonal to `status`: the step keeps its real terminal status
+     * underneath, but renders struck-through and de-emphasized while staying
+     * inspectable. A rewound step announces its unwound state to assistive
+     * technology in addition to its status.
+     */
+    rewound?: boolean | undefined;
+    /**
+     * Id of the forward step that this step compensates (reverses), as in a
+     * saga rollback. When set, the step renders inset beneath its forward step
+     * with a dashed reversal connector. The referenced id should be a sibling
+     * step's `id`; an unmatched id renders the step in place without inset.
+     */
+    compensates?: string | undefined;
     /**
      * Nested child-workflow steps rendered as indented lanes.
      */
     children?: RunStep[] | undefined;
 };
+/**
+ * Outcome of a single sub-lane within a {@link RunStepBranchGroup}.
+ *
+ * - `won`     — this lane produced the committed result; emphasized.
+ * - `lost`    — this lane was superseded by the winner; muted.
+ * - `settled` — this lane completed without a competitive winner/loser
+ *               distinction (e.g. all lanes were kept). Neutral emphasis.
+ *
+ * Omit the outcome entirely while a race is still in flight.
+ */
+export type RunStepBranchLaneOutcome = 'won' | 'lost' | 'settled';
+/**
+ * One parallel sub-lane inside a {@link RunStepBranchGroup}. Each lane is an
+ * ordered sequence of steps that executed concurrently with its siblings.
+ */
+export type RunStepBranchLane = {
+    /** Stable identity; used as the keyed list identity within the group. */
+    id: string;
+    /** Optional display label for the lane (e.g. the candidate or strategy name). */
+    label?: string | undefined;
+    /**
+     * Competitive outcome for the lane. Drives winner emphasis / loser muting.
+     * Omit while the branch is still racing.
+     */
+    outcome?: RunStepBranchLaneOutcome | undefined;
+    /** Ordered steps that ran within this lane. */
+    steps: RunStep[];
+};
+/**
+ * A branch/coordination group: a single timeline entry that fans out into N
+ * parallel sub-lanes (e.g. a speculative race or a scatter/gather). Rendered
+ * with the lanes side by side conceptually — the winning lane emphasized and
+ * the losers muted — and collapsible. Distinguished from a plain {@link RunStep}
+ * by its `kind` discriminator, mirroring the additive-entry pattern used by
+ * other cinder timelines.
+ *
+ * @schemaObject
+ */
+export type RunStepBranchGroup = {
+    /** Discriminator identifying a branch-group entry. */
+    kind: 'branch';
+    /** Stable identity; used as the keyed list identity. */
+    id: string;
+    /** Display label for the branch group (e.g. "Race deploy candidates"). */
+    label: string;
+    /** The parallel sub-lanes. Order is presentational only. */
+    lanes: RunStepBranchLane[];
+    /**
+     * Collapse the group by default once the lane count reaches this threshold.
+     * Defaults to 3. Set to a large number to effectively disable auto-collapse.
+     */
+    collapseThreshold?: number | undefined;
+    /**
+     * Force the initial collapsed (`true`) or expanded (`false`) state,
+     * overriding `collapseThreshold`. The group remains user-togglable.
+     */
+    collapsed?: boolean | undefined;
+};
+/**
+ * A single top-level entry in a RunStepTimeline: either a normal step or a
+ * branch/coordination group. Existing `RunStep[]` arrays remain valid because
+ * the union is additive and branch groups are opt-in via the `kind`
+ * discriminator.
+ */
+export type RunStepTimelineEntry = RunStep | RunStepBranchGroup;
 /**
  * Schema generator surface for one top-level step.
  * Public `RunStep` stays recursive; this finite shape keeps JSON Schema generation bounded.
@@ -150,6 +230,10 @@ export type RunStepTimelineSchemaStep = {
      * Optional link to logs, traces, or a step detail route.
      */
     link?: RunStepLink | undefined;
+    /** Marks a step that was speculatively executed and then unwound (rolled back). */
+    rewound?: boolean | undefined;
+    /** Id of the forward step that this step compensates (reverses). */
+    compensates?: string | undefined;
     /**
      * Schema-bounded nested child-workflow steps.
      */
@@ -184,6 +268,10 @@ export type RunStepTimelineSchemaChildStep = {
     details?: RunStepDetail[] | undefined;
     /** Optional link to logs, traces, or a step detail route. */
     link?: RunStepLink | undefined;
+    /** Marks a step that was speculatively executed and then unwound (rolled back). */
+    rewound?: boolean | undefined;
+    /** Id of the forward step that this step compensates (reverses). */
+    compensates?: string | undefined;
     /**
      * Nested child-workflow steps rendered at depth 2.
      */
@@ -218,6 +306,10 @@ export type RunStepTimelineSchemaGrandchildStep = {
     details?: RunStepDetail[] | undefined;
     /** Optional link to logs, traces, or a step detail route. */
     link?: RunStepLink | undefined;
+    /** Marks a step that was speculatively executed and then unwound (rolled back). */
+    rewound?: boolean | undefined;
+    /** Id of the forward step that this step compensates (reverses). */
+    compensates?: string | undefined;
     /**
      * Nested child-workflow steps rendered at depth 3.
      */
@@ -252,7 +344,91 @@ export type RunStepTimelineSchemaGreatGrandchildStep = {
     details?: RunStepDetail[] | undefined;
     /** Optional link to logs, traces, or a step detail route. */
     link?: RunStepLink | undefined;
+    /** Marks a step that was speculatively executed and then unwound (rolled back). */
+    rewound?: boolean | undefined;
+    /** Id of the forward step that this step compensates (reverses). */
+    compensates?: string | undefined;
 };
+/**
+ * Schema-facing step used for branch-lane sequences. Lane steps are
+ * `RunStep[]` at runtime and can nest, so this type carries an optional
+ * `children` array of the same shape (recursive at the type level, for
+ * consumer-typing convenience) that validates lane-step children as steps.
+ * The generated JSON Schema depth-caps this nesting to the same rendered depth
+ * as the main rail; the recursive TYPE is the ergonomic mirror of that
+ * depth-capped schema, not an assertion that arbitrary depth is rendered.
+ * @schemaObject
+ */
+export type RunStepTimelineSchemaLaneStep = {
+    /** Stable identity; used as the keyed list identity. */
+    id: string;
+    /** Display label for this step. */
+    label: string;
+    /** Generic execution state. */
+    status: RunStepStatus;
+    /** ISO datetime string for when this step started. */
+    startTime?: string | undefined;
+    /** ISO datetime string for when this step ended. */
+    endTime?: string | undefined;
+    /** Human-readable duration string, e.g. "1m 23s". */
+    duration?: string | undefined;
+    /** Number of attempts made so far, including any retries. */
+    attemptCount?: number | undefined;
+    /** Number of actions associated with this step. */
+    actionsCount?: number | undefined;
+    /** Optional determinate progress value between 0 and `progressMax`. */
+    progress?: number | undefined;
+    /** Maximum value for the progress bar. Defaults to 100. */
+    progressMax?: number | undefined;
+    /** Expandable detail panels (logs, payloads, errors) shown inline. */
+    details?: RunStepDetail[] | undefined;
+    /** Optional link to logs, traces, or a step detail route. */
+    link?: RunStepLink | undefined;
+    /** Marks a step that was speculatively executed and then unwound (rolled back). */
+    rewound?: boolean | undefined;
+    /** Id of the forward step that this step compensates (reverses). */
+    compensates?: string | undefined;
+    /** Nested steps within a branch lane. */
+    children?: RunStepTimelineSchemaLaneStep[] | undefined;
+};
+/**
+ * Schema-bounded sub-lane inside a {@link RunStepTimelineSchemaBranchGroup}.
+ * Lane steps are bounded to a leaf surface so JSON Schema generation stays
+ * finite.
+ * @schemaObject
+ */
+export type RunStepTimelineSchemaBranchLane = {
+    /** Stable identity; used as the keyed list identity within the group. */
+    id: string;
+    /** Optional display label for the lane. */
+    label?: string | undefined;
+    /** Competitive outcome for the lane. Omit while the branch is still racing. */
+    outcome?: RunStepBranchLaneOutcome | undefined;
+    /** Ordered steps that ran within this lane. */
+    steps: RunStepTimelineSchemaLaneStep[];
+};
+/**
+ * Schema generator surface for one top-level branch/coordination group.
+ * @schemaObject
+ */
+export type RunStepTimelineSchemaBranchGroup = {
+    /** Discriminator identifying a branch-group entry. */
+    kind: 'branch';
+    /** Stable identity; used as the keyed list identity. */
+    id: string;
+    /** Display label for the branch group. */
+    label: string;
+    /** The parallel sub-lanes. */
+    lanes: RunStepTimelineSchemaBranchLane[];
+    /** Collapse the group by default once the lane count reaches this threshold. Defaults to 3. */
+    collapseThreshold?: number | undefined;
+    /** Force the initial collapsed (`true`) or expanded (`false`) state. */
+    collapsed?: boolean | undefined;
+};
+/**
+ * A single schema-bounded top-level entry: either a step or a branch group.
+ */
+export type RunStepTimelineSchemaEntry = RunStepTimelineSchemaStep | RunStepTimelineSchemaBranchGroup;
 /**
  * Props for the RunStepTimeline component.
  *
@@ -262,10 +438,12 @@ export type RunStepTimelineSchemaGreatGrandchildStep = {
  */
 export type RunStepTimelineProps = Omit<HTMLAttributes<HTMLOListElement>, 'class' | 'children'> & {
     /**
-     * Ordered list of steps to render.
+     * Ordered list of timeline entries to render. Each entry is either a
+     * {@link RunStep} or a {@link RunStepBranchGroup}. Plain `RunStep[]` arrays
+     * remain valid — branch groups are opt-in via the `kind` discriminator.
      * @schemaObject
      */
-    steps: RunStep[];
+    steps: RunStepTimelineEntry[];
     /**
      * Accessible label for the timeline list.
      * Used as `aria-label` when `aria-labelledby` is absent.
@@ -281,10 +459,9 @@ export type RunStepTimelineProps = Omit<HTMLAttributes<HTMLOListElement>, 'class
 /** Schema generator surface for RunStepTimeline — excludes snippet props. */
 export interface RunStepTimelineSchemaProps {
     /**
-     * Ordered list of steps to render.
-     * @schemaObject
+     * Ordered list of timeline entries to render — either steps or branch groups.
      */
-    steps: RunStepTimelineSchemaStep[];
+    steps: RunStepTimelineSchemaEntry[];
     /** Accessible label for the timeline list. */
     label?: string | undefined;
     /** Additional CSS classes applied to the root element. */

package/dist/components/run-step-timeline/run-step-timeline.utilities.d.ts

@@ -0,0 +1,60 @@
+import type { StatusDotStatus } from '../status-dot/status-dot.types.ts';
+import type { RunStep, RunStepBranchGroup, RunStepBranchLane, RunStepBranchLaneOutcome, RunStepStatus, RunStepTimelineEntry } from './run-step-timeline.types.ts';
+/**
+ * Relocate resolved compensation steps immediately after the subtree of the
+ * sibling they reverse. Unresolved, self-referential, and cyclic links retain
+ * consumer order. Multiple compensations retain their relative input order.
+ */
+export declare function relocateCompensationSteps(steps: RunStep[]): RunStep[];
+/** Relocate top-level compensations while preserving branch rows as rail entries. */
+export declare function relocateCompensationEntries(entries: RunStepTimelineEntry[]): RunStepTimelineEntry[];
+/** Badge variants used for the per-step status chip. */
+export type RunStepBadgeVariant = 'neutral' | 'success' | 'warning' | 'danger' | 'info' | 'accent';
+/** Map a generic {@link RunStepStatus} onto a StatusDot status token. */
+export declare function statusDotStatus(status: RunStepStatus): StatusDotStatus;
+/** Human-readable label for the StatusDot accessible name. */
+export declare function statusLabel(status: RunStepStatus): string;
+/** Map a {@link RunStepStatus} to a Badge variant for the status chip. */
+export declare function badgeVariant(status: RunStepStatus): RunStepBadgeVariant;
+/** Whether this status is a terminal state (no further changes expected). */
+export declare function isTerminal(status: RunStepStatus): boolean;
+/** Whether this status represents an in-flight ("current") step. */
+export declare function isCurrent(status: RunStepStatus): boolean;
+/** Whether this step should render a progress bar. */
+export declare function hasProgress(step: RunStep): boolean;
+/** Metadata items for a step, as term/definition pairs. */
+export declare function metadataItems(step: RunStep): {
+    term: string;
+    definition: string;
+}[];
+/** Pluralized "N action(s)" label. */
+export declare function actionsCountLabel(actionsCount: number): string;
+/** Pluralized "N nested step(s) hidden" label for the depth-cap row. */
+export declare function hiddenNestedStepLabel(hiddenStepCount: number): string;
+/** Human-readable label for a branch-lane outcome, used in badges and announcements. */
+export declare function laneOutcomeLabel(outcome: RunStepBranchLaneOutcome): string;
+/** Badge variant for a branch-lane outcome. */
+export declare function laneOutcomeBadgeVariant(outcome: RunStepBranchLaneOutcome): RunStepBadgeVariant;
+/**
+ * One-line accessible summary of a branch group's lane outcomes, e.g.
+ * "1 won, 2 lost" or "3 lanes racing" while outcomes are still pending.
+ */
+export declare function branchOutcomeSummary(lanes: RunStepBranchLane[]): string;
+/**
+ * Whether any step in any lane of a branch group is currently in-flight.
+ * Iterative (explicit stack) so a deeply-nested lane can't overflow the call
+ * stack — this runs before the render path's depth cap.
+ */
+export declare function branchGroupHasCurrentStep(group: RunStepBranchGroup): boolean;
+/**
+ * Resolve whether a branch group starts collapsed. An explicit `collapsed`
+ * wins; otherwise the group collapses once its lane count reaches the
+ * threshold (default 3).
+ */
+export declare function branchStartsCollapsed(laneCount: number, collapseThreshold: number | undefined, collapsed: boolean | undefined): boolean;
+/**
+ * Normalize a step link href to a safe value, or `undefined` when the href is
+ * empty, control-character-laden, backslash-bearing, protocol-relative, or a
+ * non-http(s) scheme.
+ */
+export declare function safeStepLinkHref(href: string): string | undefined;

package/dist/components/schedule-builder/index.d.ts

@@ -0,0 +1,5 @@
+import './schedule-builder.css';
+import ScheduleBuilder from './schedule-builder.svelte';
+export default ScheduleBuilder;
+export type { ScheduleAuthoringMode, ScheduleBuilderProps, ScheduleBuilderSchemaProps, ScheduleFire, ScheduleIntervalUnit, ScheduleValue, ScheduleValueSchema, } from './schedule-builder.types.ts';
+export { ScheduleBuilder };