Skip to content

Widget behavior.md

Latest commit

 

History

History
636 lines (486 loc) · 17.6 KB

Widget behavior.md

File metadata and controls

636 lines (486 loc) · 17.6 KB

FROG logo

FROG Widget Behavior

Normative behavior boundary for widget classes, bounded package-published reaction rules, and host-private realization support
FROG — Free Open Graphical Language

Contents

1. Overview

This document defines the normative boundary for widget behavior in FROG.

Widget behavior concerns how a widget reacts over time to:

  • value updates,
  • property changes,
  • method invocation,
  • part-local interaction,
  • event emission conditions,
  • bounded internal state transitions.

This document does not define the entire .wfrog package structure. That serialization format is owned by Widget package (.wfrog).md.

Instead, this document defines what categories of behavior are allowed, how they are separated architecturally, and which behavior surfaces remain portable and reviewable.

Its purpose is not to make behavior disappear. Its purpose is to prevent behavior from becoming hidden, arbitrary, or runtime-defined by accident.

2. Why This Document Exists

Without an explicit behavior boundary, widget systems tend to collapse into one of two failures:

  • all behavior becomes runtime-private and therefore non-portable,
  • all behavior becomes unrestricted package-defined arbitrary code and therefore non-auditable.

FROG rejects both extremes.

A FROG widget may have rich interaction and rich internal reaction, but the public behavior law of that widget must remain explicit and inspectable.

This document therefore exists to keep the behavior corridor disciplined:

  • rich enough for real widgets,
  • bounded enough for portability and auditability,
  • explicit enough that one runtime never becomes the hidden owner of widget behavior law.

3. Scope

This document defines:

  • the allowed categories of widget behavior in FROG,
  • the separation between intrinsic behavior, declarative behavior, bounded expressions, and host-private support,
  • the relationship between behavior and public object surfaces such as properties, methods, events, and parts,
  • the portability boundary across runtime families.

This document does not define:

  • the full widget package JSON structure,
  • the full widget class contract structure,
  • the full host realization resource model,
  • the implementation internals of a given runtime toolkit.

It also does not redefine widget class law. It defines how published widget law may react and evolve without escaping into undocumented runtime behavior or unrestricted host scripting.

4. What Widget Behavior Means in FROG

In FROG, widget behavior means the normative reaction rules associated with a widget class or composite widget class.

Examples include:

  • coercing a numeric value into a valid range,
  • preventing interaction when interaction.enabled is false,
  • emitting value_changed after a committed value update,
  • routing a button click to an increment action,
  • mapping a changed object property onto part-facing appearance state.

Behavior therefore sits between:

  • public object law,
  • runtime realization,
  • diagram-facing interaction.

It is neither just “visual refresh logic” nor a free-form scripting substrate. It is the published reaction doctrine that explains how legal widget surfaces evolve and interact over time.

5. Ownership Boundary

The following distinctions are normative: 

widget class contract   -> what public object surfaces exist
widget behavior         -> how those surfaces react and evolve
widget realization      -> how those surfaces are rendered or hosted
runtime-private code    -> how one runtime implements support details

This means:

  • behavior does not create undocumented public properties,
  • behavior does not override published class law,
  • behavior does not turn SVG into semantic truth,
  • runtime-private implementation support does not become the normative source of widget behavior law.

Likewise: 

portable bounded behavior
    !=
arbitrary package-defined host code

realization support
    !=
public behavior law

one runtime implementation
    !=
the behavioral definition of the class

6. Behavior Levels

FROG widget behavior is divided into four levels.

6.1 Intrinsic class behavior

This is the built-in reaction law that belongs to the widget class definition itself.

6.2 Declarative behavior rules

These are explicit published rules that describe reaction without unrestricted arbitrary code.

6.3 Bounded expressions

These are constrained expression-driven reactions used where declarative mapping alone is insufficient.

6.4 Host-private implementation support

These are runtime-specific internal details required to realize the published behavior on a host toolkit.

Portable widget behavior must remain concentrated in the first three levels. The fourth level exists only to support realization.

This hierarchy is fundamental: portable meaning must live above host-private support, not be reconstructed from it after the fact.

7. Intrinsic Class Behavior

Intrinsic class behavior is the behavior that a widget class always has by virtue of its published class law.

Examples:

  • a numeric control may clamp or reject values outside its allowed range according to its value model,
  • a button may emit pressed and released when host interaction occurs,
  • a disabled widget may reject user-originated edit operations,
  • a chart may append samples using a published update method contract.

Intrinsic behavior belongs to the widget definition. It MUST be inspectable from package-published widget content. It MUST NOT exist only as undocumented runtime convention.

Intrinsic behavior is the strongest portable behavioral tier. If a runtime claims support for a class, it must preserve the intrinsic behavior surfaces that are part of the published class law.

8. Declarative Behavior Rules

Declarative behavior rules are package-published reaction rules that remain explicit and reviewable.

Examples:

  • when interaction.enabled is false, suppress user-originated part actions,
  • when value changes, refresh value_display,
  • when label.text changes, refresh the label part,
  • when a button part is activated, invoke a published class method.

Declarative behavior rules SHOULD prefer:

  • stable source identifiers,
  • stable property and part references,
  • explicit event triggers,
  • bounded state consequences.

A declarative rule MUST remain understandable without reading one runtime implementation.

Declarative rules are therefore the preferred publication surface whenever the intended reaction can be expressed without imperative host-specific logic.

9. Bounded Expressions

