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/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 Zustand 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, extendLoginPageTheme } from "nucleus-core/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 theme={extendLoginPageTheme({ accent: "var(--brand)" })}16 />17 );18}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. Use the exported default (loginPageTheme, notificationCenterTheme, …) as-is, or extendXTheme({ … }) to deep-merge overrides. Tailwind-class based, so it inherits 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/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 for compact vs full layouts.
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 (UserListItem + UserDetailPanel) 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 and verification subsystems.
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.
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 proof-of-work / challenge widget wired to CAPTCHA_GENERATE, used by LoginPage and RegisterPage but mountable anywhere.
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