@pharos-ds/core 0.1.9

package/dist/Typeahead/Typeahead.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @file Typeahead.tsx
+ * @input Uses React, BaseTypeahead, Field, Token, InputGroupContext
+ * @output Exports Typeahead styled typeahead component
+ * @position Styled wrapper; composes BaseTypeahead with Field or InputGroup
+ *
+ * Owns the input wrapper (border, padding, status styles), selected value
+ * token with spacing compensation, and edit mode behavior. Delegates
+ * search, keyboard navigation, and dropdown to BaseTypeahead.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Typeahead/index.ts
+ * - /apps/storybook/stories/Typeahead.stories.tsx
+ * - /packages/cli/templates/blocks/components/Typeahead/ (showcase blocks)
+ */
+import React, { type ReactNode } from 'react';
+import { type InputStatus, type FieldStatusVariant } from '../Field';
+import { type IconType } from '../Icon';
+import type { BaseProps } from '../BaseProps';
+import type { SizeValue } from '../utils/types';
+import type { SearchableItem, SearchSource } from './types';
+export type { InputStatus as TypeaheadStatus, InputStatusType as TypeaheadStatusType, } from '../Field';
+export type TypeaheadSize = 'sm' | 'md' | 'lg';
+export interface TypeaheadProps<T extends SearchableItem> extends Omit<BaseProps<HTMLDivElement>, 'onChange'> {
+    ref?: React.Ref<HTMLDivElement>;
+    /** Accessible label (required). */
+    label: string;
+    /** Visually hide the label. @default false */
+    isLabelHidden?: boolean;
+    /** Helper text. */
+    description?: string;
+    /** Required field. @default false */
+    isRequired?: boolean;
+    /** Optional field. @default false */
+    isOptional?: boolean;
+    /** Validation status. */
+    status?: InputStatus;
+    /**
+     * How the status message is placed relative to the input.
+     * - 'attached': message overlaps directly below the input (bordered treatment)
+     * - 'detached': message floats below as a separate element with spacing
+     * @default 'attached'
+     */
+    statusVariant?: FieldStatusVariant;
+    /**
+     * Icon to display at the start of the input.
+     * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
+     */
+    startIcon?: ReactNode | IconType;
+    /**
+     * Width of the field. Numbers are treated as pixels, strings are used as-is
+     * (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
+     * stay aligned, unlike setting width via `xstyle`/`className`/`style`.
+     */
+    width?: SizeValue;
+    /** Label tooltip. */
+    labelTooltip?: string;
+    /** Search source providing items. */
+    searchSource: SearchSource<T>;
+    /** Currently selected item (null = nothing selected). */
+    value: T | null;
+    /** Callback when selection changes. */
+    onChange: (item: T | null) => void;
+    /** Render function for dropdown items. Default: TypeaheadItem. */
+    renderItem?: (item: T) => ReactNode;
+    /** Placeholder text. */
+    placeholder?: string;
+    /** Show results on focus before typing. @default false */
+    hasEntriesOnFocus?: boolean;
+    /** Max dropdown items. @default 10 */
+    maxMenuItems?: number;
+    /** Text shown when no results found. @default 'No results found' */
+    emptySearchResultsText?: string;
+    /** Whether the input is disabled. @default false */
+    isDisabled?: boolean;
+    /**
+     * Explains why the input is disabled. When set together with `isDisabled`,
+     * the input shows a tooltip with this text on hover and keyboard focus, and
+     * the field stays focusable (via `aria-disabled`) so the reason is
+     * discoverable by keyboard and assistive technology. Editing and selection
+     * stay blocked.
+     *
+     * Use this instead of wrapping a disabled input in `Tooltip` — disabled
+     * controls don't emit the pointer events an external tooltip needs.
+     *
+     * @example
+     * ```
+     * <Typeahead
+     *   label="Assignee"
+     *   searchSource={userSource}
+     *   value={assignee}
+     *   onChange={setAssignee}
+     *   isDisabled
+     *   disabledMessage="You need the Editor role to change this"
+     * />
+     * ```
+     */
+    disabledMessage?: string;
+    /** Show clear button. @default true */
+    hasClear?: boolean;
+    /** Auto-focus on mount. @default false */
+    hasAutoFocus?: boolean;
+    /** Input size. @default 'md' */
+    size?: TypeaheadSize;
+    /**
+     * Debounce delay in ms before triggering search after typing.
+     * Set to 0 for synchronous/local search sources that don't need debouncing.
+     * @default 150
+     */
+    debounceMs?: number;
+    /** Query change callback. */
+    onChangeQuery?: (query: string) => void;
+    /** Callback when dropdown opens/closes. */
+    onOpenChange?: (isOpen: boolean) => void;
+}
+/**
+ * A search-as-you-type component for selecting an item from a search source.
+ *
+ * Wraps BaseTypeahead with Field for label, description, and status.
+ * Owns the input wrapper styling, selected value token, and edit mode.
+ *
+ * Edit mode: clicking the token or input area removes the token, populates
+ * the input with the value's label, and selects all text. Blurring without
+ * selecting restores the original token. Escape also restores.
+ *
+ * @example
+ * ```
+ * <Typeahead
+ *   label="Assignee"
+ *   searchSource={userSource}
+ *   value={assignee}
+ *   onChange={setAssignee}
+ *   placeholder="Search users..."
+ * />
+ * ```
+ */
+export declare function Typeahead<T extends SearchableItem>({ ref, label, isLabelHidden, description, isRequired, isOptional, status, statusVariant, startIcon, labelTooltip, searchSource, value, onChange, renderItem, placeholder, hasEntriesOnFocus, maxMenuItems, emptySearchResultsText, isDisabled, disabledMessage, hasClear, hasAutoFocus, size: sizeProp, debounceMs, onChangeQuery, onOpenChange, width, xstyle, className, style, 'data-testid': testId, }: TypeaheadProps<T>): React.JSX.Element;
+export declare namespace Typeahead {
+    var displayName: string;
+}
+//# sourceMappingURL=Typeahead.d.ts.map

