@north-light/crouter 0.3.197 → 0.3.198

package/dist/pages/elements/chart.d.ts

@@ -1 +1,23 @@
+/**
+ * `<crtr-chart>` — the line, bar and area plots the page bundle draws.
+ *
+ * ## Every value here is a `--crtr-chart-*` token
+ *
+ * The frame, the legend, the axes and the marks themselves are painted through
+ * `var(--crtr-chart-<part>-<knob>, <kit default>)`, so a host restyles this element by setting
+ * properties on the document root — custom properties inherit into shadow roots, which is the
+ * whole mechanism. Series colour keeps coming from the bundle-wide `--crtr-chart-1..5` ramp,
+ * which is the theme layer rather than a component knob.
+ *
+ * Mark paint that SVG would otherwise carry as a presentation attribute — the grid's stroke,
+ * the line's width and caps, the area's fill opacity, the point radius, the bar's corner
+ * radius — is written as CSS instead, because an attribute cannot hold a `var()` chain and so
+ * cannot be overridden. The rendered plot height is styling and reads
+ * `--crtr-chart-plot-height`; what stays in TypeScript is the coordinate system's layout
+ * arithmetic — the drawing height, margins, tick budget and label metrics are inputs to the
+ * geometry this element computes, not declarations a stylesheet could carry.
+ *
+ * Defaults stay inline at the rule that spends them and no `--crtr-chart-*` component token is
+ * ever declared: an unset token is what carries the kit default down the chain.
+ */
 export {};

package/dist/pages/elements/chart.js

@@ -1,4 +1,25 @@
-import { artifactData } from '../host.js';
+/**
+ * `<crtr-chart>` — the line, bar and area plots the page bundle draws.
+ *
+ * ## Every value here is a `--crtr-chart-*` token
+ *
+ * The frame, the legend, the axes and the marks themselves are painted through
+ * `var(--crtr-chart-<part>-<knob>, <kit default>)`, so a host restyles this element by setting
+ * properties on the document root — custom properties inherit into shadow roots, which is the
+ * whole mechanism. Series colour keeps coming from the bundle-wide `--crtr-chart-1..5` ramp,
+ * which is the theme layer rather than a component knob.
+ *
+ * Mark paint that SVG would otherwise carry as a presentation attribute — the grid's stroke,
+ * the line's width and caps, the area's fill opacity, the point radius, the bar's corner
+ * radius — is written as CSS instead, because an attribute cannot hold a `var()` chain and so
+ * cannot be overridden. The rendered plot height is styling and reads
+ * `--crtr-chart-plot-height`; what stays in TypeScript is the coordinate system's layout
+ * arithmetic — the drawing height, margins, tick budget and label metrics are inputs to the
+ * geometry this element computes, not declarations a stylesheet could carry.
+ *
+ * Defaults stay inline at the rule that spends them and no `--crtr-chart-*` component token is
+ * ever declared: an unset token is what carries the kit default down the chain.
+ */
 import { registerElement } from '../register.js';
 import { readSlotConfig } from '../slot-config.js';
 /** The five chart tokens, cycled when a config declares more than five series. */
@@ -30,36 +51,38 @@ const STYLE = `
   [part="container"] {
     display: flex;
     flex-direction: column;
-    gap: var(--crtr-space-2);
+    gap: var(--crtr-chart-container-gap, var(--crtr-space-2));
     width: 100%;
   }
 
   [part="title"] {
-    color: var(--crtr-color-text);
-    font-weight: 500;
+    color: var(--crtr-chart-title-text-color, var(--crtr-color-text));
+    font-weight: var(--crtr-chart-title-font-weight, 500);
   }
 
   [part="legend"] {
     display: flex;
     flex-wrap: wrap;
     align-items: center;
-    gap: var(--crtr-space-1) var(--crtr-space-4);
-    color: var(--crtr-color-text-muted);
-    font-size: calc(var(--crtr-font-size) * 0.85);
+    gap: var(--crtr-chart-legend-gap, var(--crtr-space-1) var(--crtr-space-4));
+    color: var(--crtr-chart-legend-text-color, var(--crtr-color-text-muted));
+    font-size: var(--crtr-chart-legend-font-size, 0.875em);
   }
 
   [part="legend-item"] {
     display: flex;
     align-items: center;
-    gap: var(--crtr-space-1);
+    gap: var(--crtr-chart-legend-item-gap, var(--crtr-space-1));
     min-width: 0;
   }
 
+  /* Sized against the legend's own text, not a spacing token doing a sizing job. One knob:
+     the swatch is a square, so its width and height are the same value. */
   [part="legend-swatch"] {
     flex: none;
-    width: calc(var(--crtr-space-2) - 1px);
-    height: calc(var(--crtr-space-2) - 1px);
-    border-radius: 2px;
+    width: var(--crtr-chart-legend-swatch-size, 0.75em);
+    height: var(--crtr-chart-legend-swatch-size, 0.75em);
+    border-radius: var(--crtr-chart-legend-swatch-radius, calc(var(--crtr-radius-small) * 0.5));
   }
 
   [part="legend-label"] {
@@ -74,51 +97,91 @@ const STYLE = `
 
   [part="chart"] {
     display: block;
+    height: var(--crtr-chart-plot-height, 260px);
     overflow: visible;
   }
 
