docs(site): label beta API references

.agents/skills/write-api-reference/references/mdx-structure.md

@@ -12,12 +12,15 @@ title: MuteButton              # PascalCase component name
 frameworkTitle:
   html: media-mute-button      # HTML custom element tag name
 description: A button component for muting and unmuting audio playback
+stability: beta                  # Optional; marks an individual API as beta
 ---
 ```
 
 - `title`: PascalCase React component name
 - `frameworkTitle.html`: The `static tagName` from the HTML element file
 - `description`: One-line description of the component
+- `stability`: Optional API maturity. Use `beta` when the API is available for testing but may still change; the site
+  adds the status to the page header and sidebar.
 
 ### Page Structure
 

site/src/components/BetaPill.tsx

@@ -1,3 +1,4 @@
+import Pill from '@/components/Pill';
 import { twMerge } from '@/utils/twMerge';
 
 interface BetaPillProps {
@@ -10,15 +11,10 @@ interface BetaPillProps {
 
 export default function BetaPill({ className, style, compact, label }: BetaPillProps) {
   return (
-    <span
-      className={twMerge(
-        'inline-flex items-center justify-center rounded-full border border-orange text-(length:--text) font-bold text-orange',
-        compact
-          ? 'h-5 px-2 font-display-compact sm:h-6 sm:px-3 sm:font-display'
-          : 'h-7 px-3 font-display lg:h-10 lg:border-2 lg:px-4 lg:text-h4',
-        className
-      )}
-      style={{ '--text': '0.75rem', ...style } as React.CSSProperties}
+    <Pill
+      className={twMerge(compact ? 'font-display-compact sm:font-display' : 'font-display', className)}
+      size={compact ? 'compact' : 'default'}
+      style={style}
     >
       {label ? (
         <span className="whitespace-nowrap">{label}</span>
@@ -32,6 +28,6 @@ export default function BetaPill({ className, style, compact, label }: BetaPillP
           v10<span className="whitespace-pre uppercase"> beta</span>
         </>
       )}
-    </span>
+    </Pill>
   );
 }

site/src/components/Pill.tsx

@@ -0,0 +1,29 @@
+import { twMerge } from '@/utils/twMerge';
+
+type PillStyle = React.CSSProperties & {
+  '--text'?: string;
+};
+
+interface PillProps {
+  children: React.ReactNode;
+  className?: string;
+  style?: PillStyle;
+  size?: 'default' | 'compact';
+}
+
+export default function Pill({ children, className, style, size = 'default' }: PillProps) {
+  const pillStyle: PillStyle = { '--text': '0.75rem', ...style };
+
+  return (
+    <span
+      className={twMerge(
+        'inline-flex items-center justify-center rounded-full border border-orange text-(length:--text) font-bold whitespace-nowrap text-orange',
+        size === 'compact' ? 'h-5 px-2 sm:h-6 sm:px-3' : 'h-7 px-3 lg:h-10 lg:border-2 lg:px-4 lg:text-h4',
+        className
+      )}
+      style={pillStyle}
+    >
+      {children}
+    </span>
+  );
+}

site/src/components/docs/ApiStabilityBadge.astro

@@ -0,0 +1,20 @@
+---
+import Pill from '@/components/Pill';
+import type { DocStability } from '@/types/docs';
+
+type Props = {
+  stability: DocStability;
+};
+
+const { stability } = Astro.props;
+const labels = {
+  beta: 'Beta',
+} satisfies Record<DocStability, string>;
+---
+
+<Pill
+  size="compact"
+  className="h-5 shrink-0 px-2 font-display-compact uppercase sm:h-5 sm:px-2"
+>
+  {labels[stability]}
+</Pill>

site/src/components/docs/DocsSidebar.astro

@@ -3,16 +3,17 @@ import clsx from 'clsx';
 
 import { PreferenceUpdater } from '@/components/docs/PreferenceUpdater';
 import SidebarItem from '@/components/docs/SidebarItem.astro';
-import type { SupportedFramework } from '@/types/docs';
+import type { DocStability, SupportedFramework } from '@/types/docs';
 import { filterSidebar } from '@/utils/docs/sidebar';
 
 type Props = {
   framework: SupportedFramework;
   docTitles: Map<string, string>;
+  docStabilities: Map<string, DocStability | undefined>;
   class?: string;
 };
 
-const { framework, docTitles, class: className } = Astro.props;
+const { framework, docTitles, docStabilities, class: className } = Astro.props;
 const filteredSidebar = filterSidebar(framework);
 ---
 
@@ -22,7 +23,7 @@ const filteredSidebar = filterSidebar(framework);
   <nav aria-label="Docs sidebar" class="p-6">
     {
       filteredSidebar.map((item) => (
-        <SidebarItem item={item} framework={framework} docTitles={docTitles} />
+        <SidebarItem item={item} framework={framework} docTitles={docTitles} docStabilities={docStabilities} />
       ))
     }
   </nav>

site/src/components/docs/SidebarItem.astro

@@ -2,19 +2,22 @@
 import GithubSlugger from 'github-slugger';
 import { ArrowUpRight } from 'lucide-react';
 import DropdownIcon from '@/assets/icons/dropdown-arrow.svg?react';
-import type { SidebarItem as SidebarItemType, SupportedFramework } from '@/types/docs';
+import ApiStabilityBadge from '@/components/docs/ApiStabilityBadge.astro';
+import type { DocStability, SidebarItem as SidebarItemType, SupportedFramework } from '@/types/docs';
 import { isLink, isSection } from '@/types/docs';
 
 type Props = {
   item: SidebarItemType;
   framework: SupportedFramework;
   docTitles: Map<string, string>;
+  docStabilities: Map<string, DocStability | undefined>;
   depth?: number;
 };
 
-const { item, framework, docTitles, depth = 0 } = Astro.props;
+const { item, framework, docTitles, docStabilities, depth = 0 } = Astro.props;
 const currentPath = Astro.url.pathname;
 const slugger = new GithubSlugger();
+const stability = !isSection(item) && !isLink(item) ? docStabilities.get(item.slug) : undefined;
 
 // Helper to check if this item or any of its children contains the active path
 function containsActivePath(item: SidebarItemType): boolean {
@@ -93,6 +96,7 @@ function getGroupRotate(depth: number) {
             item={contentItem}
             framework={framework}
             docTitles={docTitles}
+            docStabilities={docStabilities}
             depth={depth + 1}
           />
         ))}
@@ -128,7 +132,10 @@ function getGroupRotate(depth: number) {
       href={`/docs/framework/${framework}/${item.slug}`}
     >
       {item.devOnly ? "[Dev only] " : ""}
-      {item.sidebarLabel || docTitles.get(item.slug) || item.slug}
+      <span class="min-w-0 flex-1">
+        {item.sidebarLabel || docTitles.get(item.slug) || item.slug}
+      </span>
+      {stability && <ApiStabilityBadge stability={stability} />}
     </a>
   )
 }

site/src/content.config.ts

@@ -3,7 +3,7 @@ import { z } from 'astro/zod';
 import { defineCollection, reference } from 'astro:content';
 
 import { ComponentReferenceSchema } from './types/component-reference';
-import { SUPPORTED_FRAMEWORKS } from './types/docs';
+import { DOC_STABILITIES, SUPPORTED_FRAMEWORKS } from './types/docs';
 import { FeatureReferenceSchema } from './types/feature-reference';
 import { MediaReferenceSchema } from './types/media-reference';
 import { PresetReferenceSchema } from './types/preset-reference';
@@ -92,6 +92,7 @@ const docs = defineCollection({
     description: z.string(),
     updatedDate: z.coerce.date().optional(),
     ogTitle: z.string().optional(),
+    stability: z.enum(DOC_STABILITIES).optional(),
     frameworkTitle: z.partialRecord(z.enum(SUPPORTED_FRAMEWORKS as [string, ...string[]]), z.string()).optional(),
   }),
 });

site/src/content/docs/reference/dash-video.mdx

@@ -3,6 +3,7 @@ title: DashVideo
 frameworkTitle:
   html: dash-video
 description: DASH video element powered by dash.js for adaptive bitrate streaming
+stability: beta
 ---
 
 import MediaReference from "@/components/docs/api-reference/MediaReference.astro";

site/src/content/docs/reference/shaka-video.mdx

@@ -3,6 +3,7 @@ title: ShakaVideo
 frameworkTitle:
   html: shaka-video
 description: Video element powered by Shaka Player for DASH, HLS, and progressive playback with DRM
+stability: beta
 ---
 
 import MediaReference from "@/components/docs/api-reference/MediaReference.astro";

site/src/content/docs/reference/write-references.mdx

@@ -147,10 +147,12 @@ title: PlayButton
 frameworkTitle:
   html: media-play-button
 description: A button component for playing and pausing media playback
+stability: beta
 ---
 ```
 
 Use `frameworkTitle` to show the HTML custom element tag name when the HTML framework is selected.
