@chenzy-design/svelte 0.3.1 → 0.4.1

package/dist/collapse/meta.js

@@ -1,78 +1,81 @@
 /**
  * Machine-readable component metadata for AI/docs consumption.
  * See specs/00-foundation/ai-friendly.spec.md.
+ * API / tokens 全面对齐 Semi Design collapse。
  */
 export const meta = {
     name: 'Collapse',
     category: 'show',
-    description: '折叠面板，分组承载内容、按需展开。支持数据驱动 panels 与声明式 <Collapse.Panel> 两种用法（择一）、受控 activeKey、accordion 手风琴、展开动画、箭头位置、边框与面板级 disabled。',
+    description: '折叠面板，可展开或折叠展示内容区域。用 <Collapse.Panel itemKey header> 声明面板，支持受控 activeKey、accordion 手风琴、clickHeaderToExpand、自定义 expandIcon/collapseIcon、keepDOM/lazyRender、展开动画。DOM/API/tokens 对齐 Semi。',
     props: [
-        {
-            name: 'panels',
-            type: 'CollapsePanel[]',
-            default: '[]',
-            desc: '面板头部数据（数据驱动模式；为空且传 children 时切换为声明式 <Collapse.Panel>）',
-        },
-        {
-            name: 'activeKey',
-            type: 'string|string[]',
-            default: 'undefined',
-            desc: '受控展开键，仅 onChange 不回写',
-        },
-        { name: 'defaultActiveKey', type: 'string|string[]', default: 'undefined' },
-        { name: 'accordion', type: 'boolean', default: 'false', desc: '手风琴模式，仅展开一个' },
-        { name: 'size', type: "'small'|'default'|'large'", default: 'default' },
-        { name: 'expandIconPosition', type: "'left'|'right'", default: 'right' },
-        { name: 'bordered', type: 'boolean', default: 'true' },
-        { name: 'disabled', type: 'boolean', default: 'false' },
-        { name: 'motion', type: 'boolean', default: 'true', desc: '展开动画开关' },
-        { name: 'lazyRender', type: 'boolean', default: 'false', desc: '首次展开后才渲染内容' },
-        { name: 'keepDOM', type: 'boolean', default: 'true', desc: '展开过的内容保留 DOM' },
-        { name: 'onChange', type: '(keys: string[]) => void', default: 'undefined' },
-        { name: 'onExpand', type: '(detail: { key: string }) => void', default: 'undefined', desc: '某面板被展开后触发' },
-        { name: 'onCollapse', type: '(detail: { key: string }) => void', default: 'undefined', desc: '某面板被收起后触发' },
-        {
-            name: 'onHeaderClick',
-            type: '(detail: { key: string; event: MouseEvent }) => void',
-            default: 'undefined',
-            desc: 'Header 被点击触发（disabled 拦截前发出，可用于埋点）',
-        },
-        {
-            name: 'children',
-            type: 'Snippet<[{ key: string }]> | Snippet',
-            default: 'undefined',
-            desc: '数据驱动：按 key 渲染面板内容；声明式（不传 panels）：内嵌 <Collapse.Panel> 列表',
-        },
+        { name: 'accordion', type: 'boolean', default: 'false', desc: '手风琴模式，每次只允许展开一个面板' },
+        { name: 'activeKey', type: 'string|string[]', default: 'undefined', desc: '受控属性，当前展开的面板 key（仅 onChange 不回写）' },
+        { name: 'class', type: 'string', default: 'undefined', desc: '样式类名' },
+        { name: 'clickHeaderToExpand', type: 'boolean', default: 'true', desc: '点击 Header 展开收起，否则只响应点击箭头' },
+        { name: 'collapseIcon', type: 'Snippet', default: 'IconChevronUp', desc: '自定义折叠图标（展开态显示）' },
+        { name: 'defaultActiveKey', type: 'string|string[]', default: 'undefined', desc: '初始化选中面板的 key' },
+        { name: 'expandIcon', type: 'Snippet', default: 'IconChevronDown', desc: '自定义展开图标（收起态显示）' },
+        { name: 'expandIconPosition', type: "'left'|'right'", default: 'right', desc: '展开图标位置' },
+        { name: 'keepDOM', type: 'boolean', default: 'false', desc: '是否保留隐藏的面板 DOM 树，默认销毁' },
+        { name: 'lazyRender', type: 'boolean', default: 'false', desc: '配合 keepDOM，为 true 时挂载时不渲染内容' },
+        { name: 'motion', type: 'boolean', default: 'true', desc: '是否开启动画' },
+        { name: 'style', type: 'string', default: 'undefined', desc: '内联 CSS 样式' },
+        { name: 'onChange', type: '(activeKey: string[], event: MouseEvent) => void', default: 'undefined', desc: '切换面板的回调' },
+        { name: 'children', type: 'Snippet', default: 'undefined', desc: '内嵌 <Collapse.Panel> 列表' },
     ],
     subcomponents: [
         {
             name: 'Collapse.Panel',
-            desc: '声明式单面板，经 Object.assign(Collapse, { Panel }) 导出，父子状态用 context 传递（同 Timeline.Item / Form.Field 复合模式）。等价于 panels 数据驱动的一项，可放富内容头部/内容。',
+            desc: '单面板，经 Object.assign(Collapse, { Panel }) 导出，父子状态用 context 传递（同 Timeline.Item / Form.Field 复合模式）。DOM 对齐 Semi collapse/item：header role=button，content 用 Collapsible 原语折叠。',
             props: [
-                { name: 'itemKey', type: 'string', default: '(required)', desc: '面板唯一标识，等价 panel.key' },
-                { name: 'header', type: 'string', default: 'undefined', desc: '头部文本' },
-                { name: 'disabled', type: 'boolean', default: 'false', desc: '面板级 disabled，该面板不可展开/收起' },
-                { name: 'head', type: 'Snippet', default: 'undefined', desc: '头部富内容插槽，优先于 header' },
+                { name: 'itemKey', type: 'string', default: '(required)', desc: '必填且唯一，匹配 activeKey / defaultActiveKey' },
+                { name: 'header', type: 'string', default: 'undefined', desc: '面板头文本（string 时渲染 header-right + extra）' },
+                { name: 'head', type: 'Snippet', default: 'undefined', desc: '面板头富内容插槽（ReactNode 语义，优先于 header）' },
+                { name: 'extra', type: 'Snippet|string', default: 'undefined', desc: '右上角辅助内容（仅 header 为 string 且未用 head 时生效）' },
+                { name: 'disabled', type: 'boolean', default: 'false', desc: '面板是否被禁用' },
+                { name: 'showArrow', type: 'boolean', default: 'true', desc: '是否展示箭头' },
+                { name: 'reCalcKey', type: 'number|string', default: 'undefined', desc: 'reCalcKey 改变时重算内容高度（动态内容用）' },
+                { name: 'onMotionEnd', type: '() => void', default: 'undefined', desc: '动画结束回调' },
                 { name: 'children', type: 'Snippet', default: 'undefined', desc: '面板内容' },
             ],
         },
     ],
     a11y: {
-        role: 'region',
+        role: 'button',
         keyboard: ['Tab', 'Enter', 'Space'],
         notes: [
-            '面板头为原生 button，aria-expanded 标记展开态',
-            'button aria-controls 指向内容 region，region aria-labelledby 指回头部',
-            '折叠时内容区 hidden 移出可达性树',
-            '箭头 aria-hidden=true',
+            '面板 header 为 role=button，aria-expanded 标记展开态',
+            'header aria-owns 指向内容区，内容区 aria-hidden 随展开态切换',
+            'header aria-disabled 与 disabled 属性同步',
+            '箭头图标 aria-hidden=true',
         ],
     },
     tokens: [
-        '--cd-collapse-*',
+        // Semi collapse/variables.scss 全量对齐（20），组件直接消费（无中间变量）
+        '--cd-color-collapse-item-border-default',
+        '--cd-color-collapse-header-text-default',
+        '--cd-color-collapse-header-text-disabled',
+        '--cd-color-collapse-header-icon-default',
+        '--cd-color-collapse-header-bg-hover',
+        '--cd-color-collapse-header-bg-active',
+        '--cd-color-collapse-content-text-default',
+        '--cd-font-collapse-header-fontweight',
+        '--cd-spacing-collapse-header-marginx',
+        '--cd-spacing-collapse-header-marginy',
+        '--cd-spacing-collapse-header-padding',
+        '--cd-spacing-collapse-right-paddingright',
+        '--cd-spacing-collapse-header-iconleft-marginright',
+        '--cd-spacing-collapse-content-paddingtop',
+        '--cd-spacing-collapse-content-paddingright',
+        '--cd-spacing-collapse-content-paddingbottom',
+        '--cd-spacing-collapse-content-paddingleft',
+        '--cd-radius-collapse-header',
+        '--cd-width-collapse-item-border',
+        '--cd-size-collapse-icon-default',
+        // 组件另消费的共享基元
+        '--cd-color-disabled-text',
+        '--cd-font-size-regular',
+        '--cd-line-height-regular',
         '--cd-focus-ring',
-        '--cd-border-radius-small',
-        '--cd-spacing-tight',
-        '--cd-motion-ease-standard',
-        '--cd-color-text-3',
     ],
 };

