<?php

declare(strict_types=1);

$moduleGuide = [
    'id' => 'miscGuideModal',
    'eyebrow' => 'Project behavior handbook',
    'title' => 'Misc settings guide',
    'subtitle' => 'Configure project-wide behavior, operational safeguards, delivery services, and application language.',
    'icon' => 'sliders2',
    'default' => 'start',
    'topics' => [
        [
            'id' => 'start',
            'label' => 'Start here',
            'icon' => 'compass',
            'keywords' => 'beginner overview autosave generated application project settings workflow',
            'body' => <<<'HTML'
                <div class="pp-guide-hero">
                    <span class="pp-guide-level">All levels</span>
                    <h3>Settings that shape the whole generated application</h3>
                    <p>Misc is the control room for behavior that does not belong to one page or field: locale, error handling, accessibility, email/SMS delivery, locking, auditing, labels, and more.</p>
                </div>
                <div class="pp-guide-callout"><i class="bi bi-cloud-check"></i><div><strong>Changes save automatically.</strong> Finish related settings together, then build the project so the generated application receives the latest configuration.</div></div>
                <div class="pp-guide-grid">
                    <article class="pp-guide-card"><span class="pp-guide-step">1</span><h4>Set the foundation</h4><p>Choose language, regional format, landing page, error behavior, accessibility, and privacy options.</p></article>
                    <article class="pp-guide-card"><span class="pp-guide-step">2</span><h4>Configure operations</h4><p>Decide how sessions, audit history, record locks, reports, and notifications behave.</p></article>
                    <article class="pp-guide-card"><span class="pp-guide-step">3</span><h4>Connect delivery</h4><p>Set up email and SMS providers, then use the built-in tests before relying on them.</p></article>
                    <article class="pp-guide-card"><span class="pp-guide-step">4</span><h4>Polish language</h4><p>Use Label Editor for page titles, app strings, menus, placeholders, and branding — or enable Live translations to edit them inside the running app.</p></article>
                </div>
                <h4>Know the scope</h4>
                <ul class="pp-guide-list">
                    <li><strong>Project settings</strong> affect the generated application broadly.</li>
                    <li><strong>Table settings</strong> apply only to the table selected in this module.</li>
                    <li><strong>Provider credentials</strong> should be treated as secrets and limited to the permissions the application needs.</li>
                </ul>
            HTML,
        ],
        [
            'id' => 'project',
            'label' => 'Project & regional',
            'icon' => 'globe2',
            'keywords' => 'language locale regional landing page maps errors dark mode gdpr section 508 accessibility',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Beginner → intermediate</span><h3>Make the application feel local and predictable</h3><p>Project settings establish the defaults users encounter throughout the generated app.</p></div>
                <div class="pp-guide-table-wrap"><table class="pp-guide-table"><thead><tr><th>Control</th><th>What it changes</th><th>Practical guidance</th></tr></thead><tbody>
                    <tr><td>Default / available languages</td><td>Initial UI language and languages users may choose.</td><td>Keep only translations you intend to maintain.</td></tr>
                    <tr><td>Show language selector</td><td>Whether the generated app shows a language switcher in its navbar.</td><td>Auto-suggested once a second language exists; turn off to lock the app to one language even with several defined.</td></tr>
                    <tr><td>Live translation editing</td><td>Ships a database-backed Translations editor into the built app.</td><td>Lets administrators translate and add languages in production with no rebuild — see the “Live translations” topic.</td></tr>
                    <tr><td>Regional format</td><td>Date, number, and locale presentation.</td><td>Match the primary audience and verify date inputs after building.</td></tr>
                    <tr><td>Landing page</td><td>First application destination after entry or authentication.</td><td>Choose a stable page available to the intended role.</td></tr>
                    <tr><td>Map provider / key</td><td>Provider used by map-capable controls.</td><td>Restrict API keys by domain and service in the vendor console.</td></tr>
                    <tr><td>Error reporting / message</td><td>Technical diagnostics and the safe message shown to users.</td><td>Use detailed errors in development; hide internals in production.</td></tr>
                    <tr><td>Dark mode</td><td>Generated-app appearance capability.</td><td>This is separate from the builder's own theme selector.</td></tr>
                    <tr><td>GDPR / Section 508</td><td>Privacy and accessibility-oriented behaviors.</td><td>These assist implementation; they do not replace a legal or accessibility review.</td></tr>
                </tbody></table></div>
                <div class="pp-guide-callout warning"><i class="bi bi-exclamation-triangle"></i><div><strong>Production rule:</strong> do not expose stack traces, SQL, filesystem paths, credentials, or personal data in public error messages.</div></div>
            HTML,
        ],
        [
            'id' => 'tables',
            'label' => 'Table defaults',
            'icon' => 'table',
            'keywords' => 'table records per page row highlight search defaults selected table pagination',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Beginner → intermediate</span><h3>Tune everyday record browsing per table</h3><p>Select a table first; the controls in this section affect that table rather than every data source.</p></div>
                <div class="pp-guide-grid">
                    <article class="pp-guide-card"><i class="bi bi-list-ol"></i><h4>Records per page</h4><p>Balance scanning and load time. Start modestly for wide or relationship-heavy tables.</p></article>
                    <article class="pp-guide-card"><i class="bi bi-highlighter"></i><h4>Row highlighting</h4><p>Use visual emphasis to help users track important record states without obscuring readability.</p></article>
                    <article class="pp-guide-card"><i class="bi bi-search"></i><h4>Search defaults</h4><p>Choose sensible initial search behavior for the selected table's typical data.</p></article>
                </div>
                <h4>Recommended workflow</h4>
                <ol class="pp-guide-list numbered"><li>Select the table and confirm its name in the section.</li><li>Set pagination for real expected data volume.</li><li>Coordinate search behavior with the <strong>Fields</strong> module, where individual searchable/filter fields are chosen.</li><li>Build and test list-page performance with representative data.</li></ol>
                <div class="pp-guide-callout"><i class="bi bi-link-45deg"></i><div><strong>Related modules:</strong> Pages enables list capabilities; Fields controls which fields appear and participate in search.</div></div>
            HTML,
        ],
        [
            'id' => 'operations',
            'label' => 'Operations & safety',
            'icon' => 'shield-check',
            'keywords' => 'advanced audit trail record locking timeout session export watermark reports notifications concurrency',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Intermediate → advanced</span><h3>Protect data during real multi-user operation</h3><p>Advanced settings cover traceability, concurrent editing, session duration, reporting, exports, and application notifications.</p></div>
                <div class="pp-guide-table-wrap"><table class="pp-guide-table"><thead><tr><th>Feature</th><th>Use it when…</th><th>Watch for</th></tr></thead><tbody>
                    <tr><td>Audit trail / table</td><td>You need a history of significant data actions.</td><td>Retention, access controls, storage growth, and sensitive values.</td></tr>
                    <tr><td>Record locking / timeout</td><td>Multiple users may edit the same record.</td><td>Locks that are too long block work; locks that are too short may expire mid-edit.</td></tr>
                    <tr><td>Export watermark</td><td>Exports need ownership or confidentiality context.</td><td>A watermark is a deterrent, not access control.</td></tr>
                    <tr><td>Notifications</td><td>Important application events should surface to users/admins.</td><td>Avoid alert fatigue; define actionable recipients and messages.</td></tr>
                </tbody></table></div>
                <div class="pp-guide-callout warning"><i class="bi bi-database-lock"></i><div>Audit and lock tables should be protected as system data. Test cleanup, expiry, permissions, and failure recovery before production.</div></div>
            HTML,
        ],
        [
            'id' => 'delivery',
            'label' => 'Email & SMS',
            'icon' => 'send',
            'keywords' => 'email smtp gmail outlook yahoo sms provider custom test credentials app password tls ssl delivery',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Intermediate</span><h3>Connect transactional delivery safely</h3><p>Email and SMS settings power features such as password recovery, account notices, and application-triggered messages.</p></div>
                <h4>Email setup</h4>
                <ol class="pp-guide-list numbered"><li>Choose a preset provider or custom SMTP.</li><li>Confirm host, port, and encryption with the provider.</li><li>Use an app-specific password or scoped credential where supported.</li><li>Set a recognizable From name/address.</li><li>Send a test and verify delivery, sender alignment, and spam placement.</li></ol>
                <h4>SMS setup</h4>
                <ol class="pp-guide-list numbered"><li>Select the supported provider or custom integration.</li><li>Supply the requested account identifiers, token, and sending identity.</li><li>Use an international test number you control.</li><li>Verify consent, opt-out, sender-registration, and regional requirements.</li></ol>
                <div class="pp-guide-callout warning"><i class="bi bi-key"></i><div><strong>Secrets:</strong> never paste production credentials into labels, custom messages, or client-side code. Rotate exposed credentials immediately.</div></div>
            HTML,
        ],
        [
            'id' => 'labels',
            'label' => 'Labels & branding',
            'icon' => 'translate',
            'keywords' => 'label editor translation page titles table labels placeholders tooltips logo cookie language branding localization',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">All levels</span><h3>Replace technical names with user language</h3><p>Label Editor controls human-facing copy without renaming database objects. Values are stored per language and baked into the app at build time.</p></div>
                <div class="pp-guide-callout"><i class="bi bi-collection"></i><div><strong>Every translatable surface has its own tab.</strong> Pick a language, then edit any tab — each field's built-in English text is shown as the placeholder, and a blank value falls back to it.</div></div>
                <div class="pp-guide-table-wrap"><table class="pp-guide-table"><thead><tr><th>Tab</th><th>What it translates</th></tr></thead><tbody>
                    <tr><td>Page Titles</td><td>The heading at the top of each generated page (List, Add, Edit, View, Print, Export, Import, Cards) per table.</td></tr>
                    <tr><td>Table Labels</td><td>The friendly name each table shows in menus and headings.</td></tr>
                    <tr><td>Field Labels</td><td>The label each column shows on forms and lists.</td></tr>
                    <tr><td>Placeholders / Tooltips</td><td>Input hint text and hover help on forms.</td></tr>
                    <tr><td>App Strings</td><td>The app's built-in interface text — navigation, buttons, dashboard, notifications, account &amp; admin menus. One catalogue covers the whole chrome for any language.</td></tr>
                    <tr><td>Menu</td><td>The sidebar / top-nav item labels (Dashboard, your tables, custom links).</td></tr>
                    <tr><td>Custom Labels / Logo / Cookie</td><td>Your own reusable keys, the header logo, and the cookie-consent banner text.</td></tr>
                </tbody></table></div>
                <h4>Localization checklist</h4>
                <ul class="pp-guide-list"><li>Select the language before editing translated values.</li><li>Use <strong>App Strings</strong> and <strong>Menu</strong> to translate the framework's own buttons and navigation — not just your data labels.</li><li>Keep terminology consistent across List, Add, Edit, Search, and validation messages.</li><li>Avoid embedding data or HTML unless the control explicitly supports it.</li><li>Review long translations at mobile widths and with keyboard navigation.</li><li>Rebuild after editing — Label Editor values are baked in. To change strings <em>without</em> rebuilding, enable Live translations (next topic).</li></ul>
            HTML,
        ],
        [
            'id' => 'translations',
            'label' => 'Live translations',
            'icon' => 'translate',
            'keywords' => 'live translation database production no rebuild in-app editor generate defaults machine translate google add language runtime pp_translations administrator',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Intermediate → advanced</span><h3>Translate and add languages inside the running app</h3><p>Turn on <strong>Project → Live translation editing</strong> to ship a database-backed Translations editor into the generated app. Administrators can then localise every interface string and manage languages <strong>in production, with no rebuild</strong>.</p></div>
                <div class="pp-guide-callout"><i class="bi bi-layers"></i><div><strong>Two complementary layers.</strong> Label Editor (this module) sets the built-in translations that are <em>baked</em> at build time. Live translations add a small database <em>override</em> layer on top — edits there win instantly, and a rebuild never overwrites them.</div></div>
                <h4>How to use it</h4>
                <ol class="pp-guide-list numbered">
                    <li>Define at least two languages, then tick <strong>Live translation editing</strong> in Project settings and build once.</li>
                    <li>In the generated app, open the account menu → <strong>Admin Area → Translations</strong> (administrators only).</li>
                    <li>Pick a language and edit any tab — <strong>App Strings, Menu, Tables, Fields, Page Titles</strong>. Each field saves the moment you leave it; blank reverts to the built-in text.</li>
                    <li>Use <strong>Manage languages</strong> to add, rename, enable/disable, or remove a language. A language added here appears in the app's switcher immediately.</li>
                </ol>
                <div class="pp-guide-grid">
                    <article class="pp-guide-card"><i class="bi bi-magic"></i><h4>Generate defaults</h4><p>One click machine-translates all the empty fields in the current tab using a free online translation service. Existing translations are never touched, and you can overwrite any result.</p></article>
                    <article class="pp-guide-card"><i class="bi bi-shield-lock"></i><h4>Safe by design</h4><p>The editor is limited to administrators and CSRF-protected. The override table is tiny and self-healing — if it is ever unavailable the app simply falls back to the built-in text.</p></article>
                </div>
                <div class="pp-guide-callout warning"><i class="bi bi-globe"></i><div><strong>“Generate defaults” calls an external service.</strong> It sends only interface labels (never your records) to a public translation endpoint, and needs outbound internet from the app server. Machine output is a starting point — review important strings before relying on them.</div></div>
            HTML,
        ],
        [
            'id' => 'checklist',
            'label' => 'Build checklist',
            'icon' => 'check2-square',
            'keywords' => 'checklist troubleshoot build production verify testing',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Release readiness</span><h3>Before you ship</h3><p>Use this compact review whenever Misc settings change.</p></div>
                <div class="pp-guide-checklist">
                    <label><input type="checkbox"> Locale, date formats, and language switching are correct.</label>
                    <label><input type="checkbox"> Production errors reveal no technical internals.</label>
                    <label><input type="checkbox"> Email and SMS tests succeed with production-like credentials.</label>
                    <label><input type="checkbox"> Session timeout and record-lock behavior suit the workflow.</label>
                    <label><input type="checkbox"> Audit/notification recipients and retention are reviewed.</label>
                    <label><input type="checkbox"> Labels, tooltips, privacy copy, and accessibility are reviewed.</label>
                    <label><input type="checkbox"> App Strings and Menu are translated for every offered language (not just data labels).</label>
                    <label><input type="checkbox"> If Live translations is on, the Admin Area → Translations editor works and the app server has outbound internet for “Generate defaults”.</label>
                    <label><input type="checkbox"> The project was rebuilt and tested at desktop and mobile sizes.</label>
                </div>
                <div class="pp-guide-callout"><i class="bi bi-lightbulb"></i><div>If a generated behavior appears unchanged, confirm the setting saved, run a fresh build, and test the newly generated output rather than an older browser tab.</div></div>
            HTML,
        ],
    ],
];

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