@teactjs/telegram 0.1.0-alpha.1

package/dist/runtime/src/auth-session.d.ts

@@ -0,0 +1,51 @@
+/** Shape of auth data stored in the session. */
+export interface AuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+}
+/** Return value of `useAuthSession`. */
+export interface AuthSessionState {
+    /** Whether the user is currently authenticated (has a non-expired access token). */
+    isAuthenticated: boolean;
+    /** The current access token, or `null` if not logged in. */
+    accessToken: string | null;
+    /** The current refresh token, or `null`. */
+    refreshToken: string | null;
+    /** Expiry timestamp (ms since epoch), or `null`. */
+    expiresAt: number | null;
+    /** Store auth tokens. Marks the session as authenticated. */
+    login(tokens: AuthTokens): void;
+    /** Clear all auth data. */
+    logout(): void;
+    /** Update the access token (e.g. after a refresh). */
+    setAccessToken(token: string, expiresAt?: number): void;
+}
+/**
+ * Token-based auth session hook.
+ *
+ * Stores `accessToken`, `refreshToken`, and `expiresAt` inside the
+ * per-chat session (backed by whatever `SessionStore` you configured —
+ * memory, file, or custom).
+ *
+ * @example
+ * ```tsx
+ * const auth = useAuthSession();
+ *
+ * if (!auth.isAuthenticated) {
+ *   return (
+ *     <Message text="Please log in">
+ *       <InlineKeyboard>
+ *         <ButtonRow>
+ *           <Button text="Login" onClick={() => auth.login({ accessToken: 'tok_abc' })} />
+ *         </ButtonRow>
+ *       </InlineKeyboard>
+ *     </Message>
+ *   );
+ * }
+ *
+ * return <Message text={`Logged in! Token: ${auth.accessToken}`} />;
+ * ```
+ */
+export declare function useAuthSession(): AuthSessionState;
+//# sourceMappingURL=auth-session.d.ts.map

package/dist/runtime/src/auth-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-session.d.ts","sourceRoot":"","sources":["../../../../runtime/src/auth-session.ts"],"names":[],"mappings":"AAGA,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,oFAAoF;IACpF,eAAe,EAAE,OAAO,CAAC;IACzB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,4CAA4C;IAC5C,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,oDAAoD;IACpD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,6DAA6D;IAC7D,KAAK,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,2BAA2B;IAC3B,MAAM,IAAI,IAAI,CAAC;IACf,sDAAsD;IACtD,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzD;AAID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,IAAI,gBAAgB,CA+BjD"}

package/dist/runtime/src/auth.d.ts

@@ -0,0 +1,37 @@
+import type { TeactPlugin } from './plugin';
+export interface AuthConfig {
+    /** Telegram user IDs with admin access. Admins implicitly have all roles. */
+    admins?: (string | number)[];
+    /** Named roles mapped to arrays of user IDs. */
+    roles?: Record<string, (string | number)[]>;
+}
+export interface AuthState {
+    userId: string;
+    isAdmin: boolean;
+    /** The user's highest role, or null if none. */
+    role: string | null;
+    /** Check if the current user has a specific role. Admins pass all checks. */
+    is(role: string): boolean;
+    /** Check if the current user has at least one of the given roles. */
+    hasAny(...roles: string[]): boolean;
+}
+/**
+ * Access the current user's auth state.
+ * Requires `authPlugin()` to be registered.
+ *
+ * @example
+ * const { isAdmin, is } = useAuth();
+ * if (!is('moderator')) return <Message text="Access denied" />;
+ */
+export declare function useAuth(): AuthState;
+/**
+ * Role-based auth plugin.
+ *
+ * @example
+ * authPlugin({
+ *   admins: [123456789],
+ *   roles: { moderator: [987654321, 111222333] },
+ * })
+ */
+export declare function authPlugin(config?: AuthConfig): TeactPlugin;
+//# sourceMappingURL=auth.d.ts.map

package/dist/runtime/src/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../../runtime/src/auth.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC7B,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,6EAA6E;IAC7E,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,qEAAqE;IACrE,MAAM,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;CACrC;AAID;;;;;;;GAOG;AACH,wBAAgB,OAAO,IAAI,SAAS,CAInC;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,MAAM,GAAE,UAAe,GAAG,WAAW,CA6C/D"}

