From 399da18eb6ebb75603df8a52ac8f203739b70a97 Mon Sep 17 00:00:00 2001
From: krmlp <keremalparslan@gmail.com>
Date: Thu, 29 Jan 2026 16:58:46 +0300
Subject: [PATCH] feat(FilterPanel): add filter panel component with Storybook
 stories

---
 .../utility/FilterPanel.stories.svelte        | 124 +++++++
 .../utility/utility/FilterPanel.svelte        | 309 ++++++++++++++++++
 2 files changed, 433 insertions(+)
 create mode 100644 hexawebshare/src/components/utility/utility/FilterPanel.stories.svelte

diff --git a/hexawebshare/src/components/utility/utility/FilterPanel.stories.svelte b/hexawebshare/src/components/utility/utility/FilterPanel.stories.svelte
new file mode 100644
index 00000000..e9e09228
--- /dev/null
+++ b/hexawebshare/src/components/utility/utility/FilterPanel.stories.svelte
@@ -0,0 +1,124 @@
+<!--
+SPDX-FileCopyrightText: 2025 hexaTune LLC
+SPDX-License-Identifier: MIT
+-->
+
+<script module lang="ts">
+	import { defineMeta } from '@storybook/addon-svelte-csf';
+	import { fn } from 'storybook/test';
+	import FilterPanel from './FilterPanel.svelte';
+	import type { FilterItem } from './FilterPanel.svelte';
+
+	const defaultItems: FilterItem[] = [
+		{ id: 1, label: 'Option A', checked: false, disabled: false },
+		{ id: 2, label: 'Option B', checked: false, disabled: false },
+		{ id: 3, label: 'Option C', checked: false, disabled: false },
+		{ id: 4, label: 'Option D', checked: false, disabled: false }
+	];
+
+	const preselectedItems: FilterItem[] = [
+		{ id: 1, label: 'Option A', checked: true, disabled: false },
+		{ id: 2, label: 'Option B', checked: false, disabled: false },
+		{ id: 3, label: 'Option C', checked: true, disabled: false },
+		{ id: 4, label: 'Option D', checked: false, disabled: false }
+	];
+
+	const itemsWithDisabled: FilterItem[] = [
+		{ id: 1, label: 'Option A', checked: false, disabled: false },
+		{ id: 2, label: 'Option B', checked: false, disabled: true },
+		{ id: 3, label: 'Option C', checked: false, disabled: false },
+		{ id: 4, label: 'Option D', checked: false, disabled: true }
+	];
+
+	const { Story } = defineMeta({
+		component: FilterPanel,
+		title: 'Utility/Utility/FilterPanel',
+		tags: ['autodocs'],
+		argTypes: {
+			variant: {
+				control: { type: 'select' },
+				options: ['default', 'bordered', 'ghost'],
+				description: 'Visual variant of the dropdown'
+			},
+			size: {
+				control: { type: 'select' },
+				options: ['sm', 'md', 'lg'],
+				description: 'Size preset for the component'
+			},
+			position: {
+				control: { type: 'select' },
+				options: ['bottom', 'top', 'left', 'right'],
+				description: 'Position of dropdown content relative to trigger'
+			},
+			align: {
+				control: { type: 'select' },
+				options: ['start', 'end'],
+				description: 'Alignment of dropdown content'
+			},
+			disabled: {
+				control: 'boolean',
+				description: 'Whether the filter panel is disabled'
+			},
+			loading: {
+				control: 'boolean',
+				description: 'Whether the filter panel is in loading state'
+			},
+			onApply: { action: 'apply' },
+			onClear: { action: 'clear' },
+			onChange: { action: 'change' },
+			onChipRemove: { action: 'chipRemove' }
+		},
+		args: {
+			items: defaultItems,
+			triggerLabel: 'Filters',
+			applyLabel: 'Apply',
+			clearLabel: 'Clear',
+			ariaLabel: 'Filter options',
+			chipCloseLabel: 'Remove filter',
+			checkboxListAriaLabel: 'Filter checkbox list',
+			actionsAriaLabel: 'Filter actions',
+			selectedFiltersAriaLabel: 'Selected filters',
+			variant: 'default',
+			size: 'md',
+			position: 'bottom',
+			align: 'start',
+			disabled: false,
+			loading: false,
+			class: '',
+			onApply: fn(),
+			onClear: fn(),
+			onChange: fn(),
+			onChipRemove: fn()
+		}
+	});
+</script>
+
+<!-- Story 1: Default -->
+<Story name="Default" />
+
+<!-- Story 2: With Preselected Items -->
+<Story name="WithPreselected" args={{ items: preselectedItems }} />
+
+<!-- Story 3: Small Size -->
+<Story name="SmallSize" args={{ size: 'sm' }} />
+
+<!-- Story 4: Large Size -->
+<Story name="LargeSize" args={{ size: 'lg' }} />
+
+<!-- Story 5: Bordered Variant -->
+<Story name="BorderedVariant" args={{ variant: 'bordered' }} />
+
+<!-- Story 6: Ghost Variant -->
+<Story name="GhostVariant" args={{ variant: 'ghost' }} />
+
+<!-- Story 7: With Disabled Items -->
+<Story name="WithDisabledItems" args={{ items: itemsWithDisabled }} />
+
+<!-- Story 8: Disabled State -->
+<Story name="DisabledState" args={{ disabled: true }} />
+
+<!-- Story 9: Loading State -->
+<Story name="LoadingState" args={{ loading: true }} />
+
+<!-- Story 10: Playground (Interactive) -->
+<Story name="Playground" />
diff --git a/hexawebshare/src/components/utility/utility/FilterPanel.svelte b/hexawebshare/src/components/utility/utility/FilterPanel.svelte
index 315da078..05377783 100644
--- a/hexawebshare/src/components/utility/utility/FilterPanel.svelte
+++ b/hexawebshare/src/components/utility/utility/FilterPanel.svelte
@@ -2,3 +2,312 @@
 SPDX-FileCopyrightText: 2025 hexaTune LLC
 SPDX-License-Identifier: MIT
 -->
