PSA/packages/ui-kit/README.md

@alga-psa/ui-kit

Zero-dependency React component library for Alga extensions. All components use CSS custom properties for theming and work seamlessly inside extension iframes.

See the showcase extension (ee/extensions/showcase) for interactive demos of every component.

Install

Import the theme stylesheet once at the root of your app:

import '@alga-psa/ui-kit/theme.css';

---

Theme Tokens

Tokens are exposed as CSS variables. When running inside an extension iframe the host automatically injects them into :root.

Variable	Light	Dark	Purpose
--alga-bg	#ffffff	#0b0f14	Background
--alga-fg	#111111	#e5e7eb	Foreground / text
--alga-muted	#f5f5f7	#0f1720	Muted background
--alga-muted-fg	#4b5563	#9ca3af	Muted text
--alga-primary	#9855ee	#8a4dea	Primary (purple)
--alga-primary-foreground	#ffffff	#ffffff	Text on primary
--alga-secondary	#53d7fa	#40cff9	Secondary (blue)
--alga-secondary-foreground	#111111	#0b0f14	Text on secondary
--alga-border	#e5e7eb	#1f2937	Borders
--alga-radius	8px	8px	Border radius
--alga-danger	#dc2626	#ef4444	Danger / error
--alga-warning	#d97706	#f59e0b	Warning
--alga-success	#16a34a	#22c55e	Success

You can also access tokens programmatically:

import { tokens } from '@alga-psa/ui-kit';

tokens.primary   // 'var(--alga-primary)'
tokens.bg        // 'var(--alga-bg)'

---

Components

Core

Button

Themed button with multiple variants and sizes.

Prop	Type	Default	Description
variant	'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link' | 'soft' | 'dashed'	'primary'	Visual style
size	'xs' | 'sm' | 'md' | 'lg' | 'icon'	'md'	Controls padding and font size

<Button variant="secondary" size="sm">Save</Button>

Text

Typography component with size, tone, and weight presets.

Prop	Type	Default	Description
as	'span' | 'p' | 'label' | 'strong'	'span'	HTML element to render
size	'xs' | 'sm' | 'md' | 'lg'	'md'	Font size preset
tone	'default' | 'muted' | 'danger' | 'warning' | 'success'	'default'	Text colour
weight	400 | 500 | 600 | 700	400	Font weight

<Text as="p" size="lg" tone="muted" weight={600}>Hello</Text>

Card

Bordered container with background, shadow, and rounded corners. Extends standard <div> attributes.

<Card style={{ padding: 24 }}>Content here</Card>

Badge

Small pill-shaped label for status indicators.

Prop	Type	Default	Description
tone	'default' | 'info' | 'success' | 'warning' | 'danger'	'default'	Colour scheme

<Badge tone="success">Active</Badge>

Alert, AlertTitle, AlertDescription

Contextual alert banner with optional icon.

Prop	Type	Default	Description
tone	'info' | 'success' | 'warning' | 'danger'	'info'	Visual tone
showIcon	boolean	true	Show tone-specific icon

<Alert tone="warning">
  <AlertTitle>Heads up</AlertTitle>
  <AlertDescription>This action cannot be undone.</AlertDescription>
</Alert>

Separator

Thin divider line for separating content.

Prop	Type	Default	Description
orientation	'horizontal' | 'vertical'	'horizontal'	Direction of the line
style	CSSProperties	—	Additional inline styles

---

Form

Input

Text input with error state support.

Prop	Type	Default	Description
error	boolean	—	Show error styling
errorMessage	string	—	Error message displayed below input

<Input placeholder="Email" error={!!err} errorMessage={err} />

TextArea

Multi-line text input. Extends <textarea> attributes.

Prop	Type	Default	Description
error	boolean	—	Show error border
errorMessage	string	—	Error text below the field
resize	'none' | 'vertical' | 'horizontal' | 'both'	'vertical'	Resize behaviour

CustomSelect

Dropdown with search filtering.

Prop	Type	Default	Description
options	SelectOption[]	—	Available options
value	string	—	Selected value
onChange	(value: string) => void	—	Change callback
placeholder	string	—	Placeholder text
searchable	boolean	true	Enable search filtering
disabled	boolean	false	Disable the select

SearchInput

Input with built-in search icon and optional debounce.

Prop	Type	Default	Description
onSearch	(value: string) => void	—	Debounced search callback
debounceMs	number	300	Debounce delay in ms
size	'sm' | 'md'	'md'	Input size

