fluentui-extended 0.1.0

package/README.md

@@ -0,0 +1,239 @@
+# FluentUI-Extended
+
+Extended components for Fluent UI v9, designed to match Dynamics 365 patterns.
+
+[![npm version](https://badge.fury.io/js/fluentui-extended.svg)](https://www.npmjs.com/package/fluentui-extended)
+[![CI](https://github.com/garethcheyne/npm-fluentui-extended/actions/workflows/ci.yml/badge.svg)](https://github.com/garethcheyne/npm-fluentui-extended/actions)
+
+## Installation
+
+```bash
+npm install fluentui-extended @fluentui/react-components @fluentui/react-icons
+```
+
+## Components
+
+### Lookup
+
+A searchable dropdown component styled after Dynamics 365 lookup fields. Supports async search, expandable option details, and customizable header/footer.
+
+## Quick Start
+
+```tsx
+import { Lookup, LookupOption } from 'fluentui-extended';
+import { FluentProvider, webLightTheme } from '@fluentui/react-components';
+
+const options: LookupOption[] = [
+  { key: '1', text: 'Contoso Ltd', secondaryText: 'CON001' },
+  { key: '2', text: 'Fabrikam Inc', secondaryText: 'FAB001' },
+  { key: '3', text: 'Adventure Works', secondaryText: 'ADV001' },
+];
+
+function App() {
+  const [selected, setSelected] = useState<LookupOption | null>(null);
+
+  return (
+    <FluentProvider theme={webLightTheme}>
+      <Lookup
+        options={options}
+        selectedOption={selected}
+        onOptionSelect={setSelected}
+        placeholder="Search accounts..."
+      />
+    </FluentProvider>
+  );
+}
+```
+
+## Features
+
+### Basic Selection (with key)
+
+```tsx
+const [selectedKey, setSelectedKey] = useState<string | null>(null);
+
+<Lookup
+  options={options}
+  selectedKey={selectedKey}
+  onOptionSelect={(opt) => setSelectedKey(opt?.key ?? null)}
+  placeholder="Search..."
+/>
+```
+
+### Async Search (API Integration)
+
+For async scenarios, use `selectedOption` to persist the display value when options change:
+
+```tsx
+function AsyncLookup() {
+  const [options, setOptions] = useState<LookupOption[]>([]);
+  const [selected, setSelected] = useState<LookupOption | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  const handleSearch = async (searchText: string) => {
+    setLoading(true);
+    const response = await fetch(`/api/accounts?search=${searchText}`);
+    setOptions(await response.json());
+    setLoading(false);
+  };
+
+  return (
+    <Lookup
+      options={options}
+      selectedOption={selected}
+      onOptionSelect={setSelected}
+      onSearchChange={handleSearch}
+      loading={loading}
+      searchDebounceMs={300}
+      placeholder="Type to search..."
+    />
+  );
+}
+```
+
+### With Icons and Expandable Details
+
+Options can include icons and expandable detail rows (click chevron to expand):
+
+```tsx
+import { BuildingRegular } from '@fluentui/react-icons';
+
+const options: LookupOption[] = [
+  {
+    key: '1',
+    text: 'Contoso Ltd',
+    secondaryText: 'CON001',
+    icon: <BuildingRegular />,
+    details: [
+      { label: 'Phone', value: '555-0100' },
+      { label: 'Industry', value: 'Technology' },
+      { value: 'Active Customer' },
+    ],
+    data: { id: 'acc-001', revenue: 5000000 }, // Custom data accessible in onOptionSelect
+  },
+];
+```
+
+### Dynamics 365 Style (Header & Footer)
+
+```tsx
+import { Text, Button, Link } from '@fluentui/react-components';
+import { AddRegular, PersonSearchRegular } from '@fluentui/react-icons';
+
+<Lookup
+  options={options}
+  selectedOption={selected}
+  onOptionSelect={setSelected}
+  header={
+    <>
+      <Text size={200}>Accounts</Text>
+      <Button appearance="outline" size="small">Recent records</Button>
+    </>
+  }
+  footer={
+    <>
+      <Link style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+        <AddRegular /> New
+      </Link>
+      <Link style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+        <PersonSearchRegular /> Advanced
+      </Link>
+    </>
+  }
+/>
+```
+
+## API Reference
+
+### Lookup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `LookupOption[]` | `[]` | Options to display in the dropdown |
+| `selectedKey` | `string \| null` | - | Selected option key (controlled) |
+| `selectedOption` | `LookupOption \| null` | - | Selected option object (recommended for async) |
+| `onOptionSelect` | `(option: LookupOption \| null) => void` | - | Selection change callback |
+| `onSearchChange` | `(searchText: string) => void` | - | Search text change callback |
+| `placeholder` | `string` | `'Search...'` | Input placeholder |
+| `loading` | `boolean` | `false` | Show loading spinner |
+| `noResultsMessage` | `string` | `'No results found'` | Empty state message |
+| `clearable` | `boolean` | `true` | Show clear button |
+| `minSearchLength` | `number` | `0` | Min chars before search fires |
+| `searchDebounceMs` | `number` | `300` | Search debounce delay (ms) |
+| `header` | `ReactNode` | - | Header content |
+| `footer` | `ReactNode` | - | Footer content |
+| `disabled` | `boolean` | `false` | Disable the lookup |
+
+*Also accepts all Fluent UI `Input` props except `onChange` and `value`.*
+
+### LookupOption
+
+```ts
+interface LookupOption {
+  key: string;                    // Unique identifier (required)
+  text: string;                   // Display text (required)
+  secondaryText?: string;         // Secondary line of text
+  icon?: ReactNode;               // Icon component
+  details?: LookupOptionDetail[]; // Expandable details (chevron appears)
+  data?: unknown;                 // Custom data payload
+  disabled?: boolean;             // Disable this option
+}
+
+interface LookupOptionDetail {
+  label?: string;  // Optional label (e.g., "Phone:")
+  value: string;   // Detail value
+}
+```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `↓` | Open dropdown / Move to next option |
+| `↑` | Move to previous option |
+| `Enter` | Select highlighted option |
+| `Escape` | Close dropdown |
+| `Tab` | Close dropdown and move focus |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run demo app
+npm run demo
+
+# Build library
+npm run build
+
+# Type check
+npm run typecheck
+
+# Watch mode
+npm run dev
+```
+
+## GitHub Actions
+
+This project includes CI/CD workflows:
+
+- **CI** (`ci.yml`) - Runs on push/PR to main: type checking and build
+- **Release** (`release.yml`) - Publishes to npm when a GitHub release is created
+
+### Setup npm Publishing
+
+1. Create an npm access token at [npmjs.com](https://www.npmjs.com/settings/~/tokens)
+2. Add it as a repository secret named `NPM_TOKEN` in GitHub Settings → Secrets
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MITMIT

package/dist/index.d.mts

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import { InputProps } from '@fluentui/react-components';
+
+interface LookupOptionDetail {
+    /** Label for the detail row */
+    label?: string;
+    /** Value for the detail row */
+    value: string;
+}
+interface LookupOption {
+    /** Unique identifier for the option */
+    key: string;
+    /** Display text for the option */
+    text: string;
+    /** Optional secondary text */
+    secondaryText?: string;
+    /** Optional icon to display */
+    icon?: React.ReactNode;
+    /** Optional expandable details */
+    details?: LookupOptionDetail[];
+    /** Optional data associated with the option */
+    data?: unknown;
+    /** Whether the option is disabled */
+    disabled?: boolean;
+}
+interface LookupProps extends Omit<InputProps, 'onChange' | 'value'> {
+    /** The options to display in the dropdown */
+    options?: LookupOption[];
+    /** Currently selected option key (use with options array lookup) */
+    selectedKey?: string | null;
+    /** Currently selected option (use for controlled selection with full data) */
+    selectedOption?: LookupOption | null;
+    /** Callback when selection changes - receives full option with data */
+    onOptionSelect?: (option: LookupOption | null) => void;
+    /** Callback when search text changes - use for async loading */
+    onSearchChange?: (searchText: string) => void;
+    /** Placeholder text when no selection */
+    placeholder?: string;
+    /** Whether the lookup is loading options */
+    loading?: boolean;
+    /** Message to display when no results found */
+    noResultsMessage?: string;
+    /** Whether to allow clearing the selection */
+    clearable?: boolean;
+    /** Minimum characters before triggering search */
+    minSearchLength?: number;
+    /** Debounce delay for search in milliseconds */
+    searchDebounceMs?: number;
+    /** Whether the dropdown should match the input width */
+    matchInputWidth?: boolean;
+    /** Header content rendered at the top of the dropdown */
+    header?: React.ReactNode;
+    /** Footer content rendered at the bottom of the dropdown */
+    footer?: React.ReactNode;
+}
+
+declare const Lookup: React.FC<LookupProps>;
+
+export { Lookup, type LookupOption, type LookupOptionDetail, type LookupProps };

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import { InputProps } from '@fluentui/react-components';
+
+interface LookupOptionDetail {
+    /** Label for the detail row */
+    label?: string;
+    /** Value for the detail row */
+    value: string;
+}
+interface LookupOption {
+    /** Unique identifier for the option */
+    key: string;
+    /** Display text for the option */
+    text: string;
+    /** Optional secondary text */
+    secondaryText?: string;
+    /** Optional icon to display */
+    icon?: React.ReactNode;
+    /** Optional expandable details */
+    details?: LookupOptionDetail[];
+    /** Optional data associated with the option */
+    data?: unknown;
+    /** Whether the option is disabled */
+    disabled?: boolean;
+}
+interface LookupProps extends Omit<InputProps, 'onChange' | 'value'> {
+    /** The options to display in the dropdown */
+    options?: LookupOption[];
+    /** Currently selected option key (use with options array lookup) */
+    selectedKey?: string | null;
+    /** Currently selected option (use for controlled selection with full data) */
+    selectedOption?: LookupOption | null;
+    /** Callback when selection changes - receives full option with data */
+    onOptionSelect?: (option: LookupOption | null) => void;
+    /** Callback when search text changes - use for async loading */
+    onSearchChange?: (searchText: string) => void;
+    /** Placeholder text when no selection */
+    placeholder?: string;
+    /** Whether the lookup is loading options */
+    loading?: boolean;
+    /** Message to display when no results found */
+    noResultsMessage?: string;
+    /** Whether to allow clearing the selection */
+    clearable?: boolean;
+    /** Minimum characters before triggering search */
+    minSearchLength?: number;
+    /** Debounce delay for search in milliseconds */
+    searchDebounceMs?: number;
+    /** Whether the dropdown should match the input width */
+    matchInputWidth?: boolean;
+    /** Header content rendered at the top of the dropdown */
+    header?: React.ReactNode;
+    /** Footer content rendered at the bottom of the dropdown */
+    footer?: React.ReactNode;
+}
+
+declare const Lookup: React.FC<LookupProps>;
+
+export { Lookup, type LookupOption, type LookupOptionDetail, type LookupProps };