# caique/clack

> Every export of caique/clack, with its signature and doc comment: CANCEL_SYMBOL, formatInstructionFooter, isCancel, isCI, isTTY, MULTISELECT_INSTRUCTIONS and 54 more, plus 26 types.

Source: https://caique.interlace.tools/docs/api/clack

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`caique/clack` — `@clack/prompts`' API on caique's own engine: its twelve prompts, its
writers, its symbols and its settings, under the names clack gives them.

## Read this before reading the compatibility number

`@clack/prompts`' own suite is 606 cases, and **289 of its 444 assertions are
`toMatchSnapshot()`, spread across 17 of its 19 files**. Those seventeen files grade
clack's exact frames — every bar, every colour, every cursor move — and they stay
subtracted from the row by D-001: agreeing with them byte for byte would mean copying
clack's renderer, which is not what a drop-in owes a caller.

**What is left is seventeen cases in two files, and this module passes sixteen:**

- `limit-options.test.ts`, 14 cases — the sliding window a list draws through
  (`clack-limit.ts`).
- `guide.test.ts`, 3 cases — all twelve prompts render the same grey guide, and none
  renders one when `withGuide` is false. Until D-152 this module exported only
  `limitOptions`, and the first two were written off as "the drawing"; they are not —
  they grade that the twelve prompts exist, take clack's options and streams, cancel on
  escape and draw clack's layout, which is the whole of what a caller migrating a prompt
  needs. They pass now.
- The third, `no prompt renders a guide when withGuide is globally false`, calls
  `updateSettings` **imported from `@clack/core`** and asserts our prompts obey it. That is
  module state in a package caique does not depend on (U6) and cannot read, so it is the
  row's one ceiling. `updateSettings` from *this* module does the same job for a program
  that imports it from here.

Not built, and named so it is a decision rather than a silence: `box`, `progress` and
`taskLog`, which no graded case reaches (D-152).

```ts
import { CANCEL_SYMBOL, formatInstructionFooter, isCancel, … } from 'caique/clack';
```

## Functions

### formatInstructionFooter

The key hints under a list: one line, and the closing guide under it when there is one.

```ts
function formatInstructionFooter(instructions: string[], hasGuide: boolean): string[];
```

| Parameter | Type |
| :-- | :-- |
| `instructions` | `string[]` |
| `hasGuide` | `boolean` |

**Returns** `string[]`

### limitOptions

The window of options a list should draw, as lines, with `...` where it was cut.

The order of the four decisions is the behaviour, and every one of them is a graded case:

1. **How many options may show at all** — the smaller of `maxItems` and the rows left
   after `rowPadding`, but never fewer than five. "clamps to 5 rows minimum" is that
   floor, and it is why a list in a seven-row terminal still shows something.
2. **Where the window starts** — it only slides once the cursor comes within three of the
   bottom, and it stops at the end of the list rather than running past it.
3. **Which ends get an ellipsis** — each `...` costs a line, so it is counted before the
   options are, not after.
4. **What to give up when the options wrapped** — options are dropped whole, away from the
   cursor first, and an ellipsis appears wherever something was dropped. The three
   "multi-line item clamping" cases are start, middle and end of that.

```ts
function limitOptions<TOption>({ cursor, options, style, output, maxItems, columnPadding, rowPadding, }: LimitOptionsParams<TOption>): string[];
```

| Parameter | Type |
| :-- | :-- |
| `{ cursor, options, style, output, maxItems, columnPadding, rowPadding, }` | `LimitOptionsParams<TOption>` |

**Returns** `string[]`

### updateSettings

Change the settings every later prompt reads.

**These are caique's settings, not `@clack/core`'s**, and that is the one place this
subpath cannot follow the incumbent: clack's live in a module caique does not depend on
(U6), so a program that calls `@clack/core`'s `updateSettings` is changing a package our
prompts never read. A program that imports this one from `caique/clack` gets the behaviour.

