dockview-core 6.6.1 → 7.0.2

package/dist/cjs/dockview/liveRegionService.js

@@ -0,0 +1,185 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveRegionModule = exports.LiveRegionService = void 0;
+var lifecycle_1 = require("../lifecycle");
+var accessibilityMessages_1 = require("./accessibilityMessages");
+var modules_1 = require("./modules");
+/** Bulk transactions whose per-panel events should not each be announced. */
+var isBulk = function (kind) {
+    return kind === 'load' || kind === 'clear';
+};
+function createLiveRegion(politeness) {
+    var el = document.createElement('div');
+    el.className =
+        politeness === 'assertive'
+            ? 'dv-live-region-assertive'
+            : 'dv-live-region';
+    // assertive interrupts the SR (errors / cancellations); polite waits for a
+    // pause (routine status). `alert` implies assertive, `status` implies polite.
+    el.setAttribute('role', politeness === 'assertive' ? 'alert' : 'status');
+    el.setAttribute('aria-live', politeness);
+    el.setAttribute('aria-atomic', 'true');
+    // Visually hidden but kept in the accessibility tree (never display:none /
+    // visibility:hidden, which would drop it from AT). Standard clip pattern.
+    Object.assign(el.style, {
+        position: 'absolute',
+        width: '1px',
+        height: '1px',
+        margin: '-1px',
+        padding: '0',
+        overflow: 'hidden',
+        clip: 'rect(0 0 0 0)',
+        clipPath: 'inset(50%)',
+        whiteSpace: 'nowrap',
+        border: '0',
+    });
+    return el;
+}
+/**
+ * Narrates layout state changes to screen readers via visually-hidden
+ * `aria-live` regions. Free / core (WCAG 4.1.3). Announces panel open/close +
+ * the shared `announce()` sink (the accessibility module narrates docking here too).
+ * Two regions: a **polite** one for routine status and an **assertive** one
+ * for errors/cancellations. The bulk load/clear burst is suppressed via the
+ * mutation-transaction events, and an app can take over delivery entirely with
+ * the `announcer` option.
+ */
+var LiveRegionService = /** @class */ (function (_super) {
+    __extends(LiveRegionService, _super);
+    function LiveRegionService(host) {
+        var _this = _super.call(this) || this;
+        _this._suppressDepth = 0;
+        _this._locationSubs = new Map();
+        _this._host = host;
+        _this._polite = createLiveRegion('polite');
+        _this._assertive = createLiveRegion('assertive');
+        host.element.appendChild(_this._polite);
+        host.element.appendChild(_this._assertive);
+        _this.addDisposables({ dispose: function () { return _this._polite.remove(); } }, { dispose: function () { return _this._assertive.remove(); } }, host.onDidAddPanel(function (panel) { return _this._announce(panel, 'open'); }), host.onDidRemovePanel(function (panel) { return _this._announce(panel, 'close'); }), 
+        // Bracket bulk transactions so a fromJSON / clear doesn't announce
+        // every nested add/remove.
+        host.onWillMutateLayout(function (e) {
+            if (isBulk(e.kind)) {
+                _this._suppressDepth++;
+            }
+        }), host.onDidMutateLayout(function (e) {
+            if (isBulk(e.kind)) {
+                _this._suppressDepth = Math.max(0, _this._suppressDepth - 1);
+            }
+        }), host.onDidMaximizedGroupChange(function (e) {
+            var panel = e.group.activePanel;
+            if (panel) {
+                _this._announce(panel, e.isMaximized ? 'maximize' : 'restore');
+            }
+        }), 
+        // Narrate a group floating / docking back / popping out. A group is
+        // born in the grid then transitions, so track each group's previous
+        // location and ignore the no-op initial `-> grid`.
+        host.onDidAddGroup(function (group) { return _this._trackLocation(group); }), host.onDidRemoveGroup(function (group) {
+            var _a;
+            (_a = _this._locationSubs.get(group.id)) === null || _a === void 0 ? void 0 : _a.dispose();
+            _this._locationSubs.delete(group.id);
+        }), {
+            dispose: function () {
+                _this._locationSubs.forEach(function (sub) { return sub.dispose(); });
+                _this._locationSubs.clear();
+            },
+        });
+        return _this;
+    }
+    LiveRegionService.prototype._trackLocation = function (group) {
+        var _this = this;
+        var prev = group.api.location.type;
+        var sub = group.api.onDidLocationChange(function (e) {
+            var next = e.location.type;
+            if (next === prev) {
+                return;
+            }
+            prev = next;
+            var panel = group.activePanel;
+            if (!panel) {
+                return;
+            }
+            var kind = next === 'floating'
+                ? 'float'
+                : next === 'popout'
+                    ? 'popout'
+                    : 'dock';
+            _this._announce(panel, kind);
+        });
+        this._locationSubs.set(group.id, sub);
+    };
+    LiveRegionService.prototype.announce = function (message, politeness) {
+        if (politeness === void 0) { politeness = 'polite'; }
+        // Opt-out (read live so `updateOptions({ announcements })` applies).
+        if (this._host.options.announcements === false ||
+            this._suppressDepth > 0 ||
+            !message) {
+            return;
+        }
+        // Apps can route announcements into their own SR system instead of the
+        // built-in regions (e.g. a shared app-wide live region).
+        var announcer = this._host.options.announcer;
+        if (announcer) {
+            announcer({ message: message, politeness: politeness });
+            return;
+        }
+        // Clearing first forces SRs to re-announce an identical message.
+        var region = politeness === 'assertive' ? this._assertive : this._polite;
+        region.textContent = '';
+        region.textContent = message;
+    };
+    LiveRegionService.prototype._announce = function (panel, kind) {
+        var _a, _b;
+        // The app may localise/override the message, suppress it (null / ''),
+        // or fall through to the default (undefined).
+        var custom = (_b = (_a = this._host.options).getAnnouncement) === null || _b === void 0 ? void 0 : _b.call(_a, { kind: kind, panel: panel });
+        if (custom === null || custom === '') {
+            return;
+        }
+        this.announce(custom !== null && custom !== void 0 ? custom : this._defaultMessage(panel, kind));
+    };
+    LiveRegionService.prototype._defaultMessage = function (panel, kind) {
+        var _a;
+        var m = (0, accessibilityMessages_1.resolveMessages)(this._host.options.messages);
+        var name = (_a = panel.title) !== null && _a !== void 0 ? _a : panel.id;
+        switch (kind) {
+            case 'open':
+                return m.panelOpened(name);
+            case 'close':
+                return m.panelClosed(name);
+            case 'maximize':
+                return m.groupMaximized(name);
+            case 'restore':
+                return m.groupRestored(name);
+            case 'float':
+                return m.groupFloated(name);
+            case 'dock':
+                return m.groupDocked(name);
+            case 'popout':
+                return m.groupPoppedOut(name);
+        }
+    };
+    return LiveRegionService;
+}(lifecycle_1.CompositeDisposable));
+exports.LiveRegionService = LiveRegionService;
+exports.LiveRegionModule = (0, modules_1.defineModule)({
+    name: 'LiveRegion',
+    serviceKey: 'liveRegionService',
+    create: function (host) { return new LiveRegionService(host); },
+});

