Skip to content

Button default realization.wfrog.md

Latest commit

 

History

History
427 lines (369 loc) · 13.5 KB

Button default realization.wfrog.md

File metadata and controls

427 lines (369 loc) · 13.5 KB

FROG logo

Example — Default Button Realization Package

Illustrative machine-readable .wfrog publication example for the default realization of frog.widgets.button
FROG — Free Open Graphical Language

Contents

1. Overview

This document provides an illustrative machine-readable .wfrog publication example for the default realization of frog.widgets.button.

It is intentionally small, but already complete enough to demonstrate:

  • package identity,
  • target-class declaration,
  • realization declaration,
  • state inventory,
  • structural part bindings,
  • resource publication,
  • state-to-resource mapping,
  • anchor publication for dynamic text placement,
  • fallback posture.

This example is not presented as the only possible encoding shape of all future realization packages. It is presented as the first coherent reference pattern for the default family.

It is also intentionally conservative. It demonstrates the shared button realization corridor first, before adding variant-specific or skin-specific specialization layers.

2. Purpose of this Example

This example is not the generic .wfrog specification. It is a concrete publication example built on top of the realization-package posture already defined elsewhere.

Its purpose is to show how the default official realization family may publish one standard widget embodiment in a machine-readable way without collapsing class law, realization publication, resources, and runtime implementation into the same layer.

It also serves a narrower purpose: to prove that the default button corridor can already be published in a way that keeps dynamic public text portable and inspectable.

Because the button is the clearest first proof case for dynamic semantic text versus realization-owned placement, it is the correct place to establish the publication pattern that later numeric, string, boolean, and chart examples should follow.

3. Architectural Focus

This example preserves the architectural split between:

  • the semantic button label owned by the widget class through label.text,
  • the realization-side placement surface used to display that text,
  • the state-sensitive visual resources used for the button face,
  • the runtime-side responsibility for rendering live text into the published placement surface.

That split is the most important rule demonstrated by this example.

The button face is treated as a state-sensitive visual surface. The button label is treated as a dynamic semantic public part whose placement is realization-owned but whose content remains class-owned.

This means the example is designed to prove three things simultaneously:

  • state_maps are the preferred mechanism for state-sensitive visual embodiment,
  • part_bindings are the preferred mechanism for stable structural correspondence,
  • anchors are the preferred mechanism for dynamic host-rendered button text placement.

The example is also family-generic rather than variant-specific. It does not attempt to prove a specialized flat, raised, rounded, or skin-specific button posture yet. That later specialization remains possible, but it should be layered on top of the base publication pattern shown here rather than replacing it.

4. Example JSON

{
  "wfrog_version": "1",
  "package_kind": "widget_realization_library",
  "package": {
    "id": "frog.realizations.default.button",
    "name": "FROG Default Button Realization",
    "namespace": "frog.realizations.default",
    "publisher": "FROG",
    "summary": "Default official realization for frog.widgets.button"
  },
  "imports": [],
  "exports": {
    "realizations": [
      "frog.realizations.default.button"
    ],
    "resources": [
      "button.face.normal.svg",
      "button.face.disabled.svg",
      "button.face.focused.svg",
      "button.face.pressed.svg",
      "button.label.anchor_map"
    ],
    "anchors": [
      "button.label.center"
    ]
  },
  "targets": [
    {
      "class_id": "frog.widgets.button"
    }
  ],
  "realizations": [
    {
      "id": "frog.realizations.default.button",
      "family": "default",
      "target_class": "frog.widgets.button",
      "parts": [
        "root",
        "face",
        "label",
        "frame"
      ],
      "states": [
        "normal",
        "disabled",
        "focused",
        "pressed"
      ],
      "part_bindings": [
        {
          "target_class": "frog.widgets.button",
          "part": "face",
          "binding_kind": "resource_layer",
          "binding_target": "face"
        },
        {
          "target_class": "frog.widgets.button",
          "part": "label",
          "binding_kind": "anchor",
          "binding_target": "button.label.center",
          "placement_role": "text_anchor",
          "fallback": "host_centered_text_region"
        },
        {
          "target_class": "frog.widgets.button",
          "part": "frame",
          "binding_kind": "resource_layer",
          "binding_target": "frame"
        }
      ],
      "state_maps": [
        {
          "target_class": "frog.widgets.button",
          "target_part": "face",
          "state": "normal",
          "resource_refs": [
            "button.face.normal.svg"
          ]
        },
        {
          "target_class": "frog.widgets.button",
          "target_part": "face",
          "state": "disabled",
          "resource_refs": [
            "button.face.disabled.svg"
          ],
          "fallback": "normal"
        },
        {
          "target_class": "frog.widgets.button",
          "target_part": "face",
          "state": "focused",
          "resource_refs": [
            "button.face.focused.svg"
          ],
          "fallback": "normal"
        },
        {
          "target_class": "frog.widgets.button",
          "target_part": "face",
          "state": "pressed",
          "resource_refs": [
            "button.face.pressed.svg"
          ],
          "fallback": "normal"
        }
      ],
      "fallbacks": {
        "focused": "normal",
        "pressed": "normal",
        "disabled": "normal"
      },
      "host_hints": {
        "supports_host_focus_ring": true,
        "supports_host_pressed_feedback": true,
        "preferred_scaling": "uniform"
      }
    }
  ],
  "resources": [
    {
      "id": "button.face.normal.svg",
      "kind": "svg",
      "path": "./assets/button/face/normal.svg",
      "target_class": "frog.widgets.button",
      "target_part": "face",
      "target_state": "normal"
    },
    {
      "id": "button.face.disabled.svg",
      "kind": "svg",
      "path": "./assets/button/face/disabled.svg",
      "target_class": "frog.widgets.button",
      "target_part": "face",
      "target_state": "disabled"
    },
    {
      "id": "button.face.focused.svg",
      "kind": "svg",
      "path": "./assets/button/face/focused.svg",
      "target_class": "frog.widgets.button",
      "target_part": "face",
      "target_state": "focused"
    },
    {
      "id": "button.face.pressed.svg",
      "kind": "svg",
      "path": "./assets/button/face/pressed.svg",
      "target_class": "frog.widgets.button",
      "target_part": "face",
      "target_state": "pressed"
    },
    {
      "id": "button.label.anchor_map",
      "kind": "anchor_map",
      "path": "./assets/button/anchors/label.json",
      "target_class": "frog.widgets.button",
      "target_part": "label",
      "role": "text_anchor"
    }
  ],
  "anchors": [
    {
      "id": "button.label.center",
      "target_class": "frog.widgets.button",
      "target_part": "label",
      "source_resource": "button.label.anchor_map",
      "anchor_kind": "text_anchor",
      "horizontal_alignment": "center",
      "vertical_alignment": "center",
      "padding": {
        "left": 10,
        "right": 10,
        "top": 6,
        "bottom": 6
      }
    }
  ]
}