```ts
function updateSettings(updates: ClackSettings): void;
```

| Parameter | Type |
| :-- | :-- |
| `updates` | `ClackSettings` |

**Returns** `void`

## Constants

### autocomplete

`autocomplete` — `select` with a search box over the list.

```ts
const autocomplete: <Value>(opts: AutocompleteOptions<Value>) => Answer<Value>;
```

### autocompleteMultiselect

`autocompleteMultiselect` — `multiselect` with a search box over the list.

```ts
const autocompleteMultiselect: <Value>(opts: AutocompleteMultiSelectOptions<Value>) => Answer<Value[]>;
```

### cancel

Closes a session that was cancelled: the end of the guide, and the message in red.

```ts
const cancel: (message?: string, opts?: CommonOptions) => void;
```

### CANCEL_SYMBOL

What every prompt resolves to when it is cancelled. Test it with `isCancel`.

```ts
const CANCEL_SYMBOL: unique symbol;
```

### confirm

`confirm` — yes or no: arrows toggle, `y` and `n` answer at once.

```ts
const confirm: (opts: ConfirmOptions) => Answer<boolean>;
```

### date

`date` — a date typed field by field, or stepped with the arrows inside `minDate`…`maxDate`.

```ts
const date: (opts: DateOptions) => Answer<Date>;
```

### group

Ask a set of prompts in order; a cancelled one is recorded as `'canceled'` when `onCancel` is given.

```ts
const group: <T>(prompts: PromptGroup<T>, opts?: PromptGroupOptions<T>) => Promise<Prettify<PromptGroupAwaitedReturn<T>>>;
```

### groupMultiselect

`groupMultiselect` — a multi-selection in named groups; a group toggles all of its options.

```ts
const groupMultiselect: <Value>(opts: GroupMultiSelectOptions<Value>) => Answer<Value[]>;
```

### intro

Opens a session: the top of the guide, and a title beside it.

```ts
const intro: (title?: string, opts?: CommonOptions) => void;
```

### isCancel

Whether a prompt's answer is a cancellation rather than an answer.

```ts
const isCancel: (value: unknown) => value is symbol;
```

### isCI

Whether `CI` is the string `true`, which is the test clack makes. This and the glyph table
above stay clack's rules rather than roundel's: `interactive()` asks whether a person can
answer, which clack never asks, and clack's table counts `CI` where roundel's `unicode()` does not.

```ts
const isCI: () => boolean;
```

### isTTY

Whether a stream is a terminal.

```ts
const isTTY: (output: {
    isTTY?: boolean;
}) => boolean;
```

### log

clack's `log`: a message on the guide, with a symbol for its kind.

```ts
const log: {
    message: typeof message;
    info: (text: string, opts?: LogMessageOptions) => void;
    success: (text: string, opts?: LogMessageOptions) => void;
    step: (text: string, opts?: LogMessageOptions) => void;
    warn: (text: string, opts?: LogMessageOptions) => void;
    /** An alias for `log.warn()`. */
    warning: (text: string, opts?: LogMessageOptions) => void;
    error: (text: string, opts?: LogMessageOptions) => void;
};
```

### multiline

`multiline` — typing across lines; a second enter at the end submits, or tab reaches `[ submit ]`.

```ts
const multiline: (opts: MultiLineOptions) => Answer<string>;
```

### multiselect

`multiselect` — any number of options: space toggles, `a` toggles all, `i` inverts.

```ts
const multiselect: <Value>(opts: MultiSelectOptions<Value>) => Answer<Value[]>;
```

### MULTISELECT_INSTRUCTIONS

```ts
const MULTISELECT_INSTRUCTIONS: string[];
```

### note

A message in a box on the guide, with a title in its top edge.

```ts
const note: (text?: string, title?: string, opts?: NoteOptions) => void;
```

### outro

Closes a session: the end of the guide, and a last message beside it.

```ts
const outro: (message?: string, opts?: CommonOptions) => void;
```

