Skip to content

Widget realization.md

Latest commit

 

History

History
670 lines (517 loc) · 16.8 KB

Widget realization.md

File metadata and controls

670 lines (517 loc) · 16.8 KB

FROG logo

FROG Widget Realization

Normative realization boundary for widget rendering, visual resources, part-to-visual mapping, and host-facing realization support
FROG — Free Open Graphical Language

Contents

1. Overview

This document defines the normative realization boundary for FROG widgets.

Realization concerns how a published widget class is rendered and hosted visually.

This includes:

  • appearance tokens,
  • layout and sizing posture,
  • visual assets,
  • part-to-visual mapping,
  • host-side realization metadata.

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

Instead, this document defines what realization is allowed to do, what it is not allowed to do, and how it remains subordinate to published widget class law.

Realization is therefore the visual and host-facing embodiment layer of a widget, not the semantic source of truth for what the widget is.

2. Why This Document Exists

Graphical widgets need rendering and host integration, but rendering is not the same thing as object law.

Without a clear realization boundary, widget systems often drift into one of two failures:

  • the visual asset becomes the hidden owner of widget meaning,
  • one runtime's private toolkit mapping becomes the true widget definition.

FROG rejects both failures.

A widget may be rendered richly, skinned flexibly, and realized differently on different hosts, but its public object model must remain stable and inspectable independently of realization details.

This document therefore exists to preserve a disciplined layering:

  • class law defines the public surface,
  • behavior defines reaction,
  • realization defines embodiment,
  • runtime-private support defines implementation convenience only.

3. Scope

This document defines:

  • the realization boundary around widget classes,
  • the layering between abstract appearance, layout, visual resources, and host support,
  • how parts bind to visual assets,
  • how SVG participates in the realization corridor,
  • how realization stays subordinate to widget class law and widget behavior law.

This document does not define:

  • the full widget package serialization format,
  • the full class contract structure,
  • the full bounded behavior structure,
  • the private rendering internals of any one runtime family.

It also does not define the legal set of public properties, methods, events, or parts. It defines how those already-published surfaces may be visually and interactively embodied on a host.

4. What Realization Means in FROG

In FROG, realization means the host-facing visual and interactive embodiment of a widget class.

Realization answers questions such as:

  • how is the widget drawn,
  • how are its parts mapped to visual regions,
  • which visual assets are used,
  • how are appearance tokens resolved,
  • how does a host toolkit support focus, redraw, hit testing, and part-local interaction.

Realization does not answer:

  • which public properties exist,
  • which public methods exist,
  • which public events exist,
  • which public parts exist,
  • what the primary value law of the widget is.

Realization is therefore about embodiment, mapping, and support. It is not about defining public semantic law.

5. Ownership Boundary

The following distinctions are normative: 

widget class contract -> public object law
widget behavior       -> portable reaction law
widget realization    -> visual and host-facing embodiment
runtime-private code  -> internal realization support details

Accordingly:

  • realization MUST follow published class law,
  • realization MUST NOT invent undocumented public members,
  • realization MUST NOT replace bounded behavior law,
  • realization MUST NOT treat visual assets as semantic truth.

Likewise: 

published parts
    !=
toolkit-private visual fragments

appearance tokens
    !=
full semantic object law

host bridge
    !=
widget definition

This ownership boundary is what allows several runtimes to realize one widget class differently while still remaining aligned on the same published meaning.

6. Realization Layers

FROG realization is layered.

A well-formed realization posture distinguishes:

  • abstract appearance,
  • layout and sizing,
  • visual resources,
  • part-to-visual binding,
  • runtime-private host support.

This layered structure keeps semantic truth separate from the skin or toolkit.

The layers are related but not interchangeable. A runtime may merge them internally for efficiency, but a published realization posture must not collapse them into one opaque implementation artifact.

7. Abstract Appearance Layer

The abstract appearance layer defines portable appearance-facing properties and tokens without committing to one host toolkit or one concrete visual resource.

Examples:

  • text color,
  • background fill,
  • stroke color,
  • font family,
  • font size,
  • padding,
  • corner radius,
  • alignment.

These surfaces are part of the public or package-published object model where declared. They remain portable and inspectable.

The abstract appearance layer exists so that runtimes can preserve appearance intent even when they do not share one concrete rendering implementation.

8. Layout and Sizing Layer

The layout and sizing layer defines how the widget is spatially structured.

Examples:

  • minimum size,
  • preferred size,
  • resizable dimensions,
  • label placement,
  • button placement,
  • internal spacing.

Layout posture may influence realization, but layout posture does not create or remove public object law.

This layer may guide host windowing, part placement, scaling, and responsive adaptation, but it must remain subordinate to the already-published part structure and appearance surfaces.

9. Visual Resource Layer

The visual resource layer contains concrete assets used by realization.

Examples:

  • SVG files,
  • icon fragments,
  • vector templates,
  • named layers,
  • anchor sets.

These resources support rendering.

They do not replace the widget class contract.

A visual resource may help a runtime render a widget faithfully. It does not publish new portable properties, methods, events, parts, or behavior.

