@sableui/react 0.6.2 → 0.7.0

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

@@ -0,0 +1,135 @@
+"use client";
+
+// src/components/media-tile/media-tile.tsx
+import { useRender } from "@base-ui/react/use-render";
+import { AspectBox } from "../../layout/AspectBox.js";
+import { cn } from "../../lib/cn.js";
+import { MediaImage } from "../media-image/index.js";
+import {
+  mediaTileInsetVariants,
+  mediaTileSubtitleVariants,
+  mediaTileTitleVariants,
+  mediaTileVariants
+} from "./media-tile.variants.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var ASPECT = { square: 1, video: 16 / 9, poster: 2 / 3 };
+function TileLink({
+  href,
+  render,
+  className,
+  children
+}) {
+  return useRender({
+    render: render ?? /* @__PURE__ */ jsx("a", { href }),
+    props: { className, children },
+    defaultTagName: "a"
+  });
+}
+function MediaTile({
+  title,
+  subtitle,
+  src,
+  alt,
+  seed,
+  aspect = "square",
+  size = "md",
+  href,
+  render,
+  subtitleHref,
+  subtitleRender,
+  action,
+  badge,
+  titleAs: TitleTag = "p",
+  loading,
+  className,
+  ...props
+}) {
+  const linked = href != null || render != null;
+  const subtitleLinked = subtitleHref != null || subtitleRender != null;
+  const ratio = typeof aspect === "number" ? aspect : ASPECT[aspect];
+  const titleText = typeof title === "string" ? title : void 0;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-slot": "media-tile",
+      "data-size": size,
+      className: cn(
+        mediaTileVariants({ size }),
+        mediaTileInsetVariants({ size }),
+        "[--stretched-link-radius:var(--media-tile-radius)]",
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 flex-col gap-0.5", children: [
+          /* @__PURE__ */ jsx(TitleTag, { title: titleText, className: mediaTileTitleVariants({ size }), children: linked ? /* @__PURE__ */ jsx(
+            TileLink,
+            {
+              href,
+              render,
+              className: "stretched-link motion-interactive",
+              children: title
+            }
+          ) : title }),
+          subtitle != null ? subtitleLinked ? /* @__PURE__ */ jsx(
+            TileLink,
+            {
+              href: subtitleHref,
+              render: subtitleRender,
+              className: cn(
+                mediaTileSubtitleVariants({ size }),
+                // Raised over the stretched overlay, so it is its own target.
+                // `self-start` keeps the hit area to the words, not the column.
+                "relative z-10 max-w-full self-start rounded-xs motion-interactive hover:text-foreground hover:underline focus-visible:text-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
+              ),
+              children: subtitle
+            }
+          ) : /* @__PURE__ */ jsx("p", { className: mediaTileSubtitleVariants({ size }), children: subtitle }) : null
+        ] }),
+        /* @__PURE__ */ jsxs(
+          AspectBox,
+          {
+            ratio,
+            "data-slot": "media-tile-cover",
+            className: "order-first rounded-(--media-tile-radius)",
+            children: [
+              /* @__PURE__ */ jsx(MediaImage, { src, alt, seed: seed ?? titleText, loading }),
+              linked || action != null ? (
+                // The tile answers the pointer and the keyboard alike: a light scrim
+                // deepens the cover so the action reads over any artwork. Hover only
+                // where the device can hover — on touch a tap would leave it stuck on.
+                /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    "aria-hidden": true,
+                    className: "pointer-events-none absolute inset-0 bg-overlay/25 opacity-0 motion-interactive group-focus-within:opacity-100 [@media(hover:hover)]:group-hover:opacity-100"
+                  }
+                )
+              ) : null,
+              badge != null ? /* @__PURE__ */ jsx(
+                "div",
+                {
+                  "data-slot": "media-tile-badge",
+                  className: "pointer-events-none absolute start-(--media-tile-inset) top-(--media-tile-inset) z-10 flex",
+                  children: badge
+                }
+              ) : null,
+              action != null ? /* @__PURE__ */ jsx(
+                "div",
+                {
+                  "data-slot": "media-tile-action",
+                  className: "reveal-on-hover absolute end-(--media-tile-inset) bottom-(--media-tile-inset) z-10 flex drop-shadow-md [--reveal-offset:calc(var(--spacing)*1)]",
+                  children: action
+                }
+              ) : null
+            ]
+          }
+        )
+      ]
+    }
+  );
+}
+MediaTile.displayName = "MediaTile";
+export {
+  MediaTile
+};

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

