@collective-intelligence/ui-react

Public, accessible React primitives and the Collective Intelligence design system for Collective Intelligence applications.

The package preserves the design-system source structure under src/components/, including ui, ui-extensions, icons, and illustrations, plus shared hooks, utilities, and theme tokens. The /resources entrypoint contains generic table, list, filter, pagination, dialog, and action primitives.

All components accept display-ready props and do not fetch data, own authentication, or depend on private CI packages. React and React DOM remain peer dependencies.

react-hook-form is also a peer dependency and is excluded from the browser prebundle. Consumers must provide it so the public Form provider and their form hooks share the same context.

bun run build produces production JSX for the published entrypoints while keeping React and React DOM external. These artifacts support consumers using either production or development React. After building, bun run test test/built-runtime.test.ts verifies rendering with both modes.

react-markdown remains a regular runtime dependency and is excluded only from this package's browser prebundle. Browser and server-side rendering consumers resolve its dependencies for their own runtime, keeping browser-only DOM code out of server imports.

Published entrypoints share runtime chunks inside dist; distribute that directory intact. This keeps modal focus and pointer-lock state shared when composing primitives from /ui with dialogs from /ui-extensions. bun run test:pack rebuilds the package and checks this cross-entrypoint modal lifecycle and consumer form context before validating the packed consumer.

Controlled entity presentation

Import shared entity presentation from @collective-intelligence/ui-react/resources. Dashboard's private CRUD wrappers and external consumers use the same table, list, filter layout, pagination and dialog implementation. Data loading, authorization, URL state, selection, drafts and mutations belong to the caller.

ResourceTablePrimitive takes rows, columns, stable getRowKey, and renderCell. Optional row action, context-menu and detail renderers receive the same row. Action clicks do not activate the row; row activation supports Enter and Space. Expanded and selected state is controlled by caller callbacks. ResourceListPrimitive accepts stable item keys and an optional container slot. ResourceFiltersBar lays out caller-owned controls, while ResourcePaginationPrimitive supports previous/next and controlled numbered pages. Pending controls remain disabled. Pass navigationLabel to localize the navigation's accessible name (defaults to Resource pagination), alongside previousLabel, nextLabel, and ellipsisLabel for the controls.

ResourceDialogPrimitive uses the existing focus-managed dialog by default; pass open, onOpenChange, title, and optional description. Its explicit custom Dialog slot remains available, with focus management then owned by that replacement.

ResourceFormPrimitive renders display-ready ResourceField metadata, values, field errors and callbacks. Built-in controls cover text/email, numbers, booleans, enum options, date/datetime strings and explicit nullable clearing. Numbers and booleans retain their JSON value types. Custom controls receive the same value/change, disabled, read-only, required and error metadata; schema inference and registry lookup stay with the caller. Unsupported custom controls are shown explicitly. Form submission delegates validation and persistence to the caller; the presentation never constructs a client or QueryClient.

ResourceListPagePrimitive picks one body from caller-owned slots by status (pending, error or ready) and totalItems: loading for a first load, error, nothingYet for an empty list, noResults when hasActiveQuery is set, otherwise children. The optional toolbar shows with rows and with noResults. Pass paging (page, totalPages, onPageChange) and optional pagination labels for a pager that appears above one page. When the current page vanishes, the list asks onPageChange for the last page once. isRefetching marks a background refresh with aria-busy. Content fades in only when it replaces the loading slot.

ResourceAdvancedFilters adds a collapsible advanced-filter region to a ResourceFiltersBar. Pass the always-visible primary controls, the advanced content, the activeCount and the localized labels. Optional activeFilters render removable chips, onClear resets every filter, and the region opens by default when a filter is active or defaultOpen is set. The caller owns filter state and URL sync.

Run bun run build-storybook for the interactive Resources / Controlled entity / Journey example. bun run test:pack checks these exports from the packed JavaScript and declarations in an isolated external consumer.

Error alerts

Import ErrorAlert from @collective-intelligence/ui-react/ui-extensions. It composes the existing destructive Alert and Radix Collapsible primitives. Pass the visible message as children, an optional title, and an optional details object containing a trigger label and arbitrary React content. Omitting details removes both the disclosure trigger and its panel.

import { ErrorAlert } from "@collective-intelligence/ui-react/ui-extensions"

;<ErrorAlert
  title="Connection failed"
  details={{
    label: "Technical details",
    content: (
      <pre className="whitespace-pre-wrap break-words">{diagnostics}</pre>
    )
  }}
>
  The service could not be reached. Please try again.
</ErrorAlert>

The details start closed. Use defaultOpen for an initially expanded panel, or open with onOpenChange to control it. Labels, translations, diagnostic formatting and error recovery remain with the caller. Use className and classes to customize the root and individual presentation parts.

Failed write toast

