@zyncat/ui 0.8.0

package/src/components/primitives/avatar/Avatar.tsx

@@ -0,0 +1,120 @@
+'use client';
+
+import './avatar.css';
+import { useState, type CSSProperties, type HTMLAttributes, type ReactNode } from 'react';
+import type { DataAttributes } from '../../../dom-props';
+import { cx } from '../../internal/utils/cx';
+
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export type AvatarShape = 'circle' | 'square';
+export type AvatarStatus = 'online' | 'away' | 'busy' | 'offline';
+export type AvatarPaletteIndex = 1 | 2 | 3 | 4 | 5 | 6;
+
+interface AvatarOwnProps {
+  /** Image URL. Falls back to initials / icon / silhouette if absent or fails. */
+  src?: string | null;
+  /** Display name - drives initials generation, palette hash, and aria-label. */
+  name?: string | null;
+  /** Content override - any React node (e.g. <Icon name="globe" />). */
+  icon?: ReactNode | null;
+  /** 'circle' for people; 'square' for channels / brand pages. Default 'circle'. */
+  shape?: AvatarShape;
+  /** Size step. Default 'md' (32 px). */
+  size?: AvatarSize;
+  /** Presence indicator dot at bottom-right. Default null (hidden). */
+  status?: AvatarStatus | null;
+  /** Override identity slot 1-6 (blue - violet - plum - rose - clay - moss); auto from name hash when null, neutral when anonymous. */
+  paletteIndex?: AvatarPaletteIndex | null;
+  /** Extra class(es) merged onto the root. */
+  className?: string;
+  /** Inline styles merged onto the root. */
+  style?: CSSProperties;
+}
+
+export interface AvatarProps extends AvatarOwnProps {
+  /** Standard <span> attributes (onClick, title, data-*, ...) forwarded to the root. */
+  htmlProps?: Omit<HTMLAttributes<HTMLSpanElement>, keyof AvatarOwnProps> & DataAttributes;
+}
+
+const PALETTE_SLOTS = 6;
+
+function hashName(str: string) {
+  let h = 0;
+  for (let i = 0; i < str.length; i++) h = ((h << 5) - h + str.charCodeAt(i)) | 0;
+  return (Math.abs(h) % PALETTE_SLOTS) + 1;
+}
+
+function initialsOf(name: string | null, max: number) {
+  if (!name) return '';
+  const parts = name.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return '';
+  if (parts.length === 1 || max === 1) return parts[0][0].toUpperCase();
+  return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase();
+}
+
+function Silhouette() {
+  return (
+    <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+      <circle cx="12" cy="8.5" r="3.8" fill="currentColor" />
+      <path d="M4 20.5C4 16.1 7.6 13 12 13s8 3.1 8 7.5" fill="currentColor" opacity="0.65" />
+    </svg>
+  );
+}
+
+export function Avatar({
+  src = null,
+  name = null,
+  icon = null,
+  shape = 'circle',
+  size = 'md',
+  status = null,
+  paletteIndex = null,
+  className = '',
+  style = {},
+  htmlProps,
+}: AvatarProps) {
+  const [imgError, setImgError] = useState(false);
+  const showImg = Boolean(src) && !imgError;
+
+  const maxInits = size === 'xs' ? 1 : 2;
+  const inits = initialsOf(name, maxInits);
+  const slot = paletteIndex ?? (name ? hashName(name) : null);
+
+  const cls = cx('avatar', size !== 'md' && `avatar--${size}`, shape === 'square' && 'avatar--square', className);
+
+  return (
+    <span
+      className={cls}
+      role={name ? 'img' : undefined}
+      aria-label={name || undefined}
+      data-palette={!showImg && slot != null ? slot : undefined}
+      style={style}
+      {...htmlProps}
+    >
+      <span className="avatar__face">
+        {showImg && (
+          <img className="avatar__img" src={src} alt={name || ''} onError={() => setImgError(true)} draggable={false} />
+        )}
+        {!showImg && icon && (
+          <span className="avatar__icon" aria-hidden="true">
+            {icon}
+          </span>
+        )}
+        {!showImg && !icon && inits && (
+          <span className="avatar_initialsOf" aria-hidden="true">
+            {inits}
+          </span>
+        )}
+        {!showImg && !icon && !inits && (
+          <span className="avatar__icon" aria-hidden="true">
+            <Silhouette />
+          </span>
+        )}
+      </span>
+
+      {status && (
+        <span className={`avatar__status avatar__status--${status}`} role="img" aria-label={status} title={status} />
+      )}
+    </span>
+  );
+}

