@18studio/aicloud-uikit-react

Web React component package for UIKIT v1.

Scope

• React components, providers, hooks, adapters, examples, tests, and documentation.
• May use Web-only libraries such as React DOM, Radix UI, Tailwind CSS 4, TanStack, ECharts, React Flow, Monaco, and browser focus APIs.
• Public component contracts remain AI Cloud UIKIT contracts, not raw engine APIs.
• Components must not fetch product APIs or own canonical data lifecycle.

Phase 3 status

Phase 3 implements the React foundation and primitive/shared components:

• UikitProvider, useUikit, cn(), createVariants(), icon slots, provider metadata, Tailwind token-class integration, and permission/state adapters.
• Action components: Button, IconButton, SplitButton, ActionMenu, CopyButton, and LinkAction.
• Field components: Field, TextInput, TextArea, NumericInput, SearchInput, PasswordInput, OneTimeSecret, MarkdownEditor, and JsonEditor.
• Selection components: Checkbox, RadioGroup, Switch, Select, EntitySelect, MultiSelect, EntityMultiSelect, Combobox, and SegmentedControl.
• Structured inputs: DateTimeInput, DurationInput, MoneyInput, QuantityInput, KeyValueEditor, SchemaFieldRenderer, ExpressionEditor, CronScheduleEditor, and FileDropzone.
• Status and metadata: StatusPill, RiskBadge, ClassificationBadge, EnvironmentBadge, PrincipalBadge, ReferenceLabel, Timestamp, and MetricValue.
• Feedback and state surfaces: InlineNotice, ErrorBanner, ValidationSummary, EmptyState, Skeleton, Progress, ToastCenter, ConnectionState, PartialDataNotice, StaleDataNotice, MutationStatus, BatchResultSummary, and StateSurface.

Phase 4 status

Phase 4 implements shell, navigation, layout, and overlay components:

• Shell/navigation: AppShell, GlobalNav, ScopeSelector, RoleSwitcher, UniversalSearch, CommandPalette, NotificationCenter, ActivityCenter, and ContextHelpPanel.
• Structure: PageHeader, Breadcrumbs, Tabs, Toolbar, Section, Panel, KeyValueList, ResourceSummary, and ResourceOverview.
• Overlays: Modal, ConfirmationDialog, Drawer, DetailsEditDrawer, Popover, and Tooltip.

The components provide responsive mobile/tablet/desktop layout semantics, permission-aware navigation and action affordances, focus and restore handling for dialogs/drawers, escape-key behavior, and dirty/pending guards for unsafe drawer close paths. They remain host-router agnostic: navigation props expose intent and hrefs, but the consuming application owns routing, persistence, API transport, and audit.

Phase 5 status

Phase 5 implements tables and collections for enterprise resource lists:

• DataTable with server-side search, filters, sorting, cursor pagination, column preferences, saved views, row selection, row actions, bulk actions, refresh, export, URL-compatible controlled state, contained horizontal scroll, keyboard row opening with Enter/Space, unknown-value rendering, and required-column protection.
• Table states for loading, empty, no-result, partial, stale, error, unavailable, permission, and unknown values. Loading preserves geometry with skeleton rows; partial and stale states keep valid rows visible; permission and unavailable states use safe explanations supplied by the application.
• Support components: FilterBuilder, ActiveFilterBar, ColumnPicker, SavedViewPicker, BulkActionBar, CursorPagination, InlineEditRow, CollectionCard, and QueueList.
• TanStack Table and TanStack Virtual are declared as internal table-engine dependencies; the public contract remains DataTable, normalized TableQuery, core ColumnDef, and UIKIT intent callbacks.
• TanStack Query integration examples live in examples/preview/src/tables-query-example.ts and tanStackQueryIntegrationExamples. They demonstrate loading, stale refresh, polling, and mutation adapter boundaries without direct product API calls in components.

Phase 5 table events are server-side intent callbacks: search, filter, sort, paginate, select, column preference, saved view, refresh, export, row open, row action, and bulk action events report intent only. Consuming applications own URL serialization, persistence, server cache, query functions, mutation functions, audit, and export transport.

Phase 6 status

