@nice2dev/ui-graphics 1.0.0

package/dist/types/core/i18n.d.ts

@@ -0,0 +1,27 @@
+/**
+ * i18n — Lightweight translation context for @nice2dev/ui-graphics.
+ *
+ * Drop-in replacement for react-i18next's useTranslation, requires NO
+ * external dependencies. Consumers can optionally wrap with NiceI18nProvider
+ * to supply their own translation function. Falls back to the default
+ * (English key strings) when no provider is present.
+ *
+ * Usage in components:
+ *   const { t } = useNiceTranslation();
+ *   <button>{t('actions.save', 'Save')}</button>
+ *
+ * Usage in apps:
+ *   <NiceI18nProvider t={(key, fallback) => myI18n(key) ?? fallback}>
+ *     <App />
+ *   </NiceI18nProvider>
+ */
+import React from 'react';
+export type NiceTranslateFn = (key: string, defaultValue: string) => string;
+export interface NiceI18nProviderProps {
+    t: NiceTranslateFn;
+    children: React.ReactNode;
+}
+export declare const NiceI18nProvider: React.FC<NiceI18nProviderProps>;
+export declare function useNiceTranslation(): {
+    t: NiceTranslateFn;
+};

package/dist/types/core/integrations.d.ts

@@ -0,0 +1,103 @@
+/**
+ * integrations.ts — External service integrations for editors.
+ *
+ * Stock image pickers (Unsplash/Pexels), Adobe CC connector,
+ * Figma import/export, template library, and AI image generation.
+ */
+export interface StockImage {
+    id: string;
+    url: string;
+    thumbnailUrl: string;
+    author: string;
+    source: "unsplash" | "pexels";
+    width: number;
+    height: number;
+    description?: string;
+}
+export interface StockImageSearchOptions {
+    query: string;
+    page?: number;
+    perPage?: number;
+    orientation?: "landscape" | "portrait" | "squarish";
+}
+export interface FigmaImportResult {
+    nodes: FigmaNode[];
+    images: Map<string, Blob>;
+}
+export interface FigmaNode {
+    id: string;
+    name: string;
+    type: string;
+    width: number;
+    height: number;
+    svg?: string;
+    imageData?: ImageData;
+}
+export interface AIGenerationOptions {
+    prompt: string;
+    width?: number;
+    height?: number;
+    style?: "realistic" | "artistic" | "pixel-art" | "vector" | "sketch";
+    provider: "openai" | "stability" | "custom";
+    apiKey?: string;
+    apiUrl?: string;
+}
+export interface AIGenerationResult {
+    imageUrl: string;
+    imageBlob: Blob;
+    metadata: Record<string, unknown>;
+}
+export interface TemplateItem {
+    id: string;
+    name: string;
+    category: string;
+    thumbnailUrl: string;
+    width: number;
+    height: number;
+    data: unknown;
+}
+export declare class UnsplashProvider {
+    private accessKey;
+    constructor(accessKey: string);
+    search(options: StockImageSearchOptions): Promise<StockImage[]>;
+}
+export declare class PexelsProvider {
+    private apiKey;
+    constructor(apiKey: string);
+    search(options: StockImageSearchOptions): Promise<StockImage[]>;
+}
+export interface AdobeCCConfig {
+    clientId: string;
+    redirectUri: string;
+}
+export declare class AdobeCCConnector {
+    private config;
+    constructor(config: AdobeCCConfig);
+    /** Get the OAuth authorization URL. */
+    getAuthUrl(): string;
+    /** Import a file from Adobe CC Libraries. */
+    importFromLibrary(accessToken: string, assetId: string): Promise<Blob>;
+}
+export declare class FigmaConnector {
+    private accessToken;
+    constructor(accessToken: string);
+    /** Import nodes from a Figma file. */
+    importFile(fileKey: string, nodeIds?: string[]): Promise<FigmaImportResult>;
+    /** Export a design to Figma (via plugin API—returns Figma plugin code). */
+    exportToFigmaPlugin(svg: string, nodeName?: string): string;
+    private extractNodes;
+}
+export declare class TemplateLibrary {
+    private templates;
+    /** Register a template. */
+    register(template: TemplateItem): void;
+    /** Get all templates. */
+    getAll(): TemplateItem[];
+    /** Get templates by category. */
+    getByCategory(category: string): TemplateItem[];
+    /** Get all categories. */
+    getCategories(): string[];
+    /** Search templates by name. */
+    search(query: string): TemplateItem[];
+}
+export declare function generateAIImage(options: AIGenerationOptions): Promise<AIGenerationResult>;

