Setup S2 release notes (adobe#6881)

blefnk · Aug 16, 2024 · cfd890e · cfd890e
1 parent 0f2c781
commit cfd890e
Show file tree

Hide file tree

Showing 19 changed files with 824 additions and 1,001 deletions.
diff --git a/.storybook-s2/docs/Icons.jsx b/.storybook-s2/docs/Icons.jsx
@@ -1,7 +1,7 @@
 import icons from '@react-spectrum/s2/s2wf-icons/*.svg';
 import { style } from '../../packages/@react-spectrum/s2/style/spectrum-theme' with {type: 'macro'};
 import {ActionButton, Text} from '@react-spectrum/s2';
-import {P, Code, Pre} from './typography';
+import {H2, H3, P, Code, Pre, Link} from './typography';
 import {highlight} from './highlight' with {type: 'macro'};
 
 export function Icons() {
@@ -29,6 +29,25 @@ export function Icons() {
             );
           })}
         </div>
+        <H2>Custom icons</H2>
+        <P>To use custom icons, you first need to convert your SVGs into compatible icon components. This depends on your bundler.</P>
+        <H3>Parcel</H3>
+        <P>If you are using Parcel, the <Code>@react-spectrum/parcel-transformer-s2-icon</Code> plugin can be used to convert SVGs to icon components. First install it into your project as a dev dependency:</P>
+        <Pre>yarn add @react-spectrum/parcel-transformer-s2-icon --dev</Pre>
+        <P>Then, add it to your <Code>.parcelrc</Code>:</P>
+        <Pre>{highlight(`{
+  "extends": "@parcel/config-default",
+  "transformers": {
+    "icon:*.svg": ["@react-spectrum/parcel-transformer-s2-icon"]
+  }
+}`)}</Pre>
+        <P>Now you can import icon SVGs using the <Code>icon:</Code> <Link href="https://parceljs.org/features/plugins/#named-pipelines">pipeline</Link>:</P>
+        <Pre>{highlight(`import Icon from 'icon:./path/to/Icon.svg';`)}</Pre>
+        <H3>Other bundlers</H3>
+        <P>The <Code>@react-spectrum/s2-icon-builder</Code> CLI tool can be used to pre-process a folder of SVG icons into TSX files.</P>
+        <Pre>npx @react-spectrum/s2-icon-builder -i 'path/to/icons/*.svg' -o 'path/to/destination'</Pre>
+        <P>This outputs a folder of TSX files with names corresponding to the input SVG files. You may rename them as you wish. To use them in your application, import them like normal components.</P>
+        <Pre>{highlight(`import Icon from './path/to/destination/Icon';`)}</Pre>
       </div>
     </div>
   );

diff --git a/.storybook-s2/docs/Illustrations.jsx b/.storybook-s2/docs/Illustrations.jsx
@@ -1,9 +1,9 @@
 import linearIllustrations from '@react-spectrum/s2/spectrum-illustrations/linear/*.tsx';
-import gradientIllustrations from '@react-spectrum/s2/spectrum-illustrations/gradient/*.svg';
+import gradientIllustrations from 'illustration:@react-spectrum/s2/spectrum-illustrations/gradient/*.svg';
 import Paste from '@react-spectrum/s2/s2wf-icons/S2_Icon_Paste_20_N.svg';
 import { style } from '../../packages/@react-spectrum/s2/style/spectrum-theme' with {type: 'macro'};
 import {ActionButton, Text} from '@react-spectrum/s2';
-import {H2, P, Code, Pre} from './typography';
+import {H2, H3, P, Code, Pre, Link} from './typography';
 import {highlight} from './highlight' with {type: 'macro'};
 import { Radio, RadioGroup } from '../../packages/@react-spectrum/s2/src';
 import { useState } from 'react';