### password

`password` — typing that is drawn as a mask and never echoed.

```ts
const password: (opts: PasswordOptions) => Answer<string>;
```

### path

`path` — an autocomplete over the filesystem, starting at `root` or the working directory.

```ts
const path: (opts: PathOptions) => Answer<string>;
```

### S_BAR

```ts
const S_BAR: string;
```

### S_BAR_END

```ts
const S_BAR_END: string;
```

### S_BAR_END_RIGHT

```ts
const S_BAR_END_RIGHT: string;
```

### S_BAR_H

```ts
const S_BAR_H: string;
```

### S_BAR_START

```ts
const S_BAR_START: string;
```

### S_BAR_START_RIGHT

```ts
const S_BAR_START_RIGHT: string;
```

### S_CHECKBOX_ACTIVE

```ts
const S_CHECKBOX_ACTIVE: string;
```

### S_CHECKBOX_INACTIVE

```ts
const S_CHECKBOX_INACTIVE: string;
```

### S_CHECKBOX_SELECTED

```ts
const S_CHECKBOX_SELECTED: string;
```

### S_CONNECT_LEFT

```ts
const S_CONNECT_LEFT: string;
```

### S_CORNER_BOTTOM_LEFT

```ts
const S_CORNER_BOTTOM_LEFT: string;
```

### S_CORNER_BOTTOM_RIGHT

```ts
const S_CORNER_BOTTOM_RIGHT: string;
```

### S_CORNER_TOP_LEFT

```ts
const S_CORNER_TOP_LEFT: string;
```

### S_CORNER_TOP_RIGHT

```ts
const S_CORNER_TOP_RIGHT: string;
```

### S_ERROR

```ts
const S_ERROR: string;
```

### S_INFO

```ts
const S_INFO: string;
```

### S_PASSWORD_MASK

```ts
const S_PASSWORD_MASK: string;
```

### S_RADIO_ACTIVE

```ts
const S_RADIO_ACTIVE: string;
```

### S_RADIO_INACTIVE

```ts
const S_RADIO_INACTIVE: string;
```

### S_STEP_ACTIVE

```ts
const S_STEP_ACTIVE: string;
```

### S_STEP_CANCEL

```ts
const S_STEP_CANCEL: string;
```

### S_STEP_ERROR

```ts
const S_STEP_ERROR: string;
```

### S_STEP_SUBMIT

```ts
const S_STEP_SUBMIT: string;
```

### S_SUCCESS

```ts
const S_SUCCESS: string;
```

### S_WARN

```ts
const S_WARN: string;
```

### select

`select` — one option from a list, drawn through `limitOptions`.

```ts
const select: <Value>(opts: SelectOptions<Value>) => Answer<Value>;
```

### SELECT_INSTRUCTIONS

```ts
const SELECT_INSTRUCTIONS: string[];
```

### selectKey

`selectKey` — one option, chosen by pressing the first letter of its value.

```ts
const selectKey: <Value extends string>(opts: SelectKeyOptions<Value>) => Answer<Value>;
```

### settings

The process-wide settings every prompt here reads, and `updateSettings` writes.

```ts
const settings: {
    actions: Set<Action>;
    aliases: Map<string, Action>;
    messages: {
        cancel: string;
        error: string;
    };
    withGuide: boolean;
};
```

### spinner

A spinner on the guide: animated on a terminal outside CI, printed once per message anywhere else.

```ts
const spinner: (opts?: SpinnerOptions) => SpinnerResult;
```

### stream

clack's `stream`: `log`, for text that arrives in pieces.

```ts
const stream: {
    message: typeof streamed;
    info: (chunks: Chunks) => Promise<void>;
    success: (chunks: Chunks) => Promise<void>;
    step: (chunks: Chunks) => Promise<void>;
    warn: (chunks: Chunks) => Promise<void>;
    warning: (chunks: Chunks) => Promise<void>;
    error: (chunks: Chunks) => Promise<void>;
};
```

