@zyncat/ui 0.11.0 → 0.13.0

package/src/components/expressive/confetti/Confetti.usage.md

@@ -0,0 +1,18 @@
+# Confetti - @zyncat/ui/confetti
+
+Group: expressive
+Docs: https://ui.zyncat.app/confetti
+
+A canvas particle burst you fire yourself: paper flakes, curls, ribbons and foil sequins tumbling on real drag, lift and flip, across three depth layers.
+
+Fire it from the ref handle - ref.current.fire({count, duration, emitter}) - bursts coexist, never
+cancel. emitter sides|top|corners is the launch geometry; count is pieces per fire (cap 520, the
+oldest piece retires past it); duration is the seconds the emitter stays open, 0.15 for one shove
+and 2.5 for a taper; speed is sampled live; field container|viewport picks what the canvas covers.
+Retune through --confetti-* on the canvas: paper-1..5, weights, ink, light, shade, gloss, layer.
+Purely decorative - aria-hidden, pointer-events none, never focusable, no live region: announce the
+success yourself. Reduced motion renders nothing and fire() is a no-op.
+
+```tsx
+<Confetti ref={confetti} count={170} />
+```

package/src/components/expressive/confetti/confetti.css

@@ -0,0 +1,45 @@
+@layer zyncat.tokens, zyncat.components;
+
+@layer zyncat.components {
+  .confetti {
+    --confetti-paper-1: oklch(0.53 0.2 288);
+    --confetti-paper-2: var(--accent);
+    --confetti-paper-3: oklch(0.78 0.115 62);
+    --confetti-paper-4: oklch(0.67 0.18 12);
+    --confetti-paper-5: var(--text-strong);
+    --confetti-weights: 1 1 1 1 0.45;
+
+    --confetti-ink: var(--text-strong);
+    --confetti-light: var(--bg-surface);
+    --confetti-shade: 42%;
+    --confetti-gloss: 66%;
+    --confetti-layer: var(--layer-toast);
+
+    --confetti-reverse-1: color-mix(in oklab, var(--confetti-ink) var(--confetti-shade), var(--confetti-paper-1));
+    --confetti-reverse-2: color-mix(in oklab, var(--confetti-ink) var(--confetti-shade), var(--confetti-paper-2));
+    --confetti-reverse-3: color-mix(in oklab, var(--confetti-ink) var(--confetti-shade), var(--confetti-paper-3));
+    --confetti-reverse-4: color-mix(in oklab, var(--confetti-ink) var(--confetti-shade), var(--confetti-paper-4));
+    --confetti-reverse-5: color-mix(in oklab, var(--confetti-ink) var(--confetti-shade), var(--confetti-paper-5));
+
+    --confetti-sheen-1: color-mix(in oklab, var(--confetti-light) var(--confetti-gloss), var(--confetti-paper-1));
+    --confetti-sheen-2: color-mix(in oklab, var(--confetti-light) var(--confetti-gloss), var(--confetti-paper-2));
+    --confetti-sheen-3: color-mix(in oklab, var(--confetti-light) var(--confetti-gloss), var(--confetti-paper-3));
+    --confetti-sheen-4: color-mix(in oklab, var(--confetti-light) var(--confetti-gloss), var(--confetti-paper-4));
+    --confetti-sheen-5: color-mix(in oklab, var(--confetti-light) var(--confetti-gloss), var(--confetti-paper-5));
+
+    position: absolute;
+    inset: 0;
+    display: block;
+    width: 100%;
+    height: 100%;
+    pointer-events: none;
+    touch-action: none;
+    user-select: none;
+    background: none;
+  }
+
+  .confetti--viewport {
+    position: fixed;
+    z-index: var(--confetti-layer);
+  }
+}

package/src/components/expressive/facebook-feed/FacebookFeed.tsx

