Skip to content

Build your personal knowledge base with Trilium Notes

16.5 KB
Raw Blame
/**
 * Public type surface for the **Preact API** available to JSX render notes via
 * `import { … } from "trilium:preact"` (which the server rewrites to `api.preact`
 * at runtime).
 *
 * Single source of truth shared by the in-editor language service and the
 * `script-deployer`, mirroring `script_api.ts`. Following the same philosophy,
 * the genuinely useful props (enums, flags, callbacks) are typed precisely while
 * references into the heavy client widget graph (editor instances, bootstrap
 * options, note view scopes, …) are loosened to `unknown`/`Record`.
 *
 * Preact core (`h`, `Fragment`, …) and the hooks are NOT declared here — the
 * consumers re-export them straight from the real `preact` / `preact/hooks`
 * packages. This module only declares the Trilium-specific surface
 * (`defineWidget` + the bundled UI components), kept honest against the real
 * `preactAPI` by a drift guard in `frontend_script_api_preact.ts`.
 *
 * Components are `export declare const` (ambient — no runtime value); prop types
 * are intentionally module-private so the only *value* exports are the runtime
 * members, which keeps the drift guard's `keyof typeof` clean.
 */
import type { ComponentChild, ComponentChildren, FunctionComponent, RefObject, VNode } from "preact";

/** A CSS style object (loose: property names are not validated). */
type Css = Record<string, string | number>;
/** A Trilium command name (loosened from the client's `CommandNames` union). */
type Cmd = string;

interface WidgetDefinition {
    parent: "left-pane" | "center-pane" | "note-detail-pane" | "right-pane";
    render: () => VNode;
    position?: number;
}
export declare function defineWidget(definition: WidgetDefinition): WidgetDefinition & { type: "preact-widget" };
export declare function defineLauncherWidget(definition: { render: () => VNode }): { type: "preact-launcher-widget"; render: () => VNode };

interface ActionButtonProps {
    text: string;
    icon: string;
    className?: string;
    titlePosition?: "top" | "right" | "bottom" | "left";
    triggerCommand?: Cmd;
    noIconActionClass?: boolean;
    frame?: boolean;
    active?: boolean;
    disabled?: boolean;
    onClick?: (e: MouseEvent) => void;
    onAuxClick?: (e: MouseEvent) => void;
    onContextMenu?: (e: MouseEvent) => void;
    style?: Css;
}
export declare const ActionButton: FunctionComponent<ActionButtonProps>;

interface AdmonitionProps {
    type: "warning" | "note" | "caution";
    children?: ComponentChildren;
    className?: string;
    style?: Css;
}
export declare const Admonition: FunctionComponent<AdmonitionProps>;

interface ButtonProps {
    text: string;
    name?: string;
    buttonRef?: RefObject<HTMLButtonElement>;
    className?: string;
    icon?: string;
    keyboardShortcut?: string;
    onClick?: () => void;
    kind?: "primary" | "secondary" | "lowProfile";
    disabled?: boolean;
    size?: "normal" | "small" | "micro";
    style?: Css;
    triggerCommand?: Cmd;
    title?: string;
}
export declare const Button: FunctionComponent<ButtonProps>;

/**
 * Generic FullCalendar wrapper. The full FullCalendar `CalendarOptions` surface is loosened here
 * (any option may be passed through); `calendarRef` receives the underlying calendar instance.
 */
interface CalendarProps {
    calendarRef?: RefObject<unknown>;
    [option: string]: unknown;
}
export declare const Calendar: FunctionComponent<CalendarProps>;

interface CKEditorApi {
    focus(): void;
    setText(text: string): void;
}
interface CKEditorProps {
    apiRef: RefObject<CKEditorApi | undefined>;
    currentValue?: string;
    className: string;
    tabIndex?: number;
    config: unknown;
    editor: unknown;
    disableNewlines?: boolean;
    disableSpellcheck?: boolean;
    onChange?: (newValue?: string) => void;
    onClick?: (e: MouseEvent, pos?: unknown) => void;
    onKeyDown?: (e: KeyboardEvent) => void;
    onBlur?: () => void;
    onInitialized?: (editorInstance: unknown) => void;
}
export declare const CKEditor: FunctionComponent<CKEditorProps>;

interface CollapsibleProps {
    title: string;
    children?: ComponentChildren;
    initiallyExpanded?: boolean;
    className?: string;
}
export declare const Collapsible: FunctionComponent<CollapsibleProps>;