package/dist/Typeahead/Typeahead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Typeahead.d.ts","sourceRoot":"","sources":["../../src/Typeahead/Typeahead.tsx"],"names":[],"mappings":"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"}

package/dist/Typeahead/Typeahead.js

@@ -0,0 +1,356 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Typeahead.tsx
+ * @input Uses React, BaseTypeahead, Field, Token, InputGroupContext
+ * @output Exports Typeahead styled typeahead component
+ * @position Styled wrapper; composes BaseTypeahead with Field or InputGroup
+ *
+ * Owns the input wrapper (border, padding, status styles), selected value
+ * token with spacing compensation, and edit mode behavior. Delegates
+ * search, keyboard navigation, and dropdown to BaseTypeahead.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Typeahead/index.ts
+ * - /apps/storybook/stories/Typeahead.stories.tsx
+ * - /packages/cli/templates/blocks/components/Typeahead/ (showcase blocks)
+ */
+import React, { useCallback, useId, useRef, useState } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import { BaseTypeahead } from "./BaseTypeahead.js";
+import { useSize } from "../SizeContext/SizeContext.js";
+import { Field, InputClearButton, inputWrapperStyles, inputStatusBorderStyles, inputStatusHoverShadowStyles, inputStatusFocusWithinStyles } from "../Field/index.js";
+import { Token } from "../Token/index.js";
+import { useTooltip } from "../Tooltip/index.js";
+import { renderIconSlot } from "../Icon/index.js";
+import { VisuallyHidden } from "../VisuallyHidden/index.js";
+import "../theme/tokens.stylex.js";
+import { spacingVars, sizeVars } from "../theme/tokens.stylex.js";
+import { groupStyles } from "../InputGroup/groupStyles.js";
+import { useInputGroup } from "../InputGroup/InputGroupContext.js";
+import { getInputARIA, mergeProps, mergeRefs } from "../utils/index.js";
+import { themeProps } from "../utils/themeProps.js";
+import { useTranslator } from "../i18n/index.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = {
+  wrapper: {
+    kVAEAm: "x1n2onr6",
+    kwnvtZ: "x1a02dak",
+    kOIVth: "xzye2dw",
+    k8WAf4: "x1x7cmac",
+    kkrTdU: "x1ed109x",
+    $$css: true
+  },
+  token: {
+    kogj98: "x1n5sqmh",
+    $$css: true
+  },
+  clearButton: {
+    kVAEAm: "x10l6tqk",
+    k87sOh: "x1nzz77m",
+    kt4wiu: "x1oinnt5",
+    kZKoxP: "x1qx5ct2",
+    $$css: true
+  },
+  clearButtonSm: {
+    k87sOh: "xeqxqpg",
+    kt4wiu: "x8qlsd8",
+    $$css: true
+  },
+  inputHidden: {
+    kzqmXN: "xnalus7",
+    k7Eaqz: "xeuugli",
+    kUk6DE: "x1somy94",
+    kmVPX3: "x1717udv",
+    kSiTet: "xg01cxk",
+    kVAEAm: "x10l6tqk",
+    $$css: true
+  }
+};
+const wrapperSizeStyles = {
+  sm: {
+    kAzted: "x1gdqauq",
+    $$css: true
+  },
+  md: {
+    kAzted: "x1uogy3y",
+    $$css: true
+  },
+  lg: {
+    kAzted: "x1xf4nls",
+    $$css: true
+  }
+};
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * A search-as-you-type component for selecting an item from a search source.
+ *
+ * Wraps BaseTypeahead with Field for label, description, and status.
+ * Owns the input wrapper styling, selected value token, and edit mode.
+ *
+ * Edit mode: clicking the token or input area removes the token, populates
+ * the input with the value's label, and selects all text. Blurring without
+ * selecting restores the original token. Escape also restores.
+ *
+ * @example
+ * ```
+ * <Typeahead
+ *   label="Assignee"
+ *   searchSource={userSource}
+ *   value={assignee}
+ *   onChange={setAssignee}
+ *   placeholder="Search users..."
+ * />
+ * ```
+ */
+export function Typeahead({
+  ref,
+  label,
+  isLabelHidden = false,
+  description,
+  isRequired = false,
+  isOptional = false,
+  status,
+  statusVariant = 'attached',
+  startIcon,
+  labelTooltip,
+  searchSource,
+  value,
+  onChange,
+  renderItem,
+  placeholder,
+  hasEntriesOnFocus,
+  maxMenuItems,
+  emptySearchResultsText,
+  isDisabled = false,
+  disabledMessage,
+  hasClear = true,
+  hasAutoFocus,
+  size: sizeProp,
+  debounceMs,
+  onChangeQuery,
+  onOpenChange,
+  width,
+  xstyle,
+  className,
+  style,
+  'data-testid': testId
+}) {
+  const t = useTranslator();
+  const size = useSize(sizeProp, 'md');
+  const inputId = useId();
+  const inputLabelId = useId();
+  const descriptionId = useId();
+  const statusMessageId = useId();
+  const inputGroup = useInputGroup();
+  const wrapperRef = useRef(null);
+  const inputRef = useRef(null);
+  const tokenRef = useRef(null);
+
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the input wrapper (which already exists) and
+  // the input stays perceivable via aria-disabled + readOnly instead of the
+  // disabled attribute. Editing and selection stay blocked by the isDisabled
+  // guards (handleWrapperClick, handleEnterEditMode, and BaseTypeahead's own
+  // focus/change guards).
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The wrapper div is not naturally focusable; focusin bubbles up from the
+    // input, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage
+  });
+
+  // Edit mode: when the user clicks the token to edit the selected value
+  const [isEditing, setIsEditing] = useState(false);
+  const [editingValue, setEditingValue] = useState(null);
+
+  // Show token when value is selected and not in edit mode
+  const showToken = value != null && !isEditing;
+
+  // Enter edit mode: remove token visually, populate input with value label
+  const handleEnterEditMode = useCallback(() => {
+    if (isDisabled || !value) {
+      return;
+    }
+    setEditingValue(value);
+    setIsEditing(true);
+    // The base will receive onChangeQuery with the value's label
+    onChangeQuery?.(value.label);
+    requestAnimationFrame(() => {
+      const input = inputRef.current;
+      if (input) {
+        // Set the input value directly since the base manages its own query state
+        // We trigger a synthetic change to sync the base's internal state
+        const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')?.set;
+        nativeInputValueSetter?.call(input, value.label);
+        input.dispatchEvent(new Event('input', {
+          bubbles: true
+        }));
+        input.focus();
+        input.setSelectionRange(0, input.value.length);
+      }
+    });
+  }, [isDisabled, value, onChangeQuery]);
+
+  // Handle blur: restore token if editing and no selection was made
+  const handleBlur = useCallback(e => {
+    // Don't restore if focus is moving within the wrapper (e.g. to dropdown)
+    if (wrapperRef.current?.contains(e.relatedTarget)) {
+      return;
+    }
+    if (editingValue && isEditing) {
+      setIsEditing(false);
+      setEditingValue(null);
+      // Value was never cleared from parent, so no onChange needed
+    }
+  }, [editingValue, isEditing]);
+
+  // Handle selection from dropdown — clears edit mode
+  const handleChange = useCallback(item => {
+    setIsEditing(false);
+    setEditingValue(null);
+    onChange(item);
+    // After selection, focus the token so keyboard users stay in the component.
+    // Use requestAnimationFrame because the token renders on the next cycle.
+    if (item) {
+      requestAnimationFrame(() => {
+        const tokenEl = tokenRef.current;
+        if (tokenEl) {
+          // Focus the internal button inside the token
+          const button = tokenEl.querySelector('button');
+          (button ?? tokenEl).focus();
+        }
+      });
+    }
+  }, [onChange]);
+
+  // Handle clear (explicit X button on token)
+  const handleClear = useCallback(() => {
+    setIsEditing(false);
+    setEditingValue(null);
+    onChange(null);
+    inputRef.current?.focus();
+  }, [onChange]);
+
+  // Handle Escape during edit mode — restore token
+  const handleKeyDown = useCallback(e => {
+    if (e.key === 'Escape' && editingValue) {
+      e.preventDefault();
+      setIsEditing(false);
+      setEditingValue(null);
+      inputRef.current?.blur();
+    }
+  }, [editingValue]);
+
+  // Click wrapper to focus input or enter edit mode
+  const handleWrapperClick = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
+    if (showToken) {
+      handleEnterEditMode();
+    } else {
+      inputRef.current?.focus();
+    }
+  }, [isDisabled, showToken, handleEnterEditMode]);
+  const {
+    ariaLabelledBy,
+    ariaDescribedBy
+  } = getInputARIA(inputLabelId, [description ? descriptionId : null, status?.message ? statusMessageId : null, showsDisabledMessage ? disabledMessageTooltip.describedBy : null], inputGroup);
+  const sizeStyle = wrapperSizeStyles[size];
+  const typeaheadContent = /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsxs("div", {
+      ref: mergeRefs(wrapperRef, disabledMessageTooltip.ref, inputGroup ? ref : undefined),
+      "data-testid": testId,
+      onClick: handleWrapperClick,
+      onBlur: handleBlur,
+      ...mergeProps(themeProps('typeahead', {
+        size,
+        status: status?.type
+      }), stylex.props(inputWrapperStyles.base, styles.wrapper, sizeStyle, status && inputStatusBorderStyles[status.type], status && !isDisabled && inputStatusHoverShadowStyles[status.type], status && inputStatusFocusWithinStyles[status.type], isDisabled && inputWrapperStyles.disabled, inputGroup && groupStyles.inGroup, inputGroup && xstyle), inputGroup ? className : undefined, inputGroup ? style : undefined),
+      children: [startIcon && renderIconSlot(startIcon, {
+        size: 'sm',
+        color: 'secondary'
+      }), inputGroup && /*#__PURE__*/_jsx(VisuallyHidden, {
+        id: inputLabelId,
+        children: label
+      }), showToken && /*#__PURE__*/_jsx(Token, {
+        ref: tokenRef,
+        label: value.label,
+        size: size,
+        onClick: handleEnterEditMode,
+        isDisabled: isDisabled,
+        xstyle: styles.token
+      }), /*#__PURE__*/_jsx(BaseTypeahead, {
+        ref: inputRef,
+        searchSource: searchSource,
+        value: value,
+        onChange: handleChange,
+        renderItem: renderItem,
+        placeholder: showToken ? undefined : placeholder,
+        hasEntriesOnFocus: hasEntriesOnFocus,
+        maxMenuItems: maxMenuItems,
+        emptySearchResultsText: emptySearchResultsText,
+        isDisabled: isDisabled,
+        hasAutoFocus: hasAutoFocus,
+        isFocusableDisabled: showsDisabledMessage,
+        inputId: inputId,
+        ariaDescribedBy: ariaDescribedBy,
+        ariaLabelledBy: ariaLabelledBy,
+        onChangeQuery: onChangeQuery,
+        onOpenChange: onOpenChange,
+        debounceMs: debounceMs,
+        anchorRef: wrapperRef,
+        onKeyDown: handleKeyDown,
+        inputXStyle: showToken ? styles.inputHidden : undefined,
+        size: size
+      }), hasClear && value && !isDisabled && /*#__PURE__*/_jsx(InputClearButton, {
+        label: t('@pharos.typeahead.clearSelection'),
+        onClick: e => {
+          e.stopPropagation();
+          handleClear();
+        },
+        xstyle: [styles.clearButton, size === 'sm' && styles.clearButtonSm]
+      })]
+    }), showsDisabledMessage && disabledMessageTooltip.renderTooltip(disabledMessage)]
+  });
+  if (inputGroup) {
+    return typeaheadContent;
+  }
+  return /*#__PURE__*/_jsx(Field, {
+    ref: ref,
+    label: label,
+    isLabelHidden: isLabelHidden,
+    description: description,
+    inputID: inputId,
+    descriptionID: description ? descriptionId : undefined,
+    isOptional: isOptional,
+    isRequired: isRequired,
+    isDisabled: isDisabled,
+    status: status ? {
+      type: status.type,
+      message: status.message,
+      messageID: status.message ? statusMessageId : undefined
+    } : undefined,
+    statusVariant: statusVariant,
+    labelTooltip: labelTooltip,
+    width: width,
+    xstyle: xstyle,
+    className: className,
+    style: style,
+    children: typeaheadContent
+  });
+}
+Typeahead.displayName = 'Typeahead';

