clack 0.6.2 → 0.7.0

data/lib/clack.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "clack/version"
+require_relative "clack/errors"
 require_relative "clack/environment"
 require_relative "clack/symbols"
 require_relative "clack/colors"
 require_relative "clack/utils"
 require_relative "clack/core/cursor"
 require_relative "clack/core/settings"
+require_relative "clack/core/chrome"
 require_relative "clack/core/key_reader"
 require_relative "clack/core/prompt"
 require_relative "clack/core/options_helper"
@@ -101,7 +103,9 @@ module Clack
     # Useful for guard clauses in CLI scripts.
     #
     # @param value [Object] the result from a prompt
-    # @param message [String] message to display if cancelled
+    # @param message [String, nil] message to display if cancelled (default: the global
+    #   messages[:cancel], "Cancelled"; see {#update_settings})
+    # @param with_guide [Boolean, nil] show the guide symbol (default: Clack.settings[:with_guide])
     # @param output [IO] output stream
     # @return [Boolean] true if cancelled
     #
@@ -111,41 +115,53 @@ module Clack
     #
     # @example With custom message
     #   return if Clack.handle_cancel(name, "Aborted by user")
-    def handle_cancel(value, message = "Cancelled", output: $stdout)
+    def handle_cancel(value, message = nil, with_guide: nil, output: $stdout)
       return false unless cancel?(value)
 
-      cancel(message, output: output)
+      cancel(message || Core::Settings.message(:cancel), with_guide:, output:)
       true
     end
 
     # Display an intro banner at the start of a CLI session.
     #
     # @param title [String, nil] optional title text
+    # @param with_guide [Boolean, nil] show the guide symbol (default: Clack.settings[:with_guide])
     # @param output [IO] output stream (default: $stdout)
     # @return [void]
-    def intro(title = nil, output: $stdout)
-      output.puts "#{Colors.gray(Symbols::S_BAR_START)}  #{title}"
+    def intro(title = nil, with_guide: nil, output: $stdout)
+      prefix = Core::Settings.with_guide?(with_guide) ? "#{Colors.gray(Symbols::S_BAR_START)}  " : ""
+      output.puts "#{prefix}#{title}"
     end
 
     # Display an outro banner at the end of a CLI session.
     #
     # @param message [String, nil] optional closing message
+    # @param with_guide [Boolean, nil] show the guide symbol (default: Clack.settings[:with_guide])
     # @param output [IO] output stream (default: $stdout)
     # @return [void]
-    def outro(message = nil, output: $stdout)
-      output.puts Colors.gray(Symbols::S_BAR)
-      output.puts "#{Colors.gray(Symbols::S_BAR_END)}  #{message}"
+    def outro(message = nil, with_guide: nil, output: $stdout)
+      if Core::Settings.with_guide?(with_guide)
+        output.puts Colors.gray(Symbols::S_BAR)
+        output.puts "#{Colors.gray(Symbols::S_BAR_END)}  #{message}"
+      else
+        output.puts message.to_s
+      end
       output.puts
     end
 
     # Display a cancellation message (typically after user presses Escape).
     #
     # @param message [String, nil] optional cancellation message
+    # @param with_guide [Boolean, nil] show the guide symbol (default: Clack.settings[:with_guide])
     # @param output [IO] output stream (default: $stdout)
     # @return [void]
-    def cancel(message = nil, output: $stdout)
-      output.puts Colors.gray(Symbols::S_BAR)
-      output.puts "#{Colors.gray(Symbols::S_BAR_END)}  #{Colors.red(message)}"
+    def cancel(message = nil, with_guide: nil, output: $stdout)
+      if Core::Settings.with_guide?(with_guide)
+        output.puts Colors.gray(Symbols::S_BAR)
+        output.puts "#{Colors.gray(Symbols::S_BAR_END)}  #{Colors.red(message)}"
+      else
+        output.puts Colors.red(message)
+      end
       output.puts
     end
 
