ink-cartridge 3.6.1

package/dist/cli/makeThemeType.d.ts

@@ -0,0 +1,43 @@
+interface ThemeFile {
+    /** Theme id from the file name (e.g. "dark"). */
+    id: string;
+    /** Flat key → value map (excluding 'id'). */
+    values: Record<string, string | boolean>;
+}
+export interface MakeThemeTypeOptions {
+    /** Directory containing {id}.json theme files. */
+    sourceDir: string;
+    /** Directory where the generated files will be written. */
+    outputDir: string;
+    /** Whether to re-generate on file changes. */
+    watch: boolean;
+    /** Debounce delay in milliseconds (default 500). */
+    debounceMs: number;
+    /** npm package name to import the original useTheme from. */
+    packageName: string;
+}
+/** Keys present in EVERY theme file. */
+export declare function findCommonKeys(files: ThemeFile[]): string[];
+/** Classify keys into color keys (string values) and style keys (boolean values). */
+export declare function classifyKeys(files: ThemeFile[], commonKeys: string[]): {
+    colorKeys: string[];
+    styleKeys: string[];
+};
+/** @internal Exported for testing only. */
+export declare function generateTypesContent(colorKeys: string[], styleKeys: string[]): string;
+/** @internal Exported for testing only. */
+export declare function generateRuntimeContent(packageName: string): string;
+/** @internal Exported for testing only. */
+export declare function escapeSingleQuote(s: string): string;
+/**
+ * Generate type-safe theme bindings from a directory of {id}.json theme files.
+ *
+ * Produces two files in {@link MakeThemeTypeOptions.outputDir}:
+ * - `theme-types.d.ts` — type declarations (ThemeColorKey, ThemeStyleKey, ThemeKey)
+ * - `theme.ts` — typed `useTheme()` hook
+ *
+ * In watch mode it re-generates whenever a .json file in sourceDir changes,
+ * debounced to avoid rapid rebuilds.
+ */
+export declare function makeThemeType(options: MakeThemeTypeOptions): void;
+export {};

package/dist/cli/makeThemeType.js

