### Minimal Prodash Setup

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Use this configuration for the smallest binary size and manual progress tracking without rendering.

```toml
[dependencies]
prodash = "31"

```

--------------------------------

### Line Renderer Setup

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/README.md

Shows how to set up the line-based renderer for piped output or lean builds. Ensure to call `shutdown_and_wait` to finalize rendering.

```rust
use prodash::render::line;

let root = Root::new();

let mut handle = line::render(
    std::io::stdout(),
    root.downgrade(),
    line::Options::default(),
);

// ... run tasks ...

handle.shutdown_and_wait();
```

--------------------------------

### Minimal Progress Tree Example

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/README.md

Demonstrates the basic usage of creating a progress tree, adding a task, updating its progress, and marking it as complete.

```rust
use prodash::tree::Root;
use prodash::Progress;

let root = Root::new();
let mut progress = root.add_child("Task");
progress.init(Some(100), None);

for i in 0..100 {
    progress.set(i);
}

progress.done("Complete");
```

--------------------------------

### Absolute Minimal Configuration

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Configure Prodash for an absolute minimal setup, providing only the progress tree without rendering or logging.

```toml
prodash = { version = "31", default-features = false, features = [
    "progress-tree",
] }
```

--------------------------------

### Example Usage of WeakRoot::upgrade

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/traits.md

Demonstrates how to use the `upgrade` method to check if a root is still alive after downgrading it. Handles both the case where the root is available and when it has been dropped.

```rust
let weak = root.downgrade();
match weak.upgrade() {
    Some(strong_root) => { /* root still alive */ },
    None => { /* root was dropped */ },
}
```

--------------------------------

### Example Message Struct Initialization

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/types.md

Illustrates the fields of a Message struct after a typical operation like calling progress.info. Requires SystemTime and MessageLevel imports.

```rust
use prodash::messages::MessageLevel;

// Message fields after calling progress.info("Task started")
Message {
    time: SystemTime::now(),
    level: MessageLevel::Info,
    origin: "My Task".to_string(),
    message: "Task started".to_string(),
}
```

--------------------------------

### TUI Renderer: Example Usage

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/renderers.md

Demonstrates how to initialize and run the TUI renderer with a progress tree. Tasks are run in parallel with the renderer, and the renderer is aborted when tasks complete.

```rust
use prodash::tree::Root;
use prodash::render::tui;
use futures::future::FutureExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = Root::new();
    
    let render_fut = tui::render(
        std::io::stdout(),
        root.downgrade(),
        tui::Options::default(),
    )?;
    
    let (render_fut, abort) = futures::future::abortable(render_fut);
    
    // Run tasks and renderer in parallel
    tokio::select! {
        _ = render_fut => println!("Renderer stopped"),
        _ = run_tasks(&root) => {
            abort.abort();
            println!("Tasks completed");
        }
    }
    
    Ok(())
}

async fn run_tasks(root: &Arc<Root>) {
    let mut task = root.add_child("Processing");
    task.init(Some(100), None);
    for i in 0..100 {
        task.set(i);
        tokio::time::sleep(tokio::time::Duration::from_millis(10)).await;
    }
}
```

--------------------------------

### TUI Renderer: Custom Options Example

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/renderers.md

Illustrates creating and using custom options for the TUI renderer, such as setting a specific title, enabling throughput display, and adjusting the refresh rate.

```rust
use prodash::render::tui;

let opts = tui::Options {
    title: "My Application".into(),
    frames_per_second: 20.0,
    throughput: true,
    recompute_column_width_every_nth_frame: Some(40),
    window_size: None,
    stop_if_progress_missing: true,
};

let render_fut = tui::render(
    std::io::stdout(),
    root.downgrade(),
    opts,
)?;
```

--------------------------------

### Building a Task Hierarchy with Prodash

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

Illustrates the creation of a multi-level task hierarchy using `prodash::tree::Root`. This example shows how to add top-level tasks, subtasks, initialize their progress, update their status, and finally generate a snapshot of the entire task tree.

```rust
use prodash::tree::Root;
use prodash::Progress;

let root = Root::new();

// Top-level tasks
let mut download = root.add_child_with_id("Download Files", *b"DOWN");
let mut process = root.add_child_with_id("Process Data", *b"PROC");

// Subtasks
let mut download_images = download.add_child("Images");
let mut download_metadata = download.add_child("Metadata");

download_images.init(Some(50), Some("images".into()));
download_metadata.init(Some(10), Some("files".into()));
process.init(Some(100), None);

for i in 0..50 {
    download_images.set(i);
}

for i in 0..100 {
    process.set(i);
}

download_images.done("Downloaded all images");
process.done("Processing complete");

// View the full tree
let mut snapshot = Vec::new();
root.sorted_snapshot(&mut snapshot);
println!("Total tasks: {}", snapshot.len());
```