@@ -156,9 +172,12 @@ module Clack
     # @option opts [String, nil] :default_value value used if submitted empty
     # @option opts [String, nil] :initial_value pre-filled editable text
     # @option opts [Array<String>, Proc, nil] :completions tab completion candidates (array or proc)
-    # @option opts [Proc, nil] :validate validation function returning error string, Warning, or nil
+    # @option opts [Proc, Regexp, Symbol, Array, Hash, nil, false] :validate validator (see {Validators.resolve});
+    #   a proc returns an error string, Warning, or nil; nil or false disables validation
     # @option opts [Symbol, Proc, nil] :transform transform function to normalize the value
     # @option opts [String, nil] :help help text shown below the message
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
+    # @option opts [String, Array<String>, nil] :instructions custom keyboard hint footer text, rendered verbatim on one line (newlines are not re-prefixed)
     # @return [String, CANCEL] user input or CANCEL if cancelled
     def text(message:, **opts)
       Prompts::Text.new(message:, **opts).run
@@ -171,8 +190,11 @@ module Clack
     #
     # @param message [String] the prompt message
     # @option opts [String, nil] :initial_value pre-filled editable text (can contain newlines)
-    # @option opts [Proc, nil] :validate validation function returning error string, Warning, or nil
+    # @option opts [Proc, Regexp, Symbol, Array, Hash, nil, false] :validate validator (see {Validators.resolve});
+    #   a proc returns an error string, Warning, or nil; nil or false disables validation
     # @option opts [String, nil] :help help text shown below the message
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
+    # @option opts [String, Array<String>, nil] :instructions custom keyboard hint footer text, rendered verbatim on one line (newlines are not re-prefixed)
     # @return [String, CANCEL] user input (lines joined with \n) or CANCEL if cancelled
     def multiline_text(message:, **opts)
       Prompts::MultilineText.new(message:, **opts).run
@@ -182,8 +204,11 @@ module Clack
     #
     # @param message [String] the prompt message
     # @option opts [String] :mask character to display for each input character (default: ▪)
-    # @option opts [Proc, nil] :validate validation function returning error string, Warning, or nil
+    # @option opts [Proc, Regexp, Symbol, Array, Hash, nil, false] :validate validator (see {Validators.resolve});
+    #   a proc returns an error string, Warning, or nil; nil or false disables validation
     # @option opts [String, nil] :help help text shown below the message
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
+    # @option opts [String, Array<String>, nil] :instructions custom keyboard hint footer text, rendered verbatim on one line (newlines are not re-prefixed)
     # @return [String, CANCEL] password or CANCEL if cancelled
     def password(message:, **opts)
       Prompts::Password.new(message:, **opts).run
@@ -194,8 +219,22 @@ module Clack
     # @param message [String] the prompt message
     # @option opts [String] :active label for "yes" option (default: "Yes")
     # @option opts [String] :inactive label for "no" option (default: "No")
-    # @option opts [Boolean] :initial_value default selection (default: true)
+    # @option opts [Object] :initial_value default selection (default: true); coerced to a
+    #   Boolean, so nil and false start on "no" and any other value starts on "yes"
+    # @option opts [Boolean] :vertical render the two options on separate lines instead of
+    #   side by side (default: false); handy for long or localized labels
+    # @option opts [String, nil] :help help text shown below the message
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
+    # @option opts [String, Array<String>, nil] :instructions custom keyboard hint footer text, rendered verbatim on one line (newlines are not re-prefixed)
     # @return [Boolean, CANCEL] true/false or CANCEL if cancelled
+    #
+    # @example Stacked layout
+    #   Clack.confirm(
+    #     message: "Overwrite ~/.zshrc?",
+    #     active: "Yes, back it up and replace it",
+    #     inactive: "No, keep my existing file",
+    #     vertical: true
+    #   )
     def confirm(message:, **opts)
       Prompts::Confirm.new(message:, **opts).run
     end
