React components and hooks

Choose a task below, then copy the matching import and example. The package root supplies pure contracts and helpers; /host supplies host-bound runtime APIs; /testing supplies test helpers. A registered screen runs inside the configured NEXIA host.

Find an API

Task-specific host APIs

Import these APIs from @nexia/sdk/host. Core connects components, hooks, runtime functions and registries in resources/js/app-sdk/configure-host.ts. SDK exports and Core bindings do not establish tenant/user availability or authorization. Pure helpers need no binding; SDK-composed helpers such as useFeedbackAction and useDataMigrationBackgroundOperation use existing host APIs/hooks.

Signature

Import pure contracts from the package root. Import host-bound components, hooks, registries, and the HTTP client from the host subpath:

import type { ResourceListSchema } from "@nexia/sdk";
import {
    WorkSurface,
    ResourceTable,
    NxSearchField,
    useResourceListParams,
    api,
    can,
} from "@nexia/sdk/host";123456789

The package declares its runtime libraries as peer dependencies, so your App shares the host's copies rather than bundling its own:

{
    "peerDependencies": {
        "@nexia/sdk": "0.5.0",
        "@tanstack/react-query": "^5.99.0",
        "axios": "^1.11.0",
        "react": "^19.1.0"
    }
}12345678

Never add these to your App's dependencies. A second React or Query client in the bundle breaks context.

App frontend boundary rules

Every external package imported by App frontend source must be declared in that App's own package.json. A package supplied or hoisted by Core is not an implicit dependency. For example, importing axios without declaring it is a phantom dependency even when the current host installation happens to resolve it.

Runtime singletons belong in peerDependencies: react, react-dom, @tanstack/react-query, and @nexia/sdk. Declare axios as a peer with the repository convention ^1.11.0 when the App imports it. Test-only tools may be devDependencies; runtime imports may not rely on them.

Cross-boundary interaction goes through SDK contracts only. Use the package root for pure contracts and the /host subpath for host-bound APIs. #app/* resolves inside resources/js; #lang/* resolves inside the fixed resources/lang contract path. Both are App-internal package imports. Neither authorizes Core aliases, cross-App imports, or imports into another package. Because package imports targets are exact, include the source extension in #app specifiers, for example #app/resources/orders/order-resource-contract.ts.

The host discovers an App only through these fixed shapes:

• composer.json → extra.nexia.app
• resources/js/index.ts
• resources/js/resources/*/*-resource-contract.ts
• resources/lang

Do not move or rename those discovery surfaces. Their contents and every other module under the App remain App-private; discovery is not a general import API.

The SDK itself resolves through its exports conditions, never through a path alias. The development condition serves TypeScript source directly, so the dev server, Vitest, and typecheck need no built artifact; production builds resolve the import condition against dist, which task frontend:build compiles first. If a subpath fails to resolve, check the installed SDK version and its package exports before changing imports.

Minimal example

An App entry registers its surfaces and its Inspector adapters lazily. Two calls cover the conventional layout:

import {
    autoRegisterPackageResourceInspectors,
    autoRegisterPackageSurfaces,
} from "@nexia/sdk/host";

autoRegisterPackageResourceInspectors(
    import.meta.glob("./resources/*/inspector/register-*-inspector.ts", {
        eager: true,
    })
);

autoRegisterPackageSurfaces({
    appPrefix: "Workshop",
    appKey: "workshop",
    overview: () => import("./overview/WorkshopOverviewSurface"),
    surfaces: import.meta.glob("./resources/*/surface/*Surface.tsx"),
});1234567891011121314151617

appComponentRegistry is host-only. It exists in the platform at resources/js/shell/runtime/app-component-registry.ts, but @nexia/sdk does not export it — so an App Package can only reach it through a forbidden @shell/ alias. Older documentation shows appComponentRegistry.register(...); use autoRegisterPackageSurfaces instead, and registerAgentComponent for agent components.

Both registrations are filesystem-derived. autoRegisterPackageResourceInspectors rejects a path outside ./resources/{resource}/inspector/register-{resource}-inspector.ts, so a hand-maintained list of Inspector side-effect imports is never needed.

Parameters

AutoRegisterPackageSurfacesOptions:

Component names are derived from the surface file path. A surface that has moved or been renamed needs an overrides entry, or the backend's published pageElements() name will have no binding.

Route prefetch overrides

PackageSurfaceOverride accepts either the existing bare lazy loader or an explicit registration with load and an optional routePrefetcher:

This Note detail example uses the generated endpoint and cache key. Put noteDetailQueryOptions in a Resource-local query module and import that same function in the entry and NoteShowSurface; remove the surface’s original local copy. The endpoint authorizes the stored owner. Do not infer a list target from Shell context to prefetch a Legal Entity list.

import { queryOptions } from "@tanstack/react-query";
import { api, autoRegisterPackageSurfaces } from "@nexia/sdk/host";
import {
    type NoteRecord,
    noteApiRoute,
} from "#app/resources/notes/note-resource-contract.ts";

function noteDetailQueryOptions(tenantId: string, id: string) {
    return queryOptions({
        queryKey: ["workshop-note", tenantId, tenantId, id],
        queryFn: async ({ signal }) => {
            const { data } = await api.get<{ note: NoteRecord }>(
                noteApiRoute(id),
                { signal },
            );
            return data;
        },
    });
}

autoRegisterPackageSurfaces({
    appPrefix: "Workshop",
    appKey: "workshop",
    overview: () => import("./overview/WorkshopOverviewSurface"),
    surfaces: import.meta.glob("./resources/*/surface/*Surface.tsx"),
    overrides: {
        WorkshopNoteShowSurface: {
            load: () => import("./resources/notes/surface/NoteShowSurface"),
            routePrefetcher: ({ queryClient, tenantId, params }) => {
                if (!tenantId || !params.id) return false;
                void queryClient.prefetchQuery(
                    noteDetailQueryOptions(tenantId, params.id),
                );
                return true;
            },
        },
    },
});1234567891011121314151617181920212223242526272829303132333435363738

The host starts this prefetcher on the same navigation tick as the surface chunk request. Returning true marks the route as handled and suppresses the surface module's later prefetch fallback. Returning false keeps that fallback, which is appropriate when a permission or route parameter is missing. The context also supplies Legal Entity, pathname, search parameters, route pattern, and parsed route parameters.

Keep the prefetcher in a module that does not eagerly import the surface component. Importing that component defeats code splitting by pulling the surface into the App entry chunk.

Responsive layout parameters

NxResponsiveRegion accepts normal HTMLAttributes<HTMLDivElement> and makes its allocated inline size available to descendant CSS container queries. NxAdaptiveSplit establishes that region itself and adds these options:

Output or return: Layout primitives

Import these instead of writing layout markup. They carry the Shell's spacing, density, and dark-mode behavior.

In-place tab navigation

NxTabNav renders the host's shared underline-tab interaction while the App owns the selected value and the content below it. It does not navigate, fetch, or persist state. Keep URL synchronization in the App when a tab must survive a reload or be shareable.

import type { NxTabNavItem } from "@nexia/sdk";
import { NxTabNav } from "@nexia/sdk/host";

const tabs: NxTabNavItem[] = [
    { id: "daily", label: t("attendance.tabs.daily") },
    {
        id: "issues",
        label: t("attendance.tabs.issues"),
        badge: openIssueCount,
    },
];

<NxTabNav
    aria-label={t("attendance.tabs.label")}
    items={tabs}
    value={activeTab}
    onChange={setActiveTab}
    scrollable
/>;12345678910111213141516171819

items, value, and onChange are required. Each NxTabNavItem has an id and label, with optional badge, disabled, and testId. Use scrollable when the complete tab set may not fit the allocated pane width, and supply an aria-label that names the group rather than repeating one tab label.

Section spacing ownership

AppRouteFrame owns the gap between its direct section children. A reusable component that renders two or more complete sibling sections uses NxSectionStack; do not reproduce that contract with space-y-section or a local gap. NxFormSection requires an explicit spacing choice: use spacing="stack" for fields within one section and spacing="section" when its direct children are independent section cards.

Shared Resource information schema

An ordinary CRUD Resource declares its sections and fields once with defineResourceInformationSchema. Each field owns one label key, help or definition keys, requirement classification, responsive span, projection modes, read value, and Edit control. NxResourceInformationView and NxResourceInformationForm then preserve the same section and field order.

For unsaved form automation, pass binding={{ effect: 'draft', disabled: pending }} to NxResourceInformationForm. A published Resource route supplies its resource key, mode, record identity and route scope. Outside that route owner, supply resourceKey, resourceId and scopeKey explicitly. Do not repeat schema fields in a separate Agent map or add an Agent registration to every Resource.

Use the controls' public value writers, such as NxTextInput.onValueChange below; an event-only onChange does not expose a safe draft setter. Existing field labels and current selectable options describe the mounted action. Hidden, sensitive, read-only, disabled and unsupported controls are excluded. Missing bindings and effect: 'autosave' do not expose draft actions. Keep the page's permission gate. The shared batch validates up to 32 supplied fields before writes, protects user edits and reports an unsaved draft after render; it does not invoke Save.

