admin

type Action string

type Audit struct {

	// Retain bounds how long entries are kept. Zero keeps them forever, which
	// is a decision rather than a default: an audit trail that a cleanup job
	// truncates is not one.
	Retain time.Duration
	// contains filtered or unexported fields
}

type Authorizer interface {
	Allow(ctx Context, q Query) error
}

type AuthorizerFunc func(ctx Context, q Query) error

type BelongsTo struct {
	// Table is the table the key points at.
	Table string

	// Key is the column in that table, usually its primary key.
	Key string

	// Label is the column to show a person. An id in a dropdown is a puzzle.
	Label string
}

type BulkAction struct {
	// Name appears in the URL and must be unique within the resource.
	Name string

	// Label is the button.
	Label string

	// Confirm asks first. Use it for anything that destroys data.
	Confirm bool

	// Run receives the selected primary keys.
	//
	// Authorization has already run: the panel checks ActionUpdate on every
	// selected record before calling this, so a bulk action cannot be a way
	// around per-record permissions.
	Run func(ctx Context, ids []string) error
}

type Choice struct {
	Value string
	Label string
}

type Config struct {
	// DB is the database the resources live in.
	DB *sql.DB

	// Driver is the application's DATABASE_TYPE: "sqlite", "mysql",
	// "mariadb", "postgres". It selects both the placeholder syntax and the
	// audit table's schema.
	Driver string

	// Authorizer decides who may do what. Without one nothing is permitted.
	Authorizer Authorizer

	// Title is shown in the header. Defaults to "Admin".
	Title string

	// Actor names the person behind a request, for the audit trail. Optional;
	// without it the trail records the action and not who took it, which is
	// half a trail.
	Actor func(ctx Context) string

	// Audit records who changed what. Nil disables it.
	//
	// Enabled by default when a DB is present: an admin panel is where someone
	// eventually asks "who deleted that", and the answer has to have been
	// recorded before the question.
	Audit *Audit

	// Uploads receives files from file fields. Without it, a file field falls
	// back to a plain text input for a path.
	Uploads Uploader
}

type Content = template.HTML

type Context struct {
	context.Context

	// Request is the HTTP request behind this, for a session lookup or a
	// header. Never nil.
	Request *http.Request
}

type Entry struct {
	At       time.Time
	Actor    string
	Action   Action
	Resource string
	RecordID string

	// Changes holds only what differed, as column -> [before, after]. A create
	// records the values it set; a delete records the record as it was.
	Changes map[string]any
}

type Field struct {
	// Name is the database column.
	Name string

	// Label is what a person sees. Derived from the column unless overridden.
	Label string

	Kind FieldKind

	// PrimaryKey marks the identifying column. Never editable.
	PrimaryKey bool

	// ReadOnly shows the value but does not accept a new one.
	//
	// Enforced when the form is processed, not only when it is drawn. A
	// disabled input is a suggestion to the browser and nothing at all to
	// anything else.
	ReadOnly bool

	// Hidden keeps the column out of every screen.
	Hidden bool

	// Required rejects an empty value.
	Required bool

	// Searchable includes the column in the search box's LIKE.
	Searchable bool

	// Relation is set for a belongs-to column: the values offered are the
	// related table's rows.
	Relation *BelongsTo

	// Choices turns a column into a fixed dropdown.
	Choices []Choice
}

type FieldKind string

type FileStore struct {
	// FS is the destination.
	FS filesystems.FS

	// Folder is the prefix within it.
	Folder string

	// MaxBytes overrides MaxUploadBytes.
	MaxBytes int64

	// AllowedExtensions restricts what may be uploaded, lower case and with
	// the dot: {".png", ".jpg"}. Empty allows anything, which is a decision to
	// make deliberately -- an admin panel that accepts .html is a way to host
	// an attacker's page on your origin, and one that accepts .svg is the same
	// thing with a friendlier extension.
	AllowedExtensions []string
}

type HasMany struct {
	// Title is the heading above the list.
	Title string

	// Table holds the related rows.
	Table string

	// ForeignKey is the column in Table pointing at this record.
	ForeignKey string

	// Columns are shown, in order. Empty means the first three the table has.
	Columns []string

	// Limit caps how many are listed. Zero means DefaultHasManyLimit.
	Limit int
}

type Organization func(ctx Context) (orgID, accountID string, err error)

type Page struct {
	// Path is the URL segment, e.g. "reports".
	Path string

	// Title is the nav entry and heading.
	Title string

	// Body renders the page's content, which the panel wraps in its chrome.
	//
	// Returning HTML rather than writing to the ResponseWriter is what makes
	// the page look like the rest of the panel without every page having to
	// reproduce the layout.
	Body func(ctx Context) (Content, error)

	// Handler takes the whole request instead, for a page that streams, or
	// redirects, or is not HTML. Set one or the other; Handler wins.
	Handler http.Handler

	// Post handles a form submitted from this page and returns where to send
	// the browser next. An empty redirect returns to the page itself.
	//
	// A page without one accepts no writes at all: an internal tool that only
	// reads should not have a POST endpoint just because pages can have them.
	Post func(ctx Context) (redirect string, err error)

	// Action is the permission checked before the page is shown. Defaults to
	// ActionList.
	Action Action

	// PostAction is the permission checked before Post runs. Defaults to
	// ActionUpdate, so a page that reads with one role and writes with another
	// gets that without configuration.
	PostAction Action
}

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

type Query struct {
	Action   Action
	Resource string
	Field    string
	Record   map[string]any
}

type Resource struct {
	// Model is any value of the struct type. Its fields are reflected over;
	// it is never stored or mutated.
	Model any

	// Table is the database table.
	Table string

	// Name is the URL segment and heading. Derived from Table when empty.
	Name string

	// Singular and Plural override the headings.
	Singular string
	Plural   string

	// PrimaryKey defaults to "id".
	PrimaryKey string

	// ListColumns limits the list view. Empty shows every visible field, up to
	// MaxListColumns -- a table with forty columns is not a useful screen.
	ListColumns []string

	// DefaultSort is the column the list is ordered by. Defaults to the
	// primary key, descending.
	DefaultSort string
	DefaultDesc bool

	// PerPage defaults to DefaultPerPage.
	PerPage int

	// HasMany renders related rows on the edit screen.
	HasMany []HasMany

	// BulkActions appear on the list when rows are selected.
	BulkActions []BulkAction

	// FieldOverrides adjusts what reflection worked out. The key is the column.
	FieldOverrides map[string]Field

	// ReadOnly forbids create, update and delete for everyone, regardless of
	// what the authorizer says. For tables that are reports.
	ReadOnly bool
	// contains filtered or unexported fields
}

type Uploader interface {
	Upload(ctx Context, field string, file multipart.File, header *multipart.FileHeader) (string, error)
}

type UploaderFunc func(ctx Context, field string, file multipart.File, header *multipart.FileHeader) (string, error)