@agent-native/core 0.114.16 → 0.115.3

package/corpus/templates/slides/.agents/skills/agent-native-docs/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: agent-native-docs
+description: >-
+  How to find version-matched Agent Native framework docs and source bundled in
+  node_modules. Use before implementing or answering questions about
+  @agent-native/core APIs, generated apps, workspaces, templates, or advanced
+  features.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing or explaining non-trivial Agent Native behavior, read the
+version-matched docs installed with `@agent-native/core`. When examples,
+imports, or implementation details matter, inspect the packaged source corpus
+too.
+
+## Why
+
+Generated apps and workspaces may be on a different framework version than the
+public docs or model memory. The installed package is the source that matches
+the app in front of you. It also includes a source-only corpus of core and
+first-party templates so agents can replicate current best-practice patterns
+without needing the framework monorepo checkout.
+
+## How
+
+From a generated app directory:
+
+```bash
+pnpm action docs-search --query "<feature>"
+pnpm action docs-search --slug <slug>
+pnpm action docs-search --list
+pnpm action source-search --query "<pattern>"
+pnpm action source-search --path templates/plan/AGENTS.md
+pnpm action source-search --path toolkit/src/index.ts
+pnpm action source-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
+read-only `source-search` tool with `query`, `path`, and `list`.
+
+If the action runner is unavailable, search the package directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
+```
+
+Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
+under `node_modules/@agent-native/core/docs/content/`. For source examples,
+read files under `node_modules/@agent-native/core/corpus/core/` or
+`node_modules/@agent-native/core/corpus/templates/`.
+
+Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
+readable TypeScript under `node_modules/@agent-native/toolkit/src/`. Read
+`customizing-agent-native` before taking ownership of a shared component: inspect package
+source as a read-only reference, then configure, compose, or eject the smallest
+supported unit into app-owned source. Preserve public actions, application
+state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
+deep-import its private source. Manual copying is only the fallback described by
+an unknown third-party package's add-style blueprint.
+
+## Reuse Proven Patterns (rg + cp)
+
+Version-matched installed source outranks web docs or memory: it is the exact
+code shipping with this app. `node_modules/@agent-native/core/corpus/templates/`
+holds source for every first-party template, not just the one this app started
+from, so a pattern from the mail template is fair game for a tasks app. Grep
+across it, then copy a whole file as a starting point instead of writing the
+pattern from scratch:
+
+```bash
+# Find how other templates solved a similar problem
+rg -n "drag.*drop|reorder" node_modules/@agent-native/core/corpus/templates
+
+# Grab a proven action file as a starting point, then adapt names/schema
+cp node_modules/@agent-native/core/corpus/templates/mail/actions/archive-email.ts \
+   actions/archive-item.ts
+
+# Read the full framework source behind an API, not just the corpus copy
+rg -n "defineAction" node_modules/@agent-native/core/src/action.ts
+```
+
+Copying template-level app code (actions, components, skill files) is the
+expected reuse path — templates exist to be forked. This is different from
+copying `core`/`toolkit` **runtime internals**: for those, follow
+`customizing-agent-native`'s configure/compose/eject ladder instead of
+hand-duplicating framework logic.
+
+## Useful Slugs
+
+| Need                           | Slugs                                                         |
+| ------------------------------ | ------------------------------------------------------------- |
+| Actions and typed client calls | `actions`, `client`                                           |
+| SQL, auth, access, sharing     | `database`, `authentication`, `security`, `sharing`           |
+| UI state visible to the agent  | `context-awareness`                                           |
+| Headless and chat-first apps   | `pure-agent-apps`, `agent-surfaces`, `using-your-agent`       |
+| Automations and schedules      | `automations`, `recurring-jobs`                               |
+| Cross-app and external agents  | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions        | `skills-guide`, `writing-agent-instructions`                  |
+
+## Don't
+
+- Do not rely on memory for framework APIs when package docs are present.
+- Do not add custom REST wrappers for app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.
+- Do not copy framework runtime internals when a public API or narrow UI copy
+  will do; read `customizing-agent-native` for the supported override ladder.