Phase 6 complete for forms, editing, and creation:

• FormLayout and FormSection compose accessible form structure, validation summaries, permission states, one/two-column responsive layouts, and application-owned submit intent callbacks.
• DirtyStateGuard preserves entered values and blocks unsafe close, navigation, scope change, entity switch, or tab change when form or wizard state is dirty or pending.
• ConflictResolver, SemanticDiff, and RevisionPicker preserve local input, show semantic differences, and expose reload, merge, or fork recovery intents without owning persistence or product API transport.
• Wizard and WizardStepNav support complex creation with controlled step state, keyboard-operable step buttons, aria-current="step", disabled blocked steps, non-color status symbols, review sidebars, save-draft intent, and submit intent callbacks.
• ReviewStep renders normalized ReviewValue summaries, redaction-aware values, validation issues, and semantic diffs before submission.
• React Hook Form, Zod, and resolver adapters are available through createReactHookFormAdapter(), createZodValidationAdapter(), and createHookFormResolverAdapter(). These adapters are optional: schemas are not UIKIT-only requirement and components do not require schema props.
• Editing rules are enforced and documented through editingSurfaceRules, validateEditingSurfaceUsage(), and data-editing-surface markers: use DetailsEditDrawer for non-trivial existing entities, InlineEditRow for simple row-complete entities, and Wizard for complex creation; no separate details/edit overlays may be created for the same entity.

Form values, wizard drafts, canonical saves, conflict reload/merge/fork, audit, and product API transport remain application-owned persistence. UIKIT components expose normalized models, supplied permissions, validation issues, dirty decisions, and intent callbacks only.

Phase 7 status

Phase 7 complete for governance, approvals, policy review, and release safety surfaces:

• Policy and permission surfaces: PermissionExplanation, EffectivePolicyViewer, PolicyRuleEditor, and PolicyInheritanceDiagram render only application-supplied policy semantics, omit denied rules, and show redacted placeholders instead of restricted content.
• Review and approval surfaces: ImpactPreview, RiskSummary, ApprovalPackageView, ApprovalDecisionPanel, and ReviewQueueTable expose approval and review intent callbacks only; approval decisions require supplied permission and auditable context before submit; audit reason required states keep unsafe actions disabled until applications provide context.
• Validation and evaluation surfaces: ValidationResults and EvaluationScorecard display normalized validation and score evidence with visual state markers, non-color text/status labels, and redaction-aware values.
• Release safety surfaces: ReleaseGateSummary, DependencyDiff, ReleaseBundleView, ReleaseTimeline, and RollbackSelector cover gates, dependency changes, bundles, timelines, and rollback/restore selection without owning product release policy or transport.
• Dangerous or destructive actions such as policy deletion, approval rejection, destructive impact review, and rollback are permission-safe, disabled when audit context is missing, and marked with data-audit-required for application audit pipelines.

Restricted governance, approval, validation, dependency, evidence, and release content is omitted or redacted before render. Business policy semantics, risk scoring, gate evaluation, approval persistence, audit record creation, rollback execution, and product API transport remain application-owned.

Phase 8 status

Phase 8 complete for operations, evidence, timelines, traces, charts, and graphs:

• Operations components: RunStatusPanel, RecoveryPanel, OperationsStatusBoard, and EvidenceList consume normalized run controls, recovery options, trace summaries, audit records, evidence refs, citations, supplied permissions, and intent callbacks only.
• Timeline/trace components: UnifiedTimeline merges timeline events, annotations, audits, and trace summaries; TraceWaterfall renders trace spans with duration text and table/list-readable information.
• Graph components: DependencyGraph, LineageGraph, WorkflowGraph, TopologyExplorer, GraphLegendView, and RelationshipTable consume normalized GraphNode, GraphEdge, GraphLegend, and RelationshipTableRow contracts.
• Chart components: MetricChart, TimeSeriesChart, DistributionChart, ComparisonChart, CapacityBar, RankedBarChart, CompositionChart, TimeCellMatrix, MetricTable, and TimeRangePicker consume NormalizedMetricSeries, TimeRange, Threshold, and TimelineAnnotation without exposing engine option objects.
• ECharts and @xyflow/react are dynamically loaded internal defaults when available; SVG/CSS/list/table fallbacks and table fallbacks are always available, including MetricTable and RelationshipTable textual alternatives.
• Data-quality states are visible through text labels and data-quality; reduced motion is accepted through props or UikitProvider.

