Skip to content

Validation.md

Latest commit

 

History

History
131 lines (100 loc) · 6.45 KB

Validation.md

File metadata and controls

131 lines (100 loc) · 6.45 KB

FROG logo

Default Realization Validation

Validation checklist for the published Default widget realization layer
FROG — Free Open Graphical Language

Purpose

This document defines the repository-visible validation posture for the Default widget realization layer. It is intentionally downstream from widget class law.

The goal is to keep the published widget layer coherent as a standard-facing surface rather than a loose set of unrelated documents. Validation therefore focuses on repository hygiene, publication alignment, manifest integrity, resource resolution, public-part consistency, and realization/class-law boundaries.

Validation Targets

Each published widget family should provide:

  • a widget class-law document under Libraries/Widgets/,
  • a Default realization document under Libraries/Realizations/Default/,
  • a machine-readable manifest *.default.wfrog,
  • resolvable SVG template or subobject resources where the manifest declares them,
  • part bindings that refer to public widget parts,
  • target classes that appear in the corresponding widget class-law document,
  • role posture that distinguishes control, indicator, command, support, layout, container, or structured families,
  • clear realization-private boundaries for host-native handles, renderer caches, virtualized rows/nodes/items, canvas surfaces, GPU surfaces, and IDE-private editing structures.

Machine-Checkable Expectations

  • All manifests must be valid JSON.
  • Each manifest must include format, kind, package, targets, resources, and validation_expectations.
  • Each manifest should include publication_role, version_governance_ref, ownership_boundary, exports, realizations, part_bindings, and host_hints.
  • Each declared target class must be listed in the corresponding validator family definition and must appear in the owning widget class-law document.
  • Each target must declare an explicit role.
  • Generic target roles such as widget should not be used in published Default manifests.
  • Each declared resource path must resolve relative to the manifest file.
  • Resource paths must not escape the Libraries/Realizations/Default/ directory.
  • Each exported resource identifier should correspond to a declared resource.
  • Each composition slot or nested slot should reference a declared resource.
  • Each part binding should refer to a supported public part.
  • Each event binding source part should refer to a supported public part.
  • Each resource target_part or target_parts entry should refer to a supported public part.
  • Each declared supported part should appear in the corresponding widget class-law document.
  • SVG resources should expose declared public parts through data-frog-part markers when applicable.
  • SVG shell resources may expose composition slots through data-frog-slot markers.
  • Any visible border, frame, selection outline, cell outline, scrollbar track, or equivalent stroke-like surface should preserve one uniform published thickness after resize; SVG-backed resources should use non-scaling strokes or an equivalent realization strategy when a single width property controls the surface.
  • Bordered fill surfaces should not leave unintended inner gaps. If a value face, text region, button face, state face, or equivalent part is meant to touch its surrounding border, the SVG geometry should meet the stroke inner edge or extend under a transparent / stroke-only frame.
  • Documentation files should not contain literal escaped newline artifacts in rendered lists.

Composite Widget Expectations

Composite widgets may use shell resources, subobject assets, slots, nested slots, layer-order records, property bindings, method bindings, event bindings, state maps, and host-native replacement hints.

The current complex families that should remain especially protected are:

  • frog.widgets.waveform_chart
  • frog.widgets.listbox_control and frog.widgets.listbox_indicator
  • frog.widgets.tab_control and frog.widgets.tab_indicator
  • frog.widgets.tree_control and frog.widgets.tree_indicator
  • frog.widgets.table_control and frog.widgets.table_indicator

For those families, validation should pay particular attention to public parts, SVG marker consistency, resource references, method/event surfaces, virtualized-host boundaries, and host-native replacement rules.

Reference Validator

The non-normative reference validator lives under: 

Implementations/Reference/WidgetValidator/validate_widget_layer.py

Run it from the repository root: 

python Implementations/Reference/WidgetValidator/validate_widget_layer.py

That validator is a repository-quality tool. It does not define widget semantics, realization semantics, FROG source law, FIR law, lowering law, runtime law, or host rendering law.

Expected Validation Boundary

The validator may reject repository hygiene errors such as missing manifests, invalid JSON, missing required keys, unresolved resources, class mismatches, invalid part references, resource references that escape the Default directory, or malformed manifest shape.

The validator may warn about weaker publication posture such as missing optional descriptive keys, incomplete SVG markers, generic roles, or abstract parts not represented directly by SVG resources.

The validator must not decide whether a runtime implementation is visually attractive, performant, or complete. It only protects the repository-visible contract between widget class law, Default realization manifests, resources, and documentation.