@dolphy-app/extension-sdk 0.2.0 → 0.4.0

package/dist/testing.d.ts

@@ -1,6 +1,204 @@
-import { ExtensionLogger, ExtensionModule, GradePolicyInput, GradeResult, GradeValue, JsonSchema, LibraryReader } from "@dolphy-app/extension-api";
+import { t as AnswerView } from "./answer-view-D6wnyThb.js";
+import { AnswerChangeDetail, AnswerElementProps, CommandOutcome, ExportInput, ExportResult, ExtensionCommands, ExtensionEvents, ExtensionExporters, ExtensionImporters, ExtensionLogger, ExtensionModule, ExtensionNotification, ExtensionNotifications, ExtensionSchedule, ExtensionSecrets, ExtensionSettings, ExtensionStats, ExtensionStorage, GradePolicyInput, GradeResult, GradeValue, ImportInput, ImportResult, ImporterInputKind, JsonSchema, JsonValue, LearningEventName, LearningEventPayloads, LibraryReader, PanelContextInfo, PanelModule, SettingContribution, SettingValue, WidgetModule } from "@dolphy-app/extension-api";
 //#region packages/extension-sdk/src/testing.d.ts
 export declare const createMemoryLibrary: (files: Readonly<Record<string, string>>) => LibraryReader;
