entangle-ui 0.2.0 → 0.3.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/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 };

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

@@ -0,0 +1,39 @@
+import React from 'react';
+import { Prettify } from '../../../types/utilities.js';
+
+type ToastSeverity = 'info' | 'success' | 'warning' | 'error';
+type ToastPosition = 'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center';
+interface ToastData {
+    id?: string;
+    title?: string;
+    message: string;
+    severity?: ToastSeverity;
+    duration?: number;
+    closable?: boolean;
+    showProgress?: boolean;
+    icon?: React.ReactNode;
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+}
+interface ToastProviderBaseProps {
+    children: React.ReactNode;
+    position?: ToastPosition;
+    maxVisible?: number;
+    defaultDuration?: number;
+    gap?: number;
+    zIndex?: number;
+}
+type ToastProviderProps = Prettify<ToastProviderBaseProps>;
+interface UseToastReturn {
+    toast: (data: ToastData) => string;
+    info: (message: string, options?: Partial<ToastData>) => string;
+    success: (message: string, options?: Partial<ToastData>) => string;
+    warning: (message: string, options?: Partial<ToastData>) => string;
+    error: (message: string, options?: Partial<ToastData>) => string;
+    dismiss: (id: string) => void;
+    dismissAll: () => void;
+}
+
+export type { ToastData, ToastPosition, ToastProviderBaseProps, ToastProviderProps, ToastSeverity, UseToastReturn };

package/dist/types/components/feedback/Toast/ToastProvider.d.ts

@@ -0,0 +1,19 @@
+import React from 'react';
+import { ToastProviderProps } from './Toast.types.js';
+
+/**
+ * ToastProvider manages toast notification state and renders them via portal.
+ *
+ * Wrap your application (or a section of it) with this provider, then use
+ * the `useToast()` hook to trigger notifications from any child component.
+ *
+ * @example
+ * ```tsx
+ * <ToastProvider position="bottom-right" maxVisible={5}>
+ *   <App />
+ * </ToastProvider>
+ * ```
+ */
+declare const ToastProvider: React.FC<ToastProviderProps>;
+
+export { ToastProvider };

package/dist/types/components/feedback/Toast/useToast.d.ts

@@ -0,0 +1,22 @@
+import { UseToastReturn } from './Toast.types.js';
+
+/**
+ * Hook to trigger toast notifications from any component
+ * inside a `<ToastProvider>`.
+ *
+ * @throws Error if used outside of a `<ToastProvider>`
+ *
+ * @example
+ * ```tsx
+ * const { toast, success, error, dismiss } = useToast();
+ *
+ * success('File saved successfully');
+ * error('Failed to export', { title: 'Export Error' });
+ *
+ * const id = toast({ message: 'Custom toast', severity: 'info' });
+ * dismiss(id);
+ * ```
+ */
+declare function useToast(): UseToastReturn;
+
+export { useToast };