La vue

view.ocml décrit ce qu’affiche un widget PlayerVox OverCrow : un arbre d’éléments, lié à l’état du widget par des expressions {…}. Il ressemble à du HTML ou à du JSX, mais ce n’est ni l’un ni l’autre : le jeu d’éléments est fermé, il n’y a pas de DOM et la vue ne contient aucun script. OverCrow met en page et dessine l’arbre lui-même.

<box class="checklist">
  <text class="title">{t("title")}</text>
  <list class="items" item-height="32">
    <for each={state.items} as="item" key={item.id}>
      <box class="row">
        <checkbox label={item.text} checked={item.done} on:change={setDone(item.id, event.value)}/>
        <text class={item.done ? "text done" : "text"}>{item.text}</text>
        <button class="remove" label={t("remove")} on:activate={remove(item.id)}>
          <icon name="x"/>
        </button>
      </box>
    </for>
  </list>
  <text class="summary">{t("remaining", { count: remaining(state.items) })}</text>
</box>

C’est le template de liste de tâches : un titre, une list défilante qui répète une ligne par entrée, et un résumé. La logique exporte setDone, remove et remaining ; t lit les messages de locales/.

La vue est compilée quand vous empaquetez le widget : overcrow-widget check signale chaque erreur avec sa ligne et sa colonne. Un élément, un attribut ou un événement inconnu est une erreur, jamais ignorée. Le fichier source lui-même n’est pas livré.

Balisage

• Le fichier est en UTF-8, sans marque d’ordre des octets.
• Le document est une liste de nœuds de premier niveau : des déclarations <component> et les enfants de la racine du widget, qui est une box.
• Les éléments s’écrivent en minuscules : <name …>…</name> ou <name …/>.
• La valeur d’un attribut est un texte entre guillemets ("…" ou '…'), une expression ({…}), ou rien, ce qui vaut true : <button submit>. Les attributs sont séparés par des blancs et ne se répètent jamais.
• Les commentaires s’écrivent <!-- … -->, sans -- à l’intérieur.
• DOCTYPE, instructions de traitement, sections CDATA et espaces de noms sont refusés.

Les entités sont & < > " ' { }  , ainsi que &#…; ou &#x…; pour tout caractère qui n’est pas un caractère de contrôle. Un { ou un } littéral dans une valeur entre guillemets, comme un } isolé dans du texte, est refusé : écrivez { et }.

Éléments

Chaque élément a un contenu fixe, un jeu d’attributs et les événements qu’il peut envoyer. Les conteneurs (box, scroll, list, form, popover, button) contiennent d’autres éléments ; text contient du texte et des enfants en ligne ; les autres sont des feuilles que PlayerVox OverCrow dessine : icon, image, toggle, slider, field, chart, gauge…

Éléments et attributs donne les attributs et les événements de chacun.

Texte

Le texte n’est admis que dans text, span, badge et option. Un text contient soit du texte, soit des enfants en ligne (span, icon, image), jamais les deux : pour styler un seul mot, placez chaque segment dans un span.

      <text class={row.valueClass} label={row.name} tooltip={row.hint}><span>{row.value}</span><if test={row.unit != ""}><span class="unit">{row.unit}</span></if></text>

Les blancs suivent la règle de JSX :

• les tabulations deviennent des espaces ;
• un saut de ligne entre deux mots devient une espace ;
• un saut de ligne accolé à une balise ou à une expression disparaît avec son indentation ;
• une suite de blancs accolée à une balise est supprimée ; entre deux expressions sur la même ligne, elle est conservée.

Un saut de ligne avant une expression supprime donc l’espace qui la précède : écrivez you have {state.count} messages sur une seule ligne pour garder les deux espaces, ou écrivez   là où il vous faut une espace que la règle supprimerait.

Attributs

Une valeur entre guillemets est convertie dans le type de l’attribut et vérifiée à la compilation de la vue :

attr={expression}, en revanche, lie l’attribut à une expression ; PlayerVox OverCrow vérifie chaque valeur qu’envoie le widget. Les valeurs qui n’existent qu’à l’exécution du widget, comme une image fournie par un service, doivent être liées.

Cinq attributs existent sur tous les éléments :

class est le point d’accroche du style. label est le nom accessible de l’élément : donnez-en un à chaque contrôle dont le contenu est une icône.

Nommer un élément : ref

ref="name" donne un nom à un élément. Ce nom sert à deux choses : draw(name, commands) dessine dans le canvas de ce nom, et un popover se place contre l’élément que nomme son anchor.

<box ref="panel" class="countdown" on:contextmenu={openMenu}>

<popover anchor="panel" placement="pointer" open={state.menu} on:dismiss={closeMenu}>
  <button class="menu-row" on:activate={resetRounds}>
    <text class="menu-text">{t("reset-rounds")}</text>
  </button>
</popover>

Un ref s’écrit toujours entre guillemets et il est unique dans la vue. Il est refusé dans un for ou dans un composant, où il nommerait plusieurs éléments.

Événements

