effective-progress 0.3.0 → 0.4.1

package/README.md

@@ -11,13 +11,13 @@
 
 <img alt="Showcase output" src="docs/images/showcase.gif" width="600" />
 
-`effective-progress` is an [Effect](https://effect.website/)-first terminal progress library with:
+`effective-progress` is an [Effect](https://effect.website/)-first terminal progress-bar library with:
 
-- multiple progress bars
-- nested child progress bars
-- spinner support for indeterminate work
-- clean log rendering alongside progress output, allowing you to simply use Effects `Console.log` or `Effect.logInfo`.
-- simple to use `.all` and `.forEach` APIs similar to the ones you already know and love from `effect`. Just swap `Effect` for `Progress` and get progress bars for free!
+- multiple nested tree-like progress bars
+- spinner support for “we have no idea how long this takes” work
+- clean log rendering alongside progress output, so you can keep using `Console.log` / `Effect.logInfo` without wrecking the UI
+- familiar `.all` and `.forEach` APIs — swap `Effect` for `Progress`, get progress bars basically for free
+- flicker-free rendering (in theory) by drawing everything in a single terminal frame
 
 ## Install
 
@@ -83,6 +83,9 @@ Effect.runPromise(program);
 - `examples/advancedExample.ts` - full API usage with custom config and manual task control
 - `examples/showcase.ts` - nested concurrent tasks, spinner workloads, and mixed Effect/Console logging
 - `examples/performance.ts` - stress-style run with high log volume and deeply nested progress updates
+- `examples/themeDepthPalette.ts` - depth-aware nested theming via `Theme.depthPalette`
+- `examples/twoLineWidthCap.ts` - two-line determinate layout with `maxTaskWidth` clamping
+- `examples/customColorStage.ts` - override `ColorStage` to emit plain (no ANSI) frame output
 
 ## Log retention
 
@@ -94,6 +97,12 @@ Effect.runPromise(program);
 
 Configure global renderer behavior once, and a global base progress bar style:
 
+Defaults:
+
+- determinate layout: `single-line`
+- max task width cap: unset (uses terminal width)
+- bar width: `40`
+
 ```ts
 import { Effect } from "effect";
 import * as Progress from "effective-progress";
@@ -168,13 +177,9 @@ const program = Progress.task(
 );
 ```
 
-## Progress bar colors
-
-Colors are configured through the `Colorizer` service. You can set a global colorizer, or provide per-task overrides using `Effect.provideService`.
-
-### Global colorizer
+## Themes and render stages
 
-Provide a custom `Colorizer` at the top level to change colors for all tasks:
+Coloring is configured through the `Theme` service.
 
 ```ts
 import chalk from "chalk";
@@ -183,51 +188,35 @@ import * as Progress from "effective-progress";
 
 const program = Progress.task(myEffect, { description: "Work" }).pipe(
   Effect.provideService(
-    Progress.Colorizer,
-    Progress.Colorizer.of({
-      fill: chalk.hex("#00b894"),
-      empty: chalk.white.dim,
-      brackets: chalk.rgb(180, 190, 210),
-      percent: chalk.whiteBright.bold,
-      spinner: chalk.ansi256(214),
-      done: chalk.greenBright,
-      failed: chalk.redBright.bold,
+    Progress.Theme,
+    Progress.Theme.of({
+      styles: {
+        plain: (text) => text,
+        barFill: chalk.hex("#00b894"),
+        barEmpty: chalk.white.dim,
+        barBracket: chalk.rgb(180, 190, 210),
+        spinner: chalk.ansi256(214),
+        statusDone: chalk.greenBright,
+        statusFailed: chalk.redBright.bold,
+        text: chalk.white,
+        units: chalk.whiteBright.bold,
+        eta: chalk.gray,
+        elapsed: chalk.gray,
+        treeConnector: chalk.gray,
+      },
+      depthPalette: (depth, role) => (role === "text" && depth > 0 ? chalk.cyanBright : undefined),
     }),
   ),
 );
 ```
 
-### Per-task colorizer
-
-Wrap any effect with `Effect.provideService(Colorizer, ...)` to override colors for that task (and its children). The colorizer is captured at task-creation time, so each task can have its own colors:
-
-```ts
-Progress.forEach(
-  ["fetch", "transform", "persist"],
-  (stage) => Effect.gen(function* () {
-    yield* Effect.sleep("500 millis");
-    return stage;
-  }),
-  { description: "Worker pipeline" },
-).pipe(
-  Effect.provideService(
-    Progress.Colorizer,
-    Progress.Colorizer.of({
-      fill: chalk.red,
-      empty: chalk.white.dim,
-      brackets: chalk.white.dim,
-      percent: chalk.white.bold,
-      spinner: chalk.magentaBright,
-      done: chalk.greenBright,
-      failed: chalk.redBright,
-    }),
-  ),
-);
-```
+Render internals are split into overrideable stages:
 
-Tasks inherit the colorizer from their parent task.
+- `BuildStage`: logical rows/cells/segments
+- `ShrinkStage`: width fitting/collapse
+- `ColorStage`: role -> styled terminal strings
 
-Each `ColorizerService` slot (`fill`, `empty`, `brackets`, `percent`, `spinner`, `done`, `failed`) is a `(text: string) => string` function. Use any chalk style — named colors, hex, rgb, ansi256, and modifiers like `.bold` or `.dim` all work.
+You can replace any stage with `Effect.provideService(...)` while keeping defaults for the rest.
 
 ## Dependencies & package size
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effective-progress",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Effect-first terminal progress bars with nested multibar support",
   "homepage": "https://github.com/stromseng/effective-progress#readme",
   "bugs": {

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./api";
-export * from "./colors";
+export * from "./renderer";
 export { Progress } from "./runtime";
 export * from "./terminal";
+export * from "./theme";
 export * from "./types";