interface ExternallyControlledCollapsibleProps {
    title: string;
    children?: ComponentChildren;
    className?: string;
    expanded: boolean | undefined;
    setExpanded(expanded: boolean): void;
}
export declare const ExternallyControlledCollapsible: FunctionComponent<ExternallyControlledCollapsibleProps>;

interface ColorPickerProps {
    currentValue: string | null;
    onChange(newValue: string | null): void;
    presets?: string[];
    disabled?: boolean;
    className?: string;
}
export declare const ColorPicker: FunctionComponent<ColorPickerProps>;

interface DropdownProps {
    id?: string;
    className?: string;
    buttonClassName?: string;
    buttonProps?: Record<string, unknown>;
    children?: ComponentChildren;
    title?: string;
    dropdownContainerStyle?: Css;
    dropdownContainerClassName?: string;
    dropdownContainerRef?: RefObject<HTMLDivElement | null>;
    hideToggleArrow?: boolean;
    iconAction?: boolean;
    noSelectButtonStyle?: boolean;
    disabled?: boolean;
    text?: ComponentChildren;
    onShown?: () => void;
    onHidden?: () => void;
    /** The side of the toggle the popup prefers, as Floating UI names it: `"top"`, `"bottom-start"`, … */
    placement?: "top" | "top-start" | "top-end" | "right" | "right-start" | "right-end"
        | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end";
    /**
     * What closes the popup besides Escape and the toggle: `true` a click inside and a press
     * outside, `"inside"` or `"outside"` that one alone, `false` neither.
     */
    autoClose?: boolean | "inside" | "outside";
    dropdownRef?: RefObject<unknown>;
    titlePosition?: "top" | "right" | "bottom" | "left";
    titleOptions?: Record<string, unknown>;
    mobileBackdrop?: boolean;
}
/** A menu under a toggle, whose rows are `FormListItem`s and the other `FormList` rows. */
export declare const Dropdown: FunctionComponent<DropdownProps>;

interface DropdownPanelProps extends DropdownProps {
    /** Caps the panel to the room beside its toggle and scrolls its content inside it. */
    scrollable?: boolean;
}
/** A popup under a toggle for content other than a menu's rows, such as a form or a picker. */
export declare const DropdownPanel: FunctionComponent<DropdownPanelProps>;

interface FormCheckboxProps {
    name?: string;
    label: ComponentChildren;
    hint?: string;
    currentValue: boolean;
    disabled?: boolean;
    onChange(newValue: boolean): void;
    containerStyle?: Css;
}
export declare const FormCheckbox: FunctionComponent<FormCheckboxProps>;

interface FormDropdownListProps<T> extends Omit<DropdownProps, "children"> {
    values: T[];
    keyProperty: keyof T;
    titleProperty: keyof T;
    titleSuffixProperty?: keyof T;
    descriptionProperty?: keyof T;
    currentValue: string;
    onChange(newValue: string): void;
}
export declare function FormDropdownList<T>(props: FormDropdownListProps<T>): VNode<any>;

export declare const FormFileUploadButton: FunctionComponent<Omit<ButtonProps, "onClick"> & { onChange: (files: FileList | null) => void }>;
export declare const FormFileUploadActionButton: FunctionComponent<Omit<ActionButtonProps, "onClick"> & { onChange: (files: FileList | null) => void }>;

interface FormGroupProps {
    name: string;
    labelRef?: RefObject<HTMLLabelElement>;
    label?: string;
    title?: string;
    className?: string;
    error?: string;
    children: VNode<any>;
    description?: ComponentChildren;
    disabled?: boolean;
    style?: Css;
}
export declare const FormGroup: FunctionComponent<FormGroupProps>;

interface FormListItemProps {
    children?: ComponentChildren;
    icon?: string;
    value?: string;
    title?: string;
    active?: boolean;
    badges?: unknown[];
    disabled?: boolean;
    disabledTooltip?: string;
    checked?: boolean | null;
    selected?: boolean;
    container?: boolean;
    onClick?: (e: MouseEvent) => void;
    triggerCommand?: Cmd;
    description?: string;
    className?: string;
    rtl?: boolean;
    postContent?: ComponentChildren;
    itemRef?: RefObject<HTMLLIElement>;
}
export declare const FormListItem: FunctionComponent<FormListItemProps>;