--------------------------------

### Render Customized Line Output

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Configure and run a line-based renderer for the progress tree. This example uses `auto_configure` to automatically detect the output stream (e.g., Stdout) and sets up default options for line rendering.

```rust
use prodash::render::line::{self, Options, StreamKind};

let opts = line::Options::default()
    .auto_configure(StreamKind::Stdout);

let handle = line::render(
    std::io::stdout(),
    root.downgrade(),
    opts,
);
```

--------------------------------

### Usage Example for progress::State

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/types.md

Demonstrates how to use the State enum to manage task progress, including marking tasks as blocked, halted with an ETA, and resuming them to running.

```rust
use prodash::progress::State;
use std::time::SystemTime;

let mut progress = root.add_child("Task");
progress.init(Some(100), None);

// Mark task as blocked while waiting for I/O
progress.blocked("waiting for network", None);

// Or with an ETA
let eta = SystemTime::now() + std::time::Duration::from_secs(30);
progress.halted("waiting for user input", Some(eta));

// Resume normal execution
progress.running();
```

--------------------------------

### Add Child Task Example

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/traits.md

Demonstrates how to create a child progress item using the add_child method. The child task is added to the parent instance and can have its own nested children up to a hierarchy limit of 6 levels.

```rust
let mut parent = root.add_child("Parent Task");
let mut child = parent.add_child("Child Task");
```

--------------------------------

### TUI Renderer: Example with Input Stream

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/renderers.md

Initializes the TUI renderer to accept custom events via a stream. This allows for interactive control or data injection into the renderer.

```rust
use prodash::render::tui;
use futures::stream::StreamExt;

let mut events = futures::stream::channel(10).1;

let render_fut = tui::render_with_input(
    std::io::stdout(),
    root.downgrade(),
    Default::default(),
    events,
)?;
```

--------------------------------

### Enable Default Progress Tree Feature

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Use this configuration to enable the default progress tree implementation, which relies on `parking_lot::Mutex` for synchronization. This is the standard setup for most use cases.

```toml
[dependencies]
prodash = "31"  # has progress-tree by default
```

--------------------------------

### Get Current Progress Value

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/traits.md

Retrieves the current progress value.

```rust
fn step(&self) -> Step
```

--------------------------------

### Get Item Name

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

Retrieves the display name of the Item. Returns `None` if the name has not been set.

```rust
pub fn name(&self) -> Option<String>
```

--------------------------------

### Get Progress ID

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/traits.md

Retrieves the stable 4-byte identifier for this progress instance. Returns `UNKNOWN` if unset.

```rust
fn id(&self) -> Id
```

--------------------------------

### Get Current Progress Step

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

Retrieves the current progress value of the Item. Returns `None` if the progress has not been initialized.

```rust
pub fn step(&self) -> Option<Step>
```

--------------------------------

### Get Item ID

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

Retrieves the unique 4-byte identifier for the Item. Returns `progress::UNKNOWN` if the ID is not available.

```rust
pub fn id(&self) -> Id
```

--------------------------------

### Snapshots

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/INDEX.md

Functions for retrieving a sorted snapshot of tasks within the progress tree and for getting the total number of tasks.

```APIDOC
## `Root::sorted_snapshot()`

### Description
Retrieves a sorted snapshot of all tasks in the progress tree.

### Signature
`pub fn sorted_snapshot(&self, out: &mut Vec<(Key, Task)>)`

### Location
[tree.md#sorted_snapshot](./tree.md#sorted_snapshot)
```

```APIDOC
## `Root::num_tasks()`

### Description
Returns the total number of tasks currently in the progress tree.

### Signature
`pub fn num_tasks(&self) -> usize`

### Location
[tree.md#num_tasks](./tree.md#num_tasks)
```

--------------------------------

### Server Configuration (Minimal Output)

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Configure Prodash for servers with minimal output, focusing on progress tree logging.

```toml
prodash = { version = "31", features = [
    "progress-tree-log",
]
}
log = "0.4"
slog = "2"  # or your preferred logging framework
```

--------------------------------

### Get Display Unit

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

Retrieves the display unit for the Item's progress. Returns `None` if no unit was specified during initialization.

```rust
pub fn unit(&self) -> Option<Unit>
```

--------------------------------

### Get Maximum Level for progress::Key

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/types.md

Returns the maximum nesting depth supported by the Key type, which is always 6.

```rust
pub const fn max_level() -> Level
```

--------------------------------

### Basic TUI Rendering (Async)

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/renderers.md

