363 lines
16 KiB
Markdown
363 lines
16 KiB
Markdown
# Dashboard: My Flows, Favorites/Pin UI, and AI Builder in Create Menu
|
|
|
|
## Final Implementation Plan (Reviewed & Merged)
|
|
|
|
### Decisions Locked
|
|
|
|
1. **"My Flows"** = trees where `author_id = currentUser.id` (includes forks, since forks set the forking user as author).
|
|
2. **Pagination** = `Prev / Next` with page-size selector (10 / 25 / 50 / All). No numbered total pages — the `/trees` API returns no total count. Page and page size are synced to URL query params (`?page=3&size=25`).
|
|
3. **Pin state** = shared Zustand store (`pinnedFlowsStore`), used by Sidebar, Dashboard, and Library. No local state for pins anywhere. **This store owns pin CRUD only — no other state belongs here.**
|
|
4. **"Show: All"** = fetches in chunks of 100, capped at 500 items maximum. If ceiling is reached, show message: "Showing first 500 flows. Use search or filters to find specific flows."
|
|
5. **Dashboard view preference** = separate key (`dashboardMyFlowsView`) from Library view preference. The two are independent.
|
|
6. **Sidebar pinned section** = two independent collapse states: header collapse (hide/show entire section) and list truncation (5 vs. all). When header is collapsed and re-expanded, list resets to 5 items (truncated default).
|
|
7. **Max pins** = 15, enforced by backend. Frontend handles 409 conflict with user-facing toast.
|
|
8. **AI Builder quota** = cached with 5-minute TTL. Not re-fetched on every page load.
|
|
9. **Favorites layout** = compact wrapping grid, max 2 rows (~8 cards visible). "View all" expand link if more than 8 pinned flows.
|
|
10. **Loading states** = skeleton loaders for both Favorites and My Flows sections during initial fetch. Meaningful empty states with CTAs for new users.
|
|
11. **Accessibility** = all pin/favorite buttons include `aria-label` (dynamic: "Add to favorites" / "Remove from favorites"), `e.stopPropagation()`, and `e.preventDefault()`.
|
|
|
|
### Known API Constraints (No Backend Changes)
|
|
|
|
- `GET /trees` returns `TreeListItem[]` with no total count metadata. Pagination uses `skip` + `limit` params (max `limit` is 100).
|
|
- `POST /trees/{id}/pin`, `DELETE /trees/{id}/pin`, `GET /trees/pinned`, `PATCH /trees/pinned/reorder` all exist and work.
|
|
- `pinnedFlowsApi` already has `list()` and `unpin()`. Needs `pin()` added.
|
|
- Backend enforces `MAX_PINNED_FLOWS=15` and returns 409 on conflict.
|
|
|
|
### Files Modified
|
|
|
|
| File | Phase | Change |
|
|
|------|-------|--------|
|
|
| `frontend/src/api/pinnedFlows.ts` | 1 | Add `pin()` method |
|
|
| `frontend/src/store/pinnedFlowsStore.ts` | 1 | **New file.** Zustand store — single source of truth for all pin state |
|
|
| `frontend/src/store/userPreferencesStore.ts` | 1 | Add `dashboardMyFlowsView` preference + setter |
|
|
| `frontend/src/hooks/usePaginationParams.ts` | 1 | **New file.** Custom hook — reads/writes `page` and `size` URL query params |
|
|
| `frontend/src/hooks/useCachedQuota.ts` | 1 | **New file.** Custom hook — fetches AI quota with 5-min TTL cache |
|
|
| `frontend/src/components/layout/Sidebar.tsx` | 1 | Replace local pinned state with `pinnedFlowsStore` selectors |
|
|
| `frontend/src/components/library/TreeGridView.tsx` | 2 | Add optional pin props + star button with aria-label |
|
|
| `frontend/src/components/library/TreeListView.tsx` | 2 | Add optional pin props + star button with aria-label |
|
|
| `frontend/src/components/library/TreeTableView.tsx` | 2 | Add optional pin props + star/favorite column with aria-label |
|
|
| `frontend/src/pages/TreeLibraryPage.tsx` | 3 | Replace Create link with dropdown menu + AI Builder (cached quota) + wire pin store |
|
|
| `frontend/src/pages/QuickStartPage.tsx` | 4 | Major refactor: Favorites grid + paginated My Flows + skeletons + empty states |
|
|
| `frontend/src/components/sidebar/PinnedFlowsSection.tsx` | 5 | Dual collapse states + reset-on-reexpand + auto-collapse on navigation |
|
|
|
|
---
|
|
|
|
### Phase 1: Infrastructure (Stores, Hooks, API)
|
|
|
|
**Goal:** Build the shared state and utility layers that every subsequent phase depends on.
|
|
|
|
#### 1a. Add `pin()` to API client
|
|
|
|
**File:** `frontend/src/api/pinnedFlows.ts`
|
|
|
|
```typescript
|
|
pin: async (treeId: string) => apiClient.post(`/trees/${treeId}/pin`)
|
|
```
|
|
|
|
#### 1b. Create `pinnedFlowsStore`
|
|
|
|
**File:** `frontend/src/store/pinnedFlowsStore.ts` (new)
|
|
|
|
State:
|
|
- `items: PinnedFlow[]` — the pinned flows list
|
|
- `isLoaded: boolean` — whether initial fetch has completed
|
|
- `isLoading: boolean` — whether initial fetch is in progress
|
|
- `isMutatingByTreeId: Record<string, boolean>` — per-tree mutation tracking
|
|
- `error: string | null`
|
|
|
|
Actions:
|
|
- `load(force?: boolean)` — fetch from API. Skip if `isLoaded` unless `force=true`.
|
|
- `pin(treeId: string)` — optimistic add to `items`, call API, rollback + toast on failure. On 409: toast "Maximum of 15 favorites reached. Unpin a flow to add a new one." and do not add to items.
|
|
- `unpin(treeId: string)` — optimistic remove from `items`, call API, rollback + toast on failure.
|
|
- `toggle(treeId: string)` — calls `pin` or `unpin` based on current state.
|
|
|
|
Derived:
|
|
- `isPinned(treeId: string): boolean`
|
|
- `pinnedTreeIds: Set<string>` — for passing as prop to view components
|
|
- `pinLoadingTreeIds: Set<string>` — derived from `isMutatingByTreeId` for disabling buttons
|
|
|
|
**Scope guardrail:** This store owns pin CRUD and derived pin state only. Dashboard layout preferences belong in `userPreferencesStore`. Recently viewed flows or other concerns belong in separate stores/hooks.
|
|
|
|
#### 1c. Replace local pin state in Sidebar
|
|
|
|
**File:** `frontend/src/components/layout/Sidebar.tsx`
|
|
|
|
- Remove local `useState` / `useEffect` for pinned flows (currently mount-only fetch)
|
|
- Import and use `usePinnedFlowsStore` selectors and actions
|
|
- Call `pinnedFlowsStore.load()` on mount (store handles deduplication)
|
|
|
|
#### 1d. Add dashboard view preference
|
|
|
|
**File:** `frontend/src/store/userPreferencesStore.ts`
|
|
|
|
- New field: `dashboardMyFlowsView: 'grid' | 'list' | 'table'` (default: `'grid'`)
|
|
- New setter: `setDashboardMyFlowsView`
|
|
- Persisted to localStorage alongside existing preferences
|
|
- This is independent from the existing `treeLibraryView` preference
|
|
|
|
#### 1e. Create pagination params hook
|
|
|
|
**File:** `frontend/src/hooks/usePaginationParams.ts` (new)
|
|
|
|
A reusable hook that syncs pagination state to URL query params:
|
|
|
|
```typescript
|
|
// Usage:
|
|
const { page, pageSize, setPage, setPageSize } = usePaginationParams({
|
|
defaultPageSize: 10,
|
|
allowedPageSizes: [10, 25, 50, 'all'],
|
|
})
|
|
// URL: /dashboard?page=2&size=25
|
|
// Handles: invalid values (falls back to defaults), page reset when size changes
|
|
```
|
|
|
|
Behavior:
|
|
- Reads `page` and `size` from URL search params on mount
|
|
- Falls back to defaults if missing or invalid
|
|
- `setPageSize` resets `page` to 1 (changing page size while on page 3 is confusing)
|
|
- Validates `page` is a positive integer, `size` is one of the allowed values
|
|
- Uses `useSearchParams` from React Router
|
|
|
|
#### 1f. Create cached quota hook
|
|
|
|
**File:** `frontend/src/hooks/useCachedQuota.ts` (new)
|
|
|
|
```typescript
|
|
// Usage:
|
|
const { aiEnabled, isLoading } = useCachedQuota()
|
|
```
|
|
|
|
Behavior:
|
|
- On first call, fetches `aiBuilderApi.getQuota()`
|
|
- Caches result in module-level variable with timestamp
|
|
- Subsequent calls within 5 minutes return cached value (no API call)
|
|
- After 5 minutes, re-fetches on next call
|
|
- Returns `{ aiEnabled: boolean, isLoading: boolean }`
|
|
|
|
---
|
|
|
|
### Phase 2: Pin/Unpin Controls in Library Views
|
|
|
|
**Goal:** Add favorite buttons to all three view components without breaking existing behavior.
|
|
|
|
**Files:** `TreeGridView.tsx`, `TreeListView.tsx`, `TreeTableView.tsx`
|
|
|
|
#### New optional props on all three:
|
|
|
|
```typescript
|
|
pinnedTreeIds?: Set<string>
|
|
onTogglePin?: (treeId: string) => void
|
|
pinLoadingTreeIds?: Set<string>
|
|
```
|
|
|
|
Props are optional so these components remain backward-compatible with any page that doesn't use pins.
|
|
|
|
#### Pin button pattern (all three views):
|
|
|
|
```tsx
|
|
<button
|
|
onClick={(e) => {
|
|
e.stopPropagation();
|
|
e.preventDefault();
|
|
onTogglePin?.(treeId);
|
|
}}
|
|
disabled={pinLoadingTreeIds?.has(treeId)}
|
|
aria-label={pinnedTreeIds?.has(treeId) ? "Remove from favorites" : "Add to favorites"}
|
|
className={/* reduced opacity when disabled */}
|
|
>
|
|
{pinnedTreeIds?.has(treeId) ? <StarFilledIcon /> : <StarOutlineIcon />}
|
|
</button>
|
|
```
|
|
|
|
#### View-specific placement:
|
|
- **Grid:** Star icon in top-right corner of card
|
|
- **List:** Star icon at the end of each row
|
|
- **Table:** Dedicated narrow "Favorite" column (leftmost)
|
|
|
|
**Critical:** `e.stopPropagation()` + `e.preventDefault()` prevents the click from triggering card/row navigation. Button is disabled (reduced opacity, no pointer events) while that tree's mutation is in-flight.
|
|
|
|
---
|
|
|
|
### Phase 3: TreeLibraryPage — Create Menu + Pin Wiring
|
|
|
|
**Goal:** Add AI Builder access and connect Library page to shared pin store.
|
|
|
|
**File:** `frontend/src/pages/TreeLibraryPage.tsx`
|
|
|
|
#### 3a. Replace Create link with dropdown
|
|
|
|
Replace the single `<Link>` create button with a dropdown menu (same visual pattern as `MyTreesPage`'s `showCreateMenu`).
|
|
|
|
Menu items (fixed order):
|
|
1. Troubleshooting Tree
|
|
2. Procedural Flow
|
|
3. Maintenance Flow
|
|
4. `<divider>`
|
|
5. Build with AI *(only shown when `aiEnabled` is true)*
|
|
|
|
#### 3b. AI Builder integration
|
|
|
|
- Use `useCachedQuota()` hook (from Phase 1f) — no fetch-on-mount, uses cached value
|
|
- Import and render `AIFlowBuilderModal` (already built)
|
|
- Modal state: `showAIBuilder` boolean, toggled by menu item click
|
|
|
|
#### 3c. Wire view components to pin store
|
|
|
|
- Import `usePinnedFlowsStore`
|
|
- Call `store.load()` on mount
|
|
- Pass `pinnedTreeIds`, `onTogglePin: store.toggle`, and `pinLoadingTreeIds` to active view component
|
|
|
|
---
|
|
|
|
### Phase 4: QuickStartPage Refactor — Favorites + My Flows
|
|
|
|
**Goal:** Transform the dashboard from a flat "All Flows" dump into a structured personal workspace.
|
|
|
|
**File:** `frontend/src/pages/QuickStartPage.tsx`
|
|
|
|
#### 4a. Favorites Section (above My Flows)
|
|
|
|
**Layout:** Compact wrapping grid. Max 2 visible rows (~8 cards). If more than 8 pinned flows, show "View all favorites" link that expands to show all.
|
|
|
|
**Data source:** `pinnedFlowsStore.items`, ordered by `display_order`.
|
|
|
|
**Each card:** Click to navigate + unpin button (star icon, same pattern as Phase 2).
|
|
|
|
**Section header:** "Favorites" with count badge (e.g., "Favorites (7)").
|
|
|
|
**Loading state:** Skeleton loader — 4 placeholder cards with pulse animation, matching the grid layout dimensions so content doesn't shift when data arrives.
|
|
|
|
**Empty state:** Subtle message: "Star a flow to pin it here for quick access." No CTA button — the action is contextual (you star flows from the Library or My Flows).
|
|
|
|
#### 4b. My Flows Section (replaces "All Flows")
|
|
|
|
**Section header:** "My Flows"
|
|
|
|
**Data source:** `treesApi.list({ author_id: currentUser.id, sort_by: 'updated_at', skip, limit })`
|
|
|
|
**Pagination (via `usePaginationParams` hook):**
|
|
- Page size selector: dropdown with 10 (default), 25, 50, All
|
|
- For numeric sizes:
|
|
```typescript
|
|
// Request one extra item to detect if there's a next page.
|
|
// If response.length > pageSize, a next page exists.
|
|
// We only display the first `pageSize` items.
|
|
const response = await treesApi.list({
|
|
author_id: currentUser.id,
|
|
limit: pageSize + 1,
|
|
skip: (page - 1) * pageSize,
|
|
});
|
|
const hasNextPage = response.length > pageSize;
|
|
const displayItems = response.slice(0, pageSize);
|
|
```
|
|
- For "All": fetch in chunks of 100 (`skip=0, limit=100`, then `skip=100`, etc.) until response returns fewer than 100 items OR 500 items total reached. If ceiling hit, show: "Showing first 500 flows. Use search or filters to find specific flows."
|
|
- Controls: `Prev` (disabled on page 1) / `Next` (disabled when `!hasNextPage`) / current page label / size dropdown
|
|
- URL synced: `?page=2&size=25` — changing page size resets to page 1
|
|
|
|
**View toggle:** Reuse `ViewToggle` component, bound to `dashboardMyFlowsView` preference (independent from Library).
|
|
|
|
**Render:** Pass `TreeGridView` / `TreeListView` / `TreeTableView` with pin props from store.
|
|
|
|
**Loading state:** Skeleton loader — 6 placeholder cards/rows matching the active view type (grid skeleton for grid view, row skeletons for list/table view).
|
|
|
|
**Empty state:** "You haven't created any flows yet." with a CTA button: "Create your first flow" that triggers the Create dropdown menu (same options as TreeLibraryPage: Troubleshooting Tree, Procedural Flow, Maintenance Flow, divider, Build with AI).
|
|
|
|
#### 4c. Cleanup
|
|
|
|
- Remove the current hard-cap of 20 items
|
|
- Remove the "All Flows" `SectionGroup` wrapper
|
|
- Keep existing stats cards, recent sessions, and search panels unless explicitly removed later
|
|
|
|
---
|
|
|
|
### Phase 5: Sidebar PinnedFlowsSection — Dual Collapse
|
|
|
|
**Goal:** Make the sidebar pinned section polished without taking over the sidebar.
|
|
|
|
**File:** `frontend/src/components/sidebar/PinnedFlowsSection.tsx`
|
|
|
|
#### Two independent collapse states:
|
|
|
|
1. **Header collapse:** Click section header → hides/shows entire pinned flows area (existing behavior, keep it). When re-expanding after a collapse, **always reset list truncation to 5 items.**
|
|
|
|
2. **List truncation:** When section is expanded:
|
|
- Show first 5 pinned flows by default
|
|
- "Show more (X)" link at bottom expands to show all (X = total count)
|
|
- "Show less" link collapses back to 5
|
|
- Clicking a pinned flow link: navigate AND auto-collapse back to 5
|
|
|
|
#### Smooth transitions:
|
|
|
|
- CSS `max-height` transition on the list container: `transition: max-height 250ms ease-out`
|
|
- Keep it subtle — no dramatic animations
|
|
|
|
---
|
|
|
|
### Test Cases
|
|
|
|
#### `pinnedFlowsStore` unit tests:
|
|
- `load()` populates `items` from API
|
|
- `load()` skips fetch when `isLoaded=true` (unless `force=true`)
|
|
- `toggle()` pins an unpinned tree, unpins a pinned tree
|
|
- Optimistic update: `items` updates immediately before API resolves
|
|
- Rollback: `items` reverts if API call fails
|
|
- 409 conflict: shows error toast, does not add to `items`
|
|
- Sidebar + Dashboard selectors reflect same state after mutation
|
|
- `pinnedTreeIds` derived set updates correctly
|
|
|
|
#### `usePaginationParams` hook tests:
|
|
- Reads `page` and `size` from URL on mount
|
|
- Falls back to defaults when URL params missing or invalid
|
|
- `setPageSize` resets page to 1
|
|
- Invalid page (negative, zero, non-number) falls back to 1
|
|
|
|
#### `useCachedQuota` hook tests:
|
|
- First call fetches from API
|
|
- Second call within 5 minutes returns cached value (no API call)
|
|
- Call after 5 minutes re-fetches
|
|
|
|
#### `PinnedFlowsSection` component tests:
|
|
- Shows max 5 items by default
|
|
- "Show more" reveals all items
|
|
- Clicking a flow collapses list back to 5
|
|
- Header collapse hides entire section
|
|
- Re-expanding after header collapse resets to 5 items
|
|
|
|
#### `QuickStartPage` integration tests:
|
|
- My Flows uses `author_id` filter
|
|
- Numeric page size: requests `limit=size+1`, displays `size` results
|
|
- "All" fetches iteratively, stops at 500 ceiling
|
|
- Favorites section updates immediately after pin/unpin
|
|
- Empty state shows CTA when user has zero flows
|
|
- Skeleton loaders appear during fetch
|
|
- URL params update when page/size changes
|
|
|
|
#### `TreeLibraryPage` tests:
|
|
- Create dropdown renders all flow type options
|
|
- "Build with AI" only shown when `aiEnabled=true`
|
|
- "Build with AI" opens `AIFlowBuilderModal`
|
|
- Pin buttons work and sync with store
|
|
|
|
#### Regression:
|
|
- `cd frontend && npm run test`
|
|
- `cd frontend && npm run build`
|
|
|
|
### Manual Verification Checklist
|
|
|
|
- [ ] Dashboard: Favorites section shows pinned flows in compact grid, My Flows shows paginated authored flows
|
|
- [ ] Pin a flow on Library page → appears in Dashboard Favorites AND Sidebar immediately (no navigation)
|
|
- [ ] Unpin from Dashboard → removed from Sidebar immediately
|
|
- [ ] Page size dropdown: 10/25/50/All all work, Prev/Next show/hide correctly
|
|
- [ ] "Show All" stops at 500 items with message if ceiling hit
|
|
- [ ] Change page → URL updates to `?page=X&size=Y`. Refresh → same page/size restored.
|
|
- [ ] View toggle on Dashboard is independent from Library view toggle
|
|
- [ ] Sidebar: max 5 shown, "Show more" expands, clicking a flow collapses and navigates
|
|
- [ ] Collapse sidebar section → re-expand → list is back to 5 (not "show all")
|
|
- [ ] Try to pin a 16th flow → toast about max limit, flow not pinned
|
|
- [ ] AI Builder: Library page "Create New" → "Build with AI" opens modal (uses cached quota)
|
|
- [ ] New user with zero flows: sees empty state with "Create your first flow" CTA
|
|
- [ ] New user with zero favorites: sees "Star a flow to pin it here" message
|
|
- [ ] During initial load: skeleton placeholders visible, no layout shift when data arrives
|
|
- [ ] Pin button: screen reader announces "Add to favorites" / "Remove from favorites"
|
|
- [ ] Build passes: `cd frontend && npm run build` with no errors
|