@sableui/react 0.6.2 → 0.7.1

package/dist/components/avatar/avatar.js

@@ -0,0 +1,192 @@
+"use client";
+
+// src/components/avatar/avatar.tsx
+import { Avatar as Base } from "@base-ui/react/avatar";
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useCallback,
+  useContext,
+  useRef,
+  useState
+} from "react";
+import { cn } from "../../lib/cn.js";
+import { GradientArt } from "../gradient-art/index.js";
+import { mergeRefs } from "../../lib/refs.js";
+import { useResizeObserver } from "../../lib/use-resize-observer.js";
+import { avatarGroupVariants, avatarVariants } from "./avatar.variants.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var AvatarGroupContext = createContext(null);
+var STATUS_SCALE = {
+  xl: "scale-200",
+  "2xl": "scale-250"
+};
+var IMAGE_FADE = {
+  xl: "motion-fade",
+  "2xl": "motion-fade"
+};
+function AvatarRoot({ size, className, ...props }) {
+  const group = useContext(AvatarGroupContext);
+  return /* @__PURE__ */ jsx(
+    Base.Root,
+    {
+      className: cn(avatarVariants({ size: group?.size ?? size }), className),
+      ...props
+    }
+  );
+}
+AvatarRoot.displayName = "AvatarRoot";
+function AvatarImage({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    Base.Image,
+    {
+      className: cn("aspect-square size-full object-cover", className),
+      ...props
+    }
+  );
+}
+AvatarImage.displayName = "AvatarImage";
+function AvatarFallback({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    Base.Fallback,
+    {
+      className: cn("text-muted-foreground", className),
+      ...props
+    }
+  );
+}
+AvatarFallback.displayName = "AvatarFallback";
+function Avatar({
+  src,
+  alt,
+  fallback,
+  fallbackDelay,
+  size,
+  status,
+  variant = "neutral",
+  seed,
+  className,
+  ...props
+}) {
+  const named = !src && alt ? { role: "img", "aria-label": alt } : null;
+  const avatar = /* @__PURE__ */ jsxs(AvatarRoot, { size, className: status == null ? className : void 0, ...named, ...props, children: [
+    src ? /* @__PURE__ */ jsx(AvatarImage, { src, alt: alt ?? "", className: size ? IMAGE_FADE[size] : void 0 }) : null,
+    variant === "art" ? /* @__PURE__ */ jsx(AvatarFallback, { delay: fallbackDelay, "aria-hidden": named ? true : void 0, className: "size-full", children: /* @__PURE__ */ jsxs(GradientArt, { seed: seed ?? (typeof fallback === "string" && fallback || alt || void 0), className: "flex size-full items-center justify-center text-overlay-foreground", children: [
+      /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: "absolute inset-0 bg-overlay/30" }),
+      /* @__PURE__ */ jsx("span", { className: "relative", children: fallback })
+    ] }) }) : /* @__PURE__ */ jsx(AvatarFallback, { delay: fallbackDelay, "aria-hidden": named ? true : void 0, children: fallback })
+  ] });
+  if (status == null) return avatar;
+  return /* @__PURE__ */ jsxs("span", { "data-slot": "avatar-status-anchor", className: cn("relative inline-flex shrink-0 rounded-full", className), children: [
+    avatar,
+    /* @__PURE__ */ jsx(
+      "span",
+      {
+        "data-slot": "avatar-status",
+        className: cn(
+          "absolute end-[14.6%] bottom-[14.6%] flex translate-x-1/2 translate-y-1/2 rounded-full rtl:-translate-x-1/2 *:ring-2 *:ring-[color:var(--avatar-group-ring,var(--background))]",
+          size ? STATUS_SCALE[size] : void 0
+        ),
+        children: status
+      }
+    )
+  ] });
+}
+Avatar.displayName = "Avatar";
+function AvatarGroupCount({
+  count,
+  label,
+  className,
+  ...props
+}) {
+  return /* @__PURE__ */ jsxs(AvatarRoot, { className, ...props, children: [
+    /* @__PURE__ */ jsxs("span", { "aria-hidden": true, className: "text-muted-foreground", children: [
+      "+",
+      count
+    ] }),
+    /* @__PURE__ */ jsx("span", { className: "sr-only", children: label ?? `and ${count} more` })
+  ] });
+}
+AvatarGroupCount.displayName = "AvatarGroupCount";
+var FIT_MIN_WIDTH = {
+  sm: "min-w-15",
+  md: "min-w-[--spacing(18.5)]",
+  lg: "min-w-22"
+};
+function AvatarGroup({
+  size,
+  surface,
+  max,
+  fit = false,
+  total,
+  countLabel,
+  className,
+  children,
+  ref,
+  ...props
+}) {
+  const items = Children.toArray(children).filter(isValidElement);
+  const people = total ?? items.length;
+  const [slots, setSlots] = useState(null);
+  const groupRef = useRef(null);
+  const measure = useCallback(() => {
+    const el = groupRef.current;
+    const first = el?.firstElementChild;
+    if (!fit || !el || !first) return;
+    const diameter = first.offsetWidth;
+    const second = first.nextElementSibling;
+    const step = second ? Math.abs(second.offsetLeft - first.offsetLeft) : diameter;
+    if (!diameter || !step) return;
+    setSlots(Math.max(1, Math.floor((el.clientWidth - diameter) / step) + 1));
+  }, [fit]);
+  useResizeObserver(measure, [groupRef]);
+  let limit = max !== void 0 && max >= 0 ? max : items.length;
+  if (slots !== null && Math.min(limit, items.length) + (people > Math.min(limit, items.length) ? 1 : 0) > slots) {
+    limit = Math.min(limit, Math.max(1, slots - 1));
+  }
+  const shown = items.length > limit ? items.slice(0, limit) : items;
+  const overflow = Math.max(0, people - shown.length);
+  const resolvedSize = size ?? "md";
+  return /* @__PURE__ */ jsx(AvatarGroupContext.Provider, { value: { size: resolvedSize }, children: /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: mergeRefs(groupRef, ref),
+      role: "group",
+      className: cn(
+        avatarGroupVariants({ size: resolvedSize, surface }),
+        // Fill the space the container leaves, rather than hug the avatars,
+        // so the width measured is the width available. `contain:
+        // inline-size` drops the avatars from the group's min-content width;
+        // without it a grid or flex parent sizes its track to fit all of
+        // them, and the group is never narrow enough to fold.
+        fit && "w-auto flex-1 [contain:inline-size]",
+        // …but never narrower than the least it will draw (one avatar and
+        // the count), so a row that cannot fit even that wraps its other
+        // items instead of letting the count slide under them.
+        fit && FIT_MIN_WIDTH[resolvedSize],
+        className
+      ),
+      ...props,
+      children: [
+        shown,
+        overflow > 0 ? /* @__PURE__ */ jsx(
+          AvatarGroupCount,
+          {
+            count: overflow,
+            label: countLabel?.(overflow)
+          }
+        ) : null
+      ]
+    }
+  ) });
+}
+AvatarGroup.displayName = "AvatarGroup";
+export {
+  Avatar,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
+  AvatarImage,
+  AvatarRoot
+};

