fluentui-extended 2026.6.12 → 2026.8.31

package/README.md

@@ -38,6 +38,7 @@ An Advanced Find-style query builder for Dynamics 365. Build complex filter cond
 ## Quick Start
 
 ```tsx
+import { useState } from 'react';
 import { Lookup, LookupOption } from 'fluentui-extended';
 import { FluentProvider, webLightTheme } from '@fluentui/react-components';
 
@@ -161,6 +162,113 @@ import { AddRegular, PersonSearchRegular } from '@fluentui/react-icons';
 />
 ```
 
+### Multi-Entity Lookup with Filter Buttons
+
+Replicate the native Dynamics 365 lookup pattern where users can filter between entity types:
+
+```tsx
+import { Text, Button, Link, ToggleButton } from '@fluentui/react-components';
+import { BuildingRegular, PersonRegular, ArrowLeftRegular } from '@fluentui/react-icons';
+
+function MultiEntityLookup() {
+  const [showAccounts, setShowAccounts] = useState(true);
+  const [showContacts, setShowContacts] = useState(true);
+
+  const options: LookupOption[] = [
+    { key: 'acc-1', text: 'Contoso Ltd', icon: <BuildingRegular />, details: [...] },
+    { key: 'con-1', text: 'John Smith', icon: <PersonRegular />, details: [...] },
+  ];
+
+  // Filter based on key prefix
+  const filteredOptions = useMemo(() => 
+    options.filter(opt => {
+      if (opt.key.startsWith('acc-')) return showAccounts;
+      if (opt.key.startsWith('con-')) return showContacts;
+      return true;
+    }), [showAccounts, showContacts]
+  );
+
+  return (
+    <Lookup
+      options={filteredOptions}
+      header={
+        // Drill-down view when single entity selected
+        showAccounts !== showContacts ? (
+          <>
+            <Link onClick={() => { setShowAccounts(true); setShowContacts(true); }}>
+              <ArrowLeftRegular /> All
+            </Link>
+            <Text weight="semibold">{showAccounts ? 'Accounts' : 'Contacts'}</Text>
+          </>
+        ) : (
+          // Filter toggles when showing all
+          <>
+            <div style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+              <Text size={200}>Results from:</Text>
+              <ToggleButton size="small" checked={showAccounts}
+                onClick={() => { setShowAccounts(true); setShowContacts(false); }}>
+                Accounts
+              </ToggleButton>
+              <ToggleButton size="small" checked={showContacts}
+                onClick={() => { setShowAccounts(false); setShowContacts(true); }}>
+                Contacts
+              </ToggleButton>
+            </div>
+            <Button size="small">Recent records</Button>
+          </>
+        )
+      }
+    />
+  );
+}
+```
+
+### Rich Secondary Text with React Elements
+
+Both `secondaryText` and `details` support React elements, not just strings:
+
+```tsx
+import { Badge } from '@fluentui/react-components';
+import { CheckmarkCircleRegular } from '@fluentui/react-icons';
+
+const options: LookupOption[] = [
+  {
+    key: '1',
+    text: 'John Smith',
+    secondaryText: (
+      <span style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+        <Badge appearance="tint" color="success" size="small" icon={<CheckmarkCircleRegular />}>
+          Active
+        </Badge>
+        <span>john.smith@contoso.com</span>
+      </span>
+    ),
+    icon: <PersonRegular />,
+    details: [
+      { label: 'Status', value: <Badge appearance="filled" color="success" size="small">Verified</Badge> },
+      { label: 'Role', value: <Badge appearance="tint" color="brand" size="small">Decision Maker</Badge> },
+      { value: <span style={{ color: '#0078d4' }}>View full profile →</span> },
+    ],
+  },
+];
+```
+
+---
+
+## Test Harness Examples
+
+Run the test harness with `npm run harness` to see all examples in action.
+
+| Example | Description |
+|---------|-------------|
+| **Basic Lookup** | Simple lookup with expandable details, no header/footer |
+| **Header & Footer** | D365-style with "Accounts" header and "New" / "Advanced" footer links |
+| **Details Only (No Secondary Text)** | Options with icons + details but no secondary text; demonstrates icon centering on single-line text |
+| **Multi-Entity Filter** | Toggle between Accounts/Contacts with drill-down header pattern (← All) |
+| **Dynamic Search (Async API)** | Simulated 800ms API delay with loading spinner; auto-loads top 5 on open |
+| **Live Dynamics Lookup** | Connects to real D365 environment via Xrm.WebApi (when connected) |
+| **QueryBuilder** | Full Advanced Find-style query builder with FetchXML serialization |
+
 ## API Reference
 
 ### Lookup Props