package/corpus/templates/slides/_gitignore

@@ -0,0 +1,39 @@
+# React Router generated types
+.react-router/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Data
+data/uploads/
+data/settings.json
+data/.sessions.json
+
+# Learnings (personal preferences and memory — use learnings.defaults.md for tracked defaults)
+learnings.md
+
+.vercel/

package/corpus/templates/tasks/.agents/skills/agent-native-docs/SKILL.md

@@ -66,6 +66,33 @@ state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
 deep-import its private source. Manual copying is only the fallback described by
 an unknown third-party package's add-style blueprint.
 
+## Reuse Proven Patterns (rg + cp)
+
+Version-matched installed source outranks web docs or memory: it is the exact
+code shipping with this app. `node_modules/@agent-native/core/corpus/templates/`
+holds source for every first-party template, not just the one this app started
+from, so a pattern from the mail template is fair game for a tasks app. Grep
+across it, then copy a whole file as a starting point instead of writing the
+pattern from scratch:
+
+```bash
+# Find how other templates solved a similar problem
+rg -n "drag.*drop|reorder" node_modules/@agent-native/core/corpus/templates
+
+# Grab a proven action file as a starting point, then adapt names/schema
+cp node_modules/@agent-native/core/corpus/templates/mail/actions/archive-email.ts \
+   actions/archive-item.ts
+
+# Read the full framework source behind an API, not just the corpus copy
+rg -n "defineAction" node_modules/@agent-native/core/src/action.ts
+```
+
+Copying template-level app code (actions, components, skill files) is the
+expected reuse path — templates exist to be forked. This is different from
+copying `core`/`toolkit` **runtime internals**: for those, follow
+`customizing-agent-native`'s configure/compose/eject ladder instead of
+hand-duplicating framework logic.
+
 ## Useful Slugs
 
 | Need                           | Slugs                                                         |

package/corpus/templates/tasks/_gitignore

@@ -0,0 +1,39 @@
+# React Router generated types
+.react-router/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Data
+data/uploads/
+data/settings.json
+data/.sessions.json
+
+# Learnings (personal preferences and memory — use learnings.defaults.md for tracked defaults)
+learnings.md
+
+.vercel/

package/corpus/toolkit/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @agent-native/toolkit
 
+## 0.9.0
+
+### Minor Changes
+
+- 0341a7d: Add an ejectable dashboard presentation kit with cards, tables, date ranges, chart state rendering, and layout helpers.
+
+## 0.8.3
+
+### Patch Changes
+
+- 5c78d2d: Fix cramped calendar day grid under Tailwind v4 and make the date picker responsive: smaller cell size on mobile, 20% smaller on desktop, and a viewport-bounded popover width.
+
 ## 0.8.2
 
 ### Patch Changes

package/corpus/toolkit/README.md

@@ -28,6 +28,14 @@ import { ToolkitProvider } from "@agent-native/toolkit/provider";
 import { ChatHistoryList } from "@agent-native/toolkit/chat-history";
 import { PresenceBar } from "@agent-native/toolkit/collab-ui";
 import { ContextMeterView } from "@agent-native/toolkit/context-ui";
+import {
+  DataTable,
+  DateRangePicker,
+  GenericChartPanel,
+  MetricCard,
+  StatsCard,
+  buildDashboardPanelGroups,
+} from "@agent-native/toolkit/dashboard";
 import { VisualTweakControl } from "@agent-native/toolkit/design-tweaks";
 import { SharedRichEditor } from "@agent-native/toolkit/editor";
 import { VisibilityBadge } from "@agent-native/toolkit/sharing";
@@ -45,6 +53,28 @@ import `@agent-native/toolkit/chat-history.css`.
 Inside template apps, prefer local adapters such as `@/components/ui/button` so
 apps can replace their primitives without changing every callsite.
 