Demonstrates how to initialize and run the TUI renderer asynchronously. This is suitable for interactive terminal environments where rich progress visualization is desired. It spawns the renderer in a background task and then proceeds to update progress. Ensure the `render-tui` feature is enabled.

```rust
use prodash::tree::Root;
use prodash::render::tui;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = Root::new();
    
    let render_fut = tui::render(
        std::io::stdout(),
        root.downgrade(),
        tui::Options::default(),
    )?;
    
    // Run renderer in background
    let render_handle = tokio::spawn(render_fut);
    
    // Run tasks
    let mut task = root.add_child("Task");
    task.init(Some(100), None);
    for i in 0..100 {
        task.set(i);
        tokio::time::sleep(std::time::Duration::from_millis(10)).await;
    }
    
    // Cancel renderer
    render_handle.abort();
    Ok(())
}
```

--------------------------------

### Get Level of progress::Key

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/types.md

Retrieves the depth of a key in the hierarchy. Returns 0 for the root and 1-6 for nested items.

```rust
pub fn level(&self) -> Level
```

--------------------------------

### Options::create()

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

Creates a Root instance using the specified Options. The returned Root is not wrapped in an Arc.

```APIDOC
## Options::create()

### Description
Create a `Root` (not wrapped in `Arc`).

### Returns
`Root` — Unwrapped root instance

### Example
```rust
use prodash::tree::root::Options;

let opts = Options {
    initial_capacity: 500,
    message_buffer_capacity: 100,
};
let root = opts.create();
let root_arc = std::sync::Arc::new(root);
```
```

--------------------------------

### Get Messages Capacity

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/traits.md

Retrieves the maximum number of messages the internal ring buffer can hold. This indicates the buffer's size.

```rust
fn messages_capacity(&self) -> usize
```

--------------------------------

### Get Progress Upper Bound

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

Retrieves the maximum progress value set for the Item during initialization. Returns `None` if no upper bound was specified.

```rust
pub fn max(&self) -> Option<Step>
```

--------------------------------

### Enable Alternative Progress Logging Implementation

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Use the `progress-log` feature if you prefer a simpler progress implementation that exclusively uses the `log` crate for output, foregoing the tree structure and message buffering. This is suitable for environments where only log output is desired.

```toml
[dependencies]
prodash = { version = "31", features = ["progress-log"] }
```

--------------------------------

### num_tasks

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

Gets the approximate current count of tasks within the progress tree. Note that concurrent operations might make this count an estimate.

```APIDOC
## num_tasks

### Description
Get the approximate current task count.

### Method
Rust function signature

### Signature
`pub fn num_tasks(&self) -> usize`

### Returns
- **usize** - Number of `Item` instances

### Caveat
Concurrent operations may make this a guess
```

--------------------------------

### Get the message buffer capacity

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

The `messages_capacity` method returns the maximum number of messages the internal buffer can hold before older messages are overwritten.

```rust
pub fn messages_capacity(&self) -> usize
```

--------------------------------

### From<Options> for Arc<Root>

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

Converts Options into an Arc<Root>, allowing for convenient creation of a thread-safe root with custom configurations.

```APIDOC
## From<Options> for Arc<Root>

### Description
Converts `Options` into an `Arc<Root>`.

### Example
```rust
let root: Arc<Root> = Options {
    initial_capacity: 200,
    ..Default::default()
}.into();
```
```

--------------------------------

### Basic Line Rendering (Sync)

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/renderers.md

Shows how to use the synchronous line renderer for progress display. This is ideal for non-interactive environments or when a simpler progress output is needed. It runs the rendering in the main thread and requires explicit shutdown. Ensure the `render-line` feature is enabled.

```rust
use prodash::tree::Root;
use prodash::render::line;

fn main() {
    let root = Root::new();
    
    let mut handle = line::render(
        std::io::stdout(),
        root.downgrade(),
        line::Options::default(),
    );
    
    // Run tasks
    let mut task = root.add_child("Task");
    task.init(Some(100), None);
    for i in 0..100 {
        task.set(i);
        std::thread::sleep(std::time::Duration::from_millis(10));
    }
    
    // Cleanup
    handle.shutdown_and_wait();
}
```

--------------------------------

### Get Unit as Trait Object

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/units.md

Retrieve the unit as a trait object for dynamic dispatch. This allows for flexible handling of different unit types.

```rust
pub fn as_display_value(&self) -> &dyn DisplayValue
```

--------------------------------

### render() Function

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/renderers.md

Spawns a thread to display line-based progress. It takes an output stream, a progress tree, and configuration options.

