Merge pull request #7 from objectql/copilot/add-page-metadata-support

Author: hotlong

docs/spec/metadata-format.md

@@ -374,3 +374,155 @@ sort:
   - - budget
     - desc
 ```
+
+## 8. Page Definition
+
+Page files define user interface pages or dashboards that display data and visualizations. They use the naming convention `*.page.yml` or `*.page.yaml`.
+
+Similar to Airtable's interface builder, pages allow you to compose various components (charts, tables, forms) into cohesive user experiences.
+
+### 8.1 Root Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `name` | `string` | **Required.** Unique API name of the page. |
+| `label` | `string` | Human-readable label for the page. |
+| `description` | `string` | Description of the page's purpose. |
+| `icon` | `string` | Icon identifier for the page (e.g., `dashboard`, `table`, `chart`). |
+| `layout` | `string` | Layout type: `grid`, `flex`, `stack`, or `tabs`. Default: `grid`. |
+| `components` | `array` | Array of page components to display. |
+| `settings` | `object` | Layout-specific settings (e.g., grid columns, gaps, responsive behavior). |
+
+### 8.2 Page Components
+
+Components are defined as objects with a `type` and optional `props`:
+
+```yaml
+components:
+  - type: chart
+    props:
+      chartName: projects_by_status
+  - type: table
+    props:
+      object: projects
+      fields:
+        - name
+        - status
+        - priority
+```
+
+**Common Component Types:**
+- `chart`: Display a chart visualization (requires `chartName` prop)
+- `table`: Display a data table (requires `object` prop)
+- `form`: Display a data entry form
+- `text`: Display static text or markdown content
+- `custom`: Custom component implementation
+
+### 8.3 Layout Types
+
+**Grid Layout**: Responsive grid with configurable columns
+
+**Flex Layout**: Flexible box layout for responsive designs
+
+**Stack Layout**: Vertical or horizontal stack of components
+
+**Tabs Layout**: Tabbed interface for organizing multiple views
+
+### 8.4 Example Page Definitions
+
+#### Dashboard with Charts
+
+```yaml
+name: projects_dashboard
+label: Projects Dashboard
+description: Overview of all projects with charts and task tracking
+icon: dashboard
+layout: grid
+components:
+  - type: chart
+    props:
+      chartName: projects_by_status
+  - type: chart
+    props:
+      chartName: projects_by_priority
+  - type: chart
+    props:
+      chartName: project_budget
+  - type: chart
+    props:
+      chartName: tasks_completion
+  - type: table
+    props:
+      object: projects
+      fields:
+        - name
+        - status
+        - priority
+        - start_date
+        - budget
+settings:
+  gridColumns: 2
+  gap: 20
+  responsive: true
+```
+
+#### Simple Detail Page
+
+```yaml
+name: project_detail
+label: Project Details
+description: Detailed view of a single project
+icon: file
+layout: stack
+components:
+  - type: form
+    props:
+      object: projects
+      mode: view
+  - type: table
+    props:
+      object: tasks
+      filters:
+        - - project
+          - =
+          - $current.id
+settings:
+  direction: vertical
+  gap: 16
+```
+
+#### Tabbed Interface
+
+```yaml
+name: project_tabs
+label: Project Workspace
+description: Tabbed interface for project management
+icon: layers
+layout: tabs
+components:
+  - type: tab
+    props:
+      label: Overview
+      children:
+        - type: chart
+          props:
+            chartName: projects_by_status
+  - type: tab
+    props:
+      label: Tasks
+      children:
+        - type: table
+          props:
+            object: tasks
+  - type: tab
+    props:
+      label: Budget
+      children:
+        - type: chart
+          props:
+            chartName: project_budget
+settings:
+  defaultTab: 0
+  tabPosition: top
+```
+

examples/project-management/src/projects_dashboard.page.yml

@@ -0,0 +1,31 @@
+name: projects_dashboard
+label: Projects Dashboard
+description: Overview of all projects with charts and task tracking
+icon: dashboard
+layout: grid
+components:
+  - type: chart
+    props:
+      chartName: projects_by_status
+  - type: chart
+    props:
+      chartName: projects_by_priority
+  - type: chart
+    props:
+      chartName: project_budget
+  - type: chart
+    props:
+      chartName: tasks_completion
+  - type: table
+    props:
+      object: projects
+      fields:
+        - name
+        - status
+        - priority
+        - start_date
+        - budget
+settings:
+  gridColumns: 2
+  gap: 20
+  responsive: true

packages/metadata/src/plugins/objectql.ts

@@ -1,7 +1,7 @@
 import * as yaml from 'js-yaml';
 import * as path from 'path';
 import { MetadataLoader } from '../loader';
-import { ObjectConfig, ChartConfig } from '../types';
+import { ObjectConfig, ChartConfig, PageConfig } from '../types';
 
 export function registerObjectQLPlugins(loader: MetadataLoader) {
     // Objects
@@ -192,6 +192,32 @@ export function registerObjectQLPlugins(loader: MetadataLoader) {
             }
         }
     });
+
+    // Pages
+    loader.use({
+        name: 'page',
+        glob: ['**/*.page.yml', '**/*.page.yaml'],
+        handler: (ctx) => {
+            try {
+                const doc = yaml.load(ctx.content) as any;
+                if (!doc) return;
+
+                if (doc.name) {
+                    registerPage(ctx.registry, doc, ctx.file, ctx.packageName);
+                } else {
+                    for (const [key, value] of Object.entries(doc)) {
+                        if (value && !Array.isArray(value) && typeof value === 'object') {
+                            const page = value as any;
+                            if (!page.name) page.name = key;
+                            registerPage(ctx.registry, page, ctx.file, ctx.packageName);
+                        }
+                    }
+                }
+            } catch (e) {
+                console.error(`Error loading page from ${ctx.file}:`, e);
+            }
+        }
+    });
 }
 
 function registerObject(registry: any, obj: any, file: string, packageName?: string) {
@@ -224,3 +250,13 @@ function registerChart(registry: any, chart: any, file: string, packageName?: st
     });
 }
 
+function registerPage(registry: any, page: any, file: string, packageName?: string) {
+    registry.register('page', {
+        type: 'page',
+        id: page.name,
+        path: file,
+        package: packageName,
+        content: page
+    });
+}
+

packages/metadata/src/types.ts

@@ -114,3 +114,21 @@ export interface ChartConfig {
     filters?: any[];
     sort?: [string, 'asc' | 'desc'][];
 }
+
+export type PageLayoutType = 'grid' | 'flex' | 'stack' | 'tabs';
+
+export interface PageComponent {
+    type: string;
+    props?: Record<string, any>;
+    children?: PageComponent[];
+}
+
+export interface PageConfig {
+    name: string;
+    label?: string;
+    description?: string;
+    icon?: string;
+    layout?: PageLayoutType;
+    components?: PageComponent[];
+    settings?: Record<string, any>;
+}

packages/metadata/test/fixtures/dashboard.page.yml

@@ -0,0 +1,18 @@
+name: dashboard
+label: Dashboard
+description: Main dashboard page with charts and metrics
+icon: dashboard
+layout: grid
+components:
+  - type: chart
+    props:
+      chartName: projects_by_status
+  - type: chart
+    props:
+      chartName: projects_by_priority
+  - type: table
+    props:
+      object: projects
+settings:
+  gridColumns: 2
+  gap: 16

packages/metadata/test/index.test.ts

@@ -102,3 +102,27 @@ describe('Chart Metadata Loader', () => {
         expect(chart.yAxisKeys).toEqual(['value']);
     });
 });
+
+describe('Page Metadata Loader', () => {
+    it('should load page metadata from .page.yml files', () => {
+        const registry = new MetadataRegistry();
+        const loader = new MetadataLoader(registry);
+        
+        registerObjectQLPlugins(loader);
+
+        const fixturesDir = path.join(__dirname, 'fixtures');
+        loader.load(fixturesDir);
+
+        const page = registry.get('page', 'dashboard');
+        expect(page).toBeDefined();
+        expect(page.name).toBe('dashboard');
+        expect(page.label).toBe('Dashboard');
+        expect(page.description).toBe('Main dashboard page with charts and metrics');
+        expect(page.icon).toBe('dashboard');
+        expect(page.layout).toBe('grid');
+        expect(page.components).toBeDefined();
+        expect(page.components).toHaveLength(3);
+        expect(page.settings).toBeDefined();
+        expect(page.settings.gridColumns).toBe(2);
+    });
+});