entangle-ui 0.1.0 → 0.3.0

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

@@ -0,0 +1,297 @@
+import React from 'react';
+import { Prettify } from '../../../types/utilities.js';
+import { BaseComponent, Size } from '../../../types/common.js';
+
+type CurveEditorSize = Size;
+/**
+ * Tangent handle mode — controls how handles behave around a keyframe.
+ * - `free`: Each handle moves independently
+ * - `aligned`: Handles stay co-linear but can differ in length
+ * - `mirrored`: Handles are symmetric (same angle and length)
+ * - `auto`: Smooth catmull-rom style — handles auto-computed from neighbors
+ * - `linear`: No handles — straight line segments
+ * - `step`: Constant value until next keyframe (hold / step function)
+ */
+type TangentMode = 'free' | 'aligned' | 'mirrored' | 'auto' | 'linear' | 'step';
+/**
+ * Single control point (keyframe) on the curve.
+ */
+interface CurveKeyframe {
+    /** X position in domain space (e.g., 0-1 for normalized, 0-100 for frames) */
+    x: number;
+    /** Y value at this position */
+    y: number;
+    /** Left tangent handle offset (relative to keyframe position) */
+    handleIn: {
+        x: number;
+        y: number;
+    };
+    /** Right tangent handle offset (relative to keyframe position) */
+    handleOut: {
+        x: number;
+        y: number;
+    };
+    /** Tangent mode for this keyframe */
+    tangentMode: TangentMode;
+    /** Optional unique ID (auto-generated if not provided) */
+    id?: string;
+}
+/**
+ * Complete curve data model.
+ */
+interface CurveData {
+    /** Ordered array of keyframes (sorted by x) */
+    keyframes: CurveKeyframe[];
+    /** Domain bounds — x range */
+    domainX: [number, number];
+    /** Domain bounds — y range */
+    domainY: [number, number];
+    /**
+     * Pre-infinity behavior — what happens before the first keyframe
+     * @default "constant"
+     */
+    preInfinity?: 'constant' | 'linear' | 'cycle' | 'pingpong';
+    /**
+     * Post-infinity behavior — what happens after the last keyframe
+     * @default "constant"
+     */
+    postInfinity?: 'constant' | 'linear' | 'cycle' | 'pingpong';
+}
+interface CurveEditorBaseProps extends Omit<BaseComponent, 'onChange' | 'value' | 'defaultValue'> {
+    /**
+     * Curve data (controlled)
+     */
+    value?: CurveData;
+    /**
+     * Default curve data (uncontrolled)
+     * @default ease-in-out preset
+     */
+    defaultValue?: CurveData;
+    /**
+     * Width of the editor in pixels
+     * @default 320
+     */
+    width?: number;
+    /**
+     * Height of the editor in pixels
+     * @default 200
+     */
+    height?: number;
+    /**
+     * Whether the editor fills its parent container.
+     * Overrides width/height — uses ResizeObserver.
+     * @default false
+     */
+    responsive?: boolean;
+    /**
+     * Whether to show the toolbar (presets, tangent mode, zoom)
+     * @default true
+     */
+    showToolbar?: boolean;
+    /**
+     * Whether to show the grid lines
+     * @default true
+     */
+    showGrid?: boolean;
+    /**
+     * Grid subdivision count (lines between domain bounds)
+     * @default 4
+     */
+    gridSubdivisions?: number;
+    /**
+     * Whether to display X/Y axis value labels on the grid
+     * @default true
+     */
+    showAxisLabels?: boolean;
+    /**
+     * Whether to allow adding new keyframes by double-clicking the curve
+     * @default true
+     */
+    allowAdd?: boolean;
+    /**
+     * Maximum number of keyframes allowed.
+     * When reached, double-click will not add new keyframes.
+     * @default Infinity
+     */
+    maxKeyframes?: number;
+    /**
+     * Whether to allow deleting keyframes (Delete/Backspace key)
+     * @default true
+     */
+    allowDelete?: boolean;
+    /**
+     * Whether the first and last keyframe X positions are locked
+     * (user can change Y but not move them along X axis)
+     * @default true
+     */
+    lockEndpoints?: boolean;
+    /**
+     * Minimum distance between keyframes on the X axis.
+     * Prevents overlapping keyframes.
+     * @default 0.001
+     */
+    minKeyframeDistance?: number;
+    /**
+     * Whether Y values are clamped to domainY bounds.
+     * @default true
+     */
+    clampY?: boolean;
+    /**
+     * Snap to grid while dragging (hold Ctrl to toggle)
+     * @default false
+     */
+    snapToGrid?: boolean;
+    /**
+     * Number format precision for displayed values
+     * @default 3
+     */
+    precision?: number;
+    /**
+     * X axis label (e.g., "Time", "Input", "Distance")
+     */
+    labelX?: string;
+    /**
+     * Y axis label (e.g., "Value", "Output", "Intensity")
+     */
+    labelY?: string;
+    /**
+     * Preset curves available in the toolbar.
+     * Merged with built-in presets.
+     */
+    presets?: CurvePreset[];
+    /**
+     * Component size — affects toolbar and label sizing
+     * @default "md"
+     */
+    size?: CurveEditorSize;
+    /**
+     * Whether the editor is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Whether the editor is read-only (can view but not edit)
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Curve line color
+     * @default theme.colors.accent.primary
+     */
+    curveColor?: string;
+    /**
+     * Curve line width in pixels
+     * @default 2
+     */
+    curveWidth?: number;
+    /**
+     * Callback when curve data changes.
+     * Fires continuously during drag.
+     */
+    onChange?: (curve: CurveData) => void;
+    /**
+     * Callback when editing is committed (drag end, keyframe add/delete).
+     * Use for undo system integration.
+     */
+    onChangeComplete?: (curve: CurveData) => void;
+    /**
+     * Callback when selection changes
+     */
+    onSelectionChange?: (selectedIds: string[]) => void;
+    /**
+     * Callback to evaluate the curve at a given X position.
+     * Useful for displaying a preview value indicator.
+     */
+    onEvaluate?: (x: number, y: number) => void;
+    /**
+     * Custom background renderer — called after clearing the canvas but before
+     * drawing the grid. Use this to draw histograms, gradients, or other
+     * visualisations behind the curve (like Photoshop / Lightroom curves).
+     *
+     * The callback receives the canvas 2D context already scaled for
+     * `devicePixelRatio`, the drawable area in CSS pixels, and the current
+     * viewport so you can map domain values to pixel positions with
+     * `domainToCanvas()`.
+     */
+    renderBackground?: (ctx: CanvasRenderingContext2D, info: CurveBackgroundInfo) => void;
+    /**
+     * Render prop for custom content below the canvas.
+     * Use for channel selectors, coordinate displays, color space
+     * pickers, or any custom status bar content.
+     *
+     * The callback receives curve state so the bottom bar can display
+     * reactive data (selected keyframe coordinates, evaluated values, etc.).
+     */
+    renderBottomBar?: (info: CurveBottomBarInfo) => React.ReactNode;
+    /**
+     * Whether tangent editing is locked.
+     * When true:
+     * - Tangent mode buttons are hidden from the toolbar
+     * - Tangent handle lines/circles are not drawn on canvas
+     * - Handle dragging is disabled
+     * - Double-click on keyframes does not cycle tangent modes
+     * - Keyboard shortcuts 1-6 for tangent modes are ignored
+     *
+     * The curve still renders normally using each keyframe's existing
+     * tangentMode — this prop only locks UI-based changes.
+     * @default false
+     */
+    lockTangents?: boolean;
+}
+type CurveEditorProps = Prettify<CurveEditorBaseProps>;
+interface CurvePreset {
+    /** Display name in the preset selector */
+    label: string;
+    /** Preset identifier */
+    id: string;
+    /** Curve data for this preset */
+    curve: CurveData;
+    /** Optional category for grouping presets */
+    category?: string;
+    /** Optional icon element */
+    icon?: React.ReactNode;
+}
+/**
+ * Information passed to the `renderBottomBar` render prop.
+ */
+interface CurveBottomBarInfo {
+    /** Current curve data */
+    curve: CurveData;
+    /** IDs of currently selected keyframes */
+    selectedIds: string[];
+    /** The actual selected keyframe objects */
+    selectedKeyframes: CurveKeyframe[];
+    /** Evaluate the curve at a given X position */
+    evaluate: (x: number) => number;
+    /** Whether the editor is disabled */
+    disabled: boolean;
+    /** Whether the editor is read-only */
+    readOnly: boolean;
+}
+/**
+ * Information passed to the `renderBackground` callback.
+ */
+interface CurveBackgroundInfo {
+    /** Canvas width in CSS pixels */
+    width: number;
+    /** Canvas height in CSS pixels */
+    height: number;
+    /** Current viewport mapping (use with `domainToCanvas`) */
+    viewport: CurveViewport;
+    /** Domain X range — e.g. [0, 1] or [0, 255] */
+    domainX: [number, number];
+    /** Domain Y range */
+    domainY: [number, number];
+}
+interface CurveViewport {
+    /** Visible domain range */
+    viewX: [number, number];
+    viewY: [number, number];
+    /** Zoom level (1 = fit to bounds) */
+    zoom: number;
+    /** Pan offset in domain units */
+    panX: number;
+    panY: number;
+}
+
+export type { CurveBackgroundInfo, CurveBottomBarInfo, CurveData, CurveEditorBaseProps, CurveEditorProps, CurveEditorSize, CurveKeyframe, CurvePreset, CurveViewport, TangentMode };

