cx 26.8.0 → 26.9.0

package/dist/svg.js

@@ -234,6 +234,15 @@ class Svg extends BoundedObject {
 	constructor(config) {
 		super(config);
 	}
+	declareData(...args) {
+		return super.declareData(
+			{
+				role: undefined,
+				ariaLabel: undefined,
+			},
+			...args,
+		);
+	}
 	initState(context, instance) {
 		const size = {
 			width: 0,
@@ -308,6 +317,8 @@ class SvgComponent extends VDOM.Component {
 	render() {
 		const { instance, data, size, children, eventHandlers } = this.props;
 		const { widget } = instance;
+		// An unnamed drawing is left alone: `role="img"` would hide its text and put nothing in its place.
+		const role = data.role ?? (data.ariaLabel ? "img" : undefined);
 		const defs = [];
 		for (const k in instance.clipRects) {
 			let cr = instance.clipRects[k];
@@ -350,6 +361,8 @@ class SvgComponent extends VDOM.Component {
 				size.width > 0 &&
 				size.height > 0 &&
 				jsxs("svg", {
+					role: role,
+					"aria-label": data.ariaLabel,
 					children: [
 						jsx("defs", {
 							children: defs,

package/dist/util.js

@@ -57,6 +57,23 @@ function isNumber(x) {
 	return typeof x === "number";
 }
 
+//IE sometimes returns null while other browsers always return document.body.
+function getActiveElement(doc = document) {
+	let active = doc.activeElement ?? doc.body;
+	//when focus is inside a same-origin iframe, `doc.activeElement` only reports the
+	//<iframe> element itself - drill into its own document to find the element that's
+	//actually focused there (recursively, in case of nested iframes)
+	if (active && active.tagName === "IFRAME") {
+		const iframe = active;
+		let frameDoc = iframe.contentDocument;
+		if (frameDoc) {
+			const inner = getActiveElement(frameDoc);
+			return inner ?? active;
+		}
+	}
+	return active;
+}
+
 function findFirst(el, condition) {
 	if (condition(el)) return el;
 	var children = el.children;
@@ -87,10 +104,10 @@ function closestParent(el, condition) {
 	return el && closest(el.parentElement, condition);
 }
 function isFocused(el) {
-	return document.activeElement == el;
+	return getActiveElement() == el;
 }
 function isFocusedDeep(el) {
-	return document.activeElement == el || (!!document.activeElement && el.contains(document.activeElement));
+	return isSelfOrDescendant(el, getActiveElement());
 }
 const focusableWithoutTabIndex = ["INPUT", "SELECT", "TEXTAREA", "A", "BUTTON"];
 function isFocusable(el) {
@@ -105,13 +122,23 @@ function isFocusable(el) {
  * @returns {Element}
  */
 function getFocusedElement() {
-	return document.activeElement;
+	return getActiveElement();
 }
 function isDescendant(el, descEl) {
 	return el.contains(descEl);
 }
+//`descEl` may live in a different document than `el` (e.g. focus is inside a same-origin
+//iframe) - Node.contains never crosses document boundaries, so walk out through each
+//frame's <iframe> element in its parent document until we either cross into el's document
+//or run out of ancestor frames.
 function isSelfOrDescendant(el, descEl) {
-	return el == descEl || el.contains(descEl);
+	let node = descEl;
+	while (node) {
+		if (el == node || el.contains(node)) return true;
+		let win = node.ownerDocument?.defaultView;
+		node = win?.frameElement;
+	}
+	return false;
 }
 
 var globalCacheIdentifier = 1;
@@ -1344,11 +1371,6 @@ function reverseSlice(array, start) {
 	}
 }
 
-//IE sometimes returns null while other browsers always return document.body.
-function getActiveElement() {
-	return document.activeElement ?? document.body;
-}
-
 /**
  * Type-checks a CreateConfig object based on its `type` or `$type` property.
  * This is a compile-time helper that returns the input unchanged at runtime.

package/dist/widgets.js

@@ -5933,9 +5933,14 @@ class OverlayComponent extends VDOM$2.Component {
 			widget.handleResize(e, instance, this);
 		} else {
 			let prefix = this.getResizePrefix(e);
-			this.setCustomStyle({
-				cursor: prefix ? prefix + "-resize" : undefined,
-			});
+			if (prefix)
+				this.setCustomStyle({
+					cursor: `${prefix}-resize`,
+				});
+			else if (this.customStyle.cursor) {
+				delete this.customStyle.cursor;
+				if (this.el) this.el.style.cursor = data.style?.cursor ?? "";
+			}
 		}
 	}
 	startMoveOperation(e) {
@@ -6209,6 +6214,21 @@ class DropdownBase extends OverlayBase {
 			el.addEventListener("scroll", component.updateDropdownPosition);
 		});
 		component.offResize = ResizeManager.subscribe(component.updateDropdownPosition);
+		//if the related element lives in a different document (e.g. inside a same-origin
+		//iframe), that document/window has its own scroll position and its own resize event
+		//(which also fires when the <iframe> element itself is resized) - neither is observed
+		//by the top-level `window` above or by the relatedElement's parentElement chain, so
+		//track every frame window between the related element's document and the top document.
+		var frameWindows = (component.frameWindows = []);
+		var frameWin = instance.relatedElement?.ownerDocument?.defaultView;
+		while (frameWin && frameWin !== window) {
+			frameWindows.push(frameWin);
+			frameWin = frameWin.frameElement?.ownerDocument?.defaultView;
+		}
+		frameWindows.forEach((w) => {
+			w.addEventListener("scroll", component.updateDropdownPosition);
+			w.addEventListener("resize", component.updateDropdownPosition);
+		});
 		if (this.onDropdownDidMount) instance.invoke("onDropdownDidMount", instance, component);
 		if (this.pipeValidateDropdownPosition)
 			instance.invoke("pipeValidateDropdownPosition", component.updateDropdownPosition, instance);
@@ -6221,14 +6241,21 @@ class DropdownBase extends OverlayBase {
 		this.updateDropdownPosition(instance, component);
 	}
 	overlayWillUnmount(instance, component) {
-		var { scrollableParents } = component;
+		var { scrollableParents, frameWindows } = component;
 		if (scrollableParents) {
 			scrollableParents.forEach((el) => {
 				el.removeEventListener("scroll", component.updateDropdownPosition);
 			});
 			delete component.scrollableParents;
-			delete component.updateDropdownPosition;
 		}
+		if (frameWindows) {
+			frameWindows.forEach((w) => {
+				w.removeEventListener("scroll", component.updateDropdownPosition);
+				w.removeEventListener("resize", component.updateDropdownPosition);
+			});
+			delete component.frameWindows;
+		}
+		delete component.updateDropdownPosition;
 		if (component.offResize) component.offResize();
 		if (this.pipeValidateDropdownPosition) instance.invoke("pipeValidateDropdownPosition", null, instance);
 		if (component.offParentPositionChange) component.offParentPositionChange();
@@ -6243,22 +6270,38 @@ class DropdownBase extends OverlayBase {
 	updateDropdownPosition(instance, component) {
 		var { el, initialScreenPosition } = component;
 		var { data, relatedElement } = instance;
-		var parentBounds = getTopLevelBoundingClientRect(relatedElement);
+		var elDocument = el.ownerDocument || document;
+		//if the dropdown renders in the same document as its related element (e.g. not
+		//portaled to the top-level body, such as an inline dropdown living inside an
+		//iframe together with its field), no cross-document offset should be applied -
+		//getBoundingClientRect() is already relative to that shared document/viewport.
+		var isSameDocument = el && relatedElement && el.ownerDocument === relatedElement.ownerDocument;
+		var parentBounds = isSameDocument
+			? relatedElement.getBoundingClientRect()
+			: getTopLevelBoundingClientRect(relatedElement);
 		//getBoundingClientRect() will return an empty rect if the element is hidden or removed
 		if (parentBounds.left == 0 && parentBounds.top == 0 && parentBounds.bottom == 0 && parentBounds.right == 0) {
 			if (!component.parentBounds) return;
 			parentBounds = component.parentBounds;
 		} else component.parentBounds = parentBounds;
-		if (this.trackMouseX && instance.mousePosition) {
-			parentBounds = new DOMRect(instance.mousePosition.x, parentBounds.top, 0, parentBounds.bottom - parentBounds.top);
+		//instance.mousePosition (set from getCursorPos) is always expressed in top-document
+		//coordinates. When the dropdown and its related element share a document that isn't
+		//the top document (e.g. both live inside the same iframe), parentBounds above is in
+		//that document's own coordinate space, so the mouse position must be translated into
+		//the same space before it can replace part of parentBounds.
+		var mousePosition = instance.mousePosition;
+		if (mousePosition && isSameDocument && elDocument !== document) {
+			const frameOffset = getParentFrameBoundingClientRect(relatedElement);
+			mousePosition = {
+				x: mousePosition.x - frameOffset.left,
+				y: mousePosition.y - frameOffset.top,
+			};
 		}
-		if (this.trackMouseY && instance.mousePosition) {
-			parentBounds = new DOMRect(
-				parentBounds.left,
-				instance.mousePosition.y,
-				parentBounds.right - parentBounds.left,
-				0,
-			);
+		if (this.trackMouseX && mousePosition) {
+			parentBounds = new DOMRect(mousePosition.x, parentBounds.top, 0, parentBounds.bottom - parentBounds.top);
+		}
+		if (this.trackMouseY && mousePosition) {
+			parentBounds = new DOMRect(parentBounds.left, mousePosition.y, parentBounds.right - parentBounds.left, 0);
 		}
 		let explode = this.pad && typeof this.elementExplode === "number" ? this.elementExplode : 0;
 		if (explode) {
@@ -6273,9 +6316,24 @@ class DropdownBase extends OverlayBase {
 		if (this.matchWidth) style.minWidth = `${parentBounds.right - parentBounds.left}px`;
 		if (this.matchMaxWidth) style.maxWidth = `${parentBounds.right - parentBounds.left}px`;
 		var contentSize = this.measureNaturalDropdownSize(instance, component);
-		var placement = this.findOptimalPlacement(contentSize, parentBounds, data.placement, component.lastPlacement);
+		var placement = this.findOptimalPlacement(
+			contentSize,
+			parentBounds,
+			data.placement,
+			component.lastPlacement,
+			elDocument,
+		);
 		var arrowAdjust = this.getArrowAdjust(component);
-		this.applyPositioningPlacementStyles(style, placement, contentSize, parentBounds, el, false, arrowAdjust);
+		this.applyPositioningPlacementStyles(
+			style,
+			placement,
+			contentSize,
+			parentBounds,
+			el,
+			false,
+			arrowAdjust,
+			elDocument,
+		);
 		component.setCustomStyle(style);
 		this.setDirectionClass(component, placement);
 		if (this.constrain) {
@@ -6283,7 +6341,16 @@ class DropdownBase extends OverlayBase {
 			let newContentSize = this.measureNaturalDropdownSize(instance, component);
 			if (newContentSize.width != contentSize.width || newContentSize.height != contentSize.height) {
 				let newStyle = {};
-				this.applyPositioningPlacementStyles(newStyle, placement, newContentSize, parentBounds, el, true, arrowAdjust);
+				this.applyPositioningPlacementStyles(
+					newStyle,
+					placement,
+					newContentSize,
+					parentBounds,
+					el,
+					true,
+					arrowAdjust,
+					elDocument,
+				);
 				component.setCustomStyle(newStyle);
 			}
 		}
@@ -6312,8 +6379,8 @@ class DropdownBase extends OverlayBase {
 		component.cachedArrowOffset = parsed;
 		return parsed;
 	}
-	applyFixedPositioningPlacementStyles(style, placement, contentSize, rel, el, noAuto, arrowAdjust = 0) {
-		let viewport = getViewportRect(this.screenPadding);
+	applyFixedPositioningPlacementStyles(style, placement, contentSize, rel, el, noAuto, arrowAdjust = 0, elDocument) {
+		let viewport = getViewportRect(this.screenPadding, elDocument);
 		style.position = "fixed";
 		if (placement.startsWith("down")) {
 			style.top = `${(this.cover ? rel.top : rel.bottom) + this.offset}px`;
@@ -6326,7 +6393,7 @@ class DropdownBase extends OverlayBase {
 			let top = rel.top - this.offset - contentSize.height - viewport.top;
 			style.top =
 				this.constrain && (noAuto || top < this.screenPadding + 10) ? Math.max(this.screenPadding, top) + "px" : "auto";
-			style.bottom = document.documentElement.offsetHeight - (this.cover ? rel.bottom : rel.top) + this.offset + "px";
+			style.bottom = elDocument.documentElement.clientHeight - (this.cover ? rel.bottom : rel.top) + this.offset + "px";
 		}
 		switch (placement) {
 			case "down":
@@ -6339,7 +6406,7 @@ class DropdownBase extends OverlayBase {
 				style.left = `${rel.left - arrowAdjust}px`;
 				break;
 			case "down-left":
-				style.right = `${document.documentElement.offsetWidth - rel.right - arrowAdjust}px`;
+				style.right = `${elDocument.documentElement.clientWidth - rel.right - arrowAdjust}px`;
 				style.left = "auto";
 				break;
 			case "up":
@@ -6352,7 +6419,7 @@ class DropdownBase extends OverlayBase {
 				style.left = `${rel.left - arrowAdjust}px`;
 				break;
 			case "up-left":
-				style.right = `${document.documentElement.offsetWidth - rel.right - arrowAdjust}px`;
+				style.right = `${elDocument.documentElement.clientWidth - rel.right - arrowAdjust}px`;
 				style.left = "auto";
 				break;
 			case "right":
@@ -6371,40 +6438,40 @@ class DropdownBase extends OverlayBase {
 			case "right-up":
 				style.top = "auto";
 				style.right = "auto";
-				style.bottom = `${document.documentElement.offsetHeight - rel.bottom - arrowAdjust}px`;
+				style.bottom = `${elDocument.documentElement.clientHeight - rel.bottom - arrowAdjust}px`;
 				style.left = `${rel.right + this.offset}px`;
 				break;
 			case "left":
 			case "left-center":
 				style.top = `${Math.round((rel.top + rel.bottom - el.offsetHeight) / 2)}px`;
-				style.right = `${document.documentElement.offsetWidth - rel.left + this.offset}px`;
+				style.right = `${elDocument.documentElement.clientWidth - rel.left + this.offset}px`;
 				style.bottom = "auto";
 				style.left = "auto";
 				break;
 			case "left-down":
 				style.top = `${rel.top - arrowAdjust}px`;
-				style.right = `${document.documentElement.offsetWidth - rel.left + this.offset}px`;
+				style.right = `${elDocument.documentElement.clientWidth - rel.left + this.offset}px`;
 				style.bottom = "auto";
 				style.left = "auto";
 				break;
 			case "left-up":
 				style.top = "auto";
-				style.right = `${document.documentElement.offsetWidth - rel.left + this.offset}px`;
-				style.bottom = `${document.documentElement.offsetHeight - rel.bottom - arrowAdjust}px`;
+				style.right = `${elDocument.documentElement.clientWidth - rel.left + this.offset}px`;
+				style.bottom = `${elDocument.documentElement.clientHeight - rel.bottom - arrowAdjust}px`;
 				style.left = "auto";
 				break;
 			case "screen-center":
-				let w = Math.min(contentSize.width, document.documentElement.offsetWidth - 2 * this.screenPadding);
-				let h = Math.min(contentSize.height, document.documentElement.offsetHeight - 2 * this.screenPadding);
-				style.top = `${Math.round((document.documentElement.offsetHeight - h) / 2)}px`;
-				style.right = `${Math.round((document.documentElement.offsetWidth - w) / 2)}px`;
-				style.bottom = `${Math.round((document.documentElement.offsetHeight - h) / 2)}px`;
-				style.left = `${Math.round((document.documentElement.offsetWidth - w) / 2)}px`;
+				let w = Math.min(contentSize.width, elDocument.documentElement.clientWidth - 2 * this.screenPadding);
+				let h = Math.min(contentSize.height, elDocument.documentElement.clientHeight - 2 * this.screenPadding);
+				style.top = `${Math.round((elDocument.documentElement.clientHeight - h) / 2)}px`;
+				style.right = `${Math.round((elDocument.documentElement.clientWidth - w) / 2)}px`;
+				style.bottom = `${Math.round((elDocument.documentElement.clientHeight - h) / 2)}px`;
+				style.left = `${Math.round((elDocument.documentElement.clientWidth - w) / 2)}px`;
 				break;
 		}
 	}
-	applyAbsolutePositioningPlacementStyles(style, placement, contentSize, rel, el, noAuto, arrowAdjust = 0) {
-		var viewport = getViewportRect(this.screenPadding);
+	applyAbsolutePositioningPlacementStyles(style, placement, contentSize, rel, el, noAuto, arrowAdjust = 0, elDocument) {
+		var viewport = getViewportRect(this.screenPadding, elDocument);
 		style.position = "absolute";
 		if (placement.startsWith("down")) {
 			style.top = `${rel.bottom - rel.top + this.offset}px`;
@@ -6488,7 +6555,16 @@ class DropdownBase extends OverlayBase {
 				break;
 		}
 	}
-	applyPositioningPlacementStyles(style, placement, contentSize, parentBounds, el, noAuto, arrowAdjust = 0) {
+	applyPositioningPlacementStyles(
+		style,
+		placement,
+		contentSize,
+		parentBounds,
+		el,
+		noAuto,
+		arrowAdjust = 0,
+		elDocument,
+	) {
 		switch (this.positioning) {
 			case "absolute":
 				this.applyAbsolutePositioningPlacementStyles(
@@ -6499,6 +6575,7 @@ class DropdownBase extends OverlayBase {
 					el,
 					noAuto,
 					arrowAdjust,
+					elDocument,
 				);
 				break;
 			case "auto":
@@ -6511,6 +6588,7 @@ class DropdownBase extends OverlayBase {
 						el,
 						noAuto,
 						arrowAdjust,
+						elDocument,
 					);
 				else
 					this.applyFixedPositioningPlacementStyles(
@@ -6521,10 +6599,20 @@ class DropdownBase extends OverlayBase {
 						el,
 						noAuto,
 						arrowAdjust,
+						elDocument,
 					);
 				break;
 			default:
-				this.applyFixedPositioningPlacementStyles(style, placement, contentSize, parentBounds, el, noAuto, arrowAdjust);
+				this.applyFixedPositioningPlacementStyles(
+					style,
+					placement,
+					contentSize,
+					parentBounds,
+					el,
+					noAuto,
+					arrowAdjust,
+					elDocument,
+				);
 				break;
 		}
 	}
@@ -6559,12 +6647,12 @@ class DropdownBase extends OverlayBase {
 		}
 		return size;
 	}
-	findOptimalPlacement(contentSize, target, placement, lastPlacement) {
+	findOptimalPlacement(contentSize, target, placement, lastPlacement, elDocument) {
 		var placementOrder = this.placementOrder.split(" ");
 		var best = lastPlacement || placement;
 		var first;
 		var score = {};
-		var viewport = getViewportRect();
+		var viewport = getViewportRect(0, elDocument);
 		for (var i = 0; i < placementOrder.length; i++) {
 			var p = placementOrder[i];
 			if (!first) first = p;
@@ -6718,12 +6806,12 @@ DropdownBase.prototype.cover = false;
 class Dropdown extends DropdownBase {}
 Widget$1.alias("dropdown", Dropdown);
 Localization$1.registerPrototype("cx/widgets/Dropdown", Dropdown);
-function getViewportRect(padding = 0) {
+function getViewportRect(padding = 0, elDocument = document) {
 	return {
 		left: padding,
 		top: padding,
-		right: document.documentElement.offsetWidth - padding,
-		bottom: document.documentElement.offsetHeight - padding,
+		right: elDocument.documentElement.clientWidth - padding,
+		bottom: elDocument.documentElement.clientHeight - padding,
 	};
 }
 
@@ -7199,7 +7287,7 @@ class WindowComponent extends OverlayComponent {
 	onFocusIn() {
 		super.onFocusIn();
 		if (!this.state.active) {
-			if (this.containerEl?.contains(document.activeElement)) this.setZIndex(ZIndexManager.next());
+			if (this.containerEl?.contains(getActiveElement())) this.setZIndex(ZIndexManager.next());
 			this.setState({
 				active: true,
 			});
@@ -8540,7 +8628,7 @@ let MenuItemComponent$1 = class MenuItemComponent extends VDOM$2.Component {
 		if (widget.dropdown) {
 			debug(menuFlag, "MenuItem", "mouseLeave", this.el);
 			this.clearAutoFocusTimer();
-			if (widget.hoverToOpen && document.activeElement == this.el) unfocusElement(this.el);
+			if (widget.hoverToOpen && getActiveElement() == this.el) unfocusElement(this.el);
 		}
 		tooltipMouseLeave$1(e, this.props.instance, widget.tooltip);
 	}
@@ -8628,7 +8716,7 @@ let MenuItemComponent$1 = class MenuItemComponent extends VDOM$2.Component {
 		let { widget } = this.props.instance;
 		if (widget.dropdown) {
 			oneFocusOut(this, this.el, this.onFocusOut.bind(this));
-			debug(menuFlag, "MenuItem", "focus", this.el, document.activeElement);
+			debug(menuFlag, "MenuItem", "focus", this.el, getActiveElement());
 			this.clearAutoFocusTimer();
 			if (widget.openOnFocus) this.openDropdown();
 		}
@@ -13000,8 +13088,12 @@ class Input extends VDOM$2.Component {
 			});
 		}
 		if (instance.widget.reactOn.indexOf(change) != -1) {
-			let value = inputValue || widget.emptyValue;
+			// Trimming on `input` would strip whitespace the user is still typing, so a trailing
+			// newline could never be entered.
+			let text = change != "input" && data.trim && isString(inputValue) ? inputValue.trim() : inputValue;
+			let value = text || widget.emptyValue;
 			instance.set("value", value);
+			if (this.input && text != inputValue) this.input.value = text;
 		}
 	}
 	onFocus() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cx",
-  "version": "26.8.0",
+  "version": "26.9.0",
   "description": "Advanced JavaScript UI framework for admin and dashboard applications with ready to use grid, form and chart components.",
   "exports": {
     "./data": {

package/src/charts/Legend.tsx

@@ -41,6 +41,15 @@ export interface LegendConfig extends HtmlElementConfig {
   /** Default shape to use for all entries. */
   shape?: StringProp;
 
+  /** ARIA role for each entry's shape `svg`. Defaults to `img` when `shapeAriaLabel` is set. */
+  shapeRole?: StringProp;
+
+  /**
+   * Accessible name for each entry's shape `svg`. Unnamed shapes are hidden from assistive
+   * technology, since the entry text already says what they mean.
+   */
+  shapeAriaLabel?: StringProp;
+
   /** Style applied to each entry. */
   entryStyle?: StyleProp;
 
@@ -97,6 +106,8 @@ export class Legend extends HtmlElement {
   declareData(...args: any[]): void {
     super.declareData(...args, {
       shape: undefined,
+      shapeRole: undefined,
+      shapeAriaLabel: undefined,
       entryStyle: { structured: true },
       entryClass: { structured: true },
       valueStyle: { structured: true },
@@ -124,6 +135,8 @@ export class Legend extends HtmlElement {
       case "shapeSize":
       case "svgSize":
       case "shape":
+      case "shapeRole":
+      case "shapeAriaLabel":
       case "entryStyle":
       case "entryClass":
       case "valueStyle":
@@ -177,7 +190,7 @@ export class Legend extends HtmlElement {
         instance.legends[this.name] && instance.legends[this.name].entries,
       list: React.ReactNode;
 
-    let { entryClass, entryStyle, shape, valueClass, valueStyle } =
+    let { entryClass, entryStyle, shape, shapeRole, shapeAriaLabel, valueClass, valueStyle } =
       instance.data;
     let valueFormatter = Format.parse(this.valueFormat);
 
@@ -210,7 +223,7 @@ export class Legend extends HtmlElement {
               onMouseMove={onMouseMove}
               onMouseLeave={onMouseLeave}
             >
-              {this.renderShape(e, shape)}
+              {this.renderShape(e, shape, shapeRole, shapeAriaLabel)}
               <div className={entryTextClass}>{e.displayText || e.name}</div>
               {this.showValues && (
                 <div className={valueClasses} style={valueStyle}>
@@ -229,6 +242,8 @@ export class Legend extends HtmlElement {
   renderShape(
     entry: LegendEntryData,
     legendEntriesShape: string | null | undefined,
+    role?: string,
+    ariaLabel?: string,
   ): React.ReactNode {
     const className = this.CSS.element(this.baseClass, "shape", {
       [`color-${entry.colorIndex}`]:
@@ -244,6 +259,11 @@ export class Legend extends HtmlElement {
     return (
       <svg
         className={this.CSS.element(this.baseClass, "svg")}
+        role={role ?? (ariaLabel ? "img" : undefined)}
+        aria-label={ariaLabel}
+        // Mutually exclusive with the above: `aria-hidden` removes the element from the
+        // accessibility tree, which is also what a tagged PDF is built from.
+        aria-hidden={role == null && !ariaLabel ? true : undefined}
         style={{
           width: `${this.svgSize}px`,
           height: `${this.svgSize}px`,

package/src/jsx-dev-runtime.ts

@@ -2,4 +2,5 @@ import { jsx, jsxs } from "./jsx-runtime";
 
 export const jsxDEV = jsx;
 export const jsxsDEV = jsxs;
-export { Fragment, JSX } from "./jsx-runtime";
+export { Fragment } from "./jsx-runtime";
+export type { JSX } from "./jsx-runtime";

package/src/svg/Svg.tsx

@@ -1,4 +1,5 @@
 /** @jsxImportSource react */
+import { StringProp } from "../ui/Prop";
 import { RenderingContext } from "../ui/RenderingContext";
 import { ResizeManager } from "../ui/ResizeManager";
 import { VDOM, Widget } from "../ui/Widget";
@@ -18,6 +19,15 @@ interface SvgInstance extends BoundedObjectInstance {
 }
 
 export interface SvgConfig extends BoundedObjectConfig {
+   /** ARIA role for the `svg` element. Defaults to `img` when `ariaLabel` is set. */
+   role?: StringProp;
+
+   /**
+    * Accessible name for the `svg` element. Setting it announces the drawing as a single graphic
+    * instead of as its individual shapes, which is also how a tagged PDF export tags it.
+    */
+   ariaLabel?: StringProp;
+
    /** Set to `true` to automatically calculate width based on the measured height and `aspectRatio`. */
    autoWidth?: boolean;
 
@@ -53,6 +63,16 @@ export class Svg extends BoundedObject<SvgConfig, SvgInstance> {
       super(config);
    }
 
+   declareData(...args: any[]) {
+      return super.declareData(
+         {
+            role: undefined,
+            ariaLabel: undefined,
+         },
+         ...args,
+      );
+   }
+
    initState(context: RenderingContext, instance: SvgInstance) {
       const size = {
          width: 0,
@@ -147,6 +167,9 @@ class SvgComponent extends VDOM.Component<SvgComponentProps> {
       const { instance, data, size, children, eventHandlers } = this.props;
       const { widget } = instance;
 
+      // An unnamed drawing is left alone: `role="img"` would hide its text and put nothing in its place.
+      const role = data.role ?? (data.ariaLabel ? "img" : undefined);
+
       const defs: any[] = [];
       for (const k in (instance as any).clipRects) {
          let cr = (instance as any).clipRects[k];
@@ -181,7 +204,7 @@ class SvgComponent extends VDOM.Component<SvgComponentProps> {
             {...eventHandlers}
          >
             {size.width > 0 && size.height > 0 && (
-               <svg>
+               <svg role={role} aria-label={data.ariaLabel}>
                   <defs>{defs}</defs>
                   {children}
                </svg>