@sableui/react 0.6.2 → 0.7.1

package/dist/components/marker/marker.meta.js

@@ -0,0 +1,132 @@
+// src/components/marker/marker.meta.ts
+var markerMeta = {
+  name: "Marker",
+  summary: "A non-message row in a conversation: streaming status, system note, bordered notice, or a labelled rule for date breaks. Quieter than the message tier by design.",
+  status: "stable",
+  keywords: [
+    "chat status",
+    "typing indicator",
+    "thinking",
+    "streaming",
+    "tool call",
+    "system message",
+    "date separator",
+    "date break",
+    "conversation divider"
+  ],
+  usage: {
+    description: 'Everything in a conversation that is not a message. Date breaks, "Carla joined", "Thinking\u2026", "Ran search \u2014 3 results", "Message failed to send". One component because they share one job: annotate the stream without competing with it.',
+    bestPractices: [
+      {
+        guidance: "do",
+        description: 'Use `status` with `icon="spinner" spin` for work in flight, and add `shimmer` while text is actually streaming. The shimmer is scale-aware, so it freezes with the rest of the system under reduced motion.'
+      },
+      {
+        guidance: "do",
+        description: 'Use `variant="separator"` for date breaks. The label sits between two rules, which reads as a division of the transcript rather than as another thing someone said.'
+      },
+      {
+        guidance: "do",
+        description: `Replace a status marker's text as the work progresses \u2014 "Thinking\u2026" \u2192 "Searching the docs" \u2192 "Writing the answer". It is a live region, so each change is announced.`
+      },
+      {
+        guidance: "do",
+        description: "Reach for `bordered` only when a note needs containing \u2014 an error, an escalation, a retention notice. Boxing routine system events makes a transcript look like a list of alerts."
+      },
+      {
+        guidance: "dont",
+        description: "Do not style a Marker up to message weight. Its whole value is being below that tier; a marker as loud as a message competes with the conversation it is annotating."
+      },
+      {
+        guidance: "dont",
+        description: 'Do not leave a status marker mounted after the work finishes. A permanent "Thinking\u2026" is a live region that never resolves, which is worse than no status at all.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it for a message from a person or an assistant. That is `Message` + `Bubble` \u2014 a marker has no author and no side."
+      },
+      {
+        guidance: "dont",
+        description: "Do not set `live` on a `separator` or on a run of `note` markers. Announcing every date break and join event turns the live region into noise and buries the status that mattered."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Message",
+      "Bubble",
+      "MessageScroller",
+      "InlineStatus",
+      "Separator"
+    ]
+  },
+  props: [
+    {
+      name: "variant",
+      type: '"status" | "note" | "bordered" | "separator"',
+      default: '"status"',
+      description: "`status` for live activity, `note` for a system event, `bordered` for a note that needs containing, `separator` for a labelled rule."
+    },
+    {
+      name: "icon",
+      type: "string",
+      description: "Semantic icon name shown before the label, resolved through IconProvider."
+    },
+    {
+      name: "spin",
+      type: "boolean",
+      default: "false",
+      description: 'Spin the icon \u2014 pair with `icon="spinner"` for work in flight.'
+    },
+    {
+      name: "shimmer",
+      type: "boolean",
+      default: "false",
+      description: "Sweep the label while something is streaming, via the scale-aware `motion-text-shimmer` recipe (freezes under reduced motion)."
+    },
+    {
+      name: "live",
+      type: "boolean",
+      default: "true for `status`, false otherwise",
+      description: "Announce the label to assistive tech as it changes. On for `status`, because a screen-reader user otherwise gets silence for the whole generation and no way to tell a slow answer from a dead one."
+    },
+    {
+      name: "...div props",
+      type: 'ComponentPropsWithRef<"div">',
+      description: "Spread onto the row."
+    }
+  ],
+  variants: { variant: ["status", "note", "bordered", "separator"] },
+  tokensUsed: ["muted-foreground", "muted", "border", "foreground"],
+  a11y: [
+    '`status` markers render as `role="status"` with `aria-live="polite"`, so a change of activity is announced without interrupting whatever is being read.',
+    "The other variants are silent by default and can opt in with `live` \u2014 announcing every date break and join event would bury the status that mattered.",
+    "The separator's rules are `aria-hidden`, leaving only the label in the accessibility tree; the shimmer is decoration over readable text, not a replacement for it.",
+    "`motion-text-shimmer` keeps the label opaque through every frame \u2014 the gradient runs muted-foreground \u2192 foreground rather than fading to transparent, so the text never becomes unreadable mid-animation, and `--motion-scale` freezes it entirely under reduced motion."
+  ],
+  examples: [
+    {
+      label: "Streaming status",
+      code: '<Marker icon="spinner" spin shimmer>Thinking\u2026</Marker>'
+    },
+    {
+      label: "Date break",
+      code: '<Marker variant="separator">Yesterday</Marker>'
+    },
+    {
+      label: "System note",
+      code: '<Marker variant="note" icon="user">Carla joined the conversation</Marker>'
+    },
+    {
+      label: "A notice that needs containing",
+      code: '<Marker variant="bordered" icon="warning">This conversation will be archived in 7 days.</Marker>'
+    },
+    {
+      label: "In a transcript",
+      code: '<MessageScroller className="h-96">\n	<Marker variant="separator">Today</Marker>\n	<Message messageId="m1"><Bubble>Can you summarise the release?</Bubble></Message>\n	<Marker variant="note" icon="sparkles">Ran changelog \u2014 12 entries</Marker>\n	<Marker icon="spinner" spin shimmer>Writing the answer</Marker>\n</MessageScroller>'
+    }
+  ]
+};
+export {
+  markerMeta
+};

package/dist/components/marker/marker.variants.js

@@ -0,0 +1,25 @@
+// src/components/marker/marker.variants.ts
+import { cva } from "class-variance-authority";
+var markerVariants = cva(
+  "flex w-full items-center gap-2 text-body-xs text-muted-foreground",
+  {
+    variants: {
+      variant: {
+        /** Live activity — "Thinking…", "Searching the docs". */
+        status: "justify-center py-0.5",
+        /** A system note — "Carla joined", "Conversation assigned to Support". */
+        note: "justify-center py-0.5",
+        /** A note that needs a container — errors, escalations, retention notices. */
+        bordered: "justify-center rounded-md border border-border bg-muted/40 px-3 py-2",
+        /** A labelled rule — the date break. */
+        separator: "gap-3 py-1"
+      }
+    },
+    defaultVariants: { variant: "status" }
+  }
+);
+var markerRuleVariants = cva("w-auto flex-1");
+export {
+  markerRuleVariants,
+  markerVariants
+};

package/dist/components/marquee/index.js

@@ -0,0 +1,7 @@
+// src/components/marquee/index.ts
+import { Marquee } from "./marquee.js";
+import { marqueeMeta } from "./marquee.meta.js";
+export {
+  Marquee,
+  marqueeMeta
+};

package/dist/components/marquee/marquee.js

@@ -0,0 +1,146 @@
+"use client";
+
+// src/components/marquee/marquee.tsx
+import { useCallback, useMemo, useRef, useState } from "react";
+import { cn } from "../../lib/cn.js";
+import { PlayPauseGlyph } from "../../lib/glyphs.js";
+import { mergeRefs } from "../../lib/refs.js";
+import { useResizeObserver } from "../../lib/use-resize-observer.js";
+import { useMotion } from "../../motion/MotionProvider.js";
+import { Button } from "../button/button.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function Marquee({
+  children,
+  direction = "left",
+  speed = 40,
+  gap = "calc(var(--spacing) * 8)",
+  pauseOnHover = true,
+  controls = false,
+  play,
+  onPlayChange,
+  fade = false,
+  label,
+  className,
+  style,
+  ref,
+  ...props
+}) {
+  const { enabled } = useMotion();
+  const [userPaused, setUserPaused] = useState(false);
+  const isPaused = play != null ? !play : userPaused;
+  const togglePlay = () => {
+    if (play != null) onPlayChange?.(!play);
+    else setUserPaused((p) => !p);
+  };
+  const containerRef = useRef(null);
+  const groupRef = useRef(null);
+  const [copies, setCopies] = useState(2);
+  const [metrics, setMetrics] = useState({ distance: 0, duration: 0 });
+  const vertical = direction === "up" || direction === "down";
+  const reverse = direction === "right" || direction === "down";
+  const measure = useCallback(() => {
+    const container = containerRef.current;
+    const group = groupRef.current;
+    if (!container || !group) return;
+    const cs = getComputedStyle(group);
+    const gapPx = Number.parseFloat(vertical ? cs.rowGap : cs.columnGap) || 0;
+    const groupSize = vertical ? group.offsetHeight : group.offsetWidth;
+    const containerSize = vertical ? container.offsetHeight : container.offsetWidth;
+    if (groupSize <= 0) return;
+    const distance = groupSize + gapPx;
+    const duration = distance / speed;
+    const needed = Math.min(
+      8,
+      Math.max(2, Math.ceil(containerSize / distance) + 1)
+    );
+    setCopies((c) => c === needed ? c : needed);
+    setMetrics(
+      (m) => Math.abs(m.distance - distance) < 0.5 && Math.abs(m.duration - duration) < 0.01 ? m : { distance, duration }
+    );
+  }, [speed, vertical]);
+  useResizeObserver(measure, [containerRef, groupRef]);
+  const setContainer = useMemo(() => mergeRefs(containerRef, ref), [ref]);
+  const animate = enabled && metrics.duration > 0;
+  const trackStyle = { gap };
+  if (animate) {
+    trackStyle["--sable-marquee-distance"] = `${metrics.distance}px`;
+    trackStyle.animationName = vertical ? "sable-marquee-y" : "sable-marquee-x";
+    trackStyle.animationDuration = `${metrics.duration}s`;
+    trackStyle.animationTimingFunction = "linear";
+    trackStyle.animationIterationCount = "infinite";
+    trackStyle.animationDirection = reverse ? "reverse" : "normal";
+    trackStyle.willChange = "transform";
+    if (isPaused) trackStyle.animationPlayState = "paused";
+  }
+  const groups = animate ? copies : 1;
+  const fadeMask = fade ? (
+    // design-lint-disable-next-line inline-color -- CSS edge-fade mask: #000 is alpha-mask machinery (only the mask alpha matters), not a rendered color
+    `linear-gradient(${vertical ? "to bottom" : "to right"}, transparent, #000 calc(var(--spacing) * 8), #000 calc(100% - var(--spacing) * 8), transparent)`
+  ) : void 0;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: setContainer,
+      "data-sable-marquee": "",
+      "data-pause-on-hover": pauseOnHover ? "" : void 0,
+      role: label ? "group" : void 0,
+      "aria-label": label,
+      className: cn(
+        "group/marquee relative max-w-full overflow-hidden",
+        // When motion is off, fall back to a normal scroll region.
+        !animate && (vertical ? "overflow-y-auto overscroll-contain scrollbar-quiet" : "overflow-x-auto overscroll-x-contain scrollbar-quiet"),
+        className
+      ),
+      style: { ...style, maskImage: fadeMask, WebkitMaskImage: fadeMask },
+      ...props,
+      children: [
+        controls && animate && // The floating Button — the same control that sits over Carousel's
+        // slides and MessageScroller's thread, read over moving content.
+        /* @__PURE__ */ jsx(
+          Button,
+          {
+            variant: "floating",
+            size: "icon-xs",
+            onClick: togglePlay,
+            "aria-label": isPaused ? "Play" : "Pause",
+            className: "absolute end-2 top-2 z-10",
+            children: /* @__PURE__ */ jsx(PlayPauseGlyph, { playing: !isPaused })
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            "data-sable-marquee-track": "",
+            className: cn(
+              "flex",
+              // Vertical track is absolute ONLY while animating, so it doesn't
+              // drive container height (the feedback loop). When motion is
+              // off it stays in-flow so the scroll fallback has content.
+              vertical ? animate ? "absolute inset-x-0 top-0 flex-col" : "flex-col" : "w-max"
+            ),
+            style: trackStyle,
+            children: Array.from({ length: groups }, (_, i) => /* @__PURE__ */ jsx(
+              "div",
+              {
+                ref: i === 0 ? groupRef : void 0,
+                "aria-hidden": i > 0 ? true : void 0,
+                inert: i > 0 || void 0,
+                className: cn(
+                  "flex shrink-0 items-center",
+                  vertical ? "flex-col" : "w-max"
+                ),
+                style: { gap },
+                children
+              },
+              i
+            ))
+          }
+        )
+      ]
+    }
+  );
+}
+Marquee.displayName = "Marquee";
+export {
+  Marquee
+};

