content: [
  // ... your existing paths
  "./node_modules/hazo_collab_forms/**/*.{js,ts,jsx,tsx}",
],

'use client';

import { HazoCollabFormInputbox } from 'hazo_collab_forms';
import { useState } from 'react';

export default function MyForm() {
  const [value, setValue] = useState('');

  return (
    <HazoCollabFormInputbox
      label="Your Name"
      value={value}
      onChange={setValue}
      field_data_id="user-name"
      field_name="User Name"
      hazo_chat_receiver_user_id="recipient-user-id"
    />
  );
}

'use client';

import { HazoCollabFormView, FileManagerConfig, FileManagerCallbacks, FileUploadOptions, FormFileAttachment } from 'hazo_collab_forms';
import { useState } from 'react';

export default function DocumentUpload() {
  // Define file management callbacks
  const fileCallbacks: FileManagerCallbacks = {
    upload: async (file: File, options: FileUploadOptions) => {
      const formData = new FormData();
      formData.append('file', file);
      formData.append('field_id', options.field_id);
      formData.append('visibility', options.visibility);

      const response = await fetch('/api/files/upload', {
        method: 'POST',
        body: formData,
      });

      const data = await response.json();
      return {
        file_id: data.file_id,
        ref_id: options.field_id,
        file_name: file.name,
        file_size: file.size,
        mime_type: file.type,
        visibility: options.visibility,
        attached_at: new Date(),
      };
    },

    remove: async (file_id: string, field_id: string) => {
      await fetch(`/api/files/${file_id}`, { method: 'DELETE' });
    },

    get_download_url: (file_id: string, field_id: string) => {
      return `/api/files/${file_id}/download`;
    },

    // Optional: File status polling
    get_status: async (file_ids: string[]) => {
      const response = await fetch(`/api/files/status?ids=${file_ids.join(',')}`);
      const data = await response.json();
      return data.statuses; // Record<file_id, FileStatus>
    },

    // Optional: Reupload functionality
    reupload: async (file_id: string, file: File, options: FileUploadOptions) => {
      // Similar to upload, but replaces existing file
      const formData = new FormData();
      formData.append('file', file);
      formData.append('file_id', file_id);

      const response = await fetch(`/api/files/${file_id}/reupload`, {
        method: 'PUT',
        body: formData,
      });

      const data = await response.json();
      return {
        file_id: data.file_id,
        ref_id: options.field_id,
        file_name: file.name,
        file_size: file.size,
        mime_type: file.type,
        visibility: options.visibility,
        attached_at: new Date(),
      };
    },
  };

  const fileManager: FileManagerConfig = {
    callbacks: fileCallbacks,
    show_file_status: true,      // Show status badges (active, orphaned, etc.)
    allow_reupload: true,         // Enable reupload button
    status_poll_interval: 10000,  // Poll status every 10s
  };

  return (
    <HazoCollabFormView
      mode="edit"
      sections={sections}
      form_data={formData}
      file_manager={fileManager}  // Required for file upload UI to appear
    />
  );
}

'use client';

import { HazoCollabFormView, FileData } from 'hazo_collab_forms';
import { useState, useEffect } from 'react';

interface FormData {
  [key: string]: unknown;
}

export default function CollaborativeForm({ formId }: { formId: string }) {
  const [formData, setFormData] = useState<FormData>({});

  // Load form data including files from your backend
  useEffect(() => {
    async function loadForm() {
      const response = await fetch(`/api/forms/${formId}`);
      const data = await response.json();
      // data should include __files_* keys with FileData arrays
      // Example: { field_name: "value", __files_document_field: [{ file_id: "...", file_name: "..." }] }
      setFormData(data);
    }
    loadForm();
  }, [formId]);

  // Handle file changes - save to your backend
  const handleFilesChange = async (field_id: string, files: FileData[]) => {
    // Update local state
    setFormData(prev => ({
      ...prev,
      [`__files_${field_id}`]: files
    }));

    // Persist to your backend
    await fetch(`/api/forms/${formId}/files`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ field_id, files })
    });
  };

  // Handle private file changes (if using file visibility feature)
  const handlePrivateFilesChange = async (field_id: string, files: FileData[]) => {
    setFormData(prev => ({
      ...prev,
      [`__private_files_${field_id}`]: files
    }));

    await fetch(`/api/forms/${formId}/private-files`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ field_id, files })
    });
  };

  return (
    <HazoCollabFormView
      mode="edit"
      sections={sections}
      form_data={formData}
      on_form_data_change={setFormData}
      on_field_files_change={handleFilesChange}
      on_field_private_files_change={handlePrivateFilesChange}
    />
  );
}

