Add configurable "Shift + Enter で改行" hint below AI overview input

Small muted gray helper text directly under the AI overview field,
configurable via the block's hintText attribute (empty = hidden) and
translatable. Wired to the textarea via aria-describedby. Hidden on
touch devices via a device-capability media query (hover:none +
pointer:coarse), deliberately not a width breakpoint.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RCRKyC4sroy5Xk144DGJdS

Author: claude

hamelp.php

@@ -297,6 +297,7 @@ function hamelp_render_search_box( $args = [] ) {
  *
  *     @type string $placeholder   Input placeholder text. Default 'Enter your question...'.
  *     @type string $button_text   Submit button text. Default 'Ask AI'.
+ *     @type string $hint_text     Helper text shown below the input (empty = hidden). Default 'Shift + Enter で改行'.
  *     @type bool   $show_sources  Whether to show source FAQ links. Default true.
  *     @type string $wrapper_attrs Pre-built wrapper attributes string (used internally by block render).
  * }
@@ -313,6 +314,7 @@ function hamelp_render_ai_overview( $args = [] ) {
 		[
 			'placeholder'   => __( 'Enter your question...', 'hamelp' ),
 			'button_text'   => __( 'Ask AI', 'hamelp' ),
+			'hint_text'     => __( 'Shift + Enter で改行', 'hamelp' ),
 			'show_sources'  => true,
 			'wrapper_attrs' => '',
 		]
@@ -352,23 +354,41 @@ function hamelp_render_ai_overview( $args = [] ) {
 		);
 	}
 
+	// Optional helper text below the field (e.g. "Shift + Enter で改行"). When set,
+	// it is associated with the textarea via aria-describedby; empty = not rendered.
+	$hint_text   = trim( (string) $args['hint_text'] );
+	$hint_html   = '';
+	$hint_attr   = '';
+	if ( '' !== $hint_text ) {
+		$hint_id   = wp_unique_id( 'hamelp-ai-overview-' ) . '-hint';
+		$hint_html = sprintf(
+			'<p class="hamelp-ai-overview__hint" id="%1$s">%2$s</p>',
+			esc_attr( $hint_id ),
+			esc_html( $hint_text )
+		);
+		$hint_attr = sprintf( ' aria-describedby="%s"', esc_attr( $hint_id ) );
+	}
+
 	return sprintf(
 		'<div %1$s>
 	<div class="hamelp-ai-overview__thread" aria-live="polite"></div>
 	<form class="hamelp-ai-overview__form">
 		%2$s
 		<div class="hamelp-ai-overview__input-row">
-			<textarea class="hamelp-ai-overview__input" placeholder="%3$s" required></textarea>
+			<textarea class="hamelp-ai-overview__input" placeholder="%3$s"%5$s required></textarea>
 			<button type="submit" class="hamelp-ai-overview__button">
 				<svg class="hamelp-ai-overview__button-icon" width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true" focusable="false" xmlns="http://www.w3.org/2000/svg"><path d="M12 19V5M6 11l6-6 6 6" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>
 				<span class="screen-reader-text">%4$s</span>
 			</button>
 		</div>
+		%6$s
 	</form>
 </div>',
 		$args['wrapper_attrs'],
 		$continue_toggle, // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- built from esc_html__ above.
 		esc_attr( $args['placeholder'] ),
-		esc_html( $args['button_text'] )
+		esc_html( $args['button_text'] ),
+		$hint_attr, // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- built from esc_attr above.
+		$hint_html // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- built from esc_html/esc_attr above.
 	);
 }

src/blocks/ai-overview/block.json

@@ -16,6 +16,10 @@
 			"type": "string",
 			"default": "Ask AI"
 		},
+		"hintText": {
+			"type": "string",
+			"default": "Shift + Enter で改行"
+		},
 		"showSources": {
 			"type": "boolean",
 			"default": true

src/blocks/ai-overview/edit.js

@@ -17,7 +17,7 @@ import { PanelBody, TextControl, ToggleControl } from '@wordpress/components';
  * @return {JSX.Element} Block editor component.
  */
 export default function Edit( { attributes, setAttributes } ) {
-	const { placeholder, buttonText, showSources } = attributes;
+	const { placeholder, buttonText, hintText, showSources } = attributes;
 
 	return (
 		<>
@@ -44,6 +44,17 @@ export default function Edit( { attributes, setAttributes } ) {
 							setAttributes( { buttonText: value } )
 						}
 					/>
+					<TextControl
+						label={ __( '入力欄下の補助テキスト', 'hamelp' ) }
+						help={ __(
+							'Shift+Enterで改行できることの案内などに。空にすると非表示。スマートフォン等のタッチ端末では自動的に非表示になります。',
+							'hamelp'
+						) }
+						value={ hintText }
+						onChange={ ( value ) =>
+							setAttributes( { hintText: value } )
+						}
+					/>
 					<ToggleControl
 						label={ __( 'Show Sources', 'hamelp' ) }
 						checked={ showSources }
@@ -80,6 +91,9 @@ export default function Edit( { attributes, setAttributes } ) {
 						</span>
 					</button>
 				</div>
+				{ hintText && (
+					<p className="hamelp-ai-overview__hint">{ hintText }</p>
+				) }
 				<p className="hamelp-ai-overview__note">
 					{ __( 'AI Overview - Preview', 'hamelp' ) }
 				</p>

src/blocks/ai-overview/render.php

@@ -23,6 +23,7 @@
 	[
 		'placeholder'   => $attributes['placeholder'] ?? __( 'Enter your question...', 'hamelp' ),
 		'button_text'   => $attributes['buttonText'] ?? __( 'Ask AI', 'hamelp' ),
+		'hint_text'     => $attributes['hintText'] ?? __( 'Shift + Enter で改行', 'hamelp' ),
 		'show_sources'  => ! empty( $attributes['showSources'] ),
 		'wrapper_attrs' => $wrapper_attributes,
 	]

src/blocks/ai-overview/style.scss

@@ -109,6 +109,24 @@
 	outline-offset: 2px;
 }
 
+// Small muted helper text directly under the input (e.g. "Shift + Enter で改行").
+// Muted via opacity so it inherits and adapts to any theme's text color.
+:where(.hamelp-ai-overview__hint) {
+	margin: 0.375rem 0 0 0.75rem;
+	font-size: 0.8em;
+	line-height: 1.4;
+	opacity: 0.6;
+}
+
+// Hide the hint on touch devices, where Shift+Enter is meaningless without a
+// physical keyboard. Device-CAPABILITY query (coarse pointer + no hover),
+// deliberately NOT a width breakpoint, to avoid colliding with theme breakpoints.
+@media (hover: none) and (pointer: coarse) {
+	:where(.hamelp-ai-overview__hint) {
+		display: none;
+	}
+}
+
 :where(.hamelp-ai-overview__button) {
 	// Fixed-size circular icon button (ChatGPT-style), floated inside the field's
 	// bottom-right corner. The constant bottom offset keeps it pinned to the