Agent-visible screen callbacks declare effect: 'read' | 'draft'. Shared list, option-search and form hosts provide this at their common registration point; Resource authors do not duplicate it. Unclassified callbacks and generic DOM event filling/clicking are not executable. An explicitly requested save uses an existing server mutation tool with its operation policy and confirmation flow.

For remote single-choice controls, NxCombobox.searchOptions accepts a scopeKey and search(query, signal?) returning authorized options. Reuse the picker's existing lookup and cache; searching neither selects nor saves a value. The draft setter accepts only an enabled option in the currently loaded list. Multi-select is not exposed by this search contract.

Nested information schemas reuse their existing section and field keys for identity. Repeated sections need stable row keys; array positions are not stable when rows reorder. A bound NxOrgChart uses its existing selectable nodes and controlled selectedId/onSelect for draft selection. This does not authorize moving nodes, editing the hierarchy or automating read-only Inspector charts.

Composed forms without an information schema may declare the same binding on NxFormSection and canonical NxFormField.fieldKey identities for ordinary fields. Schema forms already supply field identity: do not repeat it. sensitive excludes a composed field. Existing typed writers and choice lists remain authoritative. Disable bindings when permission is absent, submission is pending, or an embedded change callback can persist data. Repeated rows still need stable identities.

import {
    defineResourceInformationSchema,
    resourceInformationValue,
} from "@nexia/sdk";
import {
    NxTextInput,
} from "@nexia/sdk/host";

interface DetailContext { item: { name: string } }
interface FormContext { name: string; setName: (value: string) => void }

const schema = defineResourceInformationSchema<DetailContext, FormContext>()({
    sections: [
        {
            key: "basics",
            titleKey: "orders.sections.basics",
            fields: [
                {
                    key: "name",
                    labelKey: "orders.name.label",
                    helpKey: "orders.name.help",
                    requirement: "save",
                    view: ({ item }) => resourceInformationValue(item.name),
                    edit: {
                        kind: "control",
                        render: ({ context }, slot) => (
                            <NxTextInput
                                id={slot.id}
                                aria-describedby={slot.describedBy}
                                value={context.name}
                                onValueChange={context.setName}
                            />
                        ),
                    },
                },
            ],
        },
    ],
});123456789101112131415161718192021222324252627282930313233343536373839

Use modes for static View/Create/Edit omissions; context-dependent visibility.view, visibility.create, and visibility.edit run only after that mode contract. Use span: "full" for wide fields. A section may set one or two formColumns and an optional aggregate/projection source; View remains an ordered detail list. visibleEmptyRequirements controls which empty requirement classes remain visible in NxResourceInformationView. Use a custom Edit projection for a compound control, while the field keeps its single View value and canonical position. Route loading, mutations, permission decisions, related-resource actions, and Inspector density remain Surface-owned. Do not create separate Show and Form field lists or surface-specific section translation keys for the same information.

Container-responsive layouts

Use NxAdaptiveSplit for the common primary-plus-supporting layout. It stays a single column until the component itself receives enough width, so opening the Activity Center or moving the tab into a narrow split pane moves the aside below the primary content even when the browser remains wide.

import {
    NxAdaptiveSplit,
    NxSectionCard,
    NxSectionStack,
} from "@nexia/sdk/host";

export function OrderDetail() {
    return (
        <NxAdaptiveSplit>
            <NxSectionStack>
                <NxSectionCard title="Order">Order fields</NxSectionCard>
            </NxSectionStack>
            <aside>
                <NxSectionStack>
                    <NxSectionCard title="Actions">Order actions</NxSectionCard>
                    <NxSectionCard title="History">Order history</NxSectionCard>
                </NxSectionStack>
            </aside>
        </NxAdaptiveSplit>
    );
}123456789101112131415161718192021

Use NxResponsiveRegion when the layout is not a two-column split. Container variants on descendants measure the nearest region, not window.innerWidth:

import { NxResponsiveRegion } from "@nexia/sdk/host";

<NxResponsiveRegion>
    <div className="grid gap-4 @min-[36rem]:grid-cols-2">
        <section>Summary</section>
        <section>Evidence</section>
    </div>
</NxResponsiveRegion>;12345678

Core binds both facades to the native CSS implementation. The live approval detail at resources/js/core/approval/ApprovalCaseSurface.tsx is the source example: its actions and history move below the document when the work region falls below the split threshold. No resize listener or ResizeObserver is involved.

Organization selection

The SDK already provides the generic NxCombobox; the organization controls reuse shared choice primitives and add organization-specific presentation.

