@zeix/le-truc 0.15.0

package/examples/form-listbox/form-listbox.spec.ts

@@ -0,0 +1,1050 @@
+import { expect, test } from '@playwright/test'
+
+/**
+ * Test Suite: form-listbox Component
+ *
+ * Comprehensive tests for the Le Truc form-listbox component, which provides
+ * a filterable listbox with keyboard navigation and remote data loading.
+ *
+ * Key Features Tested:
+ * - ✅ Basic rendering and initialization
+ * - ✅ Remote JSON data loading (both flat arrays and grouped objects)
+ * - ✅ Loading states and error handling
+ * - ✅ Option selection and value management
+ * - ✅ Keyboard navigation (arrow keys, Enter, Escape)
+ * - ✅ Filtering functionality
+ * - ✅ Focus management and accessibility
+ * - ✅ Event emission on value changes
+ * - ✅ Dynamic src and property updates
+ * - ✅ Form integration and data submission
+ * - ✅ Edge cases and performance scenarios
+ *
+ * Architecture Notes:
+ * - Uses `asString` parser for src URL validation
+ * - Implements `fetchWithCache` for HTTP request caching
+ * - Uses Collections for reactive option tracking
+ * - Manages focus via `manageFocus` utility
+ * - Renders content via `dangerouslySetInnerHTML`
+ * - Emits custom 'form-listbox.change' events
+ *
+ * Test Coverage: 80+ comprehensive test cases covering all major functionality,
+ * error states, accessibility features, and edge cases. Tests validate both
+ * user interactions and programmatic property changes following Le Truc's
+ * reactive property model.
+ */
+
+test.describe('form-listbox component', () => {
+	test.beforeEach(async ({ page }) => {
+		page.on('console', msg => {
+			console.log(`[browser] ${msg.type()}: ${msg.text()}`)
+		})
+
+		await page.goto('http://localhost:3000/test/form-listbox.html')
+		await page.waitForSelector('form-listbox')
+	})
+
+	test.describe('Basic Rendering and Initialization', () => {
+		test('loads and displays timezone data successfully', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			const loading = listbox.locator('.loading')
+			const error = listbox.locator('.error')
+			const callout = listbox.locator('card-callout')
+			const listboxElement = listbox.locator('[role="listbox"]')
+
+			// Wait for content to load
+			await expect(listboxElement).toBeVisible({ timeout: 1000 })
+
+			// After loading, should hide loading and error states
+			await expect(loading).toBeHidden()
+			await expect(error).toBeHidden()
+			await expect(callout).toBeHidden()
+
+			// Should have loaded timezone options
+			const options = listbox.locator('button[role="option"]')
+			const optionCount = await options.count()
+			expect(optionCount).toBeGreaterThan(100) // Should have many timezone options
+
+			// Should have grouped content
+			const groups = listbox.locator('[role="group"]')
+			const groupCount = await groups.count()
+			expect(groupCount).toBeGreaterThan(5) // Should have continent groups
+		})
+
+		test('displays grouped timezone data with proper structure', async ({
+			page,
+		}) => {
+			const listbox = page.locator('form-listbox').first()
+			const listboxElement = listbox.locator('[role="listbox"]')
+
+			await expect(listboxElement).toBeVisible({ timeout: 1000 })
+
+			// Check for Africa group
+			const africaGroup = listbox.locator('[role="group"]').first()
+			await expect(africaGroup).toBeVisible()
+
+			const africaLabel = africaGroup.locator('[role="presentation"]').first()
+			await expect(africaLabel).toContainText('Africa')
+
+			// Check for options within Africa group
+			const africaOptions = africaGroup.locator('button[role="option"]')
+			const africaCount = await africaOptions.count()
+			expect(africaCount).toBeGreaterThan(10)
+
+			// Verify specific African cities
+			await expect(africaOptions).toContainText(['Abidjan', 'Cairo', 'Lagos'])
+		})
+	})
+
+	test.describe('Error Handling', () => {
+		test('shows error for invalid URL', async ({ page }) => {
+			// Add a listbox with invalid src (using an actual invalid URL format)
+			await page.evaluate(() => {
+				const listbox = document.createElement('form-listbox')
+				listbox.setAttribute('src', 'ftp://invalid-protocol.example')
+				listbox.innerHTML = `
+					<input type="hidden" name="timezone" />
+					<card-callout>
+						<p class="loading" role="status">Loading...</p>
+						<p class="error" role="alert" aria-live="assertive" hidden></p>
+					</card-callout>
+					<module-scrollarea orientation="vertical">
+						<div role="listbox" aria-label="Test" hidden></div>
+					</module-scrollarea>
+				`
+				document.body.appendChild(listbox)
+			})
+
+			const invalidListbox = page.locator('form-listbox').last()
+			const loading = invalidListbox.locator('.loading')
+			const error = invalidListbox.locator('.error')
+			const callout = invalidListbox.locator('card-callout')
+
+			await expect(callout).toBeVisible({ timeout: 1000 })
+			await expect(error).toBeVisible()
+			await expect(loading).toBeHidden()
+			await expect(callout).toHaveClass(/danger/)
+
+			const errorText = await error.textContent()
+			expect(errorText).toContain('Invalid URL')
+		})
+
+		test('shows error for 404 not found', async ({ page }) => {
+			await page.evaluate(() => {
+				const listbox = document.createElement('form-listbox')
+				listbox.setAttribute('src', '/nonexistent-file.json')
+				listbox.innerHTML = `
+					<input type="hidden" name="timezone" />
+					<card-callout>
+						<p class="loading" role="status">Loading...</p>
+						<p class="error" role="alert" aria-live="assertive" hidden></p>
+					</card-callout>
+					<module-scrollarea orientation="vertical">
+						<div role="listbox" aria-label="Test" hidden></div>
+					</module-scrollarea>
+				`
+				document.body.appendChild(listbox)
+			})
+
+			const notFoundListbox = page.locator('form-listbox').last()
+			const error = notFoundListbox.locator('.error')
+			const callout = notFoundListbox.locator('card-callout')
+
+			await expect(error).toBeVisible({ timeout: 1000 })
+			await expect(callout).toHaveClass(/danger/)
+		})
+
+		test('handles component without src attribute correctly', async ({
+			page,
+		}) => {
+			await page.evaluate(() => {
+				const listbox = document.createElement('form-listbox')
+				listbox.innerHTML = `
+					<input type="hidden" name="timezone" />
+					<div role="listbox" aria-label="Test">
+						<button type="button" role="option" tabindex="-1" value="test">Test Option</button>
+					</div>
+				`
+				document.body.appendChild(listbox)
+			})
+
+			const noSrcListbox = page.locator('form-listbox').last()
+			const listboxElement = noSrcListbox.locator('[role="listbox"]')
+			const options = listboxElement.locator('button[role="option"]')
+
+			// Should show listbox and options when no src but inline HTML exists
+			await expect(listboxElement).toBeVisible()
+			await expect(options).toHaveCount(1)
+
+			// Should not show any error callout
+			const callout = noSrcListbox.locator('card-callout')
+			if ((await callout.count()) > 0) {
+				await expect(callout).toBeHidden()
+			}
+		})
+	})
+
+	test.describe('Option Selection and Value Management', () => {
+		test('selects option when clicked', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			const listboxElement = listbox.locator('[role="listbox"]')
+
+			await expect(listboxElement).toBeVisible({ timeout: 1000 })
+
+			// Find and click an option
+			const firstOption = listbox.locator('button[role="option"]').first()
+			await expect(firstOption).toBeVisible()
+
+			const optionValue = await firstOption.getAttribute('value')
+
+			await firstOption.click()
+
+			// Verify selection
+			await expect(firstOption).toHaveAttribute('aria-selected', 'true')
+			await expect(firstOption).toHaveAttribute('tabindex', '0')
+
+			// Check component value property
+			const componentValue = await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				return element.value
+			})
+			expect(componentValue).toBe(optionValue)
+
+			// Check value attribute on host element
+			await expect(listbox).toHaveAttribute('value', optionValue || '')
+		})
+
+		test('updates selection when value property is changed programmatically', async ({
+			page,
+		}) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			// Get a specific option value
+			const targetOption = listbox.locator('button[role="option"]').nth(5)
+			const targetValue = await targetOption.getAttribute('value')
+
+			// Set value programmatically
+			await page.evaluate(value => {
+				const element = document.querySelector('form-listbox') as any
+				element.value = value
+			}, targetValue)
+
+			// Verify the option is now selected
+			await expect(targetOption).toHaveAttribute('aria-selected', 'true')
+			await expect(targetOption).toHaveAttribute('tabindex', '0')
+			await expect(listbox).toHaveAttribute('value', targetValue || '')
+		})
+
+		test('deselects previous option when new option is selected', async ({
+			page,
+		}) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			const firstOption = listbox.locator('button[role="option"]').first()
+			const secondOption = listbox.locator('button[role="option"]').nth(1)
+
+			// Select first option
+			await firstOption.click()
+			await expect(firstOption).toHaveAttribute('aria-selected', 'true')
+			await expect(firstOption).toHaveAttribute('tabindex', '0')
+
+			// Select second option
+			await secondOption.click()
+			await expect(secondOption).toHaveAttribute('aria-selected', 'true')
+			await expect(secondOption).toHaveAttribute('tabindex', '0')
+
+			// First option should be deselected
+			await expect(firstOption).toHaveAttribute('aria-selected', 'false')
+			await expect(firstOption).toHaveAttribute('tabindex', '-1')
+		})
+	})
+
+	test.describe('Keyboard Navigation', () => {
+		test('focuses first option when listbox receives focus', async ({
+			page,
+		}) => {
+			const listbox = page.locator('form-listbox').first()
+			const listboxElement = listbox.locator('[role="listbox"]')
+
+			await expect(listboxElement).toBeVisible({ timeout: 1000 })
+
+			// First select an option to set up initial focus management
+			const firstOption = listbox.locator('button[role="option"]').first()
+			await firstOption.click()
+
+			// Now test focus behavior
+			await listboxElement.focus()
+			await expect(firstOption).toBeFocused()
+		})
+
+		test('navigates options with arrow keys', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			const listboxElement = listbox.locator('[role="listbox"]')
+
+			await expect(listboxElement).toBeVisible({ timeout: 1000 })
+
+			// First select an option to establish focus management
+			const firstOption = listbox.locator('button[role="option"]').first()
+			const secondOption = listbox.locator('button[role="option"]').nth(1)
+
+			await firstOption.click()
+			await listboxElement.focus()
+			await expect(firstOption).toBeFocused()
+
+			// Navigate down
+			await page.keyboard.press('ArrowDown')
+			await expect(secondOption).toBeFocused()
+
+			// Navigate back up
+			await page.keyboard.press('ArrowUp')
+			await expect(firstOption).toBeFocused()
+		})
+
+		test('selects focused option with Enter key', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			const listboxElement = listbox.locator('[role="listbox"]')
+
+			await expect(listboxElement).toBeVisible({ timeout: 1000 })
+
+			const firstOption = listbox.locator('button[role="option"]').first()
+			const firstValue = await firstOption.getAttribute('value')
+
+			// First click to establish focus, then clear selection
+			await firstOption.click()
+			await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				element.value = ''
+			})
+
+			await listboxElement.focus()
+			await expect(firstOption).toBeFocused()
+
+			// Press Enter to select
+			await page.keyboard.press('Enter')
+
+			await expect(firstOption).toHaveAttribute('aria-selected', 'true')
+			await expect(listbox).toHaveAttribute('value', firstValue || '')
+		})
+
+		test('wraps navigation at boundaries', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			const listboxElement = listbox.locator('[role="listbox"]')
+
+			await expect(listboxElement).toBeVisible({ timeout: 1000 })
+
+			// First establish focus on first option
+			const firstOption = listbox.locator('button[role="option"]').first()
+			await firstOption.click()
+			await listboxElement.focus()
+
+			// Navigate up from first option should wrap to last
+			await page.keyboard.press('ArrowUp')
+
+			const lastOptionValue = await page.evaluate(() => {
+				const listbox = document.querySelector('form-listbox')
+				const options = Array.from(
+					listbox?.querySelectorAll('button[role="option"]:not([hidden])')
+						|| [],
+				)
+				return (options[options.length - 1] as HTMLElement)?.getAttribute(
+					'value',
+				)
+			})
+
+			const focusedValue = await page.evaluate(() =>
+				(document.activeElement as HTMLElement)?.getAttribute('value'),
+			)
+			expect(focusedValue).toBe(lastOptionValue)
+		})
+	})
+
+	test.describe('Filtering Functionality', () => {
+		test('filters options based on filter property', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			const allOptions = listbox.locator('button[role="option"]')
+			const initialCount = await allOptions.count()
+
+			// Set filter to show options containing 'af' (should match Africa cities)
+			await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				element.filter = 'af'
+			})
+
+			const visibleOptions = listbox.locator(
+				'button[role="option"]:not([hidden])',
+			)
+			const visibleCount = await visibleOptions.count()
+
+			expect(visibleCount).toBeLessThan(initialCount)
+			expect(visibleCount).toBeGreaterThan(0)
+
+			// Verify visible options contain "af" in their text
+			for (let i = 0; i < Math.min(visibleCount, 5); i++) {
+				const optionText = await visibleOptions.nth(i).textContent()
+				expect(optionText?.toLowerCase()).toContain('af')
+			}
+		})
+
+		test('highlights matching text when filter is applied', async ({
+			page,
+		}) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			// Set filter
+			await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				element.filter = 'new'
+			})
+
+			const visibleOptions = listbox.locator(
+				'button[role="option"]:not([hidden])',
+			)
+			const visibleCount = await visibleOptions.count()
+
+			if (visibleCount > 0) {
+				const firstVisible = visibleOptions.first()
+				const highlightedMark = firstVisible.locator('mark')
+
+				// Should have highlighted text
+				await expect(highlightedMark).toBeVisible()
+				const highlightedText = await highlightedMark.textContent()
+				expect(highlightedText?.toLowerCase()).toBe('new')
+			}
+		})
+
+		test('shows no options when filter matches nothing', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			// Set filter that won't match anything
+			await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				element.filter = 'xyzzyx-nonexistent'
+			})
+
+			const visibleOptions = listbox.locator(
+				'button[role="option"]:not([hidden])',
+			)
+			const visibleCount = await visibleOptions.count()
+
+			expect(visibleCount).toBe(0)
+		})
+
+		test('clears filter and shows all options', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			const allOptions = listbox.locator('button[role="option"]')
+			const initialCount = await allOptions.count()
+
+			// Apply filter
+			await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				element.filter = 'africa'
+			})
+
+			const filteredCount = await listbox
+				.locator('button[role="option"]:not([hidden])')
+				.count()
+			expect(filteredCount).toBeLessThan(initialCount)
+
+			// Clear filter
+			await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				element.filter = ''
+			})
+
+			const clearedCount = await listbox
+				.locator('button[role="option"]:not([hidden])')
+				.count()
+			expect(clearedCount).toBe(initialCount)
+		})
+	})
+
+	test.describe('Event Handling', () => {
+		test('emits change event when value changes', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			// Set up event listener
+			await page.evaluate(() => {
+				;(window as any).changeEvents = []
+				const element = document.querySelector('form-listbox')
+				element?.addEventListener('change', event => {
+					;(window as any).changeEvents.push(
+						(event.target as HTMLInputElement).value,
+					)
+				})
+			})
+
+			const firstOption = listbox.locator('button[role="option"]').first()
+			const optionValue = await firstOption.getAttribute('value')
+
+			await firstOption.click()
+
+			// Check that event was fired
+			const changeEvents = await page.evaluate(
+				() => (window as any).changeEvents,
+			)
+			expect(changeEvents).toHaveLength(1)
+			expect(changeEvents[0]).toBe(optionValue)
+		})
+
+		test('does not emit duplicate events for same value', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			// Set up event listener
+			await page.evaluate(() => {
+				;(window as any).changeEvents = []
+				const element = document.querySelector('form-listbox')
+				element?.addEventListener('change', event => {
+					;(window as any).changeEvents.push(
+						(event.target as HTMLInputElement).value,
+					)
+				})
+			})
+
+			const firstOption = listbox.locator('button[role="option"]').first()
+
+			// Click same option twice
+			await firstOption.click()
+			await firstOption.click()
+
+			// Should only have one event
+			const changeEvents = await page.evaluate(
+				() => (window as any).changeEvents,
+			)
+			expect(changeEvents).toHaveLength(1)
+		})
+	})
+
+	test.describe('Dynamic Behavior', () => {
+		test('updates content when src property changes', async ({ page }) => {
+			// Create a simple JSON endpoint response simulation
+			await page.route('**/simple-options.json', route => {
+				route.fulfill({
+					status: 200,
+					contentType: 'application/json',
+					body: JSON.stringify([
+						{ value: 'opt1', label: 'Option 1' },
+						{ value: 'opt2', label: 'Option 2' },
+						{ value: 'opt3', label: 'Option 3' },
+					]),
+				})
+			})
+
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			const initialOptions = listbox.locator('button[role="option"]')
+			const initialCount = await initialOptions.count()
+
+			// Change src to simple options
+			await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				element.src = '/simple-options.json'
+			})
+
+			// Wait for new content to load
+			await page.waitForTimeout(50)
+
+			const newOptions = listbox.locator('button[role="option"]')
+			const newCount = await newOptions.count()
+
+			expect(newCount).toBe(3)
+			expect(newCount).not.toBe(initialCount)
+
+			await expect(newOptions).toContainText([
+				'Option 1',
+				'Option 2',
+				'Option 3',
+			])
+		})
+
+		test('handles src property validation', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			// Set invalid src
+			await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				element.src = 'invalid-url'
+			})
+
+			const error = listbox.locator('.error')
+			const callout = listbox.locator('card-callout')
+
+			await expect(error).toBeVisible({ timeout: 1000 })
+			await expect(callout).toHaveClass(/danger/)
+		})
+	})
+
+	test.describe('Accessibility Features', () => {
+		test('maintains proper ARIA attributes', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			const listboxElement = listbox.locator('[role="listbox"]')
+
+			await expect(listboxElement).toBeVisible({ timeout: 1000 })
+
+			// Verify listbox role and aria-label
+			await expect(listboxElement).toHaveAttribute('role', 'listbox')
+			await expect(listboxElement).toHaveAttribute('aria-label')
+
+			// Verify option roles and aria-selected attributes
+			const options = listbox.locator('button[role="option"]')
+			const firstOption = options.first()
+
+			await expect(firstOption).toHaveAttribute('role', 'option')
+			await expect(firstOption).toHaveAttribute('aria-selected', 'false')
+
+			await firstOption.click()
+			await expect(firstOption).toHaveAttribute('aria-selected', 'true')
+		})
+
+		test('manages tabindex correctly for keyboard navigation', async ({
+			page,
+		}) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			const options = listbox.locator('button[role="option"]')
+			const firstOption = options.first()
+			const secondOption = options.nth(1)
+
+			// Initially no option should have tabindex="0"
+			await expect(firstOption).toHaveAttribute('tabindex', '-1')
+			await expect(secondOption).toHaveAttribute('tabindex', '-1')
+
+			// Select first option
+			await firstOption.click()
+
+			// Selected option should have tabindex="0"
+			await expect(firstOption).toHaveAttribute('tabindex', '0')
+			await expect(secondOption).toHaveAttribute('tabindex', '-1')
+
+			// Select second option
+			await secondOption.click()
+
+			// Tabindex should move to second option
+			await expect(firstOption).toHaveAttribute('tabindex', '-1')
+			await expect(secondOption).toHaveAttribute('tabindex', '0')
+		})
+
+		test('provides proper live region updates', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+
+			// Check error live region
+			const error = listbox.locator('.error')
+			await expect(error).toHaveAttribute('role', 'alert')
+			await expect(error).toHaveAttribute('aria-live', 'assertive')
+
+			// Check loading status
+			const loading = listbox.locator('.loading')
+			await expect(loading).toHaveAttribute('role', 'status')
+		})
+	})
+
+	test.describe('Form Integration', () => {
+		test('works with FormData and form submission', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			// Form is already wrapped in HTML, no need to create one
+
+			const firstOption = listbox.locator('button[role="option"]').first()
+			const optionValue = await firstOption.getAttribute('value')
+
+			await firstOption.click()
+
+			// Verify hidden input has the value
+			const hiddenInputValue = await page.evaluate(() => {
+				const hiddenInput = document.querySelector(
+					'form-listbox input[type="hidden"]',
+				) as HTMLInputElement
+				return hiddenInput?.value
+			})
+
+			expect(hiddenInputValue).toBe(optionValue)
+
+			// Test form data
+			const formData = await page.evaluate(() => {
+				const form = document.querySelector('form')
+				if (!form) return { error: 'No form found' }
+				const data = new FormData(form)
+				const entries = Object.fromEntries(data.entries())
+				return entries
+			})
+
+			// Debug form data if test fails
+			if (!formData.timezone) {
+				console.log('Form data:', formData)
+				console.log('Expected timezone value:', optionValue)
+				console.log('Hidden input value:', hiddenInputValue)
+			}
+
+			expect(formData).toEqual({ timezone: optionValue })
+		})
+	})
+
+	test.describe('Component Properties', () => {
+		test('value property reflects selected option', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			// Initially no value
+			let value = await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				return element.value
+			})
+			expect(value).toBe('')
+
+			const firstOption = listbox.locator('button[role="option"]').first()
+			const optionValue = await firstOption.getAttribute('value')
+
+			await firstOption.click()
+
+			// Value should update
+			value = await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				return element.value
+			})
+			expect(value).toBe(optionValue)
+		})
+
+		test('filter property controls option visibility', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			// Test getting filter property
+			let filter = await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				return element.filter
+			})
+			expect(filter).toBe('')
+
+			// Set filter property
+			await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				element.filter = 'america'
+			})
+
+			filter = await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				return element.filter
+			})
+			expect(filter).toBe('america')
+		})
+
+		test('src property controls data source', async ({ page }) => {
+			const src = await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				return element.src
+			})
+			expect(src).toBe('/form-listbox/mocks/timezones.json')
+
+			// Change src property
+			await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				element.src = '/different-url.json'
+			})
+
+			const newSrc = await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				return element.src
+			})
+			expect(newSrc).toBe('/different-url.json')
+		})
+	})
+
+	test.describe('Edge Cases and Performance', () => {
+		test('handles rapid property changes gracefully', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			// Test that rapid filter changes don't break the component
+			await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				// Apply filters that should all find results
+				element.filter = 'a'
+				element.filter = 'af'
+				element.filter = 'afr'
+				element.filter = 'a' // back to broader filter
+				element.filter = '' // clear filter
+			})
+
+			// Should show all options when filter is cleared
+			const visibleOptions = listbox.locator(
+				'button[role="option"]:not([hidden])',
+			)
+			const visibleCount = await visibleOptions.count()
+			const totalCount = await listbox.locator('button[role="option"]').count()
+
+			expect(visibleCount).toBe(totalCount)
+			expect(visibleCount).toBeGreaterThan(100)
+		})
+
+		test('handles empty groups correctly', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			// Apply filter that should make some groups empty
+			await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				element.filter = 'Zurich' // Only one option
+			})
+
+			// Groups with no visible options should be hidden via CSS
+			// Check that some groups are effectively hidden (either via CSS or JS)
+			const allGroups = listbox.locator('[role="group"]')
+			const totalGroups = await allGroups.count()
+
+			// Count groups that have visible options
+			let groupsWithVisibleOptions = 0
+			for (let i = 0; i < totalGroups; i++) {
+				const group = allGroups.nth(i)
+				const visibleOptionsInGroup = group.locator(
+					'button[role="option"]:not([hidden])',
+				)
+				const count = await visibleOptionsInGroup.count()
+				if (count > 0) {
+					groupsWithVisibleOptions++
+				}
+			}
+
+			expect(groupsWithVisibleOptions).toBeLessThan(totalGroups)
+			expect(groupsWithVisibleOptions).toBeGreaterThan(0)
+		})
+
+		test('maintains performance with large datasets', async ({ page }) => {
+			const listbox = page.locator('form-listbox').first()
+			await expect(listbox.locator('[role="listbox"]')).toBeVisible({
+				timeout: 1000,
+			})
+
+			const startTime = Date.now()
+
+			// Apply and clear filter rapidly
+			await page.evaluate(() => {
+				const element = document.querySelector('form-listbox') as any
+				for (let i = 0; i < 10; i++) {
+					element.filter = 'test'
+					element.filter = ''
+				}
+			})
+
+			const endTime = Date.now()
+			const duration = endTime - startTime
+
+			// Should complete quickly even with large dataset
+			expect(duration).toBeLessThan(2000)
+		})
+
+		test('handles component removal during loading', async ({ page }) => {
+			// Add a new listbox that will be removed quickly
+			await page.evaluate(() => {
+				const listbox = document.createElement('form-listbox')
+				listbox.setAttribute('src', '/form-listbox/timezones.json')
+				listbox.innerHTML = `
+					<input type="hidden" name="timezone" />
+					<card-callout>
+						<p class="loading" role="status">Loading...</p>
+						<p class="error" role="alert" aria-live="assertive" hidden></p>
+					</card-callout>
+					<module-scrollarea orientation="vertical">
+						<div role="listbox" aria-label="Test" hidden></div>
+					</module-scrollarea>
+				`
+				document.body.appendChild(listbox)
+
+				// Remove it quickly
+				setTimeout(() => listbox.remove(), 50)
+			})
+
+			// Wait to ensure no errors occur
+			await page.waitForTimeout(50)
+
+			// Test should complete without throwing errors
+			expect(true).toBe(true)
+		})
+	})
+
+	test.describe('Declarative Inline HTML', () => {
+		test('renders inline options without src attribute', async ({ page }) => {
+			const listbox = page.locator('form-listbox#colors')
+			const listboxElement = listbox.locator('[role="listbox"]')
+			const options = listboxElement.locator('button[role="option"]')
+
+			// Should show listbox immediately (no loading)
+			await expect(listboxElement).toBeVisible()
+
+			// Should have all inline options
+			await expect(options).toHaveCount(5)
+
+			// Should have correct option values and text
+			const firstOption = options.first()
+			await expect(firstOption).toHaveAttribute('value', 'red')
+			await expect(firstOption).toHaveText('Red')
+		})
+
+		test('handles option selection with inline HTML', async ({ page }) => {
+			const listbox = page.locator('form-listbox#colors')
+			const listboxElement = listbox.locator('[role="listbox"]')
+			const firstOption = listboxElement
+				.locator('button[role="option"]')
+				.first()
+
+			// Click first option
+			await firstOption.click()
+
+			// Should update component value
+			const componentValue = await listbox.getAttribute('value')
+			expect(componentValue).toBe('red')
+
+			// Should update hidden input
+			const hiddenInputValue = await listbox
+				.locator('input[type="hidden"]')
+				.inputValue()
+			expect(hiddenInputValue).toBe('red')
+
+			// Should mark option as selected
+			await expect(firstOption).toHaveAttribute('aria-selected', 'true')
+		})
+
+		test('supports filtering with inline options', async ({ page }) => {
+			const listbox = page.locator('form-listbox#colors')
+			const options = listbox.locator('button[role="option"]')
+
+			// All options visible initially
+			await expect(options).toHaveCount(5)
+			for (const option of await options.all()) {
+				await expect(option).toBeVisible()
+			}
+
+			// Set filter property
+			await listbox.evaluate((element: any) => {
+				element.filter = 'r'
+			})
+
+			// Should filter to options containing 'r'
+			const redOption = options.filter({ hasText: 'Red' })
+			const greenOption = options.filter({ hasText: 'Green' })
+			const yellowOption = options.filter({ hasText: 'Yellow' })
+			const blueOption = options.filter({ hasText: 'Blue' })
+			const purpleOption = options.filter({ hasText: 'Purple' })
+
+			await expect(redOption).toBeVisible() // Red contains 'r'
+			await expect(greenOption).toBeVisible() // Green contains 'r'
+			await expect(purpleOption).toBeVisible() // Purple contains 'r'
+			await expect(yellowOption).toBeHidden() // Yellow doesn't contain 'r'
+			await expect(blueOption).toBeHidden() // Blue doesn't contain 'r'
+
+			// Should highlight matching text
+			const greenOptionForHighlight = options.filter({ hasText: 'Green' })
+			const highlightedMark = greenOptionForHighlight.locator('mark')
+			await expect(highlightedMark).toBeVisible()
+			await expect(highlightedMark).toHaveText('r')
+		})
+
+		test('renders grouped inline options correctly', async ({ page }) => {
+			const listbox = page.locator('form-listbox#fruits')
+			const listboxElement = listbox.locator('[role="listbox"]')
+			const groups = listboxElement.locator('[role="group"]')
+			const options = listboxElement.locator('button[role="option"]')
+
+			// Should have both groups
+			await expect(groups).toHaveCount(2)
+
+			// Should have all options
+			await expect(options).toHaveCount(6)
+
+			// Should have proper group labels
+			const citrusLabel = listboxElement.locator('#fruits-citrus')
+			await expect(citrusLabel).toHaveText('Citrus')
+
+			const berriesLabel = listboxElement.locator('#fruits-berries')
+			await expect(berriesLabel).toHaveText('Berries')
+
+			// Should maintain group structure for selection
+			const orangeOption = options.filter({ hasText: 'Orange' })
+			await orangeOption.click()
+
+			const componentValue = await listbox.getAttribute('value')
+			expect(componentValue).toBe('orange')
+		})
+
+		test('works with form integration using inline options', async ({
+			page,
+		}) => {
+			const listbox = page.locator('form-listbox#colors')
+			const firstOption = listbox.locator('button[role="option"]').first()
+
+			// Select an option
+			await firstOption.click()
+
+			// Check FormData
+			const formData = await page.evaluate(() => {
+				const form = document.querySelector(
+					'form:nth-of-type(2)',
+				) as HTMLFormElement
+				if (!form) throw new Error('Form not found')
+				const data = new FormData(form)
+				const entries = Array.from(data.entries())
+				return Object.fromEntries(entries)
+			})
+
+			expect(formData.color).toBe('red')
+		})
+
+		test('handles mixed content without src attribute', async ({ page }) => {
+			const listbox = page.locator('form-listbox#colors')
+			const options = listbox.locator('button[role="option"]')
+
+			// Should only count actual option buttons (using colors example)
+			await expect(options).toHaveCount(5)
+
+			// Should still work for selection
+			const firstOption = options.first()
+			await firstOption.click()
+
+			const componentValue = await listbox.getAttribute('value')
+			expect(componentValue).toBe('red')
+		})
+	})
+})