entangle-ui 0.2.0 → 0.4.0

package/dist/types/components/editor/PropertyInspector/PropertyInspector.types.d.ts

@@ -0,0 +1,238 @@
+import React from 'react';
+import { Prettify } from '../../../types/utilities.js';
+import { BaseComponent, Size } from '../../../types/common.js';
+
+type PropertyInspectorSize = Size;
+interface PropertyPanelBaseProps extends BaseComponent {
+    /**
+     * Panel content — PropertySection, PropertyGroup, or any elements
+     */
+    children: React.ReactNode;
+    /**
+     * Content rendered in the fixed header area (above scrollable content)
+     */
+    header?: React.ReactNode;
+    /**
+     * Content rendered in the fixed footer area (below scrollable content)
+     */
+    footer?: React.ReactNode;
+    /**
+     * Size applied to all nested PropertySection and PropertyRow components.
+     * Individual components can override this.
+     * @default "md"
+     */
+    size?: PropertyInspectorSize;
+    /**
+     * Maximum height of the panel (enables scrolling via ScrollArea)
+     * @default "100%"
+     */
+    maxHeight?: number | string;
+    /**
+     * Whether to show a search/filter input in the header
+     * @default false
+     */
+    searchable?: boolean;
+    /**
+     * Placeholder for the search input
+     * @default "Search properties..."
+     */
+    searchPlaceholder?: string;
+    /**
+     * Callback when search query changes
+     */
+    onSearchChange?: (query: string) => void;
+    /**
+     * Top padding for the scrollable content area (in px).
+     * Use this to increase/decrease the space before the first property section.
+     * @default theme.spacing.sm
+     */
+    contentTopSpacing?: number;
+    /**
+     * Bottom padding for the scrollable content area (in px).
+     * Use this to increase/decrease the space after the last property section.
+     * @default theme.spacing.md
+     */
+    contentBottomSpacing?: number;
+    /**
+     * Text displayed when no sections/rows match the search
+     * @default "No matching properties"
+     */
+    emptySearchMessage?: string;
+}
+type PropertyPanelProps = Prettify<PropertyPanelBaseProps>;
+interface PropertySectionBaseProps extends Omit<BaseComponent, 'onChange'> {
+    /**
+     * Section title displayed in the collapsible header
+     */
+    title: string;
+    /**
+     * Unique identifier for this section (used for expansion state).
+     * Defaults to title if not provided.
+     */
+    value?: string;
+    /**
+     * Icon displayed before the section title
+     */
+    icon?: React.ReactNode;
+    /**
+     * Action buttons rendered on the right side of the header.
+     * Clicking actions does NOT toggle the section.
+     */
+    actions?: React.ReactNode;
+    /**
+     * Whether this section is expanded (controlled)
+     */
+    expanded?: boolean;
+    /**
+     * Whether this section starts expanded (uncontrolled)
+     * @default true
+     */
+    defaultExpanded?: boolean;
+    /**
+     * Callback when expanded state changes
+     */
+    onExpandedChange?: (expanded: boolean) => void;
+    /**
+     * Whether to keep content mounted when collapsed
+     * @default false
+     */
+    keepMounted?: boolean;
+    /**
+     * Whether this section is disabled (not collapsible, dimmed)
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Size override for this section and its rows
+     */
+    size?: PropertyInspectorSize;
+    /**
+     * Section content — PropertyRow, PropertyGroup, or any elements
+     */
+    children: React.ReactNode;
+    /**
+     * Custom chevron indicator — pass `null` to hide
+     * @default built-in chevron icon
+     */
+    indicator?: React.ReactNode | null;
+    /**
+     * Right-click context menu handler on the section header
+     */
+    onContextMenu?: (event: React.MouseEvent) => void;
+}
+type PropertySectionProps = Prettify<PropertySectionBaseProps>;
+interface PropertyRowBaseProps extends BaseComponent {
+    /**
+     * Property label text
+     */
+    label: string;
+    /**
+     * Tooltip text for the label (shown on hover)
+     */
+    tooltip?: string;
+    /**
+     * Control content — any form control or custom content.
+     * Displayed on the right side, fills remaining space.
+     */
+    children: React.ReactNode;
+    /**
+     * Whether the row spans full width (label above, control below)
+     * @default false
+     */
+    fullWidth?: boolean;
+    /**
+     * Label/value split ratio as percentages [label%, value%].
+     * @default [40, 60]
+     */
+    splitRatio?: [number, number];
+    /**
+     * Whether this property has been modified from its default value.
+     * Shows a visual indicator (dot or bold label).
+     * @default false
+     */
+    modified?: boolean;
+    /**
+     * Whether this row is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Whether this row is visible (controlled by search filtering)
+     * @default true
+     */
+    visible?: boolean;
+    /**
+     * Size override for this row
+     */
+    size?: PropertyInspectorSize;
+    /**
+     * Action button on the right edge of the row (e.g., reset to default).
+     * Appears on hover.
+     */
+    action?: React.ReactNode;
+    /**
+     * Callback when label is right-clicked (for context menu)
+     */
+    onLabelContextMenu?: (event: React.MouseEvent) => void;
+    /**
+     * Callback when reset action is triggered.
+     * If provided, a reset button automatically appears on hover.
+     */
+    onReset?: () => void;
+}
+type PropertyRowProps = Prettify<PropertyRowBaseProps>;
+interface PropertyGroupBaseProps extends BaseComponent {
+    /**
+     * Optional group title (rendered as a small label divider)
+     */
+    title?: string;
+    /**
+     * Group content — PropertyRow elements
+     */
+    children: React.ReactNode;
+    /**
+     * Indent level for nested groups (number of indent steps)
+     * @default 0
+     */
+    indent?: number;
+    /**
+     * Whether all rows in this group are disabled
+     * @default false
+     */
+    disabled?: boolean;
+}
+type PropertyGroupProps = Prettify<PropertyGroupBaseProps>;
+interface PropertyUndoEntry<T = unknown> {
+    /** Property path or identifier */
+    propertyId: string;
+    /** Value before the change */
+    previousValue: T;
+    /** Value after the change */
+    newValue: T;
+    /** Human-readable description */
+    label: string;
+    /** Timestamp */
+    timestamp: number;
+}
+interface UsePropertyUndoOptions {
+    /** Maximum undo stack size @default 50 */
+    maxHistory?: number;
+}
+interface UsePropertyUndoReturn<T = unknown> {
+    /** Wrap a value change to record it in the undo stack */
+    record: (entry: Omit<PropertyUndoEntry<T>, 'timestamp'>) => void;
+    /** Undo the last change — returns the entry that was undone, or null */
+    undo: () => PropertyUndoEntry<T> | null;
+    /** Redo the last undone change — returns the entry, or null */
+    redo: () => PropertyUndoEntry<T> | null;
+    /** Whether undo is available */
+    canUndo: boolean;
+    /** Whether redo is available */
+    canRedo: boolean;
+    /** Full undo history */
+    history: PropertyUndoEntry<T>[];
+    /** Clear all history */
+    clear: () => void;
+}
+
+export type { PropertyGroupBaseProps, PropertyGroupProps, PropertyInspectorSize, PropertyPanelBaseProps, PropertyPanelProps, PropertyRowBaseProps, PropertyRowProps, PropertySectionBaseProps, PropertySectionProps, PropertyUndoEntry, UsePropertyUndoOptions, UsePropertyUndoReturn };

