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

package/dist/shared/hooks/use-register-anchor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Register a DOM element as an anchor for menus
+ *
+ * @param documentId - Document ID
+ * @param itemId - Item ID (typically matches the toolbar/menu item ID)
+ * @returns Ref callback to attach to the element
+ *
+ * @example
+ * ```tsx
+ * function ZoomButton({ documentId }: Props) {
+ *   const anchorRef = useRegisterAnchor(documentId, 'zoom-button');
+ *
+ *   return <button ref={anchorRef}>Zoom</button>;
+ * }
+ * ```
+ */
+export declare function useRegisterAnchor(documentId: string, itemId: string): (element: HTMLElement | null) => void;

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

@@ -0,0 +1,61 @@
+/**
+ * High-level hook for rendering UI from schema
+ *
+ * Provides simple functions to render toolbars and panels by placement+slot.
+ * Always passes isOpen state to renderers so they can control animations.
+ *
+ * Automatically subscribes to UI state changes for the given document.
+ */
+export declare function useSchemaRenderer(documentId: string): {
+    /**
+     * Render a toolbar by placement and slot
+     *
+     * Always renders with isOpen state when toolbar exists in slot.
+     *
+     * @param placement - 'top' | 'bottom' | 'left' | 'right'
+     * @param slot - Slot name (e.g. 'main', 'secondary')
+     *
+     * @example
+     * ```tsx
+     * {renderToolbar('top', 'main')}
+     * {renderToolbar('top', 'secondary')}
+     * ```
+     */
+    renderToolbar: (placement: "top" | "bottom" | "left" | "right", slot: string) => import("react/jsx-runtime").JSX.Element | null;
+    /**
+     * Render a panel by placement and slot
+     *
+     * ALWAYS renders (when panel exists in slot) with isOpen state.
+     * Your renderer controls whether to display or animate.
+     *
+     * @param placement - 'left' | 'right' | 'top' | 'bottom'
+     * @param slot - Slot name (e.g. 'main', 'secondary', 'inspector')
+     *
+     * @example
+     * ```tsx
+     * {renderPanel('left', 'main')}
+     * {renderPanel('right', 'main')}
+     * ```
+     */
+    renderPanel: (placement: "left" | "right" | "top" | "bottom", slot: string) => import("react/jsx-runtime").JSX.Element | null;
+    /**
+     * Helper: Get all active toolbars for this document
+     * Useful for batch rendering or debugging
+     */
+    getActiveToolbars: () => {
+        placement: string;
+        slot: string;
+        toolbarId: string;
+        isOpen: boolean;
+    }[];
+    /**
+     * Helper: Get all active panels for this document
+     * Useful for batch rendering or debugging
+     */
+    getActivePanels: () => {
+        placement: string;
+        slot: string;
+        panelId: string;
+        isOpen: boolean;
+    }[];
+};

package/dist/shared/hooks/use-selection-menu.d.ts

@@ -0,0 +1,11 @@
+import { SelectionMenuRenderFn } from '../../react/utils.ts';
+/**
+ * Creates a render function for a selection menu from the schema
+ *
+ * @param menuId - The selection menu ID from schema
+ * @param documentId - Document ID
+ * @returns A render function compatible with layer selectionMenu props
+ */
+export declare function useSelectionMenu<TContext extends {
+    type: string;
+}>(menuId: string, documentId: string): SelectionMenuRenderFn<TContext> | undefined;

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

