<?php

declare(strict_types=1);

$moduleGuide = [
    'id' => 'fieldsGuideModal',
    'eyebrow' => 'Visibility & discovery handbook',
    'title' => 'Fields guide',
    'subtitle' => 'Control where data appears, how device layouts differ, and how users search and filter.',
    'icon' => 'layout-three-columns',
    'default' => 'start',
    'topics' => [
        [
            'id' => 'start',
            'label' => 'Start here',
            'icon' => 'compass',
            'keywords' => 'beginner overview matrix autosave table field page device',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">All levels</span><h3>A visibility matrix for every field</h3><p>Select a table, choose a device profile, then decide which fields participate in each generated page type. Search settings provide a second layer for discovery behavior.</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 matrix immediately switches to that table's fields.</p></article>
                    <article class="pp-guide-card"><span class="pp-guide-step">2</span><h4>Choose a device</h4><p>Desktop, Tablet, and Mobile can expose different field sets.</p></article>
                    <article class="pp-guide-card"><span class="pp-guide-step">3</span><h4>Set page visibility</h4><p>Use cells, a row checkbox, or a column checkbox for efficient changes.</p></article>
                    <article class="pp-guide-card"><span class="pp-guide-step">4</span><h4>Tune search</h4><p>Open the Search pill for field-specific search and filter behavior.</p></article>
                </div>
                <div class="pp-guide-callout"><i class="bi bi-cloud-check"></i><div>Changes save automatically. Build the project afterward to update generated pages.</div></div>
            HTML,
        ],
        [
            'id' => 'matrix',
            'label' => 'Visibility matrix',
            'icon' => 'grid-3x3-gap',
            'keywords' => 'matrix checkbox row column select all visibility list add edit view print export import cards search',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Beginner</span><h3>Read the matrix in two directions</h3><p>Rows are database fields; columns are generated page experiences.</p></div>
                <ul class="pp-guide-list">
                    <li><strong>Single cell:</strong> include or exclude one field on one page type.</li>
                    <li><strong>Field checkbox:</strong> toggle the whole row for the active device.</li>
                    <li><strong>Page header checkbox:</strong> toggle a whole page-type column.</li>
                    <li><strong>Top-left checkbox:</strong> apply a broad selection to the active matrix.</li>
                </ul>
                <div class="pp-guide-table-wrap"><table class="pp-guide-table"><thead><tr><th>Page</th><th>Typical field choice</th></tr></thead><tbody>
                    <tr><td>List / Cards</td><td>High-value summary fields; avoid wide text and sensitive values.</td></tr>
                    <tr><td>Add / Edit</td><td>User-editable values; omit generated IDs, audit timestamps, and protected fields.</td></tr>
                    <tr><td>View / Print / PDF</td><td>Readable detail fields appropriate for the viewer and output.</td></tr>
                    <tr><td>Export</td><td>Only data explicitly appropriate to leave the application.</td></tr>
                    <tr><td>Import</td><td>Fields that can be mapped and safely written.</td></tr>
                    <tr><td>Search</td><td>Fields users reasonably use to locate records.</td></tr>
                </tbody></table></div>
                <div class="pp-guide-callout warning"><i class="bi bi-eye-slash"></i><div>Hiding a field is presentation, not authorization. Enforce sensitive-data access in Security and server-side permissions.</div></div>
            HTML,
        ],
        [
            'id' => 'devices',
            'label' => 'Device profiles',
            'icon' => 'devices',
            'keywords' => 'desktop tablet mobile responsive narrow screen device visibility',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Intermediate</span><h3>Design for available space, not just screen labels</h3><p>The device selector lets you reduce information density on narrower layouts while preserving richer desktop workflows.</p></div>
                <div class="pp-guide-grid">
                    <article class="pp-guide-card"><i class="bi bi-display"></i><h4>Desktop</h4><p>Show the fields needed for comparison and high-throughput work.</p></article>
                    <article class="pp-guide-card"><i class="bi bi-tablet"></i><h4>Tablet</h4><p>Keep primary context and actions; reduce secondary columns.</p></article>
                    <article class="pp-guide-card"><i class="bi bi-phone"></i><h4>Mobile</h4><p>Prioritize identity, status, and the next action. Move detail to View.</p></article>
                </div>
                <h4>Responsive review</h4><ol class="pp-guide-list numbered"><li>Start from the user's task.</li><li>Keep labels and values distinguishable without horizontal scanning.</li><li>Verify Add/Edit forms remain complete enough to submit.</li><li>Test actual generated pages at narrow widths.</li></ol>
            HTML,
        ],
        [
            'id' => 'search',
            'label' => 'Search settings',
            'icon' => 'search',
            'keywords' => 'searchable always search panel advanced all fields filter panel required default option contains equals case sensitive save highlight',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Beginner → advanced</span><h3>Choose how each field participates in discovery</h3><p>Click a field's Search pill to open its settings. A Filter pill indicates that <strong>Show on Filter Panel</strong> is enabled.</p></div>
                <div class="pp-guide-table-wrap"><table class="pp-guide-table"><thead><tr><th>Option</th><th>Meaning</th></tr></thead><tbody>
                    <tr><td>Searchable</td><td>The field may be used by supported search experiences.</td></tr>
                    <tr><td>Always on Search Panel</td><td>Keep the field readily available in the search panel.</td></tr>
                    <tr><td>Show on Advanced Search</td><td>Offer it in the advanced criteria interface.</td></tr>
                    <tr><td>Include in “All Fields” search</td><td>Include the field when a broad multi-field search runs.</td></tr>
                    <tr><td>Show on Filter Panel</td><td>Expose the field as a user-facing filter and show the Filter indicator.</td></tr>
                    <tr><td>Required Search Field</td><td>Require a value for supported search flows.</td></tr>
                    <tr><td>Default Search Option</td><td>Choose the initial comparison, such as Contains or Equals.</td></tr>
                    <tr><td>Case-sensitive Search</td><td>Distinguish letter case where the database/collation supports it.</td></tr>
                    <tr><td>Enable Search Saving</td><td>Allow supported saved-search workflows.</td></tr>
                    <tr><td>Highlight Search Results</td><td>Visually emphasize matched content where supported.</td></tr>
                </tbody></table></div>
                <div class="pp-guide-callout"><i class="bi bi-lightning-charge"></i><div>Saving the modal updates the field's On/Filter indicator immediately; no page reload should be necessary.</div></div>
            HTML,
        ],
        [
            'id' => 'controls',
            'label' => 'Field controls & validation',
            'icon' => 'ui-checks-grid',
            'keywords' => 'field control edit view filter validation lookup wizard dropdown label value display id unique regex condition when required email json blur live modal double click assign once',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Beginner → advanced</span><h3>One place to pick how a field is edited, shown, filtered &amp; validated</h3><p><strong>Double-click any field</strong> (in the Designer canvas or a list column) to open <em>Field controls</em>. Assign a control once and the build applies it to every page — Add, Edit, List, View, Print. Tick <strong>Different per page</strong> only when a page needs its own control.</p></div>
                <div class="pp-guide-grid">
                    <article class="pp-guide-card"><i class="bi bi-pencil-square"></i><h4>Edit</h4><p>The input on Add/Edit forms — text box, dropdown, date picker, rich text, file upload, and more.</p></article>
                    <article class="pp-guide-card"><i class="bi bi-eye"></i><h4>View</h4><p>How the stored value is displayed on List, View and Print.</p></article>
                    <article class="pp-guide-card"><i class="bi bi-funnel"></i><h4>Filter</h4><p>The search widget shown for the column on the list's filter panel.</p></article>
                    <article class="pp-guide-card"><i class="bi bi-shield-check"></i><h4>Validation</h4><p>Rules checked in the browser and again on the server when the record is saved.</p></article>
                </div>

                <h4>Show the friendly label, not the stored code</h4>
                <p>When a field stores a code but should read as a name, the list &amp; view pages now translate it automatically:</p>
                <ul class="pp-guide-list">
                    <li><strong>Lookup Wizard</strong> fields store another table's key (e.g. an <code>id</code>) but display its label column (e.g. the customer's name) everywhere.</li>
                    <li><strong>Dropdown, Radio Group, Button Toggle, Checkbox and Switch</strong> that use <code>value:Label</code> options (e.g. <code>1:Active, 0:Inactive</code>) show the label — a Switch shows its On/Off text.</li>
                    <li>Each of these has a <strong>Show on list &amp; view</strong> toggle: <em>Label</em> (default) or <em>Value</em> when you deliberately want the raw code / id.</li>
                </ul>
                <div class="pp-guide-callout"><i class="bi bi-magic"></i><div>This needs no extra setup — configure the control once and the label appears on List, View, Print, PDF and Export. Pick “Value” only for the rare case you want the id.</div></div>

                <h4>Validation rules</h4>
                <p>On the <strong>Validation</strong> tab, click rules from the palette to stack them on a field. Each rule can carry a custom message (leave it blank to use the sensible default).</p>
                <div class="pp-guide-table-wrap"><table class="pp-guide-table"><thead><tr><th>Feature</th><th>What it does</th></tr></thead><tbody>
                    <tr><td>22 built-in rules</td><td>Presence, format (email, URL, phone…), numeric range, length, date/time, password strength, credit-card, one-of-a-list, JSON, cross-field compare/match/different, and more.</td></tr>
                    <tr><td>Regular expression helper</td><td>Enter a pattern with one-click examples (letters only, digits, ZIP, hex colour…) and a live tester that shows match / no-match as you type.</td></tr>
                    <tr><td>Only validate when…</td><td>Gate a rule on another field — e.g. require <em>Reason</em> only when <em>Status equals “other”</em>. Enforced in the browser and on the server.</td></tr>
                    <tr><td>Live feedback</td><td>Rules check <strong>as the user leaves a field</strong> and clear the instant it's fixed, with an inline message beneath the input.</td></tr>
                    <tr><td>Unique (live)</td><td>The <em>Unique</em> rule checks availability against the database as the user types, so duplicates are caught before submit — and enforced again on save.</td></tr>
                </tbody></table></div>
                <div class="pp-guide-callout warning"><i class="bi bi-shield-lock"></i><div>Client-side checks are for fast feedback only. Every rule is <strong>re-enforced on the server</strong> when the record is saved — validation can't be bypassed by editing the page.</div></div>
                <div class="pp-guide-callout"><i class="bi bi-hammer"></i><div>Field controls and validation are compiled into the app at build time — <strong>rebuild the project</strong> after changing them.</div></div>
            HTML,
        ],
        [
            'id' => 'strategy',
            'label' => 'Design strategy',
            'icon' => 'diagram-3',
            'keywords' => 'intermediate advanced strategy sensitive performance index search import export permissions',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Intermediate → advanced</span><h3>Visibility, usability, and security are different layers</h3><p>A strong design coordinates Fields with Pages, Designer, Security, and the database.</p></div>
                <div class="pp-guide-grid">
                    <article class="pp-guide-card"><h4>Reduce noise</h4><p>List pages should summarize; View pages can carry detail.</p></article>
                    <article class="pp-guide-card"><h4>Protect exports</h4><p>Do not include secrets, password hashes, tokens, or unnecessary personal data.</p></article>
                    <article class="pp-guide-card"><h4>Improve search</h4><p>Search fields that users understand; consider database indexes for frequent selective filters.</p></article>
                    <article class="pp-guide-card"><h4>Keep write paths safe</h4><p>Only expose Add/Edit/Import fields the user is allowed to set.</p></article>
                </div>
                <div class="pp-guide-callout warning"><i class="bi bi-shield-lock"></i><div>Client-side visibility can be bypassed. Permissions, validation, ownership rules, and query constraints must also be enforced server-side.</div></div>
            HTML,
        ],
        [
            'id' => 'checklist',
            'label' => 'Review checklist',
            'icon' => 'check2-square',
            'keywords' => 'checklist troubleshoot verify build testing',
            'body' => <<<'HTML'
                <div class="pp-guide-hero"><span class="pp-guide-level">Release readiness</span><h3>Validate the field experience</h3></div>
                <div class="pp-guide-checklist">
                    <label><input type="checkbox"> IDs, timestamps, and protected fields are excluded from write forms where appropriate.</label>
                    <label><input type="checkbox"> List and Cards contain only useful summary fields.</label>
                    <label><input type="checkbox"> Mobile layouts remain scannable.</label>
                    <label><input type="checkbox"> Search and filter fields match real user terminology.</label>
                    <label><input type="checkbox"> Export/Print/PDF expose no unauthorized data.</label>
                    <label><input type="checkbox"> Security permissions protect hidden fields server-side.</label>
                    <label><input type="checkbox"> A fresh build was tested on representative records.</label>
                </div>
            HTML,
        ],
    ],
];

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