skema-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,356 @@
+import React from 'react';
+
+/**
+ * Represents a single DOM element in a selection
+ */
+interface DOMElement {
+    selector: string;
+    tagName: string;
+    elementPath: string;
+    text: string;
+    boundingBox: BoundingBox;
+    cssClasses?: string;
+    attributes?: Record<string, string>;
+}
+/**
+ * Represents a DOM element selection (can contain one or more elements)
+ */
+interface DOMSelection {
+    id: string;
+    selector: string;
+    tagName: string;
+    elementPath: string;
+    text: string;
+    boundingBox: BoundingBox;
+    timestamp: number;
+    pathname: string;
+    cssClasses?: string;
+    attributes?: Record<string, string>;
+    /** User annotation comment */
+    comment?: string;
+    /** Whether this is a multi-element selection */
+    isMultiSelect?: boolean;
+    /** Individual elements when this is a grouped selection */
+    elements?: DOMElement[];
+}
+/**
+ * Pending annotation state for the popup
+ */
+interface PendingAnnotation {
+    /** Screen X position (percentage of viewport width) */
+    x: number;
+    /** Screen Y position (pixels from top of document) */
+    y: number;
+    /** Y position relative to viewport (for popup positioning) */
+    clientY: number;
+    /** Element identifier string */
+    element: string;
+    /** CSS selector path */
+    elementPath: string;
+    /** Selected text content if any */
+    selectedText?: string;
+    /** Bounding box of selected element(s) */
+    boundingBox?: BoundingBox;
+    /** Whether this is a multi-element selection */
+    isMultiSelect?: boolean;
+    /** The DOM selection(s) being annotated */
+    selections?: DOMSelection[];
+    /** Type of annotation */
+    annotationType: 'dom_selection' | 'drawing';
+    /** Drawing shape IDs if annotating drawings */
+    shapeIds?: string[];
+}
+/**
+ * Bounding box for element positioning
+ */
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Viewport information for coordinate calculations
+ */
+interface ViewportInfo {
+    width: number;
+    height: number;
+    scrollX: number;
+    scrollY: number;
+}
+/**
+ * Computed styles for an element
+ */
+interface ElementStyles {
+    fontFamily?: string;
+    fontSize?: string;
+    fontWeight?: string;
+    lineHeight?: string;
+    letterSpacing?: string;
+    textAlign?: string;
+    color?: string;
+    padding?: string;
+    margin?: string;
+    gap?: string;
+    display?: string;
+    flexDirection?: string;
+    alignItems?: string;
+    justifyContent?: string;
+    backgroundColor?: string;
+    borderRadius?: string;
+    border?: string;
+    boxShadow?: string;
+    width?: string;
+    height?: string;
+    maxWidth?: string;
+}
+/**
+ * Nearby element with style context for AI
+ */
+interface NearbyElement {
+    selector: string;
+    tagName: string;
+    text?: string;
+    className?: string;
+    styles?: ElementStyles;
+    tailwindClasses?: string[];
+}
+/**
+ * Project-level style context
+ */
+interface ProjectStyleContext {
+    cssFramework?: 'tailwind' | 'bootstrap' | 'material-ui' | 'chakra' | 'vanilla' | 'css-modules' | 'styled-components' | 'unknown';
+    cssVariables?: Record<string, string>;
+    colorPalette?: string[];
+    baseFontFamily?: string;
+    baseFontSize?: string;
+}
+/**
+ * Drawing annotation from tldraw
+ */
+interface DrawingAnnotation {
+    id: string;
+    type: 'drawing';
+    tool: string;
+    shapes: unknown[];
+    boundingBox: BoundingBox;
+    relatedTo?: string;
+    timestamp: number;
+    /** User annotation comment describing what to build */
+    comment?: string;
+    /** SVG representation of the drawing for AI processing */
+    drawingSvg?: string;
+    /** Base64 PNG image of the drawing for vision AI */
+    drawingImage?: string;
+    /** Extracted text content from text shapes in the drawing */
+    extractedText?: string;
+    /** Grid configuration used for positioning reference */
+    gridConfig?: {
+        color: string;
+        size: number;
+        labels: boolean;
+    };
+    /** Viewport info for relative sizing context */
+    viewport?: ViewportInfo;
+    /** Project-level style context */
+    projectStyles?: ProjectStyleContext;
+    /** Nearby DOM elements that the drawing may relate to */
+    nearbyElements?: NearbyElement[];
+}
+/**
+ * Gesture action annotation
+ */
+interface GestureAnnotation {
+    id: string;
+    type: 'gesture';
+    gesture: 'scribble_delete' | 'circle' | 'rectangle' | 'arrow';
+    target?: string;
+    boundingBox: BoundingBox;
+    timestamp: number;
+}
+/**
+ * Union type for all annotation types
+ */
+type Annotation = {
+    type: 'dom_selection';
+} & DOMSelection | DrawingAnnotation | GestureAnnotation;
+/**
+ * Complete export format for annotations
+ */
+interface AnnotationExport {
+    version: string;
+    timestamp: string;
+    viewport: ViewportInfo;
+    pathname: string;
+    annotations: Annotation[];
+}
+/**
+ * Skema component props
+ */
+interface SkemaProps {
+    /** Whether Skema overlay is enabled */
+    enabled?: boolean;
+    /** Callback when annotations change */
+    onAnnotationsChange?: (annotations: Annotation[]) => void;
+    /** Callback when a single annotation is submitted - for real-time integrations like Gemini */
+    onAnnotationSubmit?: (annotation: Annotation, comment: string) => void;
+    /** Callback when an annotation is deleted - for reverting changes */
+    onAnnotationDelete?: (annotationId: string) => void;
+    /** Keyboard shortcut to toggle Skema (default: Cmd/Ctrl + Shift + E) */
+    toggleShortcut?: string;
+    /** Initial annotations to load */
+    initialAnnotations?: Annotation[];
+    /** Z-index for the overlay (default: 99999) */
+    zIndex?: number;
+}
+/**
+ * Skema mode - determines what tools are available
+ */
+type SkemaMode = 'select' | 'draw';
+
+/**
+ * Main Skema component - renders tldraw as a transparent overlay
+ */
+declare const Skema: React.FC<SkemaProps>;
+
+interface AnnotationPopupProps {
+    /** Element name/description to display in header */
+    element: string;
+    /** Optional selected/highlighted text */
+    selectedText?: string;
+    /** Placeholder text for the textarea */
+    placeholder?: string;
+    /** Initial value for textarea (for edit mode) */
+    initialValue?: string;
+    /** Label for submit button (default: "Add") */
+    submitLabel?: string;
+    /** Called when annotation is submitted with text */
+    onSubmit: (text: string) => void;
+    /** Called when popup is cancelled/dismissed */
+    onCancel: () => void;
+    /** Position styles (left, top) */
+    style?: React.CSSProperties;
+    /** Custom accent color (hex) */
+    accentColor?: string;
+    /** External exit state (parent controls exit animation) */
+    isExiting?: boolean;
+    /** Whether this is a multi-select annotation */
+    isMultiSelect?: boolean;
+}
+interface AnnotationPopupHandle {
+    /** Shake the popup (e.g., when user clicks outside) */
+    shake: () => void;
+}
+declare const AnnotationPopup: React.ForwardRefExoticComponent<AnnotationPopupProps & React.RefAttributes<AnnotationPopupHandle>>;
+
+/**
+ * Generates a unique CSS selector for an element
+ */
+declare function generateSelector(element: HTMLElement): string;
+/**
+ * Gets a readable path for an element (e.g., "article > section > p")
+ */
+declare function getElementPath(target: HTMLElement, maxDepth?: number): string;
+/**
+ * Identifies an element and returns a human-readable name
+ */
+declare function identifyElement(target: HTMLElement): string;
+/**
+ * Gets bounding box for an element in document coordinates (includes scroll offset)
+ */
+declare function getBoundingBox(element: HTMLElement): BoundingBox;
+/**
+ * Gets CSS class names from an element (cleaned of module hashes)
+ */
+declare function getElementClasses(target: HTMLElement): string;
+/**
+ * Creates a DOMSelection from an element
+ */
+declare function createDOMSelection(element: HTMLElement): DOMSelection;
+/**
+ * Checks if an element should be ignored for DOM picking
+ */
+declare function shouldIgnoreElement(element: HTMLElement): boolean;
+
+/**
+ * Gets current viewport information
+ */
+declare function getViewportInfo(): ViewportInfo;
+/**
+ * Converts viewport-relative coordinates to document coordinates
+ */
+declare function viewportToDocument(x: number, y: number, viewport?: ViewportInfo): {
+    x: number;
+    y: number;
+};
+/**
+ * Converts document coordinates to viewport-relative coordinates
+ */
+declare function documentToViewport(x: number, y: number, viewport?: ViewportInfo): {
+    x: number;
+    y: number;
+};
+/**
+ * Converts a bounding box from viewport to document coordinates
+ */
+declare function bboxViewportToDocument(bbox: BoundingBox, viewport?: ViewportInfo): BoundingBox;
+/**
+ * Converts a bounding box from document to viewport coordinates
+ */
+declare function bboxDocumentToViewport(bbox: BoundingBox, viewport?: ViewportInfo): BoundingBox;
+/**
+ * Checks if two bounding boxes intersect
+ */
+declare function bboxIntersects(a: BoundingBox, b: BoundingBox): boolean;
+/**
+ * Checks if point is inside bounding box
+ */
+declare function pointInBbox(x: number, y: number, bbox: BoundingBox): boolean;
+/**
+ * Gets the center point of a bounding box
+ */
+declare function bboxCenter(bbox: BoundingBox): {
+    x: number;
+    y: number;
+};
+/**
+ * Expands a bounding box by a padding amount
+ */
+declare function expandBbox(bbox: BoundingBox, padding: number): BoundingBox;
+/**
+ * Creates a bounding box from two points
+ */
+declare function bboxFromPoints(x1: number, y1: number, x2: number, y2: number): BoundingBox;
+
+/**
+ * Convert a Blob to a base64 string
+ */
+declare function blobToBase64(blob: Blob): Promise<string>;
+/**
+ * Add a labeled grid overlay to an SVG string
+ * Grid uses A/B/C column labels and 0/1/2 row numbers for positioning reference
+ * @param svgString - The SVG markup to add grid to
+ * @param opts - Grid options (color, cell size, whether to show labels)
+ * @returns SVG string with grid overlay added
+ */
+declare function addGridToSvg(svgString: string, opts?: {
+    color?: string;
+    size?: number;
+    labels?: boolean;
+}): string;
+/**
+ * Get the grid cell reference (e.g., "B2") for a given position
+ * @param x - X coordinate in pixels
+ * @param y - Y coordinate in pixels
+ * @param gridSize - Size of each grid cell (default 100px)
+ * @returns Grid cell reference string (e.g., "B2")
+ */
+declare function getGridCellReference(x: number, y: number, gridSize?: number): string;
+/**
+ * Extract text content from tldraw shapes
+ * @param shapes - Array of tldraw shapes
+ * @returns Combined text content from text and note shapes
+ */
+declare function extractTextFromShapes(shapes: unknown[]): string;
+
+export { type Annotation, type AnnotationExport, AnnotationPopup, type AnnotationPopupHandle, type AnnotationPopupProps, type BoundingBox, type DOMElement, type DOMSelection, type DrawingAnnotation, type ElementStyles, type GestureAnnotation, type NearbyElement, type PendingAnnotation, type ProjectStyleContext, Skema, type SkemaMode, type SkemaProps, type ViewportInfo, addGridToSvg, bboxCenter, bboxDocumentToViewport, bboxFromPoints, bboxIntersects, bboxViewportToDocument, blobToBase64, createDOMSelection, Skema as default, documentToViewport, expandBbox, extractTextFromShapes, generateSelector, getBoundingBox, getElementClasses, getElementPath, getGridCellReference, getViewportInfo, identifyElement, pointInBbox, shouldIgnoreElement, viewportToDocument };