package/dist/cjs/dockview/moduleContracts.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Service + host interfaces for the pluggable feature modules. Core references
+ * only these interfaces — never a module's implementation — so each module is
+ * decoupled from core and independently testable / removable. Keep this file
+ * implementation-free.
+ */
+import { IDisposable } from '../lifecycle';
+import { Event } from '../events';
+import { DroptargetOverlayModel, Position } from '../dnd/droptarget';
+import { IDragGhostSpec } from '../dnd/backend';
+import { DockviewApi } from '../api/component.api';
+import { DockviewGroupPanel } from './dockviewGroupPanel';
+import { IDockviewPanel } from './dockviewPanel';
+import { ITabGroup } from './tabGroup';
+import { TabGroupColorPalette } from './tabGroupAccent';
+import { PopupService } from './components/popupService';
+import { DockviewComponentOptions } from './options';
+import { DockviewLayoutMutationEvent, GroupNavigationDirection } from './dockviewComponent';
+import { DockviewWillDropEvent } from './dockviewGroupPanelModel';
+import { GroupDragEvent, TabDragEvent } from './components/titlebar/tabsContainer';
+import { DockviewGroupDropLocation, DockviewTabGroupChangeEvent, DockviewTabGroupPanelChangeEvent, DockviewTabGroupCollapsedChangeEvent, DockviewWillShowOverlayLocationEvent } from './events';
+export interface IContextMenuHost {
+    readonly options: DockviewComponentOptions;
+    readonly api: DockviewApi;
+    readonly tabGroupColorPalette: TabGroupColorPalette;
+    getPopupServiceForGroup(group: DockviewGroupPanel): PopupService;
+}
+export interface IContextMenuService {
+    show(panel: IDockviewPanel, group: DockviewGroupPanel, event: MouseEvent): void;
+    showForChip(tabGroup: ITabGroup, group: DockviewGroupPanel, event: MouseEvent): void;
+}
+export interface ITabGroupChipsHost {
+    readonly onDidAddGroup: Event<DockviewGroupPanel>;
+    readonly onDidRemoveGroup: Event<DockviewGroupPanel>;
+    fireDidCreateTabGroup(event: DockviewTabGroupChangeEvent): void;
+    fireDidDestroyTabGroup(event: DockviewTabGroupChangeEvent): void;
+    fireDidAddPanelToTabGroup(event: DockviewTabGroupPanelChangeEvent): void;
+    fireDidRemovePanelFromTabGroup(event: DockviewTabGroupPanelChangeEvent): void;
+    fireDidTabGroupChange(event: DockviewTabGroupChangeEvent): void;
+    fireDidTabGroupCollapsedChange(event: DockviewTabGroupCollapsedChangeEvent): void;
+}
+export interface ITabGroupChipsService extends IDisposable {
+    /**
+     * Subscribe to the per-group tab-group events on the given group and
+     * re-fire them on the host's component-level emitters. Returns a
+     * disposable that detaches the subscriptions; intended to be bundled
+     * into the per-group CompositeDisposable so cleanup happens when the
+     * group is removed.
+     */
+    attachToGroup(group: DockviewGroupPanel): IDisposable;
+}
+export interface IAccessibilityHost {
+    /**
+     * The outermost dockview element (the shell, which also contains edge
+     * groups). A getter — it must resolve to the shell once that exists, not
+     * the inner gridview, or keydowns from edge groups are missed.
+     */
+    readonly rootElement: HTMLElement;
+    readonly options: DockviewComponentOptions;
+    readonly groups: DockviewGroupPanel[];
+    readonly activeGroup: DockviewGroupPanel | undefined;
+    readonly activePanel: IDockviewPanel | undefined;
+    /**
+     * The next / previous group in gridview (spatial) order, wrapping round —
+     * the one piece of navigation that needs the grid internals. All other
+     * focus logic lives in the service, using the public group API.
+     */
+    adjacentGroup(group: DockviewGroupPanel, reverse: boolean): DockviewGroupPanel | undefined;
+    /** The nearest grid group in a spatial direction — drives Alt+Arrow nav. */
+    adjacentGroupInDirection(group: DockviewGroupPanel, direction: GroupNavigationDirection): DockviewGroupPanel | undefined;
+    /** Fires before / after a structural layout change — used to restore focus on close. */
+    readonly onWillMutateLayout: Event<DockviewLayoutMutationEvent>;
+    readonly onDidMutateLayout: Event<DockviewLayoutMutationEvent>;
+    showDropPreview(group: DockviewGroupPanel, position: Position): IDisposable;
+    announce(message: string): void;
+    dockPanel(panel: IDockviewPanel, group: DockviewGroupPanel, position: Position): void;
+}
+export interface IAccessibilityService extends IDisposable {
+}
+/**
+ * Marker for the advanced keyboard docking service (spatial group focus +
+ * keyboard move mode). Self-driven; the component never calls into it.
+ */
+export interface IKeyboardDockingService extends IDisposable {
+}
+export interface IAdvancedDnDHost {
+    readonly options: DockviewComponentOptions;
+    readonly api: DockviewApi;
+    fireWillDragPanel(event: TabDragEvent): void;
+    fireWillDragGroup(event: GroupDragEvent): void;
+    fireWillDrop(event: DockviewWillDropEvent): void;
+    fireWillShowOverlay(event: DockviewWillShowOverlayLocationEvent): void;
+}
+export interface IAdvancedDnDService extends IDisposable {
+    dispatchWillDragPanel(event: TabDragEvent): void;
+    dispatchWillDragGroup(event: GroupDragEvent): void;
+    dispatchWillDrop(event: DockviewWillDropEvent): void;
+    dispatchWillShowOverlay(event: DockviewWillShowOverlayLocationEvent): void;
+    /**
+     * Resolve the custom group drag ghost from
+     * `createGroupDragGhostComponent`, or `undefined` when no factory is
+     * configured (the caller then renders the default chip). Returning
+     * `undefined` is also what happens when this module is absent.
+     */
+    buildGroupDragGhost(group: DockviewGroupPanel): IDragGhostSpec | undefined;
+    /**
+     * Resolve the app-supplied overlay model for a group drop target via the
+     * `dropOverlayModel` option, or `undefined` to keep the target's default.
+     */
+    resolveOverlayModel(location: DockviewGroupDropLocation, group?: DockviewGroupPanel): DroptargetOverlayModel | undefined;
+    /**
+     * Render the drop-preview overlay on a group at `position` — the same
+     * overlay a mouse drag shows — without a live drag. Returns a disposable
+     * that clears it. Used by keyboard docking so keyboard and mouse previews
+     * are identical (single source of truth). Commit the move via the public
+     * `api.moveGroupOrPanel({ to: { group, position } })`.
+     */
+    showPreviewOverlay(group: DockviewGroupPanel, position: Position): IDisposable;
+}

