silvery 0.17.0 → 0.17.2

package/dist/ui/progress.d.mts

@@ -0,0 +1,249 @@
+import { a as ProgressInfo, d as StepProgress } from "../types-CDgkE-Rw.mjs";
+import { i as createSpinner, r as Spinner, t as CallableSpinner } from "../spinner-Cgej6Vnb.mjs";
+import { n as TaskHandle, r as ProgressBar, t as MultiProgress } from "../multi-progress-C0-rkn86.mjs";
+
+//#region packages/ag-react/src/ui/progress/step-node.d.ts
+/**
+ * Step node tree structure for declarative steps
+ *
+ * Parses the user's declarative object structure into an internal tree
+ * that can be rendered and executed.
+ */
+/**
+ * A single step in the tree
+ */
+interface StepNode {
+  /** Display label (auto-generated or custom) */
+  label: string;
+  /** Object key from the declaration */
+  key: string;
+  /** Work function (if leaf node) */
+  work?: (...args: unknown[]) => unknown;
+  /** Child steps (if group node) */
+  children?: StepNode[];
+  /** Indentation level for display */
+  indent: number;
+}
+/**
+ * What users can declare as a step value
+ */
+type StepValue = ((...args: unknown[]) => unknown) | [string, (...args: unknown[]) => unknown] | StepsDef;
+/**
+ * The declarative structure users provide
+ */
+type StepsDef = {
+  [key: string]: StepValue;
+};
+//#endregion
+//#region packages/ag-react/src/ui/progress/als-context.d.ts
+/**
+ * Context available to work functions during step execution
+ */
+interface StepContext {
+  /** Update progress on current step */
+  progress(current: number, total: number): void;
+  /** Create a sub-step (auto-completes previous sub-step) */
+  sub(label: string): void;
+  /** Get current step label (for debugging) */
+  readonly label: string;
+}
+/**
+ * Get the current step context
+ *
+ * Safe to call anywhere - returns a no-op context when called outside
+ * of a steps() execution context.
+ *
+ * @example
+ * ```typescript
+ * async function processFiles(files: string[]) {
+ *   for (let i = 0; i < files.length; i++) {
+ *     step().progress(i + 1, files.length);
+ *     await process(files[i]);
+ *   }
+ * }
+ *
+ * // In tests (no steps context)
+ * await processFiles(["a.md", "b.md"]);  // step() returns no-op, no errors
+ *
+ * // In production (with steps context)
+ * await steps({ process: processFiles }).run();  // Shows progress
+ * ```
+ */
+declare function step(): StepContext;
+//#endregion
+//#region packages/ag-react/src/ui/progress/declarative.d.ts
+/**
+ * Options for run() and pipe() execution
+ */
+interface ExecuteOptions$1 {
+  /** Clear progress display after completion (default: false) */
+  clear?: boolean;
+}
+/**
+ * Extract the return type from a generator or async generator
+ */
+type GeneratorReturn<T> = T extends Generator<unknown, infer R, unknown> ? R : T extends AsyncGenerator<unknown, infer R, unknown> ? R : T;
+/**
+ * Unwrap the result type, handling generators specially
+ */
+type UnwrapResult<T> = Awaited<GeneratorReturn<Awaited<T>>>;
+/**
+ * Result type: maps step keys to their return values
+ */
+type StepResults<T extends StepsDef> = { [K in keyof T]: T[K] extends ((...args: unknown[]) => infer R) ? UnwrapResult<R> : T[K] extends [string, (...args: unknown[]) => infer R] ? UnwrapResult<R> : T[K] extends StepsDef ? StepResults<T[K]> : unknown };
+/**
+ * The runner object returned by steps()
+ */
+interface StepsRunner<T extends StepsDef> {
+  /** Internal: the parsed step nodes (for testing) */
+  readonly _steps: StepNode[];
+  /**
+   * Execute all steps sequentially
+   * @returns Results keyed by step name
+   */
+  run(options?: ExecuteOptions$1): Promise<StepResults<T>>;
+  /**
+   * Execute all steps in a pipeline (each receives previous result)
+   * @returns Final step's result
+   */
+  pipe(options?: ExecuteOptions$1): Promise<unknown>;
+  /**
+   * Manually signal completion (for manual execution mode)
+   */
+  done(options?: {
+    clear?: boolean;
+  }): void;
+}
+//#endregion
+//#region packages/ag-react/src/ui/progress/steps.d.ts
+/** Progress update (object form) */
+interface ProgressUpdate {
+  current?: number;
+  total?: number;
+}
+/** Declare all sub-steps upfront (optional, yield as first value) */
+interface DeclareSteps {
+  declare: string[];
+}
+/** What generators can yield */
+type StepYield = string | ProgressUpdate | DeclareSteps;
+/**
+ * Controller for creating and updating sub-steps
+ *
+ * Passed to work functions that need to report sub-step progress.
+ */
+interface StepController {
+  /** Create a new sub-step (auto-completes previous sub-step) */
+  new (label: string): void;
+  /** Update progress on current sub-step */
+  progress(current: number, total: number): void;
+  /** Explicitly complete current sub-step (optional - new() auto-completes) */
+  done(): void;
+}
+/** Work function types */
+type SyncWork<T> = () => T;
+type AsyncWork<T> = () => PromiseLike<T>;
+type SyncGeneratorWork<T> = () => Generator<StepYield, T, unknown>;
+type AsyncGeneratorWork<T> = () => AsyncGenerator<StepYield, T, unknown>;
+/** Work function with step controller for sub-step progress */
+type WorkWithStep<T> = (step: StepController) => T | PromiseLike<T>;
+type WorkFn<T> = SyncWork<T> | AsyncWork<T> | SyncGeneratorWork<T> | AsyncGeneratorWork<T> | WorkWithStep<T>;
+/** Options for execute() */
+interface ExecuteOptions {
+  /** Clear progress display after completion (default: false) */
+  clear?: boolean;
+}
+interface StepBuilder {
+  /**
+   * Add a step to run
+   *
+   * @param title - Display title for this step
+   * @param work - Function to execute. Can be:
+   *   - Sync function: `() => result`
+   *   - Async function: `async () => result`
+   *   - Sync generator: `function* () { yield "sub-step"; return result; }`
+   *   - Async generator: `async function* () { yield "sub-step"; return result; }`
+   *
+   * Generators can yield:
+   *   - `"string"` - Creates a new sub-step with that label
+   *   - `{ current: N, total: M }` - Updates progress on current sub-step
+   */
+  run<T>(title: string, work: WorkFn<T>): StepBuilder;
+  /**
+   * Execute all steps in sequence
+   * @param options - Execution options
+   * @returns Results keyed by step title
+   */
+  execute(options?: ExecuteOptions): Promise<Record<string, unknown>>;
+}
+/**
+ * Create a step runner
+ *
+ * @overload Declarative mode - pass an object to declare steps upfront
+ * @overload Fluent mode - chain steps with .run() and execute with .execute()
+ *
+ * @example Declarative mode (recommended)
+ * ```typescript
+ * const loader = steps({
+ *   loadModules,
+ *   loadRepo: { discover, parse },
+ * });
+ * const results = await loader.run({ clear: true });
+ * ```
+ *
+ * @example Fluent mode
+ * ```typescript
+ * await steps()
+ *   .run("Step 1", doStep1)
+ *   .run("Step 2", doStep2)
+ *   .execute();
+ * ```
+ */
+declare function steps<T extends StepsDef>(def: T): StepsRunner<T>;
+declare function steps(): StepBuilder;
+//#endregion
+//#region packages/ag-react/src/ui/progress/task.d.ts
+interface TaskWrapper {
+  /**
+   * Wrap work with a spinner indicator
+   * @param work - Promise, function, or generator
+   */
+  wrap<T>(work: T | PromiseLike<T> | (() => T | PromiseLike<T>) | (() => Generator<ProgressInfo, T, unknown>)): Promise<T>;
+}
+/**
+ * Create a task wrapper with spinner
+ *
+ * @param title - Display title for the task
+ * @returns TaskWrapper with wrap() method
+ */
+declare function task(title: string): TaskWrapper;
+//#endregion
+//#region packages/ag-react/src/ui/progress/tasks.d.ts
+/** Options for run() */
+interface RunOptions {
+  /** Clear progress display after completion (default: false) */
+  clear?: boolean;
+}
+interface TaskBuilder {
+  /**
+   * Add a task to the sequence
+   * @param title - Display title
+   * @param work - Function, async function, or generator
+   */
+  add<T>(title: string, work: () => T | PromiseLike<T> | Generator<ProgressInfo, T, unknown>): TaskBuilder;
+  /**
+   * Run all tasks in sequence
+   * @param options - Run options
+   * @returns Results keyed by task title
+   */
+  run(options?: RunOptions): Promise<Record<string, unknown>>;
+}
+/**
+ * Create a sequential task builder
+ *
+ * @returns TaskBuilder with add() and run() methods
+ */
+declare function tasks(): TaskBuilder;
+//#endregion
+export { CallableSpinner, ExecuteOptions, MultiProgress, ProgressBar, ProgressInfo, RunOptions, Spinner, StepBuilder, type StepContext, type StepNode, StepProgress, type StepsDef, type StepsRunner, TaskBuilder, TaskHandle, TaskWrapper, createSpinner, step, steps, task, tasks };
+//# sourceMappingURL=progress.d.mts.map