package/dist/components/marquee/marquee.meta.js

@@ -0,0 +1,106 @@
+// src/components/marquee/marquee.meta.ts
+var marqueeMeta = {
+  name: "Marquee",
+  summary: "Seamless, constant-speed infinite loop (logos, tags, testimonials). Zero-dependency: duplicates children to fill the track and advances exactly one group + gap per iteration so it never seams. Pauses on hover/focus; freezes to a scroll region when motion is off/reduced.",
+  status: "stable",
+  keywords: [
+    "marquee",
+    "ticker",
+    "scrolling",
+    "ambient"
+  ],
+  usage: {
+    description: "Use Marquee for decorative or ambient continuous content where motion supports the surface.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it for low-priority repeated content such as logos, tags, or lightweight highlights."
+      },
+      {
+        guidance: "do",
+        description: "Respect reduced motion and keep the content understandable without relying on animation."
+      },
+      {
+        guidance: "dont",
+        description: "Do not put critical messages, controls, or required reading inside Marquee."
+      },
+      {
+        guidance: "dont",
+        description: "Do not put content that must be read in a Marquee. It moves continuously, so anything longer than a logo or a short label cannot be read reliably \u2014 and it must stop for prefers-reduced-motion."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Scroller",
+      "Carousel",
+      "Badge"
+    ]
+  },
+  props: [
+    {
+      name: "direction",
+      type: '"left" | "right" | "up" | "down"',
+      default: '"left"',
+      description: 'Scroll direction; up/down switch to a vertical loop, which needs a bounded height (e.g. className="h-56").'
+    },
+    {
+      name: "speed",
+      type: "number",
+      default: "40",
+      description: "Constant speed in px/s \u2014 independent of content length."
+    },
+    {
+      name: "gap",
+      type: "string",
+      default: '"calc(var(--spacing) * 8)"',
+      description: "Gap between items (any CSS length). Use a spacing-scale value (calc(var(--spacing) * n)) so it moves with density."
+    },
+    {
+      name: "pauseOnHover",
+      type: "boolean",
+      default: "true",
+      description: "Pause while hovered or keyboard-focused (WCAG 2.2.2)."
+    },
+    {
+      name: "controls",
+      type: "boolean",
+      default: "false",
+      description: "Render a visible pause/play control \u2014 recommended for WCAG 2.2.2 when content auto-scrolls."
+    },
+    {
+      name: "fade",
+      type: "boolean",
+      default: "false",
+      description: "Fade the leading/trailing edges with a mask."
+    },
+    {
+      name: "label",
+      type: "string",
+      description: "Accessible label for the scrolling region."
+    }
+  ],
+  tokensUsed: [],
+  a11y: [
+    "Duplicate groups are aria-hidden, so screen readers read the content once.",
+    "Pauses on hover and focus-within; under prefers-reduced-motion / MotionProvider off it stops and becomes a normal scroll region.",
+    "Decorative by default \u2014 pass a label only when the row conveys meaning."
+  ],
+  examples: [
+    {
+      label: "Logo row",
+      code: '<Marquee>{logos.map((l) => <img key={l.id} src={l.src} alt={l.name} className="h-8" />)}</Marquee>'
+    },
+    {
+      label: "Reverse, faster",
+      code: '<Marquee direction="right" speed={70}>{tags.map((t) => <Badge key={t} appearance="outline">{t}</Badge>)}</Marquee>'
+    },
+    {
+      label: "Vertical",
+      code: '<Marquee direction="up" className="h-64">{items}</Marquee>'
+    }
+  ]
+};
+export {
+  marqueeMeta
+};