package/dist/types/core/minimap.d.ts

@@ -0,0 +1,49 @@
+/**
+ * minimap.ts — Zoom navigator / minimap component for editors.
+ *
+ * Provides a small overview of the full canvas with a viewport indicator
+ * that can be dragged to navigate around the document.
+ */
+import React from "react";
+export interface MinimapConfig {
+    /** Width of the minimap panel in pixels. */
+    width?: number;
+    /** Height of the minimap panel in pixels. */
+    height?: number;
+    /** Show/hide the minimap. */
+    visible?: boolean;
+    /** Position on screen. */
+    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    /** Opacity of the minimap. */
+    opacity?: number;
+}
+export interface ViewportRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface MinimapProps {
+    /** The full canvas/document as a data URL or canvas ref. */
+    canvasRef?: React.RefObject<HTMLCanvasElement | null>;
+    /** Alternative: provide image data directly. */
+    imageDataUrl?: string;
+    /** Total document dimensions. */
+    documentWidth: number;
+    documentHeight: number;
+    /** Currently visible viewport. */
+    viewport: ViewportRect;
+    /** Called when user drags the viewport indicator. */
+    onViewportChange?: (viewport: ViewportRect) => void;
+    /** Configuration. */
+    config?: MinimapConfig;
+    className?: string;
+}
+/** Zoom navigator / minimap showing a scaled-down view of the full document. */
+export declare const Minimap: React.FC<MinimapProps>;
+/** Hook for managing minimap visibility state. */
+export declare function useMinimap(initialVisible?: boolean): {
+    visible: boolean;
+    setVisible: React.Dispatch<React.SetStateAction<boolean>>;
+    toggle: () => void;
+};

package/dist/types/core/plugins.d.ts

@@ -0,0 +1,111 @@
+/**
+ * plugins.ts — Plugin system for @nice2dev/ui-graphics editors.
+ *
+ * Allows third-party extensions to register custom tools, filters,
+ * export formats, and UI panels for any editor.
+ */
+export type EditorType = "pixel" | "vector" | "photo" | "animation" | "game";
+export interface PluginTool {
+    id: string;
+    label: string;
+    icon?: string;
+    cursor?: string;
+    onActivate?: () => void;
+    onDeactivate?: () => void;
+    onPointerDown?: (x: number, y: number, ctx: CanvasRenderingContext2D) => void;
+    onPointerMove?: (x: number, y: number, ctx: CanvasRenderingContext2D) => void;
+    onPointerUp?: (x: number, y: number, ctx: CanvasRenderingContext2D) => void;
+}
+export interface PluginFilter {
+    id: string;
+    label: string;
+    category?: string;
+    apply: (imageData: ImageData) => ImageData;
+}
+export interface PluginExporter {
+    id: string;
+    label: string;
+    extension: string;
+    mimeType: string;
+    export: (data: unknown) => Blob | Promise<Blob>;
+}
+export interface PluginPanel {
+    id: string;
+    label: string;
+    position: "left" | "right" | "bottom";
+    render: (props: {
+        editor: unknown;
+    }) => React.ReactNode;
+}
+export interface PluginMenuAction {
+    id: string;
+    label: string;
+    menu: "file" | "edit" | "view" | "tools" | "help";
+    shortcut?: string;
+    execute: () => void;
+}
+export interface EditorPlugin {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    /** Which editors this plugin applies to. Empty = all. */
+    editors?: EditorType[];
+    tools?: PluginTool[];
+    filters?: PluginFilter[];
+    exporters?: PluginExporter[];
+    panels?: PluginPanel[];
+    menuActions?: PluginMenuAction[];
+    /** Called when plugin is loaded. */
+    onInit?: () => void;
+    /** Called when plugin is unloaded. */
+    onDestroy?: () => void;
+}
+import React from "react";
+type PluginEventHandler = (plugin: EditorPlugin) => void;
+declare class PluginRegistryImpl {
+    private plugins;
+    private listeners;
+    /** Register a plugin. Calls onInit if defined. */
+    register(plugin: EditorPlugin): void;
+    /** Unregister a plugin. Calls onDestroy if defined. */
+    unregister(pluginId: string): void;
+    /** Get a registered plugin by ID. */
+    get(pluginId: string): EditorPlugin | undefined;
+    /** Get all registered plugins. */
+    getAll(): EditorPlugin[];
+    /** Get plugins for a specific editor type. */
+    getForEditor(editor: EditorType): EditorPlugin[];
+    /** Get all tools from plugins for a specific editor. */
+    getTools(editor: EditorType): PluginTool[];
+    /** Get all filters from plugins for a specific editor. */
+    getFilters(editor: EditorType): PluginFilter[];
+    /** Get all exporters from plugins for a specific editor. */
+    getExporters(editor: EditorType): PluginExporter[];
+    /** Get all panels from plugins for a specific editor. */
+    getPanels(editor: EditorType): PluginPanel[];
+    /** Get all menu actions from plugins for a specific editor. */
+    getMenuActions(editor: EditorType): PluginMenuAction[];
+    /** Subscribe to registry events. */
+    on(event: string, handler: PluginEventHandler): () => void;
+    private emit;
+    /** Clear all plugins. */
+    clear(): void;
+}
+/** Global plugin registry singleton. */
+export declare const PluginRegistry: PluginRegistryImpl;
+/** React hook that returns plugins for a specific editor, re-renders on changes. */
+export declare function usePlugins(editor: EditorType): {
+    plugins: EditorPlugin[];
+    tools: PluginTool[];
+    filters: PluginFilter[];
+    exporters: PluginExporter[];
+    panels: PluginPanel[];
+    menuActions: PluginMenuAction[];
+};
+export declare const NicePluginProvider: React.FC<{
+    plugins?: EditorPlugin[];
+    children: React.ReactNode;
+}>;
+export declare function usePluginRegistry(): PluginRegistryImpl;
+export {};