package/dist/collapsible/Collapsible.svelte

@@ -0,0 +1,224 @@
+<!--
+  Collapsible — 折叠容器**原语**：对任意 children 做高度折叠/展开过渡。无触发器 UI
+  （aria-expanded 由使用方提供）。是 Collapse（手风琴）的底层能力，作为独立原语暴露以支持
+  keepDOM / lazyRender / collapseHeight 等精细控制。DOM / API / 机制 / tokens 逐一镜像 Semi Collapsible。
+
+  机制（单套，镜像 Semi index.tsx，不分 grid/measure 两套）：
+    始终 ResizeObserver 测内容高度（scrollHeight / borderBox），wrapper 用**显式 height** 过渡：
+      展开 → height = 实测内容高度；折叠 → height = collapsedHeight（默认 0，collapseHeight>0 时保留部分）。
+    仅在过渡进行中（isTransitioning）且 motion 时挂 .cd-collapsible-transition（才有 transition），
+    过渡结束（transitionend）移除——对齐 Semi «-transition» class 的开合。
+
+  DOM（2 层，镜像 Semi）：
+    .cd-collapsible-wrapper[.cd-collapsible-transition]  ← 显式 height / opacity / transition-duration
+      └ <div overflow:hidden id={id}>  ← ref 测高，children 挂载于此
+
+  §9.3 规避：
+    - domHeight / domInRenderTree / isTransitioning 的写只在 ResizeObserver 回调（下一宏任务）或
+      isOpen 变化的 $effect（读 isOpen/motion，不读自身），与 render 读分离。
+    - hasBeenRendered（lazyRender 簿记）用普通变量，非 $state（render 期只读，写在渲染副作用后）。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { collapsibleShouldRender, collapsibleCollapsedHeight } from '@chenzy-design/core';
+
+  interface Props {
+    /** 是否展开内容区域。 */
+    isOpen?: boolean;
+    /** 动画执行的时间（ms）。 */
+    duration?: number;
+    /** 是否开启动画（false 即时显隐）。 */
+    motion?: boolean;
+    /** 是否保留隐藏的面板 DOM 树（默认销毁）。 */
+    keepDOM?: boolean;
+    /** 配合 keepDOM 使用，为 true 时挂载时不会渲染组件（首帧惰性）。 */
+    lazyRender?: boolean;
+    /** 折叠高度（px，0=完全折叠；>0=保留部分作「展开更多」）。 */
+    collapseHeight?: number;
+    /** 当内容高度小于 collapseHeight 时，是否自适应内容高度（收起高度取 min(内容高度, collapseHeight)）。 */
+    collapseHeightAdaptive?: boolean;
+    /** 是否开启淡入淡出。 */
+    fade?: boolean;
+    /** 变更时重新计算子节点高度，用于优化动态渲染时的计算。 */
+    reCalcKey?: number | string | undefined;
+    /** id，会设置到 wrapper 内容元素，可配合其他组件的 aria-controls 指明控制关系。 */
+    id?: string;
+    /** 动画结束的回调。 */
+    onMotionEnd?: (() => void) | undefined;
+    /** 根节点 class。 */
+    class?: string;
+    /** 根节点内联样式。 */
+    style?: string;
+    /** 被折叠的内容。 */
+    children?: Snippet;
+  }
+
+  let {
+    isOpen = false,
+    duration = 250,
+    motion = true,
+    keepDOM = false,
+    lazyRender = false,
+    collapseHeight = 0,
+    collapseHeightAdaptive = false,
+    fade = false,
+    reCalcKey,
+    id,
+    onMotionEnd,
+    class: className,
+    style,
+    children,
+  }: Props = $props();
+
+  // domHeight：实测内容高度。写只在 ResizeObserver 回调 / reCalcKey 重测（与 render 读分离，规避 §9.3）。
+  let domHeight = $state(0);
+  // domInRenderTree：内容是否在渲染树中（父级 display:none 时为 false）。对齐 Semi domInRenderTree。
+  let domInRenderTree = $state(false);
+  // visible：内容视觉可见（展开中/展开完成）。折叠过渡结束后置 false 以便卸载（非 keepDOM）。
+  // svelte-ignore state_referenced_locally
+  let visible = $state(isOpen);
+  // isTransitioning：过渡进行中。isOpen 变化时置 true，transitionend 置 false。仅此时挂 -transition。
+  // svelte-ignore state_referenced_locally
+  let isTransitioning = $state(false);
+  // hasBeenRendered：lazyRender 簿记，普通变量（非 $state；render 期只读，写在渲染副作用后）。
+  // svelte-ignore state_referenced_locally
+  let hasBeenRendered = isOpen;
+
+  // isOpen 变化时（对齐 Semi getDerivedStateFromProps）：
+  //   展开或无 motion → 立即同步 visible；motion 时置 isTransitioning=true。
+  // 写读分离：只依赖 isOpen/motion，不读自身 visible/isTransitioning。
+  // cacheIsOpen 故意只快照 isOpen 初始值（对齐 Semi cacheIsOpen，后续在 $effect 内比对更新）。
+  // svelte-ignore state_referenced_locally
+  let cacheIsOpen = isOpen;
+  $effect(() => {
+    if (isOpen !== cacheIsOpen) {
+      if (isOpen || !motion) visible = isOpen;
+      if (motion) isTransitioning = true;
+      cacheIsOpen = isOpen;
+    }
+  });
+
+  const shouldRender = $derived(
+    collapsibleShouldRender({
+      isOpen,
+      keepDOM,
+      lazyRender,
+      collapseHeight,
+      visible,
+      hasBeenRendered,
+    }),
+  );
+  // 渲染后置位 hasBeenRendered（普通变量，非响应式；规避 §9.3 render 期写 $state）。
+  $effect(() => {
+    if (shouldRender) hasBeenRendered = true;
+  });
+
+  // --- JS 测高（ResizeObserver + scrollHeight），对齐 Semi componentDidMount / handleResize ---
+  let domEl: HTMLDivElement | null = $state(null);
+
+  // 从 ResizeObserverEntry 取「是否在渲染树」与「高度」，对齐 Semi getEntryInfo。
+  function getEntryInfo(entry: ResizeObserverEntry): { isShown: boolean; height: number } {
+    if (entry.borderBoxSize && entry.borderBoxSize[0]) {
+      const box = entry.borderBoxSize[0];
+      return {
+        isShown: !(box.blockSize === 0 && box.inlineSize === 0),
+        height: Math.ceil(box.blockSize),
+      };
+    }
+    const rect = entry.contentRect;
+    return {
+      isShown: !(rect.height === 0 && rect.width === 0),
+      height: (entry.target as HTMLElement).clientHeight,
+    };
+  }
+
+  $effect(() => {
+    if (!domEl || typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (!entry) return;
+      const info = getEntryInfo(entry);
+      // 写在 RO 回调（异步宏任务），与 render 读分离。
+      if (domHeight !== info.height) domHeight = info.height;
+      if (domInRenderTree !== info.isShown) domInRenderTree = info.isShown;
+    });
+    ro.observe(domEl);
+    // 挂载即测一次（对齐 Semi componentDidMount：offsetHeight>0 判定在渲染树后测 scrollHeight）。
+    const inTree = domEl.offsetHeight > 0;
+    domInRenderTree = inTree;
+    if (inTree) domHeight = domEl.scrollHeight;
+    return () => ro.disconnect();
+  });
+
+  // reCalcKey 变更 / 重回渲染树时重测（对齐 Semi componentDidUpdate）。
+  $effect(() => {
+    void reCalcKey;
+    if (domInRenderTree && domEl) {
+      const h = domEl.scrollHeight;
+      if (h !== domHeight) domHeight = h;
+    }
+  });
+
+  const collapsedHeight = $derived(
+    collapsibleCollapsedHeight(collapseHeight, collapseHeightAdaptive, domHeight),
+  );
+
+  // wrapper 显式高度（对齐 Semi）：展开=实测内容高度，折叠=collapsedHeight。
+  const wrapperHeight = $derived(`${isOpen ? domHeight : collapsedHeight}px`);
+  // opacity（对齐 Semi）：展开 / 未开 fade / collapseHeight!==0 时为 1，否则 0。
+  const wrapperOpacity = $derived(isOpen || !fade || collapseHeight !== 0 ? 1 : 0);
+  // 过渡时长：仅 motion 且过渡进行中为 duration，否则 0（对齐 Semi）。
+  const transitionDuration = $derived(`${motion && isTransitioning ? duration : 0}ms`);
+
+  function handleTransitionEnd(): void {
+    if (!isOpen) visible = false;
+    isTransitioning = false;
+    onMotionEnd?.();
+  }
+
+  const wrapperClass = $derived(
+    ['cd-collapsible-wrapper', motion && isTransitioning && 'cd-collapsible-transition', className]
+      .filter(Boolean)
+      .join(' '),
+  );
+</script>
+
+<div
+  class={wrapperClass}
+  style:height={wrapperHeight}
+  style:opacity={wrapperOpacity}
+  style:transition-duration={transitionDuration}
+  {style}
+  ontransitionend={handleTransitionEnd}
+>
+  <div bind:this={domEl} class="cd-collapsible-content" {id}>
+    {#if shouldRender}{@render children?.()}{/if}
+  </div>
+</div>
+
+<style>
+  /* wrapper：显式 height 过渡，overflow hidden 裁剪。对齐 Semi .semi-collapsible-wrapper。 */
+  .cd-collapsible-wrapper {
+    overflow: hidden;
+  }
+  /* 仅过渡进行中挂载：height + opacity 过渡。对齐 Semi .semi-collapsible-transition。 */
+  .cd-collapsible-transition {
+    transition:
+      height var(--cd-transition-duration-collapsible-height)
+        var(--cd-transition-function-collapsible-height)
+        var(--cd-transition-delay-collapsible-height),
+      opacity var(--cd-transition-duration-collapsible-opacity)
+        var(--cd-transition-function-collapsible-opacity)
+        var(--cd-transition-delay-collapsible-opacity);
+  }
+  /* 内容层：overflow hidden（对齐 Semi 内层 div style）。 */
+  .cd-collapsible-content {
+    overflow: hidden;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .cd-collapsible-transition {
+      transition-duration: 0ms !important;
+    }
+  }
+</style>

package/dist/collapsible/Collapsible.svelte.d.ts

@@ -0,0 +1,35 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    /** 是否展开内容区域。 */
+    isOpen?: boolean;
+    /** 动画执行的时间（ms）。 */
+    duration?: number;
+    /** 是否开启动画（false 即时显隐）。 */
+    motion?: boolean;
+    /** 是否保留隐藏的面板 DOM 树（默认销毁）。 */
+    keepDOM?: boolean;
+    /** 配合 keepDOM 使用，为 true 时挂载时不会渲染组件（首帧惰性）。 */
+    lazyRender?: boolean;
+    /** 折叠高度（px，0=完全折叠；>0=保留部分作「展开更多」）。 */
+    collapseHeight?: number;
+    /** 当内容高度小于 collapseHeight 时，是否自适应内容高度（收起高度取 min(内容高度, collapseHeight)）。 */
+    collapseHeightAdaptive?: boolean;
+    /** 是否开启淡入淡出。 */
+    fade?: boolean;
+    /** 变更时重新计算子节点高度，用于优化动态渲染时的计算。 */
+    reCalcKey?: number | string | undefined;
+    /** id，会设置到 wrapper 内容元素，可配合其他组件的 aria-controls 指明控制关系。 */
+    id?: string;
+    /** 动画结束的回调。 */
+    onMotionEnd?: (() => void) | undefined;
+    /** 根节点 class。 */
+    class?: string;
+    /** 根节点内联样式。 */
+    style?: string;
+    /** 被折叠的内容。 */
+    children?: Snippet;
+}
+declare const Collapsible: import("svelte").Component<Props, {}, "">;
+type Collapsible = ReturnType<typeof Collapsible>;
+export default Collapsible;
+//# sourceMappingURL=Collapsible.svelte.d.ts.map

