Initial Commit

openspec/changes/enterprise-react-ui-social/proposal.md

@@ -0,0 +1,109 @@
+# OpenSpec Change: enterprise-react-ui-social
+
+- **Change ID**: enterprise-react-ui-social
+- **Package**: `@suaveplan/react-ui-social`
+- **Category**: react
+- **Target path**: `react/social/react-ui-social`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-ui-social.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-ui-social` on genesis from scratch at enterprise quality. Two themed component clusters: "FewFaces" (feed/post/reactions/nav/sidebar/profile) and "Luxury" (hospitality hero/nav/footer/accommodation/testimonials), plus general media primitives (`GalleryGrid`, `Lightbox`). Genesis adds Storybook coverage (main branch shipped zero stories), fixes i18n violations (hard-coded "Search FewFaces" and "What's on your mind" strings), splits `FewFacesPost` beyond the 300-line hard limit, adds Playwright E2E, Zod schemas for API shapes, brand-decoupled theming props, and real caption support.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `SocialUiError` |
+| `@suaveplan/react-ui` (`workspace:^`) | Radix primitives + `cn` |
+| `@suaveplan/react-social` (`workspace:^`) | Social data hooks |
+| `@suaveplan/react-translate` (`workspace:^`) | i18n — all user-visible strings |
+| `@suaveplan/react-rich-text` (`workspace:^`) | Rich post composer |
+| `@suaveplan/react-virtual` (`workspace:^`) | Virtualised timeline |
+| `@suaveplan/react-infinite-scroll` (`workspace:^`) | Paginated feed |
+| `@suaveplan/react-file-upload` (`workspace:^`) | Composer attachments |
+| `@suaveplan/react-image` (`workspace:^`) | Image preview |
+| `@suaveplan/react-video` (`workspace:^`) | Video posts |
+| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
+| `zod` (`catalog:forms`) | API shape schemas |
+| `tslib` (`catalog:build`) | TS helpers |
+
+External: `react-router-dom catalog:routing`, `lucide-react catalog:ui`, React 18 peer.
+
+---
+
+## Preserved public API surface
+
+```ts
+// FewFaces bundle
+FewFacesNav, FewFacesSidebar, FewFacesTimeline, FewFacesPost,
+FewFacesReactions, FewFacesProfile
+FewFacesNavProps, FewFacesSidebarProps, FewFacesTimelineProps,
+FewFacesPostProps, ReactionType, ReactionCount, Comment, PostReaction
+
+// Luxury bundle
+LuxuryHero, LuxuryNav, LuxuryFooter, AccommodationCard, TestimonialSection
+LuxuryHeroProps, LuxuryNavProps, LuxuryFooterProps,
+AccommodationCardProps, TestimonialSectionProps
+
+// Media
+GalleryGrid, Lightbox
+GalleryGridProps, LightboxProps
+```
+
+---
+
+## New additions for genesis
+
+1. **Storybook coverage** — default + playground + a11y + RTL + dark-theme variants for every component (main branch had zero stories).
+2. **i18n fix** — remove all hard-coded English strings from `FewFacesNav`, `FewFacesTimeline`, `FewFacesPost` and route through `useTranslation`.
+3. **`FewFacesPost` split** — extract `FewFacesPostReactionsBar` and `FewFacesPostComments` to stay within 300-line hard limit.
+4. **Real captions** — `FewFacesPost` accepts `captions?: { src; srclang; label }[]` replacing the placeholder `<track>`.
+5. **Zod schemas** — `PostSchema`, `CommentSchema`, `ReactionSchema`, `AccommodationSchema`, `TestimonialSchema` for API boundary parsing.
+6. **Theming props** — `branding?: { appName; logo }` on `FewFacesNav`; color-token props on `Luxury*` components.
+7. **Playwright E2E** — FewFaces timeline, Luxury landing, gallery lightbox.
+8. **Optimistic reactions** — client-optimistic updates with rollback via `@suaveplan/react-notifications`.
+
+---
+
+## File layout
+
+```text
+react/social/react-ui-social/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    schemas/
+    types/
+    few-faces/
+      few-faces-nav/ (tsx + types + md + test + stories + index)
+      few-faces-sidebar/ (tsx + types + md + test + stories + index)
+      few-faces-timeline/ (tsx + types + md + test + stories + index)
+      few-faces-post/ (tsx + types + md + test + stories + index)
+        few-faces-post-reactions-bar/ (tsx + types + index)
+        few-faces-post-comments/ (tsx + types + index)
+      few-faces-reactions/ (tsx + types + md + test + stories + index)
+      few-faces-profile/ (tsx + types + md + test + stories + index)
+    luxury/
+      luxury-hero/ luxury-nav/ luxury-footer/ accommodation-card/ testimonial-section/
+    media/
+      gallery-grid/ lightbox/
+  e2e/
+    few-faces.spec.ts
+    luxury.spec.ts
+    gallery.spec.ts
+```