docs: generate documentation for UI components (#5849)
* added tool to generate spec files for React components * use typedoc for missing descriptions and types * improvements and fixes * improvements * added doc comments for half of the components * add custom resolver + more doc comments * added all tsdocs * general improvements * add specs to UI docs * added github action * remove unnecessary api route * Added readme for react-docs-generator * remove comment * Update packages/design-system/ui/src/components/currency-input/currency-input.tsx Co-authored-by: Kasper Fabricius Kristensen <45367945+kasperkristensen@users.noreply.github.com> * remove description of aria fields + add generate script --------- Co-authored-by: Kasper Fabricius Kristensen <45367945+kasperkristensen@users.noreply.github.com>
This commit is contained in:
Shahed Nasser
co-authored by
Kasper Fabricius Kristensen
Kasper Fabricius Kristensen
parent
edc49bfe1d
commit
245e5c9a69
@@ -3,13 +3,9 @@
|
||||
import { InformationCircleSolid } from "@medusajs/icons"
|
||||
import { Table, Tooltip } from "@medusajs/ui"
|
||||
|
||||
import {
|
||||
EnumType,
|
||||
FunctionType,
|
||||
ObjectType,
|
||||
PropData,
|
||||
PropDataMap,
|
||||
} from "@/types/props"
|
||||
import { PropData, PropDataMap, PropSpecType } from "@/types/props"
|
||||
import { useCallback, useMemo } from "react"
|
||||
import { InlineCode, MarkdownContent } from "docs-ui"
|
||||
|
||||
type PropTableProps = {
|
||||
props: PropDataMap
|
||||
@@ -26,101 +22,162 @@ const PropTable = ({ props }: PropTableProps) => {
|
||||
</Table.Row>
|
||||
</Table.Header>
|
||||
<Table.Body className="border-b-0 [&_tr:last-child]:border-b-0">
|
||||
{/* eslint-disable-next-line react/prop-types */}
|
||||
{props.map((propData, index) => (
|
||||
<Row key={index} {...propData} />
|
||||
{Object.entries(props).map(([propName, propData]) => (
|
||||
<Row key={propName} propName={propName} propData={propData} />
|
||||
))}
|
||||
</Table.Body>
|
||||
</Table>
|
||||
)
|
||||
}
|
||||
|
||||
const Row = ({ prop, type, defaultValue }: PropData) => {
|
||||
const isEnum = (t: unknown): t is EnumType => {
|
||||
return (t as EnumType).type !== undefined && (t as EnumType).type === "enum"
|
||||
}
|
||||
type RowProps = {
|
||||
propName: string
|
||||
propData: PropData
|
||||
}
|
||||
|
||||
const isObject = (t: unknown): t is ObjectType => {
|
||||
return (
|
||||
(t as ObjectType).type !== undefined &&
|
||||
(t as ObjectType).type === "object"
|
||||
)
|
||||
}
|
||||
type TypeNode = {
|
||||
text: string
|
||||
tooltipContent?: string
|
||||
canBeCopied?: boolean
|
||||
}
|
||||
|
||||
const isFunction = (t: unknown): t is FunctionType => {
|
||||
return (
|
||||
(t as FunctionType).type !== undefined &&
|
||||
(t as FunctionType).type === "function"
|
||||
)
|
||||
const Row = ({
|
||||
propName,
|
||||
propData: { tsType: tsType, defaultValue, description },
|
||||
}: RowProps) => {
|
||||
const normalizeRaw = (str: string): string => {
|
||||
return str.replace("\\|", "|")
|
||||
}
|
||||
|
||||
const defaultValueRenderer = (
|
||||
v: string | number | boolean | null | undefined
|
||||
) => {
|
||||
if (v === undefined) {
|
||||
return "-"
|
||||
const getTypeRaw = useCallback((type: PropSpecType): string => {
|
||||
let raw = "raw" in type ? type.raw || type.name : type.name
|
||||
if ("type" in type) {
|
||||
if (type.type === "object") {
|
||||
raw = `{\n ${type.signature.properties
|
||||
.map((property) => `${property.key}: ${property.value.name}`)
|
||||
.join("\n ")}\n}`
|
||||
} else {
|
||||
raw = type.raw
|
||||
}
|
||||
} else if (type.name === "Array" && "elements" in type) {
|
||||
raw = type.elements.map((element) => getTypeRaw(element)).join(" | ")
|
||||
}
|
||||
|
||||
if (typeof v === "boolean") {
|
||||
return v ? "true" : "false"
|
||||
return normalizeRaw(raw)
|
||||
}, [])
|
||||
const getTypeText = useCallback((type: PropSpecType): string => {
|
||||
if (type?.name === "signature" && "type" in type) {
|
||||
return type.type
|
||||
} else if (type?.name === "Array" && type.raw) {
|
||||
return normalizeRaw(type.raw) || "array"
|
||||
}
|
||||
|
||||
if (v === null) {
|
||||
return "null"
|
||||
return type.name || ""
|
||||
}, [])
|
||||
const getTypeTooltipContent = useCallback(
|
||||
(type: PropSpecType): string | undefined => {
|
||||
if (type?.name === "signature" && "type" in type) {
|
||||
return getTypeRaw(type)
|
||||
} else if (type?.name === "Array" && type.raw) {
|
||||
return getTypeRaw(type)
|
||||
}
|
||||
|
||||
return undefined
|
||||
},
|
||||
[getTypeRaw]
|
||||
)
|
||||
|
||||
const typeNodes = useMemo((): TypeNode[] => {
|
||||
const typeNodes: TypeNode[] = []
|
||||
if (tsType?.name === "union" && "elements" in tsType) {
|
||||
tsType.elements.forEach((element) => {
|
||||
if (
|
||||
("elements" in element && element.elements.length) ||
|
||||
"signature" in element
|
||||
) {
|
||||
const elementTypeText = getTypeText(element)
|
||||
const elementTooltipContent = getTypeTooltipContent(element)
|
||||
typeNodes.push({
|
||||
text: elementTypeText,
|
||||
tooltipContent:
|
||||
elementTypeText !== elementTooltipContent
|
||||
? elementTooltipContent
|
||||
: undefined,
|
||||
})
|
||||
} else if ("value" in element) {
|
||||
typeNodes.push({
|
||||
text: element.value,
|
||||
canBeCopied: true,
|
||||
})
|
||||
} else {
|
||||
typeNodes.push({
|
||||
text: element.name,
|
||||
})
|
||||
}
|
||||
})
|
||||
} else if (tsType) {
|
||||
typeNodes.push({
|
||||
text: getTypeText(tsType),
|
||||
tooltipContent: getTypeTooltipContent(tsType),
|
||||
})
|
||||
}
|
||||
|
||||
if (typeof v === "string") {
|
||||
return `"${v}"`
|
||||
}
|
||||
return typeNodes
|
||||
}, [tsType, getTypeText, getTypeTooltipContent])
|
||||
|
||||
return v
|
||||
}
|
||||
|
||||
const isComplexType = isEnum(type) || isObject(type) || isFunction(type)
|
||||
const defaultVal: string | undefined = defaultValue?.value as string
|
||||
|
||||
return (
|
||||
<Table.Row className="code-body">
|
||||
<Table.Cell>{prop}</Table.Cell>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
{!isComplexType && type.toString()}
|
||||
{isEnum(type) && (
|
||||
<Tooltip
|
||||
content={type.values.map((v) => `"${v}"`).join(" | ")}
|
||||
className="font-mono"
|
||||
>
|
||||
<div className="flex items-center gap-x-1">
|
||||
<span>enum</span>
|
||||
<div className="flex items-center gap-x-1">
|
||||
<InlineCode>{propName}</InlineCode>
|
||||
{description && (
|
||||
<Tooltip
|
||||
content={
|
||||
<MarkdownContent
|
||||
allowedElements={["a", "code"]}
|
||||
unwrapDisallowed={true}
|
||||
>
|
||||
{description}
|
||||
</MarkdownContent>
|
||||
}
|
||||
>
|
||||
<InformationCircleSolid className="text-medusa-fg-subtle" />
|
||||
</Tooltip>
|
||||
)}
|
||||
</div>
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
<div className="flex items-center flex-wrap gap-1 py-1">
|
||||
{typeNodes.map((typeNode, index) => (
|
||||
<div key={index} className="flex items-center gap-x-1">
|
||||
{index > 0 && <span>|</span>}
|
||||
{typeNode.tooltipContent && (
|
||||
<Tooltip
|
||||
content={<pre>{typeNode.tooltipContent}</pre>}
|
||||
className="font-mono !max-w-none"
|
||||
>
|
||||
<div className="flex items-center gap-x-1">
|
||||
<code>{typeNode.text}</code>
|
||||
<InformationCircleSolid className="text-medusa-fg-subtle" />
|
||||
</div>
|
||||
</Tooltip>
|
||||
)}
|
||||
{!typeNode.tooltipContent && (
|
||||
<>
|
||||
{typeNode.canBeCopied && (
|
||||
<InlineCode>{typeNode.text}</InlineCode>
|
||||
)}
|
||||
{!typeNode.canBeCopied && <code>{typeNode.text}</code>}
|
||||
</>
|
||||
)}
|
||||
</div>
|
||||
</Tooltip>
|
||||
)}
|
||||
{isObject(type) && (
|
||||
<Tooltip
|
||||
content={<pre>{type.shape}</pre>}
|
||||
className="font-mono"
|
||||
maxWidth={500}
|
||||
>
|
||||
<div className="flex items-center gap-x-1">
|
||||
<span>{type.name}</span>
|
||||
<InformationCircleSolid className="text-medusa-fg-subtle" />
|
||||
</div>
|
||||
</Tooltip>
|
||||
)}
|
||||
{isFunction(type) && (
|
||||
<Tooltip
|
||||
content={<pre>{type.signature}</pre>}
|
||||
className="font-mono"
|
||||
maxWidth={500}
|
||||
>
|
||||
<div className="flex items-center gap-x-1">
|
||||
<span>function</span>
|
||||
<InformationCircleSolid className="text-medusa-fg-subtle" />
|
||||
</div>
|
||||
</Tooltip>
|
||||
)}
|
||||
))}
|
||||
</div>
|
||||
</Table.Cell>
|
||||
<Table.Cell className="text-right">
|
||||
{defaultValueRenderer(defaultValue)}
|
||||
{defaultVal && <InlineCode>{defaultVal}</InlineCode>}
|
||||
{!defaultVal && " - "}
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
)
|
||||
|
||||
Reference in New Issue
Block a user