admin

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

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

type Card struct {
	// Key names the card: a lowercase slug, unique among Cards.
	Key string

	// Title is the card's heading.
	Title string

	// Build draws the card body with the caller's own context. A panic or
	// an error draws a generic message in the card and logs.
	Build func(r *http.Request) (component.Component, error)

	// Poll, when positive, redraws the card on that interval (at least
	// five seconds; the runtime clamps shorter ones). Zero draws it once.
	Poll time.Duration
}

type Config struct {
	// PathPrefix is the URL prefix every admin page and route mounts
	// under. Defaults to "/admin".
	PathPrefix string

	// Title is the product name in the sidebar and the page titles.
	// Defaults to the localized "Admin".
	Title string

	// Logo is an image URL drawn beside Title in the sidebar. Empty draws
	// Title's initial.
	Logo string

	// UI is the app's entity screens (App.EntityUI). Required when the
	// admin exposes any entity: the admin draws its lists and records
	// with it and points their writes at its own gated routes. The admin
	// reads every name it uses from the entities' Display config.
	UI *entityui.UI

	// Entities lists the entity names the admin exposes, under
	// <PathPrefix>/entities/<name>. Empty (the default) exposes none:
	// an admin dropped into an app names what it manages. Set AllEntities
	// for every entity with CRUD on. Naming an entity also exposes one
	// with CRUD off.
	Entities []string

	// AllEntities exposes every registered entity whose CRUD is on.
	// CRUD-off entities (battery/auth's users and sessions) stay hidden,
	// so it never exposes credential tables. Ignored when Entities is set.
	AllEntities bool

	// Themes are the page themes the account page's Appearance card
	// offers as its Look, a ui.ThemePicker beside the light and dark
	// toggle: each a theme registered with style.RegisterThemeOverride
	// (theme.Brutal is one). Empty offers the toggle alone.
	Themes []ui.ThemeChoice

	// Queue is the job queue the Jobs page and the dashboard's failed
	// jobs card read. Nil leaves both out.
	Queue queue.Browsable

	// DB holds the audit log the Audit log page and the dashboard's
	// recent activity read, and the ops pages write. Defaults to the app's
	// DB. Entity reads and writes always go through the app's own CRUD
	// handlers.
	DB *sql.DB

	// AuditTable is the audit log table. Defaults to "audit_log".
	AuditTable string

	// QueueListLimit is the Jobs page's rows per page; a pager under the
	// table reaches older jobs. Default 50.
	QueueListLimit int

	// AuditListLimit is the Audit log page's rows per page; a pager
	// under the table reaches older rows. Default 50.
	AuditListLimit int

	// SavedViews turns on per-user saved views over the admin's
	// database (Config.DB or the app's): one named filter/columns set
	// per user per entity, kept apart by owner and tenant. The store is
	// SavedViews(); the UI wiring is the host's (UI.WithSavedViews).
	SavedViews bool

	// SavedViewsTable is the saved views table. Defaults to
	// "admin_saved_views". Must be a lowercase identifier
	// ([a-z_][a-z0-9_]*).
	SavedViewsTable string

	// BulkJobs runs bulk actions over more records than one request may
	// touch, on a battery/queue backend. Build it with NewBulkJobs and
	// pass the same value to app.EntityUI's Extensions.Jobs; Init binds
	// it to Config.UI and hands back any job a crash left unenqueued.
	BulkJobs *BulkJobs

	// Authorize replaces the role check: it returns true to admit the
	// request. The embed refusal and a Decider's deny still run first.
	// Nil requires an authenticated user whose GetRoles() holds AdminRole.
	Authorize func(ctx context.Context) bool

	// AdminRole is the role the default check requires. Defaults to
	// "admin". Ignored when Authorize is set.
	AdminRole string

	// LoginPath, when set, sends a signed-out page request to
	// LoginPath?next=<path> instead of a 401. A signed-in caller without
	// the role still gets 403.
	LoginPath string

	// SignOutPath is where the account menu's Sign out posts. Defaults to
	// Auth's logout route when Auth is set; with neither, the menu has no
	// Sign out.
	SignOutPath string

	// Policy is the role policy the Roles page manages and the tier
	// checks read. With GrantStore the page grants and revokes.
	Policy *access.RolePolicy

	// GrantStore persists role grants. With Policy, Grant and Revoke
	// write both the live policy and the database. Wire it with
	// framework.NewGrantStore(db, policy), EnsureSchema and LoadInto.
	GrantStore *access.GrantStore

	// Auth backs the User roles page: its UserStore lists users and
	// updates their roles (EntityUserStore does both).
	Auth *auth.AuthManager

	// EffectiveRoles adds resolved roles to the User roles page. Direct
	// roles always show as "direct"; these are unioned with them and
	// labeled by their origin.
	EffectiveRoles func(ctx context.Context, userID string) []access.RoleWithOrigin

	// ProcessModules is the process-module supervisor the Modules page
	// manages (app.ProcessModules()). Nil leaves the page out.
	ProcessModules processModuleController

	// Pages are the app's own admin pages, drawn in the shell with
	// breadcrumbs and a palette entry.
	Pages []Page

	// Cards are the app's own dashboard cards.
	Cards []Card

	// Metrics are the figures in the strip at the top of the dashboard,
	// in order: counts and sums over exposed entities. The strip holds
	// six; with a Queue, the sixth is its Failed jobs figure.
	Metrics []Metric

	// Attention are the list views the dashboard's Needs attention panel
	// previews, beside the recent activity.
	Attention []Watch

	// DashboardNew names an exposed entity whose New button heads the
	// dashboard, the page's primary action ("New customer"). Empty draws
	// none; the entity cards keep their own New either way.
	DashboardNew string

	// Links are extra sidebar links, each in a nav group.
	Links []Link

	// Commands are extra palette entries that go to a URL.
	Commands []ui.PaletteCommand

	// Logger receives what a handler cannot tell its caller, notably an
	// audit row that failed to write after its mutation committed.
	// Defaults to slog.Default().
	Logger *slog.Logger
}

