ink-cartridge 3.6.1

package/dist/components/form/Form.js

@@ -0,0 +1,163 @@
+import React, { useState, useCallback, useEffect, useRef } from 'react';
+import { FormContext } from './context.js';
+import { useKeyboard } from '../../keyboard/hook.js';
+/**
+ * Form container — manages field values, validation, and submission.
+ *
+ * Integrates with ink-cartridge's keyboard and focus system:
+ * - **Ctrl+Enter** triggers `submitForm()` (avoids conflicting with TextInput's Enter)
+ * - On validation failure, calls `focusSet()` on the first error field
+ *
+ * Must be used inside a `<KeyboardProvider>` for keyboard bindings to work.
+ *
+ * @example
+ * ```tsx
+ * <Form
+ *   initialValues={{ email: '', password: '' }}
+ *   onSubmit={(values) => handleLogin(values)}
+ *   onError={(errors) => console.log('Validation failed', errors)}
+ * >
+ *   <Field name="email" rules={[required, isEmail]}>
+ *     {({ value, onChange, error, focusId }) => (
+ *       <TextInput focusId={focusId} value={value} onChange={onChange} />
+ *     )}
+ *   </Field>
+ *   <Field name="password" rules={[required]}>
+ *     {({ value, onChange, error, focusId }) => (
+ *       <TextInput focusId={focusId} value={value} onChange={onChange} mask="*" />
+ *     )}
+ *   </Field>
+ * </Form>
+ * ```
+ */
+export function Form({ children, onSubmit, onError, initialValues = {}, submitRef }) {
+    const [values, setValues] = useState(initialValues);
+    const [errors, setErrors] = useState({});
+    // Holds the focusId of the first error field; consumed by useEffect to
+    // call focusSet() outside of render.
+    const [focusedErrorField, setFocusedErrorField] = useState(null);
+    // Refs to avoid stale closures in callbacks
+    const valuesRef = useRef(values);
+    valuesRef.current = values;
+    const rulesRef = useRef({});
+    const focusIdRef = useRef({});
+    const { focusSet, boundKeyboard } = useKeyboard();
+    /**
+     * Register a field's validation rules and default value.
+     *
+     * Does NOT set the default if the field already has a value
+     * (e.g. set via `initialValues`).
+     */
+    const registerField = useCallback((name, defaultValue, rules) => {
+        if (rules)
+            rulesRef.current[name] = rules;
+        if (defaultValue !== undefined && !(name in valuesRef.current)) {
+            setValues((prev) => {
+                if (name in prev)
+                    return prev;
+                return { ...prev, [name]: defaultValue };
+            });
+        }
+    }, []);
+    /** Unregister a field's rules and focusId mapping on unmount. */
+    const unregisterField = useCallback((name) => {
+        delete rulesRef.current[name];
+        delete focusIdRef.current[name];
+    }, []);
+    /**
+     * Update a single field's value and clear its validation error.
+     *
+     * Errors are cleared optimistically so the user sees immediate
+     * feedback that the error is being addressed.
+     */
+    const setFieldValue = useCallback((name, value) => {
+        setValues((prev) => ({ ...prev, [name]: value }));
+        setErrors((prev) => {
+            if (prev[name] === undefined)
+                return prev;
+            const next = { ...prev };
+            delete next[name];
+            return next;
+        });
+    }, []);
+    /**
+     * Run all registered validation rules and return the errors record.
+     * For each field, rules are evaluated in order — the first error wins.
+     */
+    const validate = useCallback(() => {
+        const currentValues = valuesRef.current;
+        const newErrors = {};
+        for (const [name, validators] of Object.entries(rulesRef.current)) {
+            for (const fn of validators) {
+                const error = fn(currentValues[name], currentValues);
+                if (error) {
+                    newErrors[name] = error;
+                    break;
+                }
+            }
+        }
+        return newErrors;
+    }, []);
+    /**
+     * Validate all fields, then either:
+     * 1. On error — persist errors, call `onError`, focus first error field
+     * 2. On success — call `onSubmit` with current values
+     */
+    const submitForm = useCallback(() => {
+        const validationErrors = validate();
+        setErrors(validationErrors);
+        const hasErrors = Object.values(validationErrors).some(Boolean);
+        if (hasErrors) {
+            onError?.(validationErrors);
+            const firstError = Object.keys(validationErrors)[0];
+            const targetFocusId = focusIdRef.current[firstError];
+            if (targetFocusId) {
+                setFocusedErrorField(targetFocusId);
+            }
+            return;
+        }
+        onSubmit(valuesRef.current);
+    }, [validate, onSubmit, onError]);
+    // Stable ref so the boundKeyboard effect always calls the latest submitForm
+    const submitFormRef = useRef(submitForm);
+    submitFormRef.current = submitForm;
+    // Defer focusSet to avoid calling it inside render
+    useEffect(() => {
+        if (focusedErrorField) {
+            focusSet(focusedErrorField);
+            setFocusedErrorField(null);
+        }
+    }, [focusedErrorField, focusSet]);
+    // Expose submitForm via submitRef prop
+    useEffect(() => {
+        if (submitRef)
+            submitRef.current = submitForm;
+    }, [submitForm, submitRef]);
+    // Bind Ctrl+S to submit via screen-level binding. Focus-target bindings
+    // (TextInput's '*' wildcard) do NOT match Ctrl+S (isNormalCharacter
+    // returns false when ctrl is set), so the event safely passes through
+    // to the screen level without needing globalKeys.
+    useEffect(() => {
+        const unBind = boundKeyboard(['ctrl+s'], () => submitFormRef.current());
+        return () => unBind();
+    }, [boundKeyboard]);
+    /**
+     * Wrapper around registerField that also stores the field's focusId
+     * for error focus navigation.
+     */
+    const registerFieldWithFocus = useCallback((name, defaultValue, rules, focusId) => {
+        registerField(name, defaultValue, rules);
+        if (focusId) {
+            focusIdRef.current[name] = focusId;
+        }
+    }, [registerField]);
+    const contextValue = {
+        values,
+        errors,
+        setFieldValue,
+        registerField: registerFieldWithFocus,
+        unregisterField,
+        submitForm,
+    };
+    return (React.createElement(FormContext.Provider, { value: contextValue }, children));
+}

