@graphit/cli 0.2.248 → 0.2.252

package/skills/graphit/references/data-sources.md

@@ -116,18 +116,17 @@ Check `graphit status` for those domains before proposing a create or a config c
 
 ## Presenting data source results
 
-The user cannot see the raw CLI output - you are the rendering layer. After `graphit ds list`, present a markdown table and end with a recommendation of which source to use (or note that none covers the needed table):
+The user cannot see raw CLI output - you are the rendering layer. After `graphit ds list`, present a markdown table and end with a recommendation of which source to use (or note none covers the needed table):
 
 ~~~
-**3 data sources:**
+**2 data sources:**
 
 | Name | ID | Rows | Status | Governed |
 |---|---|---:|---|---|
 | **MARKETING_UA_DS** | ds_abc123 | 1,247,832 | active | yes |
-| **PLAYER_QUALITY** | ds_def456 | 892,104 | active | no |
 | **REVENUE_EVENTS** | ds_ghi789 | 3,412,006 | stale | yes |
 
 Using **MARKETING_UA_DS** (ds_abc123), which covers spend, installs, and ROAS columns.
 ~~~
 
-Bold every data source name. If a source is stale, say so and offer to refresh it before querying.
+Bold every data source name. If a source is stale, say so and offer to refresh it before querying. If `truncated` is true, raise `--limit` before recommending.

package/skills/graphit/references/filters-advanced.md

@@ -46,12 +46,11 @@ A `dateRange` registration persists to saved views exactly like a `filter`/`para
 
 Relative presets auto-recompute on reload (a saved "last_7_days" always means the last 7 days from today). The 11 preset ids - also available via `graphit.datePresets` (`[{id,label}]`) and `graphit.datePreset(id)` (`{start,end}`): today, yesterday, last_7_days, last_30_days, this_month, last_month, this_quarter, last_quarter, ytd, last_90_days, last_12_months.
 
-Bind a chart to the range with two scalar params and a `BETWEEN`:
+Bind a chart to the range with two scalar params and a `BETWEEN`. The entity owns the query - its `data-graphit-sql` holds the `BETWEEN :start_date AND :end_date` template and the call passes only the values:
 
 ```js
