layout

type AppShellBreakpoint string

type AppShellProps struct {
	utils.BaseProps

	// Sidebar renders in the left grid column on desktop (lg+). Hidden on
	// mobile. Typically navigation.SidebarNav, but any templ.Component works.
	Sidebar templ.Component
	// MobileNav renders below lg only (lg:hidden). Optional. Use it to host a
	// display.Drawer or other mobile navigation pattern. Nil = no mobile nav.
	MobileNav templ.Component
	// Header renders inside the content column, sticky to the top when
	// StickyHeader is true. Typically navigation.Nav. Optional.
	Header templ.Component
	// Footer renders inside the content column, after Content, pinned to the
	// bottom of the viewport (mt-auto) at every breakpoint — the shell is a
	// full-height flex column below the grid breakpoint and a stretching grid
	// above it. Optional.
	Footer templ.Component
	// Content is the main body of the shell. Required.
	Content templ.Component
	// SidebarWidth controls the desktop sidebar column width via a CSS custom
	// property (--tc-sidebar-w). Default SidebarWidthMD (16rem). The main
	// column is always minmax(0, 1fr) — never bare 1fr (grid-blowout guard).
	SidebarWidth SidebarWidth
	// Breakpoint selects the viewport width at which the desktop sidebar
	// appears and the MobileNav hides — the hamburger breakpoint. Default
	// (zero value) keeps the historical lg: (1024px); md:/xl: cover
	// tablet-first and wide-dashboard shells (M22/F102).
	Breakpoint AppShellBreakpoint
	// StickyHeader pins the Header to the top of the content column on scroll.
	// Default true. Set to false for static headers.
	StickyHeader bool
	// Container, when true (default), wraps Content in a layout.Container at
	// ContainerWidth. Set to false when Content manages its own width
	// (e.g. an edge-to-edge table or map).
	Container bool
	// ContainerWidth is the max-width applied to the Content wrapper when
	// Container is true. Default ContainerWidthLG.
	ContainerWidth ContainerWidth
}

type AsidePosition string

type ContainerProps struct {
	utils.BaseProps

	// Width controls the max-width. Default is ContainerWidthLG.
	// Use ContainerWidthProse for long-form articles.
	Width ContainerWidth
	// NoPad suppresses the responsive horizontal gutter
	// (px-4 sm:px-6 lg:px-8). The gutter is ON by default — the zero
	// value is the padded common case, so struct literals keep it
	// without setting anything. Set NoPad to true only when the
	// consumer manages padding (e.g. edge-to-edge maps inside a
	// ContainerWidthFull wrapper, or nesting inside a Card/Grid).
	NoPad bool
}

type ContainerWidth string

type HTMXVersion string

type MinimalProps struct {
	Title  string
	Locale string
	// SEO optionally emits the crawler/SEO head tags (robots noindex,
	// canonical, hreflang alternates, JSON-LD) with the same semantics as
	// PageProps.SEO. Zero value emits nothing — Minimal stays
	// dependency-free unless a tag is explicitly requested.
	SEO SEOMeta
	// HeadContent, when set, renders verbatim into <head> after the SEO
	// tags — the Minimal twin of PageProps.HeadContent: critical inline
	// styles, fonts, or extra meta tags without graduating to Base.
	HeadContent templ.Component
}