// New callback-based attachment format
interface FormFileAttachment {
  file_id: string;         // Unique identifier
  ref_id: string;          // Field ID reference
  file_name: string;       // Display name
  file_size: number;       // Size in bytes
  mime_type: string;       // MIME type (e.g., 'application/pdf')
  visibility: 'public' | 'private';
  attached_at: Date;       // Attachment timestamp
}

// File status for status badges
type FileStatus = 'active' | 'orphaned' | 'soft_deleted' | 'missing';

// Legacy format (still supported for backward compatibility)
interface FileData {
  file_path: string;      // Server path for download
  file_name: string;      // Display name
  file_size: number;      // Size in bytes
  file_type: string;      // MIME type
  file_id: string;        // Unique identifier
  uploaded_at: Date;      // Upload timestamp
  visibility?: 'public' | 'private';
}

import {
  attachment_to_file_data,
  file_data_to_attachment,
  is_form_file_attachment
} from 'hazo_collab_forms';

// Convert new format to legacy
const legacy = attachment_to_file_data(attachment);

// Convert legacy to new format
const attachment = file_data_to_attachment(fileData, 'field_id');

// Type guard
if (is_form_file_attachment(item)) {
  // item is FormFileAttachment
}

// app/api/forms/[formId]/files/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(
  request: NextRequest,
  { params }: { params: { formId: string } }
) {
  const { field_id, files } = await request.json();

  // Save to your database
  // Example with Prisma:
  // await prisma.formData.upsert({
  //   where: { formId_fieldId: { formId: params.formId, fieldId: `__files_${field_id}` } },
  //   update: { value: JSON.stringify(files) },
  //   create: { formId: params.formId, fieldId: `__files_${field_id}`, value: JSON.stringify(files) }
  // });

  return NextResponse.json({ success: true });
}

// icons_behaviour.json
{
  "roles": [
    {
      "role_id": "tax_agent",
      "controls": {
        "control_private_files": { "visible": true, "enabled": true },  // Can see private files
        // ... other controls
      }
    },
    {
      "role_id": "client",
      "controls": {
        "control_private_files": { "visible": false, "enabled": false }, // Cannot see private files
        // ... other controls
      }
    }
  ]
}

// In your component
<HazoCollabFormView
  mode="edit"
  sections={sections}
  form_data={formData}
  icons_behaviour={iconsBehaviour}
  active_role="tax_agent"  // Will have access to private files
/>

'use client';

import {
  HazoCollabFormInputbox,
  CollabFormVisibilityIcon,
  CollabFormLockIcon,
  CollabFormAddEntryIcon,
  CollabFormDeleteEntryIcon,
  CollabFormDeleteFieldIcon,
} from 'hazo_collab_forms';
import { useState } from 'react';

export default function AdvancedForm() {
  const [value, setValue] = useState('');
  const [visibility, setVisibility] = useState<'visible' | 'hidden'>('visible');
  const [locked, setLocked] = useState(false);

  return (
    <div>
      {/* Visibility Toggle */}
      <CollabFormVisibilityIcon
        label="Company Name"
        visibility={visibility}
        on_visibility_change={setVisibility}
      />

      {/* Lock/Unlock Field */}
      <CollabFormLockIcon
        label="Company Name"
        locked={locked}
        on_lock_change={setLocked}
      />

      {/* Add Entry - duplicate field */}
      <CollabFormAddEntryIcon
        label="Contact Person"
        field_id="contact_person"
        on_add_entry={(field_id) => console.log('Add entry:', field_id)}
      />

      {/* Delete Entry - remove duplicated field */}
      <CollabFormDeleteEntryIcon
        label="Contact Person"
        field_id="contact_person_2"
        on_delete_entry={(field_id) => console.log('Delete entry:', field_id)}
      />

      {/* Delete Field - soft delete */}
      <CollabFormDeleteFieldIcon
        label="Optional Field"
        field_id="optional_field"
        on_delete={(field_id) => console.log('Delete field:', field_id)}
      />
    </div>
  );
}

