Merge pull request #702 from nteract/fix-hierarchical-charts

Fix hierarchical chart rendering, hover clearing, and docs updates

Author: emeeks

CHANGELOG.md

@@ -35,6 +35,13 @@ A producer-consumer coordination system for cross-highlighting, brushing-and-lin
 - Tooltip positioned above the hovered point with colorBy label
 - `colorBy`, `fieldLabels`, `cellSize`, `pointRadius`, `showLegend` props
 
+### Fixed
+
+- **Hover state persisting on mouseout** — tooltip and linked highlight now reliably clear when the mouse leaves the chart area. Added a `mouseLeave` handler on the Frame wrapper (inside `TooltipProvider`) that clears both the tooltip and any active `customHoverBehavior` selection.
+- **`createStore` updater bug** — the internal `set` function in `createStore` passed itself instead of the current state to updater callbacks (`fn(set)` → `fn(state)`). This caused `clearClause` in the SelectionStore to silently fail (accessing `.selections` on a function), so linked hover selections were never actually cleared. `setClause` worked by coincidence because `new Map(undefined)` produces an empty map.
+- **Treemap/CirclePack hover overlays** — fixed broken hover overlays for all area-based NetworkFrame types (treemap, circlepack, partition, chord). After the Mark component removal in v3, overlay entries spread `.props` from node generators which produced `<path>` elements without a `d` attribute. Now passes `renderElement` directly for `React.cloneElement`.
+- **CirclePack rendering as force-directed** — CirclePack defaulted all circles to 10px diameter because the node size accessor ignored d3 pack layout's `r` property. Now uses `nodeSizeAccessor: (d) => d.r || 5`.
+
 ### Removed
 
 - **FacetController** — replaced entirely by `LinkedCharts`. The `cloneElement`-based approach had no HOC support and only worked with direct Frame children.

CLAUDE.md

@@ -344,14 +344,18 @@ Props: `data` (TNode, required — single root node with children),
 ```
 
 #### Treemap
-Space-filling rectangular hierarchy visualization.
+Space-filling rectangular hierarchy visualization. Labels are centered in cells.
+Hover shows ancestor breadcrumb path (grandparent → parent → **node**) with outline.
+`colorByDepth` uses a pastel palette keyed to hierarchy depth.
 
 Props: `data` (TNode, required — single root node with children),
   `childrenAccessor` (string|fn, "children"), `valueAccessor` (string|fn, "value"),
   `nodeIdAccessor` (string|fn, "name"),
   `colorBy` (string|fn), `colorScheme` (string|string[], "category10"),
   `colorByDepth` (boolean, false),
-  `showLabels` (boolean, true), `nodeLabel` (string|fn),
+  `showLabels` (boolean, true), `labelMode` ("leaf"|"parent"|"all", "leaf"),
+  `nodeLabel` (string|fn),
+  `padding` (number, 4), `paddingTop` (number, 0 — auto 18 when labelMode="parent"),
   `title` (string), `width` (number, 600), `height` (number, 600),
   `enableHover` (boolean, true), `tooltip` (fn),
   `margin` (object), `className` (string), `frameProps` (object)
@@ -361,15 +365,18 @@ Props: `data` (TNode, required — single root node with children),
 ```
 
 #### CirclePack
-Nested circles representing hierarchical data.
+Nested circles representing hierarchical data. Leaf labels are centered; parent labels
+are top-center with white-outlined black text. Circles smaller than 15px radius hide labels.
+Hover shows ancestor breadcrumb path (grandparent → parent → **node**) with circle outline.
+`colorByDepth` uses a pastel palette keyed to hierarchy depth (same as Treemap).
 
 Props: `data` (TNode, required — single root node with children),
   `childrenAccessor` (string|fn, "children"), `valueAccessor` (string|fn, "value"),
   `nodeIdAccessor` (string|fn, "name"),
   `colorBy` (string|fn), `colorScheme` (string|string[], "category10"),
   `colorByDepth` (boolean, false),
   `showLabels` (boolean, true), `nodeLabel` (string|fn),