@@ -185,6 +293,45 @@ import { AddRegular, PersonSearchRegular } from '@fluentui/react-icons';
 | `disabled` | `boolean` | `false` | Disable the lookup |
 | `open` | `boolean` | - | Controlled open state for the dropdown |
 | `onOpenChange` | `(open: boolean) => void` | - | Callback when dropdown open state changes |
+| `disableClientFilter` | `boolean` | `false` | Disable client-side filtering of options. Use this when filtering is performed server-side via `onSearchChange` |
+| `searchFields` | `string` | - | Hidden searchable text (never rendered). Use this to include additional searchable content (codes, IDs) while displaying JSX in `secondaryText` |
+
+### Client-Side Filtering
+
+By default, the Lookup component filters options client-side as the user types. The filtering logic works as follows:
+
+1. **Primary field (`text`)** — Always searched, regardless of other props
+2. **Search fields (`searchFields`)** — If provided, this hidden text is searched (useful when `secondaryText` is JSX)
+3. **Secondary text (`secondaryText`)** — Only searched if it's a string (JSX elements are skipped)
+
+This allows you to use rich JSX (badges, icons) in `secondaryText` while still providing searchable text via `searchFields`:
+
+```tsx
+const options: LookupOption[] = [
+  {
+    key: 'PROD-001',
+    text: 'Acme Widget',                           // Always searchable
+    searchFields: 'PROD-001 SKU-12345 acme-widget', // Hidden searchable text
+    secondaryText: (                               // Rich display (not searchable)
+      <span style={{ display: 'flex', gap: 4 }}>
+        <Badge size="small">PROD-001</Badge>
+        <Badge size="small" color="brand">SKU-12345</Badge>
+      </span>
+    ),
+  },
+];
+```
+
+**Server-Side Filtering:** When using `onSearchChange` to fetch results from an API, set `disableClientFilter={true}` to prevent the client from re-filtering server results:
+
+```tsx
+<Lookup
+  options={apiResults}
+  onSearchChange={(searchText) => fetchFromApi(searchText)}
+  disableClientFilter={true}  // API already filtered the results
+  loading={isLoading}
+/>
+```
 
 ### Cross-Document Support (Dynamics 365 Iframes)
 
@@ -216,21 +363,24 @@ The Lookup component extends Fluent UI's `Input` and supports these standard pro
 
 ```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
+  key: string;                      // Unique identifier (required)
+  text: string;                     // Display text (required)
+  secondaryText?: ReactNode;        // Secondary line - string, Badge, or JSX
+  searchFields?: string;            // Hidden searchable text (never rendered)
+  icon?: ReactNode;                 // Icon component (e.g., <BuildingRegular />)
+  details?: LookupOptionDetail[];   // Expandable details (chevron appears)
+  data?: unknown;                   // Custom data payload for your app
+  disabled?: boolean;               // Disable this option
 }
 
 interface LookupOptionDetail {
-  label?: string;  // Optional label (e.g., "Phone:")
-  value: string;   // Detail value
+  label?: ReactNode;  // Optional label (e.g., "Phone:" or a Badge)
+  value: ReactNode;   // Detail value - string or JSX element
 }
 ```
 
