@veltdev/sdk 5.0.2-beta.22 → 5.0.2-beta.23
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/app/models/data/comment-annotation.data.model.d.ts +8 -0
- package/app/models/data/suggestion-events.data.model.d.ts +57 -0
- package/app/models/data/suggestion.data.model.d.ts +267 -0
- package/app/models/element/suggestion-element.model.d.ts +180 -0
- package/app/utils/constants.d.ts +1 -0
- package/app/utils/enums.d.ts +9 -0
- package/models.d.ts +2 -0
- package/package.json +1 -1
- package/types.d.ts +1 -0
- package/velt.js +76 -76
|
@@ -7,6 +7,7 @@ import { CustomAnnotationDropdownItem } from "./custom-chip-dropdown.data.model"
|
|
|
7
7
|
import { CustomCategory, CustomPriority, CustomStatus } from "./custom-filter.data.model";
|
|
8
8
|
import { Location } from "./location.model";
|
|
9
9
|
import { PageInfo } from "./page-info.model";
|
|
10
|
+
import { SuggestionData } from "./suggestion.data.model";
|
|
10
11
|
import { TargetElement } from "./target-element.data.model";
|
|
11
12
|
import { TargetTextRange } from "./target-text-range.data.model";
|
|
12
13
|
import { User } from "./user.data.model";
|
|
@@ -199,6 +200,13 @@ export declare class CommentAnnotation {
|
|
|
199
200
|
viewedByUserIds?: string[];
|
|
200
201
|
viewedBy?: User[];
|
|
201
202
|
unread?: boolean;
|
|
203
|
+
/**
|
|
204
|
+
* SDK-managed suggestion data. Present iff type === 'suggestion'.
|
|
205
|
+
* Customer code must not write to this directly — use the SuggestionElement API.
|
|
206
|
+
*
|
|
207
|
+
* See docs/suggestions-api-contract.md for the full storage model.
|
|
208
|
+
*/
|
|
209
|
+
suggestion?: SuggestionData;
|
|
202
210
|
}
|
|
203
211
|
export declare class GhostComment {
|
|
204
212
|
targetElement?: TargetElement | null;
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { SuggestionEventTypes } from '../../utils/enums';
|
|
2
|
+
import { ApprovedSuggestion, PendingSuggestion, RejectedSuggestion, StaleSuggestion, TargetEditCommitBuilder, TargetEditDetails } from './suggestion.data.model';
|
|
3
|
+
/**
|
|
4
|
+
* Public payload types for the v1 Suggestions feature. Mirrors the layout of
|
|
5
|
+
* `comment-events.data.model.ts` and `recorder-events.data.model.ts`:
|
|
6
|
+
*
|
|
7
|
+
* - One named interface per event payload.
|
|
8
|
+
* - One `SuggestionEventTypesMap` keyed by `SuggestionEventTypes` enum values.
|
|
9
|
+
*
|
|
10
|
+
* Customers pass an event-name string (or the enum constant — they're
|
|
11
|
+
* equivalent) to `velt.getSuggestionElement().on(...)` and receive an
|
|
12
|
+
* `Observable<SuggestionEventTypesMap[T]>`.
|
|
13
|
+
*
|
|
14
|
+
* No separate `actor`/`user` field on the payloads: the user info is on
|
|
15
|
+
* `suggestion.createdBy` (for created) and `suggestion.resolvedBy` (for
|
|
16
|
+
* approved/rejected/stale). Matches the comment-event shape.
|
|
17
|
+
*/
|
|
18
|
+
export interface SuggestionCreatedEvent {
|
|
19
|
+
suggestion: PendingSuggestion;
|
|
20
|
+
timestamp: number;
|
|
21
|
+
}
|
|
22
|
+
export interface SuggestionApprovedEvent {
|
|
23
|
+
suggestion: ApprovedSuggestion;
|
|
24
|
+
timestamp: number;
|
|
25
|
+
}
|
|
26
|
+
export interface SuggestionRejectedEvent {
|
|
27
|
+
suggestion: RejectedSuggestion;
|
|
28
|
+
timestamp: number;
|
|
29
|
+
}
|
|
30
|
+
export interface SuggestionStaleEvent {
|
|
31
|
+
suggestion: StaleSuggestion;
|
|
32
|
+
timestamp: number;
|
|
33
|
+
}
|
|
34
|
+
export interface TargetEditStartEvent {
|
|
35
|
+
details: TargetEditDetails;
|
|
36
|
+
timestamp: number;
|
|
37
|
+
}
|
|
38
|
+
export interface TargetEditCommitEvent {
|
|
39
|
+
details: TargetEditDetails;
|
|
40
|
+
/**
|
|
41
|
+
* Pre-bound builder. Calling it commits the suggestion using the SDK's
|
|
42
|
+
* default summary/metadata, optionally overridden by `result`. If the
|
|
43
|
+
* customer's `onTargetEditCommit` handler already returned a non-null
|
|
44
|
+
* result for this edit, this builder is a no-op so subscribers can't
|
|
45
|
+
* double-commit.
|
|
46
|
+
*/
|
|
47
|
+
commitSuggestion: TargetEditCommitBuilder;
|
|
48
|
+
timestamp: number;
|
|
49
|
+
}
|
|
50
|
+
export type SuggestionEventTypesMap = {
|
|
51
|
+
[SuggestionEventTypes.SUGGESTION_CREATED]: SuggestionCreatedEvent;
|
|
52
|
+
[SuggestionEventTypes.SUGGESTION_APPROVED]: SuggestionApprovedEvent;
|
|
53
|
+
[SuggestionEventTypes.SUGGESTION_REJECTED]: SuggestionRejectedEvent;
|
|
54
|
+
[SuggestionEventTypes.SUGGESTION_STALE]: SuggestionStaleEvent;
|
|
55
|
+
[SuggestionEventTypes.TARGET_EDIT_START]: TargetEditStartEvent;
|
|
56
|
+
[SuggestionEventTypes.TARGET_EDIT_COMMIT]: TargetEditCommitEvent;
|
|
57
|
+
};
|
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Suggestions feature — public type surface for v1.
|
|
3
|
+
*
|
|
4
|
+
* Source contract: docs/suggestions-api-contract.md
|
|
5
|
+
* Source flows: docs/suggestions-implementation-flows.md
|
|
6
|
+
*
|
|
7
|
+
* Types are exported from the SDK's public barrel. Customer code interacts
|
|
8
|
+
* with these via Snippyly.getSuggestionElement(); the SDK constructs all
|
|
9
|
+
* Suggestion objects internally and customers do not build them directly.
|
|
10
|
+
*/
|
|
11
|
+
import { User } from './user.data.model';
|
|
12
|
+
/**
|
|
13
|
+
* Lifecycle state machine for a Suggestion.
|
|
14
|
+
*
|
|
15
|
+
* - pending: Just created, awaiting owner action.
|
|
16
|
+
* - approved: Owner clicked Approve. Customer apply handler ran successfully.
|
|
17
|
+
* - rejected: Owner clicked Reject (with optional reason).
|
|
18
|
+
* - stale: Target was unresolvable at approve time. Owner can dismiss.
|
|
19
|
+
* - apply_failed: Customer apply handler threw during a suggestionApproved event.
|
|
20
|
+
* Status set by the SDK after the throw was caught.
|
|
21
|
+
*/
|
|
22
|
+
export type SuggestionStatus = 'pending' | 'approved' | 'rejected' | 'stale' | 'apply_failed';
|
|
23
|
+
/**
|
|
24
|
+
* Global per-user-per-session suggestion mode. Not persisted; reload returns to 'editing'.
|
|
25
|
+
*/
|
|
26
|
+
export type SuggestionMode = 'editing' | 'suggesting';
|
|
27
|
+
/**
|
|
28
|
+
* Discriminator for the substrate that produced a suggestion. v1: always 'custom'.
|
|
29
|
+
* Wrapper libraries (e.g. tiptap-velt-comments) widen this union when they integrate.
|
|
30
|
+
*
|
|
31
|
+
* Customers should treat unknown values as opaque; the field exists so customer code
|
|
32
|
+
* can differentiate substrate when domain-specific rendering matters.
|
|
33
|
+
*/
|
|
34
|
+
export type SuggestionTargetType = 'custom';
|
|
35
|
+
/**
|
|
36
|
+
* Single-arg config passed to `SuggestionElement.registerTarget(config)`.
|
|
37
|
+
* Carrying both `targetId` and `getter` in one object so the API can grow
|
|
38
|
+
* (e.g., metadata, target-specific options) without breaking customers.
|
|
39
|
+
*/
|
|
40
|
+
export interface RegisterTargetConfig<T = unknown> {
|
|
41
|
+
targetId: string;
|
|
42
|
+
getter: TargetGetter<T>;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Function the customer registers via SuggestionElement.registerTarget(config).
|
|
46
|
+
* Required for any non-primitive (wrapper) target.
|
|
47
|
+
*
|
|
48
|
+
* The SDK calls this getter twice in a typical edit cycle:
|
|
49
|
+
* 1. On focus of the tagged element — to snapshot the pre-edit value.
|
|
50
|
+
* 2. On commit (focusout / change) — to read the current value for the diff.
|
|
51
|
+
*
|
|
52
|
+
* IMPORTANT — edit-time state, not persisted state: the getter must reflect
|
|
53
|
+
* what the user is currently editing, not what's persisted in the customer's
|
|
54
|
+
* app store. If the customer's state is only updated on commit/approve (as
|
|
55
|
+
* is typical when suggesting mode is on), reading from that state would
|
|
56
|
+
* return the snapshot value at commit time, the diff check would short-
|
|
57
|
+
* circuit, and no suggestion would ever fire.
|
|
58
|
+
*
|
|
59
|
+
* Recommended: read from the DOM (controlled or uncontrolled inputs) so the
|
|
60
|
+
* getter always returns what's visible to the user.
|
|
61
|
+
*
|
|
62
|
+
* el.registerTarget('row.123', () => ({
|
|
63
|
+
* qty: parseInt(qtyInput.value, 10),
|
|
64
|
+
* price: parseInt(priceInput.value, 10),
|
|
65
|
+
* }));
|
|
66
|
+
*
|
|
67
|
+
* For controlled inputs (state updates on every keystroke), reading from
|
|
68
|
+
* the customer state is fine: `() => myState.row123`. The contract is
|
|
69
|
+
* "edit-time state" — whichever source of truth has it.
|
|
70
|
+
*/
|
|
71
|
+
export type TargetGetter<T = unknown> = () => T;
|
|
72
|
+
/**
|
|
73
|
+
* Returned from SuggestionElement.on(...). Calling it removes the handler.
|
|
74
|
+
*/
|
|
75
|
+
export type Unsubscribe = () => void;
|
|
76
|
+
/**
|
|
77
|
+
* Details about a target edit, passed to the customer's resolver handler and
|
|
78
|
+
* to subscribers of `targetEditStart` / `targetEditCommit` events.
|
|
79
|
+
*
|
|
80
|
+
* `element` is the DOM element that produced the edit. It's the tagged
|
|
81
|
+
* descendant — or, for wrappers that nest interactive controls inside a
|
|
82
|
+
* tagged container, the inner element that actually fired the event. In
|
|
83
|
+
* either case the SDK walks up to the nearest ancestor carrying
|
|
84
|
+
* `data-velt-suggestion-target` to resolve `targetId`.
|
|
85
|
+
*
|
|
86
|
+
* `element` is provided for read access only — customers should not retain
|
|
87
|
+
* the reference past the synchronous handler call.
|
|
88
|
+
*/
|
|
89
|
+
export interface TargetEditDetails<T = unknown> {
|
|
90
|
+
targetId: string;
|
|
91
|
+
oldValue: T;
|
|
92
|
+
newValue: T;
|
|
93
|
+
element: Element | null;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Return type of `onTargetEditCommit`. Returning a value auto-commits the
|
|
97
|
+
* suggestion using the (optional) overrides; returning null skips the
|
|
98
|
+
* auto-commit so a subscriber to `targetEditCommit` can drive it explicitly.
|
|
99
|
+
*/
|
|
100
|
+
export interface TargetEditCommitResult {
|
|
101
|
+
/** Override the SDK's default `${targetId}: ${old} → ${new}` summary. */
|
|
102
|
+
summary?: string;
|
|
103
|
+
/** Customer metadata persisted on the resulting Suggestion. */
|
|
104
|
+
metadata?: Record<string, unknown>;
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* Return type of `onTargetEditStart`. Reserved for future fields; v1 has
|
|
108
|
+
* no behavior-bearing return values, so customers may omit a return.
|
|
109
|
+
*
|
|
110
|
+
* Roadmap: future versions may accept `{ oldValue }` here so customers can
|
|
111
|
+
* override the SDK's auto-snapshot with a domain-canonical value.
|
|
112
|
+
*/
|
|
113
|
+
export interface TargetEditStartResult {
|
|
114
|
+
}
|
|
115
|
+
export type TargetEditStartHandler<T = unknown> = (details: TargetEditDetails<T>) => TargetEditStartResult | void | null;
|
|
116
|
+
export type TargetEditCommitHandler<T = unknown> = (details: TargetEditDetails<T>) => TargetEditCommitResult | null;
|
|
117
|
+
/**
|
|
118
|
+
* Config passed to `SuggestionElement.enableSuggestionMode(config?)`.
|
|
119
|
+
* Both callbacks are optional. If `onTargetEditCommit` is omitted, customers
|
|
120
|
+
* can still drive auto-commit by subscribing to the `targetEditCommit` event
|
|
121
|
+
* and calling the pre-bound `commitSuggestion` builder on the payload.
|
|
122
|
+
*/
|
|
123
|
+
export interface EnableSuggestionModeConfig {
|
|
124
|
+
/**
|
|
125
|
+
* Invoked on focus of a tagged element, after the SDK captures the
|
|
126
|
+
* snapshot. v1: informational — return value is reserved for future
|
|
127
|
+
* use (e.g. `{ oldValue }` to override the SDK's auto-snapshot).
|
|
128
|
+
*/
|
|
129
|
+
onTargetEditStart?: TargetEditStartHandler;
|
|
130
|
+
/**
|
|
131
|
+
* Invoked once per detected commit (on `change` for atomic inputs, on
|
|
132
|
+
* `focusout` for text-like inputs). Returning a `TargetEditCommitResult`
|
|
133
|
+
* auto-commits with the supplied summary/metadata; returning null defers
|
|
134
|
+
* to event subscribers.
|
|
135
|
+
*/
|
|
136
|
+
onTargetEditCommit?: TargetEditCommitHandler;
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* SDK-managed suggestion data persisted on a CommentAnnotation.
|
|
140
|
+
* Present iff annotation.type === 'suggestion'.
|
|
141
|
+
*
|
|
142
|
+
* Customer code must not write to this directly — use the SuggestionElement API.
|
|
143
|
+
*/
|
|
144
|
+
export interface SuggestionData {
|
|
145
|
+
/** Lifecycle state machine. */
|
|
146
|
+
status: SuggestionStatus;
|
|
147
|
+
/** Stable, customer-owned target identifier. */
|
|
148
|
+
targetId: string;
|
|
149
|
+
/** v1: always 'custom'. Wrappers widen later. */
|
|
150
|
+
targetType: SuggestionTargetType;
|
|
151
|
+
/** Snapshot taken at startSuggestion / focus time. Frozen via structuredClone. */
|
|
152
|
+
oldValue: any;
|
|
153
|
+
/** Value submitted via commitSuggestion. */
|
|
154
|
+
newValue: any;
|
|
155
|
+
/** Optional human-readable description for logs / notifications. */
|
|
156
|
+
summary: string | null;
|
|
157
|
+
/**
|
|
158
|
+
* True if the live value at approve time differed from oldValue.
|
|
159
|
+
* v1 records flag only; v1.1 will surface a confirmation prompt.
|
|
160
|
+
*/
|
|
161
|
+
driftDetected: boolean;
|
|
162
|
+
/** Populated only when status === 'rejected'. */
|
|
163
|
+
rejectReason: string | null;
|
|
164
|
+
/**
|
|
165
|
+
* Full User snapshot of the resolver, populated when status moves to
|
|
166
|
+
* approved | rejected | stale | apply_failed. Snapshot rather than userId
|
|
167
|
+
* so customer code can render name/email/photoUrl without an extra lookup,
|
|
168
|
+
* and so historical suggestions retain their resolver record even if the
|
|
169
|
+
* user later updates their profile.
|
|
170
|
+
*/
|
|
171
|
+
resolvedBy: User | null;
|
|
172
|
+
resolvedAt: number | null;
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* Fields shared across every Suggestion regardless of status.
|
|
176
|
+
* Internal — used to build the per-status discriminated types below.
|
|
177
|
+
*/
|
|
178
|
+
interface SuggestionBase<T = unknown> {
|
|
179
|
+
/** Annotation document id (same as the underlying CommentAnnotation.annotationId). */
|
|
180
|
+
annotationId: string;
|
|
181
|
+
/** Stable, customer-owned target identifier. */
|
|
182
|
+
targetId: string;
|
|
183
|
+
/** v1: always 'custom'. */
|
|
184
|
+
targetType: SuggestionTargetType;
|
|
185
|
+
/** Snapshot taken at startSuggestion / focus time. */
|
|
186
|
+
oldValue: T;
|
|
187
|
+
/** Value submitted via commitSuggestion. */
|
|
188
|
+
newValue: T;
|
|
189
|
+
/** Optional human-readable description. */
|
|
190
|
+
summary: string | null;
|
|
191
|
+
/** Customer-defined metadata supplied via CommitSuggestionConfig.metadata. */
|
|
192
|
+
metadata: Record<string, any>;
|
|
193
|
+
/** True iff the live value at approve time differed from oldValue. */
|
|
194
|
+
driftDetected: boolean;
|
|
195
|
+
/**
|
|
196
|
+
* User of the suggestion's creator (sourced from annotation.from).
|
|
197
|
+
*/
|
|
198
|
+
createdBy?: User;
|
|
199
|
+
createdAt: number;
|
|
200
|
+
}
|
|
201
|
+
/** A suggestion in the 'pending' state — newly created, no owner action yet. */
|
|
202
|
+
export interface PendingSuggestion<T = unknown> extends SuggestionBase<T> {
|
|
203
|
+
status: 'pending';
|
|
204
|
+
rejectReason: null;
|
|
205
|
+
resolvedBy: null;
|
|
206
|
+
resolvedAt: null;
|
|
207
|
+
}
|
|
208
|
+
/** A suggestion that has been approved (apply handler success or pending invocation). */
|
|
209
|
+
export interface ApprovedSuggestion<T = unknown> extends SuggestionBase<T> {
|
|
210
|
+
status: 'approved' | 'apply_failed';
|
|
211
|
+
rejectReason: null;
|
|
212
|
+
resolvedBy: User;
|
|
213
|
+
resolvedAt: number;
|
|
214
|
+
}
|
|
215
|
+
/**
|
|
216
|
+
* A suggestion that has been rejected. `rejectReason` may be null when the
|
|
217
|
+
* rejecter dismissed without supplying a reason — matches the persisted
|
|
218
|
+
* `SuggestionData.rejectReason: string | null` shape.
|
|
219
|
+
*/
|
|
220
|
+
export interface RejectedSuggestion<T = unknown> extends SuggestionBase<T> {
|
|
221
|
+
status: 'rejected';
|
|
222
|
+
rejectReason: string | null;
|
|
223
|
+
resolvedBy: User;
|
|
224
|
+
resolvedAt: number;
|
|
225
|
+
}
|
|
226
|
+
/** A suggestion whose target was unresolvable at approve time. */
|
|
227
|
+
export interface StaleSuggestion<T = unknown> extends SuggestionBase<T> {
|
|
228
|
+
status: 'stale';
|
|
229
|
+
rejectReason: null;
|
|
230
|
+
resolvedBy: User | null;
|
|
231
|
+
resolvedAt: number | null;
|
|
232
|
+
}
|
|
233
|
+
/**
|
|
234
|
+
* Public Suggestion — discriminated union keyed by `status`. TypeScript narrows
|
|
235
|
+
* field types per status (e.g. `resolvedBy: User` is non-null on approved/rejected,
|
|
236
|
+
* `rejectReason: string | null` on rejected since one-click reject without a reason
|
|
237
|
+
* is supported).
|
|
238
|
+
*/
|
|
239
|
+
export type Suggestion<T = unknown> = PendingSuggestion<T> | ApprovedSuggestion<T> | RejectedSuggestion<T> | StaleSuggestion<T>;
|
|
240
|
+
export interface CommitSuggestionConfig<T = unknown> {
|
|
241
|
+
/**
|
|
242
|
+
* Must be registered (via data-velt-target attribute or registerTarget call)
|
|
243
|
+
* before commit, otherwise the suggestion is rejected with a dev-mode warning.
|
|
244
|
+
*/
|
|
245
|
+
targetId: string;
|
|
246
|
+
/** Any JSON-serializable value. Customer's apply handler interprets it. */
|
|
247
|
+
newValue: T;
|
|
248
|
+
/** Optional human-readable string for logs and notifications. */
|
|
249
|
+
summary?: string;
|
|
250
|
+
/** Optional customer-defined metadata. Stored on Suggestion.metadata. */
|
|
251
|
+
metadata?: Record<string, unknown>;
|
|
252
|
+
}
|
|
253
|
+
/**
|
|
254
|
+
* Pre-bound builder attached to `targetEditCommit` payloads. Calling it
|
|
255
|
+
* commits the suggestion with the SDK's default summary/metadata, optionally
|
|
256
|
+
* overridden by `result`. If the customer's `onTargetEditCommit` handler
|
|
257
|
+
* already returned a non-null result for this edit, this builder is a no-op
|
|
258
|
+
* (resolves immediately) so subscribers can't double-commit.
|
|
259
|
+
*/
|
|
260
|
+
export type TargetEditCommitBuilder = (result?: TargetEditCommitResult) => Promise<{
|
|
261
|
+
id: string;
|
|
262
|
+
} | null>;
|
|
263
|
+
export interface SuggestionGetSuggestionsFilter {
|
|
264
|
+
targetId?: string;
|
|
265
|
+
status?: SuggestionStatus | SuggestionStatus[];
|
|
266
|
+
}
|
|
267
|
+
export {};
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
// @ts-nocheck
|
|
2
|
+
import { Observable } from "rxjs";
|
|
3
|
+
import { SuggestionEventType } from "../../utils/enums";
|
|
4
|
+
import { SuggestionEventTypesMap } from "../data/suggestion-events.data.model";
|
|
5
|
+
import { CommitSuggestionConfig, EnableSuggestionModeConfig, RegisterTargetConfig, Suggestion, SuggestionGetSuggestionsFilter } from "../data/suggestion.data.model";
|
|
6
|
+
|
|
7
|
+
export declare class SuggestionElement {
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Turn on suggestion mode for this user/session and (optionally) register
|
|
11
|
+
* the onTargetEditStart / onTargetEditCommit callbacks the SDK invokes
|
|
12
|
+
* during the auto-detect edit lifecycle.
|
|
13
|
+
*
|
|
14
|
+
* Re-calling with a new config replaces the previous callbacks.
|
|
15
|
+
*/
|
|
16
|
+
enableSuggestionMode: (config?: EnableSuggestionModeConfig) => void;
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Turn off suggestion mode and clear any registered callbacks.
|
|
20
|
+
*/
|
|
21
|
+
disableSuggestionMode: () => void;
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Synchronous read of the current enable flag.
|
|
25
|
+
*/
|
|
26
|
+
isSuggestionModeEnabled: () => boolean;
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Reactive enable-flag stream; deduplicated.
|
|
30
|
+
*/
|
|
31
|
+
isSuggestionModeEnabled$: () => Observable<boolean>;
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Register a getter that returns the current value of a tagged target.
|
|
35
|
+
* Required for non-primitive (wrapper) targets — the SDK calls this on
|
|
36
|
+
* focus to snapshot the pre-edit value, and again on commit for the diff.
|
|
37
|
+
*
|
|
38
|
+
* The getter must reflect edit-time state (typically read from the DOM),
|
|
39
|
+
* not the persisted customer state. See `RegisterTargetConfig`.
|
|
40
|
+
*/
|
|
41
|
+
registerTarget: <T = unknown>(config: RegisterTargetConfig<T>) => void;
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Drop the registered getter for a target.
|
|
45
|
+
*/
|
|
46
|
+
unregisterTarget: (targetId: string) => void;
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Manually capture the current value as the snapshot for a target.
|
|
50
|
+
* Use for non-focusable elements (custom widgets, virtualized rows)
|
|
51
|
+
* where the auto-focus snapshot does not fire.
|
|
52
|
+
*/
|
|
53
|
+
startSuggestion: (targetId: string) => void;
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Programmatically commit a suggestion. Resolves with the new annotation id.
|
|
57
|
+
* Rejects with one of: INVALID_CONFIG, MODE_NOT_SUGGESTING,
|
|
58
|
+
* TARGET_NOT_REGISTERED, NO_GETTER_FOR_COMPLEX, NO_CHANGE_TO_SUGGEST,
|
|
59
|
+
* SNAPSHOT_FAILED.
|
|
60
|
+
*/
|
|
61
|
+
commitSuggestion: <T = unknown>(config: CommitSuggestionConfig<T>) => Promise<{ id: string }>;
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Synchronous read of all suggestions on the current document, optionally filtered.
|
|
65
|
+
*/
|
|
66
|
+
getSuggestions: (filter?: SuggestionGetSuggestionsFilter) => Suggestion[];
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Reactive variant of getSuggestions. Re-emits on every annotation change,
|
|
70
|
+
* deduplicated via the SDK's standard distinct-until-changed comparator.
|
|
71
|
+
*/
|
|
72
|
+
getSuggestions$: (filter?: SuggestionGetSuggestionsFilter) => Observable<Suggestion[]>;
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Newest pending suggestion for a target, or null. Convenience for
|
|
76
|
+
* pending-overlay UX patterns where each input shows the proposed
|
|
77
|
+
* value while a suggestion is awaiting resolution.
|
|
78
|
+
*/
|
|
79
|
+
getPendingSuggestion: <T = unknown>(targetId: string) => Suggestion<T> | null;
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Reactive variant of getPendingSuggestion.
|
|
83
|
+
*/
|
|
84
|
+
getPendingSuggestion$: <T = unknown>(targetId: string) => Observable<Suggestion<T> | null>;
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Subscribe to a suggestion event. Customers call `.subscribe(handler)`
|
|
88
|
+
* on the returned Observable. Event names: 'suggestionCreated',
|
|
89
|
+
* 'suggestionApproved', 'suggestionRejected', 'suggestionStale',
|
|
90
|
+
* 'targetEditStart', 'targetEditCommit'.
|
|
91
|
+
*/
|
|
92
|
+
on: <T extends SuggestionEventType>(action: T) => Observable<SuggestionEventTypesMap[T]>;
|
|
93
|
+
|
|
94
|
+
constructor();
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Turn on suggestion mode for this user/session and (optionally) register
|
|
98
|
+
* the onTargetEditStart / onTargetEditCommit callbacks the SDK invokes
|
|
99
|
+
* during the auto-detect edit lifecycle.
|
|
100
|
+
*
|
|
101
|
+
* Re-calling with a new config replaces the previous callbacks.
|
|
102
|
+
*/
|
|
103
|
+
private _enableSuggestionMode;
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Turn off suggestion mode and clear any registered callbacks.
|
|
107
|
+
*/
|
|
108
|
+
private _disableSuggestionMode;
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Synchronous read of the current enable flag.
|
|
112
|
+
*/
|
|
113
|
+
private _isSuggestionModeEnabled;
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Reactive enable-flag stream; deduplicated.
|
|
117
|
+
*/
|
|
118
|
+
private _isSuggestionModeEnabled$;
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Register a getter that returns the current value of a tagged target.
|
|
122
|
+
* Required for non-primitive (wrapper) targets — the SDK calls this on
|
|
123
|
+
* focus to snapshot the pre-edit value, and again on commit for the diff.
|
|
124
|
+
*
|
|
125
|
+
* The getter must reflect edit-time state (typically read from the DOM),
|
|
126
|
+
* not the persisted customer state. See `RegisterTargetConfig`.
|
|
127
|
+
*/
|
|
128
|
+
private _registerTarget;
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Drop the registered getter for a target.
|
|
132
|
+
*/
|
|
133
|
+
private _unregisterTarget;
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Manually capture the current value as the snapshot for a target.
|
|
137
|
+
* Use for non-focusable elements (custom widgets, virtualized rows)
|
|
138
|
+
* where the auto-focus snapshot does not fire.
|
|
139
|
+
*/
|
|
140
|
+
private _startSuggestion;
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Programmatically commit a suggestion. Resolves with the new annotation id.
|
|
144
|
+
* Rejects with one of: INVALID_CONFIG, MODE_NOT_SUGGESTING,
|
|
145
|
+
* TARGET_NOT_REGISTERED, NO_GETTER_FOR_COMPLEX, NO_CHANGE_TO_SUGGEST,
|
|
146
|
+
* SNAPSHOT_FAILED.
|
|
147
|
+
*/
|
|
148
|
+
private _commitSuggestion;
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* Synchronous read of all suggestions on the current document, optionally filtered.
|
|
152
|
+
*/
|
|
153
|
+
private _getSuggestions;
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* Reactive variant of getSuggestions. Re-emits on every annotation change,
|
|
157
|
+
* deduplicated via the SDK's standard distinct-until-changed comparator.
|
|
158
|
+
*/
|
|
159
|
+
private _getSuggestions$;
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Newest pending suggestion for a target, or null. Convenience for
|
|
163
|
+
* pending-overlay UX patterns where each input shows the proposed
|
|
164
|
+
* value while a suggestion is awaiting resolution.
|
|
165
|
+
*/
|
|
166
|
+
private _getPendingSuggestion;
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Reactive variant of getPendingSuggestion.
|
|
170
|
+
*/
|
|
171
|
+
private _getPendingSuggestion$;
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* Subscribe to a suggestion event. Customers call `.subscribe(handler)`
|
|
175
|
+
* on the returned Observable. Event names: 'suggestionCreated',
|
|
176
|
+
* 'suggestionApproved', 'suggestionRejected', 'suggestionStale',
|
|
177
|
+
* 'targetEditStart', 'targetEditCommit'.
|
|
178
|
+
*/
|
|
179
|
+
private _on;
|
|
180
|
+
}
|
package/app/utils/constants.d.ts
CHANGED
|
@@ -519,6 +519,7 @@ export declare class Constants {
|
|
|
519
519
|
VELT_AREA_PIN_HOST_STATIC: string;
|
|
520
520
|
VELT_AREA_DISABLED: string;
|
|
521
521
|
VELT_AREA_PIN_ACTIVE: string;
|
|
522
|
+
VELT_SUGGESTION_TARGET: string;
|
|
522
523
|
VELT_ONGOING_RECORDING: string;
|
|
523
524
|
VELT_COMMENT_RECORDING: string;
|
|
524
525
|
SYNC_VIDEO_PLAYER_ID: string;
|
package/app/utils/enums.d.ts
CHANGED
|
@@ -90,6 +90,14 @@ export declare const RecorderEventTypes: {
|
|
|
90
90
|
export declare const RewriterEventTypes: {
|
|
91
91
|
readonly TEXT_SELECTED: "textSelected";
|
|
92
92
|
};
|
|
93
|
+
export declare const SuggestionEventTypes: {
|
|
94
|
+
readonly SUGGESTION_CREATED: "suggestionCreated";
|
|
95
|
+
readonly SUGGESTION_APPROVED: "suggestionApproved";
|
|
96
|
+
readonly SUGGESTION_REJECTED: "suggestionRejected";
|
|
97
|
+
readonly SUGGESTION_STALE: "suggestionStale";
|
|
98
|
+
readonly TARGET_EDIT_START: "targetEditStart";
|
|
99
|
+
readonly TARGET_EDIT_COMMIT: "targetEditCommit";
|
|
100
|
+
};
|
|
93
101
|
export declare const CoreEventTypes: {
|
|
94
102
|
readonly PERMISSION_PROVIDER: "permissionProvider";
|
|
95
103
|
readonly USER_RESOLVER: "userResolver";
|
|
@@ -131,6 +139,7 @@ export type LiveStateSyncEventType = typeof LiveStateSyncEventTypes[keyof typeof
|
|
|
131
139
|
export type PresenceEventType = typeof PresenceEventTypes[keyof typeof PresenceEventTypes];
|
|
132
140
|
export type NotificationEventType = typeof NotificationEventTypes[keyof typeof NotificationEventTypes];
|
|
133
141
|
export type RewriterEventType = typeof RewriterEventTypes[keyof typeof RewriterEventTypes];
|
|
142
|
+
export type SuggestionEventType = typeof SuggestionEventTypes[keyof typeof SuggestionEventTypes];
|
|
134
143
|
export type CrdtEventType = typeof CrdtEventTypes[keyof typeof CrdtEventTypes];
|
|
135
144
|
export declare enum TagStatus {
|
|
136
145
|
ADDED = "added",
|
package/models.d.ts
CHANGED
|
@@ -50,6 +50,8 @@ export * from './app/models/data/recorder-annotation.data.model';
|
|
|
50
50
|
export * from './app/models/data/recorder-events.data.model';
|
|
51
51
|
export * from './app/models/data/rewriter-annotation.data.model';
|
|
52
52
|
export * from './app/models/data/rewriter-events.data.model';
|
|
53
|
+
export * from './app/models/data/suggestion.data.model';
|
|
54
|
+
export * from './app/models/data/suggestion-events.data.model';
|
|
53
55
|
export * from './app/models/data/screen-size.data.model';
|
|
54
56
|
export * from './app/models/data/screenshot.data.model';
|
|
55
57
|
export * from './app/models/data/selection.model';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@veltdev/sdk",
|
|
3
|
-
"version": "5.0.2-beta.
|
|
3
|
+
"version": "5.0.2-beta.23",
|
|
4
4
|
"description": "Velt is an SDK to add collaborative features to your product within minutes. Example: Comments like Figma, Frame.io, Google docs or sheets, Recording like Loom, Huddles like Slack and much more.",
|
|
5
5
|
"homepage": "https://velt.dev",
|
|
6
6
|
"keywords": [
|
package/types.d.ts
CHANGED
|
@@ -18,4 +18,5 @@ export * from './app/models/element/autocomplete-element.model';
|
|
|
18
18
|
export * from './app/models/element/reaction-element.model';
|
|
19
19
|
export * from './app/models/element/crdt-element.model';
|
|
20
20
|
export * from './app/models/element/activity-element.model';
|
|
21
|
+
export * from './app/models/element/suggestion-element.model';
|
|
21
22
|
export * from './models';
|