From cd756467d6d4938978a20f8ad6862a21aa15cff8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?ay=C5=9Feturmusn?= <trmsays@gmail.com>
Date: Fri, 30 Jan 2026 15:21:40 +0300
Subject: [PATCH 1/2] feat(DashboardLayout): add layout component with stories
 and button readability on active/focus

---
 .../utility/DashboardLayout.stories.svelte    | 249 ++++++++++++++++++
 .../utility/utility/DashboardLayout.svelte    | 220 ++++++++++++++++
 2 files changed, 469 insertions(+)
 create mode 100644 hexawebshare/src/components/utility/utility/DashboardLayout.stories.svelte

diff --git a/hexawebshare/src/components/utility/utility/DashboardLayout.stories.svelte b/hexawebshare/src/components/utility/utility/DashboardLayout.stories.svelte
new file mode 100644
index 00000000..9ba8469a
--- /dev/null
+++ b/hexawebshare/src/components/utility/utility/DashboardLayout.stories.svelte
@@ -0,0 +1,249 @@
+<!--
+SPDX-FileCopyrightText: 2025 hexaTune LLC
+SPDX-License-Identifier: MIT
+-->
+
+<script module lang="ts">
+	import { defineMeta } from '@storybook/addon-svelte-csf';
+	import DashboardLayout from './DashboardLayout.svelte';
+
+	const { Story } = defineMeta({
+		title: 'Utility/Utility/DashboardLayout',
+		component: DashboardLayout,
+		tags: ['autodocs'],
+		argTypes: {
+			variant: {
+				control: { type: 'select' },
+				options: ['default', 'bordered', 'filled'],
+				description: 'Visual variant of the layout'
+			},
+			sidebarPosition: {
+				control: { type: 'select' },
+				options: ['left', 'right'],
+				description: 'Sidebar position'
+			},
+			loading: { control: 'boolean', description: 'Show loading state' },
+			disabled: { control: 'boolean', description: 'Disable layout interaction' },
+			error: { control: 'boolean', description: 'Show error state' },
+			errorMessage: { control: 'text', description: 'Error message when error is true' },
+			ariaLabel: { control: 'text', description: 'Accessible label for layout' },
+			loadingLabel: { control: 'text', description: 'Accessible label for loading spinner' },
+			mainAriaLabel: { control: 'text', description: 'Accessible label for main content' },
+			sidebarAriaLabel: { control: 'text', description: 'Accessible label for sidebar' },
+			sidebarTitle: { control: 'text', description: 'Sidebar title when using sidebarItems' },
+			sidebarSubtitle: { control: 'text', description: 'Sidebar subtitle when using sidebarItems' },
+			sidebarWidth: {
+				control: { type: 'select' },
+				options: ['narrow', 'default', 'wide'],
+				description: 'Sidebar width when using sidebarItems'
+			},
+			sidebarSize: {
+				control: { type: 'select' },
+				options: ['sm', 'md', 'lg'],
+				description: 'Sidebar item size when using sidebarItems'
+			},
+			sidebarVariant: {
+				control: { type: 'select' },
+				options: ['default', 'compact', 'bordered'],
+				description: 'Sidebar variant when using sidebarItems'
+			}
+		}
+	});
+</script>
+
+<script lang="ts">
+	import type { SidebarItem } from '../../core/overlay-navigation/Sidebar.svelte';
+	import Heading from '../../core/typography/Heading.svelte';
+	import Text from '../../core/typography/Text.svelte';
+	import Paragraph from '../../core/typography/Paragraph.svelte';
+	import Button from '../../core/buttons/Button.svelte';
+	import Card from '../../core/layout/Card.svelte';
+	import Grid from '../../core/layout/Grid.svelte';
+	import Container from '../../core/layout/Container.svelte';
+
+	const defaultSidebarItems: SidebarItem[] = [
+		{ id: 'overview', label: 'Overview', icon: '📊', active: true },
+		{ id: 'analytics', label: 'Analytics', icon: '📈' },
+		{ id: 'reports', label: 'Reports', icon: '📋', badge: 3, badgeVariant: 'primary' },
+		{ id: 'settings', label: 'Settings', icon: '⚙️' }
+	];
+</script>
+
+{#snippet headerSnippet()}
+	<div
+		class="flex min-w-0 flex-wrap items-center justify-between gap-2 px-3 py-2 sm:gap-4 sm:px-4 sm:py-3 lg:px-6"
+	>
+		<Heading level="h1" size="lg" text="Dashboard" class="min-w-0 shrink" />
+		<Button label="Refresh" variant="primary" size="sm" class="shrink-0" />
+	</div>
+{/snippet}
+
+{#snippet mainSnippet()}
+	<Container maxWidth="6xl" padding="lg" centered className="min-w-0 py-6">
+		{#snippet children()}
+			<Heading level="h2" size="md" text="Overview" />
+			<Paragraph
+				variant="muted"
+				text="Use this layout for dashboard pages with optional header, sidebar, and footer."
+			/>
+			<Grid columns={1} gap="md" responsiveColumns={{ sm: 2, lg: 3 }} class="mt-6 min-w-0">
+				{#snippet children()}
+					<Card>
+						{#snippet children()}
+							<Text text="Card 1" variant="primary" />
+							<Paragraph variant="muted" size="sm" text="Sample widget content." />
+						{/snippet}
+					</Card>
+					<Card>
+						{#snippet children()}
+							<Text text="Card 2" variant="primary" />
+							<Paragraph variant="muted" size="sm" text="Sample widget content." />
+						{/snippet}
+					</Card>
+					<Card>
+						{#snippet children()}
+							<Text text="Card 3" variant="primary" />
+							<Paragraph variant="muted" size="sm" text="Sample widget content." />
+						{/snippet}
+					</Card>
+				{/snippet}
+			</Grid>
+		{/snippet}
+	</Container>
+{/snippet}
+
+{#snippet sidebarSnippet()}
+	<nav class="flex flex-col gap-1 p-4 lg:p-6" aria-label="Dashboard filters">
+		<Text text="Filters" variant="primary" />
+		<a href="#date-range" class="link link-primary link-hover text-sm">Date range</a>
+		<a href="#category" class="link link-primary link-hover text-sm">Category</a>
+		<a href="#status" class="link link-primary link-hover text-sm">Status</a>
+	</nav>
+{/snippet}
+
+{#snippet footerSnippet()}
+	<div class="flex items-center justify-center gap-2 px-4 py-3 text-sm opacity-70">
+		<Text text="© 2025 hexaWebShare" />
+	</div>
+{/snippet}
+
+<Story name="Default" args={{ children: mainSnippet }} />
+
+<Story
+	name="With Header"
+	args={{
+		header: headerSnippet,
+		children: mainSnippet
+	}}
+/>
+
+<Story
+	name="With Sidebar Left"
+	args={{
+		header: headerSnippet,
+		sidebar: sidebarSnippet,
+		sidebarPosition: 'left',
+		children: mainSnippet
+	}}
+/>
+
+<Story
+	name="With Core Sidebar"
+	args={{
+		header: headerSnippet,
+		sidebarItems: defaultSidebarItems,
+		sidebarTitle: 'Dashboard',
+		sidebarSubtitle: 'Navigation',
+		sidebarWidth: 'default',
+		sidebarSize: 'md',
+		sidebarVariant: 'default',
+		sidebarPosition: 'left',
+		sidebarAriaLabel: 'Dashboard navigation',
+		children: mainSnippet
+	}}
+/>
+
+<Story
+	name="With Footer"
+	args={{
+		header: headerSnippet,
+		children: mainSnippet,
+		footer: footerSnippet
+	}}
+/>
+
+<Story
+	name="Bordered Variant"
+	args={{
+		variant: 'bordered',
+		header: headerSnippet,
+		children: mainSnippet,
+		footer: footerSnippet
+	}}
+/>
+
+<Story
+	name="Filled Variant"
+	args={{
+		variant: 'filled',
+		header: headerSnippet,
+		sidebar: sidebarSnippet,
+		sidebarPosition: 'left',
+		children: mainSnippet,
+		footer: footerSnippet
+	}}
+/>
+
+<Story
+	name="Loading State"
+	args={{
+		loading: true,
+		header: headerSnippet,
+		children: mainSnippet,
+		loadingLabel: 'Loading dashboard…'
+	}}
+/>
+
+<Story
+	name="Disabled State"
+	args={{
+		disabled: true,
+		header: headerSnippet,
+		children: mainSnippet
+	}}
+/>
+
+<Story
+	name="Error State"
+	args={{
+		error: true,
+		errorMessage: 'Failed to load dashboard data. Please try again.',
+		header: headerSnippet,
+		children: mainSnippet
+	}}
+/>
+
+<Story
+	name="Playground"
+	args={{
+		variant: 'default',
+		sidebarPosition: 'left',
+		sidebarWidth: 'default',
+		sidebarSize: 'md',
+		sidebarVariant: 'default',
+		loading: false,
+		disabled: false,
+		error: false,
+		errorMessage: 'An error occurred. Please try again.',
+		ariaLabel: 'Dashboard layout',
+		loadingLabel: 'Loading content',
+		mainAriaLabel: 'Main content',
+		sidebarAriaLabel: 'Sidebar',
+		sidebarTitle: 'Dashboard',
+		sidebarSubtitle: 'Navigation',
+		header: headerSnippet,
+		sidebarItems: defaultSidebarItems,
+		children: mainSnippet,
+		footer: footerSnippet
+	}}
+/>
diff --git a/hexawebshare/src/components/utility/utility/DashboardLayout.svelte b/hexawebshare/src/components/utility/utility/DashboardLayout.svelte
index 315da078..b9bbfd01 100644
--- a/hexawebshare/src/components/utility/utility/DashboardLayout.svelte
+++ b/hexawebshare/src/components/utility/utility/DashboardLayout.svelte
@@ -2,3 +2,223 @@
 SPDX-FileCopyrightText: 2025 hexaTune LLC
 SPDX-License-Identifier: MIT
 -->
+
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { SidebarItem } from '../../core/overlay-navigation/Sidebar.svelte';
+	import Sidebar from '../../core/overlay-navigation/Sidebar.svelte';
+	import Spinner from '../../core/feedback/Spinner.svelte';
+	import Alert from '../../core/feedback/Alert.svelte';
+
+	interface Props {
+		/** Header content (e.g. title, toolbar) */
+		header?: Snippet;
+		/** Main content area */
+		children?: Snippet;
+		/** Optional sidebar content (e.g. filters, custom UI). Use either this or sidebarItems. */
+		sidebar?: Snippet;
+		/** Optional sidebar items for programmatic nav. Uses core Sidebar when provided. */
+		sidebarItems?: SidebarItem[];
+		/** Sidebar title when using sidebarItems */
+		sidebarTitle?: string;
+		/** Sidebar subtitle when using sidebarItems */
+		sidebarSubtitle?: string;
+		/** Sidebar width when using sidebarItems */
+		sidebarWidth?: 'narrow' | 'default' | 'wide';
+		/** Sidebar item size when using sidebarItems */
+		sidebarSize?: 'sm' | 'md' | 'lg';
+		/** Sidebar variant when using sidebarItems */
+		sidebarVariant?: 'default' | 'compact' | 'bordered';
+		/** Optional footer content */
+		footer?: Snippet;
+		/** Sidebar position */
+		sidebarPosition?: 'left' | 'right';
+		/** Visual variant */
+		variant?: 'default' | 'bordered' | 'filled';
+		/** Show loading overlay and disable interaction */
+		loading?: boolean;
+		/** Disable layout interaction */
+		disabled?: boolean;
+		/** Show error state with message */
+		error?: boolean;
+		/** Error message when error is true */
+		errorMessage?: string;
+		/** Accessible label for the layout container */
+		ariaLabel?: string;
+		/** Accessible label for the loading spinner */
+		loadingLabel?: string;
+		/** Accessible label for the main content region */
+		mainAriaLabel?: string;
+		/** Accessible label for the sidebar region */
+		sidebarAriaLabel?: string;
+		/** Additional CSS classes */
+		class?: string;
+	}
+
+	const {
+		header,
+		children,
+		sidebar,
+		sidebarItems,
+		sidebarTitle = '',
+		sidebarSubtitle = '',
+		sidebarWidth = 'default',
+		sidebarSize = 'md',
+		sidebarVariant = 'default',
+		footer,
+		sidebarPosition = 'left',
+		variant = 'default',
+		loading = false,
+		disabled = false,
+		error = false,
+		errorMessage = 'An error occurred. Please try again.',
+		ariaLabel = 'Dashboard layout',
+		loadingLabel = 'Loading content',
+		mainAriaLabel = 'Main content',
+		sidebarAriaLabel = 'Sidebar',
+		class: className = '',
+		...props
+	}: Props = $props();
+
+	let layoutClasses = $derived(
+		[
+			'dashboard-layout',
+			'flex',
+			'flex-col',
+			'w-full',
+			'max-w-full',
+			'min-h-screen',
+			'min-w-0',
+			'overflow-x-hidden',
+			'bg-base-100',
+			variant === 'bordered' && 'border border-base-300',
+			variant === 'filled' && 'bg-base-200',
+			disabled && 'opacity-50 pointer-events-none',
+			'[&_.btn:active]:!opacity-100',
+			'[&_.btn:focus]:!opacity-100',
+			'[&_button:active]:!opacity-100',
+			'[&_button:focus]:!opacity-100',
+			className
+		]
+			.filter(Boolean)
+			.join(' ')
+	);
+
+	let hasSidebar = $derived(sidebar || (sidebarItems != null && sidebarItems.length > 0));
+
+	let contentWrapperClasses = $derived(
+		[
+			'dashboard-content-wrapper',
+			'flex',
+			'w-full',
+			'flex-1',
+			'overflow-hidden',
+			'flex-col',
+			hasSidebar && 'lg:flex-row'
+		]
+			.filter(Boolean)
+			.join(' ')
+	);
+
+	let sidebarOrderClasses = $derived(
+		sidebarPosition === 'left' ? 'lg:order-first' : 'lg:order-last'
+	);
+
+	let mainOrderClasses = $derived(sidebarPosition === 'left' ? 'lg:order-last' : 'lg:order-first');
+
+	let sidebarConfig = $derived.by(() => {
+		if (!hasSidebar || sidebar || !sidebarItems?.length) return null;
+		return {
+			items: sidebarItems,
+			title: sidebarTitle,
+			subtitle: sidebarSubtitle,
+			width: sidebarWidth,
+			size: sidebarSize,
+			variant: sidebarVariant,
+			ariaLabel: sidebarAriaLabel
+		};
+	});
+
+	let sidebarVariantOverrides = $derived.by(() => {
+		if (!sidebarConfig) return '';
+		if (sidebarVariant === 'compact')
+			return '[&_.menu]:!p-1.5 [&_.menu]:!gap-0.5 [&_[role=menuitem]]:!py-1.5 [&_[role=menuitem]]:!px-2 [&_[role=menuitem]]:!gap-2 [&_[role=menuitem]]:!text-sm';
+		if (sidebarVariant === 'bordered') return 'ring-2 ring-base-300 ring-inset';
+		return '';
+	});
+
+	let sidebarAsideClasses = $derived(
+		[
+			'dashboard-sidebar',
+			'border-base-300',
+			'bg-base-100',
+			'w-full',
+			'min-w-0',
+			'shrink-0',
+			'border-b',
+			'lg:w-64',
+			'lg:border-r',
+			'lg:border-b-0',
+			'xl:w-72',
+			sidebarOrderClasses,
+			sidebarVariantOverrides
+		]
+			.filter(Boolean)
+			.join(' ')
+	);
+</script>
+
+<!--
+	NOTE: Structural HTML elements (div, header, main, aside, footer) are used
+	as semantic layout containers. No library components exist for these layout
+	primitives; they are required for correct HTML semantics and responsive layout.
+-->
+<div class={layoutClasses} role="main" aria-label={ariaLabel} aria-busy={loading} {...props}>
+	{#if header}
+		<header
+			class="dashboard-header border-base-300 bg-base-100 sticky top-0 z-40 min-w-0 shrink-0 border-b"
+		>
+			{@render header()}
+		</header>
+	{/if}
+
+	<div class={contentWrapperClasses}>
+		{#if hasSidebar}
+			<aside class={sidebarAsideClasses} aria-label={sidebarAriaLabel}>
+				{#if sidebar}
+					{@render sidebar()}
+				{:else if sidebarConfig}
+					<Sidebar {...sidebarConfig} />
+				{/if}
+			</aside>
+		{/if}
+
+		<main
+			class="dashboard-main bg-base-100 flex min-w-0 flex-1 flex-col overflow-auto {mainOrderClasses}"
+			aria-label={mainAriaLabel}
+		>
+			{#if loading}
+				<div class="flex flex-1 items-center justify-center p-8">
+					<Spinner size="lg" variant="primary" ariaLabel={loadingLabel} />
+				</div>
+			{:else if error}
+				<div class="p-4 lg:p-6">
+					<Alert variant="error" title={errorMessage} withIcon={true} />
+					{#if children}
+						<div class="mt-4">
+							{@render children()}
+						</div>
+					{/if}
+				</div>
+			{:else if children}
+				{@render children()}
+			{/if}
+		</main>
+	</div>
+
+	{#if footer}
+		<footer class="dashboard-footer border-base-300 bg-base-100 min-w-0 shrink-0 border-t">
+			{@render footer()}
+		</footer>
+	{/if}
+</div>

From c0b2d87f1fbbae9f4de1acca8e9a1be4b4c254e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?ay=C5=9Feturmusn?= <trmsays@gmail.com>
Date: Sat, 31 Jan 2026 18:14:23 +0300
Subject: [PATCH 2/2] feat(DashboardLayout): add onRefresh callback, use Row
 for loading state and Storybook actions

---
 .../utility/DashboardLayout.stories.svelte    | 27 ++++++++++++++-----
 .../utility/utility/DashboardLayout.svelte    | 19 +++++++++----
 2 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/hexawebshare/src/components/utility/utility/DashboardLayout.stories.svelte b/hexawebshare/src/components/utility/utility/DashboardLayout.stories.svelte
index 9ba8469a..6e276ba2 100644
--- a/hexawebshare/src/components/utility/utility/DashboardLayout.stories.svelte
+++ b/hexawebshare/src/components/utility/utility/DashboardLayout.stories.svelte
@@ -5,6 +5,7 @@ SPDX-License-Identifier: MIT
 
 <script module lang="ts">
 	import { defineMeta } from '@storybook/addon-svelte-csf';
+	import { fn } from 'storybook/test';
 	import DashboardLayout from './DashboardLayout.svelte';
 
 	const { Story } = defineMeta({
@@ -12,6 +13,10 @@ SPDX-License-Identifier: MIT
 		component: DashboardLayout,
 		tags: ['autodocs'],
 		argTypes: {
+			onRefresh: {
+				action: 'onRefresh',
+				description: 'Callback when refresh button is clicked'
+			},
 			variant: {
 				control: { type: 'select' },
 				options: ['default', 'bordered', 'filled'],
@@ -47,6 +52,9 @@ SPDX-License-Identifier: MIT
 				options: ['default', 'compact', 'bordered'],
 				description: 'Sidebar variant when using sidebarItems'
 			}
+		},
+		args: {
+			onRefresh: fn()
 		}
 	});
 </script>
@@ -62,19 +70,26 @@ SPDX-License-Identifier: MIT
 	import Container from '../../core/layout/Container.svelte';
 
 	const defaultSidebarItems: SidebarItem[] = [
-		{ id: 'overview', label: 'Overview', icon: '📊', active: true },
-		{ id: 'analytics', label: 'Analytics', icon: '📈' },
-		{ id: 'reports', label: 'Reports', icon: '📋', badge: 3, badgeVariant: 'primary' },
-		{ id: 'settings', label: 'Settings', icon: '⚙️' }
+		{ id: 'overview', label: 'Overview', icon: '📊', active: true, onClick: fn() },
+		{ id: 'analytics', label: 'Analytics', icon: '📈', onClick: fn() },
+		{
+			id: 'reports',
+			label: 'Reports',
+			icon: '📋',
+			badge: 3,
+			badgeVariant: 'primary',
+			onClick: fn()
+		},
+		{ id: 'settings', label: 'Settings', icon: '⚙️', onClick: fn() }
 	];
 </script>
 
-{#snippet headerSnippet()}
+{#snippet headerSnippet({ onRefresh }: { onRefresh?: () => void })}
 	<div
 		class="flex min-w-0 flex-wrap items-center justify-between gap-2 px-3 py-2 sm:gap-4 sm:px-4 sm:py-3 lg:px-6"
 	>
 		<Heading level="h1" size="lg" text="Dashboard" class="min-w-0 shrink" />
-		<Button label="Refresh" variant="primary" size="sm" class="shrink-0" />
+		<Button label="Refresh" variant="primary" size="sm" class="shrink-0" onclick={onRefresh} />
 	</div>
 {/snippet}
 
diff --git a/hexawebshare/src/components/utility/utility/DashboardLayout.svelte b/hexawebshare/src/components/utility/utility/DashboardLayout.svelte
index b9bbfd01..72076f1e 100644
--- a/hexawebshare/src/components/utility/utility/DashboardLayout.svelte
+++ b/hexawebshare/src/components/utility/utility/DashboardLayout.svelte
@@ -7,12 +7,20 @@ SPDX-License-Identifier: MIT
 	import type { Snippet } from 'svelte';
 	import type { SidebarItem } from '../../core/overlay-navigation/Sidebar.svelte';
 	import Sidebar from '../../core/overlay-navigation/Sidebar.svelte';
+	import Row from '../../core/layout/Row.svelte';
 	import Spinner from '../../core/feedback/Spinner.svelte';
 	import Alert from '../../core/feedback/Alert.svelte';
 
+	/** Context passed to header snippet (e.g. onRefresh for toolbar actions) */
+	interface HeaderContext {
+		onRefresh?: () => void;
+	}
+
 	interface Props {
-		/** Header content (e.g. title, toolbar) */
-		header?: Snippet;
+		/** Callback when refresh action is triggered (passed to header snippet) */
+		onRefresh?: () => void;
+		/** Header content (e.g. title, toolbar). Receives { onRefresh } for action callbacks. */
+		header?: Snippet<[HeaderContext]>;
 		/** Main content area */
 		children?: Snippet;
 		/** Optional sidebar content (e.g. filters, custom UI). Use either this or sidebarItems. */
@@ -56,6 +64,7 @@ SPDX-License-Identifier: MIT
 	}
 
 	const {
+		onRefresh,
 		header,
 		children,
 		sidebar,
@@ -178,7 +187,7 @@ SPDX-License-Identifier: MIT
 		<header
 			class="dashboard-header border-base-300 bg-base-100 sticky top-0 z-40 min-w-0 shrink-0 border-b"
 		>
-			{@render header()}
+			{@render header({ onRefresh })}
 		</header>
 	{/if}
 
@@ -198,9 +207,9 @@ SPDX-License-Identifier: MIT
 			aria-label={mainAriaLabel}
 		>
 			{#if loading}
-				<div class="flex flex-1 items-center justify-center p-8">
+				<Row align="center" justify="center" gap="0" class="flex-1 p-8" ariaLabel={loadingLabel}>
 					<Spinner size="lg" variant="primary" ariaLabel={loadingLabel} />
-				</div>
+				</Row>
 			{:else if error}
 				<div class="p-4 lg:p-6">
 					<Alert variant="error" title={errorMessage} withIcon={true} />