feat(site): list required css imports per skin in preset reference (#1521)

site/scripts/api-docs-builder/src/pipeline.ts

@@ -549,6 +549,7 @@ export { generateFeatureReferences } from './feature-handler.js';
 export interface PresetSkinDef {
   name: string;
   tagName?: string;
+  cssImport?: string;
 }
 
 export interface PresetReference {

site/scripts/api-docs-builder/src/preset-handler.ts

@@ -384,7 +384,7 @@ function scanHtmlDirectory(scanDir: string): { skins: PresetSkinDef[]; mediaElem
   return { skins, mediaElement };
 }
 
-function scanReactDirectory(scanDir: string, barrelPath: string): PresetSkinDef[] {
+function scanReactDirectory(scanDir: string, barrelPath: string, presetName: string): PresetSkinDef[] {
   const skins: PresetSkinDef[] = [];
 
   if (!fs.existsSync(scanDir)) return skins;
@@ -397,11 +397,16 @@ function scanReactDirectory(scanDir: string, barrelPath: string): PresetSkinDef[
   for (const file of files) {
     const filePath = path.join(scanDir, file);
     const exports = extractValueExports(filePath);
+    const basename = path.basename(file, path.extname(file));
+    const cssFile = path.join(scanDir, `${basename}.css`);
+    const cssImport = fs.existsSync(cssFile) ? `@videojs/react/${presetName}/${basename}.css` : undefined;
 
     for (const name of exports) {
       if (isFeatureBundle(name)) continue;
       if (isReactSkin(name)) {
-        skins.push({ name });
+        const skin: PresetSkinDef = { name };
+        if (cssImport) skin.cssImport = cssImport;
+        skins.push(skin);
       }
     }
   }
@@ -426,7 +431,7 @@ function buildPresetReference(preset: PresetInfo, featureBundleMap: Map<string,
 
   // Scan React directory for skins, read barrel for media element
   const reactSkins = preset.react
-    ? scanReactDirectory(preset.react.scanDir, preset.react.barrelPath)
+    ? scanReactDirectory(preset.react.scanDir, preset.react.barrelPath, preset.name)
     : ([] as PresetSkinDef[]);
   const reactMediaElement = preset.react ? findReactMediaElement(preset.react.barrelPath) : undefined;
 

site/scripts/api-docs-builder/src/tests/e2e.test.ts

@@ -940,9 +940,14 @@ describe('Preset pipeline (end-to-end)', () => {
       expect(ref.html.mediaElement).toBeUndefined();
     });
 
-    it('detects React skins', () => {
+    it('detects React skins with CSS imports', () => {
       const skins = findPreset('video')!.reference.react.skins;
-      expect(skins).toEqual(expect.arrayContaining([{ name: 'VideoSkin' }, { name: 'MinimalVideoSkin' }]));
+      expect(skins).toEqual(
+        expect.arrayContaining([
+          { name: 'VideoSkin', cssImport: '@videojs/react/video/skin.css' },
+          { name: 'MinimalVideoSkin', cssImport: '@videojs/react/video/minimal-skin.css' },
+        ])
+      );
     });
 
     it('excludes React tailwind skins', () => {
@@ -981,9 +986,9 @@ describe('Preset pipeline (end-to-end)', () => {
       expect(ref.html.mediaElement).toBeUndefined();
     });
 
-    it('detects single React skin', () => {
+    it('detects single React skin with CSS import', () => {
       const skins = findPreset('audio')!.reference.react.skins;
-      expect(skins).toEqual([{ name: 'AudioSkin' }]);
+      expect(skins).toEqual([{ name: 'AudioSkin', cssImport: '@videojs/react/audio/skin.css' }]);
     });
 
     it('detects React media element', () => {
@@ -1022,7 +1027,7 @@ describe('Preset pipeline (end-to-end)', () => {
       expect(skinNames).not.toContain('BackgroundVideoPlayerElement');
     });
 
-    it('detects React skin', () => {
+    it('detects React skin without CSS import when no CSS file exists', () => {
       const skins = findPreset('background')!.reference.react.skins;
       expect(skins).toEqual([{ name: 'BackgroundVideoSkin' }]);
     });

site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/react/src/presets/audio/skin.css

@@ -0,0 +1 @@
+/* fixture */

site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/react/src/presets/video/minimal-skin.css

@@ -0,0 +1 @@
+/* fixture */

site/scripts/api-docs-builder/src/tests/fixtures/monorepo/packages/react/src/presets/video/skin.css

@@ -0,0 +1 @@
+/* fixture */

site/src/components/docs/api-reference/PresetReference.astro

@@ -142,17 +142,16 @@ const listFormat = new Intl.ListFormat('en', { style: 'long', type: 'unit' });
                       <dd>
                         <FrameworkCase frameworks={["react"]}>
                           {preset.react.skins.length > 0
-                            ? listFormat
-                                .formatToParts(
-                                  preset.react.skins.map((s) => s.name),
-                                )
-                                .map((part) =>
-                                  part.type === "element" ? (
-                                    <MarkdownCode class="inline-block whitespace-nowrap">{`<${part.value}>`}</MarkdownCode>
-                                  ) : (
-                                    <span>{part.value}</span>
-                                  ),
-                                )
+                            ? preset.react.skins.map((skin) => (
+                                <div class="mb-2 last:mb-0">
+                                  <MarkdownCode class="inline-block whitespace-nowrap">{`<${skin.name}>`}</MarkdownCode>
+                                  {skin.cssImport && (
+                                    <div class="mt-0.5">
+                                      <MarkdownCode class="text-code inline-block whitespace-nowrap">{`import '${skin.cssImport}';`}</MarkdownCode>
+                                    </div>
+                                  )}
+                                </div>
+                              ))
                             : "–"}
                         </FrameworkCase>
                         <FrameworkCase frameworks={["html"]}>

site/src/content/docs/concepts/skins.mdx

@@ -105,7 +105,7 @@ There are currently two options for styling:
 
 <FrameworkCase frameworks={["react"]}>
 
-- Vanilla CSS where you import the stylesheet in your app. This is the default.
+- Vanilla CSS — import the stylesheet listed for each skin in the [preset table](#skins-features-and-presets). This is the default.
 - Tailwind where you [eject](../how-to/customize-skins#ejecting) the skin and use Tailwind classnames in your app.
 
 </FrameworkCase>

site/src/types/preset-reference.ts

@@ -6,6 +6,7 @@ import { z } from 'astro/zod';
 export const PresetSkinDefSchema = z.object({
   name: z.string(),
   tagName: z.string().optional(),
+  cssImport: z.string().optional(),
 });
 
 export const PresetReferenceSchema = z.object({