docs: Complete specification documentation with UI layer and enhanced coverage

[Copilot]

Specification documents had broken references, incomplete coverage of UI layer metadata, and inconsistent depth across specifications.

Changes

Created Missing UI Layer Specifications (+4,481 lines)

• page.md (629 lines) - List, detail, dashboard, custom page types with layout configurations
• view.md (938 lines) - Saved queries with kanban, calendar, chart, pivot visualizations
• form.md (970 lines) - Create, edit, clone, wizard forms with validation and conditional fields
• report.md (1,005 lines) - Tabular, summary, matrix, chart, dashboard reports with aggregations
• menu.md (939 lines) - Main, sidebar, dropdown, context, toolbar menu types with permissions

Expanded Existing Specifications

• app.md - 47→758 lines: Multi-app architecture, feature flags, integration settings, permission sets
• query-language.md - Added 434 lines: Offset/cursor/keyset pagination strategies with implementation examples

Updated Core Documentation

• index.md - Added "User Interface Layer" section referencing all UI specs
• metadata-standard.md - Added UI metadata types to taxonomy, expanded file organization structure, updated naming convention table (6→11 types)

Result

Metric	Before	After
Total Lines	5,630	11,488
Specifications	11	17
Broken References	5	0
UI Coverage	0%	100%

All specs now follow consistent structure: root properties table, multiple complete examples, best practices, AI context blocks, cross-references.

Example: Page Definition

# File: sales_dashboard.page.yml
label: Sales Dashboard
type: dashboard
icon: standard:dashboard

widgets:
  - type: metric
    title: Total Revenue
    position: { row: 0, col: 0, width: 3, height: 2 }
    data_source:
      object: order
      aggregation:
        field: amount
        function: sum

  - type: chart
    title: Monthly Trend
    visualization:
      chart_type: line
      x_axis: { field: order_date, group_by: month }
      y_axis: { field: amount, function: sum }

Original prompt

重新审视和整理所有的规范文档

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[github-actions]

⚠️ No Changeset Found

This PR does not include a changeset file.
If this PR includes user-facing changes, please add a changeset by running:

pnpm changeset

[Copilot]

Pull request overview

This PR completes the ObjectQL specification documentation by adding comprehensive UI layer specifications and expanding existing documentation. The changes transform the specification from primarily backend-focused to a complete full-stack metadata standard covering data, logic, and presentation layers.

Changes:

• Added 5 new UI layer specifications (page, view, form, report, menu) totaling 4,481 lines with comprehensive examples and best practices
• Expanded app.md from 47 to 758 lines to cover multi-app architecture, feature flags, and integration settings
• Added 434 lines to query-language.md documenting offset/cursor/keyset pagination strategies with implementation examples
• Updated metadata-standard.md and index.md to include UI layer taxonomy and cross-references

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
view.md	Defines saved queries, filters, and visualizations (list, kanban, calendar, chart, pivot views). Comprehensive but missing documentation for $start_of_last_year dynamic value used in examples.
form.md	Defines data entry layouts with validation and conditional fields. Contains undocumented line_items section type and address field type used in examples.
report.md	Defines analytics and data exports (tabular, summary, matrix, chart, dashboard reports). Missing dynamic value documentation and contains raw SQL example that may contradict ObjectQL's database-agnostic architecture.
page.md	Defines UI pages and layouts (list, detail, dashboard, custom pages). Well-structured with consistent examples.
menu.md	Defines navigation structure (main, sidebar, dropdown, context, toolbar menus). Comprehensive coverage of menu types and permissions.
app.md	Expanded to cover multi-app architecture, feature flags, permission sets, and integration settings. Excellent progression from minimal to complete examples.
query-language.md	Added pagination section covering offset, cursor, and keyset strategies with detailed implementation examples and best practices.
metadata-standard.md	Updated to include UI metadata types in taxonomy and expanded file organization structure. Naming convention table properly updated with all 5 new UI types.
index.md	Added "User Interface Layer" and "Application Organization" sections with proper cross-references to new specifications.

[Copilot]

The dynamic value $start_of_last_year is used in the example but is not documented in the "Dynamic Values" section (9.2 Date Functions). The documented date functions include $start_of_year and $end_of_year for the current year, and relative periods like $last_12_months, but $start_of_last_year is missing. This should either be documented in section 9.2, or the example should be updated to use a documented value like $start_of_year with an offset or $last_12_months.

[Copilot]

The dynamic value $start_of_last_year is used in the example but is not documented in a common location accessible to report definitions. Consider documenting all available dynamic date values in a central reference or ensuring consistency with view.md's dynamic values documentation.

[Copilot]

The section type line_items is used in this example but is not defined in the "Form Sections" documentation (section 3). The example shows a type: line_items property on a section, which appears to be a specialized section for managing related records (like order line items), but this type is not documented alongside other section properties like collapsible and visible_when in section 3.

[Copilot]

The field type address is used in this example but is not documented in section 4.2 "Field Types". The documented field types include text, email, phone, number, date, select, lookup, file, etc., but address is not listed. This should either be documented as a field type or the example should be clarified (e.g., if it's a composite field or requires special configuration).

Suggested change

	type: address
	type: text

[Copilot]

The inclusion of raw SQL in the custom_query data source type appears to contradict the ObjectQL architecture principle of being a "Database Compiler" rather than allowing direct SQL. According to the coding guidelines, "packages/foundation/core must NEVER contain dialect-specific SQL string concatenation. All DB-specific logic belongs in packages/drivers/*." While this is documentation rather than implementation, showing raw SQL as a configuration option may encourage practices that bypass ObjectQL's database-agnostic abstraction layer. Consider either removing this example, marking it as an advanced/escape-hatch feature with clear warnings, or clarifying that custom queries should still be expressed through ObjectQL's query language DSL.