30:T729,The `render` function takes a function that returns JSX and renders said JSX to a `

` that it returns using `react-dom`. The returned element will change when you alter the source code of the passed function (meaning that the component will remain the same if only the variables you reference change). You can safely use Hooks in this function. Your render function is passed an object containing three keys: `getValue`, `setValue`, and `useSetter`. These allow you to take advantage of Observable’s `viewof` functionality: * `getValue()` returns the current value of the view. * setValue(*newValue*) will immediately update the view’s value. * useSetter(*setter*[, *deps*]) will set the view’s value to the result of `setter(currentValue)` whenever one of the `deps` change. It’s very similar to `useEffect`. * useSetter(*value*) will set the view’s value to `value` whenever the component is rendered. Note that this won’t work if you do `useSetter(ref.current)` because changing the `current` property of the ref won’t trigger a re-render. For some more advanced use cases (usually where you call `render` in a helper function), you can pass a second parameter to `render` to help it cache properly. It can take one of two types of value: * a key (string) which will be added to your function’s code as a cache key. This can be used to keep a lightweight API by passing the string value of a renderer function your code will be called with, although I’m sure there are other things that it could be used for. * an HTML element that was previously returned from `render()`. If your helper is expected to be used at the top level of a cell, tell your users to pass `this` into your helper — it’s the currently rendered HTML element which can be passed to `render`.31:T455,// render a variable with a link to its docs. See below for how it’s used. __SECRET_DOC = { const { Inspector } = await require('@observablehq/inspector'); const doc = (url, name, value) => { const node = DOM.element('span'); const inspector = new Inspector(node); inspector.fulfilled(value, name); const nameEl = node.querySelector('.observablehq--cellname'); const clobberName = () => (nameEl.innerHTML = `${name} = `); clobberName(); new MutationObserver(clobberName).observe(nameEl.parentNode, { childList: true, attributes: true }); node.value = value; return node; }; return Object.assign(doc, { react: (name, id = 'react' + name.toLowerCase()) => doc('https://reactjs.org/docs/react-api.html#' + id, name, React[name]), hook: name => doc( 'https://reactjs.org/docs/hooks-reference.html#' + name.toLowerCase(), name, React[name] ), dom: (name, id = name.toLowerCase()) => doc('https://reactjs.org/docs/react-dom.html#' + id, name, ReactDOM[name]) }); }32:T40e,// Used to allow people to switch between variants of this notebook. __SECRET_SWITCHER = current => { const link = (name, owner = 'j-f1') => { const slug = `@${owner}/${name}`; return slug === current ? html`${DOM.text(slug)} (this notebook)` : html`

${DOM.text(
          slug
        )}`;
  };
  return md`