package/dist/types/components/controls/CurveEditor/curvePresets.d.ts

@@ -0,0 +1,5 @@
+import { CurvePreset } from './CurveEditor.types.js';
+
+declare const CURVE_PRESETS: CurvePreset[];
+
+export { CURVE_PRESETS };

package/dist/types/components/controls/CurveEditor/curveUtils.d.ts

@@ -0,0 +1,28 @@
+import { CurveData, CurveViewport } from './CurveEditor.types.js';
+
+/**
+ * Evaluate the entire curve at a given X position.
+ * Finds the right segment, solves for t, returns Y.
+ */
+declare function evaluateCurve(curve: CurveData, x: number): number;
+/**
+ * Sample the curve at N evenly-spaced X points.
+ * Returns array of {x, y} for rendering as a polyline.
+ */
+declare function sampleCurve(curve: CurveData, numSamples: number): Array<{
+    x: number;
+    y: number;
+}>;
+/**
+ * Convert domain coordinates to canvas pixel coordinates.
+ */
+declare function domainToCanvas(domainX: number, domainY: number, viewport: CurveViewport, canvasWidth: number, canvasHeight: number): {
+    px: number;
+    py: number;
+};
+/**
+ * Create a default linear curve.
+ */
+declare function createLinearCurve(domainX?: [number, number], domainY?: [number, number]): CurveData;
+
+export { createLinearCurve, domainToCanvas, evaluateCurve, sampleCurve };

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

