# 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
```