feat(showcase): expense-report example demonstrating filtered roll-up summaries (#1868)

Adds `showcase_expense_report` + `showcase_expense_line` — the headline demo
of `summaryOperations.filter`: one expense-line child feeds SIX parent
roll-ups, each aggregating only the lines a filter matches:

  total_amount        SUM(amount)                        every line
  approved_amount     SUM(amount) WHERE status=approved  filtered sum (equality)
  reimbursable_amount SUM(amount) WHERE billable=true     filtered sum (boolean)
  line_count          COUNT                               every line
  rejected_count      COUNT      WHERE status=rejected    filtered count (equality)
  over_limit_count    COUNT      WHERE amount>=500        filtered count (operator)

Master-detail with an inline line-item grid (like showcase_invoice), so the
interactive story — flip a line's status and watch approved/rejected/
reimbursable diverge from the unfiltered total — is drivable in the app. Seed
data is chosen so all six show distinct non-zero values on first boot. Wired
into the object registry, seed set, and the Data Model nav group.

Verified end-to-end in the running showcase: the six rollups compute the
expected values from seed, and recompute when a child line's status flips.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HbK4FqcHwp9jSwdhTtxYuC

Author: claude

examples/app-showcase/src/data/objects/expense-report.object.ts

@@ -0,0 +1,169 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * Expense Report + Expense Line — the canonical demonstration of **filtered**
+ * roll-up `summary` fields (framework#1868).
+ *
+ * A plain `summary` rolls up EVERY child row (see `showcase_invoice.total`).
+ * The power added by `summaryOperations.filter` is that ONE child object can
+ * feed SEVERAL different parent totals, each aggregating only the child rows
+ * that match a predicate — something that was impossible to express before and
+ * had to be hand-maintained (and drifted the moment a real child row was added).
+ *
+ * Here a single `showcase_expense_line` child feeds six rollups on the report:
+ *
+ *   • total_amount        SUM(amount)                        — every line
+ *   • approved_amount     SUM(amount) WHERE status=approved  — filtered sum (equality)
+ *   • reimbursable_amount SUM(amount) WHERE billable=true     — filtered sum (boolean)
+ *   • line_count          COUNT                               — every line
+ *   • rejected_count      COUNT      WHERE status=rejected    — filtered count (equality)
+ *   • over_limit_count    COUNT      WHERE amount>=500        — filtered count (operator)
+ *
+ * The engine keeps all six current server-side as lines are inserted / updated
+ * / deleted. Because each recompute re-runs the whole filtered aggregate, a
+ * line moving in or out of a predicate — e.g. a manager flipping one line's
+ * `status` from `submitted` to `approved` in the inline grid — updates the
+ * relevant totals on that write with no extra wiring. That is the interactive
+ * story to drive in the running app: edit line statuses and watch
+ * approved/rejected/reimbursable diverge from the unfiltered total.
+ */
+export const ExpenseReport = ObjectSchema.create({
+  name: 'showcase_expense_report',
+  // [ADR-0090 D1] grandfather stamp: world-writable demo object so any seeded
+  // persona (and the browser e2e) can create/edit reports without a bespoke
+  // permission set. Belonging to no permission set, it is intentionally absent
+  // from the access-matrix snapshot (cf. showcase_cascade).
+  sharingModel: 'public_read_write',
+  label: 'Expense Report',
+  pluralLabel: 'Expense Reports',
+  icon: 'wallet',
+  description: 'An expense report whose parent totals are filtered roll-ups of its line items.',
+
+  fields: {
+    name: Field.text({ label: 'Report Title', required: true, searchable: true, maxLength: 120 }),
+    employee: Field.text({ label: 'Employee', searchable: true, maxLength: 120 }),
+    status: Field.select({
+      label: 'Status',
+      required: true,
+      options: [
+        { label: 'Draft', value: 'draft', default: true, color: '#94A3B8' },
+        { label: 'Submitted', value: 'submitted', color: '#3B82F6' },
+        { label: 'Approved', value: 'approved', color: '#10B981' },
+        { label: 'Reimbursed', value: 'reimbursed', color: '#6366F1' },
+      ],
+    }),
+    submitted_on: Field.date({ label: 'Submitted On' }),
+
+    // ── Filtered roll-ups (the point of this object) ─────────────────────────
+    // Child FK is auto-detected (showcase_expense_line.expense_report), so none
+    // of these need `relationshipField`.
+
+    /** Baseline: unfiltered — the grand total of every line. */
+    total_amount: Field.summary({
+      label: 'Total',
+      summaryOperations: { object: 'showcase_expense_line', field: 'amount', function: 'sum' },
+    }),
+    /** Filtered SUM (equality) — only lines a manager has approved. */
+    approved_amount: Field.summary({
+      label: 'Approved',
+      summaryOperations: {
+        object: 'showcase_expense_line',
+        field: 'amount',
+        function: 'sum',
+        filter: { status: 'approved' },
+      },
+    }),
+    /** Filtered SUM (boolean) — only lines billable back to a client. */
+    reimbursable_amount: Field.summary({
+      label: 'Reimbursable',
+      summaryOperations: {
+        object: 'showcase_expense_line',
+        field: 'amount',
+        function: 'sum',
+        filter: { billable: true },
+      },
+    }),
+    /** Baseline: unfiltered line count. */
+    line_count: Field.summary({
+      label: 'Lines',
+      summaryOperations: { object: 'showcase_expense_line', field: 'amount', function: 'count' },
+    }),
+    /** Filtered COUNT (equality) — lines a manager rejected. */
+    rejected_count: Field.summary({
+      label: 'Rejected',
+      summaryOperations: {
+        object: 'showcase_expense_line',
+        field: 'amount',
+        function: 'count',
+        filter: { status: 'rejected' },
+      },
+    }),
+    /** Filtered COUNT (operator) — lines at or above the $500 receipt-required
+     *  threshold. Shows the FilterCondition operator form, not just equality. */
+    over_limit_count: Field.summary({
+      label: 'Over $500',
+      summaryOperations: {
+        object: 'showcase_expense_line',
+        field: 'amount',
+        function: 'count',
+        filter: { amount: { $gte: 500 } },
+      },
+    }),
+  },
+});
+
+/** Expense line item — owned by its report, entered inline in the grid. */
+export const ExpenseLine = ObjectSchema.create({
+  name: 'showcase_expense_line',
+  label: 'Expense Line',
+  pluralLabel: 'Expense Lines',
+  icon: 'receipt',
+  description: 'A single expense on a report; the parent report rolls these up with filters.',
+
+  // ADR-0055: a line's access is CONTROLLED BY ITS PARENT report — the same
+  // master-detail pattern as showcase_invoice_line. No RLS authored here; the
+  // security layer derives it from the required master_detail relationship.
+  sharingModel: 'controlled_by_parent',
+
+  fields: {
+    expense_report: Field.masterDetail('showcase_expense_report', {
+      label: 'Report',
+      required: true,
+      deleteBehavior: 'cascade',
+      // Thin, high-volume line items → the editable grid form factor. The
+      // report's filtered summaries recompute as rows are saved in this grid.
+      inlineEdit: 'grid',
+      inlineTitle: 'Expense Lines',
+    }),
+    merchant: Field.text({ label: 'Merchant', required: true, maxLength: 120 }),
+    category: Field.select({
+      label: 'Category',
+      options: [
+        { label: 'Travel', value: 'travel' },
+        { label: 'Meals', value: 'meals' },
+        { label: 'Lodging', value: 'lodging' },
+        { label: 'Supplies', value: 'supplies' },
+        { label: 'Software', value: 'software' },
+        { label: 'Other', value: 'other', default: true },
+      ],
+    }),
+    amount: Field.currency({ label: 'Amount', required: true, scale: 2, min: 0 }),
+    // Whether the expense is billable back to a client — the `billable: true`
+    // filter on the report's `reimbursable_amount` rollup reads this.
+    billable: Field.boolean({ label: 'Billable to client', defaultValue: false }),
+    // Per-line approval status — a manager approves/rejects individual lines,
+    // which is what the report's `approved_amount` / `rejected_count` filter on.
+    status: Field.select({
+      label: 'Line Status',
+      required: true,
+      options: [
+        { label: 'Submitted', value: 'submitted', default: true, color: '#3B82F6' },
+        { label: 'Approved', value: 'approved', color: '#10B981' },
+        { label: 'Rejected', value: 'rejected', color: '#EF4444' },
+      ],
+    }),
+    incurred_on: Field.date({ label: 'Incurred On' }),
+  },
+});

examples/app-showcase/src/data/objects/index.ts

@@ -7,6 +7,7 @@ export { Category } from './category.object.js';
 export { BusinessUnit } from './business-unit.object.js';
 export { Team, ProjectMembership } from './team.object.js';
 export { Product, Invoice, InvoiceLine } from './invoice.object.js';
+export { ExpenseReport, ExpenseLine } from './expense-report.object.js';
 export { FieldZoo } from './field-zoo.object.js';
 export { CascadingSelect } from './cascading-select.object.js';
 export { Preference } from './preference.object.js';

examples/app-showcase/src/data/seed/index.ts

@@ -10,6 +10,7 @@ import { Category } from '../objects/category.object.js';
 import { BusinessUnit } from '../objects/business-unit.object.js';
 import { Team, ProjectMembership } from '../objects/team.object.js';
 import { Product, Invoice, InvoiceLine } from '../objects/invoice.object.js';
+import { ExpenseReport, ExpenseLine } from '../objects/expense-report.object.js';
 import { Contact } from '../objects/contact.object.js';
 import { Inquiry } from '../objects/inquiry.object.js';
 import { FieldZoo } from '../objects/field-zoo.object.js';
@@ -300,6 +301,41 @@ const invoiceLines = defineSeed(InvoiceLine, {
   ],
 });
 
+// Expense reports + lines — the filtered-rollup demo (framework#1868). Line
+// amounts, `billable`, and per-line `status` are chosen so the report's SIX
+// summaries show visibly DIFFERENT values on first boot: the unfiltered total
+// vs the approved-only sum vs the billable-only sum, etc. Drive the interactive
+// story in the app by flipping a line's status in the inline grid and watching
+// approved_amount / rejected_count move. Merchants are unique → externalId.
+const expenseReports = defineSeed(ExpenseReport, {
+  mode: 'upsert',
+  externalId: 'name',
+  records: [
+    { name: 'EXP-2001', employee: 'Ada Lovelace', status: 'submitted', submitted_on: cel`daysAgo(5)` },
+    { name: 'EXP-2002', employee: 'Linus Torvalds', status: 'approved', submitted_on: cel`daysAgo(12)` },
+    { name: 'EXP-2003', employee: 'Grace Hopper', status: 'draft' },
+  ],
+});
+
+const expenseLines = defineSeed(ExpenseLine, {
+  mode: 'upsert',
+  externalId: 'merchant',
+  records: [
+    // EXP-2001 → total 1500.50 · approved 960 · reimbursable 512 · rejected 0 · over$500 2
+    { merchant: 'United Airlines', expense_report: 'EXP-2001', category: 'travel', amount: 620, billable: false, status: 'approved', incurred_on: cel`daysAgo(9)` },
+    { merchant: 'Marriott Downtown', expense_report: 'EXP-2001', category: 'lodging', amount: 340, billable: false, status: 'approved', incurred_on: cel`daysAgo(8)` },
+    { merchant: 'Chipotle', expense_report: 'EXP-2001', category: 'meals', amount: 28.5, billable: false, status: 'submitted', incurred_on: cel`daysAgo(8)` },
+    { merchant: 'AWS', expense_report: 'EXP-2001', category: 'software', amount: 512, billable: true, status: 'submitted', incurred_on: cel`daysAgo(7)` },
+    // EXP-2002 → total 917 · approved 825 · reimbursable 825 · rejected 1 · over$500 1
+    { merchant: 'Delta Air Lines', expense_report: 'EXP-2002', category: 'travel', amount: 780, billable: true, status: 'approved', incurred_on: cel`daysAgo(15)` },
+    { merchant: 'Uber', expense_report: 'EXP-2002', category: 'travel', amount: 45, billable: true, status: 'approved', incurred_on: cel`daysAgo(14)` },
+    { merchant: 'Staples', expense_report: 'EXP-2002', category: 'supplies', amount: 92, billable: false, status: 'rejected', incurred_on: cel`daysAgo(14)` },
+    // EXP-2003 (draft) → total 225.75 · approved 0 · reimbursable 0 · rejected 0 · over$500 0
+    { merchant: 'Hilton Garden Inn', expense_report: 'EXP-2003', category: 'lodging', amount: 210, billable: false, status: 'submitted', incurred_on: cel`daysAgo(3)` },
+    { merchant: 'Starbucks', expense_report: 'EXP-2003', category: 'meals', amount: 15.75, billable: false, status: 'submitted', incurred_on: cel`daysAgo(2)` },
+  ],
+});
+
 // Inquiries so the staff triage list (inquiry views + Contact Form page)
 // renders on first boot — the "every view renders real data" principle. One
 // per status; the `closed` row doubles as live prey for InquiryPurgeFlow.
@@ -337,4 +373,4 @@ const announcements = defineSeed(Announcement, {
   ],
 });
 
