@elementor/editor-floating-panels 4.3.0-970

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @elementor/editor-floating-panels
+
+## 4.3.0
+
+- Initial release. Generic floating panels framework for the Elementor Editor.

package/README.md

@@ -0,0 +1,117 @@
+# Editor Floating Panels
+
+A generic floating panel framework for the Elementor Editor that provides the primitives for rendering panels on the canvas. The panels can be dragged and resized freely within the viewport, independent of any specific feature concern.
+
+The panes are persisted and survive reloads. The state stores open/closed, position, size, and z-index in `localStorage`.
+
+## Usage
+
+```ts
+import {
+	createFloatingPanel,
+	init,
+	registerFloatingPanel,
+
+	FloatingPanelBody,
+	FloatingPanelFooter,
+	FloatingPanelHeader,
+} from '@elementor/editor-floating-panels';
+
+init();
+
+const myPanel = createFloatingPanel( {
+	id: 'my-panel',
+	title: 'My Panel',
+	icon: MyIcon,
+	component: MyPanelComponent,
+	isDraggable: true,
+	isResizable: true,
+	defaults: {
+		width: 320,
+		height: 480,
+		minWidth: 240,
+		minHeight: 320,
+		corner: 'block-start-inline-start',
+		initialPosition: {
+			insetBlockStart: 80,
+			insetInlineStart: 200
+		},
+	},
+} );
+
+registerFloatingPanel( myPanel.panel );
+
+function MyPanelComponent() {
+	return (
+		<>
+			<FloatingPanelHeader
+				panelId="my-panel"
+				title="My Panel"
+				actions={ [ /* ... */ ] }
+			/>
+			<FloatingPanelBody>
+				{ /* ... */ }
+			</FloatingPanelBody>
+			<FloatingPanelFooter>
+				{ /* ... */ }
+			</FloatingPanelFooter>
+		</>
+	);
+}
+```
+
+### `isDraggable`
+
+When `isDraggable` is `true`, the panel header acts as a drag handle — the user can reposition the panel freely. When `false` (the default), the header renders without drag interaction and the panel stays at its `initialPosition` (see `defaults.initialPosition`).
+
+Programmatic positioning via `setPosition` from `useFloatingPanelActions` works regardless of `isDraggable`.
+
+### `isResizable`
+
+When `isResizable` is `true`, edge and corner resize handles render on the panel — the user can resize freely within the viewport and the minimums defined in `defaults` (`minWidth` / `minHeight`). When `false` (the default), no resize handles render and the panel stays at its declared or persisted size.
+
+Programmatic sizing via `setSize` from `useFloatingPanelActions` works regardless of `isResizable`.
+
+### `defaults`
+
+`defaults` is required and defines the panel's initial dimensions and (optionally) its initial position.
+
+| Field | Purpose |
+| ----- | ------- |
+| `width` | Initial panel width (in pixels). |
+| `height` | Initial panel height (in pixels). |
+| `minWidth` | Minimum width the panel can be resized to. |
+| `minHeight` | Minimum height the panel can be resized to. |
+| `corner` (optional) | Viewport corner anchor. One of `block-start-inline-start`, `block-start-inline-end`, `block-end-inline-start`, `block-end-inline-end`. Default: `block-start-inline-start`. |
+| `initialPosition` (optional) | Offsets on the two insets that match `corner`. Used only when no persisted position exists. Other keys are ignored. |
+
+Sizes use physical names (`width`/`height`) because Elementor renders in horizontal writing mode only. Position uses logical inset names because it is direction-sensitive (e.g. RTL).
+
+`LogicalPosition` stores all four insets (`insetInlineStart`, `insetInlineEnd`, `insetBlockStart`, `insetBlockEnd`). Only the pair matching `corner` is used for rendering and interaction; inactive insets are `0`.
+
+| `corner` | Active insets | Default `initialPosition` |
+| --- | --- | --- |
+| `block-start-inline-start` | `insetInlineStart`, `insetBlockStart` | `{ insetInlineStart: 24, insetBlockStart: 80 }` |
+| `block-start-inline-end` | `insetInlineEnd`, `insetBlockStart` | `{ insetInlineEnd: 24, insetBlockStart: 80 }` |
+| `block-end-inline-start` | `insetInlineStart`, `insetBlockEnd` | `{ insetInlineStart: 24, insetBlockEnd: 80 }` |
+| `block-end-inline-end` | `insetInlineEnd`, `insetBlockEnd` | `{ insetInlineEnd: 24, insetBlockEnd: 80 }` |
+
+Example for bottom-right anchoring:
+
+```ts
+defaults: {
+	width: 360,
+	height: 600,
+	minWidth: 280,
+	minHeight: 400,
+	corner: 'block-end-inline-end',
+	initialPosition: {
+		insetBlockEnd: 80,
+		insetInlineEnd: 24
+	},
+}
+```
+
+When persisted state exists, the persisted `position`, `corner`, and `size` override `initialPosition`, `corner`, `width`, and `height`. The resize minimums (`minWidth`/`minHeight`) are always derived from `defaults`.
+
+Call `init()` once during editor bootstrap, **before** any `createFloatingPanel` call, to register the slice, sync persisted state, and mount the host into the editor's top location.

