@behindthemusictree/app-kit-ui 28.0.2 → 29.0.1

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

@@ -1,9 +1,9 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
+import { ReactNode, ComponentProps } from 'react';
 import { z } from 'zod';
-import { GenreTreeProps, FocusChangeReason, GenreTreeNode, GenreTreeAction, GenreTreeViewMode, GenreTreeViewport, ControlsOrientation, InfoPanelSections, InfoPanelBody, WheelZoomMode } from '@behindthemusictree/genre-tree-view';
-export { ControlsOrientation, FocusChangeReason, GenreTreeAction, GenreTreeOutlineSkeleton, GenreTreeSkeleton, GenreTreeViewMode, GenreTreeViewSkeleton, GenreTreeViewSkeletonProps, GenreTreeViewport, GenreTreeWheelSkeleton } from '@behindthemusictree/genre-tree-view';
-import { TrackBase, CriteriaOverview, CriteriaPlaylistSimple, GenreUuid, GenrePlaylistUuid, ArtistSearchResult, CriteriaMinimum, RenderArtistLink } from '@behindthemusictree/app-kit/genre-tree';
+import { GenreTreeProps, FocusChangeReason, GenreTreeNode, GenreTreeAction, GenreTreeViewMode, GenreTreeViewport, InfoPanelSections, InfoPanelBody, 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 { Scope } from '@behindthemusictree/app-kit/transport';
 
 type GenrePlaylistTracksSlots = {
@@ -21,15 +21,46 @@ type GenreDetailSlots<O extends CriteriaOverview> = {
     /** Replaces the default Essential section (e.g. "Essential songs"). */
     renderEssentialTracks?: (overview: O) => ReactNode;
 };
+type GenreDetailExtrasProps<O extends CriteriaOverview> = GenreDetailSlots<O> & GenrePlaylistTracksSlots & {
+    genreUuid: GenreUuid;
+    genrePlaylist: CriteriaPlaylistMinimum;
+    wikidataId?: string | null;
+    scope: Scope;
+    getBackendBaseUrl: () => string;
+    criteriaOverviewSchema?: z.ZodType<O, unknown>;
+    renderGenreDetailExtras?: (overview: O) => ReactNode;
+    renderArtistLink?: RenderArtistLink;
+    /** When set, the tracks list shows only this artist's songs in the genre. */
+    artist?: {
+        uuid: string;
+        name: string;
+    } | null;
+    /** genre-tree-view's Family section, placed right after the Summary. */
+    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">>;
 
+/** What a play button needs of a playlist; `criteria` is only read when playing one artist's songs in the genre. */
+type PlayableGenrePlaylistInput = CriteriaPlaylistMinimum & {
+    criteria?: CriteriaPlaylistSimple["criteria"];
+};
 /** What a tree node's play button plays, and which node is the one currently playing. */
 type GenrePlaylistPlayback = {
     playingNodeId: string | null;
-    play: (genrePlaylist: CriteriaPlaylistSimple) => Promise<void>;
+    play: (genrePlaylist: PlayableGenrePlaylistInput) => Promise<void>;
 };
+type UseGenrePlaylistPlaybackOptions = {
+    scope: Scope;
+    genrePlaylists: CriteriaPlaylistSimple[];
+    /** When set, nodes play only this artist's songs in the genre's subtree instead of the whole genre playlist. */
+    artist?: {
+        uuid: string;
+        name: string;
+    } | null;
+};
+declare function useGenrePlaylistPlayback<T extends TrackBase = TrackBase>({ scope, genrePlaylists, artist, }: UseGenrePlaylistPlaybackOptions): GenrePlaylistPlayback;
 
 type GenreTreeSizeMetric = "songs" | "views";
 
@@ -103,6 +134,10 @@ type GenreTreeViewProps<O extends CriteriaOverview = CriteriaOverview> = {
     onSelectedNodeIdChange?: (nodeId: string | null) => void;
     /** Mount-only seed for the pan/zoom (wheel, pop-core and stacked views), replacing the initial fit. */
     defaultViewport?: GenreTreeViewport;
+    /** Restore silently after layout; use a new revision for each navigation. Supply focus, selection,
+     * and restoration together. User interaction supersedes a pending request. In stacked view,
+     * the selected genre must resolve to a root; outline ignores restoration. */
+    viewportRestore?: GenreTreeProps["viewportRestore"];
     /** Fires after a user-driven pan/zoom settles. In stacked view, only the tree holding the selection reports. */
     onViewportChange?: (viewport: GenreTreeViewport) => void;
     /** When true, hides the "Add root" button and suppresses per-node
@@ -120,8 +155,6 @@ type GenreTreeViewProps<O extends CriteriaOverview = CriteriaOverview> = {
     criteriaOverviewSchema?: z.ZodType<O, unknown>;
     /** Consumer-specific rows rendered in the info panel after Summary. */
     renderGenreDetailExtras?: (overview: O) => ReactNode;
-    /** Layout of the wheel/tree floating zoom/pop/fit controls. Defaults to "horizontal". */
-    controlsOrientation?: ControlsOrientation;
     /** Host control displayed before the size metric in the floating controls. */
     floatingControlsLeading?: ReactNode;
     /** Controlled size metric of the wheel and pop-core nodes: song count or summed song views. Uncontrolled when omitted
@@ -148,7 +181,81 @@ 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, onViewportChange, readOnly, className, showDisplayOptions, showAddRoot, allowWheelRotation: controlledAllowWheelRotation, criteriaOverviewSchema, renderGenreDetailExtras, controlsOrientation, 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, renderSummary, renderEssentialTracks, renderSongLeading, renderSongActions, renderTracksToolbar, renderDangerZone, expanded, onExpandedChange, collapsed, onCollapsedChange, overlayPanel, placement, ...focus }: GenreTreeViewProps<O>): react.JSX.Element;
+
+type GenreActionBandProps = {
+    node: GenreTreeNode;
+    /** When set, shows the Play/Pause action. */
+    onPlayPause?: () => void;
+    isPlaying?: boolean;
+    /** When set, shows the "Zoom in" action. */
+    onZoomIn?: () => void;
+    /** When set, shows the "Add" (sub-genre) action. */
+    onAddChild?: () => void;
+    /** When set, shows the "Rename" action. */
+    onRename?: () => void;
+    /** When set, shows the "Parent" (change parent) action. */
+    onChangeParent?: () => void;
+    side?: "core" | "pop";
+    /** When set, shows the "Make pop" / "Make core" action. */
+    onToggleSide?: () => void;
+    /** When set, disables the side toggle and explains why in its tooltip. */
+    toggleSideDisabledReason?: string;
+    additionalActions?: (node: GenreTreeNode) => GenreTreeAction[];
+    shareTarget?: GenreTreeShareTarget;
+    shareUrl?: string;
+};
+declare function GenreActionBand({ node, onPlayPause, isPlaying, onZoomIn, onAddChild, onRename, onChangeParent, side, onToggleSide, toggleSideDisabledReason, additionalActions, shareTarget, shareUrl, }: GenreActionBandProps): react.JSX.Element | null;
+
+/** What the action band reads of a genre's playlist: enough to play it and to know whether it can be. */
+type PlayableGenrePlaylist = CriteriaPlaylistMinimum & {
+    tracksCount: number;
+};
+type GenreNodeActionBandProps = Omit<ComponentProps<typeof GenreActionBand>, "onPlayPause" | "isPlaying"> & {
+    genrePlaylist: PlayableGenrePlaylist;
+    playback: GenrePlaylistPlayback;
+};
+declare function GenreNodeActionBand({ genrePlaylist, playback, ...bandProps }: GenreNodeActionBandProps): react.JSX.Element;
+type GenreInfoPanelBodyProps<O extends CriteriaOverview> = {
+    /** genre-tree-view's toolbar section, rendered first. */
+    toolbar?: ReactNode;
+    family: ReactNode;
+    genreUuid: GenreUuid;
+    genrePlaylist: PlayableGenrePlaylist;
+    wikidataId?: string | null;
+    scope: Scope;
+    getBackendBaseUrl: () => string;
+    playback: GenrePlaylistPlayback;
+    /** Action band props other than play, which the body derives from `playback`. */
+    band: Omit<GenreNodeActionBandProps, "genrePlaylist" | "playback">;
+    extras?: Omit<GenreDetailExtrasProps<O>, "family" | "genreUuid" | "genrePlaylist" | "wikidataId" | "scope" | "getBackendBaseUrl">;
+};
+/** The body of a genre's info panel: action band, then the genre's overview, family and tracks.
+ * Shared by the tree's panel and the standalone GenreDetailPanel. */
+declare function GenreInfoPanelBody<O extends CriteriaOverview>({ toolbar, family, genreUuid, genrePlaylist, wikidataId, scope, getBackendBaseUrl, playback, band, extras, }: GenreInfoPanelBodyProps<O>): react.JSX.Element;
+
+type GenreDetailPanelProps<O extends CriteriaOverview> = {
+    genreUuid: GenreUuid;
+    scope: Scope;
+    getBackendBaseUrl: () => string;
+    onClose: () => void;
+    /** Fired with the uuid of a family or ancestor chip the user picked. */
+    onSelectGenre: (genreUuid: GenreUuid) => void;
+    /** When set, the panel offers "Focus". */
+    onZoomIn?: () => void;
+    /** Absolute or relative URL that shares this genre; the share action shows only when set. */
+    shareUrl?: string;
+    shareTarget?: GenreTreeShareTarget;
+    collapsed?: boolean;
+    expanded?: boolean;
+    onExpandedChange?: (expanded: boolean) => void;
+    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;
 
 type GenrePlaylistTreePerRootProps<T extends TrackBase> = {
     scope: Scope;
@@ -174,16 +281,16 @@ type GenrePlaylistTreePerRootProps<T extends TrackBase> = {
     /** When false, suppresses the hover toolbar on every node. Defaults to true. */
     showToolbar?: boolean;
     wheelZoom?: WheelZoomMode;
-    /** Layout of the floating zoom/pop/fit controls. Defaults to "vertical". */
-    controlsOrientation?: ControlsOrientation;
     /** Mount-only seed for the pan/zoom, replacing the initial fit. */
     defaultViewport?: GenreTreeViewport;
+    /** Runtime viewport restoration request. */
+    viewportRestore?: GenreTreeProps["viewportRestore"];
     /** Fires after a user-driven pan/zoom settles. */
     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, controlsOrientation, defaultViewport, onViewportChange, playback, ...infoPanelCuration }: GenrePlaylistTreePerRootProps<T>): react.JSX.Element;
+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;
 
 type GenreSearchExtraResults = {
     /** Heading of this group; genre matches then get a "Genres" heading above it. */
@@ -286,4 +393,4 @@ interface PanelEdgeTabProps {
 }
 declare function PanelEdgeTab({ side, edge, center, controls, className }: PanelEdgeTabProps): react.JSX.Element | null;
 
-export { type ArtistSearchProps, type GenreDetailSlots, type GenreFocusProps, 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, PlayerPanel, type PlayerPanelProps, Rating, type RatingProps, TrackItem, type TrackItemProps, TrackListSidebar, type TrackListSidebarProps, TrackPositionPlayPause, type TrackPositionPlayPauseProps };
+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 };

package/dist/genre-tree/index.js

@@ -1,4 +1,7 @@
 import {
+  GenreDetailPanel,
+  GenreInfoPanelBody,
+  GenreNodeActionBand,
   GenrePlaylistTreePerRoot,
   GenreSearch,
   GenreTreeOutlineSkeleton,
@@ -11,10 +14,15 @@ import {
   Rating,
   TrackItem,
   TrackListSidebar,
-  TrackPositionPlayPause
-} from "../chunk-5PQWJRDZ.js";
+  TrackPositionPlayPause,
+  useGenrePlaylistPlayback,
+  useLeftDetailPanelLayout
+} from "../chunk-TFLX6C5Q.js";
 import "../chunk-DKQQLLMY.js";
 export {
+  GenreDetailPanel,
+  GenreInfoPanelBody,
+  GenreNodeActionBand,
   GenrePlaylistTreePerRoot,
   GenreSearch,
   GenreTreeOutlineSkeleton,
@@ -27,6 +35,8 @@ export {
   Rating,
   TrackItem,
   TrackListSidebar,
-  TrackPositionPlayPause
+  TrackPositionPlayPause,
+  useGenrePlaylistPlayback,
+  useLeftDetailPanelLayout
 };
 //# sourceMappingURL=index.js.map