package/dist/runtime/src/bot.d.ts

@@ -0,0 +1,143 @@
+import type { FunctionComponent, ReactNode } from 'react';
+import { type TeactRoot, type SessionStore, type Middleware } from '@teactjs/renderer';
+import { TelegramAdapter } from '@teactjs/telegram';
+import { type CallbackMap } from '@teactjs/react';
+import { type RouterConfig, type CommitModeRef } from './router';
+import type { TeactPlugin } from './plugin';
+/** A button in an inline keyboard sent via {@link CommandContext.reply}. */
+export interface ReplyButton {
+    text: string;
+    url?: string;
+    route?: string;
+}
+/** A button in a custom reply keyboard sent via {@link CommandContext.reply}. */
+export interface ReplyKeyboardButton {
+    text: string;
+    requestContact?: boolean;
+    requestLocation?: boolean;
+}
+/** Options for {@link CommandContext.reply}. */
+export interface ReplyOptions {
+    /** Inline keyboard rows. */
+    buttons?: ReplyButton[][];
+    /** Custom reply keyboard rows. */
+    replyKeyboard?: ReplyKeyboardButton[][];
+}
+/** Context object passed to command handlers defined in `commands`. */
+export interface CommandContext {
+    args: string[];
+    reply: (text: string, options?: ReplyOptions) => Promise<void>;
+    chatId: string;
+    user: {
+        id: string;
+        username?: string;
+        firstName?: string;
+    };
+    platform: string;
+    raw: any;
+}
+/**
+ * Definition of a bot command registered via `createBot({ commands })`.
+ *
+ * @example
+ * const commands = {
+ *   start: { description: 'Start the bot', route: '/' },
+ *   help:  { description: 'Show help', handler: 'Use /start to begin.' },
+ *   echo:  { description: 'Echo args', handler: async (ctx) => ctx.reply(ctx.args.join(' ')) },
+ * };
+ */
+export interface CommandDef {
+    description: string;
+    /** A static string reply, or an async handler function. */
+    handler?: string | ((ctx: CommandContext) => Promise<void> | void);
+    /** Route to navigate to when the command is triggered. */
+    route?: string;
+    /** Resolve deep-link parameters (e.g. `/start payload`) into a route path. */
+    deepLink?: (args: string[]) => string;
+}
+/** Webhook server configuration for production deployments. */
+export interface WebhookConfig {
+    domain: string;
+    port?: number;
+    path?: string;
+    secretToken?: string;
+}
+/**
+ * Options for {@link createBot}.
+ *
+ * @example
+ * createBot({
+ *   adapter: new TelegramAdapter(),
+ *   router: createRouter({ '/': Home }),
+ *   commands: { start: { description: 'Start', route: '/' } },
+ * });
+ */
+export interface CreateBotOptions {
+    component?: FunctionComponent<any>;
+    router?: RouterConfig;
+    providers?: FunctionComponent<{
+        children: ReactNode;
+    }>;
+    adapter: TelegramAdapter;
+    token?: string;
+    /** @default 'polling' — overrides teact.config */
+    mode?: 'polling' | 'webhook';
+    /** Webhook configuration — overrides teact.config */
+    webhook?: WebhookConfig;
+    session?: {
+        store?: SessionStore;
+        ttl?: number;
+    };
+    /** Additional middleware — merged with teact.config middleware */
+    middleware?: Middleware[];
+    /** Additional plugins — merged with teact.config plugins */
+    plugins?: TeactPlugin[];
+    /** Bot commands (stays in the React/app layer, not in config) */
+    commands?: Record<string, CommandDef>;
+    /** Experimental feature flags for opt-in features. */
+    experimental?: Record<string, unknown>;
+    /**
+     * Enable verbose debug logging.
+     * Logs every incoming update, render cycle, middleware execution, and errors
+     * with timestamps so you can diagnose stuck bots or unexpected behavior.
+     * @default false
+     */
+    debug?: boolean;
+}
+interface ChatRoot {
+    root: TeactRoot;
+    handlers: CallbackMap;
+    chatId: string;
+    lastMessageId?: number;
+    commitQueue: Promise<void>;
+    commitMode: CommitModeRef;
+}
+/**
+ * Create and configure a Teact bot instance.
+ *
+ * Provide either a `component` (single-page) or a `router` (multi-page) for the UI.
+ * Call `.start()` on the returned object to connect and begin processing updates.
+ *
+ * @param options - Bot configuration including adapter, component/router, commands, and plugins.
+ * @returns A bot instance with `start()` and `stop()` methods.
+ *
+ * @example
+ * const bot = createBot({
+ *   adapter: new TelegramAdapter(),
+ *   router: createRouter({ '/': Home, '/settings': Settings }),
+ *   commands: {
+ *     start: { description: 'Start the bot', route: '/' },
+ *     settings: { description: 'Open settings', route: '/settings' },
+ *   },
+ * });
+ *
+ * bot.start();
+ */
+export declare function createBot(options: CreateBotOptions): {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    _chatRoots: Map<string, ChatRoot>;
+    _sessionStore: SessionStore;
+};
+export {};
+//# sourceMappingURL=bot.d.ts.map