+/**
+ * In-memory storage with the same limits and errors as the engine
+ * (`EXTENSION_STORAGE_LIMITS`, `StorageQuotaError`): values are stored as
+ * JSON text and returned as copies; on rejection nothing changes.
+ */
+export declare const createMemoryStorage: () => ExtensionStorage;
+/** In-memory secrets for tests: `ExtensionSecrets` plus a switch that imitates a missing system key store. */
+export interface MemorySecrets extends ExtensionSecrets {
+  /** Imitates the system key store becoming (un)available; stored values are kept. */
+  setAvailable(available: boolean): void;
+}
+export interface MemorySecretsOptions {
+  /** Default `true`; `false` imitates Linux `basic_text`, no key store, or an app that is not ready. */
+  available?: boolean;
+}
+/**
+ * In-memory secrets with the engine's limits and errors
+ * (`EXTENSION_SECRET_LIMITS`, `StorageQuotaError`, `SecretsUnavailableError`):
+ * without a key store `set` and `get` of an existing key throw, `get` of a
+ * missing key gives `undefined` and `delete` works.
+ */
+export declare const createMemorySecrets: (options?: MemorySecretsOptions) => MemorySecrets;
+export interface MemorySettings extends ExtensionSettings {
+  /**
+   * Changes the value as the user does in the dialog: the value is validated
+   * against the definition, and `onDidChange` subscribers are called if it changed.
+   * Unlike the host, a handler failure is not swallowed but rejects the promise.
+   */
+  set(id: string, value: SettingValue): Promise<void>;
+}
+/** In-memory settings from manifest definitions; `initial` provides user values in place of `default`. */
+export declare const createMemorySettings: (definitions: readonly SettingContribution[], initial?: Readonly<Record<string, SettingValue>>) => MemorySettings;
+export interface MemoryEvents extends ExtensionEvents {
+  /**
+   * Sends the event to the subscribed handler and awaits it. With no subscription,
+   * the event is skipped, as in the host. Unlike the host, a handler failure
+   * is not swallowed but rejects the promise, and the 2 s handler timeout is not applied.
+   */
+  emit<N extends LearningEventName>(name: N, payload: LearningEventPayloads[N]): Promise<void>;
+}
+export interface MemoryEventsOptions {
+  /** Events from `contributes.events`: subscribing to another throws, as in the host. Unset — any are allowed. */
+  declared?: readonly LearningEventName[];
+  /** false — subscribing throws `PermissionError`, as for an extension without `learning.events`. Defaults to true. */
+  permitted?: boolean;
+}
+/** In-memory learning event subscriptions: one handler per event, as in the host. */
+export declare const createMemoryEvents: (options?: MemoryEventsOptions) => MemoryEvents;
+export interface MemoryCommands extends ExtensionCommands {
+  /**
+   * Runs a registered command the way the host does: the same
+   * argument and result bounds, the same result normalization. An unregistered
+   * command and an invalid result reject the promise. The 10 s handler timeout is not applied.
+   */
+  run(id: string, args?: JsonValue): Promise<CommandOutcome>;
+  /** Registered commands in registration order. */
+  ids(): string[];
+}
+export interface MemoryCommandsOptions {
+  /** Commands from `contributes.commands`: registering another throws, as in the host. Unset — any are allowed. */
+  declaredCommands?: readonly string[];
+  /** Panels from `contributes.panels`: `openPanel` on another is invalid, as in the host. Unset — any. */
+  declaredPanels?: readonly string[];
+}
+/** In-memory commands: the same registration rules and result parsing as the host. */
+export declare const createMemoryCommands: (options?: MemoryCommandsOptions) => MemoryCommands;
+export interface MemorySchedule extends ExtensionSchedule {
+  /**
+   * Fires a schedule the way the host does and awaits the handler: resolves
+   * `true` once the handler returned. With no subscription, or while the
+   * handler of the previous firing is still running, the firing is skipped and
+   * resolves `false`. Unlike the host, a handler failure is not swallowed but
+   * rejects the promise, and the 10 s handler timeout is not applied.
+   */
+  fire(id: string): Promise<boolean>;
+  /** Subscribed schedules in subscription order. */
+  ids(): string[];
+}
+export interface MemoryScheduleOptions {
+  /** Schedules from `contributes.schedules`: subscribing to another throws, as in the host. Unset — any are allowed. */
+  declared?: readonly string[];
+}
+/** In-memory schedule subscriptions: one handler per schedule and no overlapping firings, as in the host. */
+export declare const createMemorySchedule: (options?: MemoryScheduleOptions) => MemorySchedule;
+export interface MemoryImporters extends ExtensionImporters {
+  /**
+   * Runs a registered importer the way the host does: the input must have the
+   * form the importer declares (`text` unless `input: 'bytes'`) and at most
+   * `EXTENSION_TRANSFER_LIMITS.inputBytes`; the result goes through the host's
+   * rules (`normalizeImportResult`: paths, sizes, number of files). An
+   * unregistered importer and an invalid result reject the promise. The 30 s
+   * handler timeout is not applied.
+   */
+  run(id: string, input: ImportInput): Promise<ImportResult>;
+  /** Registered importers in registration order. */
+  ids(): string[];
+}
+export interface MemoryImportersOptions {
+  /** Importers from `contributes.importers`: registering another throws and `input` is checked, as in the host. Unset — any are allowed. */
+  declaredImporters?: readonly {
+    id: string;
+    input?: ImporterInputKind;
+  }[];
+}
+/** In-memory importers: the same registration rules and result checks as the host. */
+export declare const createMemoryImporters: (options?: MemoryImportersOptions) => MemoryImporters;
+export interface MemoryExporters extends ExtensionExporters {
+  /**
+   * Runs a registered exporter the way the host does: the input must match the
+   * exporter's declared `scope` and a course snapshot is at most
+   * `EXTENSION_TRANSFER_LIMITS.totalBytes`; the result goes through the host's
+   * rules (`normalizeExportResult`: file name, size, `text` xor `bytes`). An
+   * unregistered exporter and an invalid result reject the promise. The 30 s
+   * handler timeout is not applied.
+   */
+  run(id: string, input: ExportInput): Promise<ExportResult>;
+  /** Registered exporters in registration order. */
+  ids(): string[];
+}
+export interface MemoryExportersOptions {
+  /** Exporters from `contributes.exporters`: registering another throws and `scope` is checked, as in the host. Unset — any are allowed. */
+  declaredExporters?: readonly {
+    id: string;
+    scope: ExportInput['scope'];
+  }[];
+}
+/** In-memory exporters: the same registration rules and result checks as the host. */
+export declare const createMemoryExporters: (options?: MemoryExportersOptions) => MemoryExporters;
+export interface MemoryStatsAttempt {
+  /** When the attempt happened: epoch milliseconds, a `Date`, or an ISO-8601 string. */
+  at: number | Date | string;
+  /** Grade 1-5; 3 and higher counts as correct, as in the app. */
+  grade: number;
+  /** Course of the attempt, for the `courseId` filter. Without it the attempt belongs to no course. */
+  courseId?: string;
+}
+export interface MemoryStatsOptions {
+  /** Attempts the statistics start with; more arrive through `record`. */
+  attempts?: readonly MemoryStatsAttempt[];
+  /** IANA time zone whose local days are counted. Defaults to the time zone of this process. */
+  timeZone?: string;
+  /** The current time, for the `current` streak. Defaults to `Date.now`. */
+  now?: () => number;
+  /** false — every call rejects with `PermissionError('learning.stats')`, as for an extension without the permission. Defaults to true. */
+  permitted?: boolean;
+}
+export interface MemoryStats extends ExtensionStats {
+  /** Adds an attempt to the history. */
+  record(attempt: MemoryStatsAttempt): void;
+}
+/**
+ * In-memory statistics with the semantics of the app: local days in a time zone,
+ * correct at grade 3 or higher, `current` streak not broken while today has no
+ * attempts yet, one `daily` entry per date (at most `EXTENSION_STATS_LIMITS.dailyDays`).
+ */
+export declare const createMemoryStats: (options?: MemoryStatsOptions) => MemoryStats;
+export interface MemoryNotificationsOptions {
+  /** false — every call rejects with `PermissionError('notifications')`, as for an extension without the permission. Defaults to true. */
+  permitted?: boolean;
+  /** false — the operating system does not support notifications: `show` resolves `false`. Defaults to true. */
+  supported?: boolean;
+  /** false — the user switched notifications off for the extension: `show` resolves `false`. Defaults to true. */
+  enabled?: boolean;
+  /** The current time for the rate windows. Defaults to `Date.now`. */
+  now?: () => number;
+}
+export interface MemoryNotifications extends ExtensionNotifications {
+  /** Notifications handed to the (imitated) operating system, oldest first, as the app shows them: sanitized text. */
+  readonly shown: readonly ExtensionNotification[];
+  /** The user's switch "Notifications" of the extension. */
+  setEnabled(enabled: boolean): void;
+  /** Whether the imitated operating system supports notifications. */
+  setSupported(supported: boolean): void;
+}
+/**
+ * In-memory notifications with the engine's rules: the text is sanitized and
+ * limited, `perMinute`/`perHour` windows throw `NotificationRateLimitError`,
+ * a switched-off extension or an unsupporting system resolves `false` (and
+ * does not use the rate limit). `shown` is the log the app's fake notifier
+ * would keep.
+ */
+export declare const createMemoryNotifications: (options?: MemoryNotificationsOptions) => MemoryNotifications;
+/** What a test replaces in the extension context; by default everything is in memory and silent. */
+export interface LoadOptions {
+  library?: LibraryReader;
+  logger?: ExtensionLogger;
+  storage?: ExtensionStorage;
+  secrets?: ExtensionSecrets;
+  settings?: ExtensionSettings;
+  events?: ExtensionEvents;
+  commands?: ExtensionCommands;
+  importers?: ExtensionImporters;
+  exporters?: ExtensionExporters;
+  stats?: ExtensionStats;
+  notifications?: ExtensionNotifications;
+  schedule?: ExtensionSchedule;
+}
 export declare const createSchemaValidator: (schema: JsonSchema) => (value: unknown) => string[];
 export interface LoadedExerciseType {
   project(spec: unknown, options?: {
@@ -21,20 +219,141 @@ export interface LoadedExerciseType {
   } | {
     found: false;
   }>;
-  /** Деактивирует модуль расширения. */
+  /** Deactivates the extension module. */
   dispose(): Promise<void>;
 }
-export declare const loadExerciseType: (module: ExtensionModule, type: string, options?: {
-  library?: LibraryReader;
-  logger?: ExtensionLogger;
-}) => Promise<LoadedExerciseType>;
+export declare const loadExerciseType: (module: ExtensionModule, type: string, options?: LoadOptions) => Promise<LoadedExerciseType>;
 export interface LoadedGradePolicy {
   evaluate(input: GradePolicyInput): Promise<GradeValue | null>;
-  /** Деактивирует модуль расширения. */
+  /** Deactivates the extension module. */
   dispose(): Promise<void>;
 }
-export declare const loadGradePolicy: (module: ExtensionModule, id: string, options?: {
-  library?: LibraryReader;
-  logger?: ExtensionLogger;
-}) => Promise<LoadedGradePolicy>;
+export declare const loadGradePolicy: (module: ExtensionModule, id: string, options?: LoadOptions) => Promise<LoadedGradePolicy>;
+export interface LoadedEvents {
+  /** Events are delivered as in the host: to the subscribed handler, one at a time. See `MemoryEvents.emit`. */
+  emit: MemoryEvents['emit'];
+  storage: ExtensionStorage;
+  secrets: ExtensionSecrets;
+  settings: MemorySettings;
+  /** Deactivates the extension module. */
+  dispose(): Promise<void>;
+}
+export interface LoadEventsOptions extends Omit<LoadOptions, 'storage' | 'secrets' | 'settings' | 'events'>, MemoryEventsOptions {
+  storage?: ExtensionStorage;
+  secrets?: ExtensionSecrets;
+  /** Definitions from the manifest's `contributes.settings`; values are read and changed through `settings`. */
+  settings?: readonly SettingContribution[];
+  /** User values in place of `default`. */
+  settingValues?: Readonly<Record<string, SettingValue>>;
+}
+/**
+ * Activates the module with in-memory storage, settings, and events, and lets the test
+ * send events and change settings.
+ */
+export declare const loadEvents: (module: ExtensionModule, options?: LoadEventsOptions) => Promise<LoadedEvents>;
+export interface LoadedCommands {
+  run: MemoryCommands['run'];
+  ids: MemoryCommands['ids'];
+  /** Deactivates the extension module. */
+  dispose(): Promise<void>;
+}
+export interface LoadCommandsOptions extends Omit<LoadOptions, 'commands'>, MemoryCommandsOptions {}
+/** Activates the module with in-memory commands and lets the test invoke them like the host. */
+export declare const loadCommands: (module: ExtensionModule, options?: LoadCommandsOptions) => Promise<LoadedCommands>;
+export interface LoadedImporters {
+  run: MemoryImporters['run'];
+  ids: MemoryImporters['ids'];
+  /** Deactivates the extension module. */
+  dispose(): Promise<void>;
+}
+export interface LoadImportersOptions extends Omit<LoadOptions, 'importers'>, MemoryImportersOptions {}
+/** Activates the module with in-memory importers and lets the test run them like the host. */
+export declare const loadImporters: (module: ExtensionModule, options?: LoadImportersOptions) => Promise<LoadedImporters>;
+export interface LoadedExporters {
+  run: MemoryExporters['run'];
+  ids: MemoryExporters['ids'];
+  /** Deactivates the extension module. */
+  dispose(): Promise<void>;
+}
+export interface LoadExportersOptions extends Omit<LoadOptions, 'exporters'>, MemoryExportersOptions {}
+/** Activates the module with in-memory exporters and lets the test run them like the host; `stats` feeds `ctx.stats` of a progress exporter. */
+export declare const loadExporters: (module: ExtensionModule, options?: LoadExportersOptions) => Promise<LoadedExporters>;
+export interface LoadedSchedules {
+  fire: MemorySchedule['fire'];
+  ids: MemorySchedule['ids'];
+  /** Deactivates the extension module. */
+  dispose(): Promise<void>;
+}
+export interface LoadSchedulesOptions extends Omit<LoadOptions, 'schedule'>, MemoryScheduleOptions {}
+/** Activates the module with in-memory schedules and lets the test fire them like the host. */
+export declare const loadSchedules: (module: ExtensionModule, options?: LoadSchedulesOptions) => Promise<LoadedSchedules>;
+export interface LoadViewOptions extends Partial<AnswerElementProps> {
+  /** `aria-label` of the host element, as the app sets it. */
+  label?: string;
+  /** Where to mount; defaults to a new `div` in `document.body`. */
+  container?: HTMLElement;
+}
+export interface LoadedView {
+  /** The kind's custom element, as the app creates it. */
+  readonly element: HTMLElement;
+  /** The element's shadow root: the view renders its UI here. */
+  readonly root: ShadowRoot;
+  /** `dolphy-answer-change` events in order. */
+  readonly changes: readonly AnswerChangeDetail[];
+  /** How many times the view asked to submit the answer (`dolphy-answer-submit`). */
+  readonly submissions: number;
+  /** Sets element properties and waits for the view to apply the update. */
+  update(props: Partial<AnswerElementProps>): Promise<void>;
+  query<E extends Element = Element>(selector: string): E | null;
+  queryAll<E extends Element = Element>(selector: string): E[];
+  /** Removes the element from the document; the view receives `destroy()`. */
+  dispose(): void;
+}
+/**
+ * Mounts a view from `views[id]` in the test DOM environment with the same element
+ * the app creates (test tags are issued; the manifest `element` is not needed).
+ */
+export declare const loadView: (views: Readonly<Record<string, AnswerView>>, id: string, options?: LoadViewOptions) => Promise<LoadedView>;
+export interface LoadPanelOptions {
+  /** Properties the panel was opened with (`openPanel(id, props)`). */
+  props?: JsonValue;
+  /** Reply to `ctx.call`; by default the call is rejected. */
+  call?: (commandId: string, args: JsonValue | undefined) => JsonValue | undefined | Promise<JsonValue | undefined>;
+  /** The surroundings the frame starts with (`ctx.context`); defaults to all courses (`courseId: null`). */
+  context?: PanelContextInfo;
+  /** Where to mount; defaults to a new `div` in `document.body`. */
+  container?: HTMLElement;
+}
+export interface LoadWidgetOptions {
+  /** Reply to `ctx.call`; by default the call is rejected. */
+  call?: LoadPanelOptions['call'];
+  /** The surroundings the frame starts with (`ctx.context`); defaults to all courses (`courseId: null`). */
+  context?: PanelContextInfo;
+  /** Where to mount; defaults to a new `div` in `document.body`. */
+  container?: HTMLElement;
+}
+export interface LoadedFrame {
+  /** Container the module received in `mount`. */
+  readonly container: HTMLElement;
+  /** `ctx.call` invocations in order. */
+  readonly calls: readonly {
+    commandId: string;
+    args: JsonValue | undefined;
+  }[];
+  /** Whether `ctx.signal` was aborted (after `dispose()`). */
+  readonly aborted: boolean;
+  /** The app focused another course: updates `ctx.context` and notifies `ctx.onContextChange` subscribers. */
+  setContext(context: PanelContextInfo): void;
+  /** Closes the frame: aborts `ctx.signal` and removes the container. */
+  dispose(): void;
+}
+export interface LoadedPanel extends LoadedFrame {
+  /** Sends new properties to the panel (`ctx.onProps`). */
+  setProps(props: JsonValue | undefined): void;
+}
+export type LoadedWidget = LoadedFrame;
+/** Mounts a panel from `panels[id]` in the test DOM environment with the same context the frame provides. */
+export declare const loadPanel: (panels: Readonly<Record<string, PanelModule<HTMLElement>>>, id: string, options?: LoadPanelOptions) => Promise<LoadedPanel>;
+/** Mounts a widget from `widgets[id]` in the test DOM environment with the same context the frame provides. */
+export declare const loadWidget: (widgets: Readonly<Record<string, WidgetModule<HTMLElement>>>, id: string, options?: LoadWidgetOptions) => Promise<LoadedWidget>;
 //#endregion