/**
 * @file useKeyboardHint.tsx
 * @input Uses React, StyleX, Kbd, useLayer, i18n (useTranslator)
 * @output Exports useKeyboardHint hook — ephemeral arrow-key navigation hint
 * @position Core hook; shows sighted keyboard users how to navigate composite
 *   widgets that use roving tabindex (single Tab stop, arrows inside)
 *
 * SYNC: When modified, update:
 * - /packages/core/src/hooks/index.ts
 * - /packages/core/src/hooks/useKeyboardHint.doc.mjs
 * - /apps/storybook/stories/useKeyboardHint.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
 */
import React, { type ReactNode } from 'react';
export type KeyboardHintOrientation = 'horizontal' | 'vertical' | 'both';
export interface UseKeyboardHintOptions {
    /**
     * Orientation of the arrow-key navigation. Controls which arrow icons are
     * shown in the hint badge.
     * - `'horizontal'` → ← →
     * - `'vertical'` → ↑ ↓
     * - `'both'` → ← → ↑ ↓
     * @default 'horizontal'
     */
    orientation?: KeyboardHintOrientation;
    /**
     * Milliseconds before the hint auto-dismisses after appearing.
     * @default 3000
     */
    dismissAfterMs?: number;
    /**
     * Whether the hint is enabled. Set to false to disable for a specific
     * instance (e.g. when the widget is read-only or the user has dismissed
     * globally).
     * @default true
     */
    isEnabled?: boolean;
}
export interface UseKeyboardHintReturn {
    /**
     * The popover hint element to render inside your component tree (portals to
     * top layer via `popover="manual"`). Render unconditionally — it manages its
     * own visibility.
     */
    hintElement: ReactNode;
    /**
     * Attach to the composite container's `onFocus`. Shows the hint on the first
     * keyboard-focus (`:focus-visible`) entry from outside.
     */
    onFocus: (e: React.FocusEvent) => void;
    /**
     * Attach to the composite container's `onBlur`. Hides the hint when focus
     * leaves the composite entirely.
     */
    onBlur: (e: React.FocusEvent) => void;
    /**
     * Attach to the composite container's `onKeyDown`. Dismisses the hint on the
     * first arrow press (the user discovered the interaction).
     */
    onKeyDown: (e: React.KeyboardEvent) => void;
}
/**
 * Shows an ephemeral visual hint ("← → to navigate") anchored to the focused
 * item when a composite widget first receives keyboard focus. Teaches sighted
 * keyboard users that arrows navigate within the group.
 *
 * The hint renders in the top layer (popover="manual") and is CSS-anchor-
 * positioned to the currently focused element, so it is never clipped by
 * overflow containers. It auto-dismisses on first arrow press, timeout, or
 * blur, and does not re-show for that instance.
 *
 * @example
 * ```
 * const hint = useKeyboardHint({orientation: 'horizontal'});
 * <div role="toolbar" onFocus={hint.onFocus} onBlur={hint.onBlur} onKeyDown={hint.onKeyDown}>
 *   {children}
 *   {hint.hintElement}
 * </div>
 * ```
 */
export declare function useKeyboardHint(options?: UseKeyboardHintOptions): UseKeyboardHintReturn;
//# sourceMappingURL=useKeyboardHint.d.ts.map