Standard UI Components Reference

This document defines the standard component library for @objectos/ui. These components are the reference implementations for the View & Layout Specifications.

---

1. Page Architecture

The top-level system for composing screens from Widgets and Layouts. Driven by *.page.yml.

ObjectPage

The master controller for any URL-addressable page in the application.

• Props:
  • pageId: string (e.g., "dashboard-sales") - The ID of the page definition to load.
  • context: Record<string, any> - Optional global variable to pass to widgets (e.g., { recordId: "123" }).
• Behavior:
  1. Loads *.page.yml from the Metadata Kernel.
  2. Resolves permissions (can the user see this page?).
  3. Injects the PageContext provider.
  4. Renders the appropriate Layout renderer.

DashboardLayout

Implements: layout: dashboard / layout: grid

A Responsive Grid Layout Engine (based on react-grid-layout or CSS Grid).

• Features:
  • Grid System: 12-column grid.
  • Responsive: Stacks widgets on mobile, respects (x, y, w, h) on desktop.
  • Editable: (Future) Allows dragging widgets to rearrange if user has "Customize Page" permission.

SingleColumnLayout

Implements: layout: single_column / layout: list

A simple stack layout, mostly used for Wiki-style pages or Mobile app views.

---

2. Page Components (Widgets)

These are the "Blocks" that live inside a Layout. In *.page.yml, these are the items in the components array.

WidgetMetric

Type: metric Displays a single KPI with trend indicator.

• Props: label, value (expression or query), trend, format.
• UI: A compact card (Card, CardHeader, CardContent).

WidgetChart

Type: chart Renders a visualization.

• Props: chart_id.
• Behavior: Use the chart_id to fetch the Chart definition (*.chart.yml), then renders the appropriate Visualization Primitive (see Section 7).

WidgetView

Type: view Embeds a full ObjectView inside a dashboard tile.

• Props: view_id OR (object, view).
• Behavior: Renders the <ObjectView /> component (see Section 3) within a constrained container. Key difference: The toolbar might be simplified (e.g., no global search) to fit into a widget.

WidgetHtml

Type: html / markdown Renders static or dynamic content.

• Props: content (HTML/Markdown string).

---

3. View Architecture

The system for rendering Object Data Collections. Can appear standalone (as a full page) or inside a Widget.

ObjectView

The "Switchboard" component. It connects to the Metadata Registry, fetches the requested view definition (YAML), and renders the appropriate concrete View Component.

• Props:
  • objectName: string (e.g., "tasks")
  • viewName: string (e.g., "task_kanban") - Optional, defaults to object's default view
  • initialFilter: FindOptions - Optional runtime filters
• Behavior:
  1. Loads *.view.yml.
  2. Resolves type (e.g., kanban).
  3. Renders <ObjectKanbanView config={...} />.

---

4. View Component Library

These "Smart Components" implement the specific logic for each View Type defined in *.view.yml.

ObjectGridView

Implements: type: list, type: grid

A high-density, interactive data table based on AG Grid.

• Features:
  • Advanced Layout: Supports Tabs for switching Views (e.g., "Outline", "Summary").
  • Row Drag & Drop: Manual reordering of records.
  • Selection: Checkbox selection with "Select All" and Indeterminate states.
  • Cell Rendering:
    • Status: Visual badges with icons.
    • User/Reviewer: User avatars or dropdown assignment.
    • Progress: visual progress bars or drag handles.
  • Columns:
    • Visibility Control: Users can toggle columns via dropdown.
    • Resizing & Sorting: Built-in AG Grid capabilities.
  • Pagination: Custom footer with "Rows per page" and navigation controls.
• Config Support: columns, sort, filters, row_actions, bulk_actions, tabs.

ObjectKanbanView

Implements: type: kanban

A drag-and-drop board for stage-based management.

• Features:
  • Grouping: Buckets records by group_by field (Select/Lookup).
  • Drag & Drop: Updates the group_by field on drop.
  • Summaries: Column headers show count/sum (e.g., "Expected Revenue").
• Config Support: group_by, card, columns (colors, limits).

ObjectCalendarView

Implements: type: calendar

A full-sized calendar for date-based records.

• Features:
  • Views: Month, Week, Day, Agenda.
  • DnD: Drag to reschedule (update start_date / end_date).
  • Events: Color-coded based on color_mapping.
• Config Support: start_date_field, end_date_field, color_mapping.

ObjectTimelineView

Implements: type: timeline

A Gantt-chart style visualization for project planning.

• Features:
  • Dependencies: Renders connecting lines if dependency field exists.
  • Resizing: Drag edge to change duration.
  • Grouping: Group rows by User or Project.
• Config Support: start_date_field, end_date_field, group_by.

ObjectGalleryView

Implements: type: card

A responsive grid of cards, ideal for visual assets or mobile views.

• Features:
  • Cover Image: Renders large media preview.
  • Responsive: Reflows from 1 column (mobile) to N columns (desktop).
• Config Support: card (title, subtitle, image).

ObjectDetailView

Implements: type: detail

A read-only presentation of a single record.

• Features:
  • Sections: Layout grouping (2-col, 1-col).
  • Related Lists: Renders child records in sub-grids (e.g., "Project Tasks").
  • Activity Timeline: System generated history and comments.
• Config Support: sections, related_lists.

ObjectFormView

Implements: type: form

A full-featured editor for creating or updating records.

• Features:
  • Validation: Client-side (Zod) + Server-side error mapping.
  • Conditional Fields: Hides inputs based on other field values.
  • Layout: Respects the same section layout as Detail View.
• Config Support: sections, visible_if.

---

5. Layout & Shell

Building blocks for the outer application shell and view wrappers.

ViewToolbar

The header bar rendered above any view.

• Props: title, actions, viewSwitcherOptions.
• Contains:
  • Breadcrumbs: Navigation path.
  • View Switcher: Dropdown to change current view.
  • Global Actions: "New Record", "Import/Export".

FilterBuilder

A complex filter construction UI.

• Features:
  • Add/Remove criteria rows.
  • Field-aware method selection (e.g., Date fields show "Before", "After"; Text shows "Contains").
  • "And/Or" logic groups.

---

6. Field System

The Field component is the factory that decides which specific widget to render inside Forms, Cells, and Cards.

Import: import { Field } from '@objectos/ui/components/fields/Field'

ObjectQL Type	UI Component	Usage
text, string	TextField	Single-line input.
textarea	TextAreaField	Multi-line text.
email, url, phone	TextField	Input with specific validation/masking.
number, integer	NumberField	Numeric input with step.
currency, percent	NumberField	Formatted numeric display.
boolean	BooleanField	Checkbox (Grid/List) or Switch (Form).
date, datetime	DateField	Popover calendar picker.
select	SelectField	Dropdown or Command Palette.
lookup, master_detail	LookupField	Async searchable select for related records.
image, file	FileUploadField	Drag-and-drop uploader + Preview.
formula	ReadOnlyField	Display-only calculated value.

---

7. Visualization Primitives

Low-level charting components used by WidgetChart.

ChartAreaInteractive

Interactive area chart for trends.

ChartBarInteractive

Bar chart for categorical comparisons.

ChartDonut

Donut/Pie chart for part-to-whole analysis.

---

8. UI Atoms

We strictly use Tailwind CSS and Radix UI (shadcn/ui) primitives.

• src/components/ui/: Low-level atoms.
  • button.tsx, input.tsx, dialog.tsx, popover.tsx, calendar.tsx.
• Styling: All components must use CSS variables for theming (--primary, --radius).