Operations policy, run execution, recovery execution, evidence retrieval, graph discovery, metric queries, audit persistence, and product API transport remain application-owned.

Phase 9 status

Phase 9 complete for technical and runtime surfaces:

• Code and editing surfaces: CodeBlock and YAMLEditor expose copy/export/validate intents, redaction placeholders, and lazy Monaco loading as an internal default with a textarea fallback rather than public Monaco APIs.
• Output surfaces: LogViewer and Terminal preserve buffered output during disconnected/reconnecting states, expose copy/export/download/terminal-signal intents only, and avoid permanent keyboard traps by releasing terminal focus on Escape.
• Inspection surfaces: PayloadInspector, SchemaViewer, and DiffViewer render normalized payload, schema, and diff models with permission and redaction states before visible content.
• Runtime resource surfaces: FileTree, ArtifactList, WorkspacePanel, SnapshotList, DiffSummary, WorktreeStatus, MountList, and ScanResultList cover file, artifact, workspace, snapshot, diff, worktree, mount, and scan result workflows with state/intent callbacks only.
• Copy, export, download, permission, and redaction examples live in examples/preview/src/technical-runtime-example.ts.

Workspace file retrieval, artifact download transport, terminal process execution, log streaming, schema validation semantics, scan execution, mount execution, snapshot restore execution, audit persistence, and product API transport remain application-owned.

Phase 10 status

Phase 10 complete for application runtime surfaces:

• Business-language-first runtime entry: DomainActionLauncher and DynamicForm model domain outcomes, required business inputs, permissions, and state/intent callbacks without making prompt entry the primary contract.
• Results and artifacts: ResultCard, ResultTable, and EditableArtifact render normalized result summaries, citation evidence, artifact references, dirty-state editing, and feedback intents.
• Conversation and streaming: ConversationThread and StreamingResponse render accessible streaming with aria-live, aria-busy, retention-boundary metadata, and forbidden-history tests that omit excluded or forbidden retained messages before render.
• Required input, approvals, and runs: RequiredInputPrompt, RuntimeApprovalCard, and ApplicationRunStatus expose required input, runtime approval, audit reason, run step, and run control intents only.
• Feedback and channels: FeedbackControl and ChannelPreview support permission-aware feedback and channel previews with citation, artifact, retention-boundary, and application-owned send intents.

Runtime transport, product API transport remain application-owned, as do model execution, channel delivery, approval persistence, feedback persistence, conversation retention selection, audit storage, and server state. Components consume normalized models, supplied permission decisions, and state/intent callbacks only.

Phase 11 status

Phase 11 complete for reusable domain composition contracts and examples:

• DomainCompositionWorkbench, CompositionSlotList, and CompositionTraceabilityTable render normalized DomainCompositionContract, CompositionSlotContract, and CompositionTraceabilityEntry models.
• Composition domains cover Managed Models, Knowledge & Retrieval, MCP, Agent, Workflow, AI Application, Context, Workspace, Organization, IAM/Security, Policy, Capacity, Registry, Connectors, Assurance, Observability & Audit, GPU Telemetry & Profiling, and SaaS Operations.
• UF-001 through UF-100 support is verified through composition traceability, not business-flow implementation; each UF row maps to existing reusable UIKIT slots such as shell, tables, forms, governance, operations, technical runtime, and application runtime components.
• The no-local-fork policy is explicit: reject local forks in favor of variants/slots/documented composition, and keep domain-specific orchestration, runtime transport, telemetry collection, profiling capture, audit persistence, SaaS operations execution, and product API transport remain application-owned.
• Responsive and permission behavior is inherited from reusable slots and reinforced by md/xl layout markers, PermissionDecision filtering, and data-no-local-fork evidence markers.

Phase 12 status

Phase 12 complete for cross-catalog quality gates:

• Cross-catalog accessibility and responsive evidence verifies tables, forms, governance, operations, technical runtime, application runtime, and domain compositions retain semantic labels, aria-live/aria-busy, keyboard escape/release paths, table alternatives, and md/xl responsive behavior instead of removing accessibility alternatives to pass performance.
• Security/permission/redaction checks cover dangerous action gates, data-audit-required audit-context requirements, omitted denied rows, redaction placeholders, and guarded copy/export/download/terminal/code/payload/artifact/secret-adjacent transport paths with data-redaction-transport-guard markers.
• Error, trace, citation, and audit leakage checks preserve safe StateSurface errors, trace/citation redaction, audit reason requirements, and application-owned product API transport.
• Performance gates for tables/logs/metrics/heavy engines/loading fallbacks keep DataTable skeleton rows, log append bounds, MetricTable/relationship table alternatives, dynamic heavy-engine fallbacks, and reduced-motion/data-quality states.

Phase 13 status

Phase 13 complete for UIKIT v1 release readiness:

• TASK-13-01 component DoD complete: the component inventory marks each item complete for purpose, use, prohibited use, anatomy, variants, props, slots, events, states, normalized model boundary, permission boundary, examples, keyboard/focus and accessible role/name/state evidence, light/dark/long-content/responsive/material-state evidence, and performance evidence where applicable.
• TASK-13-02 external artifacts complete: package READMEs, component inventory, token sheet, dependency decision register, preview route, accessibility/visual evidence archive, migration notes, spec traceability matrix, confirmation dependency register, performance reports, and release-readiness report are stored outside specifications/uikit-v1/.
• TASK-13-03 final readiness review: package boundary gate passed, React Native readiness is preserved through neutral tokens/core contracts, engine-independent public contracts are documented, unresolved confirmations are explicit release blockers, no hidden public-contract dependency on implementation engines remains, and product API transport remains application-owned.

Component contract notes

Purpose

Primitive components provide the reusable Web React foundation for higher-order UIKIT surfaces while preserving normalized models, supplied permissions, semantic tokens, accessible names, keyboard focus, and safe state explanations.

Use

Use these components for base controls, field composition, low-level selection, metadata display, and reusable loading/empty/error/permission/disconnected/partial/stale surfaces. Compose them in shell, table, form, governance, operation, and runtime components instead of creating local forks.

Prohibited use

Do not pass raw backend responses, infer permissions from hidden data, embed product API calls, use hardcoded product colors, use emoji status icons as the only signal, or expose a lower-level engine such as Radix as the public product contract.

Anatomy

Each primitive exposes a stable root element, semantic token classes, optional slots for labels, descriptions, icons, actions, errors, and children, plus data-state or permission attributes when state affects rendering.

Variants

Shared variants cover size (sm, md, lg), semantic tone (neutral, info, success, warning, error), action style (primary, secondary, ghost, danger), density through the provider, and state via DataState mappings.

Props and slots

Props accept React children and primitive-specific values. Intent callbacks such as onAction, onCopy, and onChange expose user intent only; consuming applications own transport, persistence, audit, and server state.

Events

Events are local interaction events or intent callbacks. No primitive performs fetches, mutations, cache invalidation, or audit persistence directly.

State coverage

StateSurface and feedback primitives cover loading, empty, partial, stale, error, unavailable, permission, disconnected, deleted, conflict, and pending-action presentations. adaptPermissionState() and mapUxStateToDataState() map blocked/denied to permission and degraded UX to partial, stale, unavailable, or a safe warning metadata surface.

Normalized model boundary

Primitives consume normalized core models such as PermissionDecision, AsyncActionState, SafeUiError, ResourceRef, and FormValidationIssue. Product-specific schemas are adapted before render by the consuming application.

Permission boundary

Components render disabled, omitted, or explanatory UI from supplied PermissionDecision. They do not infer access, fetch missing permission data, or render restricted content for later redaction.

Phase 4 layout and overlay boundary

