@vcmap/ui 5.1.8 → 5.2.1

package/src/manager/panel/panelHelper.js

@@ -0,0 +1,272 @@
+import {
+  PanelLocation,
+  getPanelPosition,
+  setPanelPosition,
+  DefaultPanelPositions,
+} from './panelManager.js';
+
+/**
+ *
+ * @type {Partial<import("./panelManager.js").PanelPosition>}
+ */
+export const DefaultMainPanelPosition = {
+  top: '0px',
+  left: '0px',
+  right: '0px',
+  bottom: '0px',
+  width: '100%',
+  minWidth: '10%',
+  minHeight: '25%',
+};
+
+/**
+ * @typedef {Object} NumberPanelPosition
+ * @property {number?} left - The left CSS property participates in specifying the horizontal position of a panel.
+ * @property {number?} top - The top CSS property participates in specifying the vertical position of a panel.
+ * @property {number?} right - The right CSS property participates in specifying the horizontal position of a panel.
+ * @property {number?} bottom - The bottom CSS property participates in specifying the vertical position of a panel.
+ * @property {number} width - The width CSS property sets an element's width.
+ * @property {number} height - The height CSS property sets an element's height.
+ * @property {number} maxHeight - The maxHeight CSS property sets an element's maximal height.
+ * @property {number} maxWidth - The maxWidth CSS property sets an element's maximal width.
+ * @property {number} minHeight - The minHeight CSS property sets an element's minimal height.
+ * @property {number} minWidth - The minWidth CSS property sets an element's minimal width.
+ */
+/**
+ * Parses a position to numeric percentage value (0-100). Non-numeric values return undefined.
+ * @param {string|number|undefined} pos
+ * @param {string} key - one of PanelPosition keys
+ * @param {DOMRect} targetSize - size of the current target
+ * @returns {number|undefined}
+ */
+export function posToRelativeTarget(pos, key, targetSize) {
+  if (typeof pos === 'string') {
+    if (pos.match(/^-?\d+\.?\d*px$/)) {
+      const scalar = [
+        'bottom',
+        'top',
+        'height',
+        'minHeight',
+        'maxHeight',
+      ].includes(key)
+        ? targetSize?.height
+        : targetSize?.width;
+      return (parseInt(pos, 10) / scalar) * 100;
+    } else if (targetSize && pos.match(/^-?\d+\.?\d*%$/)) {
+      return parseInt(pos, 10);
+    }
+    return undefined;
+  }
+  return pos;
+}
+
+/**
+ * Parses CSS position string properties to percentage numeric position properties
+ * @param {Partial<import("./panelManager.js").PanelPosition>} panelPosition
+ * @param {DOMRect} targetSize - the map's target size
+ * @returns {NumberPanelPosition}
+ */
+export function percentageFromPanelOptions(panelPosition, targetSize) {
+  const options = {};
+  Object.keys(panelPosition).forEach((key) => {
+    if (panelPosition[key] !== undefined) {
+      options[key] = posToRelativeTarget(panelPosition[key], key, targetSize);
+    }
+  });
+  return options;
+}
+
+/**
+ * Returns the maximum permitted width of a panel as a function of the main panel minWidth and other active side panel width
+ * @param {Partial<import("./panelManager.js").PanelPosition>} main
+ * @param {Partial<import("./panelManager.js").PanelPosition>} side
+ * @param {DOMRect} targetSize
+ * @returns {number}
+ */
+function getMaxWidth(main, side, targetSize) {
+  const maxWidth =
+    100 - posToRelativeTarget(main.minWidth, 'minWidth', targetSize);
+  if (side) {
+    return maxWidth - posToRelativeTarget(side.width, 'width', targetSize);
+  }
+  return maxWidth;
+}
+
+/**
+ * Updates side panel width and height
+ * Sets new main panel width depending on side panel
+ * @param {'left'|'right'} key
+ * @param {Partial<import("./panelManager.js").PanelComponent>} panel
+ * @param {Partial<NumberPanelPosition>} main
+ * @param {Partial<NumberPanelPosition>} side
+ * @param {DOMRect} targetSize
+ * @returns {Partial<import("./panelManager.js").PanelPosition>}
+ */
+function handleSidePanel(key, panel, main, side, targetSize) {
+  const toUpdate = {};
+  if (panel.state.resizable) {
+    const position = percentageFromPanelOptions(
+      getPanelPosition(panel),
+      targetSize,
+    );
+    if (side.maxWidth !== position.maxWidth) {
+      position.maxWidth = side.maxWidth;
+      toUpdate.maxWidth = `${side.maxWidth}%`;
+    }
+
+    const width = Math.max(
+      position.minWidth,
+      Math.min(position.width, position.maxWidth),
+    );
+    main.width -= width;
+    main[key] = width;
+
+    if (width !== position.width) {
+      toUpdate.width = `${width}%`;
+    }
+    if (position.height !== side.height) {
+      toUpdate.height = `${side.height}%`;
+    }
+  }
+  return toUpdate;
+}
+
+/**
+ * Updates size of main panel according to other active panels
+ * @param {import("./panelManager.js").default} panelManager
+ * @param {Partial<import("./panelManager.js").PanelComponent>} mainPanel
+ * @param {DOMRect} targetSize
+ * @param {string|undefined} resizeKey
+ */
+export function updatePanelSizes(
+  panelManager,
+  mainPanel,
+  targetSize,
+  resizeKey = undefined,
+) {
+  const defaultMain = percentageFromPanelOptions(
+    DefaultMainPanelPosition,
+    targetSize,
+  );
+  const defaultSide = {
+    height: 100,
+  };
+
+  if (panelManager.hasLocation(PanelLocation.BOTTOM)) {
+    const bottomPanelPosition = getPanelPosition(
+      panelManager.getLocation(PanelLocation.BOTTOM),
+    );
+    const bottomHeight = Math.max(
+      posToRelativeTarget(
+        bottomPanelPosition.minHeight,
+        'minHeight',
+        targetSize,
+      ),
+      Math.min(
+        posToRelativeTarget(bottomPanelPosition.height, 'height', targetSize),
+        posToRelativeTarget(
+          bottomPanelPosition.maxHeight,
+          'maxHeight',
+          targetSize,
+        ),
+      ),
+    );
+    defaultMain.bottom += bottomHeight;
+    defaultSide.height -= bottomHeight;
+  }
+
+  const leftPanel = panelManager.getLocation(PanelLocation.LEFT);
+  const leftWidth =
+    posToRelativeTarget(
+      getPanelPosition(leftPanel)?.width,
+      'width',
+      targetSize,
+    ) || 0;
+
+  const rightPanel = panelManager.getLocation(PanelLocation.RIGHT);
+  const rightWidth =
+    posToRelativeTarget(
+      getPanelPosition(rightPanel)?.width,
+      'width',
+      targetSize,
+    ) || 0;
+
+  const left = {
+    maxWidth: DefaultPanelPositions[PanelLocation.LEFT].maxWidth,
+  };
+
+  const right = {
+    maxWidth: DefaultPanelPositions[PanelLocation.RIGHT].maxWidth,
+  };
+
+  const maxWidth = getMaxWidth(defaultMain, undefined, targetSize);
+  if (
+    panelManager.hasLocation(PanelLocation.LEFT) &&
+    panelManager.hasLocation(PanelLocation.RIGHT) &&
+    leftWidth + rightWidth > maxWidth
+  ) {
+    if (leftWidth > maxWidth / 2 && rightWidth > maxWidth / 2) {
+      left.maxWidth = maxWidth / 2;
+      right.maxWidth = maxWidth / 2;
+    } else if (leftWidth > maxWidth / 2) {
+      left.maxWidth = maxWidth - rightWidth;
+      right.maxWidth = rightWidth;
+    } else if (rightWidth > maxWidth / 2) {
+      right.maxWidth = maxWidth - leftWidth;
+      left.maxWidth = leftWidth;
+    }
+  } else {
+    left.maxWidth = getMaxWidth(
+      defaultMain,
+      getPanelPosition(rightPanel),
+      targetSize,
+    );
+    right.maxWidth = getMaxWidth(
+      defaultMain,
+      getPanelPosition(leftPanel),
+      targetSize,
+    );
+  }
+
+  if (panelManager.hasLocation(PanelLocation.LEFT) && resizeKey !== 'right') {
+    const updatedLeft = handleSidePanel(
+      'left',
+      leftPanel,
+      defaultMain,
+      {
+        ...defaultSide,
+        ...left,
+      },
+      targetSize,
+    );
+    setPanelPosition(leftPanel, updatedLeft);
+  }
+  if (panelManager.hasLocation(PanelLocation.RIGHT) && resizeKey !== 'left') {
+    const updatedRight = handleSidePanel(
+      'right',
+      rightPanel,
+      defaultMain,
+      {
+        ...defaultSide,
+        ...right,
+      },
+      targetSize,
+    );
+    setPanelPosition(rightPanel, updatedRight);
+  }
+
+  const main = percentageFromPanelOptions(
+    getPanelPosition(mainPanel),
+    targetSize,
+  );
+
+  const toUpdate = Object.keys(defaultMain).reduce((acc, key) => {
+    if (defaultMain[key] !== main[key]) {
+      acc[key] = `${defaultMain[key]}%`;
+    }
+    return acc;
+  }, {});
+  if (Object.keys(toUpdate).length > 0) {
+    setPanelPosition(mainPanel, toUpdate);
+  }
+}

