@visulima/dev-toolbar 1.0.0-alpha.4 → 1.0.0-alpha.40

package/dist/toolbar/hooks/use-toolbar.d.ts

@@ -1,16 +0,0 @@
-import type { ToolbarPlacement } from "../../types/index.d.ts";
-/**
- * Exposes toolbar visibility and placement controls from the toolbar context.
- */
-declare const useToolbar: () => {
-    hide: () => void;
-    isDragging: boolean;
-    isVisible: boolean;
-    placement: ToolbarPlacement;
-    setDragging: (dragging: boolean) => void;
-    setPlacement: (placement: ToolbarPlacement) => void;
-    show: () => void;
-    toggle: () => void;
-};
-export { useToolbar };
-export default useToolbar;

package/dist/toolbar/settings.d.ts

@@ -1,17 +0,0 @@
-import type { ToolbarSettings } from "../types/toolbar.d.ts";
-/**
- * Loads settings from localStorage, merging with defaults.
- * @returns Toolbar settings.
- */
-export declare const loadSettings: () => ToolbarSettings;
-/**
- * Saves settings to localStorage.
- * @param settings Toolbar settings to save.
- */
-export declare const saveSettings: (settings: ToolbarSettings) => void;
-/**
- * Merges partial updates into the current settings and persists them.
- * @param updates Partial settings to update.
- * @returns Updated settings.
- */
-export declare const updateSettings: (updates: Partial<ToolbarSettings>) => ToolbarSettings;

package/dist/toolbar/stylesheet.d.ts

@@ -1,3 +0,0 @@
-declare const sharedToolbarStylesheet: CSSStyleSheet | undefined;
-export { sharedToolbarStylesheet };
-export default sharedToolbarStylesheet;

package/dist/toolbar/utils/index.d.ts

@@ -1,12 +0,0 @@
-/**
- * Clamps a value between min and max.
- */
-export declare const clamp: (value: number, min: number, max: number) => number;
-/**
- * Returns true when the current browser is Safari.
- */
-export declare const checkIsSafari: () => boolean;
-/**
- * Converts a pixel string value to a number (e.g. "10px" becomes 10).
- */
-export declare const pixelToNumber: (value: string | number) => number;

package/dist/types/app.d.ts