package/dist/components/avatar/avatar.meta.js

@@ -0,0 +1,233 @@
+// src/components/avatar/avatar.meta.ts
+var avatarMeta = {
+  name: "Avatar",
+  summary: 'Circular profile image over Base UI Avatar \u2014 automatic image-load tracking with an initials/glyph fallback. Ergonomic Avatar plus low-level AvatarRoot/AvatarImage/AvatarFallback parts, and AvatarGroup for an overlapping stack with a "+N" overflow count.',
+  keywords: [
+    "avatar",
+    "profile",
+    "user",
+    "identity",
+    "initials",
+    "fallback",
+    "group",
+    "team",
+    "stack",
+    "overflow",
+    "collaborators",
+    "facepile"
+  ],
+  usage: {
+    description: 'Use Avatar to represent a person, team, or account with a compact visual identity. Wrap several in AvatarGroup for collaborators, assignees, or attendees \u2014 it overlaps them, rings each in the surface colour, and collapses the rest into a "+N" count; use the low-level parts only when you need custom image/fallback layout.',
+    bestPractices: [
+      {
+        guidance: "do",
+        description: 'Use `variant="art"` where people without photos sit side by side \u2014 a member list, an activity feed, a chat. Seeded by the person, each gets their own colour, so faces stay tellable apart at a glance; the neutral fallback makes everyone the same grey circle.'
+      },
+      {
+        guidance: "do",
+        description: "Provide meaningful alt text for profile images, or an empty alt when the adjacent text already names the person."
+      },
+      {
+        guidance: "do",
+        description: "Use initials or a simple glyph fallback so missing images still communicate identity."
+      },
+      {
+        guidance: "do",
+        description: "Pick the size by the job: sm in dense rows and tables, md (the default) beside one line of text, lg in a row with a title and subtitle, xl (96px) for a profile header beside the person's name, 2xl (160px) for an artist or profile hero and roster portraits. Keep one size within a list or group."
+      },
+      {
+        guidance: "do",
+        description: 'Use AvatarGroup for a stack of people, and give it an aria-label with the real count ("12 collaborators"). Set `surface` (or `--avatar-group-ring`) to whatever the group sits on, so the separating ring matches a card or popover, not the page. When it shares a row with actions, set `fit` so it gives up avatars to the "+N" count before the row has to wrap.'
+      },
+      {
+        guidance: "dont",
+        description: 'Hand-build a stack with negative margins and per-avatar ring classes, or fake the overflow as an Avatar with "+4" initials \u2014 screen readers hear "plus 4" with no context. Use AvatarGroup\'s `max`/`total`, or AvatarGroupCount.'
+      },
+      {
+        guidance: "dont",
+        description: "Use avatars as decoration without nearby identity context. They should help users recognize a person or account."
+      },
+      {
+        guidance: "dont",
+        description: "Overload a dense table with large avatars; use sm or omit images when scanning data is more important."
+      },
+      {
+        guidance: "dont",
+        description: 'Build a portrait by stretching an Avatar with size classes (`className="size-40"`) \u2014 the initials, the status indicator and the image fade stay at row scale. Use size="xl" or "2xl", which scale all three. Past 160px, or for a non-circular cover, it is media: an AspectBox, not an avatar.'
+      }
+    ],
+    anatomy: [
+      {
+        name: "Root",
+        required: true,
+        description: "The circular frame that clips the image, owns size, and contains image plus fallback."
+      },
+      {
+        name: "Image",
+        required: false,
+        description: "The loaded profile image, cropped to fill the root."
+      },
+      {
+        name: "Fallback",
+        required: true,
+        description: "Initials, a glyph, or short text shown while loading, on error, or when no image exists."
+      },
+      {
+        name: "Group",
+        required: false,
+        description: "AvatarGroup: the overlapping stack. Sets one size for every avatar and rings each in the surface colour."
+      },
+      {
+        name: "Count",
+        required: false,
+        description: 'AvatarGroupCount: the "+N" avatar ending a group, read as "and N more". Rendered automatically by `max`/`total`.'
+      }
+    ]
+  },
+  related: {
+    components: ["Entity", "StatusDot", "Badge", "Row"],
+    patterns: ["DashboardPage", "ListDetailPage"]
+  },
+  status: "stable",
+  props: [
+    {
+      name: "src",
+      type: "string",
+      description: "Image source. When omitted, still loading, or failed, the fallback shows."
+    },
+    {
+      name: "alt",
+      type: "string",
+      default: '""',
+      description: "Alt text for the image. Without an image it becomes the avatar's accessible name (role=img), so the initials are never read out as the name."
+    },
+    {
+      name: "fallback",
+      type: "ReactNode",
+      description: "Initials or a glyph rendered when no image is displayed."
+    },
+    {
+      name: "fallbackDelay",
+      type: "number",
+      description: "Delay before showing the fallback, in ms \u2014 avoids a flash on fast loads."
+    },
+    {
+      name: "status",
+      type: "ReactNode",
+      description: 'A presence indicator pinned to the bottom-end edge, usually <StatusDot tone="success" />. It sits outside the clipped circle and wears a ring in the surface colour (--avatar-group-ring, else the page background). Use this instead of absolutely positioning a dot over an Avatar.'
+    },
+    {
+      name: "size",
+      type: '"sm" | "md" | "lg" | "xl" | "2xl"',
+      default: '"md"',
+      description: "Square footprint: 32px / 40px / 48px for rows; 96px / 160px for portraits (a profile header, an artist hero, a roster tile). The initials, a status indicator and its cut-out ring scale with it, and at the portrait sizes the photo fades in over the resting surface."
+    },
+    {
+      name: "variant",
+      type: '"neutral" | "art"',
+      default: '"neutral"',
+      description: "What the fallback looks like. neutral: initials on the muted surface. art: initials over GradientArt seeded by the person, so each person without a photo gets their own stable colour from the theme."
+    },
+    {
+      name: "seed",
+      type: "string | number",
+      description: "The art variant's seed. Defaults to the fallback text, then `alt`, so a person keeps one colour wherever they appear; pass a user id to tell apart two people who share initials."
+    }
+  ],
+  subcomponents: [
+    {
+      name: "AvatarRoot",
+      type: "Base UI Avatar.Root props + size + className",
+      description: "Low-level circular frame for full composition control \u2014 clips the image and holds the `size` axis. Wraps AvatarImage and AvatarFallback."
+    },
+    {
+      name: "AvatarImage",
+      type: "Base UI Avatar.Image props + className",
+      description: "The profile image. Fills and crops the frame; hidden by Base UI until it loads."
+    },
+    {
+      name: "AvatarFallback",
+      type: "Base UI Avatar.Fallback props (delay) + className",
+      description: "Shown when no image is available \u2014 typically initials or a glyph. Accepts a delay prop."
+    },
+    {
+      name: "AvatarGroup",
+      type: '{ size?: "sm" | "md" | "lg"; surface?: "background" | "card" | "popover" | "muted"; max?: number; fit?: boolean; total?: number; countLabel?: (count: number) => string; "aria-label"?: string; className?: string; children: ReactNode }',
+      description: 'Overlapping stack (role=group) \u2014 name it with aria-label ("12 collaborators"). `size` applies to every avatar inside. `max` shows that many and collapses the rest into a "+N" count; `total` is the real head-count when you only pass some people. `fit` shows only as many avatars as fit the width the group is given (it fills the space left in a flex row) and folds the rest into the count, so a tight row reads "MO SR +5" instead of wrapping. The separating ring reads the inherited `--avatar-group-ring` (default: the page background); `surface` sets it to card, popover, or muted.'
+    },
+    {
+      name: "AvatarGroupCount",
+      type: '{ count: number; label?: string; size?: "sm" | "md" | "lg"; className?: string }',
+      description: 'The "+N" avatar. Shows "+4" and reads "and 4 more" (override with label). AvatarGroup renders it for you from max/total; use it directly only when composing the stack yourself.'
+    }
+  ],
+  variants: {
+    size: ["sm", "md", "lg", "xl", "2xl"],
+    variant: ["neutral", "art"]
+  },
+  tokensUsed: ["muted", "muted-foreground", "background", "card", "popover", "overlay", "overlay-foreground"],
+  a11y: [
+    "Base UI tracks the image loading status and swaps to the fallback on missing/loading/error \u2014 no manual onError wiring.",
+    "Provide meaningful alt text via the alt prop; pass an empty alt for decorative avatars.",
+    "The fallback (initials/glyph) gives a non-image identity cue for screen readers and slow connections.",
+    'AvatarGroup renders role=group; give it an aria-label naming the whole set ("12 collaborators"), since the visible stack only shows some of them.',
+    'The "+N" count is hidden from screen readers and replaced by "and N more" (AvatarGroupCount `label`, or AvatarGroup `countLabel`).'
+  ],
+  motion: [
+    { slot: "arrival", recipe: "motion-fade", part: "Image", why: "At the portrait sizes (xl, 2xl) the photo replacing the initials is a visible pop across one of the page's largest elements; fading it in reads as the picture arriving, not the layout glitching. Row sizes swap instantly \u2014 too small to register, and a list of fading faces would shimmer." },
+    { slot: "response", recipe: "none", part: "Root", why: "An avatar is not interactive itself; a link or button wrapping it owns the response." },
+    { slot: "transition", recipe: "none", part: "Root", why: "It has no states of its own to move between beyond the image arriving." },
+    { slot: "activity", recipe: "none", part: "Root", why: "Loading shows the fallback, which is already a finished resting state rather than a spinner." }
+  ],
+  examples: [
+    {
+      label: "With image",
+      code: '<Avatar src="/pfp.png" alt="Alex Morgan" fallback="AM" />'
+    },
+    {
+      label: "Fallback only",
+      code: '<Avatar fallback="AM" alt="Alex Morgan" />'
+    },
+    {
+      label: "Art fallback",
+      code: '<Avatar variant="art" fallback="AM" alt="Alex Morgan" />'
+    },
+    {
+      label: "Sizes",
+      code: '<Avatar src="/pfp.png" alt="Alex Morgan" fallback="AM" size="sm" />\n<Avatar src="/pfp.png" alt="Alex Morgan" fallback="AM" size="md" />\n<Avatar src="/pfp.png" alt="Alex Morgan" fallback="AM" size="lg" />'
+    },
+    {
+      label: "Profile portrait",
+      code: `<div className="flex flex-col items-center gap-3 text-center">
+	<Avatar variant="art" size="2xl" fallback="LV" alt="Lena Vale" status={<StatusDot tone="success" />} />
+	<div className="flex flex-col gap-1">
+		<h1 className="text-heading-1">Lena Vale</h1>
+		<p className="text-body-sm text-muted-foreground">1.2M monthly listeners</p>
+	</div>
+</div>`
+    },
+    {
+      label: "Low-level parts",
+      code: '<AvatarRoot size="lg"><AvatarImage src="/pfp.png" alt="Mara Okafor" /><AvatarFallback>MO</AvatarFallback></AvatarRoot>'
+    },
+    {
+      label: "Group with overflow",
+      code: '<AvatarGroup aria-label="6 collaborators" max={3} size="sm" surface="card"><Avatar src="/ana.png" alt="Ana Chen" fallback="AC" /><Avatar src="/mika.png" alt="Mika Lee" fallback="ML" /><Avatar fallback="JL" alt="Jo Lund" /><Avatar fallback="AK" alt="Ari Kim" /><Avatar fallback="SR" alt="Sam Reyes" /><Avatar fallback="MO" alt="Mo Ortiz" /></AvatarGroup>'
+    },
+    {
+      label: "Group of a larger set",
+      code: '<AvatarGroup aria-label="12 attendees" total={12} countLabel={(n) => `and ${n} more attendees`}><Avatar fallback="MO" alt="Mo Ortiz" /><Avatar fallback="SR" alt="Sam Reyes" /><Avatar fallback="JL" alt="Jo Lund" /></AvatarGroup>'
+    },
+    {
+      label: "Composed count",
+      code: '<AvatarGroup aria-label="7 reviewers"><Avatar fallback="AC" alt="Ana Chen" /><Avatar fallback="ML" alt="Mika Lee" /><AvatarGroupCount count={5} label="and 5 more reviewers" /></AvatarGroup>'
+    },
+    {
+      label: "With status",
+      code: '<Entity leading={<Avatar src="/pfp.png" alt="Nova Reed" fallback="NR" status={<StatusDot tone="success" />} />} title="Nova Reed" subtitle="Online" />'
+    }
+  ]
+};
+export {
+  avatarMeta
+};