+## Dashboard kit
+
+`@agent-native/toolkit/dashboard` is an ejectable, presentation-only dashboard
+kit. It includes metric and stats cards, tables, a date-range picker, panel
+ordering and layout helpers, and `GenericChartPanel`. Supply rows, schema, and
+callbacks through app-owned action-backed adapters; the kit never fetches data,
+stores dashboard state, resolves credentials, or imports Core runtime APIs.
+
+Inspect or take ownership of the complete unit with:
+
+```bash
+agent-native eject inspect toolkit/dashboard
+agent-native eject toolkit/dashboard --app <app> --apply
+```
+
+For durable dashboards, use `@agent-native/core/dashboard-storage` in the app's
+server layer. Instantiate its schema and access-scoped store per app, rather
+than sharing dashboard rows between apps. Resolve panel data with a
+`PanelSourceResolver`; the built-in `program` resolver runs an app-owned data
+program and is the zero-wiring default. Provider-specific resolvers stay in the
+app that owns their credentials and query policy.
+
 ## Customize Or Take Ownership
 
 Use public props, slots, callbacks, stable classes, and local adapters first.

package/corpus/toolkit/agent-native.eject.json

@@ -133,6 +133,7 @@
         "@tabler/icons-react",
         "clsx",
         "react",
+        "recharts",
         "tailwind-merge"
       ],
       "verification": ["pnpm typecheck"]
@@ -206,6 +207,38 @@
       ],
       "verification": ["pnpm typecheck"]
     },
+    {
+      "id": "toolkit/dashboard",
+      "label": "Dashboard kit",
+      "catalog": "toolkit-ui",
+      "catalogItems": ["dashboard"],
+      "entrypoints": ["./dashboard", "./dashboard/*"],
+      "strategy": "source-copy",
+      "sourceEntries": ["src/dashboard"],
+      "targetRoot": "app/components/agent-native/toolkit",
+      "dependencies": [
+        "@radix-ui/react-select",
+        "@radix-ui/react-slot",
+        "@tabler/icons-react",
+        "class-variance-authority",
+        "clsx",
+        "react",
+        "recharts",
+        "tailwind-merge"
+      ],
+      "protectedImports": [
+        "@agent-native/toolkit/ui/button",
+        "@agent-native/toolkit/ui/card",
+        "@agent-native/toolkit/ui/select",
+        "@agent-native/toolkit/ui/skeleton",
+        "@agent-native/toolkit/ui/table",
+        "@agent-native/toolkit/utils"
+      ],
+      "verification": [
+        "pnpm --filter @agent-native/toolkit typecheck",
+        "pnpm --filter @agent-native/toolkit test"
+      ]
+    },
     {
       "id": "toolkit/editor",
       "label": "Rich editor",

package/corpus/toolkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/toolkit",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Reusable app-building UI and helpers for Agent-Native apps.",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -61,6 +61,20 @@
       "import": "./dist/collab-ui/*.js",
       "default": "./dist/collab-ui/*.js"
     },
