@wippy-fe/types-global-proxy 0.0.23 → 0.0.25

package/index.d.ts

@@ -1,9 +1,125 @@
+import { PanelTree, ModalSize, PanelTarget } from '@wippy-fe/layout';
 import { AxiosDefaults, AxiosInstance } from 'axios';
 import { ConfirmationOptions } from 'primevue/confirmationoptions';
 import { ToastMessageOptions } from 'primevue/toast';
 import * as nanoevents from 'nanoevents';
 import * as tailwindcss_types_config from 'tailwindcss/types/config';
 
+/**
+ * Host-side layout types (Wippy-flavored wrapper around `@wippy-fe/layout`).
+ *
+ * The pure package speaks in `PanelDef = { component: Component, props? }` —
+ * bring-your-own Vue component. The host layer replaces that with a
+ * tagged-union where `kind` picks a content resolver:
+ *
+ *  - `page`      → renders a Wippy page (WPage double-buffer for `main: true`, single-instance otherwise)
+ *  - `artifact`  → renders a Wippy artifact (WPage with type='artifact')
+ *  - `component` → renders a registered web component via `tagName`
+ *  - `builtin`   → renders host chrome (nav-sidebar / chat-wrapper / artifact-viewer / session-selector)
+ *
+ * The host resolver converts this into `@wippy-fe/layout`'s `PanelDef` at
+ * construction time and passes it into a `LayoutManager`.
+ */
+
+interface HostPanelBase {
+    title?: string;
+    icon?: string;
+    props?: Record<string, unknown>;
+}
+interface HostPagePanelDef extends HostPanelBase {
+    kind: 'page';
+    id: string;
+    route?: string;
+}
+interface HostArtifactPanelDef extends HostPanelBase {
+    kind: 'artifact';
+    id: string;
+}
+interface HostComponentPanelDef extends HostPanelBase {
+    kind: 'component';
+    tagName: string;
+}
+type HostBuiltinId = 'nav-sidebar' | 'chat-wrapper' | 'artifact-viewer' | 'session-selector';
+interface HostBuiltinPanelDef extends HostPanelBase {
+    kind: 'builtin';
+    id: HostBuiltinId;
+}
+type HostPanelDef = HostPagePanelDef | HostArtifactPanelDef | HostComponentPanelDef | HostBuiltinPanelDef;
+/**
+ * Overlay content shape — what kind of thing to render. Mirrors
+ * HostPanelDef's discriminant exactly so the same resolver dispatch
+ * works for both inline panels and overlays. This makes floating
+ * panels and modals declarable in pure JSON config (no Vue component
+ * references in the declaration).
+ */
+type HostOverlayContent = {
+    kind: 'page';
+    id: string;
+    route?: string;
+} | {
+    kind: 'artifact';
+    id: string;
+} | {
+    kind: 'component';
+    tagName: string;
+} | {
+    kind: 'builtin';
+    id: HostBuiltinId;
+};
+interface HostOverlayBase {
+    title?: string;
+    icon?: string;
+    props?: Record<string, unknown>;
+    dismissable?: boolean;
+}
+/**
+ * Floating window def — absolute-positioned, draggable, resizable.
+ * Composition: content kind + window chrome properties.
+ */
+type HostFloatingDef = HostOverlayContent & HostOverlayBase & {
+    position: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+    minSize?: {
+        width: number;
+        height: number;
+    };
+    maxSize?: {
+        width: number;
+        height: number;
+    };
+    minimizable?: boolean;
+    maximizable?: boolean;
+    zIndex?: number;
+};
+/**
+ * Modal def — centered overlay. Size is either a single `ModalSize`
+ * or a breakpoint-keyed map (desktop centered / mobile fullscreen).
+ */
+type HostModalDef = HostOverlayContent & HostOverlayBase & {
+    size?: ModalSize | Record<string, ModalSize>;
+};
+/**
+ * The root layout declaration stored in `AppConfig.hostConfig.layout`.
+ * Shape mirrors `@wippy-fe/layout`'s `LayoutDeclaration` but replaces
+ * `panels` with a tagged-union `HostPanelDef` map.
+ */
+interface HostLayoutDeclaration {
+    layouts: Record<string, PanelTree> & {
+        default: PanelTree;
+    };
+    breakpoints?: Record<string, number>;
+    panels: Record<string, HostPanelDef>;
+    floating?: Record<string, HostFloatingDef>;
+    modals?: Record<string, HostModalDef>;
+    dragEnabled?: boolean;
+}
+
 declare namespace PageApi {
     interface Page {
         icon: string;
@@ -278,6 +394,11 @@ interface HostConfig {
         type: 'non-persistent' | 'cookie';
     };
     history?: 'browser' | 'hash';
+    /**
+     * Declarative multi-panel layout for the `managed-layout.html` entry point.
+     * Ignored by `iframe.html` / `chat-iframe.html` shells.
+     */
+    layout?: HostLayoutDeclaration;
 }
 interface AppContext {
     resourceId: string;
@@ -289,6 +410,16 @@ interface AppContext {
     isNavOwner?: boolean;
     layoutPanelId?: string;
     layoutId?: string;
+    /**
+     * Initial layout snapshot baked into the child payload by the
+     * managed-layout host. Child proxies seed `host.layout.snapshot` from
+     * this at boot — so `host.layout.snapshot` is NEVER null inside a
+     * managed-layout host, and consumers never have to wait for a
+     * round-trip. `undefined` outside a managed-layout host.
+     *
+     * Updates arrive asynchronously via the `@layout-change` proxy topic.
+     */
+    layout?: unknown;
     extensions?: Record<string, unknown>;
 }
 interface AppEnv {
@@ -770,7 +901,51 @@ interface OtherCommand {
 }
 type WsCommand = SessionOpenCommand | SessionCloseCommand | SessionMessageCommand | SessionCommandCommand | ExternalEventCommand;
 
-type KnownTopics = '@history' | '@visibility' | '@message' | '@state-error';
+/**
+ * Read-only mirror of the current host `HostLayoutDeclaration`, minus
+ * Vue-component references (those can't cross the postMessage boundary).
+ * Child iframes use this to reason about the tree — e.g. which panels
+ * exist, what their current sizes/collapsed state / routes are — without
+ * being coupled to the host's component registry.
+ *
+ * `null` outside a managed-layout host (compat mode, `iframe.html`, or
+ * any standalone/headless entry point).
+ */
+interface LayoutSnapshot {
+    layouts: Record<string, unknown>;
+    panels: Record<string, unknown>;
+    breakpoints?: Record<string, number>;
+    floating?: Record<string, unknown>;
+    modals?: Record<string, unknown>;
+    activeBreakpoint?: string;
+    dragEnabled?: boolean;
+}
+interface LayoutApi {
+    /**
+     * Current layout snapshot — sync property getter, never waits. Returns
+     * `null` when the child is NOT inside a managed-layout host. Updates
+     * arrive via the `@layout-change` proxy topic; read the property
+     * directly inside an `@layout-change` handler to see the fresh value,
+     * or subscribe reactively via `@wippy-fe/vue-host`'s `useWippyLayout`.
+     */
+    readonly snapshot: LayoutSnapshot | null;
+    /** Resize a panel in the active breakpoint layout. */
+    resizePanel: (panelId: string, size: string) => void;
+    /** Collapse a panel (no-op if not `collapsible`). */
+    collapsePanel: (panelId: string) => void;
+    /** Expand a collapsed panel. */
+    expandPanel: (panelId: string) => void;
+    /** Move a panel to a new position in the active layout. */
+    movePanel: (panelId: string, target: PanelTarget) => void;
+    /** Remove a panel from all breakpoint layouts + panels map. */
+    removePanel: (panelId: string) => void;
+    /** Close a currently-open modal by id. */
+    closeModal: (modalId: string) => void;
+    /** Remove a floating panel by id. */
+    removeFloating: (floatingId: string) => void;
+}
+
+type KnownTopics = '@history' | '@visibility' | '@message' | '@state-error' | '@layout-change' | '@layout-breakpoint';
 type Events = {
     /** Emitted when pages are updated */
     '@history': (data: {
@@ -783,6 +958,11 @@ type Events = {
         error: string;
         key?: string;
     }) => void;
+    '@layout-change': (snapshot: LayoutSnapshot) => void;
+    '@layout-breakpoint': (data: {
+        name: string;
+        width: number;
+    }) => void;
 } & {
     [K in string as K extends KnownTopics ? never : K]: (data: WsMessage) => void;
 };
@@ -937,6 +1117,12 @@ interface ProxyApiInstance {
          * system route segments. Pure function — safe to call anywhere.
          */
         classifyLink: (href: string | null | undefined) => LinkClassification;
+        /**
+         * Declarative multi-panel layout control (managed-layout entry point only).
+         * Calls from child iframes not embedded inside a `managed-layout.html`
+         * host will be dropped silently by the parent.
+         */
+        layout: LayoutApi;
         logout: () => void;
     };
     api: AxiosInstance;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wippy-fe/types-global-proxy",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "Global type declarations for Wippy iframe proxy (window.getWippyApi, $W, etc.)",
   "license": "UNLICENSED",
   "types": "index.d.ts"