```APIDOC
## render() Function

### Description
Spawns a thread to display line-based progress. It takes an output stream, a progress tree, and configuration options.

### Signature
```rust
pub fn render(
    out: impl io::Write + Send + 'static,
    progress: impl WeakRoot + Send + 'static,
    options: Options,
) -> JoinHandle
```

### Parameters
- **out** (`impl Write + Send`): Output stream (e.g., stdout)
- **progress** (`impl WeakRoot + Send`): Progress tree to render
- **options** (`Options`): Configuration

### Returns
- `JoinHandle` — Handle to control the renderer thread

### Behavior
- Spawns a separate thread for rendering
- Draws progress lines and log messages to the terminal
- Stops automatically when the progress tree is dropped

### Example
```rust
use prodash::tree::Root;
use prodash::render::line;

let root = Root::new();

let mut handle = line::render(
    std::io::stdout(),
    root.downgrade(),
    line::Options::default(),
);

// ... run tasks ...

handle.shutdown_and_wait();  // Cleanup
```
```

--------------------------------

### Initialize Default Progress Tree

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Create a new progress tree with default settings. This initializes a tree capable of holding 100 items and 20 messages.

```rust
use prodash::tree::Root;

let root = Root::new();  // 100 items, 20 messages
```

--------------------------------

### Update Progress and Get Throughput

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/types.md

Updates the tracking for a specific progress item and returns the computed throughput. This is a core method for real-time throughput monitoring.

```rust
pub fn update_and_get(
    &mut self,
    key: &progress::Key,
    progress: Option<&progress::Value>,
) -> Option<unit::display::Throughput>
```

--------------------------------

### Initialize Custom Progress Tree

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Create a progress tree with custom initial capacity and message buffer capacity. The `into()` method converts the Options into an `Arc<Root>`.

```rust
use prodash::tree::root::Options;

let root: Arc<Root> = Options {
    initial_capacity: 500,
    message_buffer_capacity: 100,
}.into();
```

--------------------------------

### Create Unit with Static Label and Display Mode

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/types.md

Use `label_and_mode` to create a Unit with both a static label and a specified display mode for formatting.

```rust
pub fn label_and_mode(label: &'static str, mode: display::Mode) -> Unit
```

--------------------------------

### Get Number of Tasks

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/traits.md

Returns the current count of tasks within the progress tree. Note that this count is approximate due to potential concurrent modifications.

```rust
fn num_tasks(&self) -> usize
```

--------------------------------

### Lean CLI Tool Configuration

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Set up Prodash for a lean CLI tool using a minimal line renderer with auto-configuration and signal handling. This results in a smaller binary than the TUI version.

```toml
[dependencies]
prodash = { version = "31", features = [
    "render-line",
    "render-line-crossterm",
    "render-line-autoconfigure",
    "signal-hook",
] }

```

--------------------------------

### Configure Unit Display Mode

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/units.md

Use this to set up how units are displayed, enabling fraction and throughput information. Requires importing `prodash::unit` and `prodash::unit::display::Mode`.

```rust
use prodash::unit::{self, display::Mode};

let unit = unit::label_and_mode("items", Mode {
    fraction: true,
    throughput: true,
});

progress.init(Some(1000), Some(unit));
```

--------------------------------

### Basic Sequential Task Progress

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/patterns.md

Demonstrates how to create a single progress bar for a sequential task. Initialize the progress bar with a total count and then update it as work is done.

```rust
use prodash::tree::Root;
use prodash::Progress;

let root = Root::new();
let mut progress = root.add_child("Processing");

progress.init(Some(100), Some("items".into()));

for i in 0..100 {
    // Do work
    progress.set(i);
}

progress.done("Completed successfully");
```

--------------------------------

### Get Sorted Task Snapshot

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/traits.md

Copies the entire progress state into a vector, sorted by hierarchical key. Useful for rendering the progress tree or taking snapshots for inspection.

```rust
fn sorted_snapshot(&self, out: &mut Vec<(Key, Task)>)
```

--------------------------------

### Initialize Progress Instance

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/traits.md

Initializes the progress instance, setting the upper bound and display unit. Calling `init()` multiple times changes these parameters and resets the current step to 0. If not called, progress acts as an organizational unit without a bar.

```rust
progress.init(Some(100), Some("items".into()));
progress.init(None, None);  // Reset to unbounded
```

--------------------------------

### Get the approximate current task count

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

Use `num_tasks` to retrieve an estimate of the current number of active tasks. Note that due to concurrent operations, this count may not be exact.

```rust
pub fn num_tasks(&self) -> usize
```

--------------------------------

### Item Initialization

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

Initializes progress tracking for an Item. You can set an upper bound and a display unit.

```APIDOC
## init

### Description
Initialize progress tracking for an Item.

### Method
`init`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **max** (`Option<usize>`) - Optional - Upper bound, or `None` for unbounded
- **unit** (`Option<Unit>`) - Optional - Display unit, or `None` for unitless
```