+// entity #rev: data-graphit-sql="SELECT day, SUM(rev) AS rev FROM orders WHERE day BETWEEN :start_date AND :end_date GROUP BY 1"
 graphit.bind('#rev', {
-  sql: 'SELECT day, SUM(rev) AS rev FROM orders WHERE day BETWEEN :start_date AND :end_date GROUP BY 1',
-  dataSourceId: 'ORDERS',
   params: () => ({ start_date: dr.start, end_date: dr.end }),
   deps: dr.deps,
   render: (r, el) => graphit.graph(el, { type: 'area', data: r.data, x: 'day', y: 'rev' }),

package/skills/graphit/references/filters.md

@@ -31,7 +31,7 @@ const country = graphit.filter('country', {
 Handle API:
 - `country.get()` - current value
 - `country.set(value)` - update value (triggers subscribers + bound re-resolves)
-- `country.subscribe(cb)` - called on change; returns unsubscribe fn
+- `country.subscribe(cb)` - called immediately with the current value, then on every change; returns unsubscribe fn
 
 ## graphit.param(id, options)
 
@@ -45,14 +45,14 @@ const topN = graphit.param('top_n', { label: 'Top N', default: 10, options: [5,
 
 The registration renders nothing, so connect your own markup to the handle in three steps: set the element's initial value from `handle.get()`, call `handle.set(newValue)` in the change event, and pass `handle.subscribe(v => updateElement(v))` so the control restores its visual state on saved-view apply or page reload. The Complete Example below shows this end to end for a `<select>`.
 
+`subscribe` fires the callback IMMEDIATELY at registration, then on every change, so init must be order-independent: a callback reaching a `const`/`let` declared further down throws at boot, and one uncaught throw kills the whole dashboard script - every chart spins forever with no error surfaced. Declare what the callback touches before you subscribe.
+
 ## graphit.bind(el, options) - Reactive Data Binding
 
-Connects a data entity to filter dependencies so it re-resolves automatically on change.
+Connects a data entity to filter dependencies so it re-resolves automatically on change. The entity owns the query: `el` sits inside the `[data-graphit-id]` wrapper whose `data-graphit-sql` carries the `:name` placeholders, and the call supplies only the values (`runtime.md`).
 
 ```js
 graphit.bind(document.getElementById('revenue-chart'), {
-  sql: 'SELECT date, SUM(revenue) AS revenue FROM orders WHERE country = :country GROUP BY 1',
-  dataSourceId: 'ORDERS',
   params: () => ({ country: graphit.state.get('country') }),
   deps: ['country'],      // state keys that trigger re-resolve (inferred from params if omitted)
   render: (result, el) => {
@@ -96,7 +96,9 @@ One control, wired to one reactive chart. The `<select>` is your own markup; `bi
   <option value="NA">North America</option>
   <option value="EU">Europe</option>
 </select>
-<div id="revenue-by-region"></div>
+<div data-graphit-id="revenue-by-region" data-graphit-label="Revenue by Region"
+     data-graphit-sql="SELECT month, SUM(revenue) AS revenue FROM sales WHERE (:region = 'ALL' OR region = :region) GROUP BY 1 ORDER BY 1"
+     data-graphit-ds="SALES"></div>
 
 <script>
   const region = graphit.filter('region', { label: 'Region', field: 'REGION', default: 'ALL' });
@@ -107,8 +109,6 @@ One control, wired to one reactive chart. The `<select>` is your own markup; `bi
   region.subscribe(v => { sel.value = v; });
 
   graphit.bind(document.getElementById('revenue-by-region'), {
-    sql: 'SELECT month, SUM(revenue) AS revenue FROM sales WHERE (:region = \'ALL\' OR region = :region) GROUP BY 1 ORDER BY 1',
-    dataSourceId: 'SALES',
     params: () => ({ region: region.get() }),
     deps: ['region'],
     render: (result, el) => {

package/skills/graphit/references/kpi.md

@@ -23,13 +23,14 @@ Fetch `compareValue` in the same resolve as the value (a prior-period column) or
 
 ## KPI Row: One Resolve, Several Cards
 
-The standard dashboard header - several KPI cards fed by ONE query (per the rate-limit budget in `runtime.md`). Put the loading overlay on the shared container and pass it as the single `target`; render each card with `graphit.kpi`; anchor provenance with `sourceEntityId` (first card) plus `targetEntityIds` (the rest) so every card's details panel shows the live query. Each card still carries its own complete, executable `data-graphit-sql`.
+The standard dashboard header - several KPI cards fed by ONE query (per the rate-limit budget in `runtime.md`). One card OWNS the shared query: its `data-graphit-sql` is the combined statement the resolve runs, named by `sourceEntityId`. The other cards are `targetEntityIds` - each keeps its own complete, executable `data-graphit-sql` and gets the live query in its details panel. The resolve itself passes no `sql` and no `dataSourceId`; the entity contract in `runtime.md` holds here too, and passing both is the legacy shape that trips a `legacy_query_source` save warning (`migration.md`). Put the loading overlay on the shared container and pass it as the single `target` - with `sourceEntityId` set, `target` only carries the overlay, so it may wrap several entities.
 
 ```html
 <div id="kpi-row" class="gh-loading" style="display:grid;grid-template-columns:repeat(3,1fr);gap:16px">
   <!-- gh-loading-overlay spinner from runtime.md First-paint section goes here -->
+  <!-- owner: its sql IS the shared query the resolve runs -->
   <div data-graphit-id="kpi-credits" data-graphit-label="Total Credits"
-       data-graphit-sql="SELECT SUM(CREDIT_USED) AS v FROM CREDIT_USAGE_DS"
+       data-graphit-sql="SELECT SUM(CREDIT_USED) AS credits, COUNT(*) AS txns FROM CREDIT_USAGE_DS"
        data-graphit-ds="CREDIT_USAGE_DS">
     <div id="kpi-credits-card"></div>
   </div>
@@ -38,8 +39,6 @@ The standard dashboard header - several KPI cards fed by ONE query (per the rate
 <script>
 (async function () {
   var r = await graphit.resolve({
-    sql: "SELECT SUM(CREDIT_USED) AS credits, COUNT(*) AS txns FROM CREDIT_USAGE_DS",
-    dataSourceId: "CREDIT_USAGE_DS",
     target: "#kpi-row",
     sourceEntityId: "kpi-credits",
     targetEntityIds: ["kpi-txns", "kpi-success"]

package/skills/graphit/references/presentations.md

@@ -89,12 +89,9 @@ deck.slide({
 // After deck.start(), fire resolve calls
 deck.start();
 
-graphit.resolve({
-  sql: "SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) AS spend FROM MARKETING_UA_DS GROUP BY 1 ORDER BY spend DESC LIMIT 6",
-  dataSourceId: "MARKETING_UA_DS",
-  target: "#chart1"
-}).then(function(r) {
-  graphit.graph("#chart1", { type: "bar", data: r.data, x: "MEDIA_SOURCE", y: "spend", valueFormat: "currency" });
+// No sql/dataSourceId: target sits inside the entity, which owns the query
+graphit.resolve({ target: "#chart1" }).then(function(r) {
+  graphit.graph("#chart1", { type: "bar", data: r.data, x: "source", y: "spend", valueFormat: "currency" });
 });
 ```
 

package/skills/graphit/references/runtime.md

@@ -12,7 +12,7 @@ Consult when authoring dashboard HTML and wiring its data: fetching live data, m
 
 `graphit.resolve()` fetches live data from cached data sources on every page load. NEVER embed query results as static JS variables (`const data = [...]`) - that freezes a snapshot that never refreshes and breaks provenance.
 
-The entity owns the query. A resolve call passes no `sql` and no `dataSourceId`: both are read from the entity wrapper, authored once in the attributes and never repeated in the call.
+The entity owns the query. A resolve call passes no `sql` and no `dataSourceId`: both are read from the entity - the wrapper around `target`, or the one named by `sourceEntityId` - authored once in the attributes and never repeated in the call.
 
 ```js
 const result = await graphit.resolve({
@@ -25,7 +25,7 @@ const result = await graphit.resolve({
 - `target` (CSS selector or element) does two jobs: locates the entity whose `data-graphit-sql` / `data-graphit-ds` this call runs, and shows a blur/spinner overlay while loading, removed on completion.
 - `params` (optional) supplies values for the `:name` placeholders in the entity's SQL.
 - `targetEntityIds` (optional, `string[]`) - `data-graphit-id`s of OTHER graphs this result also renders into, so each one's details panel reflects filters (not just `target`); entity ids, never CSS selectors.
-- `sourceEntityId` (optional) - the graph that owns a `target`-less resolve feeding several graphs (pair with `targetEntityIds`).
+- `sourceEntityId` (optional) - the entity that owns the query when one result feeds several graphs; the SQL is read from IT, so `target` may be a plain container holding several entities and serves only the overlay (pair with `targetEntityIds`; canonical shape in `kpi.md`).
 - `maxRows` (optional) defaults to **10,000**, capped at **50,000**. Aggregate to a chartable grain well under the default; raise it only for a genuine row-level export, never above the cap.
 - `result.data` is an array of row objects you render however you want.