@@ -0,0 +1,133 @@
+// src/components/media-tile/media-tile.meta.ts
+var mediaTileMeta = {
+  name: "MediaTile",
+  summary: "A cover-first tile \u2014 square, 16:9 or poster artwork with an optional play-style action over it, then a title and a subtitle that can each be links \u2014 that is one link as a whole without nesting its other controls inside one.",
+  status: "beta",
+  keywords: [
+    "album",
+    "album art",
+    "cover",
+    "tile",
+    "media card",
+    "video thumbnail",
+    "podcast",
+    "playlist",
+    "gallery",
+    "product tile",
+    "poster",
+    "grid item",
+    "play button",
+    "music"
+  ],
+  usage: {
+    description: "The item in a media grid or shelf: an album, a playlist, a video, a podcast, a film, a photo, a product. The cover leads and carries the weight; the title and subtitle sit underneath without a card around them. The whole tile follows the title's link, the subtitle can link somewhere else (the artist, the channel), and an action \u2014 usually play \u2014 floats over the cover's corner, revealed on hover and focus and always shown on touch. A missing or broken cover becomes GradientArt seeded by the title, so a grid of items without artwork still reads as distinct things.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: 'Lay tiles out with `Grid` (`<Grid minItemWidth="10rem">`) or a horizontal `Scroller` for a shelf. The tile fills its cell; the grid decides the width.'
+      },
+      {
+        guidance: "do",
+        description: 'Pass `render={<Link to="\u2026" />}` (or `href`) for where the tile goes, and `subtitleRender` / `subtitleHref` for a second destination. Each stays a separate control; never wrap the tile in your own link.'
+      },
+      {
+        guidance: "do",
+        description: 'Name the action for its item \u2014 `aria-label="Play Low tide, high noon"`, not "Play". A grid of twenty identical "Play" buttons is unusable from a screen reader\'s list of controls.'
+      },
+      {
+        guidance: "do",
+        description: 'Use `titleAs="h3"` when the tiles sit under a section heading, so screen-reader users can move tile to tile by heading.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not build this from `Card render={<Link />}`. A card that is a link cannot hold a second link or a button \u2014 interactive content cannot nest \u2014 which is exactly what a media tile needs."
+      },
+      {
+        guidance: "dont",
+        description: "Do not put more than one action on the cover. A second control over the art is a toolbar on a thumbnail; move secondary actions (add to queue, share) into an OverflowMenu in the action slot or onto the item's page."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it for a framed commerce card with a price and a buy button \u2014 that is ProductCardBlock \u2014 or for a person, which is an Avatar."
+      }
+    ],
+    anatomy: [
+      { name: "Cover", required: true, description: "An AspectBox holding MediaImage: the image, or GradientArt seeded by the title. Drawn first, read last." },
+      { name: "Title", required: true, description: "The item's name. When the tile links, this is the link, stretched over the whole tile." },
+      { name: "Subtitle", required: false, description: "The second line. Optionally its own link, raised above the stretched one." },
+      { name: "Action", required: false, description: "One control over the cover's bottom-end corner \u2014 usually play. Revealed on hover and focus; always visible on touch." },
+      { name: "Badge", required: false, description: `A static label over the cover's top-start corner \u2014 a duration, "New". Click-through.` }
+    ]
+  },
+  related: { components: ["MediaImage", "GradientArt", "Grid", "AspectBox", "Card", "Scroller"] },
+  props: [
+    { name: "title", type: "ReactNode", description: "The item's name. Seeds the fallback art when it is a string." },
+    { name: "subtitle", type: "ReactNode", description: "The second line \u2014 an artist, a channel, a year." },
+    { name: "src", type: "string", description: "Cover image URL. Without one, or when it fails, the cover is GradientArt seeded by the item." },
+    { name: "alt", type: "string", default: '""', description: "Cover alt text. Empty by default: the title below already names the item." },
+    { name: "seed", type: "string | number", description: "Seeds the fallback art. Defaults to `title` when it is a string." },
+    {
+      name: "aspect",
+      type: '"square" | "video" | "poster" | number',
+      default: '"square"',
+      description: "The cover's shape: square (albums, podcasts), video (16:9), poster (2:3 \u2014 films, books), or any width / height ratio."
+    },
+    { name: "size", type: '"sm" | "md" | "lg"', default: '"md"', description: "Moves the type tier, the cover-to-text gap, the corner and the overlay inset together." },
+    { name: "href", type: "string", description: "Where the tile goes. The title becomes the link, stretched over the whole tile." },
+    { name: "render", type: "useRender.RenderProp", description: 'The title link\'s element, for a router: `render={<Link to="/albums/1" />}`. Takes precedence over `href`.' },
+    { name: "subtitleHref", type: "string", description: "Makes the subtitle its own link \u2014 a separate tab stop above the tile's." },
+    { name: "subtitleRender", type: "useRender.RenderProp", description: "The subtitle link's element, for a router." },
+    { name: "action", type: "ReactNode", description: "One control over the cover's bottom-end corner, usually a play Button. Hidden until hover or focus on hover-capable devices; always shown on touch." },
+    { name: "badge", type: "ReactNode", description: 'A static label on the cover\'s top-start corner \u2014 `<Badge appearance="overlay">`.' },
+    { name: "titleAs", type: '"h2" | "h3" | "h4" | "h5" | "p"', default: '"p"', description: "The title's element. A heading one level below the section's lets screen-reader users move tile to tile." },
+    { name: "loading", type: '"lazy" | "eager"', default: '"lazy"', description: "Native image loading. `eager` for the first row above the fold." },
+    { name: "...div props", type: 'Omit<ComponentPropsWithRef<"div">, "title">', description: "Spread onto the root." }
+  ],
+  variants: { size: ["sm", "md", "lg"], aspect: ["square", "video", "poster"] },
+  tokensUsed: ["foreground", "muted-foreground", "muted", "overlay", "ring"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "motion-fade",
+      part: "Cover",
+      why: "The cover image fades in over a quiet surface once it decodes, so a grid loading on a slow connection settles tile by tile instead of popping."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Cover",
+      why: "Hovering the tile deepens the cover with a light scrim and lifts the action in (`reveal-on-hover`), so it is clear the whole tile is one target and where its action is."
+    },
+    { slot: "transition", recipe: "none", part: "root", why: "A tile has no states of its own to move between; the action carries any (play / pause)." },
+    { slot: "activity", recipe: "none", part: "root", why: "Nothing runs inside a tile; a now-playing indicator belongs to the player, not the grid." }
+  ],
+  a11y: [
+    "No nested interactive content: the title is the tile's link, and its `stretched-link` overlay covers the tile, while the subtitle link and the action sit above it as separate controls.",
+    "Tab order is title \u2192 subtitle \u2192 action. The text comes first in the DOM and the cover is drawn above it with CSS `order`, so focus follows how a reader names the item.",
+    "Focusing the title link rings the whole tile, rounded like the cover, because the whole tile is what the link is; the subtitle link and the action ring themselves.",
+    "The action is hidden with opacity only, and only where the device can hover; it stays in the tab order and the accessibility tree, appears when anything in the tile has focus, and is always visible on touch.",
+    'The cover is decorative by default (`alt=""`), since the title names the item; the fallback art is aria-hidden.',
+    "Truncated titles keep their full text in the link's accessible name and in a `title` tooltip."
+  ],
+  examples: [
+    {
+      label: "Album grid",
+      code: '<Grid minItemWidth="10rem" gap={3}>\n	{albums.map((album) => (\n		<MediaTile\n			key={album.id}\n			title={album.title}\n			subtitle={album.artist}\n			src={album.cover}\n			render={<Link to={`/albums/${album.id}`} />}\n			subtitleRender={<Link to={`/artists/${album.artistId}`} />}\n			action={\n				<Button size="icon" aria-label={`Play ${album.title}`} onClick={() => play(album)}>\n					<Icon name="play" variant="solid" />\n				</Button>\n			}\n		/>\n	))}\n</Grid>'
+    },
+    {
+      label: "Video tile with a duration",
+      code: '<MediaTile\n	aspect="video"\n	title="Building a synth from scratch"\n	subtitle="Undertow Sessions \xB7 2 days ago"\n	src={video.thumbnail}\n	href={`/watch/${video.id}`}\n	badge={<Badge appearance="overlay">12:04</Badge>}\n/>'
+    },
+    {
+      label: "Gallery, no links",
+      code: '<Grid minItemWidth="8rem" gap={2}>\n	{photos.map((photo) => (\n		<MediaTile key={photo.id} size="sm" title={photo.caption} src={photo.url} alt={photo.description} />\n	))}\n</Grid>'
+    },
+    {
+      label: "Poster shelf",
+      code: '<MediaTile aspect="poster" size="lg" titleAs="h3" title="The Long Dark" subtitle="2026 \xB7 Drama" href="/films/the-long-dark" />'
+    }
+  ]
+};
+export {
+  mediaTileMeta
+};

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

