@markerjs/markerjs3 3.6.3 → 3.7.0

package/markerjs3.d.ts

@@ -1932,6 +1932,26 @@ declare class MarkerBaseEditor<TMarkerType extends MarkerBase = MarkerBase> {
      * Does a check if the state has indeed changed before firing the handler.
      */
     protected stateChanged(): void;
+    /**
+     * Hides all marker's visuals and editor controls.
+     *
+     * @remarks
+     * This could be useful when you want to temporarily hide the marker so you can,
+     * for example, create a new one in the same place. Reveal it later with {@link show}.
+     *
+     * @since 3.7.0
+     */
+    hide(): void;
+    /**
+     * Shows all marker's visuals and editor controls.
+     *
+     * @remarks
+     * This could be useful when you want to temporarily hide the marker (with {@link hide}) so you can,
+     * for example, create a new one in the same place.
+     *
+     * @since 3.7.0
+     */
+    show(): void;
     /**
      * Returns marker's state that can be restored in the future.
      *
@@ -1948,58 +1968,139 @@ declare class MarkerBaseEditor<TMarkerType extends MarkerBase = MarkerBase> {
 
 /**
  * Marker area custom event types.
+ *
+ * @summary
+ * Defines the custom events that can be dispatched by the {@link MarkerArea} component.
+ *
+ * @remarks
+ * The `MarkerAreaEventMap` interface defines the events that can be dispatched by the {@link MarkerArea} component.
+ *
+ * You can listen to these events using the {@link MarkerArea.addEventListener | addEventListener} method on the {@link MarkerArea} instance.
+ *
+ * The events can be logically grouped into two categories:
+ * 1. Marker area events (start with `area`)
+ * 2. Marker editor events (start with `marker`).
+ *
+ * The marker area events are related to the overall state of the {@link MarkerArea} component,
+ * while the marker editor events are related to the individual marker editors within the area.
+ *
+ * Marker area events receive {@link MarkerAreaEventData} as their `event.detail`,
+ * while marker editor events receive {@link MarkerEditorEventData} as their `event.detail`.
+ * Both event data types contain a reference to the {@link MarkerArea} instance
+ * and, for marker editor events, a reference to the specific marker editor that triggered the event.
  */
 interface MarkerAreaEventMap {
     /**
      * Marker area initialized.
+     *
+     * @remarks
+     * This event is dispatched early in the lifecycle when the {@link MarkerArea} component is initialized
+     * but none of its internal elements have been created yet.
+     *
+     * Use {@link areashow} to know when the component is fully initialized and ready to be used.
      */
     areainit: CustomEvent<MarkerAreaEventData>;
     /**
      * Marker area shown.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerArea} component is fully initialized and ready to be used.
      */
     areashow: CustomEvent<MarkerAreaEventData>;
     /**
      * Marker area state restored.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerArea} component restores its state from
+     * a previously saved state.
      */
     arearestorestate: CustomEvent<MarkerAreaEventData>;
     /**
      * Marker area focused.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerArea} component receives focus.
      */
     areafocus: CustomEvent<MarkerAreaEventData>;
     /**
      * Marker area lost focus.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerArea} component loses focus.
      */
     areablur: CustomEvent<MarkerAreaEventData>;
     /**
      * Marker area state changed.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerArea} component's state changes.
+     *
+     * This is a good place to implement auto-saving or update the UI based on the current state.
      */
     areastatechange: CustomEvent<MarkerAreaEventData>;
     /**
      * Marker selected.
+     *
+     * @remarks
+     * This event is dispatched when a marker editor is selected.
+     * You can use this event to update the UI or perform actions based on the selected marker editor.
      */
     markerselect: CustomEvent<MarkerEditorEventData>;
     /**
      * Marker deselected.
+     *
+     * @remarks
+     * This event is dispatched when a marker editor is deselected.
+     * You can use this event to update the UI or perform actions based on the deselected marker editor.
      */
     markerdeselect: CustomEvent<MarkerEditorEventData>;
     /**
      * Marker creating.
+     *
+     * @remarks
+     * This event is dispatched when a marker creation has been initiated.
+     * You can use this event to update the UI or perform actions based on the marker creation process.
      */
     markercreating: CustomEvent<MarkerEditorEventData>;
     /**
      * Marker created.
+     *
+     * @remarks
+     * This event is dispatched when a marker has been created.
+     * You can use this event to update the UI or perform actions based on the created marker editor.
+     *
+     * One common use case is implementing continuous marker creation,
+     * where you create a new marker editor immediately after the previous one has been created.
+     *
+     * @example
+     * ```js
+     * // create another marker of the same type
+     * markerArea.addEventListener("markercreate", (ev) => {
+     *   markerArea.createMarker(ev.detail.markerEditor.marker.typeName);
+     * });
+     * ```
      */
     markercreate: CustomEvent<MarkerEditorEventData>;
     /**
      * Marker about to be deleted.
+     *
+     * @remarks
+     * This event is dispatched before a marker editor is deleted.
      */
     markerbeforedelete: CustomEvent<MarkerEditorEventData>;
     /**
      * Marker deleted.
+     *
+     * @remarks
+     * This event is dispatched after a marker editor is deleted.
+     * You can use this event to update the UI or perform actions based on the deleted marker editor.
      */
     markerdelete: CustomEvent<MarkerEditorEventData>;
     /**
      * Marker changed.
+     *
+     * @remarks
+     * This event is dispatched when a marker editor's state has changed.
      */
     markerchange: CustomEvent<MarkerEditorEventData>;
 }
@@ -2198,7 +2299,7 @@ declare class MarkerArea extends HTMLElement {
      * Deletes a marker represented by the specified editor.
      * @param markerEditor
      */
-    deleteMarker(markerEditor: MarkerBaseEditor): void;
+    deleteMarker(markerEditor: MarkerBaseEditor, suppressUndo?: boolean): void;
     /**
      * Deselects all markers.
      */
@@ -2827,7 +2928,7 @@ declare class TextBlockEditor {
      * Returns editor's UI,
      * @returns UI in a div element.
      */
-    getEditorUi(): HTMLDivElement;
+    getEditorUi(): HTMLTextAreaElement;
     /**
      * Focuses text editing in the editor.
      */
@@ -2969,47 +3070,102 @@ declare class CurveMarkerEditor<TMarkerType extends CurveMarker = CurveMarker> e
 }
 
 /**
- * Event map for {@link MarkerView}.
+ * Marker view custom event types.
+ *
+ * @summary
+ * Defines the custom events that can be dispatched by the {@link MarkerView} component.
+ *
+ * @remarks
+ * The `MarkerViewEventMap` interface defines the events that can be dispatched by the {@link MarkerView} component.
+ *
+ * You can listen to these events using the {@link MarkerView.addEventListener | addEventListener} method on the {@link MarkerView} instance.
+ *
+ * The events can be logically grouped into two categories:
+ * 1. Marker view events (start with `view`)
+ * 2. Marker events (start with `marker`).
+ *
+ * The marker view events are related to the overall state of the {@link MarkerView} component,
+ * while the marker events are related to the individual markers within the view.
+ *
+ * Marker view events receive {@link MarkerViewEventData} as their `event.detail`,
+ * while marker events receive {@link MarkerEventData} as their `event.detail`.
+ * Both event data types contain a reference to the {@link MarkerView} instance
+ * and, for marker events, a reference to the specific marker that triggered the event.
  */
 interface MarkerViewEventMap {
     /**
      * Viewer initialized.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerView} instance is created and initialized
+     * but none of its internal elements have been created yet.
      */
     viewinit: CustomEvent<MarkerViewEventData>;
     /**
      * Viewer shown.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerView} instance is fully initialized,
+     * its internal elements are created, and the target image is loaded.
+     * It indicates that the viewer is ready to display markers and annotations.
      */
     viewshow: CustomEvent<MarkerViewEventData>;
     /**
      * Viewer state restored.
+     *
+     * @remarks
+     * This event is dispatched when the {@link MarkerView} instance has restored a previously saved state.
+     * It indicates that the viewer has loaded markers and annotations from a saved state.
      */
     viewrestorestate: CustomEvent<MarkerViewEventData>;
     /**
      * Marker clicked.
+     *
+     * @remarks
+     * This event is dispatched when a marker within the {@link MarkerView} is clicked.
+     * It provides access to the clicked marker and the {@link MarkerView} instance.
      */
     markerclick: CustomEvent<MarkerEventData>;
     /**
      * Marker mouse over.
+     *
+     * @remarks
+     * This event is dispatched when the mouse pointer hovers over a marker within the {@link MarkerView}.
      */
     markerover: CustomEvent<MarkerEventData>;
     /**
      * Marker pointer down.
+     *
+     * @remarks
+     * This event is dispatched when a pointer (mouse, touch, etc.) is pressed down on a marker within the {@link MarkerView}.
      */
     markerpointerdown: CustomEvent<MarkerEventData>;
     /**
      * Marker pointer move.
+     *
+     * @remarks
+     * This event is dispatched when a pointer (mouse, touch, etc.) moves while over a marker within the {@link MarkerView}.
      */
     markerpointermove: CustomEvent<MarkerEventData>;
     /**
      * Marker pointer up.
+     *
+     * @remarks
+     * This event is dispatched when a pointer (mouse, touch, etc.) is released after being pressed down on a marker within the {@link MarkerView}.
      */
     markerpointerup: CustomEvent<MarkerEventData>;
     /**
      * Marker pointer enter.
+     *
+     * @remarks
+     * This event is dispatched when a pointer (mouse, touch, etc.) enters the area of a marker within the {@link MarkerView}.
      */
     markerpointerenter: CustomEvent<MarkerEventData>;
     /**
      * Marker pointer leave.
+     *
+     * @remarks
+     * This event is dispatched when a pointer (mouse, touch, etc.) leaves the area of a marker within the {@link MarkerView}.
      */
     markerpointerleave: CustomEvent<MarkerEventData>;
 }