@ham2k/extension-sdk 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.11.0
+// @ham2k/extension-sdk 0.12.0
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -490,6 +490,8 @@ export interface Ref {
 	lon?: number;
 	location?: string;
 	program?: string;
+	activationRadiusInMeters?: number;
+	activationRadiusInFeet?: number;
 	retired?: boolean;
 	for?: "operation" | "qso";
 	[key: string]: JSONValue | undefined;
@@ -1874,7 +1876,9 @@ export interface ReferenceActivityConfig {
 	linkUrl?: (reference: string) => string;
 	transforms?: RefTransform[];
 	refInput?: (args: RefInputArgs, ctx: HookContext) => Promise<RefInputExtras> | RefInputExtras;
+	activationRadius?: ActivationRadius | ((row: LookupRow) => ActivationRadius | undefined);
 }
+export type ActivationRadius = Pick<Ref, "activationRadiusInMeters" | "activationRadiusInFeet">;
 export interface RefInputArgs {
 	operation: Record<string, JSONValue>;
 	qso?: Record<string, JSONValue>;

package/dist/referenceActivity.js

@@ -58,6 +58,10 @@ function referenceActivity(config) {
   const category = config.category ?? config.key;
   const program = config.adifProgram ?? config.label;
   const allowsMultiple = config.allowsMultiple ?? false;
+  function radiusFor(row) {
+    const radius = row ? typeof config.activationRadius === "function" ? config.activationRadius(row) : config.activationRadius : void 0;
+    return { activationRadiusInMeters: radius?.activationRadiusInMeters, activationRadiusInFeet: radius?.activationRadiusInFeet };
+  }
   async function lookupReference(ref) {
     const host = await hostApi();
     try {
@@ -78,7 +82,8 @@ function referenceActivity(config) {
       grid: void 0,
       lat: void 0,
       lon: void 0,
-      location: void 0
+      location: void 0,
+      ...radiusFor(null)
     };
   }
   function decorate(ref, reference, row, unknown) {
@@ -91,6 +96,7 @@ function referenceActivity(config) {
       grid: data.grid,
       lat: row.lat,
       lon: row.lon,
+      ...radiusFor(row),
       location: data.location,
       program,
       label: `${config.label} ${reference}: ${row.name}`,
@@ -206,6 +212,7 @@ function referenceActivity(config) {
           grid: data.grid,
           lat: row.lat,
           lon: row.lon,
+          ...radiusFor(row),
           location: data.location,
           program,
           label: `${config.label} ${row.key}: ${row.name ?? ""}`,
@@ -230,6 +237,7 @@ function referenceActivity(config) {
           grid: data.grid,
           lat: row?.lat,
           lon: row?.lon,
+          ...radiusFor(row),
           location: data.location,
           program,
           label: `${config.label} ${typed}: ${name}`,

package/docs/hooks.md

@@ -429,7 +429,8 @@ interface RefHandlerHook {
   linkForRef?(args: { ref: Ref }, ctx): Promise<RefLink | null>   // {url, label?}
   geojsonUrlForRef?(args: { ref: Ref }, ctx): Promise<RefGeojson | null>
 }
-// Ref: {type, ref?, name?, label?, shortLabel?, grid?, location?, program?, ...}
+// Ref: {type, ref?, name?, label?, shortLabel?, grid?, lat?, lon?, location?, program?,
+//       activationRadiusInMeters?, activationRadiusInFeet?, ...}
 // TitleSuggestion: {title?, for?, at?, subtitle?, priority?} — a fragment of
 // the operation's title/subtitle sentence (ham2k/halo-dist#174). Only
 // return one for the ref type that means "this operation is happening AT/FOR
@@ -517,6 +518,23 @@ SOTLAS's `az.sotl.as`, used with the operators' permission) and `pota` (both
 types, via `services.ham2k.net/lookups/outlines/pota/`, which links parks to
 OpenStreetMap shapes; a park not yet linked answers 404).
 
+**An activation radius is a circle, drawn the same way.** A reference that
+carries `activationRadiusInMeters` or `activationRadiusInFeet` — how far from
+its point the program lets an activator be — is circled on both maps, in the
+same color and under the same rules as an outline: solid for the operation's
+own references and the open card, dashed for the other suggestions once
+zoomed in. It is set on the reference itself, by `suggest` and `decorateRef`,
+because some programs set different distances by region or by kind of
+reference; a suggestion is stored on the operation verbatim, so the Map tab
+draws it too. Give whichever unit the rules are written in; meters win when
+both are set. It is drawn only around `lat`/`lon`, never around a `grid`,
+whose centre can sit further from the reference than the whole radius
+(docs/design/locations.md). A reference with an outline AND a radius draws
+both. A circle has no source, so it adds nothing to the map's outline credits
+and is not offered for an outline report. Programs built on the SDK's
+`referenceActivity` factory get this from one `activationRadius` config line —
+a value, or a function of the list row for rules that vary.
+
 `suggestOperationTitle` lets an activity build a natural-language operation
 title/subtitle from its refs — "at Yosemite NP" (POTA), "for Field Day"
 (contest programs, when ported) — mirroring app-polo's

package/package.json

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