|
| 1 | +/* |
| 2 | + * Generates `src/generated/ui-api.json` for the UI Library docs. |
| 3 | + * |
| 4 | + * Props are extracted with TypeDoc (source of truth: the component prop types |
| 5 | + * in `@workflowbuilder/ui`); CSS variables are extracted from each component's |
| 6 | + * stylesheets. The per-component docs pages render this JSON, so the Props and |
| 7 | + * CSS variables tables never drift from source. Run by `pnpm generate:ui-api` |
| 8 | + * and as a prebuild step in `dev` / `build`. |
| 9 | + */ |
| 10 | +import { execFile } from 'node:child_process'; |
| 11 | +import { mkdir, readFile, writeFile } from 'node:fs/promises'; |
| 12 | +import { globSync, readFileSync } from 'node:fs'; |
| 13 | +import path from 'node:path'; |
| 14 | +import { fileURLToPath } from 'node:url'; |
| 15 | +import { promisify } from 'node:util'; |
| 16 | + |
| 17 | +const here = path.dirname(fileURLToPath(import.meta.url)); |
| 18 | +const docsRoot = path.resolve(here, '..'); |
| 19 | +const repoRoot = path.resolve(docsRoot, '../..'); |
| 20 | +const uiSrc = path.resolve(repoRoot, 'packages/ui/src'); |
| 21 | +const outFile = path.resolve(docsRoot, 'src/generated/ui-api.json'); |
| 22 | +const tdJson = path.resolve(docsRoot, 'node_modules/.cache/ui-typedoc.json'); |
| 23 | + |
| 24 | +// slug -> { name, propsType, dir }. `propsType` is the exported prop type the |
| 25 | +// component accepts; `dir` is the component folder under packages/ui/src/components. |
| 26 | +const COMPONENTS = [ |
| 27 | + { slug: 'accordion', name: 'Accordion', propsType: 'AccordionProps', dir: 'accordion' }, |
| 28 | + { slug: 'avatar', name: 'Avatar', propsType: 'AvatarProps', dir: 'avatar' }, |
| 29 | + { slug: 'button', name: 'Button', propsType: 'BaseRegularButtonProps', dir: 'button' }, |
| 30 | + { slug: 'checkbox', name: 'Checkbox', propsType: 'CheckboxProps', dir: 'checkbox' }, |
| 31 | + { slug: 'date-picker', name: 'DatePicker', propsType: 'DatePickerProps', dir: 'date-picker' }, |
| 32 | + { slug: 'input', name: 'Input', propsType: 'InputProps', dir: 'input' }, |
| 33 | + { slug: 'menu', name: 'Menu', propsType: 'MenuProps', dir: 'menu' }, |
| 34 | + { slug: 'modal', name: 'Modal', propsType: 'ModalProps', dir: 'modal' }, |
| 35 | + { slug: 'nav-button', name: 'NavButton', propsType: 'NavBaseButtonProps', dir: 'button/nav-button' }, |
| 36 | + { slug: 'radio', name: 'Radio', propsType: 'RadioProps', dir: 'radio-button' }, |
| 37 | + { slug: 'segment-picker', name: 'SegmentPicker', propsType: 'SegmentPickerProps', dir: 'segment-picker' }, |
| 38 | + { slug: 'select', name: 'Select', propsType: 'SelectBaseProps', dir: 'select' }, |
| 39 | + { slug: 'separator', name: 'Separator', propsType: null, dir: 'separator' }, |
| 40 | + { slug: 'snackbar', name: 'Snackbar', propsType: 'SnackbarProps', dir: 'snackbar' }, |
| 41 | + { slug: 'status', name: 'Status', propsType: 'StatusProps', dir: 'status' }, |
| 42 | + { slug: 'switch', name: 'Switch', propsType: 'BaseSwitchProps', dir: 'switch' }, |
| 43 | + { slug: 'text-area', name: 'TextArea', propsType: 'TextAreaProps', dir: 'text-area' }, |
| 44 | + { slug: 'tooltip', name: 'Tooltip', propsType: 'TooltipProps', dir: 'tooltip' }, |
| 45 | + // Diagram components (props extracted the same way; NodePanel is a compound |
| 46 | + // component documented narratively, so it has no flat props entry here). |
| 47 | + { slug: 'node-icon', name: 'NodeIcon', propsType: 'NodeIconProps', dir: 'node/node-icon' }, |
| 48 | + { slug: 'node-description', name: 'NodeDescription', propsType: 'NodeDescriptionProps', dir: 'node/node-description' }, |
| 49 | + { slug: 'node-as-port-wrapper', name: 'NodeAsPortWrapper', propsType: 'NodeAsPortWrapperProps', dir: 'node/node-as-port-wrapper' }, |
| 50 | + { slug: 'edge', name: 'EdgeLabel', propsType: 'EdgeLabelProps', dir: 'edge' }, |
| 51 | +]; |
| 52 | + |
| 53 | +async function runTypedoc() { |
| 54 | + await mkdir(path.dirname(tdJson), { recursive: true }); |
| 55 | + const bin = path.resolve(docsRoot, 'node_modules/.bin/typedoc'); |
| 56 | + await promisify(execFile)( |
| 57 | + bin, |
| 58 | + [ |
| 59 | + '--json', tdJson, |
| 60 | + '--entryPoints', path.resolve(uiSrc, 'index.ts'), |
| 61 | + '--tsconfig', path.resolve(repoRoot, 'packages/ui/tsconfig.json'), |
| 62 | + '--excludeExternals', '--excludePrivate', '--skipErrorChecking', '--logLevel', 'Error', |
| 63 | + ], |
| 64 | + { cwd: repoRoot, maxBuffer: 64 * 1024 * 1024 }, |
| 65 | + ); |
| 66 | + return JSON.parse(await readFile(tdJson, 'utf8')); |
| 67 | +} |
| 68 | + |
| 69 | +function indexById(root) { |
| 70 | + const byId = new Map(); |
| 71 | + (function walk(node) { |
| 72 | + if (node && typeof node.id === 'number') byId.set(node.id, node); |
| 73 | + for (const child of node.children ?? []) walk(child); |
| 74 | + })(root); |
| 75 | + return byId; |
| 76 | +} |
| 77 | + |
| 78 | +function findTypeByName(root, name) { |
| 79 | + let found = null; |
| 80 | + (function walk(node) { |
| 81 | + if (found) return; |
| 82 | + // 2097152 = TypeAlias, 256 = Interface |
| 83 | + if (node.name === name && (node.kind === 2097152 || node.kind === 256)) found = node; |
| 84 | + for (const child of node.children ?? []) walk(child); |
| 85 | + })(root); |
| 86 | + return found; |
| 87 | +} |
| 88 | + |
| 89 | +function typeToString(t, byId, depth = 0) { |
| 90 | + if (!t || depth > 6) return 'unknown'; |
| 91 | + switch (t.type) { |
| 92 | + case 'intrinsic': return t.name; |
| 93 | + case 'literal': return typeof t.value === 'string' ? `'${t.value}'` : String(t.value); |
| 94 | + case 'reference': { |
| 95 | + const args = t.typeArguments?.length ? `<${t.typeArguments.map((a) => typeToString(a, byId, depth + 1)).join(', ')}>` : ''; |
| 96 | + return `${t.name}${args}`; |
| 97 | + } |
| 98 | + case 'union': return t.types.map((x) => typeToString(x, byId, depth + 1)).join(' | '); |
| 99 | + case 'intersection': return t.types.map((x) => typeToString(x, byId, depth + 1)).join(' & '); |
| 100 | + case 'array': return `${typeToString(t.elementType, byId, depth + 1)}[]`; |
| 101 | + case 'tuple': return `[${(t.elements ?? []).map((x) => typeToString(x, byId, depth + 1)).join(', ')}]`; |
| 102 | + case 'reflection': { |
| 103 | + const sig = t.declaration?.signatures?.[0]; |
| 104 | + if (sig) { |
| 105 | + const params = (sig.parameters ?? []).map((p) => `${p.name}: ${typeToString(p.type, byId, depth + 1)}`).join(', '); |
| 106 | + return `(${params}) => ${typeToString(sig.type, byId, depth + 1)}`; |
| 107 | + } |
| 108 | + return '{ … }'; |
| 109 | + } |
| 110 | + case 'indexedAccess': return `${typeToString(t.objectType, byId, depth + 1)}[${typeToString(t.indexType, byId, depth + 1)}]`; |
| 111 | + case 'templateLiteral': return 'string'; |
| 112 | + case 'query': return typeToString(t.queryType, byId, depth + 1); |
| 113 | + case 'predicate': return 'boolean'; |
| 114 | + case 'typeOperator': return `${t.operator} ${typeToString(t.target, byId, depth + 1)}`; |
| 115 | + default: return t.name ?? 'unknown'; |
| 116 | + } |
| 117 | +} |
| 118 | + |
| 119 | +function summaryText(comment) { |
| 120 | + if (!comment?.summary) return ''; |
| 121 | + return comment.summary.map((s) => s.text).join('').trim(); |
| 122 | +} |
| 123 | + |
| 124 | +function defaultTag(comment) { |
| 125 | + const tag = (comment?.blockTags ?? []).find((b) => b.tag === '@default' || b.tag === '@defaultValue'); |
| 126 | + if (!tag) return null; |
| 127 | + let value = tag.content.map((c) => c.text).join('').trim(); |
| 128 | + value = value.replace(/^```[a-z]*\s*/i, '').replace(/\s*```$/, '').trim(); // strip ```ts … ``` fences |
| 129 | + value = value.replace(/^`+|`+$/g, '').trim(); // strip inline backticks |
| 130 | + return value || null; |
| 131 | +} |
| 132 | + |
| 133 | +// Collect own properties from a prop type alias / interface, walking |
| 134 | +// intersections and skipping referenced (extended / native HTML) members. |
| 135 | +function collectProps(typeNode, byId, acc = new Map()) { |
| 136 | + if (!typeNode) return acc; |
| 137 | + // TypeAlias / Interface: plain object members land directly on `.children`; |
| 138 | + // computed types (intersections etc.) land on `.type`. |
| 139 | + if (typeNode.kind === 2097152 || typeNode.kind === 256) { |
| 140 | + if (typeNode.children?.length) { |
| 141 | + for (const child of typeNode.children) addProp(child, byId, acc); |
| 142 | + return acc; |
| 143 | + } |
| 144 | + return collectProps(typeNode.type, byId, acc); |
| 145 | + } |
| 146 | + if (typeNode.type === 'intersection' || typeNode.type === 'union') { |
| 147 | + for (const member of typeNode.types) collectProps(member, byId, acc); |
| 148 | + return acc; |
| 149 | + } |
| 150 | + if (typeNode.type === 'reflection' && typeNode.declaration?.children) { |
| 151 | + for (const child of typeNode.declaration.children) addProp(child, byId, acc); |
| 152 | + return acc; |
| 153 | + } |
| 154 | + if (typeNode.type === 'reference' && typeof typeNode.target === 'number') { |
| 155 | + const target = byId.get(typeNode.target); |
| 156 | + // Only follow references into our own package's prop types, not native ones. |
| 157 | + if (target && target.kind === 2097152) collectProps(target, byId, acc); |
| 158 | + return acc; |
| 159 | + } |
| 160 | + return acc; |
| 161 | +} |
| 162 | + |
| 163 | +function addProp(child, byId, acc) { |
| 164 | + if (child.kind !== 1024 || acc.has(child.name)) return; // 1024 = Property |
| 165 | + acc.set(child.name, { |
| 166 | + name: child.name, |
| 167 | + type: typeToString(child.type, byId), |
| 168 | + required: !child.flags?.isOptional, |
| 169 | + default: defaultTag(child.comment), |
| 170 | + description: summaryText(child.comment), |
| 171 | + }); |
| 172 | +} |
| 173 | + |
| 174 | +function extractCssVariables(dir) { |
| 175 | + const abs = path.resolve(uiSrc, 'components', dir); |
| 176 | + const files = globSync('**/*.css', { cwd: abs }).sort(); |
| 177 | + const seen = new Set(); |
| 178 | + const vars = []; |
| 179 | + for (const file of files) { |
| 180 | + const css = readFileSync(path.resolve(abs, file), 'utf8'); |
| 181 | + // Match `--ax-public-xxx:` declarations, capturing an optional same-line comment. |
| 182 | + const re = /(--ax-public-[\w-]+)\s*:[^;]*?(?:\/\*\s*(.*?)\s*\*\/)?\s*;/g; |
| 183 | + let m; |
| 184 | + while ((m = re.exec(css))) { |
| 185 | + if (seen.has(m[1])) continue; |
| 186 | + seen.add(m[1]); |
| 187 | + vars.push({ name: m[1], comment: (m[2] ?? '').trim() }); |
| 188 | + } |
| 189 | + } |
| 190 | + return vars; |
| 191 | +} |
| 192 | + |
| 193 | +async function main() { |
| 194 | + const project = await runTypedoc(); |
| 195 | + const byId = indexById(project); |
| 196 | + const out = {}; |
| 197 | + const warnings = []; |
| 198 | + |
| 199 | + for (const c of COMPONENTS) { |
| 200 | + let props = []; |
| 201 | + if (c.propsType) { |
| 202 | + const typeNode = findTypeByName(project, c.propsType); |
| 203 | + if (typeNode) { |
| 204 | + props = [...collectProps(typeNode, byId).values()].sort((a, b) => a.name.localeCompare(b.name)); |
| 205 | + } else { |
| 206 | + warnings.push(`props type "${c.propsType}" not found for "${c.slug}"`); |
| 207 | + } |
| 208 | + } |
| 209 | + out[c.slug] = { name: c.name, props, cssVariables: extractCssVariables(c.dir) }; |
| 210 | + } |
| 211 | + |
| 212 | + await mkdir(path.dirname(outFile), { recursive: true }); |
| 213 | + await writeFile(outFile, JSON.stringify(out, null, 2) + '\n'); |
| 214 | + |
| 215 | + const summary = Object.entries(out).map(([s, v]) => `${s}: ${v.props.length} props, ${v.cssVariables.length} vars`); |
| 216 | + console.log('✔ ui-api.json generated\n ' + summary.join('\n ')); |
| 217 | + if (warnings.length) console.warn('⚠ ' + warnings.join('\n⚠ ')); |
| 218 | +} |
| 219 | + |
| 220 | +main().catch((error) => { |
| 221 | + console.error(error); |
| 222 | + process.exit(1); |
| 223 | +}); |
0 commit comments