Shell and navigation components consume normalized navigation/resource models (NavItem, ResourceRef, PermissionDecision) plus intent callbacks such as onNavigate, onSearch, and onCommand; they do not import or require a host router. Overlay components expose open/onOpenChange controlled state, trap user attention with dialog roles, restore focus when closed, and use dirty/pending guards to block unsafe close when supplied by the application. Mobile behavior uses overlay global navigation and full-width drawers, tablet behavior uses collapsible-width structures, and desktop behavior supports persistent navigation, dense toolbars, and standard drawers.

Evidence

• scripts/check-react-primitives.mjs verifies Phase 3 exports and required documentation headings.
• scripts/check-react-shell.mjs verifies Phase 4 shell/navigation/overlay exports, documentation, preview route, inventory, and traceability updates.
• scripts/check-react-tables.mjs verifies Phase 5 tables/collections exports, controlled state, server-side intent markers, required-column protection, query examples, artifact updates, no product API transport, and representative 100-row performance.
• scripts/check-react-forms.mjs verifies Phase 6 form/editing exports, React Hook Form/Zod/resolver dependencies, dirty/conflict/wizard accessibility markers, editing rules, preview examples, and evidence artifacts.
• scripts/check-react-governance.mjs verifies Phase 7 governance/release exports, permission/redaction markers, approval and audit safeguards, visual-state markers, preview examples, and evidence artifacts.
• scripts/check-react-operations.mjs verifies Phase 8 operations/visualization exports, engine-independent contracts, dynamic ECharts/@xyflow loading/fallback markers, table alternatives, data-quality/reduced motion evidence, no product API transport, and the 1000 samples across 10 series performance fixture.
• scripts/check-react-runtime.mjs verifies Phase 9 technical/runtime exports, keyboard release, Monaco lazy fallback markers, log/terminal disconnected output preservation, permission/redaction/copy/export/download examples, no product API transport, and representative 100-line log frame append under 16ms where practical.
• scripts/check-react-application-runtime.mjs verifies Phase 10 application runtime exports, business-language-first examples, accessible streaming, citation, artifact, feedback, retention-boundary, forbidden-history tests, permission, responsive markers, no product API transport, and state/intent callbacks only.
• scripts/check-react-compositions.mjs verifies Phase 11 domain composition exports, all required composition domains, UF-001..UF-100 composition traceability, responsive markers, PermissionDecision filtering, no-local-fork policy, variants/slots/documented composition evidence, and no product API transport.
• scripts/check-react-cross-catalog-quality.mjs verifies Phase 12 cross-catalog accessibility, responsive, security/permission/redaction, dangerous action, copy/export/download/terminal/code/payload/artifact/secret-adjacent, error, trace, citation, audit leakage, and performance gates for tables/logs/metrics/heavy engines/loading fallbacks.
• scripts/check-release-readiness.mjs verifies Phase 13 UIKIT v1 release readiness, component DoD complete status, external artifacts complete status, package boundary gate passed evidence, React Native readiness, engine-independent public contracts, explicit release blockers for unresolved confirmations, and no hidden public-contract dependency on implementation engines.
• examples/preview/src/route.ts records Phase 13 preview status and component families; examples/preview/src/tables-query-example.ts records TanStack Query adapter examples; examples/preview/src/forms-editing-example.ts records forms, dirty guard, conflict, wizard, review, and adapter examples; examples/preview/src/governance-release-example.ts records governance, approval, release, rollback, permission, redaction, and audit examples; examples/preview/src/operations-visualization-example.ts records operations, graph, chart, data-quality, reduced motion, and performance examples; examples/preview/src/technical-runtime-example.ts records technical runtime copy, export, download, permission, redaction, disconnection, keyboard, and Monaco lazy examples; examples/preview/src/application-runtime-example.ts records application runtime domain action, dynamic form, result, artifact, conversation, streaming, approval, run, feedback, channel, retention-boundary, and forbidden-history examples; examples/preview/src/domain-composition-example.ts records Phase 11 composition contracts, no-local-fork policy, and UF traceability.
• docs/uikit-v1/component-inventory.md, docs/uikit-v1/spec-traceability-matrix.md, and docs/uikit-v1/artifacts/release-readiness.md track final acceptance status.

Source

Derived from platform/specifications/uikit-v1/SPEC.md.