Composables

Reactive state helpers and DOM behaviours. A factory is called and returns a controller built on runes; an action is attached to an element; a transition is handed to Svelte. The class behind a factory never leaves its module — call the factory, never new.

`createMediaQuery`

factory

Call it — createMediaQuery(query)

Reactive matchMedia, for layout that has to branch on a breakpoint in markup rather than in CSS. matches is seeded false and filled by an effect, so anything that must be decided before the first paint — prefers-reduced-motion inside a DOM action, say — has to call matchMedia directly instead, or it will act on the seed.

Parameters

Prop	Type	Default	Description
`query` required	`string`		A CSS media query, e.g. `'(min-width: 768px)'`.

MediaQueryController

Prop	Type	Default	Description
`matches` required	`boolean`		Whether the query matches right now.

Import from ground/composables/use-media-query, or from the barrel.

`createTextScale`

factory

Call it — createTextScale()

Reader-controlled text size, applied as the --text-scale multiplier on the document element so popovers and dialogs rendered outside the shell scale with it. AppShell owns one and passes it to DisplayControls — an app needs its own only for a shell it built itself.

TextScaleController

Prop	Type	Description
`level` required	`number`	Index of the current step, `0` being the default size.
`steps` required	`number`	How many steps exist, for labelling the control.
`next` required	`() => void`	Advances one step, wrapping back to the default past the last.

Import from ground/composables/use-text-scale, or from the barrel.

`createTheme`

factory

Call it — createTheme(fallback?)

Colour-scheme controller for an app shell: reads the visitor's stored choice, falls back to the OS, and keeps .dark/.light on the document element in sync. Create one per app and hand it to AppShell, which forwards it to DisplayControls.

Parameters

Prop	Type	Default	Description
`fallback`	`'system'\|'light'\|'dark'`		Scheme to use on a first visit only — once anything is stored, the visitor's own choice outranks it. An app with no dark design yet can pass `'light'` so a dark-OS visitor doesn't land on a theme nobody drew.

ThemeController

Prop	Type	Description
`mode` required	`'system'\|'light'\|'dark'`	The stored preference. `system` follows the OS.
`resolved` required	`'light'\|'dark'`	The scheme actually in effect, with `system` already resolved against the OS. This is what a control should display.
`set` required	`(mode: 'system'\|'light'\|'dark') => void`	Pins a preference and persists it.
`toggle` required	`() => void`	Flips between light and dark, pinning the result.

Import from ground/composables/use-theme, or from the barrel.

`countUp`

action

Attach it with use: — use:countUp={{ options? }}

use: action that counts every number inside an element up to the value already rendered, the first time it scrolls into view. The finished text is the target, so the real figure survives with no JS and under reduced motion; thousands separators and the copy around them ($, %, M+) stay exactly where they were. Eases out on --ease-entrance, because a linear count reads as a spinner still loading.

Parameters

Prop	Type	Default	Description
`node` required	`HTMLElement`
`options`	`CountUpOptions`

CountUpOptions

Prop	Type	Default	Description
`duration`	`number`		How long the climb takes, in milliseconds.
`delay`	`number`		Delay in milliseconds, for staggering a row of figures.

Import from ground/composables/use-count-up, or from the barrel.

`lightSource`

action

Attach it with use: — use:lightSource={{ options? }}

use: action that aims the theme's single light source at the pointer. It listens on window and writes --light-x on the document element rather than on the node, so every surface-sheen surface leans the same way — dialogs and popovers rendered outside this tree included. AppShell already applies it; an app needs it only for a shell of its own. Idle under reduced motion.

Parameters

Prop	Type	Default	Description
`node` required	`HTMLElement`
`options`	`LightSourceOptions`

LightSourceOptions

Prop	Type	Default	Description
`swing`	`number`		Total travel of the hot spot across the full viewport width, in percentage points — a lean toward the pointer, not the lamp being dragged.

Import from ground/composables/use-light-source, or from the barrel.

`scrollFade`

action

Attach it with use: — use:scrollFade={{ options? }}

use: action that fades a scrolling box's clipped edges, so a cut-off list reads as "there is more" instead of as its own end. Required on any box that clips its content. Each edge is sized by its distance from the end, so it grows and shrinks with the scroll and is simply absent when the content fits — nothing to transition, nothing to tune.

Parameters

Prop	Type	Default	Description
`node` required	`HTMLElement`
`options`	`ScrollFadeOptions`