@@ -203,10 +242,18 @@ module Clack
     # Prompt to select one option from a list.
     #
     # @param message [String] the prompt message
-    # @param options [Array<Hash, String>] list of options
+    # @param options [Array<Hash, String>, Hash] list of options, or a Hash of value => label
+    #   (or value => {label:, hint:, disabled:}); see README "Option shorthands"
     # @option opts [Object, nil] :initial_value value of initially selected option
     # @option opts [Integer, nil] :max_items max visible items (enables scrolling)
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
+    # @option opts [Boolean, nil] :show_instructions show the keyboard hint footer (default: Clack.settings[:show_instructions])
+    # @option opts [String, Array<String>, nil] :instructions custom keyboard hint footer text, rendered verbatim on one line (newlines are not re-prefixed)
     # @return [Object, CANCEL] selected value or CANCEL if cancelled
+    #
+    # @example Hash shorthand
+    #   db = Clack.select(message: "Database?", options: {pg: "PostgreSQL", mysql: "MySQL"})
+    #   # => :pg
     def select(message:, options:, **opts)
       Prompts::Select.new(message:, options: options, **opts).run
     end
@@ -214,11 +261,15 @@ module Clack
     # Prompt to select multiple options from a list.
     #
     # @param message [String] the prompt message
-    # @param options [Array<Hash, String>] list of options
+    # @param options [Array<Hash, String>, Hash] list of options, or a Hash of value => label
+    #   (or value => {label:, hint:, disabled:})
     # @option opts [Array, nil] :initial_values initially selected values
     # @option opts [Boolean] :required require at least one selection (default: true)
     # @option opts [Integer, nil] :max_items max visible items (enables scrolling)
     # @option opts [Object, nil] :cursor_at value of initially focused option
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
+    # @option opts [Boolean, nil] :show_instructions show the keyboard hint footer (default: Clack.settings[:show_instructions])
+    # @option opts [String, Array<String>, nil] :instructions custom keyboard hint footer text, rendered verbatim on one line (newlines are not re-prefixed)
     # @return [Array, CANCEL] selected values or CANCEL if cancelled
     def multiselect(message:, options:, **opts)
       Prompts::Multiselect.new(message:, options: options, **opts).run
@@ -230,17 +281,42 @@ module Clack
     # @option opts [Array<String>, nil] :frames custom animation frames
     # @option opts [Float, nil] :delay seconds between frames
     # @option opts [Proc, nil] :style_frame proc to style each frame
+    # @option opts [String, nil] :cancel_message text for #cancel with no argument and for
+    #   Ctrl+C / exit while running (default: the global messages[:cancel], "Cancelled")
+    # @option opts [String, nil] :error_message text for #error with no argument and for an
+    #   uncaught exception while running (default: the global messages[:error],
+    #   "Something went wrong")
+    # @option opts [#call, nil] :on_cancel called with no arguments after the spinner is
+    #   cancelled, whether by #cancel, Ctrl+C, exit, or an early exit from a Clack.spin
+    #   block; a StandardError raised by the hook is reported with Kernel#warn and swallowed
     # @option opts [IO] :output output stream (default: $stdout)
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
     # @return [Prompts::Spinner] spinner instance (call #start, #stop, #error, #cancel, #clear)
+    # @raise [ArgumentError] if cancel_message/error_message are not Strings or on_cancel
+    #   does not respond to #call
+    #
+    # @example Custom cancel and error messages
+    #   s = Clack.spinner(cancel_message: "Deploy aborted", error_message: "Deploy failed",
+    #                     on_cancel: -> { release_lock })
+    #   s.start("Deploying")
     def spinner(**opts)
       Prompts::Spinner.new(**opts)
     end
 
     # Run a block with a spinner, handling success/error automatically.
     #
