Skip to content

Readme.md

Latest commit

 

History

History
402 lines (312 loc) · 12.7 KB

Readme.md

File metadata and controls

402 lines (312 loc) · 12.7 KB

FROG logo

FROG Standard Realizations

Normative baseline for official realization families of intrinsic standardized widget classes
FROG — Free Open Graphical Language

Contents

1. Overview

This directory defines the official realization families for the intrinsic standardized widget classes of FROG.

A realization family specifies how already-published widget classes may be embodied visually and interactively while remaining subordinate to class law, bounded behavior law, and the source-level widget model.

A realization family is not the owner of widget semantics. It is the official publication surface for:

  • state-sensitive visual embodiment,
  • part-to-realization correspondence,
  • placement posture for dynamically rendered public parts,
  • recommended resource organization,
  • host-facing realization expectations.

2. Why this Directory Exists

Once standard widget classes exist, the next architectural need is to define how an official realization family may embody them without collapsing semantics into skins, SVG files, or one runtime-private toolkit mapping.

Without a realization layer:

  • the standard widget baseline remains too abstract for serious front-panel publication,
  • each runtime is tempted to invent its own de facto visual standard,
  • SVG and host assets drift toward semantic ownership,
  • state-specific skins become ad hoc rather than structured,
  • dynamic text-bearing parts risk being treated as asset-only content instead of realization-bound surfaces.

This directory exists to prevent that drift.

3. Scope

This directory defines:

  • official realization families for standard widgets,
  • their realization-side state posture,
  • their part-to-realization posture,
  • their resource-organization posture,
  • their host-facing realization expectations,
  • their fallback posture when resources or host features are unavailable.

This directory does not define:

  • widget class identity,
  • widget properties, methods, events, or parts as public law,
  • the generic realization doctrine of the language,
  • the generic .wfrog package format,
  • one mandatory toolkit-specific implementation.

4. Architectural Position

The standard realization layer occupies the following position: 

Libraries/Widgets/      -> intrinsic standardized class law baseline
Libraries/Realizations/ -> official realization families for those classes
Expression/             -> source model and generic realization boundary
.wfrog publication      -> machine-readable publication of realization artifacts
Implementations/        -> runtime and host execution of realization families

This means:

  • class identity is upstream from realization,
  • realization is upstream from machine-readable realization publication,
  • machine-readable realization publication is upstream from host-private rendering details,
  • runtime-private implementation remains downstream from published realization posture.

5. Ownership Boundary

The following ownership boundary is normative:

  • Libraries/Widgets/ owns which standard classes exist and what their public surfaces mean.
  • Libraries/Realizations/ owns official realization-family posture for those classes.
  • Expression/Widget realization.md owns the generic realization doctrine.
  • Expression/Widget package (.wfrog).md owns the widget-oriented publication format.
  • SVG and other visual assets remain realization resources, not semantic truth.

Therefore:

  • a realization family MUST NOT invent public widget semantics,
  • a realization family MUST NOT redefine class identity,
  • a realization family MAY define visual states, state-to-resource mappings, part bindings, anchors, and placement surfaces,
  • a runtime MAY realize the same family differently internally while preserving its published posture.

6. What a Standard Realization Family Is

A standard realization family is an official published realization posture associated with one or more standard widget classes.

A realization family SHOULD define:

  • family identity,
  • target widget classes,
  • state inventory,
  • part-to-realization mapping posture,
  • resource naming posture,
  • host-facing realization expectations,
  • fallback posture when a resource or host feature is unavailable.

A realization family MAY also define:

  • structural bindings between public parts and realization-side surfaces,
  • anchor or text-region publication for host-rendered dynamic parts,
  • state-sensitive resource families for specific parts.

A realization family is allowed to have multiple state-specific assets for the same widget or widget part. That does not make the asset the source of semantic truth. It only makes the realization explicit and inspectable.

7. Current Standard Family

The first official realization family published here is:

  • Default/ — the default standard realization family for the intrinsic widget baseline.

This family exists to provide:

  • a first coherent official embodiment of the standard widget baseline,
  • a stable reference target for examples,
  • a concrete realization posture that runtimes may interpret faithfully or approximate compatibly.

The Default family also serves as the first end-to-end example of how realization-side states, structural part bindings, and dynamic placement surfaces can be published without redefining widget semantics.

8. Relationship with Standard Widget Classes

Every realization family document in this directory is downstream from one or more standard widget class documents in Libraries/Widgets/.

This means:

  • the widget class defines which public parts and public surfaces exist,
  • the realization family defines how those parts and surfaces are embodied visually,
  • the runtime interprets the resulting realization posture without becoming its semantic owner.

The realization family may publish how a label is placed, clipped, styled by default, or mapped to a visual surface. It does not become the semantic owner of the label text or of other dynamic widget data.

9. Relationship with .wfrog and Assets

This directory defines the normative documentation posture of realization families.

Machine-readable publication may later be carried through:

  • .wfrog realization libraries,
  • resource manifests,
  • SVG and other visual assets,
  • part-binding maps,
  • state maps,
  • anchor maps or text-region maps.

The governing rule remains: 

published class law
    !=
published realization family
    !=
machine-readable realization package
    !=
visual asset
    !=
runtime-private rendering implementation

This separation is especially important for dynamic text-bearing parts. A visual asset may provide decoration, background, or anchor geometry, but it must not become the only semantic owner of live user-facing text.

10. State, Binding, and Placement Posture

A realization family MAY define:

  • widget-level states such as normal, disabled, focused, or pressed,
  • part-level states such as increment_button.pressed,
  • resource maps that assign state-sensitive assets to widget parts,
  • structural bindings that associate public parts with realization surfaces,
  • anchors, text regions, or equivalent placement surfaces for dynamically rendered public parts,
  • fallback rules when a specialized resource or placement surface is unavailable.

This directory is therefore the correct place for:

  • multiple SVG skins or state-specific SVG fragments,
  • part-level visual mappings,
  • anchor publication for dynamic labels,
  • inspectable fallback posture.

It is not the correct place to redefine widget law.

A useful rule of thumb is:

  • state maps answer which resource embodies a part in a given realization state,
  • part bindings answer where a public part lives in the realization structure,
  • anchors or text regions answer where a host should place dynamically rendered content.

11. Portability

A standard realization family is portable if:

  • its target class law remains preserved,
  • its public parts remain recognizable,
  • its published realization-state posture remains preserved,
  • its structural bindings remain interpretable,
  • its host-specific substitutions do not change the public interaction meaning.

Pixel-identical rendering is not required. Semantic and realization-structure compatibility is required.

This portability requirement is what allows one official realization family to be interpreted across Python, Rust, and C/C++ runtime families without turning one implementation into the real definition of the UI system.

12. Status

This directory defines the official realization-family layer for the intrinsic standard widget baseline.

Its closure direction is:

  • explicit official realization families,
  • clean separation between class law and realization resources,
  • state-structured and binding-structured publication,
  • inspectable dynamic-placement posture for dynamic public parts,
  • multi-runtime realizability without semantic drift.

13. Summary

This directory defines how official realization families may embody the intrinsic standard widget classes of FROG.

In short:

  • Libraries/Widgets/ defines what the widget is,
  • Libraries/Realizations/ defines how an official standard family embodies it,
  • .wfrog packages and assets may later materialize that family machine-readably,
  • runtimes interpret the family without becoming the owner of its meaning.

The central architectural rule is simple: realization may define embodiment, mapping, placement, and fallback, but semantic widget meaning remains upstream from realization and cannot be delegated to assets or to one runtime implementation.