# Provider Form Requirements Guidance Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Make required fields, conditional constraints, blocking dependencies, optional steps, and publication minimums explicit across every provider account and portal form. **Architecture:** Add one reusable Blade guide partial and one focused JavaScript requirements module. Static forms declare concise localized guidance in Blade; JavaScript decorates required controls accessibly and renders safe dynamic dependency notices. Existing API payloads, validation, provider state, and review transitions remain unchanged. **Tech Stack:** Laravel Blade and translations, vanilla JavaScript, provider portal CSS, Node assertion tests, PHPUnit feature tests, Laravel Mix. --- ## File Structure - Create `resources/views/provider/partials/requirements-guide.blade.php`: shared safe guide/blocker markup. - Create `resources/js/provider/02-requirements.js`: required-marker decoration and safe dynamic notice rendering. - Create `tests/js/provider-requirements.test.js`: DOM-unit coverage for markers and notices. - Create `tests/Feature/ProviderPortalRequirementsGuidanceTest.php`: account and authenticated form coverage in both locales. - Modify `webpack.mix.js` and `package.json`: include the new source module and test. - Modify `resources/lang/es/provider_portal.php` and `resources/lang/en/provider_portal.php`: all requirement, optional, blocking, and minimum copy. - Modify provider Blade partials under `resources/views/provider/partials/`: insert guides and stable dynamic notice containers without changing form actions. - Modify `resources/js/provider/07-categories-view.js`, `11-locations-view.js`, `18-media-view.js`, `19-verifications-view.js`, and `20-review-view.js`: render prominent dynamic states through the shared requirements helper. - Modify `public/css/provider/portal/04-components.css`: MyCode blue/coral guide, marker, helper, optional, and checklist states. - Modify `public/js/provider/app.js`: generated bundle produced by Laravel Mix. - Modify `VERSION`: patch release selected through the repository version hook. ### Task 1: Shared requirement primitives **Files:** - Create: `tests/js/provider-requirements.test.js` - Create: `resources/js/provider/02-requirements.js` - Modify: `webpack.mix.js` - Modify: `package.json` - [ ] **Step 1: Write the failing JavaScript test** Create a small fake DOM and assert that required controls receive one visible marker, `aria-required="true"`, stable helper text, and no duplicate marker after a second pass. Assert that dynamic notices accept only `info`, `blocking`, `error`, and `success`, use text nodes, and hide when the message is empty. ```js assert.strictEqual(context.providerApplyRequiredGuidance(root, documentStub), 2); assert.strictEqual(email.getAttribute('aria-required'), 'true'); assert.strictEqual(emailLabel.querySelectorAll('[data-provider-required-marker]').length, 1); context.providerRenderRequirementNotice(notice, { tone: 'blocking', title: 'Acción requerida', message: '', }, documentStub); assert.strictEqual(notice.dataset.tone, 'blocking'); assert.strictEqual(notice.textContent.includes(' child.tagName === 'IMG'), false); ``` - [ ] **Step 2: Run the test and verify RED** Run: ```bash node tests/js/provider-requirements.test.js ``` Expected: FAIL because `resources/js/provider/02-requirements.js` and its functions do not exist. - [ ] **Step 3: Implement the minimal requirements module** Provide these focused functions: ```js function providerRequirementText(value) { return typeof value === 'string' ? providerTranslate(value) : ''; } function providerApplyRequiredGuidance(root = document, doc = document) { // Find label-wrapped required controls, add one aria-hidden coral marker, // add one screen-reader label, and preserve existing aria-describedby. } function providerRenderRequirementNotice(node, state, doc = document) { // Allowlist tones, replace children with icon/title/message text nodes, // set data-tone and hidden state, and never use innerHTML. } ``` Register a `DOMContentLoaded` pass for server-rendered forms. Add the source file immediately after `00-i18n-validation.js` in both Laravel Mix provider source lists. Add the new test at the beginning of `npm run test:provider`. - [ ] **Step 4: Run the test and verify GREEN** Run: ```bash node tests/js/provider-requirements.test.js npm run test:provider ``` Expected: the new focused test and the existing provider suite pass. - [ ] **Step 5: Commit the shared behavior** ```bash git add tests/js/provider-requirements.test.js resources/js/provider/02-requirements.js webpack.mix.js package.json git commit -m "feat: add provider requirement guidance primitives" ``` ### Task 2: Localized Blade guidance for account and identity flows **Files:** - Create: `resources/views/provider/partials/requirements-guide.blade.php` - Create: `tests/Feature/ProviderPortalRequirementsGuidanceTest.php` - Modify: `resources/lang/es/provider_portal.php` - Modify: `resources/lang/en/provider_portal.php` - Modify: `resources/views/provider/partials/account.blade.php` - Modify: `resources/views/provider/partials/profile.blade.php` - Modify: `resources/views/provider/partials/categories.blade.php` - Modify: `resources/views/provider/partials/media.blade.php` - Modify: `resources/views/provider/partials/verifications.blade.php` - Modify: `resources/views/provider/partials/review.blade.php` - [ ] **Step 1: Write failing feature tests** Test Spanish and English account pages plus authenticated profile/review pages. Assert stable guide IDs, translated titles, required legends, and no untranslated Spanish copy on the English response. ```php $this->get('/prestadores/registro') ->assertOk() ->assertSee('provider-account-requirements', false) ->assertSee('Todos los campos son obligatorios'); $this->get('/en/providers/register') ->assertOk() ->assertSee('All fields are required') ->assertDontSee('Todos los campos son obligatorios'); ``` Use existing provider-session test helpers for authenticated routes and assert guides for identity, categories, logo/cover, verification, and review. - [ ] **Step 2: Run the test and verify RED** Run: ```bash php artisan test tests/Feature/ProviderPortalRequirementsGuidanceTest.php ``` Expected: FAIL because the guide partial, translation keys, and guide IDs do not exist. - [ ] **Step 3: Create the safe guide partial and translations** The partial must allowlist its visual tone and render translated plain strings: ```blade @php($guideTone = in_array($tone ?? 'info', ['info', 'blocking', 'error', 'success'], true) ? ($tone ?? 'info') : 'info')
{{ $title }}