@@ -0,0 +1,48 @@
+// src/components/media-tile/media-tile.variants.ts
+import { cva } from "class-variance-authority";
+var mediaTileVariants = cva("group relative isolate flex min-w-0 flex-col", {
+  variants: {
+    size: {
+      sm: "gap-2 [--media-tile-radius:var(--radius-sm)]",
+      md: "gap-3 [--media-tile-radius:var(--radius-md)]",
+      lg: "gap-3 [--media-tile-radius:var(--radius-lg)]"
+    }
+  },
+  defaultVariants: { size: "md" }
+});
+var mediaTileInsetVariants = cva("", {
+  variants: {
+    size: {
+      sm: "[--media-tile-inset:calc(var(--spacing)*1.5)]",
+      md: "[--media-tile-inset:calc(var(--spacing)*2)]",
+      lg: "[--media-tile-inset:calc(var(--spacing)*3)]"
+    }
+  },
+  defaultVariants: { size: "md" }
+});
+var mediaTileTitleVariants = cva("min-w-0 truncate text-foreground", {
+  variants: {
+    size: {
+      sm: "text-label-md",
+      md: "text-label-lg",
+      lg: "text-title-lg"
+    }
+  },
+  defaultVariants: { size: "md" }
+});
+var mediaTileSubtitleVariants = cva("min-w-0 truncate text-muted-foreground", {
+  variants: {
+    size: {
+      sm: "text-caption",
+      md: "text-body-sm",
+      lg: "text-body-md"
+    }
+  },
+  defaultVariants: { size: "md" }
+});
+export {
+  mediaTileInsetVariants,
+  mediaTileSubtitleVariants,
+  mediaTileTitleVariants,
+  mediaTileVariants
+};

