Initial Commit
This commit is contained in:
119
openspec/changes/enterprise-react-social/proposal.md
Normal file
119
openspec/changes/enterprise-react-social/proposal.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# OpenSpec Change: enterprise-react-social
|
||||
|
||||
- **Change ID**: enterprise-react-social
|
||||
- **Package**: `@suaveplan/react-social`
|
||||
- **Category**: react
|
||||
- **Target path**: `react/social/react-social`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-social.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/react-social` on genesis from scratch at enterprise quality. A bring-your-own-transport social stack: `SocialProvider` context, feed components (`Feed`, `CreatePost`), chat components (`ChatWindow`, `ConversationList`, `MessageInput`, `MessageList`), hooks (`useFeed`, `usePost`, `useChat`, `useConversations`, `useMessages`), and a plugin system (`BasePlugin`, `PluginManager`, `ChatPlugin`) backed by `ConnectionManager`, `FeedManager`, `PostManager`, `ConversationManager`, and `MessageManager`. Genesis adds full unit test coverage (main branch shipped with 0% coverage), Storybook for every component, explicit index re-exports, rich-text and media post composing, moderation plugin, and Playwright E2E.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
Package does not exist on genesis — fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `SocialError` |
|
||||
| `@suaveplan/events` (`workspace:^`) | Pub/sub transport |
|
||||
| `@suaveplan/logger` (`workspace:^`) | Structured logging |
|
||||
| `@suaveplan/react-translate` (`workspace:^`) | i18n for all UI strings |
|
||||
| `@suaveplan/react-ui` (`workspace:^`) | Radix primitives |
|
||||
| `@suaveplan/react-rich-text` (`workspace:^`) | Rich post composer |
|
||||
| `@suaveplan/react-infinite-scroll` (`workspace:^`) | Feed + conversation list |
|
||||
| `@suaveplan/react-image` (`workspace:^`) | Media post preview |
|
||||
| `@suaveplan/data-masking` (`workspace:^`) | Moderation plugin |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
|
||||
| `zod` (`catalog:forms`) | Schema validation |
|
||||
| `tslib` (`catalog:build`) | TS helpers |
|
||||
|
||||
External: React 18 peer.
|
||||
|
||||
---
|
||||
|
||||
## Preserved public API surface
|
||||
|
||||
```ts
|
||||
// Context
|
||||
SocialProvider, useSocial
|
||||
|
||||
// Feed
|
||||
Feed, CreatePost
|
||||
useFeed, usePost
|
||||
FeedManager, PostManager
|
||||
|
||||
// Chat
|
||||
ChatWindow, ConversationList, MessageInput, MessageList
|
||||
useChat, useConversations, useMessages
|
||||
ConversationManager, MessageManager, ChatPlugin
|
||||
|
||||
// Plugins
|
||||
BasePlugin, PluginManager
|
||||
|
||||
// Services
|
||||
ConnectionManager, SocialClient
|
||||
|
||||
// Types
|
||||
SocialPost, SocialComment, SocialReaction, MentionItem,
|
||||
FeedOptions, PostOptions, ChatMessage, ConversationSummary,
|
||||
SocialProviderProps, FeedProps, CreatePostProps, ChatWindowProps,
|
||||
ConversationListProps, MessageInputProps, MessageListProps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **`SocialError`** — codes: `SOCIAL_CONNECTION_FAILED`, `SOCIAL_POST_FAILED`, `SOCIAL_SEND_FAILED`.
|
||||
2. **100% test coverage** — all services, hooks, components, and plugins.
|
||||
3. **Storybook coverage** — stories for `Feed`, `CreatePost`, `ChatWindow`, `ConversationList`, `MessageInput`, `MessageList`, plus hooks playground.
|
||||
4. **Explicit re-exports** — no `export *` in `index.ts`.
|
||||
5. **Rich-text composer** — `CreatePost` integrates `@suaveplan/react-rich-text`.
|
||||
6. **Infinite scroll** — `Feed` and `ConversationList` use `@suaveplan/react-infinite-scroll`.
|
||||
7. **Moderation plugin** — block/report/profanity-filter via `@suaveplan/data-masking`.
|
||||
8. **Realtime presence** — typing indicators, online status, read receipts via `ConnectionManager`.
|
||||
9. **Playwright E2E** — post create, comment, DM send, typing indicator, read receipt.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
react/social/react-social/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
types/
|
||||
context/
|
||||
social-provider/ (tsx + types + md + test + index)
|
||||
components/
|
||||
feed/ (tsx + types + md + test + stories + index)
|
||||
create-post/ (tsx + types + md + test + stories + index)
|
||||
chat-window/ (tsx + types + md + test + stories + index)
|
||||
conversation-list/ (tsx + types + md + test + stories + index)
|
||||
message-input/ (tsx + types + md + test + stories + index)
|
||||
message-list/ (tsx + types + md + test + stories + index)
|
||||
hooks/
|
||||
use-feed/ use-post/ use-chat/ use-conversations/ use-messages/
|
||||
services/
|
||||
connection-manager/ feed-manager/ post-manager/
|
||||
conversation-manager/ message-manager/ social-client/
|
||||
plugins/
|
||||
base-plugin/ plugin-manager/ chat-plugin/ moderation-plugin/
|
||||
e2e/
|
||||
social.spec.ts
|
||||
```
|
||||
142
openspec/changes/enterprise-react-social/tasks.md
Normal file
142
openspec/changes/enterprise-react-social/tasks.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# Tasks: enterprise-react-social
|
||||
|
||||
**Change ID**: enterprise-react-social
|
||||
**Package**: `@suaveplan/react-social`
|
||||
**Target path**: `react/social/react-social`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/react-translate`, `@suaveplan/react-ui`, `@suaveplan/react-rich-text`, `@suaveplan/react-infinite-scroll`, `@suaveplan/react-image`, `@suaveplan/data-masking`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create directory tree. Write `package.json` at `0.1.0`, `tsconfig.json`, `vitest.config.ts`, scripts.
|
||||
- [ ] Dependencies: `@suaveplan/error workspace:^`, `@suaveplan/events workspace:^`, `@suaveplan/logger workspace:^`, `@suaveplan/react-translate workspace:^`, `@suaveplan/react-ui workspace:^`, `@suaveplan/react-rich-text workspace:^`, `@suaveplan/react-infinite-scroll workspace:^`, `@suaveplan/react-image workspace:^`, `@suaveplan/data-masking workspace:^`, `@opentelemetry/api catalog:observability`, `zod catalog:forms`, `tslib catalog:build`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Error codes and types
|
||||
|
||||
- [ ] Define `SocialError`; codes: `SOCIAL_CONNECTION_FAILED`, `SOCIAL_POST_FAILED`, `SOCIAL_SEND_FAILED`.
|
||||
- [ ] Define all types: `SocialPost`, `SocialComment`, `SocialReaction`, `MentionItem`, `FeedOptions`, `PostOptions`, `ChatMessage`, `ConversationSummary`, `SocialProviderProps`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Services
|
||||
|
||||
- [ ] `ConnectionManager` — WebSocket relay adapter with typing indicators, online status, read receipts. Throws `SocialError(SOCIAL_CONNECTION_FAILED)`.
|
||||
- [ ] `FeedManager` — CRUD feed posts; pluggable ranker (chronological/algorithmic).
|
||||
- [ ] `PostManager` — create/update/delete posts, reactions, comments, mentions.
|
||||
- [ ] `ConversationManager` — conversation list with unread counts.
|
||||
- [ ] `MessageManager` — DM send/receive with optimistic updates and rollback.
|
||||
- [ ] `SocialClient` — top-level orchestrator wiring all managers to `ConnectionManager`.
|
||||
- [ ] Write `services.test.ts` (≤500 lines): connection lifecycle, feed CRUD, post reactions, DM round-trip, presence events. `{ timeout: 10000 }`.
|
||||
- [ ] Write `.md` for each service.
|
||||
|
||||
---
|
||||
|
||||
## 4. Plugins
|
||||
|
||||
- [ ] `BasePlugin` — abstract plugin with `name`, `install(manager)`, `uninstall()`.
|
||||
- [ ] `PluginManager` — registry with `register`/`unregister`/`emit`.
|
||||
- [ ] `ChatPlugin` — extends `BasePlugin`; hooks into `MessageManager` for chat-specific events.
|
||||
- [ ] `ModerationPlugin` — block-list, report, profanity filter via `@suaveplan/data-masking`.
|
||||
- [ ] Write `plugins.test.ts` (≤500 lines): install/uninstall, emit propagation, moderation filter. `{ timeout: 5000 }`.
|
||||
- [ ] Write `.md` for each plugin.
|
||||
|
||||
---
|
||||
|
||||
## 5. Context
|
||||
|
||||
### SocialProvider
|
||||
|
||||
- [ ] Provides `SocialClient`, `ConnectionManager`, plugin registry via React context. Accepts `transport`, `plugins[]`, `userId`.
|
||||
- [ ] `useSocial()` hook to consume context; throws `SocialError` if used outside provider.
|
||||
- [ ] Write test + md.
|
||||
|
||||
---
|
||||
|
||||
## 6. Hooks
|
||||
|
||||
### useFeed
|
||||
|
||||
- [ ] Loads feed via `FeedManager`; returns `{ posts, loading, error, refresh, loadMore }`. OTel `social.feed.load` span.
|
||||
- [ ] Write test + md.
|
||||
|
||||
### usePost
|
||||
|
||||
- [ ] CRUD hook; returns `{ create, update, delete, react, comment }`. OTel spans per action.
|
||||
- [ ] Write test + md.
|
||||
|
||||
### useChat
|
||||
|
||||
- [ ] `useChat(conversationId)` — sends/receives messages, manages `MessageManager`. OTel `social.message.send` span.
|
||||
- [ ] Write test + md.
|
||||
|
||||
### useConversations
|
||||
|
||||
- [ ] Lists conversations with unread counts; returns `{ conversations, loading, markRead }`.
|
||||
- [ ] Write test + md.
|
||||
|
||||
### useMessages
|
||||
|
||||
- [ ] Loads messages for a conversation with pagination; returns `{ messages, loading, sendMessage }`.
|
||||
- [ ] Write test + md.
|
||||
|
||||
---
|
||||
|
||||
## 7. Components
|
||||
|
||||
### Feed
|
||||
|
||||
- [ ] `<Feed userId onPostCreate onPostClick />` — infinite-scroll feed via `@suaveplan/react-infinite-scroll`. `useTranslation` for empty state.
|
||||
- [ ] Write test, stories (default, loading, empty, with-posts, playground), md.
|
||||
|
||||
### CreatePost
|
||||
|
||||
- [ ] Rich-text composer via `@suaveplan/react-rich-text`. File attachments, mentions via `@mention`, post submit.
|
||||
- [ ] Write test, stories (default, with-attachment, playground), md.
|
||||
|
||||
### ChatWindow
|
||||
|
||||
- [ ] Full chat pane with `MessageList`, `MessageInput`, typing indicator, online status badge.
|
||||
- [ ] Write test, stories (default, with-messages, typing, playground), md.
|
||||
|
||||
### ConversationList
|
||||
|
||||
- [ ] Infinite-scroll list of conversations with unread badge, avatar, last-message preview.
|
||||
- [ ] Write test, stories (default, with-unread, empty, playground), md.
|
||||
|
||||
### MessageInput
|
||||
|
||||
- [ ] Text + emoji input with `@mention` support. Sends on Enter.
|
||||
- [ ] Write test, stories (default, with-emoji, playground), md.
|
||||
|
||||
### MessageList
|
||||
|
||||
- [ ] Virtualized message list with date separators, read receipts, reaction pills.
|
||||
- [ ] Write test, stories (default, with-reactions, read-receipts, playground), md.
|
||||
|
||||
---
|
||||
|
||||
## 8. E2E
|
||||
|
||||
- [ ] `e2e/social.spec.ts` — Playwright:
|
||||
- Create a post; verify it appears in the feed.
|
||||
- Add a comment; verify nested comment thread renders.
|
||||
- Open DM conversation; send a message; verify delivery + read receipt.
|
||||
- Verify typing indicator appears while composing.
|
||||
|
||||
---
|
||||
|
||||
## 9. Verify and publish
|
||||
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-social` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-social` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/react-social`.
|
||||
- [ ] Archive change folder.
|
||||
Reference in New Issue
Block a user