Skip to content

Chart builder

A dialog that builds a chart block from CSV, shows what the check flags, and inserts on request.

<div data-mount="plain"></div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/chart-builder.css";
import { chooseColumns, chartReady, chartDirective } from "capsomer/behavior/chart-builder";

Usage

import { ChartBuilder } from "capsomer/react/chart-builder";

<ChartBuilder
  onInsert={(block) => editor.insertAtCursor(block)}
  // The family sites' check: Prelum's editorialPack with strictCharts, loaded when needed.
  check={async (block, drawable) => {
    const m = await import("./chart-check.client");
    return { findings: m.checkCharts(block), suggestion: m.suggestFinding(drawable) };
  }}
  preview={{ action: "/p/site/e/item/preview", source: (block) => withFrontmatter(block) }}
/>;

Examples

With the app's check, drafted finding and a chart drawn here

<p class="cap-muted">Open it, paste <code>month,visits</code> and two rows, and the columns, the check and the chart follow. The inserted block shows below.</p>
<div data-mount="full"></div>

API reference

ChartBuilder

PropTypeRequiredDoes
onInsert(block: string) => voidYesPuts the finished block in the text, at the cursor.
typesreadonly ChartType[]The chart types offered, first one chosen. Default: Prelum's bar, line, area, dot.
write(fields: ChartFields) => stringThe block for the fields, in the site's syntax. Default: Prelum's :::chart directive.
check(block: string, drawable: string) => Promise<ChartCheck>The app's chart check (Prelum's under strictCharts on the family sites), run on the block as written and, for the suggestion, on one with a stand-in finding so it can be drawn.
draw(fields: ChartFields, width: number, fit: ChartFit) => stringThe chart drawn here, in the chart frame, as the fields change: Enarratio's figure as a string.
preview{ action: string; name?: string; source?: (block: string) => string }The chart as the site renders it: the block, wrapped by source, posted to action as the field name (default "source") into a sandboxed frame.
maxBytesnumber
initialPartial<ChartFields>The fields the dialog starts with, and returns to after an insert: a chart being edited again.
labelReactNodeThe opening button's words. Default "Insert chart".
buttonVariant"default" | "quiet" | "secondary"
buttonSize"xs" | "sm" | "default"

Functions

FunctionSignatureDoes
chooseColumns(columns: readonly CsvColumn[], current: { x: string; y: readonly string[]; }): { x: string; y: string[]; }The columns chosen after the data changed: a choice that is still a column is kept; otherwise x is the first column and y every numeric column after it.
chartReady(f: Pick<ChartFields, "x" | "y" | "csv">): booleanWhether the fields make a chart: two columns or more, an x, and at least one y that is not x.
chartDirective(f: ChartFields): stringPrelum's chart block. An empty title or caption is left out; the alt is always written, so a blank one is flagged by Prelum's required-alt rule rather than silently missing.

Parts and data attributes

ClassIs
.cap-chart-builderthe root
.cap-chart-builder-checka part
.cap-chart-builder-csva part
.cap-chart-builder-findingsa part
.cap-chart-builder-notea part
.cap-chart-builder-previewa part
.cap-chart-builder-suggestiona part
.cap-chart-builder-ya part
StateRead from
:emptythe platform

Accessibility

KeyDoes
Enter or Space (Insert chart)Opens the dialog, focus inside it
Tab, Shift+TabMoves through the fields, kept inside the dialog
Left arrow, Right arrow (chart type)Chooses the type
Space (a y column)Adds or removes it
Enter (Use as the finding)Puts the drafted finding in the Finding box
Enter (Insert chart)Inserts the block, closes, focus back on the opening button
EscCloses without inserting, focus back on the opening button
  • The dialog is the shared Dialog: modal, named by its title, described by its lead, focus kept inside and returned to the button.
  • Every field is a Field: label above, help as its description, Required marked. The y columns are a fieldset with a legend.
  • The check's result is a status region, so a finding arriving is said once. The drafted finding is a named group.
  • The site preview frame is titled ("The chart as the site renders it"); the drawn chart is the chart frame's, with its own title, finding and table.
  • Insert's refusal is the button's disabledReason, read as its description.