@adea-ai/ui
v0.158.0
Published
The Adea design system: Kobalte-backed Solid components, semantic OKLCH tokens, and the app-shell layout primitives shared by Adea and Cortana.
Maintainers
Readme
@adea-ai/ui
The shared Solid component library for Adea and Cortana. Applications retain their domain compositions, persistence, services, and native capabilities.
bun add @adea-ai/uiBuilt on SolidJS, Tailwind v4, Kobalte and corvu. solid-js is a peer, and the
four heavy optional peers (chart.js,
embla-carousel, embla-carousel-solid, solid-chartjs) are marked optional
so installing the library does not drag in a charting or carousel engine you
never use.
Contents
- Getting started and entry points
- Theming and fonts
- Components: forms and navigation, catalog browser, composer, transcript, split layout, scene controls
- Package checks
- Adding a component and reviewing it
Getting started
Import the stylesheet and wrap your app in the provider.
import { ThemeProvider } from '@adea-ai/ui/components/theme'
import '@adea-ai/ui/globals.css'
export function App() {
return (
<ThemeProvider>
<YourApp />
</ThemeProvider>
)
}ThemeProvider is what applies a theme, an accent and a typeface, and what
persists the choice. Without it you get the two default variants and nothing
else.
Tailwind ignores dependency directories by default. Register the component directories your application uses in its stylesheet, relative to that stylesheet:
@import 'tailwindcss';
@import '@adea-ai/ui/theme.css';
@import '@adea-ai/ui/base.css';
@import '@adea-ai/ui/appearance-font-settings.css'; /* optional: shared font roles and Appearance controls */
@source '../node_modules/@adea-ai/ui/src/components/ui/button';globals.css combines Tailwind, base styles, and theme tokens. Fonts require a
separate explicit @adea-ai/ui/fonts.css import. The packed-artifact gate expands
all component and library export conditions and rejects leaked story/test files,
including declaration output.
Entry points
Folder subpaths such as @adea-ai/ui/components/ui/button resolve the folder's
public index under the types, Solid source, development, and compiled conditions.
The package includes source for Solid compilation and Tailwind discovery, and
compiled JavaScript plus declarations for other supported consumers. License and
donor notices travel in dist/LICENSE and dist/NOTICE.
For shortcut labels in server-side or other non-UI code, import
platformModifierKey from @adea-ai/ui/components/ui/kbd/platform-modifier.
This entry does not load the keyboard components; the keyboard folder entry
continues to export the same helper for component consumers.
Charts and carousels are exported only from their subpaths, so root imports work without their optional peers:
import { Button } from '@adea-ai/ui'
import { LineChart } from '@adea-ai/ui/components/ui/chart'
import { Carousel, CarouselSlide } from '@adea-ai/ui/components/ui/carousel'Install chart.js and solid-chartjs for charts, or embla-carousel and
embla-carousel-solid for carousels. Their helpers and types live on the same
subpaths.
Split-layout tree imports
Scoped persistence decoders can import MAX_LAYOUT_LEAVES, MAX_LAYOUT_DEPTH,
MIN_SPLIT_RATIO, MAX_SPLIT_RATIO, listLeaves, countLeaves, layoutDepth,
and the opaque tree types from
@adea-ai/ui/components/layout/split-layout/tree. This read-only entry has no
UI runtime, renderer, or pane-editing dependencies. The existing /model entry
re-exports the same functions and types for compatibility. Use /model for
split, close, move, resize, and undo operations; use the component entry when
rendering the layout.
Theming
The catalogue is 34 themes across two appearances, grouped into families. The provider takes an initial selection and every axis is a plain value:
<ThemeProvider
initial={{
appearance: 'system', // 'light' | 'dark' | 'system'
lightThemeId: 'adea-light',
darkThemeId: 'adea-dark',
accent: 'theme', // or 'violet' | 'blue' | 'green' | 'amber' | 'cyan' | 'pink',
// or a theme-carried accent such as 'ansi-blue'
fonts: {
ui: { family: 'system', size: 14 },
content: { family: 'system', size: 14 },
code: { family: 'system', size: 12 },
},
}}
>| Axis | Values | How it is applied |
| ---------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Appearance | light, dark, system | a dark class plus color-scheme on <html> |
| Theme | any of the 34 catalogue ids | the variant's tokens, written as custom properties on <html> |
| Accent | theme (follow the variant), one of six presets, or an accent the theme pair carries (ansi-blue…) | a data-accent attribute on <html>, plus the resolved roles as custom properties |
| Fonts | UI, content and code family ids from the shared catalogue; sizes from 10–32px | Stable data-*-font ids plus resolved --font-* family and pixel-size properties |
Older single-font font preferences remain readable and migrate their family to
the UI axis; new preferences store fonts with one family and size per axis.
Canonical size properties stay in pixels for native editor integrations; the
shared text tokens use rem-relative ratios so browser root-text enlargement still
scales UI, prose, keyboard keys and code.
Read and change the current selection with useTheme():
const { selection, resolvedAppearance, setSelection, themes, themeAccents } = useTheme()
setSelection({ accent: 'amber' })themeAccents() lists the accents the selected light/dark theme pair carries
itself (@adea-ai/themes' themeAccentPresets): the palette's own blue,
magenta, cyan and green, offered only when both themes clear the catalogue's
accent floors. Their ids are role-shaped, so ansi-blue follows a theme switch
to the new theme's blue; a slot the new pair cannot offer falls back to the
theme's own primary. The primary grid is the theme default plus five standard
presets; Violet remains available under Additional colors, and theme accents
have their own group.
Two components ship for the settings surface: AppearancePanel is the whole
appearance view, and ThemeToggle is the light/dark switch on its own.
SettingsLayout composes a controlled vertical tab root, grouped SettingsNavigation,
and a scrollable panel viewport. Supply the selected value, onChange, navigation
groups, and matching TabsContent panels. The host owns URL or preference updates
and panel content; below 48rem of viewport width the rail becomes a horizontal,
scrollable strip of tabs above the panels (groups in order, Left/Right keys,
aria-orientation="horizontal"), and navigationLayout="rail" | "strip" pins one
shape at every width. The layout reports repeated activation through onReselect
and reveals the selected row on either axis by default. Use SettingsNavigation
directly when you already own the surrounding tabs composition; it follows the
enclosing Tabs orientation.
Shared tabs associate panels with custom trigger IDs in browser and server renders;
an explicit panel aria-labelledby takes precedence. Independent tab roots keep
their associations separate.
Controlled appearance mode
ThemeModeToggle provides the shared light/dark/system selector for hosts that
own their preference provider and storage. Pass mode and onModeChange; the
control owns roving keyboard focus, pressed state and explanatory tooltips. It
does not require or mount the shared ThemeProvider. ThemeToggle retains its
existing provider-bound API.
Controlled appearance editor
AppearanceEditor and AppearancePopover retain the accepted Zeron-derived
System/Light/Dark miniature cards, independent light/dark theme rows, palette
swatches, default/preset/custom accent choices and Theme default/Frosted/Opaque
surface choices. The popup supports live host preview and Save/Cancel/Reset;
Kobalte provides radio navigation, selection, dismissal and focus restoration. Since
its menus prevent Tab, the theme row carries Tab and Shift+Tab through the enclosing
dialog's focus order. DropdownMenuContent.portalMount keeps the theme menu within
its enclosing modal's accessible subtree.
Supply canonical AdeaTheme previews and AdeaThemeRecord choices.
themeRecords/themeRecordById export those records, and
appearancePreviewThemes({ lightThemeId, darkThemeId, accent }) resolves a
draft's ids and accent, a preset or a theme-carried accent, into the two
preview themes, exactly as ThemeProvider would apply them; withAccent is the
overlay on its own. builtinThemes is the shadcn projection a document is
painted with, not an editor input. Pass themeAccentOptions,
themeAccentsFor(lightThemeId, darkThemeId), to offer the accents the previewed
pair carries after the presets; the editor itself loads no catalogue or
normalization. Hosts own saved-ID recovery, validation, draft snapshots,
System appearance resolution, native transparency, live application tokens,
Save persistence and restoration on Cancel/dismissal. saving,
saveDisabledReason, recoveryNotice, customAccentError, and
surfaceCapability expose those outcomes; an unavailable import or Frosted
capability stays visibly unavailable. App-specific persisted versions and the
legacy translucent value need an app-owned adapter to the editor's theme
surface selection. The library does not silently migrate stored preferences.
A host recomposes the editor through props, never by forking it. Every option keeps the default below, so an existing consumer renders as before:
| Prop | Default | What it changes |
| -------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fontSettingsPlacement | inline | end closes the option list with the typefaces, after Glass, Reduce transparency and Theme library. |
| accentEntryStyle | swatches | labels renders every choice as a named chip. row draws the presets as circles in one equally spaced line (it holds at 320px, where the grid wraps) and turns Custom into a button that opens the native colour selector: only a chosen colour changes the draft. |
| showThemeDefaultAccent | true | false drops the leading "Theme default" entry, for a host whose default accent already is a preset. |
| showCustomAccentCaption | true | false drops the "Custom" caption over the swatches style's custom chip. No effect on labels or row. |
| showModeIcons | false | A sun, moon or monitor glyph beside each mode card's label. |
| triggerVariant (popover) | ghost | toolbar holds the pressed rung while the sheet is open and repeats the palette glyph in the tooltip, like the other toolbar actions. |
customAccentValue seeds the native selector (row) and the draft the swatches
Custom chip commits; hand it your starting colour.
Avoiding the flash
A themed app has to know the appearance before the first paint, or it paints
once in the wrong mode. themeScript emits the inline script that does it:
<head>
<script innerHTML={themeScript('my-app-appearance')} />
</head>Pass the same key to ThemeProvider as storageKey, and the two agree.
Fonts
Font preference roles and font assets are separate opt-ins. Import
appearance-font-settings.css after the theme and base styles to enable the
shared UI/content/code projections and utilities. globals.css does not import
font assets; import fonts.css explicitly when those faces are wanted:
@import '@adea-ai/ui/theme.css';
@import '@adea-ai/ui/base.css';
@import '@adea-ai/ui/appearance-font-settings.css';
@import '@adea-ai/ui/fonts.css'; /* omit to bring your own */appearance-font-settings.css defaults --font-ui, --font-content and
--font-code to System and scales each text role. Import it after theme.css and
base.css, then apply settings with the shared runtime or prepaint helper; the
helper resolves catalogue ids to family tokens and writes canonical pixel sizes.
This stylesheet does not load any font files.
The font-ui-size, font-content-size and font-code-size entries in the token
gallery are runtime-projected properties: applyAppearanceFontSettings and
fontSettingsBootstrapScript write their pixel values from normalized font
settings. They are not fixed declarations in the theme stylesheet.
--font-sans and --font-mono remain compatibility aliases for UI and code.
The shared projection and prepaint helpers are exported from
@adea-ai/ui/lib/appearance-font-settings; hosts can normalize persisted ids,
apply the shared data attributes, resolve family ids through the published
--font-family-* tokens, and reuse the same bootstrap snippet without
duplicating catalogue rules.
For versioned host preferences, pass the expected version as the bootstrap
helper's second argument. Only an exact version match is applied before paint;
missing or unsupported records use the System defaults. Omitting the argument
retains the unversioned helper behavior.
Each UI, Content and Code chooser keeps the complete font catalogue, and Code
uses the exact selected catalogue family. Choose a Mono option when you want a
monospace face; System uses the platform's monospace counterpart for Code.
Forms and navigation
Use NativeSelect for a compact list of known choices that should keep native
keyboard, form submission, option, and label behavior:
import { NativeSelect } from '@adea-ai/ui/components/ui/native-select'
import { Label } from '@adea-ai/ui/components/ui/label'
<Label for="relationship-kind">Relationship kind</Label>
<NativeSelect
id="relationship-kind"
name="relationshipKind"
value={kind()}
onChange={handleChange}
options={[
{ value: 'all', label: 'All relationships' },
{ value: 'derived', label: 'Derived' },
]}
/>NativeSelect renders a real <select> and passes native props and children
through. Use value with onChange for a controlled selection, or defaultValue
to initialize an uncontrolled one. Use Select for searchable, runtime, or
longer lists that need a custom popover.
InputControl is the styled native input without suggestion-list behavior. Use
Input when a form should offer native datalist suggestions; custom values
remain valid and submit unchanged.
The library owns the datalist and unique association; a suggestion does not
restrict the submitted value. Native required, pattern, form, event, and
ref props still apply to the input.
ModalDialog defaults to a compact surface for short tasks. Use
size="settings" with SettingsPage for a wider,
viewport-bounded settings surface; the shared layout keeps its panel content
scrollable while the dialog title remains visible.
ThreadPanel.headerActions accepts shared controls for host actions such as
marking a thread unread. Closing the thread remains a separate labelled,
tooltip-backed control. Hosts retain read-marker and message authority.
AccountMenu owns the trigger tooltip, menu keyboard behavior, and session row.
Pass size to match its host control size. Use an item's onSelect for an
immediate action, or onSelectAfterClose to open a dialog after the menu has
finished closing. The latter receives the connected trigger button for dialog
focus restoration and is cancelled if the menu unmounts. Authentication,
updates, navigation, and other effects remain host callbacks.
SidebarNavTitle accepts polymorphic as for a host's title heading.
SidebarNavLabel keeps a row's complete accessible text while truncating its visible label, leaving room for adjacent controls. The navigation root clamps its preferred width to the containing lane at narrow widths and enlarged root text. SidebarNavRow moves adjacent actions onto a second line when the item's preferred label space and the controls cannot fit together.
Row and section actions remain visible when any coarse pointer is available, including on hybrid devices; hover, keyboard focus, and an expanded menu continue to reveal them as well. Action hit-area size remains determined by the supplied shared control size.
Use SidebarNavSection.headingAs (h1 through h6) for section headings.
Sections may be uncontrolled with defaultOpen or controlled with open and
onOpenChange. Put disclosure-button attributes and host-owned row interactions
in triggerProps; its onClick and onKeyDown run before shared behavior, and
preventDefault() cancels the corresponding toggle or Alt+Arrow reorder callback.
triggerProps.onReorder receives up or down; the host remains responsible for
updating its hierarchy and preserving stable row identity.
Disclosure buttons stay inside their heading and trailing actions stay outside
it, preserving hierarchy and independent keyboard actions.
Board checks the caller's legal-move predicate before settling a pointer drop.
Ctrl/Cmd + arrow moves skip disabled columns without wrapping at the edges.
After a controlled move settles, focus follows the moved card only when the
source card owned focus; another focus or pointer action cancels restoration.
Square icon controls use the control-height tokens through the Tailwind --size
mapping; --spacing-control-* remains the separate inline-padding ladder.
Text controls, icon buttons and toggles share the same height in both densities.
Dimensions remain rem-based and follow the consumer's root font size. The browser
geometry lane checks the standard density rungs, heights and padding under both
themes/densities; the 2xl touch target remains 48px under compact density.
On narrow screens, the shared TopBar keeps a usable middle Search target while
side groups scroll horizontally when their actions do not fit. Keyboard focus
reveals each action. Groups opt out of native window dragging.
Use TopBarTitle align="center" to center text within its slot; the host controls
slot placement. Use layout-only visibility classes when a title should yield
space to essential controls.
Catalog browser
CatalogBrowser presents a host-owned searchable catalog with ordered category
groups, discover/installed tabs, bounded group expansion, optional filters and
supplemental tabs. Give entries the full set of detail records so opening an
item remains stable when a query or tab filters the visible groups. The host
owns catalog verification, filtering, installed state, permission decisions,
errors, and actions. Selecting an item opens its host-rendered detail and
returns focus to the originating result when Back is chosen. CatalogDetail
provides the shared item summary/action frame and CatalogDetailSection gives
host-specific permissions or metadata a shared section surface. Supply
resultsRegionLabel and detailRegionLabel to name their keyboard-focusable,
shared ScrollArea regions. The results area scrolls notices along with loading,
empty, and error states even when those states contain no interactive control.
Use CatalogDetail sectionsLayout="columns" for related detail fields in a single
padded, outlined card. Its sections share dividers on wide screens and stack on
narrow screens; hosts should pass CatalogDetailSection children directly and
use no local padding or border overrides. The default keeps separate section cards.
import {
CatalogBrowser,
CatalogDetail,
CatalogDetailSection,
type CatalogBrowserEntry,
type CatalogBrowserGroup,
} from '@adea-ai/ui/components/composites/catalog-browser'
const entries: readonly CatalogBrowserEntry<VerifiedPlugin>[] = /* all detail records */ []
const groups: readonly CatalogBrowserGroup<VerifiedPlugin>[] = /* visible filtered groups */ []
<CatalogBrowser
open={open()}
tabs={[
{ id: 'discover', label: 'Discover' },
{ id: 'installed', label: 'Installed' },
{ id: 'navigation', label: 'Navigation', kind: 'supplemental' },
]}
tab={tab()}
tabsLabel="Catalog views"
onTabChange={setTab}
query={query()}
onQueryChange={setQuery}
searchLabel="Search catalog"
searchPlaceholder="Search applications"
resultsRegionLabel="Catalog results"
resultCount={visibleCount()}
resultLabel={(count) => `${count} applications`}
loadingLabel="Loading catalog"
status={catalogStatus()}
catalogError={catalogError()}
emptyState={emptyState()}
groups={groups}
entries={entries}
selectedId={selectedId()}
onSelect={(plugin) => setSelectedId(plugin.id)}
onBack={() => setSelectedId(null)}
backLabel="Back to catalog"
detailRegionLabel="Application details"
installedLabel="Installed"
publishedByLabel={(publisher) => `Published by ${publisher}`}
showMoreLabel={(hidden) => `See ${hidden[0]?.name} and more`}
showLessLabel="Show less"
renderIcon={(plugin) => <PluginIcon plugin={plugin} />}
renderDetail={(plugin) => (
<CatalogDetail
title={plugin.name}
description={plugin.description}
category={plugin.category}
publisher={plugin.publisher}
publishedByLabel={(publisher) => `Published by ${publisher}`}
action={<InstallButton plugin={plugin} />}
>
<CatalogDetailSection title="Permissions">
<PluginPermissions plugin={plugin} />
</CatalogDetailSection>
</CatalogDetail>
)}
renderSupplementalView={(id) => (id === 'navigation' ? <NavigationSettings /> : undefined)}
/>The CatalogBrowser story demonstrates category expansion, search, separate
installed content, a supplemental navigation surface, and host-provided details.
Catalog detail summaries place actions and feedback beneath identity on narrow screens, preserving readable title/description flow. Grouped field sections keep their content at the top while sharing the outline and dividers.
Composer
Chat composer
ChatComposer translates the pinned Kiro composer hierarchy: knowledge context,
follow-ups and adjacent band, approval/notices, staged content, input/action
rows and the context shelf. It composes the existing IME and busy-action units.
Its optional controlled collapse contract unmounts input and shelf and replaces
them with a labeled bar showing the waiting draft's first line. Collapse keeps
the host draft and caret selection; controlRef exposes instance-scoped
focus()/expandAndFocus() instead of a global shortcut or broadcast.
The host supplies value, onValueChange and onSubmit({text, action}); it owns
attachments and runtime authority and clears its draft only after confirmation.
The shared input guards pending delivery, reports failure, visibly blocks
unsupported delivery and fences local feedback on resetKey. Enter follows the
controlled busy mode, while Ctrl/Cmd+Enter requests the other supported busy
action. sendableActions declares non-text payload eligibility per action: a
reference-only draft can send or queue without becoming steerable. Explicit false
also vetoes delivery when the draft contains text; alternate-action hints appear
only when that action is eligible. Mode selection
itself never fires. approvalFocus is host-derived
presentation, not a permission decision. Agent and model controls remain distinct
host contributions in context.
Sent-prompt history, manual resize, uploads, voice and stop/resume are not part of the shared composer; hosts build them.
sendableActions is the host's payload eligibility contract: explicit false
refuses that action even with typed text, explicit true supports structured
payloads without text, and omitted entries fall back to nonempty text. Selecting
an unavailable action cannot override this contract through keyboard delivery.
Keyboard and IME
MessageComposer preserves native IME candidate commits and suppresses sending
during composition, including the 50 ms commit window when browser flags have
already cleared. A separate Enter sends after that window; Shift+Enter remains
a soft break. A host or menu that already prevented the event keeps ownership.
The selected KiroCrew textarea guard is translated to Solid ownership; it adds
no document listener or application session state. Source and license details
are retained in NOTICE.
The field contract addresses the textarea itself: inputRef receives its native
HTMLTextAreaElement, inputId assigns its stable id, and inputLabel,
inputDescription and inputDescribedBy provide its accessible name and help.
The default inputSize="comfortable" uses the shared 4rem minimum and 12rem
maximum; inputResize selects one of the Textarea's named resize behaviors.
Textarea owns both its standalone and borderless variant="composer"
appearances, so consumers do not need to style a nested control.
Busy send button
BusySendButton translates KiroCrew's split fire/mode-picker composition. Pass
controlled mode, onModeChange and onFire. disabled prevents firing while
leaving mode choice available before typing; selectionDisabled gates choosing.
Inject unavailable reasons for unsupported or unauthorized modes: rows remain
visible, and the selected action cannot fire. Supply alternateActionHint only
when the host implements the described keyboard chord. The component adds no
keyboard chord, preference storage, runtime command or queue. Persistence and
same-session preference synchronization remain application-owned.
Kobalte owns the menu and focus lifecycle. Its Tab prevention lacks row cycling, so a menu-scoped donor translation cycles enabled rows without a document listener. Stories cover before-typing, working, unavailable and read-only states.
Paste tokens
@adea-ai/ui/components/conversation also exports the pure paste-token model:
PasteBlock, isPasteBlock, countLines, shouldCollapse, nextSeq,
formatToken, findTokenRanges, tokenRangeAt, pruneBlocks, expandAll,
recollapsePastes, remapCarriedBlocks, stripTrailingBlankLines, and the
threshold and marker constants. Hosts provide stable, bounded ASCII block IDs and own
draft state, persistence, message reconciliation and editor behavior. The model
does not read storage or the clipboard, upload files, edit a textarea, or
provide undo/history, previews or chips. The opt-in editor below composes this
pure model with a controlled textarea. Source attribution is in NOTICE.
Atomic paste editor
ChatComposer keeps its plain-text API and bundle closure. Consumers that need
atomic paste editing import AtomicChatComposer from the direct
@adea-ai/ui/components/conversation/atomic subpath. It accepts host-owned
blocks, a synchronous createBlockId() and one onChange({ text, blocks })
callback. Paste, native typing and pruning report the complete draft together.
Submit receives one snapshot containing text, the selected action and cloned
referenced blocks before delivery starts. Both entries share a private
composition shell; the UI owns no paste identity, history, storage, transport or
undo state.
The editor collapses text-only pastes at the existing three-line or
200-character thresholds, supports raw Cmd/Ctrl+Shift+V for the next paste,
preserves standalone and Markdown quote-prefix placement, and keeps token
deletion, navigation, selection and dropped-text replacement atomic.
Double-click or touch expands a token. Copy and cut expand fully selected tokens
in order while partial selections remain native. An aria-hidden mirror
highlights tokens behind the single labeled textarea. Hover and caret previews
wait 300 ms, scan and show at most 1,200 characters across up to 12 lines, close
when their text/block/scope becomes stale, and stay suppressed on touch devices. Keyboard
users can open the token next to the caret or current selection with Alt+Down
Arrow and dismiss it with Escape.
The input announces that shortcut and the open preview through aria-describedby
while keeping focus in the textarea. The preview uses the existing tooltip
portal without intercepting textarea input.
Only ClipboardEvent.clipboardData text is read. Clipboard permissions,
images and files, uploads, rich editing, persistence and sent-prompt history stay
with the host. The AtomicPasteTokens story shows the controlled contract.
Transcript
Following new output
ConversationSurface follows streamed text, earlier-row growth, turn collapse
and pane resizing using the KiroCrew plain-scroller decision contract. A
deliberate upward scroll releases follow, including small moves near the bottom.
Returning to the bottom or choosing Jump to latest re-arms it; the action
does not estimate unread messages from pixel distance. Instant pins keep
self-scroll attribution synchronized. Keyboard jumping returns focus to the
transcript when its jump control disappears; automatic pins never move focus.
threshold controls jump-button visibility (80px by default), independently of
follow intent. follow={false} is fully inert: positioning belongs to the host,
with no observer or mount pin. Re-enabling it explicitly re-arms at the bottom
unless the host supplies initialReadingPosition: { top, following }. That
snapshot is consumed only on mount, identity reset or follow re-enable; ordinary
snapshot prop changes never reposition the reader. A parked snapshot releases
follow until an explicit jump or native return to the bottom. The
onReadingPositionChange callback reports native offset and actual follow intent,
including small upward moves inside the jump visibility threshold. An optional
resetKey resets follow or consumes the current identity's snapshot. Canonical
session identity, durable restoration and virtualized transcript windows remain
application-owned. ref and onScroll still reach the inner scroller.
The SurfaceFollowing story shows streaming, collapse and pane resizing.
Transcript composition
TranscriptComposition assembles ordered host-classified rows, contiguous groups,
turn presentation and accessible fold controls. Import it from the public component
subpath:
import {
TranscriptComposition,
type TranscriptCompositionRendererProps,
type TranscriptRow,
} from '@adea-ai/ui/components/conversation/transcript-composition'
type Message = { text: string }
const rows: readonly TranscriptRow<Message>[] = [
{ id: 'question-1', value: { text: 'Inspect the cursor.' }, opensTurn: 'reset' },
{
id: 'tool-1',
value: { text: 'Read the cursor.' },
fold: 'tool',
call: { phase: 'request', id: 'call-1' },
},
]
function HostMessage(props: TranscriptCompositionRendererProps<Message>) {
return <article>{props.row.value.text}</article>
}
export function TranscriptPreview() {
return <TranscriptComposition rows={rows} renderRow={HostMessage} />
}Each row needs a stable unique id within its transcript. The host supplies the
Solid row component and classifies turn boundaries, calls, conclusions,
always-visible actions and redacted values. The renderer does not parse protocol
payloads or decide permission, session, event, delivery or success state.
Settled tool folds start closed and unmount their hidden row payloads. Live rows
stay open until the host marks them settled; an explicit row choice survives that
running-state transition. foldMode="prose" folds host-marked eligible activity
before a host-designated conclusion, leaving that conclusion visible.
The foldState="collapsed" command keeps hidden
content mounted. It folds eligible rows before a host-marked conclusion; without
that boundary it leaves prose visible and can still collapse explicitly classified
tool calls. Always-visible rows stay in place. disclosure plus
onDisclosureChange lets an application restore explicit choices from its own
durable store using transcriptDisclosureKey.
Split layout
The split-layout model (adapted from bb/Muxy; see NOTICE) is pure:
createLayoutState, splitPane,
movePane, closePane, undoClosePane, focusPane, swapPanes,
resizeSplit, normalizeLayout and the reading-order helpers.
Leaves extend {kind: 'leaf', id: string} with any host-owned payload. Closing
the last leaf calls an injected placeholder factory; it never selects a harness,
starts a terminal or deletes a project. The limits are eight leaves, depth eight and 10 to 90 percent split ratios. Construct or validate a tree before
editing it; the shared constructor validates visual structure and identities,
while applications still decode/scoped-persist preferences and retain unknown
future versions for recovery.
splitPaneBalanced(state, targetLeafId, { placement, leaf, splitId }) is an
opt-in automatic reflow for hosts that want a new pane beside the selected pane
in reading order. It keeps one row for one or two panes, starts a second row at
three, and balances the row lengths through the eight-pane limit (two rows of
four at the cap). Leaves in each row receive equal widths and both rows receive
equal height; adding a pane can therefore redistribute existing pane widths.
Opaque leaf objects are retained. Existing split ID strings are recycled across
the rebuilt branches; an ID can acquire a different axis or descendants, so hosts
must resolve resize actions against the current tree rather than cache a branch.
The new split ID names the nearest common branch of the selected and new panes.
The new pane is focused, and the close-undo stack is cleared like other structural edits. The
explicit-axis splitPane operation is unchanged for hosts that do not want an
automatic reflow.
No persistent state, session services, native drag region or host framework is imported into this model.
Host pane presentation
Controlled split ratios survive host visibility changes and disposal. Corvu panel registration and unregistration callbacks with incomplete sizes, and callbacks from detached or hidden roots, do not become host resize requests. Real pointer and keyboard resizing still flows through the same constrained callback.
SplitLayout can keep its default pane header while allowing a host to supply
inline visible content with renderPaneLabel, opt pane regions into keyboard
Tab navigation with paneTabIndex={0}, and provide a domain-specific splitter
name with labelForSeparator. Pane regions remain programmatically focusable
by default (paneTabIndex={-1}), and separators keep their orientation-based
names unless the host supplies a label.
renderPaneLabel receives a stable Accessor<L> once for each leaf owner.
Read leaf() inside the returned JSX so Solid tracks payload changes while the
same pane owner is retained during split and move operations. This visible
header content does not define the region's accessible name or the close
button's name: both continue to come from labelForLeaf, so hosts should
provide an accessible domain label there as well.
Pointer moves use a bounded, window-framed native drag-image snapshot while
the source dims and the handle changes from a grab to a grabbing cursor. The
temporary preview is inert, has no duplicate IDs, and is removed when dragging
ends. Reduced-motion preference disables the source opacity transition;
keyboard moves remain host-owned through renderPaneActions.
The HostPresentation story shows a decorative icon and host title, keyboard
pane stops, and a workspace-specific separator name. A narrow-width component
fixture also checks that a long host title does not widen its pane header.
Scene controls
SceneControls composes movement, jump and optional zoom actions for a host
scene. onMovementChange(direction, pressed) and onJumpChange(pressed) report
held state from pointer or keyboard input; zoom callbacks fire once per
activation. The shared controls capture pointers and release held actions on
pointer end/cancel, lost capture, window blur and component cleanup. The host
maps these typed callbacks to its own camera or movement system; the component
does not synthesize keyboard events or access host globals. Each icon action
uses the shared tooltip and a 2xl 48px target that stays that size under
compact density. Rounded movement and zoom group surfaces use the shared
scrim treatment, which follows the library's reduced-transparency and fallback
policy.
import { SceneControls } from '@adea-ai/ui/components/composites/scene-controls'
;<SceneControls
onMovementChange={(direction, pressed) => setMovement(direction, pressed)}
onJumpChange={(pressed) => setJumping(pressed)}
onZoomIn={zoomIn}
onZoomOut={zoomOut}
/>Labels default to English and can be supplied through labels for a host's
locale. Hold actions have separate accessible names and explanatory tooltip
strings so localization can describe the gesture without changing the action
name. SceneControls owns control arrangement and interaction lifecycle;
the host owns placement, persistence and scene behavior.
Package checks
Each check:packed-* script packs the real npm archive, installs it into a
throwaway consumer (optional peers left out, lifecycle scripts off) and checks it
under both the compiled and Solid source export conditions. Browser cases run
headless in Chromium and WebKit, and most also server-render in Node. Every check
confirms the packed LICENSE and NOTICE and enforces a size budget. Install the
browsers once with bunx playwright install chromium webkit (add --with-deps on
Linux if system libraries are missing).
| Script | What it covers | Budget (gzip JS / raw CSS) |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| check:packed-conversation | Conversation subpath: draft recovery, IME, follow, jump focus, busy actions, composer collapse, atomic paste tokens | 26 / 50 / 54 KiB (plain, busy, composed) / 42 KiB |
| check:packed-transcript | Transcript composition: row identity, tool folds, keyboard disclosure, accessibility | set in the script |
| check:packed-appearance | Appearance editor with real @adea-ai/themes records: keyboard, live preview, save, cancel and reset, narrow layouts | 64 KiB / 50 KiB |
| check:packed-scene-controls | Scene controls and ActionButton: held-action release, labels, 48px targets at 320px and 200% text | 40 KiB / 32 KiB |
| check:packed-layout | Split-layout model subpath in Node, with no runtime imports | 3 KiB |
| check:packed-layout-renderer | Split layout, sidebar and top bar rendering | 32 KiB / 34 KiB |
| check:packed-paste-model | Paste-token model subpath with a strict TypeScript consumer | 3 KiB |
| check:packed-consumer | Root imports, lightweight controls, overlays and the shell | set in the script |
The atomic paste editor may add at most 6 KiB of gzip JS over the composed
fixture. Tailwind discovery in these fixtures is explicit; they never rely on
scanning node_modules. The checks prove the published component contracts;
persistence, hydration and manual assistive-technology checks happen in the apps.
bun run test:components runs the component contracts against a real
Vite/Solid/Tailwind build in Chromium and WebKit.
What one component costs
bun run --cwd packages/ui check:tree-shaking builds real bundles against the built
package. Each row uses the public entry, and importing one component does not pull in
the rest of the library. The script writes this table (-- --write) and CI fails when
the committed figures drift from what it measures.
| Public import | Gzipped | What it brings |
| --------------------------------------------------------------- | ---------- | ------------------------------------- |
| @adea-ai/ui → Button | 22.4 kB | the floor: Solid, clsx, tw-merge |
| @adea-ai/ui → Board | 22.8 kB | nothing |
| @adea-ai/ui/components/composites/list-row → ListRowControl | 21.9 kB | nothing: the row without its tooltip |
| @adea-ai/ui → DiffBlock | 23.2 kB | lucide icons |
| @adea-ai/ui → CodeBlock | 48.7 kB | lucide icons, Kobalte tooltip on copy |
| @adea-ai/ui → MessageRow | 27.8 kB | nothing |
| @adea-ai/ui → CalendarSurface | 30.7 kB | corvu calendar |
| @adea-ai/ui → ModalDialog | 51.2 kB | Kobalte dialog, the shared tooltip |
| @adea-ai/ui/components/ui/carousel → Carousel | 34.9 kB | embla |
| @adea-ai/ui/components/composites/list-row → ListRow | 42.4 kB | Kobalte tooltip |
| @adea-ai/ui → NavigationMenu | 59.1 kB | Kobalte navigation menu |
| @adea-ai/ui/components/ui/chart → LineChart | 89.9 kB | chart.js, the line controller only |
| root plus chart and carousel entries | 470.3 kB | and Button is 4.8% of it |
The chart splits from itself, which is why chart.js was chosen: LineChart is
10.6 kB smaller than importing all seven chart types together (89.9 kB against 100.5 kB), because the
controllers are imported per component while the shared scales and plugins are
registered once. The gate fails if that stops being true.
Three budgets are enforced in CI: importing Button must stay under 40.0 kB
and under 25.0% of the whole library, and no sampled component may exceed
180.0 kB.
Adding a component
shadcn add installs an item from the registry on GitLab Pages (or from
./packages/ui/public/r/<name>.json in a checkout):
bunx shadcn@latest add https://adea-ai.gitlab.io/design-system/ui/r/button.jsonReviewing it
Every component, every variant and the token galleries are in the workshop:
bun run storybookThe toolbar switches theme, accent, fonts and density live, which is the fastest way to see how a component behaves across the catalogue rather than in one theme.
Licence
Apache-2.0. Donor attributions are in NOTICE, which ships in the package.
