@musodojo/note-collection-selector 5.0.0

package/LICENSE

@@ -0,0 +1,122 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.
+

package/README.md

@@ -0,0 +1,6 @@
+# Note Sequence Selector Web Component
+
+A versatile web component for interactively selecting and exploring musical note
+collections, such as diatonic modes, dominant variants, and more. This component
+provides a user-friendly interface for musicians, educators, and developers
+working with music theory concepts.

package/examples/example1.html

@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Note collection Selector Example</title>
+    <style>
+      :root {
+        color-scheme: dark light;
+        font-family:
+          system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+          Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue",
+          sans-serif;
+        font-size: 1.5em;
+      }
+
+      note-collection-selector::part(main-button) {
+        border: 0.2em solid currentColor;
+        border-radius: 0.6em;
+        padding: 0.3em 1em;
+      }
+    </style>
+  </head>
+  <body>
+    <h2>Select a Note Collection</h2>
+    <note-collection-selector></note-collection-selector>
+    <br />
+    <br />
+    <button id="random-button">Random Collection</button>
+
+    <script type="module" src="../dist/bundle.js"></script>
+    <script type="module">
+      document.body.addEventListener(
+        "note-collection-selected",
+        (event) => {
+          console.log("note collection selected:", event.detail);
+        },
+      );
+      const noteCollectionSelector = document.querySelector(
+        "note-collection-selector",
+      );
+      const randomButton = document.getElementById("random-button");
+      randomButton.addEventListener("click", () => {
+        noteCollectionSelector.setRandomNoteCollection();
+      });
+    </script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@musodojo/note-collection-selector",
+  "version": "5.0.0",
+  "description": "A custom HTML element for selecting a note collection, and dispatching events with the details.",
+  "keywords": [
+    "music",
+    "theory"
+  ],
+  "license": "CC0-1.0",
+  "author": "Conor Dowdall",
+  "type": "module",
+  "main": "src/mod.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/conor-dowdall/note-collection-selector.git"
+  },
+  "bugs": {
+    "url": "https://github.com/conor-dowdall/note-collection-selector/issues"
+  },
+  "dependencies": {
+    "@musodojo/music-theory-data": "^20.2.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "bundle": "esbuild src/mod.ts --bundle --minify --platform=browser --outfile=dist/bundle.js"
+  }
+}

package/src/mod.ts

