From cc45a4f1198607794b552c29b747db645a1ad677 Mon Sep 17 00:00:00 2001
From: FragginWagon <greg.r.jacobs@gmail.com>
Date: Fri, 11 Sep 2026 15:41:08 -0400
Subject: [PATCH] fix: clarify mapping and pricing fields

---
 apps/web/src/components/molecules/PricingReviewStep.vue  | 5 +++--
 .../web/src/components/molecules/ProviderMappingStep.vue | 9 ++++++---
 docs/IMPLEMENTATION-STATUS.md                            | 1 +
 3 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/apps/web/src/components/molecules/PricingReviewStep.vue b/apps/web/src/components/molecules/PricingReviewStep.vue
index d43cf89..3281032 100644
--- a/apps/web/src/components/molecules/PricingReviewStep.vue
+++ b/apps/web/src/components/molecules/PricingReviewStep.vue
@@ -41,11 +41,12 @@ defineEmits([
     <label class="fixture-label" for="pricing-source">Source identifier</label>
     <input id="pricing-source" :value="sourceIdentifier" class="fixture-input" required @input="$emit('update:sourceIdentifier', $event.target.value)" />
     <label class="fixture-label" for="pricing-price">Observed price (cents)</label>
-    <input id="pricing-price" :value="observedPrice" class="fixture-input" type="number" min="1" required @input="$emit('update:observedPrice', $event.target.value)" />
+    <input id="pricing-price" :value="observedPrice" class="fixture-input" type="number" min="1" required aria-describedby="pricing-money-help" @input="$emit('update:observedPrice', $event.target.value)" />
+    <p id="pricing-money-help">Enter observed and manual values in whole cents.</p>
     <button class="button button--primary" type="submit" :disabled="isSaving">Add observation and calculate</button>
     <button class="button button--secondary" type="button" :disabled="isSaving" @click="$emit('refresh')">Refresh from provider<span v-if="refreshStatus"> ({{ refreshStatus }})</span></button>
     <label class="fixture-label" for="override-price">Manual value (cents)</label>
-    <input id="override-price" :value="overridePrice" class="fixture-input" type="number" min="0" @input="$emit('update:overridePrice', $event.target.value)" />
+    <input id="override-price" :value="overridePrice" class="fixture-input" type="number" min="0" aria-describedby="pricing-money-help" @input="$emit('update:overridePrice', $event.target.value)" />
     <label class="fixture-label" for="override-reason">Override reason</label>
     <input id="override-reason" :value="overrideReason" class="fixture-input" minlength="3" @input="$emit('update:overrideReason', $event.target.value)" />
     <button class="button button--secondary" type="button" :disabled="isSaving" @click="$emit('override')">Save manual value</button>
diff --git a/apps/web/src/components/molecules/ProviderMappingStep.vue b/apps/web/src/components/molecules/ProviderMappingStep.vue
index 3241c4f..ae2e14d 100644
--- a/apps/web/src/components/molecules/ProviderMappingStep.vue
+++ b/apps/web/src/components/molecules/ProviderMappingStep.vue
@@ -41,16 +41,19 @@ defineEmits([
       </option>
     </select>
     <label class="fixture-label" for="mapping-provider">Provider ID</label>
-    <input id="mapping-provider" :value="providerId" class="fixture-input" required placeholder="ebay" @input="$emit('update:providerId', $event.target.value)" />
+    <input id="mapping-provider" :value="providerId" class="fixture-input" required placeholder="ebay" aria-describedby="mapping-provider-help" @input="$emit('update:providerId', $event.target.value)" />
+    <p id="mapping-provider-help">Use the configured provider identifier, such as ebay.</p>
     <label class="fixture-label" for="mapping-type">Mapping type</label>
     <select id="mapping-type" :value="mappingType" class="fixture-input" @change="$emit('update:mappingType', $event.target.value)">
       <option value="PRODUCT">Product</option>
       <option value="SEARCH">Search</option>
     </select>
     <label class="fixture-label" for="mapping-external">External identifier</label>
-    <input id="mapping-external" :value="externalIdentifier" class="fixture-input" @input="$emit('update:externalIdentifier', $event.target.value)" />
+    <input id="mapping-external" :value="externalIdentifier" class="fixture-input" aria-describedby="mapping-external-help" @input="$emit('update:externalIdentifier', $event.target.value)" />
+    <p id="mapping-external-help">For Product mappings, enter the provider’s product identifier.</p>
     <label class="fixture-label" for="mapping-query">Search query</label>
-    <input id="mapping-query" :value="searchQuery" class="fixture-input" @input="$emit('update:searchQuery', $event.target.value)" />
+    <input id="mapping-query" :value="searchQuery" class="fixture-input" aria-describedby="mapping-query-help" @input="$emit('update:searchQuery', $event.target.value)" />
+    <p id="mapping-query-help">For Search mappings, enter the provider search text.</p>
     <button class="button button--primary" type="submit" :disabled="isSaving">Save provider mapping</button>
   </form>
 </template>
diff --git a/docs/IMPLEMENTATION-STATUS.md b/docs/IMPLEMENTATION-STATUS.md
index cadf9c7..0e9c776 100644
--- a/docs/IMPLEMENTATION-STATUS.md
+++ b/docs/IMPLEMENTATION-STATUS.md
@@ -280,6 +280,7 @@ Remaining roadmap areas are approved external provider credentials/adapters, bro
 - Expired admin sessions now redirect to login with an accessible explanation that prompts the user to sign in again.
 - Session-expired login messaging now has Storybook interaction coverage.
 - Admin sale and acquisition amount fields now expose explicit units and optional-field guidance through associated help text.
+- Provider mapping fields now explain Product versus Search identifiers, and pricing values expose their cents unit through associated help text.
 
 ## Local Commands