package/dist/runtime/src/bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../../../../runtime/src/bot.ts"],"names":[],"mappings":"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"}

package/dist/runtime/src/config.d.ts

@@ -0,0 +1,38 @@
+import type { TeactPlugin } from './plugin';
+import type { WebhookConfig } from './bot';
+import type { Middleware, SessionStore } from '@teactjs/renderer';
+/**
+ * Infrastructure configuration for `teact.config.ts`.
+ * Commands and app logic belong in `createBot()` — this is for deployment settings only.
+ */
+export interface TeactConfig {
+    /** Transport mode. @default 'polling' */
+    mode?: 'polling' | 'webhook';
+    /** Webhook server settings (required when `mode` is `'webhook'`). */
+    webhook?: WebhookConfig;
+    /** Plugins loaded at startup (e.g. `storagePlugin()`, `authPlugin()`). */
+    plugins?: TeactPlugin[];
+    /** Global middleware that runs on every update. */
+    middleware?: Middleware[];
+    /** Session store override and TTL. */
+    session?: {
+        store?: SessionStore;
+        ttl?: number;
+    };
+}
+/**
+ * Type-safe config helper for `teact.config.ts`.
+ * Infrastructure-only — commands live in createBot() on the React side.
+ *
+ * @example
+ * // teact.config.ts
+ * import { defineConfig } from '@teactjs/core';
+ * import { storagePlugin } from '@teactjs/storage';
+ *
+ * export default defineConfig({
+ *   mode: 'polling',
+ *   plugins: [storagePlugin()],
+ * });
+ */
+export declare function defineConfig(config: TeactConfig): TeactConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/runtime/src/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../runtime/src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC7B,qEAAqE;IACrE,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,mDAAmD;IACnD,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IAC1B,sCAAsC;IACtC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,YAAY,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAE7D"}

package/dist/runtime/src/context.d.ts

@@ -0,0 +1,74 @@
+import React from 'react';
+import type { BotContext, SessionData } from '@teactjs/renderer';
+/** Internal context value provided to all components during a render cycle. */
+export interface RuntimeContextValue {
+    botCtx: BotContext;
+    session: SessionData;
+    updateSession: (patch: Partial<SessionData>) => void;
+    command: {
+        name: string;
+        args: string[];
+    } | null;
+}
+export declare const RuntimeContext: React.Context<RuntimeContextValue | null>;
+/**
+ * Access the current bot context (chatId, userId, text, callbackData, raw update, etc.).
+ *
+ * @example
+ * const { chatId, text, user } = useBot();
+ */
+export declare function useBot(): BotContext;
+/**
+ * Read and write session data that persists across messages for the current chat.
+ *
+ * @returns A `[session, updateSession]` tuple (like `useState`).
+ *
+ * @example
+ * const [session, setSession] = useSession<{ counter: number }>();
+ * setSession({ counter: (session.counter ?? 0) + 1 });
+ */
+export declare function useSession<T extends SessionData = SessionData>(): [T, (patch: Partial<T>) => void];
+/**
+ * Returns the current platform name (e.g. `"telegram"`).
+ *
+ * @example
+ * const platform = usePlatform(); // "telegram"
+ */
+export declare function usePlatform(): string;
+/**
+ * Returns the current chat ID.
+ *
+ * @example
+ * const chatId = useChatId();
+ */
+export declare function useChatId(): string;
+/**
+ * Returns the current message text, or `undefined` for callback queries.
+ *
+ * @example
+ * const text = useText();
+ * if (text === 'hello') return <Message text="Hi there!" />;
+ */
+export declare function useText(): string | undefined;
+/**
+ * Returns the current callback data, or `undefined` for normal messages.
+ *
+ * @example
+ * const data = useCallbackData();
+ */
+export declare function useCallbackData(): string | undefined;
+/**
+ * Returns the command that triggered this render, or `null`.
+ *
+ * Only populated when a handler-less command falls through to the component tree.
+ * Useful in `useState` initializers to pick the starting screen based on the command.
+ *
+ * @example
+ * const cmd = useCommand();
+ * if (cmd?.name === 'settings') return <SettingsPage />;
+ */
+export declare function useCommand(): {
+    name: string;
+    args: string[];
+} | null;
+//# sourceMappingURL=context.d.ts.map