@@ -0,0 +1,582 @@
+import {
+  groupedNoteCollections,
+  type NoteCollection,
+  type NoteCollectionGroupKey,
+  noteCollectionGroupsMetadata,
+  type NoteCollectionKey,
+  noteCollections,
+} from "@musodojo/music-theory-data";
+
+const noteCollectionSelectorTemplate = document.createElement("template");
+noteCollectionSelectorTemplate.innerHTML = /* HTML */ `
+  <style>
+    :host {
+      --_main-icon-size: var(--main-icon-size, 2.5ch);
+      --_close-dialog-icon-size: var(--close-dialog-icon-size, 2ch);
+
+      --_dialog-backdrop-background: var(
+        --dialog-backdrop-background,
+        light-dark(rgb(255 255 255 / 50%), rgb(0 0 0 / 50%))
+      );
+
+      --_default-spacing: var(--default-spacing, 0.5em);
+
+      display: inline-block;
+      font-size: inherit;
+    }
+
+    button {
+      font: inherit;
+      margin: 0;
+      padding: 0;
+      cursor: pointer;
+      background: none;
+      border: none;
+    }
+
+    svg {
+      fill: currentColor;
+    }
+
+    [part="main-button"] {
+      display: grid;
+      place-items: center;
+
+      min-width: var(--_main-icon-size);
+
+      > #main-button-text-span {
+        grid-area: 1 / 1;
+      }
+
+      > slot {
+        height: var(--_main-icon-size);
+      }
+
+      ::slotted(svg),
+      ::slotted(img),
+      > slot > svg {
+        grid-area: 1 / 1;
+        width: var(--_main-icon-size);
+        height: var(--_main-icon-size);
+      }
+    }
+
+    [part="dialog"] {
+      padding: var(--_default-spacing);
+
+      > [part="close-dialog-button"] {
+        display: grid;
+        place-items: center;
+        padding: var(--_default-spacing);
+        border: none;
+        margin-inline-start: auto;
+        margin-block-end: var(--_default-spacing);
+
+        /* Size icons, but let text content flow naturally */
+        ::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 */
+          grid-area: 1 / 1;
+        }
+      }
+
+      > #toggle-more-info-label {
+        padding: 0.5em;
+        border: 0.1em solid currentColor;
+        border-radius: 0.5em;
+        cursor: pointer;
+      }
+
+      > #note-collections-div {
+        display: flex;
+        flex-direction: column;
+        gap: 1em;
+        margin-block-start: 2em;
+
+        > #note-collection-group-wrapper {
+          > #note-collection-group-div {
+            margin-block: 0.5em;
+            display: flex;
+            flex-wrap: wrap;
+            gap: 1em;
+          }
+
+          > h3 {
+            margin: 0em;
+          }
+        }
+      }
+    }
+
+    [part="dialog"]::backdrop {
+      background: var(--_dialog-backdrop-background);
+    }
+
+    .note-collection-option {
+      padding: 0.5em;
+      min-width: 4ch;
+      max-width: 80ch;
+      border: 0.1em solid currentColor;
+      border-radius: 0.5em;
+      cursor: pointer;
+      text-align: left;
+      text-wrap: pretty; /* Enable smart text wrapping if supported */
+
+      > h4 {
+        margin-block: 0.2em;
+      }
+
+      /* When the "more info" div is hidden, center the text */
+      &:has(> .more-info-div.hidden) {
+        text-align: center;
+      }
+
+      > .more-info-div {
+        display: flex;
+        flex-direction: column;
+        gap: 0.5em;
+      }
+
+      > .more-info-div.hidden {
+        display: none;
+      }
+    }
+
+    .hidden {
+      display: none;
+    }
+
+    .visually-hidden {
+      clip: rect(0 0 0 0);
+      clip-path: inset(50%);
+      height: 1px;
+      overflow: hidden;
+      position: absolute;
+      white-space: nowrap;
+      width: 1px;
+    }
+  </style>
+
+  <button part="main-button">
+    <span id="main-button-text-span" style="display: none;"></span>
+    <slot>
+      <!-- Default icon when no note is selected. Can be overridden by the user. This
+      SVG is part of the project and is licensed under CC0 1.0 Universal. -->
+      <svg viewBox="0 -960 960 960">
+        <path
+          d="M 705 -793.04688 A 158.9 237.09 59.29 0 0 564.0625 -748.82812 A 158.9 237.09 59.29 0 0 423.51562 -551.09375 A 158.9 237.09 59.29 0 0 423.51562 -546.71875 L 423.51562 -530.3125 A 158.9 237.09 59.29 0 0 239.0625 -487.96875 A 158.9 237.09 59.29 0 0 113.125 -230.46875 A 158.9 237.09 59.29 0 0 255.78125 -167.73438 A 158.9 237.09 59.29 0 0 396.71875 -211.95312 A 158.9 237.09 59.29 0 0 537.26562 -409.6875 A 158.9 237.09 59.29 0 0 537.26562 -414.0625 L 537.26562 -430.46875 A 158.9 237.09 59.29 0 0 721.71875 -472.8125 A 158.9 237.09 59.29 0 0 847.65625 -730.3125 A 158.9 237.09 59.29 0 0 705 -793.04688 z M 642.89062 -610.78125 L 476.32812 -513.51562 A 158.9 237.09 59.29 0 0 476.25 -513.59375 L 642.89062 -610.78125 z M 484.45312 -447.26562 A 158.9 237.09 59.29 0 0 484.53125 -447.1875 L 317.89062 -350 L 484.45312 -447.26562 z"
+        />
+      </svg>
+    </slot>
+  </button>
+
+  <dialog part="dialog" aria-labelledby="dialog-heading">
+    <button part="close-dialog-button" aria-label="Close Dialog">
+      <slot name="close-dialog-icon">
+        <!-- Default icon when no note is selected. Can be overridden by the user. 
+         This SVG is part of the project and is licensed under CC0 1.0 Universal. -->
+        <svg viewBox="0 -960 960 960">
+          <path
+            transform="rotate(-45)"
+            d="m638.82-400h80v800h-80zm-360 360h800v80h-800z"
+          />
+        </svg>
+      </slot>
+    </button>
+
+    <h2 id="dialog-heading" class="visually-hidden">
+      Select a Note Collection
+    </h2>
+
+    <label id="toggle-more-info-label">
+      <input type="checkbox" id="toggle-more-info-checkbox" />
+      more info
+    </label>
+
+    <div id="note-collections-div">
+      <!-- the buttons in here are dynamically generated 
+       each with an attribute of part="note-collection-button" -->
+    </div>
+  </dialog>
+`;
+
+export interface NoteCollectionSelectedEventDetail {
+  noteCollectionKey: NoteCollectionKey | null;
+  noteCollection: NoteCollection | null;
+}
+
+export class NoteCollectionSelector extends HTMLElement {
+  #shadowRoot: ShadowRoot;
+
+  // cache these critical elements in the constructor with #cacheDomElements()
+  // and throw an error if they are not found
+  #mainButton!: HTMLButtonElement;
+  #mainButtonTextSpan!: HTMLSpanElement;
+  #mainButtonSlot!: HTMLSlotElement;
+  #dialog!: HTMLDialogElement;
+  #closeDialogButton!: HTMLButtonElement;
+  #toggleMoreInfoCheckbox!: HTMLInputElement;
+  #noteCollectionsDiv!: HTMLDivElement;
+
+  #abortController: AbortController | null = null;
+  #selectedNoteCollectionKey: NoteCollectionKey | null = null;
+  #selectedNoteCollection: NoteCollection | null = null;
+
+  static get observedAttributes(): string[] {
+    return ["selected-note-collection-key"];
+  }
+
+  constructor() {
+    super();
+    this.#shadowRoot = this.attachShadow({ mode: "open" });
+    this.#shadowRoot.appendChild(
+      noteCollectionSelectorTemplate.content.cloneNode(true),
+    );
+    this.#cacheDomElements();
+  }
+
+  connectedCallback() {
+    this.#populateNoteCollectionsDiv();
+    this.#addEventListeners();
+    this.#updateMainButton();
+    this.#syncSelectedNoteCollectionKeyAttribute();
+  }
+
+  disconnectedCallback() {
+    this.#abortController?.abort();
+  }
+
+  attributeChangedCallback(
+    name: string,
+    oldValue: string | null,
+    newValue: string | null,
+  ) {
+    // 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();
+    }
+  }
+
+  #cacheDomElements() {
+    const mainButton = this.#shadowRoot.querySelector<HTMLButtonElement>(
+      '[part="main-button"]',
+    );
+
+    const mainButtonTextSpan = this.#shadowRoot.querySelector<HTMLSpanElement>(
+      "#main-button-text-span",
+    );
+
+    const mainButtonSlot = mainButton?.querySelector<HTMLSlotElement>("slot");
+
+    const dialog = this.#shadowRoot.querySelector<HTMLDialogElement>(
+      '[part="dialog"]',
+    );
+
+    const closeDialogButton = this.#shadowRoot.querySelector<HTMLButtonElement>(
+      '[part="close-dialog-button"]',
+    );
+
+    const toggleMoreInfoCheckbox = this.#shadowRoot.querySelector<
+      HTMLInputElement
+    >(
+      "#toggle-more-info-checkbox",
+    );
+
+    const noteCollectionsDiv = this.#shadowRoot.querySelector<HTMLDivElement>(
+      "#note-collections-div",
+    );
+
+    if (
+      !mainButton ||
+      !mainButtonTextSpan ||
+      !mainButtonSlot ||
+      !dialog ||
+      !closeDialogButton ||
+      !noteCollectionsDiv ||
+      !toggleMoreInfoCheckbox
+    ) {
+      throw new Error(
+        "NoteCollectionSelector: Critical elements not found in shadow DOM.",
+      );
+    }
+
+    this.#mainButton = mainButton;
+    this.#mainButtonTextSpan = mainButtonTextSpan;
+    this.#mainButtonSlot = mainButtonSlot;
+    this.#dialog = dialog;
+    this.#closeDialogButton = closeDialogButton;
+    this.#toggleMoreInfoCheckbox = toggleMoreInfoCheckbox;
+    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 },
+    );
+  }
+
+  #populateNoteCollectionsDiv() {
+    const frag = document.createDocumentFragment();
+
+    // for each note collection group, add a wrapper div, which contains
+    // a heading and a note collection group div
+    Object.entries(noteCollectionGroupsMetadata).forEach(
+      ([groupKey, groupMetadata]) => {
+        // wrapper for heading and note-collection
+        const groupWrapper = document.createElement("div");
+        groupWrapper.id = "note-collection-group-wrapper";
+        groupWrapper.innerHTML = /* HTML */ `<h3>
+          ${groupMetadata.displayName}
+        </h3>`;
+
+        // more info on the group (can hide)
+        const groupMoreInfoDiv = document.createElement("div");
+        groupMoreInfoDiv.classList.add("more-info-div", "hidden");
+        groupMoreInfoDiv.textContent = `${groupMetadata.description}`;
+        groupWrapper.appendChild(groupMoreInfoDiv);
+
+        // div to group the current group of note collections
+        const noteCollectionGroupDiv = document.createElement("div");
+        noteCollectionGroupDiv.id = "note-collection-group-div";
+        groupWrapper.appendChild(noteCollectionGroupDiv);
+
+        const currentNoteCollectionGroup =
+          groupedNoteCollections[groupKey as NoteCollectionGroupKey];
+
+        Object.entries(currentNoteCollectionGroup).forEach(
+          ([key, collection]) => {
+            const noteCollectionDiv = document.createElement("div");
+            noteCollectionDiv.classList.add("note-collection-option");
+            noteCollectionDiv.innerHTML = /* HTML */ `<h4>
+              ${collection.primaryName}
+            </h4>`;
+
+            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);
+          },
+        );
+
+        frag.appendChild(groupWrapper);
+      },
+    );
+
+    this.#noteCollectionsDiv.replaceChildren(frag);
+  }
+
+  /**
+   * 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.
+   */
+  #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>
+    `;
+  }
+
+  /**
+   * 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);
+    });
+  }
+
+  /**
+   * Updates the text content of the main note selector button to reflect
+   * the `primaryName` of the currently selected note collection, or a default text.
+   * @private
+   */
+  #updateMainButton() {
+    if (
+      this.#selectedNoteCollectionKey !== null &&
+      this.#selectedNoteCollection !== null
+    ) {
+      // State when a note is selected
+      this.#mainButtonTextSpan.textContent =
+        this.#selectedNoteCollection.primaryName;
+      this.#mainButtonTextSpan.style.display = "initial";
+      this.#mainButtonSlot.style.display = "none";
+      this.#mainButton.ariaLabel =
+        `${this.#selectedNoteCollection.primaryName} selected`;
+    } else {
+      // Default state when no note is selected
+      this.#mainButtonTextSpan.style.display = "none";
+      this.#mainButtonSlot.style.display = "initial";
+      this.#mainButton.ariaLabel = "Select Note Collection";
+    }
+  }
+
+  /**
+   * Synchronizes the `selected-note-collection-key` attribute on the host element
+   * with the component's internal state.
+   * @private
+   */
+  #syncSelectedNoteCollectionKeyAttribute() {
+    if (this.#selectedNoteCollectionKey) {
+      this.setAttribute(
+        "selected-note-collection-key",
+        this.#selectedNoteCollectionKey,
+      );
+    } else {
+      this.removeAttribute("selected-note-collection-key");
+    }
+  }
+
+  /**
+   * Dispatches a custom event named 'note-collection-selected' when a note collection is chosen.
+   * The event bubbles and composes, carrying the key and the full data object of the selected note collection.
+   * @private
+   * @fires NoteSequenceSelectedEvent
+   */
+  #dispatchNoteCollectionSelectedEvent() {
+    this.dispatchEvent(
+      new CustomEvent<NoteCollectionSelectedEventDetail>(
+        "note-collection-selected",
+        {
+          detail: {
+            noteCollectionKey: this.#selectedNoteCollectionKey,
+            noteCollection: this.#selectedNoteCollection,
+          },
+          bubbles: true,
+          composed: true, // Allows the event to cross the Shadow DOM boundary
+        },
+      ),
+    );
+  }
+
+  /**
+   * Selects a random note collection from all available and updates
+   * the component's state and display.
+   * This method programmatically sets the `selectedNoteCollectionKey` property.
+   * Ensures the newly selected note is different from the current one.
+   * @public
+   */
+  setRandomNoteCollection() {
+    const noteCollectionKeys = Object.keys(
+      noteCollections,
+    ) as NoteCollectionKey[];
+
+    let randomNoteCollectionKey: NoteCollectionKey;
+
+    // Keep selecting at random until it's different from the current one.
+    do {
+      const randomIndex = Math.floor(Math.random() * noteCollectionKeys.length);
+      randomNoteCollectionKey = noteCollectionKeys[randomIndex];
+    } while (randomNoteCollectionKey === this.selectedNoteCollectionKey);
+
+    this.selectedNoteCollectionKey = randomNoteCollectionKey;
+  }
+
+  /**
+   * Gets the unique key of the currently selected note collection.
+   * @prop {NoteCollectionKey | null} selectedNoteCollectionKey
+   * @returns {NoteCollectionKey | null} The note collection key (e.g., "ionian") or `null` if no collection is selected.
+   */
+  get selectedNoteCollectionKey(): NoteCollectionKey | null {
+    return this.#selectedNoteCollectionKey;
+  }
+
+  /**
+   * 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.
+   * @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;
+    }
+    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
+   * @returns {NoteCollection | null} The full note collection object or `null` if no collection is selected.
+   * @readonly
+   */
+  get selectedNoteCollection(): NoteCollection | null {
+    return this.#selectedNoteCollection;
+  }
+}
+
+/**
+ * Defines the custom element 'note-collection-selector' in the browser's CustomElementRegistry.
+ * This makes the element available for use in HTML documents.
+ */
+customElements.define("note-collection-selector", NoteCollectionSelector);