Use NxOrganizationTargetSelector for a page-owned list scope. Import it and useOrganizationListScope from @nexia/sdk/host; pass the page's read permission explicitly. The hook signature is useOrganizationListScope(tenantId, permission, mode = "legal-entity-list", enabled = true).

With one authorized option, the selector displays a summary without setting value or calling onChange. The Surface owns any single-target default; create and recovery forms that require a selection use the form contracts below.

The hook supports the two list modes. Inside a Route Surface, connect its selectorProps directly to the frame slot:

import {
    NxOrganizationTargetSelector,
    NxPageFrame,
    useOrganizationListScope,
} from "@nexia/sdk/host";

const scope = useOrganizationListScope(tenantId, readPermission);

<NxPageFrame
    organizationScope={<NxOrganizationTargetSelector {...scope.selectorProps} />}
>
    {children}
</NxPageFrame>;12345678910111213

tenantId, readPermission, and children above belong to the consuming Surface. Use "legal-entity-operating-unit-list" as the third hook argument for an LE/OU list. NxPageFrame places the selector after the breadcrumb and before actions; AppRouteFrame also accepts organizationScope. The frame provides placement, while the Surface owns the permission, supported axes, and list query. Do not repeat the selector in actions, the table toolbar, or ordinary column filters.

Fetch the list only when scope.requestParams !== undefined; pass those URLSearchParams to the request and include the selected scope in its cache key. An empty parameter set means all authorized targets. An undefined set means the scope is loading, invalid, unavailable, or disabled: do not replace it with an empty set and fetch a broader list. The selector's status presents the non-ready state. Canonical list keys are legal_entity_public_ids[] and operating_unit_public_ids[].

The target catalog comes from useOrganizationTargetsQuery for the requested permission. Preserve the returned exact LE/OU pairs; never form a Cartesian product from independent lists. Backend authorization remains authoritative. Custom relationship or multi-permission pages may keep their own URL adapter and target loading while reusing the selector. Standard tenant common-data pages have no selector; a tenant-owned custom relation or Operating Unit page may explicitly declare organization read scope. Record ownership alone does not determine list scope.

For forms, use the body rather than the header scope slot:

• NxResourceInformationForm.legalEntity accepts the root-exported ResourceFormLegalEntity: create uses { kind: "select", value, options, onChange } with optional disabled and error; edit uses { kind: "stored", label } from the saved record or an authorized lookup. The host places it first inside the first schema section at full width. Omit it when unnecessary and remove a duplicate form-schema owner field; retain the View/Inspector owner field.
• Custom forms use NxResourceFormLegalEntityField from /host inside their first input section, passing target and mode="create" or mode="edit".
• NxOperatingUnitSelector from /host is a single-choice, full-width OU form input with localized defaults. Supply authorized options, value, and onChange; the App owns target loading and clearing dependent values when the Legal Entity changes. It does not change page or Shell scope.

The older OperatingUnitScopeField takes an OperatingUnitScopeResult through its scope prop and renders a selected-OU scope panel. It is not the LE/OU multi-select list contract or the form input above. Keep existing workflows that need that contract explicit; use NxOrganizationTargetSelector for new page-owned list scopes. Detail and edit display the saved owner, and no selector creates a Shell-global active organization.

Form and input controls

Use NxButton, NxIconButton, or NxActionButton for commands such as submit, retry, open a dialog, or mutate data. Use NxLinkButton href or NxIconLink href when activating the control changes the route. Their real link destination preserves browser link behavior and adds the Shell's right-click Open in new work tab action for internal routes. onNavigate on NxLinkButton is an optional navigation side effect; it does not replace href.

With NxCombobox multiple, the host adds a localized close action to the fixed panel footer. Set showSelectedItems when selected values must remain visible as removable chips below the field. Use selectedItemsAriaLabel and removeSelectedItemLabel when the default accessible labels are not specific enough for the field.

Radio cards

NxRadio accepts variant="default" | "card"; omitting it keeps the existing circular radio. Use card for a single-choice option that needs a larger label or explanation. Both variants use the same native radio and NxRadioGroup value/name/onChange contract, including keyboard navigation and disabled state. inputSize controls only the circular indicator in the default variant.

The label accepts React content, so put a short description inside it rather than adding a separate description property. Do not nest buttons, links, or other inputs inside the label. Give the group an accessible name and use a grid inside the group for equal-width cards. Multi-choice fields still use checkboxes; a button that immediately runs an action is not a radio.

import { NxRadio, NxRadioGroup } from "@nexia/sdk/host";

