/* * Copyright 2020 Adobe. All rights reserved. * This file is licensed to you under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. You may obtain a copy * of the License at http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software distributed under * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS * OF ANY KIND, either express or implied. See the License for the specific language * governing permissions and limitations under the License. */ import Asterisk from '@spectrum-icons/workflow/Asterisk'; import clsx from 'clsx'; import {getAnchorProps, getUsedLinks} from './utils'; import {getDoc} from 'globals-docs'; import linkStyle from '@adobe/spectrum-css-temp/components/link/vars.css'; import Lowlight from 'react-lowlight'; import Markdown from 'markdown-to-jsx'; import React, {useContext} from 'react'; import styles from './docs.css'; import tableStyles from '@adobe/spectrum-css-temp/components/table/vars.css'; import typographyStyles from '@adobe/spectrum-css-temp/components/typography/vars.css'; const DOC_LINKS = { 'React.Component': 'https://reactjs.org/docs/react-component.html', ReactElement: 'https://reactjs.org/docs/rendering-elements.html', ReactNode: 'https://reactjs.org/docs/rendering-elements.html', Generator: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator', Iterator: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols', Iterable: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols', DataTransfer: 'https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer', CSSProperties: 'https://reactjs.org/docs/dom-elements.html#style', DOMAttributes: 'https://reactjs.org/docs/dom-elements.html#all-supported-html-attributes', FocusableElement: 'https://developer.mozilla.org/en-US/docs/Web/API/Element', 'Intl.NumberFormat': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat', 'Intl.NumberFormatOptions': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat', 'Intl.ListFormatOptions': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat', 'Intl.DateTimeFormat': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat', 'Intl.DateTimeFormatOptions': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat', 'Intl.Collator': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator', 'Intl.CollatorOptions': 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator', AbortSignal: 'https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal', Key: 'https://reactjs.org/docs/lists-and-keys.html', HTMLAttributes: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes', InputHTMLAttributes: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes', TextareaHTMLAttributes: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea#attributes', LabelHTMLAttributes: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label#attributes', OutputHTMLAttributes: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/output#attributes' }; export const TypeContext = React.createContext(); export const LinkContext = React.createContext(); export function Type({type}) { let links = useContext(TypeContext); if (!type) { return null; } switch (type.type) { case 'any': case 'null': case 'undefined': case 'void': case 'unknown': case 'never': return ; case 'this': return ; case 'symbol': return ; case 'identifier': return ; case 'string': if (type.value) { return ; } return ; case 'number': if (type.value) { return ; } return ; case 'boolean': if (type.value) { return ; } return ; case 'union': return ; case 'intersection': return ; case 'application': return ; case 'typeOperator': return ; case 'function': return ; case 'parameter': return ; case 'link': return ; case 'interface': return ; case 'object': if (type.properties) { return ; } return ; case 'alias': return ( ); case 'array': return ; case 'tuple': return ; case 'typeParameter': return ; case 'component': { let props = type.props; if (props.type === 'application') { props = props.base; } if (props.type === 'link') { props = links[props.id]; } return ; } case 'conditional': return ; case 'indexedAccess': return ; case 'keyof': return ; case 'template': return ; default: console.log('no render component for TYPE', type); return null; } } function TypeOperator({operator, value}) { return ( {operator} ); } function IndexedAccess({objectType, indexType}) { return ( [] ); } function StringLiteral({value}) { return {`'${value.replace(/'/, "\\'")}'`}; } function NumberLiteral({value}) { return {'' + value}; } function BooleanLiteral({value}) { return {'' + value}; } function Symbol() { return symbol; } function Keyof({keyof}) { return ( ); } function Keyword({type}) { let link = getDoc(type); if (link) { return ( {type} ); } return {type}; } function Identifier({name}) { let link = getDoc(name) || DOC_LINKS[name]; if (link) { return ( {name} ); } return {name}; } const IndentContext = React.createContext({small: '', large: ''}); export function Indent({params, open, close, children, alwaysIndent}) { let {small, large} = useContext(IndentContext); if (params.length === 0) { open = {open}; close = {close}; } else if (params.length > 2 || alwaysIndent) { // Always indent. open = {open.trimEnd() + '\n' + large + ' '}; close = {'\n' + large + close.trimStart()}; large += ' '; small += ' '; } else { // Indent on small screens. Don't indent on large screens. open = ( <> {open.trimEnd() + '\n' + small + ' '} {open} ); close = ( <> {'\n' + small + close.trimStart()} {close} ); small += ' '; } return ( {open} {children} {close} ); } export function JoinList({elements, joiner, minIndent = 2, newlineBefore, neverIndent}) { let {small, large, alwaysIndent} = useContext(IndentContext); let contents; if (neverIndent || (elements.length <= minIndent && small.length === 0)) { contents = joiner; } else if (elements.length > minIndent || alwaysIndent) { // Always indent. if (newlineBefore) { large += ' '; small += ' '; } contents = newlineBefore ? '\n' + large + joiner.trimStart() : joiner.trimEnd() + '\n' + large; } else { // Indent on small screens. Don't indent on large screens. if (newlineBefore) { small += ' '; } let indented = newlineBefore ? '\n' + small + joiner.trimStart() : joiner.trimEnd() + '\n' + small; contents = ( <> {indented} {joiner} ); } return elements .filter(Boolean) .reduce( (acc, v, i) => [ ...acc, {contents} , ], [] ) .slice(1); } function UnionType({elements}) { return ; } function IntersectionType({types}) { return ; } function TypeApplication({base, typeParameters}) { return ( <> ); } export function TypeParameters({typeParameters}) { if (typeParameters.length === 0) { return null; } return ( <> < > ); } function TypeParameter({name, constraint, default: defaultType}) { return ( <> {name} {constraint && ( <> {' '} extends )} {defaultType && ( <> {' = '} )} ); } function FunctionType({name, parameters, return: returnType, typeParameters, rest}) { return ( <> {name && {name}} {name ? ': ' : ' => '} ); } function Parameter({name, value, default: defaultValue, optional, rest}) { return ( <> {rest && ...} {name} {optional && ?} {value && ( <> : )} {defaultValue && ( <> = )} ); } export function LinkProvider({children}) { let links = new Map(); return ( {children} ); } export function LinkRenderer() { let links = useContext(LinkContext); return [...links.values()].map(({type, links}) => ( )); } export function LinkType({id}) { let links = useContext(TypeContext) || {}; let registered = useContext(LinkContext); let value = links[id]; if (!value) { return null; } if (DOC_LINKS[value.name]) { return ; } registered.set(id, {type: value, links}); let used = getUsedLinks(value, links); for (let id in used) { registered.set(id, {type: used[id], links}); } return ( {value.name} ); } function SpectrumLink({href, children, title}) { return ( {children} ); } export function renderHTMLfromMarkdown(description, opts) { if (description) { const options = { forceInline: true, overrides: {a: {component: SpectrumLink}}, disableParsingRawHTML: true, ...opts }; return {description}; } return ''; } export function InterfaceType({ description, properties: props, typeParameters, showRequired, showDefault, isComponent, name, hideType, hideProperties, hideMethods }) { let properties = hideProperties ? [] : Object.values(props).filter( prop => prop.type === 'property' && prop.access !== 'private' && prop.access !== 'protected' ); let methods = hideMethods ? [] : Object.values(props).filter( prop => prop.type === 'method' && prop.access !== 'private' && prop.access !== 'protected' ); // Default to showing required indicators if some properties are optional but not all. // oxlint-disable-next-line react/react-compiler showRequired = showRequired || (!properties.every(p => p.optional) && !properties.every(p => !p.optional)); // Show default values by default if any of the properties have one defined. // oxlint-disable-next-line react/react-compiler showDefault = showDefault || properties.some(p => !!p.default); // Sort props so required ones are shown first. if (showRequired) { properties.sort((a, b) => { if (!a.optional && b.optional) { return -1; } if (a.optional && !b.optional) { return 1; } return 0; }); } return ( <> {methods.length > 0 && properties.length > 0 && (

Properties

)} {properties.length > 0 && ( {!hideType && ( )} {showDefault && ( )} {properties.map((prop, index) => ( {!hideType && ( )} {showDefault && ( )} ))}
Name Type Default Description
{prop.name} {!prop.optional && showRequired ? ( ) : null} {prop.default ? ( ) : ( '—' )} {renderHTMLfromMarkdown(prop.description, {forceInline: false})}
)} {methods.length > 0 && properties.length > 0 && (

Methods

)} {methods.length > 0 && ( {methods.map((prop, index) => ( ))}
Method Description
{prop.static && static } {prop.abstract && abstract } {prop.name} {': '} {renderHTMLfromMarkdown(prop.description, {forceInline: false})}
)} ); } function ObjectType({properties, exact}) { const startObject = {exact ? '{|' : '{'}; const endObject = {exact ? '|}' : '}'}; return ( <> {startObject} {Object.values(properties).map((property, i, arr) => { let token = 'hljs-attr'; let k = property.name; // https://mathiasbynens.be/notes/javascript-identifiers-es6 if (!/^[$_\p{ID_Start}][$_\u{200C}\u{200D}\p{ID_Continue}]+$/u.test(property.key)) { k = `'${property.name}'`; token = 'hljs-string'; } let optional = property.optional; let value = property.value; let punc = optional ? '?: ' : ': '; return (
{property.indexType && [} {k} {property.indexType && {': '}} {property.indexType && } {property.indexType && ]} {punc} {i < arr.length - 1 ? ',' : ''}
); })} {endObject} ); } function ArrayType({elementType}) { return ( <> [] ); } function TupleType({elements}) { return ( <> ); } function ConditionalType({checkType, extendsType, trueType, falseType}) { return ( <> extends{' '} {' ? '} {' :' + (falseType.type === 'conditional' ? '\n' : ' ')} ); } function TemplateLiteral({elements}) { return ( <> {'`'} {elements.map((element, i) => { if (element.type === 'string' && element.value) { return ( {element.value} ); } return ( {'${'} {'}'} ); })} {'`'} ); }