--------------------------------

### Options Struct

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/renderers.md

Configuration for the line renderer, allowing customization of output, appearance, and behavior.

```APIDOC
## Options Struct

### Description
Configuration for the line renderer, allowing customization of output, appearance, and behavior.

### Signature
```rust
#[derive(Clone)]
pub struct Options {
    pub output_is_terminal: bool,
    pub colored: bool,
    pub timestamp: bool,
    pub terminal_dimensions: (u16, u16),
    pub hide_cursor: bool,
    pub throughput: bool,
    pub level_filter: Option<RangeInclusive<progress::key::Level>>,
    pub initial_delay: Option<Duration>,
    pub frames_per_second: f32,
    pub keep_running_if_progress_is_empty: bool,
}
```

### Fields
- **output_is_terminal** (`bool`): Assume output is connected to a terminal (Default: `true`)
- **colored** (`bool`): Use ANSI color codes (respects NO_COLOR env var) (Default: `true`)
- **timestamp** (`bool`): Show timestamp before each message (Default: `false`)
- **terminal_dimensions** (`(u16, u16)`): Terminal size for layout (Default: `(80, 20)`)
- **hide_cursor** (`bool`): Hide the cursor (restore requires proper shutdown) (Default: `false`)
- **throughput** (`bool`): Compute and display throughput (Default: `false`)
- **level_filter** (`Option<Range>`): Only show items at specified hierarchy levels (Default: `None`)
- **initial_delay** (`Option<Duration>`): Delay before showing progress (messages always shown) (Default: `None`)
- **frames_per_second** (`f32`): Refresh rate (Default: `6.0`)
- **keep_running_if_progress_is_empty** (`bool`): Keep waiting if no items present (Default: `true`)

### Example
```rust
use prodash::render::line;
use std::time::Duration;

let opts = line::Options {
    output_is_terminal: true,
    colored: true,
    timestamp: true,
    terminal_dimensions: (120, 30),
    hide_cursor: false,
    throughput: true,
    level_filter: Some(1..=2),  // Only show first 2 levels
    initial_delay: Some(Duration::from_millis(500)),
    frames_per_second: 4.0,
    keep_running_if_progress_is_empty: true,
};

line::render(std::io::stdout(), root.downgrade(), opts);
```
```

--------------------------------

### Create Unit with Dynamic Label and Display Mode

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/types.md

Use `dynamic_and_mode` to create a Unit with a dynamic label formatter and a specified display mode.

```rust
pub fn dynamic_and_mode(
    label: impl DisplayValue + Send + Sync + 'static,
    mode: display::Mode,
) -> Unit
```

--------------------------------

### Unix-Only Build Configuration

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Configure Prodash for a Unix-only build using `progress-tree` and the `termion` backend. This offers a minimal dependency tree but lacks Windows support.

```toml
[dependencies]
prodash = { version = "31", default-features = false, features = [
    "progress-tree",
    "render-line",
    "render-line-termion",
] }

```

--------------------------------

### Add Child Task with ID Example

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/traits.md

Illustrates creating child progress items with stable 4-byte identifiers using the add_child_with_id method. This is useful for referencing specific tasks consistently.

```rust
let mut child = parent.add_child_with_id("Task 1", *b"TSK1");
let mut child2 = parent.add_child_with_id("Task 2", *b"TSK2");
```

--------------------------------

### Implement Custom Octal Value Formatting

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/units.md

Example implementation of the `DisplayValue` trait to format progress values as octal numbers. This custom formatter handles both bounded and unbounded progress values.

```rust
struct OctalFormatter;

impl DisplayValue for OctalFormatter {
    fn display_value(&self, value: usize, upper_bound: Option<usize>) -> Option<String> {
        match upper_bound {
            Some(max) => Some(format!("{:o}/{:o}", value, max)),
            None => Some(format!("{:o}", value)),
        }
    }
    
    fn dyn_hash(&self, state: &mut dyn std::hash::Hasher) {
        use std::hash::Hash;
        "OctalFormatter".hash(state);
    }
    
    fn display_current_value(
        &self,
        out: &mut String,
        current: usize,
        _upper_bound: Option<usize>,
    ) -> std::io::Result<()> {
        use std::fmt::Write;
        write!(out, "{:o}", current)?;
        Ok(())
    }
}
```

--------------------------------

### Hierarchical Task Initialization

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/README.md

Illustrates creating nested tasks within a progress tree, initializing each with specific maximum values and units.

```rust
use prodash::NestedProgress;

let root = Root::new();
let mut parent = root.add_child("Pipeline");
let mut extract = parent.add_child("Extract");
let mut transform = parent.add_child("Transform");

extract.init(Some(50), Some("files".into()));
transform.init(Some(50), Some("records".into()));
```

