mdx-artifacts 0.1.2 → 0.2.0
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 +211 -59
- package/README.zh-CN.md +299 -42
- package/agents/AGENTS.snippet.md +21 -10
- package/artifact-docs/examples/commentable-feedback.mdx +76 -70
- package/artifact-docs/examples/decision-matrix.mdx +122 -50
- package/artifact-docs/examples/layout-composition.mdx +106 -128
- package/artifact-docs/examples/streamlit-style-mixed.mdx +100 -85
- package/dist/lib/cli/{build.js → commands/build.js} +2 -2
- package/dist/lib/cli/{components.js → commands/components.js} +19 -3
- package/dist/lib/cli/{dev.js → commands/dev.js} +2 -2
- package/dist/lib/cli/commands/interactions.d.ts +2 -0
- package/dist/lib/cli/commands/interactions.js +280 -0
- package/dist/lib/cli/commands/review.d.ts +1 -0
- package/dist/lib/cli/commands/review.js +171 -0
- package/dist/lib/cli/commands/scaffold.d.ts +16 -0
- package/dist/lib/cli/commands/scaffold.js +440 -0
- package/dist/lib/cli/commands/validate.d.ts +18 -0
- package/dist/lib/cli/commands/validate.js +311 -0
- package/dist/lib/cli/config/config.d.ts +2 -0
- package/dist/lib/cli/{config.js → config/config.js} +3 -2
- package/dist/lib/cli/{types.d.ts → config/types.d.ts} +2 -1
- package/dist/lib/cli/{vite-artifact.d.ts → dev-server/vite-artifact.d.ts} +3 -3
- package/dist/lib/cli/{vite-artifact.js → dev-server/vite-artifact.js} +170 -10
- package/dist/lib/cli/diagnostics/diagnostics.d.ts +11 -0
- package/dist/lib/cli/diagnostics/diagnostics.js +1 -0
- package/dist/lib/cli/index.js +39 -18
- package/dist/lib/cli/mdx/sortable-list.d.ts +14 -0
- package/dist/lib/cli/mdx/sortable-list.js +520 -0
- package/dist/lib/cli/resources/resource-policy.d.ts +15 -0
- package/dist/lib/cli/resources/resource-policy.js +46 -0
- package/dist/lib/cli/resources/safe-path.d.ts +13 -0
- package/dist/lib/cli/resources/safe-path.js +55 -0
- package/dist/lib/cli/services/interaction-service.d.ts +40 -0
- package/dist/lib/cli/services/interaction-service.js +226 -0
- package/dist/lib/cli/services/review.d.ts +43 -0
- package/dist/lib/cli/{review.js → services/review.js} +34 -172
- package/dist/lib/react/{components → composites/comparison-set}/ComparisonSet.d.ts +1 -1
- package/dist/lib/react/{components → composites/comparison-set}/ComparisonSet.js +3 -3
- package/dist/lib/react/composites/comparison-set/index.d.ts +2 -0
- package/dist/lib/react/composites/comparison-set/index.js +1 -0
- package/dist/lib/react/composites/content-set/ContentItem.d.ts +37 -0
- package/dist/lib/react/composites/content-set/ContentItem.js +49 -0
- package/dist/lib/react/composites/content-set/index.d.ts +2 -0
- package/dist/lib/react/composites/content-set/index.js +1 -0
- package/dist/lib/react/{components → composites/export-panel}/ExportPanel.js +2 -2
- package/dist/lib/react/composites/export-panel/index.d.ts +2 -0
- package/dist/lib/react/composites/export-panel/index.js +1 -0
- package/dist/lib/react/{components → composites/section}/Section.js +1 -1
- package/dist/lib/react/composites/section/index.d.ts +2 -0
- package/dist/lib/react/composites/section/index.js +1 -0
- package/dist/lib/react/index.d.ts +36 -31
- package/dist/lib/react/index.js +18 -15
- package/dist/lib/react/interactions/artifact-state/index.d.ts +1 -0
- package/dist/lib/react/interactions/artifact-state/index.js +1 -0
- package/dist/lib/react/{components → interactions/comments}/Comments.d.ts +2 -2
- package/dist/lib/react/{components → interactions/comments}/Comments.js +3 -3
- package/dist/lib/react/interactions/comments/index.d.ts +1 -0
- package/dist/lib/react/interactions/comments/index.js +1 -0
- package/dist/lib/react/interactions/sortable-list/SortableList.d.ts +29 -0
- package/dist/lib/react/interactions/sortable-list/SortableList.js +282 -0
- package/dist/lib/react/interactions/sortable-list/index.d.ts +1 -0
- package/dist/lib/react/interactions/sortable-list/index.js +1 -0
- package/dist/lib/react/layout/layout-primitives/index.d.ts +2 -0
- package/dist/lib/react/layout/layout-primitives/index.js +1 -0
- package/dist/lib/react/legacy/LegacyContentComponents.d.ts +65 -0
- package/dist/lib/react/legacy/LegacyContentComponents.js +26 -0
- package/dist/lib/react/mdx-components.d.ts +5 -0
- package/dist/lib/react/mdx-components.js +38 -0
- package/dist/lib/react/{components → primitives/annotated-code}/AnnotatedCode.d.ts +1 -1
- package/dist/lib/react/{components → primitives/annotated-code}/AnnotatedCode.js +5 -5
- package/dist/lib/react/primitives/annotated-code/index.d.ts +2 -0
- package/dist/lib/react/primitives/annotated-code/index.js +1 -0
- package/dist/lib/react/primitives/callout/Callout.d.ts +11 -0
- package/dist/lib/react/{components → primitives/callout}/Callout.js +9 -6
- package/dist/lib/react/primitives/callout/index.d.ts +2 -0
- package/dist/lib/react/primitives/callout/index.js +1 -0
- package/dist/lib/react/primitives/code-block/CodeBlock.d.ts +20 -0
- package/dist/lib/react/primitives/code-block/CodeBlock.js +32 -0
- package/dist/lib/react/primitives/code-block/index.d.ts +2 -0
- package/dist/lib/react/primitives/code-block/index.js +1 -0
- package/dist/lib/react/primitives/code-surface/CodeSurface.d.ts +11 -0
- package/dist/lib/react/primitives/code-surface/CodeSurface.js +34 -0
- package/dist/lib/react/primitives/code-surface/index.d.ts +2 -0
- package/dist/lib/react/primitives/code-surface/index.js +1 -0
- package/dist/lib/react/primitives/diff-block/DiffBlock.js +25 -0
- package/dist/lib/react/primitives/diff-block/index.d.ts +2 -0
- package/dist/lib/react/primitives/diff-block/index.js +1 -0
- package/dist/lib/react/{components → primitives/inline-text}/InlineText.d.ts +4 -2
- package/dist/lib/react/primitives/inline-text/InlineText.js +28 -0
- package/dist/lib/react/primitives/inline-text/index.d.ts +2 -0
- package/dist/lib/react/primitives/inline-text/index.js +1 -0
- package/dist/lib/react/primitives/markdown-body/MarkdownBody.d.ts +9 -0
- package/dist/lib/react/primitives/markdown-body/MarkdownBody.js +49 -0
- package/dist/lib/react/primitives/markdown-body/index.d.ts +2 -0
- package/dist/lib/react/primitives/markdown-body/index.js +1 -0
- package/dist/lib/react/primitives/severity-badge/index.d.ts +2 -0
- package/dist/lib/react/primitives/severity-badge/index.js +1 -0
- package/dist/lib/react/registry.d.ts +10 -0
- package/dist/lib/react/registry.js +505 -210
- package/dist/lib/react/styles.css +490 -38
- package/docs/cli-structure.md +141 -0
- package/docs/component-protocol.md +199 -33
- package/docs/component-taxonomy.md +40 -4
- package/docs/design.md +42 -21
- package/docs/design.zh-CN.md +41 -21
- package/docs/naming.md +17 -7
- package/docs/releasing.md +132 -0
- package/docs/testing.md +35 -10
- package/package.json +9 -7
- package/dist/lib/cli/config.d.ts +0 -2
- package/dist/lib/cli/review.d.ts +0 -33
- package/dist/lib/cli/scaffold.d.ts +0 -1
- package/dist/lib/cli/scaffold.js +0 -56
- package/dist/lib/cli/validate.d.ts +0 -6
- package/dist/lib/cli/validate.js +0 -79
- package/dist/lib/react/components/Callout.d.ts +0 -9
- package/dist/lib/react/components/CodeBlock.d.ts +0 -10
- package/dist/lib/react/components/CodeBlock.js +0 -28
- package/dist/lib/react/components/DecisionMatrix.d.ts +0 -16
- package/dist/lib/react/components/DecisionMatrix.js +0 -27
- package/dist/lib/react/components/DiffBlock.js +0 -24
- package/dist/lib/react/components/InlineText.js +0 -18
- package/dist/lib/react/components/MarkdownBody.d.ts +0 -7
- package/dist/lib/react/components/MarkdownBody.js +0 -36
- package/dist/lib/react/components/OptionGrid.d.ts +0 -13
- package/dist/lib/react/components/OptionGrid.js +0 -21
- /package/dist/lib/cli/{build.d.ts → commands/build.d.ts} +0 -0
- /package/dist/lib/cli/{components.d.ts → commands/components.d.ts} +0 -0
- /package/dist/lib/cli/{dev.d.ts → commands/dev.d.ts} +0 -0
- /package/dist/lib/cli/{types.js → config/types.js} +0 -0
- /package/dist/lib/cli/{artifact-state.d.ts → state/artifact-state.d.ts} +0 -0
- /package/dist/lib/cli/{artifact-state.js → state/artifact-state.js} +0 -0
- /package/dist/lib/react/{components → composites/export-panel}/ExportPanel.d.ts +0 -0
- /package/dist/lib/react/{components → composites/section}/Section.d.ts +0 -0
- /package/dist/lib/react/{components → interactions/artifact-state}/ArtifactState.d.ts +0 -0
- /package/dist/lib/react/{components → interactions/artifact-state}/ArtifactState.js +0 -0
- /package/dist/lib/react/{components → layout/layout-primitives}/Layout.d.ts +0 -0
- /package/dist/lib/react/{components → layout/layout-primitives}/Layout.js +0 -0
- /package/dist/lib/react/{components → primitives/diff-block}/DiffBlock.d.ts +0 -0
- /package/dist/lib/react/{components → primitives/severity-badge}/SeverityBadge.d.ts +0 -0
- /package/dist/lib/react/{components → primitives/severity-badge}/SeverityBadge.js +0 -0
package/docs/design.zh-CN.md
CHANGED
|
@@ -37,13 +37,14 @@ HTML artifact 的价值不在于替代 Markdown,而在于把一些阅读、比
|
|
|
37
37
|
|
|
38
38
|
- `InlineText`:单行短文本,支持受控 inline Markdown。
|
|
39
39
|
- `MarkdownBody`:组件内部正文,支持受控 block Markdown。
|
|
40
|
-
- `
|
|
41
|
-
- `
|
|
40
|
+
- `ContentItem`:独立可读内容卡片。
|
|
41
|
+
- `ContentSet`:带 tone 和 emphasis 的成组内容卡片。
|
|
42
|
+
- `SortableList`:可拖拽的结构化优先级列表,保存用户排序结果。
|
|
42
43
|
- `ExportPanel`:导出 Markdown / JSON。
|
|
43
44
|
|
|
44
45
|
后续组件:
|
|
45
46
|
|
|
46
|
-
- `
|
|
47
|
+
- `KanbanBoard`:按列组织的卡片排序。
|
|
47
48
|
- `PromptWorkbench`:提示词变量和样例预览。
|
|
48
49
|
- `DiffExplainer`:PR / diff 解释。
|
|
49
50
|
- `ParameterTuner`:参数调试器。
|
|
@@ -107,30 +108,34 @@ Astro 的代价:
|
|
|
107
108
|
|
|
108
109
|
## 样式协议
|
|
109
110
|
|
|
110
|
-
|
|
111
|
+
MDX Artifacts 提供默认 CSS,但默认样式不是闭环的一部分。
|
|
111
112
|
|
|
112
|
-
使用者可以通过 `
|
|
113
|
+
使用者可以通过 `mdx-artifacts.config.mjs` 注入品牌样式:
|
|
113
114
|
|
|
114
|
-
```
|
|
115
|
+
```js
|
|
116
|
+
/** @type {import("mdx-artifacts").MdxArtifactsConfig} */
|
|
115
117
|
const config = {
|
|
116
118
|
docsDir: "artifact-docs",
|
|
117
119
|
outDir: "dist/artifacts",
|
|
118
120
|
includeDefaultStyles: true,
|
|
119
|
-
styles: ["artifact-theme.css"]
|
|
121
|
+
styles: ["artifact-theme.css"],
|
|
122
|
+
tailwindSources: ["artifact-components/**/*.{ts,tsx}"]
|
|
120
123
|
};
|
|
121
124
|
```
|
|
122
125
|
|
|
123
126
|
约定:
|
|
124
127
|
|
|
125
|
-
- `includeDefaultStyles: true` 时,先导入
|
|
128
|
+
- `includeDefaultStyles: true` 时,先导入 MDX Artifacts 默认样式。
|
|
126
129
|
- `styles` 按数组顺序在默认样式之后导入。
|
|
127
130
|
- 使用者可以通过覆盖 CSS variables 或 `ak-*` class 调整品牌。
|
|
128
|
-
- `includeDefaultStyles: false`
|
|
131
|
+
- `includeDefaultStyles: false` 表示关闭 MDX Artifacts 默认样式。
|
|
132
|
+
- 当前 MDX 文件会自动注册为 Tailwind source,用于支持本地 MDX 组件。
|
|
133
|
+
- `tailwindSources` 用于注册额外的项目本地组件文件。
|
|
129
134
|
- CLI 构建仍会把最终 CSS 内联到单文件 HTML。
|
|
130
135
|
|
|
131
136
|
### Tailwind 的角色
|
|
132
137
|
|
|
133
|
-
Tailwind 是
|
|
138
|
+
Tailwind 是 mdx-artifacts 内部的样式生产工具,不要求用户项目自己配置 Tailwind。
|
|
134
139
|
|
|
135
140
|
### Radix 的角色
|
|
136
141
|
|
|
@@ -153,8 +158,8 @@ Storybook 不负责:
|
|
|
153
158
|
|
|
154
159
|
```text
|
|
155
160
|
组件开发:pnpm storybook
|
|
156
|
-
协议验证:pnpm typecheck / pnpm test / pnpm
|
|
157
|
-
artifact 验证:pnpm
|
|
161
|
+
协议验证:pnpm typecheck / pnpm test / pnpm mdx-artifacts:validate
|
|
162
|
+
artifact 验证:pnpm mdx-artifacts:build
|
|
158
163
|
```
|
|
159
164
|
|
|
160
165
|
## 测试协议
|
|
@@ -175,7 +180,9 @@ artifact 验证:pnpm artifact:build
|
|
|
175
180
|
- 浏览器 E2E
|
|
176
181
|
- 视觉回归
|
|
177
182
|
- Astro adapter 测试
|
|
178
|
-
- npm tarball 安装 smoke test
|
|
183
|
+
- 默认 `pnpm check` 中的 npm tarball 安装 smoke test
|
|
184
|
+
|
|
185
|
+
Package readiness 由单独命令覆盖:`pnpm release:check`、`pnpm pack:smoke`,以及发布前手动 `npm pack --dry-run`。
|
|
179
186
|
|
|
180
187
|
## Agent 使用约定
|
|
181
188
|
|
|
@@ -185,24 +192,37 @@ Agent 生成 artifact 时应该遵守:
|
|
|
185
192
|
2. 优先使用已有高阶组件,不临时重写同类 UI。
|
|
186
193
|
3. 交互型 artifact 必须提供导出入口。
|
|
187
194
|
4. 大型数据后续应拆到相邻 `.json`。
|
|
188
|
-
5. 不确定组件参数时运行 `
|
|
189
|
-
6. 需要机器可读元数据时运行 `
|
|
190
|
-
7. 构建前运行 `
|
|
191
|
-
8. 单页输出运行 `
|
|
195
|
+
5. 不确定组件参数时运行 `mdx-artifacts components <ComponentName>`。
|
|
196
|
+
6. 需要机器可读元数据时运行 `mdx-artifacts components --json`。
|
|
197
|
+
7. 构建前运行 `mdx-artifacts validate <file.mdx>`。
|
|
198
|
+
8. 单页输出运行 `mdx-artifacts build <file.mdx>`。
|
|
192
199
|
|
|
193
200
|
## CLI 查询协议
|
|
194
201
|
|
|
195
202
|
为了减少 skill、AGENTS.md、CLAUDE.md 中的冗余组件说明,CLI 提供组件查询能力:
|
|
196
203
|
|
|
197
204
|
```bash
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
205
|
+
mdx-artifacts components
|
|
206
|
+
mdx-artifacts components ExportPanel
|
|
207
|
+
mdx-artifacts components --json
|
|
208
|
+
mdx-artifacts components ExportPanel --json
|
|
202
209
|
```
|
|
203
210
|
|
|
204
211
|
查询数据来自 `componentRegistry`,未来应同时服务 CLI 查询、Storybook docs、validate 规则和 Agent skill 说明。
|
|
205
212
|
|
|
213
|
+
## 包边界
|
|
214
|
+
|
|
215
|
+
当前继续保持单个 npm 包。
|
|
216
|
+
|
|
217
|
+
这个包通过不同入口暴露当前稳定表面:
|
|
218
|
+
|
|
219
|
+
- `mdx-artifacts`:CLI。
|
|
220
|
+
- `mdx-artifacts/react`:React components。
|
|
221
|
+
- `mdx-artifacts/registry`:组件 registry metadata。
|
|
222
|
+
- `mdx-artifacts/styles.css`:默认样式。
|
|
223
|
+
|
|
224
|
+
暂不拆成 `@mdx-artifacts/react`、`@mdx-artifacts/cli` 或 `@mdx-artifacts/schema`。只有当独立版本、依赖隔离、adapter 发布节奏成为真实维护压力时,再重新评估拆包。当前优先保持安装、初始化和 agent guidance 简单。
|
|
225
|
+
|
|
206
226
|
## 公开路线图与本地执行记录
|
|
207
227
|
|
|
208
228
|
公开项目方向放在:
|
package/docs/naming.md
CHANGED
|
@@ -8,8 +8,8 @@ Use `PascalCase`.
|
|
|
8
8
|
|
|
9
9
|
Component names should describe the artifact workflow:
|
|
10
10
|
|
|
11
|
-
- `
|
|
12
|
-
- `
|
|
11
|
+
- `ContentSet`
|
|
12
|
+
- `ContentItem`
|
|
13
13
|
- `ExportPanel`
|
|
14
14
|
- `InlineText`
|
|
15
15
|
- `MarkdownBody`
|
|
@@ -29,7 +29,9 @@ Use a small shared vocabulary:
|
|
|
29
29
|
|
|
30
30
|
- `title`: short title, usually `inlineMarkdown`
|
|
31
31
|
- `subtitle`: secondary short title, usually `inlineMarkdown`
|
|
32
|
-
- `
|
|
32
|
+
- `badge`: short display label, usually `plainText`
|
|
33
|
+
- `summary`: one-line explanation, usually `inlineMarkdown`
|
|
34
|
+
- `description`: short explanation for non-content metadata only, usually `plainText`
|
|
33
35
|
- `caption`: auxiliary note, usually `inlineMarkdown`
|
|
34
36
|
- `text`: primary field for `InlineText`
|
|
35
37
|
- `body`: primary field for `MarkdownBody` and future long-form prose components
|
|
@@ -42,6 +44,15 @@ Avoid introducing synonyms unless a component has a specific workflow reason:
|
|
|
42
44
|
- `details`
|
|
43
45
|
- `richText`
|
|
44
46
|
|
|
47
|
+
For content components, prefer the display slot model:
|
|
48
|
+
|
|
49
|
+
- `title`
|
|
50
|
+
- `badge`
|
|
51
|
+
- `summary`
|
|
52
|
+
- `children`
|
|
53
|
+
|
|
54
|
+
Do not introduce component-specific aliases such as `name`, `intent`, `verdict`, or `tradeoffs` unless the component has a clear workflow reason and the field is not just a display slot.
|
|
55
|
+
|
|
45
56
|
## Content Types
|
|
46
57
|
|
|
47
58
|
The registry can label prop content with these content types:
|
|
@@ -55,8 +66,8 @@ The registry can label prop content with these content types:
|
|
|
55
66
|
Agents should inspect content types through:
|
|
56
67
|
|
|
57
68
|
```bash
|
|
58
|
-
|
|
59
|
-
|
|
69
|
+
mdx-artifacts components <ComponentName>
|
|
70
|
+
mdx-artifacts components <ComponentName> --json
|
|
60
71
|
```
|
|
61
72
|
|
|
62
73
|
## Complex Prop Types
|
|
@@ -67,7 +78,6 @@ If a prop type references a named object or object array, add `types` metadata i
|
|
|
67
78
|
|
|
68
79
|
Examples:
|
|
69
80
|
|
|
70
|
-
- `DecisionMatrixOption[]` requires a `DecisionMatrixOption` type entry.
|
|
71
81
|
- `DiffLine[]` requires a `DiffLine` type entry.
|
|
72
82
|
- `CodeAnnotation[]` requires a `CodeAnnotation` type entry.
|
|
73
83
|
|
|
@@ -111,7 +121,7 @@ For main artifact structure, prefer component title props or `InlineText as="h2"
|
|
|
111
121
|
Use:
|
|
112
122
|
|
|
113
123
|
```tsx
|
|
114
|
-
<InlineText as="h3"
|
|
124
|
+
<InlineText as="h3">**Recommended option**</InlineText>
|
|
115
125
|
```
|
|
116
126
|
|
|
117
127
|
Avoid:
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Releasing
|
|
2
|
+
|
|
3
|
+
This project currently uses manual npm publishing.
|
|
4
|
+
|
|
5
|
+
CI and release checks are quality gates. They do not publish the package and they do not configure an npm token.
|
|
6
|
+
|
|
7
|
+
## Release Model
|
|
8
|
+
|
|
9
|
+
- Publish from a clean local checkout.
|
|
10
|
+
- Keep `mdx-artifacts` as a single npm package.
|
|
11
|
+
- Use CI, `release:check`, `pack:smoke`, and `npm pack --dry-run` as pre-publish gates.
|
|
12
|
+
- Run `npm publish` manually only after the package contents and version are confirmed.
|
|
13
|
+
|
|
14
|
+
## Before Publishing
|
|
15
|
+
|
|
16
|
+
1. Confirm the worktree is clean.
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
git status --short
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
2. Confirm the version in `package.json` is the version intended for npm.
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
node -p "require('./package.json').version"
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
3. Confirm CI has passed for the commit being published.
|
|
29
|
+
|
|
30
|
+
If CI is not available yet, run the local gates below and treat the publish as local-manual.
|
|
31
|
+
|
|
32
|
+
4. Run the default validation baseline.
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pnpm check
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
5. Run the lightweight release gate.
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
pnpm release:check
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
6. Run the package smoke test.
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
pnpm pack:smoke
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
7. Run the final npm pack dry run.
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
npm pack --dry-run --cache /private/tmp/mdx-artifacts-npm-cache
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
8. Inspect the dry-run output.
|
|
57
|
+
|
|
58
|
+
Confirm the tarball includes expected files such as:
|
|
59
|
+
|
|
60
|
+
- `dist/lib`
|
|
61
|
+
- `agents/AGENTS.snippet.md`
|
|
62
|
+
- `artifact-docs/examples/*.mdx`
|
|
63
|
+
- `docs/*.md`
|
|
64
|
+
- `README.md`
|
|
65
|
+
- `README.zh-CN.md`
|
|
66
|
+
- `LICENSE`
|
|
67
|
+
|
|
68
|
+
Confirm the tarball does not include:
|
|
69
|
+
|
|
70
|
+
- `src/`
|
|
71
|
+
- `docs/local/`
|
|
72
|
+
- `.storybook/`
|
|
73
|
+
- Storybook stories
|
|
74
|
+
- sourcemaps
|
|
75
|
+
- `node_modules/`
|
|
76
|
+
- generated `dist/artifacts`
|
|
77
|
+
- `.state.json`
|
|
78
|
+
- `.local.*`
|
|
79
|
+
- `.log`
|
|
80
|
+
- `.tgz`
|
|
81
|
+
|
|
82
|
+
## Publishing
|
|
83
|
+
|
|
84
|
+
1. Confirm npm authentication.
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
npm whoami
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
2. Publish the package.
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
npm publish
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Do not publish if any pre-publish gate failed or if the dry-run tarball contains unexpected files.
|
|
97
|
+
|
|
98
|
+
## After Publishing
|
|
99
|
+
|
|
100
|
+
1. Confirm npm shows the expected version.
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
npm view mdx-artifacts version
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
2. Smoke test the published package from a temporary project.
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
mkdir -p /private/tmp/mdx-artifacts-published-smoke
|
|
110
|
+
cd /private/tmp/mdx-artifacts-published-smoke
|
|
111
|
+
npm init -y
|
|
112
|
+
npm install --save-dev mdx-artifacts
|
|
113
|
+
npx mdx-artifacts init --yes
|
|
114
|
+
npx mdx-artifacts validate artifact-docs/examples/hello.mdx
|
|
115
|
+
npx mdx-artifacts build artifact-docs/examples/hello.mdx
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
3. If the post-publish smoke test fails, do not overwrite the published version.
|
|
119
|
+
|
|
120
|
+
Publish a follow-up patch version with a fix instead.
|
|
121
|
+
|
|
122
|
+
## Not Automated Yet
|
|
123
|
+
|
|
124
|
+
These steps are intentionally not automated yet:
|
|
125
|
+
|
|
126
|
+
- npm token setup
|
|
127
|
+
- GitHub release creation
|
|
128
|
+
- changelog generation
|
|
129
|
+
- version bump automation
|
|
130
|
+
- tag-based publishing
|
|
131
|
+
|
|
132
|
+
Add those only when manual publishing becomes a real bottleneck.
|
package/docs/testing.md
CHANGED
|
@@ -14,7 +14,7 @@ This runs:
|
|
|
14
14
|
|
|
15
15
|
1. `pnpm typecheck`
|
|
16
16
|
2. `pnpm test`
|
|
17
|
-
3. `pnpm
|
|
17
|
+
3. `pnpm mdx-artifacts:validate`
|
|
18
18
|
|
|
19
19
|
Current test coverage:
|
|
20
20
|
|
|
@@ -26,9 +26,26 @@ Current test coverage:
|
|
|
26
26
|
Current test files:
|
|
27
27
|
|
|
28
28
|
- `src/react/registry.test.ts`
|
|
29
|
-
- `src/react/
|
|
29
|
+
- `src/react/primitives/markdown-body/text-components.test.tsx`
|
|
30
30
|
- `src/cli/components.test.ts`
|
|
31
|
-
- `src/cli/validate.test.ts`
|
|
31
|
+
- `src/cli/commands/validate.test.ts`
|
|
32
|
+
|
|
33
|
+
## Release Check
|
|
34
|
+
|
|
35
|
+
Run the release check before publishing or after changes to package metadata, public docs, agent guidance, examples, or release scripts:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pnpm release:check
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The release check is a lightweight static gate. It does not build the package and does not publish to npm.
|
|
42
|
+
|
|
43
|
+
It verifies:
|
|
44
|
+
|
|
45
|
+
- `package.json` `files` matches the intended publish allowlist
|
|
46
|
+
- package file candidates do not include forbidden paths such as `src/`, `docs/local/`, `.state.json`, `.local.*`, logs, tarballs, sourcemaps, Storybook output, or generated artifacts
|
|
47
|
+
- public English/code files do not contain Han characters
|
|
48
|
+
- public files do not contain legacy package naming
|
|
32
49
|
|
|
33
50
|
## Package Smoke Test
|
|
34
51
|
|
|
@@ -41,14 +58,22 @@ pnpm pack:smoke
|
|
|
41
58
|
The smoke test creates an npm tarball, installs it into a temporary project, and verifies:
|
|
42
59
|
|
|
43
60
|
- `import("mdx-artifacts/react")`
|
|
44
|
-
- `
|
|
45
|
-
- `
|
|
46
|
-
- `
|
|
47
|
-
- `
|
|
61
|
+
- `mdx-artifacts components`
|
|
62
|
+
- `mdx-artifacts init`
|
|
63
|
+
- `mdx-artifacts validate artifact-docs/examples/hello.mdx`
|
|
64
|
+
- `mdx-artifacts build artifact-docs/examples/hello.mdx`
|
|
65
|
+
- `mdx-artifacts dev artifact-docs/examples/hello.mdx`
|
|
66
|
+
- `mdx-artifacts review validate`
|
|
67
|
+
- `mdx-artifacts review add`
|
|
68
|
+
- `mdx-artifacts review reply`
|
|
69
|
+
|
|
70
|
+
It also checks that:
|
|
48
71
|
|
|
49
|
-
|
|
72
|
+
- the tarball does not include `src/`, `docs/local/`, `.state.json`, or `.local.*` files
|
|
73
|
+
- the temporary project can install only the `mdx-artifacts` tarball without explicitly adding `react` or `react-dom`
|
|
74
|
+
- dev server MDX imports and the generated artifact shell resolve `mdx-artifacts/react` to the same package entry, so comment context is not split by dependency prebundling
|
|
50
75
|
|
|
51
|
-
This smoke test
|
|
76
|
+
This smoke test proves that the published package can be installed, imported, initialized, validated, built, served in dev mode, and used with review-state commands. It does not yet cover a real browser click-through of the review UI or multi-artifact workspaces.
|
|
52
77
|
|
|
53
78
|
## When Adding a Component
|
|
54
79
|
|
|
@@ -114,7 +139,7 @@ These checks are not part of the current default baseline:
|
|
|
114
139
|
- visual regression
|
|
115
140
|
- Storybook test runner
|
|
116
141
|
- Astro adapter tests
|
|
117
|
-
- `
|
|
142
|
+
- `mdx-artifacts:build`
|
|
118
143
|
- `npm pack --dry-run`
|
|
119
144
|
|
|
120
145
|
Use them before npm publishing or when the changed behavior touches packaging, standalone HTML output, browser-only APIs, or future docs-site adapters.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mdx-artifacts",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Build interactive MDX artifacts with reusable React components and a local CLI.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -41,23 +41,24 @@
|
|
|
41
41
|
"./styles.css": "./dist/lib/react/styles.css"
|
|
42
42
|
},
|
|
43
43
|
"bin": {
|
|
44
|
-
"
|
|
44
|
+
"mdx-artifacts": "dist/lib/cli/index.js"
|
|
45
45
|
},
|
|
46
46
|
"scripts": {
|
|
47
|
-
"
|
|
48
|
-
"
|
|
49
|
-
"
|
|
50
|
-
"
|
|
47
|
+
"mdx-artifacts": "tsx src/cli/index.ts",
|
|
48
|
+
"mdx-artifacts:dev": "tsx src/cli/index.ts dev artifact-docs/examples/decision-matrix.mdx",
|
|
49
|
+
"mdx-artifacts:build": "tsx src/cli/index.ts build artifact-docs/examples/decision-matrix.mdx",
|
|
50
|
+
"mdx-artifacts:validate": "tsx src/cli/index.ts validate artifact-docs/examples/decision-matrix.mdx",
|
|
51
51
|
"storybook": "storybook dev -p 6106 --no-open",
|
|
52
52
|
"test": "vitest run",
|
|
53
53
|
"test:watch": "vitest",
|
|
54
|
-
"check": "pnpm typecheck && pnpm test && pnpm
|
|
54
|
+
"check": "pnpm typecheck && pnpm test && pnpm mdx-artifacts:validate",
|
|
55
55
|
"typecheck": "tsc --noEmit",
|
|
56
56
|
"clean:lib": "rm -rf dist/lib",
|
|
57
57
|
"build:lib": "tsc -p tsconfig.build.json",
|
|
58
58
|
"build:esm": "node scripts/fix-dist-esm.mjs",
|
|
59
59
|
"build:styles": "cp src/react/styles.css dist/lib/react/styles.css",
|
|
60
60
|
"build:cli": "pnpm clean:lib && pnpm build:lib && pnpm build:esm && pnpm build:styles",
|
|
61
|
+
"release:check": "node scripts/check-release.mjs",
|
|
61
62
|
"pack:smoke": "node scripts/pack-smoke.mjs",
|
|
62
63
|
"prepack": "pnpm build:cli"
|
|
63
64
|
},
|
|
@@ -76,6 +77,7 @@
|
|
|
76
77
|
"react-dom": ">=18.3.0 <20"
|
|
77
78
|
},
|
|
78
79
|
"devDependencies": {
|
|
80
|
+
"@storybook/addon-docs": "10.3.6",
|
|
79
81
|
"@storybook/react-vite": "^10.3.6",
|
|
80
82
|
"@types/node": "^22.0.0",
|
|
81
83
|
"@types/react": "^19.0.0",
|
package/dist/lib/cli/config.d.ts
DELETED
package/dist/lib/cli/review.d.ts
DELETED
|
@@ -1,33 +0,0 @@
|
|
|
1
|
-
type ReviewReply = {
|
|
2
|
-
threadId: string;
|
|
3
|
-
body: string;
|
|
4
|
-
};
|
|
5
|
-
type ReviewAddOptions = {
|
|
6
|
-
anchorId: string;
|
|
7
|
-
body: string;
|
|
8
|
-
title?: string;
|
|
9
|
-
};
|
|
10
|
-
type ReviewReplyOptions = {
|
|
11
|
-
replies: ReviewReply[];
|
|
12
|
-
status?: string;
|
|
13
|
-
};
|
|
14
|
-
export type ReviewValidationResult = {
|
|
15
|
-
anchorCount: number;
|
|
16
|
-
missingThreads: ReviewMissingThread[];
|
|
17
|
-
output: string;
|
|
18
|
-
threadCount: number;
|
|
19
|
-
};
|
|
20
|
-
export type ReviewMissingThread = {
|
|
21
|
-
anchorId: string;
|
|
22
|
-
threadId: string;
|
|
23
|
-
title?: string;
|
|
24
|
-
status?: string;
|
|
25
|
-
};
|
|
26
|
-
export declare function reviewCommand(projectRoot: string, args: string[]): Promise<void>;
|
|
27
|
-
export declare function addReviewThread(projectRoot: string, input: string, options: ReviewAddOptions): Promise<string>;
|
|
28
|
-
export declare function replyToReviewThread(projectRoot: string, input: string, options: ReviewReply & {
|
|
29
|
-
status?: string;
|
|
30
|
-
}): Promise<string>;
|
|
31
|
-
export declare function replyToReviewThreads(projectRoot: string, input: string, options: ReviewReplyOptions): Promise<string>;
|
|
32
|
-
export declare function validateReviewState(projectRoot: string, input: string): Promise<ReviewValidationResult>;
|
|
33
|
-
export {};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export declare function initProject(projectRoot: string): Promise<void>;
|
package/dist/lib/cli/scaffold.js
DELETED
|
@@ -1,56 +0,0 @@
|
|
|
1
|
-
import { mkdir, writeFile } from "node:fs/promises";
|
|
2
|
-
import path from "node:path";
|
|
3
|
-
export async function initProject(projectRoot) {
|
|
4
|
-
const docsDir = path.join(projectRoot, "artifact-docs", "examples");
|
|
5
|
-
const agentsDir = path.join(projectRoot, "agents");
|
|
6
|
-
await mkdir(docsDir, { recursive: true });
|
|
7
|
-
await mkdir(agentsDir, { recursive: true });
|
|
8
|
-
await writeFile(path.join(projectRoot, "artifact-kit.config.mjs"), `/** @type {import("mdx-artifacts").ArtifactKitConfig} */
|
|
9
|
-
const config = {
|
|
10
|
-
docsDir: "artifact-docs",
|
|
11
|
-
outDir: "dist/artifacts",
|
|
12
|
-
includeDefaultStyles: true,
|
|
13
|
-
styles: []
|
|
14
|
-
};
|
|
15
|
-
|
|
16
|
-
export default config;
|
|
17
|
-
`, { flag: "wx" }).catch(ignoreExisting);
|
|
18
|
-
await writeFile(path.join(agentsDir, "AGENTS.snippet.md"), `# Artifact Kit Agent Instructions
|
|
19
|
-
|
|
20
|
-
1. Create .mdx files under artifact-docs/.
|
|
21
|
-
2. Prefer Artifact Kit high-level components. Do not generate raw HTML unless explicitly requested.
|
|
22
|
-
3. Interactive artifacts must include ExportPanel or an equivalent export path.
|
|
23
|
-
4. Run artifact-kit components <ComponentName> when component props are unclear.
|
|
24
|
-
5. Run artifact-kit validate <file.mdx> before build.
|
|
25
|
-
6. Run artifact-kit build <file.mdx> to produce standalone HTML.
|
|
26
|
-
`, { flag: "wx" }).catch(ignoreExisting);
|
|
27
|
-
await writeFile(path.join(docsDir, "hello.mdx"), `import { DecisionMatrix, ExportPanel } from "mdx-artifacts/react";
|
|
28
|
-
|
|
29
|
-
# Hello Artifact
|
|
30
|
-
|
|
31
|
-
<DecisionMatrix
|
|
32
|
-
id="decision.initialized"
|
|
33
|
-
question="Has Artifact Kit been initialized?"
|
|
34
|
-
options={[
|
|
35
|
-
{
|
|
36
|
-
name: "Initialized",
|
|
37
|
-
pros: ["MDX source exists", "Export panel exists"],
|
|
38
|
-
cons: ["Real content still needs to be added"],
|
|
39
|
-
verdict: "Ready to continue generating artifacts"
|
|
40
|
-
}
|
|
41
|
-
]}
|
|
42
|
-
/>
|
|
43
|
-
|
|
44
|
-
<ExportPanel
|
|
45
|
-
value={{
|
|
46
|
-
recommendation: "Continue generating interactive HTML artifacts with MDX and high-level components"
|
|
47
|
-
}}
|
|
48
|
-
/>
|
|
49
|
-
`, { flag: "wx" }).catch(ignoreExisting);
|
|
50
|
-
console.log("Artifact Kit initialized.");
|
|
51
|
-
}
|
|
52
|
-
function ignoreExisting(error) {
|
|
53
|
-
if (error.code !== "EEXIST") {
|
|
54
|
-
throw error;
|
|
55
|
-
}
|
|
56
|
-
}
|
package/dist/lib/cli/validate.js
DELETED
|
@@ -1,79 +0,0 @@
|
|
|
1
|
-
import { readFile } from "node:fs/promises";
|
|
2
|
-
import path from "node:path";
|
|
3
|
-
import { componentRegistry } from "../react/registry.js";
|
|
4
|
-
const componentsRequiringStableId = [
|
|
5
|
-
"Section",
|
|
6
|
-
"DecisionMatrix",
|
|
7
|
-
"OptionGrid",
|
|
8
|
-
"ComparisonSet",
|
|
9
|
-
"ComparisonSet.Item",
|
|
10
|
-
"AnnotatedCode",
|
|
11
|
-
"CodeBlock",
|
|
12
|
-
"DiffBlock",
|
|
13
|
-
"Callout"
|
|
14
|
-
];
|
|
15
|
-
export async function validateMdx(filePath) {
|
|
16
|
-
const result = { errors: [], warnings: [] };
|
|
17
|
-
if (path.extname(filePath) !== ".mdx") {
|
|
18
|
-
result.errors.push("Input file must be .mdx.");
|
|
19
|
-
return result;
|
|
20
|
-
}
|
|
21
|
-
let source = "";
|
|
22
|
-
try {
|
|
23
|
-
source = await readFile(filePath, "utf8");
|
|
24
|
-
}
|
|
25
|
-
catch {
|
|
26
|
-
result.errors.push(`Failed to read file: ${filePath}`);
|
|
27
|
-
return result;
|
|
28
|
-
}
|
|
29
|
-
if (source.includes("<script")) {
|
|
30
|
-
result.errors.push("Do not write <script> directly in MDX. Wrap behavior in a controlled component.");
|
|
31
|
-
}
|
|
32
|
-
if (!source.includes("ExportPanel") && !source.includes("CommentExport")) {
|
|
33
|
-
result.warnings.push("ExportPanel or equivalent export component not found. Interactive artifacts should provide an export path.");
|
|
34
|
-
}
|
|
35
|
-
if (source.length > 40_000) {
|
|
36
|
-
result.warnings.push("MDX file is large. Move bulky data to adjacent JSON files.");
|
|
37
|
-
}
|
|
38
|
-
const knownComponents = componentRegistry.map((component) => component.name);
|
|
39
|
-
const usedArtifactComponent = knownComponents.some((name) => source.includes(`<${name}`));
|
|
40
|
-
if (!usedArtifactComponent) {
|
|
41
|
-
result.warnings.push("No first-stage high-level artifact component found. Confirm plain MDX is intentional.");
|
|
42
|
-
}
|
|
43
|
-
const sourceWithoutStringLiterals = stripStringLiterals(source);
|
|
44
|
-
for (const componentName of componentsRequiringStableId) {
|
|
45
|
-
if (hasOpeningTagWithoutProp(sourceWithoutStringLiterals, componentName, "id")) {
|
|
46
|
-
result.warnings.push(`${componentName} should include a stable id prop so comments and state can use a durable anchorId.`);
|
|
47
|
-
}
|
|
48
|
-
}
|
|
49
|
-
return result;
|
|
50
|
-
}
|
|
51
|
-
export function printValidationResult(result) {
|
|
52
|
-
for (const error of result.errors) {
|
|
53
|
-
console.error(`error: ${error}`);
|
|
54
|
-
}
|
|
55
|
-
for (const warning of result.warnings) {
|
|
56
|
-
console.warn(`warn: ${warning}`);
|
|
57
|
-
}
|
|
58
|
-
if (result.errors.length === 0 && result.warnings.length === 0) {
|
|
59
|
-
console.log("validate ok");
|
|
60
|
-
}
|
|
61
|
-
}
|
|
62
|
-
function stripStringLiterals(source) {
|
|
63
|
-
return source
|
|
64
|
-
.replace(/`(?:\\[\s\S]|[^`\\])*`/g, "``")
|
|
65
|
-
.replace(/"(?:\\.|[^"\\])*"/g, '""')
|
|
66
|
-
.replace(/'(?:\\.|[^'\\])*'/g, "''");
|
|
67
|
-
}
|
|
68
|
-
function hasOpeningTagWithoutProp(source, componentName, propName) {
|
|
69
|
-
const escapedName = componentName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
70
|
-
const tagPattern = new RegExp(`<${escapedName}(?=[\\s>/])[^>]*>`, "g");
|
|
71
|
-
const propPattern = new RegExp(`\\s${propName}\\s*=`);
|
|
72
|
-
for (const match of source.matchAll(tagPattern)) {
|
|
73
|
-
const openingTag = match[0];
|
|
74
|
-
if (!propPattern.test(openingTag)) {
|
|
75
|
-
return true;
|
|
76
|
-
}
|
|
77
|
-
}
|
|
78
|
-
return false;
|
|
79
|
-
}
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
export type CalloutTone = "info" | "success" | "warning" | "danger";
|
|
2
|
-
export type CalloutProps = {
|
|
3
|
-
id?: string;
|
|
4
|
-
body: string;
|
|
5
|
-
title?: string;
|
|
6
|
-
tone?: CalloutTone;
|
|
7
|
-
className?: string;
|
|
8
|
-
};
|
|
9
|
-
export declare function Callout({ id, body, title, tone, className }: CalloutProps): import("react/jsx-runtime").JSX.Element;
|
|
@@ -1,10 +0,0 @@
|
|
|
1
|
-
export type CodeBlockProps = {
|
|
2
|
-
id?: string;
|
|
3
|
-
code: string;
|
|
4
|
-
language?: string;
|
|
5
|
-
filename?: string;
|
|
6
|
-
showLineNumbers?: boolean;
|
|
7
|
-
highlightLines?: number[];
|
|
8
|
-
className?: string;
|
|
9
|
-
};
|
|
10
|
-
export declare function CodeBlock({ id, code, language, filename, showLineNumbers, highlightLines, className }: CodeBlockProps): import("react/jsx-runtime").JSX.Element;
|