<NxRadioGroup value={mode} onChange={setMode} aria-label="Entry mode">
  <div className="grid gap-3 md:grid-cols-2">
    <NxRadio variant="card" value="new" label={
      <>
        New entry
        <span className="mt-1 block font-normal">Enter the details for a new record.</span>
      </>
    } />
    <NxRadio variant="card" value="existing" label="Use existing entry" />
  </div>
</NxRadioGroup>12345678910111213

Apps adopting this option require both the updated SDK and a Core host that implements the card variant. Existing callers require no changes.

Favorites

Use the host-bound FavoriteButton when an App presents a durable target that Core has already declared favoriteable. Import the component and its target type from the package root:

import { FavoriteButton, type FavoriteTarget } from "@nexia/sdk";

const target: FavoriteTarget = {
    kind: "record",
    resourceKey: "workshop.note",
    resourceId: note.public_id,
};

<FavoriteButton target={target} size="xs" testId="note-favorite" />;123456789

FavoriteTarget is either a record identity (resourceKey and resourceId) or a server-declared page identity (key). The only button props are target, optional size ("xs", "sm", or "md"), and optional testId. The host owns state, requests, labels, and the server binding. An App must not send or store a title, href, permission, or arbitrary URL with this control; favoriting never grants access.

For a detail header, place the compact control in NxPageFrame's breadcrumbActions slot. For a list primary cell, pass server metadata as favoriteTarget, or pass the owner record identity as favoriteCandidate so the host can authorize it first. Set favoriteable={false} for a cell whose link identifies a related record rather than its row owner. These inputs do not create another App-owned favorites state or a custom paging contract.

Hierarchical choices

Use NxColumnBrowser when the hierarchy is part of the page. Use NxColumnPicker when choosing one leaf or several leaves is a blocking modal step. Both consume the same NxColumnNode[] and search the same leaf labels and keywords. The browser owns no overlay chrome; the picker composes the browser inside the host's centered NxModalDialog and commits the pending leaf through its Select action.

Import the portable node and props types from the package root and the host-bound renderers from /host:

import type { NxColumnNode } from "@nexia/sdk";
import { NxColumnBrowser, NxColumnPicker } from "@nexia/sdk/host";

const roots: NxColumnNode[] = [
    {
        value: "platform",
        label: t("apps.platform"),
        children: [{ value: "tenant.user", label: t("resources.users") }],
    },
];

<NxColumnBrowser
    roots={roots}
    value={resourceKey}
    onSelect={setResourceKey}
    ariaLabel={t("resources.choose")}
/>;

<NxColumnPicker
    open={pickerOpen}
    onClose={() => setPickerOpen(false)}
    title={t("resources.choose")}
    roots={roots}
    value={resourceKey}
    onSelect={setResourceKey}
/>;1234567891011121314151617181920212223242526

The App owns translated labels, node values, disabled state, the selected value, and any data loading or mutation triggered by selection. onSelect on the embedded browser fires when a leaf is chosen; branch rows only navigate the columns. onActivate can add a separate Enter or double-click action. Use renderPreview for the final column and onClearSelection when changing a branch should clear the current leaf. For multi-selection, set multiple, pass values, and receive the committed leaf list through onSelectMany(values, nodes). Use renderSelectionPreview for a review pane whose onRemove(value) callback removes a pending choice; single mode instead uses value, onSelect, and renderPreview.

Table and list

Column sorting and visibility

ResourceTable is also the canonical table for dashboard, dialog, and detail rows. Omit toolbar and footer for that chrome-free form. Add a stable tableId only when the logical view should persist per-table display or column overrides. The host combines it with the current tenant and user, so do not derive it from translated text:

Surface excerpt: use the generated Note list’s data, search state, refetch, translation function t, and formatDateTime from useDateTimeFormatter(). Add these columns after the loading/error guards.

import type { ResourceTableColumn } from "@nexia/sdk";
import { ResourceTable, ResourcePrimaryCell, NxSearchField } from "@nexia/sdk/host";
import { type NoteRecord, noteResourceRef } from "#app/resources/notes/note-resource-contract.ts";

const columns: ResourceTableColumn<NoteRecord>[] = [
    {
        key: "name",
        header: t("workshop.note.name.label"),
        size: "primary",
        cell: (row) => (
            <ResourcePrimaryCell
                resource={noteResourceRef(row)}
                label={row.name}
            />
        ),
    },
    {
        key: "created",
        sortKey: "created_at",
        header: t("workshop.note.created_at.label"),
        cell: (row) => formatDateTime(row.created_at),
    },
    {
        key: "updated_at",
        defaultVisible: false,
        header: t("workshop.note.updated_at.label"),
        cell: (row) => formatDateTime(row.updated_at),
    },
];

