FROG Widget Interaction

Canonical source-level representation of natural-value, object-style, and event-oriented diagram interaction with front-panel widget instances
FROG — Free Open Graphical Language

1. Overview
2. Why This Document Exists
3. Scope
4. Design Objectives
5. Relation with Other Specifications
6. Core Model
7. Natural Value Path vs Object-Style Path
8. Widget Member Addressing
9. Interaction Node Families
10. Property Read
11. Property Write
12. Method Invoke
13. Event Observe
14. Typing, Sequencing, and Effect Boundaries
15. Diagram Representation
16. Validation Rules
17. Source-to-Library Mapping
18. Examples
19. Out of Scope
20. Status
21. License

1. Overview

FROG front-panel widgets are source-level widget instances declared in front_panel. They participate in execution through the authoritative diagram, not through the front panel by itself.

This document defines the canonical source-level representation of three distinct diagram-side widget interaction paths:

natural-value participation through widget_value,
object-style interaction through widget_reference together with explicit widget interaction primitives,
event-oriented observation through widget_reference together with explicit event observation primitives.

These paths are related but semantically distinct.

The natural-value path is the canonical representation of ordinary participation of a widget primary value in typed dataflow. The object-style path is the canonical representation of explicit member interaction such as:

property reads,
property writes,
method invocation.

The event-oriented path is the canonical representation of observing declared widget or widget-part events through an explicit source-visible primitive rather than through hidden runtime conventions.

FROG standardizes the following widget interaction primitive families for the object-style and event-oriented paths:

frog.ui.property_read
frog.ui.property_write
frog.ui.method_invoke
frog.ui.event_observe

A value-carrying widget may expose a primary value member such as value. That member has a dual architectural posture:

it participates naturally through widget_value, and
it MAY also be exposed as an ordinary object property when the corresponding widget class contract permits that access.

Accordingly, the same conceptual primary value may be reachable through two different interaction forms, but those forms MUST remain distinct in source and semantics.

This document also preserves the separation between executable value participation, object-style member interaction, event observation, and source-owned instance metadata. A widget MAY expose non-semantic presentation members such as style.text_color or interaction.visible, and a widget instance MAY persist presentation-oriented package or asset references through source-owned metadata. Those members belong to object-style access or source-owned instance metadata, not to the natural typed value path.

2. Why This Document Exists

A serious widget system requires more than a front-panel declaration. It also requires a disciplined way to express how a diagram interacts with widgets as values, as objects, and as event sources.

Without that distinction, several architectural collapses appear:

ordinary typed dataflow gets mixed with object-style member access,
presentation properties get confused with semantic primary values,
widget references get confused with ordinary typed values,
events get trapped in runtime-private code,
runtime convenience gets confused with language truth.

This document therefore fixes a clean interaction corridor:

widget_value for natural primary-value participation,
widget_reference for object-style widget access and event-oriented observation,
frog.ui.* primitives for explicit reads, writes, invocations, and event observation.

It exists so that a runtime may implement widget interaction, but may not silently redefine the interaction model. The interaction corridor must remain source-visible, inspectable, and portable across runtime families.

3. Scope

This document specifies:

the canonical source-level representation of natural-value, object-style, and event-oriented widget interaction in the diagram,
the semantic boundary between widget_value and widget_reference-based interaction,
the member-addressing model for widget and widget-part properties, methods, and events,
the required node-local descriptor fields used by widget interaction primitives,
the graph-shape constraints that tie widget interaction primitives to widget_reference,
the source-level validation rules for these interaction forms.

This document does not specify:

the full widget object model,
the class-side legality of widget members,
the canonical declaration and composition of the front panel,
the full primitive identities and complete primitive signatures beyond their source-facing use here,
the primitive-local execution semantics of UI interaction operations,
the general execution semantics of the diagram,
one mandatory rendering engine or one mandatory realization stack.

This document therefore sits between widget instance declaration and primitive execution semantics: it defines how interaction is expressed in canonical source, not the full meaning of every class member and not the full behavior of every primitive implementation.

4. Design Objectives

The widget interaction model is designed to satisfy the following objectives:

Object consistency — widget interaction MUST follow the widget object model instead of introducing ad hoc UI exceptions.
Contract consistency — object-style access and event observation MUST be legal only when permitted by the corresponding widget class contract.
Dataflow clarity — ordinary value flow and explicit object access MUST remain distinct.
Event explicitness — event observation MUST be source-visible and MUST NOT depend solely on runtime-private conventions.
Source explicitness — widget interaction MUST be represented through explicit source constructs rather than hidden editor conventions.
Type safety — ordinary value typing and event payload typing MUST remain compatible with the FROG type system.
Token separation — ordinary typed values, widget references, event payloads, and UI sequencing tokens MUST remain distinct categories and MUST NOT be silently collapsed.
Profile extensibility — widget classes MAY expose different properties, methods, parts, and events under different profiles while preserving one common interaction model.
Presentation separation — presentation properties and realization-oriented metadata MUST remain distinct from the natural executable value path.
Architectural separation — widget interaction MUST NOT redefine public interface semantics, front-panel composition semantics, widget class contracts, general execution semantics, or the ownership of the standardized frog.ui.* primitive surface.

5. Relation with Other Specifications

This document depends on and complements the following specifications:

Expression/Type.md — ordinary value types, compatibility rules, and implicit coercion rules.
Expression/Widget.md — widget instances, roles, value behavior at instance level, source-visible widget parts, and widget identity.
Expression/Widget class contract.md — class-side member contracts, event contracts, part ownership, member legality, access modes, and class-level object exposure.
Expression/Front panel.md — declaration and serialization of widget instances and source-owned instance metadata.
Expression/Diagram.md — executable graph structure, node categories, canonical widget node kinds, and port-resolution rules.
Libraries/UI.md — the standardized frog.ui.* primitive surface, primitive signatures, sequencing rules, and primitive-local semantics.
Expression/Widget package (.wfrog).md — the architectural role of .wfrog packages when class law, bounded behavior, or realization mappings are resolved through external widget-oriented artifacts.

This document complements, but does not redefine, the following canonical diagram node kinds:

widget_value — natural primary-value participation,
widget_reference — object-style widget access anchor and event observation anchor.

This document also does not redefine public interface semantics. A front-panel widget does not create a public interface port by itself. Public interface behavior remains represented canonically through diagram-side interface nodes.

Ownership is intentionally split as follows:

Widget interaction.md
  -> source-level interaction model
  -> boundary between widget_value and widget_reference
  -> member and event descriptor model used by interaction nodes
  -> graph-shape constraints
  -> source-level validation rules for widget interaction forms

Widget.md
  -> widget instance model
  -> widget roles
  -> instance-side value behavior
  -> source-visible widget identity and source-owned metadata

Widget class contract.md
  -> class-side member and event contracts
  -> part ownership
  -> readable / writable / invocable / observable legality
  -> design-time vs runtime access constraints

Front panel.md
  -> widget declaration and front-panel composition
  -> source-owned instance metadata

Diagram.md
  -> executable graph structure
  -> widget_value / widget_reference node kinds
  -> primitive-node structural integration

Libraries/UI.md
  -> frog.ui.* primitive identities
  -> primitive signatures
  -> primitive-local typing and sequencing rules
  -> primitive-local interaction semantics

Widget package (.wfrog).md
  -> external widget-oriented class and realization artifacts
  -> package-level bounded behavior publication
  -> package-level asset and host-binding boundaries

6. Core Model

A widget interaction node addresses a declared surface of a widget object.

A widget surface addressed through this document is one of:

a widget property,
a widget-part property,
a widget method,
a widget-part method,
a widget event,
a widget-part event.

Examples of conceptual interaction:

ctrl_gain.value
ctrl_gain.interaction.visible
ctrl_gain.style.text_color
ctrl_gain.label.text
ctrl_gain.focus()
graph_1.axes.x.interaction.visible
count_indicator.value_display.value_rendered

The object-style interaction path is always represented conceptually as:

widget_reference -> frog.ui.property_read
widget_reference -> frog.ui.property_write
widget_reference -> frog.ui.method_invoke
widget_reference -> frog.ui.event_observe

A widget interaction node does not declare the widget instance. It operates on a widget instance that already exists in the front_panel.

A widget interaction node also does not define which members or events are legal. It relies on the corresponding widget class contract.

When explicit ordering of UI side effects is required, widget interaction nodes MAY participate in a sequencing chain through ui_in and ui_out. The primitive-level meaning of those sequencing ports is defined elsewhere.

The following distinction MUST remain explicit:

ordinary typed value
    !=
widget reference token
    !=
UI sequencing token

The following distinction MUST also remain explicit:

natural primary value flow
    !=
object-style property access
    !=
object-style method invocation
    !=
event observation
    !=
source-owned instance metadata

The interaction corridor therefore has two anchors and several explicit operations:

widget_value anchors natural value participation,
widget_reference anchors object-style and event-oriented interaction,
the primitive node identifies the interaction kind,
the local descriptor identifies the addressed surface,
the class contract decides whether the interaction is legal.

7. Natural Value Path vs Object-Style Path

A value-carrying widget class may expose a primary value member, often named value.

FROG recognizes two possible ways to access that member:

the natural value path through widget_value,
the object-style path through widget_reference and an explicit interaction primitive.

7.1 Natural Value Path

The natural value path is the canonical path for ordinary typed value participation in dataflow.

Conceptually:

widget_value(ctrl_count)
    -> u16

This path SHOULD be used when the program intends to:

read the primary value of a control as an ordinary input to dataflow,
write the primary value of an indicator as an ordinary output from dataflow,
participate in normal computation without object-style intent.

7.2 Object-Style Path

The object-style path is the canonical path for:

property reads,
property writes,
method invocation,
addressing named parts,
accessing presentation properties such as style.text_color or interaction.visible,
accessing members that have no natural value-path representation.

Conceptually:

widget_reference(ctrl_count)
    -> frog.ui.property_write { "member": "style.text_color" }

7.3 Primary Value through Object-Style Access

A widget class MAY also expose its primary value member as an object-style property named value.

If the class contract allows it, the following is legal:

widget_reference(ctrl_count)
    -> frog.ui.property_read { "member": "value" }

However, this path MUST remain semantically distinct from widget_value. When the program intent is ordinary value participation in dataflow, tools SHOULD prefer the natural widget_value form.

7.4 Event-Oriented Observation Path

A widget class MAY expose named events at the widget root or at declared parts. Those events are not ordinary typed values and are not properties. They are observed through the event-oriented path.

Conceptually:

widget_reference(count_indicator)
    -> frog.ui.event_observe { "name": "value_rendered" }

If an event payload exists, that payload becomes available through the primitive-level output contract defined elsewhere. This observation path MUST remain distinct from both widget_value and property access.

7.5 Presentation Property Boundary

A widget class MAY expose presentation-oriented members such as:

style.text_color,
style.background_fill,
interaction.visible,
other explicitly declared presentation-facing properties.

These members belong to object-style access or source-owned instance metadata. They MUST NOT be treated as natural value-path equivalents.

In particular:

style.text_color MAY be read or written through object-style property access when the class contract allows it,
a source-owned asset or template reference MAY exist without becoming an ordinary executable value-flow member.

7.6 Prohibited Collapses

The following collapses are invalid unless another specification explicitly states otherwise:

treating widget_reference as an ordinary typed value,
treating a presentation property as if it were the natural primary value of the widget,
treating an event payload channel as if it were the widget primary value path,
treating a presentation asset reference as executable semantic state by default,
treating source-owned instance metadata as a substitute for widget_value.

Widget member addressing identifies:

the target widget instance,
optionally a named widget part,
the addressed property, method, or event.

8.1 Full Conceptual Address

A full conceptual property address may be understood as:

{
  "widget": "ctrl_gain",
  "part": "label",
  "member": "text"
}

For methods:

{
  "widget": "ctrl_gain",
  "part": "label",
  "name": "show"
}

For events:

{
  "widget": "count_indicator",
  "part": "value_display",
  "name": "value_rendered"
}

8.2 Primitive-Local Descriptor Model

In the canonical diagram model, widget identity is carried by the incoming ref port rather than embedded directly in the primitive node.

Accordingly:

property interaction nodes MUST declare a widget_member descriptor,
method interaction nodes MUST declare a widget_method descriptor,
event interaction nodes MUST declare a widget_event descriptor.

Canonical property descriptors:

{ "member": "text" }
{ "part": "label", "member": "text" }

Canonical method descriptors:

{ "name": "focus" }
{ "part": "label", "name": "show" }

Canonical event descriptors:

{ "name": "value_rendered" }
{ "part": "value_display", "name": "value_rendered" }

8.3 Widget-Level Addressing