Checkbox

Themed checkbox with label.

Prop	Type	Default	Description
label	string	—	Label text
size	'sm' | 'md' | 'lg'	'md'	Size preset

RadioGroup

Group of mutually exclusive radio buttons.

Prop	Type	Default	Description
options	RadioOption[]	—	Available options
value	string	—	Selected value
onChange	(value: string) => void	—	Change callback
name	string	auto	HTML name attribute
disabled	boolean	false	Disable all options
orientation	'horizontal' | 'vertical'	'vertical'	Layout direction
size	'sm' | 'md' | 'lg'	'md'	Size preset

RadioOption: { value: string; label: string; disabled?: boolean }

<RadioGroup
  options={[{ value: 'a', label: 'Alpha' }, { value: 'b', label: 'Beta' }]}
  value={selected}
  onChange={setSelected}
/>

Switch

Toggle switch for boolean values.

Prop	Type	Default	Description
checked	boolean	—	Controlled state
onChange	(checked: boolean) => void	—	Change callback
size	'sm' | 'md' | 'lg'	'md'	Size preset
disabled	boolean	false	Disable the switch
label	string	—	Label text

Label

Styled <label> element.

Prop	Type	Default	Description
required	boolean	—	Show required indicator
disabled	boolean	—	Apply muted styling

---

Data Display

DataTable

Paginated table with sorting, search, and custom cell rendering.

Prop	Type	Default	Description
data	Row[]	—	Array of row objects
columns	Column<Row>[]	—	Column definitions
initialSortKey	string	—	Initial sort column
searchable	boolean	false	Show search input
pageSize	number	10	Rows per page

Column<Row>: { key: string; header: string; width?: number; sortable?: boolean; render?: (row) => ReactNode }

<DataTable
  data={items}
  columns={[
    { key: 'name', header: 'Name', sortable: true },
    { key: 'status', header: 'Status', render: (row) => <Badge>{row.status}</Badge> },
  ]}
/>

---

Navigation

Tabs

Horizontal tab bar.

Prop	Type	Default	Description
tabs	TabItem[]	—	Tab definitions
activeTab	string	—	Currently active tab id
onChange	(id: string) => void	—	Tab change callback

TabItem: { id: string; label: string; icon?: ComponentType; disabled?: boolean }

<Tabs
  tabs={[{ id: 'one', label: 'Tab 1' }, { id: 'two', label: 'Tab 2' }]}
  activeTab={tab}
  onChange={setTab}
/>

ViewSwitcher

Segmented button group for switching between views.

Prop	Type	Default	Description
currentView	T	—	Active view value
onChange	(view: T) => void	—	View change callback
options	ViewSwitcherOption<T>[]	—	Available views

ViewSwitcherOption<T>: { value: T; label: string; icon?: ComponentType }

<ViewSwitcher
  currentView={view}
  onChange={setView}
  options={[{ value: 'list', label: 'List' }, { value: 'grid', label: 'Grid' }]}
/>

Breadcrumbs

Horizontal breadcrumb navigation trail.

Prop	Type	Default	Description
items	BreadcrumbItem[]	—	Breadcrumb segments
separator	ReactNode	'/'	Custom separator

BreadcrumbItem: { label: ReactNode; href?: string; onClick?: () => void }

<Breadcrumbs items={[
  { label: 'Home', href: '/' },
  { label: 'Settings', onClick: goSettings },
  { label: 'Profile' },
]} />

DropdownMenu

Popover menu triggered by a button.

Prop	Type	Default	Description
trigger	ReactNode	—	Trigger element
items	DropdownMenuItem[]	—	Menu items

DropdownMenuItem: { label: string; onClick?: () => void; icon?: ComponentType; danger?: boolean; disabled?: boolean; separator?: boolean }

---

Layout

Stack

Flexbox layout helper for stacking children with consistent spacing.

Prop	Type	Default	Description
direction	'row' | 'column'	'column'	Flex direction
gap	number | string	8	Gap between children (numbers = px)
align	'stretch' | 'flex-start' | 'center' | 'flex-end' | 'baseline'	—	Cross-axis alignment
justify	'flex-start' | 'center' | 'flex-end' | 'space-between' | 'space-around' | 'space-evenly'	—	Main-axis alignment

<Stack direction="row" gap={12} align="center">
  <Text>Left</Text>
  <Button>Right</Button>
