@softr/sdk 0.0.26-alpha-0 → 0.0.26

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -1,178 +0,0 @@
----
-name: charts-and-metrics
-description: >-
-  Aggregate Softr datasource records inside a server function: ds.chart with
-  groupBy, metrics, where and orderBy for chart rows, ds.metric for a single
-  headline number, date bucket intervals, which aggregations each kind of field
-  offers, the two-group-column ceiling, and distinct values for filter
-  controls. Aggregation only. Listing and fetching records is reading-records.
-metadata:
-  type: sub-skill
-  library: softr-sdk
-  library_version: 0.0.22
----
-
-This skill builds on softr-sdk, and on reading-records for declaring the action a chart aggregates over.
-
-# Charts and metrics
-
-`ds.chart` groups records and aggregates each group into one row: the data behind a bar chart, a line, a pie. `ds.metric` aggregates everything into one value: the number on a stat tile. Both live on `@softr/sdk/server` and run inside a `createServerFn` handler, and both take the same read action `ds.list` takes, with the same `where` filters.
-
-## Setup
-
-```ts
-import { createServerFn } from '@tanstack/react-start'
-import { defineAction } from '@softr/sdk'
-import { ds } from '@softr/sdk/server'
-
-const sales = defineAction({
-  id: 'sales',
-  datasource: '8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77',
-  operation: 'read',
-  fields: {
-    amount: 'Vk9cXm2pSz6Ld4',   // CURRENCY
-    region: 'fZk3Qm9pLw2Xa1',   // SELECT
-    status: 'Ru7bVx2cNq0Ed9',   // SELECT, choice ids 'paid' | 'open' | 'void'
-    closedAt: 'Xp2dLh6vKz9Fa3', // DATETIME
-    rep: 'Gq5wNt8rJy3Hb1',      // LINKED_RECORD
-  },
-  permission: { userGroup: 'LOGGED_IN_USERS' },
-})
-```
-
-A chart only sees the action's declared fields, so a field to group, aggregate or filter by must be in `fields`.
-
-## Core Patterns
-
-### A bar chart
-
-```ts
-const ordersByRegion = createServerFn().handler(async () => {
-  const { data } = await ds
-    .chart(sales)
-    .groupBy((q) => ({ region: q.region }))
-    .metrics((q) => ({ orders: q.$count }))
-    .orderBy((q) => q.orders.desc)
-  return data
-})
-// data: Array<{ region: string | null; orders: number }>
-```
-
-One row per group, keyed by the names you chose in `groupBy` and `metrics`. `orders` is `number`, not `number | null`: a group that exists holds at least one record. The `null` region is the bucket of records with no value. The result also carries `executionTimestamp: Date`, when the numbers were computed.
-
-A SELECT or LINKED_RECORD group column comes back as the choice's display label, not its id. Labels are user-editable and a `where` on the same field compares ids, so a clicked bar's value cannot be fed straight back into a filter.
-
-### A time series
-
-```ts
-const { data } = await ds
-  .chart(sales)
-  .groupBy((q) => ({ month: q.closedAt.byMonth }))
-  .metrics((q) => ({ revenue: q.amount.sum }))
-  .where((q) => q.status.is('paid'))
-  .orderBy((q) => q.month.asc)
-// data: Array<{ month: string | null; revenue: number | null }>
-```
-
-`q.closedAt` bare groups by the field's value. The bucket leaves hanging off it group a date field by the bucket: `byDay`, `byWeek`, `byMonth`, `byQuarter`, `byYear`, and the cyclic `byHourOfDay`, `byDayOfWeek`, `byMonthOfYear`, `byQuarterOfYear`. What each one holds is in [references/aggregations.md](./references/aggregations.md); `byMonth` reads as `"2025-06"`.
-
-**Sort the time axis ascending yourself.** Left unsorted, rows come back by the first bucket ascending when there is one, else by the first metric descending. A time axis that misses the fallback arrives in value order, which draws a scrambled line rather than failing.
-
-### Spread, not just totals
-
-```ts
-const { data } = await ds
-  .chart(sales)
-  .groupBy((q) => ({ region: q.region }))
-  .metrics((q) => ({
-    smallest: q.amount.min,
-    typical: q.amount.avg,
-    biggest: q.amount.max,
-  }))
-  .orderBy((q) => q.typical.desc)
-```
-
-Any number of metrics in one request, several over the same field included. Each row carries all of them, so one request can feed two panels. A metric key may not reuse a group key, and two metrics may not ask for the same value. `avg` comes back rounded to two decimals.
-
-### Two group columns, which is the ceiling
-
-```ts
-const { data } = await ds
-  .chart(sales)
-  .groupBy((q) => ({ month: q.closedAt.byMonth, region: q.region }))
-  .metrics((q) => ({ revenue: q.amount.sum }))
-  .orderBy((q) => [q.month.asc, q.revenue.desc])
-// data: Array<{ month: string | null; region: string | null; revenue: number | null }>
-```
-
-The result is long format, one row per month and region pair, so the app pivots into one array per series before charting. **A chart groups by at most two columns**, each a different field, and a field cannot be grouped and aggregated in the same chart. A third group column is a compile error.
-
-### Distinct values, for a filter control
-
-```ts
-const { data } = await ds.chart(sales).groupBy((q) => ({ region: q.region }))
-// data: Array<{ region: string | null }>
-```
-
-Skip `metrics` entirely and the rows hold the distinct group values, one each. This is the cheapest way to fill a dropdown from a real column.
-
-### A headline number
-
-```ts
-const { value } = await ds
-  .metric(sales, (q) => q.amount.sum)
-  .where((q) => q.status.is('paid'))
-// value: number | null
-```
-
-One aggregation, no grouping, one value. Whenever the answer is a single number, a stat tile or a count, reach for `ds.metric` rather than a one-row chart: there is nothing to group by and nothing to unpack out of `data`. The same measure handles apply, `q.$count` included:
-
-```ts
-const { value: open } = await ds.metric(sales, (q) => q.$count).where((q) => q.status.is('open'))
-// open: number
-```
-
-### Top N
-
-```ts
-const { data } = await ds
-  .chart(sales)
-  .groupBy((q) => ({ rep: q.rep }))
-  .metrics((q) => ({ revenue: q.amount.sum }))
-  .orderBy((q) => q.revenue.desc)
-
-const top5 = data.slice(0, 5)
-```
-
-A chart has no row limit to set, so a top-N is a client-side slice of the fully sorted rows.
-
-### A dashboard load
-
-```ts
-const loadDashboard = createServerFn().handler(async () => {
-  const [mtd, series] = await Promise.all([
-    ds
-      .metric(sales, (q) => q.amount.sum)
-      .where((q) => q.$and(q.status.is('paid'), q.closedAt.gte('2026-09-01'))),
-    ds
-      .chart(sales)
-      .groupBy((q) => ({ month: q.closedAt.byMonth }))
-      .metrics((q) => ({ revenue: q.amount.sum }))
-      .where((q) => q.status.is('paid'))
-      .orderBy((q) => q.month.asc),
-  ])
-  return { mtd: mtd.value, series: series.data }
-})
-```
-
-Each tile and panel is its own request, fired in parallel from one handler.
-
-## Order of calls
-
-`groupBy` comes first and exactly once; a chart cannot be awaited before it. `metrics` follows, at most once, or not at all for distinct values. `where` can be chained anywhere, repeatedly, and calling it more than once ands the filters together. `orderBy` sorts by the chart's own keys, group and metric alike, and only sees the keys declared so far, so call it last.
-
-## References
-
-- [references/aggregations.md](./references/aggregations.md): every bucket interval and its value type, which aggregations each kind of field offers, and the chart rules
-- [reading-records/SKILL.md](../reading-records/SKILL.md): declaring the action, and the filter operators `where` accepts
-- [reading-records/references/query-builder.md](../reading-records/references/query-builder.md): the full filter matrix

