docs(phase-03): research note history & display implementation

2026-02-13 12:49:28 +08:00
parent 3d6cefef00
commit 2791b34e59
1 changed files with 558 additions and 0 deletions
--- a/.planning/phases/03-note-history-display/03-RESEARCH.md
+++ b/.planning/phases/03-note-history-display/03-RESEARCH.md
@@ -0,0 +1,558 @@
+# Phase 03: Note History & Display - Research
+
+**Researched:** 2026-02-13
+**Domain:** Alpine.js expandable table rows, Laravel query patterns, accessibility
+**Confidence:** HIGH
+
+## Summary
+
+Phase 3 implements an expandable inline panel in the member list table that displays full note history when clicking the note count badge. This requires Alpine.js state management for expand/collapse behavior, Laravel query optimization for fetching notes with author relationships, client-side search filtering within the displayed notes, and proper accessibility attributes for screen readers.
+
+The existing architecture already provides the foundation: Phase 1 built the Notes API endpoint (`GET /admin/members/{member}/notes`) that returns notes with author information, and Phase 2 established the per-row Alpine.js pattern with independent `x-data` scopes that work correctly with Laravel pagination. The key technical challenges are: (1) adding expand/collapse state to the existing Alpine component, (2) fetching notes via AJAX when expanding, (3) implementing client-side search filtering, and (4) formatting dates in Traditional Chinese locale.
+
+**Primary recommendation:** Use Alpine.js x-show with x-collapse plugin for smooth height animation, fetch notes once on first expand and cache in component state, implement client-side filtering with computed property pattern, ensure ARIA accessibility with aria-expanded and aria-controls attributes.
+
+## Standard Stack
+
+### Core
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| Alpine.js | 3.4.2 | Reactive UI state management | Already used in Phase 2 for inline form; lightweight, works with server-rendered HTML |
+| @alpinejs/collapse | 3.x | Smooth expand/collapse animation | Official Alpine plugin for height transitions, cleaner than manual CSS |
+| Laravel Eloquent | 10.x | Query notes with relationships | Built-in ORM with eager loading prevents N+1 queries |
+| Axios | Latest | AJAX requests for notes | Already included in Laravel bootstrap.js |
+| Tailwind CSS | 3.1 | Styling and dark mode | Project standard for all UI components |
+
+### Supporting
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| Laravel Carbon | 2.x (Laravel default) | Datetime formatting | Format created_at for display, supports locale |
+
+### Alternatives Considered
+| Instead of | Could Use | Tradeoff |
+|------------|-----------|----------|
+| x-collapse plugin | Manual x-transition with height classes | More boilerplate, harder to maintain smooth animations |
+| Client-side search | Server-side filtering with AJAX | More complex, requires additional API endpoint, overkill for small datasets |
+| Fetch on expand | Pre-load all notes in page load | Wasteful for members with many notes, degrades pagination performance |
+
+**Installation:**
+```bash
+npm install @alpinejs/collapse
+```
+
+Then register in `resources/js/app.js`:
+```javascript
+import Alpine from 'alpinejs';
+import collapse from '@alpinejs/collapse';
+
+Alpine.plugin(collapse);
+window.Alpine = Alpine;
+Alpine.start();
+```
+
+## Architecture Patterns
+
+### Recommended Project Structure
+```
+resources/views/admin/members/
+├── index.blade.php           # Main table with expandable rows
+└── partials/
+    └── note-history.blade.php  # (Optional) Extracted panel markup for clarity
+```
+
+### Pattern 1: Expandable Row with Lazy-Loaded Content
+
+**What:** Clicking badge expands panel below the row, fetches notes on first expand only, caches in Alpine state
+
+**When to use:** When content is not needed immediately, reduces initial page load, prevents N+1 in index query
+
+**Example:**
+```javascript
+// Source: https://alpinejs.dev/plugins/collapse
+{
+    noteFormOpen: false,      // From Phase 2
+    noteContent: '',          // From Phase 2
+    noteCount: {{ $member->notes_count }},  // From Phase 1
+
+    // NEW in Phase 3
+    historyOpen: false,       // Controls panel visibility
+    notes: [],                // Cached note data
+    notesLoaded: false,       // Tracks if we've fetched
+    isLoadingNotes: false,    // Loading state
+    searchQuery: '',          // Filter text
+
+    async toggleHistory() {
+        this.historyOpen = !this.historyOpen;
+        if (this.historyOpen && !this.notesLoaded) {
+            await this.loadNotes();
+        }
+    },
+
+    async loadNotes() {
+        this.isLoadingNotes = true;
+        try {
+            const response = await axios.get('{{ route("admin.members.notes.index", $member) }}');
+            this.notes = response.data.notes;
+            this.notesLoaded = true;
+        } catch (error) {
+            console.error('Failed to load notes:', error);
+        } finally {
+            this.isLoadingNotes = false;
+        }
+    },
+
+    get filteredNotes() {
+        if (!this.searchQuery.trim()) return this.notes;
+        const query = this.searchQuery.toLowerCase();
+        return this.notes.filter(note =>
+            note.content.toLowerCase().includes(query) ||
+            note.author.name.toLowerCase().includes(query)
+        );
+    }
+}
+```
+
+**Template:**
+```html
+<!-- Badge with click handler -->
+<button @click="toggleHistory()"
+        type="button"
+        :aria-expanded="historyOpen"
+        aria-controls="notes-panel-{{ $member->id }}"
+        class="inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium bg-blue-100 dark:bg-blue-900 text-blue-800 dark:text-blue-200 hover:bg-blue-200 dark:hover:bg-blue-800 cursor-pointer">
+    <span x-text="noteCount"></span>
+</button>
+
+<!-- Expandable panel (separate <tr> for proper table structure) -->
+<tr x-show="historyOpen"
+    x-collapse
+    :id="'notes-panel-' + {{ $member->id }}"
+    class="bg-gray-50 dark:bg-gray-900">
+    <td colspan="8" class="px-4 py-3">
+        <!-- Loading state -->
+        <div x-show="isLoadingNotes" class="text-center py-4">
+            <span class="text-sm text-gray-500 dark:text-gray-400">載入中...</span>
+        </div>
+
+        <!-- Content when loaded -->
+        <div x-show="!isLoadingNotes" x-cloak>
+            <!-- Search input -->
+            <input type="text"
+                   x-model="searchQuery"
+                   placeholder="搜尋備忘錄內容..."
+                   class="mb-3 block w-full rounded-md border-gray-300 dark:border-gray-600 shadow-sm...">
+
+            <!-- Notes list -->
+            <template x-if="filteredNotes.length > 0">
+                <div class="space-y-2">
+                    <template x-for="note in filteredNotes" :key="note.id">
+                        <div class="border-l-4 border-blue-500 pl-3 py-2">
+                            <p class="text-sm text-gray-900 dark:text-gray-100" x-text="note.content"></p>
+                            <p class="text-xs text-gray-500 dark:text-gray-400 mt-1">
+                                <span x-text="note.author.name"></span> ·
+                                <span x-text="formatDateTime(note.created_at)"></span>
+                            </p>
+                        </div>
+                    </template>
+                </div>
+            </template>
+
+            <!-- Empty state -->
+            <template x-if="notes.length === 0">
+                <p class="text-sm text-gray-500 dark:text-gray-400">尚無備註</p>
+            </template>
+
+            <!-- No results state -->
+            <template x-if="notes.length > 0 && filteredNotes.length === 0">
+                <p class="text-sm text-gray-500 dark:text-gray-400">找不到符合的備忘錄</p>
+            </template>
+        </div>
+    </td>
+</tr>
+```
+
+### Pattern 2: Client-Side Search with Computed Property
+
+**What:** Reactive filtering using Alpine.js getter that automatically updates when searchQuery changes
+
+**When to use:** Small to medium datasets (< 100 items), instant feedback, no server round-trip needed
+
+**Example:**
+```javascript
+// Source: https://github.com/alpinejs/alpine/discussions/484
+{
+    searchQuery: '',
+    notes: [...],
+
+    get filteredNotes() {
+        if (!this.searchQuery.trim()) return this.notes;
+
+        const query = this.searchQuery.toLowerCase();
+        return this.notes.filter(note => {
+            // Search in content and author name
+            const searchableText = (note.content + ' ' + note.author.name).toLowerCase();
+            return searchableText.includes(query);
+        });
+    }
+}
+```
+
+**Template:**
+```html
+<input type="text" x-model="searchQuery" placeholder="搜尋備忘錄...">
+<template x-for="note in filteredNotes" :key="note.id">
+    <!-- Note display -->
+</template>
+```
+
+### Pattern 3: Laravel Query Optimization for Notes Index
+
+**What:** Fetch notes with author relationship, order by newest first
+
+**When to use:** Always for the notes index endpoint to prevent N+1 and ensure consistent ordering
+
+**Example:**
+```php
+// Source: https://laravel.com/docs/10.x/pagination
+public function index(Member $member)
+{
+    $notes = $member->notes()
+        ->with('author:id,name')  // Eager load only needed author fields
+        ->latest('created_at')     // Newest first (equivalent to orderBy('created_at', 'desc'))
+        ->get();
+
+    return response()->json(['notes' => $notes]);
+}
+```
+
+**Why not paginate?**
+- Members typically have < 20 notes (based on system context)
+- Client-side search/filter requires all notes present
+- Pagination adds complexity without meaningful UX benefit for this use case
+
+### Pattern 4: Datetime Formatting for Traditional Chinese
+
+**What:** Format created_at in Blade for server-side rendering, or use JavaScript helper for client-side
+
+**When to use:** When displaying dates in JSON responses consumed by Alpine.js
+
+**Example (Blade - server-side):**
+```blade
+{{ $note->created_at->format('Y年m月d日 H:i') }}
+```
+
+**Example (Alpine.js helper - client-side):**
+```javascript
+{
+    formatDateTime(dateString) {
+        const date = new Date(dateString);
+        const year = date.getFullYear();
+        const month = String(date.getMonth() + 1).padStart(2, '0');
+        const day = String(date.getDate()).padStart(2, '0');
+        const hours = String(date.getHours()).padStart(2, '0');
+        const minutes = String(date.getMinutes()).padStart(2, '0');
+        return `${year}年${month}月${day}日 ${hours}:${minutes}`;
+    }
+}
+```
+
+**Why client-side?** Notes are fetched via AJAX, so Blade can't format them. Carbon's `toIso8601String()` provides consistent JSON serialization, then format in JavaScript.
+
+### Anti-Patterns to Avoid
+
+- **Nested x-data scopes within table rows:** Creates complexity with event bubbling and state isolation issues. Keep all row state in a single x-data on the `<tr>`.
+
+- **Fetching notes on every expand:** Wasteful if user toggles multiple times. Cache in `notes` array and use `notesLoaded` flag.
+
+- **Server-side search for small datasets:** Adds latency and requires new API endpoint. Client-side filtering with computed property is instant and simpler.
+
+- **Including panel markup in main row `<tr>`:** Breaks table semantics. Use separate `<tr>` with colspan for the expansion panel.
+
+- **Forgetting `x-cloak` on conditional content:** Causes flash of unstyled content during Alpine initialization. Add `[x-cloak] { display: none !important; }` in styles.
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Smooth height animation | Manual transition classes with max-height hacks | `@alpinejs/collapse` plugin | Official plugin handles edge cases (dynamic content height, nested animations), cleaner API |
+| AJAX wrapper | Custom fetch/promise handling | Axios (already in Laravel bootstrap) | Error handling, request/response interceptors, CSRF token auto-injection for Laravel |
+| Datetime localization | String concatenation with date parts | Carbon `->format()` on server, or built-in `Intl.DateTimeFormat` in JS | Edge cases with timezones, leap years, DST; Carbon handles locale-aware formatting |
+| Search algorithm | Custom string matching logic | Native `String.includes()` with normalization | Built-in, fast, handles Unicode edge cases; for advanced needs use fuse.js or lunr.js |
+
+**Key insight:** Alpine.js excels at enhancing server-rendered HTML with reactivity. Don't fight this by building complex client-side state synchronization—let Laravel render initial state, use Alpine for interactions only.
+
+## Common Pitfalls
+
+### Pitfall 1: Expansion Panel Breaks Table Layout
+
+**What goes wrong:** Putting panel content inside the main `<td>` distorts column widths, makes styling inconsistent
+
+**Why it happens:** HTML table layout algorithm treats content as part of the cell's intrinsic size calculation
+
+**How to avoid:** Use a separate `<tr>` immediately after the main row, with a single `<td colspan="8">` spanning all columns
+
+**Warning signs:** Uneven column widths when panel is open, horizontal scrollbar appears, adjacent rows shift
+
+**Example:**
+```html
+<!-- Main row -->
+<tr x-data="{ ... }">
+    <td>...</td>
+    <td>
+        <button @click="toggleHistory()">{{ count }}</button>
+    </td>
+    <td>...</td>
+</tr>
+
+<!-- Expansion panel - SEPARATE row -->
+<tr x-show="historyOpen" x-collapse>
+    <td colspan="8" class="bg-gray-50 dark:bg-gray-900 px-4 py-3">
+        <!-- Panel content here -->
+    </td>
+</tr>
+```
+
+### Pitfall 2: Notes Not Ordered Newest First
+
+**What goes wrong:** Notes display in random or oldest-first order, confusing for users who expect recent notes at top
+
+**Why it happens:** Eloquent returns results in database order (usually insertion order = oldest first) unless explicitly ordered
+
+**How to avoid:** Always use `->latest('created_at')` in controller, add test to verify ordering (Phase 1 already includes this test)
+
+**Warning signs:** Test `test_notes_returned_newest_first()` fails, manual testing shows oldest notes at top
+
+**Example:**
+```php
+// WRONG - no ordering
+$notes = $member->notes()->with('author')->get();
+
+// RIGHT - explicit newest first
+$notes = $member->notes()->with('author')->latest('created_at')->get();
+```
+
+### Pitfall 3: N+1 Query When Loading Authors
+
+**What goes wrong:** Loading 10 notes triggers 1 query for notes + 10 queries for authors (11 total), slow page load
+
+**Why it happens:** Lazy loading relationships fetches author individually for each note when accessed
+
+**How to avoid:** Use `->with('author')` to eager load, Laravel debugbar shows query count in development
+
+**Warning signs:** Many duplicate SELECT queries for users table, slow response time for notes endpoint
+
+**Example:**
+```php
+// WRONG - N+1 queries
+$notes = $member->notes()->latest()->get();
+// When iterating: $notes->each(fn($n) => $n->author->name) triggers N queries
+
+// RIGHT - 2 queries total
+$notes = $member->notes()->with('author')->latest()->get();
+```
+
+### Pitfall 4: Stale Note Count After Adding Note
+
+**What goes wrong:** User adds note via Phase 2 inline form, count badge updates, but history panel shows old data if already loaded
+
+**Why it happens:** Phase 2 increments `noteCount++` but doesn't update cached `notes` array in Phase 3
+
+**How to avoid:** After successful note creation in `submitNote()`, check if `notesLoaded === true`, if so, unshift new note into `notes` array
+
+**Warning signs:** Count says "3" but panel only shows 2 notes, refreshing page fixes it
+
+**Example:**
+```javascript
+async submitNote() {
+    this.isSubmitting = true;
+    try {
+        const response = await axios.post('...', { content: this.noteContent });
+        this.noteCount++;
+        this.noteContent = '';
+        this.noteFormOpen = false;
+
+        // IMPORTANT: Update cached notes if panel has been opened
+        if (this.notesLoaded) {
+            this.notes.unshift(response.data.note);  // Add to beginning (newest first)
+        }
+    } catch (error) {
+        // ...
+    } finally {
+        this.isSubmitting = false;
+    }
+}
+```
+
+### Pitfall 5: Accessibility - Missing ARIA Attributes
+
+**What goes wrong:** Screen reader users don't know button expands content, can't navigate back to collapsed state
+
+**Why it happens:** Expandable patterns require explicit ARIA attributes that aren't automatically added by Alpine.js
+
+**How to avoid:** Add `aria-expanded`, `aria-controls`, and `id` attributes to button and panel
+
+**Warning signs:** Automated accessibility testing flags missing attributes, manual testing with screen reader shows poor UX
+
+**Example:**
+```html
+<!-- Toggle button -->
+<button @click="toggleHistory()"
+        :aria-expanded="historyOpen"
+        aria-controls="notes-panel-{{ $member->id }}"
+        type="button">
+    <span x-text="noteCount"></span>
+</button>
+
+<!-- Expansion panel -->
+<tr x-show="historyOpen"
+    x-collapse
+    :id="'notes-panel-' + {{ $member->id }}">
+    <td colspan="8">...</td>
+</tr>
+```
+
+**Sources:**
+- [aria-expanded - MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded)
+- [Table with Expando Rows - Adrian Roselli](https://adrianroselli.com/2019/09/table-with-expando-rows.html)
+
+### Pitfall 6: Search Doesn't Clear When Closing Panel
+
+**What goes wrong:** User searches in panel, finds note, closes panel, reopens later—old search term still active, confusing results
+
+**Why it happens:** `searchQuery` state persists across open/close cycles
+
+**How to avoid:** Reset `searchQuery = ''` in `toggleHistory()` when closing (when `historyOpen` becomes false)
+
+**Warning signs:** Reopening panel shows filtered results without visible search query, or search input has old value
+
+**Example:**
+```javascript
+toggleHistory() {
+    this.historyOpen = !this.historyOpen;
+
+    // Clear search when closing
+    if (!this.historyOpen) {
+        this.searchQuery = '';
+    }
+
+    // Load notes when opening for first time
+    if (this.historyOpen && !this.notesLoaded) {
+        this.loadNotes();
+    }
+}
+```
+
+## Code Examples
+
+Verified patterns from official sources and existing codebase:
+
+### Alpine.js Collapse Plugin Usage
+```javascript
+// Source: https://alpinejs.dev/plugins/collapse
+<div x-data="{ expanded: false }">
+    <button @click="expanded = !expanded">Toggle</button>
+    <div x-show="expanded" x-collapse>
+        Content here
+    </div>
+</div>
+```
+
+### Laravel Latest (Newest First) with Eager Loading
+```php
+// Source: https://laravel.com/docs/10.x/pagination
+$notes = Note::with('author:id,name')
+    ->latest('created_at')  // Same as orderBy('created_at', 'desc')
+    ->get();
+```
+
+### Alpine.js Client-Side Search Pattern
+```javascript
+// Source: https://github.com/alpinejs/alpine/discussions/484
+{
+    search: '',
+    items: [...],
+
+    get filteredItems() {
+        if (!this.search) return this.items;
+        return this.items.filter(item =>
+            item.name.toLowerCase().includes(this.search.toLowerCase())
+        );
+    }
+}
+```
+
+### ARIA Expanded Pattern
+```html
+<!-- Source: https://adrianroselli.com/2019/09/table-with-expando-rows.html -->
+<button aria-expanded="false"
+        aria-controls="panel-id"
+        @click="expanded = !expanded"
+        :aria-expanded="expanded.toString()">
+    Toggle
+</button>
+<div id="panel-id" x-show="expanded">
+    Panel content
+</div>
+```
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| jQuery slideToggle() | Alpine.js x-collapse plugin | Alpine 3.x (2021) | Lighter bundle, reactive state, better DX |
+| Server-side pagination for notes | Client-side filtering | Modern SPA patterns (2020+) | Instant feedback, reduced server load |
+| Manual height transitions | x-collapse with automatic height detection | @alpinejs/collapse v3 | Handles dynamic content, smoother animations |
+| aria-hidden for hiding | x-show (uses display: none) | Alpine 3.x | Better screen reader support, x-show doesn't need aria-hidden |
+
+**Deprecated/outdated:**
+- `x-show.transition` modifier: Replaced by x-collapse plugin for height animations (x-transition is for opacity/scale)
+- Storing notes in global Alpine.store(): Per-row state is cleaner for table rows, avoids complexity
+- Using `v-if` / `v-show` from Vue.js syntax: Alpine uses `x-if` / `x-show`
+
+## Open Questions
+
+1. **Should notes be paginated on the backend?**
+   - What we know: Current API returns all notes with `->get()`, client-side filtering requires all data
+   - What's unclear: If a member could have 100+ notes, would pagination be needed?
+   - Recommendation: Start without pagination (simpler UX, matches requirement DISP-04 "search within member's history"). Add pagination later if performance issue emerges in real usage. Consider limit of 50 notes per member as reasonable threshold.
+
+2. **Should the expansion panel be a separate Blade component?**
+   - What we know: Current member list has all markup inline in `index.blade.php`, panel adds ~50 lines of markup
+   - What's unclear: Project preference for inline vs. extracted partials
+   - Recommendation: Start inline for simplicity (keeps all row logic in one file), extract to `partials/note-history-panel.blade.php` if it grows beyond 100 lines or if reused elsewhere.
+
+3. **Should datetime formatting use JavaScript Intl.DateTimeFormat or manual formatting?**
+   - What we know: Project uses `->format('Y年m月d日 H:i')` pattern in Blade (seen in documents views)
+   - What's unclear: Whether to replicate this exact format in JavaScript or use Intl API
+   - Recommendation: Use manual formatting helper to match existing project style (`2026年02月13日 14:30`), ensures consistency with server-rendered dates. Intl API would be more flexible for future i18n but adds complexity.
+
+## Sources
+
+### Primary (HIGH confidence)
+- [Alpine.js Collapse Plugin Official Docs](https://alpinejs.dev/plugins/collapse) - x-collapse usage, modifiers
+- [Laravel 10.x Pagination Docs](https://laravel.com/docs/10.x/pagination) - orderBy, latest, pagination patterns
+- [Alpine.js Transition Directive](https://alpinejs.dev/directives/transition) - x-show animations
+- Existing codebase:
+  - `/Users/gbanyan/Project/usher-manage-stack/app/Http/Controllers/Admin/MemberNoteController.php` - Current API structure
+  - `/Users/gbanyan/Project/usher-manage-stack/resources/views/admin/members/index.blade.php` - Phase 2 Alpine.js patterns
+  - `/Users/gbanyan/Project/usher-manage-stack/tests/Feature/Admin/MemberNoteTest.php` - Test coverage, ordering expectations
+
+### Secondary (MEDIUM confidence)
+- [Adrian Roselli - Table with Expando Rows](https://adrianroselli.com/2019/09/table-with-expando-rows.html) - Accessibility best practices verified with MDN ARIA docs
+- [MDN ARIA: aria-expanded](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-expanded) - Official W3C attribute specification
+- [Alpine.js GitHub Discussion #484 - Search Multiple Keys](https://github.com/alpinejs/alpine/discussions/484) - Community pattern for client-side search
+- [Raymond Camden - Table Sorting and Pagination in Alpine.js](https://www.raymondcamden.com/2022/05/02/building-table-sorting-and-pagination-in-alpinejs) - Practical implementation examples
+
+### Tertiary (LOW confidence)
+- Alpine Toolbox examples - Community-contributed patterns (useful for inspiration, verify before using)
+- GitHub search results for Alpine.js table patterns - Various implementations, quality varies
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH - Alpine.js 3.4.2 already in use, @alpinejs/collapse is official plugin, Laravel patterns are documented
+- Architecture: HIGH - Patterns verified in existing codebase (Phase 1 & 2), official docs confirm syntax
+- Pitfalls: MEDIUM to HIGH - Expansion panel layout and N+1 queries are well-known issues (HIGH), ARIA patterns verified with official specs (HIGH), stale cache sync is inferred from Alpine reactivity model (MEDIUM)
+
+**Research date:** 2026-02-13
+**Valid until:** ~30 days (Alpine.js and Laravel 10 are stable, no breaking changes expected)