vue-dockable-desktop 1.0.0

package/dist/core/toolbarTypes.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Toolbar item shapes.
+ *
+ * Kept as data, with rdd's field names, so a React app's `items` array transfers verbatim —
+ * a toolbar is configuration, not markup.
+ */
+import type { Component } from 'vue';
+/** A one-shot button. */
+export interface ToolbarActionItem {
+    type: 'action';
+    id: string;
+    label: string;
+    icon: Component;
+    onClick: () => void;
+    disabled?: boolean;
+}
+/** One of a set, of which exactly one is active. */
+export interface ToolbarRadioItem {
+    type: 'radio';
+    id: string;
+    /** Items sharing a group are mutually exclusive. */
+    group: string;
+    label: string;
+    icon: Component;
+    /** Shown in a group flyout; reserved for a richer tooltip. */
+    shortcut?: string;
+    onActivate?: (id: string) => void;
+    disabled?: boolean;
+}
+/**
+ * An independent on/off modifier — snap-to-grid, say.
+ *
+ * Uncontrolled by default, with the state kept on the workspace and keyed by `id`. Supply
+ * `active` and the caller becomes the source of truth, which is what lets two instances of
+ * the same panel type report independent state instead of colliding on a shared id.
+ */
+export interface ToolbarToggleItem {
+    type: 'toggle';
+    id: string;
+    label: string;
+    icon: Component;
+    shortcut?: string;
+    /** Controlled state. Supplying it — **including as `false`** — makes the caller the owner. */
+    active?: boolean;
+    onToggle?: (active: boolean) => void;
+    disabled?: boolean;
+}
+/** One entry inside a group's flyout. */
+export interface ToolbarGroupSubItem {
+    id: string;
+    label: string;
+    icon: Component;
+    /** Displayed in the flyout. */
+    shortcut?: string;
+    disabled?: boolean;
+    onActivate?: (id: string) => void;
+}
+export type ToolbarGroupEntry = ToolbarGroupSubItem | {
+    type: 'separator';
+};
+/**
+ * A collapsed family of tools: one button that opens a flyout, with radio semantics inside.
+ *
+ * The button's icon becomes the active sub-tool's, so the strip shows what is selected
+ * without being expanded.
+ */
+export interface ToolbarGroupItem {
+    type: 'group';
+    /** Both the button id and the radio group key. */
+    id: string;
+    /** Tooltip when nothing is selected. */
+    label: string;
+    /** Icon when nothing is selected. */
+    defaultIcon: Component;
+    items: ToolbarGroupEntry[];
+    disabled?: boolean;
+    /** Controlled active sub-item. Supplying it — **including as `null`** — makes the caller the owner. */
+    activeItemId?: string | null;
+    onActiveItemChange?: (id: string) => void;
+}
+export interface ToolbarSeparator {
+    type: 'separator';
+}
+export type ToolbarItem = ToolbarActionItem | ToolbarRadioItem | ToolbarToggleItem | ToolbarGroupItem | ToolbarSeparator;
+export declare const isSubItem: (entry: ToolbarGroupEntry) => entry is ToolbarGroupSubItem;
+/**
+ * Where a group's flyout opens: away from the strip, mirrored for reading direction.
+ *
+ * Pure, so the placement is testable without layout.
+ */
+export declare function flyoutPlacement(rect: {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}, position: 'left' | 'right' | 'top' | 'bottom', viewport: {
+    width: number;
+    height: number;
+}, isRtl?: boolean, gap?: number): Record<string, number>;

package/dist/core/workspace.d.ts