+Add `stability: beta` when the individual API is available for testing but may still change. The page header and sidebar display the status automatically.
 
 ### Imports
 

site/src/layouts/Docs.astro

@@ -23,6 +23,7 @@ const { doc, framework, slug } = Astro.props;
 // Fetch all docs to get their framework-specific titles
 const allDocs = await getCollection('docs');
 const docTitles = new Map(allDocs.map((d) => [d.id, getDocTitle(d, framework)]));
+const docStabilities = new Map(allDocs.map((d) => [d.id, d.data.stability]));
 
 const seoCategory = `${FRAMEWORK_LABELS[framework]} Video Player`;
 const docsSidebarId = 'docs-sidebar';
@@ -57,14 +58,15 @@ const docsSidebarId = 'docs-sidebar';
         slot="mobile-nav"
         framework={framework}
         docTitles={docTitles}
+        docStabilities={docStabilities}
       />
     </NavBarDocs>
     <aside
       id={docsSidebarId}
       class="sticky z-10 hidden flex-col overflow-y-auto border-manila-75 md:flex md:border-r dark:border-warm-gray"
       style="top: var(--nav-h); max-height: calc(100vh - var(--nav-h));"
     >
-      <DocsSidebar framework={framework} docTitles={docTitles} class="flex-1">
+      <DocsSidebar framework={framework} docTitles={docTitles} docStabilities={docStabilities} class="flex-1">
         <Selectors
           client:idle
           currentFramework={framework}