type PageProps struct {
	Title       string
	Description string
	Locale      string
	OGImage     string
	// OGType sets the Open Graph type for the og:type meta tag. Defaults to
	// "website" when empty. Common values: "website", "profile", "article".
	OGType         string
	ThemeColor     string
	DarkThemeColor string
	// CSSPath auto-injects `<link rel="stylesheet" href={CSSPath}>` into the
	// page `<head>`. DefaultPageProps sets it to "/app.css". Set CSSPath to ""
	// to suppress the stylesheet tag entirely — for example when you load
	// Tailwind via the browser Play CDN, embed styles inline, or serve your
	// own stylesheet through HeadContent.
	CSSPath string
	Favicon string
	// HTMXVersion controls auto-injection of the htmx `<script>` tag.
	// DefaultPageProps sets it to HTMXVersion2_0_10, which emits
	// `<script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.10" ...>`.
	// Set HTMXVersion to "" (the zero value) to disable auto-injection — for
	// example when you bundle htmx yourself, serve it from a local path via
	// HeadContent, or don't use htmx at all.
	HTMXVersion HTMXVersion
	// HTMXUseSRI adds an `integrity` attribute (subresource integrity) to the
	// auto-injected htmx script. Only meaningful when HTMXVersion is non-empty.
	HTMXUseSRI bool
	// HTMXCDN overrides the CDN base URL for htmx scripts. When empty, defaults
	// to "https://cdn.jsdelivr.net/npm". Set to e.g. "https://unpkg.com" to use
	// a different CDN, or a self-hosted origin. Both the htmx main script and
	// the response-targets extension derive their URLs from this value.
	HTMXCDN string
	// HTMXNone renders NO htmx runtime at all: no script, no preconnect — for
	// pages that use no htmx-powered components (backlog #282). Components
	// degrade gracefully without the runtime.
	// HTMXSrc, when non-empty, switches the htmx main script from the CDN URL
	// to a self-hosted path. The value becomes the <script src> attribute verbatim.
	// Example: "/static/htmx.min.js". When set, HTMXVersion/HTMXCDN/HTMXUseSRI
	// are ignored for the main script (no SRI is emitted because the asset is
	// same-origin). The CDN response-targets extension is also suppressed — a
	// self-hoster manages extensions too. Add your own <script> tag for it if
	// needed. See ADR-0007.
	HTMXSrc string
	// HTMXResponseTargets controls whether the htmx response-targets extension
	// is loaded from the CDN alongside htmx. Defaults to true for backward
	// compatibility; set to false to skip the extra request. Ignored when
	// HTMXSrc is set (self-host implies you manage extensions).
	HTMXResponseTargets bool
	// SkipLinkText overrides the default "Skip to main content" text for the
	// accessibility skip link. Useful for i18n.
	SkipLinkText string
	// HTMLDataAttrs adds extra attributes to the <html> element (e.g.
	// data-nonce for Datastar's opt-in CSP mode, which reads root-level
	// attributes off document.documentElement). Keys are rendered as-is.
	// Pass nil for no extra attributes — the zero value keeps existing pages
	// byte-identical.
	HTMLDataAttrs templ.Attributes
	// BodyDataAttrs adds extra attributes to the <body> element (e.g.
	// data-language). Keys are rendered as-is. Pass nil for no extra attributes.
	BodyDataAttrs templ.Attributes
	BodyClass     string
	Nonce         string
	// SEO carries crawler/SEO head tags (noindex, canonical, hreflang
	// alternates, JSON-LD). Zero value emits nothing — existing pages keep
	// byte-identical output.
	SEO         SEOMeta
	HeadContent templ.Component
	Footer      templ.Component
	// SecurityHeaders is a deprecated no-op: HTTP security headers cannot be
	// expressed as meta tags (browsers ignore meta http-equiv for
	// X-Content-Type-Options and Referrer-Policy, and the latter was never a
	// registered http-equiv, so the emitted tags were invalid HTML that
	// failed HTML validation). Send real headers at the server instead. The
	// field remains for API compatibility and emits nothing.
	SecurityHeaders bool
	// NoMainWrapper, when true, omits the `<main id="main-content">` wrapper
	// and renders children directly under <body> — for pages whose content is
	// itself a full landmark component (errorpage.ErrorPage and
	// errorpage.NotFound404 render their own <main>; nesting a second <main>
	// is an HTML violation and an axe/html-validate failure). The skip link
	// still targets #main-content, so give your own landmark that ID
	// (errorpage.NotFound404Props.BaseProps.ID accepts it, plus a tabindex
	// Attr for skip-link focus). Zero value keeps the wrapper — existing
	// pages render byte-identically.
	NoMainWrapper bool
	// NoThemeScript, when true, skips the inline dark-mode preload script
	// Base emits in <head> (the ThemeScript that reads localStorage['theme']
	// and sets the .dark class + color-scheme before paint). For consumers
	// running a strict CSP that allows no inline scripts: ship the same
	// logic as a same-origin, render-blocking <script src> via HeadContent,
	// or drop the script entirely when the page only follows
	// prefers-color-scheme (the script is only needed for the toggle dark
	// strategy — see ThemeScript's doc). Zero value keeps the script —
	// existing pages render byte-identically.
	NoThemeScript bool
}

type SEOAlternate struct {
	Lang string
	URL  string
}

type SEOMeta struct {
	// NoIndex emits <meta name="robots" content="noindex"> for transient
	// pages (tailored variants, operator surfaces) that must stay out of
	// search results.
	NoIndex bool
	// Canonical emits <link rel="canonical">; empty omits the tag. Should
	// be an absolute URL.
	Canonical string
	// Alternates emits one <link rel="alternate" hreflang> per entry, in
	// order. Empty omits all.
	Alternates []SEOAlternate
	// JSONLD is embedded VERBATIM as <script type="application/ld+json">
	// via templ.Raw — it bypasses templ's auto-escaping by design. Only
	// pass trusted, correctly serialized JSON (marshal your struct with
	// encoding/json before handing it here); never interpolate user input.
	JSONLD string
}

type SidebarWidth string

type SplitProps struct {
	utils.BaseProps

	// Main is the primary content column. Required.
	Main templ.Component
	// Aside is the secondary content column (sidebar, metadata, related
	// links). Required.
	Aside templ.Component
	// AsidePosition controls whether Aside renders before or after Main.
	// Default AsidePositionEnd (aside after main in source order + visual).
	AsidePosition AsidePosition
	// AsideLabel, when set, names the aside landmark (aria-label). Setting it
	// renders the column as a semantic <aside> complementary landmark — a
	// labeled non-landmark element is invalid HTML-ARIA (aria-label on a
	// roleless generic), so the label implies the landmark. Without it, an
	// unnamed <aside> would show up unlabeled in screen-reader landmark
	// rotors. Empty keeps the plain element (see AsideLandmark).
	AsideLabel string
	// AsideLandmark, when true, renders the aside column as a semantic
	// <aside> complementary landmark instead of the default plain <div>.
	// Use it when the column genuinely holds complementary content (related
	// links, metadata, TOC); leave it false for plain two-column layouts so
	// screen-reader landmark rotors stay clean. Zero value = <div>.
	AsideLandmark bool
	// Ratio controls the relative column widths. Default SplitRatio1To3
	// (main 2/3, aside 1/3).
	Ratio SplitRatio
	// Gap controls spacing between the two columns. Default GridGapLG (1.5rem).
	Gap string
	// ContainerAware, when true, wraps the Split in a @container div and swaps
	// md: breakpoint classes for @md: so the 2-column collapse responds to the
	// parent container's width, not the viewport. Useful when Split is placed
	// inside a sidebar, card body, drawer, or other constrained layout. Default
	// false (viewport breakpoints). See ADR-0018.
	ContainerAware bool
}

type SplitRatio string

type StackGap string

type StackProps struct {
	utils.BaseProps

	// Gap controls the vertical space between children. Default StackGapMD
	// when zero or unknown.
	Gap StackGap
}