@@ -0,0 +1,222 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/* ------------------------------------------------------------------ */
+/*  File scanning                                                     */
+/* ------------------------------------------------------------------ */
+function scanThemeFiles(dirPath) {
+    const files = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dirPath);
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries.sort()) {
+        if (!entry.endsWith('.json'))
+            continue;
+        const id = entry.slice(0, -'.json'.length);
+        const fullPath = path.resolve(dirPath, entry);
+        try {
+            const raw = fs.readFileSync(fullPath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            const values = {};
+            for (const [k, v] of Object.entries(parsed)) {
+                if (k === 'id')
+                    continue;
+                if (typeof v === 'string' || typeof v === 'boolean') {
+                    values[k] = v;
+                }
+            }
+            files.push({ id, values });
+        }
+        catch {
+            process.stderr.write(`[ink-cartridge] Warning: failed to parse "${entry}" — skipped\n`);
+        }
+    }
+    return files;
+}
+/* ------------------------------------------------------------------ */
+/*  Key analysis                                                      */
+/* ------------------------------------------------------------------ */
+/** Keys present in EVERY theme file. */
+export function findCommonKeys(files) {
+    if (files.length === 0)
+        return [];
+    const keySets = files.map((f) => new Set(Object.keys(f.values)));
+    const common = new Set(keySets[0]);
+    for (let i = 1; i < keySets.length; i++) {
+        for (const key of common) {
+            if (!keySets[i].has(key))
+                common.delete(key);
+        }
+    }
+    return [...common].sort();
+}
+/** Classify keys into color keys (string values) and style keys (boolean values). */
+export function classifyKeys(files, commonKeys) {
+    const colorKeys = [];
+    const styleKeys = [];
+    for (const key of commonKeys) {
+        // Peek at the first file's value type
+        const val = files[0]?.values[key];
+        if (typeof val === 'boolean') {
+            styleKeys.push(key);
+        }
+        else {
+            // string or anything else → color
+            colorKeys.push(key);
+        }
+    }
+    return { colorKeys, styleKeys };
+}
+/* ------------------------------------------------------------------ */
+/*  Code generation                                                   */
+/* ------------------------------------------------------------------ */
+/** @internal Exported for testing only. */
+export function generateTypesContent(colorKeys, styleKeys) {
+    const lines = [
+        '// Auto-generated by ink-cartridge makeThemeType.',
+        '// Do not edit manually.',
+        '',
+    ];
+    // ThemeColorKey
+    if (colorKeys.length === 0) {
+        lines.push('export type ThemeColorKey = never;');
+    }
+    else {
+        lines.push('export type ThemeColorKey =');
+        for (let i = 0; i < colorKeys.length; i++) {
+            const delim = i < colorKeys.length - 1 ? '' : ';';
+            lines.push(`  | '${escapeSingleQuote(colorKeys[i])}'${delim}`);
+        }
+    }
+    lines.push('');
+    // ThemeStyleKey
+    if (styleKeys.length === 0) {
+        lines.push('export type ThemeStyleKey = never;');
+    }
+    else {
+        lines.push('export type ThemeStyleKey =');
+        for (let i = 0; i < styleKeys.length; i++) {
+            const delim = i < styleKeys.length - 1 ? '' : ';';
+            lines.push(`  | '${escapeSingleQuote(styleKeys[i])}'${delim}`);
+        }
+    }
+    lines.push('');
+    // Combined type
+    lines.push('/** Union of all theme keys (color + style). */');
+    lines.push('export type ThemeKey = ThemeColorKey | ThemeStyleKey;');
+    lines.push('');
+    return lines.join('\n');
+}
+/** @internal Exported for testing only. */
+export function generateRuntimeContent(packageName) {
+    return (`// Auto-generated by ink-cartridge makeThemeType.\n` +
+        `// Do not edit manually.\n` +
+        `\n` +
+        `import { useTheme as rawUseTheme } from '${escapeSingleQuote(packageName)}';\n` +
+        `import type { ThemeColorKey, ThemeStyleKey } from './theme-types.js';\n` +
+        `\n` +
+        `/**\n` +
+        ` * Typed theme hook. Drop-in replacement for the original \`useTheme\`.\n` +
+        ` *\n` +
+        ` * - \`color()\` only accepts keys classified as color values\n` +
+        ` * - \`style()\` only accepts keys classified as style (boolean) values\n` +
+        ` */\n` +
+        `export function useTheme(): Omit<ReturnType<typeof rawUseTheme>, 'color' | 'style'> & {\n` +
+        `  color: (key: ThemeColorKey) => string | undefined;\n` +
+        `  style: (key: ThemeStyleKey) => boolean | undefined;\n` +
+        `} {\n` +
+        `  const ctx = rawUseTheme();\n` +
+        `  return {\n` +
+        `    ...ctx,\n` +
+        `    color: (key: any) => ctx.color(key),\n` +
+        `    style: (key: any) => ctx.style(key),\n` +
+        `  };\n` +
+        `}\n`);
+}
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                            */
+/* ------------------------------------------------------------------ */
+/** @internal Exported for testing only. */
+export function escapeSingleQuote(s) {
+    return s.replace(/'/g, "\\'");
+}
+function writeOutput(outputDir, typesContent, runtimeContent) {
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.writeFileSync(path.join(outputDir, 'theme-types.d.ts'), typesContent, 'utf-8');
+    fs.writeFileSync(path.join(outputDir, 'theme.ts'), runtimeContent, 'utf-8');
+}
+/* ------------------------------------------------------------------ */
+/*  Public API                                                         */
+/* ------------------------------------------------------------------ */
+/**
+ * Generate type-safe theme bindings from a directory of {id}.json theme files.
+ *
+ * Produces two files in {@link MakeThemeTypeOptions.outputDir}:
+ * - `theme-types.d.ts` — type declarations (ThemeColorKey, ThemeStyleKey, ThemeKey)
+ * - `theme.ts` — typed `useTheme()` hook
+ *
+ * In watch mode it re-generates whenever a .json file in sourceDir changes,
+ * debounced to avoid rapid rebuilds.
+ */
+export function makeThemeType(options) {
+    const { sourceDir, outputDir, debounceMs } = options;
+    if (!fs.existsSync(sourceDir)) {
+        process.stderr.write(`[ink-cartridge] Error: source directory not found — "${sourceDir}"\n`);
+        process.exit(1);
+    }
+    generate(sourceDir, outputDir, options);
+    if (options.watch) {
+        let timer;
+        try {
+            fs.watch(sourceDir, (_eventType, filename) => {
+                if (!filename || !filename.endsWith('.json'))
+                    return;
+                if (timer)
+                    clearTimeout(timer);
+                timer = setTimeout(() => {
+                    process.stderr.write(`[ink-cartridge] Change detected in "${filename}", regenerating…\n`);
+                    generate(sourceDir, outputDir, options);
+                }, debounceMs);
+            });
+            process.stderr.write(`[ink-cartridge] Watching "${sourceDir}" for changes (debounce: ${debounceMs}ms)…\n`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[ink-cartridge] Error: watch mode failed — ${msg}\n`);
+            process.exit(1);
+        }
+    }
+}
+/* ------------------------------------------------------------------ */
+/*  Core generate function                                            */
+/* ------------------------------------------------------------------ */
+function generate(sourceDir, outputDir, options) {
+    const files = scanThemeFiles(sourceDir);
+    if (files.length === 0) {
+        process.stderr.write(`[ink-cartridge] Warning: no .json files found in "${sourceDir}"\n`);
+        const typesContent = generateTypesContent([], []);
+        const runtimeContent = generateRuntimeContent(options.packageName);
+        writeOutput(outputDir, typesContent, runtimeContent);
+        return;
+    }
+    const commonKeys = findCommonKeys(files);
+    const { colorKeys, styleKeys } = classifyKeys(files, commonKeys);
+    // Warn about keys not in all files
+    const allKeys = new Set();
+    for (const f of files)
+        for (const k of Object.keys(f.values))
+            allKeys.add(k);
+    for (const key of allKeys) {
+        if (!commonKeys.includes(key)) {
+            const missingIn = files.filter((f) => !(key in f.values)).map((f) => f.id);
+            process.stderr.write(`[ink-cartridge] Warning: key "${key}" is missing in [${missingIn.join(', ')}] — excluded from type\n`);
+        }
+    }
+    const typesContent = generateTypesContent(colorKeys, styleKeys);
+    const runtimeContent = generateRuntimeContent(options.packageName);
+    writeOutput(outputDir, typesContent, runtimeContent);
+    process.stderr.write(`[ink-cartridge] Generated ${colorKeys.length} color keys + ${styleKeys.length} style keys → ${path.resolve(outputDir)}\n`);
+}

package/dist/components/badge/Badge.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+interface BadgeProps {
+    children: string;
+    color?: string;
+}
+export declare function Badge({ children, color }: BadgeProps): React.JSX.Element;
+export {};

package/dist/components/badge/Badge.js

@@ -0,0 +1,9 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+export function Badge({ children, color = 'cyan' }) {
+    return (React.createElement(Box, { marginRight: 1 },
+        React.createElement(Text, { backgroundColor: color, color: "black" },
+            ' ',
+            children,
+            ' ')));
+}

package/dist/components/dialog/ConfirmDialog.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+import type { ConfirmDialogProps } from './types.js';
+/**
+ * A modal confirmation dialog with two buttons.
+ *
+ * Designed to be displayed via {@link overlay}:
+ *
+ * ```tsx
+ * registerComponent(ConfirmDialog, {});
+ * overlay(ConfirmDialog, {
+ *   title: 'delete',
+ *   message: 'continue?',
+ *   onConfirm: () => { deleteItem(); closeOverlay(); },
+ *   onCancel: () => closeOverlay(),
+ * });
+ * ```
+ *
+ * Keyboard:
+ * - Tab / Shift+Tab — switch between buttons
+ * - Enter — trigger focused button
+ * - Esc — cancel
+ */
+export declare function ConfirmDialog({ title, message, confirmLabel, cancelLabel, onConfirm, onCancel, }: ConfirmDialogProps): React.JSX.Element;

package/dist/components/dialog/ConfirmDialog.js

@@ -0,0 +1,57 @@
+import React, { useEffect, useRef } from 'react';
+import { Box, Text } from 'ink';
+import { useKeyboard, useFocusState } from '../../keyboard/hook.js';
+/**
+ * A modal confirmation dialog with two buttons.
+ *
+ * Designed to be displayed via {@link overlay}:
+ *
+ * ```tsx
+ * registerComponent(ConfirmDialog, {});
+ * overlay(ConfirmDialog, {
+ *   title: 'delete',
+ *   message: 'continue?',
+ *   onConfirm: () => { deleteItem(); closeOverlay(); },
+ *   onCancel: () => closeOverlay(),
+ * });
+ * ```
+ *
+ * Keyboard:
+ * - Tab / Shift+Tab — switch between buttons
+ * - Enter — trigger focused button
+ * - Esc — cancel
+ */
+export function ConfirmDialog({ title, message, confirmLabel = '确认', cancelLabel = '取消', onConfirm, onCancel, }) {
+    const { boundKeyboard, focusSet, focusUnregister } = useKeyboard();
+    const confirmFocused = useFocusState('dialog-confirm');
+    const cancelFocused = useFocusState('dialog-cancel');
+    // Keep stable refs so the keyboard effect doesn't capture stale callbacks
+    const onConfirmRef = useRef(onConfirm);
+    onConfirmRef.current = onConfirm;
+    const onCancelRef = useRef(onCancel);
+    onCancelRef.current = onCancel;
+    useEffect(() => {
+        // Esc 在任何按钮上都是取消（屏幕级绑定，不受 focus 影响）
+        const unEsc = boundKeyboard(['escape'], () => onCancelRef.current());
+        const unConfirm = boundKeyboard(['return'], () => onConfirmRef.current(), { focusId: 'dialog-confirm' });
+        const unCancel = boundKeyboard(['return'], () => onCancelRef.current(), { focusId: 'dialog-cancel' });
+        focusSet('dialog-confirm');
+        return () => {
+            unEsc();
+            unConfirm();
+            unCancel();
+            focusUnregister('dialog-confirm');
+            focusUnregister('dialog-cancel');
+        };
+    }, []);
+    return (React.createElement(Box, { flexDirection: "column", borderStyle: "round", borderColor: "yellow", paddingX: 2, paddingY: 1 },
+        React.createElement(Box, { marginBottom: 1 },
+            React.createElement(Text, { bold: true, color: "yellow" }, '⚠ ' + title)),
+        React.createElement(Box, { marginBottom: 1 },
+            React.createElement(Text, null, message)),
+        React.createElement(Box, { justifyContent: "flex-end", gap: 2 },
+            React.createElement(Box, null,
+                React.createElement(Text, { color: cancelFocused ? 'cyan' : 'grey', bold: cancelFocused, underline: cancelFocused }, cancelLabel)),
+            React.createElement(Box, null,
+                React.createElement(Text, { color: confirmFocused ? 'green' : 'grey', bold: confirmFocused, underline: confirmFocused }, confirmLabel)))));
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Props for the ConfirmDialog component.
+ *
+ * A modal confirmation dialog with two buttons (confirm / cancel),
+ * designed to be shown via the overlay system.
+ */
+export interface ConfirmDialogProps {
+    /** Dialog title, displayed prominently at the top. */
+    readonly title: string;
+    /** Body message explaining what the user is confirming. */
+    readonly message: string;
+    /** Label for the confirm (rightmost) button. @default "确认" */
+    readonly confirmLabel?: string;
+    /** Label for the cancel (left) button. @default "取消" */
+    readonly cancelLabel?: string;
+    /** Called when the user confirms (Enter on confirm button). */
+    readonly onConfirm: () => void;
+    /** Called when the user cancels (Enter on cancel button or Esc). */
+    readonly onCancel: () => void;
+}

package/dist/components/dialog/types.js

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

package/dist/components/divider/Divider.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+interface DividerProps {
+    label?: string;
+    char?: string;
+    width?: number;
+}
+export declare function Divider({ label, char, width }: DividerProps): React.JSX.Element;
+export {};

package/dist/components/divider/Divider.js

@@ -0,0 +1,10 @@
+import React from 'react';
+import { Text } from 'ink';
+export function Divider({ label, char = '─', width = 50 }) {
+    if (label) {
+        const side = Math.max(0, Math.floor((width - label.length - 2) / 2));
+        const line = char.repeat(side) + ` ${label} ` + char.repeat(side);
+        return React.createElement(Text, { dimColor: true }, line);
+    }
+    return React.createElement(Text, { dimColor: true }, char.repeat(width));
+}

package/dist/components/fold/Fold.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import type { FoldProps } from './types.js';
+export declare function Fold({ focusId, label, preview, children, expanded, onToggle, defaultExpanded, storage, storageKey, }: FoldProps): React.JSX.Element;

package/dist/components/fold/Fold.js

@@ -0,0 +1,44 @@
+import React, { useState, useEffect } from 'react';
+import { Box, Text } from 'ink';
+import { useKeyboard, useFocusState } from '../../keyboard/index.js';
+export function Fold({ focusId, label, preview, children, expanded, onToggle, defaultExpanded, storage, storageKey, }) {
+    const isControlled = expanded !== undefined;
+    const [internalExpanded, setInternal] = useState(defaultExpanded ?? false);
+    const isExpanded = isControlled ? expanded : internalExpanded;
+    const isFocused = useFocusState(focusId);
+    const { boundKeyboard, focusUnregister } = useKeyboard();
+    const persistKey = storageKey ?? `fold:${focusId}`;
+    useEffect(() => {
+        if (!storage)
+            return;
+        let cancelled = false;
+        storage.read.b(persistKey, defaultExpanded ?? false).then((v) => {
+            if (!cancelled)
+                setInternal(v);
+        });
+        return () => { cancelled = true; };
+    }, [storage, persistKey, defaultExpanded]);
+    const toggle = () => {
+        if (isControlled) {
+            onToggle?.();
+        }
+        else {
+            setInternal((prev) => {
+                const next = !prev;
+                storage?.write.b(persistKey, next);
+                return next;
+            });
+        }
+    };
+    useEffect(() => {
+        const unSpace = boundKeyboard([' '], () => toggle(), { focusId });
+        return () => { unSpace(); focusUnregister(focusId); };
+    }, [focusId]);
+    return (React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Box, null,
+            React.createElement(Text, { color: isFocused ? 'cyan' : 'grey' }, isExpanded ? '▼ ' : '▶ '),
+            React.createElement(Text, null, label)),
+        isExpanded
+            ? React.createElement(Box, null, children)
+            : (preview ? React.createElement(Box, null, preview) : null)));
+}

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

@@ -0,0 +1,28 @@
+import React from "react";
+import type { StorageAPI } from "../../storage/index.js";
+export interface FoldProps {
+    /** Focus target for the fold header bar. */
+    focusId: string;
+    /** Label shown on the header bar. */
+    label: string;
+    /** Optional preview content displayed when folded. */
+    preview?: React.ReactNode;
+    /** Content rendered when the fold is expanded. */
+    children: React.ReactNode;
+    /** Controlled: expanded state. */
+    expanded?: boolean;
+    /** Controlled: called when expand state is toggled. */
+    onToggle?: () => void;
+    /** Uncontrolled: initial expanded state. Defaults to false. */
+    defaultExpanded?: boolean;
+    /**
+     * Optional persistence instance. When provided, the expanded state is
+     * automatically saved and restored across sessions.
+     */
+    storage?: StorageAPI;
+    /**
+     * Storage key used for persistence. Defaults to `"fold:<focusId>"` when
+     * not provided.
+     */
+    storageKey?: string;
+}

package/dist/components/fold/types.js

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

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

@@ -0,0 +1,30 @@
+import React from 'react';
+import type { FieldProps } from './types.js';
+/**
+ * A single field in a {@link Form}.
+ *
+ * Uses the **render prop pattern** — children receives
+ * `{ value, error, onChange, focusId }` and returns the input component.
+ *
+ * Responsibilities:
+ * - Registers itself (name + rules + defaultValue + focusId) with Form on mount
+ * - Reads current value and error from Form context
+ * - Wraps `onChange` to call Form's `setFieldValue` (updates value + clears error)
+ * - Auto-generates `focusId` from `name` if not explicitly provided
+ * - Unregisters on unmount
+ *
+ * @example
+ * ```tsx
+ * <Field name="email" rules={[required]} defaultValue="">
+ *   {({ value, error, onChange, focusId }) => (
+ *     <TextInput
+ *       focusId={focusId}
+ *       value={value}
+ *       onChange={onChange}
+ *       placeholder="Email"
+ *     />
+ *   )}
+ * </Field>
+ * ```
+ */
+export declare function Field({ name, children, rules, defaultValue, focusId }: FieldProps): React.JSX.Element;

package/dist/components/form/Field.js

@@ -0,0 +1,59 @@
+import React, { useEffect, useCallback, useMemo } from 'react';
+import { useFormContext } from './context.js';
+/**
+ * A single field in a {@link Form}.
+ *
+ * Uses the **render prop pattern** — children receives
+ * `{ value, error, onChange, focusId }` and returns the input component.
+ *
+ * Responsibilities:
+ * - Registers itself (name + rules + defaultValue + focusId) with Form on mount
+ * - Reads current value and error from Form context
+ * - Wraps `onChange` to call Form's `setFieldValue` (updates value + clears error)
+ * - Auto-generates `focusId` from `name` if not explicitly provided
+ * - Unregisters on unmount
+ *
+ * @example
+ * ```tsx
+ * <Field name="email" rules={[required]} defaultValue="">
+ *   {({ value, error, onChange, focusId }) => (
+ *     <TextInput
+ *       focusId={focusId}
+ *       value={value}
+ *       onChange={onChange}
+ *       placeholder="Email"
+ *     />
+ *   )}
+ * </Field>
+ * ```
+ */
+export function Field({ name, children, rules, defaultValue, focusId }) {
+    const { values, errors, setFieldValue, registerField, unregisterField } = useFormContext();
+    /** Auto-generate focusId from field name if not explicitly provided. */
+    const effectiveFocusId = focusId ?? `${name}-field`;
+    /** Register field with Form on mount, unregister on unmount. */
+    useEffect(() => {
+        registerField(name, defaultValue, rules, effectiveFocusId);
+        return () => unregisterField(name);
+    }, [name, registerField, unregisterField]);
+    /**
+     * Stable onChange handler — calls Form's setFieldValue,
+     * which updates the value and clears any validation error.
+     */
+    const onChange = useCallback((value) => setFieldValue(name, value), [name, setFieldValue]);
+    /**
+     * Resolve the field value. If the Form has no value for this name yet
+     * (e.g. before the first render's registerField effect), fall back to
+     * the Field's own defaultValue. This avoids passing undefined to input
+     * components on the initial render.
+     */
+    const resolvedValue = values[name] !== undefined ? values[name] : (defaultValue ?? '');
+    /** Memoize the render props to avoid unnecessary re-renders. */
+    const fieldProps = useMemo(() => ({
+        value: resolvedValue,
+        error: errors[name],
+        onChange,
+        focusId: effectiveFocusId,
+    }), [resolvedValue, errors[name], onChange, effectiveFocusId]);
+    return React.createElement(React.Fragment, null, children(fieldProps));
+}

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

@@ -0,0 +1,32 @@
+import React from 'react';
+import type { FormProps } from './types.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 declare function Form({ children, onSubmit, onError, initialValues, submitRef }: FormProps): React.JSX.Element;