@embedpdf/plugin-ui 2.0.0-next.0 → 2.0.0-next.2

package/dist/shared/types.d.ts

@@ -1,5 +1,5 @@
 import { ComponentType } from '../react/adapter.ts';
-import { ToolbarSchema, PanelSchema, MenuSchema, SelectionMenuSchema } from '../index.ts';
+import { ToolbarSchema, SidebarSchema, ModalSchema, OverlaySchema, MenuSchema, SelectionMenuSchema } from '../index.ts';
 import { SelectionMenuPropsBase } from '../react/utils.ts';
 export type { SelectionMenuPropsBase };
 export type UIComponents = Record<string, ComponentType<BaseComponentProps>>;
@@ -23,17 +23,40 @@ export interface ToolbarRendererProps {
 }
 export type ToolbarRenderer = ComponentType<ToolbarRendererProps>;
 /**
- * Props for panel renderer
+ * Props for sidebar renderer
  * The app provides a component matching this contract
  */
-export interface PanelRendererProps {
-    schema: PanelSchema;
+export interface SidebarRendererProps {
+    schema: SidebarSchema;
     documentId: string;
     isOpen: boolean;
     onClose: () => void;
     className?: string;
 }
-export type PanelRenderer = ComponentType<PanelRendererProps>;
+export type SidebarRenderer = ComponentType<SidebarRendererProps>;
+/**
+ * Props for modal renderer (with animation lifecycle support)
+ * The app provides a component matching this contract
+ */
+export interface ModalRendererProps {
+    schema: ModalSchema;
+    documentId: string;
+    isOpen: boolean;
+    onClose: () => void;
+    onExited: () => void;
+    className?: string;
+}
+export type ModalRenderer = ComponentType<ModalRendererProps>;
+/**
+ * Props for overlay renderer
+ * The app provides a component matching this contract
+ */
+export interface OverlayRendererProps {
+    schema: OverlaySchema;
+    documentId: string;
+    className?: string;
+}
+export type OverlayRenderer = ComponentType<OverlayRendererProps>;
 /**
  * Props for menu renderer
  * The app provides a component matching this contract
@@ -61,7 +84,9 @@ export type SelectionMenuRenderer = ComponentType<SelectionMenuRendererProps>;
  */
 export interface UIRenderers {
     toolbar: ToolbarRenderer;
-    panel: PanelRenderer;
+    sidebar: SidebarRenderer;
+    modal?: ModalRenderer;
+    overlay?: OverlayRenderer;
     menu: MenuRenderer;
     selectionMenu: SelectionMenuRenderer;
 }

package/dist/shared-preact/hooks/index.d.ts

@@ -1,4 +1,5 @@
 export * from './use-ui';
+export * from './use-ui-container';
 export * from './use-register-anchor';
 export * from './use-item-renderer';
 export * from './use-schema-renderer';

package/dist/shared-preact/hooks/use-schema-renderer.d.ts

@@ -1,7 +1,7 @@
 /**
  * High-level hook for rendering UI from schema
  *
- * Provides simple functions to render toolbars and panels by placement+slot.
+ * Provides simple functions to render toolbars, sidebars, and modals.
  * Always passes isOpen state to renderers so they can control animations.
  *
  * Automatically subscribes to UI state changes for the given document.
@@ -23,9 +23,9 @@ export declare function useSchemaRenderer(documentId: string): {
      */
     renderToolbar: (placement: "top" | "bottom" | "left" | "right", slot: string) => import("preact").JSX.Element | null;
     /**
-     * Render a panel by placement and slot
+     * Render a sidebar by placement and slot
      *
-     * ALWAYS renders (when panel exists in slot) with isOpen state.
+     * ALWAYS renders (when sidebar exists in slot) with isOpen state.
      * Your renderer controls whether to display or animate.
      *
      * @param placement - 'left' | 'right' | 'top' | 'bottom'
@@ -33,11 +33,28 @@ export declare function useSchemaRenderer(documentId: string): {
      *
      * @example
      * ```tsx
-     * {renderPanel('left', 'main')}
-     * {renderPanel('right', 'main')}
+     * {renderSidebar('left', 'main')}
+     * {renderSidebar('right', 'main')}
      * ```
      */
-    renderPanel: (placement: "left" | "right" | "top" | "bottom", slot: string) => import("preact").JSX.Element | null;
+    renderSidebar: (placement: "left" | "right" | "top" | "bottom", slot: string) => import("preact").JSX.Element | null;
+    /**
+     * Render the active modal (if any)
+     *
+     * Only one modal can be active at a time.
+     * Modals are defined in schema.modals.
+     *
+     * Supports animation lifecycle:
+     * - isOpen: true = visible
+     * - isOpen: false = animate out (modal still rendered)
+     * - onExited called after animation → modal removed
+     *
+     * @example
+     * ```tsx
+     * {renderModal()}
+     * ```
+     */
+    renderModal: () => import("preact").JSX.Element | null;
     /**
      * Helper: Get all active toolbars for this document
      * Useful for batch rendering or debugging
@@ -49,13 +66,28 @@ export declare function useSchemaRenderer(documentId: string): {
         isOpen: boolean;
     }[];
     /**
-     * Helper: Get all active panels for this document
+     * Helper: Get all active sidebars for this document
      * Useful for batch rendering or debugging
      */
-    getActivePanels: () => {
+    getActiveSidebars: () => {
         placement: string;
         slot: string;
-        panelId: string;
+        sidebarId: string;
         isOpen: boolean;
     }[];
+    /**
+     * Render all enabled overlays
+     *
+     * Overlays are floating components positioned over the document content.
+     * Unlike modals, multiple overlays can be visible and they don't block interaction.
+     *
+     * @example
+     * ```tsx
+     * <div className="relative">
+     *   {children}
+     *   {renderOverlays()}
+     * </div>
+     * ```
+     */
+    renderOverlays: () => import("preact").JSX.Element | null;
 };

package/dist/shared-preact/hooks/use-ui-container.d.ts

@@ -0,0 +1,39 @@
+import { RefObject } from '../../preact/adapter.ts';
+export interface UIContainerContextValue {
+    /** Reference to the UIRoot container element */
+    containerRef: RefObject<HTMLDivElement>;
+    /** Get the container element (may be null if not mounted) */
+    getContainer: () => HTMLDivElement | null;
+}
+export declare const UIContainerContext: import('preact').Context<UIContainerContextValue | null>;
+/**
+ * Hook to access the UI container element.
+ *
+ * This provides access to the UIRoot container for:
+ * - Container query based responsiveness
+ * - Portaling elements to the root
+ * - Measuring container dimensions
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { containerRef, getContainer } = useUIContainer();
+ *
+ *   // Use containerRef for ResizeObserver
+ *   useEffect(() => {
+ *     const container = getContainer();
+ *     if (!container) return;
+ *
+ *     const observer = new ResizeObserver(() => {
+ *       console.log('Container width:', container.clientWidth);
+ *     });
+ *     observer.observe(container);
+ *     return () => observer.disconnect();
+ *   }, [getContainer]);
+ *
+ *   // Or portal to the container
+ *   return createPortal(<Modal />, getContainer()!);
+ * }
+ * ```
+ */
+export declare function useUIContainer(): UIContainerContextValue;

package/dist/shared-preact/root.d.ts

@@ -8,5 +8,5 @@ interface UIRootProps extends HTMLAttributes<HTMLDivElement> {
  * 2. Managing the data-disabled-categories attribute
  * 3. Updating styles on locale changes
  */
-export declare function UIRoot({ children, ...restProps }: UIRootProps): import("preact").JSX.Element;
+export declare function UIRoot({ children, style, ...restProps }: UIRootProps): import("preact").JSX.Element;
 export {};

package/dist/shared-preact/types.d.ts

@@ -1,5 +1,5 @@
 import { ComponentType } from '../preact/adapter.ts';
-import { ToolbarSchema, PanelSchema, MenuSchema, SelectionMenuSchema } from '../lib/index.ts';
+import { ToolbarSchema, SidebarSchema, ModalSchema, OverlaySchema, MenuSchema, SelectionMenuSchema } from '../lib/index.ts';
 import { SelectionMenuPropsBase } from '../preact/utils.ts';
 export type { SelectionMenuPropsBase };
 export type UIComponents = Record<string, ComponentType<BaseComponentProps>>;
@@ -23,17 +23,40 @@ export interface ToolbarRendererProps {
 }
 export type ToolbarRenderer = ComponentType<ToolbarRendererProps>;
 /**
- * Props for panel renderer
+ * Props for sidebar renderer
  * The app provides a component matching this contract
  */
-export interface PanelRendererProps {
-    schema: PanelSchema;
+export interface SidebarRendererProps {
+    schema: SidebarSchema;
     documentId: string;
     isOpen: boolean;
     onClose: () => void;
     className?: string;
 }
-export type PanelRenderer = ComponentType<PanelRendererProps>;
+export type SidebarRenderer = ComponentType<SidebarRendererProps>;
+/**
+ * Props for modal renderer (with animation lifecycle support)
+ * The app provides a component matching this contract
+ */
+export interface ModalRendererProps {
+    schema: ModalSchema;
+    documentId: string;
+    isOpen: boolean;
+    onClose: () => void;
+    onExited: () => void;
+    className?: string;
+}
+export type ModalRenderer = ComponentType<ModalRendererProps>;
+/**
+ * Props for overlay renderer
+ * The app provides a component matching this contract
+ */
+export interface OverlayRendererProps {
+    schema: OverlaySchema;
+    documentId: string;
+    className?: string;
+}
+export type OverlayRenderer = ComponentType<OverlayRendererProps>;
 /**
  * Props for menu renderer
  * The app provides a component matching this contract
@@ -61,7 +84,9 @@ export type SelectionMenuRenderer = ComponentType<SelectionMenuRendererProps>;
  */
 export interface UIRenderers {
     toolbar: ToolbarRenderer;
-    panel: PanelRenderer;
+    sidebar: SidebarRenderer;
+    modal?: ModalRenderer;
+    overlay?: OverlayRenderer;
     menu: MenuRenderer;
     selectionMenu: SelectionMenuRenderer;
 }

package/dist/shared-react/hooks/index.d.ts

@@ -1,4 +1,5 @@
 export * from './use-ui';
+export * from './use-ui-container';
 export * from './use-register-anchor';
 export * from './use-item-renderer';
 export * from './use-schema-renderer';

package/dist/shared-react/hooks/use-schema-renderer.d.ts

@@ -1,7 +1,7 @@
 /**
  * High-level hook for rendering UI from schema
  *
- * Provides simple functions to render toolbars and panels by placement+slot.
+ * Provides simple functions to render toolbars, sidebars, and modals.
  * Always passes isOpen state to renderers so they can control animations.
  *
  * Automatically subscribes to UI state changes for the given document.
@@ -23,9 +23,9 @@ export declare function useSchemaRenderer(documentId: string): {
      */
     renderToolbar: (placement: "top" | "bottom" | "left" | "right", slot: string) => import("react/jsx-runtime").JSX.Element | null;
     /**
-     * Render a panel by placement and slot
+     * Render a sidebar by placement and slot
      *
-     * ALWAYS renders (when panel exists in slot) with isOpen state.
+     * ALWAYS renders (when sidebar exists in slot) with isOpen state.
      * Your renderer controls whether to display or animate.
      *
      * @param placement - 'left' | 'right' | 'top' | 'bottom'
@@ -33,11 +33,28 @@ export declare function useSchemaRenderer(documentId: string): {
      *
      * @example
      * ```tsx
-     * {renderPanel('left', 'main')}
-     * {renderPanel('right', 'main')}
+     * {renderSidebar('left', 'main')}
+     * {renderSidebar('right', 'main')}
      * ```
      */
-    renderPanel: (placement: "left" | "right" | "top" | "bottom", slot: string) => import("react/jsx-runtime").JSX.Element | null;
+    renderSidebar: (placement: "left" | "right" | "top" | "bottom", slot: string) => import("react/jsx-runtime").JSX.Element | null;
+    /**
+     * Render the active modal (if any)
+     *
+     * Only one modal can be active at a time.
+     * Modals are defined in schema.modals.
+     *
+     * Supports animation lifecycle:
+     * - isOpen: true = visible
+     * - isOpen: false = animate out (modal still rendered)
+     * - onExited called after animation → modal removed
+     *
+     * @example
+     * ```tsx
+     * {renderModal()}
+     * ```
+     */
+    renderModal: () => import("react/jsx-runtime").JSX.Element | null;
     /**
      * Helper: Get all active toolbars for this document
      * Useful for batch rendering or debugging
@@ -49,13 +66,28 @@ export declare function useSchemaRenderer(documentId: string): {
         isOpen: boolean;
     }[];
     /**
-     * Helper: Get all active panels for this document
+     * Helper: Get all active sidebars for this document
      * Useful for batch rendering or debugging
      */
-    getActivePanels: () => {
+    getActiveSidebars: () => {
         placement: string;
         slot: string;
-        panelId: string;
+        sidebarId: string;
         isOpen: boolean;
     }[];
+    /**
+     * Render all enabled overlays
+     *
+     * Overlays are floating components positioned over the document content.
+     * Unlike modals, multiple overlays can be visible and they don't block interaction.
+     *
+     * @example
+     * ```tsx
+     * <div className="relative">
+     *   {children}
+     *   {renderOverlays()}
+     * </div>
+     * ```
+     */
+    renderOverlays: () => import("react/jsx-runtime").JSX.Element | null;
 };

package/dist/shared-react/hooks/use-ui-container.d.ts

@@ -0,0 +1,39 @@
+import { RefObject } from '../../react/adapter.ts';
+export interface UIContainerContextValue {
+    /** Reference to the UIRoot container element */
+    containerRef: RefObject<HTMLDivElement>;
+    /** Get the container element (may be null if not mounted) */
+    getContainer: () => HTMLDivElement | null;
+}
+export declare const UIContainerContext: import('react').Context<UIContainerContextValue | null>;
+/**
+ * Hook to access the UI container element.
+ *
+ * This provides access to the UIRoot container for:
+ * - Container query based responsiveness
+ * - Portaling elements to the root
+ * - Measuring container dimensions
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { containerRef, getContainer } = useUIContainer();
+ *
+ *   // Use containerRef for ResizeObserver
+ *   useEffect(() => {
+ *     const container = getContainer();
+ *     if (!container) return;
+ *
+ *     const observer = new ResizeObserver(() => {
+ *       console.log('Container width:', container.clientWidth);
+ *     });
+ *     observer.observe(container);
+ *     return () => observer.disconnect();
+ *   }, [getContainer]);
+ *
+ *   // Or portal to the container
+ *   return createPortal(<Modal />, getContainer()!);
+ * }
+ * ```
+ */
+export declare function useUIContainer(): UIContainerContextValue;

package/dist/shared-react/root.d.ts

@@ -8,5 +8,5 @@ interface UIRootProps extends HTMLAttributes<HTMLDivElement> {
  * 2. Managing the data-disabled-categories attribute
  * 3. Updating styles on locale changes
  */
-export declare function UIRoot({ children, ...restProps }: UIRootProps): import("react/jsx-runtime").JSX.Element;
+export declare function UIRoot({ children, style, ...restProps }: UIRootProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/shared-react/types.d.ts

@@ -1,5 +1,5 @@
 import { ComponentType } from '../react/adapter.ts';
-import { ToolbarSchema, PanelSchema, MenuSchema, SelectionMenuSchema } from '../lib/index.ts';
+import { ToolbarSchema, SidebarSchema, ModalSchema, OverlaySchema, MenuSchema, SelectionMenuSchema } from '../lib/index.ts';
 import { SelectionMenuPropsBase } from '../react/utils.ts';
 export type { SelectionMenuPropsBase };
 export type UIComponents = Record<string, ComponentType<BaseComponentProps>>;
@@ -23,17 +23,40 @@ export interface ToolbarRendererProps {
 }
 export type ToolbarRenderer = ComponentType<ToolbarRendererProps>;
 /**
- * Props for panel renderer
+ * Props for sidebar renderer
  * The app provides a component matching this contract
  */
-export interface PanelRendererProps {
-    schema: PanelSchema;
+export interface SidebarRendererProps {
+    schema: SidebarSchema;
     documentId: string;
     isOpen: boolean;
     onClose: () => void;
     className?: string;
 }
-export type PanelRenderer = ComponentType<PanelRendererProps>;
+export type SidebarRenderer = ComponentType<SidebarRendererProps>;
+/**
+ * Props for modal renderer (with animation lifecycle support)
+ * The app provides a component matching this contract
+ */
+export interface ModalRendererProps {
+    schema: ModalSchema;
+    documentId: string;
+    isOpen: boolean;
+    onClose: () => void;
+    onExited: () => void;
+    className?: string;
+}
+export type ModalRenderer = ComponentType<ModalRendererProps>;
+/**
+ * Props for overlay renderer
+ * The app provides a component matching this contract
+ */
+export interface OverlayRendererProps {
+    schema: OverlaySchema;
+    documentId: string;
+    className?: string;
+}
+export type OverlayRenderer = ComponentType<OverlayRendererProps>;
 /**
  * Props for menu renderer
  * The app provides a component matching this contract
@@ -61,7 +84,9 @@ export type SelectionMenuRenderer = ComponentType<SelectionMenuRendererProps>;
  */
 export interface UIRenderers {
     toolbar: ToolbarRenderer;
-    panel: PanelRenderer;
+    sidebar: SidebarRenderer;
+    modal?: ModalRenderer;
+    overlay?: OverlayRenderer;
     menu: MenuRenderer;
     selectionMenu: SelectionMenuRenderer;
 }

package/dist/svelte/hooks/index.d.ts

@@ -1,4 +1,5 @@
 export * from './use-ui.svelte';
+export * from './use-ui-container.svelte';
 export * from './use-register-anchor.svelte';
 export * from './use-item-renderer.svelte';
 export * from './use-schema-renderer.svelte';

package/dist/svelte/hooks/use-schema-renderer.svelte.d.ts

@@ -1,18 +1,19 @@
 /**
  * High-level hook for rendering UI from schema
  *
- * Provides information about active toolbars and panels by placement+slot.
+ * Provides information about active toolbars, sidebars, and modals.
  * Always includes isOpen state so renderers can control animations.
  *
- * Use with Svelte's component binding to render toolbars and panels.
+ * Use with Svelte's component binding to render toolbars and sidebars.
  *
  * @example
  * ```svelte
  * <script lang="ts">
- *   const { getToolbarInfo, getPanelInfo } = useSchemaRenderer(() => documentId);
+ *   const { getToolbarInfo, getSidebarInfo, getModalInfo } = useSchemaRenderer(() => documentId);
  *
  *   const topMainToolbar = $derived(getToolbarInfo('top', 'main'));
- *   const leftMainPanel = $derived(getPanelInfo('left', 'main'));
+ *   const leftMainSidebar = $derived(getSidebarInfo('left', 'main'));
+ *   const modal = $derived(getModalInfo());
  * </script>
  *
  * {#if topMainToolbar}
@@ -42,19 +43,37 @@ export declare function useSchemaRenderer(getDocumentId: () => string | null): {
         onClose: (() => void) | undefined;
     } | null;
     /**
-     * Get panel information by placement and slot
+     * Get sidebar information by placement and slot
      *
      * @param placement - 'left' | 'right' | 'top' | 'bottom'
      * @param slot - Slot name (e.g. 'main', 'secondary', 'inspector')
-     * @returns Panel info or null if no panel in slot
+     * @returns Sidebar info or null if no sidebar in slot
      */
-    getPanelInfo: (placement: "left" | "right" | "top" | "bottom", slot: string) => {
-        renderer: import('..').PanelRenderer;
-        schema: import('../../lib').PanelSchema;
+    getSidebarInfo: (placement: "left" | "right" | "top" | "bottom", slot: string) => {
+        renderer: import('..').SidebarRenderer;
+        schema: import('../../lib').SidebarSchema;
         documentId: string;
         isOpen: boolean;
         onClose: () => void;
     } | null;
+    /**
+     * Get modal information (if active)
+     *
+     * Supports animation lifecycle:
+     * - isOpen: true = visible
+     * - isOpen: false = animate out (modal still rendered)
+     * - onExited called after animation → modal removed
+     *
+     * @returns Modal info or null if no modal active
+     */
+    getModalInfo: () => {
+        renderer: import('..').ModalRenderer;
+        schema: import('../../lib').ModalSchema;
+        documentId: string;
+        isOpen: boolean;
+        onClose: () => void;
+        onExited: () => void;
+    } | null;
     /**
      * Helper: Get all active toolbars for this document
      * Useful for batch rendering or debugging
@@ -66,13 +85,37 @@ export declare function useSchemaRenderer(getDocumentId: () => string | null): {
         isOpen: boolean;
     }[];
     /**
-     * Helper: Get all active panels for this document
+     * Helper: Get all active sidebars for this document
      * Useful for batch rendering or debugging
      */
-    getActivePanels: () => {
+    getActiveSidebars: () => {
         placement: string;
         slot: string;
-        panelId: string;
+        sidebarId: string;
         isOpen: boolean;
     }[];
+    /**
+     * Get overlay information for all enabled overlays
+     *
+     * Overlays are floating components positioned over the document content.
+     * Unlike modals, multiple overlays can be visible and they don't block interaction.
+     *
+     * @example
+     * ```svelte
+     * <script lang="ts">
+     *   const { getOverlaysInfo } = useSchemaRenderer(() => documentId);
+     *   const overlays = $derived(getOverlaysInfo());
+     * </script>
+     *
+     * {#each overlays as overlay (overlay.schema.id)}
+     *   {@const OverlayRenderer = overlay.renderer}
+     *   <OverlayRenderer schema={overlay.schema} documentId={overlay.documentId} />
+     * {/each}
+     * ```
+     */
+    getOverlaysInfo: () => {
+        renderer: import('..').OverlayRenderer;
+        schema: import('../../lib').OverlaySchema;
+        documentId: string;
+    }[];
 };

package/dist/svelte/hooks/use-ui-container.svelte.d.ts

@@ -0,0 +1,41 @@
+export interface UIContainerContextValue {
+    /** Get the container element (may be null if not mounted) */
+    getContainer: () => HTMLDivElement | null;
+}
+/**
+ * Set up the container context (called by UIRoot)
+ */
+export declare function setUIContainerContext(value: UIContainerContextValue): void;
+/**
+ * Hook to access the UI container element.
+ *
+ * This provides access to the UIRoot container for:
+ * - Container query based responsiveness
+ * - Portaling elements to the root
+ * - Measuring container dimensions
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useUIContainer } from '@embedpdf/plugin-ui/svelte';
+ *   import { onMount, onDestroy } from 'svelte';
+ *
+ *   const { getContainer } = useUIContainer();
+ *
+ *   let observer;
+ *
+ *   onMount(() => {
+ *     const container = getContainer();
+ *     if (!container) return;
+ *
+ *     observer = new ResizeObserver(() => {
+ *       console.log('Container width:', container.clientWidth);
+ *     });
+ *     observer.observe(container);
+ *   });
+ *
+ *   onDestroy(() => observer?.disconnect());
+ * </script>
+ * ```
+ */
+export declare function useUIContainer(): UIContainerContextValue;

package/dist/svelte/hooks/use-ui.svelte.d.ts

@@ -1,4 +1,4 @@
-import { UIPlugin, UIDocumentState, UISchema, UIScope } from '../../lib';
+import { UIPlugin, UIDocumentState, UIScope } from '../../lib';
 /**
  * Hook to get the raw UI plugin instance.
  */
@@ -29,6 +29,6 @@ export declare const useUIState: (getDocumentId: () => string | null) => UseUISt
  * Returns an object with a reactive getter for the schema
  */
 export declare const useUISchema: () => {
-    readonly schema: UISchema | null;
+    readonly schema: import('../../lib').UISchema | null;
 };
 export {};