package/dist/collapsible/Collapsible.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Collapsible.svelte.d.ts","sourceRoot":"","sources":["../../src/collapsible/Collapsible.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAIpC,UAAU,KAAK;IACb,gBAAgB;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mBAAmB;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,sCAAsC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,gBAAgB;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACxC,0DAA0D;IAC1D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,eAAe;IACf,WAAW,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IACvC,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAmJH,QAAA,MAAM,WAAW,2CAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}

package/dist/collapsible/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Collapsible } from './Collapsible.svelte';
+export { meta as collapsibleMeta } from './meta.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/collapsible/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/collapsible/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,IAAI,IAAI,eAAe,EAAE,MAAM,WAAW,CAAC"}

package/dist/collapsible/index.js

@@ -0,0 +1,2 @@
+export { default as Collapsible } from './Collapsible.svelte';
+export { meta as collapsibleMeta } from './meta.js';

package/dist/collapsible/meta.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export declare const meta: {
+    readonly name: "Collapsible";
+    readonly category: "show";
+    readonly semiEquivalent: "Collapsible";
+    readonly relatedTo: "Collapse";
+    readonly description: "折叠容器原语：对任意内容做高度折叠/展开过渡，无触发器 UI（aria-expanded 由使用方提供）。是 Collapse 手风琴的底层能力，作为独立原语暴露以支持 keepDOM / lazyRender / collapseHeight 等精细控制。机制镜像 Semi：ResizeObserver 测内容高度 + wrapper 显式 height 过渡，仅过渡进行中挂载 transition class。";
+    readonly props: readonly [{
+        readonly name: "isOpen";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "是否展开";
+    }, {
+        readonly name: "duration";
+        readonly type: "number";
+        readonly default: "250";
+        readonly desc: "过渡时长（ms）";
+    }, {
+        readonly name: "motion";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "是否启用过渡动画（false 即时显隐）";
+    }, {
+        readonly name: "keepDOM";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "折叠时是否保留 DOM（false 则完全折叠后移除内容 DOM）";
+    }, {
+        readonly name: "lazyRender";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "首次展开前不渲染内容（配合 keepDOM，首帧惰性）";
+    }, {
+        readonly name: "collapseHeight";
+        readonly type: "number";
+        readonly default: "0";
+        readonly desc: "折叠时保留的高度（px，0=完全折叠；>0=保留部分作「展开更多」）";
+    }, {
+        readonly name: "collapseHeightAdaptive";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "折叠高度是否自适应（不超过实测内容高度）";
+    }, {
+        readonly name: "fade";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "折叠时是否叠加透明度渐变";
+    }, {
+        readonly name: "reCalcKey";
+        readonly type: "number | string";
+        readonly default: "undefined";
+        readonly desc: "变更时强制重算高度（内容动态变化后触发重测，仅 collapseHeight>0 生效）";
+    }, {
+        readonly name: "id";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "内容容器 id";
+    }, {
+        readonly name: "onMotionEnd";
+        readonly type: "() => void";
+        readonly default: "undefined";
+        readonly desc: "展开/折叠过渡动画结束回调";
+    }, {
+        readonly name: "class";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "根节点 class";
+    }, {
+        readonly name: "style";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "根节点内联样式";
+    }, {
+        readonly name: "children";
+        readonly type: "Snippet";
+        readonly default: "undefined";
+        readonly desc: "被折叠的内容";
+    }];
+    readonly a11y: {
+        readonly role: "presentation";
+        readonly keyboard: readonly [];
+        readonly notes: readonly ["折叠时 wrapper overflow:hidden 裁剪内容；完全折叠（不 keepDOM 且 collapseHeight===0）后内容 DOM 卸载移出可达性树", "原语不含触发器：aria-expanded / aria-controls 由使用方（或 Collapse）提供；id 透传至内容元素供 aria-controls 关联", "reduced-motion：motion=true 但用户 prefers-reduced-motion 时移除过渡（即时）"];
+    };
+    readonly examples: readonly [{
+        readonly title: "基本用法";
+        readonly desc: "isOpen 驱动高度过渡（ResizeObserver 测高 + 显式 height）";
+    }, {
+        readonly title: "自定义动画时间";
+        readonly desc: "duration 设置过渡时长，motion=false 关闭动画";
+    }, {
+        readonly title: "嵌套使用";
+        readonly desc: "Collapsible 可嵌套，父子各自 isOpen 独立控制";
+    }, {
+        readonly title: "自定义折叠高度";
+        readonly desc: "collapseHeight 保留部分高度呈现截断，配合遮罩「展开更多」";
+    }, {
+        readonly title: "fade 渐变";
+        readonly desc: "折叠时叠加透明度渐变";
+    }, {
+        readonly title: "keepDOM 保留 DOM";
+        readonly desc: "折叠后内容 DOM 不卸载（保留表单状态/滚动位置）";
+    }, {
+        readonly title: "lazyRender 惰性";
+        readonly desc: "首次展开前不渲染内容，省首屏成本（配合 keepDOM）";
+    }, {
+        readonly title: "无障碍 id 关联";
+        readonly desc: "id 透传内容元素，配合触发器 aria-controls / aria-expanded";
+    }];
+    readonly doNot: readonly ["需要手风琴分组 UI（头部/箭头/分组）时改用 Collapse，Collapsible 只是无 UI 的折叠原语", "简单显隐无动画用 {#if} 即可，无需 Collapsible", "不要在 reduced-motion 下保留过渡（组件已自动移除）"];
+    readonly tokens: readonly ["--cd-transition-function-collapsible-height", "--cd-transition-duration-collapsible-height", "--cd-transition-delay-collapsible-height", "--cd-transition-function-collapsible-opacity", "--cd-transition-duration-collapsible-opacity", "--cd-transition-delay-collapsible-opacity"];
+};
+//# sourceMappingURL=meta.d.ts.map

