* wrapping a with one row per field. Hidden inputs * and datalist elements are emitted before the table; notices before the card, * submit button after the fields. * * Usage: * echo RsvFormBuilder::create('settings', $action, 'PATCH', 'Saved.') * ->heading('Settings') * ->text('name', 'Name', required: true) * ->email('email', 'Email') * ->submit('Save'); */ class RsvFormBuilder { private string $form_id; /** Where the form submits, and how RsvAdminForm should send it. */ private string $action; private string $rest_method; private string $success_msg; /** Optional heading shown inside the card. */ private string $heading = ''; /** @var string[] Rendered before the table (hidden inputs, datalists). */ private array $before = []; /** @var string[] WP admin notice banners rendered before the card. */ private array $notices = []; /** @var string[] elements inside the table. */ private array $rows = []; /** @var string[] Rendered after the table (submit button). */ private array $after = []; private function __construct() {} /** * @param string $rest_method Verb sent via data-method (POST, PUT, PATCH…). * @param string $success_msg Message RsvAdminForm shows on success. */ public static function create( string $id, string $action, string $rest_method = 'POST', string $success_msg = '' ): static { $builder = new static(); $builder->form_id = $id; $builder->action = $action; $builder->rest_method = $rest_method; $builder->success_msg = $success_msg; return $builder; } /** Heading shown inside the card, above the fields. */ public function heading(string $text): static { $this->heading = $text; return $this; } // ------------------------------------------------------------------------- // Input fields — each becomes a in the table // ------------------------------------------------------------------------- public function text( string $id, string $label, string $desc = '', bool $required = false, string $value = '' ): static { $req = $required ? 'required' : ''; $ctrl = ''; return $this->row($id, $label, $ctrl, $desc); } public function email( string $id, string $label, string $desc = '', bool $required = false, string $value = '', ?string $list_id = null ): static { $req = $required ? 'required' : ''; $list = $list_id !== null ? 'list="' . esc_attr($list_id) . '"' : ''; $ctrl = ''; return $this->row($id, $label, $ctrl, $desc); } public function password( string $id, string $label, string $desc = '', bool $required = false, string $placeholder = '' ): static { $req = $required ? 'required' : ''; $ph = $placeholder !== '' ? 'placeholder="' . esc_attr($placeholder) . '"' : ''; $ctrl = ''; return $this->row($id, $label, $ctrl, $desc); } public function number( string $id, string $label, string $desc = '', bool $required = false, string|int $value = '', ?int $min = null, ?int $max = null ): static { $req = $required ? 'required' : ''; $min_attr = $min !== null ? 'min="' . $min . '"' : ''; $max_attr = $max !== null ? 'max="' . $max . '"' : ''; $ctrl = ''; return $this->row($id, $label, $ctrl, $desc); } public function date( string $id, string $label, string $desc = '', bool $required = false, string $value = '' ): static { $req = $required ? 'required' : ''; $ctrl = ''; return $this->row($id, $label, $ctrl, $desc); } public function time( string $id, string $label, string $desc = '', bool $required = false, string $value = '' ): static { $req = $required ? 'required' : ''; $ctrl = ''; return $this->row($id, $label, $ctrl, $desc); } public function checkbox( string $id, string $label, string $desc = '', bool $checked = false ): static { $c = $checked ? 'checked' : ''; $ctrl = ''; return $this->row($id, $label, $ctrl, $desc); } /** * @param array $options Associative: value => display text. */ public function select( string $id, string $label, array $options, string $desc = '', bool $required = false, string $selected = '' ): static { $req = $required ? 'required' : ''; $opts = $this->build_options($options, $selected); $ctrl = '' . $opts . ''; return $this->row($id, $label, $ctrl, $desc); } public function textarea( string $id, string $label, string $desc = '', bool $required = false, string $value = '', int $rows = 5 ): static { $req = $required ? 'required' : ''; $ctrl = '' . esc_textarea($value) . ''; return $this->row($id, $label, $ctrl, $desc); } /** * Syntax-highlighted editor backed by WordPress' bundled CodeMirror. * * Serializes exactly like {@see textarea()} — the underlying * stays the source of truth. * * @param string $mode MIME type for highlighting, e.g. 'text/html'. */ public function code( string $id, string $label, string $desc = '', string $value = '', string $mode = 'text/html', int $rows = 8 ): static { $ctrl = RsvCodeEditor::render($id, [ 'value' => $value, 'mode' => $mode, 'rows' => $rows, ]); return $this->row($id, $label, $ctrl, $desc); } public function custom(string $label, callable $fn) : static { $this->rows[] = '<tr>' . '<th>' . esc_html($label) . '</th>' . '<td>' . $fn() . '</td>' . '</tr>'; return $this; } /** * Groups multiple inputs into a single row with a shared label. * * The callable receives an RsvFormGroup instance; inputs added to it * are laid out as a flex row inside the row's <td>. * * Example: * ->group('Availability Range', fn($g) => $g * ->time('start_time', 'Start') * ->time('end_time', 'End') * ) */ public function group(string $label, callable $fn): static { $group = RsvFormGroup::create(); $fn($group); $this->rows[] = '<tr>' . '<th>' . esc_html($label) . '</th>' . '<td>' . $group->render() . '</td>' . '</tr>'; return $this; } // ------------------------------------------------------------------------- // Non-field outputs // ------------------------------------------------------------------------- /** Hidden input — no row, emitted before the table. */ public function hidden(string $id, string|int $value): static { $this->before[] = '<input type="hidden" id="' . esc_attr($id) . '" name="' . esc_attr($id) . '" value="' . esc_attr((string) $value) . '">'; return $this; } /** WordPress nonce field, emitted inside the form before the table. */ public function nonce(string $action, string $name): static { $this->before[] = wp_nonce_field($action, $name, true, false); return $this; } /** * <datalist> element for email/text suggestions — emitted before the table. * * @param string[] $values */ public function datalist(string $id, array $values): static { $options = ''; foreach ($values as $v) { $options .= '<option value="' . esc_attr($v) . '">'; } $this->before[] = '<datalist id="' . esc_attr($id) . '">' . $options . '</datalist>'; return $this; } /** * A spanning note row inside the table — useful for contextual hints * between fields, rendered as a full-width <td colspan="2">. */ public function note(string $text): static { $this->rows[] = '<tr><td colspan="2"><p class="description">' . esc_html($text) . '</p></td></tr>'; return $this; } /** * WordPress admin notice — emitted before the table. * * @param string $type One of: success | error | warning | info */ public function notice(string $type, string $message, bool $dismissible = true): static { $classes = 'notice notice-' . esc_attr($type) . ($dismissible ? ' is-dismissible' : ''); $this->notices[] = '<div class="' . $classes . '"><p>' . esc_html($message) . '</p></div>'; return $this; } /** Submit button — emitted after the table as <p class="submit">. */ public function submit(string $label, string $css_class = 'button-primary', string $name = ''): static { $name_attr = $name !== '' ? 'name="' . esc_attr($name) . '"' : ''; $this->after[] = '<p class="submit"><button type="submit" class="button ' . esc_attr($css_class) . '" ' . $name_attr . '>' . esc_html($label) . '</button></p>'; return $this; } // ------------------------------------------------------------------------- // Rendering // ------------------------------------------------------------------------- public function render(): string { $inner = implode('', $this->before); if (!empty($this->rows)) { $inner .= '<table class="form-table"><tbody>' . implode('', $this->rows) . '</tbody></table>'; } $inner .= implode('', $this->after); $success = $this->success_msg !== '' ? ' data-success-msg="' . esc_attr($this->success_msg) . '"' : ''; $form = '<form id="' . esc_attr($this->form_id) . '"' . ' action="' . esc_url($this->action) . '"' . ' method="post"' . ' data-method="' . esc_attr($this->rest_method) . '"' . $success . '>' . $inner . '</form>'; $heading = $this->heading !== '' ? '<h2>' . esc_html($this->heading) . '</h2>' : ''; return implode('', $this->notices) . '<div class="form-wrap">' . $heading . $form . '</div>'; } public function output(): void { echo $this->render(); } // ------------------------------------------------------------------------- // Private helpers // ------------------------------------------------------------------------- private function row(string $id, string $label, string $control_html, string $desc): static { $d = $desc !== '' ? '<p class="description">' . esc_html($desc) . '</p>' : ''; $this->rows[] = '<tr>' . '<th><label for="' . esc_attr($id) . '">' . esc_html($label) . '</label></th>' . '<td>' . $control_html . $d . '</td>' . '</tr>'; return $this; } /** * @param array<string|int, string> $options */ private function build_options(array $options, string $selected): string { $html = ''; foreach ($options as $value => $text) { $is_selected = (string) $value === $selected ? 'selected' : ''; $html .= '<option value="' . esc_attr((string) $value) . '" ' . $is_selected . '>' . esc_html($text) . '</option>'; } return $html; } }