# Visualization library ## Tools A library entry is the only home for visualization code — a widget points at an entry and never inlines it. Any member of any workspace may author one, and `render` (kind `visualization`, on the Widgets page) checks that it draws. For a hover tooltip, use a div with class `vz-tooltip` (a `vz-tooltip-title` header, then `vz-tooltip-row`s holding a `vz-tooltip-label` and a `vz-tooltip-value`, an optional `vz-tooltip-marker` coloured by `color`) so it matches the dashboard's charts; you position it. | Tool | What it does | | |---|---|---| | [`list_visualizations`](#list_visualizations) | List visualizations | Read-only | | [`get_visualization`](#get_visualization) | Get visualization | Read-only | | [`save_visualization`](#save_visualization) | Save visualization | Destructive write | | [`delete_visualization`](#delete_visualization) | Delete visualization | Destructive write | ## list_visualizations `Read-only` List the workspace's visualization library: shared entries plus your own, archived excluded. CALL IT BEFORE creating one with save_visualization — each row carries what the entry draws and the row shape it expects, so reusing or improving one usually beats a near-duplicate. Rows report the dashboards binding it and `health` (ok, render_error, non_finite) with `healthAt`: prefer an ok entry, and fix a flagged one before reuse (get_visualization shows why). source:'gallery' lists the STARTER GALLERY (a beeswarm, a Gantt, a waterfall), each row a slug and its data shape. All three also draw as an echartsConfig (get_chart_recipe), so copy one (save_visualization fromGallery) only for its finish: signed labels, sentiment colouring, per-point dodging. ## get_visualization `Read-only` Return one library visualization in full — its metadata, its complete code, and its recent sealed versions (rev + when, for manage_version `restore`, kind visualization). Also its render health: `health`, lastRenderError* (survives later successes, cleared when the code is replaced) and lastNonFinite* (count and examples of NaN/Infinity/undefined labels, cleared by a clean server render). Use before editing an entry, to pattern-match a new visualization against a working one, or to investigate a render error: the code is the contract, the description is only a summary. You supply the workspace and entry id. Any workspace member may read any entry by id — visibility governs listings and new bindings, not reads. ## save_visualization `Destructive write` Create or update a library visualization: authored code for a chart the built-in renderers can't draw (a marimekko, a circle pack, a custom mark). Omit `entryId` to create; pass it to update (rules on `entryId`). An echartsConfig already draws sankey, chord, graph, tree, boxplot, candlestick, parallel, theme river, gauge, and map or lines over the `world` and `usa` atlases, and get_chart_recipe has the composed forms (waterfall, Gantt, beeswarm, pyramid, violin, X-Y scatter): none needs code. Create one only when neither can express the chart and list_visualizations has nothing reusable, or copy a gallery entry with `fromGallery`. Otherwise pass a name, a REQUIRED description (what it draws, what rows it expects), `code` (its field is the contract) and `sampleRows` so the Widgets page can preview it. A throw or NaN at save returns a `warning` and flags the entry. Private until visibility 'workspace'. VERIFY with render (kind visualization), then bind it with add_widget type visualizationRef. ### `entryId` The entry to update: code, description, name, engine label, visibility, archived, or sampleRows (keep them matching the row shape). LIVE REFERENCE: every bound dashboard renders the entry's head, so a code edit changes every bound widget the moment it lands — check boundDashboardCount first and tell the user what else will change. Fix or improve an entry this way rather than creating a near-duplicate. archived:true retires it (refused while bound); false restores it, as any code edit does. Code and description edits seal a version after a quiet period; the rest is metadata. The author or a workspace admin may edit. A code or sampleRows edit returns `sampleRender`, with a `warning` if they threw or printed NaN. After a code edit, VERIFY with render (kind visualization): every bound dashboard is already drawing it. ## delete_visualization `Destructive write` Delete a library visualization permanently. REFUSES while any non-archived dashboard still binds it, naming those dashboards — repoint or remove those widgets first, so deleting can never blank a rendering dashboard. Use for genuine cleanup of an unbound or archived entry; there is no undo and no restore. Confirm with the user only when their request does NOT identify the entry unambiguously ("delete the old map" in a library holding three maps); when the request names the visualization, or you resolved the id from list_visualizations and it matches what was asked for, that request IS the confirmation — verify the id, then delete it. Author or workspace admin.