@lincyaw/kernel 1.0.0-rc.26 → 1.0.0-rc.28
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 +1 -1
- package/src/contracts/document.ts +8 -1
- package/src/document-authoring-actions.ts +8 -4
- package/src/document-comments.ts +30 -37
- package/src/document-components.ts +4 -12
- package/src/document-operations.ts +15 -1
- package/src/document-pages.ts +8 -1
- package/src/document-places.ts +92 -0
- package/src/document-schema.ts +1 -1
- package/src/document.ts +13 -1
- package/src/index.ts +2 -1
- package/src/node/authoring-actions.ts +1 -1
package/package.json
CHANGED
|
@@ -199,6 +199,13 @@ export interface Production {
|
|
|
199
199
|
|
|
200
200
|
/** A stable rich-text/code ID, or `page:${sectionId}` reserved for an existing section title. */
|
|
201
201
|
export interface DocumentTextPoint { blockId: string, offset: number }
|
|
202
|
+
export interface DocumentTextAnchor { from: DocumentTextPoint, to: DocumentTextPoint }
|
|
203
|
+
/** A stable block, optionally at one step that renders it; the step belongs to the block's section. */
|
|
204
|
+
export interface DocumentPlaceAnchor { blockId: BlockId, stepId?: StepId }
|
|
205
|
+
export type DocumentThreadAnchor = DocumentTextAnchor | DocumentPlaceAnchor
|
|
206
|
+
/** A text range and a place are disjoint shapes; read the shape instead of guessing from offsets. */
|
|
207
|
+
export const isDocumentTextAnchor = (anchor: DocumentThreadAnchor | undefined): anchor is DocumentTextAnchor => Boolean(anchor && 'from' in anchor && 'to' in anchor)
|
|
208
|
+
export const isDocumentPlaceAnchor = (anchor: DocumentThreadAnchor | undefined): anchor is DocumentPlaceAnchor => Boolean(anchor && 'blockId' in anchor && !('from' in anchor))
|
|
202
209
|
export interface DocumentComment {
|
|
203
210
|
id: string
|
|
204
211
|
type: 'comment'
|
|
@@ -220,7 +227,7 @@ export interface DocumentThread {
|
|
|
220
227
|
resolvedBy?: string
|
|
221
228
|
metadata?: JsonObject
|
|
222
229
|
deletedAt?: string
|
|
223
|
-
anchor?:
|
|
230
|
+
anchor?: DocumentThreadAnchor
|
|
224
231
|
comments: DocumentComment[]
|
|
225
232
|
}
|
|
226
233
|
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { applyDocumentCaptionTiming } from './document-caption-timings.ts'
|
|
2
2
|
import { hasRole } from './access.ts'
|
|
3
|
-
import { applyDocumentCommentAction, DocumentCommentError, validateDocumentCommentAnchor } from './document-comments.ts'
|
|
3
|
+
import { applyDocumentCommentAction, degradeDocumentCommentAnchor, DocumentCommentError, validateDocumentCommentAnchor } from './document-comments.ts'
|
|
4
|
+
import { documentAnchorKey } from './document-places.ts'
|
|
4
5
|
import { changeDocumentVoice, documentVoiceStepIds, previewDocumentVoiceChange } from './document-voices.ts'
|
|
5
6
|
import { applyDocumentComponentAction } from './document-components.ts'
|
|
6
7
|
import type { DocumentAuthoringAction, DocumentAuthoringActionEffect } from './contracts/authoring-actions.ts'
|
|
@@ -29,17 +30,20 @@ export function applyDocumentAuthoringAction(document: TeachingDocument, action:
|
|
|
29
30
|
return { content, effect: { kind: 'voice', scope: action.scope.kind, value: previewDocumentVoiceChange(document, action.scope, action.source, { replaceOverrides: action.replaceOverrides }), recordings } }
|
|
30
31
|
}
|
|
31
32
|
if (action.type === 'comment.create') validateDocumentCommentAnchor(document, action.anchor ?? undefined)
|
|
32
|
-
let source = document.comments ?? {}, detached = false
|
|
33
|
+
let source = document.comments ?? {}, detached = false, degraded = false
|
|
33
34
|
if (action.type !== 'comment.create' && Object.hasOwn(source, action.threadId)) {
|
|
34
35
|
const thread = source[action.threadId]!
|
|
35
|
-
|
|
36
|
-
|
|
36
|
+
const anchor = degradeDocumentCommentAnchor(document, thread.anchor)
|
|
37
|
+
if (thread.anchor && !anchor) {
|
|
37
38
|
const { anchor: _anchor, ...unanchored } = thread
|
|
38
39
|
source = { ...source, [thread.id]: unanchored }; detached = true
|
|
40
|
+
} else if (anchor && documentAnchorKey(anchor) !== documentAnchorKey(thread.anchor)) {
|
|
41
|
+
source = { ...source, [thread.id]: { ...thread, anchor } }; degraded = true
|
|
39
42
|
}
|
|
40
43
|
}
|
|
41
44
|
const { threads, effect } = applyDocumentCommentAction(source, action, context)
|
|
42
45
|
if (detached) { effect.anchorDetached = true; effect.changed = true }
|
|
46
|
+
else if (degraded) effect.changed = true
|
|
43
47
|
const content = { ...document }
|
|
44
48
|
if (Object.keys(threads).length) content.comments = threads
|
|
45
49
|
else delete content.comments
|
package/src/document-comments.ts
CHANGED
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
import { hasRole } from './access.ts'
|
|
2
2
|
import type { DocumentCommentAction, DocumentCommentContext, DocumentCommentEffect } from './contracts/document-comments.ts'
|
|
3
|
-
import
|
|
3
|
+
import { isDocumentPlaceAnchor, isDocumentTextAnchor } from './contracts/document.ts'
|
|
4
|
+
import { documentBlockSection, documentCommentTargets } from './document-places.ts'
|
|
5
|
+
import type { DocumentComment, DocumentThread, DocumentThreadAnchor, JsonObject, ListItemNode, RichTextNode, TableCellNode, TableRowNode, TeachingDocument } from './contracts/document.ts'
|
|
6
|
+
|
|
7
|
+
export { documentCommentTargets, isDocumentTextLink } from './document-places.ts'
|
|
4
8
|
|
|
5
9
|
export class DocumentCommentError extends Error {
|
|
6
10
|
readonly status: number
|
|
@@ -8,45 +12,19 @@ export class DocumentCommentError extends Error {
|
|
|
8
12
|
}
|
|
9
13
|
function fail(status: number, code: string): never { throw new DocumentCommentError(status, code) }
|
|
10
14
|
|
|
11
|
-
/** Canonical anchor v1 expands only nonempty styled-text links; other inline values are atoms. */
|
|
12
|
-
export function isDocumentTextLink(node: InlineNode): node is Extract<InlineNode, { type: 'link' }> & { children: Extract<InlineNode, { type: 'text' | 'break' }>[] } {
|
|
13
|
-
return node.type === 'link' && node.children.length > 0 && node.children.every(child => child.type === 'text' || child.type === 'break')
|
|
14
|
-
}
|
|
15
|
-
function inlineText(nodes: readonly InlineNode[]): string {
|
|
16
|
-
return nodes.map(node => node.type === 'text' ? node.text : node.type === 'break' ? '\n' : isDocumentTextLink(node) ? inlineText(node.children) : '\uFFFC').join('')
|
|
17
|
-
}
|
|
18
|
-
|
|
19
|
-
/** Only addressable canonical text identities, in native document order; opaque data is never traversed. */
|
|
20
|
-
export function documentCommentTargets(document: TeachingDocument): Map<string, { order: number, text: string }> {
|
|
21
|
-
const targets = new Map<string, { order: number, text: string }>()
|
|
22
|
-
const add = (id: string, text: string) => { targets.set(id, { order: targets.size, text }) }
|
|
23
|
-
const rich = (node: RichTextNode): void => {
|
|
24
|
-
if (node.type === 'paragraph' || node.type === 'heading') add(node.id, inlineText(node.children))
|
|
25
|
-
else if (node.type === 'code') add(node.id, node.value)
|
|
26
|
-
else if (node.type === 'list') for (const item of node.children) {
|
|
27
|
-
const [first, ...rest] = item.children
|
|
28
|
-
add(item.id, first?.type === 'paragraph' ? inlineText(first.children) : '')
|
|
29
|
-
;(first?.type === 'paragraph' ? rest : item.children).forEach(rich)
|
|
30
|
-
}
|
|
31
|
-
else if (node.type === 'blockquote') {
|
|
32
|
-
const [first, ...rest] = node.children
|
|
33
|
-
if (first?.type === 'paragraph') { add(node.id, inlineText(first.children)); rest.forEach(rich) }
|
|
34
|
-
else node.children.forEach(rich)
|
|
35
|
-
} else if (node.type === 'table') for (const row of node.children) for (const cell of row.children) add(cell.id, inlineText(cell.children))
|
|
36
|
-
}
|
|
37
|
-
const block = (id: string): void => {
|
|
38
|
-
const value = document.blocks[id]
|
|
39
|
-
if (value?.type === 'text') value.content.forEach(rich)
|
|
40
|
-
else if (value?.type === 'code' && value.value !== undefined) add(id, value.value)
|
|
41
|
-
else if (value?.type === 'container' || value?.type === 'component') value.children?.forEach(block)
|
|
42
|
-
}
|
|
43
|
-
for (const id of document.sectionOrder) { const page = document.sections[id]!; add(`page:${id}`, page.title); page.children.forEach(block) }
|
|
44
|
-
return targets
|
|
45
|
-
}
|
|
46
|
-
|
|
47
15
|
/** No ordinal, offset clamping, surrogate splitting or guessed fallback identity. */
|
|
48
16
|
export function validateDocumentCommentAnchor(document: TeachingDocument, anchor: DocumentThread['anchor']): void {
|
|
49
17
|
if (!anchor) return
|
|
18
|
+
if (isDocumentPlaceAnchor(anchor)) {
|
|
19
|
+
if (!Object.hasOwn(document.blocks, anchor.blockId)) fail(422, 'comment-anchor-target-unavailable')
|
|
20
|
+
if (anchor.stepId !== undefined) {
|
|
21
|
+
const step = Object.hasOwn(document.steps, anchor.stepId) ? document.steps[anchor.stepId] : undefined
|
|
22
|
+
const section = step ? document.sections[step.sectionId] : undefined
|
|
23
|
+
if (!step || !section || !section.stepOrder.includes(anchor.stepId) || step.sectionId !== documentBlockSection(document, anchor.blockId)) fail(422, 'comment-anchor-target-unavailable')
|
|
24
|
+
}
|
|
25
|
+
return
|
|
26
|
+
}
|
|
27
|
+
if (!isDocumentTextAnchor(anchor)) fail(422, 'comment-anchor-target-unavailable')
|
|
50
28
|
const targets = documentCommentTargets(document), a = targets.get(anchor.from.blockId), b = targets.get(anchor.to.blockId)
|
|
51
29
|
if (!a || !b) fail(422, 'comment-anchor-target-unavailable')
|
|
52
30
|
for (const [point, target] of [[anchor.from, a], [anchor.to, b]] as const) {
|
|
@@ -57,6 +35,21 @@ export function validateDocumentCommentAnchor(document: TeachingDocument, anchor
|
|
|
57
35
|
if (a.order > b.order || a.order === b.order && anchor.from.offset >= anchor.to.offset) fail(422, 'comment-anchor-range-invalid')
|
|
58
36
|
}
|
|
59
37
|
|
|
38
|
+
/**
|
|
39
|
+
* The strongest still-valid anchor. A place whose step no longer exists keeps the block; a missing block or an
|
|
40
|
+
* unmappable text range leaves the discussion explicitly unanchored rather than silently pointing elsewhere.
|
|
41
|
+
*/
|
|
42
|
+
export function degradeDocumentCommentAnchor(document: TeachingDocument, anchor: DocumentThreadAnchor | undefined): DocumentThreadAnchor | undefined {
|
|
43
|
+
if (!anchor) return undefined
|
|
44
|
+
try { validateDocumentCommentAnchor(document, anchor); return anchor }
|
|
45
|
+
catch (error) { if (!(error instanceof DocumentCommentError) || error.status !== 422) throw error }
|
|
46
|
+
if (isDocumentPlaceAnchor(anchor) && anchor.stepId !== undefined && Object.hasOwn(document.blocks, anchor.blockId)) {
|
|
47
|
+
const place: DocumentThreadAnchor = { blockId: anchor.blockId }
|
|
48
|
+
try { validateDocumentCommentAnchor(document, place); return place } catch { /* The block itself is not addressable. */ }
|
|
49
|
+
}
|
|
50
|
+
return undefined
|
|
51
|
+
}
|
|
52
|
+
|
|
60
53
|
/** Shared native/editor permissions: editors may delete any discussion, but edit their own comment; a document owner may manage earlier authors. */
|
|
61
54
|
export function applyDocumentCommentAction(source: NonNullable<TeachingDocument['comments']>, action: DocumentCommentAction, context: DocumentCommentContext): { threads: NonNullable<TeachingDocument['comments']>, effect: DocumentCommentEffect } {
|
|
62
55
|
const member = context.member
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import jsonPatch from 'fast-json-patch'
|
|
2
2
|
import type { Operation } from 'fast-json-patch'
|
|
3
3
|
import { validateDocument } from './document.ts'
|
|
4
|
+
import { documentBlockSection } from './document-places.ts'
|
|
4
5
|
import { documentParameterAccess } from './parameters.ts'
|
|
5
6
|
import { DOCUMENT_PARAMETER_MAX_CHANGES, DOCUMENT_PARAMETER_MAX_PATH_DEPTH } from './contracts/authoring-actions.ts'
|
|
6
7
|
import type { DocumentComponentAction, DocumentComponentEffect, DocumentParameterChange } from './contracts/authoring-actions.ts'
|
|
@@ -26,18 +27,9 @@ function component(document: TeachingDocument, id: string): ComponentBlock {
|
|
|
26
27
|
}
|
|
27
28
|
export function documentComponentSection(document: TeachingDocument, blockId: string): string {
|
|
28
29
|
component(document, blockId)
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
const id = pending.pop()!
|
|
33
|
-
if (id === blockId) return sectionId
|
|
34
|
-
if (seen.has(id)) continue
|
|
35
|
-
seen.add(id)
|
|
36
|
-
const block = document.blocks[id]
|
|
37
|
-
if (block?.type === 'container' || block?.type === 'component') pending.push(...block.children ?? [])
|
|
38
|
-
}
|
|
39
|
-
}
|
|
40
|
-
return fail(422, 'component-block-owner-missing', { blockId })
|
|
30
|
+
const section = documentBlockSection(document, blockId)
|
|
31
|
+
if (!section) return fail(422, 'component-block-owner-missing', { blockId })
|
|
32
|
+
return section
|
|
41
33
|
}
|
|
42
34
|
function stepOf(document: TeachingDocument, stepId: string, sectionId: string) {
|
|
43
35
|
const step = own(document.steps, stepId) ? document.steps[stepId] : undefined
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { isDocumentPlaceAnchor } from './contracts/document.ts'
|
|
2
|
+
import { degradeDocumentCommentAnchor } from './document-comments.ts'
|
|
1
3
|
import type { DocumentBlock, DocumentEditOperation, TeachingDocument } from './contracts/document.ts'
|
|
2
4
|
|
|
3
5
|
/** Operations describe author intent; the caller validates the resulting complete document before committing it. */
|
|
@@ -69,6 +71,14 @@ export function applyDocumentOperations(source: TeachingDocument, operations: re
|
|
|
69
71
|
if (!targetSteps.has(value.id)) value.visuals = value.visuals.filter(visual => !moved.has(visual.blockId))
|
|
70
72
|
else for (const id of moved) if (!value.visuals.some(visual => visual.blockId === id)) value.visuals.push({ blockId: id, visible: true })
|
|
71
73
|
}
|
|
74
|
+
// A step belongs to one section; a place comment stays on the block when that step no longer renders it.
|
|
75
|
+
for (const thread of Object.values(document.comments ?? {})) {
|
|
76
|
+
const anchor = thread.anchor
|
|
77
|
+
if (!anchor || !isDocumentPlaceAnchor(anchor) || anchor.stepId === undefined || !moved.has(anchor.blockId)) continue
|
|
78
|
+
const degraded = degradeDocumentCommentAnchor(document, anchor)
|
|
79
|
+
if (degraded) thread.anchor = degraded
|
|
80
|
+
else delete thread.anchor
|
|
81
|
+
}
|
|
72
82
|
break
|
|
73
83
|
}
|
|
74
84
|
case 'deleteBlock': {
|
|
@@ -82,7 +92,11 @@ export function applyDocumentOperations(source: TeachingDocument, operations: re
|
|
|
82
92
|
}
|
|
83
93
|
for (const id of removed) visit(block(id))
|
|
84
94
|
// A deleted range becomes an unanchored thread; its discussion survives.
|
|
85
|
-
for (const thread of Object.values(document.comments ?? {}))
|
|
95
|
+
for (const thread of Object.values(document.comments ?? {})) {
|
|
96
|
+
const anchor = thread.anchor
|
|
97
|
+
if (!anchor) continue
|
|
98
|
+
if (isDocumentPlaceAnchor(anchor) ? identities.has(anchor.blockId) : identities.has(anchor.from.blockId) || identities.has(anchor.to.blockId)) delete thread.anchor
|
|
99
|
+
}
|
|
86
100
|
detach(operation.blockId)
|
|
87
101
|
for (const id of removed) delete document.blocks[id]
|
|
88
102
|
for (const value of Object.values(document.steps)) value.visuals = value.visuals.filter(visual => !removed.has(visual.blockId))
|
package/src/document-pages.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { isDocumentPlaceAnchor } from './contracts/document.ts'
|
|
1
2
|
import type { ListItemNode, RichTextNode, TableCellNode, TableRowNode, TeachingDocument } from './contracts/document.ts'
|
|
2
3
|
import type { DocumentPageDeletionImpact, DocumentPageIds } from './contracts/authoring.ts'
|
|
3
4
|
import type { PageDeletePlan } from './contracts/workspace.ts'
|
|
@@ -89,7 +90,13 @@ export function pageDeletionImpact(document: TeachingDocument, section: string):
|
|
|
89
90
|
for (const id of blocks) { const block = document.blocks[id]; if (block?.type === 'text') block.content.forEach(rich) }
|
|
90
91
|
return { sectionId: section, retainedEmpty: document.sectionOrder.length === 1, blocks: [...blocks], steps: [...steps], narrations: [...removed], retainedNarrations: [...candidates].filter(id => !removed.has(id)), cues,
|
|
91
92
|
clips: document.production.mediaClips.filter(clip => steps.has(clip.attachment.stepId)).map(clip => clip.id),
|
|
92
|
-
detachedComments: Object.values(document.comments ?? {}).filter(thread =>
|
|
93
|
+
detachedComments: Object.values(document.comments ?? {}).filter(thread => {
|
|
94
|
+
const anchor = thread.anchor
|
|
95
|
+
if (!anchor) return false
|
|
96
|
+
return isDocumentPlaceAnchor(anchor)
|
|
97
|
+
? targets.has(anchor.blockId) || Boolean(anchor.stepId && steps.has(anchor.stepId))
|
|
98
|
+
: targets.has(anchor.from.blockId) || targets.has(anchor.to.blockId)
|
|
99
|
+
}).map(thread => thread.id), references }
|
|
93
100
|
}
|
|
94
101
|
|
|
95
102
|
export function pageDeletion(document: TeachingDocument, directory: string, version: string, section: string): PageDeletePlan {
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
import { isDocumentPlaceAnchor, isDocumentTextAnchor } from './contracts/document.ts'
|
|
2
|
+
import type { DocumentThreadAnchor, InlineNode, RichTextNode, TeachingDocument } from './contracts/document.ts'
|
|
3
|
+
|
|
4
|
+
/** The stable places a discussion can point at, in document order. */
|
|
5
|
+
export interface DocumentPlacesVisitor {
|
|
6
|
+
/** A page title or a block. */
|
|
7
|
+
place(id: string): void
|
|
8
|
+
/** An addressable text identity: a rich-text node, a code block or a page title. */
|
|
9
|
+
text(id: string, text: string): void
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
/** Canonical anchor v1 expands only nonempty styled-text links; other inline values are atoms. */
|
|
13
|
+
export function isDocumentTextLink(node: InlineNode): node is Extract<InlineNode, { type: 'link' }> & { children: Extract<InlineNode, { type: 'text' | 'break' }>[] } {
|
|
14
|
+
return node.type === 'link' && node.children.length > 0 && node.children.every(child => child.type === 'text' || child.type === 'break')
|
|
15
|
+
}
|
|
16
|
+
function inlineText(nodes: readonly InlineNode[]): string {
|
|
17
|
+
return nodes.map(node => node.type === 'text' ? node.text : node.type === 'break' ? '\n' : isDocumentTextLink(node) ? inlineText(node.children) : '\uFFFC').join('')
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* One walk over the document's stable places. Only addressable canonical identities are visited; opaque plugin
|
|
22
|
+
* data is never traversed. A caller that only needs text targets can ignore `place`.
|
|
23
|
+
*/
|
|
24
|
+
export function walkDocumentPlaces(document: TeachingDocument, visit: DocumentPlacesVisitor): void {
|
|
25
|
+
const rich = (node: RichTextNode): void => {
|
|
26
|
+
if (node.type === 'paragraph' || node.type === 'heading') visit.text(node.id, inlineText(node.children))
|
|
27
|
+
else if (node.type === 'code') visit.text(node.id, node.value)
|
|
28
|
+
else if (node.type === 'list') for (const item of node.children) {
|
|
29
|
+
const [first, ...rest] = item.children
|
|
30
|
+
visit.text(item.id, first?.type === 'paragraph' ? inlineText(first.children) : '')
|
|
31
|
+
;(first?.type === 'paragraph' ? rest : item.children).forEach(rich)
|
|
32
|
+
}
|
|
33
|
+
else if (node.type === 'blockquote') {
|
|
34
|
+
const [first, ...rest] = node.children
|
|
35
|
+
if (first?.type === 'paragraph') { visit.text(node.id, inlineText(first.children)); rest.forEach(rich) }
|
|
36
|
+
else node.children.forEach(rich)
|
|
37
|
+
} else if (node.type === 'table') for (const row of node.children) for (const cell of row.children) visit.text(cell.id, inlineText(cell.children))
|
|
38
|
+
}
|
|
39
|
+
const block = (id: string): void => {
|
|
40
|
+
visit.place(id)
|
|
41
|
+
const value = document.blocks[id]
|
|
42
|
+
if (value?.type === 'text') value.content.forEach(rich)
|
|
43
|
+
else if (value?.type === 'code' && value.value !== undefined) visit.text(id, value.value)
|
|
44
|
+
else if (value?.type === 'container' || value?.type === 'component') value.children?.forEach(block)
|
|
45
|
+
}
|
|
46
|
+
for (const id of document.sectionOrder) {
|
|
47
|
+
const page = document.sections[id]
|
|
48
|
+
if (!page) continue
|
|
49
|
+
visit.place(`page:${id}`)
|
|
50
|
+
visit.text(`page:${id}`, page.title)
|
|
51
|
+
page.children.forEach(block)
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Only addressable canonical text identities, in native document order; opaque data is never traversed. */
|
|
56
|
+
export function documentCommentTargets(document: TeachingDocument): Map<string, { order: number, text: string }> {
|
|
57
|
+
const targets = new Map<string, { order: number, text: string }>()
|
|
58
|
+
walkDocumentPlaces(document, { place() {}, text: (id, text) => { targets.set(id, { order: targets.size, text }) } })
|
|
59
|
+
return targets
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** Every anchorable place in document order: page titles, blocks and text identities on one scale. */
|
|
63
|
+
export function documentAnchorOrder(document: TeachingDocument): Map<string, number> {
|
|
64
|
+
const places = new Map<string, number>()
|
|
65
|
+
const add = (id: string) => { if (!places.has(id)) places.set(id, places.size) }
|
|
66
|
+
walkDocumentPlaces(document, { place: add, text: add })
|
|
67
|
+
return places
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** The section that owns a block, following container and component children. */
|
|
71
|
+
export function documentBlockSection(document: TeachingDocument, blockId: string): string | undefined {
|
|
72
|
+
for (const sectionId of document.sectionOrder) {
|
|
73
|
+
const pending = [...document.sections[sectionId]!.children], seen = new Set<string>()
|
|
74
|
+
while (pending.length) {
|
|
75
|
+
const id = pending.pop()!
|
|
76
|
+
if (id === blockId) return sectionId
|
|
77
|
+
if (seen.has(id)) continue
|
|
78
|
+
seen.add(id)
|
|
79
|
+
const block = document.blocks[id]
|
|
80
|
+
if (block?.type === 'container' || block?.type === 'component') pending.push(...block.children ?? [])
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
return undefined
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** A key-order independent identity for comparing a thread anchor with a draft target. */
|
|
87
|
+
export function documentAnchorKey(anchor: DocumentThreadAnchor | undefined): string | undefined {
|
|
88
|
+
if (!anchor) return undefined
|
|
89
|
+
if (isDocumentPlaceAnchor(anchor)) return JSON.stringify(['place', anchor.blockId, anchor.stepId ?? null])
|
|
90
|
+
if (!isDocumentTextAnchor(anchor)) return undefined
|
|
91
|
+
return JSON.stringify(['text', anchor.from.blockId, anchor.from.offset, anchor.to.blockId, anchor.to.offset])
|
|
92
|
+
}
|
package/src/document-schema.ts
CHANGED
|
@@ -80,6 +80,6 @@ export const DOCUMENT_JSON_SCHEMA: Schema = {
|
|
|
80
80
|
Production: object({ defaults: ref('StepProduction'), sectionOverrides: record(ref('StepProduction')), stepOverrides: record(ref('StepProduction')), narrationOverrides: record(object({ narrationStart: { enum: ['with-animation', 'after-animation'] } })), cueTimings: record(object({ pauseMs: nonnegative })), captionTimings: record(ref('CaptionTiming')), mediaClips: list(ref('MediaClip')) }, ['defaults', 'stepOverrides', 'mediaClips']),
|
|
81
81
|
TextPoint: object({ blockId: { type: 'string', minLength: 1, maxLength: 205 }, offset: integer }),
|
|
82
82
|
Comment: object({ id, type: tag('comment'), userId: id, createdAt: string, updatedAt: string, deletedAt: string, content: list(ref('RichTextNode')), metadata: ref('JsonObject'), reactions: list(object({ emoji: string, createdAt: string, userIds: ids })) }, ['id', 'type', 'userId', 'createdAt', 'updatedAt', 'reactions']),
|
|
83
|
-
Thread: object({ id, type: tag('thread'), createdAt: string, updatedAt: string, resolved: { type: 'boolean' }, resolvedUpdatedAt: string, resolvedBy: id, metadata: ref('JsonObject'), deletedAt: string, anchor: object({ from: ref('TextPoint'), to: ref('TextPoint') }), comments: list(ref('Comment')) }, ['id', 'type', 'createdAt', 'updatedAt', 'resolved', 'comments']),
|
|
83
|
+
Thread: object({ id, type: tag('thread'), createdAt: string, updatedAt: string, resolved: { type: 'boolean' }, resolvedUpdatedAt: string, resolvedBy: id, metadata: ref('JsonObject'), deletedAt: string, anchor: { oneOf: [object({ from: ref('TextPoint'), to: ref('TextPoint') }), object({ blockId: id, stepId: id }, ['blockId'])] }, comments: list(ref('Comment')) }, ['id', 'type', 'createdAt', 'updatedAt', 'resolved', 'comments']),
|
|
84
84
|
},
|
|
85
85
|
}
|
package/src/document.ts
CHANGED
|
@@ -3,6 +3,8 @@ import { DOCUMENT_JSON_SCHEMA } from './document-schema.ts'
|
|
|
3
3
|
import { isRecord } from './errors.ts'
|
|
4
4
|
import { captionSourceFingerprint, captionTimingProblem, stepCaptionText } from './document-caption-timings.ts'
|
|
5
5
|
import { validateDocumentParameters } from './parameters.ts'
|
|
6
|
+
import { isDocumentPlaceAnchor } from './contracts/document.ts'
|
|
7
|
+
import { documentBlockSection } from './document-places.ts'
|
|
6
8
|
import type { DocumentIssue, DocumentValidation, RichTextNode, TeachingDocument } from './contracts/document.ts'
|
|
7
9
|
|
|
8
10
|
export { DOCUMENT_JSON_SCHEMA } from './document-schema.ts'
|
|
@@ -240,7 +242,17 @@ export function validateDocument(value: unknown): DocumentValidation {
|
|
|
240
242
|
const path = at('/comments', id)
|
|
241
243
|
if (id !== thread.id) issue(`${path}/id`, 'id.key', 'A thread ID must match its map key.')
|
|
242
244
|
identify(thread.id, `${path}/id`)
|
|
243
|
-
|
|
245
|
+
const anchor = thread.anchor
|
|
246
|
+
if (anchor && isDocumentPlaceAnchor(anchor)) {
|
|
247
|
+
if (!Object.hasOwn(doc.blocks, anchor.blockId)) issue(`${path}/anchor/blockId`, 'comment.target', 'A place comment must name an existing block.')
|
|
248
|
+
else if (anchor.stepId !== undefined) {
|
|
249
|
+
const step = Object.hasOwn(doc.steps, anchor.stepId) ? doc.steps[anchor.stepId] : undefined
|
|
250
|
+
const section = step ? doc.sections[step.sectionId] : undefined
|
|
251
|
+
if (!step || !section || !section.stepOrder.includes(anchor.stepId) || step.sectionId !== documentBlockSection(doc, anchor.blockId)) issue(`${path}/anchor/stepId`, 'comment.target', 'A place comment must name a step of the block\'s own section.')
|
|
252
|
+
}
|
|
253
|
+
} else if (anchor) {
|
|
254
|
+
for (const edge of ['from', 'to'] as const) if (!textTargets.has(anchor[edge].blockId)) issue(`${path}/anchor/${edge}/blockId`, 'comment.target', 'A comment anchor must name a stable rich-text node or section title.')
|
|
255
|
+
}
|
|
244
256
|
for (const [index, comment] of thread.comments.entries()) {
|
|
245
257
|
identify(comment.id, `${path}/comments/${index}/id`)
|
|
246
258
|
comment.content?.forEach((node, child) => rich(node, `${path}/comments/${index}/content/${child}`, new Set()))
|
package/src/index.ts
CHANGED
|
@@ -7,7 +7,8 @@ export { documentOutline, documentPart, DocumentReadError } from './document-rea
|
|
|
7
7
|
export { changeDocumentVoice, documentVoiceStepIds, previewDocumentVoiceChange, resolveDocumentStepVoice } from './document-voices.ts'
|
|
8
8
|
export { DOCUMENT_COLOR_NAMES, documentColorToken, documentColorValue } from './document-colors.ts'
|
|
9
9
|
export type { DocumentColorKind, DocumentColorName } from './document-colors.ts'
|
|
10
|
-
export { applyDocumentCommentAction, isDocumentTextLink, documentCommentTargets, validateDocumentCommentAnchor, DocumentCommentError } from './document-comments.ts'
|
|
10
|
+
export { applyDocumentCommentAction, degradeDocumentCommentAnchor, isDocumentTextLink, documentCommentTargets, validateDocumentCommentAnchor, DocumentCommentError } from './document-comments.ts'
|
|
11
|
+
export { documentAnchorKey, documentAnchorOrder, documentBlockSection, walkDocumentPlaces } from './document-places.ts'
|
|
11
12
|
export { applyDocumentAuthoringAction } from './document-authoring-actions.ts'
|
|
12
13
|
export { applyDocumentComponentAction, effectiveComponentParameters, createDocumentParameterChanges, documentComponentSection, DocumentComponentError } from './document-components.ts'
|
|
13
14
|
export type { DocumentStepVoice, DocumentVoiceImpact, DocumentVoiceOptions, DocumentVoiceScope } from './document-voices.ts'
|
|
@@ -24,7 +24,7 @@ export const DOCUMENT_AUTHORING_ACTION_SCHEMA: Schema = {
|
|
|
24
24
|
...object({ id, source: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.source as unknown as Schema, action: { $ref: '#/$defs/AuthoringAction' } }),
|
|
25
25
|
$defs: { ...(structuredClone(DOCUMENT_JSON_SCHEMA) as Exclude<Schema, boolean>).$defs,
|
|
26
26
|
AuthoringAction: { oneOf: [
|
|
27
|
-
action('comment.create', { content, anchor: { oneOf: [{ type: 'null' }, object({ from: { $ref: '#/$defs/TextPoint' }, to: { $ref: '#/$defs/TextPoint' } })] }, metadata, commentMetadata: metadata }, ['content', 'anchor']),
|
|
27
|
+
action('comment.create', { content, anchor: { oneOf: [{ type: 'null' }, object({ from: { $ref: '#/$defs/TextPoint' }, to: { $ref: '#/$defs/TextPoint' } }), object({ blockId: id, stepId: id }, ['blockId'])] }, metadata, commentMetadata: metadata }, ['content', 'anchor']),
|
|
28
28
|
action('comment.reply', { threadId: id, content, metadata }, ['threadId', 'content']),
|
|
29
29
|
action('comment.update', { threadId: id, commentId: id, content, metadata }, ['threadId', 'commentId', 'content']),
|
|
30
30
|
action('comment.react', { threadId: id, commentId: id, emoji: { type: 'string', minLength: 1, maxLength: 32 }, active: { type: 'boolean' } }),
|