+  /* Waiting for data and having none hold the same space, but each stays in its own scope:
+     one scope never names two different parts. */
   [part="empty"] {
     display: flex;
     align-items: center;
     justify-content: center;
-    padding: 0 var(--crtr-space-4);
-    color: var(--crtr-color-text-muted);
-    border: 1px dashed var(--crtr-color-border);
-    border-radius: var(--crtr-radius-medium);
+    padding: var(--crtr-chart-empty-padding, 0 var(--crtr-space-4));
+    color: var(--crtr-chart-empty-text-color, var(--crtr-color-text-muted));
+    font-size: var(--crtr-chart-empty-font-size, 0.875em);
+    border: var(--crtr-chart-empty-border-width, 1px)
+      var(--crtr-chart-empty-border-style, dashed)
+      var(--crtr-chart-empty-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-chart-empty-radius, var(--crtr-radius-medium));
   }
 
   [part="status"] {
     display: flex;
     align-items: center;
     justify-content: center;
-    padding: 0 var(--crtr-space-4);
-    color: var(--crtr-color-text-muted);
-    border: 1px dashed var(--crtr-color-border);
-    border-radius: var(--crtr-radius-medium);
+    padding: var(--crtr-chart-status-padding, 0 var(--crtr-space-4));
+    color: var(--crtr-chart-status-text-color, var(--crtr-color-text-muted));
+    font-size: var(--crtr-chart-status-font-size, 0.875em);
+    border: var(--crtr-chart-status-border-width, 1px)
+      var(--crtr-chart-status-border-style, dashed)
+      var(--crtr-chart-status-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-chart-status-radius, var(--crtr-radius-medium));
   }
 
