Summary

Adds an optional onCancel callback to all prompt functions via CommonOptions. When the user cancels a prompt (Ctrl+C or Escape), the callback is invoked — eliminating the need for isCancel guards at every call site. When onCancel is provided, the return type narrows from Promise<T | symbol> to Promise<T>.

Closes #83

Motivation

Every clack user repeats this pattern:

const result = await confirm({ message: "Continue?" });
if (isCancel(result)) {
  cancel("Operation cancelled.");
  process.exit(0);
}

This PR makes it:

const result = await confirm({
  message: "Continue?",
  onCancel: () => {
    cancel("Operation cancelled.");
    process.exit(0);
  },
});
// result is `boolean` — no isCancel guard needed

Changes

• CommonOptions — added onCancel?: () => void
• handleCancel utility — exported from @clack/prompts for custom prompt implementations
• All 12 prompt functions — converted to function declarations with overloads for return type narrowing
• Tests — runtime tests for cancel behavior + compile-time type narrowing tests

Type narrowing

Each prompt uses function overloads so TypeScript narrows the return type when onCancel is present:

// Without onCancel: result is boolean | symbol
const a = await confirm({ message: "Continue?" });
//    ^? boolean | symbol

// With onCancel: result is boolean (narrowed)
const b = await confirm({ message: "Continue?", onCancel: () => { process.exit(0); } });
//    ^? boolean

This works for all prompts: text, confirm, select, multiselect, groupMultiselect, password, autocomplete, autocompleteMultiselect, selectKey, date, multiline, path.

Design decisions

• Additive, no breaking changes — onCancel is optional; existing code works unchanged
• Function overloads for narrowing — the idiomatic TypeScript pattern; converts export const arrows to export function declarations
• handleCancel is exported — useful for custom prompt implementations

Test plan

• All 727 existing + new tests pass
• pnpm run build succeeds
• pnpm run types succeeds
• pnpm run lint succeeds
• pnpm run format succeeds
• Type narrowing verified via compile-time assertions (@ts-expect-error)