@d34dman/flowdrop 0.0.42 → 0.0.44

package/dist/types/settings.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Settings Types for FlowDrop
+ *
+ * Provides comprehensive type definitions for all user-configurable settings.
+ * Supports theme, editor, UI, behavior, and API settings with hybrid persistence.
+ *
+ * @module types/settings
+ */
+/**
+ * Theme preference options
+ * - 'light': Force light theme
+ * - 'dark': Force dark theme
+ * - 'auto': Follow system preference
+ */
+export type ThemePreference = "light" | "dark" | "auto";
+/**
+ * Resolved theme (actual applied theme, never 'auto')
+ */
+export type ResolvedTheme = "light" | "dark";
+/**
+ * Theme-related settings
+ */
+export interface ThemeSettings {
+    /** User's theme preference */
+    preference: ThemePreference;
+}
+/**
+ * Editor canvas and interaction settings
+ */
+export interface EditorSettings {
+    /** Show grid lines on the canvas */
+    showGrid: boolean;
+    /** Snap nodes to grid when dragging */
+    snapToGrid: boolean;
+    /** Grid cell size in pixels */
+    gridSize: number;
+    /** Show minimap for navigation */
+    showMinimap: boolean;
+    /** Default zoom level (1 = 100%) */
+    defaultZoom: number;
+    /** Automatically fit workflow to view on load */
+    fitViewOnLoad: boolean;
+}
+/**
+ * UI layout and display settings
+ */
+export interface UISettings {
+    /** Width of the node sidebar in pixels */
+    sidebarWidth: number;
+    /** Whether the sidebar is collapsed */
+    sidebarCollapsed: boolean;
+    /** Enable compact mode for denser UI */
+    compactMode: boolean;
+}
+/**
+ * Application behavior and automation settings
+ */
+export interface BehaviorSettings {
+    /** Automatically save changes */
+    autoSave: boolean;
+    /** Auto-save interval in milliseconds */
+    autoSaveInterval: number;
+    /** Maximum number of undo history entries */
+    undoHistoryLimit: number;
+    /** Show confirmation dialog before deleting nodes */
+    confirmDelete: boolean;
+}
+/**
+ * API connection and request settings
+ */
+export interface ApiSettings {
+    /** Request timeout in milliseconds */
+    timeout: number;
+    /** Enable automatic retry on failure */
+    retryEnabled: boolean;
+    /** Maximum number of retry attempts */
+    retryAttempts: number;
+    /** Enable response caching */
+    cacheEnabled: boolean;
+}
+/**
+ * All FlowDrop settings organized by category
+ */
+export interface FlowDropSettings {
+    /** Theme appearance settings */
+    theme: ThemeSettings;
+    /** Editor canvas settings */
+    editor: EditorSettings;
+    /** UI layout settings */
+    ui: UISettings;
+    /** Application behavior settings */
+    behavior: BehaviorSettings;
+    /** API connection settings */
+    api: ApiSettings;
+}
+/**
+ * Settings category names for iteration and tab rendering
+ */
+export type SettingsCategory = keyof FlowDropSettings;
+/**
+ * All available settings categories
+ */
+export declare const SETTINGS_CATEGORIES: SettingsCategory[];
+/**
+ * Human-readable labels for settings categories
+ */
+export declare const SETTINGS_CATEGORY_LABELS: Record<SettingsCategory, string>;
+/**
+ * Icons for settings categories (Iconify icon names)
+ */
+export declare const SETTINGS_CATEGORY_ICONS: Record<SettingsCategory, string>;
+/**
+ * Default theme settings
+ */
+export declare const DEFAULT_THEME_SETTINGS: ThemeSettings;
+/**
+ * Default editor settings
+ */
+export declare const DEFAULT_EDITOR_SETTINGS: EditorSettings;
+/**
+ * Default UI settings
+ */
+export declare const DEFAULT_UI_SETTINGS: UISettings;
+/**
+ * Default behavior settings
+ */
+export declare const DEFAULT_BEHAVIOR_SETTINGS: BehaviorSettings;
+/**
+ * Default API settings
+ */
+export declare const DEFAULT_API_SETTINGS: ApiSettings;
+/**
+ * Complete default settings object
+ */
+export declare const DEFAULT_SETTINGS: FlowDropSettings;
+/**
+ * Deep partial type for nested settings updates
+ */
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Partial settings for incremental updates
+ */
+export type PartialSettings = DeepPartial<FlowDropSettings>;
+/**
+ * Event payload for settings changes
+ */
+export interface SettingsChangeEvent {
+    /** The category that changed */
+    category: SettingsCategory;
+    /** The key within the category that changed */
+    key: string;
+    /** The previous value */
+    previousValue: unknown;
+    /** The new value */
+    newValue: unknown;
+}
+/**
+ * Callback type for settings change listeners
+ */
+export type SettingsChangeCallback = (event: SettingsChangeEvent) => void;
+/**
+ * localStorage key for persisting settings
+ */
+export declare const SETTINGS_STORAGE_KEY = "flowdrop-settings";
+/**
+ * API sync status
+ */
+export type SyncStatus = "idle" | "syncing" | "synced" | "error";
+/**
+ * Settings store state including sync metadata
+ */
+export interface SettingsStoreState {
+    /** Current settings values */
+    settings: FlowDropSettings;
+    /** Whether settings have been loaded from storage */
+    initialized: boolean;
+    /** API sync status */
+    syncStatus: SyncStatus;
+    /** Last sync timestamp */
+    lastSyncedAt: number | null;
+    /** Last sync error message */
+    syncError: string | null;
+}

