hazo_ui 2.3.1 → 2.4.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
+import { Node, Extension } from '@tiptap/core';
 
 interface FilterField {
     value: string;
@@ -162,4 +163,349 @@ interface HazoUiRteProps {
  */
 declare const HazoUiRte: React.FC<HazoUiRteProps>;
 
-export { type FilterConfig, type FilterField, HazoUiFlexInput, type HazoUiFlexInputProps, HazoUiFlexRadio, type HazoUiFlexRadioItem, type HazoUiFlexRadioProps, HazoUiMultiFilterDialog, HazoUiMultiSortDialog, HazoUiRte, type HazoUiRteProps, type RteAttachment, type RteOutput, type RteVariable, type SortConfig, type SortField };
+/**
+ * Types for HazoUiCommand - Command/Mention System
+ *
+ * Shared type definitions for command pills in text inputs with
+ * prefix-triggered command menus (e.g., @mentions, /commands, #tags).
+ */
+
+/**
+ * Individual command item that can be selected from the command menu
+ */
+interface CommandItem {
+    /** Unique identifier for this command (e.g., "user_123", "due_date") */
+    action: string;
+    /** Display label shown in the pill and dropdown (e.g., "John Doe", "Due Date") */
+    action_label: string;
+    /** Optional description shown in the dropdown */
+    action_description?: string;
+    /** Optional icon to display alongside the command */
+    icon?: React.ReactNode;
+    /** Optional group name for categorizing commands in the dropdown */
+    group?: string;
+}
+/**
+ * Configuration for a prefix trigger character
+ */
+interface PrefixConfig {
+    /** Trigger character (e.g., "/", "@", "#") */
+    char: string;
+    /** Available commands for this prefix */
+    commands: CommandItem[];
+    /** Allow free text entries that don't match existing commands */
+    allow_free_text?: boolean;
+}
+/**
+ * Represents a command that has been inserted into the text
+ */
+interface InsertedCommand {
+    /** Unique identifier for this insertion (for tracking position) */
+    id: string;
+    /** The prefix character used (e.g., "@", "/") */
+    prefix: string;
+    /** The action identifier */
+    action: string;
+    /** The display label */
+    action_label: string;
+    /** Position in the plain text output */
+    position: number;
+    /** Length of the command string in plain text */
+    length: number;
+}
+/**
+ * Output format for text with commands
+ */
+interface CommandTextOutput {
+    /** Plain text with prefix + action format (e.g., "Hello @user_123 /due_date tomorrow") */
+    plain_text: string;
+    /** Display text with prefix + label format (e.g., "Hello @John Doe /Due Date tomorrow") */
+    display_text: string;
+    /** Array of all inserted commands with position info */
+    commands: InsertedCommand[];
+}
+/**
+ * Props for the command popover component
+ */
+interface CommandPopoverProps {
+    /** Whether the popover is open */
+    is_open: boolean;
+    /** Commands to display, filtered by current query */
+    commands: CommandItem[];
+    /** The current prefix being used */
+    prefix: string;
+    /** Current search/filter query */
+    query: string;
+    /** Currently selected index for keyboard navigation */
+    selected_index: number;
+    /** Position for the popover */
+    position: {
+        top: number;
+        left: number;
+    };
+    /** Called when query changes */
+    on_query_change: (query: string) => void;
+    /** Called when a command is selected */
+    on_select: (command: CommandItem) => void;
+    /** Called when the popover should close */
+    on_close: () => void;
+    /** Called when selection changes via keyboard */
+    on_selection_change: (index: number) => void;
+}
+/**
+ * Props for the command pill component
+ */
+interface CommandPillProps {
+    /** The prefix character */
+    prefix: string;
+    /** The action identifier */
+    action: string;
+    /** The display label */
+    action_label: string;
+    /** Unique ID for this pill instance */
+    id: string;
+    /** Whether the pill is currently selected in the editor */
+    selected?: boolean;
+    /** Pill style variant */
+    variant?: "default" | "outline" | "subtle";
+    /** Called when the pill is clicked (to open edit popover) */
+    on_click?: () => void;
+}
+/**
+ * Suggestion state passed from TipTap suggestion extension
+ */
+interface SuggestionState {
+    /** Whether suggestion mode is active */
+    is_active: boolean;
+    /** Current query string (text after prefix) */
+    query: string;
+    /** The prefix character that triggered this suggestion */
+    prefix: string;
+    /** Client rect for positioning the popover */
+    client_rect: (() => DOMRect | null) | null;
+    /** Commands available for this prefix */
+    commands: CommandItem[];
+    /** TipTap range for the suggestion */
+    range: {
+        from: number;
+        to: number;
+    };
+}
+/**
+ * Props shared between HazoUiTextbox and HazoUiTextarea
+ */
+interface BaseCommandInputProps {
+    /** Controlled value - plain text with prefix + action format */
+    value?: string;
+    /** Default value for uncontrolled mode */
+    default_value?: string;
+    /** Prefix configurations for command triggers */
+    prefixes: PrefixConfig[];
+    /** Placeholder text */
+    placeholder?: string;
+    /** Whether the input is disabled */
+    disabled?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Pill style variant */
+    pill_variant?: "default" | "outline" | "subtle";
+    /** Called when the content changes */
+    on_change?: (output: CommandTextOutput) => void;
+    /** Called when a command is inserted */
+    on_command_insert?: (command: CommandItem, prefix: string) => void;
+    /** Called when an existing command is changed */
+    on_command_change?: (old_command: InsertedCommand, new_command: CommandItem) => void;
+    /** Called when a command is removed */
+    on_command_remove?: (command: InsertedCommand) => void;
+}
+/**
+ * Props for HazoUiTextbox (single-line input)
+ */
+interface HazoUiTextboxProps extends BaseCommandInputProps {
+    /** Called when Enter is pressed */
+    on_submit?: (output: CommandTextOutput) => void;
+}
+/**
+ * Props for HazoUiTextarea (multi-line input)
+ */
+interface HazoUiTextareaProps extends BaseCommandInputProps {
+    /** Minimum height for the textarea */
+    min_height?: string;
+    /** Maximum height for the textarea */
+    max_height?: string;
+    /** Number of visible rows */
+    rows?: number;
+    /** Called when Cmd/Ctrl+Enter is pressed */
+    on_submit?: (output: CommandTextOutput) => void;
+}
+/**
+ * Context type for command editing
+ */
+interface CommandEditContext {
+    /** The command being edited */
+    command: InsertedCommand;
+    /** Position of the node in the document */
+    node_pos: number;
+    /** Client rect for positioning the edit popover */
+    rect: DOMRect;
+}
+
+/**
+ * Command Node Extension for TipTap
+ *
+ * Custom atomic node extension for command pills (mentions, slash commands, etc.).
+ * Commands are rendered as non-editable pills and serialize to prefix + action format.
+ */
+
+declare module "@tiptap/core" {
+    interface Commands<ReturnType> {
+        commandNode: {
+            /**
+             * Insert a command node
+             */
+            insertCommand: (attrs: {
+                prefix: string;
+                action: string;
+                action_label: string;
+                variant?: "default" | "outline" | "subtle";
+            }) => ReturnType;
+            /**
+             * Update an existing command node by ID
+             */
+            updateCommand: (id: string, attrs: {
+                action: string;
+                action_label: string;
+            }) => ReturnType;
+        };
+    }
+}
+declare const CommandNodeExtension: Node<any, any>;
+
+/**
+ * Command Suggestion Extension for TipTap
+ *
+ * Detects prefix characters and triggers the command popover for selection.
+ * Works with multiple configurable prefixes (e.g., @, /, #).
+ */
+
+/**
+ * Props for creating the suggestion extension
+ */
+interface CommandSuggestionConfig {
+    /** Prefix configurations */
+    prefixes: PrefixConfig[];
+    /** Callback when suggestion state changes */
+    on_suggestion_change: (state: SuggestionState | null) => void;
+    /** Callback to insert a command */
+    on_insert_command: (command: CommandItem, prefix: string, range: {
+        from: number;
+        to: number;
+    }) => void;
+}
+/**
+ * Create a combined suggestion extension for all configured prefixes
+ */
+declare const create_command_suggestion_extension: (config: CommandSuggestionConfig) => Extension[];
+
+/**
+ * Command Pill Component
+ *
+ * Standalone pill component for displaying commands outside the editor.
+ * Used in edit popovers and previews.
+ */
+
+/**
+ * CommandPill - Displays a command as a styled badge/pill
+ */
+declare const CommandPill: React.FC<CommandPillProps>;
+
+/**
+ * Command Popover Component
+ *
+ * Dropdown menu for searching and selecting commands.
+ * Supports keyboard navigation and command grouping.
+ *
+ * Note: The query filtering is handled by TipTap's suggestion extension,
+ * so typing continues in the editor and filters the list automatically.
+ */
+
+/**
+ * CommandPopover - Dropdown for command selection
+ */
+declare const CommandPopover: React.FC<CommandPopoverProps>;
+
+/**
+ * HazoUiCommand - Headless Command/Mention System
+ *
+ * Provides TipTap extensions and UI components for implementing
+ * command pills with prefix triggers (e.g., @mentions, /commands, #tags).
+ *
+ * This module exports:
+ * - CommandNodeExtension: TipTap node for rendering command pills
+ * - CommandPill: Standalone pill component
+ * - CommandPopover: Dropdown menu for command selection
+ * - create_command_suggestion_extension: Factory for prefix detection
+ * - Types for building custom command UIs
+ */
+
+/**
+ * Utility to parse plain text with commands into structured format
+ *
+ * @param text - Plain text with prefix + action format (e.g., "Hello @user_123")
+ * @param prefixes - Prefix configurations to detect
+ * @returns Parsed commands with positions
+ */
+declare const parse_commands_from_text: (text: string, prefixes: {
+    char: string;
+    commands: {
+        action: string;
+        action_label: string;
+    }[];
+}[]) => {
+    action: string;
+    action_label: string;
+    prefix: string;
+    position: number;
+    length: number;
+}[];
+/**
+ * Convert parsed commands to TipTap content structure
+ *
+ * @param text - Plain text with prefix + action format
+ * @param prefixes - Prefix configurations
+ * @param variant - Pill variant style
+ * @returns TipTap JSON content structure
+ */
+declare const text_to_tiptap_content: (text: string, prefixes: {
+    char: string;
+    commands: {
+        action: string;
+        action_label: string;
+    }[];
+}[], variant?: "default" | "outline" | "subtle") => Record<string, unknown>;
+
+/**
+ * HazoUiTextbox - Single-line Input with Command Support
+ *
+ * A TipTap-based single-line text input that supports prefix-triggered
+ * command pills (e.g., @mentions, /commands, #tags).
+ */
+
+/**
+ * HazoUiTextbox Component
+ */
+declare const HazoUiTextbox: React.FC<HazoUiTextboxProps>;
+
+/**
+ * HazoUiTextarea - Multi-line Input with Command Support
+ *
+ * A TipTap-based multi-line text input that supports prefix-triggered
+ * command pills (e.g., @mentions, /commands, #tags).
+ */
+
+/**
+ * HazoUiTextarea Component
+ */
+declare const HazoUiTextarea: React.FC<HazoUiTextareaProps>;
+
+export { type BaseCommandInputProps, type CommandEditContext, type CommandItem, CommandNodeExtension, CommandPill, type CommandPillProps, CommandPopover, type CommandPopoverProps, type CommandTextOutput, type FilterConfig, type FilterField, HazoUiFlexInput, type HazoUiFlexInputProps, HazoUiFlexRadio, type HazoUiFlexRadioItem, type HazoUiFlexRadioProps, HazoUiMultiFilterDialog, HazoUiMultiSortDialog, HazoUiRte, type HazoUiRteProps, HazoUiTextarea, type HazoUiTextareaProps, HazoUiTextbox, type HazoUiTextboxProps, type InsertedCommand, type PrefixConfig, type RteAttachment, type RteOutput, type RteVariable, type SortConfig, type SortField, type SuggestionState, create_command_suggestion_extension, parse_commands_from_text, text_to_tiptap_content };