package/dist/types/components/editor/PropertyInspector/PropertyPanel.d.ts

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

package/dist/types/components/editor/PropertyInspector/PropertyRow.d.ts

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

package/dist/types/components/editor/PropertyInspector/PropertySection.d.ts

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

package/dist/types/components/editor/PropertyInspector/usePropertyUndo.d.ts

@@ -0,0 +1,9 @@
+import { UsePropertyUndoOptions, UsePropertyUndoReturn } from './PropertyInspector.types.js';
+
+/**
+ * Lightweight undo/redo stack for property changes.
+ * Records entries with property identifiers and values for precise undo control.
+ */
+declare function usePropertyUndo<T = unknown>(options?: UsePropertyUndoOptions): UsePropertyUndoReturn<T>;
+
+export { usePropertyUndo };

package/dist/types/components/editor/ViewportGizmo/ViewportGizmo.d.ts

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

package/dist/types/components/editor/ViewportGizmo/ViewportGizmo.types.d.ts

@@ -0,0 +1,146 @@
+import { Prettify } from '../../../types/utilities.js';
+import { BaseComponent, Size } from '../../../types/common.js';
+
+type ViewportGizmoSize = Size;
+/**
+ * Camera/viewport orientation as Euler angles (degrees).
+ * Convention: intrinsic YXZ (heading-pitch-roll), matching Three.js default.
+ */
+interface GizmoOrientation {
+    /** Rotation around Y axis (heading/yaw) in degrees */
+    yaw: number;
+    /** Rotation around X axis (pitch) in degrees */
+    pitch: number;
+    /** Rotation around Z axis (roll) in degrees @default 0 */
+    roll?: number;
+}
+/**
+ * Orbital rotation delta during a drag gesture.
+ * The app applies this to its camera orbit controller.
+ */
+interface OrbitDelta {
+    /** Yaw change in degrees (horizontal drag) */
+    deltaYaw: number;
+    /** Pitch change in degrees (vertical drag) */
+    deltaPitch: number;
+}
+/**
+ * Preset axis color conventions.
+ * - `blender`: X=red, Y=green, Z=blue
+ * - `unreal`: X=red, Y=green, Z=blue (same colors, Z-up)
+ * - `custom`: use `axisConfig` prop
+ */
+type GizmoAxisColorPreset = 'blender' | 'unreal' | 'custom';
+/**
+ * Up axis convention.
+ * - `y-up`: Y is vertical (Three.js, Babylon, Maya)
+ * - `z-up`: Z is vertical (Blender, Unreal, CAD)
+ */
+type GizmoUpAxis = 'y-up' | 'z-up';
+/** Custom per-axis configuration. */
+interface GizmoAxisConfig {
+    /** Axis label text @default "X"/"Y"/"Z" */
+    label?: string;
+    /** Axis color (CSS color string) */
+    color?: string;
+    /** Whether this axis arm is visible @default true */
+    visible?: boolean;
+}
+/** Named preset camera views for snap navigation. */
+type GizmoPresetView = 'front' | 'back' | 'left' | 'right' | 'top' | 'bottom';
+interface ViewportGizmoBaseProps extends Omit<BaseComponent, 'onChange'> {
+    /**
+     * Current viewport orientation (controlled).
+     * The gizmo always reflects this — it never owns orientation state.
+     */
+    orientation: GizmoOrientation;
+    /**
+     * Which axis points up.
+     * @default "y-up"
+     */
+    upAxis?: GizmoUpAxis;
+    /**
+     * Axis color convention.
+     * @default "blender"
+     */
+    axisColorPreset?: GizmoAxisColorPreset;
+    /**
+     * Per-axis customization [X, Y, Z].
+     * Used when `axisColorPreset="custom"`.
+     */
+    axisConfig?: [GizmoAxisConfig, GizmoAxisConfig, GizmoAxisConfig];
+    /**
+     * Whether to show axis labels at arm tips.
+     * @default true
+     */
+    showLabels?: boolean;
+    /**
+     * Whether to show negative axis arms (dimmed, shorter).
+     * @default true
+     */
+    showNegativeAxes?: boolean;
+    /**
+     * Whether to show a thin orbit ring around the gizmo.
+     * @default true
+     */
+    showOrbitRing?: boolean;
+    /**
+     * Whether to show an origin handle (home button).
+     * @default true
+     */
+    showOriginHandle?: boolean;
+    /**
+     * Background style.
+     * @default "subtle"
+     */
+    background?: 'transparent' | 'subtle' | 'solid';
+    /**
+     * Interaction mode.
+     * @default "full"
+     */
+    interactionMode?: 'full' | 'snap-only' | 'orbit-only' | 'display-only';
+    /**
+     * Orbit speed multiplier.
+     * @default 1
+     */
+    orbitSpeed?: number;
+    /**
+     * Whether to constrain pitch to [-90, 90].
+     * @default true
+     */
+    constrainPitch?: boolean;
+    /** Called continuously while the user drags to orbit. */
+    onOrbit?: (delta: OrbitDelta) => void;
+    /** Called when the user finishes an orbit drag. */
+    onOrbitEnd?: (finalOrientation: GizmoOrientation) => void;
+    /** Called when the user clicks an axis to snap to a preset view. */
+    onSnapToView?: (view: GizmoPresetView) => void;
+    /** Called when the user clicks a specific axis arm. */
+    onAxisClick?: (axis: 'x' | 'y' | 'z', positive: boolean) => void;
+    /** Called when the user clicks the origin handle. */
+    onOriginClick?: () => void;
+    /**
+     * Gizmo diameter in pixels.
+     * @default 120
+     */
+    diameter?: number;
+    /**
+     * Component size — affects label font size.
+     * @default "md"
+     */
+    size?: ViewportGizmoSize;
+    /**
+     * Whether the gizmo is disabled.
+     * @default false
+     */
+    disabled?: boolean;
+}
+type ViewportGizmoProps = Prettify<ViewportGizmoBaseProps>;
+/** Axis arm hit region for interaction. */
+interface GizmoHitRegion {
+    type: 'axis-positive' | 'axis-negative' | 'label' | 'origin' | 'ring' | 'none';
+    axis?: 'x' | 'y' | 'z';
+    distance: number;
+}
+
+export type { GizmoAxisColorPreset, GizmoAxisConfig, GizmoHitRegion, GizmoOrientation, GizmoPresetView, GizmoUpAxis, OrbitDelta, ViewportGizmoBaseProps, ViewportGizmoProps, ViewportGizmoSize };