--------------------------------

### Unit::display()

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/units.md

Creates a display wrapper for a unit, allowing formatted output of progress values with optional upper bounds and throughput.

```APIDOC
## Unit::display()

### Description
Create a display wrapper for a unit.

### Method Signature
```rust
pub fn display(
    &self,
    current_value: Step,
    upper_bound: Option<Step>,
    throughput: impl Into<Option<display::Throughput>>,
) -> display::UnitDisplay<'_>
```

### Parameters
#### Path Parameters
- **current_value** (Step) - Required - Current progress
- **upper_bound** (Option<Step>) - Optional - Maximum value
- **throughput** (impl Into<Option<display::Throughput>>) - Optional - Computed throughput

### Returns
`UnitDisplay` — Implements `std::fmt::Display`

### Example
```rust
let unit = unit::label("files");
let display = unit.display(150, Some(1000), None);
println!("{}", display);  // "150/1000 files"
```
```

--------------------------------

### Access Underlying Atomic Counter

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/traits.md

Provides direct atomic access to the underlying counter, useful for multi-threaded updates without additional synchronization. Example shows spawning a thread to increment the counter.

```rust
fn counter(&self) -> StepShared
```

```rust
let counter = progress.counter();
let counter_clone = counter.clone();
std::thread::spawn(move || {
    for i in 0..100 {
        counter_clone.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
    }
});
```

--------------------------------

### Set Logging Level with RUST_LOG

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Configure the logging level for Prodash using the RUST_LOG environment variable, compatible with env_logger. For example, setting it to 'debug' for the 'prodash' crate enables debug messages.

```bash
RUST_LOG=prodash=debug ./my-app
```

--------------------------------

### unit::Unit::dynamic_and_mode

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/types.md

Creates a `Unit` with dynamic formatting and a specified display mode. This offers the most flexibility, combining custom display logic with presentation control.

```APIDOC
## unit::Unit::dynamic_and_mode

### Description
Create a unit with dynamic formatting and display mode.

### Signature
```rust
pub fn dynamic_and_mode(
    label: impl DisplayValue + Send + Sync + 'static,
    mode: display::Mode,
) -> Unit
```

### Parameters
#### Path Parameters
- **label** (impl `DisplayValue` + `Send` + `Sync` + `'static`) - Required - Custom formatting implementation.
- **mode** (`display::Mode`) - Required - How to display the unit.
```

--------------------------------

### Render Default TUI

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Initialize and run the default Text-based User Interface (TUI) renderer for the progress tree. This requires a `Root` instance and configures the TUI with default options, targeting standard output and updating at 10 FPS.

```rust
use prodash::render::tui;

let render_fut = tui::render(
    std::io::stdout(),
    root.downgrade(),
    tui::Options::default(),  // "Progress Dashboard", 10 FPS
)?;
```

--------------------------------

### Interactive Terminal App Configuration

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Configure Prodash with TUI rendering, crossterm backend, and human-readable units for a rich, cross-platform progress dashboard with keyboard control.

```toml
[dependencies]
prodash = { version = "31", features = [
    "render-tui",
    "render-tui-crossterm",
    "unit-bytes",
    "unit-human",
] }
tokio = { version = "1", features = ["full"] }

```

--------------------------------

### Log Progress Throughput

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/traits.md

Sends a throughput message based on the elapsed time since a given start point. This method computes steps per second and logs the information using the `info()` method.

```rust
let start = std::time::Instant::now();
progress.init(Some(1000), None);
for i in 0..1000 {
    progress.set(i);
}
progress.show_throughput(start);  // Logs "done 1000 items in 2.34s (427 items/s)"
```

--------------------------------

### Initialize Progress with Units

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/units.md

Set up progress trackers with different unit types like countable items, bytes (requires 'unit-bytes' feature), and human-readable large numbers (requires 'unit-human' feature).

```rust
use prodash::tree::Root;
use prodash::unit;

let root = Root::new();

// Countable items
let mut items = root.add_child("Items");
items.init(Some(100), Some(unit::label("items")));

// Bytes
#[cfg(feature = "unit-bytes")]
{
    use prodash::unit::Bytes;
    let mut download = root.add_child("Download");
    download.init(Some(1024 * 1024), Some(Bytes.into()));
}

