@estiva-app/interop 0.55.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 +42 -0
- package/README.md +4 -0
- package/dist/folders.d.ts +5 -1
- package/dist/folders.d.ts.map +1 -1
- package/dist/folders.js +5 -1
- 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 +32 -2
- package/dist/projection.d.ts.map +1 -1
- package/dist/projection.js +154 -11
- package/dist/projection.js.map +1 -1
- package/package.json +1 -1
- package/src/folders.ts +5 -1
- package/src/index.ts +1 -0
- package/src/projection.ts +177 -14
package/dist/projection.js
CHANGED
|
@@ -839,6 +839,18 @@ export const MOVED_TO_TAG = 'A';
|
|
|
839
839
|
* not only the author.
|
|
840
840
|
*/
|
|
841
841
|
export const ARCHIVED_FIELD = 'archived';
|
|
842
|
+
/**
|
|
843
|
+
* The field, and the root tag seeding it, that holds a file's one-line summary,
|
|
844
|
+
* whatever its kind — SPEC §6.12.
|
|
845
|
+
*
|
|
846
|
+
* Plain text, one or two sentences, beside the title: what a card, a row or a
|
|
847
|
+
* picker shows under it. Changed by a `kind:1851` like the title, last write
|
|
848
|
+
* wins, and a value that is blank after trimming means no summary. Every file
|
|
849
|
+
* kind's `subtitle` reads it ({@link defaultSubtitle}), so no manifest has to.
|
|
850
|
+
*
|
|
851
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-files-summary-is-its-own-field.md
|
|
852
|
+
*/
|
|
853
|
+
export const SUMMARY_FIELD = 'summary';
|
|
842
854
|
/**
|
|
843
855
|
* Where a `ResolvedManifest.address` would name the manifest event, this names
|
|
844
856
|
* the section of the specification the manifest is built from. Not an address,
|
|
@@ -879,7 +891,7 @@ const BARE_FILE_MANIFEST = {
|
|
|
879
891
|
// `movedBy` is SPEC §6.7's `parent` field, declared rather than
|
|
880
892
|
// hard-coded since MAN-1, so a bare file moves by the rule every other
|
|
881
893
|
// kind does — the move action below sets the same field.
|
|
882
|
-
list: { children: { kind: KIND_BARE_FILE, via: 'a', limit: 200, movedBy: 'parent' } },
|
|
894
|
+
list: { children: { kind: KIND_BARE_FILE, via: 'a', limit: 200, movedBy: 'parent', anyParent: true } },
|
|
883
895
|
},
|
|
884
896
|
},
|
|
885
897
|
/*
|
|
@@ -959,6 +971,22 @@ const BARE_FILE_MANIFEST = {
|
|
|
959
971
|
emits: { kind: 1851, field: 'description' },
|
|
960
972
|
input: { type: 'string', format: BLOCK_DOCUMENT_FORMAT },
|
|
961
973
|
},
|
|
974
|
+
/*
|
|
975
|
+
`summarize` sets the file's one-line summary (SPEC §6.12): plain text, so
|
|
976
|
+
its input declares no `format` (§7.3), and a consumer finds it by
|
|
977
|
+
`emits.field`, not by this id. An empty value clears it, the summary the
|
|
978
|
+
file was created with included.
|
|
979
|
+
*/
|
|
980
|
+
{
|
|
981
|
+
id: 'summarize',
|
|
982
|
+
label: 'Summary',
|
|
983
|
+
description: "Set this file's summary: one or two sentences of plain text, about 240 characters, shown under its " +
|
|
984
|
+
'title wherever it is met in one line. A change event, so anyone in the Folder may; an empty value clears it.',
|
|
985
|
+
effect: 'writes',
|
|
986
|
+
appliesTo: [String(KIND_BARE_FILE)],
|
|
987
|
+
emits: { kind: 1851, field: SUMMARY_FIELD },
|
|
988
|
+
input: { type: 'string' },
|
|
989
|
+
},
|
|
962
990
|
/*
|
|
963
991
|
`move` is the `parent` field SPEC §6.7 already defines, declared so a
|
|
964
992
|
consumer draws the control from here as it draws Rename (FOL-4). The value
|
|
@@ -1023,6 +1051,8 @@ function bareFileManifest() {
|
|
|
1023
1051
|
* What a Folder's built-in actions are declared by — SPEC §3.2, as
|
|
1024
1052
|
* {@link BARE_FILE_MANIFEST_ADDRESS} is for the bare file. The
|
|
1025
1053
|
* `declaredBy.address` of an action no app declared.
|
|
1054
|
+
*
|
|
1055
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/folders-belong-to-the-protocol.md
|
|
1026
1056
|
*/
|
|
1027
1057
|
export const FOLDER_ACTIONS_ADDRESS = 'spec:3.2';
|
|
1028
1058
|
/**
|
|
@@ -1053,12 +1083,18 @@ const FOLDER_CREATOR = {
|
|
|
1053
1083
|
{
|
|
1054
1084
|
id: 'create-file',
|
|
1055
1085
|
label: 'New file',
|
|
1056
|
-
description: 'Put a new file in this Folder: a title
|
|
1086
|
+
description: '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 ' +
|
|
1057
1087
|
'it, and the Folder lists it straight away. The app opening files calls it by its own word — Peek says topic.',
|
|
1058
1088
|
effect: 'writes',
|
|
1059
1089
|
appliesTo: String(KIND_CHANNEL_METADATA),
|
|
1060
1090
|
emits: { kind: KIND_BARE_FILE, listed: true },
|
|
1061
|
-
|
|
1091
|
+
// `summary` is the root tag that seeds the new file's summary (SPEC
|
|
1092
|
+
// §3.2, §6.12); left empty, it is omitted (§7.3).
|
|
1093
|
+
input: {
|
|
1094
|
+
type: 'object',
|
|
1095
|
+
properties: { title: { type: 'string' }, [SUMMARY_FIELD]: { type: 'string' } },
|
|
1096
|
+
required: ['title'],
|
|
1097
|
+
},
|
|
1062
1098
|
},
|
|
1063
1099
|
],
|
|
1064
1100
|
},
|
|
@@ -1073,6 +1109,8 @@ const FOLDER_CREATOR = {
|
|
|
1073
1109
|
* runtime's, so a published manifest still cannot change how a bare file
|
|
1074
1110
|
* behaves; it can only say what it is called where it opens. A comment takes
|
|
1075
1111
|
* the name (it opens in the same app) and not the noun, which is the file's.
|
|
1112
|
+
*
|
|
1113
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-file-is-labelled-by-its-type-not-its-app.md
|
|
1076
1114
|
*/
|
|
1077
1115
|
function bareFileOpenedBy(opener, template) {
|
|
1078
1116
|
const name = wordOf(opener.name) ?? BARE_FILE_MANIFEST.name;
|
|
@@ -1518,6 +1556,8 @@ import { contentFormatOf } from '@estiva-app/protocol';
|
|
|
1518
1556
|
* and a consumer reads `slots.body` to find it.
|
|
1519
1557
|
*/
|
|
1520
1558
|
export const BODY_SLOT = 'body';
|
|
1559
|
+
/** The slot that is a file's summary, one line of plain text (SPEC §7.2). */
|
|
1560
|
+
const SUBTITLE_SLOT = 'subtitle';
|
|
1521
1561
|
/**
|
|
1522
1562
|
* Does this change sit in the Folder its target is filed in — SPEC §6.2.
|
|
1523
1563
|
*
|
|
@@ -1581,6 +1621,10 @@ function foldChanges(changes, rule, root) {
|
|
|
1581
1621
|
const value = tagValue(change, rule.valueTag);
|
|
1582
1622
|
if (!field || value === undefined)
|
|
1583
1623
|
continue; // a partial change sets nothing
|
|
1624
|
+
// A summary is new, so it takes neither of §6.2's exceptions: a change the
|
|
1625
|
+
// reader cannot check against the root's Folder is not read (SPEC §6.12).
|
|
1626
|
+
if (field === SUMMARY_FIELD && !folders)
|
|
1627
|
+
continue;
|
|
1584
1628
|
// The format travels with the *winning* change, not with the object. SPEC
|
|
1585
1629
|
// §13.4: "an app MUST read the tag from the event it took the value from,
|
|
1586
1630
|
// never from the object's root" — a description created as marker text and
|
|
@@ -2007,7 +2051,20 @@ function resolveSlot(spec, root, folded, manifest, name) {
|
|
|
2007
2051
|
const source = rawSlotValue(spec, root, folded, name === BODY_SLOT);
|
|
2008
2052
|
if (source === undefined || source.value === '')
|
|
2009
2053
|
return null;
|
|
2010
|
-
|
|
2054
|
+
let raw = source.value;
|
|
2055
|
+
/*
|
|
2056
|
+
`subtitle` is plain text on one line (SPEC §7.2, §6.12): line breaks fold to
|
|
2057
|
+
spaces, and a value that is blank once trimmed is no subtitle — a summary
|
|
2058
|
+
cleared with " " reads as cleared, and the seed does not show through it.
|
|
2059
|
+
Left to each consumer, `slots.subtitle &&` drew a blank one as an empty line
|
|
2060
|
+
(Peek's ForeignObjectWidget). A body-shaped value declared into the slot is
|
|
2061
|
+
left alone; the truncation guard below is what speaks to that.
|
|
2062
|
+
*/
|
|
2063
|
+
if (name === SUBTITLE_SLOT && source.format !== 'blocks' && source.format !== 'unknown') {
|
|
2064
|
+
raw = raw.replace(/\s+/g, ' ').trim();
|
|
2065
|
+
if (raw === '')
|
|
2066
|
+
return null;
|
|
2067
|
+
}
|
|
2011
2068
|
/*
|
|
2012
2069
|
PRO-8's rule, now enforceable rather than only written down.
|
|
2013
2070
|
|
|
@@ -2045,6 +2102,65 @@ function resolveSlot(spec, root, folded, manifest, name) {
|
|
|
2045
2102
|
...(source.format ? { format: source.format } : {}),
|
|
2046
2103
|
};
|
|
2047
2104
|
}
|
|
2105
|
+
/*
|
|
2106
|
+
`truncate` is the clamp SPEC §6.12 makes a reader's job: the relay does not
|
|
2107
|
+
hold a writer to about 240 characters, and with no manifest declaring the
|
|
2108
|
+
slot nothing else would cut a 1,000-character summary down to a line. A
|
|
2109
|
+
consumer still clamps it to its own room; this is the backstop.
|
|
2110
|
+
*/
|
|
2111
|
+
const SUMMARY_TRUNCATE = 280;
|
|
2112
|
+
const SUMMARY_SUBTITLE = { tag: SUMMARY_FIELD, fold: SUMMARY_FIELD, truncate: SUMMARY_TRUNCATE };
|
|
2113
|
+
const FOLDER_SUBTITLE = { tag: 'about' };
|
|
2114
|
+
/**
|
|
2115
|
+
* Where a kind's `subtitle` comes from whatever its manifest says, or
|
|
2116
|
+
* `undefined` where the manifest decides — SPEC §7.2, §6.12, §3.2.
|
|
2117
|
+
*
|
|
2118
|
+
* - **A Folder** (`kind:39000`): the `about` of its channel record, NIP-29's
|
|
2119
|
+
* one-liner. A `summary` change aimed at one is not read.
|
|
2120
|
+
* - **Every other addressable kind is a file**, and its subtitle is its
|
|
2121
|
+
* summary: the `summary` fold over the root tag of that name. Built in, so an
|
|
2122
|
+
* app's files — an outside company's included — show their summary on every
|
|
2123
|
+
* card with nothing in its manifest, and no manifest can point the line at
|
|
2124
|
+
* another field (Miky, 2026-10-15, kickoff).
|
|
2125
|
+
* - NIP-29's other `39001`–`39009` records, and regular events (a message, a
|
|
2126
|
+
* comment), keep what their manifest declares.
|
|
2127
|
+
*/
|
|
2128
|
+
function defaultSubtitle(kind) {
|
|
2129
|
+
if (kind === KIND_CHANNEL_METADATA)
|
|
2130
|
+
return FOLDER_SUBTITLE;
|
|
2131
|
+
if (kind >= 39000 && kind <= 39009)
|
|
2132
|
+
return undefined;
|
|
2133
|
+
return isAddressableKind(kind) ? SUMMARY_SUBTITLE : undefined;
|
|
2134
|
+
}
|
|
2135
|
+
/**
|
|
2136
|
+
* A projection's slots with `subtitle` taken from {@link defaultSubtitle}.
|
|
2137
|
+
*
|
|
2138
|
+
* A declaration naming the same source keeps its `label` and a `truncate`
|
|
2139
|
+
* tighter than the built-in one (Peek's Folder projection truncates `about` at
|
|
2140
|
+
* 120); one naming any other source, or an array, is replaced.
|
|
2141
|
+
*/
|
|
2142
|
+
function withDefaultSubtitle(slots, kind) {
|
|
2143
|
+
const builtIn = defaultSubtitle(kind);
|
|
2144
|
+
if (!builtIn)
|
|
2145
|
+
return slots;
|
|
2146
|
+
const declared = slots[SUBTITLE_SLOT];
|
|
2147
|
+
const same = declared !== undefined &&
|
|
2148
|
+
!Array.isArray(declared) &&
|
|
2149
|
+
declared.tag === builtIn.tag &&
|
|
2150
|
+
declared.fold === builtIn.fold &&
|
|
2151
|
+
declared.field === undefined &&
|
|
2152
|
+
declared.default === undefined &&
|
|
2153
|
+
declared.map === undefined &&
|
|
2154
|
+
declared.as === undefined &&
|
|
2155
|
+
declared.children === undefined;
|
|
2156
|
+
if (!same)
|
|
2157
|
+
return { ...slots, [SUBTITLE_SLOT]: builtIn };
|
|
2158
|
+
// Same source: its `label` and a tighter `truncate` stand, never a looser one.
|
|
2159
|
+
const truncate = declared.truncate === undefined || builtIn.truncate === undefined
|
|
2160
|
+
? (declared.truncate ?? builtIn.truncate)
|
|
2161
|
+
: Math.min(declared.truncate, builtIn.truncate);
|
|
2162
|
+
return { ...slots, [SUBTITLE_SLOT]: { ...builtIn, label: declared.label, truncate } };
|
|
2163
|
+
}
|
|
2048
2164
|
/**
|
|
2049
2165
|
* Every slot a projection declares, resolved.
|
|
2050
2166
|
*
|
|
@@ -2055,7 +2171,7 @@ function resolveSlot(spec, root, folded, manifest, name) {
|
|
|
2055
2171
|
function resolveSlots(projection, root, folded, manifest) {
|
|
2056
2172
|
const slots = {};
|
|
2057
2173
|
const meta = [];
|
|
2058
|
-
for (const [name, spec] of Object.entries(projection.slots)) {
|
|
2174
|
+
for (const [name, spec] of Object.entries(withDefaultSubtitle(projection.slots, root.kind))) {
|
|
2059
2175
|
if (Array.isArray(spec)) {
|
|
2060
2176
|
for (const one of spec) {
|
|
2061
2177
|
// An array spec collects into `meta`, so the name it was declared under
|
|
@@ -2094,7 +2210,9 @@ function buildObject(args) {
|
|
|
2094
2210
|
* nothing.
|
|
2095
2211
|
*/
|
|
2096
2212
|
const held = {};
|
|
2097
|
-
|
|
2213
|
+
// The built-in subtitle too, or a summary seeded at creation shows on the
|
|
2214
|
+
// card while `summarize` offers a blank to edit (SPEC §6.12).
|
|
2215
|
+
for (const spec of Object.values(withDefaultSubtitle(projection.slots, root.kind)).flat()) {
|
|
2098
2216
|
// `tag` may name several spellings (see `SlotSpec`); the field this slot
|
|
2099
2217
|
// *is* keyed on is the first, which is the one the app writes today. The
|
|
2100
2218
|
// rest are only there to keep older records rendering.
|
|
@@ -2947,8 +3065,9 @@ function parentRefOf(manifest, kind, root, folded = {}) {
|
|
|
2947
3065
|
return prefix.test(moved.value) ? moved.value : undefined;
|
|
2948
3066
|
}
|
|
2949
3067
|
}
|
|
2950
|
-
|
|
2951
|
-
|
|
3068
|
+
const own = ownParentTagOf(manifest, kind);
|
|
3069
|
+
if (own) {
|
|
3070
|
+
return root.tags.find((t) => t[0] === own && t[1] && /^\d+:[0-9a-f]{64}:/.test(t[1]))?.[1];
|
|
2952
3071
|
}
|
|
2953
3072
|
for (const [parentKind, projection] of Object.entries(manifest.projections ?? {})) {
|
|
2954
3073
|
const children = declaredChildSpec(projection);
|
|
@@ -2975,8 +3094,9 @@ function parentRefOf(manifest, kind, root, folded = {}) {
|
|
|
2975
3094
|
* parent it names — SPEC §7.2's `movedBy`, read off whichever projection lists
|
|
2976
3095
|
* `kind` as its children (MAN-1).
|
|
2977
3096
|
*
|
|
2978
|
-
* `parentKind` is absent for a bare file
|
|
2979
|
-
*
|
|
3097
|
+
* `parentKind` is absent for a bare file and for any kind a list declares with
|
|
3098
|
+
* `anyParent` (a document): each may sit under a file of any kind (§6.7), so
|
|
3099
|
+
* the list naming it is not a limit on where it may go.
|
|
2980
3100
|
* Absent too for `match: 'identifier'`, where `movedBy` is ignored because a
|
|
2981
3101
|
* move's value is an address and that list compares identifiers.
|
|
2982
3102
|
*/
|
|
@@ -2985,7 +3105,28 @@ function movedByOf(manifest, kind) {
|
|
|
2985
3105
|
const children = declaredChildSpec(projection);
|
|
2986
3106
|
if (!children || children.kind !== kind || !children.movedBy || children.match === 'identifier')
|
|
2987
3107
|
continue;
|
|
2988
|
-
|
|
3108
|
+
// Any list declaring `anyParent` for the kind lifts the limit, so this and
|
|
3109
|
+
// `ownParentTagOf` never disagree about where the kind may sit.
|
|
3110
|
+
return ownParentTagOf(manifest, kind) !== undefined
|
|
3111
|
+
? { field: children.movedBy }
|
|
3112
|
+
: { field: children.movedBy, parentKind: Number(parentKind) };
|
|
3113
|
+
}
|
|
3114
|
+
return undefined;
|
|
3115
|
+
}
|
|
3116
|
+
/**
|
|
3117
|
+
* The tag a `kind` object names its own parent with, of any kind — `a` on a
|
|
3118
|
+
* bare file (SPEC §6.7), and the `via` of any list declaring the kind with
|
|
3119
|
+
* `anyParent` (a document's, 2026-10-14). Undefined for every other kind,
|
|
3120
|
+
* whose parent is found from the parent's declared list instead.
|
|
3121
|
+
*/
|
|
3122
|
+
function ownParentTagOf(manifest, kind) {
|
|
3123
|
+
if (kind === KIND_BARE_FILE)
|
|
3124
|
+
return 'a';
|
|
3125
|
+
for (const projection of Object.values(manifest.projections ?? {})) {
|
|
3126
|
+
const children = declaredChildSpec(projection);
|
|
3127
|
+
// Strictly `true`: nothing validates a published manifest, and "false" is truthy.
|
|
3128
|
+
if (children?.kind === kind && children.anyParent === true && children.match !== 'identifier')
|
|
3129
|
+
return children.via;
|
|
2989
3130
|
}
|
|
2990
3131
|
return undefined;
|
|
2991
3132
|
}
|
|
@@ -4279,6 +4420,8 @@ const nameOf = (event) => (event ? tagValue(event, 'name') : undefined);
|
|
|
4279
4420
|
/**
|
|
4280
4421
|
* The owners and admins a `kind:39001` lists — kept only when the channel's own
|
|
4281
4422
|
* signer, the relay, signed it: anybody can publish an event of that shape.
|
|
4423
|
+
*
|
|
4424
|
+
* why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/only-owners-and-admins-rename-or-archive-a-folder.md
|
|
4282
4425
|
*/
|
|
4283
4426
|
function folderAdminsOf(admins, channel) {
|
|
4284
4427
|
if (!admins || !channel || admins.pubkey !== channel.pubkey)
|