package/dist/types/components/editor/ViewportGizmo/gizmoMath.d.ts

@@ -0,0 +1,73 @@
+import { GizmoUpAxis, GizmoPresetView, GizmoOrientation, GizmoHitRegion } from './ViewportGizmo.types.js';
+
+/** 3D vector */
+interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Build a 3×3 rotation matrix from Euler angles (YXZ intrinsic order).
+ * Matches Three.js default Euler order.
+ *
+ * @param yaw  - Y-axis rotation in degrees
+ * @param pitch - X-axis rotation in degrees
+ * @param roll  - Z-axis rotation in degrees
+ * @returns [right, up, forward] basis vectors (columns of rotation matrix)
+ */
+declare function eulerToRotationMatrix(yaw: number, pitch: number, roll?: number): [Vec3, Vec3, Vec3];
+/**
+ * Project a 3D point to 2D canvas coordinates using orthographic projection.
+ *
+ * @param point   - 3D point to project
+ * @param orientation - Camera orientation
+ * @param center  - Canvas center in pixels
+ * @param scale   - Pixels per unit
+ * @returns Projected position { x, y, depth }
+ */
+declare function projectToCanvas(point: Vec3, orientation: GizmoOrientation, center: {
+    x: number;
+    y: number;
+}, scale: number): {
+    x: number;
+    y: number;
+    depth: number;
+};
+/** Projected axis arm data */
+interface ProjectedArm {
+    axis: 'x' | 'y' | 'z';
+    positive: boolean;
+    screenX: number;
+    screenY: number;
+    depth: number;
+}
+/**
+ * Get all 6 axis arm endpoints projected to 2D, sorted by depth (furthest first).
+ */
+declare function projectAxes(orientation: GizmoOrientation, center: {
+    x: number;
+    y: number;
+}, armLength: number, upAxis: GizmoUpAxis): ProjectedArm[];
+/**
+ * Hit test a screen position against the gizmo geometry.
+ */
+declare function gizmoHitTest(px: number, py: number, orientation: GizmoOrientation, center: {
+    x: number;
+    y: number;
+}, armLength: number, upAxis: GizmoUpAxis, tolerancePx?: number, originRadius?: number): GizmoHitRegion;
+/**
+ * Convert a preset view name to Euler angles.
+ */
+declare function presetViewToOrientation(view: GizmoPresetView, upAxis: GizmoUpAxis): GizmoOrientation;
+/**
+ * Convert quaternion [x, y, z, w] to Euler representation (YXZ order, degrees).
+ * Utility for Three.js integration where `camera.quaternion` is available.
+ */
+declare function quaternionToEuler(qx: number, qy: number, qz: number, qw: number): GizmoOrientation;
+/**
+ * Map an axis tip click to the corresponding preset view.
+ */
+declare function axisToPresetView(axis: 'x' | 'y' | 'z', positive: boolean, upAxis: GizmoUpAxis): GizmoPresetView | null;
+
+export { axisToPresetView, eulerToRotationMatrix, gizmoHitTest, presetViewToOrientation, projectAxes, projectToCanvas, quaternionToEuler };
+export type { ProjectedArm, Vec3 };

