contributor

type AuthPageContributor interface {
	DashboardContributor

	// RenderAuthPage renders an authentication page by type (e.g. "login", "register").
	RenderAuthPage(ctx context.Context, pageType string, params Params) (templ.Component, error)

	// HandleAuthAction handles form submissions for authentication pages.
	// Returns a redirect URL on success, or a templ component to re-render on failure.
	HandleAuthAction(ctx context.Context, pageType string, params Params) (redirectURL string, component templ.Component, err error)
}

type AuthPageDef struct {
	Type     string `json:"type"`     // "login", "logout", "register", "forgot-password", etc.
	Path     string `json:"path"`     // relative path under auth base (e.g. "/login")
	Title    string `json:"title"`    // page title
	Icon     string `json:"icon"`     // optional icon name
	Priority int    `json:"priority"` // sort order
}

type ContextPreparer interface {
	PrepareContext(ctx context.Context, route string) context.Context
}

type ContributorRegistry struct {
	// contains filtered or unexported fields
}

type DashboardContributor interface {
	// Manifest returns the contributor's manifest describing its pages, widgets, settings, etc.
	Manifest() *Manifest
}

type DashboardIconProvider interface {
	Icon() templ.Component
}

type EmbeddedContributor struct {
	// contains filtered or unexported fields
}

type EmbeddedOption func(*EmbeddedContributor)

type ExtensionEntry struct {
	Name          string          // contributor name
	DisplayName   string          // display name
	Icon          string          // lucide icon name
	ExtensionIcon string          // custom icon/logo URL (overrides Icon)
	IconComponent templ.Component // custom icon component (highest priority, from DashboardIconProvider)
	BasePath      string          // entry point URL for this extension
}

type LocalContributor interface {
	DashboardContributor

	// RenderPage renders a page for the given route.
	RenderPage(ctx context.Context, route string, params Params) (templ.Component, error)

	// RenderWidget renders a specific widget by ID.
	RenderWidget(ctx context.Context, widgetID string) (templ.Component, error)

	// RenderSettings renders a settings panel for the given setting ID.
	RenderSettings(ctx context.Context, settingID string) (templ.Component, error)
}

type Manifest struct {
	// IconComponent is a custom templ.Component icon provided by DashboardIconProvider.
	// Takes priority over Icon and ExtensionIcon when rendering in the app grid,
	// sidebar header, and topbar branding.
	IconComponent templ.Component `json:"-"`

	Name            string               `json:"name"`
	DisplayName     string               `json:"display_name"`
	Icon            string               `json:"icon"`
	Version         string               `json:"version"`
	Layout          string               `json:"layout,omitempty"`       // "dashboard", "settings", "base", "full", "extension" — default "dashboard"
	Root            bool                 `json:"root,omitempty"`         // true = nav paths resolve at dashboard root (e.g. /health), not /ext/{name}/pages/...
	ShowSidebar     *bool                `json:"show_sidebar,omitempty"` // extension layout only: show sidebar with extension nav items (default: false)
	Nav             []NavItem            `json:"nav"`
	Widgets         []WidgetDescriptor   `json:"widgets"`
	Settings        []SettingsDescriptor `json:"settings"`
	SearchProviders []SearchProviderDef  `json:"search_providers,omitempty"`
	Notifications   []NotificationDef    `json:"notifications,omitempty"`
	Capabilities    []string             `json:"capabilities,omitempty"`
	AuthPages       []AuthPageDef        `json:"auth_pages,omitempty"`
	TopbarConfig    *TopbarConfig        `json:"topbar_config,omitempty"`  // per-extension topbar customization (extension layout only)
	ExtensionIcon   string               `json:"extension_icon,omitempty"` // icon/logo URL for the app grid navigator

	// SidebarHeaderContent is custom content rendered in the extension sidebar
	// header below the branding. Used for app switchers, status indicators, etc.
	SidebarHeaderContent templ.Component `json:"-"`

	// SidebarFooterContent is custom content rendered in the extension sidebar
	// footer above the user dropdown. Used for links like API Docs, support, etc.
	SidebarFooterContent templ.Component `json:"-"`

	// TopbarExtraContent is custom content rendered in the extension topbar
	// after the search trigger. Used for environment switchers, context indicators, etc.
	TopbarExtraContent templ.Component `json:"-"`
}

type NavGroup struct {
	Name     string // "Platform", "Identity", etc.
	Icon     string
	Items    []ResolvedNav // merged + sorted by priority
	Priority int
}

