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.
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 | …OptionalYou 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 storeOptionalEach 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 objectOptionalAppearance 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' | …OptionalMost pages ship multiple layouts. Auth pages offer default / minimal / split; data and account pages have their own variants. Switch layout without touching logic.
config + callbacksobjectOptionalFeature 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'OptionalSign-in and sign-up, with captcha, remember-me, a live password-strength meter and terms gating. See Auth Pages.
ForgotPasswordPage / ResetPasswordPage / SetPasswordPage / ChangePasswordPagecredential recoveryOptionalThe full reset/recovery set, plus SetPasswordPage which doubles as the invite-acceptance / magic-link landing. Share one PasswordPolicy engine. See Auth Pages.
VerifyEmailPage / MagicLinkVerifyPagetoken landingsOptionalThe 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.
ProfilePageuseProfileStoreOptionalThe 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.
DevicesPageuseDevicesStoreOptionalActive sessions / devices with DeviceCard + revoke and revoke-all actions — the UI for the multi-device session surface documented under Authentication.
UsersPageuseUsersStoreOptionalAn 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 · usePermissionOptionalClient-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 · RoleClaimEditorOptionalA 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 / useChatOptionalThe 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 / NotificationCenteruseNotificationCenterStoreOptionalA 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 builderOptionalA 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 UIOptionalThe 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.
useNucleusEntityhookOptionalThe 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 hookOptionalThe 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.
DataTablecomponentOptionalA sortable, filterable, paginated table that pairs with useNucleusEntity — column inference from the entity, row selection and bulk actions.
NucleusEntityShowcasecomponentOptionalA 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.
FormBuildercomponentOptionalRenders 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 · TooltipOptionalThemeable form and UI primitives with consistent styling hooks. Captcha is included for bot defence on auth forms.
CaptchacaptchaThemeOptionalThe challenge-response captcha widget (math / image / puzzle / text) wired to CAPTCHA_GENERATE, used by LoginPage but mountable anywhere.
AbstractAnimatedBackgrounddecorative backgroundOptionalA 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.
DesignSystemPageuseDesignSystemStoreOptionalA built-in component explorer (ComponentSidebar, ComponentCanvas, PropsPanel, createDefaultRegistry) — a living style guide for the kit, themeable like everything else.
Utilitiescn · column utils · endpoint keysOptionalcn() 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