@playstack/admin-ui
Host-composed account and audience operator sections with scoped, localized controls.
Reference: @playstack/admin-ui@0.1.0-beta.5 · TypeScript
Pro. Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See package access.
Available exports include AdminShell, MembersSection, standalone MembersTable,
AudiencesSection, AudienceSubscribersTable, AudienceSubscriberDetail,
AudienceInvitationsSection, optional AudienceSubscriptionRemoval,
AudienceExport, AudienceSubscriberErasure and
WebhookIntegrationsSection. These are
host-composed sections, not a complete admin app or global staff authorization service.
AdminShell accepts explicit loading, denied, error or ready access, trusted navigation entries, a host link renderer and slots for branding, notices and account/user controls. Non-ready states do not mount private content. Server authorization still runs before returning private data.
MembersSection accepts token-free member views, including nullable email, allowed-role hints and removal hints. A ready response must match its account/authority scope key. Role/removal callbacks serialize, receive cancellation signals and ignore stale completion; the server must revalidate current authority. Member removal includes confirmation and safe failure handling.
Install
After confirming preview access, install the package at your application's shared Playstack version:
npm install --save-exact @playstack/admin-ui@0.1.0-beta.5Check the peer requirements below before choosing a runtime or provider.
Prebuilt and custom Next routes
Use an application-owned client shell in a Next layout. Put MembersSection on a members route and ordinary App UI/product components on custom routes. Next Link, active-route matching, data clients and the composition root remain in that application; the package does not install a second router or discover plugins.
The reference composition combines a members route, a read-only members view, custom publishing routes and localized routes under one shell, on Chakra 3 with React 18 or 19 and server-side rendering.
Global staff access, impersonation, audit browsing, billing panels and other prebuilt sections are not shipped yet; the host Next application owns those routes and the services behind them.
Audience operator controls
Compose list navigation, paginated status/tag/segment filters and safe consent/ provenance detail from host-controlled read projections. Survey data stays in host extension slots. Scope/query/generation identity prevents late responses from replacing the current view; loading, denied and error access never mounts private subtrees. The host owns Pages Router/App Router integration, request-local SSR clients and independently authorized backend reads/actions.
AudienceInvitationsSection displays confirmed-subscriber batch preview, explicit
commit, status and revoke/reissue controls. Callbacks receive bounded immutable
selection/context and cancellation; returned projections must match the exact
scope and request. A fingerprint/confirmation is not authority: native invitation
mutation must recheck current recipient, consent and admission policy. No proof,
email, bearer credential, HTTP route or new audience service is created in the UI.
AudienceSubscriptionRemoval is a separate optional soft-removal control, with
Cancel-focused confirmation, safe errors and authoritative reload. Abort means
stop waiting, not rollback; remote unsubscribe may still await provider convergence.
The host must enable native transaction-bound operator removal and trusted server
principal/source separately. These controls do not supply export download
infrastructure or automatically activate erasure/settings. Localized Chakra v3
controls retain keyboard/focus and stale-response checks; live app composition
still requires its own authorization/browser qualification.
Explicit export and erasure controls
AudienceExport confirms a private export admission using exact scope, list,
query, selected fields and current server permission. The host supplies the
authorized native AudienceExports.page route and private transfer. Accepted
means admitted, not downloaded; pagination, total-work budgets, file retention
and CSV conversion remain host-owned. No contact rows or download URLs are
retained in the control.
AudienceSubscriberErasure reviews the complete all-list manifest and an
accepted server policy reference. It additionally requires explicit qualified
linked-cleanup, suppression, provider and re-enrollment hints before confirmation.
The server reauthorizes current all-list authority and maps its own trusted policy
to native lifecycle erasure. Matching accepted action and authoritative
erased inspection are required to settle a new action; neither implies complete
provider/backup erasure. Local cancellation cannot undo a commit or recall data.
Both are separately opt-in, localized, Cancel-focused controls. Scope/access/ generation changes cancel local waiting and ignore stale responses. No browser projection grants authority, selects cleanup policy or replaces the package's server lifecycle contracts.
Package controls versus the Playstack admin app
Playstack's own admin app currently composes optional read-only early-access
and newsletter views through API-owned ADMIN_EARLY_ACCESS_LIST_KEY and
ADMIN_NEWSLETTER_LIST_KEY. ADMIN_PRODUCT_UPDATES_CONSENT_ENABLED enables a
separate read-only view of existing product-update preferences; it does not
convert them into audience subscriptions. All are disabled by default and retain
independent operator/session authorization.
Those flags do not create lists, accept public subscriptions, send invitations, export/remove/erase contacts or enable webhook settings. Deploy the reviewed schema and create the exact native lists through a qualified host composition before configuring keys. Consuming applications choose their own controls and guards; the package does not install these environment variables or a hosted administration service.
Masked webhook integration controls
WebhookIntegrationsSection composes current masked Slack/Discord settings with
explicit create/rotate/routing/enable/disable/revoke/test callbacks. The host
supplies approved event options and per-action permission hints; server-side
authorization and revision checks remain mandatory. Ready responses bind exact
scope, list, query and generation; malformed/substituted projections fail closed.
Destination URLs are write-only form input, cleared before callback and on cancel, revision/scope/access changes and unmount. Never include URLs/ciphertext in masked rows, read responses or diagnostics. Clearing cannot protect against browser compromise. Mutations require Cancel-focused confirmation, exact acknowledgment and authoritative reload; abort means stop waiting, not rollback. Test requests contain no destination, payload or profile override and mean admission only, not provider delivery. Compose the explicit native settings/Nest/outbox contracts and qualify the deployed operator/provider flow separately.
Shared localization
Shell states, navigation labels, member controls and portal confirmation/error copy use the shared @playstack/i18n-react provider. Compose adminUICatalog from @playstack/admin-ui/messages with appUICatalog from @playstack/app-ui/messages; both namespaces are required.
./locales/en.json and admin-ui.messages.en provide English source artifacts. Existing message overrides retain precedence and English works without a provider. Account/member names, roles and custom navigation remain host-owned. See UI localization; translations never change authorization or mutation ordering.
API entry points and requirements
Reference snapshot: @playstack/admin-ui@0.1.0-beta.5. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.
| Public entry point | Declaration file |
|---|---|
@playstack/admin-ui | ./dist/index.d.ts |
@playstack/admin-ui/package.json | No TypeScript declaration (asset or metadata export). |
@playstack/admin-ui/messages | ./dist/messages.d.ts |
@playstack/admin-ui/locales/en.json | No TypeScript declaration (asset or metadata export). |
@playstack/admin-ui/playstack.artifacts.json | No TypeScript declaration (asset or metadata export). |
@playstack/admin-ui/playstack.integration.json | No TypeScript declaration (asset or metadata export). |
Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.
Peer dependencies
Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.
| Peer | Compatible range | When needed |
|---|---|---|
@chakra-ui/react | ^3.0.0 | Required by the package. |
@emotion/react | ^11.0.0 | Required by the package. |
@playstack/chakra | 0.1.0-beta.5 | Required by the package. |
react | ^18.2.0 || ^19.0.0 | Required by the package. |
react-dom | ^18.2.0 || ^19.0.0 | Required by the package. |
@playstack/app-ui | 0.1.0-beta.5 | Required by the package. |
@playstack/i18n-react | 0.1.0-beta.5 | Required by the package. |
For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.