@dxos/react-ui-searchlist 0.8.4-main.ae835ea → 0.8.4-main.bc674ce

package/src/components/SearchList/hooks/useGlobalFilter.tsx

@@ -0,0 +1,61 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type PropsWithChildren, createContext, useContext, useMemo } from 'react';
+
+/**
+ * Type for a filter function that filters an array of objects.
+ */
+export type FilterFunction<T = any> = (objects: T[]) => T[];
+
+type GlobalFilterContextType = {
+  /** The current filter function. */
+  filter?: FilterFunction;
+};
+
+const GlobalFilterContext = createContext<GlobalFilterContextType>({});
+
+export type GlobalFilterProviderProps = PropsWithChildren<{
+  /** The filter function to apply globally. */
+  filter?: FilterFunction;
+}>;
+
+/**
+ * Provider that makes a filter function available globally.
+ * Used by plugin-search to provide its regex-based filtering.
+ */
+export const GlobalFilterProvider = ({ children, filter }: GlobalFilterProviderProps) => {
+  const value = useMemo(() => ({ filter }), [filter]);
+  return <GlobalFilterContext.Provider value={value}>{children}</GlobalFilterContext.Provider>;
+};
+
+/**
+ * Hook to access the global filter context.
+ * Returns the filter function if one is provided.
+ */
+export const useGlobalFilter = () => {
+  return useContext(GlobalFilterContext);
+};
+
+/**
+ * Hook that applies the global filter to an array of objects.
+ * If no filter is set, returns the original objects unchanged.
+ *
+ * @example
+ * const objects = useQuery(db, Filter.everything());
+ * const filteredObjects = useGlobalFilteredObjects(objects);
+ */
+export const useGlobalFilteredObjects = <T extends Record<string, any>>(objects?: T[]): T[] => {
+  const { filter } = useGlobalFilter();
+
+  return useMemo(() => {
+    if (!objects) {
+      return [];
+    }
+    if (!filter) {
+      return objects;
+    }
+    return filter(objects);
+  }, [objects, filter]);
+};

package/src/components/SearchList/hooks/useSearchListInput.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useSearchListInputContext } from '../context';
+
+/**
+ * Hook to access the search context for custom input implementations.
+ */
+export const useSearchListInput = () => {
+  const { query, onQueryChange, selectedValue, onSelectedValueChange, getItemValues, triggerSelect } =
+    useSearchListInputContext('useSearchListInput');
+  return { query, onQueryChange, selectedValue, onSelectedValueChange, getItemValues, triggerSelect };
+};

package/src/components/SearchList/hooks/useSearchListItem.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useSearchListItemContext } from '../context';
+
+/**
+ * Hook to access selection state for custom item renderers.
+ * Returns the current selected value and registration functions.
+ */
+export const useSearchListItem = () => {
+  const { selectedValue, registerItem, unregisterItem } = useSearchListItemContext('useSearchListItem');
+  return { selectedValue, registerItem, unregisterItem };
+};

package/src/components/SearchList/hooks/useSearchListResults.ts

@@ -0,0 +1,104 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import commandScore from 'command-score';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+export type UseSearchListResultsOptions<T> = {
+  /** Items to filter. */
+  items: T[];
+  /** Custom filter function. Defaults to filtering by extracted string. */
+  filter?: (item: T, query: string) => boolean;
+  /** Enable fuzzy filtering using command-score algorithm. Defaults to true. */
+  fuzzy?: boolean;
+  /** Custom function to extract the searchable string from an item. Defaults to accessing 'label' property if it exists. */
+  extract?: (item: T) => string;
+  /** Minimum score threshold for fuzzy matches (0-1). Defaults to 0. */
+  minScore?: number;
+};
+
+/**
+ * Hook to manage search results with fuzzy filtering (enabled by default).
+ * Returns filtered results and a handleSearch function to pass to SearchList.Root.
+ *
+ * @example
+ * // Default fuzzy filtering using command-score (tries to extract from 'label' property)
+ * const { results, handleSearch } = useSearchListResults({ items });
+ *
+ * @example
+ * // Disable fuzzy for basic case-insensitive substring match
+ * const { results, handleSearch } = useSearchListResults({ items, fuzzy: false });
+ *
+ * @example
+ * // Custom extraction for fuzzy filtering
+ * const { results, handleSearch } = useSearchListResults({
+ *   items,
+ *   extract: (item) => `${item.name} ${item.description}`,
+ * });
+ */
+export const useSearchListResults = <T = unknown>({
+  items,
+  filter,
+  fuzzy = true,
+  extract,
+  minScore = 0,
+}: UseSearchListResultsOptions<T>) => {
+  const [query, setQuery] = useState<string>('');
+  const queryRef = useRef<string>('');
+
+  // Update results when items change.
+  useEffect(() => {
+    queryRef.current = '';
+    setQuery('');
+  }, [items]);
+
+  const defaultExtract = useCallback((item: T) => {
+    // If item is a string, return it directly
+    if (typeof item === 'string') {
+      return item;
+    }
+    // Otherwise, try to access 'label' property
+    return (item as any)?.label ?? '';
+  }, []);
+  const extractFn = extract ?? defaultExtract;
+
+  const defaultFilter = useCallback(
+    (item: T, query: string) => {
+      const searchable = extractFn(item);
+      return searchable.toLowerCase().includes(query.toLowerCase());
+    },
+    [extractFn],
+  );
+
+  const filterFn = filter ?? defaultFilter;
+
+  const handleSearch = useCallback((searchQuery: string) => {
+    queryRef.current = searchQuery;
+    setQuery(searchQuery);
+  }, []);
+
+  const results = useMemo(() => {
+    const currentQuery = queryRef.current;
+    if (!currentQuery) {
+      return items;
+    }
+
+    if (fuzzy) {
+      // Score and filter items using command-score.
+      const scored = items
+        .map((item) => ({
+          item,
+          score: commandScore(extractFn(item), currentQuery) as number,
+        }))
+        .filter(({ score }) => score > minScore)
+        .sort((a, b) => b.score - a.score);
+
+      return scored.map(({ item }) => item);
+    } else {
+      return items.filter((item) => filterFn(item, currentQuery));
+    }
+  }, [items, query, filterFn, fuzzy, extractFn, minScore]);
+
+  return { results, handleSearch };
+};

package/src/components/SearchList/index.ts

@@ -3,3 +3,4 @@
 //
 
 export * from './SearchList';
+export * from './hooks';

package/src/translations.ts

@@ -4,7 +4,7 @@
 
 import { type Resource } from '@dxos/react-ui';
 
-export const translationKey = 'react-ui-searchlist';
+export const translationKey = '@dxos/react-ui-searchlist';
 
 export const translations = [
   {

package/src/types/command-score.d.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+declare module 'command-score' {
+  /**
+   * Scores how well a string matches a query using a fuzzy matching algorithm.
+   * Used by cmdk for its built-in filtering.
+   *
+   * @param string - The string to score against.
+   * @param query - The search query.
+   * @returns A score between 0 and 1, where higher values indicate better matches.
+   */
+  function commandScore(string: string, query: string): number;
+  export default commandScore;
+}