Documentation
¶
Overview ¶
Package examples captures component constructor invocations as typed examples and describes them: Props as JSON Schema, named slots, observed HTML and child occurrences, derived by reflection from the actual Go inputs. Gallery is the foundation's own catalogue of one example per component.
It is a package of its own because ui/components is the runtime: a button renders without reflect, encoding/json or go/format, and a shell that serves pages should not link the description and code-generation machinery. This package imports ui/components; nothing in ui/components imports it. ui/forms and ui/page build examples of their own through the same constructors, and ui/export projects them into snapshots.
Index ¶
- func Documentation(e Example) g.Node
- func GalleryGroups() []string
- type ChildOccurrence
- type Example
- func ExampleOf[P any](info ExampleInfo, props P, render func(P) g.Node) Example
- func ExamplePreview(info ExampleInfo, node g.Node, reason string) Example
- func ExampleWithChildren[P any](info ExampleInfo, props P, children []g.Node, render func(P, ...g.Node) g.Node) Example
- func ExampleWithSlots[P, S any](info ExampleInfo, props P, slots S, render func(P, S) g.Node) Example
- func Gallery() []Example
- func (e Example) At(path []string) (Example, error)
- func (e Example) Describe() (ExampleDescription, error)
- func (e Example) DescribeWithLayout() (ExampleDescription, error)
- func (e Example) GoProps() (string, error)
- func (e Example) WithProps(patch json.RawMessage) (Example, error)
- func (e Example) WithPropsAt(path []string, patch json.RawMessage) (Example, error)
- func (e Example) WithReplacementAt(path []string, replacement Example) (Example, error)
- func (e Example) WithSlot(name string, nodes ...g.Node) (Example, error)
- type ExampleDescription
- type ExampleInfo
- type HTMLSpan
- type SlotDescription
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Documentation ¶
Documentation is what a person needs in order to use the component beside it: the id the design export names it by, every property its Props type takes with the value this example gave it, and the slots something else can be put into.
It is projected from the same Example the specimen is rendered from — the schema and the props are the ones export.Export publishes — so a page cannot describe a component this package does not have, or a property it does not take. That is the reason it exists: a wall of specimens says what a badge looks like and nothing about how to ask for one.
func GalleryGroups ¶
func GalleryGroups() []string
GalleryGroups is the groups the examples fall into, in order, so a page a hundred specimens long can be jumped through. Derived from the list above, so a new group needs no second edit.
Types ¶
type ChildOccurrence ¶
type ChildOccurrence struct {
Description ExampleDescription `json:"description"`
Slot string `json:"slot,omitempty"`
Span *HTMLSpan `json:"span,omitempty"`
}
ChildOccurrence retains a source-local invocation identity, not a native node ID. Enclosing identities distinguish placements of the same nested definition. Slot names a declared input, not proof that rendering fetched that field; it is empty when named ownership is unresolved. A nil Span means unobserved, not absent: opaque Go nodes may buffer, omit or duplicate their children's HTML.
type Example ¶
type Example struct {
ExampleInfo
Node g.Node
// contains filtered or unexported fields
}
Example captures typed inputs while keeping the existing gallery renderer. Props and slot containers are copied. Nodes and callbacks remain opaque, trusted Go capabilities: callers must not mutate state captured by them.
func ExampleOf ¶
func ExampleOf[P any](info ExampleInfo, props P, render func(P) g.Node) Example
ExampleOf captures Props and delegates all rendering to render.
func ExamplePreview ¶
func ExamplePreview(info ExampleInfo, node g.Node, reason string) Example
ExamplePreview explicitly records a helper without an editable Props contract.
func ExampleWithChildren ¶
func ExampleWithChildren[P any](info ExampleInfo, props P, children []g.Node, render func(P, ...g.Node) g.Node) Example
ExampleWithChildren names an existing variadic constructor's node slice "children". It does not introduce a portable child graph or renderer.
func ExampleWithSlots ¶
func ExampleWithSlots[P, S any](info ExampleInfo, props P, slots S, render func(P, S) g.Node) Example
ExampleWithSlots captures the actual slot struct beside its Props.
func Gallery ¶
func Gallery() []Example
Gallery is every component this package renders, once each per variant worth distinguishing.
func (Example) At ¶
At resolves an exact source occurrence without rendering. Like WithPropsAt, it refuses ambiguous or unsupported ancestor inputs, but permits a directly declared child that is currently suppressed. The result remains bound to the original capture; subsequent edits return new captures, not mutable handles.
func (Example) Describe ¶
func (e Example) Describe() (ExampleDescription, error)
Describe observes one synchronous rendering through the existing constructors. Children describe bound invocations, not all HTML nodes. OpaqueSlots identifies supported slots containing unbound, non-nil Go nodes; neither their complete contents nor their rendering correspondence can be inferred from this record.
func (Example) DescribeWithLayout ¶
func (e Example) DescribeWithLayout() (ExampleDescription, error)
DescribeWithLayout opts into source declarations without changing Describe's v1 serialization. Unknown ancestors/children still require explicit refusal. The declarations themselves are components.LayoutDescription: a layout component owns what it says about its root, and this package only reads it.
func (Example) GoProps ¶
GoProps returns a copyable Go declaration of the captured properties. Rich slots remain trusted application composition and are documented separately. Unsupported callback or opaque values are refused, never printed as addresses.
func (Example) WithProps ¶
func (e Example) WithProps(patch json.RawMessage) (Example, error)
WithProps applies a strict, exact-case top-level JSON patch. Each supplied nested value replaces that field in full; unspecified trusted transport fields are retained. This is typed data editing, not HTML sanitization.
func (Example) WithPropsAt ¶
WithPropsAt edits one captured invocation by its exact root ID followed by source-local child IDs. It does not render: directly declared but suppressed children can be edited. Callers needing a visible edit must separately check rendering evidence before and after the change; this is not persistence.
Traversed ancestors must have only directly bound Node/[]Node inputs and zero values in other advertised slots. Hidden fields and closures are not inspected. The target retains its slots. Only its owning slot chain is immutably rebuilt through WithProps and WithSlot; no JSON value constructs a node.
func (Example) WithReplacementAt ¶
WithReplacementAt replaces one typed invocation with another of the same declared interface. It keeps the destination's ExampleInfo and copies the replacement's complete props, slots and renderer; it never merges overrides. Both captures must be valid. Paths and owning slots follow WithPropsAt's non-rendering rules. Trusted nodes and closures are not cloned or inspected.
type ExampleDescription ¶
type ExampleDescription struct {
ExampleInfo
PropsEditable bool `json:"propsEditable"`
Reason string `json:"reason,omitempty"`
Props json.RawMessage `json:"props"`
Schema json.RawMessage `json:"schema"`
Slots []SlotDescription `json:"slots"`
HTML string `json:"html"`
Children []ChildOccurrence `json:"children"`
OpaqueSlots []string `json:"opaqueSlots"`
Layout *components.LayoutDescription `json:"layout,omitempty"`
}
ExampleDescription projects one captured invocation and its known children. PropsEditable and slot support describe Go APIs, not native/editor readiness.
func (ExampleDescription) SameInterface ¶
func (d ExampleDescription) SameInterface(other ExampleDescription) bool
SameInterface compares source-generated component contracts, not arbitrary JSON Schema equivalence or native editor capabilities. Identity, editability, canonical schema bytes and every named slot declaration must agree. Slot declaration order, invocation metadata, values and content are not interfaces. Equal read-only descriptions remain read-only; equality grants no edit right.
type ExampleInfo ¶
type ExampleInfo struct {
ID string `json:"id"`
ComponentID string `json:"componentId"`
Group string `json:"group"`
Name string `json:"name"`
}
ExampleInfo identifies a particular constructor invocation, not a second component registry. IDs are supplied by the owner of the example collection. ComponentID names one Props/slot interface independently of example grouping; helpers with different interfaces need distinct component identities.
type HTMLSpan ¶
HTMLSpan addresses bytes in the immediate parent's Description.HTML. It is evidence from one synchronous render, never a durable identity or DOM address. Equal endpoints describe an observed invocation that emitted no bytes.
type SlotDescription ¶
type SlotDescription struct {
Name string `json:"name"`
GoType string `json:"goType"`
Supported bool `json:"supported"`
Multiple bool `json:"multiple"`
TrustedOnly bool `json:"trustedOnly"`
}
SlotDescription advertises the actual field type. Supported replacements accept trusted Go nodes only; callbacks and compound slot data are read-only.
Source Files