feat(ncids): Implement Autocomplete combobox component

.npmrc

@@ -1,3 +1,3 @@
 @nciocpl:registry=https://npm.pkg.github.com
 engine-strict=true
-legacy-peer-deps=true
+legacy-peer-deps=true

src/components/ncids/Autocomplete/Autocomplete.module.scss

@@ -0,0 +1,78 @@
+.autocomplete {
+	position: relative;
+	display: inline-block;
+}
+
+.inputWrapper {
+	position: relative;
+	display: flex;
+	align-items: center;
+}
+
+.autocompleteInput {
+	width: 100%;
+	padding-right: 2rem;
+}
+
+.clearButton {
+	position: absolute;
+	right: 0.5rem;
+	top: 50%;
+	transform: translateY(-50%);
+	background: none;
+	border: none;
+	cursor: pointer;
+	font-size: 1.25rem;
+	line-height: 1;
+	padding: 0 0.25rem;
+	color: #71767a;
+
+	&:hover {
+		color: #1b1b1b;
+	}
+
+	&:focus {
+		outline: 0.25rem solid #2491ff;
+		outline-offset: 0;
+	}
+}
+
+.listbox {
+	position: absolute;
+	z-index: 100;
+	top: 100%;
+	left: 0;
+	right: 0;
+	background-color: #ffffff;
+	border: 1px solid #a9aeb1;
+	border-top: none;
+	border-radius: 0 0 0.25rem 0.25rem;
+	list-style: none;
+	margin: 0;
+	padding: 0;
+	max-height: 15rem;
+	overflow-y: auto;
+	box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
+}
+
+.option {
+	padding: 0.5rem 1rem;
+	cursor: pointer;
+	font-size: 1rem;
+
+	&:hover {
+		background-color: #f0f0f0;
+	}
+}
+
+.optionHighlighted {
+	background-color: #d9e8f6;
+	outline: none;
+}
+
+.statusMessage {
+	padding: 0.5rem 1rem;
+	color: #71767a;
+	font-style: italic;
+	cursor: default;
+}

src/components/ncids/Autocomplete/Autocomplete.stories.tsx