@@ -35,7 +35,7 @@ export function Illustrations() {
               return 'gradient/' + style + '/' + name;
             });
             return (
-              <div className={style({display: 'flex', flexDirection: 'column', rowGap: 8, alignItems: 'center', padding: 16, borderRadius: 'lg', boxShadow: 'elevated'})}>
+              <div key={icon} className={style({display: 'flex', flexDirection: 'column', rowGap: 8, alignItems: 'center', padding: 16, borderRadius: 'lg', boxShadow: 'elevated', backgroundColor: 'layer-2'})}>
                 <Illustration UNSAFE_style={{width: 96, height: 96}} />
                 <span className={style({font: 'ui', display: 'flex', gap: 8, alignItems: 'center', maxWidth: 'full'})}>
                   <span className={style({truncate: true})}>{name}</span>
@@ -58,7 +58,7 @@ export function Illustrations() {
           {Object.keys(linearIllustrations).map(icon => {
             let Illustration = linearIllustrations[icon].default;
             return (
-              <div className={style({display: 'flex', flexDirection: 'column', rowGap: 8, alignItems: 'center', padding: 16, borderRadius: 'lg', boxShadow: 'elevated'})}>
+              <div key={icon} className={style({display: 'flex', flexDirection: 'column', rowGap: 8, alignItems: 'center', padding: 16, borderRadius: 'lg', boxShadow: 'elevated', backgroundColor: 'layer-2'})}>
                 <Illustration />
                 <span className={style({font: 'ui', display: 'flex', gap: 8, alignItems: 'center', maxWidth: 'full'})}>
                   <span className={style({truncate: true})}>{icon}</span>
@@ -74,6 +74,25 @@ export function Illustrations() {
             );
           })}
         </div>
+        <H2>Custom illustrations</H2>
+        <P>To use custom illustrations, you first need to convert your SVGs into compatible illustration components. This depends on your bundler.</P>
+        <H3>Parcel</H3>
+        <P>If you are using Parcel, the <Code>@react-spectrum/parcel-transformer-s2-icon</Code> plugin can be used to convert SVGs to illustration components. First install it into your project as a dev dependency:</P>
+        <Pre>yarn add @react-spectrum/parcel-transformer-s2-icon --dev</Pre>
+        <P>Then, add it to your <Code>.parcelrc</Code>:</P>
+        <Pre>{highlight(`{
+  "extends": "@parcel/config-default",
+  "transformers": {
+    "illustration:*.svg": ["@react-spectrum/parcel-transformer-s2-icon"]
+  }
+}`)}</Pre>
+        <P>Now you can import illustration SVGs using the <Code>illustration:</Code> <Link href="https://parceljs.org/features/plugins/#named-pipelines">pipeline</Link>:</P>
+        <Pre>{highlight(`import Illustration from 'illustration:./path/to/Illustration.svg';`)}</Pre>
+        <H3>Other bundlers</H3>
+        <P>The <Code>@react-spectrum/s2-icon-builder</Code> CLI tool can be used to pre-process a folder of SVG illustrations into TSX files.</P>
+        <Pre>npx @react-spectrum/s2-icon-builder -i 'path/to/illustrations/*.svg' --type illustration -o 'path/to/destination'</Pre>
+        <P>This outputs a folder of TSX files with names corresponding to the input SVG files. You may rename them as you wish. To use them in your application, import them like normal components.</P>
+        <Pre>{highlight(`import Illustration from './path/to/destination/Illustration';`)}</Pre>
       </div>
     </div>
   );

diff --git a/.storybook-s2/docs/Intro.jsx b/.storybook-s2/docs/Intro.jsx
@@ -1,5 +1,5 @@
 import { style } from '../../packages/@react-spectrum/s2/style/spectrum-theme' with {type: 'macro'};
-import {Button, LinkButton, ButtonGroup, Checkbox, Content, Dialog, DialogTrigger, Footer, Header, Heading, Image, InlineAlert, Menu, MenuItem, MenuSection, MenuTrigger, SubmenuTrigger, Switch, Link, Text} from '@react-spectrum/s2';
+import {Button, LinkButton, ButtonGroup, Checkbox, Content, Dialog, DialogTrigger, Footer, Header, Heading, Image, InlineAlert, Menu, MenuItem, MenuSection, MenuTrigger, SubmenuTrigger, Switch, Text} from '@react-spectrum/s2';
 import NewIcon from '@react-spectrum/s2/s2wf-icons/S2_Icon_New_20_N.svg';
 import ImgIcon from '@react-spectrum/s2/s2wf-icons/S2_Icon_Image_20_N.svg';
 import CopyIcon from '@react-spectrum/s2/s2wf-icons/S2_Icon_Copy_20_N.svg';
@@ -9,7 +9,7 @@ import CommunityIcon from '@react-spectrum/s2/s2wf-icons/S2_Icon_Community_20_N.
 import DeviceTabletIcon from '@react-spectrum/s2/s2wf-icons/S2_Icon_DeviceTablet_20_N.svg';
 import DeviceDesktopIcon from '@react-spectrum/s2/s2wf-icons/S2_Icon_DeviceDesktop_20_N.svg';
 import {highlight} from './highlight' with {type: 'macro'};
-import {H2, H3, H4, P, Pre, Code, Strong} from './typography';
+import {H2, H3, H4, P, Pre, Code, Strong, Link} from './typography';
 
 export function Docs() {
   return (
@@ -165,12 +165,14 @@ function App() {
         <H3>Overriding the locale</H3>
         <P>By default, React Spectrum uses the browser/operating system language setting for localized strings, date and number formatting, and to determine the layout direction (left-to-right or right-to-left). This can be overridden by rendering a <Code>{'<Provider>'}</Code> component at the root of your app, and setting the <Code>locale</Code> prop.</P>
         <Pre>{highlight(`import {Provider} from '@react-spectrum/s2';
+
 <Provider locale="en-US">
   {/* your app */}
 </Provider>`)}</Pre>
         <H3>Embedded sections</H3>
         <P>If you’re building an embedded section of a larger page using Spectrum 2, use the <Code>{'<Provider>'}</Code> component to set the background instead of importing <Code>page.css</Code>. The <Code>background</Code> prop should be set to the Spectrum background layer appropriate for your app, and the <Code>colorScheme</Code> can be overridden as well.</P>
         <Pre>{highlight(`import {Provider} from '@react-spectrum/s2';
+
 <Provider background="base">
   {/* your app */}
 </Provider>`)}</Pre>
@@ -186,7 +188,7 @@ import {ActionButton} from '@react-spectrum/s2';
         <P>The <Code>styles</Code> prop accepts a limited set of CSS properties, including layout, spacing, sizing, and positioning. Other styles such as colors and internal padding cannot be customized within Spectrum components.</P>
         <InlineAlert variant="informative" fillStyle="subtleFill" styles={style({marginBottom: 16})}>
           <Heading>Learn more about styling</Heading>
-          <Content>See the <Link href="/?path=/docs/style-macro--docs" variant="secondary" target="_top">full docs</Link> to learn about using the style macro to build custom components.</Content>
+          <Content>See the <Link href="?path=/docs/style-macro--docs" variant="secondary" target="_top">full docs</Link> to learn about using the style macro to build custom components.</Content>
         </InlineAlert>
         <H3>Supported CSS properties on Spectrum components</H3>
         <ul className={'sb-unstyled' + style({fontSize: 'body-lg', lineHeight: 'body', color: 'body', columns: 3, padding: 0, listStyleType: 'none'})}>
@@ -225,7 +227,7 @@ import {ActionButton} from '@react-spectrum/s2';
           <li><Code>insetEnd</Code></li>
         </ul>
         <H3>UNSAFE Style Overrides</H3>
-        <P>We highly discourage overriding the styles of React Spectrum components because it may break at any time when we change our implementation, making it difficult for you to update in the future. Consider using <Link href="https://react-spectrum.adobe.com/react-aria/" target="_blank">React Aria Components</Link> with our <Link href="/?path=/docs/style-macro--docs" target="_top">style macro</Link> to build a custom component with Spectrum styles instead.</P>
+        <P>We highly discourage overriding the styles of React Spectrum components because it may break at any time when we change our implementation, making it difficult for you to update in the future. Consider using <Link href="https://react-spectrum.adobe.com/react-aria/" target="_blank">React Aria Components</Link> with our <Link href="?path=/docs/style-macro--docs" target="_top">style macro</Link> to build a custom component with Spectrum styles instead.</P>
         <P>That said, just like in React Spectrum v3, the <Code>UNSAFE_className</Code> and <Code>UNSAFE_style</Code> props are supported on Spectrum 2 components as last-resort escape hatches. However, unlike in v3, UNSAFE_classNames must be placed in a special <Code>UNSAFE_overrides</Code> <Link href="https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers" target="_blank">CSS cascade layer</Link>. This guarentees that your overrides will always win over other styles on the page, no matter the order or specificity of the selector.</P>
         <Pre>{highlight(`/* YourComponent.tsx */
 import {Button} from '@react-spectrum/s2';

diff --git a/.storybook-s2/docs/MDXLayout.jsx b/.storybook-s2/docs/MDXLayout.jsx
@@ -0,0 +1,30 @@
+import { style } from '../../packages/@react-spectrum/s2/style/spectrum-theme' with {type: 'macro'};
+import {highlight} from './highlight' with {type: 'macro'};
+import {H2, H3, H3, P, Pre, Code, Strong, H4, Link} from './typography';
+import {MDXProvider} from '@mdx-js/react';
+
+const mdxComponents = {
+  h1: ({children}) => <h1 className={style({font: 'heading-2xl'})}>{children}</h1>,
+  h2: H2,
+  h3: H3,
+  h4: H4,
+  p: P,
+  pre: Pre,
+  code: Code,
+  strong: Strong,
+  ul: ({children}) => <ul className="sb-unstyled">{children}</ul>,
+  li: ({children}) => <li className={style({font: 'body-lg', marginTop: 0, marginBottom: 4})}>{children}</li>,
+  a: Link
+}
+
+export function MDXLayout({children}) {
+  return (
+    <div className={style({maxWidth: 'lg', marginX: 'auto'})}>
+      <main className={style({marginX: 48})}>
+        <MDXProvider components={mdxComponents}>
+          {children}
+        </MDXProvider>
+      </main>
+    </div>
+  );
+}