package/dist/Typeahead/TypeaheadItem.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @file TypeaheadItem.tsx
+ * @input Uses React, StyleX, SearchableItem
+ * @output Exports TypeaheadItem component for rendering dropdown items
+ * @position Presentational component; used as default renderItem in BaseTypeahead
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Typeahead/index.ts
+ * - /packages/cli/templates/blocks/components/Typeahead/ (showcase blocks)
+ */
+import React, { type ReactNode } from 'react';
+import type { SearchableItem } from './types';
+import type { BaseProps } from '../BaseProps';
+export interface TypeaheadItemProps<T extends SearchableItem = SearchableItem> extends BaseProps<HTMLDivElement> {
+    ref?: React.Ref<HTMLDivElement>;
+    /**
+     * The search result item.
+     */
+    item: T;
+    /**
+     * Icon or avatar to display before the label.
+     */
+    icon?: ReactNode;
+    /**
+     * Description text displayed below the label.
+     */
+    description?: string;
+    /**
+     * Whether this item is disabled.
+     * @default false
+     */
+    isDisabled?: boolean;
+    /**
+     * Group label for grouping items visually.
+     */
+    group?: string;
+}
+/**
+ * Default item component for typeahead dropdown results.
+ *
+ * Renders a label with optional icon and description.
+ * Exported for use in custom `renderItem` implementations.
+ *
+ * @example
+ * ```
+ * <Typeahead searchSource={source} value={v} onChange={setV} label="Search" />
+ * <Typeahead
+ *   searchSource={source}
+ *   value={v}
+ *   onChange={setV}
+ *   label="Search"
+ *   renderItem={(item) => (
+ *     <TypeaheadItem
+ *       item={item}
+ *       icon={<Avatar src={item.auxiliaryData.avatar} size="sm" />}
+ *       description={item.auxiliaryData.role}
+ *     />
+ *   )}
+ * />
+ * ```
+ */
+export declare function TypeaheadItem<T extends SearchableItem>({ ref, item, icon, description, isDisabled, xstyle, }: TypeaheadItemProps<T>): React.JSX.Element;
+export declare namespace TypeaheadItem {
+    var displayName: string;
+}
+//# sourceMappingURL=TypeaheadItem.d.ts.map