@@ -0,0 +1,190 @@
+import React, { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { fn } from '@storybook/test';
+
+import { Autocomplete } from './Autocomplete';
+import type { AutocompleteOption } from './Autocomplete';
+
+const fruits: AutocompleteOption[] = [
+	{ label: 'Apple', value: 'apple' },
+	{ label: 'Apricot', value: 'apricot' },
+	{ label: 'Avocado', value: 'avocado' },
+	{ label: 'Banana', value: 'banana' },
+	{ label: 'Blueberry', value: 'blueberry' },
+	{ label: 'Cherry', value: 'cherry' },
+	{ label: 'Coconut', value: 'coconut' },
+	{ label: 'Grape', value: 'grape' },
+	{ label: 'Kiwi', value: 'kiwi' },
+	{ label: 'Lemon', value: 'lemon' },
+	{ label: 'Mango', value: 'mango' },
+	{ label: 'Orange', value: 'orange' },
+	{ label: 'Peach', value: 'peach' },
+	{ label: 'Pear', value: 'pear' },
+	{ label: 'Pineapple', value: 'pineapple' },
+	{ label: 'Strawberry', value: 'strawberry' },
+	{ label: 'Watermelon', value: 'watermelon' },
+];
+
+const meta: Meta<typeof Autocomplete<AutocompleteOption>> = {
+	title: 'NCIDS/Autocomplete',
+	component: Autocomplete,
+	tags: ['autodocs'],
+	argTypes: {
+		debounceDelay: {
+			control: { type: 'number', min: 0, max: 1000, step: 50 },
+			description: 'Debounce delay in milliseconds',
+		},
+		disabled: { control: 'boolean' },
+		noOptionsMessage: { control: 'text' },
+		loadingMessage: { control: 'text' },
+		placeholder: { control: 'text' },
+	},
+};
+
+export default meta;
+type Story = StoryObj<typeof Autocomplete<AutocompleteOption>>;
+
+/** Basic usage with a synchronous list of options. */
+export const Default: Story = {
+	args: {
+		id: 'fruit-autocomplete',
+		label: 'Fruit',
+		options: fruits,
+		placeholder: 'Type to search…',
+		onChange: fn(),
+	},
+};
+
+/** Asynchronous data loading with a simulated 400 ms network delay. */
+export const AsyncLoadOptions: Story = {
+	args: {
+		id: 'fruit-async',
+		label: 'Fruit (async)',
+		placeholder: 'Type to search…',
+		debounceDelay: 300,
+		loadOptions: (query: string) =>
+			new Promise((resolve) =>
+				setTimeout(
+					() =>
+						resolve(
+							fruits.filter((f) =>
+								f.label.toLowerCase().includes(query.toLowerCase())
+							)
+						),
+					400
+				)
+			),
+		onChange: fn(),
+	},
+};
+
+/** Customise the message when no option matches the search query. */
+export const CustomNoOptionsMessage: Story = {
+	args: {
+		id: 'fruit-no-opts',
+		label: 'Fruit',
+		options: fruits,
+		placeholder: 'Try "xyz"…',
+		noOptionsMessage: 'No matching fruit — try something else.',
+		onChange: fn(),
+	},
+};
+
+/** Custom option renderer that adds an emoji prefix. */
+export const CustomRenderOption: Story = {
+	args: {
+		id: 'fruit-custom',
+		label: 'Fruit',
+		options: fruits,
+		renderOption: (opt: AutocompleteOption, isHighlighted: boolean) => (
+			<span style={{ fontWeight: isHighlighted ? 'bold' : 'normal' }}>
+				🍓 {opt.label}
+			</span>
+		),
+		onChange: fn(),
+	},
+};
+
+/** Disabled state. */
+export const Disabled: Story = {
+	args: {
+		id: 'fruit-disabled',
+		label: 'Fruit',
+		options: fruits,
+		value: { label: 'Apple', value: 'apple' },
+		disabled: true,
+		onChange: fn(),
+	},
+};
+
+/** Controlled component — the parent manages the selected value. */
+const ControlledTemplate = (args: React.ComponentProps<typeof Autocomplete<AutocompleteOption>>) => {
+	const [value, setValue] = useState<AutocompleteOption | null>(null);
+	return (
+		<div>
+			<Autocomplete
+				{...args}
+				value={value}
+				onChange={(opt) => setValue(opt)}
+			/>
+			<p style={{ marginTop: '1rem' }}>
+				Selected:{' '}
+				<strong>{value ? `${value.label} (${value.value})` : 'none'}</strong>
+			</p>
+		</div>
+	);
+};
+
+export const Controlled: Story = {
+	render: (args) => <ControlledTemplate {...args} />,
+	args: {
+		id: 'fruit-controlled',
+		label: 'Fruit',
+		options: fruits,
+		placeholder: 'Pick a fruit…',
+	},
+};
+
+interface Country {
+	name: string;
+	code: string;
+}
+
+const countries: Country[] = [
+	{ name: 'United States', code: 'us' },
+	{ name: 'United Kingdom', code: 'uk' },
+	{ name: 'Canada', code: 'ca' },
+	{ name: 'Australia', code: 'au' },
+	{ name: 'Germany', code: 'de' },
+	{ name: 'France', code: 'fr' },
+	{ name: 'Japan', code: 'jp' },
+];
+
+const CustomOptionShapeTemplate = () => {
+	const [value, setValue] = useState<Country | null>(null);
+	return (
+		<div>
+			<Autocomplete<Country>
+				id="country"
+				label="Country"
+				options={countries}
+				getOptionLabel={(c) => c.name}
+				getOptionValue={(c) => c.code}
+				placeholder="Search countries…"
+				value={value}
+				onChange={(c) => setValue(c)}
+			/>
+			{value && (
+				<p style={{ marginTop: '1rem' }}>
+					Selected: <strong>{value.name}</strong> ({value.code})
+				</p>
+			)}
+		</div>
+	);
+};
+
+/** Using generic options with custom getOptionLabel / getOptionValue. */
+export const CustomOptionShape: Story = {
+	render: () => <CustomOptionShapeTemplate />,
+	args: {},
+};