type Link struct {
	// Group is the nav group key; "" is the default group.
	Group string
	Label string
	// Href is a same-origin path.
	Href string
	// Icon is a registered kit icon name, or "".
	Icon string
}

type Metric struct {
	// Label names the figure.
	Label string

	// Entity is an exposed entity's name. A Detail's defaults to its
	// parent's.
	Entity string

	// Agg is "count" (or "") or "sum".
	Agg string

	// Field is the Int, Float or Decimal field a sum totals.
	Field string

	// Where narrows the rows, in the list's query DSL:
	// `status = "active"`. Empty takes every row.
	Where string

	// Format "money" prints a sum as currency.
	Format string

	// View is a key of the entity's Display.Views: the figure links to
	// that list view. Empty links to the whole list.
	View string

	// Icon is a registered kit icon name, or "".
	Icon string

	// Detail is a second, smaller figure under the value, its Label after
	// the number: "$1,240.00 outstanding" beside a count of past-due
	// invoices. A Detail takes no View, Icon or Detail of its own.
	Detail *Metric

	// Tone colours a Detail's line: ui.TrendUp good news, ui.TrendDown
	// bad, empty or ui.TrendFlat muted. Only a Detail takes one.
	Tone ui.TrendDirection
}

type Page struct {
	// Path is the page's path under the admin, e.g. "/reports". It may
	// not take one of the admin's own paths.
	Path string

	// Title is the page title, its crumb and its nav and palette label.
	Title string

	// Nav places the page in the sidebar (Group, Order, Icon). Nil, or
	// Hide, leaves it out of the sidebar; the palette still lists it.
	Nav *entity.EntityNav

	// Access narrows who sees the page beyond the admin gate. Nil admits
	// every admin. A refused caller gets 403 and no nav entry. Like Build,
	// it runs with the caller's own context, never the admin's elevation.
	Access func(ctx context.Context) bool

	// Build draws the page body. It runs with the caller's own context:
	// the admin's elevation never reaches app code. A panic or an error
	// fails the page with a generic message and a log line.
	Build func(r *http.Request) (component.Component, error)
}

type PrincipalFunc func(ctx context.Context, userID, tenant string) (context.Context, error)

type Watch struct {
	// Entity is an exposed entity's name.
	Entity string

	// View is a key of the entity's Display.Views: its Where picks the
	// rows and its Sort orders them.
	View string

	// Columns replaces the entity's list columns in the preview; empty
	// keeps them.
	Columns []string

	// Rows is how many rows the preview shows: 5 when zero, at most 20.
	Rows int
}