feat(spec+showcase): add 'tree' view type + business_unit org-chart example

.changeset/spec-tree-view-type.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): add a `tree` view type to the ListView schema
+
+`'tree'` is now a valid `ListView.type` (and `VisualizationType`), backed by a
+new `TreeConfigSchema` (`parentField` / `labelField` / `fields` /
+`defaultExpandedDepth`, passthrough). This lets a self-referencing object be
+served as a tree-grid; without it the runtime Zod-validates view metadata and
+silently drops `type:'tree'`. Renderer ships in objectui `@object-ui/plugin-tree`.

examples/app-showcase/objectstack.config.ts

@@ -16,7 +16,7 @@ import { ShowcaseExternalDatasource } from './src/datasources/showcase-external.
 import { ExternalCustomer, ExternalOrder } from './src/objects/external/index.js';
 import { setupShowcaseExternalDatasource } from './src/datasources/external-fixture.js';
 import { registerRecalcEndpoint } from './src/server/recalc-endpoint.js';
-import { TaskViews, ProjectViews, InquiryViews } from './src/views/index.js';
+import { TaskViews, ProjectViews, InquiryViews, BusinessUnitViews } from './src/views/index.js';
 import { ShowcaseApp } from './src/apps/index.js';
 import { ChartGalleryDashboard, OpsDashboard } from './src/dashboards/index.js';
 import { ShowcaseTaskDataset, ShowcaseProjectDataset } from './src/datasets/index.js';