type NavItem struct {
	Label    string    `json:"label"`
	Path     string    `json:"path"`
	Icon     string    `json:"icon"`
	Badge    string    `json:"badge,omitempty"`
	Group    string    `json:"group,omitempty"`
	Children []NavItem `json:"children,omitempty"`
	Priority int       `json:"priority,omitempty"`
	Access   string    `json:"access,omitempty"` // "public", "protected", "partial" (empty = dashboard default)
}

type NotifiableContributor interface {
	DashboardContributor

	// Notifications returns a channel that emits notifications.
	// The channel should be closed when the context is cancelled.
	Notifications(ctx context.Context) (<-chan Notification, error)
}

type Notification struct {
	ID       string `json:"id"`
	Source   string `json:"source"`
	Message  string `json:"message"`
	Severity string `json:"severity"`
	URL      string `json:"url,omitempty"`
	Time     int64  `json:"time"` // unix timestamp
}

type NotificationDef struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Severity string `json:"severity"` // "info", "warning", "error", "critical"
}

type Params struct {
	Route       string
	BasePath    string
	PathParams  map[string]string
	QueryParams map[string]string
	FormData    map[string]string
}

type RemoteContributor struct {
	// contains filtered or unexported fields
}

type RemoteContributorOption func(*RemoteContributor)

type ResolvedNav struct {
	NavItem

	Contributor string        // contributor name (e.g., "authsome", "nexus")
	FullPath    string        // resolved path (e.g., "/dashboard/ext/authsome/pages/users")
	Children    []ResolvedNav // resolved child nav items (from NavItem.Children)
}

type ResolvedSetting struct {
	SettingsDescriptor

	Contributor string
}

type ResolvedWidget struct {
	WidgetDescriptor

	Contributor string
}

type SSRContributor struct {
	// contains filtered or unexported fields
}

type SSROption func(*SSRContributor)

type SearchProviderDef struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Prefix      string   `json:"prefix,omitempty"`       // e.g., "user:" filters to this provider
	ResultTypes []string `json:"result_types,omitempty"` // "page", "entity", "action"
}

type SearchResult struct {
	Title       string  `json:"title"`
	Description string  `json:"description"`
	URL         string  `json:"url"`
	Icon        string  `json:"icon"`
	Source      string  `json:"source"` // contributor name
	Category    string  `json:"category"`
	Score       float64 `json:"score"`
}

type SearchableContributor interface {
	DashboardContributor

	// Search performs a search query and returns matching results.
	Search(ctx context.Context, query string, limit int) ([]SearchResult, error)
}

type SettingsDescriptor struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	Description string `json:"description"`
	Group       string `json:"group"`
	Icon        string `json:"icon"`
	Priority    int    `json:"priority"`
}

type TopbarAction struct {
	// Label is the button text (hidden on small screens if Icon is set).
	Label string `json:"label"`

	// Icon is the lucide icon name for the action button.
	Icon string `json:"icon,omitempty"`

	// Href is the navigation target. Can be a full URL or a dashboard path.
	Href string `json:"href"`

	// Tooltip is shown on hover.
	Tooltip string `json:"tooltip,omitempty"`

	// Variant controls button styling: "default", "outline", "ghost".
	Variant string `json:"variant,omitempty"`
}

type TopbarConfig struct {
	// Title shown in the topbar (overrides extension DisplayName).
	Title string `json:"title,omitempty"`

	// LogoURL is the URL for the extension logo shown in the topbar.
	LogoURL string `json:"logo_url,omitempty"`

	// LogoIcon is a lucide icon name to use as the logo when LogoURL is empty.
	LogoIcon string `json:"logo_icon,omitempty"`

	// AccentColor is a CSS color value for the topbar accent (e.g. brand color).
	AccentColor string `json:"accent_color,omitempty"`

	// Actions are custom action buttons shown in the topbar (right side).
	Actions []TopbarAction `json:"actions,omitempty"`

	// ShowSearch controls whether the search trigger appears in this extension's topbar.
	ShowSearch bool `json:"show_search,omitempty"`

	// ShowThemeToggle controls whether the theme toggle appears. Default: true.
	ShowThemeToggle *bool `json:"show_theme_toggle,omitempty"`

	// ShowUserMenu controls whether the user menu appears. Default: true.
	ShowUserMenu *bool `json:"show_user_menu,omitempty"`
}

type WidgetDescriptor struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	Description string `json:"description"`
	Size        string `json:"size"`        // "sm", "md", "lg"
	RefreshSec  int    `json:"refresh_sec"` // 0 = static
	Group       string `json:"group"`
	Priority    int    `json:"priority"`
}