Initial commit

2026-03-23 21:37:59 +01:00
commit 2547717edb
2193 changed files with 972171 additions and 0 deletions
--- a/references/CALL_CARD_DISPLAY_REFERENCE.md
+++ b/references/CALL_CARD_DISPLAY_REFERENCE.md
@@ -0,0 +1,335 @@
+# Call Card Display Reference
+
+This document describes when and how call cards are displayed on the platform, covering guest vs authenticated contexts, component variants, layout options, scoring logic, and platform configuration.
+
+---
+
+## Overview
+
+Call cards appear in two page contexts:
+
+| Page | Audience | Components used |
+|------|----------|-----------------|
+| Welcome page (`/`) | Guests (unauthenticated) | `WelcomePage\CallCardHalf`, `WelcomePage\CallCardCarousel` (in CTA post) |
+| Main dashboard | Authenticated users | `MainPage\CallCardCarousel`, `MainPage\CallCardHalf`, `MainPage\CallCardFull` |
+
+---
+
+## Component Map
+
+```
+welcome.blade.php
+├── @livewire('welcome-page.call-card-half', ['random' => true, 'rows' => 2])
+│   └── WelcomePage\CallCardHalf
+│       └── view: livewire/main-page/call-card-half.blade.php
+│           └── x-call-card (components/call-card.blade.php) × N
+│
+└── @livewire('welcome.cta-post')
+    └── cta-post.blade.php
+        └── @livewire('welcome-page.call-card-carousel', ['random' => false])
+            └── WelcomePage\CallCardCarousel
+                └── view: livewire/main-page/call-card-carousel.blade.php
+
+main-page.blade.php (authenticated)
+├── @livewire('main-page.call-card-carousel', ['related' => true, 'random' => false])
+│   └── MainPage\CallCardCarousel
+│       └── view: livewire/main-page/call-card-carousel.blade.php
+│
+├── @livewire('main-page.call-card-half', ['related' => false, 'random' => true, 'rows' => 2])
+│   └── MainPage\CallCardHalf
+│       └── view: livewire/main-page/call-card-half.blade.php
+│           └── x-call-card (components/call-card.blade.php) × N
+│
+└── [individual card sections use livewire/main-page/call-card-full.blade.php]
+```
+
+---
+
+## Guest vs Authenticated Distinction
+
+### Guest (Welcome page)
+
+Components: `WelcomePage\CallCardCarousel`, `WelcomePage\CallCardHalf`
+
+- `is_public = true` is **always hardcoded** — cannot be overridden by config
+- No profile context → no locality filtering applied
+- `CallCarouselScorer` is instantiated with `null` for all location IDs
+- Uses config block `calls.welcome_carousel`
+- Location proximity boost factors have no effect (no profile location to compare against)
+- Reaction buttons: displayed as read-only (no click to react). When `like_count > 0`, a solid filled icon is shown in white. When `like_count = 0`, the reaction button is hidden entirely.
+
+### Authenticated (Main dashboard)
+
+Components: `MainPage\CallCardCarousel`, `MainPage\CallCardHalf`
+
+- `is_public` enforcement controlled by `calls.carousel.exclude_non_public` (platform config)
+- Profile resolved via `getActiveProfile()` → location extracted for locality filtering
+- `CallCarouselScorer` receives profile city/division/country IDs → location proximity boosts apply
+- Uses config block `calls.carousel`
+- Own calls excluded when `calls.carousel.exclude_own_calls = true`
+- Reaction buttons: fully interactive (like/unlike)
+
+---
+
+## Shared Query Filters (all variants)
+
+The following filters are always hardcoded regardless of config or auth state:
+
+```php
+->whereNull('deleted_at')
+->where('is_paused', false)
+->where('is_suppressed', false)
+->where(fn ($q) => $q->whereNull('till')->orWhere('till', '>=', now()))
+```
+
+---
+
+## Locality Filtering (authenticated only)
+
+When a profile has a location, the auth carousel and half-card components build location ID arrays and add a WHERE clause to restrict calls to nearby locations.
+
+**Location resolution hierarchy:**
+
+1. **City level** — `location.city` is set → expands to all sibling cities in the same division (when `related = true`)
+2. **Division level** — `location.division` set but no city → expands to all sibling divisions in same parent (when `related = true`)
+3. **Country level** — only country set → all countries (when `related = true`) or just the profile's country
+
+**Locality config keys** (under `calls.carousel`):
+
+| Key | Default | Effect |
+|-----|---------|--------|
+| `include_unknown_location` | `true` | Also include calls with unknown/unspecified location (`country_id = 10`) |
+| `include_same_division` | `true` | Include calls in same division as profile |
+| `include_same_country` | `true` | Include calls in same country as profile |
+
+---
+
+## Scoring — CallCarouselScorer
+
+All variants use `App\Http\Livewire\Calls\CallCarouselScorer`. The scorer multiplies a base score of `1.0` by a series of boost factors read from config.
+
+### Location proximity boosts (authenticated only — null IDs → no effect)
+
+| Config key | Default | Applied when |
+|------------|---------|--------------|
+| `boost_same_district` | 3.0 | Call location city matches profile city |
+| `boost_location_city` | 2.0 | Call has city-level location |
+| `boost_location_division` | 1.5 | Call has division-level location |
+| `boost_location_country` | 1.1 | Call has country-level location |
+| `boost_location_unknown` | 0.8 (default) / 2.5 (timebank_cc) | Call has unknown location |
+
+### Engagement boosts
+
+| Config key | Default | Applied when |
+|------------|---------|--------------|
+| `boost_like_count` | 0.05 | Multiplied by call's like count |
+| `boost_star_count` | 0.10 | Multiplied by callable's star count |
+
+### Recency / urgency boosts
+
+| Config key | Default | Applied when |
+|------------|---------|--------------|
+| `boost_recent_from` | 1.3 | Call was created within `recent_days` (14) days |
+| `boost_soon_till` | 1.2 | Call expires within `soon_days` (7) days |
+
+### Callable type boosts
+
+| Config key | Default | Applied when |
+|------------|---------|--------------|
+| `boost_callable_user` | 1.0 | Call posted by a User |
+| `boost_callable_organization` | 1.2 | Call posted by an Organization |
+| `boost_callable_bank` | 1.0 | Call posted by a Bank |
+
+### Random jitter
+
+When the component is mounted with `random = true`, the final score is multiplied by `random_int(85, 115) / 100`, introducing ±15% variation to shuffle order on each page load.
+
+---
+
+## Pool and Selection Logic
+
+All components fetch a **candidate pool** larger than the number of cards to display, score all candidates in PHP, then take the top N by score.
+
+```
+pool_size = display_limit × pool_multiplier
+```
+
+| Component | display_limit | pool_multiplier config key |
+|-----------|--------------|---------------------------|
+| `CallCardCarousel` (auth) | `max_cards` | `calls.carousel.pool_multiplier` |
+| `CallCardCarousel` (guest) | `max_cards` | `calls.welcome_carousel.pool_multiplier` |
+| `CallCardHalf` (auth) | `rows × 2` | `calls.carousel.pool_multiplier` |
+| `CallCardHalf` (guest) | `rows × 2` | `calls.welcome_carousel.pool_multiplier` |
+
+---
+
+## Platform Configuration
+
+### `calls.carousel` — authenticated main-page carousel and half cards
+
+```php
+'carousel' => [
+    'max_cards'                   => 12,
+    'pool_multiplier'             => 5,
+    'exclude_non_public'          => true,   // false in timebank_cc (shows private calls to auth users)
+    'exclude_own_calls'           => true,
+    'include_unknown_location'    => true,
+    'include_same_division'       => true,
+    'include_same_country'        => true,
+
+    // Scoring boosts
+    'boost_same_district'         => 3.0,
+    'boost_location_city'         => 2.0,
+    'boost_location_division'     => 1.5,
+    'boost_location_country'      => 1.1,
+    'boost_location_unknown'      => 0.8,   // 2.5 in timebank_cc
+    'boost_like_count'            => 0.05,
+    'boost_star_count'            => 0.10,
+    'boost_recent_from'           => 1.3,
+    'recent_days'                 => 14,
+    'boost_soon_till'             => 1.2,
+    'soon_days'                   => 7,
+    'boost_callable_user'         => 1.0,
+    'boost_callable_organization' => 1.2,
+    'boost_callable_bank'         => 1.0,
+
+    'show_score'                  => false,
+    'show_score_for_admins'       => true,
+],
+```
+
+### `calls.welcome_carousel` — guest welcome page carousel and half cards
+
+```php
+'welcome_carousel' => [
+    'max_cards'                   => 12,
+    'pool_multiplier'             => 5,
+
+    // No location boosts — no profile context for guests
+    'boost_like_count'            => 0.05,
+    'boost_star_count'            => 0.10,
+    'boost_recent_from'           => 1.3,
+    'recent_days'                 => 14,
+    'boost_soon_till'             => 1.2,
+    'soon_days'                   => 7,
+    'boost_callable_user'         => 1.0,
+    'boost_callable_organization' => 1.2,
+    'boost_callable_bank'         => 1.0,
+
+    'show_score'                  => false,
+    'show_score_for_admins'       => true,
+],
+```
+
+**Key difference:** `welcome_carousel` has no `exclude_non_public` key because `is_public = true` is hardcoded in the component. It also has no location keys because locality filtering is never applied on the guest page.
+
+---
+
+## Visual Layouts
+
+### Carousel (`call-card-carousel.blade.php`)
+
+Horizontal scrollable strip. Cards are small (170px tall, ~1/3 viewport wide, min 200px, max 320px). Intended for quick browsing. Alpine.js handles smooth scroll with left/right navigation buttons that appear on hover and hide at scroll boundaries.
+
+Each card shows:
+- Deepest (leaf) tag category badge
+- Call title (truncated)
+- Location and expiry badges
+- Callable avatar and name
+- Reaction button (top-right, `w-5 h-5`)
+- Score (bottom-right, admin-only)
+
+### Half cards (`call-card-half.blade.php` + `x-call-card`)
+
+Responsive grid: 1 column on mobile, 2 columns on `md+`. Each row contains 2 cards; `rows` prop controls how many rows are shown.
+
+The `x-call-card` Blade component (`components/call-card.blade.php`) is used. Props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `result` | array | `[]` | Call data array |
+| `index` | int | `0` | Used to key nested Livewire components |
+| `href` | string\|null | `null` | Override link URL |
+| `wireClick` | string\|null | `null` | Use `wire:click` instead of href |
+| `showScore` | bool | `false` | Show score badge (bottom-right) |
+| `showCallable` | bool | `true` | Show callable avatar + name section |
+| `showReactions` | bool | `true` | Show reaction (like) button |
+| `heightClass` | string | `h-[430px] md:h-[550px] lg:h-[430px]` | Tailwind height classes |
+| `truncateExcerpt` | bool | `false` | Clamp excerpt to 2 lines |
+
+Each card shows:
+- Tag color background with `bg-black/50` overlay
+- Deepest (leaf) tag category badge
+- Call title (2-line clamp)
+- Location and expiry badges
+- Excerpt (2-line clamp when `truncateExcerpt = true`)
+- Callable avatar, name, location (when `showCallable = true`)
+- Reaction button top-right (when `showReactions = true`)
+
+### Full card (`call-card-full.blade.php`)
+
+Large hero-style card, full width. Used on the main dashboard for featured individual calls. Taller than half cards with larger typography (`text-3xl`/`text-4xl` title). Like button is absolutely positioned at `top-14 right-4` with `w-10 h-10` size.
+
+---
+
+## Call Data Array Structure
+
+All components produce a uniform array for each call:
+
+```php
+[
+    'id'                => int,
+    'model'             => 'App\Models\Call',
+    'title'             => string,   // tag name in active locale
+    'excerpt'           => string,   // call translation content
+    'photo'             => string,   // callable profile photo URL
+    'location'          => string,   // "City, COUNTRY" or null
+    'tag_color'         => string,   // Tailwind color name (e.g. 'green', 'blue')
+    'tag_categories'    => [         // ancestor chain from root to leaf
+        ['name' => string, 'color' => string],
+        ...
+    ],
+    'callable_name'     => string,
+    'callable_location' => string,   // built from callable's profile location
+    'till'              => datetime|null,
+    'expiry_badge_text' => string|null,  // e.g. "Expires in 5 days"
+    'like_count'        => int,
+    'score'             => float,
+]
+```
+
+Only the **deepest** (last) entry in `tag_categories` is displayed as a badge on the card.
+
+---
+
+## Reaction Button Behaviour on Call Cards
+
+| Context | State | Behaviour |
+|---------|-------|-----------|
+| Guest, `like_count = 0` | Hidden | Entire reaction button hidden |
+| Guest, `like_count > 0` | Read-only | Solid filled icon + count, white (`inverseColors`) |
+| Authenticated, not reacted | Interactive | Outline icon, clickable to like |
+| Authenticated, reacted | Interactive | Solid filled icon, clickable to unlike |
+
+On the call show page (`calls/show-guest.blade.php`) for guests, the reaction button links to the login page with the current URL as redirect, so clicking the icon takes the guest to login.
+
+---
+
+## File Reference
+
+| File | Role |
+|------|------|
+| `app/Http/Livewire/MainPage/CallCardCarousel.php` | Auth carousel — fetches, scores, filters by location |
+| `app/Http/Livewire/MainPage/CallCardHalf.php` | Auth half-grid — same logic as carousel, `rows` prop |
+| `app/Http/Livewire/WelcomePage/CallCardCarousel.php` | Guest carousel — public only, no location filter |
+| `app/Http/Livewire/WelcomePage/CallCardHalf.php` | Guest half-grid — public only, no location filter |
+| `app/Http/Livewire/Calls/CallCarouselScorer.php` | Scoring engine used by all four components |
+| `app/Http/Livewire/Calls/ProfileCalls.php` | Helpers: `buildCallableLocation()`, `buildExpiryBadgeText()` |
+| `resources/views/livewire/main-page/call-card-carousel.blade.php` | Carousel UI (shared by auth + guest carousel components) |
+| `resources/views/livewire/main-page/call-card-half.blade.php` | Half-grid UI (shared by auth + guest half components) |
+| `resources/views/livewire/main-page/call-card-full.blade.php` | Full-width card (main dashboard only) |
+| `resources/views/components/call-card.blade.php` | Reusable card component used by half-grid |
+| `resources/views/welcome.blade.php` | Guest welcome page layout |
+| `resources/views/livewire/welcome/cta-post.blade.php` | CTA section — embeds guest carousel |
+| `config/timebank-default.php` | Default `calls.carousel` and `calls.welcome_carousel` config |
+| `config/timebank_cc.php` | Platform overrides (`exclude_non_public`, `boost_location_unknown`) |