@@ -1,175 +0,0 @@
-import type { ComponentType } from "preact";
-import type { NotificationLevel } from "./toolbar.d.ts";
-/**
- * Server helpers available to apps
- */
-export interface ServerHelpers {
-    /**
-     * RPC client for calling server functions
-     */
-    rpc: {
-        [K in keyof ServerFunctions]: ServerFunctions[K];
-    };
-}
-/**
- * Props passed to app tooltip (hover mini-canvas) components.
- * Keep compact — tooltip components should be lightweight.
- */
-export interface AppTooltipProps {
-    /**
-     * Server helpers (RPC, etc.)
-     */
-    helpers: ServerHelpers;
-}
-/**
- * Event target for app communication
- */
-export interface ToolbarAppEventTarget extends EventTarget {
-    /**
-     * Dispatch a custom event
-     */
-    dispatchEvent: (event: Event) => boolean;
-}
-/**
- * App view configuration
- */
-export type AppView = {
-    /**
-     * Render app inline in shadow DOM (default)
-     */
-    type: "inline";
-} | {
-    /**
-     * URL to load in iframe
-     */
-    src: string;
-    /**
-     * Render app in iframe for isolation
-     */
-    type: "iframe";
-};
-/**
- * Props passed to Preact component apps
- */
-export interface AppComponentProps {
-    /**
-     * Event target for app communication
-     */
-    eventTarget: ToolbarAppEventTarget;
-    /**
-     * Server helpers (RPC, etc.)
-     */
-    helpers: ServerHelpers;
-}
-/**
- * Dev toolbar app definition
- */
-export interface DevToolbarApp {
-    /**
-     * Called before app is toggled off
-     * Return false to prevent closing
-     * @param canvas Shadow root of the app
-     * @returns Whether to allow closing
-     */
-    beforeTogglingOff?: (canvas: ShadowRoot) => boolean | Promise<boolean>;
-    /**
-     * Preact component for rendering (alternative to init)
-     * If provided, this will be used instead of init
-     */
-    component?: ComponentType<AppComponentProps>;
-    /**
-     * When true, this app is automatically activated when the toolbar opens for
-     * the first time (or when no other app has been activated yet).
-     * Only the first registered app with defaultOpen: true is used.
-     * @default false
-     */
-    defaultOpen?: boolean;
-    /**
-     * Called when the app is unregistered / removed from the toolbar.
-     * Use this for final cleanup (event listeners, timers, subscriptions).
-     * @param canvas Shadow root of the app
-     */
-    destroy?: (canvas: ShadowRoot) => Promise<void> | void;
-    /**
-     * Icon HTML string (SVG)
-     */
-    icon: string;
-    /**
-     * Unique identifier for the app
-     */
-    id: string;
-    /**
-     * Initialize the app when opened (vanilla JS/CSS/HTML)
-     * @param canvas Shadow root to render into
-     * @param eventTarget Event target for app communication
-     * @param helpers Server helpers (RPC, etc.)
-     */
-    init?: (canvas: ShadowRoot, eventTarget: ToolbarAppEventTarget, helpers: ServerHelpers) => void | Promise<void>;
-    /**
-     * Display name of the app
-     */
-    name: string;
-    /**
-     * Action button callback — called when the button is activated (active: false → true).
-     * When present, clicking the toolbar button will NOT open a panel.
-     * Instead the button toggles its active state and calls onClick (activate)
-     * or onDeactivate (deactivate).
-     */
-    onClick?: () => Promise<void> | void;
-    /**
-     * Called when the action button is deactivated (active: true → false).
-     * Only meaningful when onClick is also provided.
-     */
-    onDeactivate?: () => Promise<void> | void;
-    /**
-     * Optional hover tooltip component — renders a compact live preview when the
-     * user hovers over this app's button in the toolbar pill.
-     * The component should be small (≤280px wide) and self-contained.
-     * If omitted, hovering shows the native title tooltip only.
-     */
-    tooltip?: ComponentType<AppTooltipProps>;
-    /**
-     * App rendering mode
-     */
-    view?: AppView;
-}
-/**
- * Internal app state (extends DevToolbarApp)
- */
-export interface DevToolbarAppState extends DevToolbarApp {
-    /**
-     * Whether the app is currently active/open
-     */
-    active: boolean;
-    /**
-     * Whether this is a built-in app
-     */
-    builtIn: boolean;
-    /**
-     * Event target for this app
-     */
-    eventTarget: ToolbarAppEventTarget;
-    /**
-     * Notification state
-     */
-    notification: {
-        /**
-         * Notification level
-         */
-        level?: NotificationLevel;
-        /**
-         * Whether notification is active
-         */
-        state: boolean;
-    };
-    /**
-     * App initialization status
-     */
-    status: "ready" | "loading" | "pending" | "error";
-}
-/**
- * Placeholder for ServerFunctions (defined in rpc.ts)
- */
-export interface ServerFunctions {
-    [key: string]: (...args: any[]) => Promise<any>;
-}

package/dist/types/global-api.d.ts