@@ -0,0 +1,200 @@
+'use client';
+
+import './facebook-feed.css';
+
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react';
+
+import type { DataAttributes } from '../../../dom-props';
+import { useControllable } from '../../internal/hooks/use-controllable';
+import type { FacebookFeedAction, FacebookMediaType, FacebookRatio } from './chrome';
+import { FacebookPost, type FacebookPostWidth } from './post';
+import { FacebookReel, type FacebookReelStage } from './reel';
+import { FacebookStory } from './story';
+
+export type { FacebookFeedAction, FacebookMediaType, FacebookRatio } from './chrome';
+export type { FacebookPostWidth } from './post';
+export type { FacebookReelStage } from './reel';
+
+export type FacebookSurface = 'post' | 'reel' | 'story';
+
+const DEFAULT_NAME = 'Swiss Nature';
+const DEFAULT_CAPTION = 'This is Switzerland';
+const DEFAULT_STAMP = '31m';
+const DEFAULT_AUDIO = 'Original audio';
+const DEFAULT_RATIO: FacebookRatio = '4:5';
+const DEFAULT_LIKES = 267;
+const DEFAULT_COMMENTS = 12;
+const DEFAULT_SHARES = 4;
+const DEFAULT_SEGMENTS = 2;
+const DEFAULT_SEGMENT = 0;
+const MUTED_BY_SURFACE: Record<FacebookSurface, boolean> = { post: true, reel: true, story: false };
+
+export interface FacebookFeedOwnProps {
+  /** Which Facebook surface to reproduce: the feed card, the reels stage, or the story stage. @default 'post' */
+  surface?: FacebookSurface;
+  /** Feed card width. `mobile` is the 390px square-cornered card, `web` the 680px rounded one. @default 'web' */
+  width?: FacebookPostWidth;
+  /** Reels stage. `narrow` is 557x878 around a 9:16 video, `wide` is 1601x886 around a 16:9 one. @default 'narrow' */
+  stage?: FacebookReelStage;
+  /** Whether `media` is a still or a clip. A still is echoed into the feed's blurred letterbox backdrop; a clip is not, so it is never fetched twice. @default 'image' */
+  type?: FacebookMediaType;
+  /** Poster or page name in the header. @default 'Swiss Nature' */
+  name?: string;
+  /** Post body. The feed cuts it at 250 characters with `See more`; reels take one ellipsised line. Hashtags and @mentions render in link blue. */
+  caption?: string;
+  /** Frame aspect for the feed card and the story card. Reels stages are fixed. @default '4:5' */
+  ratio?: FacebookRatio;
+  /** A URL string, or your own node (`<img>`, `<video>`, `next/image`). Omit for a CSS-only placeholder. Nothing is ever autoplayed and no request is ever made for you. */
+  media?: ReactNode;
+  /** A URL string, or your own node, for the header portrait. Omit for the platform's grey. */
+  avatar?: ReactNode;
+  /** Show the `· Follow` affordance. Blue in the feed, white on reels. @default true */
+  follow?: boolean;
+  /** Blue active-story ring around the feed avatar. @default true */
+  ring?: boolean;
+  /** Relative timestamp in the meta line. @default '31m' */
+  stamp?: string;
+  /** Blue verified badge after the reels name. @default true */
+  verified?: boolean;
+  /** Track name on the reels and story audio line. @default 'Original audio' */
+  audio?: string;
+  /** Reaction count. Exact below 1,000, then `1.2K` / `48K` / `1.4M`. @default 267 */
+  likes?: number;
+  /** Comment count, formatted like `likes`. @default 12 */
+  comments?: number;
+  /** Share count, formatted like `likes`. @default 4 */
+  shares?: number;
+  /** How many story progress segments to draw. @default 2 */
+  segments?: number;
+  /** Index of the newest filled story segment; every earlier one fills too. @default 0 */
+  segment?: number;
+  /** Controlled mute state for the reels and story sound button. */
+  muted?: boolean;
+  /** Uncontrolled initial mute state. @default true on reels, false on the story */
+  defaultMuted?: boolean;
+  /** Fires when the sound button is pressed. You own the actual `<video>`, so wire it to your own element. */
+  onMutedChange?: (muted: boolean) => void;
+  /** Controlled like state for the thumb on the feed card and the reels rail. The displayed reaction count adds one while this is on. */
+  liked?: boolean;
+  /** Uncontrolled initial like state. @default false */
+  defaultLiked?: boolean;
+  /** Fires when the thumb toggles the like. */
+  onLikedChange?: (liked: boolean) => void;
+  /** Fires for the actions that carry no state: comment, share, follow, menu, dismiss, more, search, play. */
+  onAction?: (action: FacebookFeedAction) => void;
+  /** Extra class(es) merged onto the surface root. */
+  className?: string;
+  /** Inline styles merged onto the surface root. */
+  style?: CSSProperties;
+}
+
+export interface FacebookFeedProps extends FacebookFeedOwnProps {
+  /** Standard element attributes (aria-*, data-*, title, ...) forwarded to the surface root. */
+  htmlProps?: Omit<HTMLAttributes<HTMLElement>, keyof FacebookFeedOwnProps> & DataAttributes;
+}
+
+export function FacebookFeed({
+  surface = 'post',
+  width = 'web',
+  stage = 'narrow',
+  type = 'image',
+  name = DEFAULT_NAME,
+  caption = DEFAULT_CAPTION,
+  ratio = DEFAULT_RATIO,
+  media,
+  avatar,
+  follow = true,
+  ring = true,
+  stamp = DEFAULT_STAMP,
+  verified = true,
+  audio = DEFAULT_AUDIO,
+  likes = DEFAULT_LIKES,
+  comments = DEFAULT_COMMENTS,
+  shares = DEFAULT_SHARES,
+  segments = DEFAULT_SEGMENTS,
+  segment = DEFAULT_SEGMENT,
+  muted,
+  defaultMuted,
+  onMutedChange,
+  liked,
+  defaultLiked = false,
+  onLikedChange,
+  onAction,
+  className = '',
+  style,
+  htmlProps,
+}: FacebookFeedProps) {
+  const [sound, setSound] = useControllable(muted, defaultMuted ?? MUTED_BY_SURFACE[surface], onMutedChange);
+  const [reacted, setReacted] = useControllable(liked, defaultLiked, onLikedChange);
+
+  if (surface === 'reel')
+    return (
+      <FacebookReel
+        name={name}
+        caption={caption}
+        stage={stage}
+        follow={follow}
+        verified={verified}
+        audio={audio}
+        media={media}
+        avatar={avatar}
+        type={type}
+        likes={likes}
+        comments={comments}
+        shares={shares}
+        muted={sound}
+        onMutedChange={setSound}
+        liked={reacted}
+        onLikedChange={setReacted}
+        onAction={onAction}
+        className={className}
+        style={style}
+        htmlProps={htmlProps}
+      />
+    );
+
+  if (surface === 'story')
+    return (
+      <FacebookStory
+        name={name}
+        stamp={stamp}
+        audio={audio}
+        ratio={ratio}
+        media={media}
+        avatar={avatar}
+        type={type}
+        segments={segments}
+        segment={segment}
+        muted={sound}
+        onMutedChange={setSound}
+        onAction={onAction}
+        className={className}
+        style={style}
+        htmlProps={htmlProps}
+      />
+    );
+
+  return (
+    <FacebookPost
+      name={name}
+      caption={caption}
+      stamp={stamp}
+      follow={follow}
+      ring={ring}
+      ratio={ratio}
+      media={media}
+      avatar={avatar}
+      type={type}
+      likes={likes}
+      comments={comments}
+      shares={shares}
+      width={width}
+      liked={reacted}
+      onLikedChange={setReacted}
+      onAction={onAction}
+      className={className}
+      style={style}
+      htmlProps={htmlProps}
+    />
+  );
+}