package/dist/types/core/rtl.d.ts

@@ -0,0 +1,32 @@
+/**
+ * rtl.ts — Right-to-left (RTL) UI support for editors.
+ *
+ * Provides RTL direction context, CSS logical properties,
+ * and layout utilities for RTL languages (Arabic, Hebrew, etc.).
+ */
+import React from "react";
+export type Direction = "ltr" | "rtl";
+export interface RTLConfig {
+    direction: Direction;
+    /** Mirror horizontal tool positions. */
+    mirrorToolbar: boolean;
+    /** Mirror panel positions (left↔right). */
+    mirrorPanels: boolean;
+}
+/** Provider for RTL configuration. Wraps editors to enable RTL support. */
+export declare const NiceRTLProvider: React.FC<{
+    direction?: Direction;
+    mirrorToolbar?: boolean;
+    mirrorPanels?: boolean;
+    children: React.ReactNode;
+}>;
+/** Hook to access RTL configuration. */
+export declare function useRTL(): RTLConfig;
+/** Hook that returns true if the current direction is RTL. */
+export declare function useIsRTL(): boolean;
+/** Convert physical CSS properties to logical equivalents for RTL awareness. */
+export declare function logicalStyles(direction: Direction, styles: React.CSSProperties): React.CSSProperties;
+/** Get panel flex direction based on RTL. */
+export declare function rtlFlexDirection(direction: Direction): "row" | "row-reverse";
+/** Detect direction from document or browser locale. */
+export declare function detectDirection(): Direction;

package/dist/types/core/shortcuts.d.ts

