@estiva-app/interop 0.103.0 → 0.105.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.103.0",
3
+ "version": "0.105.0",
4
4
  "description": "Render and act on another app's objects from its published NIP-89 manifest. The owner defines the projection; the consumer decides how it looks.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/src/index.ts CHANGED
@@ -50,6 +50,7 @@ export {
50
50
  progressOfStages,
51
51
  statusStageOf,
52
52
  stageTagOf,
53
+ stageTagFor,
53
54
  type Stage,
54
55
  archiveImpact,
55
56
  type Archive,
@@ -105,6 +106,7 @@ export {
105
106
  type FolderRecord,
106
107
  type ResolvedSlot,
107
108
  type ResolvedAction,
109
+ type ResolvedOption,
108
110
  type ActionFormField,
109
111
  type ProseFormat,
110
112
  type ManifestAction,
package/src/projection.ts CHANGED
@@ -890,7 +890,26 @@ export interface ActionFormField {
890
890
  */
891
891
  format?: ProseFormat
892
892
  /** When the property names a vocabulary, its entries, already looked up. */
893
- options?: { value: string; label: string; colour?: string }[]
893
+ options?: ResolvedOption[]
894
+ }
895
+
896
+ /**
897
+ * A vocabulary entry a consumer draws and writes from. `stage` is the entry's
898
+ * declared stage when it is one of the four (SPEC §7.3) — what an app that
899
+ * builds its own change passes to {@link stageTagFor}, so the change says what
900
+ * the choice means as a declared action's does (EAC-5).
901
+ */
902
+ export interface ResolvedOption {
903
+ value: string
904
+ label: string
905
+ colour?: string
906
+ stage?: Stage
907
+ }
908
+
909
+ /** A vocabulary entry as a consumer gets it: its stage only when it is one of the four. */
910
+ function resolvedOption(entry: { value: string; label: string; colour: string; stage?: string }): ResolvedOption {
911
+ const stage = asStage(entry.stage)
912
+ return { value: entry.value, label: entry.label, colour: entry.colour, ...(stage ? { stage } : {}) }
894
913
  }
895
914
 
896
915
  /**
@@ -923,8 +942,8 @@ export interface ResolvedAction {
923
942
  * it.
924
943
  */
925
944
  control: 'select' | 'pubkey' | 'text' | 'form' | 'confirm'
926
- /** For `select`: the declared vocabulary, already looked up. */
927
- options?: { value: string; label: string; colour?: string }[]
945
+ /** For `select`: the declared vocabulary, already looked up, each entry with its stage (see {@link ResolvedOption}). */
946
+ options?: ResolvedOption[]
928
947
  /**
929
948
  * For `form`: the fields to draw, in declaration order, with any vocabulary
930
949
  * already looked up — the same service `options` performs for a `select`.
@@ -1126,13 +1145,7 @@ function resolveActions(
1126
1145
  // Prose only where the value is `content` — a tag is a scalar (§7.3).
1127
1146
  ...(spec.target === 'content' && proseFormatOf(spec.format) ? { format: proseFormatOf(spec.format) } : {}),
1128
1147
  ...(spec.enum && manifest.vocabularies?.[spec.enum]
1129
- ? {
1130
- options: manifest.vocabularies[spec.enum].map((v) => ({
1131
- value: v.value,
1132
- label: v.label,
1133
- colour: v.colour,
1134
- })),
1135
- }
1148
+ ? { options: manifest.vocabularies[spec.enum].map(resolvedOption) }
1136
1149
  : {}),
1137
1150
  })),
1138
1151
  // The parent is not a property and never appears in `properties`; it
@@ -1156,7 +1169,7 @@ function resolveActions(
1156
1169
  ...(action.effect ? { effect: action.effect } : {}),
1157
1170
  control,
1158
1171
  ...(format ? { format } : {}),
1159
- options: vocab?.map((v) => ({ value: v.value, label: v.label, colour: v.colour })),
1172
+ options: vocab?.map(resolvedOption),
1160
1173
  current: action.emits.field ? folded[action.emits.field]?.value : undefined,
1161
1174
  field: action.emits.field,
1162
1175
  })
@@ -2443,6 +2456,29 @@ export function stageTagOf(event: Pick<SignedEvent, 'tags'>, field: string): Sta
2443
2456
  return asStage(event.tags.find((t) => t[0] === 'stage' && t[1] === field)?.[2])
2444
2457
  }
2445
2458
 
2459
+ /**
2460
+ * The tag a change (or a root) that sets `field` to `value` carries last: the
2461
+ * stage of the option the writer offered, `["stage", <field>, <stage>]` (SPEC
2462
+ * §6.2, §7.3). `options` are the ones the writer offered it from — its own
2463
+ * vocabulary, or the layer of §7.4 it read. None when the value is cleared
2464
+ * (`''`), is not among the options, or its option carries no stage of the four:
2465
+ * a writer never guesses what a status means. {@link stageTagOf} reads it back.
2466
+ *
2467
+ * Exported for an app that builds its own changes (Ship, EAC-4); a
2468
+ * manifest-declared action gets it from {@link buildActionEvent}.
2469
+ *
2470
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-companys-statuses-are-its-own-layer-of-a-types-properties.md
2471
+ */
2472
+ export function stageTagFor(
2473
+ field: string,
2474
+ value: string,
2475
+ options: readonly { value: string; stage?: string }[] | undefined,
2476
+ ): ['stage', string, Stage] | undefined {
2477
+ if (value === '') return undefined
2478
+ const stage = asStage(options?.find((option) => option.value === value)?.stage)
2479
+ return stage ? ['stage', field, stage] : undefined
2480
+ }
2481
+
2446
2482
  /**
2447
2483
  * The fields one change sets under `rule`: one per `set` when it carries any
2448
2484
  * (SPEC §6.2, applied at the change's time as that many one-field changes),
@@ -6378,6 +6414,13 @@ function buildCreationEvent(args: {
6378
6414
  // Each person the new root names, once, where the relay indexes them — the
6379
6415
  // property's own tag is not indexed (SPEC §11.8, decided 2026-10-05).
6380
6416
  for (const person of people) tags.push(['p', person])
6417
+ // What each chosen option means, last (§6.2's `stage`, §7.3): a creation
6418
+ // that sets a staged property, such as a status, carries its stage on the root.
6419
+ for (const [name, held] of Object.entries(value)) {
6420
+ const vocabName = properties[name]?.enum
6421
+ const stage = vocabName ? stageTagFor(name, held, args.vocabularies?.[vocabName]) : undefined
6422
+ if (stage) tags.push(stage)
6423
+ }
6381
6424
 
6382
6425
  return {
6383
6426
  pubkey: args.pubkey,
@@ -6781,10 +6824,10 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
6781
6824
  }
6782
6825
  // What the chosen option means, last (§6.2's `stage`): a status says
6783
6826
  // whether it is open, started, done or dropped, whichever app reads it.
6784
- const stage = declared.emits.field && declared.input?.enum
6785
- ? manifest.vocabularies?.[declared.input.enum]?.find((entry) => entry.value === value)?.stage
6827
+ const stage = declared.emits.field && declared.input?.enum && typeof value === 'string'
6828
+ ? stageTagFor(declared.emits.field, value, manifest.vocabularies?.[declared.input.enum])
6786
6829
  : undefined
6787
- if (declared.emits.field && stage && STAGES.has(stage as Stage)) tags.push(['stage', declared.emits.field, stage])
6830
+ if (stage) tags.push(stage)
6788
6831
 
6789
6832
  return {
6790
6833
  pubkey: args.pubkey,