mdx-artifacts 0.1.2 → 0.2.0

package/artifact-docs/examples/streamlit-style-mixed.mdx

@@ -2,11 +2,10 @@ import {
   Callout,
   CodeBlock,
   ComparisonSet,
-  DecisionMatrix,
+  ContentSet,
   ExportPanel,
   Frame,
   MarkdownBody,
-  OptionGrid,
 } from "mdx-artifacts/react";
 
 # Streamlit-Style Linear Artifact
@@ -28,56 +27,60 @@ Streamlit works well because authors can write a small amount of text, drop in a
   id="callout.linear-check"
   tone="info"
   title="What this example is checking"
-  body="The artifact should read as one continuous document, not as disconnected component demos."
-/>
+>
+  The artifact should read as one continuous document, not as disconnected component demos.
+</Callout>
 
 ## Decision point
 
 The first question is whether the core authoring experience should stay close to native MDX or move toward more explicit text components.
 
-<DecisionMatrix
-  id="decision.native-mdx"
-  question="Should top-level prose use native MDX by default?"
-  options={[
-    {
-      id: "native-mdx",
-      name: "Native MDX prose",
-      summary:
-        "Use regular headings, paragraphs, lists, links, and blockquotes between workflow components.",
-      pros: [
-        "Shortest authoring path",
-        "Agent-friendly",
-        "No extra text API to learn",
-      ],
-      cons: [
-        "Needs strong default prose styling",
-        "Harder to constrain every edge case",
-      ],
-      confidence: "high",
-      verdict: "Recommended baseline",
-    },
-    {
-      id: "text-components",
-      name: "Text components everywhere",
-      summary:
-        "Require components such as InlineText and MarkdownBody for most visible copy.",
-      pros: ["More controlled rendering", "Clear metadata boundary"],
-      cons: ["Verbose for simple documents", "Less natural than MDX"],
-      confidence: "medium",
-      verdict: "Use inside reusable components",
-    },
-    {
-      id: "raw-html",
-      name: "Raw HTML escape hatch",
-      summary:
-        "Let authors write arbitrary HTML when layout or text rendering gets specific.",
-      pros: ["Maximum flexibility"],
-      cons: ["Style drift", "Weak validation", "Harder for agents to reuse"],
-      confidence: "low",
-      verdict: "Avoid unless necessary",
-    },
-  ]}
-/>
+<ContentSet
+  id="set.native-mdx"
+  title="Should top-level prose use native MDX by default?"
+  layout="grid"
+  columns={3}
+>
+  <ContentSet.Item
+    id="native-mdx"
+    title="Native MDX prose"
+    badge="Recommended"
+    tone="positive"
+    emphasis="primary"
+    summary="Use regular headings, paragraphs, lists, links, and blockquotes between workflow components."
+  >
+    - Shortest authoring path
+    - Agent-friendly
+    - No extra text API to learn
+    - Needs strong default prose styling
+    - Harder to constrain every edge case
+  </ContentSet.Item>
+  <ContentSet.Item
+    id="text-components"
+    title="Text components everywhere"
+    badge="Component-local"
+    tone="info"
+    summary="Require components such as `InlineText` and `MarkdownBody` for most visible copy."
+  >
+    - More controlled rendering
+    - Clear metadata boundary
+    - Verbose for simple documents
+    - Less natural than MDX
+  </ContentSet.Item>
+  <ContentSet.Item
+    id="raw-html"
+    title="Raw HTML escape hatch"
+    badge="Avoid"
+    tone="danger"
+    emphasis="subtle"
+    summary="Let authors write arbitrary HTML when layout or text rendering gets specific."
+  >
+    - Maximum flexibility
+    - Style drift
+    - Weak validation
+    - Harder for agents to reuse
+  </ContentSet.Item>
+</ContentSet>
 
 After the decision block, the document should continue naturally. This paragraph is intentionally plain MDX so the spacing between prose and the component above is easy to judge.
 
@@ -87,40 +90,50 @@ After the decision block, the document should continue naturally. This paragraph
 
 The next block lists the current component roles. It should feel like a continuation of the same document, not a separate app screen.
 
-<OptionGrid
-  id="option.linear-building-blocks"
+<ContentSet
+  id="set.linear-building-blocks"
   title="Linear authoring building blocks"
