@behindthemusictree/genre-tree-view 6.2.0 → 6.5.0

package/dist/index.d.cts

@@ -60,6 +60,8 @@ interface GenreTreeAction {
 type WheelZoomMode = "always" | "modifier";
 /** Layout of the floating zoom/pop/fit controls — see `GenreTreeProps.controlsOrientation`. */
 type ControlsOrientation = "horizontal" | "vertical";
+/** When the floating zoom in / zoom out / fit buttons show — see `GenreTreeProps.showZoomControls`. */
+type ZoomControlsVisibility = "auto" | "always" | "never";
 /** The pan/zoom view as the content-space point shown at the viewport's center plus the scale —
  * independent of the container's pixel size, so a saved view lands on the same spot in any window. */
 interface GenreTreeViewport {
@@ -91,6 +93,13 @@ interface GenreTreeProps {
     nodes: GenreTreeNode[];
     /** Label for the info panel's `itemCount` row (e.g. "Song count"); the library can't know what unit is counted. */
     itemCountLabel: string;
+    /** Optional total for the current itemCount metric. When provided, node sizes use a fixed
+     * logarithmic domain from zero to this total, so filtering recalculates each node's size against
+     * the filtered total. The total must use the same metric as GenreTreeNode.itemCount. */
+    itemCountScaleMax?: number;
+    /** Full node count used to adapt maximum node/card/dot size to visualization density. Defaults
+     * to nodes.length; wheel renderers pass their complete dataset to their selected subtree. */
+    nodeCountForSizing?: number;
     className?: string;
     rootColor?: string;
     orientation?: TreeOrientation;
@@ -136,6 +145,10 @@ interface GenreTreeProps {
     /** Stacks the floating zoom/pop/fit controls vertically ("vertical", the default) or lays them
      * out in a row ("horizontal"). */
     controlsOrientation?: ControlsOrientation;
+    /** "auto" (the default) hides the zoom in / zoom out / fit buttons on touch screens
+     * (`pointer: coarse`), where pinch and pan replace them; "always" and "never" force them. The
+     * `floatingControlsLeading` content stays visible either way. */
+    showZoomControls?: ZoomControlsVisibility;
     /** Host content rendered in the floating controls box, beside the zoom buttons ("horizontal")
      * or above them ("vertical"); stacked above them in narrow containers. */
     floatingControlsLeading?: ReactNode;
@@ -203,6 +216,13 @@ interface GenreTreeProps {
      * initial `selectedNodeId`. Read once; later changes are ignored. Ignored when `interactive` is
      * false and by `GenreTreeOutline`. */
     defaultViewport?: GenreTreeViewport;
+    /** Restores a viewport silently after the target frame has measurable geometry. Change
+     * revision for each navigation, and supply its focus/selection in the same props update.
+     * User interaction supersedes pending restoration. Ignored by GenreTreeOutline. */
+    viewportRestore?: {
+        viewport: GenreTreeViewport;
+        revision: string | number;
+    };
     /** Fired once a user-driven pan/zoom settles (drag, wheel, pinch, zoom/fit buttons, centering on
      * a clicked node) — not for the initial fit or for applying `defaultViewport`. */
     onViewportChange?: (viewport: GenreTreeViewport) => void;
@@ -237,7 +257,7 @@ interface GenreTreeOverlayPanel {
  * Purely presentational: fetching, mutations, and popups are the consumer's responsibility,
  * wired through the callback props.
  */
-declare function GenreTree({ nodes, className, rootColor, orientation, hideRoot, playingNodeId, playState, reparentingNodeId, onPlayPause, onAddChild, onRenameRequest, onDeleteRequest, onReparentRequest, onReparent, onNodeClick, additionalActions, interactive, depthSpacingScale, showToolbar, selectedNodeId: selectedNodeIdProp, renderInfoPanelBody, onSelectedNodeChange, hideInfoPanelClose, hideInfoPanelTitle, itemCountLabel, readOnly, renderDangerZone, expanded, onExpandedChange, collapsed, hideExpandButton, overlayPanel, wheelZoom, defaultViewport, onViewportChange, controlsOrientation, floatingControlsLeading, busy, }: GenreTreeProps): react.JSX.Element;
+declare function GenreTree({ nodes, className, rootColor, orientation, hideRoot, playingNodeId, playState, reparentingNodeId, onPlayPause, onAddChild, onRenameRequest, onDeleteRequest, onReparentRequest, onReparent, onNodeClick, additionalActions, interactive, depthSpacingScale, showToolbar, selectedNodeId: selectedNodeIdProp, renderInfoPanelBody, onSelectedNodeChange, hideInfoPanelClose, hideInfoPanelTitle, itemCountLabel, itemCountScaleMax, nodeCountForSizing, readOnly, renderDangerZone, expanded, onExpandedChange, collapsed, hideExpandButton, overlayPanel, wheelZoom, defaultViewport, viewportRestore, onViewportChange, controlsOrientation, showZoomControls, floatingControlsLeading, busy, }: GenreTreeProps): react.JSX.Element;
 
 interface GenreTreeWheelProps extends Omit<GenreTreeProps, "nodes" | "rootColor" | "orientation"> {
     nodes: GenreTreeNode[];
@@ -338,7 +358,7 @@ type GenreTreeWheelRadialPopCoreProps = WheelRadialPopCoreProps;
  */
 declare function GenreTreeWheelRadialPopCore(props: GenreTreeWheelRadialPopCoreProps): react.JSX.Element;
 
-type GenreTreeOutlineProps = Omit<GenreTreeProps, "rootColor" | "orientation" | "hideRoot" | "interactive" | "depthSpacingScale" | "wheelZoom" | "controlsOrientation" | "floatingControlsLeading" | "busy">;
+type GenreTreeOutlineProps = Omit<GenreTreeProps, "rootColor" | "orientation" | "hideRoot" | "interactive" | "depthSpacingScale" | "wheelZoom" | "controlsOrientation" | "showZoomControls" | "floatingControlsLeading" | "busy">;
 /**
  * Text counterpart of `GenreTreeWheelRadialPopCore`: the same forest as nested collapsible lists
  * (`<details>`), "Mainstream Pop" first, then every other root with its direct children split
@@ -384,4 +404,4 @@ declare function groupNodesByRoot(nodes: GenreTreeNode[]): GenreTreeRootGroup[];
  */
 declare function isZoomableNode(nodes: readonly GenreTreeNode[], id: string): boolean;
 
-export { type ControlsOrientation, DEFAULT_FRAME_HEIGHT, DEFAULT_FRAME_WIDTH, type FocusChangeReason, GenreTree, type GenreTreeAction, type GenreTreeNode, GenreTreeOutline, type GenreTreeOutlineProps, GenreTreeOutlineSkeleton, type GenreTreeOverlayPanel, type GenreTreePlayState, type GenreTreeProps, type GenreTreeRootGroup, GenreTreeSkeleton, type GenreTreeViewMode, GenreTreeViewSkeleton, type GenreTreeViewSkeletonProps, type GenreTreeViewport, GenreTreeWheel, type GenreTreeWheelProps, GenreTreeWheelRadial, GenreTreeWheelRadialPopCore, type GenreTreeWheelRadialPopCoreProps, type GenreTreeWheelRadialProps, GenreTreeWheelRight, type GenreTreeWheelRightProps, GenreTreeWheelSkeleton, type InfoPanelBody, type InfoPanelSections, type TreeOrientation, type WheelZoomMode, getGenreTreeColor, groupNodesByRoot, isZoomableNode };
+export { type ControlsOrientation, DEFAULT_FRAME_HEIGHT, DEFAULT_FRAME_WIDTH, type FocusChangeReason, GenreTree, type GenreTreeAction, type GenreTreeNode, GenreTreeOutline, type GenreTreeOutlineProps, GenreTreeOutlineSkeleton, type GenreTreeOverlayPanel, type GenreTreePlayState, type GenreTreeProps, type GenreTreeRootGroup, GenreTreeSkeleton, type GenreTreeViewMode, GenreTreeViewSkeleton, type GenreTreeViewSkeletonProps, type GenreTreeViewport, GenreTreeWheel, type GenreTreeWheelProps, GenreTreeWheelRadial, GenreTreeWheelRadialPopCore, type GenreTreeWheelRadialPopCoreProps, type GenreTreeWheelRadialProps, GenreTreeWheelRight, type GenreTreeWheelRightProps, GenreTreeWheelSkeleton, type InfoPanelBody, type InfoPanelSections, type TreeOrientation, type WheelZoomMode, type ZoomControlsVisibility, getGenreTreeColor, groupNodesByRoot, isZoomableNode };

package/dist/index.d.ts

@@ -60,6 +60,8 @@ interface GenreTreeAction {
 type WheelZoomMode = "always" | "modifier";
 /** Layout of the floating zoom/pop/fit controls — see `GenreTreeProps.controlsOrientation`. */
 type ControlsOrientation = "horizontal" | "vertical";
+/** When the floating zoom in / zoom out / fit buttons show — see `GenreTreeProps.showZoomControls`. */
+type ZoomControlsVisibility = "auto" | "always" | "never";
 /** The pan/zoom view as the content-space point shown at the viewport's center plus the scale —
  * independent of the container's pixel size, so a saved view lands on the same spot in any window. */
 interface GenreTreeViewport {
@@ -91,6 +93,13 @@ interface GenreTreeProps {
     nodes: GenreTreeNode[];
     /** Label for the info panel's `itemCount` row (e.g. "Song count"); the library can't know what unit is counted. */
     itemCountLabel: string;
+    /** Optional total for the current itemCount metric. When provided, node sizes use a fixed
+     * logarithmic domain from zero to this total, so filtering recalculates each node's size against
+     * the filtered total. The total must use the same metric as GenreTreeNode.itemCount. */
+    itemCountScaleMax?: number;
+    /** Full node count used to adapt maximum node/card/dot size to visualization density. Defaults
+     * to nodes.length; wheel renderers pass their complete dataset to their selected subtree. */
+    nodeCountForSizing?: number;
     className?: string;
     rootColor?: string;
     orientation?: TreeOrientation;
@@ -136,6 +145,10 @@ interface GenreTreeProps {
     /** Stacks the floating zoom/pop/fit controls vertically ("vertical", the default) or lays them
      * out in a row ("horizontal"). */
     controlsOrientation?: ControlsOrientation;
+    /** "auto" (the default) hides the zoom in / zoom out / fit buttons on touch screens
+     * (`pointer: coarse`), where pinch and pan replace them; "always" and "never" force them. The
+     * `floatingControlsLeading` content stays visible either way. */
+    showZoomControls?: ZoomControlsVisibility;
     /** Host content rendered in the floating controls box, beside the zoom buttons ("horizontal")
      * or above them ("vertical"); stacked above them in narrow containers. */
     floatingControlsLeading?: ReactNode;
@@ -203,6 +216,13 @@ interface GenreTreeProps {
      * initial `selectedNodeId`. Read once; later changes are ignored. Ignored when `interactive` is
      * false and by `GenreTreeOutline`. */
     defaultViewport?: GenreTreeViewport;
+    /** Restores a viewport silently after the target frame has measurable geometry. Change
+     * revision for each navigation, and supply its focus/selection in the same props update.
+     * User interaction supersedes pending restoration. Ignored by GenreTreeOutline. */
+    viewportRestore?: {
+        viewport: GenreTreeViewport;
+        revision: string | number;
+    };
     /** Fired once a user-driven pan/zoom settles (drag, wheel, pinch, zoom/fit buttons, centering on
      * a clicked node) — not for the initial fit or for applying `defaultViewport`. */
     onViewportChange?: (viewport: GenreTreeViewport) => void;
@@ -237,7 +257,7 @@ interface GenreTreeOverlayPanel {
  * Purely presentational: fetching, mutations, and popups are the consumer's responsibility,
  * wired through the callback props.
  */
-declare function GenreTree({ nodes, className, rootColor, orientation, hideRoot, playingNodeId, playState, reparentingNodeId, onPlayPause, onAddChild, onRenameRequest, onDeleteRequest, onReparentRequest, onReparent, onNodeClick, additionalActions, interactive, depthSpacingScale, showToolbar, selectedNodeId: selectedNodeIdProp, renderInfoPanelBody, onSelectedNodeChange, hideInfoPanelClose, hideInfoPanelTitle, itemCountLabel, readOnly, renderDangerZone, expanded, onExpandedChange, collapsed, hideExpandButton, overlayPanel, wheelZoom, defaultViewport, onViewportChange, controlsOrientation, floatingControlsLeading, busy, }: GenreTreeProps): react.JSX.Element;
+declare function GenreTree({ nodes, className, rootColor, orientation, hideRoot, playingNodeId, playState, reparentingNodeId, onPlayPause, onAddChild, onRenameRequest, onDeleteRequest, onReparentRequest, onReparent, onNodeClick, additionalActions, interactive, depthSpacingScale, showToolbar, selectedNodeId: selectedNodeIdProp, renderInfoPanelBody, onSelectedNodeChange, hideInfoPanelClose, hideInfoPanelTitle, itemCountLabel, itemCountScaleMax, nodeCountForSizing, readOnly, renderDangerZone, expanded, onExpandedChange, collapsed, hideExpandButton, overlayPanel, wheelZoom, defaultViewport, viewportRestore, onViewportChange, controlsOrientation, showZoomControls, floatingControlsLeading, busy, }: GenreTreeProps): react.JSX.Element;
 
 interface GenreTreeWheelProps extends Omit<GenreTreeProps, "nodes" | "rootColor" | "orientation"> {
     nodes: GenreTreeNode[];
@@ -338,7 +358,7 @@ type GenreTreeWheelRadialPopCoreProps = WheelRadialPopCoreProps;
  */
 declare function GenreTreeWheelRadialPopCore(props: GenreTreeWheelRadialPopCoreProps): react.JSX.Element;
 
-type GenreTreeOutlineProps = Omit<GenreTreeProps, "rootColor" | "orientation" | "hideRoot" | "interactive" | "depthSpacingScale" | "wheelZoom" | "controlsOrientation" | "floatingControlsLeading" | "busy">;
+type GenreTreeOutlineProps = Omit<GenreTreeProps, "rootColor" | "orientation" | "hideRoot" | "interactive" | "depthSpacingScale" | "wheelZoom" | "controlsOrientation" | "showZoomControls" | "floatingControlsLeading" | "busy">;
 /**
  * Text counterpart of `GenreTreeWheelRadialPopCore`: the same forest as nested collapsible lists
  * (`<details>`), "Mainstream Pop" first, then every other root with its direct children split
@@ -384,4 +404,4 @@ declare function groupNodesByRoot(nodes: GenreTreeNode[]): GenreTreeRootGroup[];
  */
 declare function isZoomableNode(nodes: readonly GenreTreeNode[], id: string): boolean;
 
-export { type ControlsOrientation, DEFAULT_FRAME_HEIGHT, DEFAULT_FRAME_WIDTH, type FocusChangeReason, GenreTree, type GenreTreeAction, type GenreTreeNode, GenreTreeOutline, type GenreTreeOutlineProps, GenreTreeOutlineSkeleton, type GenreTreeOverlayPanel, type GenreTreePlayState, type GenreTreeProps, type GenreTreeRootGroup, GenreTreeSkeleton, type GenreTreeViewMode, GenreTreeViewSkeleton, type GenreTreeViewSkeletonProps, type GenreTreeViewport, GenreTreeWheel, type GenreTreeWheelProps, GenreTreeWheelRadial, GenreTreeWheelRadialPopCore, type GenreTreeWheelRadialPopCoreProps, type GenreTreeWheelRadialProps, GenreTreeWheelRight, type GenreTreeWheelRightProps, GenreTreeWheelSkeleton, type InfoPanelBody, type InfoPanelSections, type TreeOrientation, type WheelZoomMode, getGenreTreeColor, groupNodesByRoot, isZoomableNode };
+export { type ControlsOrientation, DEFAULT_FRAME_HEIGHT, DEFAULT_FRAME_WIDTH, type FocusChangeReason, GenreTree, type GenreTreeAction, type GenreTreeNode, GenreTreeOutline, type GenreTreeOutlineProps, GenreTreeOutlineSkeleton, type GenreTreeOverlayPanel, type GenreTreePlayState, type GenreTreeProps, type GenreTreeRootGroup, GenreTreeSkeleton, type GenreTreeViewMode, GenreTreeViewSkeleton, type GenreTreeViewSkeletonProps, type GenreTreeViewport, GenreTreeWheel, type GenreTreeWheelProps, GenreTreeWheelRadial, GenreTreeWheelRadialPopCore, type GenreTreeWheelRadialPopCoreProps, type GenreTreeWheelRadialProps, GenreTreeWheelRight, type GenreTreeWheelRightProps, GenreTreeWheelSkeleton, type InfoPanelBody, type InfoPanelSections, type TreeOrientation, type WheelZoomMode, type ZoomControlsVisibility, getGenreTreeColor, groupNodesByRoot, isZoomableNode };