+    # If the block does not complete, the spinner still ends with a final line before the
+    # exception or non-local exit propagates: the cancel message for exit (any status),
+    # Ctrl+C, break, and throw; +error+ or the exception message for anything raised.
+    #
     # @param message [String] initial spinner message
     # @param success [String, nil] message on success (defaults to message)
     # @param error [String, nil] message on error (defaults to exception message)
+    # @option opts [String, nil] :cancel_message see {#spinner}
+    # @option opts [String, nil] :error_message see {#spinner}; note that an exception
+    #   raised by the block uses +error:+ or the exception message, not this
+    # @option opts [#call, nil] :on_cancel see {#spinner}
+    # @option opts [Boolean, nil] :with_guide see {#spinner}
     # @return [Object] the block's return value
     # @raise [Exception] re-raises any exception from the block
     #
@@ -257,6 +333,10 @@ module Clack
     #     s.message "Step 2..."
     #     do_step_2
     #   end
+    #
+    # @example Early exit still prints a final line
+    #   Clack.spin("Building", cancel_message: "Build cancelled") { exit 2 }
+    #   # => "■  Build cancelled", then the process exits with status 2
     def spin(message, success: nil, error: nil, **opts)
       s = spinner(**opts)
       s.start(message)
@@ -264,21 +344,31 @@ module Clack
         result = yield(s)
         s.stop(success || message)
         result
-      rescue => exception
+      rescue SystemExit, SignalException
+        s.cancel
+        raise
+      rescue Exception => exception # standard:disable Lint/RescueException
         s.error(error || exception.message)
         raise
+      ensure
+        # break or throw out of the block leave no exception in flight; a
+        # no-op when one of the clauses above already finished the spinner.
+        s.abandon
       end
     end
 
     # Prompt with type-to-filter autocomplete.
     #
     # @param message [String] the prompt message
-    # @param options [Array<Hash, String>] list of options to filter
+    # @param options [Array<Hash, String>, Hash] list of options to filter, or a Hash of value => label
     # @option opts [String, nil] :placeholder placeholder text
     # @option opts [Proc, nil] :filter custom filter proc receiving (option_hash, query_string)
     #   and returning true/false. Defaults to fuzzy matching across label, value, and hint,
     #   sorted by relevance score.
     # @option opts [Integer, nil] :max_items max visible items (enables scrolling, default: 5)
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
+    # @option opts [Boolean, nil] :show_instructions show the keyboard hint footer (default: Clack.settings[:show_instructions])
+    # @option opts [String, Array<String>, nil] :instructions custom keyboard hint footer text, rendered verbatim on one line (newlines are not re-prefixed)
     # @return [Object, CANCEL] selected value or CANCEL if cancelled
     def autocomplete(message:, options:, **opts)
       Prompts::Autocomplete.new(message:, options: options, **opts).run
@@ -287,7 +377,7 @@ module Clack
     # Prompt with type-to-filter autocomplete and multiselect.
     #
     # @param message [String] the prompt message
-    # @param options [Array<Hash, String>] list of options to filter
+    # @param options [Array<Hash, String>, Hash] list of options to filter, or a Hash of value => label
     # @option opts [String, nil] :placeholder placeholder text
     # @option opts [Boolean] :required require at least one selection (default: true)
     # @option opts [Array, nil] :initial_values initially selected values
@@ -295,6 +385,9 @@ module Clack
     #   and returning true/false. Defaults to fuzzy matching across label, value, and hint,
     #   sorted by relevance score.
     # @option opts [Integer, nil] :max_items max visible items (enables scrolling, default: 5)
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
+    # @option opts [Boolean, nil] :show_instructions show the keyboard hint footer (default: Clack.settings[:show_instructions])
+    # @option opts [String, Array<String>, nil] :instructions custom keyboard hint footer text, rendered verbatim on one line (newlines are not re-prefixed)
     # @return [Array, CANCEL] selected values or CANCEL if cancelled
     def autocomplete_multiselect(message:, options:, **opts)
       Prompts::AutocompleteMultiselect.new(message:, options: options, **opts).run
