@estiva-app/interop 0.56.0 → 0.57.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.56.0",
3
+ "version": "0.57.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/folders.ts CHANGED
@@ -42,6 +42,8 @@
42
42
  * relay lets only the channel's owners and admins change that, while any
43
43
  * member may send a `kind:1852` — so a name on a command would let anyone
44
44
  * retitle the Folder for every reader that believed it.
45
+ *
46
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/folders-belong-to-the-protocol.md
45
47
  */
46
48
  import {
47
49
  buildCreateChannel,
@@ -316,6 +318,8 @@ export function listedBeneath<T extends MovableFile>(listing: readonly T[], file
316
318
  * channel or absent (`target-is-private`, §3.1).
317
319
  *
318
320
  * A move to the same Folder, or of a set the source does not list, plans nothing.
321
+ *
322
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/moving-a-file-never-changes-who-can-read-it.md
319
323
  */
320
324
  export function planMoveFile(
321
325
  pubkey: string,
package/src/index.ts CHANGED
@@ -38,6 +38,7 @@ export {
38
38
  listFolders,
39
39
  topLevelFolders,
40
40
  ARCHIVED_FIELD,
41
+ SUMMARY_FIELD,
41
42
  isArchived,
42
43
  isClosedStatus,
43
44
  archiveImpact,
package/src/projection.ts CHANGED
@@ -1374,6 +1374,19 @@ export const MOVED_TO_TAG = 'A'
1374
1374
  */
1375
1375
  export const ARCHIVED_FIELD = 'archived'
1376
1376
 
1377
+ /**
1378
+ * The field, and the root tag seeding it, that holds a file's one-line summary,
1379
+ * whatever its kind — SPEC §6.12.
1380
+ *
1381
+ * Plain text, one or two sentences, beside the title: what a card, a row or a
1382
+ * picker shows under it. Changed by a `kind:1851` like the title, last write
1383
+ * wins, and a value that is blank after trimming means no summary. Every file
1384
+ * kind's `subtitle` reads it ({@link defaultSubtitle}), so no manifest has to.
1385
+ *
1386
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-files-summary-is-its-own-field.md
1387
+ */
1388
+ export const SUMMARY_FIELD = 'summary'
1389
+
1377
1390
  /**
1378
1391
  * Where a `ResolvedManifest.address` would name the manifest event, this names
1379
1392
  * the section of the specification the manifest is built from. Not an address,
@@ -1498,6 +1511,23 @@ const BARE_FILE_MANIFEST: Manifest = {
1498
1511
  emits: { kind: 1851, field: 'description' },
1499
1512
  input: { type: 'string', format: BLOCK_DOCUMENT_FORMAT },
1500
1513
  },
1514
+ /*
1515
+ `summarize` sets the file's one-line summary (SPEC §6.12): plain text, so
1516
+ its input declares no `format` (§7.3), and a consumer finds it by
1517
+ `emits.field`, not by this id. An empty value clears it, the summary the
1518
+ file was created with included.
1519
+ */
1520
+ {
1521
+ id: 'summarize',
1522
+ label: 'Summary',
1523
+ description:
1524
+ "Set this file's summary: one or two sentences of plain text, about 240 characters, shown under its " +
1525
+ 'title wherever it is met in one line. A change event, so anyone in the Folder may; an empty value clears it.',
1526
+ effect: 'writes',
1527
+ appliesTo: [String(KIND_BARE_FILE)],
1528
+ emits: { kind: 1851, field: SUMMARY_FIELD },
1529
+ input: { type: 'string' },
1530
+ },
1501
1531
  /*
1502
1532
  `move` is the `parent` field SPEC §6.7 already defines, declared so a
1503
1533
  consumer draws the control from here as it draws Rename (FOL-4). The value
@@ -1567,6 +1597,8 @@ function bareFileManifest(): ResolvedManifest {
1567
1597
  * What a Folder's built-in actions are declared by — SPEC §3.2, as
1568
1598
  * {@link BARE_FILE_MANIFEST_ADDRESS} is for the bare file. The
1569
1599
  * `declaredBy.address` of an action no app declared.
1600
+ *
1601
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/folders-belong-to-the-protocol.md
1570
1602
  */
1571
1603
  export const FOLDER_ACTIONS_ADDRESS = 'spec:3.2'
1572
1604
 
@@ -1599,12 +1631,18 @@ const FOLDER_CREATOR: ResolvedManifest = {
1599
1631
  id: 'create-file',
1600
1632
  label: 'New file',
1601
1633
  description:
1602
- 'Put a new file in this Folder: a title, and nothing else yet. Everyone who can read the Folder can read ' +
1634
+ 'Put a new file in this Folder: a title and, if you have one, a short summary. Everyone who can read the Folder can read ' +
1603
1635
  'it, and the Folder lists it straight away. The app opening files calls it by its own word — Peek says topic.',
1604
1636
  effect: 'writes',
1605
1637
  appliesTo: String(KIND_CHANNEL_METADATA),
1606
1638
  emits: { kind: KIND_BARE_FILE, listed: true },
1607
- input: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] },
1639
+ // `summary` is the root tag that seeds the new file's summary (SPEC
1640
+ // §3.2, §6.12); left empty, it is omitted (§7.3).
1641
+ input: {
1642
+ type: 'object',
1643
+ properties: { title: { type: 'string' }, [SUMMARY_FIELD]: { type: 'string' } },
1644
+ required: ['title'],
1645
+ },
1608
1646
  },
1609
1647
  ],
1610
1648
  },