@@ -0,0 +1,150 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { Prettify } from '../../../types/utilities.js';
+import { BaseComponent, Size } from '../../../types/common.js';
+import { UseNumberInputOptions } from './useNumberInput.js';
+
+/**
+ * Props specific to NumberInput component
+ */
+interface NumberInputBaseProps extends Omit<BaseComponent, 'onChange'>, UseNumberInputOptions {
+    /**
+     * Current numeric value
+     */
+    value: number;
+    /**
+     * Callback when value changes
+     */
+    onChange: (value: number) => void;
+    /**
+     * Unit suffix to display (e.g., "px", "%", "°")
+     * Can be a string or a function that formats the value
+     */
+    unit?: string | ((value: number) => string);
+    /**
+     * Whether to show increment/decrement buttons on hover
+     * @default true
+     */
+    showStepButtons?: boolean;
+    /**
+     * Custom validation function
+     * Return error message string if invalid, undefined if valid
+     */
+    validate?: (value: number) => string | undefined;
+    /**
+     * Format value for display (e.g., add commas, currency symbols)
+     * This is separate from unit display
+     */
+    formatValue?: (value: number) => string;
+    /**
+     * Parse custom formatted input back to number
+     * Used in conjunction with formatValue
+     */
+    parseValue?: (input: string) => number | null;
+    /**
+     * Input size using standard library sizing
+     * - `sm`: 20px height, compact for toolbars
+     * - `md`: 24px height, standard for forms
+     * - `lg`: 32px height, prominent inputs
+     * @default "md"
+     */
+    size?: Size;
+    /**
+     * Whether the input is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Whether the input is read-only
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Error message displayed when error is true
+     */
+    errorMessage?: string | undefined;
+    /**
+     * Placeholder text
+     */
+    placeholder?: string | undefined;
+    /**
+     * Input label
+     */
+    label?: string | undefined;
+    /**
+     * Helper text displayed below the input
+     */
+    helperText?: string | undefined;
+    /**
+     * Whether the input is required
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Focus event handler
+     */
+    onFocus?: (event: React.FocusEvent<HTMLInputElement>) => void;
+    /**
+     * Blur event handler
+     */
+    onBlur?: (event: React.FocusEvent<HTMLInputElement>) => void;
+    /**
+     * Key down event handler
+     */
+    onKeyDown?: (event: React.KeyboardEvent<HTMLInputElement>) => void;
+}
+/**
+ * Props for the NumberInput component with prettified type for better IntelliSense
+ */
+type NumberInputProps = Prettify<NumberInputBaseProps>;
+/**
+ * A specialized number input component with Blender-like functionality.
+ *
+ * Features:
+ * - Drag left/right to change values with mouse
+ * - Click chevron buttons to increment/decrement
+ * - Keyboard input with mathematical expression support
+ * - Modifier keys: Ctrl (large steps), Shift (precision), Minus (negate)
+ * - Soft and hard value limits
+ * - Unit display support
+ * - Expression evaluation (pi, sqrt, sin, etc.)
+ * - Custom validation and formatting
+ * - Centered value and unit display
+ *
+ * @example
+ * ```tsx
+ * // Basic number input
+ * <NumberInput
+ *   value={rotation}
+ *   onChange={setRotation}
+ *   unit="°"
+ *   step={1}
+ * />
+ *
+ * // With limits and precision
+ * <NumberInput
+ *   value={opacity}
+ *   onChange={setOpacity}
+ *   min={0}
+ *   max={1}
+ *   step={0.1}
+ *   precision={2}
+ *   unit="%"
+ * />
+ *
+ * // With custom validation
+ * <NumberInput
+ *   value={dimension}
+ *   onChange={setDimension}
+ *   validate={(v) => v <= 0 ? "Must be positive" : undefined}
+ *   placeholder="Enter value or expression"
+ * />
+ * ```
+ */
+declare const NumberInput: {
+    ({ value, onChange, unit, showStepButtons, validate, formatValue, parseValue, min, max, softMin, softMax, step, precisionStep, largeStep, precision, allowExpressions, dragSensitivity, size, disabled, readOnly, errorMessage, placeholder, label, helperText, required, className, testId, onFocus, onBlur, onKeyDown, ref, ...props }: NumberInputProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+export { NumberInput };
+export type { NumberInputBaseProps, NumberInputProps };

package/dist/types/components/controls/NumberInput/useNumberInput.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Configuration options for NumberInput behavior
+ */
+interface UseNumberInputOptions {
+    /**
+     * Minimum allowed value (hard limit)
+     */
+    min?: number;
+    /**
+     * Maximum allowed value (hard limit)
+     */
+    max?: number;
+    /**
+     * Soft minimum for drag operations (can be overridden by keyboard)
+     */
+    softMin?: number;
+    /**
+     * Soft maximum for drag operations (can be overridden by keyboard)
+     */
+    softMax?: number;
+    /**
+     * Step size for increment/decrement operations
+     * @default 1
+     */
+    step?: number;
+    /**
+     * Step size when Shift is held (precision mode)
+     * @default step / 10
+     */
+    precisionStep?: number;
+    /**
+     * Step size when Ctrl is held (large steps)
+     * @default step * 10
+     */
+    largeStep?: number;
+    /**
+     * Number of decimal places to round to
+     */
+    precision?: number;
+    /**
+     * Whether to allow mathematical expressions
+     * @default true
+     */
+    allowExpressions?: boolean;
+    /**
+     * Whether the input is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Drag sensitivity multiplier
+     * @default 1
+     */
+    dragSensitivity?: number;
+    /**
+     * Custom format function for display
+     */
+    formatValue?: (value: number) => string;
+    /**
+     * Custom parse function for input
+     */
+    parseValue?: (input: string) => number | null;
+}
+
+export type { UseNumberInputOptions };

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

@@ -0,0 +1,29 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { SelectProps } from './Select.types.js';
+
+/**
+ * Select component for choosing single values from a dropdown list.
+ *
+ * Supports searchable mode, grouped options, keyboard navigation,
+ * clearable state, and multiple visual variants.
+ *
+ * @example
+ * ```tsx
+ * <Select
+ *   label="Blend Mode"
+ *   options={[
+ *     { value: 'normal', label: 'Normal' },
+ *     { value: 'multiply', label: 'Multiply' },
+ *     { value: 'screen', label: 'Screen' },
+ *   ]}
+ *   value={blendMode}
+ *   onChange={setBlendMode}
+ * />
+ * ```
+ */
+declare function Select<T extends string = string>({ value: valueProp, defaultValue, options, placeholder, searchable, searchPlaceholder, filterFn, emptyMessage, size, variant, label, helperText, error, errorMessage, disabled, required, clearable, maxDropdownHeight, minDropdownWidth, name, onChange, onOpenChange, className, style, css, testId, ref, id: idProp, ...rest }: SelectProps<T>): react_jsx_runtime.JSX.Element;
+declare namespace Select {
+    var displayName: string;
+}
+
+export { Select };

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

@@ -0,0 +1,131 @@
+import React from 'react';
+import { Prettify } from '../../../types/utilities.js';
+import { BaseComponent, Size } from '../../../types/common.js';
+
+type SelectSize = Size;
+type SelectVariant = 'default' | 'ghost' | 'filled';
+interface SelectOptionItem<T extends string = string> {
+    /** Unique value used for selection */
+    value: T;
+    /** Display label (falls back to value if not provided) */
+    label?: string;
+    /** Optional icon rendered before the label */
+    icon?: React.ReactNode;
+    /** Whether this option is disabled */
+    disabled?: boolean;
+}
+interface SelectOptionGroup<T extends string = string> {
+    /** Group label displayed as a non-selectable header */
+    label: string;
+    /** Options within this group */
+    options: SelectOptionItem<T>[];
+}
+interface SelectBaseProps<T extends string = string> extends Omit<BaseComponent<HTMLButtonElement>, 'onChange' | 'value' | 'defaultValue'> {
+    /**
+     * Selected value (controlled)
+     */
+    value?: T | null;
+    /**
+     * Default selected value (uncontrolled)
+     */
+    defaultValue?: T;
+    /**
+     * Options to display — flat list or grouped
+     */
+    options: Array<SelectOptionItem<T> | SelectOptionGroup<T>>;
+    /**
+     * Placeholder text when no value is selected
+     * @default "Select..."
+     */
+    placeholder?: string;
+    /**
+     * Whether to show a search/filter input inside the dropdown
+     * @default false
+     */
+    searchable?: boolean;
+    /**
+     * Placeholder for the search input
+     * @default "Search..."
+     */
+    searchPlaceholder?: string;
+    /**
+     * Custom filter function for searchable mode
+     */
+    filterFn?: (option: SelectOptionItem<T>, query: string) => boolean;
+    /**
+     * Message shown when search yields no results
+     * @default "No results found"
+     */
+    emptyMessage?: string;
+    /**
+     * Size using standard library sizing
+     * - `sm`: 20px trigger height
+     * - `md`: 24px trigger height
+     * - `lg`: 32px trigger height
+     * @default "md"
+     */
+    size?: SelectSize;
+    /**
+     * Visual variant for the trigger button
+     * @default "default"
+     */
+    variant?: SelectVariant;
+    /**
+     * Label displayed above the select
+     */
+    label?: string;
+    /**
+     * Helper text displayed below the select
+     */
+    helperText?: string;
+    /**
+     * Error state
+     * @default false
+     */
+    error?: boolean;
+    /**
+     * Error message
+     */
+    errorMessage?: string;
+    /**
+     * Whether the select is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Whether the select is required
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Whether a clear button appears when value is selected
+     * @default false
+     */
+    clearable?: boolean;
+    /**
+     * Maximum height of the dropdown in pixels
+     * @default 240
+     */
+    maxDropdownHeight?: number;
+    /**
+     * Minimum width of the dropdown in pixels.
+     * When set, the dropdown will be at least this wide,
+     * even if the trigger is narrower.
+     */
+    minDropdownWidth?: number;
+    /**
+     * Name attribute for form submission
+     */
+    name?: string;
+    /**
+     * Change event handler
+     */
+    onChange?: (value: T | null) => void;
+    /**
+     * Open state change handler
+     */
+    onOpenChange?: (open: boolean) => void;
+}
+type SelectProps<T extends string = string> = Prettify<SelectBaseProps<T>>;
+
+export type { SelectBaseProps, SelectOptionGroup, SelectOptionItem, SelectProps, SelectSize, SelectVariant };