@zylem/editor 0.6.9 → 0.7.0

package/dist/zylem-editor.d.ts

@@ -3,120 +3,6 @@ import { LucideProps } from 'lucide-solid';
 import * as _zylem_bridge from '@zylem/bridge';
 import { BridgeDebugTool } from '@zylem/bridge';
 
-type EditorLauncherMode = 'floating' | 'hidden';
-
-/**
- * Configuration options for the ZylemEditorElement
- */
-interface ZylemEditorConfig {
-    /**
-     * External debug state to sync with.
-     * If provided, the editor will use this state instead of its internal state.
-     */
-    debugState?: any;
-    /**
-     * External game state to sync with.
-     */
-    gameState?: any;
-    /**
-     * External stage state to sync with.
-     */
-    stageState?: any;
-    /**
-     * Whether to include default styles.
-     * @default true
-     */
-    includeStyles?: boolean;
-    /**
-     * Controls whether the internal floating launcher is rendered.
-     * @default 'floating'
-     */
-    launcherMode?: EditorLauncherMode;
-}
-/**
- * ZylemEditorElement - A web component that wraps the Zylem Editor.
- *
- * This component is fully self-contained with bundled styles.
- * It can be imported and used in any project without additional CSS configuration.
- *
- * @example
- * ```html
- * <!-- Standalone usage -->
- * <zylem-editor></zylem-editor>
- * ```
- *
- * @example
- * ```js
- * // Configured usage
- * const editor = document.querySelector('zylem-editor');
- * editor.config = {
- *   debugState: myGame.debugState,
- *   gameState: myGame.gameState,
- *   stageState: myGame.stageState,
- * };
- * ```
- *
- * @example
- * ```js
- * // Manual registration in another project
- * import { ZylemEditorElement } from '@zylem/editor';
- *
- * // Optionally customize before registering
- * customElements.define('my-editor', ZylemEditorElement);
- * ```
- */
-declare class ZylemEditorElement extends HTMLElement {
-    private dispose;
-    private _config;
-    private _initialized;
-    private controller;
-    /** Releases this element's bridge subscription (reference-counted). */
-    private releaseBridge;
-    constructor();
-    /**
-     * Set configuration for the editor.
-     * Must be set before the element is connected to the DOM, or call `reinitialize()` after.
-     */
-    set config(value: ZylemEditorConfig);
-    get config(): ZylemEditorConfig;
-    set launcherMode(value: EditorLauncherMode);
-    get launcherMode(): EditorLauncherMode;
-    /**
-     * Observed attributes for the web component
-     */
-    static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
-    connectedCallback(): void;
-    private initialize;
-    openPanel(): void;
-    closePanel(): void;
-    togglePanel(): void;
-    /**
-     * Reinitialize the editor with new configuration.
-     * Call this after changing the `config` property if the element is already connected.
-     */
-    reinitialize(): void;
-    disconnectedCallback(): void;
-    private teardown;
-}
-/**
- * Register the ZylemEditorElement as a custom element.
- * Call this function to use the default 'zylem-editor' tag name.
- *
- * @example
- * ```js
- * import { registerZylemEditor } from '@zylem/editor';
- * registerZylemEditor();
- * // Now you can use <zylem-editor> in your HTML
- * ```
- */
-declare function registerZylemEditor(tagName?: string): void;
-
-interface IconProps extends LucideProps {
-    icon: Component<LucideProps>;
-}
-declare const Icon: Component<IconProps>;
-
 /**
  * Editor Event Bus
  *
@@ -259,6 +145,58 @@ interface StageStateInterface {
 
 declare const stageState: StageStateInterface;
 
+/**
+ * Dock layout geometry.
+ *
+ * Docking used to be per-panel: each panel snapped itself to a viewport edge
+ * and sized itself from `window.innerWidth`. That cannot express two panels
+ * sharing a side, or a bottom strip that stops at a left-docked panel, so the
+ * dock state lives in one registry (persisted in the editor store) and every
+ * panel's rect comes from `computeDockLayout`.
+ *
+ * This module is deliberately free of Solid and `window` so the geometry can
+ * be unit tested directly.
+ */
+type DockSide = 'left' | 'right' | 'top' | 'bottom';
+/** `'main'` is the editor panel; any other id is a detached section id. */
+type DockPanelId = string;
+interface DockZoneState {
+    /** Occupants in slot order along the zone's long axis. */
+    panels: DockPanelId[];
+    /**
+     * Width for left/right, height for top/bottom.
+     * `0` means "not chosen yet"; the layout falls back to a viewport quarter.
+     */
+    thickness: number;
+}
+type DockRegistry = Record<DockSide, DockZoneState>;
+interface Viewport {
+    width: number;
+    height: number;
+}
+interface DockRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+declare const DOCK_SIDES: readonly DockSide[];
+declare const findDockedSide: (registry: DockRegistry, panelId: DockPanelId) => DockSide | null;
+interface DockLayoutOptions {
+    /** Smallest slot extent along a zone's long axis. */
+    minSlotExtent?: number;
+}
+/**
+ * Rect for every docked panel.
+ *
+ * Left and right zones take the full viewport height and win over top and
+ * bottom, which inset horizontally to the space between them. Panels sharing a
+ * zone split its long axis evenly.
+ */
+declare const computeDockLayout: (registry: DockRegistry, viewport: Viewport, options?: DockLayoutOptions) => Record<DockPanelId, DockRect>;
+
+/** Registry id of the main editor panel; detached sections use their panel id. */
+declare const MAIN_PANEL_ID = "main";
 interface DetachedPanelState {
     position: {
         x: number;
@@ -269,6 +207,8 @@ interface DetachedPanelState {
         height: number;
     };
 }
+/** First-run dock assignments a host can request; see `applyDefaultDocks`. */
+type EditorDockDefaults = Partial<Record<DockSide, DockPanelId[]>>;
 declare const debugStore: {
     debug: boolean;
     tool: DebugTools;
@@ -279,6 +219,11 @@ declare const debugStore: {
         x: number;
         y: number;
     } | null;
+    /** Main panel's floating size; its docked size comes from the registry. */
+    panelSize: {
+        width: number;
+        height: number;
+    } | null;
     toggleButtonPosition: {
         x: number;
         y: number;
@@ -287,9 +232,143 @@ declare const debugStore: {
     detachedPanels: Record<string, DetachedPanelState>;
     openSections: string[];
     panelZOrder: string[];
+    docks: DockRegistry;
+    dockDefaultsApplied: boolean;
     draggingPanelId: string | null;
     dropTargetIndex: number | null;
 };
+declare const dockPanelToSide: (panelId: DockPanelId, side: DockSide, index?: number) => void;
+declare const undockPanelFromSides: (panelId: DockPanelId) => void;
+declare const getDockedSide: (panelId: DockPanelId) => DockSide | null;
+
+type EditorLauncherMode = 'floating' | 'hidden';
+
+/**
+ * Configuration options for the ZylemEditorElement
+ */
+interface ZylemEditorConfig {
+    /**
+     * External debug state to sync with.
+     * If provided, the editor will use this state instead of its internal state.
+     */
+    debugState?: any;
+    /**
+     * External game state to sync with.
+     */
+    gameState?: any;
+    /**
+     * External stage state to sync with.
+     */
+    stageState?: any;
+    /**
+     * Whether to include default styles.
+     * @default true
+     */
+    includeStyles?: boolean;
+    /**
+     * Controls whether the internal floating launcher is rendered.
+     * @default 'floating'
+     */
+    launcherMode?: EditorLauncherMode;
+    /**
+     * Dock layout to seed the first time the editor runs in this browser, keyed
+     * by viewport edge. Use `'main'` for the editor panel itself; any other id is
+     * a section (for example `'console'`), which gets detached from the accordion
+     * so it can hold a dock slot.
+     *
+     * Ignored once the user has a saved layout, so it sets a starting point
+     * rather than forcing one.
+     */
+    defaultDocks?: EditorDockDefaults;
+}
+/**
+ * ZylemEditorElement - A web component that wraps the Zylem Editor.
+ *
+ * This component is fully self-contained with bundled styles.
+ * It can be imported and used in any project without additional CSS configuration.
+ *
+ * @example
+ * ```html
+ * <!-- Standalone usage -->
+ * <zylem-editor></zylem-editor>
+ * ```
+ *
+ * @example
+ * ```js
+ * // Configured usage
+ * const editor = document.querySelector('zylem-editor');
+ * editor.config = {
+ *   debugState: myGame.debugState,
+ *   gameState: myGame.gameState,
+ *   stageState: myGame.stageState,
+ * };
+ * ```
+ *
+ * @example
+ * ```js
+ * // Manual registration in another project
+ * import { ZylemEditorElement } from '@zylem/editor';
+ *
+ * // Optionally customize before registering
+ * customElements.define('my-editor', ZylemEditorElement);
+ * ```
+ */
+declare class ZylemEditorElement extends HTMLElement {
+    private dispose;
+    private _config;
+    private _initialized;
+    private controller;
+    /** Releases this element's bridge subscription (reference-counted). */
+    private releaseBridge;
+    constructor();
+    /**
+     * Set configuration for the editor.
+     * Must be set before the element is connected to the DOM, or call `reinitialize()` after.
+     */
+    set config(value: ZylemEditorConfig);
+    get config(): ZylemEditorConfig;
+    set launcherMode(value: EditorLauncherMode);
+    get launcherMode(): EditorLauncherMode;
+    /**
+     * Observed attributes for the web component
+     */
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    connectedCallback(): void;
+    private initialize;
+    openPanel(): void;
+    closePanel(): void;
+    togglePanel(): void;
+    /**
+     * Dock a panel to a viewport edge, or pass `null` to float it again.
+     * Defaults to the main editor panel.
+     */
+    dockPanel(side: DockSide | null, panelId?: DockPanelId): void;
+    /**
+     * Reinitialize the editor with new configuration.
+     * Call this after changing the `config` property if the element is already connected.
+     */
+    reinitialize(): void;
+    disconnectedCallback(): void;
+    private teardown;
+}
+/**
+ * Register the ZylemEditorElement as a custom element.
+ * Call this function to use the default 'zylem-editor' tag name.
+ *
+ * @example
+ * ```js
+ * import { registerZylemEditor } from '@zylem/editor';
+ * registerZylemEditor();
+ * // Now you can use <zylem-editor> in your HTML
+ * ```
+ */
+declare function registerZylemEditor(tagName?: string): void;
+
+interface IconProps extends LucideProps {
+    icon: Component<LucideProps>;
+}
+declare const Icon: Component<IconProps>;
 
 declare const channel: _zylem_bridge.BridgeChannel;
 /**
@@ -401,6 +480,17 @@ interface MountZylemEditorOptions extends EditorStateBridgeOptions {
      * @default 'floating'
      */
     launcherMode?: EditorLauncherMode;
+    /**
+     * Dock layout to seed on first run, keyed by viewport edge. `'main'` is the
+     * editor panel; any other id is a section such as `'console'`. Ignored once
+     * the user has a saved layout.
+     *
+     * @example
+     * ```ts
+     * mountZylemEditor({ defaultDocks: { left: ['main'], bottom: ['console'] } });
+     * ```
+     */
+    defaultDocks?: EditorDockDefaults;
     /**
      * Element the <zylem-editor> overlay is appended to.
      * @default document.body
@@ -409,6 +499,8 @@ interface MountZylemEditorOptions extends EditorStateBridgeOptions {
 }
 interface MountedZylemEditor extends EditorStateBridge {
     element: ZylemEditorElement;
+    /** Dock a panel to a viewport edge, or pass `null` to float it again. */
+    dockPanel(side: DockSide | null, panelId?: DockPanelId): void;
 }
 /**
  * Imperatively mount a <zylem-editor> overlay and attach the state bridge.
@@ -422,4 +514,4 @@ interface MountedZylemEditor extends EditorStateBridge {
  */
 declare function mountZylemEditor(options?: MountZylemEditorOptions): MountedZylemEditor;
 
-export { type EditorEvent, type EditorEventType, type EditorStateBridge, type EditorStateBridgeOptions, type EditorUpdatePayload, Icon, type MountZylemEditorOptions, type MountedZylemEditor, type ZylemEditorConfig, ZylemEditorElement, attachEditorStateBridge, channel as bridgeChannel, connectEditorBridge, debugState, debugStore, disconnectEditorBridge, dispatchEditorUpdate, dispatchToEditor, editorEvents, gameState, mountZylemEditor, registerZylemEditor, sendDebugEnabled, sendEntityFocus, sendEntitySelect, sendPlayback, sendStageVariable, sendTool, stageState };
+export { DOCK_SIDES, type DockPanelId, type DockRect, type DockRegistry, type DockSide, type DockZoneState, type EditorDockDefaults, type EditorEvent, type EditorEventType, type EditorStateBridge, type EditorStateBridgeOptions, type EditorUpdatePayload, Icon, MAIN_PANEL_ID, type MountZylemEditorOptions, type MountedZylemEditor, type ZylemEditorConfig, ZylemEditorElement, attachEditorStateBridge, channel as bridgeChannel, computeDockLayout, connectEditorBridge, debugState, debugStore, disconnectEditorBridge, dispatchEditorUpdate, dispatchToEditor, dockPanelToSide, editorEvents, findDockedSide, gameState, getDockedSide, mountZylemEditor, registerZylemEditor, sendDebugEnabled, sendEntityFocus, sendEntitySelect, sendPlayback, sendStageVariable, sendTool, stageState, undockPanelFromSides };