@onerjs/shared-ui-components 8.48.3 → 8.48.5

package/modularTool/services/shellService.d.ts

@@ -0,0 +1,256 @@
+import { type ComponentType } from "react";
+import { type IDisposable, type Nullable } from "@onerjs/core/index.js";
+import { type IService, type ServiceDefinition } from "../modularity/serviceDefinition.js";
+import { type SettingDescriptor } from "./settingsStore.js";
+/**
+ * Setting descriptor for persisting side pane dock location overrides.
+ */
+export declare const SidePaneDockOverridesSettingDescriptor: SettingDescriptor<Record<string, Readonly<{
+    horizontalLocation: HorizontalLocation;
+    verticalLocation: VerticalLocation;
+}> | undefined>>;
+/**
+ * Setting descriptor for persisting the left side pane width adjustment.
+ */
+export declare const LeftSidePaneWidthAdjustSettingDescriptor: SettingDescriptor<number>;
+/**
+ * Setting descriptor for persisting the left side pane height adjustment.
+ */
+export declare const LeftSidePaneHeightAdjustSettingDescriptor: SettingDescriptor<number>;
+/**
+ * Setting descriptor for persisting the right side pane width adjustment.
+ */
+export declare const RightSidePaneWidthAdjustSettingDescriptor: SettingDescriptor<number>;
+/**
+ * Setting descriptor for persisting the right side pane height adjustment.
+ */
+export declare const RightSidePaneHeightAdjustSettingDescriptor: SettingDescriptor<number>;
+/**
+ * Represents a horizontal location in the shell layout.
+ */
+export type HorizontalLocation = "left" | "right";
+/**
+ * Represents a vertical location in the shell layout.
+ */
+export type VerticalLocation = "top" | "bottom";
+type TeachingMomentInfo = boolean | {
+    readonly title: string;
+    readonly description: string;
+};
+/**
+ * Describes an item that can be added to one of the shell's toolbars.
+ */
+export type ToolbarItemDefinition = {
+    /**
+     * A unique key for the toolbar item.
+     */
+    key: string;
+    /**
+     * The component to render for the toolbar item.
+     */
+    component: ComponentType;
+    /**
+     * An optional order for the toolbar item, relative to other items.
+     * Defaults to 0.
+     */
+    order?: number;
+    /**
+     * The horizontal location of the toolbar item.
+     * Can be either "left" or "right".
+     * In "compact" toolbar mode, "left" and "right" mean the "compact" toolbars at the top/bottom of the left/right side panes.
+     * In "full" toolbar mode, "left" and "right" mean the left side and right side of the full width toolbars above/below the side panes.
+     */
+    horizontalLocation: HorizontalLocation;
+    /**
+     * The vertical location of the toolbar item.
+     * Can be either "top" or "bottom".
+     */
+    verticalLocation: VerticalLocation;
+    /**
+     * An optional display name for the toolbar item, used for teaching moments, tooltips, etc.
+     */
+    displayName?: string;
+    /**
+     * An optional teaching moment info. The default assumes the toolbar item was added by an extension and provides a generic title and description based on the display name or id, which is helpful for discoverability of new items.
+     * Set this to false to suppress the teaching moment, which may be desirable for built in items or items that are added in a non-dynamic way.
+     * Set it to an object with a title and description to provide a custom teaching moment, which may be desirable if the generic title and description are not sufficient.
+     * Teaching moments are more helpful for dynamically added items, possibly from extensions.
+     */
+    teachingMoment?: TeachingMomentInfo;
+};
+/**
+ * Describes a side pane that can be added to the shell's left or right side.
+ */
+export type SidePaneDefinition = {
+    /**
+     * A unique key for the side pane.
+     */
+    key: string;
+    /**
+     * An icon component to render for the pane tab.
+     */
+    icon: ComponentType;
+    /**
+     * The component to render for the side pane's content.
+     */
+    content: ComponentType;
+    /**
+     * An optional order for the side pane, relative to other panes.
+     * Defaults to 0.
+     */
+    order?: number;
+    /**
+     * The horizontal location of the side pane.
+     * Can be either "left" or "right".
+     */
+    horizontalLocation: HorizontalLocation;
+    /**
+     * The vertical location of the side pane.
+     * Can be either "top" or "bottom".
+     */
+    verticalLocation: VerticalLocation;
+    /**
+     * The title of the side pane, displayed as a standardized header at the top of the pane.
+     */
+    title: string;
+    /**
+     * An optional teaching moment info. The default assumes the side pane was added by an extension and provides a generic title and description based on the display name or id, which is helpful for discoverability of new items.
+     * Set this to false to suppress the teaching moment, which may be desirable for built in items or items that are added in a non-dynamic way.
+     * Set it to an object with a title and description to provide a custom teaching moment, which may be desirable if the generic title and description are not sufficient.
+     * Teaching moments are more helpful for dynamically added panes, possibly from extensions.
+     */
+    teachingMoment?: TeachingMomentInfo;
+    /**
+     * Keep the pane mounted even when it is not visible. This is useful if you don't want the
+     * user to lose the complex visual state when switching between tabs.
+     */
+    keepMounted?: boolean;
+};
+type RegisteredSidePane = {
+    readonly key: string;
+    select(): void;
+};
+type SidePaneContainer = {
+    readonly isDocked: boolean;
+    dock(): void;
+    undock(): void;
+    readonly isCollapsed: boolean;
+    collapse(): void;
+    expand(): void;
+};
+/**
+ * Describes content that can be added to the shell's central area (between the side panes and toolbars - e.g. the main content).
+ */
+export type CentralContentDefinition = {
+    /**
+     * A unique key for the central content.
+     */
+    key: string;
+    /**
+     * The component to render for the central content.
+     */
+    component: ComponentType;
+    /**
+     * An optional order for content, relative to other central content.
+     * Defaults to 0.
+     */
+    order?: number;
+};
+/**
+ * The unique identity symbol for the root component service.
+ */
+export declare const RootComponentServiceIdentity: unique symbol;
+/**
+ * Exposes a top level component that should be rendered as the React root.
+ */
+export interface IRootComponentService extends IService<typeof RootComponentServiceIdentity> {
+    /**
+     * The root component that should be rendered as the React root.
+     */
+    readonly rootComponent: ComponentType;
+}
+/**
+ * The unique identity symbol for the shell service.
+ */
+export declare const ShellServiceIdentity: unique symbol;
+/**
+ * Provides a shell for the application, including toolbars, side panes, and central content.
+ * This service allows adding toolbar items, side panes, and central content dynamically.
+ */
+export interface IShellService extends IService<typeof ShellServiceIdentity> {
+    /**
+     * Adds a new item to one of the shell's toolbars.
+     * @param item Defines the item to add.
+     */
+    addToolbarItem(item: Readonly<ToolbarItemDefinition>): IDisposable;
+    /**
+     * Adds a new side pane to the shell.
+     * @param pane Defines the side pane to add.
+     */
+    addSidePane(pane: Readonly<SidePaneDefinition>): IDisposable;
+    /**
+     * Adds new central content to the shell.
+     * @param content Defines the content area to add.
+     */
+    addCentralContent(content: Readonly<CentralContentDefinition>): IDisposable;
+    /**
+     * The left side pane container.
+     */
+    readonly leftSidePaneContainer: Nullable<SidePaneContainer>;
+    /**
+     * The right side pane container.
+     */
+    readonly rightSidePaneContainer: Nullable<SidePaneContainer>;
+    /**
+     * The side panes currently present in the shell.
+     */
+    readonly sidePanes: readonly RegisteredSidePane[];
+}
+type ToolbarMode = "full" | "compact";
+/**
+ * Options for configuring the shell service.
+ */
+export type ShellServiceOptions = {
+    /**
+     * The default width of the left side pane.
+     */
+    leftPaneDefaultWidth?: number;
+    /**
+     * The minimum width of the left side pane.
+     */
+    leftPaneMinWidth?: number;
+    /**
+     * The default width of the right side pane.
+     */
+    rightPaneDefaultWidth?: number;
+    /**
+     * The minimum width of the right side pane.
+     */
+    rightPaneMinWidth?: number;
+    /**
+     * The mode of the toolbars.
+     * Can be either "full" (default) or "compact".
+     * In "full" mode, toolbars are displayed above and below the side panes.
+     * In "compact" mode, toolbars are displayed at the top and bottom of the left and right side panes.
+     */
+    toolbarMode?: ToolbarMode;
+    /**
+     * Whether the left side pane should start collapsed. Default is false.
+     */
+    leftPaneDefaultCollapsed?: boolean;
+    /**
+     * Whether the right side pane should start collapsed. Default is false.
+     */
+    rightPaneDefaultCollapsed?: boolean;
+    /**
+     * A function that can remap the default location of side panes.
+     * @param sidePane The side pane to remap.
+     * @returns The new location for the side pane.
+     */
+    sidePaneRemapper?: (sidePane: Readonly<SidePaneDefinition>) => Nullable<{
+        horizontalLocation: HorizontalLocation;
+        verticalLocation: VerticalLocation;
+    }>;
+};
+export declare function MakeShellServiceDefinition({ leftPaneDefaultWidth, leftPaneMinWidth, rightPaneDefaultWidth, rightPaneMinWidth, leftPaneDefaultCollapsed, rightPaneDefaultCollapsed, toolbarMode, sidePaneRemapper, }?: ShellServiceOptions): ServiceDefinition<[IShellService, IRootComponentService], []>;
+export {};