npm - @musodojo/note-collection-selector - Versions diffs - 5.3.0 → 6.0.0 - Mend

@musodojo/note-collection-selector 5.3.0 → 6.0.0

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.

Files changed (4) hide show

package/examples/example1.html CHANGED Viewed

@@ -14,19 +14,48 @@
         font-size: 1.5em;
       }
+      #wrapper {
+        display: flex;
+        gap: 1em;
+      }
+      button {
+        font: inherit;
+        background: none;
+      }
+      button,
       note-collection-selector::part(main-button) {
         border: 0.2em solid currentColor;
         border-radius: 0.6em;
         padding: 0.3em 1em;
+        background: linear-gradient(
+          45deg,
+          transparent,
+          light-dark(rgb(0 0 0 / 35%), rgb(255 255 255 / 35%))
+        );
       }
     </style>
   </head>
   <body>
-    <h2>Select a Note Collection</h2>
-    <note-collection-selector></note-collection-selector>
+    <h2>Select from a Note Collection Selector</h2>
+    <div id="wrapper">
+      <note-collection-selector></note-collection-selector>
+      <note-collection-selector>
+        <svg viewBox="0 0 100 100">
+          <circle cx="50" cy="50" r="50" fill="currentColor" />
+        </svg>
+      </note-collection-selector>
+      <note-collection-selector>
+        <img
+          src="./scale.png"
+          alt="scale"
+          style="object-fit: contain; border-radius: 0.2rem"
+        />
+      </note-collection-selector>
+    </div>
     <br />
-    <br />
-    <button id="random-button">Random Collection</button>
+    <button id="random-button">Randomize</button>
     <script type="module" src="../dist/bundle.js"></script>
     <script type="module">
@@ -36,12 +65,17 @@
           console.log("note collection selected:", event.detail);
         },
       );
-      const noteCollectionSelector = document.querySelector(
+      const noteCollectionSelector = document.querySelectorAll(
         "note-collection-selector",
       );
       const randomButton = document.getElementById("random-button");
       randomButton.addEventListener("click", () => {
-        noteCollectionSelector.setRandomNoteCollection();
+        noteCollectionSelector.forEach((selector) =>
+          selector.setRandomNoteCollection()
+        );
       });
     </script>
   </body>

package/examples/scale.png ADDED Viewed

Binary file

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@musodojo/note-collection-selector",
-  "version": "5.3.0",
+  "version": "6.0.0",
   "description": "A custom HTML element for selecting a note collection, and dispatching events with the details.",
   "keywords": [
     "music",

package/src/mod.ts CHANGED Viewed

@@ -1,11 +1,38 @@
+/**
+ * @module
+ * A custom element for selecting musical note collections (scales, chords, etc.).
+ *
+ * @fires {CustomEvent<NoteCollectionSelectedEventDetail>} note-collection-selected - Dispatched when a note collection is selected.
+ *
+ * @example
+ * ```html
+ * <note-collection-selector
+ *   id="my-selector"
+ *   selected-note-collection-key="ionian"
+ * ></note-collection-selector>
+ * ```
+ *
+ * ```javascript
+ * const selector = document.getElementById('my-selector');
+ * selector.addEventListener('note-collection-selected', (event) => {
+ *   console.log('Selected key:', event.detail.noteCollectionKey);
+ *   console.log('Selected collection:', event.detail.noteCollection);
+ * });
+ *
+ * // Programmatically change the selection
+ * selector.selectedNoteCollectionKey = 'dorian';
+ * ```
+ */
 import {
   groupedNoteCollections,
-  type NoteCollection,
-  type NoteCollectionGroupKey,
   noteCollectionGroupsMetadata,
-  type NoteCollectionKey,
   noteCollections,
 } from "@musodojo/music-theory-data";
+import type {
+  NoteCollection,
+  NoteCollectionGroupKey,
+  NoteCollectionKey,
+} from "@musodojo/music-theory-data";
 const noteCollectionSelectorTemplate = document.createElement("template");
 noteCollectionSelectorTemplate.innerHTML = /* HTML */ `
@@ -44,27 +71,29 @@ noteCollectionSelectorTemplate.innerHTML = /* HTML */ `
       min-width: var(--_main-icon-size);
-      > #main-button-text-span {
+      & > #main-button-text-span {
         grid-area: 1 / 1;
       }
-      > slot {
+      & > slot {
         height: var(--_main-icon-size);
       }
-      ::slotted(svg),
-      ::slotted(img),
-      > slot > svg {
-        grid-area: 1 / 1;
+      /* Size icons, but let text content flow naturally */
+      & > ::slotted(svg),
+      & > ::slotted(img),
+      & > slot > svg {
         width: var(--_main-icon-size);
         height: var(--_main-icon-size);
+        /* Ensure icons are on the same grid cell if multiple are slotted */
+        grid-area: 1 / 1;
       }
     }
     [part="dialog"] {
       padding: var(--_default-spacing);
-      > [part="close-dialog-button"] {
+      & > [part="close-dialog-button"] {
         display: grid;
         place-items: center;
         padding: var(--_default-spacing);
@@ -73,9 +102,9 @@ noteCollectionSelectorTemplate.innerHTML = /* HTML */ `
         margin-block-end: var(--_default-spacing);
         /* Size icons, but let text content flow naturally */
-        ::slotted(svg),
-        ::slotted(img),
-        > slot[name="close-dialog-icon"] > svg {
+        & > ::slotted(svg),
+        & > ::slotted(img),
+        & > slot[name="close-dialog-icon"] > svg {
           width: var(--_close-dialog-icon-size);
           height: var(--_close-dialog-icon-size);
           /* Ensure icons are on the same grid cell if multiple are slotted */
@@ -83,39 +112,42 @@ noteCollectionSelectorTemplate.innerHTML = /* HTML */ `
         }
       }
-      > #toggle-more-info-label {
+      & > [part="clear-selection-button"],
+      & > #toggle-more-info-label {
         padding: 0.5em;
         border: 0.1em solid currentColor;
         border-radius: 0.5em;
         cursor: pointer;
       }
-      > #note-collections-div {
+      & > #note-collections-div {
         display: flex;
         flex-direction: column;
-        gap: 1em;
-        margin-block-start: 2em;
+        gap: 2em;
+        margin-block-start: 1.5em;
-        > #note-collection-group-wrapper {
-          > #note-collection-group-div {
+        & > #note-collection-group-wrapper {
+          & > #note-collection-group-div {
             margin-block: 0.5em;
             display: flex;
             flex-wrap: wrap;
             gap: 1em;
           }
-          > h3 {
-            margin: 0em;
+          & > h3 {
+            margin: 0;
+            font-size: 1em;
+            font-variant: small-caps;
           }
         }
-      }
+      }
     }
     [part="dialog"]::backdrop {
       background: var(--_dialog-backdrop-background);
     }