package/dist/components/avatar/avatar.variants.js

@@ -0,0 +1,44 @@
+// src/components/avatar/avatar.variants.ts
+import { cva } from "class-variance-authority";
+var avatarVariants = cva(
+  "relative inline-flex shrink-0 select-none items-center justify-center overflow-hidden rounded-full bg-muted",
+  {
+    variants: {
+      size: {
+        sm: "size-8 text-label-sm",
+        md: "size-10 text-label-md",
+        lg: "size-12 text-label-lg",
+        xl: "size-24 text-heading-2",
+        "2xl": "size-40 text-display-lg"
+      }
+    },
+    defaultVariants: {
+      size: "md"
+    }
+  }
+);
+var avatarGroupVariants = cva(
+  "flex w-fit items-center *:ring-2 *:ring-[color:var(--avatar-group-ring,var(--background))]",
+  {
+    variants: {
+      size: {
+        sm: "*:not-first:-ms-1",
+        md: "*:not-first:-ms-1.5",
+        lg: "*:not-first:-ms-2"
+      },
+      surface: {
+        background: "[--avatar-group-ring:var(--background)]",
+        card: "[--avatar-group-ring:var(--card)]",
+        popover: "[--avatar-group-ring:var(--popover)]",
+        muted: "[--avatar-group-ring:var(--muted)]"
+      }
+    },
+    defaultVariants: {
+      size: "md"
+    }
+  }
+);
+export {
+  avatarGroupVariants,
+  avatarVariants
+};

