@veltdev/types-dev 5.0.2-beta.88 → 5.0.2-beta.9

package/app/models/data/suggestion.data.model.d.ts

@@ -1,267 +0,0 @@
-/**
- * Suggestions feature — public type surface for v1.
- *
- * Source contract: docs/suggestions-api-contract.md
- * Source flows:    docs/suggestions-implementation-flows.md
- *
- * Types are exported from the SDK's public barrel. Customer code interacts
- * with these via Snippyly.getSuggestionElement(); the SDK constructs all
- * Suggestion objects internally and customers do not build them directly.
- */
-import { User } from './user.data.model';
-/**
- * Lifecycle state machine for a Suggestion.
- *
- * - pending:      Just created, awaiting owner action.
- * - approved:     Owner clicked Approve. Customer apply handler ran successfully.
- * - rejected:     Owner clicked Reject (with optional reason).
- * - stale:        Target was unresolvable at approve time. Owner can dismiss.
- * - apply_failed: Customer apply handler threw during a suggestionApproved event.
- *                 Status set by the SDK after the throw was caught.
- */
-export type SuggestionStatus = 'pending' | 'approved' | 'rejected' | 'stale' | 'apply_failed';
-/**
- * Global per-user-per-session suggestion mode. Not persisted; reload returns to 'editing'.
- */
-export type SuggestionMode = 'editing' | 'suggesting';
-/**
- * Discriminator for the substrate that produced a suggestion. v1: always 'custom'.
- * Wrapper libraries (e.g. tiptap-velt-comments) widen this union when they integrate.
- *
- * Customers should treat unknown values as opaque; the field exists so customer code
- * can differentiate substrate when domain-specific rendering matters.
- */
-export type SuggestionTargetType = 'custom';
-/**
- * Single-arg config passed to `SuggestionElement.registerTarget(config)`.
- * Carrying both `targetId` and `getter` in one object so the API can grow
- * (e.g., metadata, target-specific options) without breaking customers.
- */
-export interface RegisterTargetConfig<T = unknown> {
-    targetId: string;
-    getter: TargetGetter<T>;
-}
-/**
- * Function the customer registers via SuggestionElement.registerTarget(config).
- * Required for any non-primitive (wrapper) target.
- *
- * The SDK calls this getter twice in a typical edit cycle:
- *   1. On focus of the tagged element — to snapshot the pre-edit value.
- *   2. On commit (focusout / change) — to read the current value for the diff.
- *
- * IMPORTANT — edit-time state, not persisted state: the getter must reflect
- * what the user is currently editing, not what's persisted in the customer's
- * app store. If the customer's state is only updated on commit/approve (as
- * is typical when suggesting mode is on), reading from that state would
- * return the snapshot value at commit time, the diff check would short-
- * circuit, and no suggestion would ever fire.
- *
- * Recommended: read from the DOM (controlled or uncontrolled inputs) so the
- * getter always returns what's visible to the user.
- *
- *   el.registerTarget('row.123', () => ({
- *     qty:   parseInt(qtyInput.value, 10),
- *     price: parseInt(priceInput.value, 10),
- *   }));
- *
- * For controlled inputs (state updates on every keystroke), reading from
- * the customer state is fine: `() => myState.row123`. The contract is
- * "edit-time state" — whichever source of truth has it.
- */
-export type TargetGetter<T = unknown> = () => T;
-/**
- * Returned from SuggestionElement.on(...). Calling it removes the handler.
- */
-export type Unsubscribe = () => void;
-/**
- * Details about a target edit, passed to the customer's resolver handler and
- * to subscribers of `targetEditStart` / `targetEditCommit` events.
- *
- * `element` is the DOM element that produced the edit. It's the tagged
- * descendant — or, for wrappers that nest interactive controls inside a
- * tagged container, the inner element that actually fired the event. In
- * either case the SDK walks up to the nearest ancestor carrying
- * `data-velt-suggestion-target` to resolve `targetId`.
- *
- * `element` is provided for read access only — customers should not retain
- * the reference past the synchronous handler call.
- */
-export interface TargetEditDetails<T = unknown> {
-    targetId: string;
-    oldValue: T;
-    newValue: T;
-    element: Element | null;
-}
-/**
- * Return type of `onTargetEditCommit`. Returning a value auto-commits the
- * suggestion using the (optional) overrides; returning null skips the
- * auto-commit so a subscriber to `targetEditCommit` can drive it explicitly.
- */
-export interface TargetEditCommitResult {
-    /** Override the SDK's default `${targetId}: ${old} → ${new}` summary. */
-    summary?: string;
-    /** Customer metadata persisted on the resulting Suggestion. */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Return type of `onTargetEditStart`. Reserved for future fields; v1 has
- * no behavior-bearing return values, so customers may omit a return.
- *
- * Roadmap: future versions may accept `{ oldValue }` here so customers can
- * override the SDK's auto-snapshot with a domain-canonical value.
- */
-export interface TargetEditStartResult {
-}
-export type TargetEditStartHandler<T = unknown> = (details: TargetEditDetails<T>) => TargetEditStartResult | void | null;
-export type TargetEditCommitHandler<T = unknown> = (details: TargetEditDetails<T>) => TargetEditCommitResult | null;
-/**
- * Config passed to `SuggestionElement.enableSuggestionMode(config?)`.
- * Both callbacks are optional. If `onTargetEditCommit` is omitted, customers
- * can still drive auto-commit by subscribing to the `targetEditCommit` event
- * and calling the pre-bound `commitSuggestion` builder on the payload.
- */
-export interface EnableSuggestionModeConfig {
-    /**
-     * Invoked on focus of a tagged element, after the SDK captures the
-     * snapshot. v1: informational — return value is reserved for future
-     * use (e.g. `{ oldValue }` to override the SDK's auto-snapshot).
-     */
-    onTargetEditStart?: TargetEditStartHandler;
-    /**
-     * Invoked once per detected commit (on `change` for atomic inputs, on
-     * `focusout` for text-like inputs). Returning a `TargetEditCommitResult`
-     * auto-commits with the supplied summary/metadata; returning null defers
-     * to event subscribers.
-     */
-    onTargetEditCommit?: TargetEditCommitHandler;
-}
-/**
- * SDK-managed suggestion data persisted on a CommentAnnotation.
- * Present iff annotation.type === 'suggestion'.
- *
- * Customer code must not write to this directly — use the SuggestionElement API.
- */
-export interface SuggestionData {
-    /** Lifecycle state machine. */
-    status: SuggestionStatus;
-    /** Stable, customer-owned target identifier. */
-    targetId: string;
-    /** v1: always 'custom'. Wrappers widen later. */
-    targetType: SuggestionTargetType;
-    /** Snapshot taken at startSuggestion / focus time. Frozen via structuredClone. */
-    oldValue: any;
-    /** Value submitted via commitSuggestion. */
-    newValue: any;
-    /** Optional human-readable description for logs / notifications. */
-    summary: string | null;
-    /**
-     * True if the live value at approve time differed from oldValue.
-     * v1 records flag only; v1.1 will surface a confirmation prompt.
-     */
-    driftDetected: boolean;
-    /** Populated only when status === 'rejected'. */
-    rejectReason: string | null;
-    /**
-     * Full User snapshot of the resolver, populated when status moves to
-     * approved | rejected | stale | apply_failed. Snapshot rather than userId
-     * so customer code can render name/email/photoUrl without an extra lookup,
-     * and so historical suggestions retain their resolver record even if the
-     * user later updates their profile.
-     */
-    resolvedBy: User | null;
-    resolvedAt: number | null;
-}
-/**
- * Fields shared across every Suggestion regardless of status.
- * Internal — used to build the per-status discriminated types below.
- */
-interface SuggestionBase<T = unknown> {
-    /** Annotation document id (same as the underlying CommentAnnotation.annotationId). */
-    annotationId: string;
-    /** Stable, customer-owned target identifier. */
-    targetId: string;
-    /** v1: always 'custom'. */
-    targetType: SuggestionTargetType;
-    /** Snapshot taken at startSuggestion / focus time. */
-    oldValue: T;
-    /** Value submitted via commitSuggestion. */
-    newValue: T;
-    /** Optional human-readable description. */
-    summary: string | null;
-    /** Customer-defined metadata supplied via CommitSuggestionConfig.metadata. */
-    metadata: Record<string, any>;
-    /** True iff the live value at approve time differed from oldValue. */
-    driftDetected: boolean;
-    /**
-     * User of the suggestion's creator (sourced from annotation.from).
-     */
-    createdBy?: User;
-    createdAt: number;
-}
-/** A suggestion in the 'pending' state — newly created, no owner action yet. */
-export interface PendingSuggestion<T = unknown> extends SuggestionBase<T> {
-    status: 'pending';
-    rejectReason: null;
-    resolvedBy: null;
-    resolvedAt: null;
-}
-/** A suggestion that has been approved (apply handler success or pending invocation). */
-export interface ApprovedSuggestion<T = unknown> extends SuggestionBase<T> {
-    status: 'approved' | 'apply_failed';
-    rejectReason: null;
-    resolvedBy: User;
-    resolvedAt: number;
-}
-/**
- * A suggestion that has been rejected. `rejectReason` may be null when the
- * rejecter dismissed without supplying a reason — matches the persisted
- * `SuggestionData.rejectReason: string | null` shape.
- */
-export interface RejectedSuggestion<T = unknown> extends SuggestionBase<T> {
-    status: 'rejected';
-    rejectReason: string | null;
-    resolvedBy: User;
-    resolvedAt: number;
-}
-/** A suggestion whose target was unresolvable at approve time. */
-export interface StaleSuggestion<T = unknown> extends SuggestionBase<T> {
-    status: 'stale';
-    rejectReason: null;
-    resolvedBy: User | null;
-    resolvedAt: number | null;
-}
-/**
- * Public Suggestion — discriminated union keyed by `status`. TypeScript narrows
- * field types per status (e.g. `resolvedBy: User` is non-null on approved/rejected,
- * `rejectReason: string | null` on rejected since one-click reject without a reason
- * is supported).
- */
-export type Suggestion<T = unknown> = PendingSuggestion<T> | ApprovedSuggestion<T> | RejectedSuggestion<T> | StaleSuggestion<T>;
-export interface CommitSuggestionConfig<T = unknown> {
-    /**
-     * Must be registered (via data-velt-target attribute or registerTarget call)
-     * before commit, otherwise the suggestion is rejected with a dev-mode warning.
-     */
-    targetId: string;
-    /** Any JSON-serializable value. Customer's apply handler interprets it. */
-    newValue: T;
-    /** Optional human-readable string for logs and notifications. */
-    summary?: string;
-    /** Optional customer-defined metadata. Stored on Suggestion.metadata. */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Pre-bound builder attached to `targetEditCommit` payloads. Calling it
- * commits the suggestion with the SDK's default summary/metadata, optionally
- * overridden by `result`. If the customer's `onTargetEditCommit` handler
- * already returned a non-null result for this edit, this builder is a no-op
- * (resolves immediately) so subscribers can't double-commit.
- */
-export type TargetEditCommitBuilder = (result?: TargetEditCommitResult) => Promise<{
-    id: string;
-} | null>;
-export interface SuggestionGetSuggestionsFilter {
-    targetId?: string;
-    status?: SuggestionStatus | SuggestionStatus[];
-}
-export {};

package/app/models/element/activity-element.model.d.ts

@@ -1,33 +0,0 @@
-// @ts-nocheck
-import { Observable } from "rxjs";
-import { ActivityRecord, ActivitySubscribeConfig, CreateActivityData } from "../data/activity.data.model";
-
-export declare class ActivityElement {
-
-    /**
-     * Subscribe to activities with optional filtering configuration.
-     * Returns an Observable that, when unsubscribed, automatically cleans up the internal subscription.
-     * @param config Optional configuration to filter activities by scope, feature types, action types, etc.
-     * @returns Observable<ActivityRecord[] | null>
-     */
-    getAllActivities: (config?: ActivitySubscribeConfig) => Observable<ActivityRecord[] | null>;
-
-    /**
-     * Create a new activity record.
-     * @param data The activity data including feature type, action type, target entity, etc.
-     * @returns Promise<void>
-     */
-    createActivity: (data: CreateActivityData) => Promise<void>;
-
-    constructor();
-
-    /**
-     * Subscribe to activities with optional filtering configuration.
-     */
-    private _getAllActivities;
-
-    /**
-     * Create a new activity record.
-     */
-    private _createActivity;
-}

package/app/models/element/suggestion-element.model.d.ts

@@ -1,180 +0,0 @@
-// @ts-nocheck
-import { Observable } from "rxjs";
-import { SuggestionEventType } from "../../utils/enums";
-import { SuggestionEventTypesMap } from "../data/suggestion-events.data.model";
-import { CommitSuggestionConfig, EnableSuggestionModeConfig, RegisterTargetConfig, Suggestion, SuggestionGetSuggestionsFilter } from "../data/suggestion.data.model";
-
-export declare class SuggestionElement {
-
-  /**
-   * Turn on suggestion mode for this user/session and (optionally) register
-   * the onTargetEditStart / onTargetEditCommit callbacks the SDK invokes
-   * during the auto-detect edit lifecycle.
-   *
-   * Re-calling with a new config replaces the previous callbacks.
-   */
-  enableSuggestionMode: (config?: EnableSuggestionModeConfig) => void;
-
-  /**
-   * Turn off suggestion mode and clear any registered callbacks.
-   */
-  disableSuggestionMode: () => void;
-
-  /**
-   * Synchronous read of the current enable flag.
-   */
-  isSuggestionModeEnabled: () => boolean;
-
-  /**
-   * Reactive enable-flag stream; deduplicated.
-   */
-  isSuggestionModeEnabled$: () => Observable<boolean>;
-
-  /**
-   * Register a getter that returns the current value of a tagged target.
-   * Required for non-primitive (wrapper) targets — the SDK calls this on
-   * focus to snapshot the pre-edit value, and again on commit for the diff.
-   *
-   * The getter must reflect edit-time state (typically read from the DOM),
-   * not the persisted customer state. See `RegisterTargetConfig`.
-   */
-  registerTarget: <T = unknown>(config: RegisterTargetConfig<T>) => void;
-
-  /**
-   * Drop the registered getter for a target.
-   */
-  unregisterTarget: (targetId: string) => void;
-
-  /**
-   * Manually capture the current value as the snapshot for a target.
-   * Use for non-focusable elements (custom widgets, virtualized rows)
-   * where the auto-focus snapshot does not fire.
-   */
-  startSuggestion: (targetId: string) => void;
-
-  /**
-   * Programmatically commit a suggestion. Resolves with the new annotation id.
-   * Rejects with one of: INVALID_CONFIG, MODE_NOT_SUGGESTING,
-   * TARGET_NOT_REGISTERED, NO_GETTER_FOR_COMPLEX, NO_CHANGE_TO_SUGGEST,
-   * SNAPSHOT_FAILED.
-   */
-  commitSuggestion: <T = unknown>(config: CommitSuggestionConfig<T>) => Promise<{ id: string }>;
-
-  /**
-   * Synchronous read of all suggestions on the current document, optionally filtered.
-   */
-  getSuggestions: (filter?: SuggestionGetSuggestionsFilter) => Suggestion[];
-
-  /**
-   * Reactive variant of getSuggestions. Re-emits on every annotation change,
-   * deduplicated via the SDK's standard distinct-until-changed comparator.
-   */
-  getSuggestions$: (filter?: SuggestionGetSuggestionsFilter) => Observable<Suggestion[]>;
-
-  /**
-   * Newest pending suggestion for a target, or null. Convenience for
-   * pending-overlay UX patterns where each input shows the proposed
-   * value while a suggestion is awaiting resolution.
-   */
-  getPendingSuggestion: <T = unknown>(targetId: string) => Suggestion<T> | null;
-
-  /**
-   * Reactive variant of getPendingSuggestion.
-   */
-  getPendingSuggestion$: <T = unknown>(targetId: string) => Observable<Suggestion<T> | null>;
-
-  /**
-   * Subscribe to a suggestion event. Customers call `.subscribe(handler)`
-   * on the returned Observable. Event names: 'suggestionCreated',
-   * 'suggestionApproved', 'suggestionRejected', 'suggestionStale',
-   * 'targetEditStart', 'targetEditCommit'.
-   */
-  on: <T extends SuggestionEventType>(action: T) => Observable<SuggestionEventTypesMap[T]>;
-
-  constructor();
-
-  /**
-   * Turn on suggestion mode for this user/session and (optionally) register
-   * the onTargetEditStart / onTargetEditCommit callbacks the SDK invokes
-   * during the auto-detect edit lifecycle.
-   *
-   * Re-calling with a new config replaces the previous callbacks.
-   */
-  private _enableSuggestionMode;
-
-  /**
-   * Turn off suggestion mode and clear any registered callbacks.
-   */
-  private _disableSuggestionMode;
-
-  /**
-   * Synchronous read of the current enable flag.
-   */
-  private _isSuggestionModeEnabled;
-
-  /**
-   * Reactive enable-flag stream; deduplicated.
-   */
-  private _isSuggestionModeEnabled$;
-
-  /**
-   * Register a getter that returns the current value of a tagged target.
-   * Required for non-primitive (wrapper) targets — the SDK calls this on
-   * focus to snapshot the pre-edit value, and again on commit for the diff.
-   *
-   * The getter must reflect edit-time state (typically read from the DOM),
-   * not the persisted customer state. See `RegisterTargetConfig`.
-   */
-  private _registerTarget;
-
-  /**
-   * Drop the registered getter for a target.
-   */
-  private _unregisterTarget;
-
-  /**
-   * Manually capture the current value as the snapshot for a target.
-   * Use for non-focusable elements (custom widgets, virtualized rows)
-   * where the auto-focus snapshot does not fire.
-   */
-  private _startSuggestion;
-
-  /**
-   * Programmatically commit a suggestion. Resolves with the new annotation id.
-   * Rejects with one of: INVALID_CONFIG, MODE_NOT_SUGGESTING,
-   * TARGET_NOT_REGISTERED, NO_GETTER_FOR_COMPLEX, NO_CHANGE_TO_SUGGEST,
-   * SNAPSHOT_FAILED.
-   */
-  private _commitSuggestion;
-
-  /**
-   * Synchronous read of all suggestions on the current document, optionally filtered.
-   */
-  private _getSuggestions;
-
-  /**
-   * Reactive variant of getSuggestions. Re-emits on every annotation change,
-   * deduplicated via the SDK's standard distinct-until-changed comparator.
-   */
-  private _getSuggestions$;
-
-  /**
-   * Newest pending suggestion for a target, or null. Convenience for
-   * pending-overlay UX patterns where each input shows the proposed
-   * value while a suggestion is awaiting resolution.
-   */
-  private _getPendingSuggestion;
-
-  /**
-   * Reactive variant of getPendingSuggestion.
-   */
-  private _getPendingSuggestion$;
-
-  /**
-   * Subscribe to a suggestion event. Customers call `.subscribe(handler)`
-   * on the returned Observable. Event names: 'suggestionCreated',
-   * 'suggestionApproved', 'suggestionRejected', 'suggestionStale',
-   * 'targetEditStart', 'targetEditCommit'.
-   */
-  private _on;
-}