package/dist/cjs/dockview/moduleContracts.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/dockview/modules.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Internal module system for dockview.
+ *
+ * Modules are feature bundles that register services into the dockview
+ * component. `registerModules(...)` is the one public entry point — it lets a
+ * sibling package contribute modules that `DockviewComponent` picks up at
+ * construction. The richer opt-in surface (a per-component `modules` option,
+ * framework wrappers) is still reserved for a future version; the module
+ * authoring API (`defineModule`, the service contracts) remains internal.
+ */
+import { IDisposable } from '../lifecycle';
+import { IFloatingGroupService } from './floatingGroupService';
+import { IPopoutWindowService } from './popoutWindowService';
+import { IWatermarkService } from './watermarkService';
+import { IEdgeGroupService } from './edgeGroupService';
+import { IRootDropTargetService } from './rootDropTargetService';
+import { IHeaderActionsService } from './headerActionsService';
+import { ILiveRegionService } from './liveRegionService';
+import { IAccessibilityService, IAdvancedDnDService, IContextMenuService, IKeyboardDockingService, ITabGroupChipsService } from './moduleContracts';
+export interface ServiceCollection {
+    floatingGroupService?: IFloatingGroupService;
+    popoutWindowService?: IPopoutWindowService;
+    watermarkService?: IWatermarkService;
+    edgeGroupService?: IEdgeGroupService;
+    tabGroupChipsService?: ITabGroupChipsService;
+    contextMenuService?: IContextMenuService;
+    rootDropTargetService?: IRootDropTargetService;
+    headerActionsService?: IHeaderActionsService;
+    advancedDnDService?: IAdvancedDnDService;
+    liveRegionService?: ILiveRegionService;
+    accessibilityService?: IAccessibilityService;
+    keyboardDockingService?: IKeyboardDockingService;
+}
+export interface DockviewModule<THost = unknown> {
+    moduleName: string;
+    services?: Record<string, (host: THost) => unknown>;
+    /**
+     * Optional post-construct hook called once after the host is fully
+     * constructed and all module services are instantiated. Use this to
+     * subscribe to host events — the returned disposable runs at host
+     * teardown. Components don't need to call into the service from event
+     * handlers; the module owns its own reactivity.
+     */
+    init?: (host: THost, services: ServiceCollection) => IDisposable;
+    dependsOn?: DockviewModule<any>[];
+}
+/**
+ * Typed helper for defining a module. Enforces that the factory's return
+ * type matches the slot in ServiceCollection at compile time, replacing
+ * the manual cast each module file would otherwise need.
+ */
+export declare function defineModule<K extends keyof ServiceCollection, THost>(config: {
+    name: string;
+    serviceKey: K;
+    create: (host: THost) => NonNullable<ServiceCollection[K]>;
+    init?: (host: THost, service: NonNullable<ServiceCollection[K]>) => IDisposable;
+    dependsOn?: DockviewModule<any>[];
+}): DockviewModule<THost>;
+/**
+ * For tests — clears the once-per-key dedup cache used by `assertModule`.
+ */
+export declare function _resetMissingModuleWarnings(): void;
+/**
+ * Returns the service if its module is registered, otherwise logs a
+ * deduplicated console error and returns `undefined`. Modelled on AG Grid's
+ * `assertModuleRegistered`: missing modules never throw — they degrade the
+ * affected feature to a no-op so consuming applications don't crash in
+ * production.
+ *
+ * Use at public-API entry points where the caller wants to surface which
+ * module is missing. For internal/lifecycle paths, plain `?.` chaining on
+ * the service slot is preferred — no log, just a silent no-op.
+ */
+export declare function assertModule<T>(service: T | undefined, moduleName: string, context?: string): T | undefined;
+export declare class ModuleRegistry<THost> implements IDisposable {
+    private readonly _modules;
+    private readonly _services;
+    private readonly _initDisposables;
+    get services(): ServiceCollection;
+    register<H>(module: DockviewModule<H>): void;
+    initialize(host: THost): void;
+    postConstruct(host: THost): void;
+    has(moduleName: string): boolean;
+    dispose(): void;
+}
+/**
+ * Register modules globally. Idempotent per `moduleName` — registering the
+ * same module twice is a no-op. Intended to be called once at import time by
+ * the package that bundles a given set of modules.
+ */
+export declare function registerModules(modules: DockviewModule<any>[]): void;
+/**
+ * Returns the globally-registered modules (a copy). `DockviewComponent` reads
+ * this to extend its built-in module set.
+ */
+export declare function getRegisteredModules(): DockviewModule<any>[];
+/**
+ * For tests — clears the global module registry.
+ */
+export declare function clearRegisteredModules(): void;
+/**
+ * Called once by the `dockview` package on import, solely so `dockview-core`
+ * can warn when it is used directly (see above). Not used for anything else.
+ */
+export declare function markDockviewPackageLoaded(): void;
+/**
+ * Whether the `dockview` package has been loaded in this process. Used only to
+ * gate the "don't use dockview-core directly" developer warning.
+ */
+export declare function isDockviewPackageLoaded(): boolean;