{{ $message }}

``` Add a `requirements` translation group containing common labels and form-specific copy for login, registration, verification, password recovery, identity, categories, media, verification evidence, location operations, and review minimums. - [ ] **Step 4: Insert guides without changing payloads** Add the shared guide after each relevant form heading. Preserve all input names, endpoint data attributes, methods, submit buttons, and existing validation attributes. Add missing native `required` only where the current JavaScript/API contract already requires the control, such as contact type. - [ ] **Step 5: Run focused and localization tests** Run: ```bash php artisan test tests/Feature/ProviderPortalRequirementsGuidanceTest.php tests/Feature/ProviderPortalLocalizationTest.php tests/Feature/ProviderPortalProfileTest.php ``` Expected: PASS with equivalent Spanish and English guidance. - [ ] **Step 6: Commit static guidance** ```bash git add resources/views/provider/partials resources/lang/es/provider_portal.php resources/lang/en/provider_portal.php tests/Feature/ProviderPortalRequirementsGuidanceTest.php git commit -m "feat: explain provider form requirements" ``` ### Task 3: Location and operation-step guidance **Files:** - Modify: `resources/views/provider/partials/location-form.blade.php` - Modify: `resources/views/provider/partials/location-address-fields.blade.php` - Modify: `resources/views/provider/partials/services.blade.php` - Modify: `resources/views/provider/partials/attributes.blade.php` - Modify: `resources/views/provider/partials/schedules.blade.php` - Modify: `resources/views/provider/partials/contacts.blade.php` - Modify: `resources/views/provider/partials/media.blade.php` - Modify: `tests/Feature/ProviderPortalRequirementsGuidanceTest.php` - Modify: `tests/js/provider-operations.test.js` - [ ] **Step 1: Extend tests for every operation form** Assert guide IDs for location, services, specialties, features, schedules, exceptions, contacts, and location images. Extend JavaScript operation tests to require markers/helper copy on generated conditional controls and to preserve names after reindexing. - [ ] **Step 2: Run focused tests and verify RED** Run: ```bash php artisan test tests/Feature/ProviderPortalRequirementsGuidanceTest.php node tests/js/provider-operations.test.js ``` Expected: FAIL for missing guides and generated-control requirement metadata. - [ ] **Step 3: Add form-specific localized guides** Use concise wording from the approved specification: - location: address/map confirmation minimums; - services: optional, with conditional price rules; - specialties/features: optional until an item is selected; - weekly hours: optional while editing but required with a qualifying location for review unless 24 hours; - exceptions: optional, date/mode required per added exception; - contacts: type/value required and at least one public contact required for review; - location media: optional, file requirements apply when uploading. Do not alter request construction or API routes. - [ ] **Step 4: Decorate dynamic operation controls** Update generated labels only where a row makes a control conditionally required. Call `providerApplyRequiredGuidance(row, doc)` after dynamic row creation. Keep conditional schedule modes accurate by marking only controls currently required for the chosen mode. - [ ] **Step 5: Run focused tests and verify GREEN** Run: ```bash php artisan test tests/Feature/ProviderPortalRequirementsGuidanceTest.php node tests/js/provider-operations.test.js npm run test:provider ``` Expected: PASS without payload snapshots changing. - [ ] **Step 6: Commit operation guidance** ```bash git add resources/views/provider/partials tests/Feature/ProviderPortalRequirementsGuidanceTest.php tests/js/provider-operations.test.js resources/js/provider git commit -m "feat: guide provider location requirements" ``` ### Task 4: Prominent dependencies and review blockers **Files:** - Modify: `resources/js/provider/07-categories-view.js` - Modify: `resources/js/provider/11-locations-view.js` - Modify: `resources/js/provider/18-media-view.js` - Modify: `resources/js/provider/19-verifications-view.js` - Modify: `resources/js/provider/20-review-view.js` - Modify: `resources/views/provider/partials/media.blade.php` - Modify: `resources/views/provider/partials/verifications.blade.php` - Modify: `tests/js/provider-payloads.test.js` - Modify: `tests/js/provider-review.test.js` - Modify: `tests/js/provider-requirements.test.js` - [ ] **Step 1: Write failing dependency-state tests** Assert that a missing provider renders a coral blocking notice with title “Acción requerida” and the existing save-identity instruction. Assert that read-only status notices use a prominent non-validation tone. Assert that review blocker text names the missing required items and excludes optional services/media/verifications. ```js context.providerRenderCategoriesState(); assert.strictEqual(categoryNotice.dataset.tone, 'blocking'); assert.match(categoryNotice.textContent, /Guarda primero la identidad/); context.providerRenderReview(provider, locations); assert.match(reviewNotice.textContent, /categoría/i); assert.doesNotMatch(reviewNotice.textContent, /imagen.*requerida/i); ``` - [ ] **Step 2: Run tests and verify RED** Run: ```bash node tests/js/provider-requirements.test.js node tests/js/provider-payloads.test.js node tests/js/provider-review.test.js ``` Expected: FAIL because notices are currently raw text with no structured tone or blocker summary. - [ ] **Step 3: Route dynamic notices through the safe helper** Replace raw dependency text updates with `providerRenderRequirementNotice`. Add stable notice containers for media and verification forms. Keep current editor policies and do not enable controls when provider state is absent or read-only. - [ ] **Step 4: Add exact review blocker summaries** Derive missing required checklist keys from the existing completion object. Translate only required keys (`identity`, `categories`, `locations`, `schedules`, `contacts`) and keep optional keys labelled optional. The API remains the final review authority. - [ ] **Step 5: Run tests and verify GREEN** Run: ```bash node tests/js/provider-requirements.test.js node tests/js/provider-payloads.test.js node tests/js/provider-review.test.js npm run test:provider ``` Expected: PASS with safe text rendering and unchanged payload behavior. - [ ] **Step 6: Commit dynamic guidance** ```bash git add resources/js/provider resources/views/provider/partials tests/js git commit -m "feat: highlight provider workflow blockers" ``` ### Task 5: MyCode styling, versioning, build, and regression **Files:** - Modify: `public/css/provider/portal/04-components.css` - Modify: `public/js/provider/app.js` - Modify: `VERSION` - Modify: relevant CSS/asset tests if selectors are asserted - [ ] **Step 1: Add failing visual-contract assertions** Extend the requirements JavaScript/CSS or feature contract tests to assert the shared classes and accessible states: ```php $css = file_get_contents(public_path('css/provider/portal/04-components.css')); $this->assertStringContainsString('.provider-requirement-guide--blocking', $css); $this->assertStringContainsString('.provider-required-marker', $css); ``` - [ ] **Step 2: Run the visual-contract test and verify RED** Run: ```bash php artisan test tests/Feature/ProviderPortalRequirementsGuidanceTest.php ``` Expected: FAIL because the approved CSS selectors do not exist. - [ ] **Step 3: Implement approved Option C styling** Use existing provider tokens and add: - blue information guides; - coral blocking/error guides; - green success guides; - coral required marker; - visually hidden accessible requirement text; - muted optional pill; - responsive spacing for desktop and mobile; - visible focus and high-contrast text. Do not introduce new hex values when an existing MyCode token represents the same color. - [ ] **Step 4: Select the patch version through the hook** Inspect `VERSION` and recent commits. Choose the next patch version because this is a backward-compatible UI improvement. When the commit hook presents the version dialogue, explicitly keep or select the reviewed patch value rather than accepting it blindly. - [ ] **Step 5: Build generated assets** Run: ```bash npm ci npm run production ``` Expected: Laravel Mix compiles `public/js/provider/app.js` successfully. - [ ] **Step 6: Run complete verification** Run: ```bash npm run test:provider php artisan test php artisan architecture:audit --strict git diff --check ``` Expected: all provider tests, the full PHPUnit suite, strict architecture audit, and whitespace check pass. - [ ] **Step 7: Perform visual QA** Inspect account, profile, location, verification, and review screens in Spanish and English at desktop and mobile breakpoints. Confirm markers, guides, blockers, focus behavior, and disabled-action explanations match approved Option C. - [ ] **Step 8: Commit the release-ready implementation** ```bash git add VERSION public/css/provider/portal/04-components.css public/js/provider/app.js resources tests webpack.mix.js package.json git commit -m "feat: clarify provider form requirements" ```