@squaredr/fieldcraft-pro 0.0.0

package/dist/form-builder/index.d.mts

@@ -0,0 +1,367 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { FormEngineSchema, QuestionType, Section, Question, Option } from '@squaredr/fieldcraft-core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ClassValue } from 'clsx';
+import * as _dnd_kit_core from '@dnd-kit/core';
+import { DragStartEvent, DragEndEvent } from '@dnd-kit/core';
+
+declare const FormBuilder: react.ComponentType<FormBuilderProps>;
+
+/**
+ * FormBuilder theme configuration.
+ * All values are CSS color strings (hex, oklch, hsl, etc.).
+ * Set these to customize the builder's appearance.
+ */
+type FormBuilderTheme = {
+    /** Main background of the entire builder */
+    background?: string;
+    /** Primary text color */
+    foreground?: string;
+    /** Card/panel background */
+    card?: string;
+    /** Primary accent color (buttons, selection, focus rings) */
+    primary?: string;
+    /** Text color on primary backgrounds */
+    primaryForeground?: string;
+    /** Secondary surfaces */
+    secondary?: string;
+    /** Text on secondary surfaces */
+    secondaryForeground?: string;
+    /** Muted background (disabled, subtle areas) */
+    muted?: string;
+    /** Muted text (labels, placeholders) */
+    mutedForeground?: string;
+    /** Hover/accent background */
+    accent?: string;
+    /** Text on accent background */
+    accentForeground?: string;
+    /** Destructive action color */
+    destructive?: string;
+    /** Text on destructive backgrounds */
+    destructiveForeground?: string;
+    /** Default border color */
+    border?: string;
+    /** Input border color */
+    input?: string;
+    /** Focus ring color */
+    ring?: string;
+    /** Border radius base (e.g. "6px", "0.375rem") */
+    radius?: string;
+    /** Surface color for panels/sidebars */
+    surface?: string;
+    /** Surface hover state */
+    surfaceHover?: string;
+    /** Main canvas background */
+    canvas?: string;
+    /** Panel background (palette, property panel) */
+    panel?: string;
+    /** Strong border color (for emphasis) */
+    borderStrong?: string;
+    /** Dim text color (secondary labels) */
+    textDim?: string;
+};
+
+type FormBuilderProps = {
+    /** Initial schema to load. If not provided, uses a default empty schema */
+    initialSchema?: FormEngineSchema;
+    /** Callback when schema changes */
+    onChange?: (schema: FormEngineSchema) => void;
+    /** Callback when user clicks "Save" */
+    onSave?: (schema: FormEngineSchema) => void;
+    /** Height of the builder container */
+    height?: string | number;
+    /** Theme customization — overrides CSS variables for all builder components */
+    theme?: FormBuilderTheme;
+    /** Additional CSS class name on the root element */
+    className?: string;
+    /** Extra content rendered in the toolbar, after the Save button */
+    toolbarExtra?: ReactNode;
+    /** Additional question type metadata — merged with built-in defaults (e.g. telehealth fields) */
+    questionTypes?: Record<string, QuestionTypeInfo>;
+    /** Additional palette categories — appended to built-in palette (e.g. telehealth categories) */
+    palette?: PaletteCategory[];
+};
+type BuilderState = {
+    schema: FormEngineSchema;
+    selectedItem: SelectedItem | null;
+    isDirty: boolean;
+};
+type SelectedItem = {
+    type: "question";
+    sectionId: string;
+    questionId: string;
+} | {
+    type: "section";
+    sectionId: string;
+};
+type DragItem = {
+    type: "palette-item";
+    questionType: QuestionType;
+} | {
+    type: "question";
+    sectionId: string;
+    questionId: string;
+    questionIndex: number;
+} | {
+    type: "section";
+    sectionId: string;
+    sectionIndex: number;
+};
+type DropTarget = {
+    type: "section";
+    sectionId: string;
+    index: number;
+} | {
+    type: "canvas";
+    index: number;
+};
+type QuestionTypeCategory = "text" | "numeric" | "selection" | "datetime" | "media" | "advanced" | "structural" | "content" | (string & {});
+type PaletteCategory = {
+    category: string;
+    label: string;
+    types: string[];
+};
+type QuestionTypeInfo = {
+    type: QuestionType;
+    label: string;
+    category: QuestionTypeCategory;
+    icon: string;
+    description: string;
+    defaultConfig?: Record<string, unknown>;
+    requiresOptions?: boolean;
+};
+type PropertyPanelTab = "basic" | "validation" | "logic" | "advanced" | "options";
+type MutationAction = {
+    type: "add-section";
+    section: Section;
+    index: number;
+} | {
+    type: "remove-section";
+    sectionId: string;
+} | {
+    type: "update-section";
+    sectionId: string;
+    updates: Partial<Section>;
+} | {
+    type: "move-section";
+    sectionId: string;
+    newIndex: number;
+} | {
+    type: "add-question";
+    sectionId: string;
+    question: Question;
+    index: number;
+} | {
+    type: "remove-question";
+    sectionId: string;
+    questionId: string;
+} | {
+    type: "update-question";
+    sectionId: string;
+    questionId: string;
+    updates: Partial<Question>;
+} | {
+    type: "move-question";
+    sectionId: string;
+    questionId: string;
+    targetSectionId: string;
+    newIndex: number;
+} | {
+    type: "duplicate-question";
+    sectionId: string;
+    questionId: string;
+} | {
+    type: "add-option";
+    sectionId: string;
+    questionId: string;
+    option: Option;
+    index: number;
+} | {
+    type: "remove-option";
+    sectionId: string;
+    questionId: string;
+    optionIndex: number;
+} | {
+    type: "update-option";
+    sectionId: string;
+    questionId: string;
+    optionIndex: number;
+    updates: Partial<Option>;
+};
+
+declare function useBuilderTheme(): FormBuilderTheme;
+type FormBuilderThemeProviderProps = {
+    theme?: FormBuilderTheme;
+    children: ReactNode;
+};
+declare function FormBuilderThemeProvider({ theme, children }: FormBuilderThemeProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * SquaredR Dark theme preset.
+ * Matches squaredr.tech Ink + Cyan design system.
+ */
+declare const squaredrDarkPreset: FormBuilderTheme;
+/**
+ * Clean light theme preset (default).
+ * Neutral colors that fit most apps.
+ */
+declare const cleanPreset: FormBuilderTheme;
+
+/**
+ * Metadata for all question types available in the Pro palette.
+ * Icons are lucide-react component names (imported dynamically via ICON_MAP).
+ *
+ * 28 field types — general-purpose form building.
+ * Telehealth-specific fields (15) are in @squaredr/fieldcraft-pro-telehealth.
+ */
+declare const QUESTION_TYPE_INFO: Record<string, QuestionTypeInfo>;
+/**
+ * Default palette layout with categories (28 Pro field types).
+ * Telehealth fields can be appended via FormBuilder's `palette` prop.
+ */
+declare const DEFAULT_PALETTE: ({
+    category: "text";
+    label: string;
+    types: string[];
+} | {
+    category: "numeric";
+    label: string;
+    types: string[];
+} | {
+    category: "selection";
+    label: string;
+    types: string[];
+} | {
+    category: "datetime";
+    label: string;
+    types: string[];
+} | {
+    category: "media";
+    label: string;
+    types: string[];
+} | {
+    category: "content";
+    label: string;
+    types: string[];
+} | {
+    category: "structural";
+    label: string;
+    types: string[];
+} | {
+    category: "advanced";
+    label: string;
+    types: string[];
+})[];
+
+/**
+ * Generate unique IDs for sections, questions, and options.
+ * Format: {prefix}_{timestamp}_{random}
+ */
+declare function generateId(prefix: string): string;
+declare function generateSectionId(): string;
+declare function generateQuestionId(): string;
+declare function generateOptionId(): string;
+
+/**
+ * Pure functions for mutating FormEngineSchema.
+ * All functions return a new schema object (immutable updates).
+ */
+
+declare function addSection(schema: FormEngineSchema, section: Section, index: number): FormEngineSchema;
+declare function removeSection(schema: FormEngineSchema, sectionId: string): FormEngineSchema;
+declare function updateSection(schema: FormEngineSchema, sectionId: string, updates: Partial<Section>): FormEngineSchema;
+declare function moveSection(schema: FormEngineSchema, sectionId: string, newIndex: number): FormEngineSchema;
+declare function duplicateSection(schema: FormEngineSchema, sectionId: string): FormEngineSchema;
+declare function addQuestion(schema: FormEngineSchema, sectionId: string, question: Question, index: number): FormEngineSchema;
+declare function removeQuestion(schema: FormEngineSchema, sectionId: string, questionId: string): FormEngineSchema;
+declare function updateQuestion(schema: FormEngineSchema, sectionId: string, questionId: string, updates: Partial<Question>): FormEngineSchema;
+declare function moveQuestion(schema: FormEngineSchema, sectionId: string, questionId: string, targetSectionId: string, newIndex: number): FormEngineSchema;
+declare function duplicateQuestion(schema: FormEngineSchema, sectionId: string, questionId: string): FormEngineSchema;
+declare function addOption(schema: FormEngineSchema, sectionId: string, questionId: string, option: Option, index: number): FormEngineSchema;
+declare function removeOption(schema: FormEngineSchema, sectionId: string, questionId: string, optionIndex: number): FormEngineSchema;
+declare function updateOption(schema: FormEngineSchema, sectionId: string, questionId: string, optionIndex: number, updates: Partial<Option>): FormEngineSchema;
+declare function moveOption(schema: FormEngineSchema, sectionId: string, questionId: string, oldIndex: number, newIndex: number): FormEngineSchema;
+declare function findQuestion(schema: FormEngineSchema, sectionId: string, questionId: string): {
+    section: Section;
+    question: Question;
+    questionIndex: number;
+} | null;
+declare function findSection(schema: FormEngineSchema, sectionId: string): {
+    section: Section;
+    sectionIndex: number;
+} | null;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * Master state hook for the FormBuilder.
+ * Combines schema state, selection, and undo/redo.
+ *
+ * All mutation callbacks use a ref to read the latest schema,
+ * avoiding stale closures when multiple mutations fire in the
+ * same render tick.
+ */
+declare function useBuilderState(initialSchema: FormEngineSchema): {
+    schema: FormEngineSchema;
+    selectedItem: SelectedItem | null;
+    isDirty: boolean;
+    updateSchema: (newSchema: FormEngineSchema) => void;
+    addSection: (section: Section, index: number) => void;
+    removeSection: (sectionId: string) => void;
+    updateSection: (sectionId: string, updates: Partial<Section>) => void;
+    moveSection: (sectionId: string, newIndex: number) => void;
+    duplicateSection: (sectionId: string) => void;
+    addQuestion: (sectionId: string, question: Question, index: number) => void;
+    removeQuestion: (sectionId: string, questionId: string) => void;
+    updateQuestion: (sectionId: string, questionId: string, updates: Partial<Question>) => void;
+    moveQuestion: (sectionId: string, questionId: string, targetSectionId: string, newIndex: number) => void;
+    duplicateQuestion: (sectionId: string, questionId: string) => void;
+    selectQuestion: (sectionId: string, questionId: string) => void;
+    selectSection: (sectionId: string) => void;
+    clearSelection: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    undo: () => void;
+    redo: () => void;
+    resetSchema: (newSchema: FormEngineSchema) => void;
+    markClean: () => void;
+};
+type BuilderStateHook = ReturnType<typeof useBuilderState>;
+
+type UndoRedoState = {
+    canUndo: boolean;
+    canRedo: boolean;
+    undo: () => void;
+    redo: () => void;
+    push: (schema: FormEngineSchema) => void;
+    clear: () => void;
+};
+/**
+ * Hook for undo/redo functionality.
+ * Maintains a history stack of schemas with max 50 entries.
+ * Uses state for the index so canUndo/canRedo trigger re-renders.
+ * The history array is kept in a ref since its identity doesn't
+ * need to cause re-renders — only the index matters.
+ */
+declare function useUndoRedo(currentSchema: FormEngineSchema, setSchema: (schema: FormEngineSchema) => void): UndoRedoState;
+
+/**
+ * Hook to wire up @dnd-kit drag-and-drop.
+ * Returns DndContext props and handlers.
+ */
+declare function useDragDrop(builderState: BuilderStateHook): {
+    sensors: _dnd_kit_core.SensorDescriptor<_dnd_kit_core.SensorOptions>[];
+    handleDragStart: (event: DragStartEvent) => void;
+    handleDragEnd: (event: DragEndEvent) => void;
+    handleDragCancel: () => void;
+    activeDragItem: DragItem | null;
+};
+
+/**
+ * Default empty schema for new forms.
+ * Contains one section with one question to get started.
+ */
+declare const DEFAULT_SCHEMA: FormEngineSchema;
+
+export { type BuilderState, type BuilderStateHook, DEFAULT_PALETTE, DEFAULT_SCHEMA, type DragItem, type DropTarget, FormBuilder, type FormBuilderProps, type FormBuilderTheme, FormBuilderThemeProvider, type MutationAction, type PaletteCategory, type PropertyPanelTab, QUESTION_TYPE_INFO, type QuestionTypeCategory, type QuestionTypeInfo, type SelectedItem, type UndoRedoState, addOption, addQuestion, addSection, cleanPreset, cn, duplicateQuestion, duplicateSection, findQuestion, findSection, generateId, generateOptionId, generateQuestionId, generateSectionId, moveOption, moveQuestion, moveSection, removeOption, removeQuestion, removeSection, squaredrDarkPreset, updateOption, updateQuestion, updateSection, useBuilderState, useBuilderTheme, useDragDrop, useUndoRedo };