+> **Note:** Both `secondaryText` and `details` support React elements, not just strings. See [Rich Secondary Text](#rich-secondary-text-with-react-elements) for examples. When using JSX in `secondaryText`, use `searchFields` to provide hidden searchable text (see [Client-Side Filtering](#client-side-filtering)).
+
 ## Keyboard Navigation
 
 | Key | Action |
@@ -526,14 +676,6 @@ if (!result.isValid) {
 
 ---
 
-## 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
-
 ## Acknowledgments
 
 This library extends [Microsoft's Fluent UI React v9](https://react.fluentui.dev/) components. Thank you to Microsoft and the Fluent UI team for creating and maintaining such an excellent design system.
@@ -542,6 +684,83 @@ This library extends [Microsoft's Fluent UI React v9](https://react.fluentui.dev
 - [Fluent UI GitHub](https://github.com/microsoft/fluentui)
 - [Fluent 2 Design System](https://fluent2.microsoft.design/)
 
+---
+
+## Changelog
+
+> Version format: `YYYY.M.DD` (e.g., `2026.8.30` = August 30, 2026)
+
+### 2026.8.30
+
+- ✨ Added multi-entity filter pattern with drill-down header ("← All" back button) in test harness
+- ✨ Added "Details Only (No Secondary Text)" example to test harness
+- ✨ Support for React elements in `secondaryText` and `details[].value` (Badges, icons, styled text)
+- ♻️ Improved `aria-selected`/`aria-disabled` attribute handling
+- 📝 Documentation overhaul with complete API reference and examples
+
+### 2026.6.12
+
+- ✨ Added React 19 support to peerDependencies
+- 📝 Updated README with cross-document support documentation
+
+### 2026.2.19
+
+- 🐛 Fixed cross-document dismiss in Dynamics 365 iframes using `ownerDocument`
+
+### 2026.2.17
+
+- 🐛 Removed `requestAnimationFrame` — handler registers immediately
+- 🐛 Switched to capture phase for dismiss handler to prevent D365 DOM interference
+
+### 2026.2.15
+
+- ✨ Added controlled `open` and `onOpenChange` props for programmatic dropdown control
+- 🐛 Removed `requestAnimationFrame` from dismiss handler
+
+### 2026.2.13
+
+- ♻️ Rebuilt popup from scratch using custom element (Fluent UI Popover had unexpected behavior)
+
+### 2026.2.11
+
+- 🐛 Added `onOpenChange` callback to sync internal state with Popover dismiss events (outside click, Escape, focus loss)
+
+### 2026.2.10
+
+- 🐛 Fixed Lookup not allowing space character in search input
+
+### 2026.2.8
+
+- ✨ **QueryBuilder**: Native API integration for field metadata
+- ✨ **QueryBuilder**: Lookup field support with related entity validation
+
+### 2026.2.7
+
+- ♻️ Removed `Xrm` global dependency — now uses native `/api/data/v9.2/` fetch calls
+
+### 2026.2.6
+
+- ♻️ **QueryBuilder**: Refactored to reuse shared components and styles
+
+### 2026.2.5
+
+- ✨ **QueryBuilder**: Initial release (beta) — Advanced Find-style query builder
+- ♻️ **Lookup**: Changed from options-only to popup-based rendering
+
+### 2026.2.3
+
+- ✨ Added `id` prop — auto-generated if not provided
+
+### 2026.2.2
+
+- 🐛 Fixed classic JSX transform for React 16 compatibility
+- ✨ Added React 16.8+ support
+
+### 2026.2.1
+
+- 🎉 Initial release
+- ✨ Lookup component with async search, expandable details, header/footer
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -2,18 +2,25 @@ 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;
+    /** Label for the detail row - can be a string or React element */
+    label?: React.ReactNode;
+    /** Value for the detail row - can be a string or React element */
+    value: React.ReactNode;
 }
 interface LookupOption {
     /** Unique identifier for the option */
     key: string;
     /** Display text for the option */
     text: string;
-    /** Optional secondary text */
-    secondaryText?: string;
+    /** Optional secondary text - can be a string or React element */
+    secondaryText?: React.ReactNode;
+    /**
+     * Optional searchable text that is never rendered. Use this to include
+     * additional searchable content (codes, IDs, etc.) without affecting display.
+     * Client-side filtering will search this field in addition to `text` and
+     * string `secondaryText`.
+     */
+    searchFields?: string;
     /** Optional icon to display */
     icon?: React.ReactNode;
     /** Optional expandable details */
@@ -64,6 +71,12 @@ interface LookupProps extends Omit<InputProps, 'onChange' | 'value'> {
      * Use together with `open` for controlled mode, or standalone to observe changes.
      */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Disable client-side filtering of options. Use this when filtering is
+     * performed server-side via `onSearchChange` and the returned options are
+     * already filtered. Defaults to `false` (client-side filtering enabled).
+     */
+    disableClientFilter?: boolean;
 }
 
 declare const Lookup: React.FC<LookupProps>;

package/dist/index.d.ts

@@ -2,18 +2,25 @@ 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;
+    /** Label for the detail row - can be a string or React element */
+    label?: React.ReactNode;
+    /** Value for the detail row - can be a string or React element */
+    value: React.ReactNode;
 }
 interface LookupOption {
     /** Unique identifier for the option */
     key: string;
     /** Display text for the option */
     text: string;
-    /** Optional secondary text */
-    secondaryText?: string;
+    /** Optional secondary text - can be a string or React element */
+    secondaryText?: React.ReactNode;
+    /**
+     * Optional searchable text that is never rendered. Use this to include
+     * additional searchable content (codes, IDs, etc.) without affecting display.
+     * Client-side filtering will search this field in addition to `text` and
+     * string `secondaryText`.
+     */
+    searchFields?: string;
     /** Optional icon to display */
     icon?: React.ReactNode;
     /** Optional expandable details */
@@ -64,6 +71,12 @@ interface LookupProps extends Omit<InputProps, 'onChange' | 'value'> {
      * Use together with `open` for controlled mode, or standalone to observe changes.
      */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Disable client-side filtering of options. Use this when filtering is
+     * performed server-side via `onSearchChange` and the returned options are
+     * already filtered. Defaults to `false` (client-side filtering enabled).
+     */
+    disableClientFilter?: boolean;
 }
 
 declare const Lookup: React.FC<LookupProps>;

package/dist/index.js

@@ -88,15 +88,19 @@ var useLookupStyles = reactComponents.makeStyles({
     flexDirection: "row",
     alignItems: "flex-start",
     boxSizing: "border-box",
-    padding: "8px 12px",
+    paddingTop: "6px",
+    paddingBottom: "6px",
+    paddingLeft: "12px",
+    paddingRight: "8px",
     cursor: "pointer",
-    borderRadius: reactComponents.tokens.borderRadiusSmall,
+    borderRadius: reactComponents.tokens.borderRadiusNone,
     backgroundColor: "transparent",
     border: "none",
     width: "100%",
     overflow: "hidden",
     textAlign: "left",
-    gap: "8px",
+    gap: "10px",
+    minHeight: "40px",
     "&:hover": {
       backgroundColor: reactComponents.tokens.colorNeutralBackground1Hover
     },
@@ -110,16 +114,24 @@ var useLookupStyles = reactComponents.makeStyles({
     display: "flex",
     alignItems: "center",
     justifyContent: "center",
-    width: "20px",
-    height: "20px",
+    width: "24px",
+    height: "24px",
+    fontSize: "20px",
     flexShrink: 0,
-    color: reactComponents.tokens.colorNeutralForeground3
+    color: reactComponents.tokens.colorNeutralForeground1,
+    marginTop: "0px"
+    // Centered on single text row
+  },
+  optionIconWithSecondary: {
+    marginTop: "6px"
+    // Centered between text + secondaryText rows
   },
   optionContent: {
     display: "flex",
     flexDirection: "column",
     flex: "1 1 auto",
-    minWidth: 0
+    minWidth: 0,
+    gap: "2px"
   },
   optionExpandButton: {
     display: "flex",
@@ -128,6 +140,7 @@ var useLookupStyles = reactComponents.makeStyles({
     width: "24px",
     height: "24px",
     marginLeft: "auto",
+    marginTop: "2px",
     flexShrink: 0,
     cursor: "pointer",
     borderRadius: reactComponents.tokens.borderRadiusSmall,
@@ -161,14 +174,15 @@ var useLookupStyles = reactComponents.makeStyles({
   },
   optionText: {
     fontSize: reactComponents.tokens.fontSizeBase300,
-    fontWeight: reactComponents.tokens.fontWeightRegular,
-    color: reactComponents.tokens.colorNeutralForeground1
+    fontWeight: reactComponents.tokens.fontWeightSemibold,
+    color: reactComponents.tokens.colorNeutralForeground1,
+    lineHeight: reactComponents.tokens.lineHeightBase300
   },
   optionSecondaryText: {
     fontSize: reactComponents.tokens.fontSizeBase200,
     fontWeight: reactComponents.tokens.fontWeightRegular,
-    color: reactComponents.tokens.colorNeutralForeground3,
-    marginTop: "2px"
+    color: reactComponents.tokens.colorNeutralForeground2,
+    lineHeight: reactComponents.tokens.lineHeightBase200
   },
   optionDetails: {
     display: "flex",
@@ -267,6 +281,7 @@ var Lookup = ({
   footer,
   open: controlledOpen,
   onOpenChange,
+  disableClientFilter = false,
   ...inputProps
 }) => {
   const styles = useLookupStyles();
@@ -302,14 +317,26 @@ var Lookup = ({
     [selectedOptionProp, options, selectedKey, internalSelectedOption]
   );
   const filteredOptions = React3__namespace.useMemo(() => {
+    if (disableClientFilter) {
+      return options;
+    }
     if (!searchText || searchText.length < minSearchLength) {
       return options;
     }
     const lowerSearch = searchText.toLowerCase();
-    return options.filter(
-      (opt) => opt.text.toLowerCase().includes(lowerSearch) || opt.secondaryText?.toLowerCase().includes(lowerSearch)
-    );
-  }, [options, searchText, minSearchLength]);
+    return options.filter((opt) => {
+      if (opt.text.toLowerCase().includes(lowerSearch)) {
+        return true;
+      }
+      if (opt.searchFields && opt.searchFields.toLowerCase().includes(lowerSearch)) {
+        return true;
+      }
+      if (typeof opt.secondaryText === "string") {
+        return opt.secondaryText.toLowerCase().includes(lowerSearch);
+      }
+      return false;
+    });
+  }, [options, searchText, minSearchLength, disableClientFilter]);
   const highlightedOptionId = React3__namespace.useMemo(() => {
     if (!isOpen || highlightedIndex < 0 || highlightedIndex >= filteredOptions.length) {
       return void 0;
@@ -580,8 +607,8 @@ var Lookup = ({
             id: `${lookupId}-option-${option.key}`,
             role: "option",
             "data-index": index,
-            "aria-selected": option.key === selectedOption?.key ? true : false,
-            "aria-disabled": option.disabled === true ? true : void 0,
+            "aria-selected": option.key === selectedOption?.key,
+            "aria-disabled": option.disabled || void 0,
             className: reactComponents.mergeClasses(
               styles.option,
               index === highlightedIndex && styles.optionHighlighted,
@@ -591,7 +618,10 @@ var Lookup = ({
             onClick: () => handleSelectOption(option),
             onMouseEnter: () => setHighlightedIndex(index)
           },
-          option.icon && /* @__PURE__ */ React3__namespace.createElement("span", { className: styles.optionIcon }, option.icon),
+          option.icon && /* @__PURE__ */ React3__namespace.createElement("span", { className: reactComponents.mergeClasses(
+            styles.optionIcon,
+            !!option.secondaryText && styles.optionIconWithSecondary
+          ) }, option.icon),
           /* @__PURE__ */ React3__namespace.createElement("span", { className: styles.optionContent }, /* @__PURE__ */ React3__namespace.createElement("span", { className: styles.optionText }, option.text), option.secondaryText && /* @__PURE__ */ React3__namespace.createElement("span", { className: styles.optionSecondaryText }, option.secondaryText), isExpanded && hasDetails && /* @__PURE__ */ React3__namespace.createElement("div", { className: styles.optionDetails }, option.details.map((detail, detailIndex) => /* @__PURE__ */ React3__namespace.createElement("div", { key: detailIndex, className: styles.optionDetailRow }, detail.label && /* @__PURE__ */ React3__namespace.createElement("span", { className: styles.optionDetailLabel }, detail.label, ":"), /* @__PURE__ */ React3__namespace.createElement("span", { className: styles.optionDetailValue }, detail.value))))),
           hasDetails && /* @__PURE__ */ React3__namespace.createElement(
             "span",