ui

Module nustd.ui.

nustd.ui -- component fabric.

Layout under src/nustd/ui/:

lens/ -- the Shape lens: LensRef, the walk that turns a Shape and a cursor into columns, and browse to assemble the two.
table/ -- sync: a TableRef kept equal to a kv store, live across tabs, and Row, the stored row it reads.
core/ -- host-independent UI fabric: Ref, Section / SectionRef, abstract Session / Subscription, wire Frame + interactions (Send / Write / Append / Remove / Changed). Reusable by any host.
refs/ -- layer 1, the widget kit as Refs: containers/ (Column, Row, Card, ...: open-ended children) and leaves/ (Text, Button, Table, charts, ...: drawn from props, no children). Any UI can be built from these alone. Depends only on core.
shapes/ -- layer 2, a declarative DSL over the container Refs: one Section per container (Row, Card, ...) that points _ref_cls at its Ref and adds named child slots.
nudle/ -- Page-based host: Index / Page / PageRef, the Boot term, and the serve preset that assembles a whole tree.

The uvicorn lifecycle, the book of live connections and the per-connection fold live in nustd.ws_server, which knows nothing about ui.

The browser half is not in this package. It lives in the repo's npm workspace at pkgs/ts (ui-core, ui-kit, and the nudle Vite app), and its compiled bundle ships as the separate nudle wheel.

The public entry is nustd.ui itself: the core fabric, the widget kit, the Shapes and the nudle host names are re-exported flat, so one import nustd.ui reaches everything a UI program spells. The lens is the exception and stays whole behind nustd.ui.lens, LensRef included: it is a subsystem rather than a widget, and a surface split between two names is worse than one more dot.

The host half loads on first use. Building Refs and serving them are two different jobs and only one of them needs a web server: nudle reaches nustd.ws_server, which reaches uvicorn and starlette, and that was most of what import nustd.ui cost. Plenty of processes only ever build Refs. The case that made this worth doing is a worker drawing on a connection it holds a proxy to: it pays the import on every launch and serves nothing, ever. So nudle, serve and the four page names come through __getattr__ below, and naming any of them loads the host with its server, which is what somebody naming them is asking for.

Modules

Module	What
`nustd.ui.lens`	nustd.ui.lens -- any Nu Shape, browsable as cascading columns.
`nustd.ui.table`	nustd.ui.table -- a table whose rows are what the store holds.

core.interactions

Module nustd.ui.core.interactions.

Wire interactions -- ops that flow over a Session on a Ref.

Name	Sort	Call	Meaning
Append	`scalar_command`	`Append()`	Send an `append` frame on a Ref -- push onto a sequence.
Changed	`scalar_query`	`Changed(ref, event=None)`	Subscribe to client-side change notifications on a Ref.
Remove	`scalar_command`	`Remove()`	Send a `remove` frame on a Ref -- drop its node and its whole subtree.
Send	`scalar_command`	`Send()`	Send a frame on a Ref: its chain, and a payload built from the arguments.
Write	`scalar_command`	`Write()`	Send a `write` frame on a Ref -- replace the value. An EMPTY value raises.

Name	Sort	Call	Meaning
Boot	`scalar_command`	`Boot(shape_cls)`	Seed one browser's tree: clear it, name it, then one `init` per slot.
PageRef	`ref`	`PageRef(address, section_cls=None, parent_ref=None, owner_shape=None, props=None)`	Substrate Ref backing a Page slot on an Index.
Index			Browser entrypoint. One per app.
Page			Section an Index mounts at a route.

Name	Sort	Call	Meaning
InsertRow	`scalar_command`	`InsertRow()`	Insert `row` before the row at `index`, clamped to the rows shown.
RemoveRows	`scalar_command`	`RemoveRows()`	Drop the rows with these `keys`; keys not shown are skipped.
SetOrder	`scalar_command`	`SetOrder()`	Show the rows named by `keys` first, in that order; the rest keep theirs after.
SetRow	`scalar_command`	`SetRow()`	Replace the row keyed `key` with `row`, or add it last when none is shown.
TableRef	`ref`	`TableRef(address, parent_ref=None, owner_shape=None, props=None)`	Rows and columns. The server owns the rows; the browser reports what you do.

Name	Sort	Call	Meaning
AccordionRef	`ref`	`AccordionRef(address, item=None, section_cls=None, parent_ref=None, owner_shape=None, props=None)`	Stack of collapsible sections, each body the child at the section's id.
BoxRef	`ref`	`BoxRef(address, item=None, section_cls=None, parent_ref=None, owner_shape=None, props=None)`	Styled card-like box with an optional title. Pin chrome on slot().
CardRef	`ref`	`CardRef(address, item=None, section_cls=None, parent_ref=None, owner_shape=None, props=None)`	Card-styled container: title + subtitle + body children + footer.
FieldRef	`ref`	`FieldRef(address, section_cls=None, parent_ref=None, owner_shape=None, props=None)`	Label + one child input + help / error text.
FieldsetRef	`ref`	`FieldsetRef(address, item=None, section_cls=None, parent_ref=None, owner_shape=None, props=None)`	Grouped fields with a legend. Display-only, server-owned.
FormRef	`ref`	`FormRef(address, item=None, section_cls=None, parent_ref=None, owner_shape=None, props=None)`	Semantic form wrapper. Pin chrome on slot(); submit lives on a child ButtonRef.
ModalRef	`ref`	`ModalRef(address, item=None, section_cls=None, parent_ref=None, owner_shape=None, props=None)`	Dialog overlay. Open vs closed is the thing it carries, so it has a `set()`.
TabsRef	`ref`	`TabsRef(address, item=None, section_cls=None, parent_ref=None, owner_shape=None, props=None)`	Tab strip plus active body. A tab's body is the child at the tab's id.

ui

On this page