@@ -1,91 +0,0 @@
-import type { DevToolbarApp } from "./app.d.ts";
-import type { DevToolbarHook } from "./hooks.d.ts";
-import type { ServerFunctions } from "./rpc.d.ts";
-import type { ToolbarSettings } from "./toolbar.d.ts";
-/**
- * Global DevTools API interface.
- * Exposed as window.__VISULIMA_DEVTOOLS__
- */
-interface VisulimaDevTools {
-    /**
-     * Clears notification for an app.
-     */
-    clearNotification: (appId: string) => void;
-    /**
-     * Closes the currently active app.
-     */
-    closeApp: () => Promise<void>;
-    /**
-     * Gets the currently active app ID.
-     */
-    getActiveApp: () => string | undefined;
-    /**
-     * Gets all registered apps.
-     */
-    getApps: () => DevToolbarApp[];
-    /**
-     * Gets current toolbar settings.
-     */
-    getSettings: () => ToolbarSettings;
-    /**
-     * Hides the toolbar.
-     */
-    hide: () => void;
-    /**
-     * Hook instance for event subscriptions.
-     */
-    hook: DevToolbarHook;
-    /**
-     * Shows a notification for an app.
-     */
-    notify: (appId: string, level: "info" | "warning" | "error") => void;
-    /**
-     * Opens an app by ID.
-     */
-    openApp: (appId: string) => Promise<void>;
-    /**
-     * Registers a custom app.
-     */
-    registerApp: (app: DevToolbarApp) => void;
-    /**
-     * RPC client for calling server functions.
-     */
-    rpc: ServerFunctions;
-    /**
-     * Directly sets the active state of an action button without invoking callbacks.
-     * Useful for deactivating a button from async work running outside the toolbar.
-     */
-    setAppActive: (appId: string, active: boolean) => void;
-    /**
-     * Shows the toolbar.
-     */
-    show: () => void;
-    /**
-     * Toggles toolbar visibility.
-     */
-    toggle: () => void;
-    /**
-     * Unregisters an app by ID.
-     */
-    unregisterApp: (appId: string) => void;
-    /**
-     * Updates toolbar settings.
-     */
-    updateSettings: (settings: Partial<ToolbarSettings>) => void;
-    /**
-     * Package version.
-     */
-    version: string;
-}
-/**
- * Global API declaration
- */
-declare global {
-    interface Window {
-        /**
-         * Visulima DevTools global API.
-         */
-        __VISULIMA_DEVTOOLS__?: VisulimaDevTools;
-    }
-}
-export type { VisulimaDevTools };

package/dist/types/hooks.d.ts

@@ -1,86 +0,0 @@
-import type { DevToolbarApp } from "./app.d.ts";
-import type { TimelineEvent } from "./timeline.d.ts";
-/**
- * Hook event definitions
- */
-interface HookEvents {
-    [key: string]: (...args: any[]) => void;
-    /**
-     * App error occurred.
-     * @param error Error object.
-     * @param appId Optional app ID where error occurred.
-     */
-    "app:error": (error: Error, appId?: string) => void;
-    /**
-     * DevTools closed.
-     */
-    "devtools:close": () => void;
-    /**
-     * DevTools initialized.
-     */
-    "devtools:init": () => void;
-    /**
-     * DevTools opened.
-     * @param appId ID of the opened app.
-     */
-    "devtools:open": (appId: string) => void;
-    /**
-     * Timeline event added.
-     * @param event Timeline event.
-     */
-    "timeline:event": (event: TimelineEvent) => void;
-}
-/**
- * Dev toolbar hook interface.
- * Exposed as window.__DEV_TOOLBAR_HOOK__
- */
-interface DevToolbarHook {
-    /**
-     * Adds a timeline event.
-     * @param groupId Timeline group ID.
-     * @param event Timeline event.
-     */
-    addTimelineEvent: (groupId: string, event: TimelineEvent) => void;
-    /**
-     * Emits an event.
-     * @param event Event name.
-     * @param args Event arguments.
-     */
-    emit: <T extends keyof HookEvents>(event: T, ...args: Parameters<HookEvents[T]>) => void;
-    /**
-     * Unsubscribes from an event.
-     * @param event Event name.
-     * @param handler Optional specific handler to remove.
-     */
-    off: <T extends keyof HookEvents>(event: T, handler?: HookEvents[T]) => void;
-    /**
-     * Subscribes to an event.
-     * @param event Event name.
-     * @param handler Event handler.
-     * @returns Unsubscribe function.
-     */
-    on: <T extends keyof HookEvents>(event: T, handler: HookEvents[T]) => () => void;
-    /**
-     * Subscribes to an event once.
-     * @param event Event name.
-     * @param handler Event handler.
-     */
-    once: <T extends keyof HookEvents>(event: T, handler: HookEvents[T]) => void;
-    /**
-     * Registers a custom app.
-     * @param app App definition.
-     */
-    registerApp: (app: DevToolbarApp) => void;
-}
-/**
- * Global hook declaration
- */
-declare global {
-    interface Window {
-        /**
-         * Dev toolbar hook for library integrations.
-         */
-        __DEV_TOOLBAR_HOOK__?: DevToolbarHook;
-    }
-}
-export type { DevToolbarHook, HookEvents };

package/dist/types/index.d.ts

