@estiva-app/interop 0.102.1 → 0.104.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.102.1",
3
+ "version": "0.104.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
@@ -47,6 +47,10 @@ export {
47
47
  archivedAncestorOf,
48
48
  isClosedStatus,
49
49
  progressOf,
50
+ progressOfStages,
51
+ statusStageOf,
52
+ stageTagOf,
53
+ stageTagFor,
50
54
  type Stage,
51
55
  archiveImpact,
52
56
  type Archive,
package/src/projection.ts CHANGED
@@ -2433,11 +2433,39 @@ function foldChanges(changes: SignedEvent[], rule: RecordsRule, root: SignedEven
2433
2433
  return fields
2434
2434
  }
2435
2435
 
2436
- /** The stage an event (a change or a root) gives `field`: `["stage", <field>, <stage>]`, one of the four. */
2437
- function stageTagOf(event: SignedEvent, field: string): Stage | undefined {
2436
+ /**
2437
+ * The stage an event (a change or a root) gives `field`: `["stage", <field>, <stage>]`,
2438
+ * one of the four (SPEC §6.2). Exported for an app that folds its own changes
2439
+ * (Ship, EAC-3): read it from the event the field's current value came from,
2440
+ * never from an older one, and pass it to {@link statusStageOf}.
2441
+ */
2442
+ export function stageTagOf(event: Pick<SignedEvent, 'tags'>, field: string): Stage | undefined {
2438
2443
  return asStage(event.tags.find((t) => t[0] === 'stage' && t[1] === field)?.[2])
2439
2444
  }
2440
2445
 
2446
+ /**
2447
+ * The tag a change (or a root) that sets `field` to `value` carries last: the
2448
+ * stage of the option the writer offered, `["stage", <field>, <stage>]` (SPEC
2449
+ * §6.2, §7.3). `options` are the ones the writer offered it from — its own
2450
+ * vocabulary, or the layer of §7.4 it read. None when the value is cleared
2451
+ * (`''`), is not among the options, or its option carries no stage of the four:
2452
+ * a writer never guesses what a status means. {@link stageTagOf} reads it back.
2453
+ *
2454
+ * Exported for an app that builds its own changes (Ship, EAC-4); a
2455
+ * manifest-declared action gets it from {@link buildActionEvent}.
2456
+ *
2457
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-companys-statuses-are-its-own-layer-of-a-types-properties.md
2458
+ */
2459
+ export function stageTagFor(
2460
+ field: string,
2461
+ value: string,
2462
+ options: readonly { value: string; stage?: string }[] | undefined,
2463
+ ): ['stage', string, Stage] | undefined {
2464
+ if (value === '') return undefined
2465
+ const stage = asStage(options?.find((option) => option.value === value)?.stage)
2466
+ return stage ? ['stage', field, stage] : undefined
2467
+ }
2468
+
2441
2469
  /**
2442
2470
  * The fields one change sets under `rule`: one per `set` when it carries any
2443
2471
  * (SPEC §6.2, applied at the change's time as that many one-field changes),
@@ -5703,6 +5731,32 @@ function stageOf(
5703
5731
  return stageByWords(raw, label)
5704
5732
  }
5705
5733
 
5734
+ /**
5735
+ * The stage a project's or an issue's `status` counts by, for an app that folds
5736
+ * its own changes rather than resolving a slot (Ship, the agent; EAC-3). The
5737
+ * same three readings {@link ResolvedSlot.stage} carries: `written`, the stage
5738
+ * on the change or root that set the current value ({@link stageTagOf}); else
5739
+ * the base type's directory stage for the id; else the words. For a kind that
5740
+ * is not a base type no manifest is at hand to say the field is staged, so
5741
+ * `written` is not read and the words decide, as a slot with no staged
5742
+ * vocabulary does.
5743
+ *
5744
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-companys-statuses-are-its-own-layer-of-a-types-properties.md
5745
+ */
5746
+ export function statusStageOf(kind: number, value: string, written?: Stage): Stage | undefined {
5747
+ // No slot spec and no manifest: only a base type's directory makes the field staged.
5748
+ return stageOf(kind, STATUS_SLOT, {} as SlotSpec, {} as Manifest, value, value, asStage(written))
5749
+ }
5750
+
5751
+ /**
5752
+ * Done over every one not dropped, from each one's stage: {@link progressOf}'s
5753
+ * count, for an app that holds stages rather than resolved slots. A stage
5754
+ * `undefined` (an unknown word) is in the total and not done.
5755
+ */
5756
+ export function progressOfStages(stages: readonly (Stage | undefined)[]): { done: number; total: number } {
5757
+ return { done: stages.filter((stage) => stage === 'done').length, total: stages.filter((stage) => stage !== 'dropped').length }
5758
+ }
5759
+
5706
5760
  /** Finished work, done or dropped: `[` puts a closed issue after an open one (PEE-21). */
5707
5761
  const isClosed = (stage: Stage | undefined) => stage === 'done' || stage === 'dropped'
5708
5762
 
@@ -5727,8 +5781,7 @@ export function isClosedStatus(slot: ResolvedSlot | undefined): boolean {
5727
5781
  */
5728
5782
  export function progressOf(children: readonly { slots: { status?: ResolvedSlot } }[]): { done: number; total: number } | undefined {
5729
5783
  if (!children.length || children.some((child) => !child.slots.status)) return undefined
5730
- const stages = children.map((child) => child.slots.status?.stage)
5731
- return { done: stages.filter((stage) => stage === 'done').length, total: stages.filter((stage) => stage !== 'dropped').length }
5784
+ return progressOfStages(children.map((child) => child.slots.status?.stage))
5732
5785
  }
5733
5786
 
5734
5787
  /**
@@ -6348,6 +6401,13 @@ function buildCreationEvent(args: {
6348
6401
  // Each person the new root names, once, where the relay indexes them — the
6349
6402
  // property's own tag is not indexed (SPEC §11.8, decided 2026-10-05).
6350
6403
  for (const person of people) tags.push(['p', person])
6404
+ // What each chosen option means, last (§6.2's `stage`, §7.3): a creation
6405
+ // that sets a staged property, such as a status, carries its stage on the root.
6406
+ for (const [name, held] of Object.entries(value)) {
6407
+ const vocabName = properties[name]?.enum
6408
+ const stage = vocabName ? stageTagFor(name, held, args.vocabularies?.[vocabName]) : undefined
6409
+ if (stage) tags.push(stage)
6410
+ }
6351
6411
 
6352
6412
  return {
6353
6413
  pubkey: args.pubkey,
@@ -6751,10 +6811,10 @@ function buildOneActionEvent(args: ActionEventArgs): UnsignedActionEvent | strin
6751
6811
  }
6752
6812
  // What the chosen option means, last (§6.2's `stage`): a status says
6753
6813
  // whether it is open, started, done or dropped, whichever app reads it.
6754
- const stage = declared.emits.field && declared.input?.enum
6755
- ? manifest.vocabularies?.[declared.input.enum]?.find((entry) => entry.value === value)?.stage
6814
+ const stage = declared.emits.field && declared.input?.enum && typeof value === 'string'
6815
+ ? stageTagFor(declared.emits.field, value, manifest.vocabularies?.[declared.input.enum])
6756
6816
  : undefined
6757
- if (declared.emits.field && stage && STAGES.has(stage as Stage)) tags.push(['stage', declared.emits.field, stage])
6817
+ if (stage) tags.push(stage)
6758
6818
 
6759
6819
  return {
6760
6820
  pubkey: args.pubkey,