@schukai/monster 4.139.1 → 4.140.0

package/source/components/layout/tabs.mjs

@@ -122,6 +122,12 @@ const closeEventHandler = Symbol("closeEventHandler");
  */
 const mutationObserverSymbol = Symbol("mutationObserver");
 
+/**
+ * @private
+ * @type {symbol}
+ */
+const tabListMutationObserverSymbol = Symbol("tabListMutationObserver");
+
 /**
  * @private
  * @type {symbol}
@@ -141,6 +147,13 @@ const timerCallbackSymbol = Symbol("timerCallback");
  */
 const resizeObserverSymbol = Symbol("resizeObserver");
 
+/**
+ * local symbol
+ * @private
+ * @type {symbol}
+ */
+const activeReferenceSymbol = Symbol("activeReference");
+
 /**
  * A Tabs Control
  *
@@ -183,6 +196,22 @@ class Tabs extends CustomElement {
 	 * @property {number} features.openDelay=500 Open delay in milliseconds
 	 * @property {string} features.removeBehavior Remove behavior, auto, next, previous and none
 	 * @property {boolean} features.openFirst Open the first tab when no active tab is set
+	 * @property {boolean} features.deriveLabelFromContent=true Generate labels from panel text when no `data-monster-button-label` is set
+	 *
+	 * Tab panels can use `data-monster-name` as stable public identity, while
+	 * DOM ids remain the internal button reference. `data-monster-tab-available`
+	 * controls whether a panel participates in the tab control. Missing or
+	 * `"true"` means available; `"false"` or an empty attribute means unavailable.
+	 * `data-monster-tab-disabled="true"` keeps a button visible but prevents
+	 * activation. `data-monster-tab-disabled-reason` is exposed on the disabled
+	 * button as contextual help. `data-monster-tab-kind`,
+	 * `data-monster-tab-priority`, and `data-monster-tab-group` are copied into
+	 * button metadata and tab event details.
+	 *
+	 * @fires monster-tab-change
+	 * @fires monster-tab-changed
+	 * @fires monster-tab-remove
+	 * @fires monster-tab-availability-changed
 	 * @property {Object} fetch Fetch [see Using Fetch mozilla.org](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)
 	 * @property {String} fetch.redirect=error
 	 * @property {String} fetch.method=GET
@@ -220,6 +249,7 @@ class Tabs extends CustomElement {
 				openDelay: null,
 				removeBehavior: "auto",
 				openFirst: true,
+				deriveLabelFromContent: true,
 			},
 
 			classes: {
@@ -272,13 +302,13 @@ class Tabs extends CustomElement {
 		this[dimensionsSymbol] = new Pathfinder({ data: {} });
 
 		initEventHandler.call(this);
+		attachTabChangeObserver.call(this);
 
 		// setup structure
 		initTabButtons.call(this).then(() => {
 			initPopperSwitch.call(this);
 			initPopper.call(this);
 			attachResizeObserver.call(this);
-			attachTabChangeObserver.call(this);
 		});
 	}
 
@@ -306,7 +336,7 @@ class Tabs extends CustomElement {
 	 * @returns {Tabs}
 	 */
 	removeTab(tabId) {
-		const tabs = this.getTabs();
+		const tabs = getAllTabPanels.call(this);
 		for (const tab of tabs) {
 			if (
 				(tab.getAttribute("id") === tabId ||
@@ -326,14 +356,7 @@ class Tabs extends CustomElement {
 	 * @returns {[]}
 	 */
 	getTabs() {
-		const nodes = getSlottedElements.call(this);
-		const tabs = [];
-		for (const node of nodes) {
-			if (node instanceof HTMLElement) {
-				tabs.push(node);
-			}
-		}
-		return tabs;
+		return getAllTabPanels.call(this).filter((node) => isTabAvailable(node));
 	}
 
 	/**
@@ -365,7 +388,7 @@ class Tabs extends CustomElement {
 		}
 
 		// check if id is already used
-		const existingTabs = this.getTabs();
+		const existingTabs = getAllTabPanels.call(this);
 		for (const existingTab of existingTabs) {
 			if (
 				existingTab.getAttribute("id") === tabId ||
@@ -398,43 +421,80 @@ class Tabs extends CustomElement {
 	}
 
 	/**
-	 * A function that activates a tab based on the provided name.
+	 * Rebuild tab buttons and synchronize the active tab.
 	 *
-	 * The tabs have to be named with the `data-monster-name` attribute.
+	 * @return {Promise<Tabs>}
+	 */
+	refreshTabs() {
+		this[dimensionsSymbol].setVia("data.calculated", false);
+		return initTabButtons.call(this).then(() => this);
+	}
+
+	/**
+	 * Alias for refreshTabs().
 	 *
-	 * @param {type} idOrName - the name or id of the tab to activate
-	 * @return {Tabs} - The current instance
+	 * @return {Promise<Tabs>}
 	 */
-	activeTab(idOrName) {
-		let found = false;
+	syncTabs() {
+		return this.refreshTabs();
+	}
 
-		getSlottedElements.call(this).forEach((node) => {
-			if (found === true) {
-				return;
+	/**
+	 * Hide a tab from the control without removing its panel.
+	 *
+	 * @param {string} idOrName
+	 * @return {Tabs}
+	 */
+	hideTab(idOrName) {
+		const tab = findTabPanel.call(this, idOrName, { availableOnly: false });
+		if (tab instanceof HTMLElement) {
+			const previousAvailable = isTabAvailable(tab);
+			tab.setAttribute("data-monster-tab-available", "false");
+			if (!hasObjectLink(tab, mutationObserverSymbol)) {
+				emitAvailabilityChanged.call(this, tab, previousAvailable, false);
 			}
+		}
+		return this;
+	}
 
-			if (node.getAttribute("data-monster-name") === idOrName) {
-				const tabControl = this.shadowRoot.querySelector(
-					`[data-monster-tab-reference="${node.getAttribute("id")}"]`,
-				);
-
-				if (tabControl) {
-					tabControl.click();
-					found = true;
-				}
+	/**
+	 * Show a tab in the control.
+	 *
+	 * @param {string} idOrName
+	 * @return {Tabs}
+	 */
+	showTab(idOrName) {
+		const tab = findTabPanel.call(this, idOrName, { availableOnly: false });
+		if (tab instanceof HTMLElement) {
+			const previousAvailable = isTabAvailable(tab);
+			tab.setAttribute("data-monster-tab-available", "true");
+			if (!hasObjectLink(tab, mutationObserverSymbol)) {
+				emitAvailabilityChanged.call(this, tab, previousAvailable, true);
 			}
+		}
+		return this;
+	}
 
-			if (node.getAttribute("id") === idOrName) {
-				const tabControl = this.shadowRoot.querySelector(
-					`[data-monster-tab-reference="${node.getAttribute("id")}"]`,
-				);
+	/**
+	 * A function that activates a tab based on the provided name.
+	 *
+	 * The tabs have to be named with the `data-monster-name` attribute.
+	 *
+	 * @param {type} idOrName - the name or id of the tab to activate
+	 * @return {Tabs} - The current instance
+	 */
+	activeTab(idOrName) {
+		const node = findTabPanel.call(this, idOrName, {
+			availableOnly: true,
+			enabledOnly: true,
+		});
 
-				if (tabControl) {
-					tabControl.click();
-					found = true;
-				}
+		if (node instanceof HTMLElement) {
+			const tabControl = findButtonElement.call(this, node.getAttribute("id"));
+			if (tabControl instanceof HTMLButtonElement) {
+				tabControl.click();
 			}
-		});
+		}
 
 		return this;
 	}
@@ -492,6 +552,7 @@ class Tabs extends CustomElement {
 		}
 
 		this[popperInstanceSymbol]?.destroy();
+		this[tabListMutationObserverSymbol]?.disconnect();
 	}
 }
 
@@ -542,6 +603,173 @@ function getTranslations() {
 	}
 }
 
+/**
+ * @private
+ * @return {HTMLElement[]}
+ */
+function getAllTabPanels() {
+	const nodes = getSlottedElements.call(this);
+	const tabs = [];
+	for (const node of nodes) {
+		if (node instanceof HTMLElement) {
+			tabs.push(node);
+		}
+	}
+	return tabs;
+}
+
+/**
+ * @private
+ * @param {HTMLElement} node
+ * @return {boolean}
+ */
+function isTabAvailable(node) {
+	if (!node.hasAttribute("data-monster-tab-available")) {
+		return true;
+	}
+	return node.getAttribute("data-monster-tab-available") === "true";
+}
+
+/**
+ * @private
+ * @param {string|null} value
+ * @return {boolean}
+ */
+function parseTabAvailableValue(value) {
+	if (value === null) {
+		return true;
+	}
+	return value === "true";
+}
+
+/**
+ * @private
+ * @param {HTMLElement} node
+ * @return {boolean}
+ */
+function isTabDisabled(node) {
+	return (
+		node.hasAttribute("disabled") ||
+		node.disabled === true ||
+		node.getAttribute("data-monster-tab-disabled") === "true"
+	);
+}
+
+/**
+ * @private
+ * @param {HTMLElement} node
+ * @return {string|null}
+ */
+function getTabName(node) {
+	if (node.hasAttribute("data-monster-name")) {
+		return node.getAttribute("data-monster-name");
+	}
+	return null;
+}
+
+/**
+ * @private
+ * @param {HTMLElement} node
+ * @return {string|null}
+ */
+function getTabReference(node) {
+	return node.getAttribute("id");
+}
+
+/**
+ * @private
+ * @param {HTMLElement} node
+ * @return {string|null}
+ */
+function getTabPublicReference(node) {
+	return getTabName(node) || getTabReference(node);
+}
+
+/**
+ * @private
+ * @param {HTMLElement} node
+ * @return {Object}
+ */
+function getTabMetadata(node) {
+	const metadata = {};
+	for (const key of ["kind", "priority", "group"]) {
+		const attr = `data-monster-tab-${key}`;
+		if (node.hasAttribute(attr)) {
+			metadata[key] = node.getAttribute(attr);
+		}
+	}
+	return metadata;
+}
+
+/**
+ * @private
+ * @param {HTMLElement} node
+ * @return {Object}
+ */
+function getTabEventDetail(node) {
+	return {
+		reference: getTabReference(node),
+		name: getTabName(node),
+		tab: getTabPublicReference(node),
+		metadata: getTabMetadata(node),
+	};
+}
+
+/**
+ * @private
+ * @param {string} idOrName
+ * @param {Object} options
+ * @return {HTMLElement|null}
+ */
+function findTabPanel(
+	idOrName,
+	{ availableOnly = false, enabledOnly = false } = {},
+) {
+	const tabs = getAllTabPanels.call(this);
+	for (const node of tabs) {
+		if (availableOnly === true && isTabAvailable(node) !== true) {
+			continue;
+		}
+		if (enabledOnly === true && isTabDisabled(node) === true) {
+			continue;
+		}
+		if (getTabName(node) === idOrName) {
+			return node;
+		}
+	}
+
+	for (const node of tabs) {
+		if (availableOnly === true && isTabAvailable(node) !== true) {
+			continue;
+		}
+		if (enabledOnly === true && isTabDisabled(node) === true) {
+			continue;
+		}
+		if (getTabReference(node) === idOrName) {
+			return node;
+		}
+	}
+
+	return null;
+}
+
+/**
+ * @private
+ * @param {HTMLElement} tab
+ * @param {boolean} previousAvailable
+ * @param {boolean} available
+ */
+function emitAvailabilityChanged(tab, previousAvailable, available) {
+	if (previousAvailable === available) {
+		return;
+	}
+
+	fireCustomEvent(this, "monster-tab-availability-changed", {
+		...getTabEventDetail(tab),
+		available,
+	});
+}
+
 /**
  * @private
  */
@@ -661,7 +889,7 @@ function attachResizeObserver() {
  */
 function attachTabChangeObserver() {
 	// against flickering
-	new MutationObserver((mutations) => {
+	this[tabListMutationObserverSymbol] = new MutationObserver((mutations) => {
 		let runUpdate = false;
 
 		for (const mutation of mutations) {
@@ -680,7 +908,9 @@ function attachTabChangeObserver() {
 			this[dimensionsSymbol].setVia("data.calculated", false);
 			initTabButtons.call(this);
 		}
-	}).observe(this, {
+	});
+
+	this[tabListMutationObserverSymbol].observe(this, {
 		childList: true,
 	});
 }
@@ -744,11 +974,16 @@ function show(element, options = {}) {
 		const id = node.getAttribute("id");
 
 		if (id === reference) {
+			if (isTabAvailable(node) !== true || isTabDisabled(node) === true) {
+				continue;
+			}
+
 			node.classList.add("active");
+			this[activeReferenceSymbol] = reference;
 
 			if (emitEvents) {
 				fireCustomEvent(this, "monster-tab-change", {
-					reference,
+					...getTabEventDetail(node),
 				});
 			}
 
@@ -774,6 +1009,9 @@ function show(element, options = {}) {
 				"data-monster-button-label",
 				"data-monster-objectlink",
 				"data-monster-role",
+				"data-monster-tab-available",
+				"data-monster-tab-disabled",
+				"data-monster-tab-disabled-reason",
 			];
 
 			for (const [, attr] of Object.entries(node.attributes)) {
@@ -798,7 +1036,7 @@ function show(element, options = {}) {
 					.then(() => {
 						if (emitEvents) {
 							fireCustomEvent(this, "monster-tab-changed", {
-								reference,
+								...getTabEventDetail(node),
 							});
 						}
 					})
@@ -808,7 +1046,7 @@ function show(element, options = {}) {
 			} else {
 				if (emitEvents) {
 					fireCustomEvent(this, "monster-tab-changed", {
-						reference,
+						...getTabEventDetail(node),
 						data,
 					});
 				}
@@ -883,10 +1121,13 @@ function initEventHandler() {
 					activeReference = activeButton?.reference || null;
 				}
 
-				const nodes = getSlottedElements.call(this);
 				const orderedTabs = [];
-				for (const node of nodes) {
-					if (node instanceof HTMLElement) {
+				for (const node of getAllTabPanels.call(this)) {
+					if (
+						node instanceof HTMLElement &&
+						isTabAvailable(node) === true &&
+						isTabDisabled(node) !== true
+					) {
 						orderedTabs.push(node);
 					}
 				}
@@ -951,7 +1192,7 @@ function initEventHandler() {
 							self.activeTab(targetReference);
 						}
 						fireCustomEvent(this, "monster-tab-remove", {
-							reference,
+							...getTabEventDetail(container),
 						});
 					}
 				}
@@ -1013,7 +1254,15 @@ function attachTabMutationObserver(observedNode) {
 	const observer = new MutationObserver(function (mutations) {
 		if (isArray(mutations)) {
 			const mutation = mutations.pop();
-			if (mutation instanceof MutationRecord) {
+			if (mutation?.type === "attributes") {
+				if (mutation.attributeName === "data-monster-tab-available") {
+					emitAvailabilityChanged.call(
+						self,
+						observedNode,
+						parseTabAvailableValue(mutation.oldValue),
+						isTabAvailable(observedNode),
+					);
+				}
 				initTabButtons.call(self);
 			}
 		}
@@ -1022,6 +1271,7 @@ function attachTabMutationObserver(observedNode) {
 	observer.observe(observedNode, {
 		childList: false,
 		attributes: true,
+		attributeOldValue: true,
 		subtree: false,
 		attributeFilter: [
 			"disabled",
@@ -1029,6 +1279,12 @@ function attachTabMutationObserver(observedNode) {
 			`${ATTRIBUTE_PREFIX}button-icon`,
 			"data-monster-tab-error",
 			"data-monster-tab-error-message",
+			"data-monster-tab-available",
+			"data-monster-tab-disabled",
+			"data-monster-tab-disabled-reason",
+			"data-monster-tab-kind",
+			"data-monster-tab-priority",
+			"data-monster-tab-group",
 		],
 	});
 
@@ -1071,6 +1327,8 @@ function initTabButtons() {
 	}
 
 	let activeReference;
+	let invalidActive = false;
+	const previousActiveReference = this[activeReferenceSymbol] || null;
 
 	const dimensionsCalculated = this[dimensionsSymbol].getVia(
 		"data.calculated",
@@ -1078,25 +1336,34 @@ function initTabButtons() {
 	);
 
 	const buttons = [];
-	const nodes = getSlottedElements.call(this, undefined, null); // null ↦ only unnamed slots
+	const nodes = getAllTabPanels.call(this);
 
 	for (const node of nodes) {
 		if (!(node instanceof HTMLElement)) continue;
-		let label = getButtonLabel.call(this, node);
+		const wasActive = node.matches(".active") === true;
 
-		let reference;
-		if (node.hasAttribute("id")) {
-			reference = node.getAttribute("id");
+		if (!node.hasAttribute("id")) {
+			node.setAttribute("id", new ID("tab").toString());
 		}
 
-		let disabled;
-		if (node.hasAttribute("disabled") || node.disabled === true) {
-			disabled = true;
+		attachTabMutationObserver.call(this, node);
+
+		if (isTabAvailable(node) !== true) {
+			if (wasActive === true) {
+				invalidActive = true;
+				node.classList.remove("active");
+			}
+			continue;
 		}
 
-		if (!reference) {
-			reference = new ID("tab").toString();
-			node.setAttribute("id", reference);
+		let label = getButtonLabel.call(this, node);
+
+		let reference = node.getAttribute("id");
+
+		let disabled = isTabDisabled(node);
+		if (wasActive === true && disabled === true) {
+			invalidActive = true;
+			node.classList.remove("active");
 		}
 
 		if (node.hasAttribute(`${ATTRIBUTE_PREFIX}button-icon`)) {
@@ -1114,32 +1381,47 @@ function initTabButtons() {
 
 		if (node.matches(".active") === true && disabled !== true) {
 			activeReference = reference;
+			this[activeReferenceSymbol] = reference;
 		}
 
 		const state = "";
 		const classes = dimensionsCalculated ? "" : "invisible";
+		const disabledReason = node.getAttribute(
+			"data-monster-tab-disabled-reason",
+		);
+		const metadata = getTabMetadata(node);
 
 		buttons.push({
 			reference,
+			name: getTabName(node),
+			tab: getTabPublicReference(node),
 			label,
 			error: errorMarkup,
 			state,
 			class: classes,
 			disabled,
+			title: disabled === true ? disabledReason : null,
+			"aria-label": disabled === true ? disabledReason : null,
 			remove,
+			kind: metadata.kind,
+			priority: metadata.priority,
+			group: metadata.group,
 		});
-
-		attachTabMutationObserver.call(this, node);
 	}
 
 	setButtonCollections.call(this, buttons, []);
 	this.setOption("marker", random());
 
 	return adjustButtonVisibility.call(this).then(() => {
-		if (!activeReference && this.getOption("features.openFirst") === true) {
-			const firstButton = this.getOption("buttons.standard").find(
-				(button) => button.disabled !== true,
-			);
+		if (
+			!activeReference &&
+			(invalidActive === true ||
+				previousActiveReference !== null ||
+				this.getOption("features.openFirst") === true)
+		) {
+			const firstButton = this.getOption("buttons.standard")
+				.concat(this.getOption("buttons.popper"))
+				.find((button) => button.disabled !== true);
 			if (firstButton) {
 				activeReference = firstButton.reference;
 			}
@@ -1152,6 +1434,8 @@ function initTabButtons() {
 				);
 				if (button instanceof HTMLButtonElement && button.disabled !== true) {
 					show.call(this, button, { emitEvents: false });
+				} else {
+					this[activeReferenceSymbol] = null;
 				}
 			})
 				.run(undefined)
@@ -1161,10 +1445,32 @@ function initTabButtons() {
 				});
 		}
 
+		clearActiveTabs.call(this);
 		return Promise.resolve();
 	});
 }
 
+/**
+ * @private
+ */
+function clearActiveTabs() {
+	this[activeReferenceSymbol] = null;
+
+	for (const node of getAllTabPanels.call(this)) {
+		node.classList.remove("active");
+	}
+
+	const standardButtons = this.getOption("buttons.standard");
+	for (const index in standardButtons) {
+		this.setOption(`buttons.standard.${index}.state`, "inactive");
+	}
+
+	const popperButtons = this.getOption("buttons.popper");
+	for (const index in popperButtons) {
+		this.setOption(`buttons.popper.${index}.state`, "inactive");
+	}
+}
+
 function checkAndRearrangeButtons() {
 	if (this[dimensionsSymbol].getVia("data.calculated", false) !== true) {
 		calculateNavigationButtonsDimensions.call(this);
@@ -1416,8 +1722,12 @@ function getButtonLabel(node) {
 	if (node.hasAttribute(ATTRIBUTE_BUTTON_LABEL)) {
 		label = node.getAttribute(ATTRIBUTE_BUTTON_LABEL);
 	} else {
-		label = node.innerText;
-		setLabel = true;
+		if (this.getOption("features.deriveLabelFromContent") === false) {
+			label = this.getOption("labels.new-tab-label", "New Tab");
+		} else {
+			label = node.innerText;
+			setLabel = true;
+		}
 	}
 
 	if (!isString(label)) {
@@ -1514,7 +1824,13 @@ function getTemplate() {
                     data-monster-attributes="
                     class path:classes.button,
                     data-monster-state path:buttons.state,
-                    disabled path:buttons.disabled | if:true,                    
+                    disabled path:buttons.disabled | if:true,
+                    title path:buttons.title,
+                    aria-label path:buttons.aria-label,
+                    data-monster-tab-name path:buttons.name,
+                    data-monster-tab-kind path:buttons.kind,
+                    data-monster-tab-priority path:buttons.priority,
+                    data-monster-tab-group path:buttons.group,
                     data-monster-tab-reference path:buttons.reference"><span part="label"
                     data-monster-replace="path:buttons.label"></span><div part="error"
                     data-monster-replace="path:buttons.error"></div><span part="remove-tab"