class.QuickButtonsBuilders.php

<?php
/**
 * Quick Buttons Plugin — Pure helper class for Map view source generators.
 *
 * Extracted from QuickButtonsAjax in v8.3.0 so the self-contained test suite
 * can exercise the builders without bootstrapping osTicket.
 *
 * Depends only on two global functions that callers must define:
 *   - qb_resolve_label($value, $locale)  → string
 *   - qb__($msgid)                       → string  (only used implicitly via callers)
 *
 * No `require_once` of osTicket internals. All inputs are arrays + scalars.
 *
 * @author  ChesnoTech
 * @version 8.3.0
 * @link    https://github.com/ChesnoTech/ost-quick-buttons
 */

class QuickButtonsBuilders {

    /**
     * v8.0.0: Build Mermaid flowchart source for an instance.
     *
     * v8.1.0: emits synthetic `STP_<dept>_<idx>` step pills + `click <id>
     * qbMapClick "<encoded-path>"` directives + `class D<id> qbDept`
     * subgraph annotations. Path encoding scheme:
     *   STATUS|<sid>
     *   STEP|<dept>|<idx>
     *   TYPE|<dept>|<idx>|<tIdx>
     *   VARIANT|<dept>|<idx>|<tIdx>|<vIdx>
     *
     * @param  array  $widget       Parsed widget_config (see parseWidgetConfig).
     * @param  array  $deptNames    Map of (string)$deptId => $deptName.
     * @param  array  $statusNames  Map of (string)$statusId => $statusName.
     * @param  string $locale       Agent locale for translatable label resolution.
     * @return string               Mermaid `flowchart LR` source.
     */
    public static function buildMermaidFlow($widget, $deptNames, $statusNames, $locale) {
        $lines = array();
        $lines[] = 'flowchart LR';
        $lines[] = '  classDef status fill:#e8d5ff,stroke:#7b3fbf,color:#222';
        $lines[] = '  classDef pause fill:#ff9595,stroke:#c0392b,color:#222';
        $lines[] = '  classDef rejection fill:#ff5555,stroke:#7c1717,color:#fff';
        $lines[] = '  classDef variant fill:#fff5d4,stroke:#bf8f10,color:#222';
        $lines[] = '  classDef terminal fill:#aaffaa,stroke:#2a8a2a,color:#222';
        // v8.1.0 — synthetic step pill + dept cluster class
        $lines[] = '  classDef step fill:#fff,stroke:#888,color:#222,stroke-dasharray: 3 2';
        $lines[] = '  classDef qbDept fill:transparent';

        $statusUsed = array();
        $variantSeq = 0;
        $typeSeq = 0;

        foreach (($widget['departments'] ?? array()) as $deptId => $dept) {
            if (empty($dept['enabled'])) continue;
            $deptName = $deptNames[(string)$deptId] ?? ('Dept ' . $deptId);
            $deptName = self::mermaidEscape($deptName);
            $lines[] = '  subgraph D' . $deptId . ' ["' . $deptName . '"]';
            $lines[] = '    direction TB';

            foreach (($dept['steps'] ?? array()) as $stIdx => $step) {
                $trig = (string)($step['trigger_status'] ?? '');
                $tgt  = (string)($step['target_status']  ?? '');
                if ($trig && !isset($statusUsed[$trig])) $statusUsed[$trig] = true;
                if ($tgt  && !isset($statusUsed[$tgt]))  $statusUsed[$tgt]  = true;
                if ($trig && $tgt) {
                    $stepLabel = self::mermaidEscape(qb_resolve_label($step['label'] ?? '', $locale)
                        ?: ucfirst($step['behavior'] ?? 'step'));
                    // v8.1.0 — synthetic step pill so each transition has a clickable node
                    $stepId = 'STP_' . $deptId . '_' . $stIdx;
                    $lines[] = '    ' . $stepId . '["' . $stepLabel . '"]';
                    $lines[] = '    class ' . $stepId . ' step';
                    $lines[] = '    click ' . $stepId . ' qbMapClick "STEP|' . $deptId . '|' . $stIdx . '"';
                    $lines[] = '    S' . $trig . ' --> ' . $stepId;
                    $lines[] = '    ' . $stepId . ' -- "' . $stepLabel . '" --> S' . $tgt;
                }
            }
            $lines[] = '  end';
            // v8.1.0 — cluster class for dept-filter dimming
            $lines[] = '  class D' . $deptId . ' qbDept';
        }

        // Emit status nodes (resolved names) + click directive
        foreach ($statusUsed as $sid => $_) {
            $name = $statusNames[(string)$sid] ?? ('Status ' . $sid);
            $name = self::mermaidEscape($name);
            $lines[] = '  S' . $sid . '(("' . $name . '"))';
            $lines[] = '  class S' . $sid . ' status';
            $lines[] = '  click S' . $sid . ' qbMapClick "STATUS|' . $sid . '"';
        }

        // Interruption variants — dashed bypass edges
        foreach (($widget['departments'] ?? array()) as $deptId => $dept) {
            if (empty($dept['enabled'])) continue;
            foreach (($dept['steps'] ?? array()) as $stIdx => $step) {
                $trig = (string)($step['trigger_status'] ?? '');
                if (!$trig) continue;
                $intCfg = $step['interruptions'] ?? array();
                if (empty($intCfg['enabled'])) continue;
                foreach (($intCfg['types'] ?? array()) as $tIdx => $type) {
                    $kind = ($type['kind'] ?? 'pause') === 'rejection' ? 'rejection' : 'pause';
                    $tNodeId = 'T' . (++$typeSeq);
                    $tLabel = self::mermaidEscape(qb_resolve_label($type['label'] ?? '', $locale));
                    $glyph = $kind === 'rejection' ? '✗' : '⏸';
                    $lines[] = '  ' . $tNodeId . '[/"' . $glyph . ' ' . $tLabel . '"/]';
                    $lines[] = '  class ' . $tNodeId . ' ' . $kind;
                    $lines[] = '  click ' . $tNodeId . ' qbMapClick "TYPE|' . $deptId . '|' . $stIdx . '|' . $tIdx . '"';
                    $lines[] = '  S' . $trig . ' -.-> ' . $tNodeId;
                    foreach (($type['variants'] ?? array()) as $vIdx => $variant) {
                        $vNodeId = 'V' . (++$variantSeq);
                        $vLabel = self::mermaidEscape(qb_resolve_label($variant['label'] ?? '', $locale));
                        $lines[] = '  ' . $vNodeId . '["' . $vLabel . '"]';
                        $lines[] = '  class ' . $vNodeId . ' variant';
                        $lines[] = '  click ' . $vNodeId . ' qbMapClick "VARIANT|' . $deptId . '|' . $stIdx . '|' . $tIdx . '|' . $vIdx . '"';
                        $lines[] = '  ' . $tNodeId . ' --> ' . $vNodeId;
                        $vTgt = (string)($variant['target_status'] ?? '');
                        if ($vTgt) {
                            if (!isset($statusUsed[$vTgt])) {
                                $name = $statusNames[(string)$vTgt] ?? ('Status ' . $vTgt);
                                $name = self::mermaidEscape($name);
                                $lines[] = '  S' . $vTgt . '(("' . $name . '"))';
                                $lines[] = '  class S' . $vTgt . ' status';
                                $lines[] = '  click S' . $vTgt . ' qbMapClick "STATUS|' . $vTgt . '"';
                                $statusUsed[$vTgt] = true;
                            }
                            $lines[] = '  ' . $vNodeId . ' --> S' . $vTgt;
                        }
                    }
                }
            }
        }

        return implode("\n", $lines);
    }