package/src/components/expressive/facebook-feed/FacebookFeed.usage.md

@@ -0,0 +1,18 @@
+# FacebookFeed - @zyncat/ui/facebook-feed
+
+Group: replicas
+Docs: https://ui.zyncat.app/facebook-feed
+
+Replica of Facebook's three post surfaces, pinned to the platform's real metrics: the feed card, the reels stage and the story stage.
+
+Pick it over InstagramFeed when you need Facebook's chrome - caption ABOVE the media, a blurred
+saturated letterbox, the 65px reels rail. surface post|reel|story, width mobile|web, stage
+narrow|wide, type image|video, ratio 4:5|1.1:1|1:1|3:4|16:9. name, caption, stamp, audio, avatar and
+media take a URL string or your own node; follow, ring, verified toggle the chrome;
+likes/comments/shares stay exact below 1,000. liked and muted are controllable toggles; onAction
+reports comment, share, follow, menu, dismiss, more, search, play. Fixed widths, no theming knobs -
+fidelity is the contract.
+
+```tsx
+<FacebookFeed surface="post" width="web" media={<img src={src} alt="" />} likes={267} />
+```

package/src/components/expressive/facebook-feed/chrome.tsx

@@ -0,0 +1,120 @@
+import type { CSSProperties, ReactNode } from 'react';
+
+export type FacebookRatio = '4:5' | '1.1:1' | '1:1' | '3:4' | '16:9';
+export type FacebookMediaType = 'image' | 'video';
+
+/** The actions a surface reports that carry no state of their own. */
+export type FacebookFeedAction = 'comment' | 'share' | 'follow' | 'menu' | 'dismiss' | 'more' | 'search' | 'play';
+
+const THOUSAND = 1e3;
+const TEN_THOUSAND = 1e4;
+const MILLION = 1e6;
+const COMPACT_DECIMALS = 1;
+const TRAILING_ZERO = /\.0$/;
+const THOUSAND_SUFFIX = 'K';
+const MILLION_SUFFIX = 'M';
+
+const CAPTION_LIMIT = 250;
+const WORD_BREAK_FLOOR = 0.65;
+const TRAILING_PUNCTUATION = /[\s,.;:—-]+$/;
+const TAG_SPLIT = /([#@][^\s#@]+)/g;
+const TAG_LEADERS = '#@';
+const QUOTE = /"/g;
+const ENCODED_QUOTE = '%22';
+
+export function countValue(value: number): number {
+  return Math.max(0, Math.round(Number(value) || 0));
+}
+
+export function compactCount(value: number): string {
+  const n = countValue(value);
+  if (n >= MILLION) return (n / MILLION).toFixed(COMPACT_DECIMALS).replace(TRAILING_ZERO, '') + MILLION_SUFFIX;
+  if (n >= TEN_THOUSAND) return Math.round(n / THOUSAND) + THOUSAND_SUFFIX;
+  if (n >= THOUSAND) return (n / THOUSAND).toFixed(COMPACT_DECIMALS).replace(TRAILING_ZERO, '') + THOUSAND_SUFFIX;
+  return String(n);
+}
+
+export interface CaptionCut {
+  head: string;
+  cut: boolean;
+}
+
+export function cutCaption(text: string): CaptionCut {
+  if (text.length <= CAPTION_LIMIT) return { head: text, cut: false };
+  let index = text.lastIndexOf(' ', CAPTION_LIMIT);
+  if (index < CAPTION_LIMIT * WORD_BREAK_FLOOR) index = CAPTION_LIMIT;
+  return { head: text.slice(0, index).replace(TRAILING_PUNCTUATION, ''), cut: true };
+}
+
+export interface CaptionRun {
+  text: string;
+  link: boolean;
+}
+
+export function splitCaption(text: string): CaptionRun[] {
+  const runs: CaptionRun[] = [];
+  for (const segment of text.split(TAG_SPLIT)) {
+    if (!segment) continue;
+    runs.push({ text: segment, link: TAG_LEADERS.includes(segment.charAt(0)) });
+  }
+  return runs.length ? runs : [{ text, link: false }];
+}
+
+function sourceUrl(media: ReactNode): string {
+  return typeof media === 'string' ? media.trim() : '';
+}
+
+function sourceNode(media: ReactNode): ReactNode {
+  return typeof media === 'string' ? null : media;
+}
+
+function backgroundOf(url: string): CSSProperties | undefined {
+  return url ? { backgroundImage: `url("${url.replace(QUOTE, ENCODED_QUOTE)}")` } : undefined;
+}
+
+function isFilled(media: ReactNode): boolean {
+  if (typeof media === 'string') return media.trim().length > 0;
+  return media !== null && media !== undefined && media !== false && media !== true;
+}
+
+export interface MediaSurfaceProps {
+  media?: ReactNode;
+  type: FacebookMediaType;
+  frontClassName: string;
+  backClassName?: string;
+  frontRatio?: FacebookRatio;
+}
+
+export function MediaSurface({ media, type, frontClassName, backClassName, frontRatio }: MediaSurfaceProps) {
+  const style = backgroundOf(sourceUrl(media));
+  const node = sourceNode(media);
+  const filled = isFilled(media);
+  const echo = type === 'image' ? node : null;
+  return (
+    <>
+      {backClassName ? (
+        <div className={backClassName} style={style} aria-hidden="true">
+          {echo}
+          {filled ? null : <span className="facebook-feed-media__fill" />}
+        </div>
+      ) : null}
+      <div className={frontClassName} style={style} data-ratio={frontRatio}>
+        {node}
+        {filled ? null : <span className="facebook-feed-media__fill" />}
+      </div>
+    </>
+  );
+}
+
+export interface PortraitProps {
+  avatar?: ReactNode;
+  className: string;
+}
+
+export function Portrait({ avatar, className }: PortraitProps) {
+  return (
+    <div className={className} style={backgroundOf(sourceUrl(avatar))}>
+      {sourceNode(avatar)}
+    </div>
+  );
+}