GameCult/Thing
Watch
9
0
Fork
You've already forked Thing
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Define CultUI indentation and control anatomy

Browse source
This commit is contained in:
Meta Vens 2026-06-05 16:46:45 +01:00
commit 1846a1c2be
3 changed files with 119 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

126
docs/cultui-style-system.md
View file

@ -23,6 +23,8 @@ designer. The stylesheet is not the truth.
deeply as the surface needs, with optional padding.
- Preserve builder ergonomics by offering standard elements and composition
helpers for common structures such as inspector rows.
- Use indentation as the authoring grammar so the written document has the same
shape as the UI tree.
- Treat styling as typed provider-owned state, not as hidden renderer CSS.
- Make cross-runtime lowering boring: tokens, rules, variants, states, and
capability gaps are explicit.
@ -44,6 +46,34 @@ designer. The stylesheet is not the truth.
CSS, UIKit, Android XML, Direct2D brushes, and TUI attributes are generated
lowerings. They are not portable state owners.
## Authoring Syntax
CultUI is indentation-authored. Blocks are owned by indentation, not `end`
markers. Tabs and spaces may both be accepted by parsers, but a file must be
internally consistent. The formatter emits tabs by default because CultUI is
tree-shaped and depth should be visible.
Inline properties are preferred while they remain readable:
```cultui
part thumb size 12 12 bleed 3 radius 999 fill color.accent
```
Dense properties can become an indented property block without changing the
retained tree:
```cultui
part thumb
size 12 12
bleed 3
radius 999
fill color.accent
```
The authoring syntax is not the portable state format. The compiler lowers the
indented document into `gamecult.eve.surface.v1` retained components and style
state.
## Composition Model
CultUI composition is partition-first. A partition owns a rectangular region
@ -53,17 +83,13 @@ property of a partition, not a global worldview.
```cultui
surface repixelizer.operator
partition main split x gap 12
pane hero size 1fr padding 12
text body "Force fake pixel art back onto a real grid."
end
partition main split x gap 12
pane hero size 1fr padding 12
text body "Force fake pixel art back onto a real grid."
partition tools size 2fr split y gap 8
card open-demo
card upload-image
end
end
end
partition tools size 2fr split y gap 8
card open-demo
card upload-image
```
The structural primitives should stay small:
@ -117,23 +143,19 @@ The inspector slider row becomes ordinary nested partitions:
```cultui
partition inspector split y gap 6
partition exposure-row split x gap 8 padding 4
partition exposure-label size 12rem
label "Exposure"
end
partition exposure-field size 1fr
slider bind camera.exposure min 0 max 1 step 0.01
end
end
end
partition exposure-row split x gap 8 padding 4
partition exposure-label size 12rem
label "Exposure"
partition exposure-field size 1fr
slider bind camera.exposure min 0 max 1 step 0.01
```
The same structure can be authored through sugar:
```cultui
fieldRow "Exposure"
slider bind camera.exposure min 0 max 1 step 0.01
end
slider bind camera.exposure min 0 max 1 step 0.01
```
The sugar is acceptable only because it lowers to the explicit partition tree.
@ -188,6 +210,68 @@ UIKit `UISlider`, Android `SeekBar`, Direct2D custom control, or TUI command
row. The portable document remains one standard element, not five renderer
dialects.
## Element Anatomy
Standard elements are not runtime-owned presentation black boxes. A renderer may
choose efficient native machinery, but it must honor the CultUI element anatomy:
parts, local sizing, hit areas, state hooks, and allowed visual overflow.
Partitions own structural layout space. Element anatomy owns visual parts inside
that space. A slider's field partition allocates the logical control box; the
slider anatomy describes the track, fill, thumb, hit area, and any bleed beyond
the strict track bounds.
```cultui
slider bind tester.fov min 0 max 120 step 1
box
height 18
overflow visible
part track
anchor center
size 100% 6
radius 2
fill color.panelInset
part fill
anchor left center
size value% 6
radius 2
fill color.accent
part thumb
anchor value center
size 12 12
bleed 3
radius 999
fill color.accent
shadow glow color.accent 0.35 radius 6
hitArea
size 100% 18
```
The thumb may extend past the track because `part thumb` has `bleed 3` and the
control box permits `overflow visible`. That is not a partition violation. It
is local control presentation.
Reusable skins can package that anatomy:
```cultui
skin inspector.orangeSlider for slider
box height 18 overflow visible
part track anchor center size 100% 6 radius 2 fill color.panelInset
part fill anchor left center size value% 6 radius 2 fill color.accent
part thumb anchor value center size 12 12 bleed 3 radius 999 fill color.accent
fieldRow "FOV"
slider bind tester.fov min 0 max 120 step 1 skin inspector.orangeSlider
```
The runtime lowers `slider` anatomy into DOM, Direct2D, UIKit, Android, or TUI.
It does not invent the slider's visual identity unless the document deliberately
uses the default skin.
## Style Model
CultUI style has four layers:

8
docs/eve-dsl-reactive-bindings.md
View file

@ -84,7 +84,6 @@ derive swarm.eventCount count swarm.events
card pulse "Reactive Pulse"
metric "Event Count" bind swarm.eventCount
button "Append Event" append swarm.events "operator touched the stream at {{now}}"
end
```
This is deliberately small. The current compiler lowers DSL cards, text,
@ -143,8 +142,11 @@ The composition surface should preserve CultUI's old reusable-element
ergonomics without preserving the old Unity construction accident.
Partitioning is the base case: users can define relative or absolute partitions,
nest partitions inside partitions, and use helpers such as `fieldRow` only when
they lower to the same explicit retained tree. Styling is a first-class typed
system, not a bag of CSS selectors. See
they lower to the same explicit retained tree. CultUI authoring uses
indentation for flow instead of `end` markers. Standard element presentation is
also specifiable through element anatomy, so a runtime lowers slider tracks,
thumbs, hit areas, and bleed instead of silently substituting its own taste.
Styling is a first-class typed system, not a bag of CSS selectors. See
[cultui-style-system.md](./cultui-style-system.md).
## Public Context

12
docs/surface-contract-v1.md
View file

@ -52,9 +52,10 @@ The composition model learns from the old Unity CultUI without preserving its
construction accident. The useful part was resolver-backed standard elements
and ergonomic helpers for common UI structures, not vertical-first layout.
CultUI is now partition-first: surfaces divide named regions into relative or
absolute partitions, and common helpers lower into that explicit tree. See
[cultui-style-system.md](./cultui-style-system.md) for the composition and
styling design target.
absolute partitions, and common helpers lower into that explicit tree. The
authoring syntax is indentation-based; compiled surface documents remain the
renderer-facing contract. See [cultui-style-system.md](./cultui-style-system.md)
for the composition and styling design target.
Browser reference support starts in `web/eve-dsl.js` and the fixture
`web/fixtures/reactive-composition.eve`. The first binding primitives are:
@ -82,7 +83,10 @@ Every component has:
}
```
Kinds are semantic, not HTML tags. Renderers lower them to native controls:
Kinds are semantic, not HTML tags. Renderers lower them to native controls, but
standard controls may also carry CultUI anatomy for presentation parts such as
slider tracks, fills, thumbs, hit areas, and visual bleed. Native projection is
an implementation route, not permission to invent a different control face:
- `surface`, `partition`, `stack`, `grid`, `dock`, `panel`, `card`
- `text`, `text.dialogue`, `avatar`