'use client';

import { HazoCollabFormView, type FieldConfig } from 'hazo_collab_forms';

const fields: FieldConfig[] = [
  {
    id: "customer_name",
    label: "Customer Name",
    field_type: "field",
    component_type: "HazoCollabFormInputbox",
    value: "",
    // Uses form-level defaults
  },
  {
    id: "tax_file_number",
    label: "Tax File Number",
    field_type: "field",
    component_type: "HazoCollabFormInputbox",
    value: "",
    enable_lock: true,
    enable_visibility_toggle: true,  // Field-level override
    enable_delete: false
  },
  {
    id: "internal_notes",
    label: "Internal Notes",
    field_type: "field",
    component_type: "HazoCollabFormTextArea",
    value: "",
    enable_lock: false,              // Hide lock on this field
    enable_visibility_toggle: true,
    enable_delete: true              // Show delete on this field
  }
];

export default function CustomerForm() {
  return (
    <HazoCollabFormView
      mode="edit"
      sections={[{ section_name: "Customer Form", groups: fields }]}
      form_data={{}}
      enable_lock={true}              // Default for all fields
      enable_visibility_toggle={false} // Default for all fields
      enable_delete={false}            // Default for all fields
    />
  );
}

const fields: FieldConfig[] = [
  {
    id: "tax_details",
    label: "Tax Information",
    field_type: "group",
    // These propagate to all children
    enable_lock: true,
    enable_visibility_toggle: true,
    enable_notes: true,
    enable_chat: true,
    sub_fields: [
      // Inherits all enable_* from parent
      { id: "tfn", label: "Tax File Number", component_type: "HazoCollabFormInputbox", value: "" },
      // Override: explicitly disable lock and chat
      { id: "abn", label: "ABN", component_type: "HazoCollabFormInputbox", value: "", enable_lock: false, enable_chat: false },
    ]
  }
];

import { resolve_field_controls } from 'hazo_collab_forms';

// Resolve effective controls for a field considering inheritance
const resolved = resolve_field_controls(field, parent_group, form_settings);
// Returns: { enable_lock, enable_visibility_toggle, enable_delete, enable_data_ok, enable_notes, enable_chat }

interface FieldMetadataInput {
  visibility?: 'visible' | 'hidden';  // or hidden?: boolean
  locked?: boolean;
  data_ok?: boolean | DataOkState;    // or dataOk
  deleted?: boolean;
}

interface FieldMetadataChange {
  field_id: string;
  visibility?: 'visible' | 'hidden';
  locked?: boolean;
  data_ok?: boolean | DataOkState;
  deleted?: boolean;
}

import { HazoCollabFormView } from 'hazo_collab_forms';
import type { FieldMetadataInput, FieldMetadataChange } from 'hazo_collab_forms';
import { useState } from 'react';

function MyForm({ sections }) {
  const [fieldMetadata, setFieldMetadata] = useState<Record<string, FieldMetadataInput>>({
    tax_file_number: { visibility: 'hidden', locked: true },
    name: { visibility: 'visible', locked: false },
  });

  // Unified handler - called for any metadata change
  const handleMetadataChange = (change: FieldMetadataChange) => {
    setFieldMetadata(prev => ({
      ...prev,
      [change.field_id]: { ...prev[change.field_id], ...change }
    }));
  };

  return (
    <HazoCollabFormView
      mode="edit"
      sections={sections}
      form_data={{}}
      enable_visibility_toggle={true}
      enable_lock={true}
      field_metadata={fieldMetadata}
      on_field_metadata_change={handleMetadataChange}
    />
  );
}

import { normalize_field_metadata_input } from 'hazo_collab_forms';

// Normalize input that uses alternative naming conventions
const input = { hidden: true, dataOk: 'ok', locked: true };
const normalized = normalize_field_metadata_input(input);
// Result: { visibility: 'hidden', data_ok: 'ok', locked: true }

