Frontend Components

Drop-in, themeable React UI for every feature

The package is two things, not one. You already met the typed client (generateAllEndpoints → useApiActions); the second half is nucleus-core-ts/fe — a complete React component library that renders the screens those actions power. Import a LoginPage, a UsersPage, an RBAC console or a visual approval-flow builder and wire it to the matching generated action. You own the routing and the look; the component owns the form, the state machine and the API choreography.

Every component follows one contract, so learning one teaches you all of them: you pass the generated action(s) in as props, the component drives its own h-state store (useXStore), and its appearance comes from a theme object (xTheme) you can deep-merge with extendXTheme(). Most pages also expose layout variants. Nothing is locked down — there are no hard-coded endpoints and no global styles to fight.

This page is the map of what ships. Auth Guard and Auth Pages have their own deep dives; the rest are catalogued here with the import you need.

The shared contract#

Five conventions hold across the whole library. Internalise these once and every component below reads the same way.

the contract in one component
1import { LoginPage } from "nucleus-core-ts/fe";2import { useApiActions } from "@/lib/api";3 4export default function SignIn() {5  const actions = useApiActions();6  return (7    <LoginPage8      variant="split"9      loginAction={actions.LOGIN}      // generated action, injected10      meAction={actions.ME}11      captchaGenerateAction={actions.CAPTCHA_GENERATE}12      showRememberMe13      signUpHref="/register"14      onSuccess={() => router.push("/app")}15    />16  );17}
actions as propsLoginAction | RegisterAction | …Optional

You inject the generated action (from useApiActions) rather than the component calling fetch itself. That keeps the component transport-agnostic and fully typed against your config, and lets it run behind your proxy/cookies. Each action exposes { start({ payload, onAfterHandle, onErrorHandle }), state }.

useXStoreh-state storeOptional

Each component family owns a store (useLoginStore, useUsersStore, useNotificationCenterStore, …) holding its form/UI state. You can read or drive it from outside for custom layouts without forking the component.

xTheme + extendXTheme()theme objectOptional

Appearance is a plain theme object exported alongside the component (chatPanelTheme, notificationCenterTheme, authorizationPageTheme, …), which you can deep-merge with its extendXTheme({ … }) helper. Themes are Tailwind-class based, so they inherit your design tokens.

variant'default' | 'minimal' | 'split' | …Optional

Most pages ship multiple layouts. Auth pages offer default / minimal / split; data and account pages have their own variants. Switch layout without touching logic.

config + callbacksobjectOptional

Feature toggles (showRememberMe, password policy, channels…) live in a config object, and lifecycle hooks (onSuccess, onLogout, onForgotPassword…) let you own navigation. Sensible defaults mean the minimal wiring is just the action.

Auth & account pages#

The credential lifecycle and the logged-in account surface, as ready pages. The eight credential pages get a full walkthrough on Auth Pages; the three account pages are listed here.

LoginPage / RegisterPageimport { … } from 'nucleus-core-ts/fe'Optional

Sign-in and sign-up, with captcha, remember-me, a live password-strength meter and terms gating. See Auth Pages.

ForgotPasswordPage / ResetPasswordPage / SetPasswordPage / ChangePasswordPagecredential recoveryOptional

The full reset/recovery set, plus SetPasswordPage which doubles as the invite-acceptance / magic-link landing. Share one PasswordPolicy engine. See Auth Pages.

VerifyEmailPage / MagicLinkVerifyPagetoken landingsOptional

The pages a user lands on from a verification or magic-link email — they consume the token, call the verify action and render verifying / success / error states.

ProfilePageuseProfileStoreOptional

The signed-in user's profile with AddressCard, PhoneCard and ProfileHeader sub-components, hydrated from the ME response. Variants (default / minimal / compact) for different layout densities.

DevicesPageuseDevicesStoreOptional

Active sessions / devices with DeviceCard + revoke and revoke-all actions — the UI for the multi-device session surface documented under Authentication.

UsersPageuseUsersStoreOptional

An admin user-management console composed of a user list + detail panel over the admin user actions — list, inspect and act on users.

Access control#

Guard routes and administer the RBAC model the Authorization config defines.

AuthGuardLoginChecker · RoleChecker · usePermissionOptional

Client-side route protection and reactive UI gating by role/claim/scope, hydrated from the ME action. Has its own deep dive — see Auth Guard.

AuthorizationPageRoleList · ClaimList · RoleClaimEditorOptional

A full RBAC console: browse roles and claims and edit role→claim assignments visually. Backed by useAuthorizationStore with its own extendable theme — the admin UI for everything on the Authorization page.

Workflow & messaging#

The user-facing surfaces for the notification, verification and chat subsystems.

ChatPanel / NewConversationModaluseChatStore / useChatOptional

The 1:1 + group realtime chat surface wired to the generated chat actions — conversation list, message thread, typing/read receipts and attachments, with an extendable chatPanelTheme. Backed by usePubSub for live message/typing events. See Chat.

NotificationBell / NotificationCenteruseNotificationCenterStoreOptional

A bell with an unread badge and a dropdown/drawer center, wired to NOTIFICATION_LIST / UNSEEN_COUNT / MARK_SEEN / MARK_ALL_SEEN. Variants and an extendable theme. See Notification.

VerificationFlowPagevisual flow builderOptional

A node-graph editor (NodePalette, StepFlowNode, VerifierFlowNode, NotificationFlowNode, PropertiesPanel, PendingTab) for authoring the approval flows the Verification engine runs — drag steps, verifiers and notification rules, then publish.

VerificationPanel / PendingVerificationsreviewer UIOptional

The approver-facing widgets: a panel to act on one record's pending verification, and a list of everything awaiting the current user — built on VERIFICATION_PENDING / STATUS / DECIDE.

Data & forms#

Turn an entity definition into a working data UI with almost no glue code.

useNucleusEntityhookOptional

The data engine: pass an entity + your apiActions and get items, pagination meta, isLoading, infinite loadMore (de-duplicated), addItem/updateItem/deleteItem, bulkAdd/bulkDelete, and search/sort/filter state — all routed through the generated CRUD actions for that table.

usePubSubrealtime hookOptional

The realtime hook for subscribing to pub/sub topics / live events over the WebSocket — the backbone behind chat, notification and presence updates. Subscribe to topics (presence arrives as ordinary events over the same socket, not a dedicated tracker API), auto-reconnect with heartbeats, and acknowledge delivery.

DataTablecomponentOptional

A sortable, filterable, paginated table that pairs with useNucleusEntity — column inference from the entity, row selection and bulk actions.

NucleusEntityShowcasecomponentOptional

A batteries-included CRUD surface for an entity (list + create/edit forms + detail) — the fastest way to get an admin screen for any table you declared.

FormBuildercomponentOptional

Renders a typed form from a field config / entity columns, with validation derived from the column definitions.

Primitives & tooling#

The lower-level building blocks the pages are composed from — usable on their own — plus the design-system harness and shared utilities.

InputsButton · Checkbox · NucleusTextInput · SelectBox · SearchBox · DatePicker · RangePicker · TooltipOptional

Themeable form and UI primitives with consistent styling hooks. Captcha is included for bot defence on auth forms.

CaptchacaptchaThemeOptional

The challenge-response captcha widget (math / image / puzzle / text) wired to CAPTCHA_GENERATE, used by LoginPage but mountable anywhere.

AbstractAnimatedBackgrounddecorative backgroundOptional

A lightweight animated FOG background (Vanta-FOG-style) for auth and landing screens — one full-screen WebGL fragment-shader draw call per frame at a capped device-pixel-ratio, so it holds 60fps cheaply. Rewritten from the old three.js/react-three-fiber 'marble' implementation: it now has ZERO extra dependencies (no three / @react-three/fiber to install). Backward compatible — the previous className-only usage renders unchanged — and customizable via optional props: baseColor / lowlightColor / midtoneColor / highlightColor (hex), speed, zoom, blur, maxDpr. Defaults keep the old indigo→blue→purple→pink feel. Respects prefers-reduced-motion (renders a single static frame), pauses while off-screen, and falls back to a CSS gradient when WebGL is unavailable.

DesignSystemPageuseDesignSystemStoreOptional

A built-in component explorer (ComponentSidebar, ComponentCanvas, PropsPanel, createDefaultRegistry) — a living style guide for the kit, themeable like everything else.

Utilitiescn · column utils · endpoint keysOptional

cn() for class merging; column helpers (getColumnType, isReferenceColumn, shouldExcludeFromForm…); and endpoint-key generators (generateEntityEndpointKey, toUpperSnakeCase…) that map an entity to its generated action keys.

Related sections