@behindthemusictree/app-kit-ui 29.1.0 → 31.0.0

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

@@ -1,10 +1,11 @@
 import * as react from 'react';
 import { ReactNode, ComponentProps } from 'react';
 import { z } from 'zod';
-import { GenreTreeProps, FocusChangeReason, GenreTreeNode, GenreTreeAction, GenreTreeViewMode, GenreTreeViewport, InfoPanelSections, InfoPanelBody, WheelZoomMode } from '@behindthemusictree/genre-tree-view';
+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, CriteriaPlaylistSimple, GenrePlaylistUuid, ArtistSearchResult, CriteriaMinimum } from '@behindthemusictree/app-kit/genre-tree';
+import { TrackBase, CriteriaOverview, GenreUuid, CriteriaPlaylistMinimum, RenderArtistLink, RenderSongLink, CriteriaPlaylistSimple, GenrePlaylistUuid, ArtistSearchResult, CriteriaMinimum, SongSearchResult } from '@behindthemusictree/app-kit/genre-tree';
 import { Scope } from '@behindthemusictree/app-kit/transport';
+import { DetailPanel } from '@behindthemusictree/ui';
 
 type GenrePlaylistTracksSlots = {
     /** Rendered first in each row, e.g. a selection checkbox. `index` is the row's position in the loaded list. */
@@ -30,6 +31,7 @@ type GenreDetailExtrasProps<O extends CriteriaOverview> = GenreDetailSlots<O> &
     criteriaOverviewSchema?: z.ZodType<O, unknown>;
     renderGenreDetailExtras?: (overview: O) => ReactNode;
     renderArtistLink?: RenderArtistLink;
+    renderSongLink?: RenderSongLink;
     /** When set, the tracks list shows only this artist's songs in the genre. */
     artist?: {
         uuid: string;
@@ -39,8 +41,24 @@ type GenreDetailExtrasProps<O extends CriteriaOverview> = GenreDetailSlots<O> &
     family: ReactNode;
 };
 
-/** Controlled expand state and danger-zone slot of the info panel, plus the generic overlay panel, as typed by genre-tree-view. */
-type InfoPanelCurationProps = Partial<Pick<GenreTreeProps, "renderDangerZone" | "expanded" | "onExpandedChange" | "collapsed" | "hideExpandButton" | "overlayPanel">>;
+/** An artist or song detail the host renders in the shared DetailPanel in place of a genre's. */
+interface OverlayPanel {
+    title: ReactNode;
+    content: ReactNode;
+    /** Second column, shown only while expanded. */
+    extraContent?: ReactNode;
+    expanded: boolean;
+    onExpandedChange: (expanded: boolean) => void;
+    onClose: () => void;
+}
+/** A host-supplied panel: expansion is optional because the host may not offer it. */
+type HostOverlayPanel = Omit<OverlayPanel, "expanded" | "onExpandedChange"> & {
+    expanded?: boolean;
+    onExpandedChange?: (expanded: boolean) => void;
+};
+
+/** The host-owned detail panel's contract with the tree: the area the panel covers, and the node-style resolver the tree publishes back. */
+type HostPanelProps = Partial<Pick<GenreTreeProps, "obscuredInset" | "onNodeStyleResolverChange">>;
 
 /** What a play button needs of a playlist; `criteria` is only read when playing one artist's songs in the genre. */
 type PlayableGenrePlaylistInput = CriteriaPlaylistMinimum & {
@@ -99,6 +117,12 @@ type GenreTreeShareTarget = {
     uuid: string;
     name: string;
     scope: Scope;
+} | {
+    kind: "song";
+    uuid: string;
+    /** The song title. */
+    name: string;
+    scope: Scope;
 };
 /** Host applications own routing and return an absolute or relative URL for this target. */
 type GetGenreTreeShareUrl = (target: GenreTreeShareTarget) => string | null | undefined;
@@ -174,14 +198,35 @@ type GenreTreeViewProps<O extends CriteriaOverview = CriteriaOverview> = {
     /** Controlled expanded state of the artist panel. Uncontrolled, it resets to compact on each artist. */
     artistExpanded?: boolean;
     onArtistExpandedChange?: (expanded: boolean) => void;
-    /** Resolves a selected genre or artist to a share URL using the host app's routes. */
+    /** Controlled song panel (a song uuid). Like the artist panel it shares the info panel's slot: opening a song clears
+     * the selected genre and the artist; selecting a genre closes it. A host `overlayPanel` takes precedence. */
+    songUuid?: string | null;
+    /** Called when the user opens a song (search pick, title link) or closes its panel. */
+    onSongUuidChange?: (uuid: string | null) => void;
+    /** Controlled expanded state of the song panel. Uncontrolled, it resets to compact on each song. */
+    songExpanded?: boolean;
+    onSongExpandedChange?: (expanded: boolean) => void;
+    /** Songs are searched by default; picking one opens its panel. */
+    songSearch?: boolean;
+    onSongSelect?: (song: SongSearchResult) => void;
+    /** When set, song titles in the info panel's track list render through it (e.g. a router `Link` to the song).
+     * By default they are buttons that open the song panel. */
+    renderSongLink?: RenderSongLink;
+    /** Resolves a selected genre, artist or song to a share URL using the host app's routes. */
     getShareUrl?: GetGenreTreeShareUrl;
-} & ArtistSearchProps & GenreDetailSlots<O> & GenrePlaylistTracksSlots & InfoPanelCurationProps & GenreFocusProps & {
+} & ArtistSearchProps & GenreDetailSlots<O> & GenrePlaylistTracksSlots & GenreFocusProps & {
+    /** Appended to a selected genre's panel, e.g. destructive actions. */
+    renderDangerZone?: (node: GenreTreeNode) => ReactNode;
+    /** Controlled expanded state of the genre panel. Uncontrolled when omitted. */
+    expanded?: boolean;
+    onExpandedChange?: (expanded: boolean) => void;
+    /** A host panel rendered in the detail panel's slot; it takes precedence over the genre, song and artist panels. */
+    overlayPanel?: HostOverlayPanel;
     /** Hides the info panel behind its edge tab; uncontrolled when omitted. Only applies with `placement="regions"`. */
     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, 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, 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;
@@ -249,13 +294,12 @@ type GenreDetailPanelProps<O extends CriteriaOverview> = {
     collapsed?: boolean;
     expanded?: boolean;
     onExpandedChange?: (expanded: boolean) => void;
+    /** Tab on the panel's inner edge, for hosts that hide and show the panel. */
+    edgeTab?: ComponentProps<typeof DetailPanel>["edgeTab"];
     extras?: GenreInfoPanelBodyProps<O>["extras"];
 };
 /** A genre's detail panel driven by one uuid, with no tree behind it. The tree's own panel shares its body. */
-declare function GenreDetailPanel<O extends CriteriaOverview>({ genreUuid, scope, getBackendBaseUrl, onClose, onSelectGenre, onZoomIn, shareUrl, shareTarget, collapsed, expanded, onExpandedChange, extras, }: GenreDetailPanelProps<O>): react.JSX.Element;
-
-/** Gives the brand layout tokens a zero-width left column while no left detail panel is showing. */
-declare function useLeftDetailPanelLayout(isPanelShown: boolean, enabled?: boolean): void;
+declare function GenreDetailPanel<O extends CriteriaOverview>({ genreUuid, scope, getBackendBaseUrl, onClose, onSelectGenre, onZoomIn, shareUrl, shareTarget, collapsed, expanded, onExpandedChange, edgeTab, extras, }: GenreDetailPanelProps<O>): react.JSX.Element;
 
 type GenrePlaylistTreePerRootProps<T extends TrackBase> = {
     scope: Scope;
@@ -267,19 +311,12 @@ type GenrePlaylistTreePerRootProps<T extends TrackBase> = {
     additionalActions?: (node: GenreTreeNode) => GenreTreeAction[];
     onNodeClick?: (node: GenreTreeNode) => void;
     onNodeHover?: (node: GenreTreeNode) => void;
-    renderInfoPanelBody?: (node: GenreTreeNode, sections: InfoPanelSections) => InfoPanelBody;
     /** Overrides which node is shown highlighted, e.g. from a search selection. */
     selectedNodeId?: string | null;
     /** Fires when a user action changes the info panel's node, or `null` when it is closed. */
     onSelectedNodeChange?: (node: GenreTreeNode | null) => void;
-    /** Hides the info panel's header close button. */
-    hideInfoPanelClose?: boolean;
-    /** Hides the info panel header's node name. */
-    hideInfoPanelTitle?: boolean;
     /** When true, suppresses per-node create/rename affordances. Defaults to false. */
     readOnly?: boolean;
-    /** When false, suppresses the hover toolbar on every node. Defaults to true. */
-    showToolbar?: boolean;
     wheelZoom?: WheelZoomMode;
     /** Mount-only seed for the pan/zoom, replacing the initial fit. */
     defaultViewport?: GenreTreeViewport;
@@ -289,11 +326,12 @@ type GenrePlaylistTreePerRootProps<T extends TrackBase> = {
     onViewportChange?: (viewport: GenreTreeViewport) => void;
     /** What node play buttons play; defaults to each node's whole genre playlist. */
     playback?: GenrePlaylistPlayback;
-} & InfoPanelCurationProps;
-declare function GenrePlaylistTreePerRoot<T extends TrackBase>({ scope, className, rootUuid, genrePlaylistTreePerRoot, handleGenreCreationAction, handleGenreRenameAction, additionalActions, onNodeClick, onNodeHover, renderInfoPanelBody, selectedNodeId, onSelectedNodeChange, hideInfoPanelClose, hideInfoPanelTitle, readOnly, showToolbar, wheelZoom, defaultViewport, viewportRestore, onViewportChange, playback, ...infoPanelCuration }: GenrePlaylistTreePerRootProps<T>): react.JSX.Element;
+} & 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 GenreSearchExtraResults = {
-    /** Heading of this group; genre matches then get a "Genres" heading above it. */
+type GenreSearchExtraGroup = {
+    key: string;
+    /** Heading of this group; genre matches then get a "Genres" heading too. */
     label: string;
     items: {
         key: string;
@@ -310,17 +348,17 @@ type GenreSearchProps<T extends CriteriaPlaylistSimple = CriteriaPlaylistSimple>
     onSelect: (genrePlaylist: T) => void;
     /** Name of the currently selected genre; fills the input whenever it changes. */
     selectedName?: string | null;
-    /** When set, renders a "Previous" button left of the text; shown only when the host's CSS reveals `.genre-search-previous`. */
+    /** When set, renders a "Previous" button left of the text and makes room for it. */
     onPrevious?: () => void;
     /** Called by the clear button, after it empties the input. */
     onClear?: () => void;
     placeholder?: string;
     /** Called with what the user types, and with "" on clear or pick; never when `selectedName` refills the input. */
     onQueryChange?: (query: string) => void;
-    /** A second result group (e.g. artists) the host resolves from `onQueryChange`. */
-    extraResults?: GenreSearchExtraResults;
+    /** Further result groups (artists, songs) the host resolves from `onQueryChange`. */
+    extraGroups?: GenreSearchExtraGroup[];
 };
-declare function GenreSearch<T extends CriteriaPlaylistSimple = CriteriaPlaylistSimple>({ genrePlaylists, onSelect, selectedName, onClear, onPrevious, placeholder, onQueryChange, extraResults, }: GenreSearchProps<T>): react.JSX.Element;
+declare function GenreSearch<T extends CriteriaPlaylistSimple = CriteriaPlaylistSimple>({ genrePlaylists, onSelect, selectedName, onClear, onPrevious, placeholder, onQueryChange, extraGroups, }: GenreSearchProps<T>): react.JSX.Element;
 
 interface TrackListSidebarProps<T extends TrackBase> {
     className?: string;
@@ -332,8 +370,10 @@ interface TrackListSidebarProps<T extends TrackBase> {
     onMinimize?: () => void;
     /** When set, artist names render through it (e.g. a router `Link`). */
     renderArtistLink?: RenderArtistLink;
+    /** When set, song titles render through it (e.g. open the song panel). */
+    renderSongLink?: RenderSongLink;
 }
-declare function TrackListSidebar<T extends TrackBase>({ className, renderDuration, renderActions, layout, isCollapsed, onExpand, onMinimize, renderArtistLink, }: TrackListSidebarProps<T>): react.JSX.Element | null;
+declare function TrackListSidebar<T extends TrackBase>({ className, renderDuration, renderActions, layout, isCollapsed, onExpand, onMinimize, renderArtistLink, renderSongLink, }: TrackListSidebarProps<T>): react.JSX.Element | null;
 
 interface PlayerPanelProps {
     className?: string;
@@ -347,8 +387,10 @@ interface PlayerPanelProps {
     /** Width once extended, e.g. to stop short of a left-hand detail panel. */
     extendedWidth?: string;
     renderArtistLink?: RenderArtistLink;
+    /** When set, song titles in the tracklist render through it (e.g. open the song panel). */
+    renderSongLink?: RenderSongLink;
 }
-declare function PlayerPanel({ className, isVisible, expanded, onExpandedChange, extendedWidth, renderArtistLink, }: PlayerPanelProps): react.JSX.Element;
+declare function PlayerPanel({ className, isVisible, expanded, onExpandedChange, extendedWidth, renderArtistLink, renderSongLink, }: PlayerPanelProps): react.JSX.Element;
 
 interface TrackItemProps<T extends TrackBase> {
     track: T;
@@ -357,8 +399,10 @@ interface TrackItemProps<T extends TrackBase> {
     renderActions?: (track: T) => ReactNode;
     /** When set, artist names render through it (e.g. a router `Link`). */
     renderArtistLink?: RenderArtistLink;
+    /** When set, a song title renders through it (e.g. opens the song panel) instead of linking to MusicBrainz. */
+    renderSongLink?: RenderSongLink;
 }
-declare function TrackItem<T extends TrackBase>({ track, position, renderDuration, renderActions, renderArtistLink, }: TrackItemProps<T>): react.JSX.Element;
+declare function TrackItem<T extends TrackBase>({ track, position, renderDuration, renderActions, renderArtistLink, renderSongLink, }: TrackItemProps<T>): react.JSX.Element;
 
 interface TrackPositionPlayPauseProps {
     position: number;
@@ -374,23 +418,4 @@ interface RatingProps {
 }
 declare function Rating({ rating, handleChange }: RatingProps): react.JSX.Element;
 
-type PanelEdgeTabAction = {
-    label: string;
-    onClick: () => void;
-    /** Reflected as `aria-expanded` on the button; omit when the button is not a disclosure. */
-    expanded?: boolean;
-};
-interface PanelEdgeTabProps {
-    /** Side of the screen the panel sits on; the tab hangs off the panel's inner edge. */
-    side: "left" | "right";
-    /** Button whose chevron points toward the screen edge. */
-    edge: PanelEdgeTabAction | null;
-    /** Button whose chevron points toward the center of the screen. */
-    center: PanelEdgeTabAction | null;
-    /** Id of the panel the buttons control, when the host can name it. */
-    controls?: string;
-    className?: string;
-}
-declare function PanelEdgeTab({ side, edge, center, controls, className }: PanelEdgeTabProps): react.JSX.Element | null;
-
-export { type ArtistSearchProps, GenreDetailPanel, type GenreDetailPanelProps, type GenreDetailSlots, type GenreFocusProps, GenreInfoPanelBody, type GenreInfoPanelBodyProps, GenreNodeActionBand, type GenrePlaylistPlayback, type GenrePlaylistTracksSlots, GenrePlaylistTreePerRoot, type GenrePlaylistTreePerRootProps, GenreSearch, type GenreSearchExtraResults, type GenreSearchProps, type GenreTreeShareTarget, GenreTreeView, type GenreTreeViewProps, type GetGenreTreeShareUrl, type InfoPanelCurationProps, PanelEdgeTab, type PanelEdgeTabAction, type PanelEdgeTabProps, type ParentChange, type PlayableGenrePlaylist, PlayerPanel, type PlayerPanelProps, Rating, type RatingProps, TrackItem, type TrackItemProps, TrackListSidebar, type TrackListSidebarProps, TrackPositionPlayPause, type TrackPositionPlayPauseProps, type UseGenrePlaylistPlaybackOptions, useGenrePlaylistPlayback, useLeftDetailPanelLayout };
+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 };

package/dist/genre-tree/index.js

@@ -9,15 +9,13 @@ import {
   GenreTreeView,
   GenreTreeViewSkeleton,
   GenreTreeWheelSkeleton,
-  PanelEdgeTab,
   PlayerPanel,
   Rating,
   TrackItem,
   TrackListSidebar,
   TrackPositionPlayPause,
-  useGenrePlaylistPlayback,
-  useLeftDetailPanelLayout
-} from "../chunk-36YVZ6JR.js";
+  useGenrePlaylistPlayback
+} from "../chunk-AQASG5KT.js";
 import "../chunk-DKQQLLMY.js";
 export {
   GenreDetailPanel,
@@ -30,13 +28,11 @@ export {
   GenreTreeView,
   GenreTreeViewSkeleton,
   GenreTreeWheelSkeleton,
-  PanelEdgeTab,
   PlayerPanel,
   Rating,
   TrackItem,
   TrackListSidebar,
   TrackPositionPlayPause,
-  useGenrePlaylistPlayback,
-  useLeftDetailPanelLayout
+  useGenrePlaylistPlayback
 };
 //# sourceMappingURL=index.js.map