export declare const FormDropdownDivider: FunctionComponent<{}>;

interface FormDropdownSubmenuProps {
    icon: string;
    title: ComponentChildren;
    children?: ComponentChildren;
    onDropdownToggleClicked?: () => void;
}
/**
 * A row that opens its children as a submenu. Outside a `Dropdown` menu, its title is shown as a
 * header above them.
 */
export declare const FormDropdownSubmenu: FunctionComponent<FormDropdownSubmenuProps>;

interface FormRadioGroupProps {
    name: string;
    currentValue?: string;
    values: ({ value: string; label: ComponentChildren; inlineDescription?: ComponentChildren } | false)[];
    onChange(newValue: string): void;
}
export declare const FormRadioGroup: FunctionComponent<FormRadioGroupProps>;

export declare const FormText: FunctionComponent<{ children?: ComponentChildren }>;

interface FormTextAreaProps {
    id?: string;
    currentValue: string;
    onChange?(newValue: string): void;
    onBlur?(newValue: string): void;
    inputRef?: RefObject<HTMLTextAreaElement>;
    className?: string;
    placeholder?: string;
    rows?: number;
    disabled?: boolean;
    readOnly?: boolean;
}
export declare const FormTextArea: FunctionComponent<FormTextAreaProps>;

interface FormTextBoxProps {
    id?: string;
    currentValue?: string;
    onChange?(newValue: string, validity: ValidityState): void;
    onBlur?(newValue: string): void;
    inputRef?: RefObject<HTMLInputElement>;
    type?: string;
    className?: string;
    placeholder?: string;
    disabled?: boolean;
    readOnly?: boolean;
    autoFocus?: boolean;
    name?: string;
}
export declare const FormTextBox: FunctionComponent<FormTextBoxProps>;

interface FormToggleProps {
    currentValue: boolean | null;
    onChange(newValue: boolean): void;
    switchOnName?: string;
    switchOnTooltip?: string;
    switchOffName?: string;
    switchOffTooltip?: string;
    helpPage?: string;
    disabled?: boolean;
    afterName?: ComponentChildren;
    id?: string;
}
export declare const FormToggle: FunctionComponent<FormToggleProps>;

interface IconProps {
    icon?: string;
    className?: string;
    onClick?: (e: MouseEvent) => void;
    title?: string;
    style?: Css;
}
export declare const Icon: FunctionComponent<IconProps>;

interface LinkButtonProps {
    onClick?: () => void;
    text: ComponentChild;
    triggerCommand?: Cmd;
}
export declare const LinkButton: FunctionComponent<LinkButtonProps>;

export declare const LoadingSpinner: FunctionComponent<{}>;

interface ModalProps {
    className?: string;
    title?: ComponentChildren;
    customTitleBarButtons?: ({ title: string; iconClassName: string; onClick: (e: MouseEvent) => void } | null)[];
    size: "xl" | "lg" | "md" | "sm";
    children?: ComponentChildren;
    header?: ComponentChildren;
    footer?: ComponentChildren;
    footerStyle?: Css;
    footerAlignment?: "right" | "between";
    minWidth?: string;
    maxWidth?: number;
    zIndex?: number;
    scrollable?: boolean;
    onSubmit?: () => void;
    onShown?: () => void;
    onHidden: () => void;
    helpPageId?: string;
    modalRef?: RefObject<HTMLDivElement>;
    formRef?: RefObject<HTMLFormElement>;
    bodyStyle?: Css;
    show: boolean;
    stackable?: boolean;
    keepInDom?: boolean;
    noFocus?: boolean;
    sidebar?: ComponentChildren;
    isFullPageOnMobile?: boolean;
}
export declare const Modal: FunctionComponent<ModalProps>;

interface NoteAutocompleteProps {
    id?: string;
    inputRef?: RefObject<HTMLInputElement>;
    text?: string;
    placeholder?: string;
    container?: RefObject<HTMLElement | null | undefined>;
    containerStyle?: Css;
    opts?: Record<string, unknown>;
    onChange?: (suggestion: unknown) => void;
    onTextChange?: (text: string) => void;
    onKeyDown?: (e: KeyboardEvent) => void;
    onBlur?: (newValue: string) => void;
    noteIdChanged?: (noteId: string) => void;
    noteId?: string;
}
export declare const NoteAutocomplete: FunctionComponent<NoteAutocompleteProps>;

