nuxt-ui-tools-dashboard

Files (5)

• SKILL.md
• blocks.md · references/
• controls.md · references/
• filters.md · references/
• schema.md · references/

SKILL.md (first lines)

# nuxt-ui-tools Dashboard

Use this skill for package-consumer tasks involving:

- `defineDashboardSchema(...)`, `defineDashboardView(...)`, and the functions that wrap them
- `useDashboard(schema)` and `useDashboard(() => accountSchema({ accountId }))`
- typed injection: `useDashboardView(consumptionView)`, `injectDashboard(accountSchema)`,
  `InferDashboard`, `InferDashboardView`
- filters: declared inline with `f`, where they live (`sync`: URL, memory, a store), headless
  filters, one value per key across views
- `UiDashboardPage`: the whole page (header, refresh, pinned tabs and filters, the current view)
- controls (`dashboard.controls.x`) and the shipped UI `UiDashboardFilters`, `UiDashboardFilter`,
  `UiDashboardViewTabs`, a chart's series picked by a filter, a block's drill-down filter chips
- staged queries, `select`, dependent queries (`requires`), and `derive`
- lazy `enabled` conditions on views, queries, and filters
- remote pickers and `remoteTableOptions`
- number formats (`format="integer"`, `Intl.NumberFormat` options, `useDashboardFormat()`)
- `UiDashboardGrid`, `UiDashboardStat`, `UiDashboardWidget`, chart and list blocks, and the rest of
  the block library

Focused references:

- `skills/consumer/dashboard/references/schema.md` — schema and view functions, stages, `select`,
  conditions, views, derive, the facade, rebuilds
- `skills/consumer/dashboard/references/filters.md` — filter kinds and options, sync, URL keys,
  controls, remote pickers
- `skills/consumer/dashboard/references/controls.md` — the filter bar, pills, view tabs, slots,
  binding a control to your own component
- `skills/consumer/dashboard/references/blocks.md` — the page, every block, formats, grid sizing,
  theming

## Setup

The dashboard ships with the module. Queries run through TanStack Query, so the app must install
`VueQueryPlugin` (same requirement as the table). Chart blocks render with unovis, an optional peer
dependency:

```bash
bun add @unovis/vue @unovis/ts
```

Stats, lists, bars, paired bars, funnels, stacked bars, and custom widgets work without unovis.

## The Shape In One Example

A single file is enough for a small dashboard:

```vue
<script setup lang="ts">
const schema = defineDashboardSchema({
  key: 'sales',
  filters: (f) => ({
    period: f.enum([7, 30, 90], {
      defaultValue: 30,
      label: 'Period',
      format: (days) => `${days} days`,
    }),
  }),
  queries: ({ essential, background, filters }) => ({
    summary: essential.query(() => ({
      queryKey: ['sales', 'summary', filters.period],
      queryFn: () => api.sales.summary({ days: filters.period }),
    })),
    daily: background.query({
      defaultValue: [],
      query: () => ({
        queryKey: ['sales', 'daily', filters.period],
        queryFn: () => api.sales.daily({ days: filters.period }),
      }),
    }),
  }),
})

const dashboard = useDashboard(schema)
</script>

<template>
  <UiDashboardPage :dashboard title="Sales">
    <UiDashboardGrid>
      <UiDashboardStat
        size="12 md:4"
        :source="dashboard.summary"
        label="Revenue"
        :value="(summary) => summary.revenue"
        :compare="(summary) => summary.previousRevenue"
        :format="{ currency: 'EUR' }"
      />
      <UiDashboardBarChart
        size="12 lg:8"
        :source="dashboard.daily"
        title="Orders per day"
        :x="(day) => day.date"
        :series="[{ key: 'orders', label: 'Orders', value: (day) => day.orders }]"
        format="integer"
        totals
      />
    </UiDashboardGrid>
  </UiDashboardPage>
</template>
```

What you get without writing it:

- the page: title, today's date and when the data was fetched, the refresh control, and the filter
  bar pinned while the page scrolls
- a "Period 30 days ⌄" pill that picks the period, turns accent when changed, and resets
- `?period=7` in the URL (defaults never reach the URL)
- `summary` fetches first; `daily` fetches once `summary` settles
- each block shows a skeleton while its source loads, a retryable error scoped to that block, an
  empty state, and a thin progress bar whenever a request is in flight (refetch or retry)
- the stat's delta and "vs €12,400 previous period" caption, in the current locale
- every accessor (`summary.revenue`, `day.date`) typed from the query result

## Compose A Dashboard From Functions

A dashboard is about something: an account, the workspace a user works in. That context is the
params of a function wrapping the schema, passed by the page and handed on to the views. Filters are
the state the user controls; each view declares its own, inline. Each view is a self-contained
schema in its own file:

From ChronicStone/nuxt-ui-tools, MIT.

More from ChronicStone/nuxt-ui-tools