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 |
A surface
Section titled “A surface”// web/index.tsx — mounted under /salesexport 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/salesexport 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.
Navigation by route id
Section titled “Navigation by route id”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' });Links outside the app
Section titled “Links outside the app”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.
Calling your API
Section titled “Calling your API”// shared/api.ts — used by web and phone screensimport { 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.
People and presence
Section titled “People and presence”usePeople(ids) returns names and photos (batched, cached); usePresence(ids) online, away or
offline. Never fetch users yourself.
The UI kit
Section titled “The UI kit”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.
Shared logic
Section titled “Shared logic”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.