import { ReactNode } from 'react';

export interface CanvasProps {
  children?: ReactNode;
  /** Enable centered layout. Default: true */
  centered?: boolean;
  /** Show dot background. Default: false */
  dotted?: boolean;
  /** Enable grid snapping (also shows dots). Default: false */
  grid?: boolean;
  /** Grid snap size in pixels when grid is enabled. Default: 18 */
  gridSize?: number;
  /** Color mode: 'auto' follows system preference, 'light' or 'dark' to override. Default: 'auto' */
  colorMode?: 'auto' | 'light' | 'dark';
  /**
   * Layout mode. `'absolute'` (default) renders widgets at saved x/y on a
   * spatial surface. `'flow'` renders widgets in normal document flow so
   * they participate in block/flex/grid layouts and can be styled
   * responsively via author CSS. Drag (when not locked) still works in
   * flow mode via transform offsets.
   */
  layout?: 'absolute' | 'flow';
  /** Optional className appended to the `.tc-canvas` parent for styling
   *  hooks (e.g. responsive layouts in flow mode). */
  className?: string;
}

export declare function Canvas(props: CanvasProps): JSX.Element;

export interface DraggableProps {
  children?: ReactNode;
  /** Grid snap size in pixels. When undefined, no snapping is applied. */
  gridSize?: number;
  /** Stable identifier for persisting drag position. Auto-generated by Canvas if not provided. */
  dragId?: string;
}

export declare function Draggable(props: DraggableProps): JSX.Element;

export interface UseResetCanvasOptions {
  /** Reload the page after clearing state. Default: false */
  reload?: boolean;
}

/** Returns a function that clears all saved canvas positions from localStorage. */
export declare function useResetCanvas(options?: UseResetCanvasOptions): () => void;

export declare function findDragId(children: ReactNode): string | null;
export declare function generateDragId(element: ReactNode, index: number): string;
export declare function getQueue(dragId: string): { x: number; y: number };
export declare function refreshStorage(): void;
export declare function saveDrag(dragId: string, x: number, y: number): void;