-    .note-collection-option {
+    [part="note-collection-button"] {
       padding: 0.5em;
       min-width: 4ch;
       max-width: 80ch;
@@ -123,10 +155,16 @@ noteCollectionSelectorTemplate.innerHTML = /* HTML */ `
       border-radius: 0.5em;
       cursor: pointer;
       text-align: left;
-      text-wrap: pretty; /* Enable smart text wrapping if supported */
+      text-wrap: pretty;
+      & > .note-collection-name {
+        /* font-weight: bold; */
+        font-size: 0.9em;
+      }
-      > h4 {
-        margin-block: 0.2em;
+      /* Style for the currently selected option */
+      &[data-selected="true"] {
+        outline: 0.3em double light-dark(black, white);
       }
       /* When the "more info" div is hidden, center the text */
@@ -134,13 +172,14 @@ noteCollectionSelectorTemplate.innerHTML = /* HTML */ `
         text-align: center;
       }
-      > .more-info-div {
+      & > .more-info-div {
         display: flex;
         flex-direction: column;
         gap: 0.5em;
       }
-      > .more-info-div.hidden {
+      /* needed a .hidden with a higher specificity here */
+      & > .more-info-div.hidden {
         display: none;
       }
     }
@@ -196,6 +235,8 @@ noteCollectionSelectorTemplate.innerHTML = /* HTML */ `
       more info
     </label>
+     <button part="clear-selection-button">Clear Selection</button>
     <div id="note-collections-div">
       <!-- the buttons in here are dynamically generated
        each with an attribute of part="note-collection-button" -->
@@ -203,11 +244,20 @@ noteCollectionSelectorTemplate.innerHTML = /* HTML */ `
   </dialog>
 `;
+/**
+ * The detail object for the `note-collection-selected` custom event.
+ */
 export interface NoteCollectionSelectedEventDetail {
+  /** The unique key of the selected note collection (e.g., "ionian"), or `null` if cleared. */
   noteCollectionKey: NoteCollectionKey | null;
+  /** The full data object for the selected note collection, or `null` if cleared. */
   noteCollection: NoteCollection | null;
 }
+/**
+ * A web component that allows users to select a musical note collection.
+ * It displays a button which, when clicked, opens a dialog with a list of options.
+ */
 export class NoteCollectionSelector extends HTMLElement {
   #shadowRoot: ShadowRoot;
@@ -219,16 +269,29 @@ export class NoteCollectionSelector extends HTMLElement {
   #dialog!: HTMLDialogElement;
   #closeDialogButton!: HTMLButtonElement;
   #toggleMoreInfoCheckbox!: HTMLInputElement;
+  #clearSelectionButton!: HTMLButtonElement;
   #noteCollectionsDiv!: HTMLDivElement;
+  /** Caches the currently selected button element in the dialog to avoid re-querying the DOM. */
+  #selectedButtonElement: HTMLButtonElement | null = null;
+  /** Manages event listeners to allow for cleanup on disconnection. */
   #abortController: AbortController | null = null;
+  /** The internal state for the selected note collection key (e.g., "ionian"). */
   #selectedNoteCollectionKey: NoteCollectionKey | null = null;
+  /** The internal state for the selected note collection key's matching object. */
   #selectedNoteCollection: NoteCollection | null = null;
+  /**
+   * Specifies which attributes should trigger `attributeChangedCallback` when they change.
+   */
   static get observedAttributes(): string[] {
     return ["selected-note-collection-key"];
   }
+  /**
+   * Initializes the component by creating the shadow DOM and caching essential elements.
+   */
   constructor() {
     super();
     this.#shadowRoot = this.attachShadow({ mode: "open" });
@@ -238,17 +301,32 @@ export class NoteCollectionSelector extends HTMLElement {
     this.#cacheDomElements();
   }
+  /**
+   * Called when the element is inserted into the DOM.
+   * Finalizes setup by populating dynamic content and attaching event listeners.
+   */
   connectedCallback() {
     this.#populateNoteCollectionsDiv();
     this.#addEventListeners();
-    this.#updateMainButton();
     this.#syncSelectedNoteCollectionKeyAttribute();
+    this.#updateSelectedButtonElementState();
+    this.#updateMainButton();
   }
+  /**
+   * Called when the element is removed from the DOM.
+   * Cleans up by aborting any pending operations and removing event listeners.
+   */
   disconnectedCallback() {
     this.#abortController?.abort();
   }
+  /**
+   * Called when an observed attribute of the custom element is added, removed, or changed.
+   * @param name - The name of the attribute that changed.
+   * @param oldValue - The old value of the attribute.
+   * @param newValue - The new value of the attribute.
+   */
   attributeChangedCallback(
     name: string,
     oldValue: string | null,
@@ -256,14 +334,20 @@ export class NoteCollectionSelector extends HTMLElement {
   ) {
     // Only proceed if the attribute's value has actually changed
     if (oldValue === newValue) return;
-    if (name === "selected-note-collection-key") {
-      // Update the internal state with the new key
-      this.selectedNoteCollectionKey = newValue as NoteCollectionKey | null;
-      // Dispatch the selection event to notify consumers of the change
-      this.#dispatchNoteCollectionSelectedEvent();
+    switch (name) {
+      case "selected-note-collection-key":
+        this.selectedNoteCollectionKey = newValue as NoteCollectionKey | null;
+        break;
+      default:
+        console.log("Unexpected attribute changed:", name);
     }
   }
+  /**
+   * Queries the shadow DOM for critical elements and caches them as private properties.
+   * Throws an error if any required element is not found, failing early.
+   */
   #cacheDomElements() {
     const mainButton = this.#shadowRoot.querySelector<HTMLButtonElement>(
       '[part="main-button"]',
@@ -289,6 +373,12 @@ export class NoteCollectionSelector extends HTMLElement {
       "#toggle-more-info-checkbox",
     );
+    const clearSelectionButton = this.#shadowRoot.querySelector<
+      HTMLButtonElement
+    >(
+      '[part="clear-selection-button"]',
+    );
     const noteCollectionsDiv = this.#shadowRoot.querySelector<HTMLDivElement>(
       "#note-collections-div",
     );
@@ -299,8 +389,9 @@ export class NoteCollectionSelector extends HTMLElement {
       !mainButtonSlot ||
       !dialog ||
       !closeDialogButton ||
-      !noteCollectionsDiv ||
-      !toggleMoreInfoCheckbox
+      !toggleMoreInfoCheckbox ||
+      !clearSelectionButton ||
+      !noteCollectionsDiv
     ) {
       throw new Error(
         "NoteCollectionSelector: Critical elements not found in shadow DOM.",
@@ -313,40 +404,13 @@ export class NoteCollectionSelector extends HTMLElement {
     this.#dialog = dialog;
     this.#closeDialogButton = closeDialogButton;
     this.#toggleMoreInfoCheckbox = toggleMoreInfoCheckbox;
+    this.#clearSelectionButton = clearSelectionButton;
     this.#noteCollectionsDiv = noteCollectionsDiv;
   }
-  #addEventListeners() {
-    // abort any previous controllers before creating a new one
-    this.#abortController?.abort();
-    this.#abortController = new AbortController();
-    const { signal } = this.#abortController;
-    this.#mainButton.addEventListener(
-      "click",
-      () => {
-        this.#dialog.showModal();
-      },
-      { signal },
-    );
-    this.#closeDialogButton.addEventListener(
-      "click",
-      () => {
-        this.#dialog.close();
-      },
-      { signal },
-    );
-    this.#toggleMoreInfoCheckbox.addEventListener(
-      "change",
-      () => {
-        this.#updateMoreInfoVisibility();
-      },
-      { signal },
-    );
-  }
+  /**
+   * Dynamically generates and populates the note collection buttons in the dialog.
+   */
   #populateNoteCollectionsDiv() {
     const frag = document.createDocumentFragment();
@@ -357,9 +421,7 @@ export class NoteCollectionSelector extends HTMLElement {
         // wrapper for heading and note-collection
         const groupWrapper = document.createElement("div");
         groupWrapper.id = "note-collection-group-wrapper";
-        groupWrapper.innerHTML = /* HTML */ `<h3>
-          ${groupMetadata.displayName}
-        </h3>`;
+        groupWrapper.innerHTML = `<h3>${groupMetadata.displayName}</h3>`;
         // more info on the group (can hide)
         const groupMoreInfoDiv = document.createElement("div");
@@ -377,26 +439,23 @@ export class NoteCollectionSelector extends HTMLElement {
         Object.entries(currentNoteCollectionGroup).forEach(
           ([key, collection]) => {
-            const noteCollectionDiv = document.createElement("div");
-            noteCollectionDiv.classList.add("note-collection-option");
-            noteCollectionDiv.innerHTML = /* HTML */ `<h4>
+            const noteCollectionBtn = document.createElement("button");
+            noteCollectionBtn.setAttribute("part", "note-collection-button");
+            // Set a data attribute to use later
+            noteCollectionBtn.dataset.noteCollectionKey = key;
+            noteCollectionBtn.innerHTML = /* HTML */ `<span
+              class="note-collection-name"
+            >
               ${collection.primaryName}
-            </h4>`;
+            </span>`;
             const collectionMoreInfoDiv = document.createElement("div");
             collectionMoreInfoDiv.classList.add("more-info-div", "hidden");
-            collectionMoreInfoDiv.innerHTML = this.#renderMoreInfo(collection);
-            noteCollectionDiv.appendChild(collectionMoreInfoDiv);
-            noteCollectionDiv.addEventListener("click", () => {
-              this.#selectedNoteCollectionKey = key as NoteCollectionKey;
-              this.#selectedNoteCollection = collection;
-              this.#updateMainButton();
-              this.#syncSelectedNoteCollectionKeyAttribute();
-              this.#dialog.close();
-            });
-            noteCollectionGroupDiv.appendChild(noteCollectionDiv);
+            collectionMoreInfoDiv.innerHTML = this.#getMoreInfoHTMLString(
+              collection,
+            );
+            noteCollectionBtn.appendChild(collectionMoreInfoDiv);
+            noteCollectionGroupDiv.appendChild(noteCollectionBtn);
           },
         );
@@ -408,36 +467,69 @@ export class NoteCollectionSelector extends HTMLElement {
   }
   /**
-   * Renders the detailed "more info" content for a given note collection.
-   * @private
-   * @param {NoteCollection} noteCollection - The note collection data object.
-   * @returns {string} An HTML string containing the detailed information.
+   * Attaches all necessary event listeners for the component's interactive elements.
+   * Uses an AbortController to facilitate easy cleanup on disconnection.
    */
-  #renderMoreInfo(noteCollection: NoteCollection): string {
-    // TODO: replace this with updated code
-    // <div>${noteCollection.exampleNotes.join(", ")}</div>
-    return /* HTML */ `
-      <div>${noteCollection.names.join(", ")}</div>
-      <div>${noteCollection.intervals.join(", ")}</div>
-      <div>${noteCollection.type.join(", ")}</div>
-      <div>${noteCollection.characteristics.join(", ")}</div>
-      <div>${noteCollection.patternShort.join("-")}</div>
-      <div>${noteCollection.pattern.join(", ")}</div>
-    `;
-  }
+  #addEventListeners() {
+    // abort any previous controllers before creating a new one
+    this.#abortController?.abort();
+    this.#abortController = new AbortController();
+    const { signal } = this.#abortController;
-  /**
-   * Toggles the visibility of all "more info" sections within the element
-   * based on the state of the `toggleMoreInfoCheckbox`.
-   * @private
-   */
-  #updateMoreInfoVisibility() {
-    const moreInfoElements = this.#shadowRoot?.querySelectorAll(
-      ".more-info-div",
-    ) as NodeListOf<HTMLDivElement>;
-    moreInfoElements.forEach((el) => {
-      el.classList.toggle("hidden", !this.#toggleMoreInfoCheckbox!.checked);
-    });
+    this.#mainButton.addEventListener(
+      "click",
+      () => {
+        this.#dialog.showModal();
+        this.#selectedButtonElement?.scrollIntoView({
+          block: "center",
+          behavior: "smooth",
+        });
+      },
+      { signal },
+    );
+    this.#closeDialogButton.addEventListener(
+      "click",
+      () => {
+        this.#dialog.close();
+      },
+      { signal },
+    );
+    this.#toggleMoreInfoCheckbox.addEventListener(
+      "change",
+      () => {
+        this.#updateMoreInfoVisibility();
+      },
+      { signal },
+    );
+    this.#clearSelectionButton.addEventListener(
+      "click",
+      () => {
+        this.selectedNoteCollectionKey = null;
+        this.#dialog.close();
+      },
+      { signal },
+    );
+    this.#noteCollectionsDiv.addEventListener(
+      "click",
+      (event) => {
+        const button = (event.target as HTMLElement).closest<HTMLButtonElement>(
+          '[part="note-collection-button"]',
+        );
+        if (button) {
+          this.selectedNoteCollectionKey =
+            button.dataset.noteCollectionKey as NoteCollectionKey ??
+              null;
+          this.#dialog.close();
+        } else {
+          console.warn("no note collection button found");
+        }
+      },
+      { signal },
+    );
   }
   /**
@@ -465,13 +557,65 @@ export class NoteCollectionSelector extends HTMLElement {
     }
   }
+  #updateSelectedButtonElementState() {
+    // Clear the highlight from the previously selected button
+    if (this.#selectedButtonElement) {
+      this.#selectedButtonElement.removeAttribute("data-selected");
+      this.#selectedButtonElement = null;
+    }
+    // Add the highlight to the newly selected button
+    if (this.#selectedNoteCollectionKey) {
+      const newSelectedButton = this.#noteCollectionsDiv.querySelector<
+        HTMLButtonElement
+      >(
+        `[data-note-collection-key="${this.#selectedNoteCollectionKey}"]`,
+      );
+      newSelectedButton?.setAttribute("data-selected", "true");
+      this.#selectedButtonElement = newSelectedButton;
+    }
+  }
+  /**
+   * Renders the detailed "more info" content for a given note collection.
+   * @private
+   * @param {NoteCollection} noteCollection - The note collection data object.
+   * @returns {string} A HTML string containing the detailed information.
+   */
+  #getMoreInfoHTMLString(noteCollection: NoteCollection): string {
+    // TODO: replace this with updated code
+    // <div>${noteCollection.exampleNotes.join(", ")}</div>
+    return /* HTML */ `
+      <div>${noteCollection.names.join(", ")}</div>
+      <div>${noteCollection.intervals.join(", ")}</div>
+      <div>${noteCollection.type.join(", ")}</div>
+      <div>${noteCollection.characteristics.join(", ")}</div>
+      <div>${noteCollection.patternShort.join("-")}</div>
+      <div>${noteCollection.pattern.join(", ")}</div>
+    `;
+  }
+  /**
+   * Toggles the visibility of all "more info" sections within the element
+   * based on the state of the `toggleMoreInfoCheckbox`.
+   * @private
+   */
+  #updateMoreInfoVisibility() {
+    const moreInfoElements = this.#shadowRoot?.querySelectorAll(
+      ".more-info-div",
+    ) as NodeListOf<HTMLDivElement>;
+    moreInfoElements.forEach((el) => {
+      el.classList.toggle("hidden", !this.#toggleMoreInfoCheckbox.checked);
+    });
+  }
   /**
    * Synchronizes the `selected-note-collection-key` attribute on the host element
    * with the component's internal state.
    * @private
    */
   #syncSelectedNoteCollectionKeyAttribute() {
-    if (this.#selectedNoteCollectionKey) {
+    if (this.#selectedNoteCollectionKey !== null) {
       this.setAttribute(
         "selected-note-collection-key",
         this.#selectedNoteCollectionKey,
@@ -515,6 +659,8 @@ export class NoteCollectionSelector extends HTMLElement {
       noteCollections,
     ) as NoteCollectionKey[];
+    if (noteCollectionKeys.length <= 1) return;
     let randomNoteCollectionKey: NoteCollectionKey;
     // Keep selecting at random until it's different from the current one.
@@ -528,7 +674,9 @@ export class NoteCollectionSelector extends HTMLElement {
   /**
    * Gets the unique key of the currently selected note collection.
-   * @prop {NoteCollectionKey | null} selectedNoteCollectionKey
+   * Setting this property updates the component's selection and dispatches a `note-collection-selected` event.
+   *
+   * @attr {NoteCollectionKey | null} selected-note-collection-key - Reflects the selected note collection key.
    * @returns {NoteCollectionKey | null} The note collection key (e.g., "ionian") or `null` if no collection is selected.
    */
   get selectedNoteCollectionKey(): NoteCollectionKey | null {
@@ -539,34 +687,52 @@ export class NoteCollectionSelector extends HTMLElement {
    * Sets the currently selected note collection by its unique key.
    * This will update the component's display and internal state. If a valid key
    * is provided, the corresponding `NoteCollection` object will be looked up
-   * and stored internally. Setting to `null` clears the selection.
+   * and stored internally along witht the key.
+   * An invalid key is equivalent to setting the key to null.
+   * Setting to `null` clears the selection.
    * @param {NoteCollectionKey | null} newNoteCollectionKey - The unique key of the note collection to select.
-   * @prop {NoteCollectionKey | null} selectedNoteCollectionKey
    */
   set selectedNoteCollectionKey(
     newNoteCollectionKey: NoteCollectionKey | null,
   ) {
-    // Look up the full note collection object based on the key,
-    // set values to null if key is null or invalid
-    if (
-      newNoteCollectionKey !== null &&
-      noteCollections[newNoteCollectionKey] !== undefined
-    ) {
-      this.#selectedNoteCollectionKey = newNoteCollectionKey;
-      this.#selectedNoteCollection = noteCollections[newNoteCollectionKey];
-    } else {
-      this.#selectedNoteCollectionKey = null;
-      this.#selectedNoteCollection = null;
+    // Resolve the input to a valid key or null
+    const resolvedNoteCollection =
+      noteCollections[newNoteCollectionKey as NoteCollectionKey] as
+        | NoteCollection
+        | undefined;
+    const resolvedKey = newNoteCollectionKey !== null &&
+        resolvedNoteCollection !== undefined
+      ? newNoteCollectionKey
+      : null;
+    const hasChanged = this.#selectedNoteCollectionKey !== resolvedKey;
+    if (hasChanged) {
+      this.#selectedNoteCollectionKey = resolvedKey;
+      this.#selectedNoteCollection = resolvedKey
+        ? resolvedNoteCollection as NoteCollection
+        : null;
+    }
+    // Only perform DOM updates and dispatch events if the component is connected
+    if (this.isConnected) {
+      // invalid values must sync attribute to null no matter what
+      // e.g. A user or script sets the attribute to an invalid value
+      // <note-collection-selector selected-note-collection-key="InvalidValue">
+      // should be synced to null
+      this.#syncSelectedNoteCollectionKeyAttribute();
+      if (hasChanged) {
+        this.#updateMainButton();
+        this.#updateSelectedButtonElementState();
+        this.#dispatchNoteCollectionSelectedEvent();
+      }
     }
-    this.#updateMainButton();
-    this.#syncSelectedNoteCollectionKeyAttribute();
-    // No need to dispatch event here, as attributeChangedCallback will do it
   }
   /**
    * Gets the full data object for the currently selected note collection.
-   * This property is read-only and is derived from `selectedNoteCollectionKey`.
-   * @prop {NoteCollection | null} selectedNoteCollection
+   * This property is read-only and is derived from the `selectedNoteCollectionKey`.
+   *
    * @returns {NoteCollection | null} The full note collection object or `null` if no collection is selected.
    * @readonly
    */