on:event={handler} demande à PlayerVox OverCrow d’envoyer à la logique un événement de l’élément. Sans cela, le widget ignore tout de l’événement : OverCrow ne lui signale ni les mouvements du pointeur ni les appuis de touches qu’il n’a pas demandés.

Un gestionnaire s’écrit de deux façons :

• le nom d’une fonction exportée par la logique, appelée avec le détail de l’événement : on:activate={increment} ;
• un appel, avec les arguments de votre choix ; event y désigne le détail de l’événement : on:change={setDone(item.id, event.value)}.

        <checkbox label={item.text} checked={item.done} on:change={setDone(item.id, event.value)}/>
        <text class={item.done ? "text done" : "text"}>{item.text}</text>
        <button class="remove" label={t("remove")} on:activate={remove(item.id)}>
          <icon name="x"/>
        </button>

Les événements sont activate, contextmenu, wheel, keydown, input, change, submit, focus, blur, reachend, stick et dismiss ; événements décrit chacun d’eux et le détail qu’il transporte, et chaque élément liste ceux qu’il envoie. Certains sont des actions de l’utilisateur, pendant lesquelles un widget peut appeler un service protégé ; voir les appels qui demandent une action de l’utilisateur. Les widgets ne reçoivent d’entrées qu’en mode interactif de PlayerVox OverCrow : en mode passif, les clics les traversent et atteignent le jeu.

Conditions, boucles et composants

if, else-if, else

        <if test={state.stopwatch.running}>
          <icon name="pause"/>
        </if>
        <else>
          <icon name="play"/>
        </else>

else-if et else suivent directement un if : seuls des blancs et des commentaires peuvent les en séparer.

for

for répète ses enfants pour chaque entrée d’une liste. each, as et key sont tous obligatoires, et la clé doit être unique parmi les entrées répétées : c’est grâce à elle que PlayerVox OverCrow sait quelle ligne a bougé, est apparue ou a disparu.

      <for each={state.results} as="item" key={item.slug}>
        <button class="result" label={item.name} on:activate={select(item.slug)}>
          <text class="result-name">{item.name}</text>
          <icon class="result-arrow" name="chevron-right"/>
        </button>
      </for>

Pour une longue liste, placez le for dans un élément list : PlayerVox OverCrow ne met en page et ne dessine que les lignes visibles.

Composants

Un composant est un morceau de vue doté d’un nom et de propriétés déclarées, à écrire une fois et à utiliser plusieurs fois. Il est local à la vue.

<component name="stat" props="name value">
  <box class="stat">
    <text class="stat-name">{name}</text>
    <text class="stat-value">{value}</text>
  </box>
</component>

  <stat name={t("state")} value={stateText(state.running, state.remainingMs)}/>

• Les composants se déclarent au premier niveau, une seule fois chacun, sous un nom qui n’est pas celui d’un élément.
• Le corps ne voit que ses propres propriétés, pas les noms visibles là où le composant est utilisé. Passez-lui ce dont il a besoin.
• Une utilisation ne passe que des propriétés déclarées. Une propriété entre guillemets est un texte ; liez-la (value={5}) pour tout autre type.
• Un corps peut contenir un seul <slot/>, où vont les enfants de chaque utilisation.
• Un composant ne peut pas se contenir lui-même, et une utilisation n’accepte pas de gestionnaires on: : placez-les sur des éléments du corps.

if, for et les composants sont transparents pour les règles de contenu : leurs enfants doivent convenir à l’élément qui les entoure.

Expressions

Les expressions forment un sous-ensemble de JavaScript, réduit et strict :

• les littéraux : nombres (0, 12, 1.5), chaînes, true, false, null, littéraux de tableau et d’objet ;
• les noms de la portée et leurs membres : a.b, a?.b, a[i], a?.[i] ;
• les opérateurs : !, - et + unaires, * / %, + -, < <= > >=, == != === !==, &&, ||, ??, et a ? b : c. ?? ne se combine pas avec && ou || sans parenthèses ;
• les appels de fonctions exportées par la logique, par leur nom seul : remaining(state.items). t(key, params) en fait partie.

Les noms de la portée sont state, les noms as des for englobants, les propriétés du composant englobant, et event dans un gestionnaire. Un nom ne peut pas en masquer un autre.

Il n’y a ni affectation, ni fonction fléchée ou littérale, ni new, ni this, ni littéral de gabarit, ni expression régulière, ni appel de méthode, ni globale : tout ce qui dépasse un calcul simple a sa place dans une fonction de la logique. C’est ce qui permet de vérifier la vue : à l’empaquetage du widget, chaque expression est compilée en une fonction de logic.js, et la vue elle-même ne contient aucun code.

        <text class={item.done ? "text done" : "text"}>{item.text}</text>

Les mots réservés de JavaScript, constructor, prototype, eval, undefined, globalThis, overcrow et tout nom qui commence par __ sont refusés.

Quand la vue est incorrecte

Chaque problème est un diagnostic de overcrow-widget check, doté d’un code stable :