// Large counts
#[cfg(feature = "unit-human")]
{
    use prodash::unit::Human;
    let mut huge = root.add_child("Huge");
    huge.init(Some(1_000_000), Some(Human.into()));
}
```

--------------------------------

### Initialize Item Progress

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

Initializes progress tracking for an Item. Use `None` for unbounded progress or when no specific unit is needed.

```rust
pub fn init(&self, max: Option<usize>, unit: Option<Unit>)
```

--------------------------------

### Enable TUI Renderer with Crossterm Backend

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Configure Prodash with the `render-tui` and `render-tui-crossterm` features to enable a full-featured terminal user interface. This setup is ideal for interactive terminal applications requiring rich progress visualization and offers cross-platform compatibility (Linux, macOS, Windows).

```toml
[dependencies]
prodash = { version = "31", features = ["render-tui", "render-tui-crossterm"] }
```

--------------------------------

### Configuration

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/README.md

Comprehensive documentation on Cargo features, feature interactions, common feature sets, runtime environment variables, and initialization patterns for prodash.

```APIDOC
## Configuration

### Cargo Features
- All available Cargo features are documented.

### Feature Interactions
- Documentation on how different features interact and potential conflicts.

### Common Feature Sets
- Examples of common feature sets for different use cases (e.g., CLI, web, servers).

### Runtime Environment Variables
- Environment variables that can be used to configure prodash at runtime.

### Initialization Patterns
- Recommended patterns for initializing and configuring prodash in applications.

### Usage
Refer to `configuration.md` for detailed configuration options and guidance.
```

--------------------------------

### Render Progress with Prodash Line Renderer

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/overview.md

Initialize and run the minimal line-based progress renderer for the progress tree, outputting to standard output. Requires the `render-line` feature.

```rust
// Line renderer
let _handle = prodash::render::line::render(
    std::io::stdout(),
    root.downgrade(),
    prodash::render::line::Options::default(),
);
```

--------------------------------

### Enable Minimal Line Renderer with Termion Backend

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Configure Prodash with `render-line` and `render-line-termion` features for a lean, Unix-only line-based progress renderer. This option minimizes dependencies while providing essential line-based progress output.

```toml
[dependencies]
prodash = { version = "31", features = ["render-line", "render-line-termion"] }
```

--------------------------------

### unit::dynamic_and_mode()

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/units.md

Creates a dynamic unit that also allows for custom display formatting modes.

```APIDOC
## unit::dynamic_and_mode()

### Description
Create a dynamic unit with custom display mode.

### Signature
```rust
pub fn dynamic_and_mode(
    label: impl DisplayValue + Send + Sync + 'static,
    mode: display::Mode,
) -> Unit
```