@@ -153,7 +153,7 @@ export default defineStack({
  // UI
  apps: [ShowcaseApp],
  portals: allPortals,
- views: [TaskViews, ProjectViews, InquiryViews],
+ views: [TaskViews, ProjectViews, InquiryViews, BusinessUnitViews],
  pages: [ComponentGalleryPage, ProjectWorkspacePage, ProjectDetailPage, TaskWorkbenchPage, TaskTriagePage, TaskBoardPage, TaskCalendarPage, TaskGalleryPage, TaskSchedulePage, TaskTimelinePage, TaskMapPage, TaskAllViewsPage, ActiveProjectsPage, TaskDetailPage, AccountDetailPage, ReviewQueuePage, NewProjectWizardPage, MyWorkPage, SettingsPage],
  dashboards: [ChartGalleryDashboard, OpsDashboard],
  books: allBooks,

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

@@ -39,6 +39,7 @@ export const ShowcaseApp = App.create({
  { 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' },
+ { id: 'nav_business_units', type: 'object', objectName: 'showcase_business_unit', label: 'Business Units', icon: 'network' },
  { id: 'nav_field_zoo', type: 'object', objectName: 'showcase_field_zoo', label: 'Field Zoo', icon: 'shapes' },
  ],
  },

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

@@ -7,6 +7,7 @@ import { Preference } from '../objects/preference.object.js';
 import { Project } from '../objects/project.object.js';
 import { Task } from '../objects/task.object.js';
 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 { FieldZoo } from '../objects/field-zoo.object.js';
@@ -83,6 +84,24 @@ const categories = defineSeed(Category, {
  ],
 });
 
+// Org-chart hierarchy seeded by `name` external id; `parent` references another
+// record's name, building a 3-level tree the `tree` view renders.
+const businessUnits = defineSeed(BusinessUnit, {
+ mode: 'upsert',
+ externalId: 'name',
+ records: [
+ { name: 'Acme Corporation', kind: 'company', manager: 'Dana Wong', headcount: 0 },
+ { name: 'Product & Engineering', parent: 'Acme Corporation', kind: 'division', manager: 'Lena Ortiz', headcount: 0 },
+ { name: 'Platform', parent: 'Product & Engineering', kind: 'department', manager: 'Sam Patel', headcount: 12 },
+ { name: 'Frontend Guild', parent: 'Product & Engineering', kind: 'department', manager: 'Yuki Tan', headcount: 9 },
+ { name: 'Design Systems', parent: 'Frontend Guild', kind: 'team', manager: 'Priya Rao', headcount: 4 },
+ { name: 'Go-To-Market', parent: 'Acme Corporation', kind: 'division', manager: 'Marcus Bell', headcount: 0 },
+ { name: 'Sales', parent: 'Go-To-Market', kind: 'department', manager: 'Erin Cole', headcount: 18 },
+ { name: 'Enterprise Sales', parent: 'Sales', kind: 'team', manager: 'Tom Nyx', headcount: 7 },
+ { name: 'Marketing', parent: 'Go-To-Market', kind: 'department', manager: 'Aria Kim', headcount: 6 },
+ ],
+});
+
 const teams = defineSeed(Team, {
  mode: 'upsert',
  externalId: 'name',
@@ -195,4 +214,4 @@ const preferences = defineSeed(Preference, {
  ],
 });
 
-export const ShowcaseSeedData = [accounts, products, projects, tasks, categories, teams, memberships, fieldZoo, invoices, invoiceLines, preferences];
+export const ShowcaseSeedData = [accounts, products, projects, tasks, categories, businessUnits, teams, memberships, fieldZoo, invoices, invoiceLines, preferences];

examples/app-showcase/src/objects/business-unit.object.ts

@@ -0,0 +1,34 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * Business Unit — a self-referencing org-chart hierarchy. `parent` points back
+ * at the same object, so the tree has arbitrary depth (company → division →
+ * department → team). This is the canonical case for the `tree` view type:
+ * fixed-depth grouping can't express an unbounded self-referencing hierarchy.
+ */
+export const BusinessUnit = ObjectSchema.create({
+ name: 'showcase_business_unit',
+ label: 'Business Unit',
+ pluralLabel: 'Business Units',
+ icon: 'network',
+ description: 'Org-chart hierarchy — demonstrates the tree / tree-grid view over a self-referencing object.',
+
+ fields: {
+ name: Field.text({ label: 'Name', required: true, searchable: true, maxLength: 120 }),
+ parent: Field.lookup('showcase_business_unit', { label: 'Parent Unit', allowCreate: true }),
+ kind: Field.select({
+ label: 'Type',
+ options: [
+ { label: 'Company', value: 'company' },
+ { label: 'Division', value: 'division' },
+ { label: 'Department', value: 'department' },
+ { label: 'Team', value: 'team' },
+ ],
+ defaultValue: 'department',
+ }),
+ manager: Field.text({ label: 'Manager', maxLength: 120 }),
+ headcount: Field.number({ label: 'Headcount', min: 0, defaultValue: 0 }),
+ },
+});

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

@@ -4,6 +4,7 @@ export { Account } from './account.object.js';
 export { Project } from './project.object.js';
 export { Task } from './task.object.js';
 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 { FieldZoo } from './field-zoo.object.js';

examples/app-showcase/src/views/business-unit.view.ts

@@ -0,0 +1,48 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineView } from '@objectstack/spec';
+
+const data = { provider: 'object' as const, object: 'showcase_business_unit' };
+
+/**
+ * Business Unit views — a flat grid plus an Organization Chart that uses the
+ * `tree` view type to nest records by their self-referencing `parent` field.
+ */
+export const BusinessUnitViews = defineView({
+ list: {
+ label: 'All Units',
+ type: 'grid',
+ data,
+ columns: [
+ { field: 'name' },
+ { field: 'kind' },
+ { field: 'manager' },
+ { field: 'headcount' },
+ { field: 'parent' },
+ ],
+ },
+ listViews: {
+ org_chart: {
+ label: 'Organization Chart',
+ type: 'tree',
+ data,
+ columns: ['name', 'kind', 'manager', 'headcount'],
+ tree: {
+ parentField: 'parent',
+ labelField: 'name',
+ fields: ['kind', 'manager', 'headcount'],
+ // Roots + one level expanded by default; deeper teams expand on click.
+ defaultExpandedDepth: 1,
+ },
+ },
+ },
+ formViews: {
+ default: {
+ type: 'simple',
+ data,
+ sections: [
+ { label: 'Unit', columns: 2, fields: ['name', 'parent', 'kind', 'manager', 'headcount'] },
+ ],
+ },
+ },
+});

examples/app-showcase/src/views/index.ts

@@ -3,3 +3,4 @@
 export { TaskViews } from './task.view.js';
 export { ProjectViews } from './project.view.js';
 export { InquiryViews } from './inquiry.view.js';
+export { BusinessUnitViews } from './business-unit.view.js';

packages/spec/api-surface.json

@@ -3282,6 +3282,7 @@
  "TransitionConfigSchema (const)",
  "TransitionPreset (type)",
  "TransitionPresetSchema (const)",
+ "TreeConfigSchema (const)",
  "Typography (type)",
  "TypographySchema (const)",
  "UrlNavItem (type)",

packages/spec/src/ui/view.zod.ts

@@ -225,6 +225,7 @@ export const VisualizationTypeSchema = lazySchema(() => z.enum([
  'gantt',
  'map',
  'chart',
+ 'tree',
 ]).describe('Visualization type that users can switch to'));
 
 /**
@@ -433,6 +434,23 @@ export const GanttConfigSchema = lazySchema(() => z.object({
 // stripped here, so a renderer release no longer has to wait on a spec release.
 }).passthrough());
 
+/**
+ * Tree (tree-grid) Settings
+ *
+ * Renders a self-referencing object as an indented, expand/collapse tree-grid.
+ * Flat records are nested via a single-parent pointer field (`parentField`).
+ * Unlike a fixed-depth `grouping`, a tree handles arbitrary depth (org charts,
+ * category trees, BOMs, nested comments). When `parentField` is omitted the
+ * renderer auto-detects the object's `tree`/self-reference field.
+ */
+export const TreeConfigSchema = lazySchema(() => z.object({
+ parentField: z.string().optional().describe('Single-parent pointer field (auto-detected from the object schema when omitted)'),
+ labelField: z.string().optional().describe('Field rendered indented in the first column (defaults to "name")'),
+ fields: z.array(z.string()).optional().describe('Additional fields rendered as flat columns alongside the label'),
+ defaultExpandedDepth: z.number().int().min(0).optional().describe('Initial expansion depth (0 = roots only; omit = expand all)'),
+// Forward-compatible: let renderer-ahead config knobs reach plugin-tree.
+}).passthrough());
+
 /**
  * Navigation Mode Enum
  * Defines how to navigate to the detail view from a list item.
@@ -502,7 +520,8 @@ export const ListViewSchema = lazySchema(() => z.object({
  'timeline', // Chronological Stream (Feed)
  'gantt', // Project Timeline
  'map', // Geospatial
- 'chart' // Aggregate visualisation
+ 'chart', // Aggregate visualisation
+ 'tree' // Self-referencing hierarchy (tree-grid)
  ]).default('grid'),
 
  /** Data Source Configuration */
@@ -552,6 +571,7 @@ export const ListViewSchema = lazySchema(() => z.object({
  gallery: GalleryConfigSchema.optional(),
  timeline: TimelineConfigSchema.optional(),
  chart: ListChartConfigSchema.optional(),
+ tree: TreeConfigSchema.optional(),
 
  /** View Metadata (Airtable-style view management) */
  description: I18nLabelSchema.optional().describe('View description for documentation/tooltips'),