docs: UI improvements (#9098)

* Adjust heading to fit viewport

* Allow horizontal scrolling in code examples instead of wrapping

* Automatically set library so sandbox links work everywhere

* Add additional aria groupings/labels

* lint

Author: devongovett

packages/@react-spectrum/s2/style/spectrum-theme.ts

@@ -760,10 +760,14 @@ export const style = createTheme({
       code: 'source-code-pro, "Source Code Pro", Monaco, monospace'
     },
     fontSize: new ExpandedProperty<keyof typeof fontSize>(['fontSize', 'lineHeight'], (value) => {
-      return {
-        '--fs': `pow(1.125, ${value})`,
-        fontSize: `round(${fontSizeCalc} / 16 * 1rem, 1px)`
-      };
+      if (typeof value === 'number') {
+        return {
+          '--fs': `pow(1.125, ${value})`,
+          fontSize: `round(${fontSizeCalc} / 16 * 1rem, 1px)`
+        } as CSSProperties;
+      }
+
+      return {fontSize: value};
     }, fontSize),
     fontWeight: new ExpandedProperty<keyof typeof fontWeight>(['fontWeight', 'fontVariationSettings', 'fontSynthesisWeight'], (value) => {
       return {

packages/dev/s2-docs/pages/s2/SelectBoxGroup.mdx

@@ -5,8 +5,9 @@ export default Layout;
 import docs from 'docs:@react-spectrum/s2';
 
 export const tags = ['box'];
+export const version = 'alpha';
 
-# SelectBoxGroup <VersionBadge version="alpha" />
+# SelectBoxGroup
 
 <PageDescription>{docs.exports.SelectBoxGroup.description}</PageDescription>
 

packages/dev/s2-docs/pages/s2/Toast.mdx

@@ -7,8 +7,9 @@ import {InterfaceType} from '../../src/types';
 import {VersionBadge} from '../../src/VersionBadge';
 
 export const tags = ['snackbar', 'notification', 'alert'];
+export const version = 'alpha';
 
-# Toast <VersionBadge version="alpha" />
+# Toast
 
 <PageDescription>{docs.exports.UNSTABLE_ToastContainer.description}</PageDescription>
 

packages/dev/s2-docs/src/Code.tsx

@@ -28,8 +28,10 @@ const mark = style({
   borderWidth: 0,
   borderStartWidth: 2,
   borderStyle: 'solid',
-  marginX: 'calc(var(--code-padding-x) * -1)',
-  paddingX: 'calc(var(--code-padding-x) - self(borderStartWidth))',
+  marginStart: 'calc(var(--code-padding-start) * -1)',
+  marginEnd: 'calc(var(--code-padding-end) * -1)',
+  paddingStart: 'calc(var(--code-padding-start) - self(borderStartWidth))',
+  paddingEnd: '--code-padding-end',
   color: 'inherit'
 });
 

packages/dev/s2-docs/src/CodeBlock.tsx

@@ -24,11 +24,15 @@ const example = style({
 });
 
 const standaloneCode = style({
-  '--code-padding-x': {
-    type: 'paddingTop',
+  '--code-padding-start': {
+    type: 'paddingStart',
     value: 32
   },
-  padding: '--code-padding-x',
+  '--code-padding-end': {
+    type: 'paddingEnd',
+    value: 32
+  },
+  padding: '--code-padding-start',
   marginY: 32,
   backgroundColor: 'layer-1',
   borderRadius: 'xl',
@@ -89,7 +93,7 @@ export function CodeBlock({render, children, files, expanded, hidden, hideExampl
   );
 
   return (
-    <div className={example}>
+    <div role="group" aria-label="Example" className={example}>
       <ExampleOutput
         component={render}
         align={props.align} />
@@ -128,9 +132,11 @@ function TruncatedCode({children, maxLines = 6, ...props}: TruncatedCodeProps) {
     </ExpandableCode>
   )
   : (
-    <Pre>
-      <Code {...props}>{children}</Code>
-    </Pre>
+    <div className={style({overflow: 'auto'})}>
+      <Pre>
+        <Code {...props}>{children}</Code>
+      </Pre>
+    </div>
   );
 }
 

packages/dev/s2-docs/src/CodePlatter.tsx

@@ -7,27 +7,30 @@ import {createStackBlitz} from './StackBlitz';
 import Download from '@react-spectrum/s2/icons/Download';
 import {iconStyle, style} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {Key} from 'react-aria';
+import {Library} from './library';
 import LinkIcon from '@react-spectrum/s2/icons/Link';
 import OpenIn from '@react-spectrum/s2/icons/OpenIn';
 import Polygon4 from '@react-spectrum/s2/icons/Polygon4';
 import Prompt from '@react-spectrum/s2/icons/Prompt';
-import React, {ReactNode, useEffect, useRef, useState} from 'react';
+import React, {createContext, ReactNode, useContext, useEffect, useRef, useState} from 'react';
 import {zip} from './zip';
 
 const platterStyle = style({
   backgroundColor: 'layer-2',
   borderRadius: 'lg',
-  '--code-padding-x': {
-    type: 'paddingTop',
+  '--code-padding-start': {
+    type: 'paddingStart',
+    value: 16
+  },
+  '--code-padding-end': {
+    type: 'paddingEnd',
     value: 16
   },
   '--code-padding-y': {
     type: 'paddingTop',
     value: 16
   },
-  position: 'relative',
-  maxHeight: 600,
-  overflow: 'auto'
+  position: 'relative'
 });
 
 interface CodePlatterProps {
@@ -38,21 +41,38 @@ interface CodePlatterProps {
   registryUrl?: string
 }
 
+interface CodePlatterContextValue {
+  library: Library
+}
+
+const CodePlatterContext = createContext<CodePlatterContextValue>({library: 'react-spectrum'});
+export function CodePlatterProvider(props: CodePlatterContextValue & {children: any}) {
+  return <CodePlatterContext.Provider value={props}>{props.children}</CodePlatterContext.Provider>;
+}
+
 export function CodePlatter({children, shareUrl, files, type, registryUrl}: CodePlatterProps) {
   let codeRef = useRef<HTMLDivElement | null>(null);
   let [showShadcn, setShowShadcn] = useState(false);
   let getText = () => codeRef.current!.querySelector('pre')!.textContent!;
+  let {library} = useContext(CodePlatterContext);
+  if (!type) {
+    if (library === 'react-aria') {
+      type = 'vanilla';
+    } else if (library === 'react-spectrum') {
+      type = 's2';
+    }
+  }
 
   return (
     <div className={platterStyle}>
-      <div className={style({display: 'flex', justifyContent: 'end', float: 'inline-end', padding: 16, position: 'relative', zIndex: 1})}>
+      <div className={style({display: 'flex', justifyContent: 'end', padding: 4, position: 'absolute', top: 8, insetEnd: 8, backgroundColor: 'layer-2', boxShadow: 'elevated', borderRadius: 'default', zIndex: 1})}>
         <ActionButtonGroup
           orientation="vertical"
           isQuiet
           density="regular"
           size="S">
           <CopyButton ariaLabel="Copy code" tooltip="Copy code" getText={getText} />
-          {(shareUrl || files || type || registryUrl) && <MenuTrigger>
+          {(shareUrl || files || type || registryUrl) && <MenuTrigger align="end">
             <TooltipTrigger placement="end">
               <ActionButton aria-label="Open in…">
                 <OpenIn />
@@ -167,9 +187,23 @@ export function CodePlatter({children, shareUrl, files, type, registryUrl}: Code
   );
 }
 
+const pre = style({
+  borderRadius: 'lg',
+  font: {
+    default: 'code-xs',
+    lg: 'code-sm'
+  },
+  margin: 0,
+  paddingStart: '--code-padding-start',
+  paddingEnd: '--code-padding-end',
+  paddingY: '--code-padding-y',
+  width: 'fit',
+  minWidth: 'full'
+});
+
 export function Pre({children}) {
   return (
-    <pre className={style({borderRadius: 'lg', font: {default: 'code-xs', lg: 'code-sm'}, whiteSpace: 'pre-wrap', margin: 0, paddingX: '--code-padding-x', paddingY: '--code-padding-y'})} style={{overflowWrap: 'break-word'}}>
+    <pre className={pre}>
       {children}
     </pre>
   );
@@ -250,7 +284,7 @@ function ShadcnDialog({registryUrl}) {
               flexDirection: 'column',
               gap: 16
             })}>
-            <SegmentedControl selectedKey={packageManager} onSelectionChange={onSelectionChange}>
+            <SegmentedControl aria-label="Package manager" selectedKey={packageManager} onSelectionChange={onSelectionChange}>
               <SegmentedControlItem id="npm">npm</SegmentedControlItem>
               <SegmentedControlItem id="yarn">yarn</SegmentedControlItem>
               <SegmentedControlItem id="pnpm">pnpm</SegmentedControlItem>

packages/dev/s2-docs/src/ExampleOutput.tsx

@@ -12,7 +12,9 @@ interface ExampleOutputProps {
 
 export function ExampleOutput({component, props = {}, align = 'center', orientation = 'horizontal'}: ExampleOutputProps) {
   return (
-    <div 
+    <div
+      role="group"
+      aria-label="Rendered component"
       className={style({
         display: 'flex',
         flexDirection: {

packages/dev/s2-docs/src/ExampleSwitcher.tsx

@@ -1,8 +1,8 @@
 'use client';
 
+import {Content, ContextualHelp, Heading, Picker, PickerItem, SegmentedControl, SegmentedControlItem} from '@react-spectrum/s2';
 import {createContext, useEffect, useState} from 'react';
 import {Key} from 'react-aria-components';
-import {Picker, PickerItem, SegmentedControl, SegmentedControlItem} from '@react-spectrum/s2';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
 const exampleStyle = style({
@@ -123,7 +123,7 @@ export function ExampleSwitcher({type = 'style', examples = DEFAULT_EXAMPLES, ch
   return (
     <div className={exampleStyle} data-example-switcher>
       <div className={switcher}>
-        <SegmentedControl selectedKey={selected} onSelectionChange={onSelectionChange}>
+        <SegmentedControl aria-label={type || 'example'} selectedKey={selected} onSelectionChange={onSelectionChange}>
           {examples.map(example => <SegmentedControlItem key={example} id={example}>{example}</SegmentedControlItem>)}
         </SegmentedControl>
       </div>
@@ -133,7 +133,13 @@ export function ExampleSwitcher({type = 'style', examples = DEFAULT_EXAMPLES, ch
           labelPosition="side"
           value={theme}
           onChange={onThemeChange}
-          styles={themePicker}>
+          styles={themePicker}
+          contextualHelp={
+            <ContextualHelp>
+              <Heading>Vanilla CSS theme</Heading>
+              <Content>This sets the <code className={style({font: 'code-sm'})}>--tint</code> CSS variable used by the Vanilla CSS examples.</Content>
+            </ContextualHelp>
+          }>
           <PickerItem id="indigo">Indigo</PickerItem>
           <PickerItem id="blue">Blue</PickerItem>
           <PickerItem id="cyan">Cyan</PickerItem>

packages/dev/s2-docs/src/ExpandableCode.tsx

@@ -9,11 +9,11 @@ const example = style({
   font: 'code-lg',
   maxHeight: {
     default: '[6lh]',
-    isExpanded: 'unset'
+    isExpanded: 800
   },
   overflow: {
     default: 'clip',
-    isExpanded: 'visible'
+    isExpanded: 'auto'
   },
   position: 'relative',
   width: 'full',
@@ -24,6 +24,13 @@ const example = style({
       default: 'none',
       isExpanded: 'inline'
     }
+  },
+  '--code-padding-end': {
+    type: 'paddingEnd',
+    value: {
+      default: 16,
+      isExpanded: 64 // Extra space for the toolbar
+    }
   }
 });
 
@@ -50,8 +57,8 @@ export function ExpandableCode({children, hasHighlightedLine}: {children: ReactN
       mask = 'linear-gradient(transparent, white 25% 50%, transparent), linear-gradient(to right, white 0% 85%, transparent)';
       padding = '0px';
     } else {
-      // only mask the bottom
-      mask = 'linear-gradient(white 0% 50%, transparent)';
+      // only mask the bottom and right
+      mask = 'linear-gradient(white 0% 50%, transparent), linear-gradient(to right, white 0% 85%, transparent)';
     }
   }
 

packages/dev/s2-docs/src/Layout.tsx

@@ -12,8 +12,10 @@ import './anatomy.css';
 import {ClassAPI} from './ClassAPI';
 import {Code} from './Code';
 import {CodeBlock} from './CodeBlock';
+import {CodePlatterProvider} from './CodePlatter';
 import {ExampleSwitcher} from './ExampleSwitcher';
-import {getLibraryFromPage, getLibraryLabel} from './library';
+import {getLibraryFromPage, getLibraryFromUrl, getLibraryLabel} from './library';
+import {getTextWidth} from './textWidth';
 import {H2, H3, H4} from './Headings';
 import Header from './Header';
 import {Link} from './Link';
@@ -23,10 +25,21 @@ import {PropTable} from './PropTable';
 import {StateTable} from './StateTable';
 import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {TypeLink} from './types';
+import {VersionBadge} from './VersionBadge';
 import {VisualExample} from './VisualExample';
 
+const h1 = style({
+  font: 'heading-3xl',
+  fontSize: {
+    // On mobile, adjust heading to fit in the viewport, and clamp between a min and max font size.
+    default: 'clamp(35px, (100vw - 32px) / var(--width-per-em), 55px)',
+    lg: 'heading-3xl'
+  },
+  marginY: 0
+});
+
 const components = {
-  h1: ({children, ...props}) => <h1 {...props} id="top" className={style({font: {default: 'heading-2xl', lg: 'heading-3xl'}, marginY: 0})}>{children}</h1>,
+  h1: ({children, ...props}) => <h1 {...props} id="top" style={{'--width-per-em': getTextWidth(children)} as any} className={h1}>{children}</h1>,
   h2: H2,
   h3: H3,
   h4: H4,
@@ -226,10 +239,13 @@ export function Layout(props: PageProps & {children: ReactElement<any>}) {
                   lg: 'auto'
                 }
               })}>
-              <article
-                className={articleStyles({isWithToC: hasToC})}>
-                {React.cloneElement(children, {components})}
-              </article>
+              <CodePlatterProvider library={getLibraryFromUrl(currentPage.url)}>
+                <article
+                  className={articleStyles({isWithToC: hasToC})}>
+                  {currentPage.exports?.version && <VersionBadge version={currentPage.exports.version} />}
+                  {React.cloneElement(children, {components})}
+                </article>
+              </CodePlatterProvider>
               {hasToC && <aside
                 className={style({
                   position: 'sticky',