@@ -0,0 +1,150 @@
+export interface ShortcutDef {
+    id: string;
+    label: string;
+    category: string;
+    /** Default key combo, e.g. "Ctrl+Z", "Shift+Delete". */
+    defaultKey: string;
+    /** Current (possibly remapped) key combo. */
+    currentKey: string;
+    /** Action to execute. */
+    action: () => void;
+}
+export interface ShortcutConfig {
+    /** Map of shortcut ID → custom key combo. */
+    overrides: Record<string, string>;
+}
+/** Convert a keyboard event to a key combo string. */
+export declare function eventToKeyCombo(e: KeyboardEvent): string;
+declare class ShortcutRegistryImpl {
+    private shortcuts;
+    private overrides;
+    private listeners;
+    /** Register a shortcut. */
+    register(def: Omit<ShortcutDef, "currentKey">): void;
+    /** Register multiple shortcuts at once. */
+    registerAll(defs: Array<Omit<ShortcutDef, "currentKey">>): void;
+    /** Unregister a shortcut. */
+    unregister(id: string): void;
+    /** Remap a shortcut to a new key combo. */
+    remap(id: string, newKey: string): void;
+    /** Reset a shortcut to its default. */
+    resetToDefault(id: string): void;
+    /** Reset all shortcuts to defaults. */
+    resetAll(): void;
+    /** Handle a keyboard event, triggering matching shortcuts. */
+    handleKeyEvent(e: KeyboardEvent): boolean;
+    /** Get all registered shortcuts. */
+    getAll(): ShortcutDef[];
+    /** Get shortcuts by category. */
+    getByCategory(category: string): ShortcutDef[];
+    /** Get all categories. */
+    getCategories(): string[];
+    /** Export custom overrides as JSON. */
+    exportConfig(): ShortcutConfig;
+    /** Import custom overrides from JSON. */
+    importConfig(config: ShortcutConfig): void;
+    /** Save overrides to localStorage. */
+    save(storageKey?: string): void;
+    /** Load overrides from localStorage. */
+    load(storageKey?: string): void;
+    /** Subscribe to changes. Returns unsubscribe function. */
+    subscribe(fn: () => void): () => void;
+    private notify;
+}
+/** Global shortcuts registry singleton. */
+export declare const ShortcutRegistry: ShortcutRegistryImpl;
+export declare const DEFAULT_SHORTCUTS: {
+    readonly undo: {
+        readonly id: "general.undo";
+        readonly label: "Undo";
+        readonly category: "General";
+        readonly defaultKey: "Ctrl+Z";
+    };
+    readonly redo: {
+        readonly id: "general.redo";
+        readonly label: "Redo";
+        readonly category: "General";
+        readonly defaultKey: "Ctrl+Y";
+    };
+    readonly copy: {
+        readonly id: "general.copy";
+        readonly label: "Copy";
+        readonly category: "General";
+        readonly defaultKey: "Ctrl+C";
+    };
+    readonly paste: {
+        readonly id: "general.paste";
+        readonly label: "Paste";
+        readonly category: "General";
+        readonly defaultKey: "Ctrl+V";
+    };
+    readonly cut: {
+        readonly id: "general.cut";
+        readonly label: "Cut";
+        readonly category: "General";
+        readonly defaultKey: "Ctrl+X";
+    };
+    readonly delete: {
+        readonly id: "general.delete";
+        readonly label: "Delete";
+        readonly category: "General";
+        readonly defaultKey: "Delete";
+    };
+    readonly selectAll: {
+        readonly id: "general.selectAll";
+        readonly label: "Select All";
+        readonly category: "General";
+        readonly defaultKey: "Ctrl+A";
+    };
+    readonly save: {
+        readonly id: "general.save";
+        readonly label: "Save";
+        readonly category: "General";
+        readonly defaultKey: "Ctrl+S";
+    };
+    readonly duplicate: {
+        readonly id: "general.duplicate";
+        readonly label: "Duplicate";
+        readonly category: "General";
+        readonly defaultKey: "Ctrl+D";
+    };
+    readonly zoomIn: {
+        readonly id: "view.zoomIn";
+        readonly label: "Zoom In";
+        readonly category: "View";
+        readonly defaultKey: "Ctrl+=";
+    };
+    readonly zoomOut: {
+        readonly id: "view.zoomOut";
+        readonly label: "Zoom Out";
+        readonly category: "View";
+        readonly defaultKey: "Ctrl+-";
+    };
+    readonly zoomFit: {
+        readonly id: "view.zoomFit";
+        readonly label: "Zoom to Fit";
+        readonly category: "View";
+        readonly defaultKey: "Ctrl+0";
+    };
+    readonly toggleGrid: {
+        readonly id: "view.toggleGrid";
+        readonly label: "Toggle Grid";
+        readonly category: "View";
+        readonly defaultKey: "Ctrl+'";
+    };
+    readonly toggleRulers: {
+        readonly id: "view.toggleRulers";
+        readonly label: "Toggle Rulers";
+        readonly category: "View";
+        readonly defaultKey: "Ctrl+R";
+    };
+    readonly toggleMinimap: {
+        readonly id: "view.toggleMinimap";
+        readonly label: "Toggle Minimap";
+        readonly category: "View";
+        readonly defaultKey: "Ctrl+M";
+    };
+};
+/** Hook to use shortcuts in a component. Attaches keyboard listener. */
+export declare function useShortcuts(active?: boolean): ShortcutDef[];
+export {};

package/dist/types/core/theme.d.ts

