Visualization library

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-rows 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.

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.

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.

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.

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.