malloy-dashboards · diff
git:20261008.6972bba to git:20261012.55216ae
9 added, 487 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: malloy-dashboards
- description: "Build or modify a Malloy Publisher dashboard, a tagged .malloy file in a package's dashboards/ directory, with auto-rendered filter controls, a grid layout, and # drill click-through. Use when the user asks for a dashboard, a filterable operational view, or drill-through between views, and no code is wanted."
+ description: "Renamed to malloy-reports. A dashboard is now a report with layout=grid: a .malloy file with an ## artifact tag, written at the package root. Load malloy-reports instead when the user asks for a dashboard, a filterable view, or drill-through between views."
---
<!--
Copyright (c) Credible Data Inc.
SPDX-License-Identifier: MIT
-->
- # Publisher Dashboards
-
- > A `dashboards/*.malloy` file **is** a dashboard. It imports the model, names the views to show in `## artifact { tiles=[…] }`, applies the filtering on those views, and tags the layout. Publisher discovers it at package load, renders the filter controls from the givens it references, offers `# drill` click-through between pages, and serves it at `/<env>/<pkg>/dashboards/<name>`. No code, no build step.
-
- ## When this is the right tool
-
- | The user wants | Use |
- | ---------------------------------------------------- | ------------------------------------------------ |
- | A recurring, at-a-glance view behind shared filters | this skill (a dashboard) |
- | A narrative, with prose between the numbers | a notebook (`skill:malloy-notebooks`) |
- | Custom design, branding, or interactions beyond tags | an HTML data app |
- | The model itself: sources, measures, joins | `malloy-model` |
-
- Notebooks and dashboards run the same engine, so **interactivity is not the axis**: both get filter
- controls, URL-addressable state, Apply batching, and `# drill`. Pick on the shape of the document.
- Scanned at a glance is a dashboard; read top to bottom is a notebook.
-
- ## Build sequence
-
- Tool names below are bare (`get_context`, `compile_model`, `reload_package`). Match each against the
- tools you actually have: a host may prefix or rename them. Where none matches, use the REST
- endpoint named beside it.
-
- 1. **READ THE MODEL FIRST.** Get the real source, view, dimension, and given names from the package:
- `get_context` if you have it, otherwise the REST model endpoint for `index.malloy` (it answers
- 404 for a file off the surface) or the `.malloy` files.
- Never guess a name. A guessed field in a query fails the whole package load, not just that one
- dashboard; a guessed tile or suggest source is quieter, and only shows up in the package warnings.
- If the package root holds an `index.malloy` (every scaffolded package does), a tile reads only the
- sources that file exports. A source the dashboard file declares on top of an exported one works;
- one on top of a hidden source does not. See "Read the lint" for the warning you get otherwise.
- 2. **PICK THE VIEWS TO SHOW.** A dashboard is `## artifact { tiles=[…] }` naming existing views, so
- this is the design step: which views, how wide each sits, what each is called.
- 3. **DECLARE THE GIVENS** the dashboard will filter by, in the dashboard file itself, with their
- control tags: see "Filter controls" below for the syntax and what each tag renders as. That is
- the convention because the dashboard builder edits the dashboard file and nothing else, so a
- filter it can add, change or remove is a declaration in that file. Bind them on the tiles (step
- 4). A given the model already declares and reads is not declared again: import it by name, and
- the builder can bind it but not edit it. See "Givens that stay in the model".
- 4. **COMPOSE THE FILE** for `dashboards/`, following the template below, but do not save it yet.
- Name the sources you need: `import { order_items, products } from '../storefront.malloy'`.
- Each tile binds its controls with a refinement, `view: t is v + { where: category ~ $CATEGORY }`,
- one clause per given it answers to; a `filter<...>` binds with `~`, a plain `date` or `number`
- given is a value and binds with `>=`, `<=` or `=`. Only the givens some tile references become
- controls, so a declaration nothing binds shows nothing. Then import every
- source or query any referenced given names in a `suggest`. Both are per-file, and getting the
- suggest wrong does not error: the control still looks like a picker but has no options, and says
- so underneath, "Could not load the options for this control". The package warnings name it too. **A `suggest` naming a `query=` needs that
- query's own source imported as well**, because an import is not transitive: the query resolves by
- name, so the file compiles and the package loads, but running the picker fails with
- `Undefined source '<name>'`. The package warnings name this one too, saying which source to
- import. Import the source that suggest query reads, not just the query.
- 5. **COMPILE IT** with your compile tool (`POST …/models/<path>/compile` over REST), against the source text,
- before you save, at the path the file will have. **Editing one that already exists needs
- `"scope": "file"`**, which compiles your source AS that file; the default appends it instead, so
- every imported name and the query name collide with the saved copy and you get a wall of
- already-defined errors that reads as broken Malloy rather than a wrong scope. **Editing a shared
- include wants `"scope": "package"`**, which recompiles every file as saved: `file` only checks the
- one you are editing, so renaming a source in `_shared.malloy` passes it while breaking every
- dashboard that imports it. **`"scope": "file"` does not check tiles, drills or suggest queries.**
- To see those before you save, compile the same text at `"scope": "package"` with `modelPath` set
- to the dashboard's path: it runs the lint step 6 reads and returns its findings with code
- `dashboard-lint` (or `render-tag`), each at the severity a load gives it, so an error finding
- makes the compile an error too. Even that is not a working dashboard: some mistakes only show when
- you look at the page in step 7. **A not-yet-saved dashboard wants
- `"scope": "file"` too**, not the default: a dashboard file opens with an `import`, and the
- default `append` scope refuses one, so the new-file case fails on the import and again on the
- path that does not exist yet. `append` is for a fragment checked against a model that is
- already on disk, which a dashboard file is not.
- 6. **SAVE IT, RELOAD, AND READ THE MANIFEST AND THE WARNINGS.** Your reload tool, or
- `GET …/packages/<pkg>?reload=true` over REST. Check the status the reload returns as well as the warnings:
- a 424 means the package did not load and your edit is not live. **The `warnings` key is absent
- when there are none**, so an empty response is the pass, not a sign you are reading the wrong
- field. Then read `GET …/packages/<pkg>/dashboards/<name>`: its `givens` are exactly the controls
- that will render, which catches a given you imported but never referenced before you open the page,
- and its `query` is the name to run in step 7. See "Read the lint" below.
- 7. **OPEN IT AND LOOK.** Not optional; see "What 'done' means".
-
- ## The form
-
- A dashboard is `## artifact { tiles=[…] }` at model level: named views, each run as its own query, laid
- out by Publisher into the grid `# dashboard { columns=N }` names.
-
- ```malloy
- ##! experimental.givens
- ## artifact { title="Storefront overview" tiles=["overview -> kpis", "overview -> revenue_trend", "overview -> revenue_by_state"] } dashboard { columns=12 }
- import { order_items, products } from '../storefront.malloy'
-
- // The controls, declared here: the tags are each one's control contract.
- # label="Category" control=select suggest { source=products dimension=category }
- given: CATEGORY :: filter<string> is f''
- # label="Ordered since"
- given: SINCE :: date is @2023-01-01
-
- // Layout goes on the VIEW, and a thin re-declaration is the place to put it: the
- // modelled view keeps its chart tag, this decides how wide it sits here, and the
- // `+ { where: ... }` says which controls the tile answers to.
- source: overview is order_items extend {
- # colspan=12
- # label="Key figures"
- # big_value
- view: kpis is key_figures + { where: category ~ $CATEGORY, where: created_at >= $SINCE }
-
- # colspan=8
- # break
- # label="Revenue by month"
- view: revenue_trend is sales_by_month + { where: category ~ $CATEGORY, where: created_at >= $SINCE }
-
- # colspan=4
- # label="Revenue by state"
- view: revenue_by_state is sales_by_state + { where: category ~ $CATEGORY, where: created_at >= $SINCE }
- }
- ```
-
- Model-level because there is no query of its own to hang a `#` tag on, and model-level for a second
- reason: tiles run as separate queries, which is the only way a page can span unrelated sources. A
- nest's pipeline starts from its own query's source and there is no way to combine two.
-
- Three things the form costs, so you are not surprised by them:
-
- - **A tile expression is a string in an annotation, so the Malloy compiler never checks it.** Rename
- a view and the file still compiles; the tile fails at package load. The lint names it: at step 6,
- or before saving with `compile_model` at `"scope": "package"` (step 5).
- - **No per-parent-row grouping.** There is no parent query to repeat a grid over.
- - **Filtering lives on the tiles**, not on the page: each view's `+ { where: ... }` names the
- controls it answers to. Below is why, and the one thing that does not work.
-
- ### Text tiles: prose between tiles
-
- Prose between tiles is a named `(markdown)` block that `tiles=` lists with `kind=text`; it renders as a tile of its own, and its body is markdown:
-
- ```malloy
- ## artifact { title="Storefront overview" tiles=[intro { kind=text colspan=6 break }, "overview -> kpis"] } dashboard { columns=12 }
- ##|(markdown) intro
- ## How to read this page
- |##
- ```
-
- The entry is `name { kind=text colspan=6 break }`: `colspan` and `break` lay it out like a query tile, and nothing else on the entry is read. The name is one bare word on the opener line, the body starts on the next line, and the `|##` closer sits at the opener's column. A heading goes inside the block, because a bare `## Heading` line is a model tag. Keep the parentheses: `##|markdown` draws a malformed-route warning. The lint reports an entry with no block, a block written twice, and a `(markdown)` block that no `tiles` entry names, so delete the last rather than leave it. The dashboard's own description is separate: the unnamed `"` notes above `## artifact`. Earlier spellings are still read: `##|(text) name` is a text tile, like `##|(markdown) name`. Write `(markdown)`.
-
- In the API a text tile has `kind: "text"`, a `name` and `markdown`, and no `query`; code that runs a dashboard's tiles skips it.
-
- ### Legacy: `# artifact` on a `query:`
-
- An older package may carry a single query tagged `# artifact` whose result is the whole page, laid out
- by `@malloydata/render` from the query's own `# dashboard` tag. It still renders. **Do not author a new
- one**, and do not convert an existing one unless asked: edit it minimally, and when it has to change
- shape, rewrite it as `tiles=[…]`. It cannot span sources, and a guessed field inside it fails the whole
- package load, where a bad tile in `tiles=[…]` fails alone, in its own cell. "Legacy single-query pages"
- near the end covers the few traps it has.
-
- ### Where the filtering goes
-
- A dashboard has no query, so its filtering lives on the views it names: a `+ { where: field ~ $GIVEN }`
- refinement on each tile, one clause per control the tile answers to. A tile without the clause does
- not move when the control does, which is how a page keeps one tile fixed while the rest filter. The
- givens those clauses read are declared in the same file (step 3).
-
- **Binding is per declaration, not per name.** Measured: a dashboard declaring its own `CATEGORY`
- over a source whose model-level `where:` reads the model's `CATEGORY` compiles, shows the control,
- and filters nothing when it moves, because the two declarations only share a name. So do not mix
- the two designs on one given. The other design still works on its own: a source with the givens
- already applied in an untagged `dashboards/_shared.malloy`, reading `import '../givens.malloy'`,
- which discovery treats as a shared include rather than a dashboard. Then the dashboard imports both
- and the controls render for the givens its tiles reach. A given the dashboard imports but nothing
- references gets no control, silently, at reload 200 with no warning. Save the include before you
- compile the dashboard that imports it, since an importer compiled against a sibling that is not on
- disk fails with an `import-error`. The builder can bind such a control but not add, change or
- remove it, since it never edits imports or model files.
-
- Note `SINCE` is a `date` rather than a `filter<>`, so it compares with `>=` rather than `~`.
-
- ### Givens that stay in the model
-
- A given stays in the model, declared once there, when any of these reads it: a model source, view or
- measure; an `#(authorize)` or `#(access_filter)` gate; or an HTML data app. The dashboard imports it by
- name (`import { CATEGORY } from '../givens.malloy'`) and never re-declares it. Getting this wrong fails
- in two different ways:
-
- - **Import a name and also declare it: a compile error** naming the clash. Drop the local declaration.
- - **Declare a name the model already reads, without importing it: no error at all.** The dashboard now
- has a second given that shares only the name. Its control renders and moves, and the model's own
- `where:` or gate never sees the value, so the filtering silently does nothing.
-
- Declare locally only what no model code reads: a control that exists for this page's tiles. A drill
- into this page seeds a given by name, so the page declares that same name as `filter<T>`, with the
- type the clicked value fits (`filter<string>` for a category).
-
- A composite declares in its own file any source it scopes itself, such as
- `source: overview is order_items extend { … }` above, so the givens its tiles bind are in the same file
- that binds them.
-
- **`# dashboard { columns=N }` is the spelling of the grid width**, beside the artifact tag. `dashboard_columns=N` inside the artifact tag is a deprecated alias: it is read when
- `columns` is absent and draws a warning, and when the two disagree it is an error naming both values.
- Any other property inside the artifact tag that Publisher does not read is a package warning naming it.
-
- A tile keeps its view's own field names on axes and column headers. `# label` titles the tile; to label
- what is inside it, label the fields in the view.
-
- ## Layout: the four tags that make a page line up
-
- Cards and tiles share one grid. Publisher reads these tags off the view each tile in `tiles=[…]`
- names. Copy this recipe and use the same count on every dashboard in the package so they read as
- one product:
-
- 1. **`columns=12`** on the `# dashboard` tag. Twelve divides by 2, 3, 4 and 6, so a row is even with
- three cards or four.
- 2. **A `# colspan` on every card and tile, summing to 12 per row.** Four cards at 3, three at 4, two
- tiles at 6, a full-width table at 12. Omit them and every item falls to a single column, a twelfth
- of the width, which is too narrow for a line chart to draw in at all. A colspan wider than
- `columns` is clamped, and the package warnings say so.
- 3. **`# break` on the first tile after the cards.** Otherwise it flows into the columns left beside
- the cards and the next tile wraps. Not needed per row: once a row sums to 12 the next item wraps
- on its own.
- 4. **`# label="..."` on every tile view and aggregate**, including the aggregates inside a table
- view, whose column headers are field names too. The heading is otherwise derived from the view's or
- field's name, and a wide table full of `total_sales` and `order_item_count` is the most visible
- thing between a rough page and a finished one. A view referenced **by name** is the exception: you
- can label the tile, but its own field names still reach the chart axes and the column headers, so
- label the fields in the view if you want those too.
-
- On a dashboard, all four go on the view a tile names, which is why a thin re-declaration
- (`view: revenue_trend is sales_by_month`) is the place to put them: the modelled view stays reusable
- and each page decides its own widths. `# subtitle="..."` and `# borderless` go there too and are the
- rest of the set; a tile reads all five.
-
- **Do not forget `columns=` itself.** Without it the grid falls back to a narrow default and every
- colspan is clamped to it, which is the usual reason a page you laid out comes out one item per row, and
- the package warnings name it.
-
- Then the traps:
-
- - **A KPI row is a view of only measures.** A tile is one whole result, so a tile that comes back as
- one row of measures renders as big-value cards on its own (`# big_value` on the view says so
- explicitly; `# table` opts out).
- - **No `# size=fill` on a dashboard tile.** Inside a dashboard it measures against the container the
- whole grid was handed, not the tile, so it yields a chart thousands of pixels tall. Tiles already
- size to their colspan.
- - **A table tile sitting in the left part of a wide card with the rest blank** is not filled by the
- dashboard. `# table { size=fill }` on the view forces it. That is the table's own tag, and it is a
- different thing from the `# size=fill` above, which is the chart one this page warns against.
- - **A KPI card's label is one line that ellipses** rather than wrapping, so a long label in a narrow
- card is truncated with no other sign. Widen the card or shorten the label.
- - **A ratio needs a number format.** `order_count / customer_count` renders as `10.695` on a card;
- `# number="#,##0.0"` is the precision it actually carries.
- - **A `# shape_map` legend is titled with the measure's field _name_, not its `# label`.** Rename it
- in the view: `aggregate: revenue is total_sales`. Renaming drops the measure's own format tags
- though, so `# currency` becomes plain digits unless you re-tag it at the rename. Prefer `# label=`
- anywhere the legend is not the problem.
- - **A series legend sizes itself from the longer of the series label and its widest value**, then
- truncates both. A 4-character label over 4-digit years clips to `20…`; `# label="Order year"`
- instead of `"Year"` buys the room. A legend showing `…` is this, not a data problem.
-
- The last two are upstream renderer behavior, cheap to work around in the model.
-
- Height is the one thing the surface decides: a dashboard's tiles are each capped, and in a notebook a
- chart cell is capped and a table cell hugs its rows.
-
- ## The rules that actually bite
-
- - **The filename is the dashboard's name:** its URL slug, its listing name, and its `# drill`
- target. The query inside can be called anything, and sometimes must be (a query named `regions`
- collides with an imported `regions` source).
- - **A given has to be in the dashboard file's scope to be bindable**: declared there (the
- convention) or imported. Malloy's given namespace is per-file. A given the file cannot see gets
- no control and cannot be sent to it, even when a `where:` that references it lives up an import
- chain. And a given declared here does not drive a `where:` in the model: bind on the tiles.
- - **A suggest's source or query has to resolve in the dashboard file too.** `suggest { source=products … }`
- means the dashboard imports `products`.
- - **A model-level `##` tag must be on one line.** Wrapping one always breaks it, but how you find
- out depends on what follows. If the continuation is not valid Malloy you get a compile error. If it
- happens to be, an `import` say, the file compiles clean, quietly stops being a dashboard and
- becomes a shared include, and only the package warnings tell you. Match on the shape rather than the
- words: the message may say a tag "does not parse", or was "refused" or "dropped rather than parsed",
- and on a file that still built it opens "Annotation" rather than "Tag". See "Legacy single-query pages" below.
- - **Only table cells are marked drillable.** See "Drill".
-
- `skill:malloy-charts` covers the renderer tags and choosing them.
-
- ## Filter controls
-
- Controls come from the `given:` declarations the tiles reference. Declare the new ones in the
- dashboard file, which is what the builder edits; a given the model already declares is imported by name
- and gets the same control, which the builder can bind but not edit.
- The tags on the declaration are the control contract:
-
- ```malloy
- ##! experimental.givens
-
- # label="Category" control=select suggest { source=products dimension=category }
- given: CATEGORY :: filter<string> is f''
-
- # label="Brand" control=multiselect suggest { query=brand_suggest dimension=brand }
- given: BRAND :: filter<string> is f''
-
- # label="Minimum line total" range_min=0 range_max=250
- given: MIN_SALE :: filter<number> is f''
-
- # label="Ordered since"
- given: SINCE :: date is @2023-01-01
- ```
-
- A sixth tag, `description`, is part of the contract and has two spellings that do different things:
- `# description="…"` publishes to the API but Publisher's own UI does not render it, while
- `#(description="…")` renders as helper text under the control but complains about any multi-word
- value, that the prefix "is not a well-formed route", because a route ends at the first space. That
- complaint is a **compile** diagnostic on a compile that still succeeds, not a package warning, so
- step 6 will not show it. Pick by which reader you care about.
-
- `dimension=` can name a field of a directly joined source (one join level). Quote it, because
- an unquoted dotted value does not parse as a tag:
- `suggest { source=sales dimension="products.department" }`.
-
- On the `query=` form of `suggest`, `dimension` names a column of that query's output, not a path into
- the model, and only the last segment of it is read. Match it to the suggest query's `group_by`. When it
- matches no column the picker falls back to the first column of the result: silently right for a
- one-column suggest query, silently wrong for a multi-column one.
-
- `control=select`/`multiselect` with a `suggest` renders a picker filled from the data;
- `range_min`/`range_max` on a `filter<number>` renders a two-handled range slider; a `filter<date>` or
- `filter<timestamp>` renders a time-range control with preset windows and a custom day range; a bare
- `date` or `timestamp` renders a date picker. Which controls appear is per-dashboard, decided by which
- givens the query references.
- `malloy-model` (a modeling skill) and `docs/givens.md` cover givens themselves.
-
- Two per-dashboard options on the artifact tag:
-
- - `autorun=false` batches control changes behind an Apply button. Add it once a page is slow enough
- that a reader notices two round trips.
- - `givens { CATEGORY=f'Outerwear' }` sets starting values, not a redeclaration. A URL parameter wins.
-
- A served `.malloy` notebook takes both inside its `## artifact { … }` tag, as `autorun=false` and
- `givens { CATEGORY=f'Outerwear' }`, and behaves identically. A file-level `## autorun=false` does
- nothing there; only a legacy `.malloynb` reads options at the file level.
-
- ## Drill
-
- `# drill` goes on a model **dimension**, never on a dashboard:
-
- ```malloy
- # drill { to=["category", "self"] given=CATEGORY }
- dimension: category is products.category
- ```
-
- `to=<slug>` navigates to that dashboard with the clicked value written into the named given;
- `to=self` filters in place; two or more destinations pop a menu.
-
- Declaring it on the dimension is the point: every result that groups by it becomes clickable, in a
- dashboard tile and in a notebook cell alike. So when a view is meant to be drilled, group by the
- tagged dimension. Declaring `dimension: category is products.category` and grouping by `category`
- gives the identical output field name and the identical numbers, and carries the tag.
-
- **Always write `given=`.** Without it the given name is the dimension name **verbatim**, so a
- `dimension: category` seeds a given called `category` rather than a declared `given: CATEGORY`. A
- `to=self` survives that, because a surface folds case when it looks up its own given. A `to=<slug>`
- does not: it navigates, still looks like it worked, and arrives as `?category=…`, which the
- destination drops by exact match, so you land on an unfiltered page. Nothing errors, and the lint
- folds case when it checks, so it stays green too. That silence is specific to a name that folds onto
- a declared given. A `to=self` whose name matches nothing at all is caught loudly and is not offered;
- a `to=<slug>` is not checked either way.
-
- A drill only lands somewhere useful if the destination declares a control for the given being
- seeded. **No lint checks that.** It verifies that the target slug is a dashboard in the package, and
- for `to=self` that some model declares the given, and stops there. Nothing reads the destination's
- own givens, so click it and look.
-
- Cells in a drillable **table** column show it: pointer cursor, and a blue underline on hover. They are
- in the tab order and carry a button role too, so a keyboard reaches them, focus is styled the way
- hover is, and Enter or Space fires the drill. Chart marks get no such affordance in either Publisher
- or Malloyyo, so a dashboard meant to be drilled wants at least one untagged (table) tile. A destination the
- surface cannot honor is not marked and not offered, which is why a `to=self` reads as plain text in a
- document that declares no control for its given.
-
- **One thing quietly switches the marking off, per column: another tile rendering a column with the
- same header.** Put a "revenue by category" chart beside a drillable `category` table, which is the
- obvious thing to build, and that column's cells stop being marked. Marking matches columns by their
- rendered header text, so a name a non-drillable field also shows is dropped rather than risk painting
- a dead link. Only a **non-drillable** column suppresses: a second tile that groups by the same tagged
- dimension is fine, which is the arrangement the paragraph above already recommends. **Other drillable
- columns on the same page keep their marking**, so counting marked cells will not tell you: look at the
- column you care about. The clicks still work, so this is invisible
- unless you hover. Give the two different headings with `# label=`. A transposed table is never marked
- either, for a different reason.
-
- ## Legacy single-query pages
-
- Only for a package that already has one (see "Legacy" above). Its layout can come out wrong in two
- visibly different ways, and the reload is 200 and the manifest reports the column count you asked for in
- both. A top-level `aggregate:` there is the KPI card; nest views for tiles; give each a `# colspan` and
- the first tile after the cards a `# break`; `# dashboard { gap=N table { max_height=N | none } }` are
- options only this form reads.
-
- **Not a dashboard at all: one plain nested table**, every `# colspan` and `# break` dropped, because a
- `f'…'` filter literal in a `givens { … }` block shares a line with `# dashboard`. Put `# dashboard` on
- its own line.
-
- **A dashboard, but nothing lines up**: `# colspan` without `columns=N`, so the items flow side by side
- at their natural widths instead of aligning to a grid.
-
- To tell them apart, run the page's own query, `{"queryName": "<the manifest's query>"}`, and read
- `renderLogs` on the response (absent when there is nothing to say):
-
- | render log | what it means |
- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
- | `Unknown render tag 'colspan'` | the renderer never saw a `# dashboard` tag. It does **not** say which of the two causes; check both |
- | `Ignored # colspan … only applies in columns mode` | it saw the tag but there is no count |
-
- Neither reaches the package warnings. A **wrapped `##` tag** is the one failure in this family that does:
- the file is absent from the listing and the package warnings say "Tag does not parse (Unclosed '{')".
-
- ## Read the lint
-
- Package warnings after a reload are the dashboard's test suite. Fix all of them:
-
- - `# drill … targets "x", which is not a dashboard in this package`: a dead click.
- - `to=self, but no model in this package declares a given "X"`: the clicked value has nowhere to go.
- - `given "X" suggests options from source "y", which this file does not define`: the dropdown will
- be empty, so import it.
- - `filters by given "X", which this file does not import, so no control is shown for it`: the trap
- under "Importing a given is what makes it bindable", which the lint now names for you, with the file
- to fix.
- - A tile that does not resolve to a real view; a non-positive `# dashboard { columns }`; a tile view's
- `# colspan` that is not a positive integer or is wider than the grid; a `dashboard_columns=` alias,
- which is an error when it disagrees with `dashboard { columns }`; and any property inside the
- artifact tag Publisher does not read.
-
- Findings carry a `severity`, but `warn` is the ordinary default and tells you nothing about how bad
- one is. Read the text, not the severity and not the count. One message is worth recognising because
- it changes what the rest of the list means: **"Dashboard lint stopped early, so this list is
- incomplete"**.
-
- **Read the status the reload itself returns, not the listing.** One dashboard that fails to compile
- fails the whole package load, and the reload answers **424** with the compile error. A package that
- was already serving then keeps serving its previous version, so the listing still answers 200 and
- looks perfectly healthy while your edit has silently not taken effect.
-
- **If you did not catch the 424, `GET /api/v0/status` still knows.** A package serving an older model
- than its files appears in `loadErrors` with **`stale: true`**, the compile message, and the time it
- failed, and the entry clears on the next reload that compiles. That is the one check that works after
- the fact, so make it the first thing you run when a page will not change. A package that never loaded
- at all appears there too, without `stale`, and is absent from the listing entirely.
-
- If the reload is 200 and the others are listed but yours is not, discovery skipped the file,
- usually a missing or misspelled `# artifact` tag. That is the same mechanism that deliberately skips
- an untagged shared include, and it is also how you hide a dashboard on purpose: drop its tag. The
- package surface never hides a dashboard. Every tagged dashboard is listed and served. Dropping the tag
- hides it as a dashboard, but not always as a file: with no `index.malloy`, or with a legacy `explores`
- that lists it, the untagged file is then listed and published as an ordinary model.
-
- **A tile over a hidden source answers 404.** When the package has an `index.malloy`, tiles, a
- legacy single-query page's query, and filter `suggest` lists read only the sources it exports. The
- dashboard file admits nothing of its own, so importing a source into it is not enough. The package
- load warns once per tile that will fail, for example:
-
- ```
- Tile orders_staging -> by_flag on dashboard overview reads orders_staging, which index.malloy doesn't export, so it won't load. Fix: add orders_staging to the export { ... } in index.malloy.
- ```
-
- The fix is the one the warning names: add the source to the `export { ... }` in `index.malloy`. In a
- package that gates a source with `#(authorize)` or `#(access_filter)`, the warning says "a source"
- instead of naming it. A
- `suggest` over a hidden source gets the same warning, ending "so its list will be empty". Do not
- add an `explores` to `publisher.json` to serve a dashboard; it is deprecated and no longer needed.
-
- **A clean reload is not proof the tags are right.** The checks above read names and resolve them; the
- separate warning for a tag that does not _parse_ is syntax only: it carries no
- position and says nothing about a name that does not resolve. It catches _a_ malformed tag; its
- absence is not evidence there are none. That is why the last step is opening the page, not reading
- the warning list.
+ # Malloy dashboards: renamed
- ## What "done" means
+ This skill was merged into `skill:malloy-reports`. Read that skill instead; it holds everything this one did.
- - Every source, view, and field name came from the model you read in step 1.
- - The reload returned **200**, not 424. A 424 means the page you are about to look at is the old one.
- - The package reloads with **zero** dashboard warnings, and your dashboard is in the listing at all.
- - **The page's items line up.** Open it and look: the checks above pass on a dashboard whose items do
- not align.
- - You opened the page and every tile shows real numbers: not stuck loading, not an error, not an
- empty state you did not intend.
- - Each control renders as the widget you intended (a select shows options; a slider is a slider),
- and changing one changes the numbers.
- - If you added a `# drill`, you clicked it and landed where you meant to, with the given seeded.
- - Every card and tile carries a colspan, each row's colspans sum to `columns`, and the rows end flush
- with each other. Nothing is clipped, no tile is thousands of pixels tall, and no legend or card
- label ends in `…`.
+ What changed, in one place:
- ## Reference
+ - A dashboard is a **report** with `layout=grid`. A notebook is the same report with `layout=linear`.
+ - A report can live anywhere in the package. Write a new one at the package root, not in `dashboards/`.
+ - Write `layout=grid` in the `## artifact` tag. `kind=dashboard` is the deprecated spelling.
+ - A `# drill { to=… }` target is the report's package path without `.malloy`, not a bare name.
- - `docs/dashboards.md`: the full guide this skill condenses.
- - `docs/givens.md`: the givens the controls are generated from.
+ This name stays only so that an install that already holds `malloy-dashboards` has it replaced with this pointer rather than keeping the old folder rules.