### Parameters
#### Path Parameters
- **label** (impl `DisplayValue` + Send + Sync + 'static) - Required - Custom formatter
- **mode** (`display::Mode`) - Required - Custom display mode

### Returns
- **Unit** - The created unit.
```

--------------------------------

### unit::label_and_mode()

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/units.md

Creates a unit with a static label and custom display formatting mode.

```APIDOC
## unit::label_and_mode()

### Description
Create a unit with label and custom display formatting.

### Signature
```rust
pub fn label_and_mode(label: &'static str, mode: display::Mode) -> Unit
```

### Parameters
#### Path Parameters
- **label** (`&'static str`) - Required - Display label
- **mode** (`display::Mode`) - Required - Formatting mode

### Returns
- **Unit** - The created unit.

### Example
```rust
use prodash::unit::{self, display::Mode};

let unit = unit::label_and_mode("tasks", Mode {
    fraction: true,
    throughput: true,
});
progress.init(Some(100), Some(unit));
```
```

--------------------------------

### Enable Progress Tree Logging Integration

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Activate the `progress-tree-log` feature to integrate progress messages with the `log` crate. This is useful when you want progress updates to be handled by your existing logging infrastructure. Ensure `log` and a logger implementation like `env_logger` are also included in your dependencies.

```toml
[dependencies]
prodash = { version = "31", features = ["progress-tree-log"] }
log = "0.4"
env_logger = "0.11"
```

--------------------------------

### Create Prodash Progress Tree

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/overview.md

Instantiate a new progress tree with default settings or custom options for initial capacity and message buffer size.

```rust
use prodash::tree::Root;

// Create with defaults
let root = Root::new();

// Create with custom configuration
let root = prodash::tree::root::Options {
    initial_capacity: 100,
    message_buffer_capacity: 20,
}.create();
```

--------------------------------

### Minimal Prodash Dependency

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/README.md

Use this configuration for the smallest possible dependency size when only progress tracking is needed. It enables manual snapshots but excludes rendering capabilities.

```toml
[dependencies]
prodash = { version = "31", default-features = false, features = ["progress-tree"] }
```

--------------------------------

### Configure and create a progress tree root

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/tree.md

Customizes the configuration for a new progress tree, such as initial capacity and message buffer size. The created Root can then be wrapped in an Arc for thread safety.

```rust
pub struct Options {
    pub initial_capacity: usize,
    pub message_buffer_capacity: usize,
}
```

```rust
impl Default for Options {
    fn default() -> Self {
        Options {
            initial_capacity: 100,
            message_buffer_capacity: 20,
        }
    }
}
```

```rust
pub fn create(self) -> Root
```

```rust
use prodash::tree::root::Options;

let opts = Options {
    initial_capacity: 500,
    message_buffer_capacity: 100,
};
let root = opts.create();
let root_arc = std::sync::Arc::new(root);
```

```rust
impl From<Options> for Arc<Root> {
    fn from(opts: Options) -> Self { ... }
}
```

```rust
let root: Arc<Root> = Options {
    initial_capacity: 200,
    ..Default::default()
}.into();
```

--------------------------------

### CLI Tool Configuration

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Configure Prodash for CLI tools, enabling line rendering and signal handling.

```toml
prodash = { version = "31", features = [
    "render-line",
    "render-line-crossterm",
    "render-line-autoconfigure",
    "signal-hook",
    "local-time",
] }
```

--------------------------------

### auto_configure() Method

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/renderers.md

Automatically configures `Options` based on terminal capabilities.

```APIDOC
## auto_configure() Method

### Description
Automatically configures `Options` based on terminal capabilities.

### Signature
```rust
#[cfg(feature = "render-line-autoconfigure")]
pub fn auto_configure(mut self, output: StreamKind) -> Self
```

### Parameters
- **output** (`StreamKind`): Stdout or Stderr to probe

### Sets
- `output_is_terminal` — Auto-detect via `is_terminal` crate
- `colored` — Based on `NO_COLOR` and `FORCE_COLOR` env vars
- `terminal_dimensions` — Query terminal size
- `hide_cursor` — true if `signal-hook` feature is enabled

### Example
```rust
let opts = line::Options::default()
    .auto_configure(line::StreamKind::Stdout);
```
```

--------------------------------

### display::Mode Configuration

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/units.md

Configuration for how to display a unit value, allowing control over showing fractions and throughput.

```APIDOC
## display::Mode

**Type**: `pub struct Mode`

Configuration for how to display a unit value.

#### Signature

```rust
pub struct Mode {
    pub fraction: bool,
    pub throughput: bool,
}
```

#### Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| fraction | `bool` | false | Show progress as a fraction/percentage |
| throughput | `bool` | false | Show throughput (items/sec) if available |

**Example**:
```rust
use prodash::unit::{self, display::Mode};

let unit = unit::label_and_mode("items", Mode {
    fraction: true,      // Show "150/1000"
    throughput: true,    // Show "(50 items/s)"
});

progress.init(Some(1000), Some(unit));
```
```

--------------------------------

### Usage of unit-bytes in Prodash

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Demonstrates how to use the `Bytes` unit for progress tracking, initializing with a total size in megabytes and updating progress incrementally.

```rust
use prodash::unit::Bytes;

let mut progress = root.add_child("Download");
progress.init(Some(1024 * 1024 * 100), Some(Bytes.into())); // 100 MB
for i in 0..(100 * 1024 * 1024) {
    progress.set(i);
}
```

--------------------------------

### Implement From<&'static str> for Unit

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/types.md

Allows passing string literals directly to `init()`. This conversion is useful for simplifying the initialization of progress indicators with string labels.

```rust
impl From<&'static str> for Unit {
    fn from(v: &'static str) -> Self {
        label(v)
    }
}
```

```rust
progress.init(Some(50), Some("tasks".into()));
```

--------------------------------

### Web/Async Application Configuration

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Configure Prodash for web and asynchronous applications, enabling TUI rendering and byte unit formatting.

```toml
prodash = { version = "31", features = [
    "render-tui",
    "render-tui-crossterm",
    "unit-bytes",
]
tokio = { version = "1", features = ["full"] }
}
```

--------------------------------

### Create Static Label Unit with Custom Mode

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/units.md

Use `unit::label_and_mode` to create a unit with a static label and a custom display mode, which can include fraction and throughput formatting.

```rust
use prodash::unit::{self, display::Mode};

let unit = unit::label_and_mode("tasks", Mode {
    fraction: true,
    throughput: true,
});
progress.init(Some(100), Some(unit));
```

--------------------------------

### Heavy Concurrent Tasks (Ultra-Scale) Configuration

Source: https://github.com/gitoxidelabs/prodash/blob/main/_autodocs/configuration.md

Use this configuration for handling thousands of concurrent tasks with high churn, leveraging `dashmap` for improved contention characteristics.

```toml
[dependencies]
prodash = { version = "31", default-features = false, features = [
    "progress-tree-hp-hashmap",
    "render-tui",
    "render-tui-crossterm",
] }

```