@@ -306,6 +399,11 @@ module Clack
     # @option opts [String] :root starting directory (default: ".")
     # @option opts [Boolean] :only_directories only show directories (default: false)
     # @option opts [Integer, nil] :max_items max visible items (enables scrolling, default: 5)
+    # @option opts [Proc, Regexp, Symbol, Array, Hash, nil, false] :validate validator for the resolved
+    #   absolute path (see {Validators.resolve}); +:directory_exists+ and +:path_exists+ fit here
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
+    # @option opts [Boolean, nil] :show_instructions show the keyboard hint footer (default: Clack.settings[:show_instructions])
+    # @option opts [String, Array<String>, nil] :instructions custom keyboard hint footer text, rendered verbatim on one line (newlines are not re-prefixed)
     # @return [String, CANCEL] selected path or CANCEL if cancelled
     def path(message:, **opts)
       Prompts::Path.new(message:, **opts).run
@@ -322,9 +420,43 @@ module Clack
 
     # Prompt to select an option by pressing a key.
     #
+    # Each option carries a single-character +:key+ (defaults to the first
+    # character of the value). Pressing that key selects the option and
+    # submits immediately, so there is no cursor to move. Enter only does
+    # something when +:initial_value+ highlights a default. Option keys win
+    # over custom key aliases (except aliases mapped to +:cancel+).
+    #
     # @param message [String] the prompt message
-    # @param options [Array<Hash>] options with :value, :label, and :key
+    # @param options [Array<Hash>, Hash] options with :value, :label, and optionally :key and :hint, or a Hash of
+    #   value => label (key defaults to the first character of the value) or value => {label:, key:, hint:}
+    # @option opts [Boolean] :case_sensitive match keys exactly instead of ignoring case (default: false)
+    # @option opts [Object, nil] :initial_value value of the option highlighted at start; Enter submits it
+    #   and CI mode returns it (default: nil). The highlight is a color effect, so when colors are off
+    #   (NO_COLOR, piped output) mark the default in that option's :hint. A value that matches no option
+    #   is ignored with a warning on stderr
+    # @option opts [Proc, Regexp, Symbol, Array, Hash, nil, false] :validate validator (see {Validators.resolve});
+    #   a proc returns an error string, Warning, or nil; nil or false disables validation
+    # @option opts [Symbol, Proc, nil] :transform transform function to normalize the value
+    # @option opts [String, nil] :help help text shown below the message
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
+    # @option opts [String, Array<String>, nil] :instructions custom keyboard hint footer text, rendered verbatim on one line (newlines are not re-prefixed)
     # @return [Object, CANCEL] selected value or CANCEL if cancelled
+    #
+    # @example Distinct upper- and lowercase keys with a safe default
+    #   Clack.select_key(
+    #     message: "Apply migration?",
+    #     options: [
+    #       { value: :yes_all, label: "Yes to all", key: "Y" },
+    #       { value: :yes, label: "Yes", key: "y" },
+    #       { value: :no, label: "No", key: "n", hint: "default" }
+    #     ],
+    #     case_sensitive: true,
+    #     initial_value: :no
+    #   )
+    #
+    # @example Hash shorthand
+    #   Clack.select_key(message: "Action?", options: {create: "Create", open: "Open", quit: "Quit"})
+    #   # press "o" => :open
     def select_key(message:, options:, **opts)
       Prompts::SelectKey.new(message:, options: options, **opts).run
     end
@@ -332,6 +464,7 @@ module Clack
     # Run multiple tasks with progress indicators.
     #
     # @param tasks [Array<Hash>] tasks with :title, :task (Proc), and optional :enabled (Boolean, default: true)
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
     # @return [Array<Hash>] task results
     def tasks(tasks:, **opts)
       Prompts::Tasks.new(tasks: tasks, **opts).run
@@ -340,12 +473,16 @@ module Clack
     # Prompt to select multiple options organized in groups.
     #
     # @param message [String] the prompt message