@@ -1620,6 +1658,8 @@ const FOLDER_CREATOR: ResolvedManifest = {
1620
1658
  * runtime's, so a published manifest still cannot change how a bare file
1621
1659
  * behaves; it can only say what it is called where it opens. A comment takes
1622
1660
  * the name (it opens in the same app) and not the noun, which is the file's.
1661
+ *
1662
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-file-is-labelled-by-its-type-not-its-app.md
1623
1663
  */
1624
1664
  function bareFileOpenedBy(opener: Manifest, template: string): ResolvedManifest {
1625
1665
  const name = wordOf(opener.name) ?? BARE_FILE_MANIFEST.name
@@ -2153,6 +2193,9 @@ import { contentFormatOf, type ContentFormat } from '@estiva-app/protocol'
2153
2193
  */
2154
2194
  export const BODY_SLOT = 'body'
2155
2195
 
2196
+ /** The slot that is a file's summary, one line of plain text (SPEC §7.2). */
2197
+ const SUBTITLE_SLOT = 'subtitle'
2198
+
2156
2199
 
2157
2200
  /**
2158
2201
  * Does this change sit in the Folder its target is filed in — SPEC §6.2.
@@ -2215,6 +2258,9 @@ function foldChanges(changes: SignedEvent[], rule: RecordsRule, root: SignedEven
2215
2258
  const field = tagValue(change, rule.fieldTag)
2216
2259
  const value = tagValue(change, rule.valueTag)
2217
2260
  if (!field || value === undefined) continue // a partial change sets nothing
2261
+ // A summary is new, so it takes neither of §6.2's exceptions: a change the
2262
+ // reader cannot check against the root's Folder is not read (SPEC §6.12).
2263
+ if (field === SUMMARY_FIELD && !folders) continue
2218
2264
  // The format travels with the *winning* change, not with the object. SPEC
2219
2265
  // §13.4: "an app MUST read the tag from the event it took the value from,
2220
2266
  // never from the object's root" — a description created as marker text and
@@ -2780,7 +2826,19 @@ function resolveSlot(
2780
2826
  const source = rawSlotValue(spec, root, folded, name === BODY_SLOT)
2781
2827
 
2782
2828
  if (source === undefined || source.value === '') return null
2783
- const raw = source.value
2829
+ let raw = source.value
2830
+ /*
2831
+ `subtitle` is plain text on one line (SPEC §7.2, §6.12): line breaks fold to
2832
+ spaces, and a value that is blank once trimmed is no subtitle — a summary
2833
+ cleared with " " reads as cleared, and the seed does not show through it.
2834
+ Left to each consumer, `slots.subtitle &&` drew a blank one as an empty line
2835
+ (Peek's ForeignObjectWidget). A body-shaped value declared into the slot is
2836
+ left alone; the truncation guard below is what speaks to that.
2837
+ */
2838
+ if (name === SUBTITLE_SLOT && source.format !== 'blocks' && source.format !== 'unknown') {
2839
+ raw = raw.replace(/\s+/g, ' ').trim()
2840
+ if (raw === '') return null
2841
+ }
2784
2842
 
2785
2843
  /*
2786
2844
  PRO-8's rule, now enforceable rather than only written down.
@@ -2820,6 +2878,69 @@ function resolveSlot(
2820
2878
  }
2821
2879
  }
2822
2880
 
2881
+ /*
2882
+ `truncate` is the clamp SPEC §6.12 makes a reader's job: the relay does not
2883
+ hold a writer to about 240 characters, and with no manifest declaring the
2884
+ slot nothing else would cut a 1,000-character summary down to a line. A
2885
+ consumer still clamps it to its own room; this is the backstop.
2886
+ */
2887
+ const SUMMARY_TRUNCATE = 280
2888
+ const SUMMARY_SUBTITLE: SlotSpec = { tag: SUMMARY_FIELD, fold: SUMMARY_FIELD, truncate: SUMMARY_TRUNCATE }
2889
+ const FOLDER_SUBTITLE: SlotSpec = { tag: 'about' }
2890
+
2891
+ /**
2892
+ * Where a kind's `subtitle` comes from whatever its manifest says, or
2893
+ * `undefined` where the manifest decides — SPEC §7.2, §6.12, §3.2.
2894
+ *
2895
+ * - **A Folder** (`kind:39000`): the `about` of its channel record, NIP-29's
2896
+ * one-liner. A `summary` change aimed at one is not read.
2897
+ * - **Every other addressable kind is a file**, and its subtitle is its
2898
+ * summary: the `summary` fold over the root tag of that name. Built in, so an
2899
+ * app's files — an outside company's included — show their summary on every
2900
+ * card with nothing in its manifest, and no manifest can point the line at
2901
+ * another field (Miky, 2026-10-15, kickoff).
2902
+ * - NIP-29's other `39001`–`39009` records, and regular events (a message, a
2903
+ * comment), keep what their manifest declares.
2904
+ */
2905
+ function defaultSubtitle(kind: number): SlotSpec | undefined {
2906
+ if (kind === KIND_CHANNEL_METADATA) return FOLDER_SUBTITLE
2907
+ if (kind >= 39000 && kind <= 39009) return undefined
2908
+ return isAddressableKind(kind) ? SUMMARY_SUBTITLE : undefined
2909
+ }
2910
+
2911
+ /**
2912
+ * A projection's slots with `subtitle` taken from {@link defaultSubtitle}.
2913
+ *
2914
+ * A declaration naming the same source keeps its `label` and a `truncate`
2915
+ * tighter than the built-in one (Peek's Folder projection truncates `about` at
2916
+ * 120); one naming any other source, or an array, is replaced.
2917
+ */
2918
+ function withDefaultSubtitle(
2919
+ slots: Record<string, SlotSpec | SlotSpec[]>,
2920
+ kind: number,
2921
+ ): Record<string, SlotSpec | SlotSpec[]> {
2922
+ const builtIn = defaultSubtitle(kind)
2923
+ if (!builtIn) return slots
2924
+ const declared = slots[SUBTITLE_SLOT]
2925
+ const same =
2926
+ declared !== undefined &&
2927
+ !Array.isArray(declared) &&
2928
+ declared.tag === builtIn.tag &&
2929
+ declared.fold === builtIn.fold &&
2930
+ declared.field === undefined &&
2931
+ declared.default === undefined &&
2932
+ declared.map === undefined &&
2933
+ declared.as === undefined &&
2934
+ declared.children === undefined
2935
+ if (!same) return { ...slots, [SUBTITLE_SLOT]: builtIn }
2936
+ // Same source: its `label` and a tighter `truncate` stand, never a looser one.
2937
+ const truncate =
2938
+ declared.truncate === undefined || builtIn.truncate === undefined
2939
+ ? (declared.truncate ?? builtIn.truncate)
2940
+ : Math.min(declared.truncate, builtIn.truncate)
2941
+ return { ...slots, [SUBTITLE_SLOT]: { ...builtIn, label: declared.label, truncate } }
2942
+ }
2943
+
2823
2944
  /**
2824
2945
  * Every slot a projection declares, resolved.
2825
2946
  *
@@ -2835,7 +2956,7 @@ function resolveSlots(
2835
2956
  ): { slots: Record<string, ResolvedSlot>; meta: ResolvedSlot[] } {
2836
2957
  const slots: Record<string, ResolvedSlot> = {}
2837
2958
  const meta: ResolvedSlot[] = []
2838
- for (const [name, spec] of Object.entries(projection.slots)) {
2959
+ for (const [name, spec] of Object.entries(withDefaultSubtitle(projection.slots, root.kind))) {
2839
2960
  if (Array.isArray(spec)) {
2840
2961
  for (const one of spec) {
2841
2962
  // An array spec collects into `meta`, so the name it was declared under
@@ -3080,7 +3201,9 @@ function buildObject(args: {
3080
3201
  * nothing.
3081
3202
  */
3082
3203
  const held: Record<string, string> = {}
3083
- for (const spec of Object.values(projection.slots).flat()) {
3204
+ // The built-in subtitle too, or a summary seeded at creation shows on the
3205
+ // card while `summarize` offers a blank to edit (SPEC §6.12).
3206
+ for (const spec of Object.values(withDefaultSubtitle(projection.slots, root.kind)).flat()) {
3084
3207
  // `tag` may name several spellings (see `SlotSpec`); the field this slot
3085
3208
  // *is* keyed on is the first, which is the one the app writes today. The
3086
3209
  // rest are only there to keep older records rendering.
@@ -5611,6 +5734,8 @@ const nameOf = (event: SignedEvent | undefined) => (event ? tagValue(event, 'nam
5611
5734
  /**
5612
5735
  * The owners and admins a `kind:39001` lists — kept only when the channel's own
5613
5736
  * signer, the relay, signed it: anybody can publish an event of that shape.
5737
+ *
5738
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/only-owners-and-admins-rename-or-archive-a-folder.md
5614
5739
  */
5615
5740
  function folderAdminsOf(admins: SignedEvent | undefined, channel: SignedEvent | undefined): string[] {
5616
5741
  if (!admins || !channel || admins.pubkey !== channel.pubkey) return []
@@ -5646,9 +5771,15 @@ export interface FolderSummary {
5646
5771
  * The title: its `kind:39000`'s `name`, and only that (SPEC §3.2). A `name`
5647
5772
  * an older `kind:1852` left on the state is never read — any member may send
5648
5773
  * one, and only owners and admins may rename the channel.
5774
+ *
5775
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/only-owners-and-admins-rename-or-archive-a-folder.md
5649
5776
  */
5650
5777
  name?: string
5651
- /** True once the relay maintains state for it, rather than it being a bare channel. */
5778
+ /**
5779
+ * True once the relay maintains state for it, rather than it being a bare channel.
5780
+ *
5781
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-folder-is-a-group-the-relay-lists.md
5782
+ */
5652
5783
  hasState: boolean
5653
5784
  /**
5654
5785
  * Present when the Folder's relay-signed `kind:39000` carries `["private"]`