@@ -0,0 +1,222 @@
+import type { App, Component, ComputedRef, InjectionKey } from 'vue';
+import type { DirtyStateOptions, DropPosition, FloatAnchor, FloatingWindow, Label, LayoutNode, MessageDescriptor, MessageFormatter, PanelInfo, SplitDirection } from '../types';
+import { PanelRegistry } from './registry';
+import type { PanelDefaultOptions } from './registry';
+import type { ContextMenuItem, ShowContextMenuOptions } from './contextMenu';
+import type { BuiltInEvents } from './eventBus';
+import { defaultMessages } from './messages';
+import type { ToolbarState } from './toolbarState';
+import type { Overlays } from './overlays';
+import type { Contributions, PanelContribution } from './contributions';
+/** One entry in the panel catalogue passed to {@link createWorkspace}. */
+export interface PanelDefinition {
+    component: Component;
+    defaultOptions?: PanelDefaultOptions;
+}
+/** Configuration for {@link createWorkspace}. */
+export interface WorkspaceConfig {
+    /** The panel catalogue: keys used by `openPanel` and in saved layouts. */
+    panels?: Record<string, PanelDefinition>;
+    /** A layout from a previous `saveLayout()`. `null`/omitted starts from an empty workspace. */
+    initialState?: string | null;
+    /** Reading direction. `'rtl'` mirrors drop zones, tab order and corner anchors. @default 'ltr' */
+    dir?: 'ltr' | 'rtl';
+    /** Resolves the library's own message descriptors. The whole i18n surface. */
+    formatMessage?: MessageFormatter;
+    /** Override any subset of the built-in UI strings. */
+    messages?: Partial<Record<keyof typeof defaultMessages, MessageDescriptor>>;
+    /** Fraction taken by a panel dropped on a leaf's edge. Clamped to 0.1–0.9. @default 0.5 */
+    defaultSplitRatio?: number;
+    /** Fraction taken by a panel dropped on a workspace edge. Clamped to 0.1–0.9. @default 0.2 */
+    defaultEdgeSplitRatio?: number;
+    /** Base z-index for floating windows and all library chrome, mirrored as `--vdd-z-base`. @default 1000 */
+    zIndexBase?: number;
+    /**
+     * Your own classes, added to the library's own chrome.
+     *
+     * For attaching a styling framework's utilities — Tailwind, MUI, Bootstrap — to elements
+     * you otherwise cannot reach, since they are inside the library's markup. The library's
+     * own `vdd-` classes stay, so this adds rather than replaces.
+     *
+     * rdd exposed the same thing through a `useStyleClasses()` hook whose only test was that
+     * the hook returned the config; here the gate and a test assert the classes reach the
+     * rendered elements, which is the part that can actually break.
+     */
+    classes?: HostClasses;
+}
+/** Consumer classes added to the library's chrome. Every field is optional. */
+export interface HostClasses {
+    /** The modal's window box. */
+    modal?: string;
+    /** The modal's scrolling body. */
+    modalBody?: string;
+    /** A side panel's window box. */
+    sidePanel?: string;
+    /** A side panel's scrolling body. */
+    sidePanelBody?: string;
+    /** A floating window's outer box. */
+    window?: string;
+    /** A floating window's body, which holds the panel. */
+    windowBody?: string;
+}
+/** Options for {@link Workspace.openPanel}. */
+export interface OpenPanelOptions<P extends object = Record<string, unknown>> {
+    /** Override the tab/window title. */
+    title?: Label;
+    /** Where it goes. @default the registry's `initialTarget`, else `'docked'` */
+    initialTarget?: 'floating' | 'docked' | 'tabbed';
+    /** Corner to pin to, for a floating panel. */
+    anchor?: FloatAnchor | null;
+    /** Make it the active panel. @default true */
+    focus?: boolean;
+    /** Per-instance data handed to the component. Whether it survives `saveLayout()` is a
+     *  runtime fact — see {@link PanelInfo.serializable}. */
+    props?: P;
+    /** If another open panel of the same `component` has this key, focus that one instead. */
+    dedupeKey?: string;
+}
+/** The live workspace state. */
+export interface WorkspaceState {
+    gridRoot: LayoutNode;
+    floating: FloatingWindow[];
+    minimized: {
+        id: string;
+        title: Label;
+        component: string;
+    }[];
+    panels: Record<string, PanelInfo>;
+    /** The panel the user is looking at. Always visible, never minimised. */
+    activePanelId: string | null;
+    /** The panel being dragged, or `null`. */
+    draggedPanelId: string | null;
+    dir: 'ltr' | 'rtl';
+    isRtl: boolean;
+    splitRatio: number;
+    edgeSplitRatio: number;
+}
+/** A workspace instance: reactive state, actions, registry, and a Vue plugin. */
+export interface Workspace<TEvents extends Record<string, unknown> = Record<string, unknown>> {
+    /** The whole state, read-only. Reactive — use it in templates and `computed`. */
+    readonly state: Readonly<WorkspaceState>;
+    /** The panel catalogue. */
+    readonly registry: PanelRegistry;
+    readonly gridRoot: ComputedRef<LayoutNode>;
+    readonly floating: ComputedRef<FloatingWindow[]>;
+    readonly minimized: ComputedRef<WorkspaceState['minimized']>;
+    readonly panels: ComputedRef<Record<string, PanelInfo>>;
+    readonly activePanelId: ComputedRef<string | null>;
+    readonly draggedPanelId: ComputedRef<string | null>;
+    readonly dir: ComputedRef<'ltr' | 'rtl'>;
+    readonly isRtl: ComputedRef<boolean>;
+    openPanel<P extends object = Record<string, unknown>>(id: string, component: string, options?: OpenPanelOptions<P>): void;
+    closePanel(id: string): void;
+    requestClosePanel(id: string, options?: {
+        force?: boolean;
+        onConfirm?: (opts?: DirtyStateOptions) => Promise<boolean>;
+    }): Promise<void>;
+    minimizePanel(id: string): void;
+    restorePanel(id: string, options?: {
+        focus?: boolean;
+    }): void;
+    floatPanel(id: string, rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, anchor?: FloatAnchor | null): void;
+    dockPanel(id: string, targetLeafId?: string): void;
+    dockPanelToGroup(id: string, targetLeafId: string, position: DropPosition): void;
+    dockPanelToWorkspaceEdge(id: string, position: SplitDirection): void;
+    /** Toggle a panel between filling the workspace and its previous size. A minimised panel
+     *  is restored first — rdd's equivalent silently did nothing (divergence D1). */
+    maximizePanel(id: string): void;
+    focusPanel(id: string): void;
+    movePanelOrder(panelId: string, targetLeafId: string, targetIndex: number): void;
+    closeLeafGroup(leafId: string): void;
+    updateSplitSizes(path: number[], sizes: number[]): void;
+    updateFloatingPosition(id: string, updates: Partial<Pick<FloatingWindow, 'x' | 'y' | 'width' | 'height' | 'anchor'>>): void;
+    setPanelDirty(id: string, dirty: boolean, options?: DirtyStateOptions): void;
+    updatePanelTitle(id: string, title: Label): void;
+    setDirection(dir: 'ltr' | 'rtl'): void;
+    /** @internal drives drag visuals */
+    setDraggedPanelId(id: string | null): void;
+    isOpen(id: string): boolean;
+    getOpenPanelIds(): string[];
+    findPanelId(component: string, dedupeKey: string): string | null;
+    saveLayout(): string;
+    loadLayout(json: string): boolean;
+    publish<K extends keyof (TEvents & BuiltInEvents) & string>(event: K, data: (TEvents & BuiltInEvents)[K]): void;
+    subscribe<K extends keyof (TEvents & BuiltInEvents) & string>(event: K, cb: (data: (TEvents & BuiltInEvents)[K]) => void): () => void;
+    registerCloseGuard(id: string, guard: () => boolean | Promise<boolean>): () => void;
+    registerStateProvider(id: string, provider: () => unknown): () => void;
+    /**
+     * Contribute extra items to a panel's own context menu. The getter is read each time the
+     * menu opens, so state-driven changes (enabled, checked, present at all) just work.
+     */
+    registerPanelMenu(id: string, getItems: () => ContextMenuItem[]): () => void;
+    /** The items a panel has contributed, or an empty list. */
+    panelMenuItems(id: string): ContextMenuItem[];
+    /**
+     * Open a context menu.
+     *
+     * Callable from anywhere, including outside the component tree — the request is state, and
+     * `<VddContextMenu>` renders whatever is pending. rdd needed a provider, an adapter ref and
+     * a registration handshake to make this reachable from components on either side of the
+     * workspace in the tree.
+     */
+    showContextMenu(options: ShowContextMenuOptions): void;
+    /** Dismiss the open menu, if any. */
+    closeContextMenu(): void;
+    /** The pending menu request, or `null`. @internal */
+    readonly contextMenu: ComputedRef<{
+        x: number;
+        y: number;
+        items: ContextMenuItem[];
+    } | null>;
+    /**
+     * Toolbar selection state, for items that are not controlled by the caller.
+     *
+     * On the workspace rather than behind its own provider, so `useToolbar()` works anywhere —
+     * including from a service. rdd needed a `<ToolbarProvider>` in the tree for this.
+     */
+    readonly toolbar: ToolbarState;
+    /**
+     * Toolbar items and sidebar sections panels publish while they are active.
+     *
+     * Read through {@link Workspace.activeContribution}, which is driven by `activePanelId` —
+     * and therefore by the invariant that `activePanelId` never names a panel the user cannot
+     * see. rdd's could (divergence D2), which made the shell's toolbar show controls belonging
+     * to a panel hidden behind another tab.
+     */
+    readonly contributions: Contributions;
+    /** What the active panel has published, or `null`. Reactive. */
+    readonly activeContribution: ComputedRef<PanelContribution | null>;
+    /**
+     * Side panels and the modal stack.
+     *
+     * Here for the same reason as `toolbar`: a modal is very often opened from something that
+     * is not a component — a save handler, a router guard, an error interceptor. rdd needed a
+     * `<PanelProvider>` in the tree, so those callers had to be handed an action object.
+     */
+    readonly overlays: Overlays;
+    /** Your own classes for the library's chrome, with every field present. */
+    readonly classes: Required<HostClasses>;
+    /** Resolve a label through the configured formatter. */
+    format(label: Label | undefined): string;
+    /** The merged message table. */
+    readonly messages: Record<keyof typeof defaultMessages, MessageDescriptor>;
+    readonly config: Readonly<Required<Pick<WorkspaceConfig, 'zIndexBase'>> & WorkspaceConfig>;
+    /** Vue plugin entry point: `app.use(workspace)`. */
+    install(app: App): void;
+    /** Drop every listener and guard. Only needed when workspaces are created dynamically. */
+    dispose(): void;
+}
+/** Injection key for {@link useWorkspace}. */
+export declare const WORKSPACE_KEY: InjectionKey<Workspace<never>>;
+/**
+ * Create a workspace.
+ *
+ * The returned object is both the imperative API and a Vue plugin, matching the
+ * `createPinia()` / `createRouter()` shape a Vue developer already knows.
+ */
+export declare function createWorkspace<TEvents extends Record<string, unknown> = Record<string, unknown>>(config?: WorkspaceConfig): Workspace<TEvents>;