### symbol

The glyph that opens a prompt's title line, coloured for its state.

```ts
const symbol: (state: State) => string;
```

### symbolBar

The guide bar beside a prompt's body, coloured for its state; none while it validates.

```ts
const symbolBar: (state: State) => string | undefined;
```

### tasks

Run tasks one after another, each under its own spinner, each ending on what it returned.

```ts
const tasks: (list: Task[], opts?: CommonOptions) => Promise<void>;
```

### text

`text` — one line of typing, with a placeholder, a default and a validator.

```ts
const text: (opts: TextOptions) => Answer<string>;
```

### unicode

Whether the terminal can draw clack's box characters; read once, as the incumbent reads it.

```ts
const unicode: boolean;
```

### unicodeOr

The first glyph where the terminal draws unicode, the second where it does not.

```ts
const unicodeOr: (glyph: string, fallback: string) => string;
```

## Interfaces

### AutocompleteMultiSelectOptions

```ts
interface AutocompleteMultiSelectOptions<Value> extends AutocompleteSharedOptions<Value> {
    initialValues?: Value[];
    required?: boolean;
}
```

### AutocompleteOptions

```ts
interface AutocompleteOptions<Value> extends AutocompleteSharedOptions<Value> {
    initialValue?: Value;
    initialUserInput?: string;
    completeOnTab?: boolean;
}
```

### ClackSettings

What `updateSettings` takes.

```ts
interface ClackSettings {
    /** Extra keys for an action — `{ w: 'up' }` — which never replace an existing alias. */
    aliases?: Record<string, Action>;
    messages?: {
        cancel?: string;
        error?: string;
    };
    /** `false` draws every prompt without its left-hand guide. */
    withGuide?: boolean;
}
```

### CommonOptions

The streams and settings every clack call accepts.

```ts
interface CommonOptions {
    input?: NodeJS.ReadableStream;
    output?: NodeJS.WritableStream & SizedOutput;
    signal?: AbortSignal;
    withGuide?: boolean;
}
```

### ConfirmOptions

```ts
interface ConfirmOptions extends CommonOptions {
    message: string;
    active?: string;
    inactive?: string;
    initialValue?: boolean;
    vertical?: boolean;
}
```

### DateOptions

```ts
interface DateOptions extends CommonOptions {
    message: string;
    format?: DateFormat;
    locale?: string;
    defaultValue?: Date;
    initialValue?: Date;
    minDate?: Date;
    maxDate?: Date;
    validate?: Validate<Date>;
}
```

### GroupMultiSelectOptions

```ts
interface GroupMultiSelectOptions<Value> extends CommonOptions {
    message: string;
    options: Record<string, Option<Value>[]>;
    initialValues?: Value[];
    maxItems?: number;
    required?: boolean;
    cursorAt?: Value;
    selectableGroups?: boolean;
    groupSpacing?: number;
    showInstructions?: boolean;
}
```

### LimitOptionsParams

What `limitOptions` takes. Named as the incumbent names it, because callers import it.

```ts
interface LimitOptionsParams<TOption> extends CommonOptions {
    /** The list to display. */
    options: TOption[];
    /** The index of the active option. */
    cursor: number;
    /** Renders one option, told whether it is the active one. */
    style: (option: TOption, active: boolean) => string;
    /** The most options to show, before the terminal's own height is taken into account. */
    maxItems?: number | undefined;
    /** Columns taken by something else on the line — a bar, an indent. */
    columnPadding?: number | undefined;
    /** Rows taken by something else on the screen — a message, a footer. */
    rowPadding?: number | undefined;
}
```

### LogMessageOptions

```ts
interface LogMessageOptions extends CommonOptions {
    symbol?: string;
    spacing?: number;
    secondarySymbol?: string;
}
```

### MultiLineOptions