package/dist/types/components/feedback/Dialog/Dialog.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+import { DialogProps } from './Dialog.types.js';
+
+/**
+ * Dialog component for modal overlays in editor interfaces.
+ *
+ * Renders an accessible modal dialog with overlay, focus trap,
+ * and keyboard support. Compound component pattern: use with
+ * DialogHeader, DialogBody, DialogFooter, and DialogClose.
+ *
+ * @example
+ * ```tsx
+ * <Dialog open={isOpen} onClose={() => setIsOpen(false)} title="Confirm">
+ *   <DialogHeader>Confirm Action</DialogHeader>
+ *   <DialogBody>Are you sure?</DialogBody>
+ *   <DialogFooter align="right">
+ *     <Button onClick={() => setIsOpen(false)}>Cancel</Button>
+ *     <Button variant="filled">Confirm</Button>
+ *   </DialogFooter>
+ * </Dialog>
+ * ```
+ */
+declare const Dialog: React.FC<DialogProps>;
+
+export { Dialog };

package/dist/types/components/feedback/Dialog/Dialog.types.d.ts

@@ -0,0 +1,55 @@
+import React from 'react';
+import { Prettify } from '../../../types/utilities.js';
+import { BaseComponent } from '../../../types/common.js';
+
+type DialogSize = 'sm' | 'md' | 'lg' | 'xl' | 'fullscreen';
+interface DialogBaseProps extends BaseComponent {
+    /** Whether the dialog is open */
+    open: boolean;
+    /** Callback fired when the dialog should close */
+    onClose: () => void;
+    /** Dialog width preset */
+    size?: DialogSize;
+    /** Dialog title — used for aria-labelledby */
+    title?: string;
+    /** Dialog description — used for aria-describedby */
+    description?: string;
+    /** Whether clicking the overlay closes the dialog */
+    closeOnOverlayClick?: boolean;
+    /** Whether pressing Escape closes the dialog */
+    closeOnEscape?: boolean;
+    /** Whether to show the overlay backdrop */
+    showOverlay?: boolean;
+    /** Whether to trap focus within the dialog */
+    trapFocus?: boolean;
+    /** Ref to the element that should receive initial focus */
+    initialFocusRef?: React.RefObject<HTMLElement>;
+    /** Whether to render the dialog in a portal (document.body) */
+    portal?: boolean;
+    /** Dialog content (use DialogHeader, DialogBody, DialogFooter) */
+    children: React.ReactNode;
+}
+type DialogProps = Prettify<DialogBaseProps>;
+interface DialogHeaderBaseProps extends BaseComponent {
+    /** Header content (typically a title) */
+    children: React.ReactNode;
+    /** Whether to show the close button */
+    showClose?: boolean;
+    /** Optional description text below the title */
+    description?: string;
+}
+type DialogHeaderProps = Prettify<DialogHeaderBaseProps>;
+interface DialogBodyBaseProps extends BaseComponent {
+    /** Body content */
+    children: React.ReactNode;
+}
+type DialogBodyProps = Prettify<DialogBodyBaseProps>;
+interface DialogFooterBaseProps extends BaseComponent {
+    /** Footer content (typically action buttons) */
+    children: React.ReactNode;
+    /** Horizontal alignment of footer content */
+    align?: 'left' | 'center' | 'right' | 'space-between';
+}
+type DialogFooterProps = Prettify<DialogFooterBaseProps>;
+
+export type { DialogBaseProps, DialogBodyBaseProps, DialogBodyProps, DialogFooterBaseProps, DialogFooterProps, DialogHeaderBaseProps, DialogHeaderProps, DialogProps, DialogSize };

