@spunto/design-system 0.21.0 → 0.22.0

package/README.md

@@ -56,6 +56,20 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
     `Separator`, `Spinner`, `Skeleton`, `Avatar` (+`AvatarImage`/`AvatarFallback`),
     `Kbd` — one keyboard cap, or a whole shortcut (`keys="mod+k"` → ⌘ K, Ctrl K off Apple),
     spelled out for screen readers.
+  - _AvatarGroup_ — the stack of overlapping avatars. `size` (`xs`…`xl`) sizes the whole
+    stack at once — on `Avatar` it sets the circle **and** its initials, because a 64 px
+    avatar with 14 px initials looks broken. **Compositional**: the group never reads a
+    `{ name, src }` shape, it wraps whatever you hand it (an `Avatar`, one inside a
+    `Tooltip`, a round `Skeleton` while the list loads) in its own span, so a loading
+    stack has exactly the geometry of the loaded one. It owns only what a caller can't
+    get right by hand: the overlap (a ratio of the diameter, `spacing` = ~40/29/20%), the
+    `ringClassName` that separates two faces (match the surface *behind* the stack —
+    `ring-card` inside a `Card`), the paint order, and the `+N`. Counting has two rules:
+    the counter adds the children `max` cut **and** the people never rendered
+    (`total` − children), so a paginated list shows `+38` without fabricating 38 ghost
+    avatars; and a `+1` never appears — one hidden child takes exactly the room its
+    counter would, saying less, so the face is drawn instead. `onOverflowClick` makes
+    the counter a real button.
   - _Forms_ — `Input`, `Textarea`, `Label`, `Switch`, `Checkbox`,
     `RadioGroup` (+`RadioGroupItem`), `Select` (+`SelectTrigger`/`SelectValue`/
     `SelectContent`/`SelectItem`/`SelectGroup`/`SelectGroupLabel`/`SelectSeparator`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",

package/src/components/avatar.tsx

@@ -1,18 +1,54 @@
 "use client"
 
+import { Children, createContext, useContext, type ComponentProps, type ReactNode } from "react"
 import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar"
+import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from "../utils"
 
+const avatarVariants = cva("relative flex shrink-0 overflow-hidden rounded-full bg-muted select-none", {
+  variants: {
+    // The font-size of each step lives here rather than on the fallback: the
+    // initials then *inherit* it, so one `size` sets the circle and its text
+    // together (a 64 px avatar with 14 px initials looks broken).
+    size: {
+      xs: "size-5 text-[0.5625rem]",
+      sm: "size-7 text-[0.6875rem]",
+      default: "size-9 text-sm",
+      lg: "size-12 text-base",
+      xl: "size-16 text-xl",
+    },
+  },
+  defaultVariants: {
+    size: "default",
+  },
+})
+
+export type AvatarSize = NonNullable<VariantProps<typeof avatarVariants>["size"]>
+
+/**
+ * The size an `AvatarGroup` imposes on the avatars inside it, so a stack is
+ * sized once instead of on every child. `null` = no group above.
+ */
+const AvatarGroupSizeContext = createContext<AvatarSize | null>(null)
+
+export interface AvatarProps extends AvatarPrimitive.Root.Props {
+  /**
+   * Diameter of the circle (20 / 28 / 36 / 48 / 64 px) — and the size of the
+   * fallback initials with it. Inside an `AvatarGroup`, defaults to the group's.
+   * @default "default"
+   */
+  size?: AvatarSize
+}
+
 /** Circular avatar container. Compose `AvatarImage` + `AvatarFallback` inside. */
-function Avatar({ className, ...props }: AvatarPrimitive.Root.Props) {
+function Avatar({ className, size, ...props }: AvatarProps) {
+  const groupSize = useContext(AvatarGroupSizeContext)
+
   return (
     <AvatarPrimitive.Root
       data-slot="avatar"
-      className={cn(
-        "relative flex size-9 shrink-0 overflow-hidden rounded-full bg-muted select-none",
-        className
-      )}
+      className={cn(avatarVariants({ size: size ?? groupSize ?? undefined }), className)}
       {...props}
     />
   )
@@ -29,7 +65,8 @@ function AvatarFallback({ className, ...props }: AvatarPrimitive.Fallback.Props)
     <AvatarPrimitive.Fallback
       data-slot="avatar-fallback"
       className={cn(
-        "flex size-full items-center justify-center bg-muted text-sm font-medium text-muted-foreground",
+        // No text-size here on purpose — it comes from the root's `size`.
+        "flex size-full items-center justify-center bg-muted font-medium text-muted-foreground",
         className
       )}
       {...props}
@@ -37,4 +74,169 @@ function AvatarFallback({ className, ...props }: AvatarPrimitive.Fallback.Props)
   )
 }
 
-export { Avatar, AvatarImage, AvatarFallback }
+export type AvatarGroupSpacing = "tight" | "default" | "loose"
+
+// How far each avatar slides under the previous one. Expressed per size because
+// an overlap is a *ratio* of the circle (~29% at default), and Tailwind needs
+// whole class names — hence a table rather than a computed `-ml-${n}`.
+const OVERLAP: Record<AvatarSize, Record<AvatarGroupSpacing, string>> = {
+  xs: { tight: "-ml-2", default: "-ml-1.5", loose: "-ml-1" },
+  sm: { tight: "-ml-3", default: "-ml-2", loose: "-ml-1.5" },
+  default: { tight: "-ml-3.5", default: "-ml-2.5", loose: "-ml-2" },
+  lg: { tight: "-ml-5", default: "-ml-3.5", loose: "-ml-2.5" },
+  xl: { tight: "-ml-6", default: "-ml-5", loose: "-ml-3.5" },
+}
+
+// The ring is what separates two overlapping circles — it has to grow with them.
+const RING: Record<AvatarSize, string> = {
+  xs: "ring-[1.5px]",
+  sm: "ring-2",
+  default: "ring-2",
+  lg: "ring-2",
+  xl: "ring-[3px]",
+}
+
+export interface AvatarGroupProps extends Omit<ComponentProps<"div">, "children"> {
+  /** The avatars, in reading order. Each one paints over its left neighbour. */
+  children?: ReactNode
+  /**
+   * Size applied to every avatar in the stack (a child's own `size` still wins).
+   * @default "default"
+   */
+  size?: AvatarSize
+  /**
+   * Show at most this many avatars; the rest collapse into a `+N` counter.
+   * Left unset, everything is drawn.
+   */
+  max?: number
+  /**
+   * Real number of people, when the caller only renders a sample of them (a
+   * members list that fetched 5 avatars out of 40 → `total={40}` counts the 35
+   * it never received). Defaults to the number of children.
+   */
+  total?: number
+  /**
+   * How much of each avatar the next one covers — ~40%, ~29%, ~20%.
+   * @default "default"
+   */
+  spacing?: AvatarGroupSpacing
+  /**
+   * Ring color punched between overlapping avatars: it must match the surface
+   * *behind* the stack, so inside a `Card` it's `ring-card`.
+   * @default "ring-background"
+   */
+  ringClassName?: string
+  /**
+   * Hovering an avatar brings it to the front (and lifts it a hair), which is
+   * how a covered face becomes readable without a click.
+   * @default true
+   */
+  revealOnHover?: boolean
+  /** Makes the `+N` counter a real button — "see all members". */
+  onOverflowClick?: () => void
+  /** Accessible name of that button. @default "Voir tout" */
+  overflowLabel?: string
+}
+
+/**
+ * A stack of overlapping avatars — the compact way to say "these people".
+ *
+ * ```tsx
+ * <AvatarGroup size="sm" max={4} total={members.length}>
+ *   {members.map((m) => (
+ *     <Avatar key={m.id}>
+ *       <AvatarImage src={m.avatarUrl} alt={m.name} />
+ *       <AvatarFallback>{initials(m.name)}</AvatarFallback>
+ *     </Avatar>
+ *   ))}
+ * </AvatarGroup>
+ * ```
+ *
+ * Purely presentational, and deliberately **compositional**: the group never
+ * reads a `{ name, src }` shape, it wraps whatever you put in it — an `Avatar`,
+ * one inside a `Tooltip`, a `Skeleton` while the list loads. It only owns what
+ * a caller can't get right by hand: the overlap, the ring that separates two
+ * faces, the paint order, and the `+N`.
+ */
+function AvatarGroup({
+  className,
+  children,
+  size = "default",
+  max,
+  total,
+  spacing = "default",
+  ringClassName = "ring-background",
+  revealOnHover = true,
+  onOverflowClick,
+  overflowLabel = "Voir tout",
+  ...props
+}: AvatarGroupProps) {
+  const items = Children.toArray(children)
+  const limit = max != null && max > 0 ? max : items.length
+
+  let shown = items.slice(0, limit)
+  // People the caller knows about but didn't render at all.
+  const unrendered = Math.max(0, (total ?? items.length) - items.length)
+  let overflow = items.length - shown.length + unrendered
+
+  // A single hidden child costs exactly the room a "+1" would take, and says
+  // strictly less. Draw the face instead.
+  if (overflow === 1 && unrendered === 0) {
+    shown = items
+    overflow = 0
+  }
+
+  const item = (node: ReactNode, index: number) => (
+    <span
+      key={index}
+      data-slot="avatar-group-item"
+      className={cn(
+        "relative inline-flex rounded-full",
+        RING[size],
+        ringClassName,
+        index > 0 && OVERLAP[size][spacing],
+        revealOnHover && "transition-transform duration-150 hover:z-10 hover:-translate-y-0.5"
+      )}
+    >
+      {node}
+    </span>
+  )
+
+  const counter = `+${overflow}`
+  const counterClass = cn(
+    avatarVariants({ size }),
+    "items-center justify-center font-medium text-muted-foreground"
+  )
+
+  return (
+    <AvatarGroupSizeContext.Provider value={size}>
+      <div data-slot="avatar-group" className={cn("flex items-center", className)} {...props}>
+        {shown.map(item)}
+        {overflow > 0 &&
+          item(
+            onOverflowClick ? (
+              <button
+                type="button"
+                data-slot="avatar-group-overflow"
+                aria-label={overflowLabel}
+                onClick={onOverflowClick}
+                className={cn(
+                  counterClass,
+                  "cursor-pointer transition-colors hover:bg-primary/15 hover:text-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
+                )}
+              >
+                {counter}
+              </button>
+            ) : (
+              <span data-slot="avatar-group-overflow" className={counterClass}>
+                {counter}
+              </span>
+            ),
+            shown.length
+          )}
+      </div>
+    </AvatarGroupSizeContext.Provider>
+  )
+}
+
+export { Avatar, AvatarImage, AvatarFallback, AvatarGroup }

package/src/index.ts

@@ -23,7 +23,11 @@ export { RadioGroup, RadioGroupItem } from "./components/radio-group"
 export { Separator } from "./components/separator"
 export { Skeleton } from "./components/skeleton"
 export { Spinner, spinnerVariants } from "./components/spinner"
-export { Avatar, AvatarImage, AvatarFallback } from "./components/avatar"
+// Avatar + the stack of overlapping avatars (`AvatarGroup`) — compositional:
+// the group wraps whatever you put in it and owns the overlap, the ring, the
+// paint order and the `+N`.
+export { Avatar, AvatarImage, AvatarFallback, AvatarGroup } from "./components/avatar"
+export type { AvatarProps, AvatarSize, AvatarGroupProps, AvatarGroupSpacing } from "./components/avatar"
 
 // xterm.js surface — theme + fit-on-resize, transport-agnostic (feed it via
 // the write/writeln ref handle).