platformd

type Brand interface {
	// BrandName is shown beside the mark, and is the mark's alt text.
	BrandName() string
	// BrandMark is a URL or inline SVG data URI. Empty is normal and expected:
	// the shell falls back to its own glyph, exactly as UserAvatar does.
	BrandMark() string
}

type Identity interface {
	// UserName is who is logged in.
	UserName() string
	// UserAvatar is the URL of their picture. Empty is normal and expected.
	UserAvatar() string
	// UserRoles are display names, not authorization codes. May be empty.
	UserRoles() []string
}

type Platform struct {
	Element

	// AppName titles the drawer on a phone, where the panel opens wholesale and
	// there is room for it. The collapsed rail never shows it: text with no icon
	// beside it would have to appear from nowhere when the rail expands.
	//
	// It is NOT the header brand: AppName belongs to the phone drawer and Brand
	// belongs to the desktop header, two surfaces of which only one exists at a
	// time. A Brand does not supersede it and it is not a fallback for a missing
	// Brand — a platform without a Brand renders no header brand slot at all.
	AppName string

	// Brand is what the platform calls itself in the header's leading slot:
	// the mark and the name at the header's start, mirrored against the user
	// menu at its end. Optional — a platform without a logo renders no brand
	// slot and the message block stays centred between nothing and the menu.
	Brand Brand

	// User is the logged-in identity. Required: the header's outer thirds and
	// the drawer's first entry are built from it.
	User Identity

	// UserActions slot — shown at the header RIGHT, next to the work-area name
	// (e.g. the light/dark theme toggle). Optional.
	// A factory, not a Component: the shell renders one menu per surface and a
	// single element cannot have two parents. Passing one instance put the same
	// element in both menus, which rendered twice with one id and left the copy
	// in the drawer inert.
	UserActions func() Component

	// Modules registered in order — appearance order in the nav rail.
	Modules []UIModule

	// CanView filters which modules the shell presents. nil = show all.
	CanView func(resource string) bool

	// DefaultID is the ModelName() of the module to show initially.
	// If empty, the first module is used.
	DefaultID string
	// contains filtered or unexported fields
}

type UIModule interface {
	layout.Module    // identity: ModelName() → used as ID
	Label() string   // text in the nav rail
	Icon() svg.Icon  // chassis renders via the sprite
	View() Component // module content (often a *rightpanel.RightPanel)
}