'use client';

import { HazoCollabFormView, type ViewSection } from 'hazo_collab_forms';
import { LuUser, LuFileText } from 'react-icons/lu';

const render_icon = (iconName: string) => {
  const iconMap = { LuUser, LuFileText };
  const Icon = iconMap[iconName];
  return Icon ? <Icon className="h-5 w-5" /> : null;
};

export default function FormSummaryPage() {
  return (
    <HazoCollabFormView
      mode="summary"
      sections={sections}
      form_data={{
        name: "John Doe",
        email: "john@example.com",
        tfn: "123456789"
      }}
      render_icon={render_icon}
      show_edit_buttons={true}
      on_edit_section={(index) => router.push(`/edit/${index}`)}
    />
  );
}

<HazoCollabFormView
  mode="summary"
  sections={sections}
  form_data={formData}
  field_metadata={fieldMetadata}

  // Enable field controls - each enabled via props
  // Use *_editable props to make controls clickable
  enable_data_ok={true}
  data_ok_mode="multi_state"
  data_ok_editable={true}
  enable_notes={true}
  enable_chat={true}
  chat_group_id="review-session-123"
  chat_read_only={false}  // Set to true for view-only chat mode
  enable_visibility_toggle={true}
  visibility_editable={true}
  enable_lock={true}
  lock_editable={true}
  enable_delete={true}

  // Display settings
  controls_display="inline"
  show_edit_buttons={true}
  on_edit_section={(index) => handleEdit(index)}

  // Callbacks
  on_data_ok_change={(fieldId, value) => console.log('Data OK changed:', fieldId, value)}
  on_notes_change={(fieldId, notes) => console.log('Notes updated:', fieldId, notes)}
  on_visibility_change={(fieldId, visibility) => console.log('Visibility changed:', fieldId, visibility)}
  on_lock_change={(fieldId, locked) => console.log('Lock changed:', fieldId, locked)}

  // Auto-actions
  on_data_ok_hidden={true}    // Auto-hide when marked OK
  on_data_ok_protected={true}  // Auto-lock when marked OK
/>

// Disable automatic polling - only fetch once on mount
<HazoCollabFormView
  mode="edit"
  sections={sections}
  form_data={formData}
  enable_chat={true}
  chat_group_id="form-session-123"
  chat_realtime_mode="manual"  // No automatic polling
/>

import { use_field_chat_status } from 'hazo_collab_forms';

const { chat_status, refresh, is_loading } = use_field_chat_status({
  field_ids: ['field1', 'field2'],
  chat_group_id: 'group-id',
  enabled: true,
  realtime_mode: 'manual',  // or 'polling' (default)
  poll_interval: 5000,      // only used when realtime_mode is 'polling'
});

// chat_status: Record<string, 'none' | 'has_messages' | 'has_unread'>
// refresh(): manually trigger a status refresh

// HazoCollabFormView - customized chat experience
<HazoCollabFormView
  mode="edit"
  sections={sections}
  form_data={formData}
  enable_chat={true}
  chat_group_id={groupId}
  chat_read_only={false}
  chat_hide_references={true}     // Hide references section
  chat_hide_sidebar={false}        // Show sidebar (requires hazo_chat v5.2.0+)
  chat_hide_preview={false}        // Show message previews
  chat_display_mode="side_panel"   // Render as side panel
  chat_log_polling={false}         // Disable polling logs
/>

// HazoCollabFormView - summary with view-only chat
<HazoCollabFormView
  mode="summary"
  sections={sections}
  form_data={formData}
  enable_chat={true}
  chat_group_id={groupId}
  chat_read_only={true}
/>

// Field-level override in FieldConfig
const fields: FieldConfig[] = [
  {
    id: "active_discussion",
    label: "Active Discussion",
    component_type: "HazoCollabFormInputbox",
    chat_read_only: false  // Can chat on this field
  },
  {
    id: "archived_data",
    label: "Archived Data",
    component_type: "HazoCollabFormInputbox",
    chat_read_only: true   // View-only chat
  }
];

import { HazoCollabFormInputbox } from 'hazo_collab_forms';