package/dist/index.d.mts

@@ -0,0 +1,159 @@
+import * as React from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { BoxProps } from '@elementor/ui';
+
+type PanelCorner = 'block-start-inline-start' | 'block-start-inline-end' | 'block-end-inline-start' | 'block-end-inline-end';
+
+type LogicalSize = {
+    inlineSize: number;
+    blockSize: number;
+};
+type LogicalPosition = {
+    insetInlineStart: number;
+    insetInlineEnd: number;
+    insetBlockStart: number;
+    insetBlockEnd: number;
+};
+/**
+ * Public API for declaring a floating panel's initial dimensions.
+ *
+ * Sizes use physical names (width/height) intentionally — Elementor renders
+ * in horizontal writing mode only, so these are equivalent to logical
+ * inline-size/block-size. Positioning continues to use logical names
+ * because position is genuinely direction-sensitive.
+ *
+ * If multi-writing-mode support is ever needed, replace these fields with
+ * `size: LogicalSize` and `minSize: LogicalSize` and update the store's
+ * register reducer.
+ */
+type FloatingPanelDefaults = {
+    width: number;
+    height: number;
+    minWidth: number;
+    minHeight: number;
+    corner?: PanelCorner;
+    initialPosition?: Partial<LogicalPosition>;
+};
+type FloatingPanelHeaderAction = {
+    id: string;
+    icon: ComponentType;
+    label: string;
+    onClick?: () => void;
+    disabled?: boolean;
+};
+type FloatingPanelDeclaration = {
+    id: string;
+    title: string;
+    icon: ComponentType;
+    component: ComponentType;
+    isDraggable?: boolean;
+    isResizable?: boolean;
+    defaults: FloatingPanelDefaults;
+};
+type FloatingPanelState = {
+    isOpen: boolean;
+    zIndex: number;
+    size: LogicalSize;
+    corner: PanelCorner;
+    position: LogicalPosition;
+};
+
+declare function createFloatingPanel(declaration: FloatingPanelDeclaration): {
+    panel: FloatingPanelDeclaration;
+    useFloatingPanelStatus: () => {
+        isOpen: boolean;
+        corner: PanelCorner;
+        position: LogicalPosition;
+        size: LogicalSize;
+    };
+    useFloatingPanelActions: () => {
+        open: () => void;
+        close: () => {
+            payload: string;
+            type: "floatingPanels/close";
+        };
+        toggle: () => void | {
+            payload: string;
+            type: "floatingPanels/close";
+        };
+        setPosition: (position: LogicalPosition) => {
+            payload: {
+                id: string;
+                position: LogicalPosition;
+            };
+            type: "floatingPanels/setPosition";
+        };
+        setSize: (size: LogicalSize) => {
+            payload: {
+                id: string;
+                size: LogicalSize;
+            };
+            type: "floatingPanels/setSize";
+        };
+        focus: () => {
+            payload: string;
+            type: "floatingPanels/bringToFront";
+        };
+    };
+};
+declare function registerFloatingPanel(declaration: Pick<FloatingPanelDeclaration, 'id' | 'component'>): void;
+
+type Props$1 = {
+    children: ReactNode;
+};
+declare function FloatingPanel({ children }: Props$1): React.JSX.Element;
+
+declare function FloatingPanelBody(props: BoxProps): React.JSX.Element;
+
+declare function FloatingPanelFooter({ children, sx, ...props }: BoxProps): React.JSX.Element;
+
+type Props = {
+    panelId: string;
+    title: string;
+    icon?: ComponentType;
+    actions?: FloatingPanelHeaderAction[];
+};
+declare function FloatingPanelHeader({ panelId, title, icon: Icon, actions }: Props): React.JSX.Element;
+
+declare function useFloatingPanelActions(id: string): {
+    open: () => void;
+    close: () => {
+        payload: string;
+        type: "floatingPanels/close";
+    };
+    toggle: () => void | {
+        payload: string;
+        type: "floatingPanels/close";
+    };
+    setPosition: (position: LogicalPosition) => {
+        payload: {
+            id: string;
+            position: LogicalPosition;
+        };
+        type: "floatingPanels/setPosition";
+    };
+    setSize: (size: LogicalSize) => {
+        payload: {
+            id: string;
+            size: LogicalSize;
+        };
+        type: "floatingPanels/setSize";
+    };
+    focus: () => {
+        payload: string;
+        type: "floatingPanels/bringToFront";
+    };
+};
+
+declare function useFloatingPanelStatus(id: string): {
+    isOpen: boolean;
+    corner: PanelCorner;
+    position: LogicalPosition;
+    size: LogicalSize;
+};
+
+declare function useFloatingPanelZIndex(panelId: string): number;
+
+declare function init(): void;
+
+export { FloatingPanel, FloatingPanelBody, type FloatingPanelDeclaration, type FloatingPanelDefaults, FloatingPanelFooter, FloatingPanelHeader, type FloatingPanelHeaderAction, type FloatingPanelState, type LogicalPosition, type LogicalSize, type PanelCorner, createFloatingPanel, init, registerFloatingPanel, useFloatingPanelActions, useFloatingPanelStatus, useFloatingPanelZIndex };

