docs: Add examples section (#9094)

* docs: Add examples section

* Support size() macro in CSS strings

* Remove font-variation-settings

* Support standalone Cards as links

* Fix border width of tertiary cards

* Fix WaterfallLayout bugs

* Add descriptions to search menu cards

* Default search menu category to current page category

* lint

* Fix mobile search menu

* Fix mobile

Author: devongovett

packages/@react-spectrum/s2/src/Card.tsx

@@ -15,7 +15,7 @@ import {AvatarContext} from './Avatar';
 import {ButtonContext, LinkButtonContext} from './Button';
 import {Checkbox} from './Checkbox';
 import {color, focusRing, lightDark, space, style} from '../style' with {type: 'macro'};
-import {composeRenderProps, ContextValue, DEFAULT_SLOT, type GridListItem, GridListItemProps, Provider} from 'react-aria-components';
+import {composeRenderProps, ContextValue, DEFAULT_SLOT, type GridListItem, GridListItemProps, Link, Provider} from 'react-aria-components';
 import {ContentContext, FooterContext, TextContext} from './Content';
 import {createContext, CSSProperties, forwardRef, ReactNode, useContext} from 'react';
 import {DividerContext} from './Divider';
@@ -95,18 +95,19 @@ let card = style({
     variant: {
       tertiary: {
         // Render border with box-shadow to avoid affecting layout.
-        default: `[0 0 0 1px ${color('gray-100')}]`,
-        isHovered: `[0 0 0 1px ${color('gray-200')}]`,
-        isFocusVisible: `[0 0 0 1px ${color('gray-200')}]`,
+        default: `[0 0 0 2px ${color('gray-100')}]`,
+        isHovered: `[0 0 0 2px ${color('gray-200')}]`,
+        isFocusVisible: `[0 0 0 2px ${color('gray-200')}]`,
         isSelected: 'none',
-        forcedColors: '[0 0 0 1px ButtonBorder]'
+        forcedColors: '[0 0 0 2px ButtonBorder]'
       },
       quiet: 'none'
     }
   },
   forcedColorAdjust: 'none',
   transition: 'default',
   fontFamily: 'sans',
+  textDecoration: 'none',
   overflow: {
     default: 'clip',
     variant: {
@@ -424,6 +425,28 @@ export const Card = forwardRef(function Card(props: CardProps, ref: DOMRef<HTMLD
     </Provider>
   );
 
+  let press = pressScale(domRef, UNSAFE_style);
+  if (ElementType === 'div' && !isSkeleton && props.href) {
+    // Standalone Card that has an href should be rendered as a Link.
+    // NOTE: In this case, the card must not contain interactive elements.
+    return (
+      <Link
+        {...filterDOMProps(otherProps, {isLink: true})}
+        ref={domRef as any}
+        className={renderProps => UNSAFE_className + card({...renderProps, size, density, variant, isCardView: false, isLink: true}, styles)}
+        style={renderProps =>
+          // Only the preview in quiet cards scales down on press
+          variant === 'quiet' ? UNSAFE_style : press(renderProps)
+        }>
+        {(renderProps) => (
+          <InternalCardContext.Provider value={{size, isQuiet, isCheckboxSelection: false, isSelected: false, ...renderProps}}>
+            {children}
+          </InternalCardContext.Provider>
+        )}
+      </Link>
+    );
+  }
+
   if (ElementType === 'div' || isSkeleton) {
     return (
       <div
@@ -441,7 +464,6 @@ export const Card = forwardRef(function Card(props: CardProps, ref: DOMRef<HTMLD
     );
   }
 
-  let press = pressScale(domRef, UNSAFE_style);
   return (
     <ElementType
       {...props}

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

@@ -11,18 +11,14 @@
  */
 
 import type * as CSS from 'csstype';
-import {Inset, fontRelative as internalFontRelative, size as internalSize, space as internalSpace, Spacing, style} from './spectrum-theme';
+import {Inset, fontRelative as internalFontRelative, space as internalSpace, Spacing, style} from './spectrum-theme';
 import type {MacroContext} from '@parcel/macros';
 import {StyleString} from './types';
 
-export {baseColor, color, edgeToText, lightDark, linearGradient, colorMix, style} from './spectrum-theme';
+export {baseColor, color, edgeToText, lightDark, linearGradient, colorMix, size, style} from './spectrum-theme';
 export type {StyleString} from './types';
 
 // Wrap these functions in arbitrary value syntax when called from the outside.
-export function size(px: number): `[${string}]` {
-  return `[${internalSize(px)}]`;
-}
-
 export function space(px: number): `[${string}]` {
   return `[${internalSpace(px)}]`;
 }

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

@@ -330,7 +330,7 @@ const padding = {
   ...relativeSpacing
 };
 
-export function size(this: MacroContext | void, px: number): string {
+export function size(this: MacroContext | void, px: number): `calc(${string})` {
   return `calc(${pxToRem(px)} * var(--s2-scale))`;
 }
 
@@ -767,9 +767,6 @@ export const style = createTheme({
     }, fontSize),
     fontWeight: new ExpandedProperty<keyof typeof fontWeight>(['fontWeight', 'fontVariationSettings', 'fontSynthesisWeight'], (value) => {
       return {
-        // Set font-variation-settings in addition to font-weight to work around typekit issue.
-        // (This was fixed, but leaving for backward compatibility for now.)
-        fontVariationSettings: value === 'inherit' ? 'inherit' : `"wght" ${value}`,
         fontWeight: value as any,
         fontSynthesisWeight: 'none'
       };

packages/@react-stately/layout/src/WaterfallLayout.ts

@@ -48,10 +48,12 @@ export interface WaterfallLayoutOptions {
 
 class WaterfallLayoutInfo extends LayoutInfo {
   column = 0;
+  index = 0;
 
   copy(): WaterfallLayoutInfo {
     let res = super.copy() as WaterfallLayoutInfo;
     res.column = this.column;
+    res.index = this.index;
     return res;
   }
 }
@@ -123,18 +125,19 @@ export class WaterfallLayout<T extends object, O extends WaterfallLayoutOptions
     // Setup an array of column heights
     let columnHeights = Array(numColumns).fill(minSpace.height);
     let newLayoutInfos = new Map();
+    let index = 0;
     let addNode = (key: Key, node: Node<T>) => {
       let oldLayoutInfo = this.layoutInfos.get(key);
       let height = itemHeight;
       let estimatedSize = true;
       if (oldLayoutInfo) {
-        height = oldLayoutInfo.rect.height;
+        height = oldLayoutInfo.rect.height / oldLayoutInfo.rect.width * itemWidth;
         estimatedSize = invalidationContext.sizeChanged || oldLayoutInfo.estimatedSize || oldLayoutInfo.content !== node;
       }
 
       // Figure out which column to place the item in, and compute its position.
       // Preserve the previous column index so items don't jump around during resizing unless the number of columns changed.
-      let prevColumn = numColumns === this.numColumns && oldLayoutInfo && oldLayoutInfo.rect.y < this.virtualizer!.visibleRect.maxY ? oldLayoutInfo.column : undefined;
+      let prevColumn = numColumns === this.numColumns && oldLayoutInfo && oldLayoutInfo.index === index && oldLayoutInfo.rect.y < this.virtualizer!.visibleRect.maxY ? oldLayoutInfo.column : undefined;
       let column = prevColumn ?? columnHeights.reduce((minIndex, h, i) => h < columnHeights[minIndex] ? i : minIndex, 0);
       let x = horizontalSpacing + column * (itemWidth + horizontalSpacing) + this.margin;
       let y = columnHeights[column];
@@ -145,6 +148,7 @@ export class WaterfallLayout<T extends object, O extends WaterfallLayoutOptions
       layoutInfo.allowOverflow = true;
       layoutInfo.content = node;
       layoutInfo.column = column;
+      layoutInfo.index = index++;
       newLayoutInfos.set(key, layoutInfo);
 
       columnHeights[column] += layoutInfo.rect.height + minSpace.height;

packages/dev/s2-docs/package.json

@@ -38,6 +38,7 @@
     "@react-spectrum/utils": "^3.12.6",
     "@react-types/shared": "^3.30.0",
     "@react-types/textfield": "^3.12.3",
+    "emojibase-data": "^16.0.3",
     "fast-glob": "^3.3.3",
     "globals-docs": "^2.4.1",
     "gray-matter": "^4.0.3",

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

@@ -5,6 +5,7 @@ export default Layout;
 import docs from 'docs:@react-spectrum/s2';
 
 export const hideFromSearch = true;
+export const hideNav = true;
 export const description = 'Page not found';
 
 <Error />

packages/dev/s2-docs/pages/react-aria/Autocomplete.mdx

@@ -160,9 +160,8 @@ function Example(props) {
 "use client";
 import {Select, Label, SelectValue, Autocomplete, useFilter} from 'react-aria-components';
 import {Button} from 'vanilla-starter/Button';
-import {SelectItem} from 'vanilla-starter/Select';
+import {SelectListBox, SelectItem} from 'vanilla-starter/Select';
 import {Popover} from 'vanilla-starter/Popover';
-import {ListBox} from 'vanilla-starter/ListBox';
 import {SearchField} from 'vanilla-starter/SearchField';
 import {ChevronDown} from 'lucide-react';
 
@@ -232,7 +231,7 @@ function Example(props) {
         <SelectValue />
         <ChevronDown size={18} />
       </Button>
-      <Popover hideArrow style={{display: 'flex', flexDirection: 'column'}}>
+      <Popover hideArrow className="select-popover" style={{display: 'flex', flexDirection: 'column'}}>
         {/*- begin highlight -*/}
         <Autocomplete {...props}/* PROPS */ filter={contains}>
           {/*- end highlight -*/}
@@ -241,12 +240,12 @@ function Example(props) {
             aria-label="Search states"
             placeholder="Search states"
             style={{margin: 4}} />
-          <ListBox
+          <SelectListBox
             items={states}
             renderEmptyState={() => 'No results.'}
             style={{flex: 1}}>
             {state => <SelectItem>{state.name}</SelectItem>}
-          </ListBox>
+          </SelectListBox>
         </Autocomplete>
       </Popover>
     </Select>
@@ -1101,6 +1100,10 @@ function AsyncLoadingExample() {
 }
 ```
 
+## Examples
+
+<ExampleList tag="autocomplete" pages={props.pages} />
+
 ## API
 
 ```tsx links={{Autocomplete: '#autocomplete', SearchField: 'SearchField.html', TextField: 'TextField.html', Menu: 'Menu.html', ListBox: 'ListBox.html', TagGroup: 'TagGroup.html', GridList: 'GridList.html', Table: 'Table.html'}}

packages/dev/s2-docs/pages/react-aria/Button.mdx

@@ -120,6 +120,10 @@ import {Link} from 'react-aria-components';
 </Link>
 ```
 
+## Examples
+
+<ExampleList tag="button" pages={props.pages} />
+
 ## API
 
 <PropTable component={docs.exports.Button} links={docs.links} />

packages/dev/s2-docs/pages/react-aria/DropZone.mdx

@@ -89,6 +89,10 @@ export const tags = ['file', 'drag', 'dnd', 'upload'];
   ```
 </ExampleSwitcher>
 
+## Examples
+
+<ExampleList tag="dropzone" pages={props.pages} />
+
 ## API
 
 ```tsx links={{DropZone: '#dropzone'}}

packages/dev/s2-docs/pages/react-aria/Form.mdx

@@ -194,6 +194,10 @@ function Example() {
 }
 ```
 
+## Examples
+
+<ExampleList tag="form" pages={props.pages} />
+
 ## API
 
 <PropTable component={docs.exports.Form} links={docs.links} />