@dogsbay/ui 0.2.0-beta.13 → 0.2.0-beta.131

package/package.json

@@ -1,25 +1,30 @@
 {
   "name": "@dogsbay/ui",
-  "version": "0.2.0-beta.13",
+  "version": "0.2.0-beta.131",
   "description": "Accessible UI components for Astro, inspired by Base UI and shadcn",
   "type": "module",
   "exports": {
     "./*": "./src/*"
   },
   "dependencies": {
-    "tailwind-variants": "^0.3.0"
+    "tailwind-variants": "^0.3.1"
   },
-  "peerDependencies": {
-    "astro": "^5.0.0 || ^6.0.0",
-    "@dogsbay/primitives": "0.2.0-beta.13",
-    "@dogsbay/elements": "0.2.0-beta.13",
-    "@dogsbay/icons": "0.2.0-beta.13"
+  "devDependencies": {
+    "vitest": "^4.1.10",
+    "@shikijs/transformers": "^4.3.1",
+    "katex": "^0.16.47",
+    "maplibre-gl": "^5.24.0",
+    "shiki": "^4.3.1"
   },
-  "optionalDependencies": {
-    "shiki": "^4.0.0",
-    "@shikijs/transformers": "^4.0.0",
-    "maplibre-gl": "^5.0.0",
-    "katex": "^0.16.0"
+  "peerDependencies": {
+    "astro": "^5.0.0 || ^6.0.0 || ^7.0.0",
+    "@shikijs/transformers": "^4.3.1",
+    "katex": "^0.16.47",
+    "maplibre-gl": "^5.24.0",
+    "shiki": "^4.3.1",
+    "@dogsbay/elements": "0.2.0-beta.131",
+    "@dogsbay/icons": "0.2.0-beta.131",
+    "@dogsbay/primitives": "0.2.0-beta.131"
   },
   "files": [
     "src",
@@ -34,5 +39,25 @@
   "homepage": "https://github.com/dogsbay/dogsbay/tree/main/packages/ui",
   "bugs": {
     "url": "https://github.com/dogsbay/dogsbay/issues"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    },
+    "@shikijs/transformers": {
+      "optional": true
+    },
+    "katex": {
+      "optional": true
+    },
+    "maplibre-gl": {
+      "optional": true
+    },
+    "shiki": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "vitest run"
   }
 }

package/src/alert/CollapsibleAlert.astro

@@ -6,18 +6,26 @@
  * Composes with the same variant tokens as Alert.
  *
  * Usage:
- *   <CollapsibleAlert variant="warning" title="Warning" open>
+ *   <CollapsibleAlert variant="warning" title="Warning" icon="lucide:rocket" open>
  *     <p>Body content here.</p>
  *   </CollapsibleAlert>
+ *
+ * A title with markup goes in the `title` slot: `<Fragment slot="title">Run <code>init</code></Fragment>`.
  */
 import { tv, type VariantProps } from "tailwind-variants";
 import { contentVariants, icons, chevronSvg } from "./variants.js";
+import { resolveIcon } from "./icon.js";
 
 const wrapper = tv({
   base: "relative w-full rounded-lg border overflow-hidden [&>summary]:list-none [&>summary::-webkit-details-marker]:hidden",
   variants: {
     variant: {
       default: "border-border",
+      // `plain` = a disclosure that is CHROME, not an alert: no tint, no
+      // icon, no ARIA role. Used for collapsed context (e.g. the
+      // comparison view's unchanged-section folds), where announcing a
+      // "note" or a live-region "status" would be a lie.
+      plain: "border-border",
       destructive: "border-destructive/50",
       note: "border-note/50",
       abstract: "border-abstract/50",
@@ -41,6 +49,7 @@ type Variant = VariantProps<typeof wrapper>["variant"];
 /** Title bar: stronger tint (~10%) */
 const titleBg: Record<string, string> = {
   default: "bg-muted",
+  plain: "bg-transparent",
   destructive: "bg-destructive/10 text-destructive",
   note: "bg-note/10", abstract: "bg-abstract/10", info: "bg-info/10",
   tip: "bg-tip/10", success: "bg-success/10", question: "bg-question/10",
@@ -51,6 +60,7 @@ const titleBg: Record<string, string> = {
 /** Body: subtle tint (~3%) */
 const bodyBg: Record<string, string> = {
   default: "bg-background",
+  plain: "bg-transparent",
   destructive: "bg-destructive/3",
   note: "bg-note/3", abstract: "bg-abstract/3", info: "bg-info/3",
   tip: "bg-tip/3", success: "bg-success/3", question: "bg-question/3",
@@ -73,31 +83,47 @@ interface Props {
   title?: string;
   /** Whether the details starts open */
   open?: boolean;
+  /** An icon name in place of the variant's (`lucide:rocket`, `compass`, an emoji shortcode); unknown names keep the variant's. */
+  icon?: string;
   class?: string;
+  /** id, data-*, aria-*: passed to the <details> (an `id` is a link target) */
+  [key: string]: unknown;
 }
 
-const { variant = "note", title, open = false, class: className } = Astro.props;
+const { variant = "note", title, open = false, class: className, icon: iconName, ...rest } = Astro.props;
 const v = variant || "note";
 
-const role = contentVariants.has(v) ? "note" : "status";
-const icon = contentVariants.has(v) ? icons[v] : null;
+// `plain` is chrome — a disclosure, nothing more. No role at all:
+// role="note"/"status" on collapsed context misinforms assistive tech
+// (and "status" would make it a live region).
+const role = v === "plain" ? undefined : contentVariants.has(v) ? "note" : "status";
+// The author's icon, as Alert draws it; else the variant's (`plain` has none)
+const icon = (iconName ? resolveIcon(iconName) : null) ?? (contentVariants.has(v) ? icons[v] : null);
+const fallbackTitle = title || v.charAt(0).toUpperCase() + v.slice(1);
 ---
 
+{/*
+  The role belongs on the CONTENT, not on <details>. A <details> element
+  has an implicit `group` role, and ARIA does not permit overriding it
+  with `note`/`status` — axe flags it (aria-allowed-role), which is
+  exactly what an accessibility pass found on the comparison site's
+  collapsed sections. Moving it to the body keeps the semantics legal.
+*/}
 <details
   class:list={[wrapper({ variant, class: className }), "group/collapsible"]}
   data-variant={variant}
-  role={role}
   open={open}
+  {...rest}
 >
   <summary class:list={[
     "flex cursor-pointer items-center gap-2 px-4 py-3 text-sm font-semibold select-none",
     titleBg[v],
   ]}>
     {icon && <span class:list={["shrink-0 [&>svg]:size-4", iconColor[v]]} set:html={icon} />}
-    <span class="flex-1 text-foreground" data-part="title">{title || v.charAt(0).toUpperCase() + v.slice(1)}</span>
+    <span class="flex-1 text-foreground" data-part="title"><slot name="title">{fallbackTitle}</slot></span>
     <span class="shrink-0 text-muted-foreground group-open/collapsible:rotate-180 transition-transform duration-200" set:html={chevronSvg} />
   </summary>
-  <div class:list={["px-4 py-3 text-sm [&_p]:leading-relaxed", bodyBg[v]]}>
+  <div class:list={["px-4 py-3 text-sm [&_p]:leading-relaxed", bodyBg[v]]} role={role}>
     <slot />
   </div>
 </details>

package/src/alert/icon.ts

@@ -1,30 +1,23 @@
 /**
- * Resolve an icon shortcode for the Alert component.
+ * Resolve an icon name for Alert and CollapsibleAlert.
  *
- * Accepts two formats:
- *   - `library:name` — e.g. "lucide:rocket", "material:check-circle", "simple:github"
- *   - bare shortcode — treated as emoji (e.g. "rocket" → 🚀)
+ * The same names as Icon.astro and dogsbay-ssg (`@dogsbay/icons` resolveIcon):
+ *   - `pack:name` — e.g. "lucide:rocket", "material:check-circle", "simple:github"
+ *   - a bare name — an emoji shortcode first ("rocket" → 🚀), then a Lucide icon ("compass")
  *
  * Returns an inline SVG string or a span with the emoji character. Returns
- * null when the shortcode can't be resolved (caller should fall back to the
+ * null when the name can't be resolved (caller should fall back to the
  * variant's default icon).
  */
-import { createIconRegistry } from "@dogsbay/icons";
-
-const registry = createIconRegistry();
+import { resolveIcon as resolveName } from "@dogsbay/icons";
 
 export function resolveIcon(shortcode: string): string | null {
-  const colonIdx = shortcode.indexOf(":");
-  const [library, name] = colonIdx >= 0
-    ? [shortcode.slice(0, colonIdx), shortcode.slice(colonIdx + 1)]
-    : ["emoji", shortcode];
-
-  const resolved = registry.resolve(library, name);
+  const resolved = resolveName(shortcode);
   if (!resolved) return null;
 
   // Emoji resolve to Unicode characters; wrap for consistent sizing/positioning
   // with the SVG icons in the Alert layout.
-  if (library === "emoji") {
+  if (!resolved.startsWith("<")) {
     return `<span aria-hidden="true" style="font-size:1em;line-height:1;display:inline-block;width:1em;text-align:center;">${resolved}</span>`;
   }
 

package/src/api-layout/ApiLayout.astro

@@ -12,17 +12,41 @@
  */
 interface Props {
   class?: string;
+  /**
+   * "page" (default): a dedicated API operation page — full-viewport
+   * min-height, sticky code rail.
+   * "embedded": the layout sits inline among prose (imported MDX docs
+   * with several endpoints per page) — natural height, no sticky.
+   */
+  variant?: "page" | "embedded";
 }
 
-const { class: className } = Astro.props;
+const { class: className, variant = "page" } = Astro.props;
+const isPage = variant === "page";
 ---
 
-<div class:list={["grid grid-cols-1 lg:grid-cols-2 lg:min-h-[calc(100vh-3rem)]", className]}>
-  <div class="px-6 py-10 lg:border-r">
+{/* dba-api marks an API-reference region: the generated .docs-prose
+    typography rules skip everything inside it via :not(.dba-api *), so
+    endpoint cards keep their own utility-class typography even when the
+    page body is wrapped in the prose article. */}
+<div
+  class:list={[
+    "dba-api grid grid-cols-1 lg:grid-cols-2",
+    isPage ? "lg:min-h-[calc(100vh-3rem)]" : "my-6 rounded-lg border overflow-hidden",
+    className,
+  ]}
+>
+  <div class:list={[isPage ? "px-6 py-10" : "p-6", "lg:border-r"]}>
     <slot name="description" />
   </div>
   <div class="bg-[var(--api-panel-bg)] text-[var(--api-panel-fg)]">
-    <div class="px-6 py-10 lg:sticky lg:top-12 lg:max-h-[calc(100vh-3rem)] lg:overflow-y-auto">
+    <div
+      class:list={[
+        isPage
+          ? "px-6 py-10 lg:sticky lg:top-12 lg:max-h-[calc(100vh-3rem)] lg:overflow-y-auto"
+          : "p-6",
+      ]}
+    >
       <slot name="code" />
     </div>
   </div>

package/src/api-layout/ExampleBlock.astro

@@ -55,9 +55,10 @@ const content = code || (json !== undefined && json !== null ? JSON.stringify(js
 
 {content && (
   <div class={className}>
-    <h3 class="mb-3 text-xs font-semibold uppercase tracking-wider text-white/60">
+    {/* A label, not a heading: on an operation page it followed the h1 (axe heading-order). */}
+    <p class="mb-3 text-xs font-semibold uppercase tracking-wider text-white/60">
       {title}
-    </h3>
+    </p>
     <CodeBlock code={content} lang={resolvedLang} copy={true} />
   </div>
 )}

package/src/api-symbol/api-symbol.css

@@ -1,4 +1,7 @@
-/* API Symbol badges — colored by kind */
+/* API Symbol badges, coloured by kind. Text on its own 20% tint must reach
+   WCAG AA (4.5:1) on the page background: the light colours were L 0.5–0.6
+   (3.2–4.0:1) and are L 0.44 (5.0:1 or more); render-html's
+   tests/contrast.test.ts measures every kind in both modes. */
 .api-badge {
   display: inline-flex;
   align-items: center;
@@ -13,8 +16,8 @@
 }
 
 .api-badge-class {
-  background-color: oklch(0.55 0.18 265 / 0.2);
-  color: oklch(0.55 0.18 265);
+  background-color: oklch(0.44 0.18 265 / 0.2);
+  color: oklch(0.44 0.18 265);
 }
 .dark .api-badge-class {
   background-color: oklch(0.7 0.15 265 / 0.2);
@@ -22,8 +25,8 @@
 }
 
 .api-badge-meth {
-  background-color: oklch(0.55 0.15 155 / 0.2);
-  color: oklch(0.55 0.15 155);
+  background-color: oklch(0.44 0.15 155 / 0.2);
+  color: oklch(0.44 0.15 155);
 }
 .dark .api-badge-meth {
   background-color: oklch(0.7 0.15 155 / 0.2);
@@ -31,8 +34,8 @@
 }
 
 .api-badge-attr {
-  background-color: oklch(0.6 0.15 55 / 0.2);
-  color: oklch(0.6 0.15 55);
+  background-color: oklch(0.44 0.15 55 / 0.2);
+  color: oklch(0.44 0.15 55);
 }
 .dark .api-badge-attr {
   background-color: oklch(0.75 0.15 55 / 0.2);
@@ -40,8 +43,8 @@
 }
 
 .api-badge-func {
-  background-color: oklch(0.55 0.18 330 / 0.2);
-  color: oklch(0.55 0.18 330);
+  background-color: oklch(0.44 0.18 330 / 0.2);
+  color: oklch(0.44 0.18 330);
 }
 .dark .api-badge-func {
   background-color: oklch(0.7 0.15 330 / 0.2);
@@ -49,8 +52,8 @@
 }
 
 .api-badge-module {
-  background-color: oklch(0.5 0.12 200 / 0.2);
-  color: oklch(0.5 0.12 200);
+  background-color: oklch(0.44 0.12 200 / 0.2);
+  color: oklch(0.44 0.12 200);
 }
 .dark .api-badge-module {
   background-color: oklch(0.65 0.12 200 / 0.2);

package/src/avatar/Avatar.astro

@@ -30,16 +30,20 @@ const initials =
     .join("")
     .slice(0, 2)
     .toUpperCase();
+// The name is on the avatar itself, so it is read whether the image loads, fails or was never given:
+// the initials stand in visually only, and a failed image is hidden with its alt.
+// An author's own aria-label wins (an empty one does not); the role is ours, as in render-html.
+const label = alt ? { role: "img", "aria-label": (rest["aria-label"] as string | undefined) || alt } : {};
 ---
 
-<span class={avatar({ class: className })} {...rest}>
+<span class={avatar({ class: className })} {...rest} {...label}>
   {
     src ? (
       <>
         <img
           class={avatarImage()}
           src={src}
-          alt={alt}
+          alt=""
           width="40"
           height="40"
           onerror="this.hidden=true;this.nextElementSibling.hidden=false"

package/src/badge/Badge.astro

@@ -1,17 +1,10 @@
 ---
 import { tv, type VariantProps } from "tailwind-variants";
+import { BADGE_BASE, BADGE_VARIANTS } from "./variants.js";
 
 const badge = tv({
-  base: "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors",
-  variants: {
-    variant: {
-      default: "border-transparent bg-primary text-primary-foreground",
-      secondary: "border-transparent bg-secondary text-secondary-foreground",
-      destructive:
-        "border-transparent bg-destructive text-destructive-foreground",
-      outline: "text-foreground",
-    },
-  },
+  base: BADGE_BASE,
+  variants: { variant: BADGE_VARIANTS },
   defaultVariants: {
     variant: "default",
   },

package/src/badge/variants.ts

@@ -0,0 +1,39 @@
+/**
+ * Badge classes, shared by Badge.astro, ContentRenderer and @dogsbay/render-html
+ * (which copies this file with scripts/sync-sources.mjs), so a badge
+ * looks the same however a page is produced.
+ */
+export const BADGE_BASE =
+  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors";
+
+export const BADGE_VARIANTS = {
+  default: "border-transparent bg-primary text-primary-foreground",
+  secondary: "border-transparent bg-secondary text-secondary-foreground",
+  destructive: "border-transparent bg-destructive text-destructive-foreground",
+  outline: "text-foreground",
+  // Status colours, from the callout palette (`:badge[Beta]{variant="warning"}`).
+  // The TEXT is the accent mixed 60% toward --foreground; the tint keeps the
+  // accent at full strength. The accent used raw measured 1.85-2.6:1 in light
+  // mode (danger 3.3-3.9:1 in dark too), from painted pixels. --foreground is
+  // near-black in light and near-white in dark, so one rule serves both themes
+  // (worst case 4.95:1); a fixed dark colour would fail dark mode. The same
+  // rule as the in-cell admonitions in format-astro's theme-css.ts.
+  // The `color:` hint is required: tailwind-merge 2.x (Badge.astro's tv())
+  // reads a bare text-[... 60% ...] as a FONT SIZE and drops text-xs.
+  // Checked per preset by @dogsbay/render-html tests/contrast.test.ts, and
+  // through tv() by ui tests/badge.test.ts.
+  info: "border-transparent bg-info/15 text-[color:color-mix(in_oklab,var(--info)_60%,var(--foreground))]",
+  success: "border-transparent bg-success/15 text-[color:color-mix(in_oklab,var(--success)_60%,var(--foreground))]",
+  warning: "border-transparent bg-warning/15 text-[color:color-mix(in_oklab,var(--warning)_60%,var(--foreground))]",
+  danger: "border-transparent bg-danger/15 text-[color:color-mix(in_oklab,var(--danger)_60%,var(--foreground))]",
+} as const;
+
+export type BadgeVariant = keyof typeof BADGE_VARIANTS;
+
+/** The class list for a variant; an unknown variant gets the base classes only. */
+export function badgeClass(variant: string | undefined): string {
+  // Own keys only: `toString` or `__proto__` must not read Object.prototype
+  const key = variant ?? "default";
+  const v = Object.prototype.hasOwnProperty.call(BADGE_VARIANTS, key) ? BADGE_VARIANTS[key as BadgeVariant] : undefined;
+  return v ? `${BADGE_BASE} ${v}` : BADGE_BASE;
+}

package/src/code-block/CodeBlock.astro

@@ -21,6 +21,10 @@ interface Props {
   lang?: string;
   /** Optional title displayed in the header bar */
   title?: string;
+  /*
+   * A `caption` slot makes the block a figure: the header bar is its
+   * <figcaption>, showing the caption with the language beside it.
+   */
   /** Show copy button (default: true) */
   copy?: boolean;
   /** Show the header title bar. true = always, false = never, "auto" = only when title prop is set (default: true) */
@@ -42,26 +46,51 @@ const {
   ...rest
 } = Astro.props;
 
+// AsciiDoc/docs language tokens that are not Shiki grammars → the nearest real
+// one, so the block actually highlights (and data-language is meaningful)
+// instead of silently falling back to plaintext. The header still shows the
+// original label (`lang` below), only the highlighter input is aliased. #009.
+const LANG_ALIASES: Record<string, string> = {
+  terminal: "bash",
+};
+const shikiLang = LANG_ALIASES[lang.toLowerCase()] ?? lang.toLowerCase();
+
 // Show header bar based on showTitle prop:
 // - true: show when there's a title or a declared language (default, original behavior)
 // - false: never show
 // - "auto": only show when an explicit title is provided (not lang-only)
+const hasCaption = Astro.slots.has("caption");
+const Wrapper = hasCaption ? "figure" : "div";
+const Header = hasCaption ? "figcaption" : "div";
 const showHeader =
-  showTitle === false ? false
+  hasCaption ? true
+  : showTitle === false ? false
   : showTitle === "auto" ? !!title
   : !!title || lang !== "plaintext";
 // When no header, copy button floats inside the code body
 const floatingCopy = copy && !showHeader;
 ---
 
-<div
-  class={codeBlockWrapper({ class: className })}
+<Wrapper
+  class={codeBlockWrapper({ class: [hasCaption && "m-0", className] })}
   data-component="code-block"
   {...rest}
 >
   {showHeader && (
-    <div class={codeBlockHeader()}>
-      <span class="select-none">{title || lang}</span>
+    <Header class={codeBlockHeader()}>
+      {/*
+        Left: what the code is (caption or filename title), or the language when that is
+        all there is. Right: the language beside the copy button, as secondary detail
+      */}
+      {hasCaption ? (
+        <span class="min-w-0 font-medium text-code-fg" data-part="caption"><slot name="caption" /></span>
+      ) : title ? (
+        <span class="min-w-0 font-medium text-code-fg" data-part="title">{title}</span>
+      ) : (
+        <span class="select-none">{lang}</span>
+      )}
+      <span class="flex shrink-0 items-center gap-2">
+      {(hasCaption || title) && lang !== "plaintext" && <span class="select-none" data-part="language">{lang}</span>}
       {copy && (
         <button
           class={codeBlockCopy()}
@@ -104,10 +133,11 @@ const floatingCopy = copy && !showHeader;
           </svg>
         </button>
       )}
-    </div>
+      </span>
+    </Header>
   )}
   <div class="relative overflow-x-auto [&_pre]:!m-0 [&_pre]:!rounded-none [&_pre]:!border-0 [&_pre]:px-4 [&_pre]:py-3">
-    <Code code={code} lang={lang.toLowerCase()} themes={{ light: "github-light-default", dark: theme }} defaultColor={false} />
+    <Code code={code} lang={shikiLang} themes={{ light: "github-light-default", dark: theme }} defaultColor={false} />
     {floatingCopy && (
       <button
         class:list={[codeBlockCopy(), "absolute right-2 top-2 opacity-0 group-hover:opacity-100 transition-opacity"]}
@@ -126,7 +156,7 @@ const floatingCopy = copy && !showHeader;
       </button>
     )}
   </div>
-</div>
+</Wrapper>
 
 <script>
   function setupCodeBlockCopy() {