<ResourceTable
    tableId="workshop.notes"
    label={t("workshop.note.list.title")}
    columns={columns}
    rows={data.data}
    schema={data.meta.list_schema}
    toolbar={{ leading: <NxSearchField value={search} onChange={setSearch} /> }}
    footer
    onRetry={() => void refetch()}
    getKey={(row) => row.public_id}
    renderCard={(row, index) => (
        <article className="space-y-2">
            {columns[0].cell(row, index)}
            <p>{columns[1].cell(row, index)}</p>
        </article>
    )}
/>;1234567891011121314151617181920212223242526272829303132333435363738394041424344454647

Toolbar and footer chrome are opt-in. An enabled toolbar derives the standard Filter, scoped Refresh, and final More utilities; onRetry is reused as the owning-query refresh callback unless an explicit refresh config overrides it. The toolbar leading slot accepts any query control, including search and date pickers. showLabel renders the semantic caption visibly, while labelTooltip adds contextual help beside it. Per-table style and density overrides win over the optional UserContext.table_style and UserContext.table_density global defaults and can be reset to “use global”. Use summaryRow.cells for an aggregate aligned to declared column keys; its optional label supplies the accessible row label. A table-specific refresh callback overrides the onRetry fallback without changing error retry behavior.

The backend schema.sortable list is the positive sorting authority. Do not repeat sortable: true in a visual column. Use sortKey only when the visual key differs from the backend query key, and sortable: false only to suppress sorting that the schema would otherwise allow.

For a resource that has a complete compact representation, add optional renderCard to the preceding ResourceTable example. Enable toolbar (an empty object is sufficient) to expose the standard More menu, which then offers Table and Cards, with Table as the default. The host retains the same query, filters, paging, sorting, refresh, selection, and activation in either mode. View and Auto/2/3/4 card-column preferences are scoped by tableId, tenant, and user. Sorting remains the caller's existing URL or query state; card sort only invokes the same onSortChange contract. renderCard owns layout: reuse existing column cells or shared permission-filtered action renderers so table and card callbacks and authorization stay defined once. Do not opt into cards for tree or summaryRow lists; those semantics are table-only. Keep nested buttons and links inside the card body so they do not activate the card row.

Set defaultView="cards" alongside renderCard to start a list in card mode. A saved view preference takes priority; tables without renderCard and lists with summaryRow retain table rendering. The Resource table live example shows both starting views and reuses the same cells and actions.

Every non-structural column appears in More > Configure columns. A size: "primary" identity column is always visible; use hideable: false for another essential presentation-only column. defaultVisible: false starts a hideable column unchecked until the user chooses otherwise. The stored choice is scoped by tenant, user, and tableId; newly added columns adopt their declared default. Hiding the currently sorted visual column clears that sort so the table never remains ordered by an invisible column. These visibility flags are frontend-only and never belong in meta.list_schema.

Resource action semantics

When one operation appears in both a row menu and a detail or Inspector action rail, derive both presentations from one action set after effective permission filtering. Keep the visible resource actions in the same order: View, Edit, management actions, send or reset actions, lifecycle actions, then Delete. Host-owned chrome such as Open in tab and Close may surround that sequence, but must not reorder it. Frontend permission checks control visibility only; the backend still authorizes every operation.

Each ResourceRowActionsMenu item keeps behavior and presentation separate:

• id is a stable, non-localized operation identifier. The host uses known IDs such as show, view, edit, archive, retire, deactivate, and delete to select the canonical leading icon.
• label is the localized text visible to the operator.
• onSelect remains App-owned and performs the actual navigation or command. The host never infers behavior from the ID or label.
• destructive declares destructive treatment; disabled preserves an unavailable or pending command.

An App does not need an SDK iconKey or an icon-library dependency for a new operation. ResourceRowActionsMenu supplies a neutral leading icon when it does not recognize an ID. A recurring platform operation can later receive a canonical host mapping without changing the App contract. An explicitly passed icon remains authoritative.

destructive and dangerGhost describe different layers:

• NxDropdownMenuItem.destructive: true is the semantic fact that a menu item performs a destructive operation. ResourceRowActionsMenu uses it to apply destructive menu treatment.
• NxButton variant="dangerGhost" is the visual projection of that same fact when the operation is rendered as a secondary button in an Inspector or detail action rail.

Do not store a button variant in a shared domain action or infer destructive intent from a localized label. Store the operation's meaning once, then map it to destructive: true for menu items and dangerGhost for buttons. Ordinary View, Edit, and management actions remain neutral.