@@ -1,12 +0,0 @@
-/**
- * Public type exports
- */
-export type { AppView, DevToolbarApp, DevToolbarAppState, ServerFunctions, ServerHelpers, ToolbarAppEventTarget } from "./app.d.ts";
-export type { VisulimaDevTools } from "./global-api.d.ts";
-export type { DevToolbarHook, HookEvents } from "./hooks.d.ts";
-export type { ChannelFactory, MessageChannel, MessageChannelContext } from "./messaging.d.ts";
-export type { ClientRPCContext, ClientFunctions as RPCClientFunctions, ServerFunctions as RPCServerFunctions, ServerRPCContext } from "./rpc.d.ts";
-export type { TimelineEvent, TimelineEventLevel, TimelineGroup } from "./timeline.d.ts";
-export { DEFAULT_TIMELINE_GROUPS } from "./timeline.d.ts";
-export type { FrameState, NotificationLevel, PositionAnchor, ToolbarPlacement, ToolbarSettings } from "./toolbar.d.ts";
-export { DEFAULT_TOOLBAR_SETTINGS } from "./toolbar.d.ts";

package/dist/types/messaging.d.ts

@@ -1,43 +0,0 @@
-/**
- * Message channel interface for bidirectional communication
- */
-export interface MessageChannel<TEvents extends Record<string, (...args: any[]) => void>> {
-    /**
-     * Unsubscribe from an event
-     * @param event Event name
-     * @param handler Optional specific handler to remove
-     */
-    off: <K extends keyof TEvents>(event: K, handler?: TEvents[K]) => void;
-    /**
-     * Subscribe to an event
-     * @param event Event name
-     * @param handler Event handler
-     * @returns Unsubscribe function
-     */
-    on: <K extends keyof TEvents>(event: K, handler: TEvents[K]) => () => void;
-    /**
-     * Subscribe to an event once
-     * @param event Event name
-     * @param handler Event handler
-     */
-    once: <K extends keyof TEvents>(event: K, handler: TEvents[K]) => void;
-    /**
-     * Send a message/event
-     * @param event Event name
-     * @param data Event data
-     */
-    send: <K extends keyof TEvents>(event: K, ...args: Parameters<TEvents[K]>) => void;
-}
-/**
- * Channel factory function
- */
-export type ChannelFactory<TEvents extends Record<string, (...args: any[]) => void>> = () => MessageChannel<TEvents>;
-/**
- * Factory result providing a method to instantiate named message channels.
- */
-export interface MessageChannelContext<TEvents extends Record<string, (...args: any[]) => void>> {
-    /**
-     * Creates and returns a new channel instance.
-     */
-    createChannel: () => MessageChannel<TEvents>;
-}

package/dist/types/rpc.d.ts

@@ -1,97 +0,0 @@
-import type { ViteDevServer } from "vite";
-import type { SerializableModuleNode } from "../rpc/functions/module-graph.d.ts";
-import type { TailwindConfigResult } from "../rpc/functions/tailwind-config.d.ts";
-/**
- * Server-side RPC functions
- * These can be called from the client
- */
-export interface ServerFunctions {
-    /**
-     * Extension point for custom server functions
-     */
-    [key: string]: (...args: any[]) => Promise<any>;
-    /**
-     * Get module dependency graph
-     */
-    getModuleGraph: () => Promise<SerializableModuleNode[]>;
-    /**
-     * Get full Tailwind CSS theme (default + user overrides)
-     */
-    getTailwindConfig: () => Promise<TailwindConfigResult>;
-    /**
-     * Get Vite configuration
-     */
-    getViteConfig: () => Promise<Record<string, any>>;
-    /**
-     * Open file in editor
-     * @param file File path
-     * @param line Line number (1-based)
-     * @param column Column number (1-based)
-     */
-    openInEditor: (file: string, line?: number, column?: number) => Promise<void>;
-    /**
-     * Read file contents
-     * @param path File path
-     */
-    readFile: (path: string) => Promise<string>;
-}
-/**
- * Client-side RPC functions
- * These can be called from the server
- */
-export interface ClientFunctions {
-    [key: string]: (...args: any[]) => void;
-    /**
-     * Notify client of config change
-     * @param config New Vite config
-     */
-    onConfigChange: (config: Record<string, unknown>) => void;
-    /**
-     * Notify client of HMR update
-     * @param payload HMR payload
-     */
-    onHMRUpdate: (payload: unknown) => void;
-    /**
-     * Notify client of module update
-     * @param module Updated module node
-     */
-    onModuleUpdate: (module: SerializableModuleNode) => void;
-}
-/**
- * RPC context for server-side
- */
-export interface ServerRPCContext {
-    /**
-     * Call a client function
-     * @param name Function name
-     * @param args Function arguments
-     */
-    callClient: <K extends keyof ClientFunctions>(name: K, ...args: Parameters<ClientFunctions[K]>) => void;
-    /**
-     * Register a server function
-     * @param name Function name
-     * @param fn Function implementation
-     */
-    registerFunction: <K extends keyof ServerFunctions>(name: K, function_: ServerFunctions[K]) => void;
-    /**
-     * Vite dev server instance
-     */
-    server: ViteDevServer;
-}
-/**
- * RPC context for client-side
- */
-export interface ClientRPCContext {
-    /**
-     * Call a server function
-     * @param name Function name
-     * @param args Function arguments
-     */
-    callServer: <K extends keyof ServerFunctions>(name: K, ...args: Parameters<ServerFunctions[K]>) => Promise<ReturnType<ServerFunctions[K]>>;
-    /**
-     * Register a client function
-     * @param name Function name
-     * @param function_ Function implementation
-     */
-    registerFunction: <K extends keyof ClientFunctions>(name: K, function_: ClientFunctions[K]) => void;
-}

