From 456e744d818cc42fcb0832ae31f6d884a3291fd7 Mon Sep 17 00:00:00 2001
From: Jonathan Miller <jmiller-moko@noreply.git.mokoconsulting.tech>
Date: Tue, 23 Jun 2026 10:47:45 -0500
Subject: [PATCH] feat: clickable placeholder pills for backup dir and archive
 name fields

Both Backup Directory and Archive Name Format fields now show clickable
placeholder tags below the input. Clicking a tag inserts the placeholder
at the current cursor position using selectionStart/End.

- FolderPickerField: pills for [HOME], [DEFAULT_DIR], [host], [site_name],
  [date], [profile_id], [profile_name], [type]
- PlaceholderTextField: new custom field type used by archive_name_format,
  configurable placeholders via XML attribute
- Cursor position preserved after insert, input event dispatched for
  live status updates
---
 .../com_mokosuitebackup/forms/profile.xml     |  4 +-
 .../src/Field/FolderPickerField.php           | 31 ++++++++
 .../src/Field/PlaceholderTextField.php        | 78 +++++++++++++++++++
 3 files changed, 112 insertions(+), 1 deletion(-)
 create mode 100644 source/packages/com_mokosuitebackup/src/Field/PlaceholderTextField.php

diff --git a/source/packages/com_mokosuitebackup/forms/profile.xml b/source/packages/com_mokosuitebackup/forms/profile.xml
index c6e65ff..131fad5 100644
--- a/source/packages/com_mokosuitebackup/forms/profile.xml
+++ b/source/packages/com_mokosuitebackup/forms/profile.xml
@@ -72,12 +72,14 @@
 		/>
 		<field
 			name="archive_name_format"
-			type="text"
+			type="PlaceholderText"
 			label="COM_MOKOJOOMBACKUP_FIELD_ARCHIVE_NAME_FORMAT"
 			description="COM_MOKOJOOMBACKUP_FIELD_ARCHIVE_NAME_FORMAT_DESC"
 			default="[host]_[datetime]_profile[profile_id]"
 			maxlength="512"
 			hint="[host]_[datetime]_profile[profile_id]"
+			placeholders="[host],[datetime],[date],[time],[year],[month],[day],[hour],[minute],[second],[profile_id],[profile_name],[site_name],[type],[random]"
+			addfieldprefix="Joomla\Component\MokoSuiteBackup\Administrator\Field"
 		/>
 		<field
 			name="include_mokorestore"
diff --git a/source/packages/com_mokosuitebackup/src/Field/FolderPickerField.php b/source/packages/com_mokosuitebackup/src/Field/FolderPickerField.php
index cb455b7..6ecb23b 100644
--- a/source/packages/com_mokosuitebackup/src/Field/FolderPickerField.php
+++ b/source/packages/com_mokosuitebackup/src/Field/FolderPickerField.php
@@ -100,6 +100,17 @@ class FolderPickerField extends FormField
 		<span class="icon-question-circle" aria-hidden="true"></span>
 	</button>
 </div>
+<div class="mt-1 mb-1" id="{$id}_placeholders" style="display:flex; flex-wrap:wrap; gap:4px;">
+	<span class="text-muted small me-1" style="line-height:24px;">Insert:</span>
+	<button type="button" class="btn btn-outline-secondary btn-sm py-0 px-1 moko-ph-insert" data-field="{$id}" data-ph="[HOME]" title="Home directory">[HOME]</button>
+	<button type="button" class="btn btn-outline-secondary btn-sm py-0 px-1 moko-ph-insert" data-field="{$id}" data-ph="[DEFAULT_DIR]" title="Default backup dir">[DEFAULT_DIR]</button>
+	<button type="button" class="btn btn-outline-secondary btn-sm py-0 px-1 moko-ph-insert" data-field="{$id}" data-ph="[host]" title="Server hostname">[host]</button>
+	<button type="button" class="btn btn-outline-secondary btn-sm py-0 px-1 moko-ph-insert" data-field="{$id}" data-ph="[site_name]" title="Joomla site name">[site_name]</button>
+	<button type="button" class="btn btn-outline-secondary btn-sm py-0 px-1 moko-ph-insert" data-field="{$id}" data-ph="[date]" title="Date (Ymd)">[date]</button>
+	<button type="button" class="btn btn-outline-secondary btn-sm py-0 px-1 moko-ph-insert" data-field="{$id}" data-ph="[profile_id]" title="Profile ID">[profile_id]</button>
+	<button type="button" class="btn btn-outline-secondary btn-sm py-0 px-1 moko-ph-insert" data-field="{$id}" data-ph="[profile_name]" title="Profile name">[profile_name]</button>
+	<button type="button" class="btn btn-outline-secondary btn-sm py-0 px-1 moko-ph-insert" data-field="{$id}" data-ph="[type]" title="Backup type">[type]</button>
+</div>
 <div class="mt-1" id="{$id}_status">
 	<small class="{$statusClass}">
 		<span class="{$statusIcon}" aria-hidden="true"></span>
