[Share] Tag Annotations by Type in selected items

[mjthoraval]

Description

Tag annotations by type.
The script will apply the tagging to all the annotations selected, and to all the annotations within the attachments, parent items, collection or library selected. It does not modify the "Date Modified" property of the annotations, so that the annotations are not affected.
It is the counterpart of this other script to tag annotations by color: #577.

The script also removes outdated type tags for:

• Current tags: if the type of the annotation was changed (switch between highlight and underline)
• Old tags: if an old annotation type tag remains, as specified in a list of outdated tags to remove.

This is a temporary workaround to filter by annotation type until this is implemented in Zotero.

First test on a small number of items.

In order to keep the annotation type tags updated, you can add two other scripts calling this one, with Operation - Trigger Other Actions:

• When an annotation is created: Event Create Annotation.
• When a tab is closed: Event Close Tab.
• It is not yet possible to trigger an action when the type of an annotation is changed).

The tags applied here can be deleted with the following script: #580, using an updated list of tags to delete.

Event

None

Operation

Script

Data

/**
 * Tag annotations by type on selected items and remove outdated type tags.
 * @author mjthoraval with Claude AI
 * @link https://github.com/windingwind/zotero-actions-tags/discussions/581
 * @version v1.3, 5 March 2026
 * @changes Preserve dateModified when tagging annotations
 */
// Actions & Tags runs the script once per item and once for the collection.
// When triggered from the menu, skip per-item calls to avoid duplicate operations.
if (item) {
  if (triggerType === "menu") {
    return;
  }
  items = [item];
}

// Maps Zotero annotation types to their corresponding tags
const TYPE_TAGS = {
  "highlight": "#A🇭", // 🇭 for Highlight
  "underline": "#A🇺", // 🇺 for Underline
  "note":      "#A🇳", // 🇳 for Note
  "text":      "#A🇹", // 🇹 for Text
  "image":     "#A🇮", // 🇮 for Image (area screenshot)
  "ink":       "#A🇰", // 🇰 for inK (freehand drawing)
};

// Includes legacy tags that should be removed if found
const ALL_TYPE_TAGS_SET = new Set([
  ...Object.values(TYPE_TAGS),
  "#A_highlight", // legacy text tag for highlight
  "#A_underline", // legacy text tag for underline
  "#A_note",      // legacy text tag for note
  "#A_text",      // legacy text tag for text
  "#A_image",     // legacy text tag for image
  "#A_ink",       // legacy text tag for ink
]);

if (items?.length > 0) {
  let taggedCount = 0;
  let removedCount = 0;
  const toSave = [];

  for (const selectedItem of items) {
    let annotations = [];

    // Collect annotations depending on the type of selected item
    if (selectedItem.isAnnotation()) {
      annotations = [selectedItem];
    } else if (selectedItem.isFileAttachment()) {
      annotations = selectedItem.getAnnotations();
    } else if (selectedItem.isAttachment()) {
      continue; // Non-file attachments (e.g. URL links) have no annotations
    } else {
      // Regular item: collect annotations from all its file attachments
      const attachmentIDs = selectedItem.getAttachments();
      const attachments = attachmentIDs.map(id => Zotero.Items.get(id)).filter(a => a.isFileAttachment());
      for (const attachment of attachments) {
        annotations = annotations.concat(attachment.getAnnotations());
      }
    }

    for (const annot of annotations) {
      const correctTag = TYPE_TAGS[annot.annotationType];
      const currentTags = annot.getTags();
      let needsSave = false;

      // Remove any type tags that don't match the current annotation type
      for (const tag of currentTags) {
        if (ALL_TYPE_TAGS_SET.has(tag.tag) && tag.tag !== correctTag) {
          annot.removeTag(tag.tag);
          needsSave = true;
          removedCount++;
        }
      }

      // Add the correct type tag if not already present
      if (correctTag && !currentTags.some(t => t.tag === correctTag)) {
        annot.addTag(correctTag);
        needsSave = true;
        taggedCount++;
      }

      if (needsSave) {
        // Capture the original dateModified before saving
        toSave.push({ annot, originalDateModified: annot.dateModified });
      }
    }
  }

  // Save all modified annotations in a single transaction for efficiency
  if (toSave.length > 0) {
    await Zotero.DB.executeTransaction(async () => {
      for (const { annot, originalDateModified } of toSave) {
        await annot.save();
        // Restore the original dateModified directly in the DB
        await Zotero.DB.queryAsync(
          "UPDATE items SET dateModified = ? WHERE itemID = ?",
          [originalDateModified, annot.id]
        );
        // Sync the in-memory object to match the DB
        annot.dateModified = originalDateModified;
      }
    });
  }

  if (removedCount > 0 && taggedCount > 0) {
    return `Updated annotations: added ${taggedCount} new tag(s), removed ${removedCount} outdated tag(s).`;
  } else if (taggedCount > 0) {
    return `Tagged ${taggedCount} annotation(s) by type.`;
  } else if (removedCount > 0) {
    return `Removed ${removedCount} outdated type tag(s).`;
  } else {
    return `No changes needed.`;
  }
}