YouBothAgent▾
You — Business rules and flows you own. Read these yourself.
Both — Know the idea; your agent follows the details.
Agent — Conventions and references your agent follows. Look up as needed.
UI Composition
Picture an order list screen. Besides the list itself, it needs six more things:
- a skeleton while it loads
- a placeholder when it is empty
- a page control at the bottom
- a modal for a new order
- a second modal for editing one
- a confirmation before anything is deleted
That is six states around one array, and none of them is your product. akanjs/ui ships all six, already wired to the generated store. You write the row and the detail view; the shells around them handle loading, empty, paging, refresh and the CRUD modals.
This page is the inventory of those shells and the rules for combining them. Where the client boundary falls is the subject of UI Architecture.
Words used on this page
TermDescription
shell
A ready-made akanjs/ui component that draws loading, empty, paging or modal states around yours.
slice
A module's named list query, such as icecreamOrderInPublic. A shell takes one as slice.
handle
What fetch.init, fetch.view and fetch.edit return: await it, or destructure one promise per field.
Suspense boundary
A spot that shows a fallback first and streams its content in when the data lands.
What akanjs/ui gives you
ExportDescription
Load.UnitsLoad.ViewLoad.Edit
Data shells: seed the store from a fetch handle and render loading, empty and list states.
Load.Stream
Awaits one promise behind its own Suspense boundary; a resolved value renders inline.
Model.NewModel.EditModel.SureToRemove
Create, edit and remove modals wired to the generated store actions.
Field
The control for every model field type. Never a bare input for a model field.
TabLayoutLinkImageEmpty
Composition primitives. Tab keeps panel bodies on the server; Link adds the locale prefix.
cn
The only class merge, from akanjs/client. Pass the caller's className last.
Where your own components go
What you write splits the same way, by whether it belongs to one model:
lib/<model>/
Anything bound to one model. The module owns its own row, detail view, form and actions.
ui/
Anything reusable across models and bound to none of them.
A component that seems to need both is really two components: one in each place.
Reach third-party packages through a lib. A third-party package may not be imported from
page/**, from a barrel, or from any module component file; re-export it through a lib first. That is why libs/shared/ui/Field.tsx extends the framework Field with Rich, Img and Map instead of each app importing an editor directly.The Shape Of A Model Screen
A model almost always produces the same four screens. Users scan a list, create a record, open one, and come back to edit it. Each arrow below is a shell that already exists, so the four screens are four small files rather than four workflows.
Index, new, view, edit
Start
IndexLoad.Units
NewModel.New
ViewLoad.View
EditLoad.Edit
End
new
submit
pick a Unit
edit
submit
back
Model.SureToRemove
Each screen has one job, and one shell that does the heavy lifting:
Index — find one
Load.UnitsFor discovery: search, scan, page through and choose a record.
New — create one
Model.NewControlled input through one Template and a submit action.
View — read one
Load.ViewPresents one record clearly, then offers the follow-up actions.
Edit — change one
Load.EditThe same Template as New, with the record's current values in it.
The same stack under every screen
Underneath all four screens, the same layers run in the same order, from the route down to the database:
From the route to the database
page()route entry
Unit · Viewserver components
Zone · Template · Utilclient components
Two roads to fetch, one rule. The route calls
fetch directly; a client component reaches it only through a store action. That one rule keeps the two paths from drifting apart.Day to day, four generated helpers are the whole surface you touch:
HelperDescription
fetch
One call per endpoint, plus per-slice init, view and edit handles. Called server-side.
st
Read with st.use.*, write with st.do.*. The CRUD actions are generated.
<Model>.*
A module's Unit, View, Zone, Template and Util. Name by role: IcecreamOrder.Unit.Card.
usePage
l, l.trans and the page context. Works in a server component.
The Load Shells
Never hand-roll a loading, empty or list state. A Load shell does three things for you:
- It takes the handle the route fetched, so the data is already on its way before the page is sent.
- It seeds the client store from that handle, so the generated pagination, query, sort and refresh actions keep working after hydration.
- It renders the loading, empty and list states around your row component.
ShellDescription
Load.Units
init from fetch.init<Model><Suffix>. renderItem draws a row; renderList takes the whole list.
Load.View
view from fetch.view<Model>. renderView is required; empty is the placeholder.
Load.Edit
edit from fetch.edit<Model>, or a partial. slice is required; type picks modal or form.
Load.Stream
of takes a promise or a value; children renders it. Takes a slice's x<Model>List<Suffix>.
Load.PaginationLoad.Page
The paging control alone, and the shared SSR/CSR page loader.
Don't wait for the slowest query
The route destructures the handle instead of awaiting it. The init field goes to a Zone, and any leftover list promise goes to a Load.Stream:
apps/koyo/page/(public)/icecreamOrder/_index.tsx
- Load.Stream shows the skeleton until the list lands, then renders the total from it.
- The Zone receives init and renders the rows behind a boundary of its own.
- Each renders as its own data lands, so the page never waits for the slowest query.
The CRUD Modals
Creating, editing and removing a record are three workflows every model needs and no model should implement. Each shell takes the slice it operates on, opens the module's own Template, and calls the generated store action on submit.
apps/koyo/lib/icecreamOrder/IcecreamOrder.Util.tsx
A Util export is named for the endpoint verb minus the model noun, so this file exports New and Remove rather than NewIcecreamOrder. Three props are worth knowing before you reach for one of these shells:
Forms Are Store-Driven
A Template, the module's form component, holds no state of its own. Every control reads one key of <model>Form from the store and writes it back through the generated setter. Two things follow from that:
- A Template contains zero useState.
- A saved draft can be restored into it, because the whole form lives in one place.
apps/koyo/lib/icecreamOrder/IcecreamOrder.Template.tsx
One Vocabulary, Many Screens
Every string a user reads goes through the module's dictionary. Field labels, enum values, error messages and the model's own name are declared once as [en, ko] pairs, and components read them by key.
That way the vocabulary lives next to the model, not scattered through whichever components happen to display it.
apps/koyo/lib/icecreamOrder/icecreamOrder.dictionary.ts
A component then reads text in one of three ways:
CallDescription
l("icecreamOrder.size")
A field label, read from the model's dictionary.