If part is omitted, the addressed member or event belongs to the widget root object.

Examples:

{ "member": "value" }
{ "member": "interaction.visible" }
{ "member": "style.text_color" }
{ "name": "focus" }
{ "name": "value_changed" }

8.4 Part-Level Addressing

If part is present, the addressed member or event belongs to the named widget part.

Examples:

{ "part": "label", "member": "text" }
{ "part": "label", "member": "interaction.visible" }
{ "part": "label", "name": "show" }
{ "part": "value_display", "name": "value_rendered" }

8.5 Address Validity

A widget member or event address is valid only if all of the following hold:

the referenced widget exists in front_panel,
the referenced part exists when part is specified,
the addressed member or event exists for the widget class or widget-part contract under the active profile,
the addressed surface is compatible with the interaction kind being used,
the relevant access or observation mode is allowed in the current context,
profile and host requirements are satisfied when such gates exist.

For example:

frog.ui.property_read MUST target a readable property,
frog.ui.property_write MUST target a writable property,
frog.ui.method_invoke MUST target an invocable method,
frog.ui.event_observe MUST target an observable event.

These legality rules are owned by the corresponding widget class contract, not by this document.

9. Interaction Node Families

Widget object-style and event-oriented interactions are represented canonically as primitive nodes in the diagram.

The standardized primitive identifiers used by this source model are:

frog.ui.property_read
frog.ui.property_write
frog.ui.method_invoke
frog.ui.event_observe

Each widget interaction node MUST satisfy all of the following source-facing constraints:

kind MUST be primitive,
type MUST be one of the standardized primitive identifiers above,
the node MUST consume a widget reference through required input port ref,
property interaction nodes MUST declare widget_member,
method interaction nodes MUST declare widget_method,
event interaction nodes MUST declare widget_event.

The full primitive signatures, including required and optional ports beyond the source-facing reference model, are owned elsewhere.

This document standardizes which interaction families exist at source level and how they attach to widget references. It does not redefine the intrinsic primitive library as such.

10. Property Read

A property read interaction represents a read of a property value from a widget or widget part into the diagram.

10.1 Standard Primitive Identifier

frog.ui.property_read

10.2 Required Structural Fields

{
  "id": "read_gain_visible",
  "kind": "primitive",
  "type": "frog.ui.property_read",
  "widget_member": {
    "member": "interaction.visible"
  }
}

10.3 Representation Rules

the node MUST consume a compatible widget reference through ref,
the node MUST declare widget_member,
the addressed member MUST be a readable property under the applicable widget class contract and active profile.

10.4 Access to Primary Value as a Property

Reading { "member": "value" } through frog.ui.property_read is valid only when the widget class contract exposes value as a readable property.

However, when the intent is ordinary value flow, tools SHOULD prefer the natural widget_value representation.

10.5 Access to Presentation Properties

Reading a presentation property such as { "member": "style.text_color" } is valid only when the widget class contract exposes that member as readable.

Such a read remains object-style access. It MUST NOT be confused with the natural primary-value path.

11. Property Write

A property write interaction represents a write of a diagram value into a writable widget or widget-part property.

11.1 Standard Primitive Identifier

frog.ui.property_write

11.2 Required Structural Fields

{
  "id": "write_gain_label",
  "kind": "primitive",
  "type": "frog.ui.property_write",
  "widget_member": {
    "part": "label",
    "member": "text"
  }
}

11.3 Representation Rules

the node MUST consume a compatible widget reference through ref,
the node MUST declare widget_member,
the addressed member MUST be a writable property under the applicable widget class contract and active profile.

11.4 Access to Primary Value as a Property

Writing { "member": "value" } through frog.ui.property_write is valid only when the widget class contract exposes value as a writable property.

This object-style write MUST remain semantically distinct from the natural primary value path represented by widget_value. For ordinary widget primary-value participation in dataflow, tools SHOULD prefer the natural path.

11.5 Access to Presentation Properties

Writing a presentation property such as { "member": "style.text_color" } is valid only when the widget class contract exposes that member as writable.

A presentation-property write MAY affect host-visible appearance. It MUST NOT by itself redefine the executable meaning of the program.

11.6 Presentation Asset Reference Boundary

When a widget surface exposes a source-owned presentation-oriented reference member, runtime object-style writes are valid only if the corresponding class contract explicitly declares that member runtime-writable.

