Standard UI Components Reference

Note: The UI components have been moved to a separate project and are no longer part of this monorepo. This document is kept for reference and describes the design principles for UI components that integrate with ObjectOS.

This document defines the standard component library for UI components. 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., "taskkanban") - _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).