FacetDocs

Behavior

A set can say how it behaves: which state shows first, which events move it on, and what decides the way in each scenario. One build stores the set, its statechart, the binding of states to variants and its design axes, as a feature named after the set in lower case with dashes (Raga card is raga-card). The build's reply names it; every chart command takes that name.

The raga card above carries this behavior:

"behavior": {
  "axes": {"history": ["fresh", "practised"],
           "streak": {"values": ["short", "long"], "when": {"history": ["practised"]}}},
  "start": "Loading",
  "states": {
    "Loading": {"LOADED": "route"},
    "route": ["history == 'fresh' -> New", "streak == 'long' -> Learning", "Locked"],
    "New": {"START": "Learning"},
    "Learning": {"PAUSE": "Locked"},
    "Locked": {"UNLOCK": "Learning"}
  },
  "plays": {"Begin a new raga": ["LOADED", "START"]},
  "targets": {"START": "Start learning"}
}

States

  • A state named like a value of the set's variant property shows that variant (New, Learning, Locked).
  • A set with several variant properties names the one its states show: "property": "State" beside start. The other properties (Kind, Size) stay design dimensions; each state keeps the instance's values of them.
  • {"EVENT": "Target"} moves on when the event happens. A target may be "guard -> Target", a list of those (the first whose guard holds wins), or {"target", "guard", "assign"}.
  • A state written as a list moves on at once: route picks the next state by the scenario. It is never on screen, so it needs no variant.
  • note, nested states, initial and type (parallel, final) are written as in the full chart format.

Behaviors by name

The common ones ship, so a set need not write them: "behavior": "toggle".

NameMoves throughEvents
toggleoff, onTOGGLE
pressrest, pressedPRESS, RELEASE
disclosureclosed, openOPEN, CLOSE, TOGGLE, DISMISS (closes)
taskidle, busy, done, failedSTART, DONE, FAIL, RESET

Their states are roles. A set whose variant values carry those names (in any case: Off, On) needs nothing more; another says which value plays each role, and adds what is its own beside it: the layers events act on, plays, and states or moves of its own, which lie over the named ones.

"behavior": {"use": "toggle", "as": {"off": "Unchecked", "on": "Checked"},
             "targets": {"TOGGLE": "Box"},
             "states": {"Unchecked": {"DISABLE": "Disabled"}, "Disabled": {"ENABLE": "Unchecked"}}}

A role left without a value is refused, with the set's values to choose from.

Scenarios

axes name what varies between situations. Every combination is a scenario; guards read the axis values. An axis with when applies only where earlier axes take those values and keeps its first value elsewhere, so streak does not double the fresh scenarios.

$ facet chart raga-card
3 scenarios over history (fresh, practised) × streak (short, long): 3 to 4 configurations each

Views:
  New          reachable where history is fresh, streak is short
  Learning     reachable in every scenario
  Locked       reachable in every scenario

Coverage: 4/10 transitions over every scenario
  untested in 3 scenario(s): Learning --PAUSE--> Locked
  untested in 3 scenario(s): Locked --UNLOCK--> Learning

Play skeletons (shortest paths to what no play reaches):
  Covers Learning --PAUSE--> Locked: LOADED → START → PAUSE
  Covers Locked --UNLOCK--> Learning: LOADED → START → PAUSE → UNLOCK
  Reaches Locked: LOADED → START → PAUSE
  Covers Locked --UNLOCK--> Learning: LOADED → UNLOCK
  Covers Learning --PAUSE--> Locked: LOADED → UNLOCK → PAUSE
  Reaches Learning: LOADED → UNLOCK
  Covers Learning --PAUSE--> Locked: LOADED → PAUSE
  Covers Locked --UNLOCK--> Learning: LOADED → PAUSE → UNLOCK
  Reaches Locked: LOADED → PAUSE

facet chart says where each view is reachable by axis values, what is not covered, and the shortest event sequences to reach what no play reaches (--full lists every scenario). Its words:

WordMeans
scenarioone combination of axis values; an axis with when adds values only where it applies
configurationthe set of states active at once; a chart has a few per scenario
transitionone event moving one state to another, counted once per scenario where it can happen
coveragethe transitions the plays take, of all transitions
reachable in every scenariosome event sequence shows the view whatever the axis values
play skeletonthe shortest event sequence to a view or transition no play reaches; name it under plays to keep it

Plays and targets

plays name event sequences to replay on the canvas: facet plays run raga-card "Begin a new raga" runs one in every scenario and says where it ends. targets name the layer each event acts on, so replays click the right thing; they are optional, and events without one replay without a click.

Using an instance

facet act lists every instance on the page whose component has a statechart: the view it shows and the events it takes now, each with the layer it acts on. facet act NODE EVENT sends one event to one instance (its id or its layer name). Its chart moves from the view the instance shows, and the instance shows the view it reaches:

facet --doc f.facet act
# "Save" (25), save-button: shows Idle; takes PRESS (on "Label")
# "Wifi" (18), switch: shows Off; takes TOGGLE (on "Knob")
facet --doc f.facet act Wifi TOGGLE
# Wifi took TOGGLE: Off -> On; takes TOGGLE (on "Knob")
facet --doc f.facet act Save PRESS
# Save took PRESS: Idle -> Saving; takes DONE, FAIL
facet --doc f.facet act --at 260,69        # a press at a point of the page: the event whose target layer holds it

Each instance has its own place in the chart, variables included, kept while the document stays open: a chart that counts wrong codes locks the instance that had three, not its neighbour. An instance changed by hand goes on from the view it shows. An event the view does not take fails, and the message lists the ones it takes. In the app the Use tool (U) does the same with clicks: a click on a layer an event acts on sends that event. Each event is one undo step; --scenario k=v chooses the axis values the guards read.

facet act --follow prints every event an instance takes, from the command line or from clicks with the Use tool, as it happens: EVENT Save PRESS from=Idle to=Saving number=3. An author that wrote the screen as a stream reads these and answers with change lines, so the screen is used and rewritten in one loop; facet act --after 3 prints what came after event 3 and ends.

Looks

looks are design axes: {"Look": {"Light": "Kit/Light", "Dark": "Kit/Dark"}} shows each option in a mode of the kit's variables. Lattice views (facet lattice) cross them with the scenarios.

The full chart format, for what the compact one does not cover, is in Chart.

Documentation for Facet 0.3.228-g032727de