<HazoCollabFormInputbox
  label="Tax File Number"
  tooltip="Your 9-digit tax identification number (TFN)"
  value={tfn}
  onChange={setTfn}
/>

// Or with full TooltipConfig
<HazoCollabFormInputbox
  label="ABN"
  tooltip={{
    enabled: true,
    content: "Australian Business Number - 11 digits",
    position: "right" // optional
  }}
  value={abn}
  onChange={setAbn}
/>

const columns: DataTableColumn[] = [
  {
    id: "amount",
    label: "Amount",
    type: "number",
    tooltip: "Enter the invoice amount in AUD",
  },
  {
    id: "date",
    label: "Invoice Date",
    type: "date",
    tooltip: {
      enabled: true,
      content: "The date shown on the invoice document"
    }
  }
];

const fields: FieldConfig[] = [
  {
    id: "gst_amount",
    label: "GST Amount",
    component_type: "HazoCollabFormInputbox",
    tooltip: "10% of the invoice amount (automatically calculated if empty)",
    value: ""
  }
];

'use client';

import { HazoFieldLibrary } from 'hazo_collab_forms';

export default function FieldLibraryPage() {
  return (
    <div className="h-screen">
      <HazoFieldLibrary
        api_base_url="/api/hazo_connect/sqlite/data"
        table_name="hazo_collab_form_elts"
        scope_id="my-project"
      />
    </div>
  );
}

import { HazoFieldLibrary, type EditorTheme } from 'hazo_collab_forms';

const customTheme: Partial<EditorTheme> = {
  label_style: 'uppercase',    // 'uppercase' | 'normal'
  tab_style: 'pill',           // 'pill' | 'underline'
  header_style: 'gradient',    // 'gradient' | 'accent' | 'simple'
  label_icons: true,           // Show icons alongside labels
  max_field_width: 'lg',       // 'full' | 'lg' | 'md'
};

<HazoFieldLibrary theme={customTheme} ... />
<HazoTemplateGenerator theme={customTheme} ... />

import { EditorThemeProvider, useEditorTheme } from 'hazo_collab_forms';

function CustomEditor() {
  const theme = useEditorTheme();
  // Access theme.label_style, theme.tab_style, etc.
}

<HazoCollabFormView
  mode="edit"
  sections={[{
    groups: [{
      id: 'income_group',
      field_type: 'group',
      label: 'Income Details',
      autofill_dropzone: true,           // Enable the dropzone
      autofill_api_endpoint: '/api/autofill',
      autofill_prompt_area: 'tax',       // Optional: prompt lookup area
      autofill_prompt_key: 'income',     // Optional: prompt lookup key
      fields: [...]
    }]
  }]}
  file_manager={fileManagerConfig}  // Required for file upload
  form_data={formData}
  on_change={handleChange}
/>

{
  success: boolean;
  data: Record<string, unknown>;  // Keyed by field_id
  error?: string;                 // Error message if failed
  message?: string;               // Info message (e.g., "No matching data found")
}

'use client';

import { HazoTemplateGenerator } from 'hazo_collab_forms';
import { useState } from 'react';

export default function TemplateBuilder() {
  const [template, setTemplate] = useState({
    sections: [],
    icons_behaviour: {}
  });

  return (
    <div className="h-screen">
      <HazoTemplateGenerator
        initial_template={template}
        on_template_change={setTemplate}
        on_save={(template) => {
          console.log('Saved template:', template);
          // Save to database or file
        }}
        on_cancel={() => router.push('/templates')}
      />
    </div>
  );
}

interface TemplateOutput {
  sections: Section[];
  icons_behaviour?: IconsBehaviour;
}

'use client';

import { HazoCollabFormView, type ViewMode } from 'hazo_collab_forms';
import { useState } from 'react';

export default function UnifiedFormPage() {
  const [viewMode, setViewMode] = useState<ViewMode>('edit');
  const [formData, setFormData] = useState<Record<string, unknown>>({});

  return (
    <div>
      {/* View mode switcher */}
      <div className="flex gap-2 mb-4">
        <button onClick={() => setViewMode('edit')}>Edit</button>
        <button onClick={() => setViewMode('summary')}>Summary</button>
        <button onClick={() => setViewMode('print')}>Print</button>
        <button onClick={() => setViewMode('approval')}>Approval</button>
      </div>

      <HazoCollabFormView
        sections={sections}
        view_mode={viewMode}
        form_data={formData}
        on_form_data_change={setFormData}
        icons_behaviour={iconsBehaviour}
        active_role="tax_agent"
        enable_chat={true}
        chat_group_id="form-session-123"
      />
    </div>
  );
}