package/dist/components/avatar/index.js

@@ -0,0 +1,22 @@
+// src/components/avatar/index.ts
+import {
+  Avatar,
+  AvatarRoot,
+  AvatarImage,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount
+} from "./avatar.js";
+import { avatarVariants, avatarGroupVariants } from "./avatar.variants.js";
+import { avatarMeta } from "./avatar.meta.js";
+export {
+  Avatar,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
+  AvatarImage,
+  AvatarRoot,
+  avatarGroupVariants,
+  avatarMeta,
+  avatarVariants
+};

package/dist/components/badge/badge.js

@@ -0,0 +1,26 @@
+// src/components/badge/badge.tsx
+import { cn } from "../../lib/cn.js";
+import { trimLabel } from "../../lib/trim-label.js";
+import { StatusDot } from "../status-dot/index.js";
+import { badgeVariants } from "./badge.variants.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function Badge({
+  appearance = "soft",
+  tone = "neutral",
+  size,
+  icon,
+  dot = false,
+  pulse = false,
+  className,
+  children,
+  ...props
+}) {
+  return /* @__PURE__ */ jsxs("span", { className: cn(badgeVariants({ appearance, tone, size }), "[&_svg]:shrink-0", className), ...props, children: [
+    dot ? /* @__PURE__ */ jsx(StatusDot, { tone, pulse, size: size === "sm" ? "sm" : "md" }) : icon,
+    trimLabel(children)
+  ] });
+}
+Badge.displayName = "Badge";
+export {
+  Badge
+};