package/src/manager/panel/panelManager.d.ts

@@ -0,0 +1,338 @@
+/**
+ * @typedef {Object} PanelComponentOptions
+ * @property {string} [id] - Optional id, which will be set as HTML container ID. If not provided an uuid will be generated.
+ * @property {import("vue").Component} [component] Optional component to be rendered in the panel.
+ * @property {Partial<PanelState>} [state]
+ * @property {Partial<VerticalPanelPositionOptions|HorizontalPanelPositionOptions>} [position] Will be merged with default position for panel
+ * @property {Object} [props]
+ * @property {Object} [provides]
+ */
+/**
+ * @typedef {Object} PanelState
+ * @property {string} id
+ * @property {string|vcsAppSymbol} owner Owner of the panel, set by panelManager on add
+ * @property {PanelLocation} location Location of the panel, set by panelManager on add
+ * @property {boolean} [resizable=true] Whether size of panel can be adapted
+ * @property {Object<string, string>} [styles] Can be used to add additional styles to the root PanelComponent. Use Vue Style Bindings Object Syntax https://vuejs.org/v2/guide/class-and-style.html
+ * @property {Array<string>|Object<string,string>} [classes] Can be used to add additional classes to the root PanelComponent. Use Vue Class Bindings Syntax https://vuejs.org/v2/guide/class-and-style.html
+ */
+/**
+ * @typedef {Object} PanelComponent
+ * @property {string} id
+ * @property {import("vue").Component} component
+ * @property {Partial<PanelState>} state
+ * @property {Object} props
+ * @property {Object} provides
+ */
+/**
+ * @param {Partial<PanelComponent>} panelComponent
+ * @returns {PanelPosition|undefined}
+ */
+export function getPanelPosition(panelComponent: Partial<PanelComponent>): PanelPosition | undefined;
+/**
+ * @param {PanelComponent} panelComponent
+ * @param {Partial<PanelPosition>} panelPosition
+ */
+export function setPanelPosition(panelComponent: PanelComponent, panelPosition: Partial<PanelPosition>): void;
+export const panelLocationSymbol: unique symbol;
+export const panelPositionSymbol: unique symbol;
+/**
+ * *
+ */
+export type PanelLocation = string;
+export namespace PanelLocation {
+    let LEFT: string;
+    let RIGHT: string;
+    let BOTTOM: string;
+}
+/**
+ * *
+ */
+export type DefaultPanelPositions = Partial<PanelPosition>;
+/**
+ * @typedef {Object} VerticalPanelPositionOptions
+ * @property {string} [width] Can be a css position string (e.g. '320px' or '50%')
+ * @property {string} [maxWidth] Can be a css position string (e.g. '320px' or '50%')
+ * @property {string} [minWidth] Can be a css position string (e.g. '320px' or '50%')
+ */
+/**
+ * @typedef {Object} HorizontalPanelPositionOptions
+ * @property {string} [height] Can be a css position string (e.g. '320px' or '50%')
+ * @property {string} [maxHeight] Can be a css position string (e.g. '320px' or '50%')
+ * @property {string} [minHeight] Can be a css position string (e.g. '320px' or '50%')
+ */
+/**
+ * @typedef {Object} PanelPosition
+ * @property {string?} left - The left CSS property participates in specifying the horizontal position of a panel.
+ * @property {string?} top - The top CSS property participates in specifying the vertical position of a panel.
+ * @property {string?} right - The right CSS property participates in specifying the horizontal position of a panel.
+ * @property {string?} bottom - The bottom CSS property participates in specifying the vertical position of a panel.
+ * @property {string} width - The width CSS property sets an element's width.
+ * @property {string} height - The height CSS property sets an element's height.
+ * @property {string} maxHeight - The maxHeight CSS property sets an element's maximal height.
+ * @property {string} maxWidth - The maxWidth CSS property sets an element's maximal width.
+ * @property {string} minHeight - The minHeight CSS property sets an element's minimal height.
+ * @property {string} minWidth - The minWidth CSS property sets an element's minimal width.
+ */
+/**
+ * @readonly
+ * @enum {Partial<PanelPosition>}
+ * @private
+ */
+export const DefaultPanelPositions: {
+    [x: string]: {
+        left: string;
+        width: string;
+        minWidth: string;
+        height: string;
+        right?: undefined;
+        bottom?: undefined;
+        minHeight?: undefined;
+        maxHeight?: undefined;
+    } | {
+        right: string;
+        width: string;
+        minWidth: string;
+        height: string;
+        left?: undefined;
+        bottom?: undefined;
+        minHeight?: undefined;
+        maxHeight?: undefined;
+    } | {
+        bottom: string;
+        width: string;
+        height: string;
+        minHeight: string;
+        maxHeight: string;
+        left?: undefined;
+        minWidth?: undefined;
+        right?: undefined;
+    };
+};
+export default PanelManager;
+export type PanelComponentOptions = {
+    /**
+     * - Optional id, which will be set as HTML container ID. If not provided an uuid will be generated.
+     */
+    id?: string | undefined;
+    /**
+     * Optional component to be rendered in the panel.
+     */
+    component?: import("vue").Component<import("vue/types/options.js").DefaultData<never>, import("vue/types/options.js").DefaultMethods<never>, import("vue/types/options.js").DefaultComputed, import("vue/types/options.js").DefaultProps, {}> | undefined;
+    state?: Partial<PanelState> | undefined;
+    /**
+     * Will be merged with default position for panel
+     */
+    position?: Partial<VerticalPanelPositionOptions | HorizontalPanelPositionOptions> | undefined;
+    props?: Object | undefined;
+    provides?: Object | undefined;
+};
+export type PanelState = {
+    id: string;
+    /**
+     * Owner of the panel, set by panelManager on add
+     */
+    owner: string | symbol;
+    /**
+     * Location of the panel, set by panelManager on add
+     */
+    location: PanelLocation;
+    /**
+     * Whether size of panel can be adapted
+     */
+    resizable?: boolean | undefined;
+    /**
+     * Can be used to add additional styles to the root PanelComponent. Use Vue Style Bindings Object Syntax https://vuejs.org/v2/guide/class-and-style.html
+     */
+    styles?: {
+        [x: string]: string;
+    } | undefined;
+    /**
+     * Can be used to add additional classes to the root PanelComponent. Use Vue Class Bindings Syntax https://vuejs.org/v2/guide/class-and-style.html
+     */
+    classes?: string[] | {
+        [x: string]: string;
+    } | undefined;
+};
+export type PanelComponent = {
+    id: string;
+    component: import("vue").Component;
+    state: Partial<PanelState>;
+    props: Object;
+    provides: Object;
+};
+export type VerticalPanelPositionOptions = {
+    /**
+     * Can be a css position string (e.g. '320px' or '50%')
+     */
+    width?: string | undefined;
+    /**
+     * Can be a css position string (e.g. '320px' or '50%')
+     */
+    maxWidth?: string | undefined;
+    /**
+     * Can be a css position string (e.g. '320px' or '50%')
+     */
+    minWidth?: string | undefined;
+};
+export type HorizontalPanelPositionOptions = {
+    /**
+     * Can be a css position string (e.g. '320px' or '50%')
+     */
+    height?: string | undefined;
+    /**
+     * Can be a css position string (e.g. '320px' or '50%')
+     */
+    maxHeight?: string | undefined;
+    /**
+     * Can be a css position string (e.g. '320px' or '50%')
+     */
+    minHeight?: string | undefined;
+};
+export type PanelPosition = {
+    /**
+     * - The left CSS property participates in specifying the horizontal position of a panel.
+     */
+    left: string | null;
+    /**
+     * - The top CSS property participates in specifying the vertical position of a panel.
+     */
+    top: string | null;
+    /**
+     * - The right CSS property participates in specifying the horizontal position of a panel.
+     */
+    right: string | null;
+    /**
+     * - The bottom CSS property participates in specifying the vertical position of a panel.
+     */
+    bottom: string | null;
+    /**
+     * - The width CSS property sets an element's width.
+     */
+    width: string;
+    /**
+     * - The height CSS property sets an element's height.
+     */
+    height: string;
+    /**
+     * - The maxHeight CSS property sets an element's maximal height.
+     */
+    maxHeight: string;
+    /**
+     * - The maxWidth CSS property sets an element's maximal width.
+     */
+    maxWidth: string;
+    /**
+     * - The minHeight CSS property sets an element's minimal height.
+     */
+    minHeight: string;
+    /**
+     * - The minWidth CSS property sets an element's minimal width.
+     */
+    minWidth: string;
+};
+export type IPanelManager = import("../../vcsUiApp.js").VcsComponentManager<PanelComponent, PanelComponentOptions>;
+/**
+ * @typedef {import("../../vcsUiApp.js").VcsComponentManager<PanelComponent,PanelComponentOptions>} IPanelManager
+ */
+/**
+ * @class PanelManager
+ * @description Manages a set of Panels
+ * @implements {IPanelManager}
+ */
+declare class PanelManager implements IPanelManager {
+    /**
+     * @type {import("@vcmap/core").VcsEvent<PanelComponent>}
+     */
+    added: import("@vcmap/core").VcsEvent<PanelComponent>;
+    /**
+     * @type {import("@vcmap/core").VcsEvent<PanelComponent>}
+     */
+    removed: import("@vcmap/core").VcsEvent<PanelComponent>;
+    /**
+     * reactive ordered array of ids,
+     * @type {Array<string>}
+     */
+    componentIds: Array<string>;
+    /**
+     * @type {Map<PanelLocation, string>}
+     * @private
+     */
+    private _panelLocations;
+    /**
+     * @type {Map<string, PanelComponent>}
+     * @private
+     */
+    private _panelComponents;
+    /**
+     * @type {Map<string, PanelPosition>}
+     * @private
+     */
+    private _panelPositionsCache;
+    /**
+     * @param {string} id
+     * @returns {PanelComponent}
+     */
+    get(id: string): PanelComponent;
+    /**
+     * @param {string} id
+     * @returns {boolean}
+     */
+    has(id: string): boolean;
+    /**
+     *
+     * @param {PanelLocation} location
+     * @returns {PanelComponent}
+     */
+    getLocation(location: PanelLocation): PanelComponent;
+    /**
+     *
+     * @param {PanelLocation} location
+     * @returns {boolean}
+     */
+    hasLocation(location: PanelLocation): boolean;
+    /**
+     *
+     * @param {PanelLocation} location
+     */
+    removePanelAtLocation(location: PanelLocation): void;
+    /**
+     * @param {string} id
+     * @returns {Partial<PanelPosition>|undefined}
+     */
+    getCachedPosition(id: string): Partial<PanelPosition> | undefined;
+    /**
+     * removes a panel, Component will not be rendered anymore and will be destroyed. Add PanelComponent again
+     * to show the component again
+     * @param {string} id
+     */
+    remove(id: string): void;
+    /**
+     * Set width for LEFT and RIGHT or height for BOTTOM panels
+     * @param {string} id
+     * @param {VerticalPanelPositionOptions|HorizontalPanelPositionOptions} panelPositionOptions
+     */
+    setPanelPosition(id: string, panelPositionOptions: VerticalPanelPositionOptions | HorizontalPanelPositionOptions): void;
+    /**
+     * adds a panelComponent to the PanelManager and renders the Panel
+     * @param {PanelComponentOptions|PanelComponent} panelComponentOptions
+     * @param {string|symbol} owner pluginName or vcsAppSymbol
+     * @param {PanelLocation} location panel render position
+     * @returns {PanelComponent}
+     */
+    // @ts-ignore
+add(panelComponentOptions: PanelComponentOptions | PanelComponent, owner: string | symbol, location: PanelLocation): PanelComponent;
+    /**
+     * removes all panelComponents of a specific owner (plugin) and fires removed Events
+     * @param {string|vcsAppSymbol} owner
+     */
+    removeOwner(owner: string | symbol): void;
+    /**
+     * removes all panelComponents and fires removed Events
+     */
+    clear(): void;
+    /**
+     * destroys the panelManager;
+     */
+    destroy(): void;
+}