package/dist/types/settings.js

@@ -0,0 +1,101 @@
+/**
+ * Settings Types for FlowDrop
+ *
+ * Provides comprehensive type definitions for all user-configurable settings.
+ * Supports theme, editor, UI, behavior, and API settings with hybrid persistence.
+ *
+ * @module types/settings
+ */
+/**
+ * All available settings categories
+ */
+export const SETTINGS_CATEGORIES = [
+    "theme",
+    "editor",
+    "ui",
+    "behavior",
+    "api"
+];
+/**
+ * Human-readable labels for settings categories
+ */
+export const SETTINGS_CATEGORY_LABELS = {
+    theme: "Theme",
+    editor: "Editor",
+    ui: "UI",
+    behavior: "Behavior",
+    api: "API"
+};
+/**
+ * Icons for settings categories (Iconify icon names)
+ */
+export const SETTINGS_CATEGORY_ICONS = {
+    theme: "mdi:palette",
+    editor: "mdi:grid",
+    ui: "mdi:view-dashboard",
+    behavior: "mdi:cog-play",
+    api: "mdi:api"
+};
+// =========================================================================
+// Default Settings
+// =========================================================================
+/**
+ * Default theme settings
+ */
+export const DEFAULT_THEME_SETTINGS = {
+    preference: "auto"
+};
+/**
+ * Default editor settings
+ */
+export const DEFAULT_EDITOR_SETTINGS = {
+    showGrid: true,
+    snapToGrid: true,
+    gridSize: 20,
+    showMinimap: true,
+    defaultZoom: 1,
+    fitViewOnLoad: true
+};
+/**
+ * Default UI settings
+ */
+export const DEFAULT_UI_SETTINGS = {
+    sidebarWidth: 280,
+    sidebarCollapsed: false,
+    compactMode: false
+};
+/**
+ * Default behavior settings
+ */
+export const DEFAULT_BEHAVIOR_SETTINGS = {
+    autoSave: false,
+    autoSaveInterval: 30000,
+    undoHistoryLimit: 50,
+    confirmDelete: true
+};
+/**
+ * Default API settings
+ */
+export const DEFAULT_API_SETTINGS = {
+    timeout: 30000,
+    retryEnabled: true,
+    retryAttempts: 3,
+    cacheEnabled: true
+};
+/**
+ * Complete default settings object
+ */
+export const DEFAULT_SETTINGS = {
+    theme: DEFAULT_THEME_SETTINGS,
+    editor: DEFAULT_EDITOR_SETTINGS,
+    ui: DEFAULT_UI_SETTINGS,
+    behavior: DEFAULT_BEHAVIOR_SETTINGS,
+    api: DEFAULT_API_SETTINGS
+};
+// =========================================================================
+// Settings Persistence Types
+// =========================================================================
+/**
+ * localStorage key for persisting settings
+ */
+export const SETTINGS_STORAGE_KEY = "flowdrop-settings";

package/dist/utils/colors.d.ts