-  `circleOpacity` (number, 0.7),
+  `circleOpacity` (number, 0.7), `padding` (number, 4),
   `title` (string), `width` (number, 600), `height` (number, 600),
   `enableHover` (boolean, true), `tooltip` (fn),
   `margin` (object), `className` (string), `frameProps` (object)

docs/src/IndexPages.js

@@ -129,7 +129,7 @@ export function GuidesIndex() {
         />
         <PageLink
           href="/guides/small-multiples"
-          title="Small Multiples"
+          title="Linked Charts"
           thumbnail={new URL("../public/assets/img/facet.png", import.meta.url)}
         />
         <PageLink

docs/src/components/navData.js

@@ -86,7 +86,7 @@ const navData = [
       { title: "Accessibility", path: "/features/accessibility" },
       { title: "Canvas Rendering", path: "/features/canvas-rendering" },
       { title: "Sparklines", path: "/features/sparklines" },
-      { title: "Small Multiples", path: "/features/small-multiples" },
+      { title: "Linked Charts", path: "/features/small-multiples" },
       { title: "Styling", path: "/features/styling" },
       { title: "Legends", path: "/features/legends" }
     ]

docs/src/guides/SmallMultiples.js

@@ -7,7 +7,7 @@ export default function() {
       <MarkdownText
         text={`
 
-Small multiples are now accomplished using \`LinkedCharts\`, which provides a modern producer-consumer coordination system for cross-highlighting, brushing-and-linking, and cross-filtering between charts. See the [Small Multiples & Coordinated Views](/features/small-multiples) page for details.
+Small multiples and coordinated views are now accomplished using \`LinkedCharts\`, which provides a modern producer-consumer coordination system for cross-highlighting, brushing-and-linking, and cross-filtering between charts. See the [Linked Charts](/features/small-multiples) page for details.
 
       `}
       />

docs/src/pages/charts/TreemapPage.js

@@ -56,7 +56,10 @@ const treemapProps = [
   { name: "colorScheme", type: "string | array", required: false, default: '"category10"', description: "Color scheme for nodes or custom colors array." },
   { name: "colorByDepth", type: "boolean", required: false, default: "false", description: "Color nodes by hierarchy depth level." },
   { name: "showLabels", type: "boolean", required: false, default: "true", description: "Show labels on treemap cells." },
+  { name: "labelMode", type: '"leaf" | "parent" | "all"', required: false, default: '"leaf"', description: 'Which nodes to label. "leaf" labels only leaf nodes, "parent" labels depth-1 group headers, "all" labels everything.' },
   { name: "nodeLabel", type: "string | function", required: false, default: "nodeIdAccessor", description: "Node label accessor." },
+  { name: "padding", type: "number", required: false, default: "4", description: "Padding between parent and child rectangles (pixels). Makes parent containers visible." },
+  { name: "paddingTop", type: "number", required: false, default: '0 (18 when labelMode="parent")', description: "Extra padding at the top of parent nodes. Provides space for parent label text." },
   { name: "enableHover", type: "boolean", required: false, default: "true", description: "Enable hover annotations." },
   { name: "tooltip", type: "object | function", required: false, default: null, description: "Tooltip configuration or render function." },
   { name: "width", type: "number", required: false, default: "600", description: "Chart width in pixels." },
@@ -176,6 +179,31 @@ export default function TreemapPage() {
         hiddenProps={{}}
       />
 
+      <h3 id="parent-labels">Parent Labels</h3>
+      <p>
+        Use <code>labelMode="parent"</code> to label only the top-level groups.
+        This automatically adds <code>paddingTop</code> for header space.
+      </p>
+
+      <LiveExample
+        frameProps={{
+          data: sampleData,
+          nodeIdAccessor: "name",
+          valueAccessor: "value",
+          colorBy: "name",
+          labelMode: "parent",
+          padding: 3,
+        }}
+        type={Treemap}
+        overrideProps={{
+          data: "hierarchyData",
+          colorBy: '"name"',
+          labelMode: '"parent"',
+          padding: "3",
+        }}
+        hiddenProps={{}}
+      />
+
       {/* ----------------------------------------------------------------- */}
       {/* Props */}
       {/* ----------------------------------------------------------------- */}

docs/src/pages/features/LegendsPage.js

@@ -591,8 +591,8 @@ function InteractiveChart({ data }) {
           patterns, and visual encodings
         </li>
         <li>
-          <Link to="/features/small-multiples">Small Multiples</Link> — shared
-          legends across multiple coordinated frames
+          <Link to="/features/small-multiples">Linked Charts</Link> — shared
+          legends across multiple coordinated charts
         </li>
       </ul>
     </PageLayout>

docs/src/pages/features/SmallMultiplesPage.js

@@ -15,24 +15,29 @@ import PropTable from "../../components/PropTable"
 import { Link } from "react-router-dom"
 
 // ---------------------------------------------------------------------------
-// Sample data for LinkedCharts
+// Sample data for LinkedCharts live example
 // ---------------------------------------------------------------------------
 
-const linkedData = [
-  { x: 10, y: 45, region: "North", income: 52 },
-  { x: 20, y: 55, region: "North", income: 61 },
-  { x: 30, y: 65, region: "South", income: 48 },
-  { x: 40, y: 35, region: "South", income: 39 },
-  { x: 50, y: 72, region: "East", income: 75 },
-  { x: 60, y: 62, region: "East", income: 68 },
-  { x: 70, y: 48, region: "West", income: 54 },
-  { x: 80, y: 58, region: "West", income: 62 },
+const salesData = [
+  { month: "Jan", revenue: 42, region: "North", spend: 18 },
+  { month: "Feb", revenue: 51, region: "North", spend: 22 },
+  { month: "Mar", revenue: 65, region: "South", spend: 28 },
+  { month: "Apr", revenue: 38, region: "South", spend: 15 },
+  { month: "May", revenue: 72, region: "East", spend: 35 },
+  { month: "Jun", revenue: 60, region: "East", spend: 30 },
+  { month: "Jul", revenue: 48, region: "West", spend: 20 },
+  { month: "Aug", revenue: 55, region: "West", spend: 24 },
+  { month: "Sep", revenue: 67, region: "North", spend: 31 },
+  { month: "Oct", revenue: 58, region: "South", spend: 26 },
+  { month: "Nov", revenue: 74, region: "East", spend: 38 },
+  { month: "Dec", revenue: 63, region: "West", spend: 29 },
 ]
 
-const barAgg = ["North", "South", "East", "West"].map((region) => ({
-  category: region,
-  total: linkedData.filter((d) => d.region === region).reduce((s, d) => s + d.income, 0),
+const regionTotals = ["North", "South", "East", "West"].map((region) => ({
   region,
+  total: salesData
+    .filter((d) => d.region === region)
+    .reduce((s, d) => s + d.revenue, 0),
 }))
 
 // ---------------------------------------------------------------------------
@@ -132,53 +137,91 @@ const splomProps = [
 export default function SmallMultiplesPage() {
   return (
     <PageLayout
-      title="Small Multiples & Coordinated Views"
+      title="Linked Charts"
       breadcrumbs={[
         { label: "Features", path: "/features" },
-        { label: "Small Multiples", path: "/features/small-multiples" },
+        { label: "Linked Charts", path: "/features/small-multiples" },
       ]}
       prevPage={{ title: "Sparklines", path: "/features/sparklines" }}
       nextPage={{ title: "Styling", path: "/features/styling" }}
     >
       <p>
-        Semiotic provides <strong>LinkedCharts</strong> for modern
-        producer-consumer coordination between charts, enabling
-        cross-highlighting, brushing-and-linking, and cross-filtering.
+        <strong>LinkedCharts</strong> is a React Context provider that enables
+        cross-highlighting, brushing-and-linking, and cross-filtering between
+        any Semiotic chart components at any depth in the tree. Charts opt in
+        via the <code>selection</code>, <code>linkedHover</code>, and{" "}
+        <code>linkedBrush</code> props.
       </p>
 
       {/* ----------------------------------------------------------------- */}
-      {/* LinkedCharts */}
+      {/* Live example */}
       {/* ----------------------------------------------------------------- */}
-      <h2 id="linked-charts">LinkedCharts (Recommended)</h2>
+      <h2 id="example">Example</h2>
 
       <p>
-        <code>LinkedCharts</code> uses React Context to enable cross-highlighting,
-        brushing-and-linking, and cross-filtering between any chart components
-        at any depth in the tree. Charts opt in via the <code>selection</code>,{" "}
-        <code>linkedHover</code>, and <code>linkedBrush</code> props.
+        Hover over a point in the scatterplot to highlight the matching region
+        in the bar chart, and vice versa:
       </p>
 
-      <h3 id="cross-highlighting">Cross-Highlighting</h3>
-      <p>
-        Hover over a point in one chart to highlight matching data in all
-        linked charts:
-      </p>
+      <div style={{ marginBottom: 32 }}>
+        <LinkedCharts>
+          <div style={{ display: "flex", gap: 24, flexWrap: "wrap" }}>
+            <Scatterplot
+              data={salesData}
+              xAccessor="revenue"
+              yAccessor="spend"
+              colorBy="region"
+              pointRadius={6}
+              width={360}
+              height={300}
+              xLabel="Revenue"
+              yLabel="Spend"
+              linkedHover={{ name: "hl", fields: ["region"] }}
+              selection={{ name: "hl" }}
+            />
+            <BarChart
+              data={regionTotals}
+              categoryAccessor="region"
+              valueAccessor="total"
+              colorBy="region"
+              width={320}
+              height={300}
+              valueLabel="Total Revenue"
+              linkedHover={{ name: "hl", fields: ["region"] }}
+              selection={{ name: "hl" }}
+            />
+          </div>
+        </LinkedCharts>
+      </div>
 
       <CodeBlock
         code={`import { LinkedCharts, Scatterplot, BarChart } from "semiotic"
 
+const salesData = [
+  { month: "Jan", revenue: 42, region: "North", spend: 18 },
+  { month: "Feb", revenue: 51, region: "North", spend: 22 },
+  // ...
+]
+
+const regionTotals = ["North", "South", "East", "West"].map(region => ({
+  region,
+  total: salesData
+    .filter(d => d.region === region)
+    .reduce((s, d) => s + d.revenue, 0),
+}))
+
 <LinkedCharts>
   <Scatterplot
-    data={data}
-    xAccessor="x"
-    yAccessor="y"
+    data={salesData}
+    xAccessor="revenue"
+    yAccessor="spend"
     colorBy="region"
     linkedHover={{ name: "hl", fields: ["region"] }}
     selection={{ name: "hl" }}
   />
   <BarChart
-    data={barData}
-    categoryAccessor="category"
+    data={regionTotals}
+    categoryAccessor="region"
     valueAccessor="total"
     colorBy="region"
     linkedHover={{ name: "hl", fields: ["region"] }}
@@ -188,6 +231,40 @@ export default function SmallMultiplesPage() {
         language="jsx"
       />
 
+      {/* ----------------------------------------------------------------- */}
+      {/* How it works */}
+      {/* ----------------------------------------------------------------- */}
+      <h2 id="how-it-works">How It Works</h2>
+
+      <p>
+        <code>LinkedCharts</code> wraps your charts in a shared selection
+        store. Each chart can <strong>produce</strong> selections (via{" "}
+        <code>linkedHover</code> or <code>linkedBrush</code>) and{" "}
+        <strong>consume</strong> them (via <code>selection</code>). When a
+        selection is active, non-matching elements are dimmed.
+      </p>
+
+      <h3 id="selection-props">Selection Props on Charts</h3>
+      <p>
+        All HOC chart components accept these coordination props when used
+        inside <code>LinkedCharts</code>:
+      </p>
+
+      <CodeBlock
+        code={`// selection — consume a named selection (dims unmatched elements)
+selection={{ name: "mySelection", unselectedOpacity: 0.2 }}
+
+// linkedHover — produce hover-based selections
+linkedHover={{ name: "hl", fields: ["category"] }}
+linkedHover={true}          // shorthand: name="hover", auto-detect fields
+linkedHover="myHoverName"   // shorthand: custom name, auto-detect fields
+
+// linkedBrush — produce brush-based selections (Scatterplot, BubbleChart only)
+linkedBrush={{ name: "brush", xField: "x", yField: "y" }}
+linkedBrush="selectionName" // shorthand`}
+        language="jsx"
+      />
+
       <h3 id="brush-and-link">Brush-and-Link</h3>
       <p>
         Brush a region in one chart to filter data in another. Use the{" "}
@@ -214,7 +291,7 @@ function FilteredDetail({ data }) {
         language="jsx"
       />
 
-      <h3 id="cross-filtering">Cross-Filtering Dashboard</h3>
+      <h3 id="cross-filtering">Cross-Filtering</h3>
       <p>
         With <code>resolution: "crossfilter"</code>, each chart's own brush is
         excluded from its filter — the standard SPLOM interaction model:
@@ -245,31 +322,6 @@ function FilteredDetail({ data }) {
         props={linkedChartsProps}
       />
 
-      {/* ----------------------------------------------------------------- */}
-      {/* Selection Props */}
-      {/* ----------------------------------------------------------------- */}
-      <h3 id="selection-props">Selection Props on Charts</h3>
-      <p>
-        All HOC chart components (Scatterplot, BarChart, LineChart, etc.)
-        accept these coordination props when used inside{" "}
-        <code>LinkedCharts</code>:
-      </p>
-
-      <CodeBlock
-        code={`// selection — consume a named selection (dims unmatched elements)
-selection={{ name: "mySelection", unselectedOpacity: 0.2 }}
-
-// linkedHover — produce hover-based selections
-linkedHover={{ name: "hl", fields: ["category"] }}
-linkedHover={true}          // shorthand: name="hover", auto-detect fields
-linkedHover="myHoverName"   // shorthand: custom name, auto-detect fields
-
-// linkedBrush — produce brush-based selections (Scatterplot, BubbleChart only)
-linkedBrush={{ name: "brush", xField: "x", yField: "y" }}
-linkedBrush="selectionName" // shorthand`}
-        language="jsx"
-      />
-
       {/* ----------------------------------------------------------------- */}
       {/* ScatterplotMatrix */}
       {/* ----------------------------------------------------------------- */}
@@ -279,7 +331,7 @@ linkedBrush="selectionName" // shorthand`}
         The <code>ScatterplotMatrix</code> (SPLOM) renders an N x N grid of
         scatterplots with built-in cross-filter brushing. Diagonal cells
         show histograms. Brushing one cell highlights matching points in
-        all other cells.
+        all other cells. It uses <code>LinkedCharts</code> internally.
       </p>
 
       <div style={{ marginBottom: 32 }}>
@@ -383,7 +435,7 @@ const filtered = useFilteredData(data, "mySelection")`}
         </li>
         <li>
           <Link to="/features/legends">Legends</Link> — adding legends to your
-          small multiple layouts
+          coordinated chart layouts
         </li>
       </ul>
     </PageLayout>