import {
  useFormViewContext,
  useViewMode,
  useFormData,
  useFieldMetadata,
  useFieldValue,
  useFieldMeta,
  useApprovalStats,
} from 'hazo_collab_forms';

function FieldComponent({ fieldId }) {
  const viewMode = useViewMode();
  const value = useFieldValue(fieldId);
  const { data_ok, locked, visibility } = useFieldMeta(fieldId);
  const { total, approved, pending } = useApprovalStats();

  // Render based on view mode and field state
}

import { HazoCollabFormView, type ReferenceData } from 'hazo_collab_forms';

const referenceData: ReferenceData = {
  salary_income: {
    value: 82450.00,                    // Formatted as $82,450.00
    label: "Prior Year (2023)",
    background_color: "bg-blue-50"      // Optional Tailwind class
  },
  has_dependents: {
    value: true,                        // Formatted as "Yes"
    label: "2023"
  },
  filing_status: {
    value: "married",                   // String pass-through
    label: "Last year"
  }
};

<HazoCollabFormView
  mode="edit"
  sections={sections}
  form_data={formData}
  reference_data={referenceData}
/>

// Load form configuration
const sectionsResponse = await fetch('/data/form-sets/tax_form_individual_full.json');
const { sections } = await sectionsResponse.json();

const behaviourResponse = await fetch('/data/form-sets/icon_behaviour.json');
const icons_behaviour = await behaviourResponse.json();

// Pass to HazoCollabFormView (edit mode)
<HazoCollabFormView
  mode="edit"
  sections={sections}
  form_data={formData}
  icons_behaviour={icons_behaviour}
  active_role="tax_agent"
/>

// Pass to HazoCollabFormView (summary mode)
<HazoCollabFormView
  mode="summary"
  sections={sections}
  form_data={formData}
  icons_behaviour={icons_behaviour}
  active_role="tax_agent"
/>

const icons_behaviour: IconsBehaviour = {
  // Data OK display mode
  data_ok_mode: 'multistate', // or 'checkbox'

  // Controls that have borders
  border_on: ['control_data_ok'],

  // Display order (left to right)
  icon_order: [
    'control_data_ok',
    'control_skip',
    'control_notes',
    'control_chat',
    'control_visibility',
    'control_lock',
    'control_delete',
    'control_edit_field',
    'control_edit_group',
    'control_delete_field',
  ],

  // Always shown individually (never in kebab)
  always_extracted: ['control_data_ok'],

  // Extracted when they have activity
  extracted_on_value: ['control_notes', 'control_chat'],

  // Role definitions
  roles: [
    {
      role_id: 'tax_agent',
      role_name: 'Tax Agent',
      role_description: 'Full access to all controls',
      controls: {
        control_data_ok: { visible: true, enabled: true },
        control_notes: { visible: true, enabled: true },
        control_chat: { visible: true, enabled: true },
        control_visibility: { visible: true, enabled: true },
        control_lock: { visible: true, enabled: true },
        control_delete: { visible: true, enabled: false },
        control_edit_field: { visible: true, enabled: true },
        control_edit_group: { visible: true, enabled: true },
        control_delete_field: { visible: true, enabled: true },
        control_private_files: { visible: true, enabled: true }  // Can see private file sections
      }
    },
    {
      role_id: 'client',
      role_name: 'Client',
      role_description: 'Limited to chat and notes',
      controls: {
        control_chat: { visible: true, enabled: true },
        control_notes: { visible: true, enabled: true },
        control_data_ok: { visible: true, enabled: false },
        control_visibility: { visible: false, enabled: false },
        control_lock: { visible: false, enabled: false },
        control_delete: { visible: false, enabled: false },
        control_edit_field: { visible: false, enabled: false },
        control_edit_group: { visible: false, enabled: false },
        control_delete_field: { visible: false, enabled: false },
        control_private_files: { visible: false, enabled: false }  // Cannot see private file sections
      }
    }
  ]
};

