@rokkit/app 1.14.0 → 1.15.0

package/dist/components/ScreenInfo.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+	/**
+	 * The info band: up to three columns on a wash of one role — a framing column (eyebrow,
+	 * large mark, display title, lead), a how-to column (steps, each mark in a paper circle) and
+	 * a stat column after a hairline (a value, its total and a meter). Each column is data, or a
+	 * snippet drawn in the column's frame. Text stays ink; only the wash and the eyebrows take
+	 * the role.
+	 */
+	import type { Snippet } from 'svelte'
+	import type { GlyphMode, InfoColumn, InfoRole, InfoSlot } from '../types/screen-shell.js'
+
+	interface Props {
+		columns: InfoSlot[]
+		role?: InfoRole
+		glyphs?: GlyphMode
+		class?: string
+	}
+
+	const { columns, role = 'accent', glyphs = 'text', class: className = '' }: Props = $props()
+
+	const isSnippet = (slot: InfoSlot): slot is Snippet => typeof slot === 'function'
+	const percent = (progress: number) => `${Math.round(Math.max(0, Math.min(1, progress)) * 100)}%`
+</script>
+
+{#snippet mark(kanji: string | undefined, icon: string | undefined, part: string)}
+	{#if glyphs === 'icon' && icon}
+		<span {...{ [`data-screen-info-${part}`]: '' }} class={icon} aria-hidden="true"></span>
+	{:else if kanji}
+		<span {...{ [`data-screen-info-${part}`]: '' }} aria-hidden="true">{kanji}</span>
+	{/if}
+{/snippet}
+
+{#snippet column(info: InfoColumn)}
+	<span data-screen-info-label>{info.label}</span>
+	{#if info.kanji || info.icon || info.title}
+		<div data-screen-info-heading>
+			{@render mark(info.kanji, info.icon, 'mark')}
+			{#if info.title}<p data-screen-info-title>{info.title}</p>{/if}
+		</div>
+	{/if}
+	{#if info.value !== undefined}
+		<div data-screen-info-figure>
+			<span data-screen-info-value>{info.value}</span>
+			{#if info.total !== undefined}<span data-screen-info-total>/ {info.total}</span>{/if}
+		</div>
+	{/if}
+	{#if info.progress !== undefined}
+		<div
+			data-screen-info-meter
+			role="meter"
+			aria-label={info.label}
+			aria-valuemin={0}
+			aria-valuemax={1}
+			aria-valuenow={info.progress}
+		>
+			<span data-screen-info-meter-fill style:inline-size={percent(info.progress)}></span>
+		</div>
+	{/if}
+	{#if info.steps?.length}
+		<ol data-screen-info-steps>
+			{#each info.steps as step, index (index)}
+				<li data-screen-info-step>
+					<span data-screen-info-step-seal>{@render mark(step.kanji, step.icon, 'step-mark')}</span>
+					<div data-screen-info-step-body>
+						<span data-screen-info-step-title>{step.title}</span>
+						{#if step.text}<span data-screen-info-step-text>{step.text}</span>{/if}
+					</div>
+				</li>
+			{/each}
+		</ol>
+	{/if}
+	{#if info.text}<p data-screen-info-text>{info.text}</p>{/if}
+{/snippet}
+
+<div data-screen-info data-role={role} class={className || undefined}>
+	{#each columns.slice(0, 3) as slot, index (index)}
+		<div data-screen-info-column>
+			{#if isSnippet(slot)}
+				{@render slot()}
+			{:else}
+				{@render column(slot)}
+			{/if}
+		</div>
+	{/each}
+</div>

package/dist/components/ScreenInfo.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { GlyphMode, InfoRole, InfoSlot } from '../types/screen-shell.js';
+interface Props {
+    columns: InfoSlot[];
+    role?: InfoRole;
+    glyphs?: GlyphMode;
+    class?: string;
+}
+declare const ScreenInfo: import("svelte").Component<Props, {}, "">;
+type ScreenInfo = ReturnType<typeof ScreenInfo>;
+export default ScreenInfo;

package/dist/components/ScreenShell.svelte

@@ -0,0 +1,323 @@
+<script lang="ts">
+	/**
+	 * One screen, laid out from data: a title bar (mark, title, context, then search, the
+	 * screen's own buttons and the band toggles), a description, the info / stats / filters
+	 * bands, a body and a sidebar that each scroll on their own, and a footer. The shell fills
+	 * its container; nothing but the body and the sidebar scrolls.
+	 *
+	 * Layout only, and it persists nothing: `panels` and `filter` are bindable (and emitted
+	 * through `onpanels` / `onfilter`); the host stores them by `viewId`.
+	 */
+	import { untrack, type Snippet } from 'svelte'
+	import { StatCard, Toolbar, type ToolbarItem } from '@rokkit/ui'
+	import { FormRenderer } from '@rokkit/forms'
+	import { messages } from '@rokkit/states'
+	import { DEFAULT_STATE_ICONS } from '@rokkit/core'
+	import ScreenInfo from './ScreenInfo.svelte'
+	import type {
+		FilterApi,
+		FilterSchema,
+		FilterState,
+		FooterParts,
+		PanelId,
+		PanelLabels,
+		ScreenShellProps,
+		ShellStat,
+		StatMemory
+	} from '../types/screen-shell.js'
+	import {
+		PANEL_IDS,
+		applyStat,
+		changedKeys,
+		clearStat,
+		isOpen,
+		presentPanels,
+		resolveToolbar,
+		setFilterValue,
+		statSpan,
+		togglePanel
+	} from '../utils/screen-shell.js'
+
+	const DEFAULT_ICONS: PanelLabels = {
+		info: DEFAULT_STATE_ICONS.state.info,
+		stats: DEFAULT_STATE_ICONS.view.chart,
+		filters: 'i-glyph:search-filter',
+		side: 'i-glyph:sidebar'
+	}
+	const SEARCH_DELAY = 250
+
+	let {
+		viewId,
+		mark,
+		title,
+		context,
+		description,
+		search = {},
+		toolbar,
+		info,
+		infoRole = 'accent',
+		stats,
+		filters,
+		sidebar,
+		sidebarSide = 'right',
+		footer,
+		children,
+		panels = $bindable({}),
+		onpanels,
+		filter = $bindable({ values: {}, stat: null }),
+		onfilter,
+		glyphs = 'text',
+		icons,
+		labels,
+		class: className = ''
+	}: ScreenShellProps = $props()
+
+	const text = $derived({ ...messages.screen, ...labels })
+	const values = $derived(filter?.values ?? {})
+	const statList = $derived(stats ?? [])
+
+	// ─── Panels ────────────────────────────────────────────────────
+
+	const has = $derived<Record<PanelId, boolean>>({
+		info: Boolean(info?.length),
+		stats: stats !== undefined,
+		filters: Boolean(filters),
+		side: Boolean(sidebar)
+	})
+	const present = $derived(presentPanels(has))
+	const shown = (id: PanelId) => has[id] && isOpen(panels, id)
+
+	function flip(id: PanelId) {
+		const next = togglePanel(panels, id, present)
+		panels = next
+		onpanels?.(next)
+	}
+
+	// ─── Toolbar ───────────────────────────────────────────────────
+
+	const items = $derived(
+		resolveToolbar(toolbar, {
+			present,
+			panels,
+			labels: text,
+			icons: { ...DEFAULT_ICONS, ...icons },
+			busy: text.busy
+		})
+	)
+
+	function runItem(value: unknown, item: ToolbarItem) {
+		if (item.type === 'toggle' && PANEL_IDS.includes(value as PanelId))
+			return flip(value as PanelId)
+		;(item.onclick as (() => void) | undefined)?.()
+	}
+
+	// ─── Filter ────────────────────────────────────────────────────
+
+	let memory: StatMemory | null = null
+
+	function commit(step: { filter: FilterState; memory: StatMemory | null }) {
+		memory = step.memory
+		filter = step.filter
+		onfilter?.(step.filter)
+	}
+
+	const current = (): FilterState => ({ values, stat: filter?.stat ?? null })
+	const setValue = (key: string, value: unknown) =>
+		commit(setFilterValue(current(), key, value, { stats: statList, memory }))
+	const clearValues = () => commit({ filter: { values: {}, stat: null }, memory: null })
+	const clearActive = () => commit(clearStat(current(), statList, memory))
+	const pickStat = (stat: ShellStat) => commit(applyStat(current(), stat, memory, statList))
+
+	const api: FilterApi = {
+		get values() {
+			return values
+		},
+		set: setValue,
+		clear: clearValues
+	}
+
+	/** A FormRenderer update: every key that changed goes through the same merge rule. */
+	function updateFromForm(next: Record<string, unknown>) {
+		for (const key of changedKeys(values, next)) setValue(key, next[key])
+	}
+
+	const formData = $derived({ ...values })
+	const activeStat = $derived(statList.find((s) => s.id === filter?.stat && s.filter))
+	const filterSchema = $derived(
+		filters && typeof filters !== 'function' ? (filters as FilterSchema) : null
+	)
+	const filterSnippet = $derived(
+		typeof filters === 'function' ? (filters as Snippet<[FilterApi]>) : null
+	)
+	const filterActions = $derived(
+		resolveToolbar(
+			{ add: filterSchema?.actions ?? [] },
+			{
+				present: [],
+				panels,
+				labels: text,
+				icons: { ...DEFAULT_ICONS, ...icons },
+				busy: text.busy
+			}
+		)
+	)
+
+	// ─── Search ────────────────────────────────────────────────────
+
+	const searchOn = $derived(search !== false)
+	const placeholder = $derived((search && search.placeholder) || text.search)
+	const delay = $derived(search ? (search.delay ?? SEARCH_DELAY) : SEARCH_DELAY)
+	let query = $state(untrack(() => String(filter?.values?.q ?? '')))
+	let timer: ReturnType<typeof setTimeout> | undefined
+
+	// A q set from outside (a restored filter, a reset) shows in the field — but not while the
+	// user's own text is still waiting out the debounce.
+	$effect(() => {
+		const q = String(values.q ?? '')
+		untrack(() => {
+			if (timer === undefined && q !== query) query = q
+		})
+	})
+
+	$effect(() => () => clearTimeout(timer))
+
+	function onsearch() {
+		clearTimeout(timer)
+		timer = setTimeout(() => {
+			timer = undefined
+			setValue('q', query)
+		}, delay)
+	}
+
+	// ─── Stats & footer ────────────────────────────────────────────
+
+	const reserve = $derived(statList.some((s) => Boolean(s.description)))
+	const footerParts = $derived(
+		footer && typeof footer !== 'function' ? (footer as FooterParts) : null
+	)
+	const footerSnippet = $derived(typeof footer === 'function' ? (footer as Snippet) : null)
+	const FOOTER_PARTS = ['left', 'mid', 'right'] as const
+</script>
+
+{#snippet glyph(kanji: string, icon: string | undefined)}
+	{#if glyphs === 'icon' && icon}
+		<span data-screen-mark class={icon} aria-hidden="true"></span>
+	{:else}
+		<span data-screen-mark aria-hidden="true">{kanji}</span>
+	{/if}
+{/snippet}
+
+{#snippet side()}
+	{#if sidebar && shown('side')}
+		<aside data-screen-sidebar data-side={sidebarSide} aria-label={text.side}>
+			{@render sidebar()}
+		</aside>
+	{/if}
+{/snippet}
+
+<div data-screen-shell data-view={viewId} class={className || undefined}>
+	<header data-screen-header>
+		<div data-screen-titlebar>
+			{@render glyph(mark.kanji, mark.icon)}
+			<h1 data-screen-title>{title}</h1>
+			{#if context}<span data-screen-context>{context}</span>{/if}
+			{#if searchOn || items.length}
+				<div data-screen-tools>
+					{#if searchOn}
+						<label data-screen-search>
+							<span
+								data-screen-search-icon
+								class={DEFAULT_STATE_ICONS.action.search}
+								aria-hidden="true"
+							></span>
+							<input
+								type="search"
+								bind:value={query}
+								oninput={onsearch}
+								{placeholder}
+								aria-label={placeholder}
+							/>
+						</label>
+					{/if}
+					{#if items.length}
+						<Toolbar {items} label={title} width="fit" showDividers={false} onclick={runItem} />
+					{/if}
+				</div>
+			{/if}
+		</div>
+		{#if description}<p data-screen-description>{description}</p>{/if}
+
+		{#if info?.length && shown('info')}
+			<ScreenInfo columns={info} role={infoRole} {glyphs} />
+		{/if}
+
+		{#if stats !== undefined && shown('stats')}
+			<div data-screen-stats aria-label={text.stats} role="group">
+				{#if stats === null}
+					<p data-screen-stats-reading>{text.reading}</p>
+				{:else}
+					{#each stats as stat (stat.id)}
+						<StatCard
+							label={stat.title}
+							value={stat.value}
+							tone={stat.tone}
+							description={stat.description}
+							reserveDescription={reserve}
+							span={statSpan(stat)}
+							href={stat.filter ? undefined : stat.href}
+							icon={glyphs === 'icon' ? stat.icon : undefined}
+							mark={stat.kanji}
+							onclick={stat.filter ? () => pickStat(stat) : undefined}
+							pressed={filter?.stat === stat.id}
+							data-stat={stat.id}
+						/>
+					{/each}
+				{/if}
+			</div>
+		{/if}
+
+		{#if filters && shown('filters')}
+			<div data-screen-filters role="group" aria-label={text.filters}>
+				{#if filterSnippet}
+					{@render filterSnippet(api)}
+				{:else if filterSchema}
+					<FormRenderer
+						data={formData}
+						schema={filterSchema.schema}
+						layout={filterSchema.layout}
+						onupdate={updateFromForm}
+					/>
+					{#if filterActions.length}
+						<div data-screen-filter-actions>
+							<Toolbar items={filterActions} label={text.filters} width="fit" onclick={runItem} />
+						</div>
+					{/if}
+				{/if}
+				{#if activeStat}
+					<span data-screen-filter-chip>
+						{text.fromStat}: <strong>{activeStat.title}</strong>
+						<button type="button" onclick={clearActive}>{text.clear}</button>
+					</span>
+				{/if}
+			</div>
+		{/if}
+	</header>
+
+	<div data-screen-main>
+		{#if sidebarSide === 'left'}{@render side()}{/if}
+		<div data-screen-body role="region" aria-label={title}>
+			{@render children()}
+		</div>
+		{#if sidebarSide !== 'left'}{@render side()}{/if}
+	</div>
+
+	{#if footerSnippet}
+		<footer data-screen-footer>{@render footerSnippet()}</footer>
+	{:else if footerParts}
+		<footer data-screen-footer>
+			{#each FOOTER_PARTS as part (part)}
+				{#if footerParts[part]}<span data-part={part}>{footerParts[part]}</span>{/if}
+			{/each}
+		</footer>
+	{/if}
+</div>

package/dist/components/ScreenShell.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { ScreenShellProps } from '../types/screen-shell.js';
+declare const ScreenShell: import("svelte").Component<ScreenShellProps, {}, "filter" | "panels">;
+type ScreenShell = ReturnType<typeof ScreenShell>;
+export default ScreenShell;

package/dist/components/index.d.ts

@@ -1,3 +1,5 @@
 export { default as ThemeSwitcherToggle } from './ThemeSwitcherToggle.svelte';
 export { default as TableOfContents } from './TableOfContents.svelte';
 export { default as SkinSwitcherToggle } from './SkinSwitcherToggle.svelte';
+export { default as ScreenShell } from './ScreenShell.svelte';
+export { default as ScreenInfo } from './ScreenInfo.svelte';

package/dist/components/index.js

@@ -1,3 +1,5 @@
 export { default as ThemeSwitcherToggle } from './ThemeSwitcherToggle.svelte';
 export { default as TableOfContents } from './TableOfContents.svelte';
 export { default as SkinSwitcherToggle } from './SkinSwitcherToggle.svelte';
+export { default as ScreenShell } from './ScreenShell.svelte';
+export { default as ScreenInfo } from './ScreenInfo.svelte';

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-export { ThemeSwitcherToggle, SkinSwitcherToggle, TableOfContents } from './components/index.js';
+export { ThemeSwitcherToggle, SkinSwitcherToggle, TableOfContents, ScreenShell, ScreenInfo } from './components/index.js';
 export * from './types/index.js';
 export { ColorModeManager, resolveMode, type ColorMode, type ResolvedMode } from './utils/color-mode.svelte.js';
+export { PANEL_IDS, isOpen, presentPanels, togglePanel, resolveToolbar, statSpan, applyStat, clearStat, setFilterValue, changedKeys } from './utils/screen-shell.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 // Components
-export { ThemeSwitcherToggle, SkinSwitcherToggle, TableOfContents } from './components/index.js';
+export { ThemeSwitcherToggle, SkinSwitcherToggle, TableOfContents, ScreenShell, ScreenInfo } from './components/index.js';
 // Types
 export * from './types/index.js';
 // Utilities
 export { ColorModeManager, resolveMode } from './utils/color-mode.svelte.js';
+export { PANEL_IDS, isOpen, presentPanels, togglePanel, resolveToolbar, statSpan, applyStat, clearStat, setFilterValue, changedKeys } from './utils/screen-shell.js';

package/dist/types/index.d.ts

@@ -1,2 +1,3 @@
 export * from './theme-switcher.js';
 export * from './skin-switcher.js';
+export * from './screen-shell.js';

package/dist/types/index.js

@@ -1,2 +1,3 @@
 export * from './theme-switcher.js';
 export * from './skin-switcher.js';
+export * from './screen-shell.js';

package/dist/types/screen-shell.d.ts

@@ -0,0 +1,165 @@
+/**
+ * ScreenShell Types
+ *
+ * The data a screen hands its shell: a title bar (mark, title, context, search, toolbar), an
+ * optional description, info / stats / filters bands, a body and a sidebar that each scroll on
+ * their own, and a footer. The shell is layout only; it persists nothing — `panels` and
+ * `filter` are bindable and the host stores them.
+ */
+import type { Snippet } from 'svelte';
+import type { ToolbarItem } from '@rokkit/ui';
+/** The bands a screen can open and close from its toolbar, in toolbar order. */
+export type PanelId = 'info' | 'stats' | 'filters' | 'side';
+/** Which bands are open. A missing key is open, so a first visit opens everything. */
+export type PanelState = Partial<Record<PanelId, boolean>>;
+/** Per-panel strings (toggle labels) or icon classes. */
+export type PanelLabels = Record<PanelId, string>;
+/** A screen's mark: the kanji, or the icon when the shell is in icon mode and one is given. */
+export interface ShellMark {
+    kanji: string;
+    icon?: string;
+}
+/** Which glyph a mark draws: the text (kanji) or, when it has one, the icon. */
+export type GlyphMode = 'text' | 'icon';
+/**
+ * A screen's own button: an icon, its label as the tooltip and the accessible name. A
+ * `disabled` string is the reason, shown with the label. A rokkit Toolbar `button` item.
+ */
+export interface ShellAction {
+    id: string;
+    label: string;
+    icon: string;
+    onclick?: () => void;
+    href?: string;
+    busy?: boolean;
+    disabled?: string | boolean;
+    [key: string]: unknown;
+}
+/**
+ * The toolbar: the default (one toggle per band the view has) extended with `add` (left of the
+ * toggles) and `remove` (drops a default by id); or a full list the screen owns.
+ */
+export type ToolbarSpec = {
+    add?: Array<ShellAction | ToolbarItem>;
+    remove?: string[];
+} | ToolbarItem[];
+/** One step in an info column: a mark in a paper circle, a title and a line. */
+export interface InfoStep {
+    kanji: string;
+    icon?: string;
+    title: string;
+    text?: string;
+}
+/**
+ * One info column. `label` is the eyebrow and `text` the lead — the contract's minimum. A
+ * column may also carry a large mark and a display title (the framing column), steps (the
+ * how-to column) or a value with an optional total and progress (the stat column).
+ */
+export interface InfoColumn {
+    label: string;
+    text?: string;
+    kanji?: string;
+    icon?: string;
+    title?: string;
+    steps?: InfoStep[];
+    value?: string | number;
+    total?: string | number;
+    /** 0–1: how far along, drawn as a meter. */
+    progress?: number;
+}
+/** A column is data, or a snippet that draws it inside the band's column frame. */
+export type InfoSlot = InfoColumn | Snippet;
+/** The role whose wash tints the info band. */
+export type InfoRole = 'accent' | 'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'danger';
+export type ShellStatTone = 'ink' | 'danger' | 'warning' | 'success' | 'muted';
+/** One stat card. With `filter` it is a toggle that sets the filter; with `href` a link. */
+export interface ShellStat {
+    id: string;
+    /** Shown capitalised by the theme, not typed in capitals. */
+    title: string;
+    kanji?: string;
+    icon?: string;
+    value: string | number;
+    tone?: ShellStatTone;
+    description?: string;
+    /** Columns of 12 the card takes; computed from its content when absent. */
+    span?: number;
+    filter?: {
+        key: string;
+        value: unknown;
+    };
+    href?: string;
+}
+/** The filter values, the one source of truth, and the active stat's id. */
+export interface FilterState {
+    values: Record<string, unknown>;
+    stat?: string | null;
+}
+/** What a filter band snippet is handed. `clear()` empties every value. */
+export interface FilterApi {
+    values: Record<string, unknown>;
+    set(key: string, value: unknown): void;
+    clear(): void;
+}
+/** A filter band drawn by `@rokkit/forms` FormRenderer; `actions` are its toolbar. */
+export interface FilterSchema {
+    schema: Record<string, unknown>;
+    layout: Record<string, unknown>;
+    actions?: ShellAction[];
+}
+/** What the shell remembers about an applied stat, so clearing it restores the key. */
+export interface StatMemory {
+    /** The stat it was taken for; it applies only while that stat is the active one. */
+    stat: string;
+    key: string;
+    had: boolean;
+    value: unknown;
+}
+export interface FooterParts {
+    left?: string;
+    mid?: string;
+    right?: string;
+}
+export interface ScreenShellLabels extends PanelLabels {
+    search: string;
+    fromStat: string;
+    clear: string;
+    reading: string;
+    busy: string;
+}
+export interface ScreenShellProps {
+    /** `<surface>.<area>[.<view>]` — the host keys its stored panels by it. */
+    viewId?: string;
+    mark: ShellMark;
+    title: string;
+    context?: string;
+    description?: string;
+    /** On by default; `false` only for a view with nothing to search. Writes `values.q`. */
+    search?: {
+        placeholder?: string;
+        delay?: number;
+    } | false;
+    toolbar?: ToolbarSpec;
+    info?: InfoSlot[];
+    /** The info band's wash: the role it tints with (default `accent`). */
+    infoRole?: InfoRole;
+    /** `null` = still reading (the band says so). */
+    stats?: ShellStat[] | null;
+    filters?: Snippet<[FilterApi]> | FilterSchema;
+    sidebar?: Snippet;
+    /** Which side the sidebar sits on (default `right`). */
+    sidebarSide?: 'left' | 'right';
+    footer?: Snippet | FooterParts;
+    children: Snippet;
+    panels?: PanelState;
+    onpanels?: (next: PanelState) => void;
+    filter?: FilterState;
+    onfilter?: (next: FilterState) => void;
+    /** Draw marks as kanji (`text`, default) or as their icons (`icon`). */
+    glyphs?: GlyphMode;
+    /** Toggle icon classes per band. */
+    icons?: Partial<PanelLabels>;
+    /** String overrides; defaults come from `messages.screen`. */
+    labels?: Partial<ScreenShellLabels>;
+    class?: string;
+}

package/dist/types/screen-shell.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/screen-shell.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ScreenShell — the pure rules behind the shell: which bands are open, what the toolbar holds,
+ * how wide a stat card is, and how a stat's filter merges into the filter values.
+ */
+import type { ToolbarItem } from '@rokkit/ui';
+import type { PanelId, PanelState, PanelLabels, ToolbarSpec, ShellStat, FilterState, StatMemory } from '../types/screen-shell.js';
+/** The bands a screen can toggle, in toolbar order. */
+export declare const PANEL_IDS: readonly PanelId[];
+/** Whether a band is open: a missing key is open (first visit: everything open). */
+export declare function isOpen(panels: PanelState | undefined, id: PanelId): boolean;
+/** The bands the view has, in toolbar order. */
+export declare function presentPanels(has: Partial<Record<PanelId, boolean>>): PanelId[];
+/**
+ * The whole panel state after one band flips, for the bands the view has. A band the view
+ * does not have is never stored, open or closed.
+ */
+export declare function togglePanel(panels: PanelState | undefined, id: PanelId, present: PanelId[]): PanelState;
+interface ToolbarContext {
+    present: PanelId[];
+    panels: PanelState | undefined;
+    labels: PanelLabels;
+    icons: PanelLabels;
+    /** Appended to a busy action's label. */
+    busy?: string;
+}
+/**
+ * The toolbar's items: the screen's own buttons, a separator, then one toggle per band the
+ * view has (`info · stats · filters · side`), or the full list a screen passes.
+ */
+export declare function resolveToolbar(spec: ToolbarSpec | undefined, ctx: ToolbarContext): ToolbarItem[];
+/**
+ * The columns (of 12) a stat card takes: a short title and no description → 1; a longer
+ * title, a long value or a short description → 2; a description over 32 characters → 3. A
+ * stat that names its span keeps it (1–12).
+ */
+export declare function statSpan(stat: Pick<ShellStat, 'title' | 'value' | 'description' | 'span'>): number;
+interface FilterStep {
+    filter: FilterState;
+    memory: StatMemory | null;
+}
+/**
+ * Clear the active stat: its key goes back to the value it had before the stat was applied
+ * (from `memory`), or is removed when the shell holds no memory for it.
+ */
+export declare function clearStat(filter: FilterState, stats: ShellStat[], memory: StatMemory | null): FilterStep;
+/**
+ * Click a stat: apply its filter (set its key, mark it active), or — when it is already the
+ * active one — clear it. A stat with no filter changes nothing. `stats` (the band) lets a
+ * previously active stat the shell holds no memory for be cleared by its key.
+ */
+export declare function applyStat(filter: FilterState, stat: ShellStat, memory: StatMemory | null, stats?: ShellStat[]): FilterStep;
+/**
+ * Set one filter value by hand. Changing the active stat's key clears the stat (the new value
+ * stays); changing any other key leaves it active.
+ */
+export declare function setFilterValue(filter: FilterState, key: string, value: unknown, { stats, memory }: {
+    stats: ShellStat[];
+    memory: StatMemory | null;
+}): FilterStep;
+/** The keys whose value differs between two value maps (added and removed keys included). */
+export declare function changedKeys(before: Record<string, unknown>, after: Record<string, unknown>): string[];
+export {};

package/dist/utils/screen-shell.js

@@ -0,0 +1,166 @@
+/** The bands a screen can toggle, in toolbar order. */
+export const PANEL_IDS = ['info', 'stats', 'filters', 'side'];
+const isPanelId = (value) => PANEL_IDS.includes(value);
+// =============================================================================
+// Panels
+// =============================================================================
+/** Whether a band is open: a missing key is open (first visit: everything open). */
+export function isOpen(panels, id) {
+    return panels?.[id] !== false;
+}
+/** The bands the view has, in toolbar order. */
+export function presentPanels(has) {
+    return PANEL_IDS.filter((id) => has[id]);
+}
+/**
+ * The whole panel state after one band flips, for the bands the view has. A band the view
+ * does not have is never stored, open or closed.
+ */
+export function togglePanel(panels, id, present) {
+    return Object.fromEntries(present.map((p) => [p, p === id ? !isOpen(panels, p) : isOpen(panels, p)]));
+}
+const SEPARATOR = { type: 'separator' };
+/** Why an action cannot run now: its disabled reason, else the busy note while it runs. */
+function unavailableNote(action, busy) {
+    if (typeof action.disabled === 'string' && action.disabled)
+        return action.disabled;
+    return action.busy ? busy : '';
+}
+/** A screen action (or any toolbar item) as a Toolbar item: value = id, a button by default. */
+function toToolbarItem(item, busy = '') {
+    const action = item;
+    const note = unavailableNote(action, busy);
+    return {
+        ...item,
+        value: item.value ?? item.id,
+        type: item.type ?? 'button',
+        label: note ? `${action.label} — ${note}` : action.label,
+        disabled: Boolean(action.disabled || action.busy)
+    };
+}
+/** One toggle per band, pressed while the band is open. */
+function panelToggle(id, ctx) {
+    return {
+        id,
+        value: id,
+        type: 'toggle',
+        icon: ctx.icons[id],
+        label: ctx.labels[id],
+        active: isOpen(ctx.panels, id)
+    };
+}
+/** A full list: kept as is, except a band toggle follows the band (dropped when it is absent). */
+function resolveFullList(spec, ctx) {
+    return spec
+        .filter((item) => item.type !== 'toggle' || !isPanelId(item.value) || ctx.present.includes(item.value))
+        .map((item) => item.type === 'toggle' && isPanelId(item.value)
+        ? { ...item, active: isOpen(ctx.panels, item.value) }
+        : item.type === 'separator' || item.type === 'spacer'
+            ? item
+            : toToolbarItem(item, ctx.busy));
+}
+/**
+ * The toolbar's items: the screen's own buttons, a separator, then one toggle per band the
+ * view has (`info · stats · filters · side`), or the full list a screen passes.
+ */
+export function resolveToolbar(spec, ctx) {
+    if (Array.isArray(spec))
+        return resolveFullList(spec, ctx);
+    const { add = [], remove = [] } = spec ?? {};
+    const removed = new Set(remove);
+    const toggles = ctx.present.filter((id) => !removed.has(id)).map((id) => panelToggle(id, ctx));
+    const added = add
+        .filter((item) => !removed.has(item.id))
+        .map((item) => toToolbarItem(item, ctx.busy));
+    const separator = added.length && toggles.length ? [SEPARATOR] : [];
+    return [...added, ...separator, ...toggles];
+}
+// =============================================================================
+// Stats
+// =============================================================================
+/** Card width thresholds (characters) — the contract's stand-in for measuring the text. */
+const SHORT_TITLE = 11;
+const SHORT_DESCRIPTION = 32;
+const SHORT_VALUE = 6;
+const MAX_SPAN = 12;
+/**
+ * The columns (of 12) a stat card takes: a short title and no description → 1; a longer
+ * title, a long value or a short description → 2; a description over 32 characters → 3. A
+ * stat that names its span keeps it (1–12).
+ */
+export function statSpan(stat) {
+    if (stat.span)
+        return Math.max(1, Math.min(MAX_SPAN, Math.round(stat.span)));
+    const description = stat.description ?? '';
+    if (description.length > SHORT_DESCRIPTION)
+        return 3;
+    if (description || stat.title.length > SHORT_TITLE || String(stat.value).length > SHORT_VALUE)
+        return 2;
+    return 1;
+}
+/** A copy of `values` with `key` set, or removed when it had none. */
+function restore(values, memory) {
+    const next = { ...values };
+    if (memory.had)
+        next[memory.key] = memory.value;
+    else
+        delete next[memory.key];
+    return next;
+}
+/** The memory, when it is the active stat's; a memory taken for another stat is stale. */
+function liveMemory(filter, memory) {
+    return memory && memory.stat === filter.stat ? memory : null;
+}
+/** The filter key the active stat set: from the shell's memory, else from the stat itself. */
+function activeKey(filter, stats, memory) {
+    const live = liveMemory(filter, memory);
+    if (live)
+        return live.key;
+    return stats.find((s) => s.id === filter.stat)?.filter?.key;
+}
+/**
+ * Clear the active stat: its key goes back to the value it had before the stat was applied
+ * (from `memory`), or is removed when the shell holds no memory for it.
+ */
+export function clearStat(filter, stats, memory) {
+    if (!filter.stat)
+        return { filter, memory: null };
+    const key = activeKey(filter, stats, memory);
+    const used = liveMemory(filter, memory) ??
+        (key ? { stat: filter.stat, key, had: false, value: undefined } : null);
+    const values = used ? restore(filter.values, used) : { ...filter.values };
+    return { filter: { values, stat: null }, memory: null };
+}
+/**
+ * Click a stat: apply its filter (set its key, mark it active), or — when it is already the
+ * active one — clear it. A stat with no filter changes nothing. `stats` (the band) lets a
+ * previously active stat the shell holds no memory for be cleared by its key.
+ */
+export function applyStat(filter, stat, memory, stats = [stat]) {
+    if (!stat.filter)
+        return { filter, memory };
+    if (filter.stat === stat.id)
+        return clearStat(filter, stats, memory);
+    const base = filter.stat ? clearStat(filter, stats, memory).filter : filter;
+    const { key, value } = stat.filter;
+    return {
+        filter: { values: { ...base.values, [key]: value }, stat: stat.id },
+        memory: { stat: stat.id, key, had: key in base.values, value: base.values[key] }
+    };
+}
+/**
+ * Set one filter value by hand. Changing the active stat's key clears the stat (the new value
+ * stays); changing any other key leaves it active.
+ */
+export function setFilterValue(filter, key, value, { stats, memory }) {
+    const values = { ...filter.values, [key]: value };
+    const stat = filter.stat ?? null;
+    if (stat && activeKey(filter, stats, memory) === key)
+        return { filter: { values, stat: null }, memory: null };
+    return { filter: { values, stat }, memory };
+}
+/** The keys whose value differs between two value maps (added and removed keys included). */
+export function changedKeys(before, after) {
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    return [...keys].filter((key) => !Object.is(before[key], after[key]));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/app",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "App-level controls for Rokkit applications - theme management and UI chrome",
   "repository": {
     "type": "git",
@@ -38,10 +38,11 @@
     "build": "svelte-package -i src -o dist"
   },
   "dependencies": {
-    "@rokkit/actions": "1.14.0",
-    "@rokkit/core": "1.14.0",
-    "@rokkit/states": "1.14.0",
-    "@rokkit/ui": "1.14.0"
+    "@rokkit/actions": "1.15.0",
+    "@rokkit/core": "1.15.0",
+    "@rokkit/forms": "1.15.0",
+    "@rokkit/states": "1.15.0",
+    "@rokkit/ui": "1.15.0"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"