or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-selection.mdbase-prompt.mdconfirmation.mdindex.mdselection.mdtext-input.mdutilities.md
tile.json

tessl/npm-clack--core

Low-level primitives for building command-line interface applications with customizable prompt components.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@clack/core@0.5.x

To install, run

npx @tessl/cli install tessl/npm-clack--core@0.5.0

index.mddocs/

Clack Core

Clack Core provides low-level primitives for building command-line interface applications in Node.js. It offers a collection of customizable prompt components including TextPrompt, SelectPrompt, ConfirmPrompt, MultiSelectPrompt, and GroupMultiSelectPrompt, all built around a base Prompt class that accepts render functions for maximum flexibility.

Package Information

  • Package Name: @clack/core
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @clack/core

Core Imports

import { 
  Prompt, 
  TextPrompt, 
  SelectPrompt, 
  ConfirmPrompt,
  MultiSelectPrompt,
  GroupMultiSelectPrompt,
  PasswordPrompt,
  SelectKeyPrompt,
  isCancel,
  block,
  updateSettings,
  type State
} from "@clack/core";

For CommonJS:

const { 
  Prompt, 
  TextPrompt, 
  SelectPrompt, 
  ConfirmPrompt,
  isCancel 
} = require("@clack/core");

Basic Usage

import { TextPrompt, isCancel } from '@clack/core';

const p = new TextPrompt({
  render() {
    return `What's your name?\n${this.valueWithCursor}`;
  },
});

const name = await p.prompt();
if (isCancel(name)) {
  process.exit(0);
}

Architecture

Clack Core is built around several key components:

  • Base Prompt Class: Foundation class providing common functionality for all prompts
  • Prompt Implementations: Specialized prompt types for different input scenarios
  • Event System: Event-driven architecture for state management and user interaction
  • Render Functions: Customizable rendering system where each prompt accepts a render function
  • Utility Functions: Helper functions for cancellation handling and terminal control
  • Settings System: Global configuration for key bindings and behavior

Capabilities

Base Prompt System

Core prompt functionality providing the foundation for all prompt types. Includes event handling, state management, and the base prompt lifecycle.

class Prompt<T = any> {
  constructor(options: PromptOptions<Prompt>, trackValue?: boolean);
  
  state: State;
  error: string;
  value: T;
  
  prompt(): Promise<string | symbol>;
  on<K extends keyof ClackEvents>(event: K, cb: ClackEvents[K]): void;
  once<K extends keyof ClackEvents>(event: K, cb: ClackEvents[K]): void;
  emit<K extends keyof ClackEvents>(event: K, ...data: Parameters<ClackEvents[K]>): void;
}

interface PromptOptions<Self> {
  render(this: Omit<Self, 'prompt'>): string | undefined;
  placeholder?: string;
  initialValue?: any;
  validate?: (value: any) => string | Error | undefined;
  input?: Readable;
  output?: Writable;
  debug?: boolean;
  signal?: AbortSignal;
}

type State = 'initial' | 'active' | 'cancel' | 'submit' | 'error';

Base Prompt System

Text Input Prompts

Text input functionality for collecting single-line and password input from users.

class TextPrompt extends Prompt<string> {
  constructor(opts: TextOptions);
  
  valueWithCursor: string;
  cursor: number;
}

class PasswordPrompt extends Prompt<string> {
  constructor(opts: PasswordOptions);
  
  valueWithCursor: string;
  cursor: number;
  masked: any;
}

interface TextOptions extends PromptOptions<TextPrompt> {
  placeholder?: string;
  defaultValue?: string;
}

interface PasswordOptions extends PromptOptions<PasswordPrompt> {
  mask?: string;
}

Text Input Prompts

Selection Prompts

Selection functionality for single and multiple choice scenarios from lists of options.

class SelectPrompt<T extends { value: any }> extends Prompt<T['value']> {
  constructor(opts: SelectOptions<T>);
  
  options: T[];
  cursor: number;
}

class MultiSelectPrompt<T extends { value: any }> extends Prompt<T['value'][]> {
  constructor(opts: MultiSelectOptions<T>);
  
  options: T[];
  cursor: number;
}

class SelectKeyPrompt<T extends { value: any }> extends Prompt<T['value']> {
  constructor(opts: SelectKeyOptions<T>);
  
  options: T[];
  cursor: number;
}

Selection Prompts

Confirmation Prompts

Simple yes/no confirmation functionality for binary choices.

class ConfirmPrompt extends Prompt<boolean> {
  constructor(opts: ConfirmOptions);
  
  cursor: 0 | 1;
}

interface ConfirmOptions extends PromptOptions<ConfirmPrompt> {
  active: string;
  inactive: string;
  initialValue?: boolean;
}

Confirmation Prompts

Advanced Selection

Advanced selection functionality including grouped multi-select options with hierarchical organization.

class GroupMultiSelectPrompt<T extends { value: any }> extends Prompt<T['value'][]> {
  constructor(opts: GroupMultiSelectOptions<T>);
  
  options: (T & { group: string | boolean })[];
  cursor: number;
  
  getGroupItems(group: string): T[];
  isGroupSelected(group: string): boolean;
}

Advanced Selection

Utility Functions

Helper functions for cancellation handling, terminal control, and settings management.

function isCancel(value: unknown): value is symbol;
function block(options?: {
  input?: NodeJS.ReadStream & { fd: 0 };
  output?: NodeJS.WriteStream & { fd: 1 };
  overwrite?: boolean;
  hideCursor?: boolean;
}): () => void;
function updateSettings(updates: ClackSettings): void;

interface ClackSettings {
  aliases?: Record<string, Action>;
}

type Action = 'up' | 'down' | 'left' | 'right' | 'space' | 'enter' | 'cancel';

Utility Functions

Types

interface ClackEvents {
  initial: (value?: any) => void;
  active: (value?: any) => void;
  cancel: (value?: any) => void;
  submit: (value?: any) => void;
  error: (value?: any) => void;
  cursor: (key?: Action) => void;
  key: (key?: string) => void;
  value: (value?: string) => void;
  confirm: (value?: boolean) => void;
  finalize: () => void;
}