package/dist/runtime/src/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../runtime/src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAqB,MAAM,OAAO,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEjE,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;IACrB,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACrD,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;CAClD;AAED,eAAO,MAAM,cAAc,2CAAwD,CAAC;AAQpF;;;;;GAKG;AACH,wBAAgB,MAAM,IAAI,UAAU,CAEnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,KAAK,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAGlG;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,IAAI,MAAM,GAAG,SAAS,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,SAAS,CAEpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAEpE"}

package/dist/runtime/src/conversation.d.ts

@@ -0,0 +1,310 @@
+import React from 'react';
+/**
+ * Validation function: return `true` to accept, or an error-message string.
+ *
+ * @example
+ * const notEmpty: ValidateFn = (v) => v.trim() ? true : 'Cannot be empty';
+ */
+export type ValidateFn = (value: string) => true | string;
+/** Duck-typed Zod / Standard Schema — anything with a `.safeParse()` method. */
+export interface SchemaLike {
+    safeParse(value: unknown): {
+        success: boolean;
+        error?: {
+            issues: Array<{
+                message: string;
+            }>;
+        };
+    };
+}
+/**
+ * Input validator — either a plain function or a Zod-compatible schema.
+ *
+ * @example
+ * // Function validator
+ * const v: Validator = (val) => val.length >= 2 || 'Too short';
+ *
+ * // Zod schema
+ * const v: Validator = z.string().min(2);
+ */
+export type Validator = ValidateFn | SchemaLike;
+type AskOption = string | {
+    text: string;
+    value: string;
+};
+/** Navigation actions available inside custom render steps. */
+export interface StepActions {
+    back(): void;
+    goTo(key: string): void;
+    canGoBack(): boolean;
+}
+/**
+ * A single conversation step definition:
+ * - `prompt` — wait for free-text input with optional validation
+ * - `ask` — present inline-keyboard buttons for selection
+ * - `render` — custom React element with manual `done()` callback
+ */
+export type StepDef = {
+    prompt: string;
+    validate?: Validator;
+} | {
+    ask: string;
+    options: AskOption[][];
+} | {
+    render: (done: (value?: string) => void, actions: StepActions) => React.ReactElement;
+};
+/** Map of step names to their definitions. */
+export type StepsConfig = Record<string, StepDef>;
+/** Navigation actions returned by `useConversation` for controlling flow. */
+export interface ConversationActions {
+    goTo(key: string): void;
+    back(): void;
+    reset(): void;
+    clear(key: string): void;
+    canGoBack(): boolean;
+}
+/** Navigation actions returned by `useForm` for controlling form flow. */
+export interface FormActions<K extends string = string> {
+    goTo(key: K): void;
+    back(): void;
+    reset(): void;
+}
+interface UseConversationOptions {
+    validate?: (key: string, value: string) => true | string;
+}
+export interface ConversationState<K extends string = string> {
+    has(key: K): boolean;
+    get(key: K): string | undefined;
+    set(key: K, value: string): void;
+    /** Remove a collected answer, causing that step to be re-asked. */
+    clear(key: K): void;
+    prompt(key: K, questionText: string): React.ReactElement;
+    ask(key: K, questionText: string, options: AskOption[][]): React.ReactElement;
+    waitFor(key: K): void;
+    /** Current step index (0-based). */
+    step: number;
+    /** Key of the current step, or null when complete. */
+    current: K | null;
+    /** True when all declared steps are done (always false in imperative mode). */
+    complete: boolean;
+    isWaiting: boolean;
+    data: Readonly<Record<K, string>>;
+    lastError: string | null;
+    /**
+     * Render the conversation flow.
+     *
+     * With a completion callback (recommended) — no `if` check needed:
+     * ```tsx
+     * return conv.render(() => <Message text="Done!" />);
+     * ```
+     *
+     * Without a callback — returns null when complete:
+     * ```tsx
+     * const el = conv.render();
+     * if (!el) return <Message text="Done!" />;
+     * return el;
+     * ```
+     */
+    render(onComplete: () => React.ReactElement): React.ReactElement;
+    render(): React.ReactElement | null;
+    /** Go back to the previous step. Clears that step's answer so it gets re-asked. */
+    back(): void;
+    /** Jump to a specific step. Clears that step's answer so it gets re-asked. After answering, resumes from there. */
+    goTo(key: K): void;
+    /** True when there is a previous step to go back to. */
+    canGoBack(): boolean;
+    reset(): void;
+}
+/**
+ * Multi-step conversation hook.
+ *
+ * @example Step-based (declarative)
+ * ```tsx
+ * const conv = useConversation({
+ *   name:   { prompt: "What's your name?" },
+ *   rating: { ask: 'Rate us:', options: [['⭐ 1', '⭐⭐ 2']] },
+ * });
+ *
+ * return conv.render(() => (
+ *   <Message text={`Thanks ${conv.data.name}! Rating: ${conv.data.rating}`} />
+ * ));
+ * ```
+ *
+ * @example Imperative (manual control)
+ * ```tsx
+ * const conv = useConversation();
+ * if (!conv.has('name')) return conv.prompt('name', "What's your name?");
+ * ```
+ */
+export declare function useConversation<T extends StepsConfig>(config: T): ConversationState<Extract<keyof T, string>>;
+export declare function useConversation(config?: UseConversationOptions): ConversationState;
+export interface FormFieldDef {
+    /** Question text, or a function that receives collected data so far. */
+    prompt: string | ((data: Readonly<Record<string, string>>) => string);
+    /** If provided, show inline-keyboard buttons instead of waiting for text input. Each inner array is a row. */
+    options?: string[][];
+    /**
+     * Validate text input before accepting.
+     * - Function: `(v) => true | "error message"`
+     * - Zod schema: `z.string().min(2)`
+     * - Any object with `.safeParse()` (Standard Schema protocol)
+     */
+    validate?: Validator;
+}
+export interface FormResult<K extends string = string> {
+    /** True when all fields have been collected. */
+    complete: boolean;
+    /** All collected answers, keyed by field name. */
+    data: Readonly<Record<K, string>>;
+    /**
+     * Render the form flow.
+     * ```tsx
+     * return form.render(() => <Message text={`Hello ${form.data.name}!`} />);
+     * ```
+     */
+    render(onComplete: () => React.ReactElement): React.ReactElement;
+    render(): React.ReactElement | null;
+    /** Go back to the previous field. */
+    back(): void;
+    /** Jump to a specific field. */
+    goTo(key: K): void;
+    /** True when there is a previous field to go back to. */
+    canGoBack(): boolean;
+    /** Clear all answers and restart the form. */
+    reset(): void;
+}
+/**
+ * Multi-step form hook with validation, back/goTo navigation, and completion state.
+ *
+ * @param schema - Map of field names to their prompt text, options, and validators.
+ * @returns A {@link FormResult} object for rendering and reading collected data.
+ *
+ * @example
+ * ```tsx
+ * const form = useForm({
+ *   name:   { prompt: "What's your name?", validate: z.string().min(2) },
+ *   region: { prompt: 'Pick a region:', options: [['Kanto', 'Johto']] },
+ * });
+ *
+ * return form.render(() => (
+ *   <Message text={`${form.data.name} from ${form.data.region}`} />
+ * ));
+ * ```
+ */
+export declare function useForm<T extends Record<string, FormFieldDef>>(schema: T): FormResult<Extract<keyof T, string>>;
+/** Access the nearest `<Conversation>` state from any child component. */
+export declare function useConversationContext(): ConversationState;
+/** Access the nearest `<Form>` state from any child component. */
+export declare function useFormContext<K extends string = string>(): FormResult<K>;
+interface ConvPromptProps {
+    name: string;
+    text: string;
+    validate?: Validator;
+}
+declare function ConversationPrompt(_: ConvPromptProps): null;
+interface ConvAskProps {
+    name: string;
+    text: string;
+    options: AskOption[][];
+}
+declare function ConversationAsk(_: ConvAskProps): null;
+interface ConvStepProps {
+    name: string;
+    children: (done: (value?: string) => void, actions: StepActions) => React.ReactElement;
+}
+declare function ConversationStepChild(_: ConvStepProps): null;
+interface ConvCompleteProps {
+    children: React.ReactNode | ((conv: ConversationState) => React.ReactElement);
+}
+declare function ConversationComplete(_: ConvCompleteProps): null;
+interface FormFieldProps {
+    name: string;
+    prompt: string | ((data: Readonly<Record<string, string>>) => string);
+    options?: string[][];
+    validate?: Validator;
+}
+declare function FormFieldChild(_: FormFieldProps): null;
+interface FormCompleteProps {
+    children: React.ReactNode | ((form: FormResult) => React.ReactElement);
+}
+declare function FormCompleteChild(_: FormCompleteProps): null;
+/**
+ * Shadcn-like composable conversation component.
+ *
+ * @example With `useConversation` hook (recommended)
+ * ```tsx
+ * const conv = useConversation({
+ *   name: { prompt: "What's your name?" },
+ *   rating: { ask: 'Rate us:', options: [['⭐ 1', '⭐⭐ 2']] },
+ * });
+ *
+ * return (
+ *   <Conversation value={conv}>
+ *     <Conversation.Complete>
+ *       <Message text={`Hello ${conv.data.name}! Rating: ${conv.data.rating}`} />
+ *     </Conversation.Complete>
+ *   </Conversation>
+ * );
+ * ```
+ *
+ * @example Self-contained (steps as children, like shadcn Tabs)
+ * ```tsx
+ * <Conversation>
+ *   <Conversation.Prompt name="name" text="What's your name?" />
+ *   <Conversation.Ask name="color" text="Pick:" options={[['Red', 'Blue']]} />
+ *   <Conversation.Complete>
+ *     {(conv) => <Message text={`${conv.data.name} chose ${conv.data.color}`} />}
+ *   </Conversation.Complete>
+ * </Conversation>
+ * ```
+ */
+declare function ConversationRoot({ children, value }: {
+    children: React.ReactNode;
+    value?: ConversationState;
+}): React.ReactElement;
+export declare const Conversation: typeof ConversationRoot & {
+    Prompt: typeof ConversationPrompt;
+    Ask: typeof ConversationAsk;
+    Step: typeof ConversationStepChild;
+    Complete: typeof ConversationComplete;
+};
+/**
+ * Shadcn-like composable form component.
+ *
+ * @example With `useForm` hook (recommended)
+ * ```tsx
+ * const form = useForm({
+ *   name: { prompt: "Name?", validate: z.string().min(2) },
+ *   region: { prompt: "Region?", options: [['Kanto', 'Johto']] },
+ * });
+ *
+ * return (
+ *   <Form value={form}>
+ *     <Form.Complete>
+ *       <Message text={`${form.data.name} from ${form.data.region}`} />
+ *     </Form.Complete>
+ *   </Form>
+ * );
+ * ```
+ *
+ * @example Self-contained (fields as children)
+ * ```tsx
+ * <Form>
+ *   <Form.Field name="name" prompt="Name?" validate={z.string().min(2)} />
+ *   <Form.Field name="region" prompt="Region?" options={[['Kanto', 'Johto']]} />
+ *   <Form.Complete>
+ *     {(form) => <Message text={`${form.data.name} from ${form.data.region}`} />}
+ *   </Form.Complete>
+ * </Form>
+ * ```
+ */
+declare function FormRoot({ children, value }: {
+    children: React.ReactNode;
+    value?: FormResult;
+}): React.ReactElement;
+export declare const Form: typeof FormRoot & {
+    Field: typeof FormFieldChild;
+    Complete: typeof FormCompleteChild;
+};
+export {};
+//# sourceMappingURL=conversation.d.ts.map