Skip to content

Readme.md

Latest commit

 

History

History
277 lines (251 loc) · 8.56 KB

Readme.md

File metadata and controls

277 lines (251 loc) · 8.56 KB

FROG logo

Widget Example Reference Notes

Implementation notes for the currently stabilized FROG widget examples
FROG - Free Open Graphical Language

Purpose

These notes describe the current repository-proven widget examples. They are not the normative widget class law. The class law remains under Libraries/Widgets/, the Default realization law remains under Libraries/Realizations/Default/, and the numbered examples remain executable proof slices.

Each page records the practical contract that must stay true while the examples evolve:

  • the .frog source owns diagram logic, front-panel instances, layout, binding, initial values, and instance-level visual customization;
  • the example .wfrog package owns realization references, Default SVG asset references, and host capability requirements;
  • the runtime consumes the .frog instance data, .wfrog package, Default SVG public parts, and native manifest when the slice is native-backed;
  • no accepted widget example may rely on a hardcoded HTML/CSS fallback or duplicated local SVG skin.

Current Stabilized Widgets

Widget family Example Reference note Default realization package Default SVG asset
Numeric 05_bounded_ui_accumulator Numeric.md Libraries/Realizations/Default/numeric.default.wfrog assets/numeric/templates/numeric_rectangular.svg
Boolean 06_boolean_value_roundtrip Boolean.md Libraries/Realizations/Default/boolean.default.wfrog assets/boolean/templates/boolean_rectangular.svg, boolean_circular.svg
String 07_string_value_roundtrip String.md Libraries/Realizations/Default/string.default.wfrog assets/string/templates/string_rectangular.svg
Enum 08_enum_value_roundtrip Enum.md Libraries/Realizations/Default/enum.default.wfrog assets/enum/templates/enum_rectangular_ring.svg
Path 09_path_value_roundtrip Path.md Libraries/Realizations/Default/path.default.wfrog assets/path/templates/path_rectangular_field.svg
Button 10_button_press_to_boolean Button.md Libraries/Realizations/Default/button.default.wfrog assets/button/templates/button_rectangular.svg

Post-Boundary Private Runtime Widget Notes

The following repository-visible widget notes document later specification-facing examples. They are validated through Graiphic private runtime slices and do not expand the current public reference runtime closure unless that boundary is explicitly promoted later.

Widget family Example Reference note Default realization package Default SVG asset
Tree 24_tree_node_selection_roundtrip Tree.md Libraries/Realizations/Default/tree.default.wfrog assets/tree/templates/tree_shell.svg + assets/tree/item_symbols/*.svg

Runtime Parity Snapshot

The stabilized widget examples are expected to run through the same reference-runtime family in every implemented language. The runtime may be written in C++, Python, or Rust, but it must consume the same source-owned front-panel instance data, the same .wfrog realization package, and the same native manifest truth when the slice is native-backed.

Example Widget family C++ Python Rust Execution posture
05 Numeric validated validated validated LLVM native kernel manifest + .frog/.wfrog UI
06 Boolean validated validated validated LLVM native kernel manifest + .frog/.wfrog UI
07 String validated validated validated LLVM native kernel manifest + .frog/.wfrog UI
08 Enum validated validated validated LLVM native kernel manifest + .frog/.wfrog UI
09 Path validated validated validated LLVM native kernel manifest + .frog/.wfrog UI
10 Button validated validated validated LLVM native kernel manifest + .frog/.wfrog UI
24 Tree validated private slice validated private slice validated private slice LLVM native kernel manifest + explicit frog.tree.records dataflow + .frog/.wfrog UI

Ownership Boundary

Concern Owner Validation expectation
Diagram algorithm .frog Derives to FIR, lowers, emits native kernel, and produces the expected runtime output.
Front-panel widget instances .frog Owns widget id, class, role, layout, binding, initial value, label/caption placement, and instance style.
Published widget realization .wfrog Points to the Default realization package and declares which SVG asset ids the runtime must resolve.
Visual geometry hooks Default SVG asset Exposes stable data-frog-part, data-frog-anchor, and data-frog-bind surfaces.
Execution bridge Runtime + native manifest The runtime loads a manifest-declared ABI artifact and does not become LLVM-only.
Visible UI host overlays Runtime May provide host input overlays, but must align them to published SVG parts and source-owned instance data.

Public Boundary

Widget examples in this directory remain framed by the public widget example boundary. The public evidence corridor is: 

.frog diagram + front-panel instances
  -> FIR
  -> lowering
  -> LLVM kernel + native manifest
  -> runtime C++ / Python / Rust
  -> .wfrog realization package
  -> Default SVG asset
  -> faithful visible UI

The public repository documents this ownership split and its repository-visible evidence. Graiphic internal acceptance recipes and manual review procedures are not published as part of these reference notes.