Add JavaScript documentation

docs/JAVASCRIPT.md

@@ -0,0 +1,124 @@
+# JavaScript Usage
+
+This project minimizes JavaScript usage, preferring pure CSS solutions where possible (e.g., `<details>` elements for toggles). JavaScript is used only where necessary for payment integrations, real-time updates, and progressive enhancement.
+
+## Philosophy
+
+- Prefer pure HTML/CSS over JavaScript
+- Use `<details>` elements for toggles instead of JS
+- External SDKs loaded only when payment method is enabled
+- No build step - vanilla JS only
+- jQuery used minimally (legacy, being phased out)
+
+## Static JavaScript Files
+
+Located in `make_post_sell/static/js/`:
+
+### jquery-3.6.0.min.js
+- jQuery library (legacy dependency)
+- Used by: Stripe card form, markdown preview
+- Loaded via `snippets/optional-javascript.j2` and `snippets/stripe.j2`
+
+### qrcode.min.js
+- QRious library for QR code generation
+- Used by: Crypto checkout page
+- Generates payment QR codes for XMR/DOGE addresses
+
+### custom.js
+- Markdown preview functionality
+- Functions: `previewAjax()`, `sendPreview()`
+- Uses jQuery for AJAX calls to `/markup-editor-preview`
+
+## Inline JavaScript by Template
+
+### base.j2
+**Purpose:** Theme switching (dark/light mode)
+
+- Runs immediately in `<head>` to prevent flash of wrong theme
+- Priority: localStorage > user preference > shop default
+- Exposes `window.setTheme()` for programmatic use
+
+### shop_settings.j2
+**Purpose:** Settings page interactions
+
+- Crypto wallets toggle (checkbox + localStorage)
+- Theme preview for shop default theme radio buttons
+- Note: Payment provider toggles now use pure CSS `<details>` elements
+
+### user_settings.j2
+**Purpose:** User theme preference sync
+
+- Syncs theme radio buttons with localStorage
+- Updates localStorage on form submit
+
+### cart_checkout.j2
+**Purpose:** Payment processing
+
+1. **PayPal SDK** (`paypal.Buttons()`)
+   - Loads PayPal SDK from `paypal.com`
+   - Creates orders via `POST /paypal/create-order`
+   - Handles approval flow and form submission
+   - Double-click protection flags
+
+2. **Cancel Crypto Quote** (`cancelQuote()`)
+   - Cancels pending crypto payment quotes
+   - Uses fetch API with CSRF token
+
+### crypto_checkout.j2
+**Purpose:** Crypto payment monitoring
+
+- QR code generation using QRious library
+- Countdown timer for quote expiry
+- Status polling via fetch API
+- Copy-to-clipboard for address/amount
+- Dynamic UI updates based on payment status
+- Functions: `disableQuoteButtons()`, `removePaymentElements()`, `replaceButtonsWithInvoiceLink()`
+
+### snippets/stripe.j2
+**Purpose:** Stripe card form (macro `new_card()`)
+
+- Loads Stripe.js SDK
+- Creates Payment Element for card input
+- Handles `stripe.confirmSetup()` flow
+- Requires jQuery
+
+### snippets/analytics.j2
+**Purpose:** Analytics tracking (optional)
+
+- Plausible Analytics (privacy-focused)
+- Google Analytics (gtag.js)
+- Only loaded if shop has configured analytics
+
+### snippets/optional-javascript.j2
+**Purpose:** Optional JS loading
+
+- Loads jQuery and custom.js async
+- Used for markdown preview functionality
+
+## External SDKs
+
+| SDK | URL | Used For |
+|-----|-----|----------|
+| PayPal | `paypal.com/sdk/js` | PayPal button/checkout |
+| Stripe | `js.stripe.com/v3/` | Card payment form |
+| Plausible | Shop-configured domain | Privacy analytics |
+| Google Analytics | `googletagmanager.com` | Google analytics |
+
+## CSRF Protection
+
+All fetch/AJAX calls include CSRF tokens:
+- Header: `X-CSRF-Token`
+- Value from: `{{ request.session.get_csrf_token() }}` or hidden input
+
+## Progressive Enhancement
+
+Pages work without JavaScript where possible:
+- Payment provider toggles use `<details>` (pure CSS)
+- Forms submit normally without JS
+- JS enhances UX (copy buttons, QR codes, live previews)
+
+## Future Improvements
+
+- Remove jQuery dependency (replace with vanilla JS)
+- Convert remaining checkbox toggles to `<details>` elements
+- Consider removing Google Analytics option (privacy)