@magic-spells/tab-group 0.1.0 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Magic Spells (Cory Schulz)
+Copyright (c) 2026 Magic Spells (Cory Schulz)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,46 +1,35 @@
-# ✨ Tab Group
+# Tab Group
 
 ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
 ![Version](https://img.shields.io/badge/version-0.1.0-brightgreen)
 
-A lightweight, accessible tab interface web component with keyboard navigation and rich customization options.
+A lightweight, accessible tab interface web component with keyboard navigation. Ships only structural CSS — you bring your own styles.
 
-🔍 **[Live Demo](https://magic-spells.github.io/tab-group/demo/)** - See it in action!
+[Live Demo](https://magic-spells.github.io/tab-group/demo/) - See it in action!
 
-## 🚀 Features
+## Features
 
 - **Fully Accessible** - Built following WAI-ARIA Tab pattern guidelines
 - **Custom Events** - Listen for tab changes with detailed event data
 - **Keyboard Navigation** - Complete keyboard support for accessibility
 - **Auto Consistency** - Ensures tab buttons and panels stay in sync
-- **Theme Support** - Extensive CSS variable customization
+- **Zero Opinions** - No cosmetic CSS; style it however you want
 - **Zero Dependencies** - Lightweight and standalone
 - **Easy Integration** - Works with any framework or vanilla JS
 
-## 📦 Installation
+## Installation
 
 ```bash
-# npm
 npm install @magic-spells/tab-group
-
-# yarn
-yarn add @magic-spells/tab-group
-
-# pnpm
-pnpm add @magic-spells/tab-group
 ```
 
-## 🔧 Usage
-
-### Basic Implementation
+## Usage
 
 ```html
-<!-- Import the component -->
 <script type="module">
   import '@magic-spells/tab-group';
 </script>
 
-<!-- Use the component -->
 <tab-group>
   <tab-list>
     <tab-button>First Tab</tab-button>
@@ -71,190 +60,50 @@ pnpm add @magic-spells/tab-group
 document
   .querySelector('tab-group')
   .addEventListener('tabchange', (event) => {
-    console.log('Tab changed!');
-
-    // Access detailed event data
-    const {
-      previousIndex, // Index of previous tab
-      currentIndex, // Index of current tab
-      previousTab, // Previous tab element
-      currentTab, // Current tab element
-      previousPanel, // Previous panel element
-      currentPanel, // Current panel element
-    } = event.detail;
-
-    // Do something with the data
-    console.log(
-      `Changed from tab ${previousIndex} to tab ${currentIndex}`
-    );
+    const { previousIndex, currentIndex } = event.detail;
+    console.log(`Changed from tab ${previousIndex} to tab ${currentIndex}`);
   });
 ```
 
-## 🎨 Styling
+## Styling
 
-### CSS Variables
-
-The Tab Group component can be extensively customized using CSS variables:
+The component ships only structural CSS (display modes, overflow, hidden state). All visual styling is yours. Target the custom elements and ARIA attributes directly:
 
 ```css
-tab-group {
-  /* Base colors */
-  --color-background: #ffffff;
-  --color-text: #333333;
-  --color-border: #dddddd;
-  --color-border-hover: #bbbbbb;
-  --color-primary: #3366ff;
-  --color-hover: #f0f5ff;
-  --color-focus: #b3cbff;
-
-  /* Panel styling */
-  --panel-background: white;
-  --panel-border: 1px solid var(--color-border);
-  --panel-padding: 1rem;
-  --panel-radius: 0 0 0.5rem 0.5rem;
-  --panel-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
-
-  /* Tab list styling */
-  --tab-list-gap: 0.25rem;
-  --tab-list-padding: 0.5rem 0.5rem 0;
-  --tab-list-background: transparent;
-  --tab-list-border-bottom: 1px solid var(--color-border);
-  --tab-list-radius: 0.5rem 0.5rem 0 0;
-
-  /* Tab button styling */
-  --tab-button-radius: 0.25rem 0.25rem 0 0;
-  --tab-active-background: white;
-  --tab-active-color: var(--color-primary);
-  --tab-active-font-weight: 500;
-  --tab-active-shadow: none;
-  --tab-active-transform: translateY(0);
-
-  /* Tab indicator styling */
-  --tab-indicator-height: 2px;
-  --tab-indicator-color: var(--color-primary);
-  --tab-indicator-left: 0;
-  --tab-indicator-right: 0;
+tab-list {
+  gap: 0.25rem;
+  border-bottom: 1px solid #ddd;
 }
-```
 
-### SCSS Integration
-
-This package provides multiple ways to integrate with your SCSS workflow:
-
-```scss
-// Option 1: Use the main entry point (recommended)
-@use "@magic-spells/tab-group/scss" with (
-  $color-primary: #3366ff,
-  $border-radius: 0.5rem
-);
-
-// Option 2: Import individual files
-@use "@magic-spells/tab-group/scss/variables" with (
-  $color-primary: #3366ff,
-  $border-radius: 0.5rem
-);
-@use "@magic-spells/tab-group/scss/tab-group";
+tab-button {
+  padding: 0.5rem 1rem;
+  border-bottom: 2px solid transparent;
+}
 
-// Option 3: Direct paths (if needed)
-@use "node_modules/@magic-spells/tab-group/dist/tab-group.scss";
-@use "node_modules/@magic-spells/tab-group/dist/scss/tab-group";
-```
+tab-button[aria-selected="true"] {
+  color: #3366ff;
+  border-bottom-color: #3366ff;
+}
 
-#### Available SCSS Variables
-
-You can customize the appearance by overriding these SCSS variables:
-
-```scss
-// Colors
-$color-background: #ffffff !default;
-$color-text: #333333 !default;
-$color-border: #dddddd !default;
-$color-border-hover: #bbbbbb !default;
-$color-border-dark: #999999 !default;
-$color-primary: #3366ff !default;
-$color-hover: #f0f5ff !default;
-$color-focus: #b3cbff !default;
-
-// Border radius
-$border-radius: 0.5rem !default;
-
-// Box shadow
-$box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1) !default;
-
-// Tab list
-$tab-list-gap: 0.25rem !default;
-$tab-list-padding: 0.5rem 0.5rem 0 !default;
-$tab-list-background: transparent !default;
-$tab-list-border-bottom: 1px solid $color-border !default;
-$tab-list-radius: $border-radius $border-radius 0 0 !default;
-
-// Tab button
-$tab-button-radius: 0.25rem 0.25rem 0 0 !default;
-$tab-active-background: white !default;
-$tab-active-color: $color-primary !default;
-$tab-active-font-weight: 500 !default;
-$tab-active-shadow: none !default;
-$tab-active-transform: translateY(0) !default;
-
-// Tab indicator
-$tab-indicator-height: 2px !default;
-$tab-indicator-color: $color-primary !default;
-$tab-indicator-left: 0 !default;
-$tab-indicator-right: 0 !default;
-
-// Panel
-$panel-background: white !default;
-$panel-border: 1px solid $color-border !default;
-$panel-padding: 1rem !default;
-$panel-radius: 0 0 $border-radius $border-radius !default;
-$panel-shadow: $box-shadow !default;
+tab-panel {
+  padding: 1rem;
+}
 ```
 
-## 🌈 Theme Examples
+Or use Tailwind utility classes — no overrides needed.
 
-### Dark Theme
+### What the component CSS includes
 
 ```css
-tab-group {
-  --color-background: #2d3748;
-  --color-text: #e2e8f0;
-  --color-border: #4a5568;
-  --color-border-hover: #718096;
-  --color-primary: #4299e1;
-  --color-hover: #1a202c;
-  --color-focus: #2c5282;
-  --panel-background: #1e293b;
-  --panel-border: 1px solid #4a5568;
-  --panel-shadow: 0 4px 6px rgba(0, 0, 0, 0.3);
-  --tab-active-color: #63b3ed;
-  --tab-indicator-color: #63b3ed;
-}
+tab-group  { display: block; }
+tab-list   { display: flex; overflow-x: auto; overflow-y: hidden; }
+tab-button { display: block; cursor: pointer; user-select: none; }
+tab-panel[hidden] { display: none; }
 ```
 
-### Rounded Pills Theme
-
-```css
-tab-group {
-  --border-radius: 0.5rem;
-  --color-primary: #9f7aea;
-  --color-focus: #e9d8fd;
-  --tab-button-radius: 999px;
-  --tab-list-padding: 0.75rem 0.5rem 0;
-  --tab-list-gap: 0.5rem;
-  --panel-radius: 1rem;
-  --panel-shadow: 0 4px 12px rgba(159, 122, 234, 0.15);
-  --panel-border: 1px solid #e9d8fd;
-  --panel-padding: 1.5rem;
-  --tab-active-background: #9f7aea;
-  --tab-active-color: white;
-  --tab-active-font-weight: 500;
-  --tab-active-transform: translateY(-3px);
-  --tab-active-shadow: 0 4px 8px rgba(159, 122, 234, 0.3);
-  --tab-indicator-height: 0;
-}
-```
+That's it. No fonts, colors, spacing, borders, transitions, shadows, or media queries.
 
-## ⌨️ Accessibility
+## Accessibility
 
 The Tab Group component follows the [WAI-ARIA Tabs Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) with:
 
@@ -266,7 +115,7 @@ The Tab Group component follows the [WAI-ARIA Tabs Pattern](https://www.w3.org/W
   - `Home` to move to the first tab
   - `End` to move to the last tab
 
-## 🛠️ API Reference
+## API Reference
 
 ### Components
 
@@ -283,16 +132,16 @@ The Tab Group component follows the [WAI-ARIA Tabs Pattern](https://www.w3.org/W
 | ----------- | --------------------------------------------------------------------------------------- | --------------------------------- |
 | `tabchange` | `{ previousIndex, currentIndex, previousTab, currentTab, previousPanel, currentPanel }` | Fired when the active tab changes |
 
-## 🌟 Examples
+## Examples
 
 Check out more examples in the [demo directory](https://github.com/magic-spells/tab-group/tree/main/demo).
 
-## 📄 License
+## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ---
 
 <p align="center">
-  Made with ✨ by <a href="https://github.com/cory-schulz">Cory Schulz</a>
+  Made with magic by <a href="https://github.com/cory-schulz">Cory Schulz</a>
 </p>

package/dist/tab-group.cjs.js

@@ -7,23 +7,13 @@ Object.defineProperty(exports, '__esModule', { value: true });
  * A fully accessible tab group web component
  */
 
+let instanceCount = 0;
+
 /**
  * @class TabGroup
  * the parent container that coordinates tabs and panels
  */
 class TabGroup extends HTMLElement {
-	// static counter to ensure global unique ids for tabs and panels
-	static tabCount = 0;
-	static panelCount = 0;
-
-	constructor() {
-		super();
-		// ensure that the number of <tab-button> and <tab-panel> elements match
-		// note: in some scenarios the child elements might not be available in the constructor,
-		// so adjust as necessary or consider running this check in connectedCallback()
-		this.ensureConsistentTabsAndPanels();
-	}
-
 	/**
 	 * @function ensureConsistentTabsAndPanels
 	 * makes sure there is an equal number of <tab-button> and <tab-panel> elements.
@@ -31,24 +21,24 @@ class TabGroup extends HTMLElement {
 	 * if there are more tabs than panels, inject extra panels.
 	 */
 	ensureConsistentTabsAndPanels() {
-		// get current tabs and panels within the tab group
-		let tabs = this.querySelectorAll("tab-button");
-		let panels = this.querySelectorAll("tab-panel");
+		// get current tabs and panels scoped to direct children only
+		let tabs = this.querySelectorAll(':scope > tab-list > tab-button');
+		let panels = this.querySelectorAll(':scope > tab-panel');
 
 		// if there are more panels than tabs
 		if (panels.length > tabs.length) {
 			const difference = panels.length - tabs.length;
 			// try to find a <tab-list> to insert new tabs
-			let tabList = this.querySelector("tab-list");
+			let tabList = this.querySelector(':scope > tab-list');
 			if (!tabList) {
 				// if not present, create one and insert it at the beginning
-				tabList = document.createElement("tab-list");
+				tabList = document.createElement('tab-list');
 				this.insertBefore(tabList, this.firstChild);
 			}
 			// inject extra <tab-button> elements into the tab list
 			for (let i = 0; i < difference; i++) {
-				const newTab = document.createElement("tab-button");
-				newTab.textContent = "default tab";
+				const newTab = document.createElement('tab-button');
+				newTab.textContent = 'default tab';
 				tabList.appendChild(newTab);
 			}
 		}
@@ -57,8 +47,8 @@ class TabGroup extends HTMLElement {
 			const difference = tabs.length - panels.length;
 			// inject extra <tab-panel> elements at the end of the tab group
 			for (let i = 0; i < difference; i++) {
-				const newPanel = document.createElement("tab-panel");
-				newPanel.innerHTML = "<p>default panel content</p>";
+				const newPanel = document.createElement('tab-panel');
+				newPanel.innerHTML = '<p>default panel content</p>';
 				this.appendChild(newPanel);
 			}
 		}
@@ -68,58 +58,77 @@ class TabGroup extends HTMLElement {
 	 * called when the element is connected to the dom
 	 */
 	connectedCallback() {
-		const _ = this;
+		// assign a stable instance id on first connect
+		if (!this._instanceId) {
+			this._instanceId = `tg-${instanceCount++}`;
+		}
+
+		// ensure that the number of <tab-button> and <tab-panel> elements match
+		this.ensureConsistentTabsAndPanels();
 
 		// find the <tab-list> element (should be exactly one)
-		_.tabList = _.querySelector("tab-list");
-		if (!_.tabList) return;
+		this.tabList = this.querySelector(':scope > tab-list');
+		if (!this.tabList) return;
 
 		// find all <tab-button> elements inside the <tab-list>
-		_.tabButtons = Array.from(_.tabList.querySelectorAll("tab-button"));
+		this.tabButtons = Array.from(
+			this.tabList.querySelectorAll('tab-button')
+		);
 
 		// find all <tab-panel> elements inside the <tab-group>
-		_.tabPanels = Array.from(_.querySelectorAll("tab-panel"));
+		this.tabPanels = Array.from(this.querySelectorAll(':scope > tab-panel'));
 
-		// initialize each tab-button with roles, ids and aria attributes
-		_.tabButtons.forEach((tab, index) => {
-			const tabIndex = TabGroup.tabCount++;
+		const prefix = this._instanceId;
 
-			// generate a unique id for each tab, e.g. "tab-0", "tab-1", ...
-			const tabId = `tab-${tabIndex}`;
+		// initialize each tab-button with roles, ids and aria attributes
+		this.tabButtons.forEach((tab, index) => {
+			const tabId = `${prefix}-tab-${index}`;
+			const panelId = `${prefix}-panel-${index}`;
 			tab.id = tabId;
-
-			// generate a corresponding panel id, e.g. "panel-0"
-			const panelId = `panel-${tabIndex}`;
-			tab.setAttribute("role", "tab");
-			tab.setAttribute("aria-controls", panelId);
+			tab.setAttribute('role', 'tab');
+			tab.setAttribute('aria-controls', panelId);
 
 			// first tab is active by default
 			if (index === 0) {
-				tab.setAttribute("aria-selected", "true");
-				tab.setAttribute("tabindex", "0");
+				tab.setAttribute('aria-selected', 'true');
+				tab.setAttribute('tabindex', '0');
 			} else {
-				tab.setAttribute("aria-selected", "false");
-				tab.setAttribute("tabindex", "-1");
+				tab.setAttribute('aria-selected', 'false');
+				tab.setAttribute('tabindex', '-1');
 			}
 		});
 
 		// initialize each tab-panel with roles, ids and aria attributes
-		_.tabPanels.forEach((panel, index) => {
-			const panelIndex = TabGroup.panelCount++;
-			const panelId = `panel-${panelIndex}`;
+		this.tabPanels.forEach((panel, index) => {
+			const panelId = `${prefix}-panel-${index}`;
 			panel.id = panelId;
-
-			panel.setAttribute("role", "tabpanel");
-			panel.setAttribute("aria-labelledby", `tab-${panelIndex}`);
+			panel.setAttribute('role', 'tabpanel');
+			panel.setAttribute('aria-labelledby', `${prefix}-tab-${index}`);
 
 			// hide panels except for the first one
 			panel.hidden = index !== 0;
 		});
 
 		// set up keyboard navigation and click delegation on the <tab-list>
-		_.tabList.setAttribute("role", "tablist");
-		_.tabList.addEventListener("keydown", (e) => _.onKeyDown(e));
-		_.tabList.addEventListener("click", (e) => _.onClick(e));
+		this.tabList.setAttribute('role', 'tablist');
+
+		// store bound handlers so we can remove them in disconnectedCallback
+		if (!this._onKeyDown) {
+			this._onKeyDown = (e) => this.onKeyDown(e);
+			this._onClick = (e) => this.onClick(e);
+		}
+		this.tabList.addEventListener('keydown', this._onKeyDown);
+		this.tabList.addEventListener('click', this._onClick);
+	}
+
+	/**
+	 * called when the element is disconnected from the dom
+	 */
+	disconnectedCallback() {
+		if (this.tabList && this._onKeyDown) {
+			this.tabList.removeEventListener('keydown', this._onKeyDown);
+			this.tabList.removeEventListener('click', this._onClick);
+		}
 	}
 
 	/**
@@ -128,21 +137,23 @@ class TabGroup extends HTMLElement {
 	 * @param {number} index - index of the tab to activate
 	 */
 	setActiveTab(index) {
-		const _ = this;
-		const previousIndex = _.tabButtons.findIndex(tab => tab.getAttribute("aria-selected") === "true");
+		if (index < 0 || index >= this.tabButtons.length) return;
+		const previousIndex = this.tabButtons.findIndex(
+			(tab) => tab.getAttribute('aria-selected') === 'true'
+		);
 
 		// update each tab-button
-		_.tabButtons.forEach((tab, i) => {
+		this.tabButtons.forEach((tab, i) => {
 			const isActive = i === index;
-			tab.setAttribute("aria-selected", isActive ? "true" : "false");
-			tab.setAttribute("tabindex", isActive ? "0" : "-1");
+			tab.setAttribute('aria-selected', isActive ? 'true' : 'false');
+			tab.setAttribute('tabindex', isActive ? '0' : '-1');
 			if (isActive) {
 				tab.focus();
 			}
 		});
 
 		// update each tab-panel
-		_.tabPanels.forEach((panel, i) => {
+		this.tabPanels.forEach((panel, i) => {
 			panel.hidden = i !== index;
 		});
 
@@ -151,12 +162,14 @@ class TabGroup extends HTMLElement {
 			const detail = {
 				previousIndex,
 				currentIndex: index,
-				previousTab: _.tabButtons[previousIndex],
-				currentTab: _.tabButtons[index],
-				previousPanel: _.tabPanels[previousIndex],
-				currentPanel: _.tabPanels[index]
+				previousTab: this.tabButtons[previousIndex],
+				currentTab: this.tabButtons[index],
+				previousPanel: this.tabPanels[previousIndex],
+				currentPanel: this.tabPanels[index],
 			};
-			_.dispatchEvent(new CustomEvent('tabchange', { detail, bubbles: true }));
+			this.dispatchEvent(
+				new CustomEvent('tabchange', { detail, bubbles: true })
+			);
 		}
 	}
 
@@ -166,17 +179,16 @@ class TabGroup extends HTMLElement {
 	 * @param {MouseEvent} e - the click event
 	 */
 	onClick(e) {
-		const _ = this;
 		// check if the click occurred on or within a <tab-button>
-		const tabButton = e.target.closest("tab-button");
+		const tabButton = e.target.closest('tab-button');
 		if (!tabButton) return;
 
 		// determine the index of the clicked tab-button
-		const index = _.tabButtons.indexOf(tabButton);
+		const index = this.tabButtons.indexOf(tabButton);
 		if (index === -1) return;
 
 		// activate the tab with the corresponding index
-		_.setActiveTab(index);
+		this.setActiveTab(index);
 	}
 
 	/**
@@ -185,39 +197,39 @@ class TabGroup extends HTMLElement {
 	 * @param {KeyboardEvent} e - the keydown event
 	 */
 	onKeyDown(e) {
-		const _ = this;
 		// only process keys if focus is on a <tab-button>
-		const targetIndex = _.tabButtons.indexOf(e.target);
+		const targetIndex = this.tabButtons.indexOf(e.target);
 		if (targetIndex === -1) return;
 
 		let newIndex = targetIndex;
 		switch (e.key) {
-			case "ArrowLeft":
-			case "ArrowUp":
+			case 'ArrowLeft':
+			case 'ArrowUp':
 				// move to the previous tab (wrap around if necessary)
-				newIndex = targetIndex > 0 ? targetIndex - 1 : _.tabButtons.length - 1;
+				newIndex =
+					targetIndex > 0 ? targetIndex - 1 : this.tabButtons.length - 1;
 				e.preventDefault();
 				break;
-			case "ArrowRight":
-			case "ArrowDown":
+			case 'ArrowRight':
+			case 'ArrowDown':
 				// move to the next tab (wrap around if necessary)
-				newIndex = (targetIndex + 1) % _.tabButtons.length;
+				newIndex = (targetIndex + 1) % this.tabButtons.length;
 				e.preventDefault();
 				break;
-			case "Home":
+			case 'Home':
 				// jump to the first tab
 				newIndex = 0;
 				e.preventDefault();
 				break;
-			case "End":
+			case 'End':
 				// jump to the last tab
-				newIndex = _.tabButtons.length - 1;
+				newIndex = this.tabButtons.length - 1;
 				e.preventDefault();
 				break;
 			default:
 				return; // ignore other keys
 		}
-		_.setActiveTab(newIndex);
+		this.setActiveTab(newIndex);
 	}
 }
 
@@ -225,50 +237,31 @@ class TabGroup extends HTMLElement {
  * @class TabList
  * a container for the <tab-button> elements
  */
-class TabList extends HTMLElement {
-	constructor() {
-		super();
-	}
-
-	connectedCallback() {
-		// additional logic or styling can be added here if desired
-	}
-}
+class TabList extends HTMLElement {}
 
 /**
  * @class TabButton
  * a single tab button element
  */
-class TabButton extends HTMLElement {
-	constructor() {
-		super();
-	}
-
-	connectedCallback() {
-		// note: role and other attributes are handled by the parent
-	}
-}
+class TabButton extends HTMLElement {}
 
 /**
  * @class TabPanel
  * a single tab panel element
  */
-class TabPanel extends HTMLElement {
-	constructor() {
-		super();
-	}
-
-	connectedCallback() {
-		// note: role and other attributes are handled by the parent
-	}
+class TabPanel extends HTMLElement {}
+
+// define the custom elements (guarded against double-registration and SSR)
+if (typeof window !== 'undefined' && window.customElements) {
+	if (!customElements.get('tab-group'))
+		customElements.define('tab-group', TabGroup);
+	if (!customElements.get('tab-list'))
+		customElements.define('tab-list', TabList);
+	if (!customElements.get('tab-button'))
+		customElements.define('tab-button', TabButton);
+	if (!customElements.get('tab-panel'))
+		customElements.define('tab-panel', TabPanel);
 }
 
-// define the custom elements
-customElements.define("tab-group", TabGroup);
-customElements.define("tab-list", TabList);
-customElements.define("tab-button", TabButton);
-customElements.define("tab-panel", TabPanel);
-
-exports.TabGroup = TabGroup;
 exports.default = TabGroup;
 //# sourceMappingURL=tab-group.cjs.js.map