@helloimjolopez-pathway/pathway-components 0.9.1 → 0.10.0

package/components/avatar/avatar.jsx

@@ -0,0 +1,167 @@
+/**
+ * Avatar: a person's or a household's photo, initials or icon. Avatar Group:
+ * several people in one spot, up to three overlapping, then +N.
+ *
+ * Figma `Avatar`, set 68:659, and `Avatar Group`, set 9704:74872, page
+ * "↳ Avatar" (5926:18314). Spec: components/avatar/avatar-spec.md.
+ *
+ * Props mirror the Figma properties (CLAUDE.md §10 rule 9):
+ *   Size        size        XXXS 16, XXS 20, XS 24, S 32, M 40, L 56, XL 96.
+ *                           One pixel size per name for every content type.
+ *   Content     content     "Image" | "Text" | "Icon". Optional: when omitted
+ *                           it follows the data, src, else text, else icon.
+ *                           An Image whose photo fails to load falls back the
+ *                           same way (Radix Avatar's Fallback model).
+ *   Shape       shape       "Circle" for people, "Square" for households and
+ *                           things. Square radius grows with the size.
+ *   Style       avatarStyle "Fill" (brand tint) | "Stroke" (outline, dense
+ *                           lists). Image is Fill only.
+ *   Text        text        the initials, at most two letters.
+ *   Icon        icon        a Material Symbols Rounded ligature, FILL 1.
+ *                           "person", or "home" for a household.
+ *   Show Badge  showBadge   the ringed status dot. badgeStatus picks Positive
+ *                           (online) or Attention (away). Always say the
+ *                           status in words too; the dot is never announced.
+ *
+ * ACCESSIBILITY. Not interactive and never focusable. Pass `name` when the
+ * Avatar stands alone: it becomes role img with that name. When the name is
+ * shown beside it, leave `name` out and the Avatar is hidden from screen
+ * readers, so the name is not read twice.
+ */
+import React, { useEffect, useState } from "react";
+
+const C = (n) => `var(--semantic-color-${n})`;
+const U = (n) => `var(--semantic-layout-units-${n})`;
+const Y = (n) => `var(--semantic-type-${n})`;
+
+export const AVATAR_SIZES = ["XXXS", "XXS", "XS", "S", "M", "L", "XL"];
+export const AVATAR_CONTENTS = ["Image", "Text", "Icon"];
+export const AVATAR_SHAPES = ["Circle", "Square"];
+export const AVATAR_STYLES = ["Fill", "Stroke"];
+export const AVATAR_BADGE_STATUS = ["Positive", "Attention"];
+export const AVATAR_GROUP_SIZES = ["XS", "S", "M"];
+
+/** Per size: the box, initials type, square radius, icon and badge. Sizes are measurements, not tokens. */
+export const SIZES = {
+  XXXS: { px: 16, fontSize: Y("font-size-xxxs"), lineHeight: Y("line-height-xxxs-single"), radius: U("cornerradius-small"),  icon: 10, badge: 6 },
+  XXS:  { px: 20, fontSize: Y("font-size-xxxs"), lineHeight: Y("line-height-xxxs-single"), radius: U("cornerradius-small"),  icon: 12, badge: 7 },
+  XS:   { px: 24, fontSize: Y("font-size-xxs"),  lineHeight: Y("line-height-xxs-single"),  radius: U("cornerradius-small"),  icon: 14, badge: 8 },
+  S:    { px: 32, fontSize: Y("font-size-s"),    lineHeight: Y("line-height-s-single"),    radius: U("cornerradius-small"),  icon: 20, badge: 10 },
+  M:    { px: 40, fontSize: Y("font-size-r"),    lineHeight: Y("line-height-r-single"),    radius: U("cornerradius-base"),   icon: 24, badge: 12 },
+  L:    { px: 56, fontSize: Y("font-size-l"),    lineHeight: Y("line-height-l-single"),    radius: U("cornerradius-large"),  icon: 34, badge: 16 },
+  XL:   { px: 96, fontSize: Y("font-size-xxl"),  lineHeight: Y("line-height-xxl-single"),  radius: U("cornerradius-xlarge"), icon: 58, badge: 28 },
+};
+
+/** Colours and widths, all semantic tokens. */
+export const T = {
+  fill:         C("fill-static-brand-subtle"),           // Text and Icon, Style Fill
+  foreground:   C("foreground-static-brand-on-subtle"),  // initials and icon
+  imageFill:    C("fill-static-neutral-faint"),          // behind the photo
+  stroke:       C("stroke-static-neutral-base"),         // Style Stroke
+  strokeWidth:  U("borderwidth-thin"),
+  circle:       U("cornerradius-full"),
+  badgeRing:    C("stroke-static-neutral-mono"),
+  badgeRingW:   U("borderwidth-base"),
+  badge:        { Positive: C("fill-static-positive-strong"), Attention: C("fill-static-attention-strong") },
+  groupRing:    C("fill-surface-elevated"),              // Avatar Group, separates overlapping avatars
+  groupRingW:   U("borderwidth-thick"),
+  family:       Y("family-brand"),
+  weight:       Y("weight-semibold"),
+};
+
+/** First letters of the first and last name, at most two. */
+export function initialsFrom(name = "") {
+  const parts = String(name).trim().split(/\s+/).filter(Boolean);
+  if (!parts.length) return "";
+  const first = parts[0][0] || "";
+  const last = parts.length > 1 ? parts[parts.length - 1][0] : "";
+  return (first + last).toUpperCase();
+}
+
+export function Avatar({
+  size = "M",
+  content,
+  shape = "Circle",
+  avatarStyle = "Fill",
+  src,
+  text,
+  icon = "person",
+  name,
+  showBadge = false,
+  badgeStatus = "Positive",
+  style,
+  ...rest
+}) {
+  const z = SIZES[size] || SIZES.M;
+  const [failed, setFailed] = useState(false);
+  useEffect(() => setFailed(false), [src]);
+  const letters = (text || "").slice(0, 2);
+  const resolved = content === "Icon" ? "Icon"
+    : content === "Text" ? (letters ? "Text" : "Icon")
+    : src && !failed ? "Image"
+    : letters ? "Text" : "Icon";
+  const look = resolved === "Image" ? "Fill" : avatarStyle;
+  const radius = shape === "Square" ? z.radius : T.circle;
+  const root = {
+    position: "relative", flex: "none", boxSizing: "border-box",
+    display: "inline-flex", alignItems: "center", justifyContent: "center",
+    width: z.px, height: z.px, borderRadius: radius,
+    background: resolved === "Image" ? T.imageFill : look === "Stroke" ? "transparent" : T.fill,
+    boxShadow: look === "Stroke" ? `inset 0 0 0 ${T.strokeWidth} ${T.stroke}` : "none",
+    color: T.foreground, fontFamily: T.family, ...style,
+  };
+  const a11y = name ? { role: "img", "aria-label": name } : { "aria-hidden": true };
+  return (
+    <span data-pw-avatar="" data-size={size} data-content={resolved} style={root} {...a11y} {...rest}>
+      {resolved === "Image" && (
+        <img src={src} alt="" onError={() => setFailed(true)}
+          style={{ width: "100%", height: "100%", objectFit: "cover", display: "block", borderRadius: radius }} />
+      )}
+      {resolved === "Text" && (
+        <span aria-hidden="true" style={{ fontSize: z.fontSize, lineHeight: z.lineHeight, fontWeight: T.weight, letterSpacing: 0, whiteSpace: "nowrap" }}>{letters}</span>
+      )}
+      {resolved === "Icon" && (
+        <span className="material-symbols-rounded" aria-hidden="true"
+          style={{ fontSize: z.icon, width: z.icon, height: z.icon, fontVariationSettings: "'FILL' 1, 'wght' 400, 'GRAD' 0, 'opsz' 24",
+            lineHeight: 1 /* pathway-allow: the icon box is the glyph's em, sized by table 3.5 */ }}>{icon}</span>
+      )}
+      {showBadge && (
+        <span aria-hidden="true" data-pw-avatar-badge="" style={{
+          position: "absolute", right: 0, bottom: 0, boxSizing: "border-box", width: z.badge, height: z.badge,
+          borderRadius: T.circle, background: T.badge[badgeStatus] || T.badge.Positive,
+          boxShadow: `inset 0 0 0 ${T.badgeRingW} ${T.badgeRing}`,
+        }} />
+      )}
+    </span>
+  );
+}
+
+/**
+ * AvatarGroup: up to `max` avatars (3), overlapping by a quarter of their size,
+ * each ringed in the surface colour, then a +N count of the rest. One role img
+ * named with the people shown and how many more.
+ *
+ * Figma: Size (XS, S, M) maps to size; Show Avatar 3 and Show more follow from
+ * how many people there are and `showMore`.
+ */
+export function AvatarGroup({ people = [], size = "XS", max = 3, showMore = true, label, style, ...rest }) {
+  const z = SIZES[size] || SIZES.XS;
+  const shown = people.slice(0, max);
+  const more = people.length - shown.length;
+  const named = shown.map((p) => p.name).filter(Boolean);
+  const aria = label || (named.join(", ") + (more > 0 ? `, and ${more} more` : ""));
+  const ring = { boxShadow: `0 0 0 ${T.groupRingW} ${T.groupRing}` };
+  return (
+    <span data-pw-avatar-group="" role="img" aria-label={aria} style={{ display: "inline-flex", alignItems: "center", ...style }} {...rest}>
+      {shown.map((p, i) => (
+        <Avatar key={(p.name || "") + i} size={size} src={p.src} text={p.text || initialsFrom(p.name)} icon={p.icon}
+          style={{ ...ring, marginLeft: i ? -z.px / 4 : 0 }} />
+      ))}
+      {showMore && more > 0 && (
+        <Avatar size={size} content="Text" text={`+${more}`.slice(0, 3)} style={{ ...ring, marginLeft: shown.length ? -z.px / 4 : 0 }} />
+      )}
+    </span>
+  );
+}
+
+export default Avatar;