10. Part-to-Visual Binding

A widget realization may bind named widget parts to concrete visual regions or anchors.

This is the preferred mechanism for connecting:

  • public or package-published parts,
  • part-facing appearance tokens,
  • part-local visual updates,
  • part-local interaction hit regions.

For example, a numeric control may bind:

  • label to a text layer or text anchor,
  • value_display to a numeric text region,
  • increment_button to an up-arrow hit region,
  • decrement_button to a down-arrow hit region,
  • frame to an outline layer.

The existence and names of these parts come from widget class law, not from the visual asset.

Part-to-visual binding therefore maps published semantic parts onto realization regions. It does not authorize realization to invent the semantic part model retroactively.

11. SVG Integration

SVG may be used as a realization resource in FROG.

SVG MAY provide:

  • scalable skins,
  • decorative layers,
  • anchor regions,
  • template geometry,
  • part-binding hints.

SVG MUST NOT own:

  • the primary value semantics of the widget,
  • the legality of properties,
  • the legality of methods,
  • the legality of events,
  • the legality of parts,
  • the bounded behavior law of the widget.

SVG is therefore a realization asset, not a semantic widget definition language.

A runtime MAY:

  • render an SVG-backed realization faithfully,
  • bind published parts to SVG anchors,
  • ignore unsupported SVG-specific detail,
  • substitute a compatible native realization.

But it MUST preserve the published public widget surface independently of the SVG asset.

12. Runtime Host Bridges

Different runtime families may realize the same widget class through different host bridges.

Examples include:

  • a Python runtime using a Qt-based widget backend,
  • a Rust runtime using a retained-mode UI toolkit,
  • a C/C++ runtime using a native or embedded rendering backend.

These bridges may differ internally in:

  • event-loop integration,
  • focus handling,
  • redraw scheduling,
  • accessibility bridging,
  • rendering strategy.

Such variation is allowed.

What must remain stable is the published object surface and the portable meaning of the realized widget.

Host bridges therefore provide transport from published widget law to host embodiment. They are implementation bridges, not semantic authorities.

13. Interaction with Behavior

Realization and behavior are related but distinct.

Behavior may request:

  • a visual refresh,
  • a part-state update,
  • focus movement,
  • interaction suppression,
  • event emission after host interaction.

Realization provides the host-side embodiment needed for these effects to occur visually and interactively.

Realization does not define the portable behavior law by itself.

A runtime may internally interleave behavior processing and realization updates, but the published behavioral meaning must remain derivable from behavior and class-law surfaces, not from realization artifacts alone.

14. Interaction with Widget Class Law

Realization is downstream of widget class law.

This means:

  • published properties may influence realization,
  • published parts may bind to visual anchors,
  • published events may be emitted in response to host interaction,
  • published methods may trigger realized state changes.

But realization MUST NOT:

  • invent new portable public properties because a toolkit happens to support them,
  • rename public parts privately and thereby change source-level addressing meaning,
  • replace the published event surface with host-specific undocumented signals,
  • replace the primary value model with a visual-text-only convention.

In short, realization may embody published law, but it may not revise published law.

15. What Realization Must Not Do

The following are prohibited as normative realization doctrine:

  • treating SVG as the owner of widget semantics,
  • treating one runtime toolkit mapping as the widget definition itself,
  • placing the only true part structure inside the rendering layer,
  • creating hidden portable public members from host convenience,
  • silently altering public mutability posture through realization-only conventions.

The following are also prohibited:

  • deriving the public part model solely from one skin file,
  • using visual-layer aliases to silently replace published member identities,
  • treating host hit regions as if they published new portable parts automatically,
  • making conformance depend on one private rendering pipeline.

16. Publication Through .wfrog

Realization resources and realization metadata are typically published through .wfrog packages.

The package specification owns how that material is serialized.

This document instead constrains what realization publication is allowed to mean.

Typical package-published realization content may include:

  • resource declarations,
  • appearance token maps,
  • layout hints,
  • part-to-resource bindings,
  • host realization profiles.

Publication through .wfrog is therefore the normal packaging corridor for realization-facing material, but that material remains subordinate to class law and behavior doctrine.

17. Portability Across Runtimes

Portable realization in FROG does not mean pixel-identical rendering across all runtimes.

It means:

  • equivalent public object surfaces,
  • equivalent part structure,
  • equivalent interaction meaning,
  • equivalent bounded behavior meaning,
  • reasonable preservation of appearance intent where the host supports it.

Different runtimes may therefore realize the same widget differently while still remaining conformant.

Portability therefore means semantic stability plus reasonable appearance fidelity, not identical private toolkit behavior or identical raster output.

18. Status

This document defines the normative realization boundary for FROG widgets.

Its closure direction is:

  • explicit part-to-visual mapping,
  • portable appearance layers,
  • SVG as a resource rather than semantic truth,
  • multi-runtime realizability without semantic drift.

Its role in the widget corridor is to keep realization flexible and rich while preventing semantic ownership from leaking into skins, toolkit bridges, or runtime-private implementation details.

19. License

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