/*
* 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}) => (
{type.description && (
{type.description}
)}
{type.type === 'interface' && type.extends?.length > 0 && (
Extends:{' '}
)}
{type.type === 'interface' || type.type === 'alias' || type.type === 'component' ? (
) : (
)}
));
}
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 && (
|
Name
|
{!hideType && (
Type
|
)}
{showDefault && (
Default
|
)}
Description
|
{properties.map((prop, index) => (
{prop.name}
{!prop.optional && showRequired ? (
) : null}
|
{!hideType && (
|
)}
{showDefault && (
{prop.default ? (
) : (
'—'
)}
|
)}
{renderHTMLfromMarkdown(prop.description, {forceInline: false})}
|
))}
)}
{methods.length > 0 && properties.length > 0 && (
Methods
)}
{methods.length > 0 && (
|
Method
|
Description
|
{methods.map((prop, index) => (
{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 (
{'${'}
{'}'}
);
})}
{'`'}
>
);
}