d3blocks 2.2.1__tar.gz → 2.3.0__tar.gz

{d3blocks-2.2.1 → d3blocks-2.3.0}/MANIFEST.in

@@ -15,5 +15,7 @@ include d3blocks/maps/d3js/*
 include d3blocks/elasticgraph/d3js/*
 include d3blocks/radialgraph/d3js/*
 include d3blocks/flowgraph/d3js/*
+include d3blocks/sequence/d3js/*
+include d3blocks/erd/d3js/*
+include d3blocks/_shared/d3js/*
 include d3blocks/*
-recursive-include d3blocks/skills *

{d3blocks-2.2.1/d3blocks.egg-info → d3blocks-2.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: d3blocks
-Version: 2.2.1
+Version: 2.3.0
 Summary: Python package d3blocks.
 Author-email: Erdogan Taskesen <erdogant@gmail.com>
 License-Expression: GPL-3.0-or-later
-Project-URL: Homepage, https://erdogant.github.io/d3blocks
-Project-URL: Download, https://github.com/erdogant/d3blocks/archive/{version}.tar.gz
+Project-URL: Homepage, https://d3blocks.github.io/d3blocks
+Project-URL: Download, https://github.com/d3blocks/d3blocks/archive/{version}.tar.gz
 Keywords: Python,visualizations,interactive,javascript,d3js,d3blocks,network,graph,data visualization,web,extendable,extension,plugin,modular,customizable
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
@@ -44,8 +44,9 @@ Dynamic: license-file
 ![GitHub repo size](https://img.shields.io/github/repo-size/d3blocks/d3blocks)
 [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://github.com/d3blocks/d3blocks/blob/main/notebooks/d3blocks.ipynb)
 [![Donate](https://img.shields.io/badge/Support%20this%20project-grey.svg?logo=github%20sponsors)](https://d3blocks.github.io/d3blocks/Documentation.html#)
+[![skills.sh](https://skills.sh/b/d3blocks/d3blocks)](https://skills.sh/d3blocks/d3blocks)
 
-### 
+###
 
 <div>
 
@@ -97,6 +98,8 @@ The [documentation pages](https://d3blocks.github.io/d3blocks/) contain detailed
 |  15 | [Maps](https://d3blocks.github.io/d3blocks/Maps.html)                   | ``` d3.maps()  ```           | [D3Blocks](https://medium.com/data-science-collective/d3blocks-the-sweet-spot-for-data-scientists-interactive-charts-without-deployment-friction-c7f576025510) |
 |  16 | [Circlepacking](https://d3blocks.github.io/d3blocks/Circlepacking.html) | ``` d3.circlepacking()  ```  | [D3Blocks](https://medium.com/data-science-collective/d3blocks-the-sweet-spot-for-data-scientists-interactive-charts-without-deployment-friction-c7f576025510) |
 |  17 | [Flowgraph](https://d3blocks.github.io/d3blocks/Flowgraph.html)         | ``` d3.flowgraph()  ```      | [Dagre](https://github.com/dagrejs/dagre) |
+|  18 | [Sequence](https://d3blocks.github.io/d3blocks/Sequence.html)           | ``` d3.sequence()  ```       | [Mermaid sequenceDiagram](https://mermaid.js.org/syntax/sequenceDiagram.html) |
+|  19 | [ERD](https://d3blocks.github.io/d3blocks/ERD.html)                     | ``` d3.erd()  ```            | [Mermaid erDiagram](https://mermaid.js.org/syntax/entityRelationshipDiagram.html) |
 
 -------------------------------------------------------------------------
 
@@ -106,12 +109,31 @@ pip install d3blocks     # Normal installation
 pip install -U d3blocks  # Force update
 ```
 
-#### Installation (clone)
+#### Clone
 ```bash
-git clone https://github.com/d3blocks/d3blocks.git
-cd d3blocks
-pip install -U .
-```  
+# Clone only the latest branch to avoid downloading large history.
+git config --global clone.depth 1
+```
+
+
+
+#### Installation (from GitHub source)
+```bash
+pip install git+https://github.com/d3blocks/d3blocks.git
+```
+
+##### Install skill:
+```bash
+# for visualizations
+npx skills add d3blocks/d3blocks --skill d3blocks
+
+# for chart builder
+npx skills add d3blocks/d3blocks --skill d3blocks-chart-builder
+
+# for docs diagrams (convert a repo's Mermaid diagrams)
+npx skills add d3blocks/d3blocks --skill d3blocks-docs-diagrams
+```
+
 
 #### Import d3blocks package
 ```python
@@ -124,16 +146,16 @@ d3 = D3Blocks()
 ---
 
 ### D3Blocks💙Streamlit
-Every chart from D3Block can easily be incorporated into a Streamlit Dashboard. Because every D3Blocks chart is just HTML and JavaScript, you can generate the HTML in memory and embed it 
+Every chart from D3Block can easily be incorporated into a Streamlit Dashboard. Because every D3Blocks chart is just HTML and JavaScript, you can generate the HTML in memory and embed it
 A few practical rules of thumb: prefer `st.iframe` over the older `components.html` for full interactive charts, always pass an explicit pixel height, and set `show_side_panel=False` when Streamlit already owns the controls so the UI doesn't duplicate. `color_background='streamlit'` picks backgrounds that match a typical Streamlit light or dark page.
 
-* [Minimal examples for each chart can be found in the Streamlit directory in the repo](https://github.com/d3blocks/d3blocks/tree/main/streamlit). 
+* [Minimal examples for each chart can be found in the Streamlit directory in the repo](https://github.com/d3blocks/d3blocks/tree/main/streamlit).
 * [More Streamlit documentation can be found here.](https://d3blocks.github.io/d3blocks/Streamlit.html)
 
 ---
 
 ### Ethical Ads
-When HTMLs are generated, it automatically includes ethical ads as a small way to support development. 
+When HTMLs are generated, it automatically includes ethical ads as a small way to support development.
 I maintain this entire project thoughtfully and in my free time. Ads can be disabled via an input parameter, and you can also support the project with a coffee donation instead.
 
 ### Star history

{d3blocks-2.2.1 → d3blocks-2.3.0}/README.md

@@ -13,8 +13,9 @@
 ![GitHub repo size](https://img.shields.io/github/repo-size/d3blocks/d3blocks)
 [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://github.com/d3blocks/d3blocks/blob/main/notebooks/d3blocks.ipynb)
 [![Donate](https://img.shields.io/badge/Support%20this%20project-grey.svg?logo=github%20sponsors)](https://d3blocks.github.io/d3blocks/Documentation.html#)
+[![skills.sh](https://skills.sh/b/d3blocks/d3blocks)](https://skills.sh/d3blocks/d3blocks)
 
-### 
+###
 
 <div>
 
@@ -66,6 +67,8 @@ The [documentation pages](https://d3blocks.github.io/d3blocks/) contain detailed
 |  15 | [Maps](https://d3blocks.github.io/d3blocks/Maps.html)                   | ``` d3.maps()  ```           | [D3Blocks](https://medium.com/data-science-collective/d3blocks-the-sweet-spot-for-data-scientists-interactive-charts-without-deployment-friction-c7f576025510) |
 |  16 | [Circlepacking](https://d3blocks.github.io/d3blocks/Circlepacking.html) | ``` d3.circlepacking()  ```  | [D3Blocks](https://medium.com/data-science-collective/d3blocks-the-sweet-spot-for-data-scientists-interactive-charts-without-deployment-friction-c7f576025510) |
 |  17 | [Flowgraph](https://d3blocks.github.io/d3blocks/Flowgraph.html)         | ``` d3.flowgraph()  ```      | [Dagre](https://github.com/dagrejs/dagre) |
+|  18 | [Sequence](https://d3blocks.github.io/d3blocks/Sequence.html)           | ``` d3.sequence()  ```       | [Mermaid sequenceDiagram](https://mermaid.js.org/syntax/sequenceDiagram.html) |
+|  19 | [ERD](https://d3blocks.github.io/d3blocks/ERD.html)                     | ``` d3.erd()  ```            | [Mermaid erDiagram](https://mermaid.js.org/syntax/entityRelationshipDiagram.html) |
 
 -------------------------------------------------------------------------
 
@@ -75,12 +78,31 @@ pip install d3blocks     # Normal installation
 pip install -U d3blocks  # Force update
 ```
 
-#### Installation (clone)
+#### Clone
 ```bash
-git clone https://github.com/d3blocks/d3blocks.git
-cd d3blocks
-pip install -U .
-```  
+# Clone only the latest branch to avoid downloading large history.
+git config --global clone.depth 1
+```
+
+
+
+#### Installation (from GitHub source)
+```bash
+pip install git+https://github.com/d3blocks/d3blocks.git
+```
+
+##### Install skill:
+```bash
+# for visualizations
+npx skills add d3blocks/d3blocks --skill d3blocks
+
+# for chart builder
+npx skills add d3blocks/d3blocks --skill d3blocks-chart-builder
+
+# for docs diagrams (convert a repo's Mermaid diagrams)
+npx skills add d3blocks/d3blocks --skill d3blocks-docs-diagrams
+```
+
 
 #### Import d3blocks package
 ```python
@@ -93,16 +115,16 @@ d3 = D3Blocks()
 ---
 
 ### D3Blocks💙Streamlit
-Every chart from D3Block can easily be incorporated into a Streamlit Dashboard. Because every D3Blocks chart is just HTML and JavaScript, you can generate the HTML in memory and embed it 
+Every chart from D3Block can easily be incorporated into a Streamlit Dashboard. Because every D3Blocks chart is just HTML and JavaScript, you can generate the HTML in memory and embed it
 A few practical rules of thumb: prefer `st.iframe` over the older `components.html` for full interactive charts, always pass an explicit pixel height, and set `show_side_panel=False` when Streamlit already owns the controls so the UI doesn't duplicate. `color_background='streamlit'` picks backgrounds that match a typical Streamlit light or dark page.
 
-* [Minimal examples for each chart can be found in the Streamlit directory in the repo](https://github.com/d3blocks/d3blocks/tree/main/streamlit). 
+* [Minimal examples for each chart can be found in the Streamlit directory in the repo](https://github.com/d3blocks/d3blocks/tree/main/streamlit).
 * [More Streamlit documentation can be found here.](https://d3blocks.github.io/d3blocks/Streamlit.html)
 
 ---
 
 ### Ethical Ads
-When HTMLs are generated, it automatically includes ethical ads as a small way to support development. 
+When HTMLs are generated, it automatically includes ethical ads as a small way to support development.
 I maintain this entire project thoughtfully and in my free time. Ads can be disabled via an input parameter, and you can also support the project with a coffee donation instead.
 
 ### Star history

{d3blocks-2.2.1 → d3blocks-2.3.0}/d3blocks/__init__.py

@@ -10,7 +10,7 @@ from d3blocks.utils import (
 
 __author__ = 'Erdogan Taskesen'
 __email__ = 'erdogant@gmail.com'
-__version__ = '2.2.1'
+__version__ = '2.3.0'
 
 # Setup root logger
 import logging

d3blocks-2.3.0/d3blocks/_shared/__init__.py

@@ -0,0 +1,208 @@
+"""Code shared by the flowgraph, sequence and erd blocks.
+
+* template_env(): a Jinja environment over a block's own d3js/ folder and
+  d3blocks/_shared/d3js/ (walkthrough.js/.css, theme.js and the d3.v7.min.js
+  used by sequence and erd), so a template can {% include %} both and the
+  output stays self-contained.
+* notebook_iframe(): the Jupyter iframe wrapper.
+* dark_mode_flag(): validates dark_mode (True, False or 'auto').
+* normalize_steps(): validates the captioned walkthrough steps.
+
+Library     : d3blocks
+Github      : https://github.com/d3blocks/d3blocks
+License     : GPL3
+"""
+
+from html import escape as html_escape
+from pathlib import Path
+
+import numpy as np
+from jinja2 import ChoiceLoader, Environment, FileSystemLoader, PackageLoader
+
+DARK_MODES = (True, False, "auto")
+STEP_KEYS = ("title", "caption", "highlight")
+
+
+def template_env(package_name, block_file):
+    """Jinja environment over the block's d3js/ folder, then _shared/d3js/.
+
+    Parameters
+    ----------
+    package_name : str
+        __name__ of the block module, e.g. 'd3blocks.sequence.Sequence'.
+    block_file : str
+        __file__ of the block module (used when the package loader is unavailable).
+    """
+
+    def loader(package, folder):
+        try:
+            return PackageLoader(package_name=package, package_path="d3js")
+        except Exception:
+            return FileSystemLoader(str(Path(folder).resolve().parent / "d3js"))
+
+    return Environment(
+        loader=ChoiceLoader(
+            [loader(package_name, block_file), loader(__name__, __file__)]
+        )
+    )
+
+
+def notebook_iframe(html, config, block):
+    """Wrap a chart page in an iframe for Jupyter.
+
+    The page fills its window (fixed positioning, own body background) and uses
+    fixed element ids, so it is isolated in an iframe instead of being injected
+    into the notebook page. Size: figsize, else full width x 650 px.
+    """
+    width, height = (list(config.get("figsize") or [None, None]) + [None, None])[:2]
+    width = "%dpx" % width if width else "100%"
+    height = "%dpx" % height if height else "650px"
+    # Wrapped in a div: IPython warns about HTML that starts with '<iframe'.
+    return (
+        '<div class="d3blocks-%s"><iframe srcdoc="%s" title="%s" '
+        'style="width:%s;height:%s;border:0;border-radius:6px" '
+        'sandbox="allow-scripts allow-downloads allow-popups"></iframe></div>'
+        % (
+            block,
+            html_escape(html, quote=True),
+            html_escape(str(config.get("title", block))),
+            width,
+            height,
+        )
+    )
+
+
+def dark_mode_flag(dark_mode):
+    """Template flag for dark_mode: 'true', 'false' or 'auto'.
+
+    * True: dark theme.
+    * False: light theme.
+    * 'auto': follow the operating system theme until the viewer uses the theme toggle.
+    """
+    if isinstance(dark_mode, (bool, np.bool_)):
+        return "true" if dark_mode else "false"
+    if isinstance(dark_mode, str) and dark_mode.lower() == "auto":
+        return "auto"
+    raise ValueError("dark_mode must be True, False or 'auto'; got %r." % (dark_mode,))
+
+
+def check_dark_mode(dark_mode):
+    """dark_mode as True, False or 'auto'; raises ValueError for anything else."""
+    flag = dark_mode_flag(dark_mode)
+    return "auto" if flag == "auto" else flag == "true"
+
+
+def normalize_steps(steps, refs, block):
+    """Validate walkthrough steps and return them as JSON-ready dicts.
+
+    Parameters
+    ----------
+    steps : list of dict or None
+        [{'title': str, 'caption': str, 'highlight': {key: [ref, ...]}}]
+    refs : dict
+        {highlight key: check(ref, step_index) -> resolved ref}. Only these
+        highlight keys are accepted; a check raises ValueError for an unknown ref.
+    block : str
+        Block name, used in error messages.
+
+    Returns
+    -------
+    list of dict or None
+        [{'title', 'caption', 'highlight'}], or None when steps is None.
+
+    """
+    if steps is None:
+        return None
+    if isinstance(steps, (str, dict)) or not hasattr(steps, "__iter__"):
+        raise ValueError(
+            "steps must be a list of dicts or None; got %s." % type(steps).__name__
+        )
+    out = []
+    for i, step in enumerate(steps):
+        if not isinstance(step, dict):
+            raise ValueError(
+                "steps[%d]: expected a dict with %s; got %s."
+                % (i, STEP_KEYS, type(step).__name__)
+            )
+        unknown = sorted(set(step) - set(STEP_KEYS))
+        if unknown:
+            raise ValueError(
+                "steps[%d]: unknown key(s) %s; use %s." % (i, unknown, STEP_KEYS)
+            )
+        highlight = step.get("highlight") or {}
+        if not isinstance(highlight, dict):
+            raise ValueError(
+                "steps[%d]: 'highlight' must be a dict; got %s."
+                % (i, type(highlight).__name__)
+            )
+        unsupported = sorted(set(highlight) - set(refs))
+        if unsupported:
+            raise ValueError(
+                "steps[%d]: highlight key(s) %s are not supported by %s; use %s."
+                % (i, unsupported, block, tuple(refs))
+            )
+        resolved = {}
+        for key, values in highlight.items():
+            if values is None:
+                continue
+            if isinstance(values, (str, int, np.integer)):
+                values = [values]
+            resolved[key] = [refs[key](v, i) for v in values]
+        out.append(
+            {
+                "title": str(step.get("title") or "Step %d" % (i + 1)),
+                "caption": str(step.get("caption") or ""),
+                "highlight": resolved,
+            }
+        )
+    return out
+
+
+def ref_in(names, what):
+    """Check for a reference that must be one of `names`."""
+    names = set(names)
+
+    def check(ref, i):
+        key = str(ref)
+        if key not in names:
+            raise ValueError("steps[%d]: unknown %s %r." % (i, what, ref))
+        return key
+
+    return check
+
+
+def pair_in(pairs, what, undirected=False):
+    """Check for a (source, target) reference that must be in `pairs`."""
+    pairs = {(str(s), str(t)) for s, t in pairs}
+
+    def check(ref, i):
+        if isinstance(ref, str) or not hasattr(ref, "__len__") or len(ref) != 2:
+            raise ValueError(
+                "steps[%d]: %s must be (source, target) pairs; got %r." % (i, what, ref)
+            )
+        s, t = str(ref[0]), str(ref[1])
+        if (s, t) in pairs:
+            return [s, t]
+        if undirected and (t, s) in pairs:
+            return [t, s]
+        raise ValueError("steps[%d]: unknown %s %r." % (i, what, tuple(ref)))
+
+    return check
+
+
+def index_in(count, what):
+    """Check for an integer index in range(count)."""
+
+    def check(ref, i):
+        if (
+            isinstance(ref, (bool, np.bool_))
+            or not isinstance(ref, (int, np.integer))
+            or not 0 <= ref < count
+        ):
+            raise ValueError(
+                "steps[%d]: unknown %s %r; use an index from 0 to %d."
+                % (i, what, ref, count - 1)
+            )
+        return int(ref)
+
+    return check

d3blocks-2.3.0/d3blocks/_shared/d3js/theme.js

@@ -0,0 +1,63 @@
+/*
+ * theme.js - dark/light theme for d3blocks diagrams (flowgraph, sequence, erd).
+ * Included right after <body data-dark-mode="true|false|auto">, so the first
+ * paint already has the right theme. 'auto' follows the operating system
+ * (prefers-color-scheme) until the viewer presses the theme toggle; a
+ * ?theme=light|dark URL parameter overrides 'auto', as in archify.
+ */
+window.D3BlocksTheme = (function () {
+  'use strict';
+  var body = document.body;
+  var mode = body.getAttribute('data-dark-mode') || 'true';
+  var followOs = mode === 'auto';
+  var media = null;
+
+  function isLight() { return body.classList.contains('light'); }
+
+  function syncButton(btn) {
+    if (!btn) return;
+    var light = isLight();
+    btn.textContent = light ? '☀' : '🌙';
+    btn.title = light ? 'Theme: Light' : 'Theme: Dark';
+    btn.setAttribute('aria-pressed', light ? 'true' : 'false');
+  }
+
+  var buttons = [];
+  function set(light) {
+    body.classList.toggle('light', !!light);
+    buttons.forEach(syncButton);
+  }
+
+  if (followOs) {
+    var param = null;
+    try { param = new URLSearchParams(window.location.search).get('theme'); } catch (e) { /* no URL */ }
+    if (param === 'light' || param === 'dark') {
+      followOs = false;
+      set(param === 'light');
+    } else if (window.matchMedia) {
+      // No OS preference (or no matchMedia) falls back to dark.
+      media = window.matchMedia('(prefers-color-scheme: light)');
+      set(media.matches);
+      var onChange = function (e) { if (followOs) set(e.matches); };
+      if (media.addEventListener) media.addEventListener('change', onChange);
+      else if (media.addListener) media.addListener(onChange);
+    } else {
+      set(false);
+    }
+  }
+
+  return {
+    isLight: isLight,
+    // Wire a toggle button; after the first press the toggle wins over the OS theme.
+    bind: function (id) {
+      var btn = document.getElementById(id);
+      if (!btn) return;
+      buttons.push(btn);
+      syncButton(btn);
+      btn.addEventListener('click', function () {
+        followOs = false;
+        set(!isLight());
+      });
+    }
+  };
+})();