-  options={[
-    {
-      id: "native-mdx",
-      name: "Native MDX",
-      intent: "Own top-level narrative flow.",
-      tradeoffs: [
-        "Best for headings and explanatory paragraphs",
-        "Needs polished document-level CSS",
-      ],
-    },
-    {
-      id: "markdown-body",
-      name: "MarkdownBody",
-      intent: "Own controlled body copy inside a component slot.",
-      tradeoffs: [
-        "Good for reusable components",
-        "Less convenient for top-level prose",
-      ],
-    },
-    {
-      id: "workflow-components",
-      name: "Workflow components",
-      intent:
-        "Own structured decisions, comparisons, code notes, and export surfaces.",
-      tradeoffs: [
-        "Agent-queryable through the registry",
-        "Should stay higher-level than raw cards",
-      ],
-    },
-  ]}
-/>
+  layout="grid"
+  columns={3}
+>
+  <ContentSet.Item
+    id="native-mdx"
+    title="Native MDX"
+    badge="Document"
+    tone="info"
+    emphasis="primary"
+    summary="Own top-level narrative flow."
+  >
+    Use this for the document's main reading order.
+
+    - Best for headings and explanatory paragraphs
+    - Needs polished document-level CSS
+  </ContentSet.Item>
+  <ContentSet.Item
+    id="markdown-body"
+    title="MarkdownBody"
+    badge="Controlled"
+    tone="neutral"
+    summary="Own controlled body copy inside a component slot."
+  >
+    Use this when reusable components need safe Markdown rendering.
+
+    - Good for reusable components
+    - Less convenient for top-level prose
+  </ContentSet.Item>
+  <ContentSet.Item
+    id="workflow-components"
+    title="Workflow components"
+    badge="Reusable"
+    tone="accent"
+    summary="Own structured decisions, comparisons, code notes, and export surfaces."
+  >
+    Use this for reusable artifact meaning rather than layout-only cards.
+
+    - Agent-queryable through the registry
+    - Should stay higher-level than raw cards
+  </ContentSet.Item>
+</ContentSet>
 
 ## Mixed content
 
@@ -131,8 +144,9 @@ Here is a small comparison set with component-local Markdown inside each item. T
     <Frame surface="subtle">
       <MarkdownBody
         variant="compact"
-        body="Use this for the document's main reading order: headings, paragraphs, lists, and short notes between components."
-      />
+      >
+        Use this for the document's main reading order: headings, paragraphs, lists, and short notes between components.
+      </MarkdownBody>
     </Frame>
   </ComparisonSet.Item>
 
@@ -140,8 +154,9 @@ Here is a small comparison set with component-local Markdown inside each item. T
   <Frame surface="subtle">
     <MarkdownBody
       variant="compact"
-      body="Use this when a component needs a controlled body field with safe Markdown rendering."
-    />
+    >
+      Use this when a component needs a controlled body slot with safe Markdown rendering.
+    </MarkdownBody>
   </Frame>
 </ComparisonSet.Item>
 
@@ -154,7 +169,7 @@ Here is a small comparison set with component-local Markdown inside each item. T
 
 Plain MDX prose.
 