package/dist/collapsible/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/collapsible/meta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqFP,CAAC"}

package/dist/collapsible/meta.js

@@ -0,0 +1,89 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export const meta = {
+    name: 'Collapsible',
+    category: 'show',
+    semiEquivalent: 'Collapsible',
+    relatedTo: 'Collapse',
+    description: '折叠容器原语：对任意内容做高度折叠/展开过渡，无触发器 UI（aria-expanded 由使用方提供）。是 Collapse 手风琴的底层能力，作为独立原语暴露以支持 keepDOM / lazyRender / collapseHeight 等精细控制。机制镜像 Semi：ResizeObserver 测内容高度 + wrapper 显式 height 过渡，仅过渡进行中挂载 transition class。',
+    props: [
+        { name: 'isOpen', type: 'boolean', default: 'false', desc: '是否展开' },
+        { name: 'duration', type: 'number', default: '250', desc: '过渡时长（ms）' },
+        { name: 'motion', type: 'boolean', default: 'true', desc: '是否启用过渡动画（false 即时显隐）' },
+        {
+            name: 'keepDOM',
+            type: 'boolean',
+            default: 'false',
+            desc: '折叠时是否保留 DOM（false 则完全折叠后移除内容 DOM）',
+        },
+        {
+            name: 'lazyRender',
+            type: 'boolean',
+            default: 'false',
+            desc: '首次展开前不渲染内容（配合 keepDOM，首帧惰性）',
+        },
+        {
+            name: 'collapseHeight',
+            type: 'number',
+            default: '0',
+            desc: '折叠时保留的高度（px，0=完全折叠；>0=保留部分作「展开更多」）',
+        },
+        {
+            name: 'collapseHeightAdaptive',
+            type: 'boolean',
+            default: 'false',
+            desc: '折叠高度是否自适应（不超过实测内容高度）',
+        },
+        { name: 'fade', type: 'boolean', default: 'false', desc: '折叠时是否叠加透明度渐变' },
+        {
+            name: 'reCalcKey',
+            type: 'number | string',
+            default: 'undefined',
+            desc: '变更时强制重算高度（内容动态变化后触发重测，仅 collapseHeight>0 生效）',
+        },
+        { name: 'id', type: 'string', default: 'undefined', desc: '内容容器 id' },
+        {
+            name: 'onMotionEnd',
+            type: '() => void',
+            default: 'undefined',
+            desc: '展开/折叠过渡动画结束回调',
+        },
+        { name: 'class', type: 'string', default: 'undefined', desc: '根节点 class' },
+        { name: 'style', type: 'string', default: 'undefined', desc: '根节点内联样式' },
+        { name: 'children', type: 'Snippet', default: 'undefined', desc: '被折叠的内容' },
+    ],
+    a11y: {
+        role: 'presentation',
+        keyboard: [],
+        notes: [
+            '折叠时 wrapper overflow:hidden 裁剪内容；完全折叠（不 keepDOM 且 collapseHeight===0）后内容 DOM 卸载移出可达性树',
+            '原语不含触发器：aria-expanded / aria-controls 由使用方（或 Collapse）提供；id 透传至内容元素供 aria-controls 关联',
+            'reduced-motion：motion=true 但用户 prefers-reduced-motion 时移除过渡（即时）',
+        ],
+    },
+    examples: [
+        { title: '基本用法', desc: 'isOpen 驱动高度过渡（ResizeObserver 测高 + 显式 height）' },
+        { title: '自定义动画时间', desc: 'duration 设置过渡时长，motion=false 关闭动画' },
+        { title: '嵌套使用', desc: 'Collapsible 可嵌套，父子各自 isOpen 独立控制' },
+        { title: '自定义折叠高度', desc: 'collapseHeight 保留部分高度呈现截断，配合遮罩「展开更多」' },
+        { title: 'fade 渐变', desc: '折叠时叠加透明度渐变' },
+        { title: 'keepDOM 保留 DOM', desc: '折叠后内容 DOM 不卸载（保留表单状态/滚动位置）' },
+        { title: 'lazyRender 惰性', desc: '首次展开前不渲染内容，省首屏成本（配合 keepDOM）' },
+        { title: '无障碍 id 关联', desc: 'id 透传内容元素，配合触发器 aria-controls / aria-expanded' },
+    ],
+    doNot: [
+        '需要手风琴分组 UI（头部/箭头/分组）时改用 Collapse，Collapsible 只是无 UI 的折叠原语',
+        '简单显隐无动画用 {#if} 即可，无需 Collapsible',
+        '不要在 reduced-motion 下保留过渡（组件已自动移除）',
+    ],
+    tokens: [
+        '--cd-transition-function-collapsible-height',
+        '--cd-transition-duration-collapsible-height',
+        '--cd-transition-delay-collapsible-height',
+        '--cd-transition-function-collapsible-opacity',
+        '--cd-transition-duration-collapsible-opacity',
+        '--cd-transition-delay-collapsible-opacity',
+    ],
+};