-export const ShowcaseSeedData = [accounts, contacts, inquiries, products, projects, tasks, categories, businessUnits, orgUnits, teams, memberships, fieldZoo, invoices, invoiceLines, preferences, announcements];
+export const ShowcaseSeedData = [accounts, contacts, inquiries, products, projects, tasks, categories, businessUnits, orgUnits, teams, memberships, fieldZoo, invoices, invoiceLines, expenseReports, expenseLines, preferences, announcements];

examples/app-showcase/src/ui/apps/index.ts

@@ -52,6 +52,9 @@ export const ShowcaseApp = App.create({
         { id: 'nav_accounts', type: 'object', objectName: 'showcase_account', label: 'Accounts', icon: 'building' },
         { id: 'nav_contacts', type: 'object', objectName: 'showcase_contact', label: 'Contacts', icon: 'user' },
         { id: 'nav_invoices', type: 'object', objectName: 'showcase_invoice', label: 'Invoices', icon: 'receipt' },
+        // Filtered roll-up summary demo (framework#1868): one expense-line child
+        // feeds six parent totals, each aggregating only the lines a filter matches.
+        { id: 'nav_expense_reports', type: 'object', objectName: 'showcase_expense_report', label: 'Expense Reports', icon: 'wallet' },
         { id: 'nav_products', type: 'object', objectName: 'showcase_product', label: 'Products', icon: 'package' },
         { id: 'nav_teams', type: 'object', objectName: 'showcase_team', label: 'Teams', icon: 'users' },
         { id: 'nav_categories', type: 'object', objectName: 'showcase_category', label: 'Categories', icon: 'list-tree' },