d3blocks-2.3.0/d3blocks/_shared/d3js/walkthrough.css

@@ -0,0 +1,56 @@
+/* Captioned walkthrough (walkthrough.js). Colours come from the block's theme
+   variables, so the bar follows the dark/light theme. */
+.d3b-walk {
+  position: fixed;
+  left: 50%;
+  bottom: 16px;
+  transform: translateX(-50%);
+  width: min(760px, calc(100vw - 32px));
+  box-sizing: border-box;
+  z-index: 1300;
+  display: grid;
+  grid-template-columns: 1fr auto;
+  grid-template-areas: "text controls" "rail rail";
+  gap: 8px 14px;
+  align-items: center;
+  padding: 12px 16px;
+  border-radius: 10px;
+  background: var(--panel-bg);
+  color: var(--text);
+  border: 1px solid var(--panel-border);
+  box-shadow: var(--panel-shadow);
+  font-family: "Helvetica", Arial, sans-serif;
+  transition: var(--transition);
+}
+.d3b-walk[hidden] { display: none; }
+.d3b-walk-text { grid-area: text; min-width: 0; }
+.d3b-walk-count {
+  font-size: 11px;
+  color: var(--text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+.d3b-walk-title { font-size: 15px; font-weight: bold; margin: 2px 0; }
+.d3b-walk-caption { font-size: 13px; line-height: 1.45; color: var(--text); opacity: 0.9; }
+.d3b-walk-controls { grid-area: controls; display: flex; gap: 6px; }
+.d3b-walk-controls .button-switch { margin: 0; padding: 5px 10px; font-size: 13px; white-space: nowrap; }
+.d3b-walk-rail { grid-area: rail; display: flex; flex-wrap: wrap; gap: 5px; }
+.d3b-walk-stop {
+  width: 18px;
+  height: 6px;
+  padding: 0;
+  border: 0;
+  border-radius: 3px;
+  background: var(--btn-border);
+  cursor: pointer;
+  transition: background 0.15s;
+}
+.d3b-walk-stop.done { background: var(--text-muted); }
+.d3b-walk-stop.active { background: var(--accent); }
+.d3b-walk-stop:focus-visible, .d3b-walk-controls .button-switch:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+@media (max-width: 640px) {
+  .d3b-walk { grid-template-columns: 1fr; grid-template-areas: "text" "rail" "controls"; }
+}

d3blocks-2.3.0/d3blocks/_shared/d3js/walkthrough.js

@@ -0,0 +1,145 @@
+/*
+ * walkthrough.js - captioned walkthrough shared by flowgraph, sequence and erd.
+ * A caption bar at the bottom of the chart shows the step title, caption and
+ * "Step i of n", a rail of step stops and Prev / Play-Pause / Next. The block
+ * highlights the step's elements in onStep(step) and restores in onClose().
+ * Keyboard while open: <- and -> move, Space plays or pauses, Esc closes.
+ * Playback is reader-started and bounded: it stops on the last step.
+ */
+window.D3BlocksWalkthrough = function (opts) {
+  'use strict';
+  var steps = opts.steps || [];
+  var PLAY_MS = 3000;
+  var index = -1, timer = null, isOpen = false;
+
+  function el(tag, cls, text) {
+    var e = document.createElement(tag);
+    if (cls) e.className = cls;
+    if (text !== undefined) e.textContent = text;
+    return e;
+  }
+  function button(cls, text, title) {
+    var b = el('button', 'button-switch ' + cls, text);
+    b.type = 'button';
+    b.title = title;
+    b.setAttribute('aria-label', title);
+    return b;
+  }
+
+  var bar = el('div', 'd3b-walk');
+  bar.setAttribute('role', 'region');
+  bar.setAttribute('aria-label', 'Walkthrough');
+  bar.hidden = true;
+  var text = el('div', 'd3b-walk-text');
+  var count = el('div', 'd3b-walk-count');
+  var title = el('div', 'd3b-walk-title');
+  var caption = el('div', 'd3b-walk-caption');
+  caption.setAttribute('aria-live', 'polite');
+  text.appendChild(count); text.appendChild(title); text.appendChild(caption);
+  var rail = el('div', 'd3b-walk-rail');
+  rail.setAttribute('aria-label', 'Steps');
+  var stops = steps.map(function (s, i) {
+    var b = el('button', 'd3b-walk-stop');
+    b.type = 'button';
+    b.title = (i + 1) + '. ' + s.title;
+    b.setAttribute('aria-label', 'Step ' + (i + 1) + ': ' + s.title);
+    b.addEventListener('click', function () { pause(); go(i); });
+    rail.appendChild(b);
+    return b;
+  });
+  if (steps.length > 40) rail.style.display = 'none';
+  var controls = el('div', 'd3b-walk-controls');
+  var prevBtn = button('d3b-walk-prev', '‹ Prev', 'Previous step');
+  var playBtn = button('d3b-walk-play', '▶ Play', 'Play the walkthrough');
+  var nextBtn = button('d3b-walk-next', 'Next ›', 'Next step');
+  var closeBtn = button('d3b-walk-close', '✕', 'Close the walkthrough');
+  [prevBtn, playBtn, nextBtn, closeBtn].forEach(function (b) { controls.appendChild(b); });
+  bar.appendChild(text); bar.appendChild(rail); bar.appendChild(controls);
+  document.body.appendChild(bar);
+
+  prevBtn.addEventListener('click', function () { pause(); go(index - 1); });
+  nextBtn.addEventListener('click', function () { pause(); go(index + 1); });
+  playBtn.addEventListener('click', function () { if (timer) pause(); else play(); });
+  closeBtn.addEventListener('click', close);
+
+  var triggers = (opts.triggers || []).map(function (id) { return document.getElementById(id); }).filter(Boolean);
+  triggers.forEach(function (b) {
+    b.addEventListener('click', function () { if (isOpen) close(); else open(); });
+  });
+
+  function go(i) {
+    if (!steps.length) return;
+    index = Math.max(0, Math.min(steps.length - 1, i));
+    var s = steps[index];
+    count.textContent = 'Step ' + (index + 1) + ' of ' + steps.length;
+    title.textContent = s.title;
+    caption.textContent = s.caption;
+    caption.style.display = s.caption ? '' : 'none';
+    stops.forEach(function (b, k) {
+      b.classList.toggle('done', k < index);
+      b.classList.toggle('active', k === index);
+      if (k === index) b.setAttribute('aria-current', 'step'); else b.removeAttribute('aria-current');
+    });
+    prevBtn.disabled = index === 0;
+    nextBtn.disabled = index === steps.length - 1;
+    if (opts.onStep) opts.onStep(s, index);
+  }
+
+  function play() {
+    if (index >= steps.length - 1) go(0);
+    playBtn.textContent = '❚❚ Pause';
+    playBtn.title = 'Pause the walkthrough';
+    timer = setInterval(function () {
+      if (index >= steps.length - 1) { pause(); return; }
+      go(index + 1);
+    }, PLAY_MS);
+  }
+
+  function pause() {
+    clearInterval(timer);
+    timer = null;
+    playBtn.textContent = '▶ Play';
+    playBtn.title = 'Play the walkthrough';
+  }
+
+  function open(i) {
+    if (!steps.length) return;
+    isOpen = true;
+    bar.hidden = false;
+    document.body.classList.add('d3b-walking');
+    triggers.forEach(function (b) { b.classList.add('active'); });
+    if (opts.onOpen) opts.onOpen();
+    go(i === undefined ? 0 : i);
+  }
+
+  function close() {
+    if (!isOpen) return;
+    pause();
+    isOpen = false;
+    bar.hidden = true;
+    index = -1;
+    document.body.classList.remove('d3b-walking');
+    triggers.forEach(function (b) { b.classList.remove('active'); });
+    if (opts.onClose) opts.onClose();
+  }
+
+  document.addEventListener('keydown', function (e) {
+    if (!isOpen) return;
+    var tag = document.activeElement && document.activeElement.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return;
+    if (e.key === 'ArrowRight') { e.preventDefault(); pause(); go(index + 1); }
+    else if (e.key === 'ArrowLeft') { e.preventDefault(); pause(); go(index - 1); }
+    else if (e.key === ' ' || e.key === 'Spacebar') { e.preventDefault(); if (timer) pause(); else play(); }
+    else if (e.key === 'Escape') { close(); }
+  });
+
+  return {
+    open: open,
+    close: close,
+    go: go,
+    isOpen: function () { return isOpen; },
+    index: function () { return index; },
+    // Height of the caption bar (plus its margin) while open; 0 when closed.
+    height: function () { return isOpen ? bar.getBoundingClientRect().height + 16 : 0; }
+  };
+};