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.

the contract in one component
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 | …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. 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' | …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/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 for compact vs full layouts.

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 (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 · 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 and verification subsystems.

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.

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 proof-of-work / challenge widget wired to CAPTCHA_GENERATE, used by LoginPage and RegisterPage but mountable anywhere.

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