@czxingyu/xycomponents 0.1.1 → 0.1.3

package/README.md

@@ -98,41 +98,34 @@ pnpm run docs:preview
 pnpm run type-check
 ```
 
-## CLI for AI-assisted usage
+## CLI and Skills for AI-assisted usage
 
-The package publishes a `xycomponents` CLI for tools and AI agents that need
-stable component metadata.
+The `xycomponents` CLI ships inside `@czxingyu/xycomponents` and **always matches
+the installed package version**. Install the library in your app and invoke the
+CLI locally—do not install the CLI globally.
 
 ```bash
-xycomponents components --json
-xycomponents components --category data-entry --json
-xycomponents components --include-retired --json
-xycomponents component button --json
-xycomponents snippet button --example primary
-xycomponents migrate link --json
-xycomponents doctor --json
-xycomponents package --json
+pnpm add @czxingyu/xycomponents
+pnpm exec xycomponents doctor --json
+pnpm exec xycomponents components --json
+pnpm exec xycomponents component button --json
+pnpm exec xycomponents snippet button --example primary
+pnpm exec xycomponents migrate link --json
+pnpm exec xycomponents package --json
 ```
 
+Re-run `pnpm add @czxingyu/xycomponents@<version>` when upgrading; the CLI
+updates with the package.
+
+Cursor Agent Skills live in [`skills/`](./skills/) (`xycomponents-shared`,
+`xycomponents-cli`). Copy them into a consumer project's `.cursor/skills/` or
+from `node_modules/@czxingyu/xycomponents/skills/` after install. See
+[`skills/README.md`](./skills/README.md).
+
 The CLI catalog covers every documented component with detailed props, events,
-slots, examples, and AI hints. The canonical component list lives in
-[`component-groups.ts`](./docs/src/pages/components/component-groups.ts). The
-component generator atomically adds a detailed baseline entry to
-[`generated-components.ts`](./cli/metadata/generated-components.ts); replace
-that placeholder contract while implementing the component, and move mature
-metadata into the appropriate domain module when useful. All metadata modules
-are composed by [`cli/metadata.ts`](./cli/metadata.ts), and the component audit
-rejects catalog-only fallbacks. The same audit normalizes Vue bindings and
-kebab-case names, then verifies every Props, Events, and Slots identifier is
-present in its component documentation.
-Schema v3 also publishes a lifecycle record for every active component and
-keeps retired-component tombstones. Use `migrate <name> --json` before replacing
-deprecated APIs or when an old component is no longer present in the runtime;
-the result contains the reason, removal timeline, migration instructions, and
-guide path.
-The release gate also installs the packed tarball into an isolated consumer,
-type-checks its TypeScript and Vue SFC public entries, and executes the
-installed CLI binary before publishing.
+slots, examples, and AI hints. Use `pnpm exec xycomponents migrate <name> --json`
+before replacing deprecated APIs. The release gate installs the packed tarball
+into an isolated consumer and executes the project-local CLI before publishing.
 
 ## Global component types
 

package/README.zh-CN.md

@@ -100,24 +100,27 @@ pnpm run docs:preview
 pnpm run type-check
 ```
 
-## 面向 AI 使用的 CLI
+## 面向 AI 使用的 CLI 与 Skills
 
-包发布时会提供 `xycomponents` CLI，方便脚本和 AI Agent 稳定读取组件元数据。
+CLI 随 `@czxingyu/xycomponents` 发布，**版本与 npm 包一致**。业务项目在本地安装后通过 `pnpm exec` 调用；升级库时重新 `pnpm add` 即可同步 CLI。
 
 ```bash
-xycomponents components --json
-xycomponents components --category data-entry --json
-xycomponents components --include-retired --json
-xycomponents component button --json
-xycomponents snippet button --example primary
-xycomponents migrate link --json
-xycomponents doctor --json
-xycomponents package --json
+pnpm add @czxingyu/xycomponents
+pnpm exec xycomponents doctor --json
+pnpm exec xycomponents components --json
+pnpm exec xycomponents component button --json
+pnpm exec xycomponents snippet button --example primary
+pnpm exec xycomponents migrate link --json
+pnpm exec xycomponents package --json
 ```
 
