From edeab0f22a87e6586e5d96fbf178e9cb5337dc35 Mon Sep 17 00:00:00 2001
From: krmlp <keremalparslan@gmail.com>
Date: Tue, 27 Jan 2026 18:19:37 +0300
Subject: [PATCH 1/2] feat(AdminSidebar): implement component with Storybook
 stories

- Add full AdminSidebar implementation with Svelte 5 runes
- Include comprehensive Props interface with no default values
- Add size-responsive styling (sm/md/lg) with derived classes
- Add 11 Storybook stories including Playground
- Follow AGENTS.md rules for raw HTML documentation
- Use core library components (Dropdown, Button, Badge, Icon, etc.)
- Export component and AdminSidebarItem type from index.ts

Closes #217
---
 .../admin/layout/AdminSidebar.stories.svelte  | 423 ++++++++++++++++
 .../admin/layout/AdminSidebar.svelte          | 455 ++++++++++++++++++
 hexawebshare/src/lib/index.ts                 |   2 +
 3 files changed, 880 insertions(+)
 create mode 100644 hexawebshare/src/components/admin/layout/AdminSidebar.stories.svelte

diff --git a/hexawebshare/src/components/admin/layout/AdminSidebar.stories.svelte b/hexawebshare/src/components/admin/layout/AdminSidebar.stories.svelte
new file mode 100644
index 00000000..2fb6b0c2
--- /dev/null
+++ b/hexawebshare/src/components/admin/layout/AdminSidebar.stories.svelte
@@ -0,0 +1,423 @@
+<!--
+SPDX-FileCopyrightText: 2025 hexaTune LLC
+SPDX-License-Identifier: MIT
+-->
+
+<script module lang="ts">
+	import { defineMeta } from '@storybook/addon-svelte-csf';
+	import AdminSidebar from './AdminSidebar.svelte';
+	import type { AdminSidebarItem } from './AdminSidebar.svelte';
+
+	const defaultItems: AdminSidebarItem[] = [
+		{ id: 'dashboard', label: 'Dashboard', icon: 'D', active: true },
+		{ id: 'users', label: 'Users', icon: 'U', badge: 24 },
+		{ id: 'products', label: 'Products', icon: 'P' },
+		{ id: 'orders', label: 'Orders', icon: 'O', badge: 8, badgeVariant: 'success' },
+		{ id: 'analytics', label: 'Analytics', icon: 'A' },
+		{ id: 'settings', label: 'Settings', icon: 'S' }
+	];
+
+	const itemsWithDropdown: AdminSidebarItem[] = [
+		{ id: 'dashboard', label: 'Dashboard', icon: 'D', active: true },
+		{
+			id: 'users',
+			label: 'Users',
+			icon: 'U',
+			badge: 24,
+			children: [
+				{ id: 'users-list', label: 'All Users' },
+				{ id: 'users-active', label: 'Active Users' },
+				{ id: 'users-inactive', label: 'Inactive Users' },
+				{ id: 'users-add', label: 'Add User' }
+			]
+		},
+		{
+			id: 'products',
+			label: 'Products',
+			icon: 'P',
+			children: [
+				{ id: 'products-list', label: 'All Products' },
+				{ id: 'products-categories', label: 'Categories' },
+				{ id: 'products-inventory', label: 'Inventory' }
+			]
+		},
+		{ id: 'orders', label: 'Orders', icon: 'O', badge: 8, badgeVariant: 'success' },
+		{ id: 'analytics', label: 'Analytics', icon: 'A' },
+		{ id: 'settings', label: 'Settings', icon: 'S' }
+	];
+
+	const itemsWithBadges: AdminSidebarItem[] = [
+		{ id: 'inbox', label: 'Inbox', icon: 'I', badge: 12, badgeVariant: 'primary' },
+		{ id: 'alerts', label: 'Alerts', icon: 'A', badge: 3, badgeVariant: 'error' },
+		{ id: 'pending', label: 'Pending', icon: 'P', badge: 5, badgeVariant: 'warning' },
+		{ id: 'completed', label: 'Completed', icon: 'C', badge: 28, badgeVariant: 'success' },
+		{ id: 'info', label: 'Information', icon: 'i', badge: 2, badgeVariant: 'info' }
+	];
+
+	const itemsWithDisabled: AdminSidebarItem[] = [
+		{ id: 'dashboard', label: 'Dashboard', icon: 'D', active: true },
+		{ id: 'users', label: 'Users', icon: 'U' },
+		{ id: 'products', label: 'Products', icon: 'P', disabled: true },
+		{ id: 'orders', label: 'Orders', icon: 'O', disabled: true },
+		{ id: 'analytics', label: 'Analytics', icon: 'A' },
+		{ id: 'settings', label: 'Settings', icon: 'S' }
+	];
+
+	const { Story } = defineMeta({
+		title: 'Admin/Layout/AdminSidebar',
+		component: AdminSidebar,
+		tags: ['autodocs'],
+		argTypes: {
+			variant: {
+				control: { type: 'select' },
+				options: ['default', 'compact', 'bordered']
+			},
+			size: {
+				control: { type: 'select' },
+				options: ['sm', 'md', 'lg']
+			},
+			width: {
+				control: { type: 'select' },
+				options: ['narrow', 'default', 'wide']
+			},
+			defaultBadgeVariant: {
+				control: { type: 'select' },
+				options: ['primary', 'secondary', 'accent', 'info', 'success', 'warning', 'error']
+			},
+			sidebarId: {
+				control: { type: 'text' }
+			},
+			headerMinHeightClass: {
+				control: { type: 'text' }
+			},
+			collapsed: { control: 'boolean' },
+			collapsible: { control: 'boolean' },
+			sticky: { control: 'boolean' },
+			disabled: { control: 'boolean' },
+			loading: { control: 'boolean' }
+		}
+	});
+</script>
+
+<script lang="ts">
+	let playgroundCollapsed = $state(false);
+</script>
+
+<Story name="Default">
+	{#snippet children()}
+		<div class="h-[500px]">
+			<AdminSidebar
+				items={defaultItems}
+				title="Admin Panel"
+				subtitle="Navigation"
+				variant="default"
+				size="md"
+				width="default"
+				collapsed={false}
+				collapsible={true}
+				sticky={false}
+				disabled={false}
+				loading={false}
+				ariaLabel="Admin sidebar navigation"
+				expandAriaLabel="Expand sidebar"
+				collapseAriaLabel="Collapse sidebar"
+				sidebarId="admin-sidebar-default"
+				defaultBadgeVariant="primary"
+				headerMinHeightClass="min-h-16"
+				onItemClick={(item) => console.log('Clicked:', item.label)}
+				onCollapse={(c) => console.log('Collapsed:', c)}
+				class=""
+			/>
+		</div>
+	{/snippet}
+</Story>
+
+<Story name="With Dropdown Items">
+	{#snippet children()}
+		<div class="h-[500px]">
+			<AdminSidebar
+				items={itemsWithDropdown}
+				title="Admin Panel"
+				subtitle="With Nested Menus"
+				variant="default"
+				size="md"
+				width="default"
+				collapsed={false}
+				collapsible={true}
+				sticky={false}
+				disabled={false}
+				loading={false}
+				ariaLabel="Admin sidebar with dropdown menus"
+				expandAriaLabel="Expand sidebar"
+				collapseAriaLabel="Collapse sidebar"
+				sidebarId="admin-sidebar-default"
+				defaultBadgeVariant="primary"
+				headerMinHeightClass="min-h-16"
+				onItemClick={(item) => console.log('Clicked:', item.label)}
+				onCollapse={(c) => console.log('Collapsed:', c)}
+				class=""
+			/>
+		</div>
+	{/snippet}
+</Story>
+
+<Story name="Collapsed State">
+	{#snippet children()}
+		<div class="h-[500px]">
+			<AdminSidebar
+				items={defaultItems}
+				title="Admin Panel"
+				subtitle="Navigation"
+				variant="default"
+				size="md"
+				width="default"
+				collapsed={true}
+				collapsible={true}
+				sticky={false}
+				disabled={false}
+				loading={false}
+				ariaLabel="Collapsed admin sidebar"
+				expandAriaLabel="Expand sidebar"
+				collapseAriaLabel="Collapse sidebar"
+				sidebarId="admin-sidebar-default"
+				defaultBadgeVariant="primary"
+				headerMinHeightClass="min-h-16"
+				onItemClick={(item) => console.log('Clicked:', item.label)}
+				onCollapse={(c) => console.log('Collapsed:', c)}
+				class=""
+			/>
+		</div>
+	{/snippet}
+</Story>
+
+<Story name="With Badge Variants">
+	{#snippet children()}
+		<div class="h-[500px]">
+			<AdminSidebar
+				items={itemsWithBadges}
+				title="Notifications"
+				subtitle="Badge Examples"
+				variant="default"
+				size="md"
+				width="default"
+				collapsed={false}
+				collapsible={true}
+				sticky={false}
+				disabled={false}
+				loading={false}
+				ariaLabel="Sidebar with badge variants"
+				expandAriaLabel="Expand sidebar"
+				collapseAriaLabel="Collapse sidebar"
+				sidebarId="admin-sidebar-default"
+				defaultBadgeVariant="primary"
+				headerMinHeightClass="min-h-16"
+				onItemClick={(item) => console.log('Clicked:', item.label)}
+				onCollapse={(c) => console.log('Collapsed:', c)}
+				class=""
+			/>
+		</div>
+	{/snippet}
+</Story>
+
+<Story name="Compact Variant">
+	{#snippet children()}
+		<div class="h-[500px]">
+			<AdminSidebar
+				items={defaultItems}
+				title="Admin Panel"
+				subtitle="Compact Mode"
+				variant="compact"
+				size="sm"
+				width="narrow"
+				collapsed={false}
+				collapsible={true}
+				sticky={false}
+				disabled={false}
+				loading={false}
+				ariaLabel="Compact admin sidebar"
+				expandAriaLabel="Expand sidebar"
+				collapseAriaLabel="Collapse sidebar"
+				sidebarId="admin-sidebar-default"
+				defaultBadgeVariant="primary"
+				headerMinHeightClass="min-h-16"
+				onItemClick={(item) => console.log('Clicked:', item.label)}
+				onCollapse={(c) => console.log('Collapsed:', c)}
+				class=""
+			/>
+		</div>
+	{/snippet}
+</Story>
+
+<Story name="Bordered Variant">
+	{#snippet children()}
+		<div class="h-[500px]">
+			<AdminSidebar
+				items={defaultItems}
+				title="Admin Panel"
+				subtitle="Bordered Style"
+				variant="bordered"
+				size="md"
+				width="default"
+				collapsed={false}
+				collapsible={true}
+				sticky={false}
+				disabled={false}
+				loading={false}
+				ariaLabel="Bordered admin sidebar"
+				expandAriaLabel="Expand sidebar"
+				collapseAriaLabel="Collapse sidebar"
+				sidebarId="admin-sidebar-default"
+				defaultBadgeVariant="primary"
+				headerMinHeightClass="min-h-16"
+				onItemClick={(item) => console.log('Clicked:', item.label)}
+				onCollapse={(c) => console.log('Collapsed:', c)}
+				class=""
+			/>
+		</div>
+	{/snippet}
+</Story>
+
+<Story name="Wide Width">
+	{#snippet children()}
+		<div class="h-[500px]">
+			<AdminSidebar
+				items={defaultItems}
+				title="Admin Panel"
+				subtitle="Wide Sidebar"
+				variant="default"
+				size="lg"
+				width="wide"
+				collapsed={false}
+				collapsible={true}
+				sticky={false}
+				disabled={false}
+				loading={false}
+				ariaLabel="Wide admin sidebar"
+				expandAriaLabel="Expand sidebar"
+				collapseAriaLabel="Collapse sidebar"
+				sidebarId="admin-sidebar-default"
+				defaultBadgeVariant="primary"
+				headerMinHeightClass="min-h-16"
+				onItemClick={(item) => console.log('Clicked:', item.label)}
+				onCollapse={(c) => console.log('Collapsed:', c)}
+				class=""
+			/>
+		</div>
+	{/snippet}
+</Story>
+
+<Story name="Loading State">
+	{#snippet children()}
+		<div class="h-[500px]">
+			<AdminSidebar
+				items={defaultItems}
+				title="Admin Panel"
+				subtitle="Loading..."
+				variant="default"
+				size="md"
+				width="default"
+				collapsed={false}
+				collapsible={false}
+				sticky={false}
+				disabled={false}
+				loading={true}
+				ariaLabel="Loading admin sidebar"
+				expandAriaLabel="Expand sidebar"
+				collapseAriaLabel="Collapse sidebar"
+				sidebarId="admin-sidebar-default"
+				defaultBadgeVariant="primary"
+				headerMinHeightClass="min-h-16"
+				onItemClick={(item) => console.log('Clicked:', item.label)}
+				onCollapse={(c) => console.log('Collapsed:', c)}
+				class=""
+			/>
+		</div>
+	{/snippet}
+</Story>
+
+<Story name="Disabled State">
+	{#snippet children()}
+		<div class="h-[500px]">
+			<AdminSidebar
+				items={defaultItems}
+				title="Admin Panel"
+				subtitle="Disabled"
+				variant="default"
+				size="md"
+				width="default"
+				collapsed={false}
+				collapsible={true}
+				sticky={false}
+				disabled={true}
+				loading={false}
+				ariaLabel="Disabled admin sidebar"
+				expandAriaLabel="Expand sidebar"
+				collapseAriaLabel="Collapse sidebar"
+				sidebarId="admin-sidebar-default"
+				defaultBadgeVariant="primary"
+				headerMinHeightClass="min-h-16"
+				onItemClick={(item) => console.log('Clicked:', item.label)}
+				onCollapse={(c) => console.log('Collapsed:', c)}
+				class=""
+			/>
+		</div>
+	{/snippet}
+</Story>
+
+<Story name="Disabled Items">
+	{#snippet children()}
+		<div class="h-[500px]">
+			<AdminSidebar
+				items={itemsWithDisabled}
+				title="Admin Panel"
+				subtitle="Some Items Disabled"
+				variant="default"
+				size="md"
+				width="default"
+				collapsed={false}
+				collapsible={true}
+				sticky={false}
+				disabled={false}
+				loading={false}
+				ariaLabel="Sidebar with disabled items"
+				expandAriaLabel="Expand sidebar"
+				collapseAriaLabel="Collapse sidebar"
+				sidebarId="admin-sidebar-default"
+				defaultBadgeVariant="primary"
+				headerMinHeightClass="min-h-16"
+				onItemClick={(item) => console.log('Clicked:', item.label)}
+				onCollapse={(c) => console.log('Collapsed:', c)}
+				class=""
+			/>
+		</div>
+	{/snippet}
+</Story>
+
+<Story name="Playground">
+	{#snippet children()}
+		<div class="h-[500px]">
+			<AdminSidebar
+				items={itemsWithDropdown}
+				title="Admin Panel"
+				subtitle="Interactive Playground"
+				variant="default"
+				size="md"
+				width="default"
+				bind:collapsed={playgroundCollapsed}
+				collapsible={true}
+				sticky={false}
+				disabled={false}
+				loading={false}
+				ariaLabel="Interactive admin sidebar playground"
+				expandAriaLabel="Expand sidebar"
+				collapseAriaLabel="Collapse sidebar"
+				sidebarId="admin-sidebar-default"
+				defaultBadgeVariant="primary"
+				headerMinHeightClass="min-h-16"
+				onItemClick={(item) => console.log('Clicked:', item.label)}
+				onCollapse={(c) => console.log('Collapsed:', c)}
+				class=""
+			/>
+		</div>
+	{/snippet}
+</Story>
diff --git a/hexawebshare/src/components/admin/layout/AdminSidebar.svelte b/hexawebshare/src/components/admin/layout/AdminSidebar.svelte
index 315da078..dec703da 100644
--- a/hexawebshare/src/components/admin/layout/AdminSidebar.svelte
+++ b/hexawebshare/src/components/admin/layout/AdminSidebar.svelte
@@ -2,3 +2,458 @@
 SPDX-FileCopyrightText: 2025 hexaTune LLC
 SPDX-License-Identifier: MIT
 -->
+
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { DropdownItem } from '../../core/overlay-navigation/Dropdown.svelte';
+	import Dropdown from '../../core/overlay-navigation/Dropdown.svelte';
+	import Button from '../../core/buttons/Button.svelte';
+	import IconButton from '../../core/buttons/IconButton.svelte';
+	import Link from '../../core/typography/Link.svelte';
+	import Badge from '../../core/media/Badge.svelte';
+	import Heading from '../../core/typography/Heading.svelte';
+	import Text from '../../core/typography/Text.svelte';
+	import Spinner from '../../core/feedback/Spinner.svelte';
+	import Icon from '../../core/media/Icon.svelte';
+
+	/**
+	 * Badge variant type for sidebar items
+	 */
+	type BadgeVariant = 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'error';
+
+	/**
+	 * AdminSidebarItem interface for menu items
+	 */
+	export interface AdminSidebarItem {
+		/** Unique identifier for the item */
+		id: string;
+		/** Display label for the item */
+		label: string;
+		/** Icon identifier or character */
+		icon?: string;
+		/** Navigation URL (renders as Link) */
+		href?: string;
+		/** Click handler callback */
+		onClick?: () => void;
+		/** Whether item is currently active */
+		active?: boolean;
+		/** Whether item is disabled */
+		disabled?: boolean;
+		/** Badge content (text or number) */
+		badge?: string | number;
+		/** Badge color variant */
+		badgeVariant?: BadgeVariant;
+		/** Nested dropdown items */
+		children?: DropdownItem[];
+	}
+
+	/**
+	 * Props interface for AdminSidebar component
+	 * All props are required - no default values allowed per project standards
+	 */
+	interface Props {
+		/** Menu items array */
+		items: AdminSidebarItem[];
+		/** Sidebar title text */
+		title: string;
+		/** Sidebar subtitle text */
+		subtitle: string;
+		/** Visual variant style */
+		variant: 'default' | 'compact' | 'bordered';
+		/** Size variant */
+		size: 'sm' | 'md' | 'lg';
+		/** Width variant */
+		width: 'narrow' | 'default' | 'wide';
+		/** Collapsed state (bindable) */
+		collapsed: boolean;
+		/** Whether sidebar can be collapsed */
+		collapsible: boolean;
+		/** Whether sidebar is sticky positioned */
+		sticky: boolean;
+		/** Whether entire sidebar is disabled */
+		disabled: boolean;
+		/** Whether sidebar is in loading state */
+		loading: boolean;
+		/** Accessible label for the sidebar navigation */
+		ariaLabel: string;
+		/** Accessible label for expand button */
+		expandAriaLabel: string;
+		/** Accessible label for collapse button */
+		collapseAriaLabel: string;
+		/** Unique identifier for the sidebar element */
+		sidebarId: string;
+		/** Default badge variant when item does not specify one */
+		defaultBadgeVariant: BadgeVariant;
+		/** CSS class for header minimum height */
+		headerMinHeightClass: string;
+		/** Callback when menu item is clicked */
+		onItemClick: (item: AdminSidebarItem, index: number) => void;
+		/** Callback when collapse state changes */
+		onCollapse: (collapsed: boolean) => void;
+		/** Custom header content snippet */
+		header?: Snippet;
+		/** Custom footer content snippet */
+		footer?: Snippet;
+		/** Custom body content snippet (replaces menu) */
+		children?: Snippet;
+		/** Collapse icon snippet for custom icon rendering */
+		collapseIcon?: Snippet<[{ collapsed: boolean }]>;
+		/** Additional CSS classes */
+		class: string;
+	}
+
+	let {
+		items,
+		title,
+		subtitle,
+		variant,
+		size,
+		width,
+		collapsed = $bindable(),
+		collapsible,
+		sticky,
+		disabled,
+		loading,
+		ariaLabel,
+		expandAriaLabel,
+		collapseAriaLabel,
+		sidebarId,
+		defaultBadgeVariant,
+		headerMinHeightClass,
+		onItemClick,
+		onCollapse,
+		header,
+		footer,
+		children,
+		collapseIcon,
+		class: className,
+		...props
+	}: Props = $props();
+
+	let widthClasses = $derived(
+		collapsed ? 'w-20' : width === 'narrow' ? 'w-52' : width === 'wide' ? 'w-80' : 'w-64'
+	);
+
+	let sidebarClasses = $derived(
+		[
+			'admin-sidebar',
+			'flex',
+			'flex-col',
+			'shrink-0',
+			'bg-base-200',
+			'text-base-content',
+			'min-h-full',
+			'overflow-hidden',
+			'transition-all',
+			'duration-300',
+			widthClasses,
+			variant === 'bordered' && 'border border-base-300',
+			sticky && 'sticky top-0 z-50 h-full max-h-screen',
+			disabled && 'pointer-events-none opacity-60',
+			className
+		]
+			.filter(Boolean)
+			.join(' ')
+	);
+
+	let menuClasses = $derived(
+		[
+			'menu',
+			'flex-1',
+			'overflow-y-auto',
+			'p-2',
+			'gap-1',
+			variant === 'compact' && 'menu-compact',
+			size === 'sm' && 'menu-sm',
+			size === 'lg' && 'menu-lg'
+		]
+			.filter(Boolean)
+			.join(' ')
+	);
+
+	/**
+	 * Get padding classes based on size
+	 */
+	let paddingClasses = $derived(
+		size === 'sm' ? 'px-2 py-1.5' : size === 'lg' ? 'px-4 py-3' : 'px-3 py-2'
+	);
+
+	/**
+	 * Get gap classes based on size
+	 */
+	let gapClasses = $derived(size === 'sm' ? 'gap-2' : size === 'lg' ? 'gap-4' : 'gap-3');
+
+	/**
+	 * Get icon size classes based on size
+	 */
+	let iconSizeClasses = $derived(
+		size === 'sm' ? 'text-lg' : size === 'lg' ? 'text-2xl' : 'text-xl'
+	);
+
+	/**
+	 * Generate CSS classes for menu item based on state and size
+	 * Uses static DaisyUI/Tailwind classes only - no dynamic interpolation
+	 */
+	const getItemClasses = (item: AdminSidebarItem) => {
+		return [
+			'flex',
+			'w-full',
+			'items-center',
+			paddingClasses,
+			gapClasses,
+			'rounded-lg',
+			'transition-all',
+			'duration-200',
+			'cursor-pointer',
+			'hover:bg-base-300',
+			item.active && 'bg-primary text-primary-content hover:opacity-90',
+			item.disabled && 'opacity-50 cursor-not-allowed'
+		]
+			.filter(Boolean)
+			.join(' ');
+	};
+
+	let collapseButtonAriaLabel = $derived(collapsed ? expandAriaLabel : collapseAriaLabel);
+
+	const handleItemClick = (item: AdminSidebarItem, index: number) => {
+		if (item.disabled || disabled || loading) return;
+		onItemClick(item, index);
+		if (item.onClick) item.onClick();
+	};
+
+	const toggleCollapse = () => {
+		if (!collapsible) return;
+		collapsed = !collapsed;
+		onCollapse(collapsed);
+	};
+</script>
+
+<!--
+	NOTE: Raw HTML aside is intentional here.
+	TECHNICAL REASON: aside is a semantic HTML5 landmark element for sidebar content.
+	No library component exists for semantic landmark wrappers.
+	This provides proper document structure and accessibility.
+-->
+<aside id={sidebarId} class={sidebarClasses} role="navigation" aria-label={ariaLabel} {...props}>
+	{#if header}
+		<!--
+			NOTE: Raw HTML div is intentional here.
+			TECHNICAL REASON: This is a structural container for custom header content.
+			No suitable library component exists for generic layout wrappers.
+		-->
+		<div class="border-base-300 border-b p-4">
+			{@render header()}
+		</div>
+	{:else if title || subtitle || collapsible}
+		<!--
+			NOTE: Raw HTML div is intentional here.
+			TECHNICAL REASON: This is a structural container for header layout.
+			No suitable library component exists for flex layout wrappers.
+		-->
+		<div class="border-base-300 flex {headerMinHeightClass} items-center gap-2 border-b px-4 py-3">
+			{#if !collapsed && (title || subtitle)}
+				<!--
+					NOTE: Raw HTML div is intentional here.
+					TECHNICAL REASON: This is a structural container for title/subtitle grouping.
+					No suitable library component exists for generic content wrappers.
+				-->
+				<div class="flex min-w-0 flex-1 flex-col overflow-hidden">
+					{#if title}
+						<Heading level="h2" size="lg" weight="bold" truncate={true} text={title} />
+					{/if}
+					{#if subtitle}
+						<Text size="xs" variant="muted" truncate={true} text={subtitle} />
+					{/if}
+				</div>
+			{/if}
+			{#if collapsible}
+				<IconButton
+					variant="ghost"
+					size="sm"
+					square={true}
+					class="shrink-0"
+					ariaLabel={collapseButtonAriaLabel}
+					onclick={toggleCollapse}
+				>
+					{#snippet children()}
+						{#if collapseIcon}
+							{@render collapseIcon({ collapsed })}
+						{:else}
+							<Icon size="md" ariaHidden={true}>
+								{#snippet children()}
+									<!--
+										NOTE: Raw HTML svg is intentional here.
+										TECHNICAL REASON: Icon component accepts SVG as children snippet.
+										This is the standard pattern for custom icons in this library.
+										No pre-built chevron icon exists in the component library.
+									-->
+									<svg
+										xmlns="http://www.w3.org/2000/svg"
+										class="h-5 w-5 transition-transform {collapsed ? 'rotate-180' : ''}"
+										fill="none"
+										viewBox="0 0 24 24"
+										stroke="currentColor"
+									>
+										<path
+											stroke-linecap="round"
+											stroke-linejoin="round"
+											stroke-width="2"
+											d="M11 19l-7-7 7-7m8 14l-7-7 7-7"
+										/>
+									</svg>
+								{/snippet}
+							</Icon>
+						{/if}
+					{/snippet}
+				</IconButton>
+			{/if}
+		</div>
+	{/if}
+
+	<!--
+		NOTE: Raw HTML div is intentional here.
+		TECHNICAL REASON: This is a structural flex container for body content.
+		No suitable library component exists for flex layout wrappers.
+	-->
+	<div class="flex flex-1 flex-col overflow-hidden">
+		{#if loading}
+			<!--
+				NOTE: Raw HTML div is intentional here.
+				TECHNICAL REASON: This is a centering container for the spinner.
+				No suitable library component exists for flexbox centering wrappers.
+			-->
+			<div class="flex flex-1 items-center justify-center p-4">
+				<Spinner size="lg" variant="primary" {ariaLabel} />
+			</div>
+		{:else if children}
+			<!--
+				NOTE: Raw HTML div is intentional here.
+				TECHNICAL REASON: This is a structural container for custom children content.
+				No suitable library component exists for generic content wrappers.
+			-->
+			<div class={menuClasses}>
+				{@render children()}
+			</div>
+		{:else}
+			<!--
+				NOTE: Raw HTML ul/li is intentional here.
+				TECHNICAL REASON: DaisyUI's menu component requires ul/li structure.
+				The .menu class applies specific CSS selectors targeting ul > li children.
+				Using a library Menu component would create nested menu structures.
+				VALIDATION: DaisyUI v4.x documentation specifies ul.menu > li pattern.
+			-->
+			<ul class={menuClasses} role="menu">
+				{#each items as item, index (item.id)}
+					<li>
+						{#if item.children && item.children.length > 0}
+							<Dropdown
+								items={item.children}
+								position="right"
+								align="start"
+								{size}
+								disabled={item.disabled || disabled}
+								ariaLabel={item.label}
+								class="w-full"
+							>
+								{#snippet trigger()}
+									<Button
+										class="{getItemClasses(item)} justify-between"
+										disabled={item.disabled || disabled}
+									>
+										{#snippet children()}
+											<!--
+												NOTE: Raw HTML span is intentional here.
+												TECHNICAL REASON: This is a structural wrapper for icon and label grouping.
+												No suitable library component exists for inline flex wrappers.
+											-->
+											<span class="flex items-center {gapClasses}">
+												{#if item.icon}
+													<span class={iconSizeClasses}>{item.icon}</span>
+												{/if}
+												{#if !collapsed}
+													<span class="truncate">{item.label}</span>
+												{/if}
+											</span>
+											{#if !collapsed && item.badge !== undefined}
+												<Badge
+													label={String(item.badge)}
+													variant={item.badgeVariant ?? defaultBadgeVariant}
+													{size}
+												/>
+											{/if}
+										{/snippet}
+									</Button>
+								{/snippet}
+							</Dropdown>
+						{:else if item.href}
+							<Link
+								href={item.href}
+								class={getItemClasses(item)}
+								onclick={() => handleItemClick(item, index)}
+							>
+								{#snippet children()}
+									{#if item.icon}
+										<!--
+											NOTE: Raw HTML span is intentional here.
+											TECHNICAL REASON: This is an inline wrapper for icon display.
+											No suitable library component exists for simple icon containers.
+										-->
+										<span class={iconSizeClasses}>{item.icon}</span>
+									{/if}
+									{#if !collapsed}
+										<span class="truncate">{item.label}</span>
+										{#if item.badge !== undefined}
+											<Badge
+												label={String(item.badge)}
+												variant={item.badgeVariant ?? defaultBadgeVariant}
+												{size}
+											/>
+										{/if}
+									{/if}
+								{/snippet}
+							</Link>
+						{:else}
+							<Button
+								class={getItemClasses(item)}
+								disabled={item.disabled || disabled}
+								onclick={() => handleItemClick(item, index)}
+							>
+								{#snippet children()}
+									{#if item.icon}
+										<!--
+											NOTE: Raw HTML span is intentional here.
+											TECHNICAL REASON: This is an inline wrapper for icon display.
+											No suitable library component exists for simple icon containers.
+										-->
+										<span class={iconSizeClasses}>{item.icon}</span>
+									{/if}
+									{#if !collapsed}
+										<span class="truncate text-left">{item.label}</span>
+										{#if item.badge !== undefined}
+											<Badge
+												label={String(item.badge)}
+												variant={item.badgeVariant ?? defaultBadgeVariant}
+												{size}
+											/>
+										{/if}
+									{/if}
+								{/snippet}
+							</Button>
+						{/if}
+					</li>
+				{/each}
+			</ul>
+		{/if}
+	</div>
+
+	{#if footer}
+		<!--
+			NOTE: Raw HTML div is intentional here.
+			TECHNICAL REASON: This is a structural container for custom footer content.
+			No suitable library component exists for generic layout wrappers.
+		-->
+		<div class="border-base-300 mt-auto border-t p-4">
+			{@render footer()}
+		</div>
+	{/if}
+</aside>
diff --git a/hexawebshare/src/lib/index.ts b/hexawebshare/src/lib/index.ts
index 0409012b..9562d86f 100644
--- a/hexawebshare/src/lib/index.ts
+++ b/hexawebshare/src/lib/index.ts
@@ -104,6 +104,8 @@ export { default as Text } from '../components/core/typography/Text.svelte';
 
 // Admin / Layout
 export { default as AdminLayout } from '../components/admin/layout/AdminLayout.svelte';
+export { default as AdminSidebar } from '../components/admin/layout/AdminSidebar.svelte';
+export type { AdminSidebarItem } from '../components/admin/layout/AdminSidebar.svelte';
 export type { SidebarItem } from '../components/core/overlay-navigation/Sidebar.svelte';
 
 // Utility / Utility

From c94119359dc29342673a45645c0d76f17fa727c4 Mon Sep 17 00:00:00 2001
From: krmlp <keremalparslan@gmail.com>
Date: Tue, 27 Jan 2026 19:59:14 +0300
Subject: [PATCH 2/2] feat(AdminSidebar): add sidebar component with Storybook
 stories

---
 .../admin/layout/AdminSidebar.svelte          | 125 +++++++++++-------
 1 file changed, 78 insertions(+), 47 deletions(-)

diff --git a/hexawebshare/src/components/admin/layout/AdminSidebar.svelte b/hexawebshare/src/components/admin/layout/AdminSidebar.svelte
index dec703da..db303428 100644
--- a/hexawebshare/src/components/admin/layout/AdminSidebar.svelte
+++ b/hexawebshare/src/components/admin/layout/AdminSidebar.svelte
@@ -6,7 +6,6 @@ SPDX-License-Identifier: MIT
 <script lang="ts">
 	import type { Snippet } from 'svelte';
 	import type { DropdownItem } from '../../core/overlay-navigation/Dropdown.svelte';
-	import Dropdown from '../../core/overlay-navigation/Dropdown.svelte';
 	import Button from '../../core/buttons/Button.svelte';
 	import IconButton from '../../core/buttons/IconButton.svelte';
 	import Link from '../../core/typography/Link.svelte';
@@ -143,7 +142,6 @@ SPDX-License-Identifier: MIT
 			'bg-base-200',
 			'text-base-content',
 			'min-h-full',
-			'overflow-hidden',
 			'transition-all',
 			'duration-300',
 			widthClasses,
@@ -160,7 +158,7 @@ SPDX-License-Identifier: MIT
 		[
 			'menu',
 			'flex-1',
-			'overflow-y-auto',
+			'overflow-visible',
 			'p-2',
 			'gap-1',
 			variant === 'compact' && 'menu-compact',
@@ -346,45 +344,76 @@ SPDX-License-Identifier: MIT
 				{#each items as item, index (item.id)}
 					<li>
 						{#if item.children && item.children.length > 0}
-							<Dropdown
-								items={item.children}
-								position="right"
-								align="start"
-								{size}
-								disabled={item.disabled || disabled}
-								ariaLabel={item.label}
-								class="w-full"
-							>
-								{#snippet trigger()}
-									<Button
-										class="{getItemClasses(item)} justify-between"
-										disabled={item.disabled || disabled}
-									>
-										{#snippet children()}
-											<!--
-												NOTE: Raw HTML span is intentional here.
-												TECHNICAL REASON: This is a structural wrapper for icon and label grouping.
-												No suitable library component exists for inline flex wrappers.
-											-->
-											<span class="flex items-center {gapClasses}">
-												{#if item.icon}
-													<span class={iconSizeClasses}>{item.icon}</span>
-												{/if}
-												{#if !collapsed}
-													<span class="truncate">{item.label}</span>
+							<!--
+								NOTE: Raw HTML details/summary is intentional here.
+								TECHNICAL REASON: DaisyUI menu component uses native details/summary
+								for collapsible submenus. This is the standard pattern for nested menus.
+								Using Dropdown component creates positioning/overflow issues in sidebars.
+								VALIDATION: DaisyUI v4.x Menu documentation - Collapsible submenu pattern.
+							-->
+							<details class="group" open={item.active}>
+								<summary
+									class="{getItemClasses(item)} cursor-pointer list-none justify-between"
+									class:opacity-50={item.disabled || disabled}
+									class:pointer-events-none={item.disabled || disabled}
+								>
+									<!--
+										NOTE: Raw HTML span is intentional here.
+										TECHNICAL REASON: This is a structural wrapper for icon and label grouping.
+										No suitable library component exists for inline flex wrappers.
+									-->
+									<span class="flex items-center {gapClasses}">
+										{#if item.icon}
+											<span class={iconSizeClasses} aria-hidden="true">{item.icon}</span>
+										{/if}
+										{#if !collapsed}
+											<Text text={item.label} truncate={true} class="flex-1" />
+										{/if}
+									</span>
+									{#if !collapsed && item.badge !== undefined}
+										<Badge
+											label={String(item.badge)}
+											variant={item.badgeVariant ?? defaultBadgeVariant}
+											{size}
+										/>
+									{/if}
+								</summary>
+								{#if !collapsed}
+									<ul class="mt-1 ml-4 space-y-1">
+										{#each item.children as child (child.id)}
+											<li>
+												{#if child.href}
+													<Link
+														href={child.href}
+														class="{paddingClasses} flex items-center {gapClasses} hover:bg-base-300 rounded-lg"
+														onclick={() => child.onClick?.()}
+													>
+														{#snippet children()}
+															{#if child.icon}
+																<span class={iconSizeClasses} aria-hidden="true">{child.icon}</span>
+															{/if}
+															<Text text={child.label} truncate={true} class="flex-1" />
+														{/snippet}
+													</Link>
+												{:else}
+													<Button
+														class="{paddingClasses} flex w-full items-center {gapClasses} hover:bg-base-300 justify-start rounded-lg"
+														disabled={child.disabled}
+														onclick={() => child.onClick?.()}
+													>
+														{#snippet children()}
+															{#if child.icon}
+																<span class={iconSizeClasses} aria-hidden="true">{child.icon}</span>
+															{/if}
+															<Text text={child.label} truncate={true} class="flex-1" />
+														{/snippet}
+													</Button>
 												{/if}
-											</span>
-											{#if !collapsed && item.badge !== undefined}
-												<Badge
-													label={String(item.badge)}
-													variant={item.badgeVariant ?? defaultBadgeVariant}
-													{size}
-												/>
-											{/if}
-										{/snippet}
-									</Button>
-								{/snippet}
-							</Dropdown>
+											</li>
+										{/each}
+									</ul>
+								{/if}
+							</details>
 						{:else if item.href}
 							<Link
 								href={item.href}
@@ -396,12 +425,13 @@ SPDX-License-Identifier: MIT
 										<!--
 											NOTE: Raw HTML span is intentional here.
 											TECHNICAL REASON: This is an inline wrapper for icon display.
-											No suitable library component exists for simple icon containers.
+											Icon component uses w/h sizing but item.icon contains emoji/characters
+											which require font-size (text-lg, text-xl) for proper scaling.
 										-->
-										<span class={iconSizeClasses}>{item.icon}</span>
+										<span class={iconSizeClasses} aria-hidden="true">{item.icon}</span>
 									{/if}
 									{#if !collapsed}
-										<span class="truncate">{item.label}</span>
+										<Text text={item.label} truncate={true} class="flex-1" />
 										{#if item.badge !== undefined}
 											<Badge
 												label={String(item.badge)}
@@ -423,12 +453,13 @@ SPDX-License-Identifier: MIT
 										<!--
 											NOTE: Raw HTML span is intentional here.
 											TECHNICAL REASON: This is an inline wrapper for icon display.
-											No suitable library component exists for simple icon containers.
+											Icon component uses w/h sizing but item.icon contains emoji/characters
+											which require font-size (text-lg, text-xl) for proper scaling.
 										-->
-										<span class={iconSizeClasses}>{item.icon}</span>
+										<span class={iconSizeClasses} aria-hidden="true">{item.icon}</span>
 									{/if}
 									{#if !collapsed}
-										<span class="truncate text-left">{item.label}</span>
+										<Text text={item.label} truncate={true} class="flex-1 text-left" />
 										{#if item.badge !== undefined}
 											<Badge
 												label={String(item.badge)}