package/skills/softr-sdk/charts-and-metrics/references/aggregations.md

@@ -1,76 +0,0 @@
-# Buckets, aggregations and chart rules
-
-## Group columns
-
-A bare handle in `groupBy` groups by the field's value. What the column reads back as depends on the field's declared type:
-
-| Field type | Column value |
-| --- | --- |
-| SELECT, LINKED_RECORD, CREATED_BY, UPDATED_BY | `string \| null`, the display label, not the id |
-| Text fields | `string \| null` |
-| Number fields | `number \| null` |
-| CHECKBOX | `boolean \| null` |
-| DATE, DATETIME, CREATED_AT, UPDATED_AT | `string \| null`, or a bucket leaf below |
-| Multi-value (`SELECT[]` and friends), ATTACHMENT, DATE_RANGE | Cannot group |
-
-`null` is always the bucket of records with no value. A multi-value field can neither group nor aggregate: exploding it would count each record once per value and inflate every metric.
-
-## Date buckets
-
-Leaves on every date and datetime handle, `q.closedAt.byMonth` style:
-
-| Leaf | Groups by | Column value |
-| --- | --- | --- |
-| `.byDay` | Calendar day | `"2025-06-14"` |
-| `.byWeek` | Calendar week | The ISO date of the week's Monday |
-| `.byMonth` | Calendar month | `"2025-06"` |
-| `.byQuarter` | Calendar quarter | `"Q2 2025"`, a display string, not a parseable date |
-| `.byYear` | Calendar year | The year as a `number` |
-| `.byHourOfDay` | Hour of day | `0`–`23`. DATETIME fields only, not DATE |
-| `.byDayOfWeek` | Day of week | `1`–`7`, 1 is Sunday |
-| `.byMonthOfYear` | Month of year | `1`–`12` |
-| `.byQuarterOfYear` | Quarter of year | `1`–`4` |
-
-Every bucket value is `| null` for the empty bucket. The cyclic buckets come back as bare numbers; the app supplies the labels.
-
-`byWeek` is Monday-based while `byDayOfWeek` counts from Sunday, so the two cannot be lined up by arithmetic alone.
-
-## Aggregations
-
-Handles in `metrics`, and the second argument of `ds.metric`:
-
-| Handle | Available on | Comes back as |
-| --- | --- | --- |
-| `.sum` | Number fields | `number \| null` |
-| `.avg` | Number fields | `number \| null`, rounded to two decimals |
-| `.min` / `.max` | Number fields | `number \| null` |
-| `.min` / `.max` | Date fields | `string \| null`, as `"2025-06-14"` |
-| `.distinct` | Number and date fields | `number`, the count of distinct values |
-| `q.$count` | No field: counts rows | `number` |
-
-Number fields: NUMBER, PERCENT, CURRENCY, PROGRESS, RATING, DURATION, COUNT, AUTONUMBER. Date fields: DATE, DATETIME, CREATED_AT, UPDATED_AT.
-
-Every other field offers no aggregations at all. `q.$count` is the only measure that touches no field, so a text or choice column is measured by grouping on it and counting rows.
-
-`sum`, `avg`, `min` and `max` are `null` for a group with no values. `$count` and `distinct` are plain `number`.
-
-## Rules
-
-- `groupBy` takes one or two columns, is required, and is called once. A third column, and a chart with no group columns, are compile errors.
-- Each group column is a different field, and a field cannot be grouped and aggregated in the same chart.
-- `metrics` is optional and called at most once. A metric key may not reuse a group key, and two metrics may not ask for the same aggregation of the same field.
-- `orderBy` names the chart's own keys, group and metric alike. Call it last: it only sees keys already declared.
-- Left unsorted, rows come back by the first bucket column ascending; with no bucket, by the first metric descending; with neither, by the first group ascending.
-- There is no row limit. A top-N is a client-side `slice` of the sorted rows.
-
-## Errors
-
-| Message | Cause |
-| --- | --- |
-| `a chart needs at least one column to group by` | Awaiting a chart whose `groupBy` produced no columns |
-| `a chart may group by at most two columns` | Three or more group columns, on an untyped action |
-| `a chart may group by a field only once` | The same field twice in `groupBy` |
-| `a field cannot be grouped and aggregated in one chart` | One field in both `groupBy` and `metrics` |
-| `two metrics ask for the same value` | The same aggregation of the same field under two keys |
-| `"..." is not a column of this chart` | An `orderBy` key that is neither a group nor a metric key |
-| `a chart column must come from the callback a chart hands you` | A hand-built object where a handle belongs |