@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db7b338
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -1
- package/api/blog/blog.doc.mjs +1 -0
- package/api/build/build.doc.mjs +1 -0
- package/api/component/component.doc.mjs +1 -0
- package/api/discover/discover.doc.mjs +1 -0
- package/api/docs/_adapter.d.mts +3 -8
- package/api/docs/_adapter.mjs +13 -105
- package/api/docs/detail/section/section.mjs +9 -15
- package/api/docs/detail/section/section.test.mjs +15 -6
- package/api/docs/docs.doc.mjs +1 -0
- package/api/docs/list/list.mjs +3 -7
- package/api/doctor/doctor.d.mts +25 -3
- package/api/doctor/doctor.doc.mjs +1 -0
- package/api/doctor/doctor.mjs +186 -14
- package/api/doctor/doctor.test.mjs +332 -7
- package/api/gap-report/gap-report.doc.mjs +1 -0
- package/api/hook/_adapter.mjs +19 -5
- package/api/hook/hook.doc.mjs +1 -0
- package/api/hook/list/list.d.mts +1 -1
- package/api/hook/list/list.mjs +69 -17
- package/api/init/init.doc.mjs +1 -0
- package/api/integration/add-contribution.mjs +7 -7
- package/api/integration/add-contribution.test.mjs +37 -3
- package/api/integration/add-theme.mjs +34 -64
- package/api/integration/add-theme.test.mjs +105 -21
- package/api/integration/authoring-checks.test.mjs +8 -4
- package/api/integration/integration-block-exports.test.mjs +10 -6
- package/api/integration/integrationAdd.doc.mjs +1 -0
- package/api/integration/integrationAddAgentDoc.doc.mjs +1 -0
- package/api/integration/integrationAddCodemod.doc.mjs +1 -0
- package/api/integration/integrationAddComponent.doc.mjs +1 -0
- package/api/integration/integrationAddDoc.doc.mjs +1 -0
- package/api/integration/integrationAddTemplate.doc.mjs +1 -0
- package/api/integration/integrationAddTheme.doc.mjs +6 -5
- package/api/integration/integrationComponentConflicts.doc.mjs +1 -0
- package/api/integration/integrationDocConflicts.doc.mjs +1 -0
- package/api/integration/integrationPackCheck.doc.mjs +1 -0
- package/api/integration/integrationTemplateConflicts.doc.mjs +1 -0
- package/api/integration/pack-check.test.mjs +17 -47
- package/api/integration/summarizeIssues.doc.mjs +1 -0
- package/api/integration/validate-integration-fixes.test.mjs +1389 -0
- package/api/integration/validate-integration.mjs +50 -102
- package/api/integration/validate-integration.test.mjs +85 -23
- package/api/integration/validate-unread-theme-folders.test.mjs +110 -0
- package/api/integration/validateIntegration.doc.mjs +1 -0
- package/api/json/assertResponse.doc.mjs +1 -0
- package/api/json/isError.doc.mjs +1 -0
- package/api/json/parseResponse.doc.mjs +1 -0
- package/api/layout/layoutCheck.doc.mjs +1 -0
- package/api/layout/layoutExpand.doc.mjs +1 -0
- package/api/layout/layoutGrammar.doc.mjs +1 -0
- package/api/search/search.doc.mjs +1 -0
- package/api/search/search.mjs +16 -6
- package/api/swizzle/swizzle.doc.mjs +1 -0
- package/api/template/template-suffix.test.mjs +41 -21
- package/api/template/template.doc.mjs +1 -0
- package/api/theme/_adapter.d.mts +2 -3
- package/api/theme/_adapter.mjs +4 -5
- package/api/theme/add/add.binary.test.mjs +10 -17
- package/api/theme/add/add.test.mjs +14 -1
- package/api/theme/generateTonalPalette.doc.mjs +1 -0
- package/api/theme/integration-themes.test.mjs +39 -28
- package/api/theme/list/list.test.mjs +19 -20
- package/api/theme/listThemes.doc.mjs +6 -5
- package/api/theme/themeAdd.doc.mjs +4 -3
- package/api/theme/themeBuild.doc.mjs +1 -0
- package/api/theme/themeList.doc.mjs +6 -3
- package/api/theme/themeListAvailable.doc.mjs +5 -3
- package/api/theme/themePaletteGenerate.doc.mjs +1 -0
- package/api/theme/themeTargets.doc.mjs +1 -0
- package/api/theme/themeTemplate.doc.mjs +1 -0
- package/api/upgrade/_adapter.d.mts +32 -5
- package/api/upgrade/_adapter.mjs +97 -69
- package/api/upgrade/provider-agreement.test.mjs +152 -0
- package/api/upgrade/run/run.mjs +356 -59
- package/api/upgrade/upgrade.doc.mjs +6 -1
- package/api/upgrade/upgrade.type.d.mts +34 -0
- package/api/upgrade/upgrade.type.mjs +15 -0
- package/assets/codemods/__tests__/runner.test.mjs +330 -8
- package/assets/codemods/integration-discovery.mjs +8 -2
- package/assets/codemods/integration-discovery.test.mjs +15 -0
- package/assets/codemods/integration-runner.mjs +56 -4
- package/assets/codemods/integration-runner.protection.test.mjs +153 -0
- package/assets/codemods/run-codemod.mjs +177 -34
- package/assets/codemods/runner.mjs +350 -102
- package/assets/codemods/transforms/next/__tests__/migrate-native-picker-to-presentation.test.mjs +63 -0
- package/assets/codemods/transforms/next/__tests__/migrate-theme-catalog-to-descriptors.test.mjs +220 -0
- package/assets/codemods/transforms/next/index.mjs +19 -1
- package/assets/codemods/transforms/next/migrate-native-picker-to-presentation.mjs +148 -0
- package/assets/codemods/transforms/next/migrate-theme-catalog-to-descriptors.mjs +141 -0
- package/assets/docs/cli-integrations.doc.mjs +30 -30
- package/assets/docs/cli.doc.mjs +15 -0
- package/assets/docs/theme.doc.mjs +1 -1
- package/assets/templates/blocks/components/DateInput/DateInputDateRange.tsx +1 -1
- package/assets/templates/blocks/components/Item/ItemDocumentTabs.doc.mjs +14 -0
- package/assets/templates/blocks/components/Item/ItemDocumentTabs.tsx +100 -0
- package/assets/templates/blocks/components/TimeInput/TimeInputConstrained.tsx +1 -0
- package/assets/templates/themes/butter/butterTheme.doc.mjs +11 -0
- package/assets/templates/themes/chocolate/chocolateTheme.doc.mjs +11 -0
- package/assets/templates/themes/gothic/gothicTheme.doc.mjs +11 -0
- package/assets/templates/themes/matcha/matchaTheme.doc.mjs +11 -0
- package/assets/templates/themes/neutral/neutralTheme.doc.mjs +11 -0
- package/assets/templates/themes/stone/stoneTheme.doc.mjs +11 -0
- package/assets/templates/themes/y2k/y2kTheme.doc.mjs +11 -0
- package/authoring/codemod/codemod.doc.mjs +1 -1
- package/authoring/codemod/type.ts +12 -0
- package/authoring/config/config.doc.mjs +1 -1
- package/authoring/debug/debug.doc.d.mts +11 -0
- package/authoring/debug/debug.doc.mjs +182 -0
- package/authoring/doctypes/_schema.d.mts +71 -141
- package/authoring/doctypes/_schema.mjs +29 -2
- package/authoring/doctypes/base/graph-fields.doc.mjs +1 -1
- package/authoring/doctypes/command/command.doc.mjs +1 -1
- package/authoring/doctypes/command/type.ts +1 -1
- package/authoring/doctypes/component/type.ts +2 -2
- package/authoring/doctypes/doctypes-new.test.mjs +48 -6
- package/authoring/doctypes/enum/enum.doc.mjs +1 -1
- package/authoring/doctypes/enum/type.ts +1 -1
- package/authoring/doctypes/function/function.doc.mjs +1 -1
- package/authoring/doctypes/function/type.ts +1 -1
- package/authoring/doctypes/hook/type.ts +2 -2
- package/authoring/doctypes/load-contract.test.mjs +3 -2
- package/authoring/doctypes/namespace/namespace.doc.mjs +2 -2
- package/authoring/doctypes/namespace/parse.test.mjs +23 -25
- package/authoring/doctypes/namespace/type.ts +5 -2
- package/authoring/doctypes/parse.d.mts +4 -2
- package/authoring/doctypes/parse.mjs +10 -5
- package/authoring/doctypes/reference/reference.doc.mjs +6 -4
- package/authoring/doctypes/reference/type.ts +9 -10
- package/authoring/doctypes/schema/schema.doc.mjs +1 -1
- package/authoring/doctypes/schema/type.ts +1 -2
- package/authoring/doctypes/template/template.doc.mjs +3 -3
- package/authoring/doctypes/theme/parse.d.mts +35 -0
- package/authoring/doctypes/theme/parse.mjs +76 -0
- package/authoring/doctypes/theme/theme.doc.d.mts +9 -0
- package/authoring/doctypes/theme/theme.doc.mjs +79 -0
- package/authoring/doctypes/theme/type.ts +42 -0
- package/authoring/doctypes/types.ts +2 -1
- package/authoring/gap-report/gap-report.doc.d.mts +12 -0
- package/authoring/gap-report/gap-report.doc.mjs +183 -0
- package/authoring/index.d.mts +1 -0
- package/authoring/index.d.ts +7 -4
- package/authoring/index.mjs +2 -1
- package/authoring/integration/integration.doc.mjs +2 -2
- package/authoring/integration/type.ts +3 -9
- package/clients/cli/__tests__/cliManifest.test.ts +27 -29
- package/clients/cli/commands/blog.doc.mjs +1 -1
- package/clients/cli/commands/build-theme.adaptations.test.mjs +100 -1
- package/clients/cli/commands/build-theme.mjs +10 -44
- package/clients/cli/commands/build.doc.mjs +1 -1
- package/clients/cli/commands/component.doc.mjs +1 -1
- package/clients/cli/commands/discover.doc.mjs +1 -1
- package/clients/cli/commands/docs.doc.mjs +1 -1
- package/clients/cli/commands/docs.mjs +15 -58
- package/clients/cli/commands/docs.test.mjs +11 -14
- package/clients/cli/commands/doctor-integration-components.doc.mjs +1 -1
- package/clients/cli/commands/doctor-integration-docs.doc.mjs +1 -1
- package/clients/cli/commands/doctor-integration-templates.doc.mjs +1 -1
- package/clients/cli/commands/doctor-integration-validate.doc.mjs +1 -1
- package/clients/cli/commands/doctor-integration.doc.mjs +1 -1
- package/clients/cli/commands/doctor-integration.test.mjs +15 -7
- package/clients/cli/commands/doctor.doc.mjs +1 -1
- package/clients/cli/commands/gap-report.doc.mjs +1 -1
- package/clients/cli/commands/hook.doc.mjs +1 -1
- package/clients/cli/commands/init.doc.mjs +1 -1
- package/clients/cli/commands/integration-add.controls.test.mjs +1 -1
- package/clients/cli/commands/integration-add.doc.mjs +1 -1
- package/clients/cli/commands/integration-pack.doc.mjs +1 -1
- package/clients/cli/commands/integration-real-world.test.mjs +3 -9
- package/clients/cli/commands/integration.doc.mjs +1 -1
- package/clients/cli/commands/layout-check.doc.mjs +1 -1
- package/clients/cli/commands/layout-expand.doc.mjs +1 -1
- package/clients/cli/commands/layout-grammar.doc.mjs +1 -1
- package/clients/cli/commands/layout.doc.mjs +1 -1
- package/clients/cli/commands/manifest.doc.mjs +1 -1
- package/clients/cli/commands/search.doc.mjs +1 -1
- package/clients/cli/commands/swizzle.doc.mjs +1 -1
- package/clients/cli/commands/template.doc.mjs +1 -1
- package/clients/cli/commands/text-json-parity.test.mjs +718 -0
- package/clients/cli/commands/theme-add.doc.mjs +2 -2
- package/clients/cli/commands/theme-build.doc.mjs +1 -1
- package/clients/cli/commands/theme-list.doc.mjs +2 -2
- package/clients/cli/commands/theme-palette-generate.doc.mjs +3 -3
- package/clients/cli/commands/theme-palette.doc.mjs +1 -1
- package/clients/cli/commands/theme-targets.behavior.test.mjs +4 -3
- package/clients/cli/commands/theme-targets.doc.mjs +1 -1
- package/clients/cli/commands/theme-template.doc.mjs +1 -1
- package/clients/cli/commands/theme.doc.mjs +1 -1
- package/clients/cli/commands/upgrade.doc.mjs +3 -2
- package/clients/cli/commands/upgrade.file-protection.test.mjs +228 -0
- package/clients/cli/commands/upgrade.mjs +29 -7
- package/clients/cli/formatters/index.mjs +2 -0
- package/clients/cli/formatters/index.test.mjs +6 -0
- package/clients/cli/lib/hook-format.mjs +14 -5
- package/foundation/config/project-themes.test.mjs +11 -19
- package/foundation/config/project.d.mts +8 -0
- package/foundation/config/project.mjs +50 -21
- package/foundation/config/project.test.mjs +3 -16
- package/foundation/discovery/authoring-self-docs.d.mts +6 -0
- package/foundation/discovery/authoring-self-docs.mjs +17 -7
- package/foundation/discovery/authoring-self-docs.test.mjs +3 -2
- package/foundation/discovery/authoring-surface.d.mts +74 -0
- package/foundation/discovery/authoring-surface.mjs +525 -0
- package/foundation/discovery/authoring-surface.test.mjs +392 -0
- package/foundation/discovery/cli-self-docs.d.mts +113 -0
- package/foundation/discovery/cli-self-docs.mjs +514 -0
- package/foundation/discovery/cli-self-docs.test.mjs +437 -0
- package/foundation/discovery/component-loader.d.mts +35 -38
- package/foundation/discovery/component-loader.mjs +53 -222
- package/foundation/discovery/docs-discovery.d.mts +3 -2
- package/foundation/discovery/docs-discovery.mjs +14 -17
- package/foundation/discovery/docs-discovery.test.mjs +15 -15
- package/foundation/discovery/docs-section-key.d.mts +19 -8
- package/foundation/discovery/docs-section-key.mjs +119 -32
- package/foundation/discovery/docs-section-key.test.mjs +41 -19
- package/foundation/discovery/template-adapter.d.mts +7 -0
- package/foundation/discovery/template-adapter.mjs +27 -40
- package/foundation/discovery/template-adapter.test.mjs +15 -0
- package/foundation/discovery/theme-discovery.d.mts +67 -7
- package/foundation/discovery/theme-discovery.mjs +916 -186
- package/foundation/discovery/theme-discovery.test.mjs +613 -219
- package/foundation/doc-compiler/bundle.d.mts +47 -0
- package/foundation/doc-compiler/bundle.mjs +218 -0
- package/foundation/doc-compiler/bundle.test.mjs +255 -0
- package/foundation/doc-compiler/compile.d.mts +200 -0
- package/foundation/doc-compiler/compile.mjs +259 -9
- package/foundation/doc-compiler/diagnostics.d.mts +126 -0
- package/foundation/doc-compiler/diagnostics.mjs +277 -0
- package/foundation/doc-compiler/doc-compiler.test.mjs +28 -1
- package/foundation/doc-compiler/doc-loads.test.mjs +1642 -0
- package/foundation/doc-compiler/import.d.mts +24 -0
- package/foundation/doc-compiler/import.mjs +59 -0
- package/foundation/doc-compiler/inputs.d.mts +102 -0
- package/foundation/doc-compiler/inputs.mjs +286 -0
- package/foundation/doc-compiler/inputs.test.mjs +299 -0
- package/foundation/doc-compiler/ir.d.mts +13 -0
- package/foundation/doc-compiler/ir.mjs +189 -12
- package/foundation/doc-compiler/lower-doc.test.mjs +492 -0
- package/foundation/doc-compiler/overlays.d.mts +37 -0
- package/foundation/doc-compiler/overlays.mjs +206 -0
- package/foundation/doc-compiler/parse-readable.d.mts +9 -0
- package/foundation/doc-compiler/parse-readable.mjs +29 -0
- package/foundation/doc-compiler/read.d.mts +126 -0
- package/foundation/doc-compiler/read.mjs +320 -0
- package/foundation/doc-compiler/read.test.mjs +313 -0
- package/foundation/doc-compiler/source.d.mts +33 -0
- package/foundation/doc-compiler/source.mjs +128 -0
- package/foundation/fs/file-protection.d.mts +33 -0
- package/foundation/fs/file-protection.mjs +825 -0
- package/foundation/fs/file-protection.test.mjs +250 -0
- package/foundation/integrations/autolink.d.mts +58 -1
- package/foundation/integrations/autolink.mjs +143 -57
- package/foundation/integrations/contribution-fixes.d.mts +145 -0
- package/foundation/integrations/contribution-fixes.mjs +1284 -0
- package/foundation/integrations/contribution-inventory.d.mts +1 -1
- package/foundation/integrations/contribution-inventory.mjs +17 -20
- package/foundation/integrations/contribution-inventory.test.mjs +67 -27
- package/foundation/integrations/integrations.d.mts +3 -0
- package/foundation/integrations/integrations.mjs +11 -97
- package/foundation/integrations/provider-ledger.test.mjs +275 -0
- package/foundation/integrations/provider-resolution.d.mts +152 -0
- package/foundation/integrations/provider-resolution.mjs +576 -0
- package/foundation/integrations/provider-resolution.test.mjs +369 -0
- package/foundation/integrations/theme-descriptor.d.mts +8 -0
- package/foundation/integrations/theme-descriptor.mjs +44 -0
- package/foundation/integrations/validate-contributions.mjs +104 -10
- package/foundation/response/error-codes.d.mts +3 -1
- package/foundation/response/error-codes.d.ts +2 -0
- package/foundation/response/error-codes.doc.mjs +12 -2
- package/foundation/response/error-codes.mjs +7 -1
- package/foundation/response/error-codes.test.mjs +55 -11
- package/foundation/response/response-types.doc.mjs +1 -1
- package/foundation/response/response.doc.mjs +1 -1
- package/foundation/text/string-utils.mjs +22 -10
- package/package.json +10 -9
- package/assets/templates/themes/manifest.json +0 -95
|
@@ -1,245 +1,76 @@
|
|
|
1
1
|
// Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
|
-
* @file Component doc loader
|
|
5
|
-
*/
|
|
6
|
-
|
|
7
|
-
import {pathToFileURL} from 'node:url';
|
|
8
|
-
import {importUserModule} from '../fs/module-loader.mjs';
|
|
9
|
-
import {parseDoc} from '../../authoring/doctypes/parse.mjs';
|
|
10
|
-
|
|
11
|
-
/**
|
|
12
|
-
* Load a component doc through the shared load/validation boundary.
|
|
13
|
-
*
|
|
14
|
-
* This is the typed counterpart to {@link loadDocs}: it loads `.doc.ts` via
|
|
15
|
-
* jiti (and `.doc.mjs`/`.doc.js` via native import) and validates via
|
|
16
|
-
* `parseDoc`, which accepts BOTH formats, so this loader reads whichever the
|
|
17
|
-
* file uses:
|
|
18
|
-
* - NEW: a stamped default export (`export default {type: 'component', ...}`
|
|
19
|
-
* / `'function'` / `'generic'`) — the same single-export convention the
|
|
20
|
-
* other authoring parsers use for config/integration/template. These carry
|
|
21
|
-
* a stamped `type` and validate against the matching per-kind parser.
|
|
22
|
-
* - OLD: the legacy loose `export const docs = {...}` (no `type`), validated
|
|
23
|
-
* against the permissive legacy union.
|
|
24
|
-
* The default export wins when both are present. Throws a readable
|
|
25
|
-
* `formatZodError`-style message on failure. Translations (`docsZh`/
|
|
26
|
-
* `docsDense`) are merged exactly as {@link loadDocs} does so callers see
|
|
27
|
-
* identical output.
|
|
4
|
+
* @file Component and hook doc loader.
|
|
28
5
|
*
|
|
29
|
-
* @
|
|
30
|
-
*
|
|
31
|
-
* @
|
|
6
|
+
* @input A component or hook `.doc.{ts,mjs,js}` path and the reading language
|
|
7
|
+
* (`lang`, or the legacy `zh`/`dense` flags).
|
|
8
|
+
* @output The module's own doc, with its translation laid over it for `lang`.
|
|
9
|
+
* @position The loaders every component and hook reader calls. Both read
|
|
10
|
+
* through the doc compiler (foundation/doc-compiler/read.mjs), which lowers
|
|
11
|
+
* the doc on every read. The two differ only in how strict they are:
|
|
12
|
+
* {@link loadComponentDoc} reports a doc that fails its kind's parser, and
|
|
13
|
+
* {@link loadDocs}, which has never checked docs, still reads one.
|
|
32
14
|
*/
|
|
33
|
-
export async function loadComponentDoc(
|
|
34
|
-
docPath,
|
|
35
|
-
{zh = false, dense = false, lang} = {},
|
|
36
|
-
) {
|
|
37
|
-
const mod = await importUserModule(docPath);
|
|
38
|
-
/** @type {any} */
|
|
39
|
-
const authored = mod?.default ?? mod?.docs;
|
|
40
|
-
|
|
41
|
-
parseDoc(authored, docPath);
|
|
42
|
-
const docs = authored;
|
|
43
15
|
|
|
44
|
-
|
|
45
|
-
if (!locale) return docs;
|
|
16
|
+
import {readDocView} from '../doc-compiler/read.mjs';
|
|
46
17
|
|
|
47
|
-
|
|
48
|
-
locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
|
|
49
|
-
if (!translationKey || !mod[translationKey]) return docs;
|
|
50
|
-
|
|
51
|
-
/** @type {any} */
|
|
52
|
-
const translation = mod[translationKey];
|
|
53
|
-
if (translation.props || translation.components?.some((/** @type {any} */ c) => c.props)) {
|
|
54
|
-
return overlayComponentDoc(docs, translation);
|
|
55
|
-
}
|
|
56
|
-
return mergeTranslation(docs, translation);
|
|
57
|
-
}
|
|
18
|
+
export {mergeTranslation} from '../doc-compiler/overlays.mjs';
|
|
58
19
|
|
|
59
20
|
/**
|
|
60
|
-
* @
|
|
61
|
-
* @
|
|
62
|
-
* @
|
|
21
|
+
* @typedef {object} LoadDocOptions
|
|
22
|
+
* @property {boolean} [zh] legacy flag for `lang: 'zh'`
|
|
23
|
+
* @property {boolean} [dense] legacy flag for `lang: 'dense'`
|
|
24
|
+
* @property {string | null} [lang] wins over the legacy flags
|
|
25
|
+
* @property {'components' | 'hooks'} [root] which root reads the doc
|
|
26
|
+
* (default: components)
|
|
63
27
|
*/
|
|
64
|
-
export function mergeTranslation(docs, translation) {
|
|
65
|
-
if (!translation) return docs;
|
|
66
|
-
|
|
67
|
-
/** @type {any} */
|
|
68
|
-
const merged = {...docs};
|
|
69
|
-
|
|
70
|
-
// Merge prose into usage
|
|
71
|
-
if (merged.usage) {
|
|
72
|
-
merged.usage = {...merged.usage};
|
|
73
|
-
if (translation.usage?.description) merged.usage.description = translation.usage.description;
|
|
74
|
-
else if (translation.description) merged.usage.description = translation.description;
|
|
75
|
-
if (translation.usage?.bestPractices) merged.usage.bestPractices = translation.usage.bestPractices;
|
|
76
|
-
if (translation.usage?.accessibility) merged.usage.accessibility = translation.usage.accessibility;
|
|
77
|
-
}
|
|
78
|
-
|
|
79
|
-
// Legacy top-level fields (for docsZh that are full ComponentDoc clones)
|
|
80
|
-
if (translation.description && !merged.usage) merged.description = translation.description;
|
|
81
|
-
|
|
82
|
-
// Merge prop descriptions for single-component docs
|
|
83
|
-
if (translation.propDescriptions && merged.props) {
|
|
84
|
-
merged.props = merged.props.map((/** @type {any} */ prop) => {
|
|
85
|
-
const desc = translation.propDescriptions[prop.name];
|
|
86
|
-
return desc != null ? {...prop, description: desc} : prop;
|
|
87
|
-
});
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
// Merge hook param descriptions (HookTranslationDoc). Params are an array of
|
|
91
|
-
// {name, type, description, required}; override description by name where the
|
|
92
|
-
// translation has an entry. Names may include dots (e.g. 'options.isActive');
|
|
93
|
-
// the lookup is keyed by the exact param name.
|
|
94
|
-
if (translation.paramDescriptions && merged.params) {
|
|
95
|
-
merged.params = merged.params.map((/** @type {any} */ param) => {
|
|
96
|
-
const desc = translation.paramDescriptions[param.name];
|
|
97
|
-
return desc != null ? {...param, description: desc} : param;
|
|
98
|
-
});
|
|
99
|
-
}
|
|
100
|
-
|
|
101
|
-
// Merge hook return descriptions (HookTranslationDoc). Returns are an array
|
|
102
|
-
// of {name, type, description}; override description by name where present.
|
|
103
|
-
if (translation.returnDescriptions && merged.returns) {
|
|
104
|
-
merged.returns = merged.returns.map((/** @type {any} */ ret) => {
|
|
105
|
-
const desc = translation.returnDescriptions[ret.name];
|
|
106
|
-
return desc != null ? {...ret, description: desc} : ret;
|
|
107
|
-
});
|
|
108
|
-
}
|
|
109
|
-
|
|
110
|
-
// Merge sub-component translations
|
|
111
|
-
if (translation.components && merged.components) {
|
|
112
|
-
merged.components = merged.components.map((/** @type {any} */ comp, /** @type {any} */ i) => {
|
|
113
|
-
const trans = translation.components.find((/** @type {any} */ t) => t.name === comp.name)
|
|
114
|
-
|| translation.components[i];
|
|
115
|
-
if (!trans) return comp;
|
|
116
|
-
|
|
117
|
-
const mergedComp = {...comp};
|
|
118
|
-
if (trans.description) mergedComp.description = trans.description;
|
|
119
|
-
if (trans.propDescriptions && comp.props) {
|
|
120
|
-
mergedComp.props = comp.props.map((/** @type {any} */ prop) => {
|
|
121
|
-
const desc = trans.propDescriptions[prop.name];
|
|
122
|
-
return desc != null ? {...prop, description: desc} : prop;
|
|
123
|
-
});
|
|
124
|
-
}
|
|
125
|
-
return mergedComp;
|
|
126
|
-
});
|
|
127
|
-
}
|
|
128
|
-
|
|
129
|
-
return merged;
|
|
130
|
-
}
|
|
131
28
|
|
|
132
29
|
/**
|
|
133
|
-
*
|
|
134
|
-
*
|
|
135
|
-
*
|
|
136
|
-
* Translations are merged onto the base docs, keeping structure intact.
|
|
137
|
-
* @param {string} readmePath
|
|
138
|
-
* @param {{zh?: boolean, dense?: boolean, lang?: string}} [opts]
|
|
139
|
-
* @returns {Promise<any>}
|
|
30
|
+
* The overlay a read applies: `lang`, else the legacy flags.
|
|
31
|
+
* @param {LoadDocOptions} opts
|
|
32
|
+
* @returns {string | null}
|
|
140
33
|
*/
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
// Support both the new stamped default export (`export default {type: 'component', …}`)
|
|
144
|
-
// and the legacy named export (`export const docs = {…}`). Default wins when both
|
|
145
|
-
// are present, matching loadComponentDoc's precedence.
|
|
146
|
-
const docs = mod?.default ?? mod.docs;
|
|
147
|
-
|
|
148
|
-
// Resolve which translation to use (--lang takes priority over legacy flags)
|
|
149
|
-
const locale = lang || (dense ? 'dense' : zh ? 'zh' : null);
|
|
150
|
-
if (!locale) return docs;
|
|
151
|
-
|
|
152
|
-
const translationKey = locale === 'zh' ? 'docsZh' : locale === 'dense' ? 'docsDense' : null;
|
|
153
|
-
if (!translationKey || !mod[translationKey]) return docs;
|
|
154
|
-
|
|
155
|
-
const translation = mod[translationKey];
|
|
156
|
-
|
|
157
|
-
// A full ComponentDoc-shaped translation (legacy docsZh shape) used to be
|
|
158
|
-
// returned wholesale. That made it a REPLACEMENT, not an overlay: any prop
|
|
159
|
-
// the translation had not caught up with simply ceased to exist —
|
|
160
|
-
// `component Button --zh` silently omitted `isInterruptible` and
|
|
161
|
-
// `isIconOnly`. A reader of the translated docs cannot discover a prop that
|
|
162
|
-
// is not there. Overlay it instead, so an untranslated prop falls back to
|
|
163
|
-
// its English entry. (Same principle as the reference-doc overlays, #2182.)
|
|
164
|
-
if (translation.props || translation.components?.some((/** @type {any} */ c) => c.props)) {
|
|
165
|
-
return overlayComponentDoc(docs, translation);
|
|
166
|
-
}
|
|
167
|
-
|
|
168
|
-
// Otherwise it's a ComponentTranslationDoc — merge it onto docs
|
|
169
|
-
return mergeTranslation(docs, translation);
|
|
34
|
+
function localeOf({zh = false, dense = false, lang} = {}) {
|
|
35
|
+
return lang || (dense ? 'dense' : zh ? 'zh' : null);
|
|
170
36
|
}
|
|
171
37
|
|
|
172
38
|
/**
|
|
173
|
-
*
|
|
39
|
+
* Load a component or hook doc and check it against its kind's parser.
|
|
174
40
|
*
|
|
175
|
-
*
|
|
176
|
-
*
|
|
177
|
-
*
|
|
178
|
-
*
|
|
41
|
+
* Reads `.doc.ts` through jiti and `.doc.mjs`/`.doc.js` natively. Both formats
|
|
42
|
+
* load: a stamped default export (`export default {type: 'component', ...}`)
|
|
43
|
+
* checked against its kind, and the legacy `export const docs = {...}` checked
|
|
44
|
+
* against the permissive legacy union. The default export wins when both are
|
|
45
|
+
* present. Throws the parser's readable message when the doc fails.
|
|
179
46
|
*
|
|
180
|
-
* @param {
|
|
181
|
-
* @param {
|
|
182
|
-
* @returns {any}
|
|
47
|
+
* @param {string} docPath absolute path to a `.doc.{ts,mjs,js}` file
|
|
48
|
+
* @param {LoadDocOptions} [opts]
|
|
49
|
+
* @returns {Promise<any>} the checked (and optionally translated) doc
|
|
183
50
|
*/
|
|
184
|
-
function
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
const byName = new Map((tProps ?? []).map((/** @type {any} */ p) => [p.name, p]));
|
|
192
|
-
return baseProps.map((/** @type {any} */ prop) => {
|
|
193
|
-
const t = byName.get(prop.name);
|
|
194
|
-
// Take the translated text, but never let it drop the prop's contract
|
|
195
|
-
// (type/default/required stay authoritative from the English doc).
|
|
196
|
-
return t ? {...prop, ...t, name: prop.name, type: prop.type} : prop;
|
|
197
|
-
});
|
|
198
|
-
};
|
|
199
|
-
|
|
200
|
-
/** Preserve canonical structured guidance added after legacy full-doc translations,
|
|
201
|
-
* without changing established translated prose behavior.
|
|
202
|
-
* @param {any} baseUsage
|
|
203
|
-
* @param {any} translatedUsage
|
|
204
|
-
*/
|
|
205
|
-
const mergeUsage = (baseUsage, translatedUsage) => {
|
|
206
|
-
if (!translatedUsage) return baseUsage;
|
|
207
|
-
return {
|
|
208
|
-
...translatedUsage,
|
|
209
|
-
...(translatedUsage.accessibility === undefined &&
|
|
210
|
-
baseUsage?.accessibility !== undefined
|
|
211
|
-
? {accessibility: baseUsage.accessibility}
|
|
212
|
-
: null),
|
|
213
|
-
...(translatedUsage.accessibilityThemeCoverage === undefined &&
|
|
214
|
-
baseUsage?.accessibilityThemeCoverage !== undefined
|
|
215
|
-
? {accessibilityThemeCoverage: baseUsage.accessibilityThemeCoverage}
|
|
216
|
-
: null),
|
|
217
|
-
...(translatedUsage.anatomy === undefined && baseUsage?.anatomy !== undefined
|
|
218
|
-
? {anatomy: baseUsage.anatomy}
|
|
219
|
-
: null),
|
|
220
|
-
};
|
|
221
|
-
};
|
|
222
|
-
|
|
223
|
-
const merged = {...docs, ...translation, usage: mergeUsage(docs.usage, translation.usage)};
|
|
224
|
-
|
|
225
|
-
merged.props = overlayProps(docs.props, translation.props);
|
|
226
|
-
|
|
227
|
-
if (docs.components) {
|
|
228
|
-
const tByName = new Map(
|
|
229
|
-
(translation.components ?? []).map((/** @type {any} */ c) => [c.name, c]),
|
|
230
|
-
);
|
|
231
|
-
merged.components = docs.components.map((/** @type {any} */ base) => {
|
|
232
|
-
const t = tByName.get(base.name);
|
|
233
|
-
if (!t) return base;
|
|
234
|
-
return {...base, ...t, usage: mergeUsage(base.usage, t.usage), props: overlayProps(base.props, t.props)};
|
|
235
|
-
});
|
|
236
|
-
}
|
|
237
|
-
|
|
238
|
-
return merged;
|
|
51
|
+
export async function loadComponentDoc(docPath, opts = {}) {
|
|
52
|
+
return readDocView(docPath, {
|
|
53
|
+
root: opts.root ?? 'components',
|
|
54
|
+
lang: localeOf(opts),
|
|
55
|
+
label: docPath,
|
|
56
|
+
strict: true,
|
|
57
|
+
});
|
|
239
58
|
}
|
|
240
59
|
|
|
241
60
|
/**
|
|
242
|
-
*
|
|
243
|
-
* and
|
|
244
|
-
*
|
|
61
|
+
* Load a component or hook doc without checking it. Supports `lang` ('zh' for
|
|
62
|
+
* Chinese, 'dense' for compressed) and the legacy `zh`/`dense` flags; the
|
|
63
|
+
* translation is laid over the doc, keeping its structure. A file that exports
|
|
64
|
+
* no doc reads as `undefined`.
|
|
65
|
+
* @param {string} readmePath
|
|
66
|
+
* @param {LoadDocOptions} [opts]
|
|
67
|
+
* @returns {Promise<any>}
|
|
245
68
|
*/
|
|
69
|
+
export async function loadDocs(readmePath, opts = {}) {
|
|
70
|
+
return readDocView(readmePath, {
|
|
71
|
+
root: opts.root ?? 'components',
|
|
72
|
+
lang: localeOf(opts),
|
|
73
|
+
label: readmePath,
|
|
74
|
+
loader: 'native',
|
|
75
|
+
});
|
|
76
|
+
}
|
|
@@ -74,8 +74,9 @@ export function discoverIntegrationDocs(integration: {
|
|
|
74
74
|
/**
|
|
75
75
|
* Merge an extension onto a base topic: a section with a stable `id` replaces
|
|
76
76
|
* the base section with the same `id`; legacy sections without IDs fall back to
|
|
77
|
-
* title matching. A section with no match is appended
|
|
78
|
-
*
|
|
77
|
+
* title matching. A section with no match is appended. The title and
|
|
78
|
+
* description stay the base topic's: an extension adds to a topic, it never
|
|
79
|
+
* renames it. A topic that `replaces` another is the one that renames.
|
|
79
80
|
*
|
|
80
81
|
* Keyed by section TITLE rather than by position, the way the localization
|
|
81
82
|
* overlays are — position keying grafts an overlay onto whichever section
|
|
@@ -32,12 +32,12 @@
|
|
|
32
32
|
import * as fs from 'node:fs';
|
|
33
33
|
import * as path from 'node:path';
|
|
34
34
|
import {CLI_ROOT} from '../fs/paths.mjs';
|
|
35
|
-
import {
|
|
35
|
+
import {importDocModule} from '../doc-compiler/import.mjs';
|
|
36
36
|
import {CLI_PROVIDER_ID} from '../identity/providers.mjs';
|
|
37
|
-
import {
|
|
37
|
+
import {parseReadableDoc} from '../doc-compiler/parse-readable.mjs';
|
|
38
38
|
import {
|
|
39
39
|
sectionKey,
|
|
40
|
-
|
|
40
|
+
sectionKeyErrors,
|
|
41
41
|
sourceTitle,
|
|
42
42
|
withSourceTitle,
|
|
43
43
|
} from './docs-section-key.mjs';
|
|
@@ -117,7 +117,7 @@ export function discoverBuiltinTopics() {
|
|
|
117
117
|
* @returns {Promise<unknown>} the authored doc value
|
|
118
118
|
*/
|
|
119
119
|
export async function loadTopicModule(file) {
|
|
120
|
-
const mod = await
|
|
120
|
+
const mod = await importDocModule(file);
|
|
121
121
|
const doc = mod?.docs ?? mod?.default;
|
|
122
122
|
if (doc == null) {
|
|
123
123
|
throw new Error(
|
|
@@ -312,9 +312,10 @@ export function problemsInTopic(doc) {
|
|
|
312
312
|
);
|
|
313
313
|
},
|
|
314
314
|
);
|
|
315
|
-
//
|
|
316
|
-
//
|
|
317
|
-
|
|
315
|
+
// Explicit authored IDs are a new opt-in contract and remain strict. Topics
|
|
316
|
+
// that relied on 0.6.x title-only sections keep loading; the compiler assigns
|
|
317
|
+
// deterministic fallback/suffixed keys for the additive index API.
|
|
318
|
+
problems.push(...sectionKeyErrors(doc.sections));
|
|
318
319
|
return problems;
|
|
319
320
|
}
|
|
320
321
|
|
|
@@ -363,7 +364,7 @@ export async function discoverIntegrationDocs(integration) {
|
|
|
363
364
|
for (const file of files) {
|
|
364
365
|
let doc;
|
|
365
366
|
try {
|
|
366
|
-
doc =
|
|
367
|
+
doc = parseReadableDoc(await loadTopicModule(file), path.basename(file));
|
|
367
368
|
} catch (err) {
|
|
368
369
|
errors.push(
|
|
369
370
|
new Error(
|
|
@@ -423,8 +424,9 @@ export async function discoverIntegrationDocs(integration) {
|
|
|
423
424
|
/**
|
|
424
425
|
* Merge an extension onto a base topic: a section with a stable `id` replaces
|
|
425
426
|
* the base section with the same `id`; legacy sections without IDs fall back to
|
|
426
|
-
* title matching. A section with no match is appended
|
|
427
|
-
*
|
|
427
|
+
* title matching. A section with no match is appended. The title and
|
|
428
|
+
* description stay the base topic's: an extension adds to a topic, it never
|
|
429
|
+
* renames it. A topic that `replaces` another is the one that renames.
|
|
428
430
|
*
|
|
429
431
|
* Keyed by section TITLE rather than by position, the way the localization
|
|
430
432
|
* overlays are — position keying grafts an overlay onto whichever section
|
|
@@ -451,12 +453,7 @@ export function mergeTopic(base, overlay) {
|
|
|
451
453
|
: section;
|
|
452
454
|
}
|
|
453
455
|
}
|
|
454
|
-
return {
|
|
455
|
-
...base,
|
|
456
|
-
title: overlay.title || base.title,
|
|
457
|
-
description: overlay.description || base.description,
|
|
458
|
-
sections,
|
|
459
|
-
};
|
|
456
|
+
return {...base, sections};
|
|
460
457
|
}
|
|
461
458
|
|
|
462
459
|
/**
|
|
@@ -491,7 +488,7 @@ function findMergeTarget(sections, section) {
|
|
|
491
488
|
const sameTitle = sections.findIndex(
|
|
492
489
|
candidate => sourceTitle(candidate) === title,
|
|
493
490
|
);
|
|
494
|
-
return sameTitle
|
|
491
|
+
return sameTitle;
|
|
495
492
|
}
|
|
496
493
|
|
|
497
494
|
/**
|
|
@@ -180,7 +180,7 @@ describe('discoverIntegrationDocs', () => {
|
|
|
180
180
|
}),
|
|
181
181
|
);
|
|
182
182
|
expect(records).toEqual([]);
|
|
183
|
-
expect(errors[0].message).toContain('
|
|
183
|
+
expect(errors[0].message).toContain('Invalid discriminator value');
|
|
184
184
|
});
|
|
185
185
|
|
|
186
186
|
it('names a namespace doc instead of listing topic fields it lacks', async () => {
|
|
@@ -505,11 +505,14 @@ describe('mergeTopic', () => {
|
|
|
505
505
|
]);
|
|
506
506
|
});
|
|
507
507
|
|
|
508
|
-
it('
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
'
|
|
512
|
-
|
|
508
|
+
it('keeps the base title and description: an extension never renames a topic', () => {
|
|
509
|
+
const merged = mergeTopic(base, {
|
|
510
|
+
title: 'Acme theme notes',
|
|
511
|
+
description: 'Our additions.',
|
|
512
|
+
sections: [],
|
|
513
|
+
});
|
|
514
|
+
expect(merged.title).toBe('Theme');
|
|
515
|
+
expect(merged.description).toBe('Theming.');
|
|
513
516
|
});
|
|
514
517
|
});
|
|
515
518
|
|
|
@@ -526,12 +529,10 @@ describe('problemsInTopic section keys', () => {
|
|
|
526
529
|
})),
|
|
527
530
|
});
|
|
528
531
|
|
|
529
|
-
it('
|
|
532
|
+
it('keeps legacy title-only key conflicts readable', () => {
|
|
530
533
|
expect(
|
|
531
534
|
problemsInTopic(doc([{title: 'Quick Start'}, {title: 'Quick-start'}])),
|
|
532
|
-
).toEqual([
|
|
533
|
-
expect.stringContaining('"quick-start" is already used by sections[0]'),
|
|
534
|
-
]);
|
|
535
|
+
).toEqual([]);
|
|
535
536
|
});
|
|
536
537
|
|
|
537
538
|
it('rejects an unsafe id', () => {
|
|
@@ -540,10 +541,8 @@ describe('problemsInTopic section keys', () => {
|
|
|
540
541
|
).toEqual([expect.stringContaining('is not a stable key')]);
|
|
541
542
|
});
|
|
542
543
|
|
|
543
|
-
it('
|
|
544
|
-
expect(problemsInTopic(doc([{title: '亮/暗模式'}]))).toEqual([
|
|
545
|
-
expect.stringContaining('Give the section an id'),
|
|
546
|
-
]);
|
|
544
|
+
it('keeps a legacy title that has no derived key readable', () => {
|
|
545
|
+
expect(problemsInTopic(doc([{title: '亮/暗模式'}]))).toEqual([]);
|
|
547
546
|
expect(
|
|
548
547
|
problemsInTopic(doc([{id: 'light-dark', title: '亮/暗模式'}])),
|
|
549
548
|
).toEqual([]);
|
|
@@ -577,7 +576,7 @@ describe('mergeTopic by section key', () => {
|
|
|
577
576
|
]);
|
|
578
577
|
});
|
|
579
578
|
|
|
580
|
-
it('
|
|
579
|
+
it('keeps a legacy title variant as a separate section', () => {
|
|
581
580
|
const merged = mergeTopic(base, {
|
|
582
581
|
sections: [
|
|
583
582
|
{title: 'Light-Dark Mode', content: [{type: 'prose', text: 'acme'}]},
|
|
@@ -585,6 +584,7 @@ describe('mergeTopic by section key', () => {
|
|
|
585
584
|
});
|
|
586
585
|
expect(titles(merged)).toEqual([
|
|
587
586
|
[null, 'Quick Start', 'base'],
|
|
587
|
+
[null, 'Light/Dark Mode', 'base'],
|
|
588
588
|
[null, 'Light-Dark Mode', 'acme'],
|
|
589
589
|
]);
|
|
590
590
|
});
|
|
@@ -31,9 +31,17 @@ export function sectionTitleKey(title: unknown): string;
|
|
|
31
31
|
*/
|
|
32
32
|
export function sectionKey(section: any): string;
|
|
33
33
|
/**
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
34
|
+
* Fatal key problems: only an explicitly authored `id` can make a previously
|
|
35
|
+
* readable topic invalid. Derived-key collisions and titles with no Latin
|
|
36
|
+
* letters or digits are handled by {@link withSectionKeys} for 0.6.x
|
|
37
|
+
* compatibility.
|
|
38
|
+
* @param {any[]} sections
|
|
39
|
+
* @returns {string[]}
|
|
40
|
+
*/
|
|
41
|
+
export function sectionKeyErrors(sections: any[]): string[];
|
|
42
|
+
/**
|
|
43
|
+
* Compatibility notices for section keys. These inputs loaded in 0.6.x, so
|
|
44
|
+
* readers keep accepting them and assign deterministic fallback keys.
|
|
37
45
|
* @param {any[]} sections
|
|
38
46
|
* @returns {string[]}
|
|
39
47
|
*/
|
|
@@ -49,13 +57,16 @@ export function withSectionKeys<T extends {
|
|
|
49
57
|
sections: any[];
|
|
50
58
|
}>(doc: T): T;
|
|
51
59
|
/**
|
|
52
|
-
* Find the section a reader asked for
|
|
53
|
-
*
|
|
54
|
-
*
|
|
60
|
+
* Find the section a reader asked for. The 0.6.x first-match title-substring
|
|
61
|
+
* lookup remains first in the authored-title view. In a localized view, an
|
|
62
|
+
* exact stable key resolves before translated title substrings because those
|
|
63
|
+
* translations cannot participate in language-stable key allocation. Generated
|
|
64
|
+
* keys avoid authored-title conflicts, and authored IDs that would shadow an
|
|
65
|
+
* authored legacy query are rejected.
|
|
55
66
|
* @param {any[]} sections
|
|
56
67
|
* @param {string} query
|
|
57
|
-
* @returns {{section: any | null, candidates: any[]}} `candidates` lists
|
|
58
|
-
*
|
|
68
|
+
* @returns {{section: any | null, candidates: any[]}} `candidates` lists every
|
|
69
|
+
* legacy title match when the query is ambiguous
|
|
59
70
|
*/
|
|
60
71
|
export function findDocSection(sections: any[], query: string): {
|
|
61
72
|
section: any | null;
|