</Stack>

Drawer

Slide-in panel from the right edge with focus trapping and overlay.

Prop	Type	Default	Description
open	boolean	—	Whether the drawer is open
onClose	() => void	—	Close callback
width	string	'fit-content'	CSS width
maxWidth	string	'60vw'	Max width
title	ReactNode	—	Drawer title
overlay	boolean	true	Show backdrop overlay
closeOnOverlayClick	boolean	true	Close on overlay click
closeOnEscape	boolean	true	Close on Escape key

Dialog / ConfirmDialog

Modal dialogs.

Dialog — base modal with title and children.

Prop	Type	Default	Description
isOpen	boolean	—	Open state
onClose	() => void	—	Close callback
title	string	—	Dialog title

ConfirmDialog — confirm / cancel modal.

Prop	Type	Default	Description
isOpen	boolean	—	Open state
title	string	—	Title
message	string	—	Body text
variant	'default' | 'danger'	'default'	Visual tone
onConfirm	() => void	—	Confirm callback
onCancel	() => void	—	Cancel callback

<ConfirmDialog
  isOpen={open}
  title="Delete Item"
  message="Are you sure?"
  variant="danger"
  onConfirm={handleDelete}
  onCancel={() => setOpen(false)}
/>

Popover

Positioned content popover anchored to a trigger element.

Prop	Type	Default	Description
trigger	ReactNode	—	Trigger element
open	boolean	—	Controlled open state
onOpenChange	(open: boolean) => void	—	Open state callback
placement	'top' | 'bottom' | 'left' | 'right'	'bottom'	Popover placement

---

Feedback

Spinner / LoadingIndicator

Spinner — animated circular loading indicator.

Prop	Type	Default	Description
size	'button' | 'xs' | 'sm' | 'md' | 'lg'	'md'	Diameter preset
variant	'default' | 'inverted'	'default'	Use 'inverted' on coloured backgrounds

LoadingIndicator — spinner with optional text.

Prop	Type	Default	Description
size	same as Spinner	'md'	Spinner size
text	string	—	Label next to spinner
layout	'inline' | 'stacked'	'inline'	Text position

<Spinner size="sm" />
<LoadingIndicator text="Loading..." layout="stacked" />

Tooltip

Hover tooltip anchored to its children.

Prop	Type	Default	Description
content	ReactNode	—	Tooltip content
placement	'top' | 'bottom' | 'left' | 'right'	'top'	Position
delay	number	200	Show delay in ms

<Tooltip content="More info">
  <Button variant="ghost">?</Button>
</Tooltip>

Progress

Horizontal progress bar.

Prop	Type	Default	Description
value	number	—	Current value (0–100)
max	number	100	Maximum value
size	'sm' | 'md' | 'lg'	'md'	Bar height
tone	'primary' | 'success' | 'warning' | 'danger'	'primary'	Bar colour

<Progress value={75} tone="success" />

Skeleton / SkeletonText / SkeletonCircle / SkeletonRectangle

Placeholder loading shapes.

Prop	Type	Default	Description
width	string | number	'100%'	Width
height	string | number	'1em'	Height
variant	'text' | 'circular' | 'rectangular'	'text'	Shape
animation	'pulse' | 'wave' | 'none'	'pulse'	Animation type
lines	number	3	Number of lines (text variant)

<SkeletonText lines={3} />
<SkeletonCircle width={40} height={40} />

---

Hooks

useTheme()

Returns { setMode, getMode } for reading and setting the current theme mode ('light' | 'dark').

import { useTheme } from '@alga-psa/ui-kit';

const { setMode, getMode } = useTheme();
setMode('dark');

applyThemeVars(vars)

Applies a Record<string, string> of CSS custom property values to the document root.

import { applyThemeVars } from '@alga-psa/ui-kit';

applyThemeVars({ 'alga-primary': '#ff6600' });

---

Extension Theme Bridge

For extensions running in iframes, use the built-in theme bridge to receive host theme variables:

import { applyThemeVars } from '@alga-psa/ui-kit';

window.addEventListener('message', (ev) => {
  const data = ev.data;
  if (data?.alga === true && data?.version === '1' && data?.type === 'theme') {
    applyThemeVars(data.payload || {});
  }
});

// Signal readiness to the host
window.parent.postMessage({ alga: true, version: '1', type: 'ready' }, '*');