package/dist/types/components/feedback/Dialog/DialogBody.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import { DialogBodyProps } from './Dialog.types.js';
+
+/**
+ * DialogBody renders the scrollable content area of a Dialog.
+ *
+ * @example
+ * ```tsx
+ * <DialogBody>
+ *   <p>Dialog content goes here.</p>
+ * </DialogBody>
+ * ```
+ */
+declare const DialogBody: React.FC<DialogBodyProps>;
+
+export { DialogBody };

package/dist/types/components/feedback/Dialog/DialogClose.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+
+interface DialogCloseProps {
+    /** The element to wrap with close behavior */
+    children: React.ReactElement<{
+        onClick?: React.MouseEventHandler;
+    }>;
+}
+/**
+ * DialogClose wraps a child element and adds onClick to close the dialog.
+ *
+ * @example
+ * ```tsx
+ * <DialogClose>
+ *   <Button>Cancel</Button>
+ * </DialogClose>
+ * ```
+ */
+declare const DialogClose: React.FC<DialogCloseProps>;
+
+export { DialogClose };

package/dist/types/components/feedback/Dialog/DialogFooter.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import { DialogFooterProps } from './Dialog.types.js';
+
+/**
+ * DialogFooter renders the action area at the bottom of a Dialog.
+ *
+ * @example
+ * ```tsx
+ * <DialogFooter align="right">
+ *   <Button onClick={onCancel}>Cancel</Button>
+ *   <Button variant="filled" onClick={onConfirm}>Confirm</Button>
+ * </DialogFooter>
+ * ```
+ */
+declare const DialogFooter: React.FC<DialogFooterProps>;
+
+export { DialogFooter };

package/dist/types/components/feedback/Dialog/DialogHeader.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import { DialogHeaderProps } from './Dialog.types.js';
+
+/**
+ * DialogHeader renders the title, optional description, and close button
+ * for a Dialog.
+ *
+ * @example
+ * ```tsx
+ * <DialogHeader description="This cannot be undone">
+ *   Delete Item
+ * </DialogHeader>
+ * ```
+ */
+declare const DialogHeader: React.FC<DialogHeaderProps>;
+
+export { DialogHeader };