Toolbar and footer

The chrome the host draws around a surface: the toolbar an environment declares as data, the footer it renders as JSX, and the view channel between them.

@internote/canvas-sdk14 exports

#Functions

createViewChannel
packages/canvas-sdk/src/view/index.ts:100
A view channel for one environment type.
<V, S = unknown>(options: ViewChannelOptions<V, S>): ViewChannel<V>
validateToolbarItems
packages/canvas-sdk/src/toolbar/types.ts:139
Validate an environment's toolbar contribution.
(items: ToolbarItem[], environmentName: string): ToolbarItem[]
viewToolbarItems
packages/canvas-sdk/src/view/index.ts:187
The one item an explorable environment puts in its toolbar: a way back to the frame the author wrote.
(name: string, where: ViewHolder, channel: ViewChannel<unknown>): ToolbarItem[]

All three environments that grant exploration built the same list themselves and said so in a comment — "the graph's trio, for the same reason", "the graph's and the geo's trio, for the same reason". The ids, the icon, the wording and the rule that reset is dead until there is something to reset are the same answer every time, and a reader moving between two environments should not meet two vocabularies for one gesture.

It was a trio until the bar became the SCENE's and carried every environment's items at once: zoom in and zoom out are what the wheel and the pinch already do, so three environments' worth of them was six buttons duplicating a gesture in a bar that had to fit the reading column. The reset stays because it is the one thing no gesture does.

name prefixes the item ids, which must be unique within an environment's contribution.

#Interfaces

EnvironmentFooter
packages/canvas-sdk/src/footer/index.ts:32
An environment's pair of bands, as EnvironmentDefinition.footer declares them.
BarRequired
Always visible: what the environment reports.
CanvasFooterComponent
Panel
Behind the chevron: what the reader operates.
CanvasFooterComponent
ResolvedToolbar
packages/canvas-sdk/src/toolbar/types.ts:125
An environment's resolved toolbar: system tier + the environment tier, in render order.
itemsRequired
The environment's own items, validated.
ToolbarItem[]
systemRequired
The host-owned tier: presentation and step position.
ToolbarSystemState
ToolbarButtonItem
packages/canvas-sdk/src/toolbar/types.ts:22
A pressable button in an environment's toolbar, drawn by the host.
align
Where the host draws the button: 'leading' sits with the environment's other items; 'trailing' moves it to the bar's far side, ahead of the system tier — the slot for an environment's primary action.
leadingtrailing
Default'leading'
busy
Work is in flight behind this button: the host draws animated working feedback (a spinner in place of the icon). Declarative like everything else — the type says busy, the host decides what busy looks like.
boolean
disabled
Whether the button is shown but cannot be pressed.
boolean
icon
Icon name, resolved by the host's icon set.
string
idRequired
Unique within the environment's contribution; duplicates throw.
string
label
Accessible name and tooltip — a disabled button's label may carry the reason.
string
onPressRequired
Called when the reader presses the button.
() => void
text
Visible caption drawn inside the button, beside the icon. Distinct from label so the caption stays short ("Run") while the tooltip explains ("Sign in to run code").
string
typeRequired
Marks the item as a button.
'button'
variant
The button's weight, mirroring the app Button's registers: 'normal' is transparent-until-hovered like every toolbar control; 'subtle' is the tinted register — for the ONE action an environment leads with (a runnable environment's Run).
normalsubtle
Default'normal'
ToolbarSeparatorItem
packages/canvas-sdk/src/toolbar/types.ts:85
A divider between groups of toolbar items.
id
A key for the host to render the separator by; not checked for uniqueness.
string
typeRequired
Marks the item as a separator.
'separator'
ToolbarSystemState
packages/canvas-sdk/src/toolbar/types.ts:111
The host-owned system tier.
exitPresent
Leaves presentation.
() => void
isPresentingRequired
Presentation mode (fullscreen is a drive mode, not a fork).
boolean
requestPresent
Enters presentation.
() => void
stepRequired
Step position, shown by the host next to the type's items.
number
stepCountRequired
How many steps the scene has.
number
ToolbarToggleItem
packages/canvas-sdk/src/toolbar/types.ts:67
An on/off button in an environment's toolbar, drawn pressed while active.
activeRequired
Whether the toggle is on.
boolean
disabled
Whether the toggle is shown but cannot be pressed.
boolean
icon
Icon name, resolved by the host's icon set.
string
idRequired
Unique within the environment's contribution; duplicates throw.
string
label
Accessible name and tooltip.
string
onToggleRequired
Called when the reader presses the toggle; the environment flips its own state.
() => void
typeRequired
Marks the item as a toggle.
'toggle'
ViewChannel
packages/canvas-sdk/src/view/index.ts:77
One environment type's view: what the surface drew, what the reader explored to, and the glide between.
currentRequired
The reader's window if they have one, else the one last drawn.
V | null
glideRequired
Ease from wherever the view is now to to. release clears the stored view on arrival, handing the frame back to the author.
void
hasExploredRequired
Whether the reader has moved the view off the authored one.
boolean
recordRequired
The window this render drew. explored false also records it as the authored frame — the target reset glides back to.
void
resetRequired
Back to the authored (or automatic) frame, arriving under the author's control.
void
ViewChannelOptions
packages/canvas-sdk/src/view/index.ts:61
What an environment supplies to createViewChannel: its view's shape, where it lives, and how two blend.
glideMs
Defaults to 240ms.
number
lerpRequired
Two views, t of the way between. Called every frame of a glide, so it is also where an environment says what "between" means for its own geometry — the short way round a sphere, a zoom that moves in levels.
(from: V, to: V, t: number) => V
readRequired
Where the reader's own view sits in this environment's session state.
(session: S | undefined) => V | undefined
writeRequired
That state with the view set, or cleared when view is undefined.
(session: S | undefined, view: V | undefined) => S
ViewHolder
packages/canvas-sdk/src/view/index.ts:50
The slice of an environment's context a view channel needs.
identityRequired
Which internote, scene and environment this view belongs to.
EnvironmentIdentity
storageRequired
Where the reader's own view is kept — the session tier.
CanvasStorage

#Types

CanvasFooterComponent
packages/canvas-sdk/src/footer/index.ts:29
One band of an environment's footer: the home of bespoke machinery, such as the graph's element list or the code environment's console.
ComponentType<EnvironmentContext>

Unlike the toolbar it may take JSX, and it receives the EnvironmentContext as its props. It renders inside a host-provided frame, so it renders CONTENT and never chrome: no bar, no chevron, no panel wrapper, no rule between the bands. The host owns all of that, and owns collapse through FooterAccess.

ToolbarItem
packages/canvas-sdk/src/toolbar/types.ts:105
Anything an environment can put in its toolbar: a button, a toggle, a separator or a label.
ToolbarButtonItem | ToolbarToggleItem | ToolbarSeparatorItem | ToolbarLabelItem

Last updated