${
  current === '@j-f1/react'
    ? ''
    : `
You can use it in exactly the same ways as the original notebook, and you should be able to simply swap

~~~js
import { ... } from '@j-f1/react'
~~~

with

~~~js
import { ... } from '${current}'
~~~
`
}
Other notebooks in this series:
- ${link('react')}, which always uses the latest stable version of React
- ${link('react-16')}, which always uses the latest stable version of
  React 16.x. (You can also do this by [manually specifying the React version](#versionRangeDoc))
- ${link('react-experimental')}, which always uses the latest **experimental**
  version of React.
  `;
}33:[]
2e:{"title":"React 17","cells":[{"id":0,"value":"# React 17\n\n...in Observable!","pinned":false,"hidden":false,"mode":"md"},{"id":991,"value":"// Adapted from https://observablehq.com/@bryangingechen/toc\nGenerators.observe(notify => {\n  let headings = [];\n\n  function observed() {\n    const h = Array.from(document.querySelectorAll('h2,h3,h4,h5,h6'));\n    if (h.length !== headings.length || h.some((h, i) => headings[i] !== h)) {\n      notify(html`Table of Contents

${Array.from(headings = h, h => {\n        const level = parseInt(h.tagName.slice(1)) - 1;\n        return Object.assign(\n          html`${level > 1 ? ''.repeat(level-1) + '' : ''}${DOM.text(h.textContent)}`,\n          {onclick: e => (e.preventDefault(), h.scrollIntoView())}\n        );\n      })}`);\n    }\n  }\n\n  const observer = new MutationObserver(observed);\n  observer.observe(document.body, {childList: true, subtree: true});\n  observed();\n  return () => observer.disconnect();\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":199,"value":"---\n\n## API & Docs\n\nFirst, a note. If you have any ideas for how to improve the notebook, edit this page, click the “⋯” menu at the top, and click “Suggest…” to send me a suggestion with your comments or proposed changes.","pinned":false,"hidden":false,"mode":"md"},{"id":210,"value":"$30","pinned":false,"hidden":false,"mode":"md"},{"id":107,"value":"render = (render, keyOrElement) =>\n  __SECRET_INTERNALS('elements', String(render), keyOrElement, {\n    init: state => ({\n      renderer: () => state.render(state.public),\n      id: __SECRET_CREATE_ID(),\n      element: DOM.element('div'),\n      public: {\n        useSetter: (setterOrValue, deps) =>\n          typeof setterOrValue === 'function'\n            ? useEffect(\n                () =>\n                  state.public.setValue(setterOrValue(state.public.getValue())),\n                deps\n              )\n            : useEffect(() => state.public.setValue(setterOrValue), [\n                setterOrValue\n              ]),\n        getValue: () => state.element.value,\n        setValue: value => {\n          state.element.value = value;\n          state.element.dispatchEvent(new CustomEvent('input'));\n        }\n      }\n    }),\n    update: { render },\n    effect: state =>\n      ReactDOM.render(createElement(state.renderer), state.element),\n    return: state => state.element\n  })","pinned":true,"hidden":false,"mode":"ojs"},{"id":208,"value":"The `component` function is like `render` except that it passes props to the function instead of the metadata object and returns a function component instead of an element. Note that this notebook does not provide you a way to create class components that depend on other Observable values while still keeping their state, but you should be able to render class components by referencing them in a function component like you do in vanilla React.\n\nSimilarly to `render`, you can pass a key or previous result in for similar advanced use cases. (Except with `component`, the `this` value should be a component fucntion previously returned)","pinned":false,"hidden":false,"mode":"md"},{"id":159,"value":"component = (render, name, keyOrPrevious) =>\n  __SECRET_INTERNALS('components', String(render), keyOrPrevious, {\n    init: (state, funcFor) => ({\n      component: __SECRET_SET_DISPLAYNAME(funcFor('render'), name)\n    }),\n    update: { render },\n    return: state => state.component\n  })","pinned":true,"hidden":false,"mode":"ojs"},{"id":1192,"value":"$${3}","pinned":true,"hidden":false,"mode":"md"},{"id":592,"value":"The `jsx` function provides a copy of [`htm`](https://github.com/developit/htm) that’s already hooked up to React. It’s called `jsx` instead of `html` so you can import it and still use the `html` tag. Note that this isn’t actually JSX syntax, there are a few differences:\n\n- components that start with a capital letter have to be referred to as `<${\"${Foo}\"} />` rather than ``\n- props that are passed a non-string need to have the braces prefixed with a `$`: ``\n- spread props have to have the `...` outside the `${\"${}\"}` — ``\n- instead of fragments (`<>`), you can just pass multiple elements: ``jsx`` ``\n- quotes are optional for string props — ``\n- components can be closed without duplicating the name — `<${\"${Foo}\"}>...`","pinned":false,"hidden":false,"mode":"md"},{"id":88,"value":"jsx = {\n  const jsx = htm.bind(createElement);\n  return (...args) => {\n    try {\n      return jsx(...args);\n    } catch (e) {\n      // throw a clearer error\n      let stack = e.stack;\n      if (!stack.includes(e.message)) {\n        stack = `${e.constructor.name}: ${e.message}\\n${stack}`;\n      }\n      throw new SyntaxError('JSX syntax error\\n' + stack);\n    }\n  };\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":597,"value":"### Less common APIs","pinned":false,"hidden":false,"mode":"md"},{"id":261,"value":"The `memo` function is a version of `component()` that wraps your component in `React.memo`.\nThe `keyOrElement` parameter is fully optional and identical to the one in `render`.","pinned":false,"hidden":false,"mode":"md"},{"id":253,"value":"memo = (render, arePropsEqual, name, keyOrElement) =>\n  __SECRET_INTERNALS(\n    'memos',\n    JSON.stringify([String(render), String(arePropsEqual)]),\n    keyOrElement,\n    {\n      init: (state, funcFor) => ({\n        component: React.memo(\n          __SECRET_SET_DISPLAYNAME(funcFor('render'), name),\n          funcFor('arePropsEqual')\n        )\n      }),\n      update: { render, arePropsEqual },\n      return: state => state.component\n    }\n  )","pinned":true,"hidden":false,"mode":"ojs"},{"id":268,"value":"The `forwardRef` function is a version of `component()` that wraps your component in `React.forwardRef`.\nThe `keyOrElement` parameter fully optional and is identical to the one in `render`.","pinned":false,"hidden":false,"mode":"md"},{"id":270,"value":"forwardRef = (render, name, keyOrElement) =>\n  __SECRET_INTERNALS('forwardRefs', String(render), keyOrElement, {\n    init: (state, funcFor) => ({\n      component: React.forwardRef(\n        __SECRET_SET_DISPLAYNAME(funcFor('render'), name)\n      )\n    }),\n    update: { render },\n    return: state => state.component\n  })","pinned":true,"hidden":false,"mode":"ojs"},{"id":27,"value":"---\n## Dependencies\n\nThis is the [`htm`](https://npm.im/htm) library.","pinned":false,"hidden":false,"mode":"md"},{"id":90,"value":"htm = require('htm@2.2.1/dist/htm.umd.js')","pinned":true,"hidden":false,"mode":"ojs"},{"id":222,"value":"versionRangeDoc = md`\nYou can pass a different \\`versionRange\\` using Observable’s \\`import\\`…\\`with\\` syntax to load a different React version.\nYou can also pass an object with \\`react\\` and \\`dom\\` keys to load different versions of React and React DOM.\n\nYou should be fine without specifying a version number since the React team is reluctant to make breaking changes, but it’s possible your code will break in the future if you don’t.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":11,"value":"versionRange = \"17.0.1\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":230,"value":"Set this to `false` using Observable’s `import`…`with` syntax for better performance but less debugging information. Checkout [React’s docs](https://reactjs.org/docs/optimizing-performance.html#use-the-production-build) for some additional explanation.","pinned":false,"hidden":false,"mode":"md"},{"id":176,"value":"dev = true","pinned":false,"hidden":false,"mode":"ojs"},{"id":581,"value":"These are the React and React DOM imports. If you need to access APIs that haven’t been re-exported below, feel free to import these variables, like I do in the [Suspense-enabled version of this notebook](https://observablehq.com/@j-f1/react-experimental).","pinned":false,"hidden":false,"mode":"md"},{"id":22,"value":"React = import(\n  \"https://cdn.skypack.dev/pin/react@v17.0.1-yH0aYV1FOvoIPeKBbHxg/mode=imports,min/optimized/react.js\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":25,"value":"ReactDOM = import(\n  \"https://cdn.skypack.dev/pin/react-dom@v17.0.1-oZ1BXZ5opQ1DbTh7nu9r/mode=imports/optimized/react-dom.js\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":220,"value":"---\n## Private APIs\nThese are private APIs used to make the whole shebang work. As a user of this notebook, you don’t need to worry about them. Additionally, they can change at any time, so if you’re going to directly use them make sure to pin the notebook version.","pinned":false,"hidden":false,"mode":"md"},{"id":113,"value":"// Cache components & rendered elements\n__SECRET_INTERNALS = function cache(\n  type,\n  key,\n  ctx,\n  { init, update, effect, return: returnValue }\n) {\n  const fullKey = typeof ctx === 'string' ? key + '\\n' + ctx : key;\n  const prevResult =\n    typeof ctx === 'object' || typeof ctx === 'function' ? ctx : null;\n\n  const updateAndReturn = state => {\n    Object.assign(state, update);\n    if (effect) effect(state);\n    const ret = returnValue(state);\n    try {\n      ret[__SECRET_STATE] = state;\n    } catch {}\n    return ret;\n  };\n\n  if (prevResult) {\n    return updateAndReturn(prevResult[__SECRET_STATE]);\n  }\n\n  if (!cache[type]) cache[type] = Object.create(null);\n  if (!cache[type][fullKey]) {\n    const state = Object.create(null);\n    Object.assign(\n      state,\n      init(state, subkey => (...args) => state[subkey](...args))\n    );\n    cache[type][fullKey] = state;\n  }\n  return updateAndReturn(cache[type][fullKey]);\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":521,"value":"// create a random alphanumeric ID\n__SECRET_CREATE_ID = () =>\n  Number(\n    Math.random()\n      .toString()\n      .slice(2)\n  ).toString(36)","pinned":false,"hidden":false,"mode":"ojs"},{"id":840,"value":"// set the displayName of a function\n__SECRET_SET_DISPLAYNAME = (f, name) => {\n  f.displayName = name;\n  return f;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":638,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":806,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":9,"value":"// this makes sure that react-dom references the proper copy of React instead of having it be imported twice.\n__SECRET_REQUIRE = require.alias({\n  react: `https://unpkg.com/react@${versionRange.react ||\n    versionRange}/umd/react.${dev ? 'development' : 'production.min'}.js`,\n  'react-dom': `https://unpkg.com/react-dom@${versionRange.dom ||\n    versionRange}/umd/react-dom.${dev ? 'development' : 'production.min'}.js`\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":1010,"value":"__SECRET_STATE = Symbol('rendered state')","pinned":false,"hidden":false,"mode":"ojs"},{"id":29,"value":"---\n## React re-exports\n\nThese allow you to import various helpful functions directly from this notebook instead of having to prefix them with `React.` when using them.\n\n### Creating React Elements","pinned":false,"hidden":false,"mode":"md"},{"id":550,"value":"viewof createElement = __SECRET_DOC.react('createElement', 'createlement')","pinned":false,"hidden":false,"mode":"ojs"},{"id":699,"value":"viewof createFactory = __SECRET_DOC.react('createFactory', 'creatfactory')","pinned":false,"hidden":false,"mode":"ojs"},{"id":689,"value":"### Transforming Elements","pinned":false,"hidden":false,"mode":"md"},{"id":73,"value":"viewof cloneElement = __SECRET_DOC.react('cloneElement', 'cloneelement')","pinned":false,"hidden":false,"mode":"ojs"},{"id":693,"value":"viewof isValidElement = __SECRET_DOC.react('isValidElement', 'isvalidelement')","pinned":false,"hidden":false,"mode":"ojs"},{"id":31,"value":"viewof Children = __SECRET_DOC.react('Children')","pinned":false,"hidden":false,"mode":"ojs"},{"id":703,"value":"### Fragments","pinned":false,"hidden":false,"mode":"md"},{"id":64,"value":"viewof Fragment = __SECRET_DOC.react('Fragment')","pinned":false,"hidden":false,"mode":"ojs"},{"id":696,"value":"### Refs","pinned":false,"hidden":false,"mode":"md"},{"id":33,"value":"viewof createRef = __SECRET_DOC.react('createRef')","pinned":false,"hidden":false,"mode":"ojs"},{"id":707,"value":"[forwardRef](https://reactjs.org/docs/react-api.html#reactforwardref) = [see [above](#forwardRef)`]`\n\n### Suspense\n\n*See my [separate notebook](https://observablehq.com/@j-f1/react-concurrent-mode) for full Suspense/Concurrent Mode support.*","pinned":false,"hidden":false,"mode":"md"},{"id":39,"value":"viewof lazy = __SECRET_DOC.react('lazy')","pinned":false,"hidden":false,"mode":"ojs"},{"id":69,"value":"viewof Suspense = __SECRET_DOC.react('Suspense')","pinned":false,"hidden":false,"mode":"ojs"},{"id":67,"value":"viewof StrictMode = __SECRET_DOC.react('StrictMode')","pinned":false,"hidden":false,"mode":"ojs"},{"id":721,"value":"### Context","pinned":false,"hidden":false,"mode":"md"},{"id":35,"value":"viewof createContext = __SECRET_DOC(\n  'https://reactjs.org/docs/context.html#reactcreatecontext',\n  'createContext',\n  React.createContext\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":45,"value":"### Hooks\n#### Basic Hooks","pinned":false,"hidden":false,"mode":"md"},{"id":61,"value":"viewof useState = __SECRET_DOC.hook('useState')","pinned":false,"hidden":false,"mode":"ojs"},{"id":49,"value":"viewof useEffect = __SECRET_DOC.hook('useEffect')","pinned":false,"hidden":false,"mode":"ojs"},{"id":47,"value":"viewof useContext = __SECRET_DOC.hook('useContext')","pinned":false,"hidden":false,"mode":"ojs"},{"id":756,"value":"#### Additional Hooks","pinned":false,"hidden":false,"mode":"md"},{"id":57,"value":"viewof useReducer = __SECRET_DOC.hook('useReducer')","pinned":false,"hidden":false,"mode":"ojs"},{"id":43,"value":"viewof useCallback = __SECRET_DOC.hook('useCallback')","pinned":false,"hidden":false,"mode":"ojs"},{"id":55,"value":"viewof useMemo = __SECRET_DOC.hook('useMemo')","pinned":false,"hidden":false,"mode":"ojs"},{"id":59,"value":"viewof useRef = __SECRET_DOC.hook('useRef')","pinned":false,"hidden":false,"mode":"ojs"},{"id":51,"value":"viewof useImperativeHandle = __SECRET_DOC.hook('useImperativeHandle')","pinned":false,"hidden":false,"mode":"ojs"},{"id":53,"value":"viewof useLayoutEffect = __SECRET_DOC.hook('useLayoutEffect')","pinned":false,"hidden":false,"mode":"ojs"},{"id":601,"value":"viewof useDebugValue = __SECRET_DOC.hook('useDebugValue')","pinned":false,"hidden":false,"mode":"ojs"},{"id":83,"value":"### React DOM\n\n**Note**: the regular `ReactDOM.render` function isn’t exported since the provided `render` function above is better for use with Observable.","pinned":false,"hidden":false,"mode":"md"},{"id":85,"value":"viewof createPortal = __SECRET_DOC.dom('createPortal')","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W33","stdlib":"1","titling":"auto"}