-CLI 以详细级元数据覆盖全部已文档化组件，提供 Props、Events、Slots、示例和 AI 提示。统一组件清单位于 [`component-groups.ts`](./docs/src/pages/components/component-groups.ts)。组件生成器会原子写入 [`generated-components.ts`](./cli/metadata/generated-components.ts) 的详细元数据基线；实现组件时必须替换占位契约，成熟后可按领域移入 [`cli/metadata/`](./cli/metadata/) 的对应模块。所有模块最终由 [`cli/metadata.ts`](./cli/metadata.ts) 组合，组件审计会拒绝目录级回退，并逐项核对 CLI API 标识符已出现在对应文档中。
+**不要**全局安装 CLI，避免 AI 查到与项目 `package.json` 不一致的 API。
+
+### Cursor Skills
+
+[`skills/`](./skills/) 提供 `xycomponents-shared`（安装与接入）和 `xycomponents-cli`（命令与 JSON 工作流）。业务项目复制到 `.cursor/skills/` 或从 `node_modules/@czxingyu/xycomponents/skills/` 复制；详见 [`skills/README.md`](./skills/README.md)。本仓库维护者已在 [`.cursor/skills/`](./.cursor/skills/) 启用同名 Skill。
 
-Schema v3 为每个现役组件提供生命周期记录，并永久保留 retired tombstone。替换 deprecated API 或遇到运行时已经移除的旧组件前，先运行 `migrate <name> --json`；结果会给出原因、移除版本、替代组件、迁移步骤和指南路径。发布门禁还会把真实 tarball 安装到隔离工程，严格检查 TypeScript/Vue SFC 公开类型，并执行安装后的 CLI。
+CLI 以详细级元数据覆盖全部已文档化组件。统一组件清单位于 [`component-groups.ts`](./docs/src/pages/components/component-groups.ts)。组件生成器会原子写入 [`generated-components.ts`](./cli/metadata/generated-components.ts) 的详细元数据基线；成熟后可移入 [`cli/metadata/`](./cli/metadata/)。Schema v3 提供生命周期记录与 retired tombstone；改 deprecated/retired API 前先 `pnpm exec xycomponents migrate <name> --json`。
 
 ## 全局组件类型
 

package/dist/anchor/anchor.js

@@ -2,6 +2,6 @@ import e from "../_virtual/_plugin-vue_export-helper.js";
 import t from "./anchor.vue_vue_type_script_setup_true_lang.js";
 /* empty css                                                       */
 //#region components/anchor/anchor.vue
-var n = /*#__PURE__*/ e(t, [["__scopeId", "data-v-93931713"]]);
+var n = /*#__PURE__*/ e(t, [["__scopeId", "data-v-5b2bf520"]]);
 //#endregion
 export { n as default };

package/dist/anchor/anchor.vue_vue_type_script_setup_true_lang.js

@@ -217,13 +217,10 @@ var x = ["aria-label"], S = [
 					t.className,
 					P.value.item
 				]]),
-				style: f([
-					t.style,
-					l.direction === "vertical" ? { paddingInlineStart: `${n * 16}px` } : void 0,
-					F.value.item
-				])
+				style: f([t.style, F.value.item])
 			}, [s("a", {
 				class: d(["xy-anchor__link", { "xy-anchor__link--disabled": t.disabled }]),
+				style: f(l.direction === "vertical" && n > 0 ? { paddingInlineStart: `calc(var(--xy-anchor-link-padding-inline) + ${n * 16}px)` } : void 0),
 				href: t.href,
 				target: t.target,
 				rel: t.target === "_blank" ? "noreferrer" : void 0,
@@ -242,7 +239,7 @@ var x = ["aria-label"], S = [
 				depth: n,
 				index: r,
 				item: t
-			}, () => [c(y(z(t)), 1)])], 6)], 10, S)], 6))), 128))], 6)) : a("", !0),
+			}, () => [c(y(z(t)), 1)])], 6)], 14, S)], 6))), 128))], 6)) : a("", !0),
 			v(e.$slots, "default")
 		], 14, x));
 	}