By default, source-owned presentation references do not become runtime-writable executable state merely because they appear in source.

12. Method Invoke

A method invoke interaction represents a method call on a widget or widget part.

12.1 Standard Primitive Identifier

frog.ui.method_invoke

12.2 Required Structural Fields

{
  "id": "invoke_reset",
  "kind": "primitive",
  "type": "frog.ui.method_invoke",
  "widget_method": {
    "name": "reset_to_default"
  }
}

12.3 Representation Rules

the node MUST consume a compatible widget reference through ref,
the node MUST declare widget_method,
the addressed member MUST be an invocable method under the applicable widget class contract and active profile.

12.4 Method Invocation and Parts

Part-scoped method invocation is represented by including part in the method descriptor.

{
  "id": "invoke_label_show",
  "kind": "primitive",
  "type": "frog.ui.method_invoke",
  "widget_method": {
    "part": "label",
    "name": "show"
  }
}

Whether the targeted part exists, and whether the named method is invocable on that part, depends on the corresponding widget class contract.

Method invocation remains object interaction, not value participation. Even when a method affects widget appearance or state, it does not become a substitute for widget_value.

13. Event Observe

An event observation interaction represents source-visible observation of a declared widget or widget-part event.

13.1 Standard Primitive Identifier

frog.ui.event_observe

13.2 Required Structural Fields

{
  "id": "observe_value_rendered",
  "kind": "primitive",
  "type": "frog.ui.event_observe",
  "widget_event": {
    "name": "value_rendered"
  }
}

13.3 Representation Rules

the node MUST consume a compatible widget reference through ref,
the node MUST declare widget_event,
the addressed surface MUST be an observable event under the applicable widget class contract and active profile.

13.4 Event Observation and Parts

Part-scoped event observation is represented by including part in the event descriptor.

{
  "id": "observe_value_display_rendered",
  "kind": "primitive",
  "type": "frog.ui.event_observe",
  "widget_event": {
    "part": "value_display",
    "name": "value_rendered"
  }
}

Whether the targeted part exists, and whether the named event is observable on that part, depends on the corresponding widget class contract.

13.5 Event Payload Boundary

The event payload, if any, is governed by the event declaration in the widget class contract and by the primitive-level output contract in Libraries/UI.md.

An event payload is neither:

an ordinary property,
the widget primary value by default,
a substitute for widget reference identity.

Event observation therefore introduces an explicit observable occurrence into the diagram. It does not collapse the event into a property read and does not collapse the payload into the natural value path unless another explicit contract says so.

14. Typing, Sequencing, and Effect Boundaries

Typing rules for widget interaction nodes are not owned entirely by this document.

They depend on:

the FROG type system defined in Type.md,
the member and event types declared by the widget class contract,
the primitive-level typing rules owned by Libraries/UI.md.

Similarly, explicit sequencing through ui_in and ui_out is not owned entirely by this document.

This document only states that widget interaction nodes MAY participate in explicit UI sequencing when the underlying primitive contract supports it.

The following distinction MUST remain explicit:

member legality
  !=
event legality
  !=
primitive signature
  !=
primitive-local execution semantics

Respectively:

member and event legality belong to the widget class contract layer,
primitive signature belongs to the intrinsic UI library layer,
primitive-local execution semantics belong to the intrinsic UI library layer together with the relevant execution-semantics layers.

The following distinction MUST also remain explicit:

ordinary typed value ports
  !=
widget reference ports
  !=
event payload ports
  !=
UI sequencing ports

Accordingly:

ordinary value ports are governed by Type.md,
ref ports carry widget-reference tokens defined by the widget interaction model and primitive contracts,
event payload ports, when present, carry event payload values defined by event contracts and primitive contracts,
ui_in and ui_out carry opaque sequencing tokens used only for explicit UI ordering when supported.

The following distinction MUST also remain explicit:

semantic primary value
  !=
presentation property
  !=
presentation reference
  !=
event payload

Accordingly, a diagram that writes style.text_color is not equivalent to a diagram that writes the widget primary value, and a source-owned presentation reference is not by itself an executable value-flow edge. Likewise, an observed event payload is not automatically the widget primary value unless the event contract explicitly says so.

15. Diagram Representation

Widget interaction nodes appear inside the authoritative executable diagram as primitive nodes.

Conceptually:

front_panel widget instance
        |
        +-- widget_value -----------------> ordinary value flow
        |
        +-- widget_reference ------------> object-style and event-oriented interaction
                                             |
                                             +-- frog.ui.property_read
                                             +-- frog.ui.property_write
                                             +-- frog.ui.method_invoke
                                             +-- frog.ui.event_observe

The interaction node itself does not carry widget identity directly. Widget identity is supplied through the incoming ref edge from a widget_reference node.

This separation is intentional:

widget_reference identifies the target widget instance,
the interaction primitive identifies the kind of access or observation,
the local descriptor identifies the targeted member or event,
the widget class contract determines whether that access or observation is legal.

Source-owned instance metadata remains outside this executable interaction chain unless:

it is explicitly addressed through a legal property read or property write, or
another specification explicitly grants it executable interaction meaning.

This keeps the diagram authoritative without forcing the front panel to absorb executable semantics. The front panel declares the widget. The diagram declares the interaction.

16. Validation Rules

Validators MUST enforce at least the following rules:

a widget interaction node MUST be a primitive node,
its type MUST be one of the standardized widget interaction primitive identifiers,
it MUST consume a compatible widget reference through ref,
property interaction nodes MUST declare widget_member,
method interaction nodes MUST declare widget_method,
event interaction nodes MUST declare widget_event,
the referenced widget MUST exist,
the referenced part MUST exist when a part is specified,
the addressed member or event MUST exist on the targeted class or targeted part contract,
the requested access or observation mode MUST be legal in the current context,
profile gates and host gates MUST be respected when present.

Validators SHOULD diagnose at least the following error classes:

missing widget reference input,
invalid primitive kind,
unknown widget interaction primitive identifier,
missing widget_member, widget_method, or widget_event descriptor,
unknown widget instance,
unknown widget part,
unknown member,
unknown event,
read of non-readable property,
write to non-writable property,
invocation of non-invocable method,
observation of non-observable event,
use of profile-gated member outside the required profile,
use of host-gated member or event without required host capability,
attempt to use object-style access where only natural value access is intended,
treating a widget reference token as an ordinary typed value,
treating a sequencing port as an ordinary typed value port,
treating a non-semantic presentation property as the natural value path,
treating an event payload as the widget natural value path without an explicit contract,
treating a source-owned presentation reference as runtime-writable when the class contract forbids it,
treating presentation-oriented metadata as executable semantic state without an explicit enabling specification.

These checks validate interaction form and interaction legality. They do not redefine the full execution semantics of the targeted primitives.

17. Source-to-Library Mapping

The source-facing interaction model standardized here maps to intrinsic UI primitives in the frog.ui.* namespace.

At minimum:

source-level property read maps to frog.ui.property_read,
source-level property write maps to frog.ui.property_write,
source-level method invocation maps to frog.ui.method_invoke,
source-level event observation maps to frog.ui.event_observe.

This document standardizes the source-facing use of those primitives, not their full primitive definitions.

The natural primary-value path remains represented by widget_value, not by those object-style or event-oriented interaction primitives.

This mapping is deliberate: the interaction document defines the source contract of usage, while Libraries/UI.md defines the intrinsic primitive surface that realizes that contract.

18. Examples

18.1 Read widget property

{
  "id": "read_gain_visible",
  "kind": "primitive",
  "type": "frog.ui.property_read",
  "widget_member": {
    "member": "interaction.visible"
  }
}

18.2 Write part property

{
  "id": "write_gain_label",
  "kind": "primitive",
  "type": "frog.ui.property_write",
  "widget_member": {
    "part": "label",
    "member": "text"
  }
}

18.3 Invoke widget method

{
  "id": "invoke_reset",
  "kind": "primitive",
  "type": "frog.ui.method_invoke",
  "widget_method": {
    "name": "reset_to_default"
  }
}

18.4 Invoke part method

{
  "id": "invoke_label_show",
  "kind": "primitive",
  "type": "frog.ui.method_invoke",
  "widget_method": {
    "part": "label",
    "name": "show"
  }
}

18.5 Observe widget event

{
  "id": "observe_rendered",
  "kind": "primitive",
  "type": "frog.ui.event_observe",
  "widget_event": {
    "name": "value_rendered"
  }
}

18.6 Observe part event