-    # @param options [Array<Hash>] groups with :label and :options
+    # @param options [Array<Hash>, Hash] groups with :label and :options, or a Hash of
+    #   group label => options (each options list accepts an Array or a value => label Hash)
     # @option opts [Array, nil] :initial_values initially selected values
     # @option opts [Boolean] :required require at least one selection (default: true)
     # @option opts [Object, nil] :cursor_at value of initially focused option
     # @option opts [Boolean] :selectable_groups allow toggling entire groups (default: false)
     # @option opts [Integer] :group_spacing lines between groups (default: 0)
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
+    # @option opts [Boolean, nil] :show_instructions show the keyboard hint footer (default: Clack.settings[:show_instructions])
+    # @option opts [String, Array<String>, nil] :instructions custom keyboard hint footer text, rendered verbatim on one line (newlines are not re-prefixed)
     # @return [Array, CANCEL] selected values or CANCEL if cancelled
     def group_multiselect(message:, options:, **opts)
       Prompts::GroupMultiselect.new(message:, options: options, **opts).run
@@ -361,8 +498,11 @@ module Clack
     # @option opts [Date, Time, String, nil] :initial_value initial date value (default: today)
     # @option opts [Date, nil] :min minimum allowed date
     # @option opts [Date, nil] :max maximum allowed date
-    # @option opts [Proc, nil] :validate custom validation proc
+    # @option opts [Proc, Regexp, Symbol, Array, Hash, nil, false] :validate validator (see {Validators.resolve});
+    #   a proc returns an error string, Warning, or nil; nil or false disables validation
     # @option opts [String, nil] :help help text shown below the message
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
+    # @option opts [String, Array<String>, nil] :instructions custom keyboard hint footer text, rendered verbatim on one line (newlines are not re-prefixed)
     # @return [Date, CANCEL] selected date or CANCEL if cancelled
     def date(message:, **opts)
       Prompts::Date.new(message:, **opts).run
@@ -375,14 +515,24 @@ module Clack
     # @param message [String] the prompt message
     # @option opts [Numeric] :min minimum value (default: 0)
     # @option opts [Numeric] :max maximum value (default: 100)
-    # @option opts [Numeric] :step increment size (default: 1)
+    # @option opts [Numeric] :step increment size (default: 1); fractional steps
+    #   such as 0.1 are snapped exactly, so three steps from 0 is 0.3
     # @option opts [Numeric, nil] :initial_value initial value (defaults to min)
-    # @option opts [Proc, nil] :validate validation proc
+    # @option opts [Proc, Regexp, Symbol, Array, Hash, nil, false] :validate validator (see {Validators.resolve});
+    #   a proc returns an error string, Warning, or nil; nil or false disables validation
     # @option opts [String, nil] :help help text shown below the message
-    # @return [Numeric, CANCEL] selected value or CANCEL if cancelled
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
+    # @option opts [String, Array<String>, nil] :instructions custom keyboard hint footer text, rendered verbatim on one line (newlines are not re-prefixed)
+    # @return [Numeric, CANCEL] the selected value (Integer when min and
+    #   step are both Integers, Float when either is a Float; Rational inputs
+    #   return Rational) or CANCEL if cancelled
     #
     # @example Basic usage
     #   volume = Clack.range(message: "Volume", min: 0, max: 100, step: 5)
+    #
+    # @example Fractional step
+    #   opacity = Clack.range(message: "Opacity", min: 0, max: 1, step: 0.1)
+    #   # => 0.3 after three right arrows
     def range(message:, **opts)
       Prompts::Range.new(message:, **opts).run
     end
@@ -405,6 +555,7 @@ module Clack
     #
     # @param message [String] the note content
     # @param title [String, nil] optional title
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
     # @return [void]
     def note(message = "", title: nil, **opts)
       Note.render(message, title: title, **opts)