package/dist/descriptions/descriptions.js

@@ -2,6 +2,6 @@ import e from "../_virtual/_plugin-vue_export-helper.js";
 import t from "./descriptions.vue_vue_type_script_setup_true_lang.js";
 /* empty css                                                             */
 //#region components/descriptions/descriptions.vue
-var n = /*#__PURE__*/ e(t, [["__scopeId", "data-v-604e62a9"]]);
+var n = /*#__PURE__*/ e(t, [["__scopeId", "data-v-103d68c3"]]);
 //#endregion
 export { n as default };

package/dist/descriptions/descriptions.vue_vue_type_script_setup_true_lang.js

@@ -3,9 +3,9 @@ import { useElementSize as n } from "../core/resize/index.js";
 import { xyDescriptionsContextKey as r } from "./context.js";
 import i from "./descriptions-value.js";
 import a from "./descriptions-item.js";
-import { Fragment as o, computed as s, createBlock as c, createCommentVNode as l, createElementBlock as u, createElementVNode as d, createVNode as f, defineComponent as p, normalizeClass as m, normalizeStyle as h, openBlock as g, provide as _, ref as v, renderList as y, renderSlot as b, shallowRef as x, unref as S, useSlots as C, withCtx as w } from "vue";
+import { Fragment as o, computed as s, createBlock as ee, createCommentVNode as c, createElementBlock as l, createElementVNode as u, createVNode as d, defineComponent as f, normalizeClass as p, normalizeStyle as m, onBeforeUpdate as h, openBlock as g, provide as _, ref as v, renderList as y, renderSlot as b, shallowRef as x, unref as S, useSlots as C, withCtx as w } from "vue";
 //#region components/descriptions/descriptions.vue?vue&type=script&setup=true&lang.ts