-<DecisionMatrix ... />
+<ContentSet ... />
 
 More prose.`}
 />

package/dist/lib/cli/{build.js → commands/build.js}

@@ -1,7 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { loadConfig } from "./config.js";
-import { buildArtifact, createArtifactProject } from "./vite-artifact.js";
+import { loadConfig } from "../config/config.js";
+import { buildArtifact, createArtifactProject } from "../dev-server/vite-artifact.js";
 export async function buildCommand(projectRoot, input) {
     const config = await loadConfig(projectRoot);
     const mdxPath = path.resolve(projectRoot, input);

package/dist/lib/cli/{components.js → commands/components.js}

@@ -1,4 +1,4 @@
-import { componentRegistry, findComponentMeta } from "../react/registry.js";
+import { componentRegistry, findComponentMeta } from "../../react/registry.js";
 export function componentsCommand(input, options = {}) {
     if (input) {
         const component = findComponentMeta(input);
@@ -20,15 +20,31 @@ export function componentsCommand(input, options = {}) {
     for (const component of componentRegistry) {
         console.log(`- ${component.name}: ${component.description}`);
     }
-    console.log("\nUse `artifact-kit components <ComponentName>` to inspect props and examples.");
-    console.log("Use `artifact-kit components --json` for machine-readable metadata.");
+    console.log("\nAuthoring rule: prefer MDX children for human-readable content; use props for stable ids, variants, layout controls, export values, and structured data.");
+    console.log("\nUse `mdx-artifacts components <ComponentName>` to inspect props, authoring guidance, and examples.");
+    console.log("Use `mdx-artifacts components --json` for machine-readable metadata.");
 }
 function printComponent(component) {
     console.log(`${component.name}\n`);
     console.log(component.description);
+    if (component.deprecated) {
+        console.log(`\nDeprecated: use ${component.deprecated.replacement} for new artifacts.`);
+        for (const item of component.deprecated.guidance) {
+            console.log(`- ${item}`);
+        }
+        console.log("\nReplacement example:");
+        console.log(component.example);
+        return;
+    }
     if (component.category || component.stability) {
         console.log(`\nMetadata: ${[component.category ? `category=${component.category}` : undefined, component.stability ? `stability=${component.stability}` : undefined].filter(Boolean).join(", ")}`);
     }
+    if (component.authoring) {
+        console.log(`\nAuthoring: ${component.authoring.kind}`);
+        for (const item of component.authoring.guidance) {
+            console.log(`- ${item}`);
+        }
+    }
     console.log("\nUse when:");
     for (const item of component.useWhen) {
         console.log(`- ${item}`);

package/dist/lib/cli/{dev.js → commands/dev.js}

@@ -1,6 +1,6 @@
 import path from "node:path";
-import { loadConfig } from "./config.js";
-import { createArtifactProject, startDevServer } from "./vite-artifact.js";
+import { loadConfig } from "../config/config.js";
+import { createArtifactProject, startDevServer } from "../dev-server/vite-artifact.js";
 export async function devCommand(projectRoot, input) {
     const config = await loadConfig(projectRoot);
     const mdxPath = path.resolve(projectRoot, input);

package/dist/lib/cli/commands/interactions.d.ts

@@ -0,0 +1,2 @@
+export type { InteractionsInspectResult } from "../services/interaction-service";
+export declare function interactionsCommand(projectRoot: string, args: string[]): Promise<void>;

package/dist/lib/cli/commands/interactions.js

@@ -0,0 +1,280 @@
+import { addInteractionItemService, inspectInteractionService, promoteInteractionService, removeInteractionItemService, resetInteractionService, setInteractionOrderService, updateInteractionItemService } from "../services/interaction-service.js";
+export async function interactionsCommand(projectRoot, args) {
+    const [subcommand] = args;
+    if (subcommand === "inspect") {
+        const options = parseInspectArgs(args.slice(1));
+        const result = await inspectInteractionService(projectRoot, options.input, options.id);
+        console.log(options.json ? JSON.stringify(result, null, 2) : formatInspectResult(result));
+        return;
+    }
+    if (subcommand === "set-order") {
+        const options = parseSetOrderArgs(args.slice(1));
+        const result = await setInteractionOrderService(projectRoot, options.input, options.id, options.orderedIds);
+        console.log(formatMutationResult(result));
+        return;
+    }
+    if (subcommand === "reset") {
+        const options = parseResetArgs(args.slice(1));
+        const result = await resetInteractionService(projectRoot, options.input, options.id);
+        console.log(formatMutationResult(result));
+        return;
+    }
+    if (subcommand === "promote") {
+        const options = parsePromoteArgs(args.slice(1));
+        const result = await promoteInteractionService(projectRoot, options.input, options.id);
+        console.log(formatMutationResult(result));
+        return;
+    }
+    if (subcommand === "add-item") {
+        const options = parseAddItemArgs(args.slice(1));
+        const result = await addInteractionItemService(projectRoot, options.input, options.id, options.item, {
+            afterId: options.afterId
+        });
+        console.log(formatMutationResult(result));
+        return;
+    }
+    if (subcommand === "remove-item") {
+        const options = parseRemoveItemArgs(args.slice(1));
+        const result = await removeInteractionItemService(projectRoot, options.input, options.id, options.itemId);
+        console.log(formatMutationResult(result));
+        return;
+    }
+    if (subcommand === "update-item") {
+        const options = parseUpdateItemArgs(args.slice(1));
+        const result = await updateInteractionItemService(projectRoot, options.input, options.id, options.itemId, options.patch);
+        console.log(formatMutationResult(result));
+        return;
+    }
+    throw new Error("interactions requires a subcommand. Use inspect, set-order, reset, promote, add-item, remove-item, or update-item.");
+}
+function parseInspectArgs(args) {
+    const positional = args.filter((arg) => arg !== "--json");
+    const json = args.includes("--json");
+    const [input, id, ...rest] = positional;
+    if (!input) {
+        throw new Error("interactions inspect requires a .mdx file path.");
+    }
+    if (!id) {
+        throw new Error("interactions inspect requires a component id.");
+    }
+    if (rest.length > 0) {
+        throw new Error(`Unexpected interactions inspect argument: ${rest[0]}`);
+    }
+    return { input, id, json };
+}
+function parseSetOrderArgs(args) {
+    const [input, id, ...rest] = args;
+    if (!input) {
+        throw new Error("interactions set-order requires a .mdx file path.");
+    }
+    if (!id) {
+        throw new Error("interactions set-order requires a component id.");
+    }
+    const orderedIds = parseOrderedIds(rest);
+    return { input, id, orderedIds };
+}
+function parseResetArgs(args) {
+    const [input, id, ...rest] = args;
+    if (!input) {
+        throw new Error("interactions reset requires a .mdx file path.");
+    }
+    if (!id) {
+        throw new Error("interactions reset requires a component id.");
+    }
+    if (rest.length > 0) {
+        throw new Error(`Unexpected interactions reset argument: ${rest[0]}`);
+    }
+    return { input, id };
+}
+function parsePromoteArgs(args) {
+    const [input, id, ...rest] = args;
+    if (!input) {
+        throw new Error("interactions promote requires a .mdx file path.");
+    }
+    if (!id) {
+        throw new Error("interactions promote requires a component id.");
+    }
+    if (rest.length > 0) {
+        throw new Error(`Unexpected interactions promote argument: ${rest[0]}`);
+    }
+    return { input, id };
+}
+function parseAddItemArgs(args) {
+    const [input, id, ...rest] = args;
+    if (!input) {
+        throw new Error("interactions add-item requires a .mdx file path.");
+    }
+    if (!id) {
+        throw new Error("interactions add-item requires a component id.");
+    }
+    const options = parseOptionMap(rest, ["item-id", "title", "summary", "badge", "tags", "disabled", "after"], []);
+    const itemId = options.values.get("item-id");
+    const title = options.values.get("title");
+    if (!itemId) {
+        throw new Error("interactions add-item requires --item-id <id>.");
+    }
+    if (!title) {
+        throw new Error("interactions add-item requires --title <title>.");
+    }
+    return {
+        input,
+        id,
+        item: createItemFromOptions(itemId, title, options.values),
+        ...(options.values.get("after") ? { afterId: options.values.get("after") } : {})
+    };
+}
+function parseRemoveItemArgs(args) {
+    const [input, id, ...rest] = args;
+    if (!input) {
+        throw new Error("interactions remove-item requires a .mdx file path.");
+    }
+    if (!id) {
+        throw new Error("interactions remove-item requires a component id.");
+    }
+    const options = parseOptionMap(rest, ["item-id"], []);
+    const itemId = options.values.get("item-id");
+    if (!itemId) {
+        throw new Error("interactions remove-item requires --item-id <id>.");
+    }
+    return { input, id, itemId };
+}
+function parseUpdateItemArgs(args) {
+    const [input, id, ...rest] = args;
+    if (!input) {
+        throw new Error("interactions update-item requires a .mdx file path.");
+    }
+    if (!id) {
+        throw new Error("interactions update-item requires a component id.");
+    }
+    const options = parseOptionMap(rest, ["item-id", "title", "summary", "badge", "tags", "disabled"], ["clear-summary", "clear-badge", "clear-tags"]);
+    const itemId = options.values.get("item-id");
+    if (!itemId) {
+        throw new Error("interactions update-item requires --item-id <id>.");
+    }
+    const patch = createPatchFromOptions(options.values, options.flags);
+    if (Object.keys(patch).length === 0) {
+        throw new Error("interactions update-item requires at least one field update.");
+    }
+    return { input, id, itemId, patch };
+}
+function parseOrderedIds(args) {
+    const flagIndex = args.indexOf("--ordered-ids");
+    if (flagIndex < 0) {
+        throw new Error("interactions set-order requires --ordered-ids <id> [...id].");
+    }
+    if (flagIndex > 0) {
+        throw new Error(`Unexpected interactions set-order argument: ${args[0]}`);
+    }
+    const orderedIds = args
+        .slice(flagIndex + 1)
+        .flatMap((value) => value.split(","))
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (orderedIds.length === 0) {
+        throw new Error("interactions set-order requires at least one ordered id.");
+    }
+    return orderedIds;
+}
+function parseOptionMap(args, valueKeys, flagKeys) {
+    const values = new Map();
+    const flags = new Set();
+    for (let index = 0; index < args.length; index += 1) {
+        const name = args[index];
+        if (!name?.startsWith("--")) {
+            throw new Error(`Unexpected interactions argument: ${name}`);
+        }
+        const key = name.slice(2);
+        if (flagKeys.includes(key)) {
+            flags.add(key);
+            continue;
+        }
+        if (!valueKeys.includes(key)) {
+            throw new Error(`Unknown interactions option: --${key}.`);
+        }
+        const value = args[index + 1];
+        if (value === undefined || value.startsWith("--")) {
+            throw new Error(`Missing value for --${key}.`);
+        }
+        values.set(key, value);
+        index += 1;
+    }
+    return { flags, values };
+}
+function createItemFromOptions(itemId, title, options) {
+    return {
+        id: itemId,
+        title,
+        ...createPatchFromOptions(options, new Set())
+    };
+}
+function createPatchFromOptions(options, flags) {
+    return {
+        ...(options.has("title") ? { title: options.get("title") ?? "" } : {}),
+        ...(flags.has("clear-summary")
+            ? { summary: undefined }
+            : options.has("summary")
+                ? { summary: options.get("summary") ?? "" }
+                : {}),
+        ...(flags.has("clear-badge")
+            ? { badge: undefined }
+            : options.has("badge")
+                ? { badge: options.get("badge") ?? "" }
+                : {}),
+        ...(flags.has("clear-tags") ? { tags: undefined } : options.has("tags") ? { tags: parseTags(options.get("tags") ?? "") } : {}),
+        ...(options.has("disabled") ? { disabled: parseBooleanOption(options.get("disabled") ?? "", "disabled") } : {})
+    };
+}
+function parseTags(value) {
+    return value
+        .split(",")
+        .map((tag) => tag.trim())
+        .filter(Boolean);
+}
+function parseBooleanOption(value, name) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    throw new Error(`--${name} must be true or false.`);
+}
+function formatInspectResult(result) {
+    return [
+        "interactions inspect ok",
+        `source: ${result.source.path}`,
+        `state: ${result.state.path}${result.state.exists ? "" : " (not found)"}`,
+        `component: ${result.component.id}`,
+        `order source: ${result.order.source}`,
+        `items: ${result.component.items.length}`,
+        "order:",
+        ...result.order.orderedIds.map((itemId, index) => {
+            const item = result.component.items.find((candidate) => candidate.id === itemId);
+            return `${index + 1}. ${itemId}${item ? ` - ${item.title}` : ""}`;
+        }),
+        ...(result.order.appendedIds.length > 0 ? [`appended: ${result.order.appendedIds.join(", ")}`] : []),
+        ...(result.warnings.length > 0 ? ["warnings:", ...result.warnings.map((warning) => `- ${warning}`)] : [])
+    ].join("\n");
+}
+function formatMutationResult(result) {
+    if (result.action === "promote" && result.status === "noop") {
+        return [
+            "interactions promote noop",
+            `source: ${result.sourcePath}`,
+            `component: ${result.component}`,
+            `reason: ${result.reason ?? "no runtime overlay"}`
+        ].join("\n");
+    }
+    const lines = [
+        `interactions ${result.action} ok`,
+        ...(result.action === "reset" || result.action === "set-order" ? [] : [`source: ${result.sourcePath}`]),
+        `state: ${result.statePath}`,
+        `component: ${result.component}`
+    ];
+    if (result.itemId) {
+        lines.push(`item: ${result.itemId}`);
+    }
+    if (result.orderedIds) {
+        lines.push(`items: ${result.orderedIds.length}`);
+        lines.push(`orderedIds: ${result.orderedIds.join(", ")}`);
+    }
+    return lines.join("\n");
+}

package/dist/lib/cli/commands/review.d.ts

@@ -0,0 +1 @@
+export declare function reviewCommand(projectRoot: string, args: string[]): Promise<void>;