@@ -1,11 +1,19 @@
-import { UIPlugin } from '../../index.ts';
-export declare const useUIPlugin: () => {
-    plugin: UIPlugin | null;
+import { UIPlugin, UIDocumentState, UISchema } from '../../index.ts';
+export declare const useUICapability: () => {
+    provides: Readonly<import('../../index.ts').UICapability> | null;
     isLoading: boolean;
     ready: Promise<void>;
 };
-export declare const useUICapability: () => {
-    provides: Readonly<import('../../index.ts').UICapability> | null;
+export declare const useUIPlugin: () => {
+    plugin: UIPlugin | null;
     isLoading: boolean;
     ready: Promise<void>;
 };
+/**
+ * Get UI state for a document
+ */
+export declare const useUIState: (documentId: string) => UIDocumentState | null;
+/**
+ * Get UI schema
+ */
+export declare const useUISchema: () => UISchema | null;

package/dist/shared/index.d.ts

@@ -1,3 +1,6 @@
-export * from './components';
 export * from './hooks';
+export * from './registries';
+export { UIProvider } from './provider';
+export type { UIProviderProps } from './provider';
+export * from './types';
 export * from '../index.ts';

package/dist/shared/provider.d.ts

@@ -0,0 +1,68 @@
+import { ReactNode, ComponentType, HTMLAttributes } from '../react/adapter.ts';
+import { BaseComponentProps, UIRenderers } from './types';
+/**
+ * UIProvider Props
+ */
+export interface UIProviderProps extends HTMLAttributes<HTMLDivElement> {
+    children: ReactNode;
+    /**
+     * Document ID for this UI context
+     * Required for menu rendering
+     */
+    documentId: string;
+    /**
+     * Custom component registry
+     * Maps component IDs to components
+     */
+    components?: Record<string, ComponentType<BaseComponentProps>>;
+    /**
+     * REQUIRED: User-provided renderers
+     * These define how toolbars, panels, and menus are displayed
+     */
+    renderers: UIRenderers;
+    /**
+     * Optional: Container for menu portal
+     * Defaults to document.body
+     */
+    menuContainer?: HTMLElement | null;
+}
+/**
+ * UIProvider - Single provider for all UI plugin functionality
+ *
+ * Manages:
+ * - Anchor registry for menu positioning
+ * - Component registry for custom components
+ * - Renderers for toolbars, panels, and menus
+ * - Automatic menu rendering
+ *
+ * @example
+ * ```tsx
+ * <EmbedPDF engine={engine} plugins={plugins}>
+ *   {({ pluginsReady }) => (
+ *     pluginsReady && (
+ *       <DocumentContext>
+ *         {({ activeDocumentId }) => (
+ *           activeDocumentId && (
+ *             <UIProvider
+ *               documentId={activeDocumentId}
+ *               components={{
+ *                 'thumbnail-panel': ThumbnailPanel,
+ *                 'bookmark-panel': BookmarkPanel,
+ *               }}
+ *               renderers={{
+ *                 toolbar: ToolbarRenderer,
+ *                 panel: PanelRenderer,
+ *                 menu: MenuRenderer,
+ *               }}
+ *             >
+ *               <ViewerLayout />
+ *             </UIProvider>
+ *           )
+ *         )}
+ *       </DocumentContext>
+ *     )
+ *   )}
+ * </EmbedPDF>
+ * ```
+ */
+export declare function UIProvider({ children, documentId, components, renderers, menuContainer, ...restProps }: UIProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/shared/registries/anchor-registry.d.ts

@@ -0,0 +1,16 @@
+import { ReactNode } from '../../react/adapter.ts';
+/**
+ * Anchor Registry
+ *
+ * Tracks DOM elements for menu positioning.
+ * Each anchor is scoped by documentId and itemId.
+ */
+export interface AnchorRegistry {
+    register(documentId: string, itemId: string, element: HTMLElement): void;
+    unregister(documentId: string, itemId: string): void;
+    getAnchor(documentId: string, itemId: string): HTMLElement | null;
+}
+export declare function AnchorRegistryProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useAnchorRegistry(): AnchorRegistry;

package/dist/shared/registries/component-registry.d.ts

@@ -0,0 +1,20 @@
+import { ComponentType, ReactNode } from '../../react/adapter.ts';
+import { BaseComponentProps } from '../types';
+/**
+ * Component Registry
+ *
+ * Stores custom components that can be referenced in the UI schema.
+ */
+export interface ComponentRegistry {
+    register(id: string, component: ComponentType<BaseComponentProps>): void;
+    unregister(id: string): void;
+    get(id: string): ComponentType<BaseComponentProps> | undefined;
+    has(id: string): boolean;
+    getRegisteredIds(): string[];
+}
+export interface ComponentRegistryProviderProps {
+    children: ReactNode;
+    initialComponents?: Record<string, ComponentType<BaseComponentProps>>;
+}
+export declare function ComponentRegistryProvider({ children, initialComponents, }: ComponentRegistryProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useComponentRegistry(): ComponentRegistry;

package/dist/shared/registries/index.d.ts

@@ -0,0 +1,3 @@
+export * from './anchor-registry';
+export * from './component-registry';
+export * from './renderers-registry';

package/dist/shared/registries/renderers-registry.d.ts

@@ -0,0 +1,8 @@
+import { ReactNode } from '../../react/adapter.ts';
+import { UIRenderers } from '../types';
+export interface RenderersProviderProps {
+    children: ReactNode;
+    renderers: UIRenderers;
+}
+export declare function RenderersProvider({ children, renderers }: RenderersProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useRenderers(): UIRenderers;

package/dist/shared/root.d.ts

@@ -0,0 +1,12 @@
+import { ReactNode, HTMLAttributes } from '../react/adapter.ts';
+interface UIRootProps extends HTMLAttributes<HTMLDivElement> {
+    children: ReactNode;
+}
+/**
+ * Internal component that handles:
+ * 1. Injecting the generated stylesheet (into shadow root or document.head)
+ * 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 {};

package/dist/shared/types.d.ts

@@ -0,0 +1,67 @@
+import { ComponentType } from '../react/adapter.ts';
+import { ToolbarSchema, PanelSchema, MenuSchema, SelectionMenuSchema } from '../index.ts';
+import { SelectionMenuPropsBase } from '../react/utils.ts';
+export type { SelectionMenuPropsBase };
+export type UIComponents = Record<string, ComponentType<BaseComponentProps>>;
+/**
+ * Base props that all custom components must accept
+ */
+export interface BaseComponentProps {
+    documentId: string;
+    [key: string]: any;
+}
+/**
+ * Props for toolbar renderer
+ * The app provides a component matching this contract
+ */
+export interface ToolbarRendererProps {
+    schema: ToolbarSchema;
+    documentId: string;
+    isOpen: boolean;
+    onClose?: () => void;
+    className?: string;
+}
+export type ToolbarRenderer = ComponentType<ToolbarRendererProps>;
+/**
+ * Props for panel renderer
+ * The app provides a component matching this contract
+ */
+export interface PanelRendererProps {
+    schema: PanelSchema;
+    documentId: string;
+    isOpen: boolean;
+    onClose: () => void;
+    className?: string;
+}
+export type PanelRenderer = ComponentType<PanelRendererProps>;
+/**
+ * Props for menu renderer
+ * The app provides a component matching this contract
+ */
+export interface MenuRendererProps {
+    schema: MenuSchema;
+    documentId: string;
+    anchorEl: HTMLElement | null;
+    onClose: () => void;
+    container?: HTMLElement | null;
+}
+export type MenuRenderer = ComponentType<MenuRendererProps>;
+/**
+ * Props for the selection menu renderer component
+ */
+export interface SelectionMenuRendererProps {
+    schema: SelectionMenuSchema;
+    documentId: string;
+    /** Full props from the layer including context */
+    props: SelectionMenuPropsBase;
+}
+export type SelectionMenuRenderer = ComponentType<SelectionMenuRendererProps>;
+/**
+ * All renderers the app must provide
+ */
+export interface UIRenderers {
+    toolbar: ToolbarRenderer;
+    panel: PanelRenderer;
+    menu: MenuRenderer;
+    selectionMenu: SelectionMenuRenderer;
+}

package/dist/shared-preact/auto-menu-renderer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Automatically renders menus when opened
+ *
+ * This component:
+ * 1. Listens to UI plugin state for open menus
+ * 2. Looks up anchor elements from the anchor registry
+ * 3. Renders menus using the user-provided menu renderer
+ */
+export interface AutoMenuRendererProps {
+    container?: HTMLElement | null;
+    documentId: string;
+}
+export declare function AutoMenuRenderer({ container, documentId }: AutoMenuRendererProps): import("preact").JSX.Element | null;

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

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

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

@@ -0,0 +1,14 @@
+/**
+ * Helper utilities for building renderers
+ */
+export declare function useItemRenderer(): {
+    /**
+     * Render a custom component by ID
+     *
+     * @param componentId - Component ID from schema
+     * @param documentId - Document ID
+     * @param props - Additional props to pass to component
+     * @returns Rendered component or null if not found
+     */
+    renderCustomComponent: (componentId: string, documentId: string, props?: any) => import("preact").JSX.Element | null;
+};

package/dist/shared-preact/hooks/use-register-anchor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Register a DOM element as an anchor for menus
+ *
+ * @param documentId - Document ID
+ * @param itemId - Item ID (typically matches the toolbar/menu item ID)
+ * @returns Ref callback to attach to the element
+ *
+ * @example
+ * ```tsx
+ * function ZoomButton({ documentId }: Props) {
+ *   const anchorRef = useRegisterAnchor(documentId, 'zoom-button');
+ *
+ *   return <button ref={anchorRef}>Zoom</button>;
+ * }
+ * ```
+ */
+export declare function useRegisterAnchor(documentId: string, itemId: string): (element: HTMLElement | null) => void;

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

@@ -0,0 +1,61 @@
+/**
+ * High-level hook for rendering UI from schema
+ *
+ * Provides simple functions to render toolbars and panels by placement+slot.
+ * Always passes isOpen state to renderers so they can control animations.
+ *
+ * Automatically subscribes to UI state changes for the given document.
+ */
+export declare function useSchemaRenderer(documentId: string): {
+    /**
+     * Render a toolbar by placement and slot
+     *
+     * Always renders with isOpen state when toolbar exists in slot.
+     *
+     * @param placement - 'top' | 'bottom' | 'left' | 'right'
+     * @param slot - Slot name (e.g. 'main', 'secondary')
+     *
+     * @example
+     * ```tsx
+     * {renderToolbar('top', 'main')}
+     * {renderToolbar('top', 'secondary')}
+     * ```
+     */
+    renderToolbar: (placement: "top" | "bottom" | "left" | "right", slot: string) => import("preact").JSX.Element | null;
+    /**
+     * Render a panel by placement and slot
+     *
+     * ALWAYS renders (when panel exists in slot) with isOpen state.
+     * Your renderer controls whether to display or animate.
+     *
+     * @param placement - 'left' | 'right' | 'top' | 'bottom'
+     * @param slot - Slot name (e.g. 'main', 'secondary', 'inspector')
+     *
+     * @example
+     * ```tsx
+     * {renderPanel('left', 'main')}
+     * {renderPanel('right', 'main')}
+     * ```
+     */
+    renderPanel: (placement: "left" | "right" | "top" | "bottom", slot: string) => import("preact").JSX.Element | null;
+    /**
+     * Helper: Get all active toolbars for this document
+     * Useful for batch rendering or debugging
+     */
+    getActiveToolbars: () => {
+        placement: string;
+        slot: string;
+        toolbarId: string;
+        isOpen: boolean;
+    }[];
+    /**
+     * Helper: Get all active panels for this document
+     * Useful for batch rendering or debugging
+     */
+    getActivePanels: () => {
+        placement: string;
+        slot: string;
+        panelId: string;
+        isOpen: boolean;
+    }[];
+};

package/dist/shared-preact/hooks/use-selection-menu.d.ts

@@ -0,0 +1,11 @@
+import { SelectionMenuRenderFn } from '../../preact/utils.ts';
+/**
+ * Creates a render function for a selection menu from the schema
+ *
+ * @param menuId - The selection menu ID from schema
+ * @param documentId - Document ID
+ * @returns A render function compatible with layer selectionMenu props
+ */
+export declare function useSelectionMenu<TContext extends {
+    type: string;
+}>(menuId: string, documentId: string): SelectionMenuRenderFn<TContext> | undefined;

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

@@ -1,11 +1,19 @@
-import { UIPlugin } from '../../lib/index.ts';
-export declare const useUIPlugin: () => {
-    plugin: UIPlugin | null;
+import { UIPlugin, UIDocumentState, UISchema } from '../../lib/index.ts';
+export declare const useUICapability: () => {
+    provides: Readonly<import('../../lib/index.ts').UICapability> | null;
     isLoading: boolean;
     ready: Promise<void>;
 };
-export declare const useUICapability: () => {
-    provides: Readonly<import('../../lib/index.ts').UICapability> | null;
+export declare const useUIPlugin: () => {
+    plugin: UIPlugin | null;
     isLoading: boolean;
     ready: Promise<void>;
 };
+/**
+ * Get UI state for a document
+ */
+export declare const useUIState: (documentId: string) => UIDocumentState | null;
+/**
+ * Get UI schema
+ */
+export declare const useUISchema: () => UISchema | null;

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

@@ -1,3 +1,6 @@
-export * from './components';
 export * from './hooks';
+export * from './registries';
+export { UIProvider } from './provider';
+export type { UIProviderProps } from './provider';
+export * from './types';
 export * from '../lib/index.ts';

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

@@ -0,0 +1,68 @@
+import { ReactNode, ComponentType, HTMLAttributes } from '../preact/adapter.ts';
+import { BaseComponentProps, UIRenderers } from './types';
+/**
+ * UIProvider Props
+ */
+export interface UIProviderProps extends HTMLAttributes<HTMLDivElement> {
+    children: ReactNode;
+    /**
+     * Document ID for this UI context
+     * Required for menu rendering
+     */
+    documentId: string;
+    /**
+     * Custom component registry
+     * Maps component IDs to components
+     */
+    components?: Record<string, ComponentType<BaseComponentProps>>;
+    /**
+     * REQUIRED: User-provided renderers
+     * These define how toolbars, panels, and menus are displayed
+     */
+    renderers: UIRenderers;
+    /**
+     * Optional: Container for menu portal
+     * Defaults to document.body
+     */
+    menuContainer?: HTMLElement | null;
+}
+/**
+ * UIProvider - Single provider for all UI plugin functionality
+ *
+ * Manages:
+ * - Anchor registry for menu positioning
+ * - Component registry for custom components
+ * - Renderers for toolbars, panels, and menus
+ * - Automatic menu rendering
+ *
+ * @example
+ * ```tsx
+ * <EmbedPDF engine={engine} plugins={plugins}>
+ *   {({ pluginsReady }) => (
+ *     pluginsReady && (
+ *       <DocumentContext>
+ *         {({ activeDocumentId }) => (
+ *           activeDocumentId && (
+ *             <UIProvider
+ *               documentId={activeDocumentId}
+ *               components={{
+ *                 'thumbnail-panel': ThumbnailPanel,
+ *                 'bookmark-panel': BookmarkPanel,
+ *               }}
+ *               renderers={{
+ *                 toolbar: ToolbarRenderer,
+ *                 panel: PanelRenderer,
+ *                 menu: MenuRenderer,
+ *               }}
+ *             >
+ *               <ViewerLayout />
+ *             </UIProvider>
+ *           )
+ *         )}
+ *       </DocumentContext>
+ *     )
+ *   )}
+ * </EmbedPDF>
+ * ```
+ */
+export declare function UIProvider({ children, documentId, components, renderers, menuContainer, ...restProps }: UIProviderProps): import("preact").JSX.Element;

package/dist/shared-preact/registries/anchor-registry.d.ts

@@ -0,0 +1,16 @@
+import { ReactNode } from '../../preact/adapter.ts';
+/**
+ * Anchor Registry
+ *
+ * Tracks DOM elements for menu positioning.
+ * Each anchor is scoped by documentId and itemId.
+ */
+export interface AnchorRegistry {
+    register(documentId: string, itemId: string, element: HTMLElement): void;
+    unregister(documentId: string, itemId: string): void;
+    getAnchor(documentId: string, itemId: string): HTMLElement | null;
+}
+export declare function AnchorRegistryProvider({ children }: {
+    children: ReactNode;
+}): import("preact").JSX.Element;
+export declare function useAnchorRegistry(): AnchorRegistry;

package/dist/shared-preact/registries/component-registry.d.ts

@@ -0,0 +1,20 @@
+import { ComponentType, ReactNode } from '../../preact/adapter.ts';
+import { BaseComponentProps } from '../types';
+/**
+ * Component Registry
+ *
+ * Stores custom components that can be referenced in the UI schema.
+ */
+export interface ComponentRegistry {
+    register(id: string, component: ComponentType<BaseComponentProps>): void;
+    unregister(id: string): void;
+    get(id: string): ComponentType<BaseComponentProps> | undefined;
+    has(id: string): boolean;
+    getRegisteredIds(): string[];
+}
+export interface ComponentRegistryProviderProps {
+    children: ReactNode;
+    initialComponents?: Record<string, ComponentType<BaseComponentProps>>;
+}
+export declare function ComponentRegistryProvider({ children, initialComponents, }: ComponentRegistryProviderProps): import("preact").JSX.Element;
+export declare function useComponentRegistry(): ComponentRegistry;

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

@@ -0,0 +1,3 @@
+export * from './anchor-registry';
+export * from './component-registry';
+export * from './renderers-registry';

package/dist/shared-preact/registries/renderers-registry.d.ts

@@ -0,0 +1,8 @@
+import { ReactNode } from '../../preact/adapter.ts';
+import { UIRenderers } from '../types';
+export interface RenderersProviderProps {
+    children: ReactNode;
+    renderers: UIRenderers;
+}
+export declare function RenderersProvider({ children, renderers }: RenderersProviderProps): import("preact").JSX.Element;
+export declare function useRenderers(): UIRenderers;

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

@@ -0,0 +1,12 @@
+import { ReactNode, HTMLAttributes } from '../preact/adapter.ts';
+interface UIRootProps extends HTMLAttributes<HTMLDivElement> {
+    children: ReactNode;
+}
+/**
+ * Internal component that handles:
+ * 1. Injecting the generated stylesheet (into shadow root or document.head)
+ * 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 {};