package/dist/components/media-image/index.js

@@ -0,0 +1,7 @@
+// src/components/media-image/index.ts
+import { MediaImage } from "./media-image.js";
+import { mediaImageMeta } from "./media-image.meta.js";
+export {
+  MediaImage,
+  mediaImageMeta
+};

package/dist/components/media-image/media-image.js

@@ -0,0 +1,56 @@
+"use client";
+
+// src/components/media-image/media-image.tsx
+import { Avatar as Base } from "@base-ui/react/avatar";
+import { useState } from "react";
+import { cn } from "../../lib/cn.js";
+import { GradientArt } from "../gradient-art/index.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function MediaImage({
+  src,
+  alt = "",
+  seed,
+  fallback,
+  fit = "cover",
+  srcSet,
+  sizes,
+  loading = "lazy",
+  className,
+  ...props
+}) {
+  const [tracked, setTracked] = useState({ src, status: "idle" });
+  const status = !src ? "error" : tracked.src === src ? tracked.status : "idle";
+  const showFallback = status === "error";
+  const named = status !== "loaded" && alt ? { role: "img", "aria-label": alt } : null;
+  return /* @__PURE__ */ jsxs(
+    Base.Root,
+    {
+      render: /* @__PURE__ */ jsx("div", {}),
+      "data-slot": "media-image",
+      "data-status": status,
+      className: cn("relative block size-full overflow-hidden bg-muted", className),
+      ...named,
+      ...props,
+      children: [
+        src ? /* @__PURE__ */ jsx(
+          Base.Image,
+          {
+            src,
+            srcSet,
+            sizes,
+            alt,
+            loading,
+            decoding: "async",
+            onLoadingStatusChange: (next) => setTracked({ src, status: next }),
+            className: cn("size-full motion-fade", fit === "contain" ? "object-contain" : "object-cover")
+          }
+        ) : null,
+        showFallback ? /* @__PURE__ */ jsx("div", { "data-slot": "media-image-fallback", "aria-hidden": true, className: "absolute inset-0", children: fallback ?? /* @__PURE__ */ jsx(GradientArt, { seed: seed ?? (alt || void 0), className: "size-full" }) }) : null
+      ]
+    }
+  );
+}
+MediaImage.displayName = "MediaImage";
+export {
+  MediaImage
+};