@@ -418,6 +569,7 @@ module Clack
     # @option opts [:left, :center, :right] :title_align title alignment
     # @option opts [Integer, :auto] :width box width
     # @option opts [Boolean] :rounded use rounded corners
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
     # @return [void]
     def box(message = "", title: "", **opts)
       Box.render(message, title: title, **opts)
@@ -429,13 +581,14 @@ module Clack
     # @param title [String] title displayed at the top
     # @option opts [Integer, nil] :limit max lines to show (older lines scroll out)
     # @option opts [Boolean] :retain_log keep full log history for display on error
+    # @option opts [Boolean, nil] :with_guide show the guide rail (default: Clack.settings[:with_guide])
     # @return [TaskLog] task log instance
     def task_log(title:, **opts)
       TaskLog.new(title: title, **opts)
     end
 
     # Access global settings
-    # @return [Hash] Current configuration
+    # @return [Hash] Current configuration (:aliases, :with_guide, :show_instructions, :ci_mode, :messages)
     # @see Core::Settings.update for modifying settings
     def settings
       Core::Settings.config
@@ -443,21 +596,34 @@ module Clack
 
     # Update global settings
     # @option opts [Hash, nil] :aliases Custom key to action mappings
-    # @option opts [Boolean, nil] :with_guide Whether to show guide bars
-    # @option opts [Boolean, Symbol, nil] :ci_mode CI mode: true (always), :auto (detect non-TTY/CI env), false (never)
+    # @option opts [Boolean, nil] :with_guide Whether to show guide bars (the gray rail and corners around prompts)
+    # @option opts [Boolean, nil] :show_instructions Whether list prompts show their keyboard hint footer
+    # @option opts [Boolean, Symbol, nil] :ci_mode CI mode: true (always), :auto (active when
+    #   the prompt's input is not a TTY, or a CI env var is set), false (never)
+    # @option opts [Hash{Symbol=>String}, nil] :messages Cancel/error strings used by spinners
+    #   and {#handle_cancel}: +{cancel: "Cancelled", error: "Something went wrong"}+.
+    #   Keys are merged, so either can be given alone.
     # @return [Hash] Updated configuration
+    # @raise [ArgumentError] for an unknown messages key or a non-String value
     #
     # @example Custom key bindings
     #   Clack.update_settings(aliases: { "y" => :enter, "n" => :cancel })
     #
-    # @example Disable guide bars
+    # @example Disable guide bars everywhere (per-call with_guide: overrides this)
     #   Clack.update_settings(with_guide: false)
     #
+    # @example Hide keyboard hint footers
+    #   Clack.update_settings(show_instructions: false)
+    #
     # @example Enable CI mode (auto-submit with defaults)
     #   Clack.update_settings(ci_mode: true)
     #
-    # @example Auto-detect CI mode (non-TTY or CI environment)
+    # @example Auto-detect CI mode (piped input or CI environment)
+    #   # Without this, prompting on a piped stdin raises Clack::NotATerminalError.
     #   Clack.update_settings(ci_mode: :auto)
+    #
+    # @example Localize cancel and error messages
+    #   Clack.update_settings(messages: {cancel: "Abgebrochen", error: "Etwas ging schief"})
     def update_settings(**opts)
       Core::Settings.update(**opts)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clack
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Steve Whittaker
@@ -43,6 +43,7 @@ files:
 - lib/clack.rb
 - lib/clack/box.rb
 - lib/clack/colors.rb
+- lib/clack/core/chrome.rb
 - lib/clack/core/ci_mode.rb
 - lib/clack/core/cursor.rb
 - lib/clack/core/fuzzy_matcher.rb
@@ -54,6 +55,7 @@ files:
 - lib/clack/core/settings.rb
 - lib/clack/core/text_input_helper.rb
 - lib/clack/environment.rb
+- lib/clack/errors.rb
 - lib/clack/group.rb
 - lib/clack/log.rb
 - lib/clack/note.rb