Some behaviors require more than simple declarative mappings.

FROG therefore allows bounded expressions in widget behavior where necessary, but only under strict limits.

Bounded expressions MAY be used for:

  • value normalization,
  • derived appearance state,
  • simple computed enablement or visibility,
  • simple event payload shaping,
  • composition-local routing logic.

Bounded expressions MUST remain:

  • inspectable,
  • portable,
  • deterministic,
  • side-effect-bounded,
  • non-host-specific in their public meaning.

Bounded expressions MUST NOT become a hidden general-purpose scripting loophole that redefines widget class law.

In particular, bounded expressions MUST NOT:

  • arbitrarily create new public members,
  • call host-private APIs as part of portable public meaning,
  • silently mutate forbidden public surfaces,
  • depend on one runtime’s internal object graph to preserve meaning.

10. Host-Private Implementation Support

A runtime may require private implementation support in order to realize a published widget behavior.

Examples:

  • connecting host toolkit focus events to published focus_gained and focus_lost,
  • mapping platform-native input handling to published button events,
  • performing redraw scheduling,
  • managing accessibility bridge objects,
  • managing toolkit-private caches or retained rendering resources.

These details are allowed and expected.

However, host-private support MUST NOT:

  • invent undocumented portable public members,
  • silently change the legality of published members,
  • silently redefine event meaning,
  • silently redefine bounded behavior law.

Host-private support therefore exists to implement published behavior, not to become the hidden definition of that behavior.

11. Event Emission and State Updates

Behavior may cause event emission and state updates, but only in ways consistent with published widget law.

In particular:

  • an event MUST correspond to a published event identifier,
  • an emitted payload MUST remain compatible with the published event payload shape,
  • a state update MUST target a published writable surface or an explicitly internal surface,
  • behavior MUST NOT mutate read-only public properties through hidden side channels.

The public event and mutation surfaces therefore remain bounded by the class contract, not by runtime convenience.

If a class wants a mutation or event to be portable, that mutation or event must be published as such. Behavior law cannot smuggle new public semantics through hidden internal transitions.

12. Mutability and Safety

Widget behavior is constrained by published mutability posture.

If a property is:

  • design-time only, runtime behavior MUST NOT mutate it as a public runtime surface,
  • read-only, runtime behavior MUST NOT expose hidden public writes to it,
  • internal, the runtime MAY change it privately so long as this does not alter the published public contract.

Behavior rules SHOULD preserve deterministic and reviewable object evolution.

Behavior safety therefore depends on respecting:

  • member mutability posture,
  • member persistence posture,
  • declared event contracts,
  • declared part boundaries,
  • declared portable versus non-portable behavior tiers.

13. Interaction with Properties, Methods, Events, and Parts

Widget behavior depends on the published object model and does not replace it.

Accordingly:

  • properties define stable data-facing surfaces,
  • methods define stable operation surfaces,
  • events define stable observation surfaces,
  • parts define stable substructure surfaces,
  • behavior defines how these published surfaces react together.

A behavior rule may therefore:

  • read a published property,
  • write a published writable property,
  • invoke a published internal or public method where allowed,
  • emit a published event,
  • target a published part.

But behavior MUST NOT bypass the published object model by inventing hidden portable semantics.

This means that behavior is subordinate to object law: it coordinates published surfaces, but does not create a second invisible object model beside them.

14. What Must Not Happen

The following are prohibited as normative behavior doctrine:

  • placing the only true behavior law in runtime-private code,
  • placing behavior law only in SVG assets,
  • using unrestricted arbitrary package-defined host code as the primary behavioral publication surface,
  • using behavior declarations to create undocumented public properties, methods, events, or parts,
  • using one runtime's convenience API as the definition of portable widget law.

Likewise, the following are prohibited:

  • treating host-private callbacks as if they were portable published behavior law,
  • treating realization artifacts as if they owned public reaction semantics,
  • treating package-defined imperative escape hatches as the normal portable publication model,
  • making support for a widget class depend on undocumented behavior contracts.

15. Publication Through .wfrog

Behavior surfaces are typically published through .wfrog packages.

The package document owns the serialization structure of that publication.

This document instead constrains what those package-published behavior surfaces are allowed to mean.

In particular, a package may publish:

  • intrinsic class behavior declarations,
  • declarative rules,
  • bounded expressions,
  • behavior routing for composite widgets.

A package MUST NOT claim unrestricted opaque behavior as normative portable widget law.

Publication through .wfrog therefore enables portability only when the published behavior remains within the bounded and inspectable doctrine defined here.

16. Portability Across Runtimes

Portable FROG widget behavior must survive across Python, Rust, and C/C++ runtime families.

This does not require identical host-internal code.

It does require:

  • equivalent published public object surfaces,
  • equivalent public event meaning,
  • equivalent mutability posture,
  • equivalent bounded behavior meaning.

Runtime-specific differences in toolkit, rendering backend, event loop integration, or accessibility bridge implementation are acceptable so long as they do not redefine the public behavior contract.

Portability therefore means behavioral equivalence at the published contract level, not identical private implementation strategy.

17. Status

This document defines the normative doctrine of widget behavior in FROG.

Its closure direction is:

  • explicit class-owned behavior,
  • bounded portable declarative reaction,
  • support for developer-defined composite widgets,
  • clear separation from host-private realization support.

Its role in the widget corridor is to keep behavior rich enough for real widgets while remaining portable, inspectable, and bounded.

18. License

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