Skip to content
AntFabric Corev1.0.0local

Screens

A plugin brings screens for each platform it targets. The apps load them through their generated registries; the shell gives them the navigation (rail, sidebar or top bar), layout, session and theme.

Platform Folder Defined with Imports
User app web/ definePluginSurface @antfabric/sdk-web, @antfabric/ui-kit
Desktop app desktop/ (optional; else web/) definePluginSurface The same
Phone mobile/ defineMobileSurface @antfabric/sdk-web/client, @antfabric/ui-kit/native
App Admin admin/ definePluginSurface The same as web
// web/index.tsx — mounted under /sales
export default definePluginSurface({
routes: [
{ path: '', title: 'Sales', layout: 'workspace', component: SalesApp },
{
path: 'leads/:leadId',
title: 'Lead',
layout: 'workspace',
component: LeadPage,
},
],
badges: [{ nav: 'sales.home', useCount: useDueFollowUps }], // a count on the nav entry
});
// mobile/index.tsx — mounted under /p/sales
export default defineMobileSurface({
routes: [
{ path: '', title: 'Sales', component: HomeScreen },
{ path: 'leads/:leadId', title: 'Lead', component: LeadScreen },
],
});

layout: 'workspace' gives the plugin the whole area next to the navigation (Chat, Sales). Without it the page sits in the standard content frame. On the phone, layout: 'fill' does the same.

Declare each screen other code may open in plugin.yaml:

navigation:
routes:
- id: lead
path: leads/:leadId
targets: [web, desktop, mobile]
parameters:
leadId: { type: string, required: true, pattern: '[0-9a-f-]{36}' }
permissions: ['sales:read']

Open it by id — on web useNavigation().open(…), on the phone useMobileNavigation().open(…):

navigation.open({ pluginId: 'af.sales', routeId: 'lead', params: { leadId } });

Notifications use the same id (destination: { routeId: lead }), and other plugins open your screens the same way. Never build another plugin’s URL by hand.

On the phone, replace(…) opens a screen in place of the current one (Back then skips a finished form), and useScreenFocus(() => void reload()) runs each time your screen comes into view again, for example after the screen pushed over it closed:

const navigation = useMobileNavigation();
useScreenFocus(() => void keys.reload());
// after "I saved it":
navigation.replace({ pluginId: 'af.ai-gateway', routeId: 'keys' });

openExternal(url) from @antfabric/sdk-web (phone: @antfabric/sdk-web/client) opens a web page, an email or a phone number outside the app: a new tab in a browser, the system browser from the desktop app (it has no window.open), the phone’s browser or mail app. Only http(s), mailto and tel links are accepted. Plain <a target="_blank"> links work on the desktop app too.

// shared/api.ts — used by web and phone screens
import { api, pluginApiPath } from '@antfabric/sdk-web/client';
const base = pluginApiPath('af.sales', '/leads');
export const sales = {
lead: (id: string) => api.get<Lead>(`${base}/${id}`),
move: (id: string, input: MoveLead) =>
api.put<Lead>(`${base}/${id}/stage`, input),
};

api attaches the token, refreshes it, retries once and turns error envelopes into ApiError with the server’s message. Types come from your contracts package. Every call takes { signal, timeoutMs } as its last argument; GETs are tried again when the server is briefly away.

In a screen, prefer the query hooks: one cache for every screen, cancelled when you leave, refreshed by your live events.

const leads = usePluginQuery<Lead[]>({
key: ['leads'],
path: '/leads', // under your plugin's API
invalidateOn: ['af.sales.lead.moved.v1'],
});
const move = usePluginMutation<Lead, MoveLead & { id: string }>({
method: 'PUT',
path: (v) => `/leads/${v.id}/stage`,
invalidates: [['leads']],
});

usePluginList pages a list; usePermission('sales:manage') and <Can> hide what someone may not do (refreshed live when their roles change); useT() translates with your locales/<lang>.json. Screens load only when first opened: keep rail badges in a small badges entry (surfaces.web.badges). Another plugin’s component inside your screen is a slot (<Slot>). All of it: docs/frontend/screen-foundation.md.

usePeople(ids) returns names and photos (batched, cached); usePresence(ids) online, away or offline. Never fetch users yourself.

Use its components (Button, TextField, Dialog, Card, Tabs, Avatar, Tag, Toast, EmptyState, …) and tokens (t.space.md, t.fg.muted, t.surface.card) so screens follow the instance’s branding and dark mode. If you need something it lacks, add it to the UI kit rather than building it in your plugin.

Anything that is not UI goes in shared/: the API client, formatting, parsing, hooks for live updates and settings. Web and phone screens import it; it imports only sdk-web/client and your contracts.