Doc gap feedback form in every page footer

[Freddyminu]

Summary

• Swizzles DocItem/Footer to add a "Send feedback" button next to "Edit this page" in the footer of every doc page
• Clicking the button opens a slide-in card (bottom-right, no overlay) with a short form
• The form submits directly to the HubSpot Forms API v3, attaching the current page URL automatically
• Fields: free-text feedback (required) and email address (optional)
• The button bounces once when the footer first scrolls into view to draw attention without being intrusive
• HubSpot portal ID and form ID are configured via customFields in docusaurus.config.ts (env vars HUBSPOT_PORTAL_ID / HUBSPOT_DOC_GAP_FORM_ID override the defaults)

Test plan

• Open any doc page, scroll to the bottom and confirm the "Send feedback" button bounces once
• Click "Send feedback" — the slide-in card opens from the bottom-right
• Submit without filling the feedback field — the native required validation fires, form does not submit
• Fill feedback and submit without an email — succeeds with "Thanks, we'll look into it."
• Fill both fields and submit — succeeds
• Press Escape or click X — card closes
• Navigate to another page — card closes and button bounce resets
• Check HubSpot for the submitted entry with the correct page URL

Closes #64

[Freddyminu]

[felipefdl]

Submitting the review with findings. 4 bugs (including a TypeScript breakage that will fail typecheck), 2 suggestions, 2 nits. Primary blockers: unrelated DocSearch CSS polluting the diff (conflicts with feat/218), missing required secrets with no docs, accessibility gaps on the FAB/drawer, and the React namespace issue on SyntheticEvent. See the 8 inline comments for line-specific details.

[felipefdl]

Retrospective review

Caught this after merge while rebasing feat/218-replace-algolia-search. Filing for follow-up.

Critical

1. Scope creep: 60+ lines of unrelated DocSearch/Algolia CSS (src/css/custom.css:1383-1453)

The PR title and body are scoped to "Doc gap feedback form," but the diff adds two CSS blocks for DocSearch (Algolia) light/dark theming. These are unrelated and should have been a separate PR. They also conflict with the in-flight Algolia removal on #218.

2. Silent failure in submit handler (src/theme/DocItem/Footer/index.tsx:181-184)

} catch {
  setStatus(\"error\");
}

The catch swallows errors with no logging. If a CORS or HubSpot API issue hits in production, the user sees "Something went wrong" with zero debugging signal. Add console.error(err) at minimum.

3. PR description does not match implementation

PR body says "Swizzles DocItem/Footer to add a 'Send feedback' button next to 'Edit this page'." The actual implementation renders a fixed-position floating action button at bottom-right of the viewport (src/css/custom.css:1457-1481), not an inline button. Worth reconciling with the original spec.

Important

4. formKey remount trick is a code smell (Footer/index.tsx:16, 100)

Incrementing a key to force-remount FeedbackForm and reset its state is hacky. Move state to the parent and reset explicitly, or use a useEffect keyed on open.

5. Unnecessary as string casts (Footer/index.tsx:21-22, 141-142)

const portalId = siteConfig.customFields?.hubspotPortalId as string | undefined;
// ...
portalId={portalId as string}

The double cast indicates the type guard is not expressed through the type system. Narrow once at the top with an early return.

6. No timeout on the fetch (Footer/index.tsx:170-179)

If HubSpot hangs, the button stays in "Sending..." forever. Add AbortSignal.timeout(10000).

7. z-index magic numbers conflict with Docusaurus (custom.css:1461, 1500)

z-index: 199 and 200 collide with Docusaurus's own layered components (navbar uses 200). Use a defined scale or document the reason.

8. Hardcoded colors that should be CSS variables (custom.css)

#e53e3e, #fff, and the entire DocSearch override block uses raw hex (#1a1a1a, #252525, #707070). Should reference Infima tokens (--ifm-color-danger) for theme consistency.

9. "Secrets" treatment of public values (.github/workflows/*.yml, docusaurus.config.ts)

HUBSPOT_PORTAL_ID and HUBSPOT_DOC_GAP_FORM_ID are passed as repo secrets but end up bundled in client-side JS via customFields and sent in the URL to HubSpot's public Forms API. They are not secrets. Use repository variables (\${{ vars.HUBSPOT_PORTAL_ID }}) instead.

Suggestions

10. Feature gated on hasTags || hasEditMeta (Footer/index.tsx:71)

Pages without tags or edit metadata get no feedback button. Those are arguably pages most in need of feedback. Decide whether that gate is intentional.

11. No tests for a 239-line interactive component. The form, observer, escape handler, success timeout, and HubSpot submission all lack tests.

12. Bounce-once language vs. behavior. PR says "bounces once when the footer first scrolls into view," but the implementation resets visible on every permalink change (lines 31-35), so it bounces on every navigation.

Strengths

• Clean swizzle of DocItem/Footer instead of patching upstream
• Proper aria-modal, aria-label, and Escape key handling
• IntersectionObserver disconnects after firing (no leak)
• All effects clean up timers and listeners
• hasFeedbackConfig gracefully degrades when env vars are missing
• Native HTML5 required validation
• Submit button correctly disabled on empty input and during send

Recommended follow-ups

1. Add error logging in the catch block (changing the documentation and fixing broken links #2)
2. Move the DocSearch CSS out, or revert if it is dead code post-Algolia removal (fix simulator link #1). #218 will need to handle this conflict
3. Reconcile the FAB-vs-inline-button discrepancy with the original spec (TCORE-296 Documentation Work #3)
4. Decide on formKey reset, as string casts, fetch timeout, and z-index scale