Max Litruv Boonzaayer
e058165830
Bump Vite 8, matrix-js-sdk, and related deps; fix immer/vanilla-extract imports for new majors. Replace blocking sync error dialog with background recovery on wake/offline, and disable Vite auto-open in dev. Add feature handoff documentation index.
106 lines
4.0 KiB
Markdown
106 lines
4.0 KiB
Markdown
# Forum spaces — handoff
|
|
|
|
## Summary
|
|
|
|
Forum spaces provide a board-style UI for `m.forum` rooms and `forum_space` room kinds: topic sections, post feeds, thread detail, rich replies, filters, and dedicated composers. This is a large Paarrot-specific feature area separate from the card-based **Lobby** view.
|
|
|
|
## User-facing behavior
|
|
|
|
- Forum spaces open to a **feed** of posts (not the lobby card grid)
|
|
- Sections group topics (child rooms / subspaces)
|
|
- Create posts with title + rich body; threaded replies
|
|
- Board detail view, thread detail, topic search/filter bar
|
|
- Distinct composers: new post, reply, chat-style
|
|
|
|
## Architecture
|
|
|
|
```
|
|
ForumAwareSpaceLayout / ForumSpaceLayout
|
|
→ ForumFeedPage (feed sidebar + post list)
|
|
→ ForumBoardDetail / ForumThreadDetail
|
|
→ forumFeed.ts (aggregate posts from topic rooms)
|
|
→ forumTopicHelpers, forumRichText, topicSearch
|
|
Hooks: useForumBoard, useForumRoomLiveUpdates, useForumMessageReactions
|
|
```
|
|
|
|
Routing: `getSpaceDefaultPath` + `shouldShowForumLobby` in path utils / room utils.
|
|
|
|
## Key files
|
|
|
|
| Path | Role |
|
|
|------|------|
|
|
| `cinny/src/app/features/forum/ForumFeedPage.tsx` | Main feed page |
|
|
| `cinny/src/app/features/forum/ForumSpaceLayout.tsx` | Layout shell |
|
|
| `cinny/src/app/features/forum/ForumAwareSpaceLayout.tsx` | Forum vs non-forum switch |
|
|
| `cinny/src/app/features/forum/forumFeed.ts` | Post aggregation, root detection |
|
|
| `cinny/src/app/features/forum/types.ts` | ForumTopic, ForumPost, etc. |
|
|
| `cinny/src/app/features/forum/ForumBoardView.tsx` | Board listing |
|
|
| `cinny/src/app/features/forum/ForumThreadDetail.tsx` | Thread view |
|
|
| `cinny/src/app/features/forum/ForumNewPostModal.tsx` | Create post |
|
|
| `cinny/src/app/features/forum/ForumReplyComposer.tsx` | Replies |
|
|
| `cinny/src/app/features/forum/useForumBoard.ts` | Board data hook |
|
|
| `cinny/src/app/features/forum/useForumRoomLiveUpdates.ts` | Live timeline sync |
|
|
| `cinny/src/app/pages/pathUtils.ts` | Forum routing |
|
|
|
|
## Data model
|
|
|
|
| Signal | Purpose |
|
|
|--------|---------|
|
|
| `m.room.create` `type: m.forum` | Matrix forum room type |
|
|
| `im.paarrot.room.kind: forum_space` | Paarrot forum classification |
|
|
| `com.matrixsso.title` on messages | Forum post title (legacy/custom) |
|
|
| `formatted_body` with `<h1>` | Root post detection |
|
|
| `m.relates_to` threads | Replies and edits |
|
|
| `im.paarrot.sub_rooms` | Topic room hierarchy (see sub-rooms) |
|
|
|
|
## Dependencies
|
|
|
|
- `matrix-js-sdk` relations, threads, space hierarchy
|
|
- Rich text / Slate editor integration for composers
|
|
- Embed filters via `useForumMessageRenderOptions.ts`
|
|
|
|
## Integration points
|
|
|
|
- **lobby-forums**: routing chooses forum feed vs lobby
|
|
- **sub-rooms**: topic rooms may be sub-rooms
|
|
- **embed-filters**: forum message render options
|
|
- **local-api**: `isSpaceLikeRoom` treats forum as space-like
|
|
|
|
## Testing
|
|
|
|
### Manual
|
|
|
|
1. Open a `m.forum` space; verify feed UI loads.
|
|
2. Create post with title; verify appears in feed and topic room.
|
|
3. Reply in thread; verify counts and detail view.
|
|
4. Filter/search topics; verify results.
|
|
5. Compare behavior with `forum_space` room kind.
|
|
|
|
### Automated
|
|
|
|
- None
|
|
|
|
## Known issues & gotchas
|
|
|
|
- Root post detection uses **two** heuristics: `com.matrixsso.title` and `<h1>` in formatted_body
|
|
- Large `forumFeed.ts` — main complexity hotspot
|
|
- Forum vs lobby split scattered across path utils and layout components
|
|
- Edit/replace relations need careful handling (`isAnnotationRoomMessage`)
|
|
|
|
## Future work
|
|
|
|
- Standardize on one title field (MSC alignment)
|
|
- Unit tests for `isForumRootContent` and feed aggregation
|
|
- Performance for large spaces (pagination)
|
|
|
|
## Related docs
|
|
|
|
- [lobby-forums HANDOFF](../lobby-forums/HANDOFF.md) — lobby card UI vs forum feed routing
|
|
- [sub-rooms HANDOFF](../sub-rooms/HANDOFF.md)
|
|
- [embed-filters HANDOFF](../embed-filters/HANDOFF.md)
|
|
|
|
## Add your extra things here
|
|
|
|
- ~40 files under `features/forum/` — start with `forumFeed.ts` and `ForumFeedPage.tsx` when onboarding
|
|
- `annotatePostsWithRoomScope` in `forumTopicHelpers.ts` for cross-topic feed display
|