@behindthemusictree/app-kit-ui 33.1.0 → 33.3.0

package/dist/genre-tree/index.d.ts

@@ -3,7 +3,7 @@ import { ReactNode, ComponentProps } from 'react';
 import { z } from 'zod';
 import { GenreTreeProps, FocusChangeReason, GenreTreeNode, GenreTreeAction, GenreTreeViewMode, GenreTreeViewport, WheelZoomMode } from '@behindthemusictree/genre-tree-view';
 export { FocusChangeReason, GenreTreeAction, GenreTreeOutlineSkeleton, GenreTreeSkeleton, GenreTreeViewMode, GenreTreeViewSkeleton, GenreTreeViewSkeletonProps, GenreTreeViewport, GenreTreeWheelSkeleton } from '@behindthemusictree/genre-tree-view';
-import { TrackBase, CriteriaOverview, GenreUuid, CriteriaPlaylistMinimum, RenderArtistLink, RenderSongLink, CriteriaPlaylistSimple, GenrePlaylistUuid, ArtistSearchResult, CriteriaMinimum, SongSearchResult } from '@behindthemusictree/app-kit/genre-tree';
+import { TrackBase, CriteriaOverview, GenreUuid, CriteriaPlaylistMinimum, RenderArtistLink, RenderSongLink, CriteriaPlaylistSimple, ArtistSearchResult, SongSearchResult, UseGenreRemoteSearchOptions, GenreSearchResult, GenrePlaylistUuid, CriteriaMinimum } from '@behindthemusictree/app-kit/genre-tree';
 import { Scope } from '@behindthemusictree/app-kit/transport';
 import { DetailPanel } from '@behindthemusictree/ui';
 
@@ -97,6 +97,64 @@ type GenreFocusProps = {
     onFocusGenreChange: (uuid: string | null, reason: FocusChangeReason) => void;
 };
 
