diff --git a/apps/docs/content/docs/reference/manifest.mdx b/apps/docs/content/docs/reference/manifest.mdx index af9896a..27222cf 100644 --- a/apps/docs/content/docs/reference/manifest.mdx +++ b/apps/docs/content/docs/reference/manifest.mdx @@ -100,13 +100,11 @@ A **group** is `{ id, title?, islands }`: a string `id`, an optional `title`, an A page's optional `filters` declare shared controls in the page header. Each filter's `bind` maps each affected dataset to the column the filter applies to; islands whose `dataset` appears in `bind` re-query when the filter changes, and the rest ignore it. Two kinds are supported: a -`daterange` over a date column, and a `select` that narrows a categorical column. A `daterange` -may set a `default` initial period (resolved live against today) applied when the URL sets no -range; without it the page opens to all-time. +`daterange` over a date column, and a `select` that narrows a categorical column. ```jsonc title="manifest.json" "filters": [ - { "id": "period", "type": "daterange", "label": "Period", "default": "last-90-days", + { "id": "period", "type": "daterange", "label": "Period", "bind": { "net_worth": "month", "transactions": "ts" } }, { "id": "team", "type": "select", "label": "Team", "multiple": true, "bind": { "services": "owner" } } @@ -119,7 +117,6 @@ range; without it the page opens to all-time. | `type` | `string` | yes | The filter kind: `daterange` or `select`. | | `label` | `string` | no | Label shown on the control. | | `bind` | `object` | yes | A map of dataset name to the column the filter applies to. Each column is validated against the live data. | -| `default` | `string` | no | `daterange` only: initial period when the URL sets no range, resolved live against today. One of `today`, `last-7-days`, `last-30-days`, `last-90-days`, `this-month`, `last-month`. Omitted means all-time. | | `multiple` | `boolean` | no | `select` only: allow several values (`IN`); default single (`=`). | | `options` | `array of string` | no | `select` only: explicit choices; when omitted, the bound column's live distinct values are used. | @@ -190,7 +187,6 @@ points at. | `groupBy` | `array of string` | no | Columns to group by, for aggregate `select` entries. | | `orderBy` | `array of object` | no | Sort keys, each `{ field, dir? }` where `dir` is `asc` / `desc` (default `asc`). | | `limit` | `number` | no | Max rows returned. | -| `search` | `object` | no | Make the query a relevance-ranked full-text search over text columns (see query search). | | `params` | `object` | no | A map of parameter name to a parameter declaration (see query params). | | `description` | `string` | no | Free-form note describing the query. | @@ -213,19 +209,6 @@ declared param) or `value` (a literal). The ops are `eq`, `ne`, `lt`, `lte`, `gt date), and `in` (a literal `value` array). A filter bound to an **optional** param the caller omits is dropped, so the query runs without it. -A **query search** (`search`) turns the query into a relevance-ranked full-text (BM25) -search over text columns, distinct from a `contains` filter's unranked substring match. -It requires a `source` dataset (not a `sql` transform). An omitted `orderBy` ranks by -relevance; an explicit `orderBy` overrides it. - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `fields` | `array of string` | yes | Text columns to index and search across; each must be a real column of the dataset. | -| `param` | `string` | yes | Name of a declared `string` param holding the search term. | -| `stemmer` | `"porter" \| "none"` | no | Token stemmer. `porter` (default) folds plurals / tenses; `none` matches exact tokens. | -| `stopwords` | `"english" \| "none"` | no | Drop common words from the index and term. `english` (default) drops them; `none` keeps them. | -| `scoreField` | `string` | no | Name a column to expose the BM25 score under; omit to keep the score internal. | - ## Connectors A **connector** is a vendored integration that syncs a provider's data into `source` @@ -287,7 +270,7 @@ A single headline number, optionally with a delta vs the previous row or a targe | `compareTo` | `string` | no | 'prev', 'none', or a field name | | `target` | `string` | no | field holding a target to compare against | | `unit` | `string` | no | | -| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. See the Value formats reference (/reference/value-formats). | +| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. For any other ISO 4217 currency use 'currency:\' (e.g. currency:RSD). See the Value formats reference (/reference/value-formats). | | `color` | `string` | no | 6-digit hex color (e.g. "#22C55E") for the sparkline, overriding the default palette | ### `metric.scorecard` @@ -359,7 +342,7 @@ A dual-axis chart: bars on the primary axis, lines on a secondary axis — use t | `stacked` | `boolean` | no | stack the bar series into one bar per category | | `colors` | `array of string` | no | CSS colors per series (bars first, then lines), overriding the default palette | | `format` | [`value format`](/reference/value-formats) | no | format for the primary (bar) y-axis | -| `lineFormat` | `"usd" \| "eur" \| "gbp" \| "jpy" \| "int" \| "decimal" \| "pct" \| "compact" \| "kg" \| "bytes" \| "duration" \| "date" \| "datetime" \| "time" \| "month"` | no | format for the secondary (line) y-axis | +| `lineFormat` | `"usd" \| "eur" \| "gbp" \| "jpy" \| "int" \| "decimal" \| "pct" \| "compact" \| "kg" \| "bytes" \| "duration" \| "date" \| "datetime" \| "time" \| "month" \| string` | no | format for the secondary (line) y-axis | ### `waterfall.bars` @@ -377,7 +360,7 @@ A waterfall / bridge chart — use for a P&L walk or variance: an opening anchor | `value` | `string` | yes | signed delta per step; for a total/anchor row, its absolute level | | `kind` | `string` | no | field marking anchor rows: a row whose value here is "total" draws as an absolute bar from zero (opening/closing/subtotal). Omit to make every row a delta. | | `colors` | `object` | no | CSS colors per tone, overriding the defaults (increase green, decrease red, total neutral) | -| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. See the Value formats reference (/reference/value-formats). | +| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. For any other ISO 4217 currency use 'currency:\' (e.g. currency:RSD). See the Value formats reference (/reference/value-formats). | ### `breakdown.treemap` @@ -412,7 +395,7 @@ A matrix heatmap — use to show one value across two categorical dimensions (x | `y` | `string` | yes | row-category field (y axis) | | `value` | `string` | yes | numeric field mapped to each cell's color | | `colors` | `array of string` | no | gradient color stops for the scale, overriding the default | -| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. See the Value formats reference (/reference/value-formats). | +| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. For any other ISO 4217 currency use 'currency:\' (e.g. currency:RSD). See the Value formats reference (/reference/value-formats). | ### `activity.calendar` @@ -429,7 +412,7 @@ A calendar heatmap — use to show a daily value over weeks and months, GitHub-c | `date` | `string` | yes | date field — any parseable date or timestamp | | `value` | `string` | yes | numeric field mapped to the day's color intensity | | `colors` | `array of string` | no | gradient color stops, overriding the default | -| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. See the Value formats reference (/reference/value-formats). | +| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. For any other ISO 4217 currency use 'currency:\' (e.g. currency:RSD). See the Value formats reference (/reference/value-formats). | ### `funnel.steps` @@ -447,7 +430,7 @@ A funnel of sequential stages — use for conversion or drop-off; each stage's w | `value` | `string` | yes | numeric field — the count at each stage | | `sort` | `"none" \| "ascending" \| "descending"` | no | funnel ordering; 'none' keeps the declared row order | | `colors` | `array of string` | no | CSS colors per stage, overriding the default palette | -| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. See the Value formats reference (/reference/value-formats). | +| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. For any other ISO 4217 currency use 'currency:\' (e.g. currency:RSD). See the Value formats reference (/reference/value-formats). | ### `rank.list` @@ -467,7 +450,7 @@ A ranked Top-N list with proportional bars — use for leaderboards: top product | `sort` | `"descending" \| "ascending"` | no | rank order by value | | `secondary` | `string` | no | optional field shown beside each row's value | | `color` | `string` | no | CSS color for the bars, overriding the default accent | -| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. See the Value formats reference (/reference/value-formats). | +| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. For any other ISO 4217 currency use 'currency:\' (e.g. currency:RSD). See the Value formats reference (/reference/value-formats). | ### `compare.radar` @@ -485,7 +468,7 @@ A radar (spider) chart — use to compare entities across several metrics at onc | `series` | `string` | no | field naming each polygon (one per row); omitted numbers them Series 1, 2, … | | `max` | `number` | no | fixed max for every axis; omitted maxes each axis at its metric's peak | | `colors` | `array of string` | no | CSS colors per polygon, overriding the default palette | -| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. See the Value formats reference (/reference/value-formats). | +| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. For any other ISO 4217 currency use 'currency:\' (e.g. currency:RSD). See the Value formats reference (/reference/value-formats). | ### `map.choropleth` @@ -503,7 +486,7 @@ A geographic choropleth — use to shade regions (world countries) by a value; r | `value` | `string` | yes | numeric field mapped to each region's color | | `map` | `string` | no | the registered map name | | `colors` | `array of string` | no | gradient color stops, overriding the default | -| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. See the Value formats reference (/reference/value-formats). | +| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. For any other ISO 4217 currency use 'currency:\' (e.g. currency:RSD). See the Value formats reference (/reference/value-formats). | ### `correlation.scatter` @@ -542,7 +525,7 @@ A pie or donut chart of part-to-whole composition — use for one series' share | `value` | `string` | yes | numeric field sizing each slice | | `donut` | `boolean` | no | render with an inner radius (a donut hole) | | `colors` | `array of string` | no | CSS colors per slice (in descending-value order), overriding the default palette | -| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. See the Value formats reference (/reference/value-formats). | +| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. For any other ISO 4217 currency use 'currency:\' (e.g. currency:RSD). See the Value formats reference (/reference/value-formats). | ### `table.grid` @@ -645,7 +628,7 @@ A responsive grid of state tiles — use for service/check health on ops & statu | `label` | `string` | yes | field naming each entity (service, check, host) | | `state` | `string` | yes | field holding each entity's status value | | `value` | `string` | no | optional metric shown under the label | -| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. See the Value formats reference (/reference/value-formats). | +| `format` | [`value format`](/reference/value-formats) | no | Display format for a value. Currency: usd, eur, gbp, jpy. Number: int, decimal, pct (a 0–1 fraction shown as a %), compact (1.2K). Unit: kg, bytes (1024-scale), duration (a number of seconds → 1h 5m). Date/time: date, datetime, time, month. Omit for a plain number with up to 2 decimals. For any other ISO 4217 currency use 'currency:\' (e.g. currency:RSD). See the Value formats reference (/reference/value-formats). | | `tones` | `object` | no | map a state value to a tone; unmapped values fall back to a keyword convention (up/ok/healthy/online → success, warn/degraded/pending → warning, down/error/critical/fail → danger, else neutral) | ### `search.box` @@ -717,7 +700,7 @@ A full-page content workspace — browse and edit a directory of markdown files ### `form.entry` -A data-entry form card bound to a manifest `action` — renders one typed input per action field, with a submit button in the bottom-right that inserts a row; the bound dataset's islands then refresh live. The human-facing mirror of the agent's run_action: it reuses the action's typing and so binds no dataset of its own. +A data-entry form card bound to a manifest `action` — renders one typed input per action field, with a submit button in the bottom-right that inserts a row; the bound dataset's islands then refresh live. The human-facing mirror of the agent's runActions insert: it reuses the action's typing and so binds no dataset of its own. **Span:** min 3, recommended 5, max 8 (of 12). Omit `span` to render at the recommended width; below min or above max is a named error. diff --git a/apps/docs/scripts/gen-reference.ts b/apps/docs/scripts/gen-reference.ts index 038b1b9..96639ea 100644 --- a/apps/docs/scripts/gen-reference.ts +++ b/apps/docs/scripts/gen-reference.ts @@ -111,9 +111,13 @@ function fieldRows(schema: JsonSchemaNode): FieldRow[] { // --- MDX assembly --------------------------------------------------------------- -/** Escape a pipe so it can't break a Markdown table cell. */ +/** + * Escape a pipe (breaks the Markdown table) and MDX's JSX/expression openers + * `<` `{` (which would parse description prose like `currency:` as a tag). + * Type cells pass through too, but `renderType` never emits these characters. + */ function cell(text: string): string { - return text.replace(/\|/g, "\\|"); + return text.replace(/[|<{]/g, "\\$&"); } function fieldTable(rows: FieldRow[]): string {