@ham2k/extension-sdk 0.5.0 → 0.5.2

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.5.0
+// @ham2k/extension-sdk 0.5.2
 /** Experimental v1 scene contract. All coordinates are in the scene's viewBox. */
 export interface SvgScene {
 	version: 1;

package/dist/templateContext.js

@@ -60,6 +60,7 @@ function qsoValues(qso) {
   const their = qso.their ?? {};
   const our = qso.our ?? {};
   const startMillis = Number(qso.startAtMillis ?? 0);
+  const serialSent = refField(qso.refs, "ourSerial");
   return {
     call: their.call ?? "",
     their,
@@ -71,12 +72,31 @@ function qsoValues(qso) {
     // sides — `qso.our.sent` is what WE sent, i.e. the report they received.
     rstSent: our.sent ?? "",
     rstRcvd: their.sent ?? "",
+    // Unpadded, as stored: `001` or `1` is the operator's call, not the
+    // contest's, so it is left to the `pad` filter.
+    serialSent,
+    serialRcvd: refField(qso.refs, "theirSerial"),
+    // The short forms are the SENT side: a CW message is what we send, and
+    // that is where these get typed.
+    rst: our.sent ?? "",
+    serial: serialSent,
     notes: qso.notes ?? "",
     refs: qso.refs ?? [],
     ...startMillis > 0 ? dateValues(startMillis) : { date: "", dateCompact: "", time: "", at: "" },
     startAtMillis: startMillis
   };
 }
+function refField(refs, field) {
+  if (!Array.isArray(refs)) return "";
+  for (const ref of refs) {
+    if (ref === null || typeof ref !== "object" || Array.isArray(ref)) continue;
+    const value = ref[field];
+    if (typeof value !== "string" && typeof value !== "number") continue;
+    const text = String(value).trim();
+    if (text !== "") return text;
+  }
+  return "";
+}
 function logValues(values) {
   return {
     station: values.station ?? "",

package/dist/templates.js

@@ -30,7 +30,29 @@ function registerFilters(liquid2) {
     (value) => String(value ?? "").replace(/[^A-Za-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")
   );
   liquid2.registerFilter("alnum", (value) => String(value ?? "").replace(/[^A-Za-z0-9]/g, ""));
+  liquid2.registerFilter("pad", (value, width = 3) => {
+    const text = String(value ?? "").trim();
+    return text === "" ? "" : text.padStart(Number(width) || 0, "0");
+  });
+  liquid2.registerFilter("cut", (value, digits = "09") => {
+    const chosen = String(digits ?? "");
+    return String(value ?? "").replace(/[0159]/g, (digit) => chosen.includes(digit) ? CUT_NUMBERS[digit] : digit);
+  });
+  liquid2.registerFilter(
+    "refLabels",
+    (value) => (Array.isArray(value) ? value : []).flatMap((ref) => {
+      const label = [ref?.shortLabel, ref?.label, ref?.ref].map((text) => typeof text === "string" || typeof text === "number" ? String(text).trim() : "").find((text) => text !== "");
+      return label === void 0 ? [] : [label];
+    })
+  );
+  liquid2.registerFilter("sentence", (value, separator = ", ", final = " & ") => {
+    if (!Array.isArray(value)) return String(value ?? "");
+    const items = value.map((item) => String(item ?? "").trim()).filter((item) => item !== "");
+    if (items.length < 2) return items.join("");
+    return `${items.slice(0, -1).join(String(separator))}${String(final)}${items[items.length - 1]}`;
+  });
 }
+const CUT_NUMBERS = { "0": "T", "1": "A", "5": "E", "9": "N" };
 class TemplateError extends Error {
   constructor(message, options) {
     super(message);

package/docs/templates.md

@@ -34,7 +34,9 @@ about 2 µs each.
 the namespaces are deliberately polo's. The syntax around them does not:
 `{{#if}}` is `{% if %}{% endif %}`, `{{#each}}` is `{% for %}{% endfor %}`,
 `{{> Partial}}` has no equivalent, and helpers are filters
-(`{{ dash x }}` → `{{ x | dash }}`).
+(`{{ dash x }}` → `{{ x | dash }}`). polo's
+`{{#join op.refs separator=", " final=" & "}}{{or shortLabel label key}}{{/join}}`
+is `{{ op.refs | refLabels | sentence }}`.
 
 ## What a template can name
 
@@ -74,12 +76,22 @@ that contact's length.
 
 ### `qso` — one contact
 `call`, `their`, `our` (both whole, so `qso.their.guess.name` reaches the
-lookup's answer), `band`, `mode`, `freq`, `rstSent`, `rstRcvd`, `notes`,
-`date`, `dateCompact`, `time`, `at`, `startAtMillis`, `refs`.
+lookup's answer), `band`, `mode`, `freq`, `rstSent`, `rstRcvd`, `serialSent`,
+`serialRcvd`, `notes`, `date`, `dateCompact`, `time`, `at`, `startAtMillis`,
+`refs` — and two short forms for the sent side, `rst` (= `rstSent`) and
+`serial` (= `serialSent`), since a CW message is what we send and that is
+where these get typed: `{{ qso.call }} {{ qso.rst | cut }} {{ qso.serial | pad: 3 | cut }}`.
 
 `rstSent` is what WE sent — QSON stores each side's report under its own
 `sent`, and these are named for the operator's view of the contact.
 
+`serialSent` / `serialRcvd` are a contest's serial numbers, blank outside
+one. A contest keeps them on its own ref, so they are found by field name —
+the first ref carrying `ourSerial` / `theirSerial` — which is what lets one
+message serve every serial contest (docs/design/contests.md §5.8). In a CW
+message `serialSent` is the number the serial field is SHOWING, the one the
+QSO will be logged with. It is unpadded (`7`, not `007`): use `pad`.
+
 ### `config` — a panel's own form values
 Whatever that panel's `form` declared, under the keys it used.
 
@@ -112,12 +124,27 @@ with nothing to say it was invented.
 
 All of Liquid's own (`date`, `downcase`, `upcase`, `strip`, `default`,
 `join`, `size`, `first`, `last`, `round`, `truncate`, `replace`, `map`,
-`where`, …), plus two:
+`where`, …), plus six:
 
 | filter | does | example |
 |---|---|---|
 | `dash` | non-alphanumerics → `-`, collapsed and trimmed, **case preserved** | `N0CALL/P` → `N0CALL-P` |
 | `alnum` | strip to alphanumerics | `2026-07-27` → `20260727` |
+| `pad: n` | zero-pad on the left to `n` characters (default 3); **blank stays blank** | `7` → `007` |
+| `cut: "digits"` | CW cut numbers for the listed digits, of `0`→`T` `1`→`A` `5`→`E` `9`→`N`; default `"09"` | `599` → `5NN`, `{{ 9 \| pad: 3 \| cut }}` → `TTN` |
+| `refLabels` | a list of refs → each one's `shortLabel`, else `label`, else `ref`; a ref with none of them is skipped — an operation's contest ref HAS a label (`CQ WPX CW`) and is listed | `op.refs` → `POTA US-1234`, `KFF-9999` |
+| `sentence: "sep", "final"` | joins a list with a different LAST separator (defaults `", "` and `" & "`); blanks are dropped | `A, B & C`, `A & B` |
+
+`pad` leaves a blank alone because a CW message can be keyed before the
+serial field has a number, and `000` sent in that gap is a serial the log
+will never agree with. Order matters with `cut`: pad first, or the padding
+zeros go out uncut.
+
+`refLabels` exists because `map` reads one field: `map: "shortLabel"` drops a
+reference that resolved to nothing, since it carries no labels — an
+operation at an unlisted park would print as though it had none. Liquid's own
+`array_to_sentence_string` is the near miss for `sentence`: it always writes
+the serial comma (`A, B, & C`).
 
 `alnum` is app-polo's `compact` helper under a different name: Liquid already
 has a `compact` (it drops nils from an **array**, and `op.refs`/`qso.refs` are
@@ -140,6 +167,10 @@ Each of these was measured against the shipped runtime, not assumed.
 number as SECONDS, so epoch millis render in the year 58567. Use the `…At`
 strings.
 
+**`cut`'s digit list must be quoted.** Liquid reads a bare `0159` as the
+number 159 before the filter sees it, so `{{ n | cut: 09 }}` cuts only the
+nines — the zero is gone with no error. Write `cut: "09"`.
+
 **Unknown names are silent.** An unknown variable renders empty and an
 unknown filter passes its value through. That is deliberate — an operator's
 typo costs one line, not the document — but it means a misspelled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",