@rokkit/app 1.15.0 → 1.15.2

package/dist/components/ScreenInfo.svelte

@@ -7,16 +7,24 @@
 	 * the role.
 	 */
 	import type { Snippet } from 'svelte'
+	import type { HTMLAttributes } from 'svelte/elements'
 	import type { GlyphMode, InfoColumn, InfoRole, InfoSlot } from '../types/screen-shell.js'
 
-	interface Props {
+	// `role` is the band's wash, not the ARIA role, so it stays out of the passthrough.
+	interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
 		columns: InfoSlot[]
 		role?: InfoRole
 		glyphs?: GlyphMode
 		class?: string
 	}
 
-	const { columns, role = 'accent', glyphs = 'text', class: className = '' }: Props = $props()
+	const {
+		columns,
+		role = 'accent',
+		glyphs = 'text',
+		class: className = '',
+		...rest
+	}: 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)}%`
@@ -72,7 +80,7 @@
 	{#if info.text}<p data-screen-info-text>{info.text}</p>{/if}
 {/snippet}
 
-<div data-screen-info data-role={role} class={className || undefined}>
+<div {...rest} 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)}

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

@@ -1,5 +1,6 @@
+import type { HTMLAttributes } from 'svelte/elements';
 import type { GlyphMode, InfoRole, InfoSlot } from '../types/screen-shell.js';
-interface Props {
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
     columns: InfoSlot[];
     role?: InfoRole;
     glyphs?: GlyphMode;

package/dist/components/ScreenShell.svelte

@@ -1,8 +1,9 @@
 <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
+	 * One screen, laid out from data: a title bar (mark, title, context, then the screen's own
+	 * buttons and the band toggles), a description, the info / stats / filters bands (search is
+	 * the filters band's first control), 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
@@ -69,7 +70,10 @@
 		glyphs = 'text',
 		icons,
 		labels,
-		class: className = ''
+		class: className = '',
+		toggleAttrs,
+		bandAttrs,
+		...rest
 	}: ScreenShellProps = $props()
 
 	const text = $derived({ ...messages.screen, ...labels })
@@ -81,7 +85,9 @@
 	const has = $derived<Record<PanelId, boolean>>({
 		info: Boolean(info?.length),
 		stats: stats !== undefined,
-		filters: Boolean(filters),
+		// Search lives in the filters band, so a screen with search has the band even when it
+		// passes no filters of its own.
+		filters: Boolean(filters) || search !== false,
 		side: Boolean(sidebar)
 	})
 	const present = $derived(presentPanels(has))
@@ -101,7 +107,8 @@
 			panels,
 			labels: text,
 			icons: { ...DEFAULT_ICONS, ...icons },
-			busy: text.busy
+			busy: text.busy,
+			toggleAttrs
 		})
 	)
 
@@ -209,55 +216,38 @@
 
 {#snippet side()}
 	{#if sidebar && shown('side')}
-		<aside data-screen-sidebar data-side={sidebarSide} aria-label={text.side}>
+		<aside {...bandAttrs?.side} 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}>
+<div {...rest} 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}
+			{#if 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}
+					<Toolbar {items} label={title} width="fit" showDividers={false} onclick={runItem} />
 				</div>
 			{/if}
 		</div>
 		{#if description}<p data-screen-description>{description}</p>{/if}
 
 		{#if info?.length && shown('info')}
-			<ScreenInfo columns={info} role={infoRole} {glyphs} />
+			<ScreenInfo columns={info} role={infoRole} {glyphs} {...bandAttrs?.info} />
 		{/if}
 
 		{#if stats !== undefined && shown('stats')}
-			<div data-screen-stats aria-label={text.stats} role="group">
+			<div {...bandAttrs?.stats} 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
+							{...stat.attrs}
 							label={stat.title}
 							value={stat.value}
 							tone={stat.tone}
@@ -276,8 +266,24 @@
 			</div>
 		{/if}
 
-		{#if filters && shown('filters')}
-			<div data-screen-filters role="group" aria-label={text.filters}>
+		{#if shown('filters')}
+			<div {...bandAttrs?.filters} data-screen-filters role="group" aria-label={text.filters}>
+				{#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 filterSnippet}
 					{@render filterSnippet(api)}
 				{:else if filterSchema}
@@ -312,9 +318,9 @@
 	</div>
 
 	{#if footerSnippet}
-		<footer data-screen-footer>{@render footerSnippet()}</footer>
+		<footer {...bandAttrs?.footer} data-screen-footer>{@render footerSnippet()}</footer>
 	{:else if footerParts}
-		<footer data-screen-footer>
+		<footer {...bandAttrs?.footer} data-screen-footer>
 			{#each FOOTER_PARTS as part (part)}
 				{#if footerParts[part]}<span data-part={part}>{footerParts[part]}</span>{/if}
 			{/each}

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

@@ -7,7 +7,14 @@
  * `filter` are bindable and the host stores them.
  */
 import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
 import type { ToolbarItem } from '@rokkit/ui';
+/**
+ * Attributes a host hangs on a shell part for its own hooks (`data-testid`) or extra
+ * semantics (`aria-*`): components take them as rest props, data (actions, stats, toolbar
+ * items) carries them in an `attrs` field, rendered on the element.
+ */
+export type ShellAttrs = Record<string, string>;
 /** 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. */
@@ -33,6 +40,8 @@ export interface ShellAction {
     href?: string;
     busy?: boolean;
     disabled?: string | boolean;
+    /** Attributes rendered on the action's button or link (e.g. `data-testid`). */
+    attrs?: ShellAttrs;
     [key: string]: unknown;
 }
 /**
@@ -89,6 +98,8 @@ export interface ShellStat {
         value: unknown;
     };
     href?: string;
+    /** Attributes rendered on the stat's card (e.g. `data-testid`). */
+    attrs?: ShellAttrs;
 }
 /** The filter values, the one source of truth, and the active stat's id. */
 export interface FilterState {
@@ -127,7 +138,7 @@ export interface ScreenShellLabels extends PanelLabels {
     reading: string;
     busy: string;
 }
-export interface ScreenShellProps {
+export interface ScreenShellProps extends HTMLAttributes<HTMLDivElement> {
     /** `<surface>.<area>[.<view>]` — the host keys its stored panels by it. */
     viewId?: string;
     mark: ShellMark;
@@ -162,4 +173,8 @@ export interface ScreenShellProps {
     /** String overrides; defaults come from `messages.screen`. */
     labels?: Partial<ScreenShellLabels>;
     class?: string;
+    /** Attributes per band toggle, rendered on its toolbar button (e.g. `data-testid`). */
+    toggleAttrs?: Partial<Record<PanelId, ShellAttrs>>;
+    /** Attributes per band, rendered on the band's element (e.g. `data-testid`). */
+    bandAttrs?: Partial<Record<PanelId | 'footer', ShellAttrs>>;
 }

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

@@ -3,7 +3,7 @@
  * 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';
+import type { PanelId, PanelState, PanelLabels, ToolbarSpec, ShellAttrs, 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). */
@@ -22,6 +22,8 @@ interface ToolbarContext {
     icons: PanelLabels;
     /** Appended to a busy action's label. */
     busy?: string;
+    /** Attributes per band toggle, rendered on its toolbar button. */
+    toggleAttrs?: Partial<Record<PanelId, ShellAttrs>>;
 }
 /**
  * The toolbar's items: the screen's own buttons, a separator, then one toggle per band the

package/dist/utils/screen-shell.js

@@ -38,23 +38,32 @@ function toToolbarItem(item, busy = '') {
         disabled: Boolean(action.disabled || action.busy)
     };
 }
+/** A panel toggle with the band's attrs under its own (its own keys win). */
+function withToggleAttrs(item, band) {
+    if (!band && item.attrs === undefined)
+        return item;
+    return { ...item, attrs: { ...band, ...(item.attrs ?? {}) } };
+}
 /** One toggle per band, pressed while the band is open. */
 function panelToggle(id, ctx) {
-    return {
+    return withToggleAttrs({
         id,
         value: id,
         type: 'toggle',
         icon: ctx.icons[id],
         label: ctx.labels[id],
         active: isOpen(ctx.panels, id)
-    };
+    }, ctx.toggleAttrs?.[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) }
+        ? {
+            ...withToggleAttrs(item, ctx.toggleAttrs?.[item.value]),
+            active: isOpen(ctx.panels, item.value)
+        }
         : item.type === 'separator' || item.type === 'spacer'
             ? item
             : toToolbarItem(item, ctx.busy));

package/package.json

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