Merge pull request #1247 from Alex-Jordan/image-descriptions

long image descriptions

Author: drgrice1

htdocs/js/Problem/details-accordion.js htdocs/js/Problem/generic.jshtdocs/js/Problem/details-accordion.js renamed to htdocs/js/Problem/generic.js

@@ -1,4 +1,6 @@
 (() => {
+	// Details accordions
+
 	const setupAccordion = (accordion) => {
 		const collapseEl = accordion.querySelector('.collapse');
 		const button = accordion.querySelector('summary.accordion-button');
@@ -38,4 +40,30 @@
 		});
 	});
 	observer.observe(document.body, { childList: true, subtree: true });
+
+	// Image long descriptions
+
+	for (const dismissButton of document.querySelectorAll('.image-details-dismiss')) {
+		dismissButton.addEventListener('click', () =>
+			dismissButton.parentElement?.parentElement?.parentElement?.removeAttribute('open')
+		);
+	}
+
+	for (const imageDescription of document.querySelectorAll('.image-details')) {
+		const escapeCloseDetails = (e) => {
+			if (e.key === 'Escape') imageDescription.removeAttribute('open');
+		};
+		const clickCloseDetails = (e) => {
+			if (e.target.closest('.image-details') !== imageDescription) imageDescription.removeAttribute('open');
+		};
+		imageDescription.addEventListener('toggle', () => {
+			if (imageDescription.open) {
+				document.addEventListener('keydown', escapeCloseDetails);
+				document.addEventListener('pointerdown', clickCloseDetails);
+			} else {
+				document.removeEventListener('keydown', escapeCloseDetails);
+				document.removeEventListener('pointerdown', clickCloseDetails);
+			}
+		});
+	}
 })();

htdocs/js/Problem/problem.scss

@@ -203,6 +203,27 @@
 	}
 }
 
