Skip to content

Commit

Permalink
Initial Float docs for hoistable/semantic elements (#6486)
Browse files Browse the repository at this point in the history 
* Initial Float docs for hoistable/semantic elements
  • Loading branch information
@davidmccabe
davidmccabe authored Feb 2, 2024
1 parent 6ca0381 commit 8ba8772
Show file tree
Hide file tree
Showing 11 changed files with 815 additions and 2 deletions.
3 changes: 2 additions & 1 deletion src/components/MDX/InlineCode.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@
import cn from 'classnames';

interface InlineCodeProps {
isLink: boolean;
isLink?: boolean;
meta?: string;
}
function InlineCode({
isLink,
Expand Down
2 changes: 2 additions & 0 deletions src/components/MDX/MDXComponents.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ import Link from './Link';
import {PackageImport} from './PackageImport';
import Recap from './Recap';
import Sandpack from './Sandpack';
import SandpackWithHTMLOutput from './SandpackWithHTMLOutput';
import Diagram from './Diagram';
import DiagramGroup from './DiagramGroup';
import SimpleCallout from './SimpleCallout';
Expand Down Expand Up @@ -434,6 +435,7 @@ export const MDXComponents = {
Recap,
Recipes,
Sandpack,
SandpackWithHTMLOutput,
TeamMember,
TerminalBlock,
YouWillLearn,
Expand Down
5 changes: 4 additions & 1 deletion src/components/MDX/Sandpack/createFileMap.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,10 @@ export const SUPPORTED_FILES = [AppJSPath, StylesCSSPath];
export const createFileMap = (codeSnippets: any) => {
return codeSnippets.reduce(
(result: Record<string, SandpackFile>, codeSnippet: React.ReactElement) => {
if ((codeSnippet.type as any).mdxName !== 'pre') {
if (
(codeSnippet.type as any).mdxName !== 'pre' &&
codeSnippet.type !== 'pre'
) {
return result;
}
const {props} = codeSnippet.props.children;
Expand Down
85 changes: 85 additions & 0 deletions src/components/MDX/SandpackWithHTMLOutput.tsx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
import {Children, memo} from 'react';
import InlineCode from './InlineCode';
import Sandpack from './Sandpack';

const ShowRenderedHTML = `
import { renderToStaticMarkup } from 'react-dom/server';
import formatHTML from './formatHTML.js';
export default function ShowRenderedHTML({children}) {
const markup = renderToStaticMarkup(
<html>
<head />
<body>{children}</body>
</html>
);
return (
<>
<h1>Rendered HTML:</h1>
<pre>
{formatHTML(markup)}
</pre>
</>
);
}`;

const formatHTML = `
import format from 'html-format';
export default function formatHTML(markup) {
// Cheap tricks to format the HTML readably -- haven't been able to
// find a package that runs in browser and prettifies the HTML if it
// lacks line-breaks.
return format(markup
.replace('<html>', '<html>\\n')
.replace('<head>', '<head>\\n')
.replaceAll(/<\\/script>/g, '<\\/script>\\n')
.replaceAll(/<style([^>]*)\\/>/g, '<style $1/>\\n\\n')
.replaceAll(/<\\/style>/g, '\\n <\\/style>\\n')
.replaceAll(/<link([^>]*)\\/>/g, '<link $1/>\\n')
.replaceAll(/<meta([^/]*)\\/>/g, '<meta $1/>\\n')
.replace('</head>', '</head>\\n')
.replace('<body>', '<body>\\n')
.replace('</body>', '\\n</body>\\n')
.replace('</h1>', '</h1>\\n')
);
}
`;

const packageJSON = `
{
"dependencies": {
"react": "18.3.0-canary-6db7f4209-20231021",
"react-dom": "18.3.0-canary-6db7f4209-20231021",
"react-scripts": "^5.0.0",
"html-format": "^1.1.2"
},
"main": "/index.js",
"devDependencies": {}
}
`;

// Intentionally not a React component because <Sandpack> will read
// through its childrens' props. This imitates the output of ```
// codeblocks in MDX.
function createFile(meta: string, source: string) {
return (
<pre key={meta}>
<InlineCode meta={meta} className="language-js">
{source}
</InlineCode>
</pre>
);
}

export default memo(function SandpackWithHTMLOutput(
props: React.ComponentProps<typeof Sandpack>
) {
const children = [
...Children.toArray(props.children),
createFile('ShowRenderedHTML.js', ShowRenderedHTML),
createFile('formatHTML.js hidden', formatHTML),
createFile('package.json hidden', packageJSON),
];
return <Sandpack {...props}>{children}</Sandpack>;
});
14 changes: 14 additions & 0 deletions src/content/reference/react-dom/components/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,20 @@ They are special in React because passing the `value` prop to them makes them *[

---

## Resource and Metadata Components {/*resource-and-metadata-components*/}

These bulit-in browser components let you load external resources or annotate the document with metadata:

* [`<link>`](/reference/react-dom/components/link)
* [`<meta>`](/reference/react-dom/components/meta)
* [`<script>`](/reference/react-dom/components/script)
* [`<style>`](/reference/react-dom/components/style)
* [`<title>`](/reference/react-dom/components/title)

They are special in React because React can render them into the document head, suspend while resources are loading, and enact other behaviors that are described on the reference page for each specific component.

---

## All HTML components {/*all-html-components*/}

React supports all built-in browser HTML components. This includes:
Expand Down
228 changes: 228 additions & 0 deletions src/content/reference/react-dom/components/link.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,228 @@
---
link: "<link>"
canary: true
---

<Canary>

React's extensions to `<link>` are currently only available in React's canary and experimental channels. In stable releases of React `<link>` works only as a [built-in browser HTML component](https://react.dev/reference/react-dom/components#all-html-components). Learn more about [React's release channels here](/community/versioning-policy#all-release-channels).

</Canary>

<Intro>

The [built-in browser `<link>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) lets you use external resources such as stylesheets or annotate the document with link metadata.

```js
<link rel="icon" href="favicon.ico" />
```

</Intro>

<InlineToc />

---

## Reference {/*reference*/}

### `<link>` {/*link*/}

To link to external resources such as stylesheets, fonts, and icons, or to annotate the document with link metadata, render the [built-in browser `<link>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link). You can render `<link>` from any component and React will [in most cases](#special-rendering-behavior) place the corresponding DOM element in the document head.

```js
<link rel="icon" href="favicon.ico" />
```

[See more examples below.](#usage)

#### Props {/*props*/}

`<link>` supports all [common element props.](/reference/react-dom/components/common#props)

* `rel`: a string, required. Specifies the [relationship to the resource](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel). React [treats links with `rel="stylesheet"` differently](#special-rendering-behavior) from other links.

These props apply when `rel="stylesheet"`:

* `precedence`: a string. Tells React where to rank the `<link>` DOM node relative to others in the document `<head>`, which determines which stylesheet can override the other. Its value can be (in order of precedence) `"reset"`, `"low"`, `"medium"`, `"high"`. Stylesheets with the same precedence go together whether they are `<link>` or inline `<style>` tags or loaded using the [`preload`](/reference/react-dom/preload) or [`preinit`](/reference/react-dom/preinit) functions.
* `media`: a string. Restricts the spreadsheet to a certain [media query](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries).
* `title`: a string. Specifies the name of an [alternative stylesheet](https://developer.mozilla.org/en-US/docs/Web/CSS/Alternative_style_sheets).

These props apply when `rel="stylesheet"` but disable React's [special treatment of stylesheets](#special-rendering-behavior):

* `disabled`: a boolean. Disables the spreadsheet.
* `onError`: a function. Called when the stylesheet fails to load.
* `onLoad`: a function. Called when the stylesheet finishes being loaded.

These props apply when `rel="preload"` or `rel="modulepreload"`:

* `as`: a string. The type of resource. Its possible values are `audio`, `document`, `embed`, `fetch`, `font`, `image`, `object`, `script`, `style`, `track`, `video`, `worker`.
* `imageSrcSet`: a string. Applicable only when `as="image"`. Specifies the [source set of the image](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).
* `imageSizes`: a string. Applicable only when `as="image"`. Specifies the [sizes of the image](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).

These props apply when `rel="icon"` or `rel="apple-touch-icon"`:

* `sizes`: a string. The [sizes of the icon](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).

These props apply in all cases:

* `href`: a string. The URL of the linked resource.
* `crossOrigin`: a string. The [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to use. Its possible values are `anonymous` and `use-credentials`. It is required when `as` is set to `"fetch"`.
* `referrerPolicy`: a string. The [Referrer header](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#referrerpolicy) to send when fetching. Its possible values are `no-referrer-when-downgrade` (the default), `no-referrer`, `origin`, `origin-when-cross-origin`, and `unsafe-url`.
* `fetchPriority`: a string. Suggests a relative priority for fetching the resource. The possible values are `auto` (the default), `high`, and `low`.
* `hrefLang`: a string. The language of the linked resource.
* `integrity`: a string. A cryptographic hash of the resource, to [verify its authenticity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity).
* `type`: a string. The MIME type of the linked resource.

Props that are **not recommended** for use with React:

* `blocking`: a string. If set to `"render"`, instructs the browser not to render the page until the stylesheet is loaded. React provides more fine-grained control using Suspense.

#### Special rendering behavior {/*special-rendering-behavior*/}

React will always place the DOM element corresponding to the `<link>` component within the document’s `<head>`, regardless of where in the React tree it is rendered. The `<head>` is the only valid place for `<link>` to exist within the DOM, yet it’s convenient and keeps things composable if a component representing a specific page can render `<link>` components itself.

There are a few exceptions to this:

* If the `<link>` has a `rel="stylesheet"` prop, then it has to also have a `precedence` prop to get this special behavior. This is because the order of stylesheets within the document is significant, so React needs to know how to order this stylesheet relative to others, which you specify using the `precedence` prop. If the `precedence` prop is omitted, there is no special behavior.
* If the `<link>` has an [`itemProp`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemprop) prop, there is no special behavior, because in this case it doesn’t apply to the document but instead represents metadata about a specific part of the page.
* If the `<link>` has an `onLoad` or `onError` prop, because in that case you are managing the loading of the linked resource manually within your React component.

#### Special behavior for stylesheets {/*special-behavior-for-stylesheets*/}

In addition, if the `<link>` is to a stylesheet (namely, it has `rel="stylesheet"` in its props), React treats it specially in the following ways:

* The component that renders `<link>` will [suspend](http://localhost:3000/reference/react/Suspense) while the stylesheet is loading.
* If multiple components render links to the same stylesheet, React will de-duplicate them and only put a single link into the DOM. Two links are considered the same if they have the same `href` prop.

There are two exception to this special behavior:

* If the link doesn't have a `precedence` prop, there is no special behavior, because the order of stylesheets within the document is significant, so React needs to know how to order this stylesheet relative to others, which you specify using the `precedence` prop.
* If you supply any of the `onLoad`, `onError`, or `disabled` props, there is no special behavior, because these props indicate that you are managing the loading of the stylesheet manually within your component.

This special treatment comes with two caveats:

* React will ignore changes to props after the link has been rendered. (React will issue a warning in development if this happens.)
* React may leave the link in the DOM even after the component that rendered it has been unmounted.

---

## Usage {/*usage*/}

### Linking to related resources {/*linking-to-related-resources*/}

You can annotate the document with links to related resources such as an icon, canonical URL, or pingback. React will place this metadata within the document `<head>` regardless of where in the React tree it is rendered.

<SandpackWithHTMLOutput>

```js App.js active
import ShowRenderedHTML from './ShowRenderedHTML.js';

export default function BlogPage() {
return (
<ShowRenderedHTML>
<link rel="icon" href="favicon.ico" />
<link rel="pingback" href="http://www.example.com/xmlrpc.php" />
<h1>My Blog</h1>
<p>...</p>
</ShowRenderedHTML>
);
}
```

</SandpackWithHTMLOutput>

### Linking to a stylesheet {/*linking-to-a-stylesheet*/}

If a component depends on a certain stylesheet in order to be displayed correctly, you can render a link to that stylesheet within the component. Your component will [suspend](http://localhost:3000/reference/react/Suspense) while the stylesheet is loading. You must supply the `precedence` prop, which tells React where to place this stylesheet relative to others — stylesheets with higher precedence can override those with lower precedence.

<Note>
When you want to use a stylesheet, it can be beneficial to call the [preinit](/reference/react-dom/preinit) function. Calling this function may allow the browser to start fetching the stylesheet earlier than if you just render a `<link>` component, for example by sending an [HTTP Early Hints response](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/103).
</Note>

<SandpackWithHTMLOutput>

```js App.js active
import ShowRenderedHTML from './ShowRenderedHTML.js';

export default function SiteMapPage() {
return (
<ShowRenderedHTML>
<link rel="stylesheet" href="sitemap.css" precedence="medium" />
<p>...</p>
</ShowRenderedHTML>
);
}
```

</SandpackWithHTMLOutput>

### Controlling stylesheet precedence {/*controlling-stylesheet-precedence*/}

Stylesheets can conflict with each other, and when they do, the browser goes with the one that comes later in the document. React lets you control the order of stylesheets with the `precedence` prop. In this example, two components render stylesheets, and the one with the higher precedence goes later in the document even though the component that renders it comes earlier.

{/*FIXME: this doesn't appear to actually work -- I guess precedence isn't implemented yet?*/}

<SandpackWithHTMLOutput>

```js App.js active
import ShowRenderedHTML from './ShowRenderedHTML.js';

export default function HomePage() {
return (
<ShowRenderedHTML>
<FirstComponent />
<SecondComponent />
...
</ShowRenderedHTML>
);
}

function FirstComponent() {
return <link rel="stylesheet" href="first.css" precedence="high" />;
}

function SecondComponent() {
return <link rel="stylesheet" href="second.css" precedence="low" />;
}

```

</SandpackWithHTMLOutput>

### Deduplicated stylesheet rendering {/*deduplicated-stylesheet-rendering*/}

If you render the same stylesheet from multiple components, React will place only a single `<link>` in the document head.

<SandpackWithHTMLOutput>

```js App.js active
import ShowRenderedHTML from './ShowRenderedHTML.js';

export default function HomePage() {
return (
<ShowRenderedHTML>
<Component />
<Component />
...
</ShowRenderedHTML>
);
}

function Component() {
return <link rel="stylesheet" href="styles.css" precedence="medium" />;
}
```

</SandpackWithHTMLOutput>

### Annotating specific items within the document with links {/*annotating-specific-items-within-the-document-with-links*/}

You can use the `<link>` component with the `itemProp` prop to annotate specific items within the document with links to related resources. In this case, React will *not* place these annotations within the document `<head>` but will place them like any other React component.

```js
<section itemScope>
<h3>Annotating specific items</h3>
<link itemProp="author" href="http://example.com/" />
<p>...</p>
</section>
```
Loading

0 comments on commit 8ba8772

Please sign in to comment.