    /**
     * v8.0.0: Build exhaustive Markmap-compatible markdown for the Mind view.
     * Every config option becomes a leaf — full audit trail.
     *
     * v8.1.0: leaves wrapped in `<span class="qbmm-leaf" data-edit-target="...">`
     * for click-to-inspect via Markmap's foreignObject HTML rendering.
     */
    public static function buildMarkmapMind($widget, $deptNames, $statusNames, $locale, $instanceName) {
        $out = array();
        $out[] = '# ' . htmlspecialchars($instanceName, ENT_QUOTES, 'UTF-8');
        foreach (($widget['departments'] ?? array()) as $deptId => $dept) {
            $deptName = $deptNames[(string)$deptId] ?? ('Dept ' . $deptId);
            $deptName = htmlspecialchars($deptName, ENT_QUOTES, 'UTF-8');
            $enabled = !empty($dept['enabled']) ? 'ENABLED' : 'DISABLED';
            $out[] = '';
            // v8.1.0 — wrap dept heading in clickable span (DEPT click reserved for future)
            $out[] = '## <span class="qbmm-leaf" data-edit-target="DEPT|' . $deptId . '">' . $deptName . ' (id ' . $deptId . ') ' . $enabled . '</span>';
            $out[] = '- Schema: v' . htmlspecialchars((string)($dept['schema_version'] ?? '?'), ENT_QUOTES, 'UTF-8');
            $out[] = '- Steps: ' . count($dept['steps'] ?? array());
            foreach (($dept['steps'] ?? array()) as $stIdx => $step) {
                $stNum = $stIdx + 1;
                $out[] = '';
                // v8.1.0 — step heading wrapped for click → inspector
                $out[] = '### <span class="qbmm-leaf" data-edit-target="STEP|' . $deptId . '|' . $stIdx . '">Step ' . $stNum . '</span>';
                $trig = (string)($step['trigger_status'] ?? '');
                $tgt  = (string)($step['target_status']  ?? '');
                $out[] = '- Trigger: ' . htmlspecialchars((string)($statusNames[$trig] ?? $trig ?? '—'), ENT_QUOTES, 'UTF-8');
                $out[] = '- Target: ' . htmlspecialchars((string)($statusNames[$tgt] ?? $tgt ?? '—'), ENT_QUOTES, 'UTF-8');
                $out[] = '- Behavior: ' . htmlspecialchars((string)($step['behavior'] ?? 'none'), ENT_QUOTES, 'UTF-8');
                $out[] = '- Transfer: ' . (($step['transfer_dept'] ?? '')
                    ? htmlspecialchars((string)($deptNames[(string)$step['transfer_dept']] ?? $step['transfer_dept']), ENT_QUOTES, 'UTF-8')
                    : 'none');
                $out[] = '- Clear team: ' . (!empty($step['clear_team']) ? 'yes' : 'no');
                $stepLabel = qb_resolve_label($step['label'] ?? '', $locale);
                if ($stepLabel !== '') $out[] = '- Label: ' . htmlspecialchars($stepLabel, ENT_QUOTES, 'UTF-8');
                if (!empty($step['icon'])) $out[] = '- Icon: ' . htmlspecialchars((string)$step['icon'], ENT_QUOTES, 'UTF-8');
                $pmode = $step['perf_mode'] ?? 'off';
                if ($pmode !== 'off') {
                    $out[] = '- Performance';
                    $out[] = '  - Mode: ' . htmlspecialchars((string)$pmode, ENT_QUOTES, 'UTF-8');
                    if ($pmode === 'fixed')
                        $out[] = '  - Value: ' . htmlspecialchars((string)($step['perf_value'] ?? '0'), ENT_QUOTES, 'UTF-8');
                }
                $ac = $step['access_control'] ?? array();
                $acMode = $ac['mode'] ?? 'workflow';
                if ($acMode !== 'workflow') {
                    $out[] = '- ACL';
                    $out[] = '  - Mode: ' . htmlspecialchars((string)$acMode, ENT_QUOTES, 'UTF-8');
                    $r = $ac['restrict_to'] ?? array();
                    if (!empty($r['agents'])) $out[] = '  - Agents: ' . count($r['agents']);
                    if (!empty($r['teams']))  $out[] = '  - Teams: '  . count($r['teams']);
                    if (!empty($r['roles']))  $out[] = '  - Roles: '  . count($r['roles']);
                }
                $intCfg = $step['interruptions'] ?? array();
                if (!empty($intCfg['enabled']) && !empty($intCfg['types'])) {
                    $out[] = '- Interruption Button';
                    $intLabel = qb_resolve_label($intCfg['label'] ?? '', $locale);
                    if ($intLabel !== '') $out[] = '  - Label: ' . htmlspecialchars($intLabel, ENT_QUOTES, 'UTF-8');
                    foreach ($intCfg['types'] as $tIdx => $type) {
                        $tLabel = qb_resolve_label($type['label'] ?? '', $locale);
                        $kind = ($type['kind'] ?? 'pause');
                        // v8.1.0 — type bullet wrapped for click
                        $out[] = '  - <span class="qbmm-leaf" data-edit-target="TYPE|' . $deptId . '|' . $stIdx . '|' . $tIdx . '">Type ' . ($tIdx + 1) . ': ' . htmlspecialchars($tLabel, ENT_QUOTES, 'UTF-8') . ' (' . htmlspecialchars($kind, ENT_QUOTES, 'UTF-8') . ')</span>';
                        foreach (($type['variants'] ?? array()) as $vIdx => $variant) {
                            $vLabel = qb_resolve_label($variant['label'] ?? '', $locale);
                            // v8.1.0 — variant bullet wrapped for click
                            $out[] = '    - <span class="qbmm-leaf" data-edit-target="VARIANT|' . $deptId . '|' . $stIdx . '|' . $tIdx . '|' . $vIdx . '">Variant ' . ($vIdx + 1) . ': ' . htmlspecialchars($vLabel, ENT_QUOTES, 'UTF-8') . '</span>';
                            $vTgt = (string)($variant['target_status'] ?? '');
                            if ($vTgt) $out[] = '      - Target: ' . htmlspecialchars((string)($statusNames[$vTgt] ?? $vTgt), ENT_QUOTES, 'UTF-8');
                            if (!empty($variant['behavior'])) $out[] = '      - Behavior: ' . htmlspecialchars((string)$variant['behavior'], ENT_QUOTES, 'UTF-8');
                            if (!empty($variant['assignment'])) $out[] = '      - Assignment: ' . htmlspecialchars((string)$variant['assignment'], ENT_QUOTES, 'UTF-8');
                            if (!empty($variant['transfer_dept']))
                                $out[] = '      - Transfer: ' . htmlspecialchars((string)($deptNames[(string)$variant['transfer_dept']] ?? $variant['transfer_dept']), ENT_QUOTES, 'UTF-8');
                            if (!empty($variant['sub_list']) && !empty($variant['sub_list']['source_field_id'])) {
                                $sl = $variant['sub_list'];
                                $out[] = '      - Sub-list (reasons)';
                                $out[] = '        - Source field: ' . htmlspecialchars((string)$sl['source_field_id'], ENT_QUOTES, 'UTF-8');
                                if (!empty($sl['allow_other'])) $out[] = '        - Allow other: yes';
                            }
                        }
                    }
                }
            }
        }
        return implode("\n", $out);
    }

    /**
     * Strip control chars + escape double quotes for safe Mermaid string literals.
     */
    public static function mermaidEscape($s) {
        $s = preg_replace('/[\x00-\x1F]/', ' ', (string)$s);
        return str_replace(array('"', '\\'), array('&quot;', '\\\\'), $s);
    }
}