+    "./dashboard": {
+      "types": "./dist/dashboard/index.d.ts",
+      "browser": "./dist/dashboard/index.js",
+      "development": "./dist/dashboard/index.js",
+      "import": "./dist/dashboard/index.js",
+      "default": "./dist/dashboard/index.js"
+    },
+    "./dashboard/*": {
+      "types": "./dist/dashboard/*.d.ts",
+      "browser": "./dist/dashboard/*.js",
+      "development": "./dist/dashboard/*.js",
+      "import": "./dist/dashboard/*.js",
+      "default": "./dist/dashboard/*.js"
+    },
     "./chat-history": {
       "types": "./dist/chat-history/index.d.ts",
       "browser": "./dist/chat-history/index.js",

package/corpus/toolkit/src/dashboard/DataTable.tsx

@@ -0,0 +1,273 @@
+import {
+  IconArrowsUpDown,
+  IconChevronLeft,
+  IconChevronRight,
+} from "@tabler/icons-react";
+import { useMemo, useState } from "react";
+
+import { Button } from "../ui/button.js";
+import { Card, CardContent, CardHeader, CardTitle } from "../ui/card.js";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "../ui/select.js";
+import { Skeleton } from "../ui/skeleton.js";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "../ui/table.js";
+import { cn } from "../utils.js";
+
+const DEFAULT_PAGE_SIZE_OPTIONS = [10, 25, 50, 100];
+const TABLE_MIN_HEIGHT_CLASS = "min-h-[386px]";
+
+export interface DataTableLabels {
+  noData: string;
+  rowsPerPage: string;
+  of: string;
+  previousPage: string;
+  nextPage: string;
+}
+
+export interface DataTableProps {
+  title?: string;
+  data: Record<string, unknown>[];
+  columns?: string[];
+  loading?: boolean;
+  error?: string;
+  maxRows?: number;
+  pageSizeOptions?: number[];
+  labels?: Partial<DataTableLabels>;
+}
+
+const DEFAULT_LABELS: DataTableLabels = {
+  noData: "No data available.",
+  rowsPerPage: "Rows per page",
+  of: "of",
+  previousPage: "Previous page",
+  nextPage: "Next page",
+};
+
+/** A source-agnostic, sortable and paginated dashboard table. */
+export function DataTable({
+  title,
+  data,
+  columns: columnsProp,
+  loading,
+  error,
+  maxRows,
+  pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
+  labels: labelOverrides,
+}: DataTableProps) {
+  const labels = { ...DEFAULT_LABELS, ...labelOverrides };
+  const [sortColumn, setSortColumn] = useState<string | null>(null);
+  const [sortDirection, setSortDirection] = useState<"asc" | "desc">("desc");
+  const [page, setPage] = useState(0);
+  const [pageSize, setPageSize] = useState(pageSizeOptions[0] ?? 10);
+
+  const columns = useMemo(() => {
+    if (columnsProp) return columnsProp;
+    return data.length === 0 ? [] : Object.keys(data[0]);
+  }, [columnsProp, data]);
+  const rows = useMemo(
+    () =>
+      maxRows != null && data.length > maxRows ? data.slice(0, maxRows) : data,
+    [data, maxRows],
+  );
+  const sortedRows = useMemo(() => {
+    if (!sortColumn) return rows;
+    return [...rows].sort((a, b) => {
+      const aValue = a[sortColumn];
+      const bValue = b[sortColumn];
+      if (aValue == null && bValue == null) return 0;
+      if (aValue == null) return 1;
+      if (bValue == null) return -1;
+      const comparison =
+        typeof aValue === "number" && typeof bValue === "number"
+          ? aValue - bValue
+          : String(aValue).localeCompare(String(bValue));
+      return sortDirection === "asc" ? comparison : -comparison;
+    });
+  }, [rows, sortColumn, sortDirection]);
+  const pageCount = Math.ceil(sortedRows.length / pageSize);
+  const pagedRows = sortedRows.slice(page * pageSize, (page + 1) * pageSize);
+
+  const handleSort = (column: string) => {
+    if (sortColumn === column) {
+      setSortDirection((direction) => (direction === "asc" ? "desc" : "asc"));
+    } else {
+      setSortColumn(column);
+      setSortDirection("desc");
+    }
+    setPage(0);
+  };
+
+  const content = loading ? (
+    <DataTableLoadingSkeleton />
+  ) : error ? (
+    <p className="py-4 text-sm text-destructive">{error}</p>
+  ) : data.length === 0 ? (
+    <p className="py-4 text-center text-sm text-muted-foreground">
+      {labels.noData}
+    </p>
+  ) : (
+    <div className={cn("overflow-x-auto", TABLE_MIN_HEIGHT_CLASS)}>
+      <Table>
+        <TableHeader>
+          <TableRow>
+            {columns.map((column) => (
+              <TableHead
+                key={column}
+                className="cursor-pointer select-none whitespace-nowrap hover:text-foreground"
+                onClick={() => handleSort(column)}
+              >
+                <span className="flex items-center gap-1">
+                  {column}
+                  <IconArrowsUpDown
+                    className={cn(
+                      "h-3 w-3",
+                      sortColumn === column
+                        ? "text-foreground"
+                        : "text-muted-foreground/50",
+                    )}
+                  />
+                </span>
+              </TableHead>
+            ))}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {pagedRows.map((row, index) => (
+            <TableRow key={index}>
+              {columns.map((column) => (
+                <TableCell
+                  key={column}
+                  className="max-w-[300px] truncate whitespace-nowrap"
+                >
+                  {formatValue(row[column])}
+                </TableCell>
+              ))}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+      {sortedRows.length > (pageSizeOptions[0] ?? 10) && (
+        <div className="flex items-center justify-between border-t border-border px-2 py-2 text-xs text-muted-foreground">
+          <div className="flex items-center gap-2">
+            <span>{labels.rowsPerPage}</span>
+            <Select
+              value={String(pageSize)}
+              onValueChange={(value) => {
+                setPageSize(Number(value));
+                setPage(0);
+              }}
+            >
+              <SelectTrigger className="h-6 w-16 border-border px-2 py-0 text-xs">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {pageSizeOptions.map((size) => (
+                  <SelectItem key={size} value={String(size)}>
+                    {size}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+          <div className="flex items-center gap-2">
+            <span>
+              {page * pageSize + 1}–
+              {Math.min((page + 1) * pageSize, sortedRows.length)} {labels.of}{" "}
+              {sortedRows.length}
+            </span>
+            <Button
+              aria-label={labels.previousPage}
+              variant="ghost"
+              size="icon"
+              className="h-6 w-6"
+              onClick={() => setPage((current) => current - 1)}
+              disabled={page === 0}
+            >
+              <IconChevronLeft className="h-3.5 w-3.5" />
+            </Button>
+            <Button
+              aria-label={labels.nextPage}
+              variant="ghost"
+              size="icon"
+              className="h-6 w-6"
+              onClick={() => setPage((current) => current + 1)}
+              disabled={page >= pageCount - 1}
+            >
+              <IconChevronRight className="h-3.5 w-3.5" />
+            </Button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+
+  if (!title) return content;
+  return (
+    <Card className="border-border/50 bg-card">
+      <CardHeader>
+        <CardTitle className="text-base">{title}</CardTitle>
+      </CardHeader>
+      <CardContent>{content}</CardContent>
+    </Card>
+  );
+}
+
+function formatValue(value: unknown): string {
+  if (value == null) return "-";
+  if (typeof value === "number")
+    return Number.isInteger(value) ? value.toLocaleString() : value.toFixed(4);
+  return typeof value === "object" ? JSON.stringify(value) : String(value);
+}
+
+function DataTableLoadingSkeleton() {
+  const columnWidths = ["w-24", "w-32", "w-20", "w-28"];
+  return (
+    <div className={cn("space-y-1", TABLE_MIN_HEIGHT_CLASS)}>
+      <div className="overflow-x-auto">
+        <div className="min-w-[480px]">
+          <div className="grid h-8 grid-cols-4 items-center border-b border-border px-2">
+            {columnWidths.map((width, index) => (
+              <Skeleton key={index} className={cn("h-3", width)} />
+            ))}
+          </div>
+          {Array.from({ length: 10 }).map((_, row) => (
+            <div
+              key={row}
+              className="grid h-8 grid-cols-4 items-center border-b border-border/50 px-2"
+            >
+              {columnWidths.map((width, column) => (
+                <Skeleton
+                  key={column}
+                  className={cn(
+                    "h-3",
+                    column === 0
+                      ? "w-36"
+                      : column === 2
+                        ? "ml-auto w-16"
+                        : width,
+                  )}
+                />
+              ))}
+            </div>
+          ))}
+        </div>
+      </div>
+      <div className="flex h-8 items-center justify-between border-t border-border px-2 text-xs">
+        <Skeleton className="h-3 w-28" />
+        <Skeleton className="h-3 w-24" />
+      </div>
+    </div>
+  );
+}