interface NoteColorPickerProps {
    /** The target note instance (FNote) or its ID string. */
    note: unknown | string | null;
}
export declare const NoteColorPicker: FunctionComponent<NoteColorPickerProps>;

interface NoteLinkProps {
    className?: string;
    containerClassName?: string;
    notePath: string | string[];
    showNotePath?: boolean;
    showNoteIcon?: boolean;
    style?: Css;
    noPreview?: boolean;
    noTnLink?: boolean;
    highlightedTokens?: string[] | null;
    title?: string;
    viewScope?: unknown;
    noContextMenu?: boolean;
    onContextMenu?: (e: MouseEvent) => void;
}
export declare const NoteLink: FunctionComponent<NoteLinkProps>;

interface RawHtmlProps {
    className?: string;
    html?: string | HTMLElement;
    style?: Css;
    onClick?: (e: MouseEvent) => void;
    tabindex?: number;
    dir?: string;
    containerRef?: RefObject<HTMLSpanElement>;
}
export declare const RawHtml: FunctionComponent<RawHtmlProps>;

interface SliderProps {
    value: number;
    onChange(newValue: number): void;
    min?: number;
    max?: number;
    step?: number;
    title?: string;
}
export declare const Slider: FunctionComponent<SliderProps>;

/**
 * A card whose segments the reader can put in any order, by carrying the grip on a segment or with
 * the keyboard. The order is the caller's: every change is reported through `onChange`, and the
 * card draws whatever it is handed back.
 *
 * `items` are named by a `key` that outlives the order they stand in; `renderItem` draws a segment
 * for a card that shows more than a name, and `itemCreationButtons` puts a row of buttons at the
 * foot of the card that make another entry, answering with nothing where the reader backs out.
 */
interface SortableItem {
    key: string;
    caption?: ComponentChildren;
    icon?: string;
}
interface ItemCreationButton<T extends SortableItem> {
    label: string;
    icon?: string;
    /** Turns the button off, for a caller that cannot make an entry yet. */
    disabled?: boolean;
    onCreateItem: (event?: MouseEvent) => T | undefined | Promise<T | undefined>;
}
interface SortableCardProps<T extends SortableItem> {
    /** See `CardProps`: the words a filter finds the card by, and whether it is filter-only. */
    filterExtraKeywords?: string;
    filterOnly?: boolean;
    items: T[];
    onChange: (items: T[]) => void;
    renderItem?: (item: T, index: number) => ComponentChildren;
    /** Up to three, drawn as a row of buttons at the foot of the card. */
    itemCreationButtons?: ItemCreationButton<T>[];
    /** Which edge of a segment the grip stands on. The trailing one by default. */
    gripPlacement?: "start" | "end";
    /** Whether the reader can reorder the entries. Off, the card has no grip. True by default. */
    isReorderable?: boolean;
    /** Called with the focused entry for a key the card does not handle itself. */
    onItemKeyDown?: (item: T, event: KeyboardEvent) => void;
    selectedKey?: string;
    onSelect?: (key: string) => void;
    heading?: string;
    description?: ComponentChildren;
    actions?: ComponentChildren;
    className?: string;
}
// Generic, as the component itself is: the entries are the caller's own, so what `onChange` and
// `renderItem` are handed is the caller's type and not what this card asks of it.
export declare const SortableCard: <T extends SortableItem>(props: SortableCardProps<T>) => VNode;

/**
 * Generic Tabulator-based data grid. The full Tabulator `Options` surface is loosened here (any option
 * may be passed through); `data` is the row array, `columns` the column definitions, `modules` the
 * Tabulator modules to register, `events` the event handlers and `tabulatorRef` receives the instance.
 */
interface TableProps {
    tabulatorRef?: RefObject<unknown>;
    className?: string;
    data?: unknown[];
    columns?: unknown[];
    modules?: unknown[];
    events?: Record<string, unknown>;
    index?: string;
    footerElement?: unknown;
    onReady?: () => void;
    [option: string]: unknown;
}
export declare const Table: FunctionComponent<TableProps>;

interface RightPanelWidgetProps {
    id: string;
    title: string;
    children?: ComponentChildren;
    buttons?: ComponentChildren;
    containerRef?: RefObject<HTMLDivElement>;
    contextMenuItems?: unknown[];
    grow?: boolean;
}
export declare const RightPanelWidget: FunctionComponent<RightPanelWidgetProps>;