package/dist/index.d.ts

@@ -0,0 +1,159 @@
+import * as React from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { BoxProps } from '@elementor/ui';
+
+type PanelCorner = 'block-start-inline-start' | 'block-start-inline-end' | 'block-end-inline-start' | 'block-end-inline-end';
+
+type LogicalSize = {
+    inlineSize: number;
+    blockSize: number;
+};
+type LogicalPosition = {
+    insetInlineStart: number;
+    insetInlineEnd: number;
+    insetBlockStart: number;
+    insetBlockEnd: number;
+};
+/**
+ * Public API for declaring a floating panel's initial dimensions.
+ *
+ * Sizes use physical names (width/height) intentionally — Elementor renders
+ * in horizontal writing mode only, so these are equivalent to logical
+ * inline-size/block-size. Positioning continues to use logical names
+ * because position is genuinely direction-sensitive.
+ *
+ * If multi-writing-mode support is ever needed, replace these fields with
+ * `size: LogicalSize` and `minSize: LogicalSize` and update the store's
+ * register reducer.
+ */
+type FloatingPanelDefaults = {
+    width: number;
+    height: number;
+    minWidth: number;
+    minHeight: number;
+    corner?: PanelCorner;
+    initialPosition?: Partial<LogicalPosition>;
+};
+type FloatingPanelHeaderAction = {
+    id: string;
+    icon: ComponentType;
+    label: string;
+    onClick?: () => void;
+    disabled?: boolean;
+};
+type FloatingPanelDeclaration = {
+    id: string;
+    title: string;
+    icon: ComponentType;
+    component: ComponentType;
+    isDraggable?: boolean;
+    isResizable?: boolean;
+    defaults: FloatingPanelDefaults;
+};
+type FloatingPanelState = {
+    isOpen: boolean;
+    zIndex: number;
+    size: LogicalSize;
+    corner: PanelCorner;
+    position: LogicalPosition;
+};
+
+declare function createFloatingPanel(declaration: FloatingPanelDeclaration): {
+    panel: FloatingPanelDeclaration;
+    useFloatingPanelStatus: () => {
+        isOpen: boolean;
+        corner: PanelCorner;
+        position: LogicalPosition;
+        size: LogicalSize;
+    };
+    useFloatingPanelActions: () => {
+        open: () => void;
+        close: () => {
+            payload: string;
+            type: "floatingPanels/close";
+        };
+        toggle: () => void | {
+            payload: string;
+            type: "floatingPanels/close";
+        };
+        setPosition: (position: LogicalPosition) => {
+            payload: {
+                id: string;
+                position: LogicalPosition;
+            };
+            type: "floatingPanels/setPosition";
+        };
+        setSize: (size: LogicalSize) => {
+            payload: {
+                id: string;
+                size: LogicalSize;
+            };
+            type: "floatingPanels/setSize";
+        };
+        focus: () => {
+            payload: string;
+            type: "floatingPanels/bringToFront";
+        };
+    };
+};
+declare function registerFloatingPanel(declaration: Pick<FloatingPanelDeclaration, 'id' | 'component'>): void;
+
+type Props$1 = {
+    children: ReactNode;
+};
+declare function FloatingPanel({ children }: Props$1): React.JSX.Element;
+
+declare function FloatingPanelBody(props: BoxProps): React.JSX.Element;
+
+declare function FloatingPanelFooter({ children, sx, ...props }: BoxProps): React.JSX.Element;
+
+type Props = {
+    panelId: string;
+    title: string;
+    icon?: ComponentType;
+    actions?: FloatingPanelHeaderAction[];
+};
+declare function FloatingPanelHeader({ panelId, title, icon: Icon, actions }: Props): React.JSX.Element;
+
+declare function useFloatingPanelActions(id: string): {
+    open: () => void;
+    close: () => {
+        payload: string;
+        type: "floatingPanels/close";
+    };
+    toggle: () => void | {
+        payload: string;
+        type: "floatingPanels/close";
+    };
+    setPosition: (position: LogicalPosition) => {
+        payload: {
+            id: string;
+            position: LogicalPosition;
+        };
+        type: "floatingPanels/setPosition";
+    };
+    setSize: (size: LogicalSize) => {
+        payload: {
+            id: string;
+            size: LogicalSize;
+        };
+        type: "floatingPanels/setSize";
+    };
+    focus: () => {
+        payload: string;
+        type: "floatingPanels/bringToFront";
+    };
+};
+
+declare function useFloatingPanelStatus(id: string): {
+    isOpen: boolean;
+    corner: PanelCorner;
+    position: LogicalPosition;
+    size: LogicalSize;
+};
+
+declare function useFloatingPanelZIndex(panelId: string): number;
+
+declare function init(): void;
+
+export { FloatingPanel, FloatingPanelBody, type FloatingPanelDeclaration, type FloatingPanelDefaults, FloatingPanelFooter, FloatingPanelHeader, type FloatingPanelHeaderAction, type FloatingPanelState, type LogicalPosition, type LogicalSize, type PanelCorner, createFloatingPanel, init, registerFloatingPanel, useFloatingPanelActions, useFloatingPanelStatus, useFloatingPanelZIndex };