@@ -155,6 +166,26 @@ class FolderPickerField extends FormField
 </div>
 <script>
 (function() {
+	/* Clickable placeholder insertion at cursor position */
+	document.querySelectorAll('.moko-ph-insert[data-field="{$id}"]').forEach(function(btn) {
+		btn.addEventListener('click', function(e) {
+			e.preventDefault();
+			var target = document.getElementById(this.getAttribute('data-field'));
+			var ph = this.getAttribute('data-ph');
+			if (!target) return;
+			var start = target.selectionStart || 0;
+			var end = target.selectionEnd || 0;
+			var val = target.value;
+			target.value = val.substring(0, start) + ph + val.substring(end);
+			/* Move cursor to after the inserted placeholder */
+			var newPos = start + ph.length;
+			target.setSelectionRange(newPos, newPos);
+			target.focus();
+			/* Trigger input event so status updates */
+			target.dispatchEvent(new Event('input', { bubbles: true }));
+		});
+	});
+
 	var fieldId = '{$id}';
 	var btn = document.getElementById(fieldId + '_btn');
 	var browser = document.getElementById(fieldId + '_browser');
diff --git a/source/packages/com_mokosuitebackup/src/Field/PlaceholderTextField.php b/source/packages/com_mokosuitebackup/src/Field/PlaceholderTextField.php
new file mode 100644
index 0000000..228418e
--- /dev/null
+++ b/source/packages/com_mokosuitebackup/src/Field/PlaceholderTextField.php
@@ -0,0 +1,78 @@
+<?php
+
+/**
+ * @package     MokoSuiteBackup
+ * @subpackage  com_mokosuitebackup
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ *
+ * Text field with clickable placeholder pills that insert at cursor position.
+ * Used for backup directory and archive name format fields.
+ */
+
+namespace Joomla\Component\MokoSuiteBackup\Administrator\Field;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Form\FormField;
+
+class PlaceholderTextField extends FormField
+{
+	protected $type = 'PlaceholderText';
+
+	protected function getInput(): string
+	{
+		$value = htmlspecialchars($this->value ?? $this->default ?? '', ENT_QUOTES, 'UTF-8');
+		$id    = htmlspecialchars($this->id, ENT_QUOTES, 'UTF-8');
+		$name  = htmlspecialchars($this->name, ENT_QUOTES, 'UTF-8');
+		$hint  = htmlspecialchars($this->element['hint'] ?? '', ENT_QUOTES, 'UTF-8');
+		$max   = (int) ($this->element['maxlength'] ?? 512);
+
+		$placeholderAttr = (string) ($this->element['placeholders'] ?? '');
+		$placeholders = array_filter(array_map('trim', explode(',', $placeholderAttr)));
+
+		if (empty($placeholders)) {
+			$placeholders = ['[host]', '[date]', '[datetime]', '[time]', '[year]', '[month]', '[day]',
+				'[hour]', '[minute]', '[second]', '[profile_id]', '[profile_name]', '[site_name]', '[type]', '[random]'];
+		}
+
+		$html = '<input type="text" name="' . $name . '" id="' . $id . '" value="' . $value . '"'
+			. ' class="form-control" maxlength="' . $max . '"'
+			. ($hint ? ' placeholder="' . $hint . '"' : '') . '>';
+
+		$html .= '<div class="mt-1" style="display:flex; flex-wrap:wrap; gap:4px;">';
+		$html .= '<span class="text-muted small me-1" style="line-height:24px;">Insert:</span>';
+
+		foreach ($placeholders as $ph) {
+			$html .= '<button type="button" class="btn btn-outline-secondary btn-sm py-0 px-1 moko-ph-insert"'
+				. ' data-field="' . $id . '" data-ph="' . htmlspecialchars($ph) . '">'
+				. htmlspecialchars($ph) . '</button>';
+		}
+
+		$html .= '</div>';
+
+		$html .= <<<JS
+<script>
+document.querySelectorAll('.moko-ph-insert[data-field="{$id}"]').forEach(function(btn) {
+	btn.addEventListener('click', function(e) {
+		e.preventDefault();
+		var target = document.getElementById(this.getAttribute('data-field'));
+		var ph = this.getAttribute('data-ph');
+		if (!target) return;
+		var start = target.selectionStart || 0;
+		var end = target.selectionEnd || 0;
+		var val = target.value;
+		target.value = val.substring(0, start) + ph + val.substring(end);
+		var newPos = start + ph.length;
+		target.setSelectionRange(newPos, newPos);
+		target.focus();
+		target.dispatchEvent(new Event('input', { bubbles: true }));
+	});
+});
+</script>
+JS;
+
+		return $html;
+	}
+}