UIKit

@poliglot/ui is the component library for building matrix UIs. It provides a set of React Server Components that matrices can register to render domain entities in the Poliglot workspace.

Installation

The UIKit is installed as part of a matrix UI project. When you run rars init and enable UI components, the project is configured automatically.

For manual setup:

npm install @poliglot/ui

Architecture

Matrix UIs are React Server Components bundled and deployed alongside your matrix spec. When RARS encounters a renderable entity (e.g., a task, a deal, an invoice), it looks up the component registered for that entity's type and renders it with props derived from the graph.

The rendering pipeline:

1. A ui:Renderable in your spec declares which class gets a component
2. A ui:propsQuery (using os:json) extracts props from the entity's graph data
3. The component receives those props and renders

See the UI Components guide for how to declare renderables in your matrix spec.

Components

The UIKit is built on shadcn/ui and exports all standard components. These are the building blocks for matrix UIs.

Layout

Accordion, AspectRatio, Card, Carousel, Collapsible, Drawer, Resizable, ScrollArea, Separator, Sheet, Sidebar, Tabs

Data Display

Avatar, Badge, Calendar, Chart, Empty, Mermaid, NetworkGraph, Progress, Skeleton, Table

Input

Button, Checkbox, Form, Input, InputOTP, Label, RadioGroup, Select, Slider, Switch, Textarea, Toggle, ToggleGroup

Navigation

Breadcrumb, Command, ContextMenu, DropdownMenu, HoverCard, Menubar, NavigationMenu, Pagination, Popover

Feedback

Alert, AlertDialog, Dialog, Sonner, Spinner, Tooltip

For props and usage details, see the shadcn/ui documentation. The Poliglot UIKit components match the shadcn API.

Custom Components

These components are specific to the Poliglot platform:

Mermaid: renders Mermaid diagrams from a chart string. Used in documentation and matrix visualizations.

import { Mermaid } from "@poliglot/ui/components/mermaid";

<Mermaid
  chart={`graph TD
  A[Start] --> B[End]
`}
/>;

NetworkGraph: interactive graph visualization powered by Cytoscape. Used for exploring entity relationships in the workspace.

import { NetworkGraph } from "@poliglot/ui/components/network-graph";

<NetworkGraph
  nodes={[{ id: "1", label: "Task" }]}
  edges={[{ source: "1", target: "2" }]}
  onSelectNode={node => console.log(node)}
/>;

Empty: standardized empty state component.

Spinner: loading indicator.

Building Components

Use the CLI to build and preview your components:

# Start dev server for live preview
rars ui preview

# Build component bundle for deployment
rars ui build

See the CLI docs for all options.

Theming

Components use CSS variables for theming and support both light and dark modes automatically. The workspace provides the theme context. No additional configuration is needed for deployed matrix components.

For local development, the rars ui preview dev server provides the theme context.

Constraints

Matrix components run as React Server Components in the Poliglot runtime. Some restrictions apply:

• No client-side state (useState, useEffect, etc.)
• No browser APIs (window, document, etc.)
• No external network requests from the component
• All data comes through the os:json props query defined in the matrix spec

See the UI Components guide for the full constraint model.