react-dockable-desktop 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,427 @@
+import * as React$1 from 'react';
+import React__default, { ComponentType, ReactNode } from 'react';
+
+interface WindowManagerProps {
+    skin?: string;
+    defaultPanelIcon?: React__default.ReactNode;
+}
+declare const WindowManager: React__default.FC<WindowManagerProps>;
+
+interface PanelRegistryEntry {
+    Component: ComponentType<any>;
+    defaultOptions?: {
+        title?: string;
+        icon?: React.ReactNode;
+        initialTarget?: 'floating' | 'docked' | 'tabbed';
+        favoritePosition?: {
+            x: number | string;
+            y: number | string;
+            width: number | string;
+            height: number | string;
+        };
+        canDrag?: boolean;
+        canMinimize?: boolean;
+        canClose?: boolean;
+        defaultStickyRight?: boolean;
+        defaultStickyBottom?: boolean;
+        disableLivePreview?: boolean;
+    };
+}
+declare class PanelRegistryClass {
+    private registry;
+    register<P extends object>(id: string, Component: ComponentType<P>, defaultOptions?: PanelRegistryEntry['defaultOptions']): void;
+    get(id: string): PanelRegistryEntry | undefined;
+    getRegisteredIds(): string[];
+}
+declare const PanelRegistry: PanelRegistryClass;
+
+/**
+ * Default English messages for every action exposed by Dockable Desktop.
+ *
+ * Each value's `id` is the react-intl message ID that the consumer should
+ * define in their IntlProvider messages table. The `defaultMessage` is used
+ * as a fallback when no external formatter is provided.
+ *
+ * Pass a partial or full override to <WindowManagerProvider predefinedMessages={…} />
+ * to customise labels without replacing the whole table.
+ */
+declare const defaultPredefinedMessages: {
+    readonly floatWindow: {
+        readonly id: "dockable-desktop-floatWindow";
+        readonly defaultMessage: "Float Window";
+    };
+    readonly minimizePanel: {
+        readonly id: "dockable-desktop-minimizePanel";
+        readonly defaultMessage: "Minimize Panel";
+    };
+    readonly closeTab: {
+        readonly id: "dockable-desktop-closeTab";
+        readonly defaultMessage: "Close Tab";
+    };
+    readonly restorePanel: {
+        readonly id: "dockable-desktop-restorePanel";
+        readonly defaultMessage: "Restore Panel";
+    };
+    readonly maximizePanel: {
+        readonly id: "dockable-desktop-maximizePanel";
+        readonly defaultMessage: "Maximize Panel";
+    };
+    readonly closePanel: {
+        readonly id: "dockable-desktop-closePanel";
+        readonly defaultMessage: "Close Panel";
+    };
+    readonly dockWindow: {
+        readonly id: "dockable-desktop-dockWindow";
+        readonly defaultMessage: "Dock Window";
+    };
+    readonly minimize: {
+        readonly id: "dockable-desktop-minimize";
+        readonly defaultMessage: "Minimize";
+    };
+    readonly maximize: {
+        readonly id: "dockable-desktop-maximize";
+        readonly defaultMessage: "Maximize";
+    };
+    readonly restoreSize: {
+        readonly id: "dockable-desktop-restoreSize";
+        readonly defaultMessage: "Restore Size";
+    };
+    readonly close: {
+        readonly id: "dockable-desktop-close";
+        readonly defaultMessage: "Close";
+    };
+    readonly closeEmptyGroup: {
+        readonly id: "dockable-desktop-closeEmptyGroup";
+        readonly defaultMessage: "Close empty split group";
+    };
+    readonly anchorToRightEdge: {
+        readonly id: "dockable-desktop-anchorToRightEdge";
+        readonly defaultMessage: "Anchor to Right Edge";
+    };
+    readonly anchorToBottomEdge: {
+        readonly id: "dockable-desktop-anchorToBottomEdge";
+        readonly defaultMessage: "Anchor to Bottom Edge";
+    };
+    readonly windowAnchoringOptions: {
+        readonly id: "dockable-desktop-windowAnchoringOptions";
+        readonly defaultMessage: "Window Anchoring Options";
+    };
+};
+/**
+ * Union of every key in `defaultPredefinedMessages`.
+ *
+ * Import this type in your i18n message tables to get a compile-time
+ * guarantee that all keys are present and no typos exist:
+ *
+ *   import type { PredefinedMessageKey } from 'react-dockable-desktop';
+ *
+ *   const myMessages: Record<PredefinedMessageKey, string> = { ... };
+ */
+type PredefinedMessageKey = keyof typeof defaultPredefinedMessages;
+
+interface ContextMenuPredefinedMessage {
+    id: string;
+    defaultMessage?: string;
+    values?: Record<string, string | number>;
+}
+type MessageFormatter = (msg: ContextMenuPredefinedMessage) => string;
+type SplitOrientation = 'horizontal' | 'vertical';
+interface LayoutGridNode {
+    type: 'branch';
+    orientation: SplitOrientation;
+    children: LayoutNode[];
+    sizes: number[];
+}
+interface LayoutLeafNode {
+    type: 'leaf';
+    id: string;
+    panels: string[];
+    activePanelId: string | null;
+    canClose?: boolean;
+    /** When true the leaf group persists in the layout even after its last panel
+     *  is closed/floated/minimised. Defaults to false (auto-remove). */
+    keepOnEmpty?: boolean;
+}
+type LayoutNode = LayoutGridNode | LayoutLeafNode;
+interface FloatingWindow {
+    id: string;
+    x: number | string;
+    y: number | string;
+    width: number | string;
+    height: number | string;
+    z: number;
+    maximized?: boolean;
+    stickyRight?: boolean;
+    stickyBottom?: boolean;
+}
+interface PanelInfo {
+    id: string;
+    title: string | ContextMenuPredefinedMessage;
+    component: string;
+    state: 'docked' | 'floating' | 'minimized';
+    previousState?: 'docked' | 'floating';
+    lastFloatingRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        stickyRight?: boolean;
+        stickyBottom?: boolean;
+    };
+    lastLeafId?: string;
+    dirty?: boolean;
+}
+interface WindowState {
+    gridRoot: LayoutNode;
+    floating: FloatingWindow[];
+    minimized: {
+        id: string;
+        title: string | ContextMenuPredefinedMessage;
+        component: string;
+    }[];
+    panels: Record<string, PanelInfo>;
+    draggedPanelId: string | null;
+    pendingClose: {
+        id: string;
+        resolve: (discard: boolean) => void;
+    } | null;
+}
+interface WindowActions {
+    openPanel: (id: string, component: string, options?: {
+        title?: string | ContextMenuPredefinedMessage;
+        initialTarget?: 'floating' | 'docked' | 'tabbed';
+        stickyRight?: boolean;
+        stickyBottom?: boolean;
+    }) => void;
+    closePanel: (id: string) => void;
+    minimizePanel: (id: string) => void;
+    restorePanel: (id: string) => void;
+    floatPanel: (id: string, rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }) => void;
+    dockPanel: (id: string, targetLeafId?: string) => void;
+    maximizePanel: (id: string) => void;
+    updateSplitSizes: (path: number[], sizes: number[]) => void;
+    updateFloatingPosition: (id: string, updates: Partial<Pick<FloatingWindow, 'x' | 'y' | 'width' | 'height' | 'stickyRight' | 'stickyBottom'>>) => void;
+    bringToFront: (id: string) => void;
+    saveLayout: () => string;
+    loadLayout: (layoutJson: string) => void;
+    publish: (event: string, data: any) => void;
+    subscribe: (event: string, callback: (data: any) => void) => () => void;
+    setDraggedPanelId: (id: string | null) => void;
+    dockPanelToGroup: (id: string, targetLeafId: string, position: 'left' | 'right' | 'top' | 'bottom' | 'center') => void;
+    movePanelOrder: (panelId: string, targetLeafId: string, targetIndex: number) => void;
+    closeLeafGroup: (leafId: string) => void;
+    registerCloseGuard: (id: string, guard: () => boolean | Promise<boolean>) => void;
+    unregisterCloseGuard: (id: string) => void;
+    setPanelDirty: (id: string, dirty: boolean) => void;
+    updatePanelTitle: (id: string, title: string | ContextMenuPredefinedMessage) => void;
+    requestClosePanel: (id: string, options?: {
+        force?: boolean;
+    }) => Promise<void>;
+    resolvePendingClose: (discard: boolean) => void;
+    dockPanelToWorkspaceEdge: (id: string, position: 'left' | 'right' | 'top' | 'bottom') => void;
+}
+interface StyleClasses {
+    modalClass?: string;
+    modalBodyClass?: string;
+    sidePanelClass?: string;
+    sidePanelBodyClass?: string;
+    windowClass?: string;
+    windowBodyClass?: string;
+}
+declare const useStyleClasses: () => StyleClasses;
+interface WindowManagerProviderProps {
+    children: React__default.ReactNode;
+    formatMessage?: MessageFormatter;
+    predefinedMessages?: Record<string, ContextMenuPredefinedMessage>;
+    modalClass?: string;
+    modalBodyClass?: string;
+    sidePanelClass?: string;
+    sidePanelBodyClass?: string;
+    windowClass?: string;
+    windowBodyClass?: string;
+}
+declare const WindowManagerProvider: React__default.FC<WindowManagerProviderProps>;
+declare const useWindowManagerState: () => WindowState;
+declare const useWindowManagerActions: () => WindowActions;
+declare const useFormatMessage: () => MessageFormatter;
+declare const formatLabel: (label: string | ContextMenuPredefinedMessage | undefined, formatter: MessageFormatter) => string;
+declare const usePanelContext: () => {
+    publish: (event: string, data: any) => void;
+    subscribe: (event: string, callback: (data: any) => void) => () => void;
+};
+declare const usePredefinedMessages: () => Record<"floatWindow" | "minimizePanel" | "closeTab" | "restorePanel" | "maximizePanel" | "closePanel" | "dockWindow" | "minimize" | "maximize" | "restoreSize" | "close" | "closeEmptyGroup" | "anchorToRightEdge" | "anchorToBottomEdge" | "windowAnchoringOptions", ContextMenuPredefinedMessage>;
+
+interface CloseOptions {
+    force?: boolean;
+}
+type ContainerType = 'left-panel' | 'right-panel' | 'modal' | 'dockable-panel' | 'standalone';
+interface FormContainerContract {
+    requestClose: (options?: CloseOptions) => void;
+    setDirty: (dirty: boolean) => void;
+    onCloseRequested: (handler: () => boolean | Promise<boolean>) => (() => void);
+    setTitle: (title: string | {
+        id: string;
+        defaultMessage: string;
+        values?: Record<string, any>;
+    }) => void;
+    setIcon?: (icon: React.ReactNode) => void;
+    containerType?: ContainerType;
+    instanceId: string;
+    onClose?: (handler: () => void) => () => void;
+    onMinimize?: (handler: () => void) => () => void;
+    onRestore?: (handler: () => void) => () => void;
+    onResize?: (handler: (width: number, height: number) => void) => () => void;
+}
+declare const FormContainerContext: React$1.Context<FormContainerContract>;
+declare const FormContainerProvider: React$1.Provider<FormContainerContract>;
+declare const useFormContainer: () => FormContainerContract;
+
+type PanelInstanceId = string;
+interface PanelTitleDescriptor {
+    id: string;
+    defaultMessage?: string;
+    values?: Record<string, string | number>;
+}
+type PanelTitle = string | PanelTitleDescriptor;
+interface SidePanelOptions {
+    title?: PanelTitle;
+    icon?: React__default.ReactNode;
+    width?: number | string;
+}
+interface ModalOptions {
+    title?: PanelTitle;
+    icon?: React__default.ReactNode;
+    size?: 'small' | 'medium' | 'large' | 'fullscreen' | 'auto';
+    closable?: boolean;
+}
+interface PanelInstance {
+    id: PanelInstanceId;
+    Component: ComponentType<any>;
+    props: Record<string, any>;
+    containerType: 'left-panel' | 'right-panel' | 'modal';
+    options: SidePanelOptions | ModalOptions;
+    dirty?: boolean;
+}
+interface PanelState {
+    leftPanel: PanelInstance | null;
+    rightPanel: PanelInstance | null;
+    modals: PanelInstance[];
+}
+interface PanelActions {
+    openLeftPanel: <P extends object>(Component: ComponentType<P>, props: P, options?: SidePanelOptions) => Promise<PanelInstanceId | null>;
+    openRightPanel: <P extends object>(Component: ComponentType<P>, props: P, options?: SidePanelOptions) => Promise<PanelInstanceId | null>;
+    openModal: <P extends object>(Component: ComponentType<P>, props: P, options?: ModalOptions) => PanelInstanceId;
+    close: (id: PanelInstanceId) => void;
+    closeAll: () => void;
+    closeAllModals: () => void;
+    getInstance: (id: PanelInstanceId) => PanelInstance | undefined;
+    updateInstance: (id: PanelInstanceId, updates: Partial<Pick<PanelInstance, 'props' | 'options' | 'dirty'>>) => void;
+    setDirty: (id: PanelInstanceId, dirty: boolean) => void;
+    registerCloseHandler: (id: PanelInstanceId, handler: () => Promise<boolean>) => void;
+    unregisterCloseHandler: (id: PanelInstanceId) => void;
+}
+declare const PanelProvider: React__default.FC<{
+    children: ReactNode;
+}>;
+declare const usePanelState: () => PanelState;
+declare const usePanelActions: () => PanelActions;
+
+declare const ModalStackRenderer: React__default.FC;
+
+interface SidePanelRendererProps {
+    /**
+     * Default panel width applied when openLeftPanel/openRightPanel do not specify one.
+     * Accepts a number (treated as px) or any CSS width string (e.g. '40vw').
+     * Falls back to 400px if omitted.
+     */
+    defaultWidth?: number | string;
+}
+declare const SidePanelRenderer: React__default.FC<SidePanelRendererProps>;
+declare const LeftPanelRenderer: React__default.FC<SidePanelRendererProps>;
+declare const RightPanelRenderer: React__default.FC<SidePanelRendererProps>;
+
+interface ConfirmationFormProps {
+    title?: string | {
+        id: string;
+        defaultMessage?: string;
+        values?: any;
+    };
+    message: string | {
+        id: string;
+        defaultMessage?: string;
+        values?: any;
+    };
+    alert?: string;
+    alertType?: 'info' | 'warning' | 'success' | 'danger';
+    useYesNoTitles?: boolean;
+    onOK?: () => void;
+    onCancel?: () => void;
+}
+declare const ConfirmationForm: React__default.FC<ConfirmationFormProps>;
+
+/**
+ * Per-tab configuration supplied by the consuming application.
+ */
+interface SidebarTab {
+    id: string;
+    label: string;
+    icon: React__default.ReactNode;
+    /**
+     * Mount immediately when the Sidebar first renders, not on first user click.
+     * Implies `preserveState: true`.
+     * Use when other parts of the app need to interact with the panel before
+     * the user has opened it (e.g. push data into a context, warm up a WebGL map).
+     * Default: false
+     */
+    eagerMount?: boolean;
+    /**
+     * Once mounted for the first time, keep the component alive in the DOM
+     * behind `display: none` when closed instead of unmounting it.
+     * Use for panels with expensive local state (long forms, WebGL scenes, etc.).
+     * Ignored when `eagerMount` is true (eagerly mounted panels are always preserved).
+     * Default: false
+     */
+    preserveState?: boolean;
+    /**
+     * Called to obtain the drawer content for this tab.
+     * @param tabId   - the id of this tab
+     * @param onClose - call to collapse the sidebar drawer
+     * @param onOpen  - call to expand the drawer and select this tab programmatically
+     *                  (useful when the panel itself detects it has new data to show)
+     */
+    renderContent: (tabId: string, onClose: () => void, onOpen: () => void) => React__default.ReactNode;
+}
+interface SidebarProps {
+    /** Which side the tab strip and drawer appear on. Default: 'right' */
+    position?: 'left' | 'right';
+    tabs: SidebarTab[];
+    /** Width of the open drawer. Default: '220px' */
+    drawerWidth?: string;
+    /** Controlled active tab id. Leave undefined to use internal state. */
+    activeTabId?: string | null;
+    /** Called when the active tab changes in uncontrolled mode. */
+    onActiveTabChange?: (tabId: string | null) => void;
+    /** Main workspace content, rendered between the strip and drawer (or around them). */
+    children?: React__default.ReactNode;
+}
+/**
+ * Imperative handle exposed by <Sidebar ref={...}> via forwardRef.
+ * Allows external components (outside the sidebar tree) to control
+ * which tab is open without prop drilling.
+ */
+interface SidebarHandle {
+    /** Expand the drawer and activate the tab with the given id. */
+    openTab: (tabId: string) => void;
+    /** Collapse the drawer (equivalent to clicking the active tab icon). */
+    closeDrawer: () => void;
+    /** Returns the currently active tab id, or null if the drawer is collapsed. */
+    getActiveTab: () => string | null;
+}
+declare const Sidebar: React__default.ForwardRefExoticComponent<SidebarProps & React__default.RefAttributes<SidebarHandle>>;
+
+export { type CloseOptions, ConfirmationForm, type ConfirmationFormProps, type ContextMenuPredefinedMessage, type FloatingWindow, FormContainerContext, type FormContainerContract, FormContainerProvider, type LayoutGridNode, type LayoutLeafNode, type LayoutNode, LeftPanelRenderer, type MessageFormatter, type ModalOptions, ModalStackRenderer, type PanelActions, type PanelInfo, type PanelInstance, type PanelInstanceId, PanelProvider, PanelRegistry, type PanelState, type PanelTitle, type PredefinedMessageKey, RightPanelRenderer, type SidePanelOptions, SidePanelRenderer, type SidePanelRendererProps, Sidebar, type SidebarHandle, type SidebarProps, type SidebarTab, type SplitOrientation, type StyleClasses, type WindowActions, WindowManager, WindowManagerProvider, type WindowState, defaultPredefinedMessages, formatLabel, useFormContainer, useFormatMessage, usePanelActions, usePanelContext, usePanelState, usePredefinedMessages, useStyleClasses, useWindowManagerActions, useWindowManagerState };