enum WidgetLoadingState {
  IDLE    = 'IDLE',
  LOADING = 'LOADING',
  SUCCESS = 'SUCCESS',
  ERROR   = 'ERROR',
}

interface WidgetDefinition {
  id: string;                   // unique slug, e.g. 'grant-pipeline-summary'
  name: string;
  description: string;
  category: WidgetCategory;
  defaultSize: WidgetSize;
  supportedSizes: WidgetSize[]; // sizes the component can render at
  componentPath: string;        // path for dynamic import, e.g. 'widgets/grants/PipelineSummary'
  icon?: string;                // lucide-react icon name
  isActive: boolean;
  noFrame?: boolean;            // widget provides its own container; skip default Card wrapper
  configSchema?: WidgetConfigSchema; // Zod schema for per-instance settings
  metadata?: WidgetMetadata;
  createdAt: Timestamp;
  updatedAt: Timestamp;
}

interface WidgetAssignment {
  id: string;
  widgetId: string;
  assignedRoles: SystemRole[];
  priority: number;   // default sort order within the role's dashboard
  isActive: boolean;
  updatedAt: Timestamp;
  updatedBy: string;
}

interface WidgetOverride {
  widgetId: string;
  organizationId: string;
  isHidden?: boolean;
  displayName?: string;     // rename for this org
  priority?: number;        // reorder within this org
  updatedAt: Timestamp;
  updatedBy: string;
}

interface WidgetInstance {
  definition: WidgetDefinition;
  override?: WidgetOverride;
  currentSize: WidgetSize;
}

interface WidgetPreferences {
  hiddenWidgets: string[];               // widgetIds to hide
  widgetOrder: Array<{
    widgetId: string;
    priority: number;
  }>;
  widgetConfig?: Record<string, WidgetConfig>; // per-widget user settings
}

interface WidgetProps {
  widgetId: string;
  size: WidgetSize;
  config?: WidgetConfig;          // resolved user/org config
  onConfigChange?: (config: WidgetConfig) => void;
}

interface WidgetTemplate {
  widgetId: string;
  priority: number;       // lower = higher on dashboard
  size: WidgetSize;
  category: WidgetCategory;
  rationale?: string;     // dev-facing explanation of why this widget is included
}

interface RoleTemplate {
  role: SystemRole;
  name: string;
  description: string;
  widgets: WidgetTemplate[];
}

// Retrieve the default template for a role
getDefaultDashboardTemplate(role: SystemRole): RoleTemplate | undefined

// Convert a RoleTemplate into WidgetPreferences (for writing to user profile)
templateToWidgetPreferences(template: RoleTemplate): WidgetPreferences

const { widgets, loading, error, refresh, loadingState } = useWidgets(includeHidden?);

<DashboardTemplateEditor>
  <DashboardTemplateEditor.Header />
  <DashboardTemplateEditor.InfoCard />
  <DashboardTemplateEditor.RoleTabs />
  <DashboardTemplateEditor.TemplateCanvas />
  <DashboardTemplateEditor.Actions />
</DashboardTemplateEditor>

interface WidgetConfigSchema {
  fields: Array<{
    key: string;
    label: string;
    type: 'text' | 'number' | 'boolean' | 'select';
    defaultValue?: unknown;
    options?: Array<{ label: string; value: string }>; // for 'select'
  }>;
}