package/dist/components/form/context.d.ts

@@ -0,0 +1,14 @@
+import type { FormContextValue } from './types.js';
+/**
+ * React Context that carries form state ({@link FormContextValue}).
+ * Provided by {@link Form} and consumed by {@link Field}.
+ *
+ * @internal
+ */
+export declare const FormContext: import("react").Context<FormContextValue | null>;
+/**
+ * Access the form context from within a {@link Field} component.
+ *
+ * @throws If called outside of a {@link Form} provider.
+ */
+export declare function useFormContext(): FormContextValue;

package/dist/components/form/context.js

@@ -0,0 +1,20 @@
+import { createContext, useContext } from 'react';
+/**
+ * React Context that carries form state ({@link FormContextValue}).
+ * Provided by {@link Form} and consumed by {@link Field}.
+ *
+ * @internal
+ */
+export const FormContext = createContext(null);
+/**
+ * Access the form context from within a {@link Field} component.
+ *
+ * @throws If called outside of a {@link Form} provider.
+ */
+export function useFormContext() {
+    const ctx = useContext(FormContext);
+    if (!ctx) {
+        throw new Error('[Ink-Cartridge] useFormContext() must be used inside a <Form> component.');
+    }
+    return ctx;
+}

package/dist/components/form/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Validation function.
+ * Takes the field's current value and all form values, returns an error
+ * message string if invalid, or `undefined` if valid.
+ *
+ * @param value   The current value of the field being validated.
+ * @param values  All form values (useful for cross-field validation).
+ * @returns Error message, or undefined if valid.
+ */
+export type Validator = (value: any, values: Record<string, any>) => string | undefined;
+/**
+ * Value provided by {@link Form} via {@link FormContext}.
+ */
+export interface FormContextValue {
+    /** Current values of all registered fields. */
+    values: Record<string, any>;
+    /** Current validation errors. `undefined` means the field is valid. */
+    errors: Record<string, string | undefined>;
+    /**
+     * Update a single field's value and clear its error.
+     * Called by {@link Field} when the user changes input.
+     */
+    setFieldValue: (name: string, value: any) => void;
+    /**
+     * Register a field with the form.
+     * Called by {@link Field} on mount.
+     *
+     * @param name         Field name (unique within the form).
+     * @param defaultValue Initial value if the form has no value for this name yet.
+     * @param rules        Validation rules applied on submit.
+     * @param focusId      The focus target ID for this field's input, used by Form
+     *                     to focus the first error field on submit failure.
+     */
+    registerField: (name: string, defaultValue?: any, rules?: Validator[], focusId?: string) => void;
+    /** Unregister a field on unmount. */
+    unregisterField: (name: string) => void;
+    /** Trigger validation and submit. Bound to Enter key by Form. */
+    submitForm: () => void;
+}
+/**
+ * Props for the {@link Form} component.
+ */
+export interface FormProps {
+    /** Form body containing {@link Field} components. */
+    children: React.ReactNode;
+    /**
+     * Called when validation passes and the form is submitted.
+     * Receives all field values as a record.
+     */
+    onSubmit: (values: Record<string, any>) => void;
+    /**
+     * Called when validation fails on submit.
+     * Receives the errors record (field name → error message).
+     */
+    onError?: (errors: Record<string, string | undefined>) => void;
+    /** Initial values for fields. Overrides Field-level `defaultValue`. */
+    initialValues?: Record<string, any>;
+    /**
+     * Mutable ref that receives the `submitForm` function after mount.
+     * Useful for programmatic submission in tests or non-keyboard flows.
+     */
+    submitRef?: React.MutableRefObject<(() => void) | undefined>;
+}
+/**
+ * Props passed to the render child of {@link Field}.
+ */
+export interface FieldRenderProps {
+    /** Current value of this field (from Form state). */
+    value: any;
+    /** Current validation error for this field, or undefined. */
+    error: string | undefined;
+    /**
+     * Call this when the user changes input.
+     * Handles calling Form's `setFieldValue` and clearing errors.
+     */
+    onChange: (value: any) => void;
+    /**
+     * The focus target ID for this field's input component.
+     * Pass to the child component's `focusId` prop.
+     */
+    focusId: string;
+}
+/**
+ * Props for the {@link Field} component.
+ */
+export interface FieldProps {
+    /** Unique field name. Used as the key in Form's `values` and `errors`. */
+    name: string;
+    /**
+     * Render function receiving {@link FieldRenderProps}.
+     * Returns the actual input component (TextInput, NumberInput, etc.).
+     *
+     * @example
+     * ```tsx
+     * <Field name="email" rules={[required]}>
+     *   {({ value, onChange, error, focusId }) => (
+     *     <TextInput focusId={focusId} value={value} onChange={onChange} />
+     *   )}
+     * </Field>
+     * ```
+     */
+    children: (fieldProps: FieldRenderProps) => React.ReactNode;
+    /** Validation rules evaluated on submit, in order. First match wins. */
+    rules?: Validator[];
+    /**
+     * Default value for this field, used only on initial mount if not
+     * already set via Form's `initialValues`.
+     */
+    defaultValue?: any;
+    /**
+     * Override the auto-generated focusId (`${name}-field`).
+     * Useful when the same input name is used on different screens.
+     */
+    focusId?: string;
+}

