entangle-ui 0.2.0 → 0.4.0

package/dist/esm/utils/mathExpression.js

@@ -0,0 +1,275 @@
+// src/utils/mathExpression.ts
+/**
+ * Blocked identifiers that must be rejected before evaluation.
+ * Defense-in-depth layer to prevent prototype pollution or code execution
+ * via dangerous JavaScript identifiers that pass character validation.
+ */
+const BLOCKED_IDENTIFIERS = new Set([
+    'constructor',
+    'prototype',
+    '__proto__',
+    'this',
+    'self',
+    'window',
+    'document',
+    'globalThis',
+    'process',
+    'require',
+    'import',
+    'module',
+    'exports',
+    'eval',
+    'Function',
+    'Object',
+    'Array',
+    'Reflect',
+    'Proxy',
+    'Symbol',
+]);
+/**
+ * Mathematical constants available in expressions
+ */
+const MATH_CONSTANTS = {
+    pi: Math.PI,
+    e: Math.E,
+    tau: 2 * Math.PI,
+    phi: (1 + Math.sqrt(5)) / 2, // Golden ratio
+};
+/**
+ * Mathematical functions available in expressions
+ */
+const MATH_FUNCTIONS = {
+    // Trigonometric functions
+    sin: Math.sin,
+    cos: Math.cos,
+    tan: Math.tan,
+    asin: Math.asin,
+    acos: Math.acos,
+    atan: Math.atan,
+    // Logarithmic and exponential
+    log: Math.log,
+    log10: Math.log10,
+    log2: Math.log2,
+    exp: Math.exp,
+    // Power and root functions
+    sqrt: Math.sqrt,
+    cbrt: Math.cbrt,
+    // Rounding functions
+    floor: Math.floor,
+    ceil: Math.ceil,
+    round: Math.round,
+    // Other useful functions
+    abs: Math.abs,
+    sign: Math.sign,
+};
+/**
+ * Sanitizes mathematical expression by removing dangerous patterns
+ * and normalizing the input for safe evaluation.
+ */
+function sanitizeExpression(expression) {
+    // Remove whitespace
+    let sanitized = expression.replace(/\s+/g, '');
+    // Convert common alternative notations
+    sanitized = sanitized.replace(/×/g, '*'); // Multiplication symbol
+    sanitized = sanitized.replace(/÷/g, '/'); // Division symbol
+    sanitized = sanitized.replace(/\^/g, '**'); // Power operator
+    // Ensure proper decimal notation
+    sanitized = sanitized.replace(/,/g, '.'); // European decimal notation
+    return sanitized;
+}
+/**
+ * Validates that expression contains only allowed characters and patterns
+ */
+function isValidExpression(expression) {
+    // Allow numbers, operators, parentheses, dots, and known constants/functions
+    const allowedPattern = /^[0-9+\-*/().a-zA-Z_]+$/;
+    if (!allowedPattern.test(expression)) {
+        return false;
+    }
+    // Check for balanced parentheses
+    let depth = 0;
+    for (const char of expression) {
+        if (char === '(')
+            depth++;
+        if (char === ')')
+            depth--;
+        if (depth < 0)
+            return false;
+    }
+    return depth === 0;
+}
+/**
+ * Checks whether the expression contains any blocked identifiers or
+ * unknown alphabetic tokens. All word tokens must be either a known
+ * constant, a known function name, or part of "Math" (introduced by
+ * replaceConstantsAndFunctions). Any unrecognized identifier is rejected.
+ */
+function containsBlockedIdentifiers(expression) {
+    const wordTokens = expression.match(/[a-zA-Z_][a-zA-Z0-9_]*/g);
+    if (!wordTokens)
+        return false;
+    const allowedTokens = new Set([
+        ...Object.keys(MATH_CONSTANTS),
+        ...Object.keys(MATH_FUNCTIONS),
+    ]);
+    for (const token of wordTokens) {
+        if (BLOCKED_IDENTIFIERS.has(token))
+            return true;
+        if (!allowedTokens.has(token))
+            return true;
+    }
+    return false;
+}
+/**
+ * Replaces mathematical constants and functions in the expression
+ * with their JavaScript equivalents for safe evaluation.
+ */
+function replaceConstantsAndFunctions(expression) {
+    let result = expression;
+    // Replace constants
+    Object.entries(MATH_CONSTANTS).forEach(([name, value]) => {
+        const regex = new RegExp(`\\b${name}\\b`, 'g');
+        result = result.replace(regex, value.toString());
+    });
+    // Replace functions
+    Object.entries(MATH_FUNCTIONS).forEach(([name]) => {
+        const regex = new RegExp(`\\b${name}\\(`, 'g');
+        result = result.replace(regex, `Math.${name}(`);
+    });
+    return result;
+}
+/**
+ * Safely evaluates a mathematical expression using Function constructor
+ * instead of eval() for better security.
+ */
+function safeEvaluate(expression) {
+    // Create a function that returns the expression result
+    // This is safer than eval() as it doesn't have access to the scope
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval
+    const func = new Function('Math', `"use strict"; return (${expression});`);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    return func(Math);
+}
+/**
+ * Evaluates a mathematical expression and returns the result.
+ *
+ * Supports:
+ * - Basic arithmetic: +, -, *, /, **, ()
+ * - Mathematical constants: pi, e, tau, phi
+ * - Mathematical functions: sin, cos, tan, sqrt, log, etc.
+ * - Alternative notations: × (multiplication), ÷ (division), ^ (power)
+ * - European decimal notation: , instead of .
+ *
+ * @param expression The mathematical expression to evaluate
+ * @returns Evaluation result with success status and value or error
+ *
+ * @example
+ * ```typescript
+ * evaluateExpression("3 + 4 * 2") // { success: true, value: 11 }
+ * evaluateExpression("sqrt(16)") // { success: true, value: 4 }
+ * evaluateExpression("pi * 2") // { success: true, value: 6.283... }
+ * evaluateExpression("2 ^ 3") // { success: true, value: 8 }
+ * evaluateExpression("invalid") // { success: false, error: "..." }
+ * ```
+ */
+function evaluateExpression(expression) {
+    const originalExpression = expression;
+    try {
+        // Handle empty or whitespace-only expressions
+        if (!expression?.trim()) {
+            return {
+                success: false,
+                error: 'Expression cannot be empty',
+                expression: originalExpression,
+            };
+        }
+        // Sanitize the expression
+        const sanitized = sanitizeExpression(expression);
+        // Validate the expression
+        if (!isValidExpression(sanitized)) {
+            return {
+                success: false,
+                error: 'Expression contains invalid characters or syntax',
+                expression: originalExpression,
+            };
+        }
+        // Check for blocked or unknown identifiers (defense-in-depth)
+        if (containsBlockedIdentifiers(sanitized)) {
+            return {
+                success: false,
+                error: 'Expression contains invalid characters or syntax',
+                expression: originalExpression,
+            };
+        }
+        // Replace constants and functions
+        const processed = replaceConstantsAndFunctions(sanitized);
+        // Evaluate the expression
+        const result = safeEvaluate(processed);
+        // Check if result is a valid number
+        if (typeof result !== 'number' || !isFinite(result)) {
+            return {
+                success: false,
+                error: 'Expression does not evaluate to a valid number',
+                expression: originalExpression,
+            };
+        }
+        return {
+            success: true,
+            value: result,
+            expression: originalExpression,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown evaluation error',
+            expression: originalExpression,
+        };
+    }
+}
+/**
+ * Checks if a string looks like a mathematical expression
+ * (contains operators, functions, or constants)
+ */
+function isExpression(input) {
+    const trimmed = input.trim();
+    // Check for mathematical operators
+    if (/[+\-*/^×÷()]/.test(trimmed)) {
+        return true;
+    }
+    // Check for mathematical functions
+    const functionNames = Object.keys(MATH_FUNCTIONS);
+    const functionRegex = new RegExp(`\\b(${functionNames.join('|')})\\(`, 'i');
+    if (functionRegex.test(trimmed)) {
+        return true;
+    }
+    // Check for mathematical constants
+    const constantNames = Object.keys(MATH_CONSTANTS);
+    const constantRegex = new RegExp(`\\b(${constantNames.join('|')})\\b`, 'i');
+    if (constantRegex.test(trimmed)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Attempts to parse a string as either a direct number or mathematical expression
+ */
+function parseNumericInput(input) {
+    const trimmed = input.trim();
+    // Try direct number parsing first (more efficient)
+    const directNumber = parseFloat(trimmed);
+    if (!isNaN(directNumber) &&
+        isFinite(directNumber) &&
+        trimmed === directNumber.toString()) {
+        return {
+            success: true,
+            value: directNumber,
+            expression: input,
+        };
+    }
+    // Fall back to expression evaluation
+    return evaluateExpression(input);
+}
+
+export { evaluateExpression, isExpression, parseNumericInput };
+//# sourceMappingURL=mathExpression.js.map

package/dist/esm/utils/mathExpression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mathExpression.js","sources":["../../../../src/utils/mathExpression.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/utils/mathUtils.js

@@ -0,0 +1,18 @@
+/**
+ * Clamps a value between min and max bounds
+ */
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/**
+ * Rounds a number to specified decimal places
+ */
+function roundToPrecision(value, precision) {
+    if (precision === undefined)
+        return value;
+    const factor = Math.pow(10, precision);
+    return Math.round(value * factor) / factor;
+}
+
+export { clamp, roundToPrecision };
+//# sourceMappingURL=mathUtils.js.map

package/dist/esm/utils/mathUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mathUtils.js","sources":["../../../../src/utils/mathUtils.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;AAEG;SACa,KAAK,CAAC,KAAa,EAAE,GAAW,EAAE,GAAW,EAAA;AAC3D,IAAA,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC;AAC5C;AAEA;;AAEG;AACG,SAAU,gBAAgB,CAAC,KAAa,EAAE,SAAkB,EAAA;IAChE,IAAI,SAAS,KAAK,SAAS;AAAE,QAAA,OAAO,KAAK;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,CAAC;IACtC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,MAAM;AAC5C;;;;"}

package/dist/types/components/controls/CartesianPicker/CartesianPicker.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import { CartesianPickerProps } from './CartesianPicker.types.js';
+
+declare const CartesianPicker: React.FC<CartesianPickerProps>;
+
+export { CartesianPicker };

package/dist/types/components/controls/CartesianPicker/CartesianPicker.types.d.ts

@@ -0,0 +1,163 @@
+import React from 'react';
+import { Prettify } from '../../../types/utilities.js';
+import { BaseComponent, Size } from '../../../types/common.js';
+import { Point2D, CanvasBackgroundInfo } from '../../primitives/canvas/canvas.types.js';
+
+type CartesianPickerSize = Size;
+interface CartesianPickerBaseProps extends Omit<BaseComponent, 'onChange' | 'value' | 'defaultValue'> {
+    /**
+     * Current point value (controlled)
+     */
+    value?: Point2D;
+    /**
+     * Default point value (uncontrolled)
+     * @default { x: 0, y: 0 }
+     */
+    defaultValue?: Point2D;
+    /**
+     * Domain range for X axis
+     * @default [-1, 1]
+     */
+    domainX?: [number, number];
+    /**
+     * Domain range for Y axis
+     * @default [-1, 1]
+     */
+    domainY?: [number, number];
+    /**
+     * Whether to show grid lines
+     * @default true
+     */
+    showGrid?: boolean;
+    /**
+     * Grid subdivision count (lines between domain bounds)
+     * @default 4
+     */
+    gridSubdivisions?: number;
+    /**
+     * Whether to show X/Y axis value labels on the grid
+     * @default true
+     */
+    showAxisLabels?: boolean;
+    /**
+     * Whether to draw origin axes (X=0, Y=0) with emphasis.
+     * Useful when domain is symmetric around origin.
+     * @default true
+     */
+    showOriginAxes?: boolean;
+    /**
+     * Whether to draw crosshair lines from point to edges
+     * @default true
+     */
+    showCrosshair?: boolean;
+    /**
+     * Crosshair line style
+     * @default "dashed"
+     */
+    crosshairStyle?: 'solid' | 'dashed';
+    /**
+     * X axis name label (e.g. "Pan", "U", "X")
+     */
+    labelX?: string;
+    /**
+     * Y axis name label (e.g. "Tilt", "V", "Y")
+     */
+    labelY?: string;
+    /**
+     * Point marker radius in pixels
+     * @default 6
+     */
+    markerRadius?: number;
+    /**
+     * Snap to grid subdivisions while dragging (Ctrl toggles)
+     * @default false
+     */
+    snapToGrid?: boolean;
+    /**
+     * Discrete step for value snapping. Can be a single value for both axes
+     * or [stepX, stepY] for per-axis steps.
+     * Applied instead of grid snap when provided.
+     */
+    step?: number | [number, number];
+    /**
+     * Whether to clamp the point within domain bounds
+     * @default true
+     */
+    clampToRange?: boolean;
+    /**
+     * Number format precision for displayed values
+     * @default 2
+     */
+    precision?: number;
+    /**
+     * Width of the picker in pixels
+     * @default 200
+     */
+    width?: number;
+    /**
+     * Height of the picker in pixels.
+     * For square pickers (most common), set equal to width.
+     * @default 200
+     */
+    height?: number;
+    /**
+     * Whether the picker fills its parent container.
+     * Overrides width/height — uses ResizeObserver.
+     * @default false
+     */
+    responsive?: boolean;
+    /**
+     * Component size — affects label/value display sizing
+     * @default "md"
+     */
+    size?: CartesianPickerSize;
+    /**
+     * Whether the picker is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Whether the picker is read-only (can view but not edit)
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Callback when point changes.
+     * Fires continuously during drag.
+     */
+    onChange?: (point: Point2D) => void;
+    /**
+     * Callback when editing is committed (pointer up, click).
+     * Use for undo system integration.
+     */
+    onChangeComplete?: (point: Point2D) => void;
+    /**
+     * Custom background renderer — called after clearing the canvas
+     * but before drawing the grid.
+     *
+     * Use for heatmaps, gradients, or images behind the picker.
+     */
+    renderBackground?: (ctx: CanvasRenderingContext2D, info: CanvasBackgroundInfo) => void;
+    /**
+     * Render prop for custom content below the canvas.
+     * Receives the current point value for display.
+     */
+    renderBottomBar?: (info: CartesianPickerInfo) => React.ReactNode;
+}
+type CartesianPickerProps = Prettify<CartesianPickerBaseProps>;
+interface CartesianPickerInfo {
+    /** Current point value */
+    point: Point2D;
+    /** Whether the picker is disabled */
+    disabled: boolean;
+    /** Whether the picker is read-only */
+    readOnly: boolean;
+    /** Whether the user is currently dragging */
+    isDragging: boolean;
+    /** Domain X range */
+    domainX: [number, number];
+    /** Domain Y range */
+    domainY: [number, number];
+}
+
+export type { CartesianPickerBaseProps, CartesianPickerInfo, CartesianPickerProps, CartesianPickerSize };

package/dist/types/components/controls/ColorPicker/ColorPalette.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import { PaletteColor } from './palettes/material.js';
+
+interface ColorPaletteProps {
+    palette: PaletteColor[];
+    currentColor: string;
+    onSelect: (color: string) => void;
+    /** Title displayed in the collapsible header @default "Palette" */
+    title?: string;
+    /** Whether the palette starts expanded @default false */
+    defaultExpanded?: boolean;
+}
+declare const ColorPalette: React.FC<ColorPaletteProps>;
+
+export { ColorPalette };
+export type { ColorPaletteProps };

package/dist/types/components/controls/ColorPicker/ColorPicker.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import { ColorPickerProps } from './ColorPicker.types.js';
+
+declare const ColorPicker: React.FC<ColorPickerProps>;
+
+export { ColorPicker };

package/dist/types/components/controls/ColorPicker/ColorPicker.types.d.ts

@@ -0,0 +1,120 @@
+import { Prettify } from '../../../types/utilities.js';
+import { BaseComponent, Size } from '../../../types/common.js';
+import { ColorFormat as ColorFormat$1 } from './colorUtils.js';
+import { Palette, PaletteColor } from './palettes/material.js';
+export { PaletteShade } from './palettes/material.js';
+
+type ColorFormat = ColorFormat$1;
+type ColorPickerSize = Size;
+type ColorInputMode = 'hex' | 'rgb' | 'hsl';
+interface ColorPreset {
+    color: string;
+    label?: string;
+}
+
+interface ColorPickerBaseProps extends Omit<BaseComponent, 'onChange' | 'value' | 'defaultValue'> {
+    /**
+     * Current color value (controlled).
+     * Accepts any valid CSS color string.
+     */
+    value?: string;
+    /**
+     * Default color value (uncontrolled)
+     * @default "#007acc"
+     */
+    defaultValue?: string;
+    /**
+     * Output format for onChange
+     * @default "hex"
+     */
+    format?: ColorFormat;
+    /**
+     * Whether to show the alpha channel control
+     * @default false
+     */
+    showAlpha?: boolean;
+    /**
+     * Available input modes
+     * @default ['hex', 'rgb', 'hsl']
+     */
+    inputModes?: ColorInputMode[];
+    /**
+     * Default input mode
+     * @default "hex"
+     */
+    defaultInputMode?: ColorInputMode;
+    /**
+     * Preset color palette
+     */
+    presets?: ColorPreset[];
+    /**
+     * Swatch trigger size
+     * @default "md"
+     */
+    size?: ColorPickerSize;
+    /**
+     * Shape of the swatch trigger
+     * @default "square"
+     */
+    swatchShape?: 'square' | 'circle';
+    /**
+     * Label displayed next to the swatch
+     */
+    label?: string;
+    /**
+     * Whether the picker is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Whether the component is inline (no popover)
+     * @default false
+     */
+    inline?: boolean;
+    /**
+     * Width of the picker panel in pixels
+     * @default 240
+     */
+    pickerWidth?: number;
+    /**
+     * Callback when color changes (continuous)
+     */
+    onChange?: (color: string) => void;
+    /**
+     * Callback when color change is committed (drag end)
+     */
+    onChangeComplete?: (color: string) => void;
+    /**
+     * Whether to show the EyeDropper button (Chromium-only).
+     * Hidden automatically if browser doesn't support the EyeDropper API.
+     * @default false
+     */
+    showEyeDropper?: boolean;
+    /**
+     * Built-in color palette or custom palette data.
+     * - `'material'` — Material Design colors (19 hues × 10 shades)
+     * - `'tailwind'` — Tailwind CSS colors (22 hues × 11 shades)
+     * - `'pastel'` — Soft pastel colors
+     * - `'earth'` — Natural earth tones
+     * - `'neon'` — High-saturation neon colors
+     * - `'monochrome'` — Neutral, warm, and cool grays
+     * - `'skin-tones'` — Portrait/illustration skin palette
+     * - `'vintage'` — Desaturated retro film colors
+     * - `Palette` — custom palette with name
+     * - `PaletteColor[]` — custom palette data (legacy)
+     */
+    palette?: 'material' | 'tailwind' | 'pastel' | 'earth' | 'neon' | 'monochrome' | 'skin-tones' | 'vintage' | Palette | PaletteColor[];
+}
+type ColorPickerProps = Prettify<ColorPickerBaseProps>;
+interface ColorSwatchProps extends BaseComponent<HTMLButtonElement> {
+    color: string;
+    size?: ColorPickerSize;
+    shape?: 'square' | 'circle';
+    disabled?: boolean;
+    onClick?: () => void;
+    'aria-label'?: string;
+}
+type ColorSwatchPublicProps = Prettify<ColorSwatchProps>;
+
+export { Palette, PaletteColor };
+export type { ColorFormat, ColorInputMode, ColorPickerBaseProps, ColorPickerProps, ColorPickerSize, ColorPreset, ColorSwatchProps, ColorSwatchPublicProps };

package/dist/types/components/controls/ColorPicker/ColorSwatch.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import { ColorSwatchProps } from './ColorPicker.types.js';
+
+declare const ColorSwatch: React.NamedExoticComponent<ColorSwatchProps>;
+
+export { ColorSwatch };

package/dist/types/components/controls/ColorPicker/EyeDropper.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+import { Prettify } from '../../../types/utilities.js';
+import { BaseComponent, Size } from '../../../types/common.js';
+
+interface EyeDropperBaseProps extends Omit<BaseComponent<HTMLButtonElement>, 'onChange'> {
+    /** Callback when a color is picked */
+    onColorPick?: (color: string) => void;
+    /** Button size @default "md" */
+    size?: Size;
+    /** Whether disabled @default false */
+    disabled?: boolean;
+}
+type EyeDropperProps = Prettify<EyeDropperBaseProps>;
+/**
+ * EyeDropper button that opens the native browser EyeDropper API
+ * to sample a color from anywhere on the screen.
+ *
+ * Renders nothing if the EyeDropper API is not available in the browser.
+ *
+ * @example
+ * ```tsx
+ * <EyeDropper onColorPick={(hex) => setColor(hex)} />
+ * ```
+ */
+declare const EyeDropper: React.FC<EyeDropperProps>;
+
+export { EyeDropper };
+export type { EyeDropperProps };

package/dist/types/components/controls/ColorPicker/colorUtils.d.ts

@@ -0,0 +1,3 @@
+type ColorFormat = 'hex' | 'hex8' | 'rgb' | 'rgba' | 'hsl' | 'hsla';
+
+export type { ColorFormat };