@spec bar(non_neg_integer(), pos_integer(), keyword()) :: :ok

Renders a progress bar.

Options

• :width - Width of the progress bar (default: 40)
• :show_percent - Show percentage (default: true)
• :show_fraction - Show current/total (default: true)
• :label - Label to display before the bar (default: nil)
• :complete_char - Character for completed portion (default: "█")
• :incomplete_char - Character for incomplete portion (default: "░")

Examples

iex> Progress.bar(50, 100, label: "Processing")
Processing [████████████████████░░░░░░░░░░░░░░░░░░░░] 50% (50/100)

@spec format_elapsed(non_neg_integer()) :: String.t()

Formats elapsed time in a human-friendly way.

Examples

iex> Progress.format_elapsed(500)
"0s"

iex> Progress.format_elapsed(5_000)
"5s"

iex> Progress.format_elapsed(65_000)
"1m 5s"

@spec percent(
  number(),
  keyword()
) :: :ok

Displays a percentage-based progress update.

Examples

iex> Progress.percent(75, label: "Upload")
Upload: 75%

@spec spinner(keyword()) :: pid()

Starts a spinner for an indeterminate operation.

Returns a PID that can be used to stop the spinner. For most use cases, prefer start/1 or start/2.

Options

• :label - Label to display next to spinner (default: nil)
• :frames - Custom spinner frames (default: unicode spinner)
• :interval - Milliseconds between frames (default: 80)

Examples

iex> pid = Progress.spinner(label: "Loading")
iex> # Do work...
iex> Progress.stop_spinner(pid, "Done!")

@spec start(
  String.t(),
  keyword()
) :: pid() | nil

Starts a progress indicator with a label.

This is a convenience function that starts a spinner for indeterminate operations. Returns a reference that can be used with stop/1 or stop/2.

Options

• :type - Progress type (:spinner or :dots) (default: :spinner)
• :frames - Custom spinner frames (default: unicode spinner)
• :interval - Milliseconds between frames (default: 80)

Examples

iex> progress = Progress.start("Loading data")
iex> # Do work...
iex> Progress.stop(progress)

iex> progress = Progress.start("Processing", type: :dots)
iex> # Do work...
iex> Progress.stop(progress, "Complete!")

@spec status(
  String.t(),
  keyword()
) :: :ok

Displays a simple status message with icon.

Options

• :status - Status type (:success, :error, :warning, :info)

Examples

iex> Progress.status("All tests passed", status: :success)
✓ All tests passed

iex> Progress.status("Warning: deprecated function", status: :warning)
⚠ Warning: deprecated function

@spec steps([String.t()], non_neg_integer()) :: :ok

Renders a multi-step progress indicator.

Examples

iex> Progress.steps(["Parse", "Analyze", "Generate"], 1)
[✓] Parse
[→] Analyze
[ ] Generate

@spec stop(pid() | nil) :: :ok

Stops a progress indicator.

Accepts a PID from start/1, start/2, or spinner/1. If nil is passed, this function is a no-op (useful for conditional progress).

Examples

iex> progress = Progress.start("Loading")
iex> Progress.stop(progress)

iex> Progress.stop(nil)  # Safe - does nothing
:ok

@spec stop(pid() | nil, String.t() | nil) :: :ok

Stops a progress indicator with a completion message.

Examples

iex> progress = Progress.start("Loading")
iex> Progress.stop(progress, "Done!")

iex> Progress.stop(nil, "Skipped")  # Safe - just prints message
:ok

@spec stop_spinner(pid(), String.t() | nil) :: :ok

Stops a running spinner and displays completion message.

For most use cases, prefer stop/1 or stop/2.

Examples

iex> pid = Progress.spinner(label: "Loading")
iex> Progress.stop_spinner(pid, "Complete!")

@spec task_list([{String.t(), :done | :running | :pending | :error}]) :: :ok

Renders a task list with status indicators.

Examples

iex> Progress.task_list([
...>   {"Fetch data", :done},
...>   {"Process", :running},
...>   {"Save", :pending}
...> ])

@spec update(pid() | nil, String.t()) :: :ok

Updates a running progress indicator with a new label.

Examples

iex> progress = Progress.start("Step 1")
iex> Progress.update(progress, "Step 2")