package/dist/components/form/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/key-hint/KeyHint.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+interface HintEntry {
+    key: string;
+    desc: string;
+}
+interface KeyHintProps {
+    keys: HintEntry[];
+}
+export declare function KeyHint({ keys }: KeyHintProps): React.JSX.Element;
+export {};

package/dist/components/key-hint/KeyHint.js

@@ -0,0 +1,12 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+export function KeyHint({ keys = [] }) {
+    return (React.createElement(Box, { gap: 2 }, keys.map(({ key, desc }) => (React.createElement(Box, { key: key },
+        React.createElement(Text, { color: "yellow" },
+            "[",
+            key,
+            "]"),
+        React.createElement(Text, { dimColor: true },
+            " ",
+            desc))))));
+}

package/dist/components/multi-select/MultiSelectInput.d.ts

@@ -0,0 +1,125 @@
+import React from 'react';
+import type { MultiSelectInputProps, Item } from './types.js';
+/**
+ * Multi-select list component integrated with the ink-cartridge keyboard and
+ * focus system.
+ *
+ * Users navigate with arrow keys (or vim-style j/k), toggle items with
+ * Space, and confirm with Enter. Number keys 1-9 toggle the corresponding
+ * visible item directly.
+ *
+ * When the component is not the active focus target, its highlight is
+ * hidden but selection checkboxes remain visible.
+ *
+ * Supports both **controlled** (`selected` prop) and **uncontrolled**
+ * (`defaultSelected` prop) usage.
+ *
+ * @typeParam T - The type of the value associated with each item.
+ * @typeParam I - The extended item type, must extend Item<T>.
+ *                 Defaults to Item<T>.
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled
+ * <MultiSelectInput
+ *   focusId="colors"
+ *   items={[
+ *     { label: 'Red',  value: 'red' },
+ *     { label: 'Blue', value: 'blue' },
+ *   ]}
+ *   defaultSelected={['red']}
+ *   onSubmit={(vals) => console.log('Confirmed:', vals)}
+ * />
+ *
+ * // Controlled
+ * const [sel, setSel] = useState<string[]>([]);
+ * <MultiSelectInput
+ *   focusId="colors"
+ *   items={items}
+ *   selected={sel}
+ *   onChange={setSel}
+ * />
+ * ```
+ */
+export declare function MultiSelectInput<T, I extends Item<T> = Item<T>>({ items, selected: controlledSelected, defaultSelected, onChange, onSubmit, onSelect, onUnselect, onHighlight, indicatorComponent, checkboxComponent, itemComponent, focusId, limit: limitProp, initialIndex, storage, storageKey, }: MultiSelectInputProps<T, I>): React.FunctionComponentElement<{
+    readonly position?: "absolute" | "relative" | "static" | undefined;
+    readonly top?: number | string | undefined;
+    readonly right?: number | string | undefined;
+    readonly bottom?: number | string | undefined;
+    readonly left?: number | string | undefined;
+    readonly columnGap?: number | undefined;
+    readonly rowGap?: number | undefined;
+    readonly gap?: number | undefined;
+    readonly margin?: number | undefined;
+    readonly marginX?: number | undefined;
+    readonly marginY?: number | undefined;
+    readonly marginTop?: number | undefined;
+    readonly marginBottom?: number | undefined;
+    readonly marginLeft?: number | undefined;
+    readonly marginRight?: number | undefined;
+    readonly padding?: number | undefined;
+    readonly paddingX?: number | undefined;
+    readonly paddingY?: number | undefined;
+    readonly paddingTop?: number | undefined;
+    readonly paddingBottom?: number | undefined;
+    readonly paddingLeft?: number | undefined;
+    readonly paddingRight?: number | undefined;
+    readonly flexGrow?: number | undefined;
+    readonly flexShrink?: number | undefined;
+    readonly flexDirection?: "row" | "column" | "row-reverse" | "column-reverse" | undefined;
+    readonly flexBasis?: number | string | undefined;
+    readonly flexWrap?: "nowrap" | "wrap" | "wrap-reverse" | undefined;
+    readonly alignItems?: "flex-start" | "center" | "flex-end" | "stretch" | "baseline" | undefined;
+    readonly alignSelf?: "flex-start" | "center" | "flex-end" | "auto" | "stretch" | "baseline" | undefined;
+    readonly alignContent?: "flex-start" | "flex-end" | "center" | "stretch" | "space-between" | "space-around" | "space-evenly" | undefined;
+    readonly justifyContent?: "flex-start" | "flex-end" | "space-between" | "space-around" | "space-evenly" | "center" | undefined;
+    readonly width?: number | string | undefined;
+    readonly height?: number | string | undefined;
+    readonly minWidth?: number | string | undefined;
+    readonly minHeight?: number | string | undefined;
+    readonly maxWidth?: number | string | undefined;
+    readonly maxHeight?: number | string | undefined;
+    readonly aspectRatio?: number | undefined;
+    readonly display?: "flex" | "none" | undefined;
+    readonly borderStyle?: (keyof import("cli-boxes").Boxes | import("cli-boxes").BoxStyle) | undefined;
+    readonly borderTop?: boolean | undefined;
+    readonly borderBottom?: boolean | undefined;
+    readonly borderLeft?: boolean | undefined;
+    readonly borderRight?: boolean | undefined;
+    readonly borderColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
+    readonly borderTopColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
+    readonly borderBottomColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
+    readonly borderLeftColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
+    readonly borderRightColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
+    readonly borderDimColor?: boolean | undefined;
+    readonly borderTopDimColor?: boolean | undefined;
+    readonly borderBottomDimColor?: boolean | undefined;
+    readonly borderLeftDimColor?: boolean | undefined;
+    readonly borderRightDimColor?: boolean | undefined;
+    readonly borderBackgroundColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
+    readonly borderTopBackgroundColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
+    readonly borderBottomBackgroundColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
+    readonly borderLeftBackgroundColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
+    readonly borderRightBackgroundColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
+    readonly overflow?: "visible" | "hidden" | undefined;
+    readonly overflowX?: "visible" | "hidden" | undefined;
+    readonly overflowY?: "visible" | "hidden" | undefined;
+    readonly backgroundColor?: import("type-fest").LiteralUnion<import("ansi-styles").ForegroundColorName, string> | undefined;
+} & {
+    readonly 'aria-label'?: string;
+    readonly 'aria-hidden'?: boolean;
+    readonly 'aria-role'?: "button" | "checkbox" | "combobox" | "list" | "listbox" | "listitem" | "menu" | "menuitem" | "option" | "progressbar" | "radio" | "radiogroup" | "tab" | "tablist" | "table" | "textbox" | "timer" | "toolbar";
+    readonly 'aria-state'?: {
+        readonly busy?: boolean;
+        readonly checked?: boolean;
+        readonly disabled?: boolean;
+        readonly expanded?: boolean;
+        readonly multiline?: boolean;
+        readonly multiselectable?: boolean;
+        readonly readonly?: boolean;
+        readonly required?: boolean;
+        readonly selected?: boolean;
+    };
+} & {
+    children?: React.ReactNode | undefined;
+} & React.RefAttributes<import("ink").DOMElement>>;