package/dist/ui/progress.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.mts","names":[],"sources":["../../packages/ag-react/src/ui/progress/step-node.ts","../../packages/ag-react/src/ui/progress/als-context.ts","../../packages/ag-react/src/ui/progress/declarative.ts","../../packages/ag-react/src/ui/progress/steps.ts","../../packages/ag-react/src/ui/progress/task.ts","../../packages/ag-react/src/ui/progress/tasks.ts"],"mappings":";;;;;;;;;;AAUA;;;;UAAiB,QAAA;EAKf;EAHA,KAAA;EAMW;EAHX,GAAA;EAMW;EAHX,IAAA,OAAW,IAAA;EAML;EAHN,QAAA,GAAW,QAAA;EASD;EANV,MAAA;AAAA;;;;KAMU,SAAA,QACH,IAAA,wCACQ,IAAA,2BACb,QAAA;;;AAKJ;KAAY,QAAA;EAAA,CACT,GAAA,WAAc,SAAA;AAAA;;;;;;UCzBA,WAAA;EDIJ;ECFX,QAAA,CAAS,OAAA,UAAiB,KAAA;EDKf;ECFX,GAAA,CAAI,KAAA;EDKE;EAAA,SCFG,KAAA;AAAA;;AARX;;;;;;;;;;;;AAwDA;;;;;;;;ACjDA;iBDiDgB,IAAA,CAAA,GAAQ,WAAA;;;;;;UCjDP,gBAAA;EFHJ;EEKX,KAAA;AAAA;;;;KAMG,eAAA,MACH,CAAA,SAAU,SAAA,8BAAuC,CAAA,GAAI,CAAA,SAAU,cAAA,8BAA4C,CAAA,GAAI,CAAA;;;;KAK5G,YAAA,MAAkB,OAAA,CAAQ,eAAA,CAAgB,OAAA,CAAQ,CAAA;;;;KAKlD,WAAA,WAAsB,QAAA,kBACb,CAAA,GAAI,CAAA,CAAE,CAAA,eAAe,IAAA,2BAC7B,YAAA,CAAa,CAAA,IACb,CAAA,CAAE,CAAA,uBAAwB,IAAA,2BACxB,YAAA,CAAa,CAAA,IACb,CAAA,CAAE,CAAA,UAAW,QAAA,GACX,WAAA,CAAY,CAAA,CAAE,CAAA;;;;UAOP,WAAA,WAAsB,QAAA;;WAE5B,MAAA,EAAQ,QAAA;EDzCF;;;;EC+Cf,GAAA,CAAI,OAAA,GAAU,gBAAA,GAAiB,OAAA,CAAQ,WAAA,CAAY,CAAA;ED7C1C;;;;ECmDT,IAAA,CAAK,OAAA,GAAU,gBAAA,GAAiB,OAAA;ED7ClB;;AAgDhB;ECEE,IAAA,CAAK,OAAA;IAAY,KAAA;EAAA;AAAA;;;;UCNT,cAAA;EACR,OAAA;EACA,KAAA;AAAA;;UAIQ,YAAA;EACR,OAAA;AAAA;;KAIG,SAAA,YAAqB,cAAA,GAAiB,YAAA;;;;;;UAO1B,cAAA;EDtDf;EAAA,KCwDK,KAAA;EDxD8B;EC2DnC,QAAA,CAAS,OAAA,UAAiB,KAAA;ED3D2B;EC8DrD,IAAA;AAAA;;KAIG,QAAA,YAAoB,CAAA;AAAA,KACpB,SAAA,YAAqB,WAAA,CAAY,CAAA;AAAA,KACjC,iBAAA,YAA6B,SAAA,CAAU,SAAA,EAAW,CAAA;AAAA,KAClD,kBAAA,YAA8B,cAAA,CAAe,SAAA,EAAW,CAAA;;KAExD,YAAA,OAAmB,IAAA,EAAM,cAAA,KAAmB,CAAA,GAAI,WAAA,CAAY,CAAA;AAAA,KAE5D,MAAA,MAAY,QAAA,CAAS,CAAA,IAAK,SAAA,CAAU,CAAA,IAAK,iBAAA,CAAkB,CAAA,IAAK,kBAAA,CAAmB,CAAA,IAAK,YAAA,CAAa,CAAA;;UASzF,cAAA;ED7EM;EC+ErB,KAAA;AAAA;AAAA,UAGe,WAAA;EDlFM;;;;;;AAAiC;;;;;;;;ECiGtD,GAAA,IAAO,KAAA,UAAe,IAAA,EAAM,MAAA,CAAO,CAAA,IAAK,WAAA;EDzFpC;;;;;ECgGJ,OAAA,CAAQ,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,MAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;iBA0B7B,KAAA,WAAgB,QAAA,CAAA,CAAU,GAAA,EAAK,CAAA,GAAI,WAAA,CAAY,CAAA;AAAA,iBAC/C,KAAA,CAAA,GAAS,WAAA;;;UCxIR,WAAA;EJAL;;;;EIKV,IAAA,IACE,IAAA,EAAM,CAAA,GAAI,WAAA,CAAY,CAAA,WAAY,CAAA,GAAI,WAAA,CAAY,CAAA,YAAa,SAAA,CAAU,YAAA,EAAc,CAAA,cACtF,OAAA,CAAQ,CAAA;AAAA;;;;AJCb;;;iBIQgB,IAAA,CAAK,KAAA,WAAgB,WAAA;;;;UCSpB,UAAA;ELtBL;EKwBV,KAAA;AAAA;AAAA,UAGe,WAAA;;;;;;EAMf,GAAA,IAAO,KAAA,UAAe,IAAA,QAAY,CAAA,GAAI,WAAA,CAAY,CAAA,IAAK,SAAA,CAAU,YAAA,EAAc,CAAA,aAAc,WAAA;EJpD9E;;;;;EI2Df,GAAA,CAAI,OAAA,GAAU,UAAA,GAAa,OAAA,CAAQ,MAAA;AAAA;;;;;;iBAQrB,KAAA,CAAA,GAAS,WAAA"}