```ts
interface MultiLineOptions extends TextOptions {
    /** Draw a `[ submit ]` button, reached with tab, instead of submitting on a second enter. */
    showSubmit?: boolean;
}
```

### MultiSelectOptions

```ts
interface MultiSelectOptions<Value> extends CommonOptions {
    message: string;
    options: Option<Value>[];
    initialValues?: Value[];
    maxItems?: number;
    required?: boolean;
    cursorAt?: Value;
    showInstructions?: boolean;
}
```

### NoteOptions

```ts
interface NoteOptions extends CommonOptions {
    /** Applied to every line of the message. */
    format?: (line: string) => string;
}
```

### PasswordOptions

```ts
interface PasswordOptions extends CommonOptions {
    message: string;
    mask?: string;
    validate?: Validate<string>;
    clearOnError?: boolean;
}
```

### PathOptions

```ts
interface PathOptions extends CommonOptions {
    message: string;
    root?: string;
    directory?: boolean;
    initialValue?: string;
    validate?: Validate<string>;
}
```

### PromptGroupOptions

```ts
interface PromptGroupOptions<T> {
    /** Called when a prompt in the group is cancelled, with the answers so far. */
    onCancel?: (opts: {
        results: Prettify<Partial<PromptGroupAwaitedReturn<T>>>;
    }) => void;
}
```

### SelectKeyOptions

```ts
interface SelectKeyOptions<Value extends string> extends CommonOptions {
    message: string;
    options: Option<Value>[];
    initialValue?: Value;
    caseSensitive?: boolean;
}
```

### SelectOptions

```ts
interface SelectOptions<Value> extends CommonOptions {
    message: string;
    options: Option<Value>[];
    initialValue?: Value;
    maxItems?: number;
    showInstructions?: boolean;
}
```

### SizedOutput

A stream a list can measure itself against. Anything with a size, including a test double.

```ts
interface SizedOutput {
    columns?: number;
    rows?: number;
    isTTY?: boolean;
}
```

### SpinnerOptions

```ts
interface SpinnerOptions extends CommonOptions {
    indicator?: 'dots' | 'timer';
    onCancel?: () => void;
    cancelMessage?: string;
    errorMessage?: string;
    frames?: string[];
    delay?: number;
    styleFrame?: (frame: string) => string;
}
```

### SpinnerResult

```ts
interface SpinnerResult {
    start(msg?: string): void;
    stop(msg?: string): void;
    cancel(msg?: string): void;
    error(msg?: string): void;
    message(msg?: string): void;
    clear(): void;
    readonly isCancelled: boolean;
}
```

### Task

```ts
interface Task {
    title: string;
    task: (message: (string: string) => void) => string | Promise<string> | void | Promise<void>;
    enabled?: boolean;
}
```

### TextOptions

```ts
interface TextOptions extends CommonOptions {
    message: string;
    placeholder?: string;
    defaultValue?: string;
    initialValue?: string;
    validate?: Validate<string>;
}
```

## Types

### DateFormat

The date field order, as clack names it.

```ts
type DateFormat = 'YMD' | 'MDY' | 'DMY';
```

### Option

One choice in a list: a primitive value may go without a label, anything else may not.

```ts
type Option<Value> = Value extends Primitive ? {
    value: Value;
    label?: string;
    hint?: string;
    disabled?: boolean;
} : {
    value: Value;
    label: string;
    hint?: string;
    disabled?: boolean;
};
```

### PromptGroup

A named set of prompts, each told the answers before it.

```ts
type PromptGroup<T> = {
    [P in keyof T]: (opts: {
        results: Prettify<Partial<PromptGroupAwaitedReturn<Omit<T, P>>>>;
    }) => undefined | Promise<T[P] | undefined>;
};
```

### PromptGroupAwaitedReturn

What a group resolves to: every prompt's answer, with the cancel symbol taken out of the type.

```ts
type PromptGroupAwaitedReturn<T> = {
    [P in keyof T]: Exclude<Awaited<T[P]>, symbol>;
};
```