5. Reading Notes

This example shows a clean four-layer split:

  • the widget class already exists in Libraries/Widgets/Button.md,
  • the default realization family already exists in Libraries/Realizations/Default/Button.md,
  • this package publishes a machine-readable realization of that family,
  • the assets remain realization resources rather than semantic truth.

The example also shows that:

  • face is the main state-driven visual part and therefore uses state_maps,
  • label is not published as baked final text inside state-specific SVG assets,
  • label is structurally bound to a published anchor so that the runtime can render live label.text,
  • pressed and focused may fall back to normal,
  • host hints remain hints rather than semantic law.

The example intentionally keeps frame in the published part model even though no dedicated frame-specific resource is listed here. That is acceptable because the example is focused on the minimum button publication corridor rather than on demonstrating every optional visual layer at once.

In other words:

  • the published part model may be broader than the minimal demonstrated resource set,
  • the example still remains coherent because the main demonstrated split concerns face and label,
  • future examples may extend the same corridor with explicit frame resources or frame-specific state maps.

The example also intentionally does not publish a dedicated variants array or a dedicated skin_id specialization layer. That omission is deliberate:

  • the current goal is to prove the shared default button publication corridor first,
  • variant-aware and skin-aware specialization can be layered later without changing the architectural rule already demonstrated here,
  • the base example therefore stays small enough to remain the canonical first proof case.

6. Why This Example Matters

This distinction is important because the standard button class defines label.text as a portable semantic surface. The realization may define where that text is placed, clipped, aligned, or decorated, but it does not become the semantic owner of the label content itself.

Without this split, a runtime could easily drift into one of two broken postures:

  • treating SVG files as the hidden owner of visible button text,
  • treating runtime-private placement rules as the only real realization contract.

This example avoids both failures by making the following inspectable at publication time:

  • the state-sensitive visual resources for the button face,
  • the structural binding of the semantic label part,
  • the explicit anchor used for host-rendered label placement,
  • the fallback posture used when specialized resources or placement surfaces are unavailable.

That is why this example is the first normative proof case for the default realization example corridor. It is small, but it already demonstrates the central architectural rule that later widget families must preserve.

It also establishes the correct extension direction: future variant-specific or skin-specific button examples must specialize this base corridor rather than replacing it with a different implicit architecture.

7. Summary

This example provides a complete first machine-readable publication model for the default realization of frog.widgets.button using:

  • state-sensitive visual resources for face,
  • a published anchor map for label,
  • explicit structural bindings,
  • inspectable fallback posture.

It is suitable as a reference pattern for other widget realization packages in the same family, especially when a realization must preserve the distinction between public semantic text and realization-side visual placement.

The next most coherent file to handle after this one is:

  • Libraries/Realizations/Default/Examples/Button package and assets example.md

That file should now close the concrete side of the same proof corridor by aligning the example prose above with a simulated asset tree, concrete resource organization, and placement-support files.