+type SearchGroupItem = {
+    key: string;
+    content: ReactNode;
+    onSelect: () => void;
+};
+/** One headed list of results in a `SearchBox`, resolved by the host or by a group hook. */
+type SearchGroup = {
+    key: string;
+    /** Heading of the group; omitted when it is the only one. */
+    label?: string;
+    items: SearchGroupItem[];
+    /** Announced politely, e.g. "No artists found". */
+    status?: string;
+    /** Shows a spinner in place of the search icon while this group resolves. */
+    loading?: boolean;
+};
+declare const SEARCH_FAILED_STATUS = "Search failed";
+/** "Search failed" on error, "No <noun> found" once settled and empty, else "". */
+declare const searchStatus: (state: {
+    isError: boolean;
+    settled: boolean;
+}, count: number, noun: string) => string;
+
+type SearchBoxProps = {
+    /** Accessible name of the input and the list. */
+    label: string;
+    placeholder?: string;
+    value: string;
+    onValueChange: (value: string) => void;
+    groups: SearchGroup[];
+    /** Called after the group item is picked and the list closed. */
+    onPicked?: (groupKey: string, itemKey: string) => void;
+    /** Shows the clear button when set. */
+    onClear?: () => void;
+    /** An action left of the text, e.g. a Previous button. */
+    leading?: ReactNode;
+    className?: string;
+    /** Called when the input gains focus, e.g. to load an index lazily. */
+    onFocus?: () => void;
+};
+/** A search pill over any number of result groups; picking an item calls that item's `onSelect`. */
+declare function SearchBox({ label, placeholder, value, onValueChange, groups, onPicked, onClear, leading, className, onFocus, }: SearchBoxProps): react.JSX.Element;
+
+declare function useArtistSearchGroup(getBaseUrl: () => string, text: string, onSelect: (artist: ArtistSearchResult) => void, enabled?: boolean): SearchGroup | undefined;
+
+declare function useSongSearchGroup(getBaseUrl: () => string, text: string, onSelect: (song: SongSearchResult) => void, enabled?: boolean): SearchGroup | undefined;
+
+type UseGenreRemoteSearchGroupOptions = UseGenreRemoteSearchOptions & {
+    key?: string;
+    label?: string;
+    /** Drops hits the host already lists elsewhere. */
+    filter?: (genre: GenreSearchResult) => boolean;
+    /** Extra secondary text per hit, e.g. the region. */
+    describe?: (genre: GenreSearchResult) => string | undefined;
+};
+/** Genres from the API's ranked `genres/search/`, rendered with the umbrella tag and the tree they live in. */
+declare function useGenreRemoteSearchGroup(getBaseUrl: () => string, text: string, onSelect: (genre: GenreSearchResult) => void, { key, label, filter, describe, ...options }?: UseGenreRemoteSearchGroupOptions): SearchGroup;
+
 type ParentChange = {
     genre: GenreUuid;
     from: GenreUuid | null;
@@ -167,6 +225,12 @@ type GenreTreeViewProps<O extends CriteriaOverview = CriteriaOverview> = {
     /** When true, hides the "Add root" button and suppresses per-node
      * create/rename affordances, for a read-only consumer. Defaults to false. */
     readOnly?: boolean;
+    /** Further result groups (e.g. places) shown in the search box next to genres, artists and songs. */
+    extraSearchGroups?: SearchGroup[];
+    /** Fires with the typed search text (empty when cleared), so a host can drive its own `extraSearchGroups`. */
+    onSearchQueryChange?: (text: string) => void;
+    /** Fires when the search box gains focus, e.g. to load data for `extraSearchGroups` lazily. */
+    onSearchFocus?: () => void;
     /** Root element classes; the component adds no outer margin. */
     className?: string;
     /** Shows the "Tree display options" group (e.g. Rotation). Defaults to true. */
@@ -226,7 +290,7 @@ type GenreTreeViewProps<O extends CriteriaOverview = CriteriaOverview> = {
     collapsed?: boolean;
     onCollapsedChange?: (collapsed: boolean) => void;
 };
-declare function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({ scope, handleGenreCreationAction, handleGenreRenameAction, onParentChanged, getBackendBaseUrl, additionalActions, viewMode: controlledViewMode, selectedNodeId: controlledSelectedNodeId, onSelectedNodeIdChange, defaultViewport, viewportRestore, onViewportChange, readOnly, className, showDisplayOptions, showAddRoot, allowWheelRotation: controlledAllowWheelRotation, criteriaOverviewSchema, renderGenreDetailExtras, floatingControlsLeading, sizeMetric: controlledSizeMetric, onSizeMetricChange, renderArtistLink, artistUuid: controlledArtistUuid, onArtistUuidChange, artistExpanded: controlledArtistExpanded, onArtistExpandedChange, getShareUrl, artistSearch, onArtistSelect, artistSearchBaseUrl, songUuid: controlledSongUuid, onSongUuidChange, songExpanded: controlledSongExpanded, onSongExpandedChange, songSearch, onSongSelect, renderSongLink, renderSummary, renderEssentialTracks, renderSongLeading, renderSongActions, renderTracksToolbar, renderDangerZone, expanded, onExpandedChange, collapsed, onCollapsedChange, overlayPanel, placement, ...focus }: GenreTreeViewProps<O>): react.JSX.Element;
+declare function GenreTreeView<O extends CriteriaOverview = CriteriaOverview>({ scope, handleGenreCreationAction, handleGenreRenameAction, onParentChanged, getBackendBaseUrl, additionalActions, viewMode: controlledViewMode, selectedNodeId: controlledSelectedNodeId, onSelectedNodeIdChange, defaultViewport, viewportRestore, onViewportChange, readOnly, className, showDisplayOptions, showAddRoot, allowWheelRotation: controlledAllowWheelRotation, criteriaOverviewSchema, renderGenreDetailExtras, floatingControlsLeading, sizeMetric: controlledSizeMetric, onSizeMetricChange, renderArtistLink, artistUuid: controlledArtistUuid, onArtistUuidChange, artistExpanded: controlledArtistExpanded, onArtistExpandedChange, getShareUrl, extraSearchGroups, onSearchQueryChange, onSearchFocus, artistSearch, onArtistSelect, artistSearchBaseUrl, songUuid: controlledSongUuid, onSongUuidChange, songExpanded: controlledSongExpanded, onSongExpandedChange, songSearch, onSongSelect, renderSongLink, renderSummary, renderEssentialTracks, renderSongLeading, renderSongActions, renderTracksToolbar, renderDangerZone, expanded, onExpandedChange, collapsed, onCollapsedChange, overlayPanel, placement, ...focus }: GenreTreeViewProps<O>): react.JSX.Element;
 
 type GenreActionBandProps = {
     node: GenreTreeNode;
@@ -329,20 +393,8 @@ type GenrePlaylistTreePerRootProps<T extends TrackBase> = {
 } & HostPanelProps;
 declare function GenrePlaylistTreePerRoot<T extends TrackBase>({ scope, className, rootUuid, genrePlaylistTreePerRoot, handleGenreCreationAction, handleGenreRenameAction, additionalActions, onNodeClick, onNodeHover, selectedNodeId, onSelectedNodeChange, readOnly, wheelZoom, defaultViewport, viewportRestore, onViewportChange, playback, ...hostPanel }: GenrePlaylistTreePerRootProps<T>): react.JSX.Element;
 
-type GenreSearchExtraGroup = {
-    key: string;
-    /** Heading of this group; genre matches then get a "Genres" heading too. */
-    label: string;
-    items: {
-        key: string;
-        content: ReactNode;
-        onSelect: () => void;
-    }[];
-    /** Announced politely, e.g. "No artists found". */
-    status?: string;
-    /** Shows a spinner in place of the search icon while the host resolves this group. */
-    loading?: boolean;
-};
+/** @deprecated Use `SearchGroup`. */
+type GenreSearchExtraGroup = SearchGroup;
 type GenreSearchProps<T extends CriteriaPlaylistSimple = CriteriaPlaylistSimple> = {
     genrePlaylists: T[];
     onSelect: (genrePlaylist: T) => void;
@@ -355,10 +407,12 @@ type GenreSearchProps<T extends CriteriaPlaylistSimple = CriteriaPlaylistSimple>
     placeholder?: string;
     /** Called with what the user types, and with "" on clear or pick; never when `selectedName` refills the input. */
     onQueryChange?: (query: string) => void;
-    /** Further result groups (artists, songs) the host resolves from `onQueryChange`. */
-    extraGroups?: GenreSearchExtraGroup[];
+    /** Further result groups (places, artists, songs) the host resolves from `onQueryChange`. */
+    extraGroups?: SearchGroup[];
+    /** Called when the input gains focus. */
+    onFocus?: () => void;
 };
-declare function GenreSearch<T extends CriteriaPlaylistSimple = CriteriaPlaylistSimple>({ genrePlaylists, onSelect, selectedName, onClear, onPrevious, placeholder, onQueryChange, extraGroups, }: GenreSearchProps<T>): react.JSX.Element;
+declare function GenreSearch<T extends CriteriaPlaylistSimple = CriteriaPlaylistSimple>({ genrePlaylists, onSelect, selectedName, onClear, onPrevious, placeholder, onQueryChange, extraGroups, onFocus, }: GenreSearchProps<T>): react.JSX.Element;
 
 interface TrackListSidebarProps<T extends TrackBase> {
     className?: string;
@@ -418,4 +472,4 @@ interface RatingProps {
 }
 declare function Rating({ rating, handleChange }: RatingProps): react.JSX.Element;
 
-export { type ArtistSearchProps, GenreDetailPanel, type GenreDetailPanelProps, type GenreDetailSlots, type GenreFocusProps, GenreInfoPanelBody, type GenreInfoPanelBodyProps, GenreNodeActionBand, type GenrePlaylistPlayback, type GenrePlaylistTracksSlots, GenrePlaylistTreePerRoot, type GenrePlaylistTreePerRootProps, GenreSearch, type GenreSearchExtraGroup, type GenreSearchProps, type GenreTreeShareTarget, GenreTreeView, type GenreTreeViewProps, type GetGenreTreeShareUrl, type ParentChange, type PlayableGenrePlaylist, PlayerPanel, type PlayerPanelProps, Rating, type RatingProps, TrackItem, type TrackItemProps, TrackListSidebar, type TrackListSidebarProps, TrackPositionPlayPause, type TrackPositionPlayPauseProps, type UseGenrePlaylistPlaybackOptions, useGenrePlaylistPlayback };
+export { type ArtistSearchProps, GenreDetailPanel, type GenreDetailPanelProps, type GenreDetailSlots, type GenreFocusProps, GenreInfoPanelBody, type GenreInfoPanelBodyProps, GenreNodeActionBand, type GenrePlaylistPlayback, type GenrePlaylistTracksSlots, GenrePlaylistTreePerRoot, type GenrePlaylistTreePerRootProps, GenreSearch, type GenreSearchExtraGroup, type GenreSearchProps, type GenreTreeShareTarget, GenreTreeView, type GenreTreeViewProps, type GetGenreTreeShareUrl, type ParentChange, type PlayableGenrePlaylist, PlayerPanel, type PlayerPanelProps, Rating, type RatingProps, SEARCH_FAILED_STATUS, SearchBox, type SearchBoxProps, type SearchGroup, type SearchGroupItem, TrackItem, type TrackItemProps, TrackListSidebar, type TrackListSidebarProps, TrackPositionPlayPause, type TrackPositionPlayPauseProps, type UseGenrePlaylistPlaybackOptions, type UseGenreRemoteSearchGroupOptions, searchStatus, useArtistSearchGroup, useGenrePlaylistPlayback, useGenreRemoteSearchGroup, useSongSearchGroup };

package/dist/genre-tree/index.js

@@ -11,11 +11,17 @@ import {
   GenreTreeWheelSkeleton,
   PlayerPanel,
   Rating,
+  SEARCH_FAILED_STATUS,
+  SearchBox,
   TrackItem,
   TrackListSidebar,
   TrackPositionPlayPause,
-  useGenrePlaylistPlayback
-} from "../chunk-2M4Q2IJU.js";
+  searchStatus,
+  useArtistSearchGroup,
+  useGenrePlaylistPlayback,
+  useGenreRemoteSearchGroup,
+  useSongSearchGroup
+} from "../chunk-QMELESFB.js";
 import "../chunk-DKQQLLMY.js";
 export {
   GenreDetailPanel,
@@ -30,9 +36,15 @@ export {
   GenreTreeWheelSkeleton,
   PlayerPanel,
   Rating,
+  SEARCH_FAILED_STATUS,
+  SearchBox,
   TrackItem,
   TrackListSidebar,
   TrackPositionPlayPause,
-  useGenrePlaylistPlayback
+  searchStatus,
+  useArtistSearchGroup,
+  useGenrePlaylistPlayback,
+  useGenreRemoteSearchGroup,
+  useSongSearchGroup
 };
 //# sourceMappingURL=index.js.map