@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/CHANGELOG.md +32 -0
- package/dist/folders.d.ts +4 -0
- package/dist/folders.d.ts.map +1 -1
- package/dist/folders.js +4 -0
- package/dist/folders.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/projection.d.ts +21 -1
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +125 -5
- package/dist/projection.js.map +1 -1
- package/package.json +1 -1
- package/src/folders.ts +4 -0
- package/src/index.ts +1 -0
- package/src/projection.ts +137 -6
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@estiva-app/interop",
|
|
3
|
-
"version": "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
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
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"]`
|