package/dist/components/menu/index.js

@@ -0,0 +1,33 @@
+// src/components/menu/index.ts
+import {
+  Menu,
+  MenuTrigger,
+  MenuPortal,
+  MenuContent,
+  MenuItem,
+  MenuSeparator,
+  MenuGroup,
+  MenuGroupLabel,
+  MenuSubmenu,
+  MenuSubmenuTrigger,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuCheckboxItem
+} from "./menu.js";
+import { menuMeta } from "./menu.meta.js";
+export {
+  Menu,
+  MenuCheckboxItem,
+  MenuContent,
+  MenuGroup,
+  MenuGroupLabel,
+  MenuItem,
+  MenuPortal,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuSeparator,
+  MenuSubmenu,
+  MenuSubmenuTrigger,
+  MenuTrigger,
+  menuMeta
+};

package/dist/components/menu/menu.js

@@ -0,0 +1,168 @@
+// src/components/menu/menu.tsx
+import { Menu as Base } from "@base-ui/react/menu";
+import { Icon } from "../../icon/index.js";
+import { anchoredScroll } from "../../lib/anchored-scroll.js";
+import { cn } from "../../lib/cn.js";
+import { withPortalThemeScope } from "../../lib/portal-theme-scope.js";
+import { useAnchoredDensity, useTypeTier } from "../../lib/density.js";
+import { HighlightGlide } from "../../lib/highlight-glide.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var Menu = Base.Root;
+var MenuTrigger = Base.Trigger;
+var MenuPortal = withPortalThemeScope(Base.Portal);
+function MenuContent({
+  className,
+  children,
+  side = "bottom",
+  align = "start",
+  sideOffset = 6,
+  ...props
+}) {
+  const anchoredDensity = useAnchoredDensity();
+  return /* @__PURE__ */ jsx(MenuPortal, { children: /* @__PURE__ */ jsx(Base.Positioner, { side, align, sideOffset, className: "z-(--z-overlay)", children: /* @__PURE__ */ jsxs(
+    Base.Popup,
+    {
+      ...anchoredDensity,
+      className: cn(
+        "min-w-40 rounded-md border border-border-floating bg-popover popup-inset text-popover-foreground shadow-md outline-none",
+        // A menu taller than the room under its trigger scrolls inside
+        // itself instead of running off the screen. Rationale for the cap,
+        // the thin scrollbar and the overscroll containment: lib/anchored-scroll.
+        anchoredScroll,
+        "motion-pop",
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx(HighlightGlide, {}),
+        children
+      ]
+    }
+  ) }) });
+}
+var MENU_ITEM_DESTRUCTIVE = (
+  // The ink is pulled a quarter toward --foreground (as Badge's soft tones
+  // are), from --destructive-text rather than the fill: dark fills sit low
+  // enough for a white label, and ink mixed from them measured 3.8:1 on
+  // Meridian's popover. From the text token every theme clears 4.5:1 (worst
+  // 5.4:1, Prism dark, on the 10% red wash).
+  "text-[color-mix(in_oklch,var(--destructive-text)_75%,var(--foreground))] data-[highlighted]:bg-destructive/10 data-[highlighted]:text-[color-mix(in_oklch,var(--destructive-text)_75%,var(--foreground))]"
+);
+function MenuItem({ className, variant = "default", ...props }) {
+  const tier = useTypeTier();
+  return /* @__PURE__ */ jsx(
+    Base.Item,
+    {
+      className: cn(
+        `flex cursor-default select-none items-center gap-(--item-gap) rounded-popup-item px-(--item-px) py-1.5 ${tier.body} outline-none motion-interactive data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:shrink-0`,
+        variant === "destructive" && MENU_ITEM_DESTRUCTIVE,
+        className
+      ),
+      ...props
+    }
+  );
+}
+function MenuSeparator({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    Base.Separator,
+    {
+      className: cn("popup-bleed my-1 h-px bg-border", className),
+      ...props
+    }
+  );
+}
+function MenuGroup({ className, ...props }) {
+  return /* @__PURE__ */ jsx(Base.Group, { className: cn(className), ...props });
+}
+function MenuGroupLabel({ className, ...props }) {
+  const tier = useTypeTier();
+  return /* @__PURE__ */ jsx(
+    Base.GroupLabel,
+    {
+      className: cn(
+        `select-none px-(--item-px) py-1.5 ${tier.label} text-muted-foreground`,
+        className
+      ),
+      ...props
+    }
+  );
+}
+var MenuSubmenu = Base.SubmenuRoot;
+function MenuSubmenuTrigger({
+  className,
+  children,
+  value,
+  ...props
+}) {
+  const tier = useTypeTier();
+  return /* @__PURE__ */ jsxs(
+    Base.SubmenuTrigger,
+    {
+      className: cn(
+        `flex cursor-default select-none items-center gap-(--item-gap) rounded-popup-item px-(--item-px) py-1.5 ${tier.body} outline-none motion-interactive data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[popup-open]:bg-accent data-[popup-open]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:shrink-0`,
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx("span", { className: "flex-1 truncate text-start", children }),
+        value !== void 0 ? /* @__PURE__ */ jsx("span", { className: "truncate text-muted-foreground", children: value }) : null,
+        /* @__PURE__ */ jsx(Icon, { name: "chevron-right", className: "text-xs opacity-60" })
+      ]
+    }
+  );
+}
+var MenuRadioGroup = Base.RadioGroup;
+function MenuRadioItem({ className, children, ...props }) {
+  const tier = useTypeTier();
+  return /* @__PURE__ */ jsxs(
+    Base.RadioItem,
+    {
+      className: cn(
+        `flex cursor-default select-none items-center gap-(--item-gap) rounded-popup-item px-(--item-px) py-1.5 ${tier.body} outline-none motion-interactive data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50`,
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx("span", { className: "flex size-4 shrink-0 items-center justify-center", children: /* @__PURE__ */ jsx(Base.RadioItemIndicator, { children: /* @__PURE__ */ jsx(Icon, { name: "check", className: "text-xs" }) }) }),
+        /* @__PURE__ */ jsx("span", { className: "flex-1 truncate", children })
+      ]
+    }
+  );
+}
+function MenuCheckboxItem({
+  className,
+  children,
+  ...props
+}) {
+  const tier = useTypeTier();
+  return /* @__PURE__ */ jsxs(
+    Base.CheckboxItem,
+    {
+      className: cn(
+        `flex cursor-default select-none items-center gap-(--item-gap) rounded-popup-item px-(--item-px) py-1.5 ${tier.body} outline-none motion-interactive data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50`,
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx("span", { className: "flex size-4 shrink-0 items-center justify-center", children: /* @__PURE__ */ jsx(Base.CheckboxItemIndicator, { children: /* @__PURE__ */ jsx(Icon, { name: "check", className: "text-xs" }) }) }),
+        /* @__PURE__ */ jsx("span", { className: "flex-1 truncate", children })
+      ]
+    }
+  );
+}
+export {
+  MENU_ITEM_DESTRUCTIVE,
+  Menu,
+  MenuCheckboxItem,
+  MenuContent,
+  MenuGroup,
+  MenuGroupLabel,
+  MenuItem,
+  MenuPortal,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuSeparator,
+  MenuSubmenu,
+  MenuSubmenuTrigger,
+  MenuTrigger
+};