useResourceListParams is the one to reach for first: it keeps filters, sort, search, and page in the URL, so a list view is shareable and survives reload.

Resource projections

Board, Calendar, Resource Scheduler, and Schedule are host-bound React components. Import their pure projection and owner-action types from the package root, and import the renderers from /host:

import type {
    NxCalendarOccurrence,
    NxCalendarSelection,
    NxResourceSchedulerOccurrence,
    NxResourceSchedulerSelection,
    ResourceBoardProjection,
    ResourceScheduleProjection,
} from "@nexia/sdk";
import {
    NxCalendar,
    NxResourceScheduler,
    ResourceBoard,
    ResourceSchedule,
} from "@nexia/sdk/host";1234567891011121314

The host binds each facade lazily, so the browser loads the EventCalendar, drag-and-drop, or Gantt chunk only when that view renders.

NxCalendar can render filled bands or text-only occurrences through eventAppearance, keep the grid without a separate notice through showEmptyState: false, and use onOpenOccurrence for an occurrence that has no Resource link. Calendar and Scheduler onOpenOccurrence callbacks open the caller-owned detail flow and do not grant record access.

Creation and selection contracts:

These components do not fetch or mutate App records by themselves. The App loads an actor-authorized projection from its own API and implements the typed callback against an App-owned business action. Empty-range selection and native schedule add affordances only invoke the callbacks above; the shared renderers never create or persist domain records. Core supplies rendering and reversible optimistic feedback. See Resource projections for the complete ownership boundary.

useResourceProjectionChange({ tenantId, resource, onChanged, enabled }) subscribes to the exact app_key / resource_key / resource_id identity. The owning App emits the PII-free ResourceProjectionChanged event only after its projection commits; the callback is a refetch hint, not data or authorization.

Import and Export

Import components from /host and the following props types from the package root.

Core supplies common UI and file handling; the App defines schema, permissions, scope filtering, export rows, validation, business writes and retry behavior. See Resource Transfer to connect export sources and import recipes/pipelines.

Data migration

Register host-composed migration entries through dataMigrationRegistry:

import { dataMigrationRegistry } from "@nexia/sdk/host";

dataMigrationRegistry.registerProvider(provider);
dataMigrationRegistry.registerTarget(target);
dataMigrationRegistry.registerStage({
    ...stage,
    loader: () => import("./migration/OrdersStage"),
});12345678

An App can register providers, product targets, and lazy App-owned stages but cannot inspect or compose the host registry. A stage declares its provider and target, optional requiredPermissions with permissionMode, optional prerequisiteStageIds, and reports the public id of a server-owned migration run through onCompleted({ runPublicId }). The callback only asks the host to refetch GET /api/data-migrations/runs; browser state is never completion evidence. For a stage backed by NxDatasetImportWorkspace, the App backend declares DataMigrationStageIdentity on its ResourceImportPipelineDefinition. The host attaches that server-owned identity to the queued execution and records the actual terminal import result; the browser cannot choose or spoof it.

Migration stages use useDataMigrationBackgroundOperation() for cancellable polling of the standard accepted operation (ticket, status, optional status_url) and dataMigrationUploadAccept(formats) to derive the file-picker contract from server metadata. createDataMigrationSessionCheckpointStore() is a bounded, memory-only checkpoint for a stage that temporarily leaves to create a referenced Resource; it is not durable execution evidence. Resolve that create route by stable Resource Key through resourceCreateDestinationRegistry instead of importing or hard-coding another App's route. Identical registry declarations may be repeated during boot; a conflicting duplicate fails immediately.

Data access

Context types are published for typing your own code: TenantContext, UserContext, LegalEntityContext, WorkspaceContext, PermissionsResponse. UserInvitationPayload accepts an email or Person Party public id plus optional Legal Entity and Operating Unit role assignments. Core remains responsible for validating and authorizing the invitation request.

usePermissionsQuery(tenantId, legalEntityPublicId, operatingUnitPublicId?, enabled?) falls back to the current context when the Legal Entity argument is nullish, includes the optional Operating Unit in both the cache key and request, and runs only when enabled is true and a tenant id exists. It is still a UI affordance snapshot; the backend authorizes every protected request again.

useApprovalRoutePoliciesQuery(tenantId, legalEntityPublicId, enabled?) reads the active-context policy catalog only when it is enabled and both identifiers are present. ApprovalRoutePoliciesQueryResult returns items with key, version, name, status, scope, and legal_entity_public_id. An App may show that metadata in a reference picker and store the stable policy key, but the backend still validates the selected policy when the App command runs.