Import ciWriteFailedToast and Toaster from @collective-intelligence/ui-react/ui. ciWriteFailedToast(messages?) returns a handler for the onWriteFailed prop of CollectiveIntelligenceProvider (@collective-intelligence/external-apps-client-sdk-react). The handler calls toast.error with one text:

• For a CiError, the English text of its code.
• For a CiTransportError, an English connection text. It does not say that the change was not saved: when the answer of a write is lost, CI can have saved it.

To use other texts, for example in another language, pass messages (CiWriteFailedMessages). Its keys are the CiError codes and transport. A key that you do not give keeps its English text.

import {
  Toaster,
  ciWriteFailedToast
} from "@collective-intelligence/ui-react/ui"

const onWriteFailed = ciWriteFailedToast({
  conflict: "Quelqu'un a modifié cet élément.",
  transport:
    "Pas de connexion. La modification n'est peut-être pas enregistrée."
})

;<CollectiveIntelligenceProvider client={client} onWriteFailed={onWriteFailed}>
  <App />
  <Toaster />
</CollectiveIntelligenceProvider>

The handler reads only the _tag and code of the error (CiWriteFailedEvent), so this package does not depend on the client SDK. The toast shows in the Toaster only when the app has one copy of this package: two copies have two toast stores. For this reason the client SDK for React has this package as a peer dependency.

Card options

Import CardOptionsBlock, CheckboxCardOption and RadioCardOption from @collective-intelligence/ui-react/ui-extensions. Each option is a card with a title, an optional description and its control; a click anywhere on the card changes the value, also inside a <form>.

import {
  CardOptionsBlock,
  CheckboxCardOption
} from "@collective-intelligence/ui-react/ui-extensions"

;<CardOptionsBlock>
  <CheckboxCardOption
    checked={selected}
    title="Studio: Use agent conversations"
    description="Capability to use Studio. It adds no permission that a run uses."
    wrapDescription
    onCheckedChange={setSelected}
  />
</CardOptionsBlock>

The description shows on one truncated line. Set wrapDescription to show it in full on more lines. CheckboxCardOption and RadioCardOption link the description to their control with aria-describedby. With CardOption and a custom control, pass a descriptionId and set the same id as the aria-describedby of your control.

Video player

Import VideoPlayer from its own subpath, @collective-intelligence/ui-react/ui-extensions/video-player. It renders one <video> and plays a Stable Media URL (…/media/{ownerKind}/{ownerId}…): adaptive HLS when the video's Renditions are ready, otherwise the stored file. Pass src, the native <video> attributes (controls, poster, autoPlay, aria-label, …), className and classes.root. Captions are <track> children.

import VideoPlayer from "@collective-intelligence/ui-react/ui-extensions/video-player"

;<VideoPlayer
  aria-label="Product walkthrough"
  controls
  requestHeaders={() => ({ Authorization: `Bearer ${token}` })}
  src={file.mediaUrl}
/>

Credentials stay with the consumer:

• With requestHeaders, the player asks src with stream=hls, the callback's headers and credentials: "omit". A playlist answer starts hls.js, which adds the headers only to URLs on the origin of src under its /media/ path. Any other answer is the stored file: the player plays the final URL of the followed redirect.
• Without requestHeaders, the player asks with credentials: "include" and redirect: "manual", and hls.js sends credentials only to the same API media URLs. A redirect (the stream is not ready) or any other answer lets the element load src itself with the session cookie.
• Delivery URLs on the media host never receive a header, credentials or a query string. A browser without Media Source Extensions uses native HLS only with the cookie; with a header callback it plays the stored file.
• When a fragment answers 403 (its Delivery URL expired with its Access Window), the player reloads the stream once at the current position.

The page origin must be allowed by the API CORS policy for a credentialed request; otherwise the player falls back to the element loading src.

Exception to "do not fetch data". The player probes the one URL its consumer passes, to choose between the stream and the stored file. That probe is media transport, not data access: it builds no URL of its own, reads no token and constructs no client.

hls.js (hls.js/light) is bundled in its own chunk and loaded by dynamic import only for a ready stream on a browser with Media Source Extensions; the other entrypoints and the player's own chunk do not contain it. Its Apache-2.0 notice ships in THIRD-PARTY-NOTICES.md. bun run test:pack checks the chunk split and the notice in the packed artifact.

Enum value migration

Repository-owned component options use snake_case. Update Card.visual from accent-gradient to accent_gradient; InputGroupAddon.align from inline-start, inline-end, block-start, or block-end to inline_start, inline_end, block_start, or block_end; and InputGroupButton.size from icon-sm or icon-xs to icon_sm or icon_xs. Matching data-align, data-size, and data-visual values use these new spellings too.

Native HTML input types retain their protocol spelling: for example, ResourceField.control accepts datetime-local and forwards it to the input.