@malloy-publisher/server 0.3.0 → 0.3.1

package/dist/server.mjs

@@ -320380,14 +320380,18 @@ Scanned at a glance is a dashboard; read top to bottom is a notebook.
 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. There is one form,
    so there is no form to choose.
-3. **DECLARE THE GIVENS** the dashboard will filter by, in the model (usually \`givens.malloy\`), with
-   their control tags: see "Filter controls" below for the syntax and what each tag renders as. Skip
-   if they already exist, since a given is a model concern and dashboards share them.
+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). Reuse the package's \`givens.malloy\` only for a control several surfaces genuinely share, and
+   then import it whole, knowing the builder can bind those givens but not edit them.
 4. **COMPOSE THE FILE** for \`dashboards/\`, following the template below, but do not save it yet.
-   Import the package's givens file **whole**: \`import '../givens.malloy'\`, not a named list.
-   Only the givens the tiles reference become controls, so a whole-file import brings nothing
-   extra, and a named list is one more thing to forget; forgetting one costs you a missing control
-   rather than an error. Sources are the other way round: name the few you need. Then import every
+   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
@@ -320422,33 +320426,31 @@ 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 { scoped_sales } from './_shared.malloy'
-import { products } from '../storefront.malloy'
-import '../givens.malloy'
+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, and this decides how wide it sits here.
-source: overview is scoped_sales extend {
+// 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 {
-    aggregate:
-      # label="Revenue"
-      # currency
-      total_sales
-      # label="Orders"
-      order_count
-  }
+  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
+  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
+  view: revenue_by_state is sales_by_state + { where: category ~ $CATEGORY, where: created_at >= $SINCE }
 }
 \`\`\`
 
@@ -320461,8 +320463,8 @@ Three things the form costs, so you are not surprised by them:
 - **A tile expression is a string in an annotation, so the compiler never checks it.** Rename a view
   and the file still compiles; the tile fails at package load. Read the lint (step 6).
 - **No per-parent-row grouping.** There is no parent query to repeat a grid over.
-- **Filtering lives in what the tiles name**, not on the page. That is the shared include's job,
-  below.
+- **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.
 
 ### Also served: \`# artifact\` on a \`query:\`
 
@@ -320522,23 +320524,24 @@ object", so a dashboard has no description as a result.
 
 ### Where the filtering goes
 
-A dashboard has no query, so the filtering it applies must live in what it composes: a source that
-already has the givens applied. Put it in an untagged \`dashboards/_shared.malloy\`, which discovery
-treats as a shared include rather than a dashboard. **It has to apply every given the dashboard
-imports**: a given the dashboard imports but nothing references gets no control, silently, at reload
-200 with no warning. Note \`SINCE\` is a \`date\` rather than a \`filter<>\`, so it compares with \`>=\`
-rather than \`~\`. 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\`.
-
-\`\`\`malloy
-##! experimental.givens
-import { order_items } from '../storefront.malloy'
-import '../givens.malloy'
-
-source: scoped_sales is order_items extend {
-  where: products.category ~ $CATEGORY and created_at >= $SINCE
-}
-\`\`\`
+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 \`~\`.
 
 **\`# dashboard { columns=N }\` is the one spelling of the grid width**, on both forms, beside the
 artifact tag. Anything else inside the artifact tag is a package warning naming it, which is what you
@@ -320620,9 +320623,10 @@ rows.
 - **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).
-- **Importing a given is what makes it bindable.** Malloy's given namespace is per-file. A given the
-  dashboard file does not import gets no control and cannot be sent to it, even when the \`where:\`
-  that references it lives up an import chain. A dashboard must import the givens its tiles use.
+- **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
@@ -320641,9 +320645,10 @@ choosing them.
 
 ## Filter controls
 
-Controls come from the \`given:\` declarations the query references, and the tags on the declaration
-are the control contract, declared once and identical on every dashboard and in every notebook that
-uses them:
+Controls come from the \`given:\` declarations the tiles reference. Declare them in the dashboard
+file, which is what the builder edits; a package \`givens.malloy\` is for controls the data app and
+notebooks share, and a dashboard importing it whole gets the same controls but cannot edit them.
+The tags on the declaration are the control contract:
 
 \`\`\`malloy
 ##! experimental.givens

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/server",
    "description": "Malloy Publisher Server",
-   "version": "0.3.0",
+   "version": "0.3.1",
    "main": "dist/server.mjs",
    "bin": {
       "malloy-publisher": "dist/server.mjs"

package/dist/app/assets/ModelPage-CFnfQ6BL.js

@@ -1 +0,0 @@
-import{D as g,r as j,a0 as u,j as a,J as s,a1 as N,a2 as d,a3 as y,H as f,Q as k,a4 as b,a5 as F,a6 as U,T as l,a7 as c,a8 as x}from"./index-BVv6KQ93.js";function v(e,n){const t=g();return j.useCallback((o,i)=>{const r=new URLSearchParams(o.givens).toString(),m=encodeURIComponent(e),p=encodeURIComponent(n),h=encodeURIComponent(o.dashboard);t(`/${m}/${p}/dashboards/${h}`+(r?`?${r}`:""),i)},[t,e,n])}function W({environmentName:e,packageName:n,dashboardName:t}){const{params:o,onGivensChange:i}=u(),r=v(e,n);return a.jsx(s,{sx:{p:3,maxWidth:1600,mx:"auto"},children:a.jsx(N,{resourceUri:d({environmentName:e,packageName:n}),dashboard:t,givens:o,onGivensChange:i,onNavigate:r,maxResultSize:1024*1024})})}function P({environmentName:e,packageName:n,notebookPath:t}){const{params:o,onGivensChange:i}=u(),r=v(e,n),m=g();return a.jsx(s,{sx:{p:3,maxWidth:1200,mx:"auto"},children:a.jsx(y,{resourceUri:d({environmentName:e,packageName:n,modelPath:t}),maxResultSize:1024*1024,givens:o,onGivensChange:i,onNavigate:m,onDrillNavigate:r})})}function C(){const e=f(),n=e["*"],{server:t}=k();if(!e.environmentName)return a.jsx("div",{children:a.jsx("h2",{children:"Missing environment name"})});if(!e.packageName)return a.jsx("div",{children:a.jsx("h2",{children:"Missing package name"})});const o={p:3,maxWidth:1200,mx:"auto"};if(n?.startsWith("dashboards/")&&!n.endsWith(".malloy")&&!n.endsWith(".malloynb"))return a.jsx(W,{environmentName:e.environmentName,packageName:e.packageName,dashboardName:n.slice(11)});if(n?.startsWith("data-apps/")&&!n.endsWith(".malloy")&&!n.endsWith(".malloynb")){const p=n.slice(10),h=d({environmentName:e.environmentName,packageName:e.packageName,modelPath:p});return a.jsx(b,{resourceUri:h})}const i=d({environmentName:e.environmentName,packageName:e.packageName,modelPath:n});if(n?.endsWith(".malloy"))return a.jsx(s,{sx:o,children:a.jsx(F,{resourceUri:i,runOnDemand:!0,maxResultSize:512*1024})});if(n?.endsWith(".malloynb"))return a.jsx(P,{environmentName:e.environmentName,packageName:e.packageName,notebookPath:n});const r=/\.[^./]+$/.test(n??""),m=U({server:t,environmentName:e.environmentName,packageName:e.packageName,path:n??""});return a.jsxs(s,{sx:o,children:[a.jsx(l,{variant:"h6",sx:{fontWeight:600},children:"Nothing to open at this path"}),a.jsxs(l,{variant:"body2",color:"text.secondary",sx:{mt:1},children:[a.jsx(s,{component:"span",sx:{fontFamily:c},children:n})," ","does not name a"," ",a.jsx(s,{component:"span",sx:{fontFamily:c},children:".malloy"})," ","or"," ",a.jsx(s,{component:"span",sx:{fontFamily:c},children:".malloynb"})," ","file in package"," ",a.jsx(s,{component:"span",sx:{fontFamily:c},children:e.packageName}),". This address opens"," ",a.jsx(s,{component:"span",sx:{fontFamily:c},children:".malloy"})," ","and"," ",a.jsx(s,{component:"span",sx:{fontFamily:c},children:".malloynb"})," ","files."]}),r&&a.jsxs(l,{variant:"body2",color:"text.secondary",sx:{mt:1},children:["A file from the package's"," ",a.jsx(s,{component:"span",sx:{fontFamily:c},children:"public/"})," ","directory is served at ",a.jsx(x,{href:m,children:m}),"."]}),a.jsxs(l,{variant:"body2",color:"text.secondary",sx:{mt:1},children:[a.jsxs(x,{href:`/${encodeURIComponent(e.environmentName)}/${encodeURIComponent(e.packageName)}`,children:["Back to ",e.packageName]})," ","lists this package's models, notebooks, and data apps."]})]})}export{C as default};