package/dist/types/timeline.d.ts

@@ -1,62 +0,0 @@
-/**
- * Severity levels for timeline events.
- */
-export type TimelineEventLevel = "info" | "warning" | "error";
-/**
- * A single captured event displayed in the timeline panel.
- */
-export interface TimelineEvent {
-    /**
-     * Optional event data
-     */
-    data?: Record<string, any>;
-    /**
-     * Optional duration (milliseconds)
-     */
-    duration?: number;
-    /**
-     * Unique event ID
-     */
-    id: string;
-    /**
-     * Event level
-     */
-    level?: TimelineEventLevel;
-    /**
-     * Optional subtitle
-     */
-    subtitle?: string;
-    /**
-     * Timestamp (milliseconds since epoch)
-     */
-    time: number;
-    /**
-     * Event title
-     */
-    title: string;
-}
-/**
- * A named group that holds related timeline events.
- */
-export interface TimelineGroup {
-    /**
-     * Group color (hex or CSS color)
-     */
-    color?: string;
-    /**
-     * Events in this group
-     */
-    events: TimelineEvent[];
-    /**
-     * Group ID
-     */
-    id: string;
-    /**
-     * Group label
-     */
-    label: string;
-}
-/**
- * Default timeline groups
- */
-export declare const DEFAULT_TIMELINE_GROUPS: ReadonlyArray<TimelineGroup>;

package/dist/types/toolbar.d.ts

@@ -1,56 +0,0 @@
-/**
- * Toolbar placement options (for backward compatibility)
- */
-export type ToolbarPlacement = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
-/**
- * Notification levels
- */
-export type NotificationLevel = "info" | "warning" | "error";
-/**
- * Position anchor (which edge the toolbar is attached to)
- * Matches Vue DevTools positioning
- */
-export type PositionAnchor = "top" | "bottom" | "left" | "right";
-/**
- * Frame state - matches Vue DevTools DevToolsFrameState
- * @see https://github.com/vuejs/devtools/blob/main/packages/overlay/src/composables/state.ts
- */
-export interface FrameState {
-    /**
-     * Horizontal position as percentage (0-100)
-     */
-    left: number;
-    /**
-     * Whether panel is open
-     */
-    open: boolean;
-    /**
-     * Which edge the toolbar is anchored to
-     */
-    position: PositionAnchor;
-    /**
-     * Vertical position as percentage (0-100)
-     */
-    top: number;
-}
-/**
- * Configuration options controlling the toolbar's initial appearance.
- */
-export interface ToolbarSettings {
-    /**
-     * Whether toolbar is visible by default
-     */
-    defaultVisible: boolean;
-    /**
-     * Toolbar placement on screen
-     */
-    placement: ToolbarPlacement;
-    /**
-     * Whether to show notifications
-     */
-    showNotifications: boolean;
-}
-/**
- * Default toolbar settings
- */
-export declare const DEFAULT_TOOLBAR_SETTINGS: ToolbarSettings;