@@ -5,11 +5,12 @@
  */
 import type { NodeCategory, PortDataTypeConfig } from '../types/index.js';
 /**
- * Category color mapping to reference tokens (CSS variables)
+ * Category color mapping to design tokens (CSS variables)
+ * Uses --fd-node-* tokens from tokens.css
  */
 export declare const CATEGORY_COLOR_TOKENS: Record<NodeCategory, string>;
 /**
- * Get the reference color token for a category
+ * Get the design token for a category color
  */
 export declare function getCategoryColorToken(category: NodeCategory): string;
 /**
@@ -158,6 +159,59 @@ export declare function hexToRgb(hex: string): {
     g: number;
     b: number;
 } | null;
+/**
+ * Calculate the relative luminance of a color
+ * Based on WCAG 2.1 guidelines for contrast calculations
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @returns Relative luminance value (0-1)
+ */
+export declare function getRelativeLuminance(r: number, g: number, b: number): number;
+/**
+ * Determine if a background color is considered "light" (needs dark text)
+ * @param hex - Hex color string
+ * @returns True if the color is light and needs dark text for contrast
+ */
+export declare function isLightColor(hex: string): boolean;
+/**
+ * Get the appropriate contrast text color (black or white) for a background
+ * @param backgroundColor - Hex color string of the background
+ * @returns CSS color value for text that provides good contrast
+ */
+export declare function getContrastTextColor(backgroundColor: string): string;
+/**
+ * Resolve a CSS variable token to its hex value
+ * @param token - CSS variable token (e.g., "var(--fd-node-amber)")
+ * @returns Hex color value or the original value if not a known token
+ */
+export declare function resolveColorToken(token: string): string;
+/**
+ * Get the appropriate contrast text color for a data type badge
+ * @param dataType - The data type (e.g., "array", "string", "number")
+ * @returns CSS color value for text that provides good contrast on the data type's background
+ */
+export declare function getContrastTextColorForDataType(dataType: string): string;
+/**
+ * Get the appropriate contrast text color for a category badge
+ * @param category - The node category
+ * @returns CSS color value for text that provides good contrast on the category's background
+ */
+export declare function getContrastTextColorForCategory(category: NodeCategory): string;
+/**
+ * Get a semi-transparent tinted background color for ports
+ * Creates a cohesive look with the icon wrapper styling
+ * @param dataType - The data type
+ * @param opacity - Opacity percentage (default 25%)
+ * @returns CSS color-mix expression for the tinted background
+ */
+export declare function getPortBackgroundColor(dataType: string, opacity?: number): string;
+/**
+ * Get the border color for ports (solid data type color)
+ * @param dataType - The data type
+ * @returns CSS color value for the port border
+ */
+export declare function getPortBorderColor(dataType: string): string;
 /**
  * Convert RGB components to hex color string
  * @param r - Red component (0-255)
@@ -168,25 +222,64 @@ export declare function hexToRgb(hex: string): {
 export declare function rgbToHex(r: number, g: number, b: number): string;
 /**
  * Generate a light tint of a color (similar to Tailwind's -50 shade)
- * Creates a very light background-friendly version of the color
+ * Creates a very light background-friendly version of the color for light mode
  * @param hex - Base hex color string
  * @returns Light tint hex color string
  */
 export declare function getLightTint(hex: string): string;
+/**
+ * Generate a dark tint of a color for dark mode backgrounds
+ * Creates a subtle, muted version of the color that works well on dark backgrounds
+ * @param hex - Base hex color string
+ * @param opacity - Optional opacity for the color overlay (default 0.15)
+ * @returns Dark tint hex color string
+ */
+export declare function getDarkTint(hex: string, opacity?: number): string;
 /**
  * Generate a border tint of a color (similar to Tailwind's -300 shade)
- * Creates a medium-light version suitable for borders
+ * Creates a medium-light version suitable for borders in light mode
  * @param hex - Base hex color string
  * @returns Border tint hex color string
  */
 export declare function getBorderTint(hex: string): string;
+/**
+ * Generate a dark border tint of a color for dark mode
+ * Creates a medium-dark version suitable for borders in dark mode
+ * @param hex - Base hex color string
+ * @returns Dark border tint hex color string
+ */
+export declare function getDarkBorderTint(hex: string): string;
+/**
+ * Color variants interface for theming components
+ */
+export interface ColorVariants {
+    /** Base color value */
+    base: string;
+    /** Light tint for light mode backgrounds */
+    light: string;
+    /** Border tint for light mode borders */
+    border: string;
+    /** Dark tint for dark mode backgrounds */
+    darkLight: string;
+    /** Dark border tint for dark mode borders */
+    darkBorder: string;
+}
 /**
  * Generate color variants for theming a component
+ * Returns variants for both light and dark modes
  * @param baseColor - Base hex color string
- * @returns Object with base, light, and border color variants
+ * @returns Object with base, light, border, darkLight, and darkBorder color variants
  */
-export declare function getColorVariants(baseColor: string): {
+export declare function getColorVariants(baseColor: string): ColorVariants;
+/**
+ * Get theme-aware color variants
+ * Returns the appropriate light or dark variants based on the theme
+ * @param baseColor - Base hex color string
+ * @param isDarkMode - Whether dark mode is active
+ * @returns Object with base, background, and border colors appropriate for the theme
+ */
+export declare function getThemeAwareColorVariants(baseColor: string, isDarkMode: boolean): {
     base: string;
-    light: string;
+    background: string;
     border: string;
 };