// Edit mode
<HazoCollabFormView
  mode="edit"
  sections={sections}
  form_data={formData}
  icons_behaviour={icons_behaviour}
  active_role="tax_agent"
/>

// Summary mode
<HazoCollabFormView
  mode="summary"
  sections={sections}
  form_data={formData}
  icons_behaviour={icons_behaviour}
  active_role="client"
/>

const fields: FieldConfig[] = [
  {
    id: "sensitive_group",
    field_type: "group",
    label: "Sensitive Information",
    // Icons show automatically from role config - no show_icons needed
    // Use overrides only to force-hide:
    // show_edit_icons: false,    // Hide edit/delete icons on this group
    // show_control_icons: false, // Hide data_ok/notes/chat/etc on this group
    sub_fields: [
      {
        id: "ssn",
        label: "Social Security Number",
        component_type: "HazoCollabFormInputbox",
        value: ""
      }
    ]
  }
];

{
  role_id: 'tax_agent',
  role_name: 'Tax Agent',
  controls: {
    control_private_files: { visible: true, enabled: true },  // Shows private file sections
    // ... other controls
  }
}

import { HazoAddFieldDialog, type NewFieldDefinition } from 'hazo_collab_forms';
import { useState } from 'react';

export default function DynamicForm() {
  const [isOpen, setIsOpen] = useState(false);

  const handleAddField = (field: NewFieldDefinition) => {
    console.log('New field:', field);
    // Add field to your form sections
  };

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Add Field</button>
      <HazoAddFieldDialog
        open={isOpen}
        on_open_change={setIsOpen}
        on_add={handleAddField}
        parent_type="group" // 'section' | 'group'
        parent_id="personal_info"
      />
    </>
  );
}

import { HazoEditFieldDialog } from 'hazo_collab_forms';

<HazoEditFieldDialog
  open={isEditOpen}
  on_open_change={setIsEditOpen}
  field={selectedField}
  on_save={(updated) => updateField(updated)}
  on_delete={() => deleteField(selectedField.id)}  // Optional delete callback
/>

import { HazoFieldSelectorDialog } from 'hazo_collab_forms';

<HazoFieldSelectorDialog
  open={isSelectorOpen}
  on_open_change={setIsSelectorOpen}
  template={formTemplate}
  on_select={(selection) => {
    // Handle selected fields
    console.log('Selected:', selection);
  }}
/>

import {
  // Field traversal
  traverse_fields,
  traverse_sections,
  collect_field_ids,
  collect_leaf_field_ids,
  should_render_field,
  is_field_empty,
  get_field_value,

  // Dependency checking
  parse_dependency,
  check_dependency,

  // Field metadata normalization
  normalize_field_metadata,
  normalize_field_metadata_input,

  // File management
  get_field_attachments,
  get_field_private_attachments,
  is_form_file_attachment,
  attachment_to_file_data,
  file_data_to_attachment,
} from 'hazo_collab_forms';

// Traverse all fields in sections
traverse_sections(sections, (field, path) => {
  console.log(`Field: ${field.id} at path: ${path.join('/')}`);
});

// Check if field should render based on dependencies
const shouldRender = should_render_field(field, formData, {
  check_dependencies: true,
  show_empty_fields: false,
});

// Parse and check field dependencies
const dependency = parse_dependency(field.depends_on);
const isActive = check_dependency(dependency, formData);

// Get file attachments for a field
const publicFiles = get_field_attachments(formData, 'document_field');
const privateFiles = get_field_private_attachments(formData, 'sensitive_field');

// Default: All client-safe components and utilities
import { HazoCollabFormInputbox, cn } from 'hazo_collab_forms';

// Components only
import { HazoCollabFormInputbox } from 'hazo_collab_forms/components';

// Utilities only
import { cn, use_collab_chat } from 'hazo_collab_forms/utils';

// Server-only (config functions)
import { get_config } from 'hazo_collab_forms/lib';

export * from './lib/index.js';
export * from './components/index.js';