@scalar/api-client/dist/v2/features/command-palette/hooks/use-command-palette-state.d.ts

the open source API testing client

import type { Icon as IconType } from '@scalar/components';
import { type ComputedRef, type Ref } from 'vue';
import type { RouteLocationRaw } from 'vue-router';
/** Base properties shared by all command types (internal) */
type CommandBase = {
    /** Unique identifier for the command */
    id: string;
    /** Display name shown in the command palette */
    name: string;
};
type FolderCommand = CommandBase & {
    type: 'folder';
    icon: IconType;
    /** Props for the command */
    props?: Record<string, unknown>;
};
type HiddenFolderCommand = CommandBase & {
    type: 'hidden-folder';
    /** Props for the command */
    props?: Record<string, unknown>;
};
type RouteCommand = CommandBase & {
    type: 'route';
    to: RouteLocationRaw;
    icon: IconType;
};
/**
 * Represents a single command in the command palette.
 * Commands can be folders (open sub-actions), routes (navigate), or hidden folders.
 */
export type Command = FolderCommand | RouteCommand | HiddenFolderCommand;
/**
 * A group of related commands with a label.
 * Used to organize commands into categories in the palette.
 */
export type CommandGroup = {
    /** Label for the command group (empty string for unlabeled groups) */
    label: string;
    /** List of commands in this group */
    commands: Command[];
};
/**
 * Available commands in the command palette.
 * Organized into groups for better UX and discoverability.
 */
export declare const commands: [{
    readonly label: "";
    readonly commands: [{
        readonly type: "folder";
        readonly id: "import-from-openapi-swagger-postman-curl";
        readonly name: "Import from OpenAPI/Swagger/Postman/cURL";
        readonly icon: "Import";
    }, {
        readonly type: "folder";
        readonly id: "create-document";
        readonly name: "Create Document";
        readonly icon: "Collection";
    }, {
        readonly type: "folder";
        readonly id: "add-tag";
        readonly name: "Add Tag";
        readonly icon: "Folder";
        readonly props: {
            /** Document id to add the tag to */
            documentId?: string;
        };
    }, {
        readonly type: "folder";
        readonly id: "create-request";
        readonly name: "Create Request";
        readonly icon: "ExternalLink";
        readonly props: {
            /** The id of the document to create the request in */
            documentId?: string;
            /** Tag id to add the request to (optional) */
            tagId?: string;
        };
    }, {
        readonly type: "folder";
        readonly id: "add-example";
        readonly name: "Add Example";
        readonly icon: "Example";
        readonly props: {
            /** Document id to add the example to */
            documentId?: string;
            /** Operation id to add the example to */
            operationId?: string;
        };
    }, {
        readonly type: "hidden-folder";
        readonly id: "import-curl-command";
        readonly name: "Import cURL Command";
        readonly props: {
            curl: string;
        };
    }];
}, {
    readonly label: "Pages";
    readonly commands: [{
        readonly type: "route";
        readonly id: "environment";
        readonly name: "Environment";
        readonly icon: "Brackets";
        readonly to: {
            readonly name: "workspace.environment";
        };
    }, {
        readonly type: "route";
        readonly id: "cookies";
        readonly name: "Cookies";
        readonly icon: "Cookie";
        readonly to: {
            readonly name: "workspace.cookies";
        };
    }, {
        readonly type: "route";
        readonly id: "settings";
        readonly name: "Settings";
        readonly icon: "Settings";
        readonly to: {
            readonly name: "workspace.settings";
        };
    }];
}];
type FlatCommand = (typeof commands)[number]['commands'][number];
export type FolderCommandIds = Extract<FlatCommand, {
    type: 'folder';
}>['id'];
export type HiddenFolderCommandIds = Extract<FlatCommand, {
    type: 'hidden-folder';
}>['id'];
/** Command IDs that map to UI components (folder and hidden-folder types) */
export type UiCommandIds = FolderCommandIds | HiddenFolderCommandIds;
/**
 * Maps each command ID to its respective props type.
 * If a command has no props defined, it maps to undefined.
 *
 * This is used by the type system to validate that command components
 * accept the correct props for their respective command IDs.
 */
export type CommandPropsMap = {
    [K in UiCommandIds]: Extract<FlatCommand, {
        id: K;
    }> extends {
        props: infer P;
    } ? P : undefined;
};
/**
 * Type for the open function in the command palette.
 * Supports two usage patterns:
 * - open() - Opens the palette without a specific command
 * - open(commandId) - Opens a command that does not require props
 * - open(commandId, props) - Opens a command with required props
 */
export type OpenCommand = {
    (): void;
    <T extends UiCommandIds>(commandId: T, props: CommandPropsMap[T]): void;
};
export type OpenCommandEvent = <T extends UiCommandIds>(event: 'open-command', commandId: T, ...args: CommandPropsMap[T] extends undefined ? [] : [props: CommandPropsMap[T]]) => void;
/**
 * Return type for the useCommandPaletteState composable.
 * Provides reactive state and methods to control the command palette.
 */
export type UseCommandPaletteStateReturn = {
    /** Whether the command palette is currently open */
    isOpen: Ref<boolean>;
    /** The currently active command, or null if showing the main list */
    activeCommand: Ref<UiCommandIds | null>;
    /** Properties passed to the active command component */
    activeCommandProps: Ref<Record<string, unknown> | null>;
    /** Current filter/search query for filtering commands */
    filterQuery: Ref<string>;
    /** Filtered commands based on the current search query */
    filteredCommands: ComputedRef<readonly CommandGroup[]>;
    /**
     * Opens the command palette, optionally with a specific command active.
     * When opening a command, props are required only if the command defines them.
     */
    open: OpenCommand;
    /** Closes the command palette and resets state */
    close: () => void;
    /** Updates the filter query for searching commands */
    setFilterQuery: (query: string) => void;
    /** Resets all state to initial values */
    reset: () => void;
};
/**
 * Composable for managing command palette state.
 *
 * Centralizes all state management for the command palette including:
 * - Open/closed state
 * - Filter/search query
 * - Command filtering logic
 *
 * @example
 * const palette = useCommandPaletteState()
 *
 * // Open the palette
 * palette.open()
 *
 * // Open with a specific command
 * palette.open('create-document')
 *
 * // Open with command props
 * palette.open('import-curl-command', { curl: 'curl https://api.example.com' })
 *
 * // Update filter query (automatically filters commands)
 * palette.setFilterQuery('import')
 *
 * // Access filtered results
 * console.log(palette.filteredCommands.value)
 *
 * // Close and reset
 * palette.close()
 */
export declare const useCommandPaletteState: () => UseCommandPaletteStateReturn;
export {};
//# sourceMappingURL=use-command-palette-state.d.ts.map