package/dist/Typeahead/TypeaheadItem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypeaheadItem.d.ts","sourceRoot":"","sources":["../../src/Typeahead/TypeaheadItem.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAQ5C,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAQ5C,MAAM,WAAW,kBAAkB,CACjC,CAAC,SAAS,cAAc,GAAG,cAAc,CACzC,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,IAAI,EAAE,CAAC,CAAC;IAER;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA6CD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,cAAc,EAAE,EACtD,GAAG,EACH,IAAI,EACJ,IAAI,EACJ,WAAW,EACX,UAAkB,EAClB,MAAM,GACP,EAAE,kBAAkB,CAAC,CAAC,CAAC,qBAsBvB;yBA7Be,aAAa"}

package/dist/Typeahead/TypeaheadItem.js

@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TypeaheadItem.tsx
+ * @input Uses React, StyleX, SearchableItem
+ * @output Exports TypeaheadItem component for rendering dropdown items
+ * @position Presentational component; used as default renderItem in BaseTypeahead
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Typeahead/index.ts
+ * - /packages/cli/templates/blocks/components/Typeahead/ (showcase blocks)
+ */
+
+import React from 'react';
+import * as stylex from '@stylexjs/stylex';
+import "../theme/tokens.stylex.js";
+import { colorVars, spacingVars, fontWeightVars, typeScaleVars } from "../theme/tokens.stylex.js";
+import { mergeProps } from "../utils/index.js";
+import { themeProps } from "../utils/themeProps.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = {
+  container: {
+    k1xSpc: "x78zum5",
+    kGNEyG: "x6s0dn4",
+    kOIVth: "x1txdalj",
+    kAzted: "x2lwn1j",
+    $$css: true
+  },
+  disabled: {
+    kSiTet: "xbyyjgo",
+    $$css: true
+  }
+};
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Default item component for typeahead dropdown results.
+ *
+ * Renders a label with optional icon and description.
+ * Exported for use in custom `renderItem` implementations.
+ *
+ * @example
+ * ```
+ * <Typeahead searchSource={source} value={v} onChange={setV} label="Search" />
+ * <Typeahead
+ *   searchSource={source}
+ *   value={v}
+ *   onChange={setV}
+ *   label="Search"
+ *   renderItem={(item) => (
+ *     <TypeaheadItem
+ *       item={item}
+ *       icon={<Avatar src={item.auxiliaryData.avatar} size="sm" />}
+ *       description={item.auxiliaryData.role}
+ *     />
+ *   )}
+ * />
+ * ```
+ */
+export function TypeaheadItem({
+  ref,
+  item,
+  icon,
+  description,
+  isDisabled = false,
+  xstyle
+}) {
+  // If item has a pre-rendered element, use it
+  if (item.element) {
+    return /*#__PURE__*/_jsx(_Fragment, {
+      children: item.element
+    });
+  }
+  return /*#__PURE__*/_jsxs("div", {
+    ref: ref,
+    ...mergeProps(themeProps('typeahead-item'), stylex.props(styles.container, isDisabled && styles.disabled, xstyle)),
+    children: [icon, /*#__PURE__*/_jsxs("div", {
+      ...{
+        className: "x78zum5 xdt5ytf x98rzlu xeuugli"
+      },
+      children: [/*#__PURE__*/_jsx("span", {
+        ...{
+          className: "xcr08ib x1kq96og x1sodnla x1tgivj0 xb3r6kr xlyipyv xuxw1ft"
+        },
+        children: item.label
+      }), description && /*#__PURE__*/_jsx("span", {
+        ...{
+          className: "x141an7d x1ltkj2j xv1l7n4 xb3r6kr xlyipyv xuxw1ft"
+        },
+        children: description
+      })]
+    })]
+  });
+}
+TypeaheadItem.displayName = 'TypeaheadItem';