ScrollFadeOptions

Prop	Type	Description
`size`	`number`	Height of a fade at full strength, in pixels.
`top`	`boolean`	Fade the top edge. Pass `false` where something else already covers it, e.g. a translucent header sitting over the scroll.
`bottom`	`boolean`	Fade the bottom edge.

Import from ground/composables/use-scroll-fade, or from the barrel.

`scrollReveal`

action

Attach it with use: — use:scrollReveal={{ options? }}

use: action that fades and lifts an element into place the first time it scrolls into view. Does nothing at all when the visitor asked for reduced motion, and never hides anything without JS — the hidden state is written from script, so a crawler or a script-off render gets the finished page rather than an empty one.

Parameters

Prop	Type	Default	Description
`node` required	`HTMLElement`
`options`	`ScrollRevealOptions`

ScrollRevealOptions

Prop	Type	Description
`y`	`number`	Distance in pixels the element rises from.
`duration`	`number`	Transition duration in milliseconds.
`delay`	`number`	Delay in milliseconds, for staggering neighbours.

Import from ground/composables/use-scroll-reveal, or from the barrel.

`flyAndScale`

transition

Pass it to transition: — transition:flyAndScale={{ options? }}

Svelte transition for something that appears over the page — the small rise-and-settle a popover or menu panel uses. Pass it to transition:/in:, not use:; it is a transition, not an action.

Parameters

Prop	Type	Default	Description
`node` required	`HTMLElement`
`options`	`FlyAndScaleOptions`

FlyAndScaleOptions

Prop	Type	Description
`y`	`number`	Distance in pixels the element travels as it settles.
`start`	`number`	Scale it grows from.
`duration`	`number`	Duration in milliseconds.

Import from ground/composables/use-transition, or from the barrel.

Navigation helpers

Plain functions rather than components, shared by Sidebar, SectionNav and any nav an app builds itself, so a navigable row looks and behaves the same wherever it turns up.

`navItemRowClass`

The anchor a column nav entry sits in: the whole row, so the pointer hits the entry anywhere across the column rather than only over the label. It carries the tint nowhere itself — that is navItemClass on a child, sized to its content — and it gives up its own focus outline, which would otherwise trace the empty width beside a short label. The outline moves onto the tinted child through group-focus-visible, so what lights on focus is what lights on hover.

`navItemClass`

The one treatment every navigation entry wears — Sidebar's rows and SectionNav's sections, which sit on the same black page and so have no reason to look like two different controls. The current entry takes selected, the brand tint, and separates itself further by weight: primary text and icon. A hovered sibling gets hover's neutral film instead — a neighbouring tone, never the same emphasis — so only one entry ever reads as the location, and nothing is dimmed to make that true. It is the same pair a checked box, a pressed toggle and the primary button wear, so a selection looks like a selection wherever it turns up. The tint is drawn around the label rather than across the column: a 288px band of colour for a six-letter word claims more of the eye than the word is worth, and a column of them reads as a stack of blocks instead of a list of names. Put this on a child of navItemRowClass for a column nav; hover: and group-hover: are both listed so it still works alone, on an entry that is already only as wide as its label (a header's horizontal nav).

Prop	Type	Default	Description
`current` required	`boolean`		Whether the entry is the page the user is on.

`areaLinkClass`

The treatment for an area link in AppShell's header — deliberately *not* navItemClass. A sidebar row and a header area answer different questions. The sidebar says where you are within one area, so one row carries the selected fill and the rest sit level with it. The header says which area you are in at all, and it sits on the shell's glass beside the wordmark, where four filled pills would read as four controls competing with the page. So the header trades fill for weight: every area is a dimmed label, and the one you are in is the only one at full strength. This is the one place a navigable label is allowed to be muted, and it earns it by being a set where exactly one member is always lit — nothing here reads as disabled, because the contrast is between siblings rather than between a label and its own normal state.

Prop	Type	Default	Description
`current` required	`boolean`		Whether the area is the one the route is in.

`navItemCurrent`

Whether a nav entry is the current location. Path hrefs match the existing rule (exact, or a prefix of the route unless it's the home entry). Hash hrefs (in-page sections) match only an exact url.hash, since there is no nesting concept for an anchor.

Prop	Type	Default	Description
`href` required	`string`
`url` required	`URL`
`homeHref`	`string`