useUploadFile(): UploadFileClient starts a host-issued upload intent without exposing storage or transport policy to the App. Call uploadFile() with UploadFileInput: a required purpose and browser File, plus optional checksum and onProgress({ loaded, total, percent }). It returns an UploadTask with a result promise, cancel(), and retry().

The promise resolves to UploadIntentResponse, whose upload is the public UploadIntent projection: id, purpose, state, optional transport (direct or proxy), nullable expires_at, and optional opaque media. Core chooses direct object-storage transfer or proxy transfer; App code never selects the transport and must not depend on host-only upload URLs or storage fields. The related public types are UploadFileInput, UploadProgress, UploadIntent, UploadIntentResponse, UploadTask, and UploadFileClient.

can decides what to render, never what is allowed. Every request it guards is authorized again in the backend. A frontend permission check is a UX affordance.

Inspector and work tabs

Use useActiveWorkTabId() to key session-only drafts that must survive a route-tree remount inside one Work Tab. A surface outside a Work Tab receives null. Do not use the ID as a tenant, actor, authorization, or durable browser-storage key.

ResourceInspectorStackHost owns View and Close. An adapter adds Edit, Delete, or activate/deactivate only when the serialized backend action decision permits that operation, then supplies the same route or command used by the row menu via InspectorAction. Delete remains destructive and lifecycle labels describe the current transition; the host supplies canonical icons and header placement. The stable action id follows the same convention as ResourceRowActionsMenu. Known IDs receive canonical icons; an App may use any new resource-specific ID without changing the SDK or host, and the host renders the neutral fallback unless the App supplies an explicit icon.

Define one resource-local factory that returns ResourceActionDescriptor[], then pass its result to the row menu and InspectorResourceActions. The factory owns membership, order, labels, permissions, destructive state, and pending state; each caller supplies the callbacks appropriate to its context. The Inspector projection omits view and show because the host already owns the Inspector View action. This is data synchronization, not a closed action enum: a one-off ID remains valid without an SDK change. Use singular InspectorAction only when an action genuinely has no matching row presentation.

Wrap the Primary Section and Inspector host in one ResourceInspectorStackProvider. Keep ResourceInspectorStackHost mounted even when the provider's root is null: a ResourceLink in the Primary Section can then create the first stack entry. In a clickable table row, the row background and its own identity select the row Resource, while a different referenced value uses ResourceLink without an onActivate override so it pushes that referenced Resource. More menus, links, buttons, and form controls do not also activate the row. When resource.route is an internal route, right-clicking the ResourceLink also offers Open in new work tab.

An Inspector adapter exposed as a ResourceLink target must support an id-only ResourceRef. Treat embedded resource.data as an immediate optimization, then fetch the Resource detail by resource.id when that data is absent. This keeps cross-Resource drill-in correct instead of rendering an empty Inspector.

Dashboard renderer hooks

Dashboard renderers must follow the board's shared lifecycle instead of creating their own viewport or transport policy:

Spread the freshness result into useQuery. A spec's queryRef.refresh is a requested cadence, not permission to poll faster than the host policy.

Errors, messages, and formatting

Use useDateTimeFormatter rather than formatting dates yourself — it applies the tenant's business timezone.

Set href on NxStatCard or an NxOverviewBand card when the summary opens a canonical route. Omit it for a static summary. The former onOpen card callback is retired so route cards keep native link and Shell work-tab behavior.

For a reversible mutation, add undo to useFeedbackAction with a resolved label, the inverse operation, and success/error feedback. The inverse receives the original successful result and argument tuple and runs at most once. A custom success Toast action keeps the single action slot. Do not present a client-only visual rollback as Undo.

Approval, Signature, and agent

ApprovalBusinessFormSlotPropsV2 is the prop contract named by slotApiVersion: 2 on a SlotWidgetDescriptor. Consume only these props. An ApprovalResourceSummaryField may carry the semantic role subtitle, meta, or status. Treat it as a compact-presentation hint; field order and host layout remain host-owned.

Testing

configureNexiaAppFrontendHost and NexiaAppFrontendHostBindings are the runtime equivalents, supplied by the host.

App Packages consume these bindings; the host configures them. Import test helpers from @nexia/sdk/testing and use the configured harness in Test an App.

Errors

Use in your App

Register the entry through autoRegisterPackageSurfaces, then open its route in the host. Use Build an App screen for the screen workflow and Test an App for the frontend test harness.

Related

• SDK contracts — the PHP side of the same boundary
• Build an App screen — writing a surface with these primitives
• Add a Slot Widget — declaring the descriptor a composer widget needs
• Fix boundary violations — fixing a rejected import