@@ -0,0 +1,78 @@
+/**
+ * theme.ts — Dark/light theme system for @nice2dev/ui-graphics editors.
+ *
+ * Provides CSS custom properties, theme context, and auto-detection
+ * of system dark mode preference.
+ */
+import React from "react";
+export type ThemeMode = "light" | "dark" | "auto";
+export interface EditorTheme {
+    mode: "light" | "dark";
+    colors: {
+        bg: string;
+        bgAlt: string;
+        surface: string;
+        surfaceHover: string;
+        border: string;
+        text: string;
+        textSecondary: string;
+        textMuted: string;
+        accent: string;
+        accentHover: string;
+        accentText: string;
+        error: string;
+        warning: string;
+        success: string;
+        canvasBg: string;
+        toolbarBg: string;
+        panelBg: string;
+        statusBarBg: string;
+        selectionBg: string;
+        selectionBorder: string;
+    };
+    spacing: {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+    };
+    radius: {
+        sm: number;
+        md: number;
+        lg: number;
+    };
+    fontSize: {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+    };
+}
+export declare const LIGHT_THEME: EditorTheme;
+export declare const DARK_THEME: EditorTheme;
+/** Generate CSS custom properties from a theme. */
+export declare function themeToCssVars(theme: EditorTheme): Record<string, string>;
+/** Apply theme CSS variables to a DOM element. */
+export declare function applyThemeToElement(element: HTMLElement, theme: EditorTheme): void;
+/** Detect if system prefers dark mode. */
+export declare function systemPrefersDark(): boolean;
+/** Resolve "auto" mode to "light" or "dark". */
+export declare function resolveThemeMode(mode: ThemeMode): "light" | "dark";
+/** Get theme for a given mode. */
+export declare function getTheme(mode: ThemeMode): EditorTheme;
+interface ThemeContextValue {
+    theme: EditorTheme;
+    mode: ThemeMode;
+    setMode: (mode: ThemeMode) => void;
+    toggleMode: () => void;
+}
+/** Provider for editor theme. Supports "light", "dark", or "auto". */
+export declare const NiceEditorThemeProvider: React.FC<{
+    initialMode?: ThemeMode;
+    storageKey?: string;
+    children: React.ReactNode;
+}>;
+/** Hook to access editor theme. */
+export declare function useEditorTheme(): ThemeContextValue;
+export {};

package/dist/types/core/useGamepad.d.ts

@@ -0,0 +1,64 @@
+/**
+ * useGamepad — Hook for gamepad/controller support
+ *
+ * Supports Xbox, PlayStation, and generic controllers.
+ * Provides button mapping, axis input, and action binding.
+ */
+export type GamepadButton = 'A' | 'B' | 'X' | 'Y' | 'LB' | 'RB' | 'LT' | 'RT' | 'Back' | 'Start' | 'LS' | 'RS' | 'DpadUp' | 'DpadDown' | 'DpadLeft' | 'DpadRight' | 'Home';
+export type GamepadAxis = 'LeftX' | 'LeftY' | 'RightX' | 'RightY';
+export interface GamepadState {
+    connected: boolean;
+    id: string;
+    buttons: Record<GamepadButton, boolean>;
+    axes: Record<GamepadAxis, number>;
+    leftTrigger: number;
+    rightTrigger: number;
+    vibrate: (duration: number, weakMagnitude?: number, strongMagnitude?: number) => void;
+}
+export interface GamepadAction {
+    button?: GamepadButton;
+    buttons?: GamepadButton[];
+    axis?: GamepadAxis;
+    axisDirection?: 'positive' | 'negative';
+    trigger?: 'LT' | 'RT';
+    onPress?: () => void;
+    onRelease?: () => void;
+    onHold?: () => void;
+    onAxisChange?: (value: number) => void;
+    repeatDelay?: number;
+    repeatRate?: number;
+}
+export interface UseGamepadOptions {
+    /** Gamepad index to use (default: 0) */
+    index?: number;
+    /** Deadzone for analog sticks (default: 0.15) */
+    deadzone?: number;
+    /** Polling rate in ms (default: 16 = ~60fps) */
+    pollRate?: number;
+    /** Action bindings */
+    actions?: Record<string, GamepadAction>;
+    /** Enable/disable (default: true) */
+    enabled?: boolean;
+}
+export declare const PS_BUTTON_ALIASES: Record<string, GamepadButton>;
+export declare function useGamepad(options?: UseGamepadOptions): GamepadState;
+export interface NavigationActions {
+    onNavigateUp?: () => void;
+    onNavigateDown?: () => void;
+    onNavigateLeft?: () => void;
+    onNavigateRight?: () => void;
+    onConfirm?: () => void;
+    onCancel?: () => void;
+    onTabNext?: () => void;
+    onTabPrev?: () => void;
+    onMenu?: () => void;
+}
+/** Create standard UI navigation action map */
+export declare function createNavigationActions(handlers: NavigationActions): Record<string, GamepadAction>;
+export interface GamepadIndicatorProps {
+    connected: boolean;
+    id?: string;
+    showId?: boolean;
+}
+/** Simple indicator showing gamepad connection status */
+export declare const GamepadIndicator: ({ connected, id, showId }: GamepadIndicatorProps) => import("react/jsx-runtime").JSX.Element | null;