<?php

declare(strict_types=1);

$moduleGuide = [
    'id' => 'pagesGuideModal',
    'eyebrow' => 'Generated experiences handbook',
    'title' => 'Pages guide',
    'subtitle' => 'Choose record workflows, configure each page type, add click actions and conditional formatting, and define safe list-page capabilities.',
    'icon' => 'window-stack',
    'default' => 'start',
    'topics' => [
        [
            'id' => 'start',
            'label' => 'Start here',
            'icon' => 'compass',
            'keywords' => 'beginner overview table pages build autosave workflow',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">All levels</span><h3>Choose what users can do with each table</h3><p>Pages turns a data source into generated experiences such as List, Add, Edit, View, Print, Export, Import, PDF, and Cards.</p></div>
                <div class="pp-guide-grid">
                    <article class="pp-guide-card"><span class="pp-guide-step">1</span><h4>Select a table</h4><p>The right canvas displays that table's page configuration.</p></article>
                    <article class="pp-guide-card"><span class="pp-guide-step">2</span><h4>Enable page types</h4><p>Use the check on each colorful page card.</p></article>
                    <article class="pp-guide-card"><span class="pp-guide-step">3</span><h4>Open settings</h4><p>Use the sliders icon on supported cards for page-specific behavior.</p></article>
                    <article class="pp-guide-card"><span class="pp-guide-step">4</span><h4>Confirm identity</h4><p>Configure key columns so record-specific actions target the correct row.</p></article>
                </div>
                <div class="pp-guide-callout"><i class="bi bi-cloud-check"></i><div>Changes save automatically. Rebuild to apply them to the generated application.</div></div>
            HTML,
        ],
        [
            'id' => 'types',
            'label' => 'Page types',
            'icon' => 'collection',
            'keywords' => 'list add edit view print export import pdf cards types purpose',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Beginner</span><h3>Enable only the experiences the application needs</h3><p>Each page adds capability and an authorization surface. Keep the generated app focused.</p></div>
                <div class="pp-guide-table-wrap"><table class="pp-guide-table"><thead><tr><th>Page</th><th>Purpose</th><th>Design note</th></tr></thead><tbody>
                    <tr><td>List</td><td>Browse, search, filter, and act on many records.</td><td>Keep summary columns compact.</td></tr>
                    <tr><td>Add</td><td>Create a new record.</td><td>Expose only user-settable fields.</td></tr>
                    <tr><td>Edit</td><td>Update an existing record.</td><td>Requires reliable record identity and permission.</td></tr>
                    <tr><td>View</td><td>Read a complete record.</td><td>Use for detail that would overcrowd List.</td></tr>
                    <tr><td>Print</td><td>Produce a printer-oriented layout.</td><td>Remove interactive-only elements.</td></tr>
                    <tr><td>Export</td><td>A screen to pick rows, columns and format — plus one-click downloads from the list's <strong>Data</strong> menu.</td><td>Review sensitive fields and volume; untick formats you do not want offered.</td></tr>
                    <tr><td>Import</td><td>A wizard: paste rows or upload a file, map columns, preview, then insert / skip / update.</td><td>Validate types, required fields, and conflicts before committing.</td></tr>
                    <tr><td>PDF</td><td>Generate a portable document.</td><td>Verify pagination, fonts, and confidential data.</td></tr>
                    <tr><td>Cards</td><td>Browse records in a visual card layout.</td><td>Select a small, meaningful field set.</td></tr>
                </tbody></table></div>
            HTML,
        ],
        [
            'id' => 'identity',
            'label' => 'Record identity',
            'icon' => 'key',
            'keywords' => 'key primary composite record identity configure edit view delete export unique',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Intermediate</span><h3>Tell record pages how to address one row</h3><p>View, Edit, Delete, relationships, and other record actions need a stable key. The Record identity section shows or configures the columns used.</p></div>
                <h4>Good keys are</h4>
                <ul class="pp-guide-list"><li><strong>Unique:</strong> one value (or composite combination) identifies one record.</li><li><strong>Stable:</strong> it does not casually change during normal editing.</li><li><strong>Present:</strong> required actions can receive it in routes or requests.</li><li><strong>Protected:</strong> authorization still verifies whether the current user may access that record.</li></ul>
                <div class="pp-guide-callout warning"><i class="bi bi-shield-exclamation"></i><div>A record ID is not permission. Generated endpoints must still enforce role, ownership, and row-level rules.</div></div>
            HTML,
        ],
        [
            'id' => 'settings',
            'label' => 'Page settings',
            'icon' => 'sliders',
            'keywords' => 'modal popup settings list add edit view print export import pdf click actions options scroll fixed header reorder columns resize resizable pin freeze frozen sticky saved views presets group grouping subtotal totals kanban board drag card status after saved discard unsaved sweetalert data menu transfer csv xlsx excel workbook word json xml delimiter paste upload mapping preview scope selected filtered formats readers quick download header row security 403',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Beginner → advanced</span><h3>Refine each enabled experience</h3><p>Open a page card's settings to configure options specific to that page. Available controls vary by page type.</p></div>
                <div class="pp-guide-grid">
                    <article class="pp-guide-card"><h4>List</h4><p>End-user table behaviors (each remembered per browser): <strong>Scroll table data</strong> keeps the header fixed while rows scroll; <strong>Allow reordering of fields</strong> lets users drag column headers to reorder; <strong>Resizeable columns</strong> adds a drag handle on each header; <strong>Freeze / pin columns</strong> adds a pin toggle to each header so a column stays put while the rest scroll; and <strong>Click Actions</strong> (below) respond to row/cell clicks.</p></article>
                    <article class="pp-guide-card"><h4>Views, grouping &amp; board</h4><p><strong>Saved views</strong> lets users store named presets of search + sort + filters + columns and switch between them (a Views menu appears in the toolbar). <strong>Group rows by a column</strong> folds the list into collapsible sections with per-group counts and subtotals (subtotals reuse the columns you set as footer aggregates). <strong>Board (Kanban)</strong> adds a board view that groups records into columns by a chosen field — drag a card between columns to change that field.</p></article>
                    <article class="pp-guide-card"><h4>Add / Edit</h4><p><strong>Show in popup</strong> opens the form in an in-app modal instead of a full page. <strong>After the record is saved</strong> choose where to go — back to the list, stay to add/edit another, or open the new record's Edit or View page. <strong>Just close in popup mode</strong> simply closes the modal and refreshes the list.</p></article>
                    <article class="pp-guide-card"><h4>View / Print / PDF</h4><p>Read-only presentation. <strong>View → Show in popup</strong> opens the record in the same modal (Back closes it, Prev/Next stay inside, Edit steps out); <strong>Hide empty fields</strong> trims blanks. Print/PDF drive output layout.</p></article>
                    <article class="pp-guide-card"><h4>Export</h4><p>Tick the <strong>formats</strong> this table may be downloaded in (CSV, Excel Workbook, Word, JSON, XML) and whether to <strong>include the header row</strong>. Clearing every format <em>disables export</em> — the endpoint is not generated at all.</p></article>
                    <article class="pp-guide-card"><h4>Import</h4><p>Choose accepted <strong>sources</strong> (delimited text, Excel Workbook, JSON, XML), the default <strong>delimiter</strong>, allowed <strong>modes</strong>, max upload size, and whether Copy/Paste and file upload are offered. Clearing every source disables import.</p></article>
                </div>
                <h4>The Data menu</h4>
                <p>On the generated list, these two pages are reached from the toolbar's <strong>Data</strong> menu:</p>
                <ul class="pp-guide-list">
                    <li><strong>Export records…</strong> — a screen to choose which rows (selected / filtered / current page / all), which columns, and the format.</li>
                    <li><strong>Import records…</strong> — a four-step wizard: Source → Mapping → Preview → Import.</li>
                    <li><strong>Quick download</strong> — one click straight to a file in any enabled format, no screen in between.</li>
                </ul>
                <p>Tick rows on the list first and every Data link carries that selection, so the Export screen opens with <em>Selected records</em> already chosen.</p>
                <div class="pp-guide-callout"><i class="bi bi-shield-lock"></i><div><strong>These settings are a security boundary, not just menu dressing.</strong> A format you untick is rejected server-side (403) even if someone types the URL by hand, and a disabled page is never generated. The same applies to Print, which follows its own page type.</div></div>
                <h4>Click actions (List)</h4>
                <p>A click action connects a click on a <em>row</em> or a specific <em>field cell</em> to a response. Every action also chooses a <strong>trigger</strong> (single or double click), may ask for <strong>confirmation</strong> first, and can be limited by an <strong>“Only run when”</strong> condition over the row (for example <code>data.status === 'pending'</code>).</p>
                <ul class="pp-guide-list">
                    <li><strong>Open page</strong> — go to the record's View, Edit, Add, Print, or Export page — current window, popup, or new tab. Only pages this table generates are offered, so a click can never land on a disabled endpoint. Ctrl/⌘-click always opens a new tab.</li>
                    <li><strong>Open URL</strong> — navigate to any address with <code>{column}</code> and <code>{id}</code> tokens filled from the row, e.g. <code>/reports/{id}?ref={code}</code> or <code>https://maps.google.com/?q={city}</code> (values are URL-encoded; <code>javascript:</code> links are rejected).</li>
                    <li><strong>Select record</strong> — toggle the row's checkbox (handy for bulk actions).</li>
                    <li><strong>Expand / collapse details</strong> — reveal the row's Master–Detail section.</li>
                    <li><strong>Execute code</strong> — a three-stage flow: <strong>Client Before</strong> (JavaScript) → <strong>Server</strong> (PHP, run on a CSRF-guarded endpoint with the <code>dbAll / dbRow / dbValue / dbExecute</code> helpers in scope) → <strong>Client After</strong> (JavaScript). The Server half never reaches the browser and can return results the list applies for you — <code>$result['notify']</code> (toast), <code>$result['redirect']</code>, <code>$result['setCell']</code>, or <code>$result['refresh'] = 'row' | 'grid'</code>.</li>
                </ul>
                <p>A field-specific action wins over a row action on the same click. Whole-row actions are keyboard-accessible (Enter activates), and a row never hijacks clicks on inner links, buttons, or a text selection.</p>
                <div class="pp-guide-callout"><i class="bi bi-lightbulb"></i><div><strong>Example — approve on double-click, only when pending.</strong> Trigger <em>double click</em>; Only run when <code>data.status === 'pending'</code>; Confirm “Approve this application?”; Server <code>$result['notify'] = ['message' =&gt; 'Approved', 'type' =&gt; 'success']; $result['refresh'] = 'row';</code></div></div>
                <div class="pp-guide-callout"><i class="bi bi-shield-check"></i><div>Popup forms guard unsaved work: a discard prompt (SweetAlert2) appears if you dismiss a changed form; a clean form closes instantly. Full pages keep a last-resort browser warning only when you close the tab with unsaved edits.</div></div>
                <div class="pp-guide-callout"><i class="bi bi-mouse"></i><div>Hover over page cards and settings controls for contextual tooltips; they explain the immediate action without replacing this fuller guide.</div></div>
            HTML,
        ],
        [
            'id' => 'formatting',
            'label' => 'Conditional formatting',
            'icon' => 'palette',
            'keywords' => 'conditional formatting colour color highlight row cell rule badge icon style background bold italic border class status traffic light overdue approved compare field and or',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Intermediate</span><h3>Colour rows and cells by their data — no code</h3><p>Select the <strong>Data Grid</strong> on the List canvas and open <strong>Conditional formatting</strong> to paint a whole row or a single cell whenever a record matches a rule.</p></div>
                <h4>What a rule contains</h4>
                <ul class="pp-guide-list">
                    <li><strong>Apply to</strong> a <em>row</em> or one <em>cell</em> (choose the column).</li>
                    <li><strong>Conditions</strong> — one or more <code>field · operator · value</code> tests, combined with <strong>all</strong> (AND) or <strong>any</strong> (OR). Operators include <code>=</code>, <code>≠</code>, <code>&gt;</code>, <code>&lt;</code>, <code>contains</code>, <code>empty</code>. A value can be a literal <em>or another field</em> — e.g. flag rows where <code>actual &gt; budget</code>.</li>
                    <li><strong>Style</strong> — background, text colour, bold, italic, a border, an optional theme CSS class, and (for cells) a <strong>badge</strong> pill or a leading <strong>icon</strong>.</li>
                </ul>
                <div class="pp-guide-callout"><i class="bi bi-palette"></i><div><strong>Example — traffic-light a status.</strong> A cell rule on <code>status</code>: when <code>status = overdue</code> → red badge; a second rule when <code>status = approved</code> → green badge with a check icon. Or highlight the whole row when <code>priority = high</code> <strong>and</strong> <code>owner is empty</code>.</div></div>
                <p>Rules are evaluated on the server as each row renders, so colours are correct on the first paint (and in a PDF built from the View). A single value is matched <em>exactly</em>, so “Male” never accidentally matches “Female”.</p>
                <div class="pp-guide-callout"><i class="bi bi-info-circle"></i><div>Conditional formatting styles the row/cell container. For logic beyond the rule builder, a field's <strong>Server → Format</strong> event (its View control) can return fully custom HTML for that cell's <em>content</em>.</div></div>
            HTML,
        ],
        [
            'id' => 'listux',
            'label' => 'Using the list',
            'icon' => 'table',
            'keywords' => 'select all matching bulk delete update export filtered set shift click range keyboard navigation arrow copy clipboard tsv shareable url link view state density hidden columns filter preserved sort page size row numbers header filter accessibility live region',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Everyday use</span><h3>What end users can do on a generated list</h3><p>These behaviours ship automatically with every List page — worth knowing so you can describe them to your users.</p></div>
                <div class="pp-guide-grid">
                    <article class="pp-guide-card"><h4>Filters stay put</h4><p>Sorting a column, paging, or changing the page size keeps the active search, column filters, and where-tab — the list never silently un-filters. Because that whole state lives in the address bar, any such link is shareable as-is.</p></article>
                    <article class="pp-guide-card"><h4>Select all matching</h4><p>Tick the header checkbox and, when more rows match than the page shows, a <strong>“Select all N matching this filter”</strong> banner appears. Bulk <strong>Delete / Update / Export</strong> then act on the entire filtered set — still row-level-security scoped — not just the visible page.</p></article>
                    <article class="pp-guide-card"><h4>Fast selection &amp; copy</h4><p><strong>Shift-click</strong> a checkbox selects a range; <strong>↑ / ↓ / Home / End</strong> move between rows and <strong>Space</strong> toggles selection; <strong>Copy</strong> puts the selected rows on the clipboard as tab-separated values, ready to paste into a spreadsheet.</p></article>
                    <article class="pp-guide-card"><h4>Shareable views</h4><p>Column order, width, pins, density, hidden columns, and the table/cards/board mode are remembered per browser <em>and</em> mirrored into the URL. <strong>Columns → Copy link to this view</strong> hands a teammate a link that reproduces exactly what you arranged.</p></article>
                </div>
                <div class="pp-guide-callout"><i class="bi bi-universal-access"></i><div>The grid is keyboard- and screen-reader-friendly: sortable headers announce sort state (<code>aria-sort</code>), the record count and selection count are live regions, the table carries a caption, and heavy icon fonts are dropped from pages that don't use them.</div></div>
            HTML,
        ],
        [
            'id' => 'capabilities',
            'label' => 'List capabilities',
            'icon' => 'lightning-charge',
            'keywords' => 'spreadsheet update selected inline edit inline add delete records copy records bulk capability',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Intermediate</span><h3>Add efficient workflows without overloading the list</h3><p>Capabilities are convenient, but each one changes how users can write or move data.</p></div>
                <div class="pp-guide-table-wrap"><table class="pp-guide-table"><thead><tr><th>Capability</th><th>Best for</th><th>Safety check</th></tr></thead><tbody>
                    <tr><td>Spreadsheet mode</td><td>High-volume grid-style editing.</td><td>Validation, concurrency, and accidental bulk changes.</td></tr>
                    <tr><td>Update selected</td><td>Applying one change to chosen records — or, with “Select all matching”, the whole filtered set.</td><td>Every record is re-checked under row-level security before it is written.</td></tr>
                    <tr><td>Inline edit</td><td>Fast changes without leaving List.</td><td>Make save/cancel/error states unmistakable.</td></tr>
                    <tr><td>Inline add</td><td>Quick creation in context.</td><td>Required fields and defaults must fit the compact flow.</td></tr>
                    <tr><td>Delete records</td><td>Authorized removal from List.</td><td>Confirmation, dependency rules, audit, and restore policy.</td></tr>
                    <tr><td>Copy records</td><td>Starting from an existing record.</td><td>Reset unique IDs, timestamps, ownership, and secrets.</td></tr>
                </tbody></table></div>
            HTML,
        ],
        [
            'id' => 'workflow',
            'label' => 'Cross-module workflow',
            'icon' => 'diagram-3',
            'keywords' => 'workflow fields designer security misc relationships build test',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Intermediate → advanced</span><h3>Pages defines capability; other modules complete it</h3></div>
                <ol class="pp-guide-list numbered">
                    <li><strong>Tables:</strong> define fields, keys, views, and relationships.</li>
                    <li><strong>Pages:</strong> enable the necessary record workflows.</li>
                    <li><strong>Fields:</strong> choose field visibility per page and device.</li>
                    <li><strong>Security:</strong> authorize roles, actions, and data scope.</li>
                    <li><strong>Designer:</strong> compose the visual page layout.</li>
                    <li><strong>Events:</strong> add lifecycle logic only where declarative settings are insufficient.</li>
                    <li><strong>Build:</strong> generate and test the final PHP application.</li>
                </ol>
                <div class="pp-guide-callout warning"><i class="bi bi-lock"></i><div>Disabling a page reduces exposed UI, but enabled pages and APIs still require server-side authorization.</div></div>
            HTML,
        ],
        [
            'id' => 'checklist',
            'label' => 'Review checklist',
            'icon' => 'check2-square',
            'keywords' => 'checklist test release responsive permissions keys',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Release readiness</span><h3>Validate every enabled page</h3></div>
                <div class="pp-guide-checklist">
                    <label><input type="checkbox"> Every enabled page supports a real user task.</label>
                    <label><input type="checkbox"> Record identity is unique and stable.</label>
                    <label><input type="checkbox"> Field visibility is reviewed in Fields.</label>
                    <label><input type="checkbox"> Roles cannot open or submit unauthorized actions.</label>
                    <label><input type="checkbox"> Import/export/delete/copy behavior is safely constrained.</label>
                    <label><input type="checkbox"> List capabilities work with validation and concurrent users.</label>
                    <label><input type="checkbox"> Generated pages were tested on desktop and mobile.</label>
                </div>
            HTML,
        ],
    ],
];

include constant('BASE_PATH') . '/core/views/module-guide.php';