package/src/components/primitives/avatar/AvatarGroup.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+import './avatar.css';
+import {
+  Children,
+  cloneElement,
+  isValidElement,
+  type CSSProperties,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import type { AvatarSize } from './Avatar';
+import type { DataAttributes } from '../../../dom-props';
+import { cx } from '../../internal/utils/cx';
+
+interface AvatarGroupOwnProps {
+  /** The `Avatar` elements to stack; each is cloned to force `size`, then sliced to `max`. */
+  children: ReactNode;
+  /** Max visible avatars before "+N" overflow chip. Default 5. */
+  max?: number;
+  /** Uniform size applied to all children. Default 'md'. */
+  size?: AvatarSize;
+  /** Extra class(es) merged onto the group wrapper. */
+  className?: string;
+  /** Inline styles merged onto the group wrapper. */
+  style?: CSSProperties;
+}
+
+export interface AvatarGroupProps extends AvatarGroupOwnProps {
+  /** Standard <span> attributes forwarded to the group wrapper. */
+  htmlProps?: Omit<HTMLAttributes<HTMLSpanElement>, keyof AvatarGroupOwnProps> & DataAttributes;
+}
+
+export function AvatarGroup({ children, max = 5, size = 'md', className = '', style, htmlProps }: AvatarGroupProps) {
+  const items = Children.toArray(children);
+  const visible = max > 0 ? items.slice(0, max) : items;
+  const overflow = items.length - visible.length;
+
+  return (
+    <span className={cx('avatar-group', className)} style={style} {...htmlProps}>
+      {visible.map((child, i) =>
+        isValidElement(child)
+          ? cloneElement(child as ReactElement<{ size?: AvatarSize }>, { size, key: child.key ?? i })
+          : child,
+      )}
+      {overflow > 0 && (
+        <span className={`avatar avatar--${size} avatar--overflow`} role="img" aria-label={`${overflow} more`}>
+          <span className="avatar__face">
+            <span className="avatar__initials">+{overflow}</span>
+          </span>
+        </span>
+      )}
+    </span>
+  );
+}

package/src/components/primitives/avatar/avatar.css

@@ -0,0 +1,200 @@
+/* Avatar (image - initials - icon) + AvatarGroup - face/status structure, token sizes, 6 identity slots. */
+
+.avatar {
+  --avatar-size: 2rem;
+  --avatar-bg: var(--bg-muted);
+  --avatar-fg: var(--text-muted);
+  /* --avatar-ring: injected by .avatar-group, cascades to .avatar__face */
+
+  position: relative;
+  display: inline-flex;
+  flex: none;
+  vertical-align: middle;
+  width: var(--avatar-size);
+  height: var(--avatar-size);
+}
+
+.avatar__face {
+  width: 100%;
+  height: 100%;
+  border-radius: var(--radius-full);
+  overflow: hidden;
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  background: var(--avatar-bg);
+  color: var(--avatar-fg);
+
+  /* sheen from top, shade from bottom over the slot tint; an image child paints over both (section B3 gradient exception) */
+  background:
+    linear-gradient(to bottom, var(--avatar-sheen), transparent 55%),
+    linear-gradient(to top, var(--avatar-shade), transparent 45%), var(--avatar-bg);
+
+  /* Crisp 1px edge-catch + optional group separator ring via cascade */
+  box-shadow:
+    inset 0 1px 0 0 oklch(1 0 0 / 0.5),
+    var(--avatar-ring, none);
+
+  /* keyline keyed to the slot's own hue (fg at low alpha), not uniform black; outline paints above children so it rings photos too */
+  outline: var(--border-hairline) solid color-mix(in oklch, var(--avatar-fg) 18%, transparent);
+  outline-offset: -1px;
+
+  transition: box-shadow var(--duration-fast) var(--ease-standard);
+}
+
+.avatar__img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+/* lettermark, ratio-sized (section A7 exception); text-box trim = true optical centering; negative margin returns the trailing --tracking-caps so the pair stays centered */
+.avatar__initials {
+  font-family: var(--font-sans);
+  font-weight: var(--weight-semibold);
+  font-size: calc(var(--avatar-size) * 0.42);
+  line-height: 1;
+  text-box: trim-both cap alphabetic;
+  letter-spacing: var(--tracking-caps);
+  margin-right: calc(-1 * var(--tracking-caps));
+  text-transform: uppercase;
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+.avatar__icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 56%;
+  height: 56%;
+  opacity: 0.5;
+}
+.avatar__icon svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.avatar--xs {
+  --avatar-size: 1.25rem;
+}
+.avatar--sm {
+  --avatar-size: 1.5rem;
+}
+.avatar--lg {
+  --avatar-size: 2.5rem;
+}
+.avatar--xl {
+  --avatar-size: 3rem;
+}
+
+/* square - radius scales with size (concentric nesting) */
+.avatar--square .avatar__face {
+  border-radius: var(--radius-md);
+}
+
+.avatar--square.avatar--lg .avatar__face,
+.avatar--square.avatar--xl .avatar__face {
+  border-radius: var(--radius-lg);
+}
+
+/* data-palette 1-6: identity slots (tokens/avatar.css); no attr = neutral; identity colouring, never status */
+
+.avatar[data-palette='1'] {
+  --avatar-bg: var(--avatar-1-bg);
+  --avatar-fg: var(--avatar-1-fg);
+}
+.avatar[data-palette='2'] {
+  --avatar-bg: var(--avatar-2-bg);
+  --avatar-fg: var(--avatar-2-fg);
+}
+.avatar[data-palette='3'] {
+  --avatar-bg: var(--avatar-3-bg);
+  --avatar-fg: var(--avatar-3-fg);
+}
+.avatar[data-palette='4'] {
+  --avatar-bg: var(--avatar-4-bg);
+  --avatar-fg: var(--avatar-4-fg);
+}
+.avatar[data-palette='5'] {
+  --avatar-bg: var(--avatar-5-bg);
+  --avatar-fg: var(--avatar-5-fg);
+}
+.avatar[data-palette='6'] {
+  --avatar-bg: var(--avatar-6-bg);
+  --avatar-fg: var(--avatar-6-fg);
+}
+
+/* status dot lives outside .avatar__face (which clips) so it's never cut; ~27% of size, min 6px */
+
+.avatar__status {
+  position: absolute;
+  bottom: 0;
+  right: 0;
+
+  width: calc(var(--avatar-size) * 0.275);
+  height: calc(var(--avatar-size) * 0.275);
+  min-width: 6px;
+  min-height: 6px;
+
+  border-radius: var(--radius-full);
+  box-shadow: 0 0 0 2px var(--bg-surface);
+  transition: background-color var(--duration-fast) var(--ease-standard);
+}
+
+.avatar__status--online {
+  background: var(--success);
+}
+.avatar__status--away {
+  background: var(--warning);
+}
+.avatar__status--busy {
+  background: var(--danger);
+}
+.avatar__status--offline {
+  background: var(--border-strong);
+}
+
+.avatar-group {
+  display: inline-flex;
+  align-items: center;
+}
+
+/* inject --avatar-ring on group children - cascades to .avatar__face */
+.avatar-group > .avatar {
+  --avatar-ring: 0 0 0 2px var(--bg-surface);
+}
+
+.avatar-group > .avatar + .avatar {
+  margin-left: calc(var(--avatar-size) * -0.3);
+  transition: margin-left var(--duration-base) var(--ease-entrance);
+}
+
+.avatar-group:hover > .avatar + .avatar {
+  margin-left: var(--space-1);
+}
+
+/* "+N" chip - mono numerals, tracking off (mono is already spaced), smaller ratio to fit "+12" */
+.avatar--overflow .avatar__initials {
+  font-family: var(--font-mono);
+  font-variant-numeric: tabular-nums;
+  font-size: calc(var(--avatar-size) * 0.36);
+  letter-spacing: var(--tracking-normal);
+  margin-right: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .avatar__face {
+    transition: none;
+  }
+  .avatar__status {
+    transition: none;
+  }
+  .avatar-group > .avatar + .avatar {
+    transition: none;
+  }
+}

package/src/components/primitives/badge/Badge.tsx

@@ -0,0 +1,75 @@
+'use client';
+
+import './badge.css';
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react';
+import type { DataAttributes } from '../../../dom-props';
+import { cx } from '../../internal/utils/cx';
+
+export type BadgeTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+
+interface BadgeOwnProps {
+  /** Status hue. @default 'neutral' */
+  tone?: BadgeTone;
+  /** Surface. @default 'glass' */
+  variant?: 'glass' | 'outline';
+  /** @default 'md' */
+  size?: 'sm' | 'md';
+  /** Leading status dot. */
+  dot?: boolean;
+  /** Dot pulses (implies dot) - for in-progress status. */
+  live?: boolean;
+  /** Fully-rounded shape. */
+  pill?: boolean;
+  /** Optional leading <Icon> (overrides dot if both set). */
+  icon?: ReactNode;
+  /** Extra class(es) merged onto the chip. */
+  className?: string;
+  /** Inline styles merged onto the chip. */
+  style?: CSSProperties;
+  /** Chip label. */
+  children?: ReactNode;
+}
+
+export interface BadgeProps extends BadgeOwnProps {
+  /** Standard <span> attributes (aria-*, data-*, title, ...) forwarded to the chip. */
+  htmlProps?: Omit<HTMLAttributes<HTMLSpanElement>, keyof BadgeOwnProps> & DataAttributes;
+}
+
+export function Badge({
+  tone = 'neutral',
+  variant = 'glass',
+  size = 'md',
+  dot = false,
+  live = false,
+  pill = false,
+  icon = null,
+  className = '',
+  style,
+  children,
+  htmlProps,
+}: BadgeProps) {
+  const isGlass = variant !== 'outline';
+  const cls = cx(
+    isGlass && 'glass glass--interactive',
+    'badge',
+    `badge--${tone}`,
+    variant === 'outline' && 'badge--outline',
+    size !== 'md' && `badge--${size}`,
+    pill && 'badge--pill',
+    className,
+  );
+
+  const showDot = (dot || live) && !icon;
+
+  return (
+    <span className={cls} style={style} {...htmlProps}>
+      {showDot ? <span className={`badge__dot${live ? ' badge__dot--live' : ''}`} aria-hidden="true" /> : null}
+      {icon ? (
+        <span className="badge__icon" aria-hidden="true">
+          {icon}
+        </span>
+      ) : null}
+      <span className="badge__label">{children}</span>
+    </span>
+  );
+}

package/src/components/primitives/badge/CountBadge.tsx

@@ -0,0 +1,20 @@
+'use client';
+
+import { Badge, type BadgeProps } from './Badge';
+import { Odometer } from './odometer';
+
+export interface CountBadgeProps extends Omit<BadgeProps, 'children'> {
+  /** The chip content - stringified; in `roll` mode each digit becomes an odometer column. */
+  value: string | number;
+  /** Odometer: digits roll vertically on change. */
+  roll?: boolean;
+}
+
+export function CountBadge({ value, tone = 'neutral', roll = false, ...rest }: CountBadgeProps) {
+  const str = String(value);
+  return (
+    <Badge tone={tone} {...rest}>
+      {roll ? <Odometer value={str} /> : str}
+    </Badge>
+  );
+}

package/src/components/primitives/badge/StatusBadge.tsx

@@ -0,0 +1,111 @@
+'use client';
+
+import './badge.css';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { Badge, type BadgeProps } from './Badge';
+import { UIMotion } from '../../../tokens/motion-tokens';
+import { fireGlint } from '../../internal/glass/glint';
+import { cx } from '../../internal/utils/cx';
+
+const SM = UIMotion;
+
+export type PostStatus = 'draft' | 'scheduled' | 'processing' | 'published' | 'failed';
+
+export const POST_STATUS: Record<PostStatus, { tone: BadgeProps['tone']; label: string; live?: boolean }> = {
+  draft: { tone: 'neutral', label: 'Draft' },
+  scheduled: { tone: 'info', label: 'Scheduled' },
+  processing: { tone: 'warning', label: 'Processing', live: true },
+  published: { tone: 'success', label: 'Published' },
+  failed: { tone: 'danger', label: 'Failed' },
+};
+
+const TERMINAL: Partial<Record<PostStatus, boolean>> = { published: true, failed: true };
+
+export interface StatusBadgeProps extends Omit<BadgeProps, 'children' | 'tone'> {
+  /** Lifecycle state - maps to a canonical `tone` + label (`processing` also pulses live). Unknown falls back to `draft`. */
+  status: PostStatus;
+  /** Morph in place as `status` changes instead of swapping. */
+  morph?: boolean;
+}
+
+export function StatusBadge({ status, morph = false, ...rest }: StatusBadgeProps) {
+  if (!morph) {
+    const s = POST_STATUS[status] || POST_STATUS.draft;
+    return (
+      <Badge tone={s.tone} dot live={!!s.live} {...rest}>
+        {s.label}
+      </Badge>
+    );
+  }
+  return <StatusMorph status={status} {...rest} />;
+}
+
+interface StatusMorphProps extends Omit<BadgeProps, 'children' | 'tone'> {
+  status: PostStatus;
+}
+
+interface Word {
+  key: number;
+  label: string;
+  cls: string;
+}
+
+function StatusMorph({ status, className = '', ...rest }: StatusMorphProps) {
+  const s = POST_STATUS[status] || POST_STATUS.draft;
+
+  const prev = useRef(status);
+  const keyRef = useRef(1);
+  const labelRef = useRef<HTMLSpanElement>(null);
+  const ghostRef = useRef<HTMLSpanElement>(null);
+  const [words, setWords] = useState<Word[]>([{ key: 0, label: s.label, cls: '' }]);
+  const [boxW, setBoxW] = useState<number>();
+
+  useLayoutEffect(() => {
+    if (ghostRef.current) setBoxW(ghostRef.current.offsetWidth);
+  }, []);
+
+  useEffect(() => {
+    if (prev.current === status) return;
+    prev.current = status;
+    const next = POST_STATUS[status] || POST_STATUS.draft;
+    const nk = keyRef.current++;
+    const nextW = ghostRef.current?.offsetWidth;
+
+    setWords((ws) => ws.concat({ key: nk, label: next.label, cls: 'badge__word--in' }));
+    const raf = requestAnimationFrame(() =>
+      requestAnimationFrame(() => {
+        setWords((ws) => ws.map((w) => (w.key === nk ? { ...w, cls: '' } : { ...w, cls: 'badge__word--out' })));
+        if (nextW) setBoxW(nextW);
+      }),
+    );
+    const drop = setTimeout(
+      () => setWords((ws) => ws.filter((w) => !w.cls.includes('--out'))),
+      SM.dur.base * 1000 + 80,
+    );
+    let stopGlint: (() => void) | undefined;
+    if (TERMINAL[status] && labelRef.current) {
+      const chip = labelRef.current.closest('.badge') as HTMLElement | null;
+      if (chip) stopGlint = fireGlint(chip);
+    }
+    return () => {
+      cancelAnimationFrame(raf);
+      clearTimeout(drop);
+      stopGlint?.();
+    };
+  }, [status]);
+
+  return (
+    <Badge tone={s.tone} dot live={!!s.live} className={cx('badge--morph', className)} {...rest}>
+      <span className="badge__morph" ref={labelRef} style={boxW ? { width: boxW } : undefined}>
+        <span className="badge__ghost" ref={ghostRef} aria-hidden="true">
+          {s.label}
+        </span>
+        {words.map((w) => (
+          <span key={w.key} className={cx('badge__word', w.cls)}>
+            {w.label}
+          </span>
+        ))}
+      </span>
+    </Badge>
+  );
+}