+
+<script lang="ts">
+	import Dropdown from '../../core/overlay-navigation/Dropdown.svelte';
+	import Button from '../../core/buttons/Button.svelte';
+	import Checkbox from '../../core/forms/Checkbox.svelte';
+	import Chip from '../../core/media/Chip.svelte';
+	import Grid from '../../core/layout/Grid.svelte';
+	import Row from '../../core/layout/Row.svelte';
+	import Divider from '../../core/layout/Divider.svelte';
+
+	/**
+	 * Component configuration constants
+	 * Centralized to avoid embedded strings in template
+	 * Following AGENTS.md "No Hardcoded Strings" rule
+	 */
+	const COMPONENT_CONFIG = {
+		LAYOUT: {
+			ALIGN: 'center',
+			JUSTIFY: 'start',
+			WRAP: true,
+			COLUMNS: 1
+		},
+		VARIANTS: {
+			BUTTON_CLEAR: 'ghost',
+			BUTTON_APPLY: 'primary',
+			DROPDOWN_CLOSE_ON_SELECT: false,
+			CHIP_CLOSABLE: true
+		},
+		SPACING: {
+			CONTAINER_GAP: 'sm',
+			CONTENT_GAP: 'xs',
+			ACTIONS_GAP: '2',
+			CHIPS_GAP: '1',
+			CONTENT_PADDING: 'p-2'
+		}
+	} as const;
+
+	/**
+	 * FilterItem interface for individual filter options
+	 */
+	export interface FilterItem {
+		/**
+		 * Unique identifier for the filter item
+		 */
+		id: string | number;
+		/**
+		 * Display label for the filter item
+		 */
+		label: string;
+		/**
+		 * Whether the filter item is checked/selected
+		 */
+		checked: boolean;
+		/**
+		 * Whether the filter item is disabled
+		 */
+		disabled: boolean;
+	}
+
+	/**
+	 * Props interface for FilterPanel component
+	 * All props are required (no default values)
+	 */
+	interface Props {
+		/**
+		 * Array of filter items to display
+		 */
+		items: FilterItem[];
+		/**
+		 * Label for the dropdown trigger button
+		 */
+		triggerLabel: string;
+		/**
+		 * Label for the apply button
+		 */
+		applyLabel: string;
+		/**
+		 * Label for the clear button
+		 */
+		clearLabel: string;
+		/**
+		 * Accessible label for the filter panel
+		 */
+		ariaLabel: string;
+		/**
+		 * Accessible label for chip close buttons
+		 */
+		chipCloseLabel: string;
+		/**
+		 * Accessible label for the checkbox list
+		 */
+		checkboxListAriaLabel: string;
+		/**
+		 * Accessible label for the action buttons row
+		 */
+		actionsAriaLabel: string;
+		/**
+		 * Accessible label for the selected filters row
+		 */
+		selectedFiltersAriaLabel: string;
+		/**
+		 * Visual variant of the dropdown
+		 */
+		variant: 'default' | 'bordered' | 'ghost';
+		/**
+		 * Size preset for the component
+		 */
+		size: 'sm' | 'md' | 'lg';
+		/**
+		 * Position of dropdown content relative to trigger
+		 */
+		position: 'bottom' | 'top' | 'left' | 'right';
+		/**
+		 * Alignment of dropdown content
+		 */
+		align: 'start' | 'end';
+		/**
+		 * Whether the filter panel is disabled
+		 */
+		disabled: boolean;
+		/**
+		 * Whether the filter panel is in loading state
+		 */
+		loading: boolean;
+		/**
+		 * Callback when apply button is clicked
+		 */
+		onApply: (selectedItems: FilterItem[]) => void;
+		/**
+		 * Callback when clear button is clicked
+		 */
+		onClear: () => void;
+		/**
+		 * Callback when a filter item selection changes
+		 */
+		onChange: (item: FilterItem, checked: boolean) => void;
+		/**
+		 * Callback when a chip is removed
+		 */
+		onChipRemove: (item: FilterItem) => void;
+		/**
+		 * Additional CSS classes for the container
+		 */
+		class: string;
+	}
+
+	const {
+		items,
+		triggerLabel,
+		applyLabel,
+		clearLabel,
+		ariaLabel,
+		chipCloseLabel,
+		checkboxListAriaLabel,
+		actionsAriaLabel,
+		selectedFiltersAriaLabel,
+		variant,
+		size,
+		position,
+		align,
+		disabled,
+		loading,
+		onApply,
+		onClear,
+		onChange,
+		onChipRemove,
+		class: className,
+		...props
+	}: Props = $props();
+
+	// Internal state - track checked items locally
+	let internalItems = $state<FilterItem[]>([]);
+
+	// Sync internal items with props
+	$effect(() => {
+		internalItems = items.map((item) => ({ ...item }));
+	});
+
+	// Derived: Get selected/checked items
+	let selectedItems = $derived(internalItems.filter((item) => item.checked));
+
+	// Derived: Check if any filters are selected
+	let hasSelectedItems = $derived(selectedItems.length > 0);
+
+	// Handle checkbox change
+	function handleCheckboxChange(item: FilterItem, index: number) {
+		if (disabled || item.disabled) return;
+
+		const newChecked = !internalItems[index].checked;
+		internalItems[index].checked = newChecked;
+		onChange(item, newChecked);
+	}
+
+	// Handle apply button click
+	function handleApply() {
+		if (disabled || loading) return;
+		onApply(selectedItems);
+	}
+
+	// Handle clear button click
+	function handleClear() {
+		if (disabled || loading) return;
+		internalItems = internalItems.map((item) => ({ ...item, checked: false }));
+		onClear();
+	}
+
+	// Handle chip remove
+	function handleChipRemove(item: FilterItem) {
+		if (disabled || loading) return;
+		const index = internalItems.findIndex((i) => i.id === item.id);
+		if (index !== -1) {
+			internalItems[index].checked = false;
+			onChipRemove(item);
+		}
+	}
+</script>
+
+<Grid
+	columns={COMPONENT_CONFIG.LAYOUT.COLUMNS}
+	gap={COMPONENT_CONFIG.SPACING.CONTAINER_GAP}
+	class={className}
+	{ariaLabel}
+	{...props}
+>
+	{#snippet children()}
+		<Dropdown
+			label={triggerLabel}
+			{variant}
+			{size}
+			{position}
+			{align}
+			{disabled}
+			{loading}
+			{ariaLabel}
+			closeOnSelect={COMPONENT_CONFIG.VARIANTS.DROPDOWN_CLOSE_ON_SELECT}
+		>
+			{#snippet children()}
+				<Grid
+					columns={COMPONENT_CONFIG.LAYOUT.COLUMNS}
+					gap={COMPONENT_CONFIG.SPACING.CONTENT_GAP}
+					class={COMPONENT_CONFIG.SPACING.CONTENT_PADDING}
+					ariaLabel={checkboxListAriaLabel}
+				>
+					{#snippet children()}
+						{#each internalItems as item, index (item.id)}
+							<Checkbox
+								label={item.label}
+								checked={item.checked}
+								disabled={disabled || item.disabled}
+								{size}
+								onchange={() => handleCheckboxChange(item, index)}
+							/>
+						{/each}
+
+						<Divider />
+
+						<Row
+							gap={COMPONENT_CONFIG.SPACING.ACTIONS_GAP}
+							align={COMPONENT_CONFIG.LAYOUT.ALIGN}
+							justify={COMPONENT_CONFIG.LAYOUT.JUSTIFY}
+							ariaLabel={actionsAriaLabel}
+						>
+							{#snippet children()}
+								<Button
+									label={clearLabel}
+									variant={COMPONENT_CONFIG.VARIANTS.BUTTON_CLEAR}
+									{size}
+									disabled={disabled || !hasSelectedItems}
+									onclick={handleClear}
+								/>
+								<Button
+									label={applyLabel}
+									variant={COMPONENT_CONFIG.VARIANTS.BUTTON_APPLY}
+									{size}
+									{disabled}
+									{loading}
+									onclick={handleApply}
+								/>
+							{/snippet}
+						</Row>
+					{/snippet}
+				</Grid>
+			{/snippet}
+		</Dropdown>
+
+		{#if hasSelectedItems}
+			<Row
+				gap={COMPONENT_CONFIG.SPACING.CHIPS_GAP}
+				align={COMPONENT_CONFIG.LAYOUT.ALIGN}
+				justify={COMPONENT_CONFIG.LAYOUT.JUSTIFY}
+				wrap={COMPONENT_CONFIG.LAYOUT.WRAP}
+				ariaLabel={selectedFiltersAriaLabel}
+			>
+				{#snippet children()}
+					{#each selectedItems as item (item.id)}
+						<Chip
+							label={item.label}
+							closable={COMPONENT_CONFIG.VARIANTS.CHIP_CLOSABLE}
+							onClose={() => handleChipRemove(item)}
+							closeLabel={chipCloseLabel}
+							{size}
+							{disabled}
+						/>
+					{/each}
+				{/snippet}
+			</Row>
+		{/if}
+	{/snippet}
+</Grid>