@opensaas/stack-ui

Composable React UI components for OpenSaas Stack, built with Radix UI and shadcn/ui.

Installation

``bash
pnpm add @opensaas/stack-ui
`

Features

- 🎨 Four Levels of Abstraction - Primitives, Fields, Standalone Components, Full Admin UI
- ♿ Accessible - Built with Radix UI primitives
- 🎯 Type-Safe - Full TypeScript support
- 🎨 Customizable - Tailwind CSS v4 with CSS variables
- 📦 Tree-Shakeable - Import only what you need
- 🧩 Composable - Mix and match components

Package Exports

`typescript
// Primitives (shadcn/ui components)
import { Button, Input, Card, Table, Dialog } from '@opensaas/stack-ui/primitives'

// Field components (OpenSaas-aware)
import { TextField, SelectField, RelationshipField } from '@opensaas/stack-ui/fields'

// Standalone components (complete features)
import { ItemCreateForm, ListTable, SearchBar } from '@opensaas/stack-ui/standalone'

// Full components (page-level)
import { Dashboard, ListView, ItemForm, AdminUI } from '@opensaas/stack-ui'

// Server utilities
import { getAdminContext } from '@opensaas/stack-ui/server'

// Utility functions
import { cn, formatListName, formatFieldName } from '@opensaas/stack-ui/lib/utils'

// Styles
import '@opensaas/stack-ui/styles'
`

Architecture

$3

Low-level UI components based on Radix UI and shadcn/ui.

Available Components:

- Button - Buttons with variants
- Input - Text inputs
- Label - Form labels
- Card - Content containers
- Table - Data tables
- Dialog - Modal dialogs
- Select - Dropdown selects
- Checkbox - Checkboxes

Example:

`tsx
import { Button, Card, CardHeader, CardTitle, CardContent } from '@opensaas/stack-ui/primitives'
;

Welcome


Get Started


`

$3

OpenSaas-aware form fields with validation and access control.

Available Fields:

- TextField
- IntegerField
- CheckboxField
- SelectField
- PasswordField
- TimestampField
- RelationshipField

Example:

`tsx
import { TextField, SelectField } from '@opensaas/stack-ui/fields'
;



name="role"
label="Role"
value={role}
onChange={setRole}
options={[
{ label: 'Admin', value: 'admin' },
{ label: 'User', value: 'user' },
]}
/>



`

$3

Complete, reusable components for common admin tasks.

Available Components:

#### ItemCreateForm

`tsx
import { ItemCreateForm } from '@opensaas/stack-ui/standalone'
; fields={config.lists.Post.fields}
onSubmit={async (data) => {
const post = await createPost(data)
return { success: !!post }
}}
onCancel={() => router.back()}
/>
`

#### ItemEditForm

`tsx
import { ItemEditForm } from '@opensaas/stack-ui/standalone'
; fields={config.lists.Post.fields}
initialData={post}
onSubmit={async (data) => {
const updated = await updatePost(post.id, data)
return { success: !!updated }
}}
/>
`

#### ListTable

`tsx
import { ListTable } from '@opensaas/stack-ui/standalone'
; items={posts}
fieldTypes={{ title: 'text', status: 'select' }}
columns={['title', 'status']}
onRowClick={(post) => router.push(/posts/${post.id})}
sortable
/>
`

#### SearchBar

`tsx
import { SearchBar } from '@opensaas/stack-ui/standalone'
; fetchPosts({ search: query })} placeholder="Search posts..." />
`

#### DeleteButton

`tsx
import { DeleteButton } from '@opensaas/stack-ui/standalone'
; onDelete={async () => {
await deletePost(postId)
return { success: true }
}}
itemName="post"
/>
`

$3

Complete admin interface with routing and navigation.

`tsx
import { AdminUI } from '@opensaas/stack-ui'
; context={context}
params={params?.admin}
searchParams={searchParams}
basePath="/admin"
serverAction={handleServerAction}
/>
`

Component Registry

Extend or override field components:

`tsx
import { registerFieldComponent } from '@opensaas/stack-ui'
import { ColorPickerField } from './components/ColorPickerField'

// Register globally
registerFieldComponent('color', ColorPickerField)

// Use in config
fields: {
themeColor: text({
ui: { fieldType: 'color' },
})
}

// Or override per-field
fields: {
slug: text({
ui: { component: SlugField },
})
}
`

Theming

All components use Tailwind CSS v4 with CSS variables:

`css
/ app/globals.css /
@import '@opensaas/stack-ui/styles';

:root {
--background: 0 0% 100%;
--foreground: 0 0% 3.9%;
--primary: 0 0% 9%;
--primary-foreground: 0 0% 98%;
--destructive: 0 84.2% 60.2%;
--destructive-foreground: 0 0% 98%;
--muted: 0 0% 96.1%;
--muted-foreground: 0 0% 45.1%;
--accent: 0 0% 96.1%;
--accent-foreground: 0 0% 9%;
--border: 0 0% 89.8%;
--input: 0 0% 89.8%;
--ring: 0 0% 3.9%;
}

.dark {
--background: 0 0% 3.9%;
--foreground: 0 0% 98%;
/ ... /
}
`

Accessibility

All components follow WAI-ARIA guidelines:

- Proper semantic HTML
- ARIA attributes
- Keyboard navigation
- Focus management
- Screen reader support

TypeScript

Full TypeScript support with exported types:

`typescript
import type {
FieldComponent,
FieldComponentProps,
ItemCreateFormProps,
ListTableProps,
AdminUIProps,
} from '@opensaas/stack-ui'
``

Examples

- Blog Example - Basic usage with full AdminUI
- Custom Field Example - Custom field components
- Composable Dashboard - Using standalone components

Learn More

- Composability Guide - Complete guide to all four levels
- API Reference - Full API documentation
- OpenSaas Stack - Stack overview

License

MIT