-var T = /*@__PURE__*/ p({
+var T = /*@__PURE__*/ f({
 	name: "XyDescriptions",
 	__name: "descriptions",
 	props: {
@@ -68,8 +68,8 @@ var T = /*@__PURE__*/ p({
 			required: !1
 		}
 	},
-	setup(p) {
-		let T = p, E = C(), D = v(), { width: O } = n(D), k = x([]), A = {
+	setup(f) {
+		let T = f, E = C(), D = v(Object.keys(E)), O = v(), { width: k } = n(O), A = x([]), j = {
 			xs: 0,
 			sm: 576,
 			md: 768,
@@ -77,28 +77,28 @@ var T = /*@__PURE__*/ p({
 			xl: 1200,
 			xxl: 1600,
 			xxxl: 1920
-		}, ee = Object.keys(A);
-		function j(e) {
+		}, te = Object.keys(j);
+		function M(e) {
 			let t = Number(e);
 			return Number.isFinite(t) ? Math.max(1, Math.floor(t)) : 1;
 		}
-		function M(e, t) {
-			return e === "filled" ? t : Math.min(j(e), t);
-		}
 		function N(e, t) {
-			if (typeof e == "number") return j(e);
-			let n = ee.filter((t) => e[t] !== void 0);
+			return e === "filled" ? t : Math.min(M(e), t);
+		}
+		function P(e, t) {
+			if (typeof e == "number") return M(e);
+			let n = te.filter((t) => e[t] !== void 0);
 			if (n.length === 0) return 1;
 			let r = e[n[0]];
-			for (let i of n) t >= A[i] && (r = e[i]);
-			return j(r);
+			for (let i of n) t >= j[i] && (r = e[i]);
+			return M(r);
 		}
-		let P = s(() => T.bordered), F = s(() => T.colon), I = s(() => N(T.column, O.value)), L = s(() => T.layout), R = s(() => T.size), z = s(() => T.title !== void 0 || !!E.title), B = s(() => T.extra !== void 0 || !!E.extra), V = s(() => z.value || B.value), H = s(() => T.items !== void 0), U = s(() => {
+		let F = s(() => T.bordered), I = s(() => T.colon), L = s(() => P(T.column, k.value)), R = s(() => T.layout), z = s(() => T.size), B = s(() => T.title !== void 0 || D.value.includes("title")), V = s(() => T.extra !== void 0 || D.value.includes("extra")), H = s(() => B.value || V.value), U = s(() => T.items !== void 0), W = s(() => {
 			let e = /* @__PURE__ */ new Map(), t = 0, n = 0;
-			for (let r of k.value) {
-				let i = r.span.value, a = M(i, I.value);
-				i === "filled" ? a = Math.max(I.value - t, 1) : t + a > I.value && (t = 0, n += 1);
-				let o = t + a >= I.value;
+			for (let r of A.value) {
+				let i = r.span.value, a = N(i, L.value);
+				i === "filled" ? a = Math.max(L.value - t, 1) : t + a > L.value && (t = 0, n += 1);
+				let o = t + a >= L.value;
 				e.set(r.id, {
 					isLastColumn: o,
 					isLastRow: !1,
@@ -109,78 +109,82 @@ var T = /*@__PURE__*/ p({
 			let r = Math.max(...[...e.values()].map((e) => e.row), 0);
 			for (let t of e.values()) t.isLastRow = t.row === r;
 			return e;
-		}), W = s(() => ({ "--xy-descriptions-column": String(I.value) })), G = s(() => ({
+		}), G = s(() => ({ "--xy-descriptions-column": String(L.value) })), K = s(() => ({
 			bordered: T.bordered,
 			colon: T.colon,
-			column: I.value,
-			hasExtra: B.value,
-			hasTitle: z.value,
+			column: L.value,
+			hasExtra: V.value,
+			hasTitle: B.value,
 			layout: T.layout,
 			size: T.size
-		})), K = s(() => e(T.classNames, G.value)), q = s(() => t(T.styles, G.value)), J = s(() => [
+		})), q = s(() => e(T.classNames, K.value)), J = s(() => t(T.styles, K.value)), Y = s(() => [
 			"xy-descriptions",
 			`xy-descriptions--${T.layout}`,
 			`xy-descriptions--${T.size}`,
 			{ "xy-descriptions--bordered": T.bordered },
-			K.value.root
-		]), Y = s(() => K.value.item), X = s(() => q.value.item), Z = s(() => K.value.label), Q = s(() => ({
+			q.value.root
+		]), X = s(() => q.value.item), Z = s(() => J.value.item), Q = s(() => q.value.label), ne = s(() => ({
 			...T.labelStyle,
-			...q.value.label
-		})), te = s(() => K.value.content), ne = s(() => ({
+			...J.value.label
+		})), re = s(() => q.value.content), ie = s(() => ({
 			...T.contentStyle,
-			...q.value.content
+			...J.value.content
 		}));
-		function re(e) {
-			return k.value = [...k.value, e], () => {
-				k.value = k.value.filter((t) => t.id !== e.id);
+		h(() => {
+			let e = Object.keys(E);
+			e.length === D.value.length && e.every((e, t) => e === D.value[t]) || (D.value = e);
+		});
+		function ae(e) {
+			return A.value = [...A.value, e], () => {
+				A.value = A.value.filter((t) => t.id !== e.id);
 			};
 		}
-		function ie(e, t) {
+		function oe(e, t) {
 			return $(e, t).span;
 		}
 		function $(e, t) {
-			return U.value.get(e) ?? {
+			return W.value.get(e) ?? {
 				isLastColumn: !0,
 				isLastRow: !0,
-				span: M(t, I.value)
+				span: N(t, L.value)
 			};
 		}
 		return _(r, {
-			bordered: P,
-			colon: F,
-			column: I,
-			contentClassName: te,
-			contentStyle: ne,
-			itemClassName: Y,
-			itemStyle: X,
-			labelClassName: Z,
-			labelStyle: Q,
-			layout: L,
-			registerItem: re,
+			bordered: F,
+			colon: I,
+			column: L,
+			contentClassName: re,
+			contentStyle: ie,
+			itemClassName: X,
+			itemStyle: Z,
+			labelClassName: Q,
+			labelStyle: ne,
+			layout: R,
+			registerItem: ae,
 			resolveItemLayout: $,
-			resolveItemSpan: ie,
-			size: R
-		}), (e, t) => (g(), u("section", {
+			resolveItemSpan: oe,
+			size: z
+		}), (e, t) => (g(), l("section", {
 			ref_key: "rootRef",
-			ref: D,
-			class: m(J.value),
-			style: h(q.value.root)
-		}, [V.value ? (g(), u("header", {
+			ref: O,
+			class: p(Y.value),
+			style: m(J.value.root)
+		}, [H.value ? (g(), l("header", {
 			key: 0,
-			class: m(["xy-descriptions__header", K.value.header]),
-			style: h(q.value.header)
-		}, [z.value ? (g(), u("div", {
+			class: p(["xy-descriptions__header", q.value.header]),
+			style: m(J.value.header)
+		}, [B.value ? (g(), l("div", {
 			key: 0,
-			class: m(["xy-descriptions__title", K.value.title]),
-			style: h(q.value.title)
-		}, [b(e.$slots, "title", {}, () => [f(S(i), { value: p.title }, null, 8, ["value"])], !0)], 6)) : l("", !0), B.value ? (g(), u("div", {
+			class: p(["xy-descriptions__title", q.value.title]),
+			style: m(J.value.title)
+		}, [b(e.$slots, "title", {}, () => [d(S(i), { value: f.title }, null, 8, ["value"])], !0)], 6)) : c("", !0), V.value ? (g(), l("div", {
 			key: 1,
-			class: m(["xy-descriptions__extra", K.value.extra]),
-			style: h(q.value.extra)
-		}, [b(e.$slots, "extra", {}, () => [f(S(i), { value: p.extra }, null, 8, ["value"])], !0)], 6)) : l("", !0)], 6)) : l("", !0), d("dl", {
-			class: m(["xy-descriptions__view", K.value.view]),
-			style: h([W.value, q.value.view])
-		}, [H.value ? (g(!0), u(o, { key: 0 }, y(p.items, (e, t) => (g(), c(a, {
+			class: p(["xy-descriptions__extra", q.value.extra]),
+			style: m(J.value.extra)
+		}, [b(e.$slots, "extra", {}, () => [d(S(i), { value: f.extra }, null, 8, ["value"])], !0)], 6)) : c("", !0)], 6)) : c("", !0), u("dl", {
+			class: p(["xy-descriptions__view", q.value.view]),
+			style: m([G.value, J.value.view])
+		}, [U.value ? (g(!0), l(o, { key: 0 }, y(f.items, (e, t) => (g(), ee(a, {
 			key: e.key ?? t,
 			"class-names": e.classNames,
 			"content-style": e.contentStyle,
@@ -189,7 +193,7 @@ var T = /*@__PURE__*/ p({
 			span: e.span,
 			styles: e.styles
 		}, {
-			default: w(() => [f(S(i), { value: e.children ?? e.content }, null, 8, ["value"])]),
+			default: w(() => [d(S(i), { value: e.children ?? e.content }, null, 8, ["value"])]),
 			_: 2
 		}, 1032, [
 			"class-names",