package/dist/components/media-image/media-image.meta.js

@@ -0,0 +1,92 @@
+// src/components/media-image/media-image.meta.ts
+var mediaImageMeta = {
+  name: "MediaImage",
+  summary: "An image that fills its box and falls back to GradientArt seeded by the item when it has no source or the source fails \u2014 Avatar's image-load tracking, for covers, thumbnails and product shots instead of faces.",
+  status: "beta",
+  keywords: [
+    "image",
+    "img",
+    "image fallback",
+    "broken image",
+    "cover art",
+    "album art",
+    "thumbnail",
+    "placeholder image",
+    "onError",
+    "missing image"
+  ],
+  usage: {
+    description: "Use MediaImage wherever content imagery may be missing or broken: a cover in a grid, a thumbnail in a row, a product shot. It fills the box it is given \u2014 an AspectBox for a cover, a sized and rounded box for a thumbnail \u2014 shows a quiet muted surface while the image loads, fades the image in once decoded, and paints GradientArt seeded by the item when there is no image to show, so a grid of missing covers still reads as distinct things. For a person use Avatar; for a whole tile with title and actions use MediaTile, which composes this.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: 'Give the box the shape: `<AspectBox ratio={1} className="rounded-md"><MediaImage \u2026 /></AspectBox>`, or `size-14 rounded-md` on MediaImage itself for a thumbnail. It clips to whatever radius the box has.'
+      },
+      {
+        guidance: "do",
+        description: "Pass `seed` (the title or an id) when `alt` is empty, so the fallback art is the item's own and stays the same in every list it appears in."
+      },
+      {
+        guidance: "do",
+        description: "Leave `alt` empty when a visible title sits next to the image \u2014 a tile, a row \u2014 and describe it when the image stands alone. A set `alt` also names the fallback, so the description survives a broken URL."
+      },
+      {
+        guidance: "dont",
+        description: "Do not hand-write `<img onError={() => setBroken(true)}>`. An image that fails before hydration never fires the handler on a prerendered page; MediaImage preloads off the DOM and catches it."
+      },
+      {
+        guidance: "dont",
+        description: 'Do not use it for profile pictures. A person is a circle with initials \u2014 Avatar, whose `variant="art"` is the same fallback with the person\'s initials over it.'
+      }
+    ]
+  },
+  related: { components: ["MediaTile", "Avatar", "GradientArt", "AspectBox"] },
+  props: [
+    { name: "src", type: "string", description: "Image URL. Omitted, empty or failing to load \u21D2 the fallback shows." },
+    {
+      name: "alt",
+      type: "string",
+      default: '""',
+      description: "Alt text. Empty is decorative \u2014 right beside a visible title. When set and no image shows, it names the fallback instead."
+    },
+    { name: "seed", type: "string | number", description: "Seeds the fallback art. Defaults to `alt`; pass the title or an id when `alt` is empty." },
+    { name: "fallback", type: "ReactNode", description: "Replaces the GradientArt fallback \u2014 a glyph or monogram. Fills the frame under the same clipping." },
+    {
+      name: "fit",
+      type: '"cover" | "contain"',
+      default: '"cover"',
+      description: "`cover` crops to fill (artwork, photos); `contain` letterboxes on the muted surface (a logo, a product that must not be cropped)."
+    },
+    { name: "srcSet", type: "string", description: "Responsive sources, passed to the `<img>`." },
+    { name: "sizes", type: "string", description: "The `sizes` attribute for `srcSet`." },
+    { name: "loading", type: '"lazy" | "eager"', default: '"lazy"', description: "Native lazy loading. Use `eager` for the first row of a grid above the fold." },
+    { name: "className", type: "string", description: "Sizing and rounding when MediaImage is the box itself (`size-14 rounded-md`). Inside an AspectBox it already fills." }
+  ],
+  variants: { fit: ["cover", "contain"] },
+  tokensUsed: ["muted", "art-1", "art-2", "art-3", "art-4", "art-5", "art-6", "art-ground"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "motion-fade",
+      part: "image",
+      why: "The image fades in over the muted surface once it has decoded, so a slow cover settles in instead of popping row by row as the grid loads."
+    },
+    { slot: "response", recipe: "none", part: "root", why: "Imagery, not a control. The tile or row around it answers the pointer." },
+    { slot: "transition", recipe: "none", part: "root", why: "Its only state change is loading \u2192 loaded or failed, which the arrival covers." },
+    { slot: "activity", recipe: "none", part: "root", why: "A loading image rests on a static muted surface; a shimmer per cover across a long grid would be noise." }
+  ],
+  a11y: [
+    "`alt` defaults to empty (decorative), because the usual neighbour is a visible title that already names the item; describe the image when it stands alone.",
+    'When no image is on screen and `alt` is set, the frame takes `role="img"` with that label, so a broken URL does not erase the description. The fallback art itself is always aria-hidden.',
+    "The `<img>` mounts only once it has loaded, so assistive technology never meets a broken-image icon."
+  ],
+  examples: [
+    { label: "Cover with fallback", code: '<AspectBox ratio={1} className="rounded-md">\n	<MediaImage src={album.cover} seed={album.title} />\n</AspectBox>' },
+    { label: "No image yet", code: '<AspectBox ratio={1} className="rounded-md">\n	<MediaImage seed="Low tide, high noon" />\n</AspectBox>' },
+    { label: "Row thumbnail", code: '<MediaImage src={track.art} seed={track.title} className="size-12 shrink-0 rounded-sm" />' },
+    { label: "Logo, never cropped", code: '<AspectBox ratio={16 / 9} className="rounded-lg">\n	<MediaImage src={brand.logo} alt={brand.name} fit="contain" />\n</AspectBox>' }
+  ]
+};
+export {
+  mediaImageMeta
+};

package/dist/components/media-tile/index.js

@@ -0,0 +1,7 @@
+// src/components/media-tile/index.ts
+import { MediaTile } from "./media-tile.js";
+import { mediaTileMeta } from "./media-tile.meta.js";
+export {
+  MediaTile,
+  mediaTileMeta
+};