{
  "id": "observe_value_display_rendered",
  "kind": "primitive",
  "type": "frog.ui.event_observe",
  "widget_event": {
    "part": "value_display",
    "name": "value_rendered"
  }
}

18.7 Natural value access

widget_value(ctrl_count)
    -> u16

This is the preferred representation for ordinary primary-value participation in dataflow.

18.8 Object-style presentation write

widget_reference(ctrl_count)
    -> frog.ui.property_write {
         "member": "style.text_color"
       }

This is valid only if the active widget class contract declares style.text_color as a writable property.

18.9 Event observation

widget_reference(count_indicator)
    -> frog.ui.event_observe {
         "name": "value_rendered"
       }

This is valid only if the active widget class contract declares value_rendered as an observable event.

18.10 Invalid collapse example

widget_value(ctrl_count)
    -> interpreted as style.text_color

This is invalid. The natural value path MUST NOT be reinterpreted as a presentation-property path.

18.11 Presentation reference boundary example

{
  "id": "ctrl_count",
  "role": "control",
  "class_ref": "frog.widgets.numeric_control",
  "value_type": "u16",
  "props": {
    "face_asset_ref": {
      "kind": "resource_ref",
      "path": "./assets/widgets/u16_numeric_control_face.svg"
    }
  }
}

This source-owned presentation reference does not by itself create an executable value-flow edge. It remains source-owned instance metadata unless another specification explicitly grants additional meaning.

19. Out of Scope

The following are intentionally out of scope for this document:

a complete event registration and subscription lifecycle model,
asynchronous UI message delivery guarantees,
general-purpose widget references as ordinary first-class user values,
one mandatory UI runtime architecture,
the full execution semantics of every UI interaction primitive,
the complete effect model for all UI runtimes and profiles,
automatic interpretation of presentation assets as executable semantics,
one mandatory host rendering system for presentation assets.

20. Status

This document defines the canonical source-level widget interaction corridor for the current repository version.

Version governance and the current applicable specification version are centralized in Versioning/Readme.md.

The closure direction for this document is:

clear separation between natural value flow and object-style interaction,
explicit event observation,
stable addressing of widget properties, methods, events, and parts,
alignment with .wfrog-published widget class contracts.

21. License

See the repository-level license information for the licensing terms governing this specification.

FilesExpand file tree

Widget interaction.md

Latest commit

History

Widget interaction.md

File metadata and controls

FROG Widget Interaction

Contents

1. Overview

2. Why This Document Exists

3. Scope

4. Design Objectives

5. Relation with Other Specifications

6. Core Model

7. Natural Value Path vs Object-Style Path

7.1 Natural Value Path

7.2 Object-Style Path

7.3 Primary Value through Object-Style Access

7.4 Event-Oriented Observation Path

7.5 Presentation Property Boundary

7.6 Prohibited Collapses

8. Widget Member Addressing

8.1 Full Conceptual Address

8.2 Primitive-Local Descriptor Model

8.3 Widget-Level Addressing

8.4 Part-Level Addressing

8.5 Address Validity

9. Interaction Node Families

10. Property Read

10.1 Standard Primitive Identifier

10.2 Required Structural Fields

10.3 Representation Rules

10.4 Access to Primary Value as a Property

10.5 Access to Presentation Properties

11. Property Write

11.1 Standard Primitive Identifier

11.2 Required Structural Fields

11.3 Representation Rules

11.4 Access to Primary Value as a Property

11.5 Access to Presentation Properties

11.6 Presentation Asset Reference Boundary

12. Method Invoke

12.1 Standard Primitive Identifier

12.2 Required Structural Fields

12.3 Representation Rules

12.4 Method Invocation and Parts

13. Event Observe

13.1 Standard Primitive Identifier

13.2 Required Structural Fields

13.3 Representation Rules

13.4 Event Observation and Parts

13.5 Event Payload Boundary

14. Typing, Sequencing, and Effect Boundaries

15. Diagram Representation

16. Validation Rules

17. Source-to-Library Mapping

18. Examples

18.1 Read widget property

18.2 Write part property

18.3 Invoke widget method

18.4 Invoke part method

18.5 Observe widget event

18.6 Observe part event

18.7 Natural value access

18.8 Object-style presentation write

18.9 Event observation

18.10 Invalid collapse example

18.11 Presentation reference boundary example

19. Out of Scope

20. Status

21. License