+.image-container {
+	.image-details-content {
+		position: fixed;
+		bottom: 0;
+		left: 50%;
+		transform: translateX(-50%);
+		width: max-content;
+		max-width: 90%;
+		box-shadow: 0 0 100px black;
+		border-radius: 4px;
+		z-index: 10;
+	}
+
+	.image-details-btn {
+		--bs-btn-padding-y: 0.1rem;
+		--bs-btn-padding-x: 0.35rem;
+		--bs-btn-font-size: 0.65rem;
+		--bs-btn-border-radius: 0.375rem;
+	}
+}
+
 /* rtl:raw:
 .problem-content[dir=ltr] input[type=radio] {
 	margin-right: 0.25rem;

lib/Plots/JSXGraph.pm

@@ -34,10 +34,14 @@ sub HTML {
 
 	my $imageviewClass = $self->plots->axes->style('jsx_navigation') ? '' : ' image-view-elt';
 	my $tabindex       = $self->plots->axes->style('jsx_navigation') ? '' : ' tabindex="0"';
+	my $details        = $self->plots->{description_details} =~ s/LONG-DESCRIPTION-ID/${name}_details/r;
+	my $aria_details   = $details ? qq! aria-details="${name}_details"! : '';
+	my $divs           = qq!<div id="jsxgraph-plot-$name" class="jxgbox plots-jsxgraph$imageviewClass"$tabindex!
+		. qq!style="width: ${width}px; height: ${height}px;"$aria_details></div>!;
+	$divs = qq!<div class="image-container">$divs$details</div>! if ($details);
 
 	return <<~ "END_HTML";
-		<div id="jsxgraph-plot-$name" class="jxgbox plots-jsxgraph$imageviewClass"$tabindex
-			style="width: ${width}px; height: ${height}px;"></div>
+		$divs
 		<script>
 		(async () => {
 			const drawBoard = (id) => {

macros/PG.pl

@@ -381,12 +381,12 @@ sub ADD_JS_FILE {
 # although those problems should also be rewritten to not use jquery-ui.
 sub load_js() {
 
-	ADD_JS_FILE('js/Feedback/feedback.js',         0, { defer => undef });
-	ADD_JS_FILE('js/Base64/Base64.js',             0, { defer => undef });
-	ADD_JS_FILE('js/Knowls/knowl.js',              0, { defer => undef });
-	ADD_JS_FILE('js/Problem/details-accordion.js', 0, { defer => undef });
-	ADD_JS_FILE('js/ImageView/imageview.js',       0, { defer => undef });
-	ADD_JS_FILE('js/Essay/essay.js',               0, { defer => undef });
+	ADD_JS_FILE('js/Feedback/feedback.js',   0, { defer => undef });
+	ADD_JS_FILE('js/Base64/Base64.js',       0, { defer => undef });
+	ADD_JS_FILE('js/Knowls/knowl.js',        0, { defer => undef });
+	ADD_JS_FILE('js/Problem/generic.js',     0, { defer => undef });
+	ADD_JS_FILE('js/ImageView/imageview.js', 0, { defer => undef });
+	ADD_JS_FILE('js/Essay/essay.js',         0, { defer => undef });
 
 	if ($envir{useMathQuill}) {
 		ADD_JS_FILE('node_modules/@openwebwork/mathquill/dist/mathquill.js', 0, { defer => undef });

macros/core/PGML.pl

@@ -687,7 +687,7 @@ sub NOOP {
 		terminator         => qr/!\]/,
 		terminateMethod    => 'terminateGetString',
 		cancelNL           => 1,
-		options            => [ "source", "width", "height", "image_options" ]
+		options => [ "source", "width", "height", "image_options", "long_description", "long_description_width" ]
 	},
 	"[<" => {
 		type        => 'tag',
@@ -1484,12 +1484,22 @@ sub Text {
 
 sub Image {
 	my ($self, $item) = @_;
-	my $text          = $item->{text};
-	my $source        = $item->{source};
-	my $width         = $item->{width}         || '';
-	my $height        = $item->{height}        || '';
-	my $image_options = $item->{image_options} || {};
-	return (main::image($source, alt => $text, width => $width, height => $height, %$image_options));
+	my $text                   = $item->{text};
+	my $source                 = $item->{source};
+	my $width                  = $item->{width}                  || '';
+	my $height                 = $item->{height}                 || '';
+	my $image_options          = $item->{image_options}          || {};
+	my $long_description       = $item->{long_description}       || '';
+	my $long_description_width = $item->{long_description_width} || 1;
+	return (main::image(
+		$source,
+		alt                    => $text,
+		width                  => $width,
+		height                 => $height,
+		long_description       => $long_description,
+		long_description_width => $long_description_width,
+		%$image_options
+	));
 }
 
 ######################################################################

macros/core/PGbasicmacros.pl

@@ -2737,10 +2737,10 @@ =head2 Macros for displaying images
 
 Usage:
 
-    image($image, width => 200, height => 200, tex_size => 800, valign => 'middle', alt => 'alt text', extra_html_tags => 'style="border:solid black 1pt"');
+    image($image, width => ..., height => ..., tex_size => ..., valign => ..., alt => ..., long_description => ... );
 
 where C<$image> can be a local file path, URL, WWPlot object, PGlateximage object,
-PGtikz object, or parser::GraphTool object.
+PGtikz object, Plots::Plot object, or parser::GraphTool object.
 
 C<width> and C<height> are positive integer pixel counts for HTML display. If both
 are missing, C<width> will default to 200 and C<height> will remain undeclared,
@@ -2757,10 +2757,34 @@ =head2 Macros for displaying images
 C<valign> can be 'top', 'middle', or 'bottom'.  This aligns the image relative to
 the surrounding line of text.
 
-    image([$image1,$image2], width => 200, height => 200, tex_size => 800, alt => ['alt text 1','alt text 2'], extra_html_tags => 'style="border:solid black 1pt"');
-    image([$image1,$image2], width => 200, height => 200, tex_size => 800, alt => 'common alt text', extra_html_tags => 'style="border:solid black 1pt"');
+C<alt> should be a string, ideally with fewer than 125 characters, that describes the
+most important features of the image. This should always be used. If the image is
+decorative, C<< alt => '' >> should be used.
 
-this produces an array in array context and joins the elements with C<' '> in scalar context
+C<long_description> provides an optional way to give a more complete description of
+an image. This may include a table (for example to describe complex data in a graph).
+It may be helpful to generate blocks of text and tables and store them in a variable,
+and pass that variable to C<long_description>.
+
+C<long_description_width> defaults to 1. This should be a positive number at most 1.
+In hardcopy output, this portion of the line width will be used to cap the width
+of the long description (if there is one). This is useful for example when the image
+is inside a table.
+
+C<extra_html_tags> [DEPRECATED] can be a string will directly be placed into the
+HTML img element. For example, C<< extra_html_tags => 'style="border:solid black 1pt"' >>.
+
+The first argument to C<image()> can alternatively be an array of images:
+
+    image([$image1, $image2], ...);
+
+If so then if C<alt> or C<long_description> are not arrays, they will be used
+repeatedly for each image. Each of C<alt> and C<long_description> can instead be
+arrays of the same length and their entries will be used with the corresponding
+image.
+
+In array context, using C<image()> this way will produces an array in array context
+and join the elements with C<' '> in scalar context.
 
 =cut
 
@@ -2778,8 +2802,10 @@ sub image {
 		tex_size => '',
 		valign   => 'middle',
 		# default value for alt is undef, since an empty string is the explicit indicator of a decorative image
-		alt             => undef,
-		extra_html_tags => '',
+		alt                    => undef,
+		long_description       => undef,
+		long_description_width => 1,
+		extra_html_tags        => '',
 	);
 	# handle options
 	my %out_options = %known_options;
@@ -2802,9 +2828,12 @@ sub image {
 	$tex_size = 1000 if $tex_size > 1000;
 
 	my $alt         = $out_options{alt};
-	my $width_ratio = $tex_size * (.001);
+	my $desc        = $out_options{long_description};
+	my $ldw         = $out_options{long_description_width};
+	my $width_ratio = $tex_size * 0.001;
 	my @image_list  = ();
 	my @alt_list    = ();
+	my @desc_list   = ();
 	my $valign      = 'middle';
 	$valign = 'top'    if ($out_options{valign} eq 'top');
 	$valign = 'bottom' if ($out_options{valign} eq 'bottom');
@@ -2823,16 +2852,58 @@ sub image {
 	} else {
 		for my $i (@image_list) { push(@alt_list, $alt) }
 	}
+	if (ref($desc) =~ /ARRAY/) {
+		@desc_list = @{$desc};
+	} else {
+		for my $i (@image_list) { push(@desc_list, $desc) }
+	}
 
 	my @output_list = ();
 	while (@image_list) {
-		my $image_item = shift @image_list;
+		my $image_item          = shift @image_list;
+		my $description_details = $desc ? shift(@desc_list) : '';
+		if ($desc && $displayMode ne 'PTX' && $displayMode ne 'TeX') {
+			$description_details = tag(
+				'details',
+				'aria-live' => 'polite',
+				class       => 'image-details',
+				name        => 'image-details',
+				tag(
+					'summary',
+					class => 'mt-1',
+					title => 'details',
+					tag(
+						'span',
+						class         => 'image-details-btn btn btn-sm btn-secondary fw-bold',
+						'aria-hidden' => 'true',
+						maketext('image description')
+					)
+					)
+					. tag(
+						'div',
+						id    => 'LONG-DESCRIPTION-ID',
+						class => 'image-details-content bg-white py-2 px-3 my-2 border',
+						$description_details
+						. tag(
+							'div',
+							class => 'd-flex justify-content-end mt-2',
+							tag(
+								'button',
+								class => 'image-details-dismiss btn btn-sm btn-secondary',
+								type  => 'button',
+								maketext('Close image description')
+							)
+						)
+					)
+			);
+		}
 		if (ref $image_item eq 'parser::GraphTool') {
 			push(
 				@output_list,
 				$image_item->generateAnswerGraph(
-					$out_options{width}    || $out_options{height} ? (width   => $width, height => $height) : (),
-					$out_options{tex_size} || $out_options{width}  ? (texSize => $tex_size)                 : (),
+					$out_options{width} || $out_options{height}   ? (width           => $width, height => $height) : (),
+					$out_options{tex_size} || $out_options{width} ? (texSize         => $tex_size)                 : (),
+					$desc                                         ? (longDescription => $description_details)      : (),
 					ariaDescription => shift @alt_list // ''
 				)
 			);
@@ -2846,6 +2917,7 @@ sub image {
 			$image_item->axes->style(aria_description => shift @alt_list) if $out_options{alt};
 
 			if ($image_item->ext eq 'html') {
+				$image_item->{description_details} = $description_details;
 				push(@output_list, $image_item->draw);
 				next;
 			}
@@ -2862,25 +2934,36 @@ sub image {
 				|| ref $image_item eq 'PGtikz');
 		my $imageURL = alias($image_item) // '';
 		$imageURL = ($envir{use_site_prefix}) ? $envir{use_site_prefix} . $imageURL : $imageURL;
-		my $out = "";
+		my $id  = $main::PG->getUniqueName('img');
+		my $out = '';
 
 		if ($displayMode eq 'TeX') {
 			my $imagePath = $imageURL;    # in TeX mode, alias gives us a path, not a URL
 
 			# We're going to create PDF files with our TeX (using LaTeX), so
 			# alias should have given us the path to a PNG image.
 			if ($imagePath) {
+				if ($desc) {
+					$out .= "\\parbox{$ldw\\linewidth}{";
+					$width_ratio = $width_ratio / $ldw;
+				}
 				if ($valign eq 'top') {
-					$out = '\settoheight{\strutheight}{\strut}'
-						. "\\raisebox{-\\height + \\strutheight}{\\includegraphics[width=$width_ratio\\linewidth]{$imagePath}}\n";
+					$out .= '\settoheight{\strutheight}{\strut}\raisebox{-\height + \strutheight}'
+						. "{\\includegraphics[width=$width_ratio\\linewidth]{$imagePath}}\n";
 				} elsif ($valign eq 'bottom') {
-					$out = "\\includegraphics[width=$width_ratio\\linewidth]{$imagePath}\n";
+					$out .= "\\includegraphics[width=$width_ratio\\linewidth]{$imagePath}\n";
 				} else {
-					$out = '\settoheight{\strutheight}{\strut}'
-						. "\\raisebox{-0.5\\height + 0.5\\strutheight}{\\includegraphics[width=$width_ratio\\linewidth]{$imagePath}}\n";
+					$out .= '\settoheight{\strutheight}{\strut}\raisebox{-0.5\height + 0.5\strutheight}'
+						. "{\\includegraphics[width=$width_ratio\\linewidth]{$imagePath}}\n";
+				}
+				if ($desc) {
+					$out .=
+						"\\newline\\par\\parbox{\\linewidth}{{\\scshape\\underline{"
+						. maketext('image description')
+						. "}}\\newline{}$description_details\\par\\hfill\\(\\overline{\\mbox{\\scshape "
+						. maketext('end image description')
+						. "}}\\)}}\\par\n";
 				}
-			} else {
-				$out = "";
 			}
 		} elsif ($displayMode eq 'HTML_MathJax'
 			|| $displayMode eq 'HTML_dpng'
@@ -2889,15 +2972,31 @@ sub image {
 		{
 			my $altattrib = '';
 			if (defined $alt_list[0]) { $altattrib = 'alt="' . encode_pg_and_html(shift @alt_list) . '"' }
-			$out =
-				qq!<IMG SRC="$imageURL" class="image-view-elt $valign" tabindex="0" role="button"$width_attrib$height_attrib $out_options{extra_html_tags} $altattrib>!;
+			if ($desc) {
+				$out .= tag(
+					'div',
+					class => 'image-container pb-2',
+					qq!<img src="$imageURL" class="image-view-elt $valign" tabindex="0" role="button"!
+						. qq!$width_attrib$height_attrib aria-details="${id}_details" $out_options{extra_html_tags} $altattrib>!
+						. ($description_details =~ s/LONG-DESCRIPTION-ID/${id}_details/r)
+				);
+			} else {
+				$out .= qq!<img src="$imageURL" class="image-view-elt $valign" tabindex="0" role="button"!
+					. qq!$width_attrib$height_attrib $out_options{extra_html_tags} $altattrib>!;
+			}
 		} elsif ($displayMode eq 'PTX') {
 			my $ptxwidth = ($width ? int($width / 6) : 80);
+			$out = qq!<image width="$ptxwidth%" source="$imageURL">!;
 			if (defined $alt) {
-				$out = qq!<image width="$ptxwidth%" source="$imageURL"><description>$alt</description></image>!;
-			} else {
-				$out = qq!<image width="$ptxwidth%" source="$imageURL" />!;
+				$out .= "\n<shortdescription>$alt</shortdescription>";
+			}
+			if (defined $desc) {
+				$out .= "\n<description>\n" . PTX_cleanup($description_details) . "\n</description>";
+			}
+			if (defined $alt || defined $desc) {
+				$out .= "\n";
 			}
+			$out .= '</image>';
 		} else {
 			$out = "Error: PGbasicmacros: image: Unknown displayMode: $displayMode.\n";
 		}