+  /* Flat: this sits in the flow of the page. A shadow in this bundle means floating. */
   [part="unavailable"] {
-    padding: var(--crtr-space-3);
-    color: var(--crtr-color-text-muted);
-    background: var(--crtr-color-surface);
-    border: 1px solid var(--crtr-color-border);
-    border-radius: var(--crtr-radius-medium);
-    box-shadow: var(--crtr-shadow);
+    padding: var(--crtr-chart-unavailable-padding, var(--crtr-space-3));
+    color: var(--crtr-chart-unavailable-text-color, var(--crtr-color-text-muted));
+    background: var(--crtr-chart-unavailable-fill, var(--crtr-color-surface));
+    border: var(--crtr-chart-unavailable-border-width, 1px)
+      var(--crtr-chart-unavailable-border-style, solid)
+      var(--crtr-chart-unavailable-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-chart-unavailable-radius, var(--crtr-radius-medium));
   }
 
   [part="reason"] {
-    color: var(--crtr-color-text);
-    font-family: var(--crtr-font-mono);
+    color: var(--crtr-chart-reason-text-color, var(--crtr-color-text));
+    font-family: var(--crtr-chart-reason-font-family, var(--crtr-font-mono));
   }
 
   .grid {
-    stroke: var(--crtr-color-border);
-    stroke-width: 1;
+    stroke: var(--crtr-chart-grid-stroke-color, var(--crtr-color-border));
+    stroke-width: var(--crtr-chart-grid-stroke-width, 1);
+    opacity: var(--crtr-chart-grid-opacity, 0.45);
+  }
+
+  /* The gridline the marks are read against carries more weight than the rest. */
+  .grid.baseline {
+    opacity: var(--crtr-chart-grid-baseline-opacity, 0.9);
   }
 
   .tick {
-    fill: var(--crtr-color-text-muted);
-    font-size: calc(var(--crtr-font-size) * 0.72);
+    fill: var(--crtr-chart-tick-text-color, var(--crtr-color-text-muted));
+    font-size: var(--crtr-chart-tick-font-size, 0.75em);
+  }
+
+  /* Mark paint. Series colour arrives per node from the theme's chart ramp; everything
+     these marks are drawn WITH is a knob, which is why none of it is an SVG attribute. */
+  [part="line"] {
+    stroke-width: var(--crtr-chart-line-stroke-width, 2);
+    stroke-linecap: var(--crtr-chart-line-line-cap, round);
+    stroke-linejoin: var(--crtr-chart-line-line-join, round);
+  }
+
+  [part="area"] {
+    fill-opacity: var(--crtr-chart-area-fill-opacity, 0.18);
+  }
+
+  [part="point"] {
+    r: var(--crtr-chart-point-radius, 2.5);
+  }
+
+  /* A bar never rounds away more than a third of its own width, and --bar-max-radius is
+     that width — the one number here the stylesheet cannot know, so the plot writes it onto
+     the SVG and the knob is clamped against it. */
+  [part="bar"] {
+    rx: min(var(--crtr-chart-bar-radius, 2px), var(--bar-max-radius));
   }
 `;
 function normalizeConfig(raw) {
@@ -149,9 +212,6 @@ function normalizeConfig(raw) {
     if (raw.title !== undefined && typeof raw.title !== 'string') {
         return { status: 'invalid', reason: 'chart title is not a string' };
     }
-    if (raw.source !== undefined && typeof raw.source !== 'string') {
-        return { status: 'invalid', reason: 'chart source is not a string' };
-    }
     return {
         status: 'ok',
         config: {
@@ -160,7 +220,6 @@ function normalizeConfig(raw) {
             y,
             title: raw.title,
             data: raw.data,
-            source: raw.source,
         },
     };
 }
@@ -329,7 +388,7 @@ class CrtrChartElement extends HTMLElement {
         root.append(style, this.#container);
     }
     connectedCallback() {
-        const generation = ++this.#generation;
+        ++this.#generation;
         this.#config = null;
         this.#rows = null;
         const read = readSlotConfig(this);
@@ -345,45 +404,19 @@ class CrtrChartElement extends HTMLElement {
         this.#config = normalized.config;
         this.#renderFrame();
         this.#observe();
-        const { data, source } = normalized.config;
-        if (data !== undefined) {
-            if (!isRows(data)) {
-                this.#renderUnavailable('chart data is not a list of rows');
-                return;
-            }
-            this.#rows = data;
-            this.#renderPlot();
+        const { data } = normalized.config;
+        if (data !== undefined && !isRows(data)) {
+            this.#renderUnavailable('chart data is not a list of rows');
             return;
         }
-        if (source === undefined || source === '') {
-            this.#rows = [];
-            this.#renderPlot();
-            return;
-        }
-        this.#renderStatus('Loading chart data…');
-        void this.#resolveSource(source, generation);
+        this.#rows = data ?? [];
+        this.#renderPlot();
     }
     disconnectedCallback() {
         this.#generation += 1;
         this.#observer?.disconnect();
         this.#observer = null;
     }
-    /** The host bridge resolves `source`; this element never touches the network. */
-    async #resolveSource(source, generation) {
-        const result = await artifactData(source);
-        if (generation !== this.#generation)
-            return;
-        if (result.status !== 'ok') {
-            this.#renderUnavailable(`chart source "${source}" is ${result.status}: ${result.reason}`);
-            return;
-        }
-        if (!isRows(result.data)) {
-            this.#renderUnavailable(`chart source "${source}" is not a list of rows`);
-            return;
-        }
-        this.#rows = result.data;
-        this.#renderPlot();
-    }
     #observe() {
         this.#observer?.disconnect();
         this.#width = this.#plot.getBoundingClientRect().width;
@@ -409,16 +442,7 @@ class CrtrChartElement extends HTMLElement {
         box.append('Chart unavailable: ', detail);
         this.#container.replaceChildren(box);
     }
-    /** Holds the plot's height while a source resolves, so the page does not jump. */
-    #renderStatus(text) {
-        const box = document.createElement('div');
-        box.part.add('status');
-        box.setAttribute('role', 'status');
-        box.style.height = `${HEIGHT}px`;
-        box.textContent = text;
-        this.#plot.replaceChildren(box);
-    }
-    /** Title and legend come from the config alone, so they survive a pending source. */
+    /** Title and legend come from the config alone. */
     #renderFrame() {
         const config = this.#config;
         if (config === null)
@@ -495,7 +519,7 @@ class CrtrChartElement extends HTMLElement {
         if (plotted === 0 || rows.length === 0) {
             const empty = document.createElement('div');
             empty.part.add('empty');
-            empty.style.height = `${HEIGHT}px`;
+            empty.style.height = 'var(--crtr-chart-plot-height, 260px)';
             empty.textContent = 'No data to chart';
             this.#plot.replaceChildren(empty);
             return;
@@ -505,7 +529,7 @@ class CrtrChartElement extends HTMLElement {
             // First paint, before the container has been measured: hold the height so
             // the surrounding document does not reflow when the SVG arrives.
             const spacer = document.createElement('div');
-            spacer.style.height = `${HEIGHT}px`;
+            spacer.style.height = 'var(--crtr-chart-plot-height, 260px)';
             this.#plot.replaceChildren(spacer);
             return;
         }
@@ -527,13 +551,12 @@ class CrtrChartElement extends HTMLElement {
         svg.setAttribute('aria-label', `${config.kind} chart of ${series.map((entry) => entry.label).join(', ')} by ${titleCaseHeader(config.x)}`);
         ticks.forEach((tick, tickIndex) => {
             const line = svgNode('line');
-            line.setAttribute('class', 'grid');
+            line.setAttribute('class', tick === baselineValue ? 'grid baseline' : 'grid');
             setAttributes(line, {
                 x1: marginLeft,
                 x2: marginLeft + plotWidth,
                 y1: yOf(tick),
                 y2: yOf(tick),
-                opacity: tick === baselineValue ? 0.9 : 0.45,
             });
             const label = svgNode('text');
             label.setAttribute('class', 'tick');
@@ -582,6 +605,7 @@ class CrtrChartElement extends HTMLElement {
             const groupWidth = band * 0.72;
             const slot = groupWidth / series.length;
             const barWidth = Math.max(1, slot - (slot > 4 ? 1 : 0));
+            svg.style.setProperty('--bar-max-radius', `${barWidth / 3}px`);
             series.forEach((entry, seriesIndex) => {
                 const group = svgNode('g');
                 for (const point of entry.points) {
@@ -592,7 +616,6 @@ class CrtrChartElement extends HTMLElement {
                         y: Math.min(y, baselineY),
                         width: barWidth,
                         height: Math.max(1, Math.abs(baselineY - y)),
-                        rx: Math.min(2, barWidth / 3),
                     });
                     bar.style.fill = entry.color;
                     bar.append(tooltip(`${entry.label} · ${categories[point.index] ?? point.index}: ${formatExact(point.value)}`));
@@ -614,26 +637,19 @@ class CrtrChartElement extends HTMLElement {
                         const area = svgNode('path', 'area');
                         setAttributes(area, {
                             d: `M ${xOf(first.index)},${baselineY} L ${trace} L ${xOf(last.index)},${baselineY} Z`,
-                            'fill-opacity': 0.18,
                         });
                         area.style.fill = entry.color;
                         group.append(area);
                     }
                     const line = svgNode('path', 'line');
-                    setAttributes(line, {
-                        d: `M ${trace}`,
-                        fill: 'none',
-                        'stroke-width': 2,
-                        'stroke-linecap': 'round',
-                        'stroke-linejoin': 'round',
-                    });
+                    setAttributes(line, { d: `M ${trace}`, fill: 'none' });
                     line.style.stroke = entry.color;
                     group.append(line);
                     if (!showDots && segment.length > 1)
                         continue;
                     for (const point of segment) {
                         const dot = svgNode('circle', 'point');
-                        setAttributes(dot, { cx: xOf(point.index), cy: yOf(point.value), r: 2.5 });
+                        setAttributes(dot, { cx: xOf(point.index), cy: yOf(point.value) });
                         dot.style.fill = entry.color;
                         dot.append(tooltip(`${entry.label} · ${categories[point.index] ?? point.index}: ${formatExact(point.value)}`));
                         group.append(dot);

package/dist/pages/elements/options.d.ts

@@ -17,5 +17,14 @@
  * Selection is kept in the agent's authored order, never click order, so the response reads
  * the way the question did. `freetext` is absent rather than empty: the response says whether
  * the user wrote something, not whether the box existed.
+ *
+ * Every styling value this element paints is read through a `--crtr-options-*` component
+ * token, so a host restyles the question without touching crtr. Paint that the bundle shares —
+ * the option controls, the two writing boxes, the focus ring on every button — chains through
+ * the `--crtr-control-*` family behind its element token, which is what keeps a comment box
+ * here identical to one in `<crtr-text>` unless a host deliberately parts them. Each anatomy
+ * part carries its own scope: the option row and the control inside it, the comment trigger
+ * and the box it opens, and the two buttons in that box are five things a person can point at,
+ * so they are five scopes rather than one shared name meaning two different rectangles.
  */
 export {};