site/src/pages/docs/framework/[framework]/[...slug].astro

@@ -3,6 +3,7 @@ import type { CollectionEntry } from 'astro:content';
 import { getCollection, render } from 'astro:content';
 import clsx from 'clsx';
 import CopyMarkdownButton from '@/components/CopyMarkdownButton';
+import ApiStabilityBadge from '@/components/docs/ApiStabilityBadge.astro';
 import DocsNavigation from '@/components/docs/DocsNavigation.astro';
 import EditPageButton from '@/components/docs/EditPageButton.astro';
 import { Selectors } from '@/components/docs/Selectors';
@@ -141,15 +142,19 @@ const jsonLdSchema = createTechArticleSchema({
           ]}
         >
           <div>
-            <H2Markdown
-              as="h1"
-              class={clsx(
-                "mt-0 mb-4 text-h25 @lg:text-h2",
-                isCodeIdentifier(getDocTitle(doc, framework)) && "normal-case",
-              )}
-            >
-              {getDocTitle(doc, framework)}
-            </H2Markdown>
+            <div class="mb-4 flex flex-wrap items-center gap-3">
+              <H2Markdown
+                as="h1"
+                maxWidth={false}
+                class={clsx(
+                  "mt-0 mb-0 text-h25 @lg:text-h2",
+                  isCodeIdentifier(getDocTitle(doc, framework)) && "normal-case",
+                )}
+              >
+                {getDocTitle(doc, framework)}
+              </H2Markdown>
+              {doc.data.stability && <ApiStabilityBadge stability={doc.data.stability} />}
+            </div>
             <p class="text-p2">{doc.data.description}</p>
           </div>
           <CopyMarkdownButton client:idle />

site/src/types/docs.ts

@@ -3,6 +3,10 @@ export const FRAMEWORK_STYLES = {
   html: ['css'],
 } as const;
 
+export const DOC_STABILITIES = ['beta'] as const;
+
+export type DocStability = (typeof DOC_STABILITIES)[number];
+
 export type SupportedFramework = keyof typeof FRAMEWORK_STYLES;
 export type SupportedStyle<F extends SupportedFramework> = (typeof FRAMEWORK_STYLES)[F][number];
 export type AnySupportedStyle = SupportedStyle<SupportedFramework>;