@chenzy-design/svelte 0.3.0 → 0.4.1

package/dist/timeline/Timeline.svelte.d.ts

@@ -1,29 +1,16 @@
 import type { Snippet } from 'svelte';
+import { type TimelineMode } from './context.js';
 import type { TimelineItemData } from './types.js';
-type Mode = 'left' | 'right' | 'alternate' | 'center';
-type Direction = 'vertical' | 'horizontal';
-type Size = 'small' | 'default' | 'large';
-type LineStyle = 'solid' | 'dashed';
 interface Props {
-    dataSource?: TimelineItemData[];
-    mode?: Mode;
-    direction?: Direction;
-    reverse?: boolean;
-    pending?: boolean | string;
-    size?: Size;
-    lineStyle?: LineStyle;
+    /** 通过 mode 改变时间轴和内容的相对位置。 */
+    mode?: TimelineMode;
     class?: string;
-    /** 虚拟化：长时间轴只渲染视口内项（仅 dataSource 模式生效，强制 vertical）。 */
-    virtualized?: boolean;
-    /** 虚拟化固定项高（px），默认 56。 */
-    itemHeight?: number;
-    /** 虚拟化视口最大高（px 数字或 CSS 字符串），默认 400。 */
-    maxHeight?: number | string;
-    /** 虚拟化上下缓冲项数，默认 3。 */
-    overscan?: number;
-    /** interactive：项可聚焦 + 方向键 roving 漫游 + Enter/Space 触发 onClick。 */
-    interactive?: boolean;
-    /** 声明式用法：内嵌 <Timeline.Item> 列表（不传 dataSource 时生效）。 */
+    style?: string;
+    /** 时间轴数据源，支持 content 属性及 Timeline.Item 的所有属性。 */
+    dataSource?: TimelineItemData[];
+    /** 无障碍标签。 */
+    'aria-label'?: string;
+    /** 声明式用法：内嵌 <Timeline.Item> 列表（未传 dataSource 时生效）。 */
     children?: Snippet;
 }
 declare const Timeline: import("svelte").Component<Props, {}, "">;

package/dist/timeline/Timeline.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Timeline.svelte.d.ts","sourceRoot":"","sources":["../../src/timeline/Timeline.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAWjD,KAAK,IAAI,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAC;AACtD,KAAK,SAAS,GAAG,UAAU,GAAG,YAAY,CAAC;AAC3C,KAAK,IAAI,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAC1C,KAAK,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEpC,UAAU,KAAK;IACb,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,yBAAyB;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,sBAAsB;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA2TH,QAAA,MAAM,QAAQ,2CAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"Timeline.svelte.d.ts","sourceRoot":"","sources":["../../src/timeline/Timeline.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGjD,UAAU,KAAK;IACb,6BAA6B;IAC7B,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,aAAa;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAmFH,QAAA,MAAM,QAAQ,2CAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}

package/dist/timeline/TimelineItem.svelte

@@ -1,164 +1,122 @@
 <!--
-  Timeline.Item — 声明式单项，与 dataSource 模式渲染同一套 .cd-timeline__item 结构，
-  从而复用父 Timeline 的 :nth-child 交替布局 CSS（alternate/center）与方向样式，无需索引计算。
-
-  interactive：父 Timeline 开启时，项渲染为可聚焦 role=button，roving tabindex 由父持有的
-  焦点 id 决定（getter 经 context 保持响应性，项不写 $state——红线 #2）。方向键 roving 上交父级
-  处理，Enter/Space 触发本项 onClick。挂载时经 context 领号、卸载时退号（命令式 cleanup）。
+  Timeline.Item — 严格对齐 Semi timeline/item.tsx。
+  DOM：<li class="cd-timeline-item {posCls} {class}"> > .item-tail + .item-head(-custom/-{type}) + .item-content(children + extra + time)。
+  位置类 posCls 对齐 Semi getPosCls：
+    - 显式 position → cd-timeline-item-{position}（覆盖父 mode）
+    - alternate → 无 position 时按兄弟顺序索引奇偶 left/right
+    - center → 无 position 时统一 left
+    - left/right → cd-timeline-item-{mode}
+  声明式子项经 context 拿父 mode 与自身顺序索引；dataSource 模式由父 Timeline 直接传 posCls（此时 mode/index 为 undefined，走 posClass prop 分支）。
 -->
 <script lang="ts">
   import { untrack, type Snippet } from 'svelte';
-  import { getTimelineContext, type TimelineLineStyle } from './context.js';
+  import { getTimelineContext } from './context.js';
+  import type { TimelineItemType, TimelineItemPosition } from './types.js';
 
   interface Props {
-    /** 圆点颜色（等价 dataSource 项的 dotColor/color）。 */
-    dotColor?: string;
-    /** 圆点颜色别名（与 dotColor 等价，优先级低于 dotColor）。 */
-    color?: string;
-    /** 语义类型，给圆点附加 cd-timeline__dot--{type} class。 */
-    type?: 'default' | 'ongoing' | 'success' | 'warning' | 'error';
-    /** 自定义圆点 snippet，提供时替代默认圆点。 */
-    dot?: Snippet;
-    /** 单项连接线样式，覆盖父 Timeline 的 lineStyle。 */
-    lineStyle?: TimelineLineStyle;
-    /** 时间文本，渲染在内容下方（horizontal 模式同 dataSource）。 */
-    time?: string;
-    /** 覆盖父 Timeline mode 的单项定位（'left' | 'right'）。 */
-    position?: 'left' | 'right';
-    /** 辅助内容（时间旁附加信息），字符串或 Snippet。 */
-    extra?: string | Snippet;
-    /** interactive 模式下按 Enter/Space 或点击该节点触发。 */
-    onClick?: () => void;
-    children?: Snippet;
+    /** 自定义圆点色值（对齐 Semi color，设置 head backgroundColor）。 */
+    color?: string | undefined;
+    /** 时间文本，渲染在内容下方。 */
+    time?: string | Snippet | undefined;
+    /** 当前圆点模式。 */
+    type?: TimelineItemType | undefined;
+    /** 自定义时间轴点（提供时 head 附加 -custom class）。 */
+    dot?: string | Snippet | undefined;
+    /** 自定义辅助内容，渲染在内容与时间之间。 */
+    extra?: string | Snippet | undefined;
+    /** 自定义节点位置，覆盖 Timeline 的 mode 选项。 */
+    position?: TimelineItemPosition | undefined;
+    class?: string | undefined;
+    style?: string | undefined;
+    /** 鼠标点击事件的回调。 */
+    onClick?: ((e: MouseEvent) => void) | undefined;
+    /** 内部：dataSource 模式下父 Timeline 直接注入的位置类（优先于 context 计算）。 */
+    posClass?: string | undefined;
+    children?: Snippet | undefined;
   }
 
-  let { dotColor, color, type, dot, lineStyle, time, position, extra, onClick, children }: Props = $props();
+  let {
+    color,
+    time,
+    type = 'default',
+    dot,
+    extra,
+    position,
+    class: className,
+    style,
+    onClick,
+    posClass,
+    children,
+  }: Props = $props();
 
   const ctx = getTimelineContext();
 
-  // 未显式指定时回退到父 Timeline 的 lineStyle。
-  const effectiveLine = $derived<TimelineLineStyle>(lineStyle ?? ctx?.getLineStyle() ?? 'solid');
-
-  // dotColor 优先，其次 color 别名。
-  const effectiveDotColor = $derived(dotColor ?? color);
-
-  const dotInline = $derived(effectiveDotColor ? `--cd-timeline-dot-current: ${effectiveDotColor};` : undefined);
-
-  const dotClass = $derived(
-    ['cd-timeline__dot', type && type !== 'default' && `cd-timeline__dot--${type}`]
-      .filter(Boolean)
-      .join(' '),
-  );
-
-  // interactive：在 $effect 内 mount 领号 / unmount 退号（仿 Tabs；untrack 读初值仅跑一次，
-  // 避免重注册打乱保序）。项自身不参与 roving 簿记 $state。
-  const interactive = $derived(ctx?.getInteractive() ?? false);
-  let myId = $state(-1);
+  // 声明式：挂载登记，getIndex() 反映本项在兄弟中的当前顺序索引（alternate 奇偶用）。
+  // getIndex 依赖父级 version（每次兄弟增减 bump），故 $derived 读取即保持响应。
+  let handle = $state<{ getIndex: () => number; unregister: () => void } | null>(null);
   $effect(() => {
     const reg = ctx?.registerItem;
     if (!reg) return;
     const r = untrack(() => reg());
-    myId = r.id;
-    return r.unregister;
+    handle = r;
+    return () => {
+      r.unregister();
+      handle = null;
+    };
   });
+  const index = $derived(handle?.getIndex() ?? 0);
 
-  // roving tabindex：焦点项 0，其余 -1（焦点状态经 context getter 读取，保持响应性）。
-  const tindex = $derived(interactive && myId >= 0 && ctx?.isFocused(myId) ? 0 : -1);
+  const mode = $derived(ctx?.getMode() ?? 'left');
 
-  function onKeydown(e: KeyboardEvent): void {
-    if (!interactive) return;
-    // Enter/Space 触发本项 onClick；方向键 roving 交父级。
-    if (e.key === 'Enter' || e.key === ' ') {
-      e.preventDefault();
-      onClick?.();
-      return;
-    }
-    ctx?.onItemKeydown(myId, e);
-  }
+  // 位置类：对齐 Semi getPosCls。dataSource 模式由父传 posClass 直接用。
+  const positionClass = $derived.by(() => {
+    if (posClass !== undefined) return posClass;
+    if (position) return `cd-timeline-item-${position}`;
+    if (mode === 'alternate') return index % 2 === 0 ? 'cd-timeline-item-left' : 'cd-timeline-item-right';
+    if (mode === 'center') return 'cd-timeline-item-left';
+    if (mode === 'left' || mode === 'right') return `cd-timeline-item-${mode}`;
+    return '';
+  });
 
-  function onActivate(): void {
-    if (!interactive) {
-      onClick?.();
-      return;
-    }
-    ctx?.onItemFocus(myId);
-    onClick?.();
-  }
-</script>
+  const itemCls = $derived(
+    ['cd-timeline-item', positionClass, className].filter(Boolean).join(' '),
+  );
+
+  const headCls = $derived(
+    [
+      'cd-timeline-item-head',
+      dot && 'cd-timeline-item-head-custom',
+      type && `cd-timeline-item-head-${type}`,
+    ]
+      .filter(Boolean)
+      .join(' '),
+  );
 
-{#if interactive}
-  <!-- svelte-ignore a11y_no_noninteractive_element_to_interactive_role -->
-  <li
-    class={[
-      'cd-timeline__item',
-      'cd-timeline__item--interactive',
-      effectiveLine === 'dashed' && 'cd-timeline__item--dashed',
-      position && `cd-timeline__item--${position}`,
-    ]}
-    role="button"
-    tabindex={tindex}
-    data-tid={myId}
-    onclick={onActivate}
-    onkeydown={onKeydown}
-    onfocus={() => ctx?.onItemFocus(myId)}
-  >
-    <span class="cd-timeline__tail" aria-hidden="true"></span>
-    <span class={dotClass} style={dotInline} aria-hidden="true">
-      {#if dot}{@render dot()}{/if}
-    </span>
-    <div class="cd-timeline__body">
-      <div class="cd-timeline__content">{@render children?.()}</div>
-      {#if time || extra}
-        <div class="cd-timeline__time">
-          {#if time}{time}{/if}
-          {#if extra}
-            {#if typeof extra === 'string'}
-              <span class="cd-timeline__extra">{extra}</span>
-            {:else}
-              <span class="cd-timeline__extra">{@render extra()}</span>
-            {/if}
-          {/if}
-        </div>
-      {/if}
-    </div>
-  </li>
-{:else}
-  <li
-    class={[
-      'cd-timeline__item',
-      effectiveLine === 'dashed' && 'cd-timeline__item--dashed',
-      position && `cd-timeline__item--${position}`,
-    ]}
-  >
-    <span class="cd-timeline__tail" aria-hidden="true"></span>
-    <span class={dotClass} style={dotInline} aria-hidden="true">
-      {#if dot}{@render dot()}{/if}
-    </span>
-    <div class="cd-timeline__body">
-      <div class="cd-timeline__content">{@render children?.()}</div>
-      {#if time || extra}
-        <div class="cd-timeline__time">
-          {#if time}{time}{/if}
-          {#if extra}
-            {#if typeof extra === 'string'}
-              <span class="cd-timeline__extra">{extra}</span>
-            {:else}
-              <span class="cd-timeline__extra">{@render extra()}</span>
-            {/if}
-          {/if}
-        </div>
-      {/if}
-    </div>
-  </li>
-{/if}
+  // color 设置 head 背景色（对齐 Semi dotStyle）。
+  const headStyle = $derived(color ? `background-color: ${color};` : undefined);
+</script>
 
-<style>
-  /* 单项 dashed 覆盖：作用于自身 tail，优先于父级 solid。 */
-  .cd-timeline__item--dashed .cd-timeline__tail {
-    border-inline-start-style: dashed;
-  }
-  :global(.cd-timeline--horizontal) .cd-timeline__item--dashed .cd-timeline__tail {
-    border-inline-start: none;
-    border-block-start-style: dashed;
-  }
-</style>
+<!-- Semi Timeline.Item 将 onClick 直接挂在 <li> 上（无键盘等价，节点本身非交互控件），此处忠实对齐。 -->
+<!-- svelte-ignore a11y_click_events_have_key_events -->
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<li class={itemCls} {style} onclick={onClick}>
+  <div class="cd-timeline-item-tail" aria-hidden="true"></div>
+  <div class={headCls} style={headStyle} aria-hidden="true">
+    {#if dot}
+      {#if typeof dot === 'string'}{dot}{:else}{@render dot()}{/if}
+    {/if}
+  </div>
+  <div class="cd-timeline-item-content">
+    {@render children?.()}
+    {#if extra}
+      <div class="cd-timeline-item-content-extra">
+        {#if typeof extra === 'string'}{extra}{:else}{@render extra()}{/if}
+      </div>
+    {/if}
+    {#if time}
+      <div class="cd-timeline-item-content-time">
+        {#if typeof time === 'string'}{time}{:else}{@render time()}{/if}
+      </div>
+    {/if}
+  </div>
+</li>

package/dist/timeline/TimelineItem.svelte.d.ts

@@ -1,25 +1,25 @@
 import { type Snippet } from 'svelte';
-import { type TimelineLineStyle } from './context.js';
+import type { TimelineItemType, TimelineItemPosition } from './types.js';
 interface Props {
-    /** 圆点颜色（等价 dataSource 项的 dotColor/color）。 */
-    dotColor?: string;
-    /** 圆点颜色别名（与 dotColor 等价，优先级低于 dotColor）。 */
-    color?: string;
-    /** 语义类型，给圆点附加 cd-timeline__dot--{type} class。 */
-    type?: 'default' | 'ongoing' | 'success' | 'warning' | 'error';
-    /** 自定义圆点 snippet，提供时替代默认圆点。 */
-    dot?: Snippet;
-    /** 单项连接线样式，覆盖父 Timeline 的 lineStyle。 */
-    lineStyle?: TimelineLineStyle;
-    /** 时间文本，渲染在内容下方（horizontal 模式同 dataSource）。 */
-    time?: string;
-    /** 覆盖父 Timeline mode 的单项定位（'left' | 'right'）。 */
-    position?: 'left' | 'right';
-    /** 辅助内容（时间旁附加信息），字符串或 Snippet。 */
-    extra?: string | Snippet;
-    /** interactive 模式下按 Enter/Space 或点击该节点触发。 */
-    onClick?: () => void;
-    children?: Snippet;
+    /** 自定义圆点色值（对齐 Semi color，设置 head backgroundColor）。 */
+    color?: string | undefined;
+    /** 时间文本，渲染在内容下方。 */
+    time?: string | Snippet | undefined;
+    /** 当前圆点模式。 */
+    type?: TimelineItemType | undefined;
+    /** 自定义时间轴点（提供时 head 附加 -custom class）。 */
+    dot?: string | Snippet | undefined;
+    /** 自定义辅助内容，渲染在内容与时间之间。 */
+    extra?: string | Snippet | undefined;
+    /** 自定义节点位置，覆盖 Timeline 的 mode 选项。 */
+    position?: TimelineItemPosition | undefined;
+    class?: string | undefined;
+    style?: string | undefined;
+    /** 鼠标点击事件的回调。 */
+    onClick?: ((e: MouseEvent) => void) | undefined;
+    /** 内部：dataSource 模式下父 Timeline 直接注入的位置类（优先于 context 计算）。 */
+    posClass?: string | undefined;
+    children?: Snippet | undefined;
 }
 declare const TimelineItem: import("svelte").Component<Props, {}, "">;
 type TimelineItem = ReturnType<typeof TimelineItem>;

package/dist/timeline/TimelineItem.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TimelineItem.svelte.d.ts","sourceRoot":"","sources":["../../src/timeline/TimelineItem.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGxE,UAAU,KAAK;IACb,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IAC/D,+BAA+B;IAC/B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,wCAAwC;IACxC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAyHH,QAAA,MAAM,YAAY,2CAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"TimelineItem.svelte.d.ts","sourceRoot":"","sources":["../../src/timeline/TimelineItem.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGvE,UAAU,KAAK;IACb,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,oBAAoB;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACpC,cAAc;IACd,IAAI,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACpC,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACnC,0BAA0B;IAC1B,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACrC,qCAAqC;IACrC,QAAQ,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,iBAAiB;IACjB,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAChD,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAgGH,QAAA,MAAM,YAAY,2CAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/timeline/context.d.ts

@@ -1,19 +1,15 @@
-export type TimelineLineStyle = 'solid' | 'dashed';
+export type TimelineMode = 'left' | 'right' | 'center' | 'alternate';
 export interface TimelineContext {
-    getLineStyle: () => TimelineLineStyle;
-    /** interactive 是否开启（getter 保持响应性）。 */
-    getInteractive: () => boolean;
-    /** 声明式项挂载时领号，返回 id 与卸载清理；id 构成 roving 序列。 */
+    /** 父 Timeline 的 mode（getter 保持响应性）。 */
+    getMode: () => TimelineMode;
+    /**
+     * 声明式子项挂载时登记，返回本项在兄弟中的顺序索引（0 起）与卸载清理。
+     * 索引用于 alternate 模式的奇偶左右交替（对齐 Semi getPosCls 的 idx 判定）。
+     */
     registerItem: () => {
-        id: number;
+        getIndex: () => number;
         unregister: () => void;
     };
-    /** 该 id 是否为当前 roving 焦点项（决定 tabindex 0/-1）。 */
-    isFocused: (id: number) => boolean;
-    /** 声明式项键盘事件冒泡到父：方向键 roving 由父处理（Enter/Space 由项自身处理）。 */
-    onItemKeydown: (id: number, e: KeyboardEvent) => void;
-    /** 项获得焦点时同步父级焦点索引（点击/Tab 进入）。 */
-    onItemFocus: (id: number) => void;
 }
 export declare function setTimelineContext(ctx: TimelineContext): void;
 export declare function getTimelineContext(): TimelineContext | undefined;

package/dist/timeline/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/timeline/context.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEnD,MAAM,WAAW,eAAe;IAE9B,YAAY,EAAE,MAAM,iBAAiB,CAAC;IACtC,sCAAsC;IACtC,cAAc,EAAE,MAAM,OAAO,CAAC;IAC9B,6CAA6C;IAC7C,YAAY,EAAE,MAAM;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;IAC3D,+CAA+C;IAC/C,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,wDAAwD;IACxD,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,aAAa,KAAK,IAAI,CAAC;IACtD,iCAAiC;IACjC,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAID,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAE7D;AAED,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/timeline/context.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,OAAO,EAAE,MAAM,YAAY,CAAC;IAC5B;;;OAGG;IACH,YAAY,EAAE,MAAM;QAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;CACxE;AAID,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAE7D;AAED,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE"}

package/dist/timeline/index.d.ts

@@ -5,6 +5,6 @@ export declare const Timeline: typeof Timeline_ & {
 };
 export { TimelineItem };
 export { meta as timelineMeta } from './meta.js';
-export type { TimelineItemData } from './types.js';
-export { getTimelineContext, setTimelineContext, type TimelineContext, type TimelineLineStyle, } from './context.js';
+export type { TimelineItemData, TimelineItemType, TimelineItemPosition, } from './types.js';
+export { getTimelineContext, setTimelineContext, type TimelineContext, type TimelineMode, } from './context.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/timeline/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAC1C,OAAO,YAAY,MAAM,uBAAuB,CAAC;AAEjD,eAAO,MAAM,QAAQ,EAAE,OAAO,SAAS,GAAG;IACxC,IAAI,EAAE,OAAO,YAAY,CAAC;CACwB,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,CAAC;AACxB,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,WAAW,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/timeline/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAC1C,OAAO,YAAY,MAAM,uBAAuB,CAAC;AAEjD,eAAO,MAAM,QAAQ,EAAE,OAAO,SAAS,GAAG;IACxC,IAAI,EAAE,OAAO,YAAY,CAAC;CACwB,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,CAAC;AACxB,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,WAAW,CAAC;AACjD,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC"}

package/dist/timeline/meta.d.ts

@@ -1,138 +1,102 @@
 /**
  * Machine-readable component metadata for AI/docs consumption.
  * See specs/00-foundation/ai-friendly.spec.md.
+ * 严格对齐 Semi timeline API（index.tsx / item.tsx）。
  */
 export declare const meta: {
     readonly name: "Timeline";
     readonly category: "show";
-    readonly description: "时间轴，按时间顺序垂直/水平展示一组事件。两种用法择一：传 dataSource 数据驱动，或不传 dataSource 而在 children 内写 <Timeline.Item> 声明式（可放任意富内容）。支持 left/right/alternate/center 模式、vertical/horizontal 方向、pending 幽灵节点、reverse 倒序与实/虚线样式；交替布局由纯 CSS :nth-child 决定，两种用法共用同一套结构与样式。";
+    readonly description: "时间轴，用于对一系列信息进行时间排序时垂直展示。两种用法择一：传 dataSource 数据驱动（支持 content 属性及 Timeline.Item 全部属性），或在 children 内写 <Timeline.Item> 声明式。通过 mode 设置时间轴与内容的相对位置：left（默认）/right/center/alternate。";
     readonly props: readonly [{
-        readonly name: "dataSource";
-        readonly type: "TimelineItemData[]";
-        readonly default: "[]";
-        readonly desc: "节点数据（数据驱动用法；优先于声明式 children）";
-    }, {
-        readonly name: "children";
-        readonly type: "Snippet";
-        readonly default: "undefined";
-        readonly desc: "声明式用法：内嵌 <Timeline.Item> 列表，仅在未传 dataSource 时生效";
-    }, {
         readonly name: "mode";
-        readonly type: "'left'|'right'|'alternate'|'center'";
+        readonly type: "'left'|'right'|'center'|'alternate'";
         readonly default: "left";
-        readonly desc: "right 轴线在右、内容靠右对齐（left 镜像）；center 轴线居中、两侧内容朝轴对称对齐";
-    }, {
-        readonly name: "direction";
-        readonly type: "'vertical'|'horizontal'";
-        readonly default: "vertical";
-        readonly desc: "时间轴方向";
-    }, {
-        readonly name: "reverse";
-        readonly type: "boolean";
-        readonly default: "false";
-        readonly desc: "倒序展示";
-    }, {
-        readonly name: "pending";
-        readonly type: "boolean|string";
-        readonly default: "false";
-        readonly desc: "末尾追加幽灵节点，string 作为其内容";
-    }, {
-        readonly name: "size";
-        readonly type: "'small'|'default'|'large'";
-        readonly default: "default";
-    }, {
-        readonly name: "lineStyle";
-        readonly type: "'solid'|'dashed'";
-        readonly default: "solid";
+        readonly desc: "通过设置 mode 可以改变时间轴和内容的相对位置";
     }, {
-        readonly name: "virtualized";
-        readonly type: "boolean";
-        readonly default: "false";
-        readonly desc: "虚拟化：长时间轴只渲染视口内项（复用 core fixedRange；仅 dataSource 模式生效，强制 vertical 列布局，轴线靠固定项高连续）";
-    }, {
-        readonly name: "itemHeight";
-        readonly type: "number";
-        readonly default: "56";
-        readonly desc: "虚拟化固定项高（px）";
-    }, {
-        readonly name: "maxHeight";
-        readonly type: "number|string";
-        readonly default: "400";
-        readonly desc: "虚拟化视口最大高（px 数字或 CSS 字符串）";
+        readonly name: "class";
+        readonly type: "string";
+        readonly default: "-";
+        readonly desc: "类名";
     }, {
-        readonly name: "overscan";
-        readonly type: "number";
-        readonly default: "3";
-        readonly desc: "虚拟化上下缓冲项数";
+        readonly name: "style";
+        readonly type: "string";
+        readonly default: "-";
+        readonly desc: "样式";
     }, {
-        readonly name: "interactive";
-        readonly type: "boolean";
-        readonly default: "false";
-        readonly desc: "roving tabindex 键盘漫游：项可聚焦，↑↓/←→ 移动焦点、Home/End 跳首尾、Enter/Space 触发项 onClick";
+        readonly name: "dataSource";
+        readonly type: "TimelineItemData[]";
+        readonly default: "-";
+        readonly desc: "时间轴数据源，支持 content 属性及 Timeline.Item 的所有属性";
     }, {
-        readonly name: "class";
+        readonly name: "aria-label";
         readonly type: "string";
-        readonly default: "''";
+        readonly default: "-";
+        readonly desc: "无障碍标签";
+    }, {
+        readonly name: "children";
+        readonly type: "Snippet";
+        readonly default: "-";
+        readonly desc: "声明式用法：内嵌 <Timeline.Item> 列表（未传 dataSource 时生效）";
     }];
     readonly subComponents: readonly [{
         readonly name: "Timeline.Item";
-        readonly desc: "声明式单项，渲染 dot/line/内容（children），与 dataSource 项视觉一致";
+        readonly desc: "时间轴单项，渲染节点圆点 / 连线 / 内容";
         readonly props: readonly [{
-            readonly name: "dotColor";
+            readonly name: "class";
             readonly type: "string";
-            readonly default: "undefined";
-            readonly desc: "圆点颜色";
+            readonly default: "-";
+            readonly desc: "类名";
         }, {
             readonly name: "color";
             readonly type: "string";
-            readonly default: "undefined";
-            readonly desc: "圆点颜色别名（与 dotColor 等价，dotColor 优先）";
-        }, {
-            readonly name: "type";
-            readonly type: "'default'|'ongoing'|'success'|'warning'|'error'";
-            readonly default: "undefined";
-            readonly desc: "语义类型，给圆点附加 cd-timeline__dot--{type} class";
+            readonly default: "-";
+            readonly desc: "自定义的圆圈色值";
         }, {
             readonly name: "dot";
-            readonly type: "Snippet";
-            readonly default: "undefined";
-            readonly desc: "自定义圆点 snippet，提供时替代默认圆点";
-        }, {
-            readonly name: "lineStyle";
-            readonly type: "'solid'|'dashed'";
-            readonly default: "继承父 Timeline";
-            readonly desc: "单项连接线样式";
+            readonly type: "string | Snippet";
+            readonly default: "-";
+            readonly desc: "自定义时间轴点";
         }, {
-            readonly name: "time";
-            readonly type: "string";
-            readonly default: "undefined";
-            readonly desc: "时间文本";
+            readonly name: "extra";
+            readonly type: "string | Snippet";
+            readonly default: "-";
+            readonly desc: "自定义辅助内容";
         }, {
             readonly name: "position";
             readonly type: "'left'|'right'";
-            readonly default: "undefined";
-            readonly desc: "覆盖父 Timeline mode 的单项定位";
+            readonly default: "-";
+            readonly desc: "自定义节点位置，可以覆盖 Timeline 的模式选项";
         }, {
-            readonly name: "extra";
+            readonly name: "style";
+            readonly type: "string";
+            readonly default: "-";
+            readonly desc: "样式";
+        }, {
+            readonly name: "time";
             readonly type: "string | Snippet";
-            readonly default: "undefined";
-            readonly desc: "时间旁辅助内容";
+            readonly default: "-";
+            readonly desc: "时间文本";
+        }, {
+            readonly name: "type";
+            readonly type: "'default'|'ongoing'|'success'|'warning'|'error'";
+            readonly default: "default";
+            readonly desc: "当前圆圈的模式";
         }, {
             readonly name: "onClick";
-            readonly type: "() => void";
-            readonly default: "undefined";
-            readonly desc: "interactive 模式下点击或 Enter/Space 触发";
+            readonly type: "(e: MouseEvent) => void";
+            readonly default: "-";
+            readonly desc: "鼠标点击事件的回调";
         }, {
             readonly name: "children";
             readonly type: "Snippet";
-            readonly default: "undefined";
-            readonly desc: "项内容";
+            readonly default: "-";
+            readonly desc: "节点内容";
         }];
     }];
     readonly a11y: {
         readonly role: "list";
-        readonly notes: readonly ["ul/li 结构", "圆点与连接线 aria-hidden=true", "内容与时间为可读文本", "interactive：项 role=button + roving tabindex（焦点项 tabindex=0 其余 -1），↑↓/←→ 移动焦点、Home/End 跳首尾、Enter/Space 激活，aria-label 取节点内容"];
+        readonly notes: readonly ["ul/li 结构", "时间点的连线以及时间点本身被设置了 aria-hidden，不会响应 Accessibility API", "可通过传入 aria-label 设置 Timeline 组件的标签"];
     };
-    readonly tokens: readonly ["--cd-timeline-*", "--cd-border-radius-full", "--cd-spacing-extra-tight", "--cd-font-size-small"];
+    readonly tokens: readonly ["--cd-color-timeline-dot-default-bg-default", "--cd-color-timeline-dot-success-bg-default", "--cd-color-timeline-dot-warning-bg-default", "--cd-color-timeline-dot-error-bg-default", "--cd-color-timeline-dot-info-bg-default", "--cd-color-timeline-tail-border", "--cd-color-timeline-time-default-text-default", "--cd-color-timeline-item-head-bg", "--cd-color-timeline-item-content-text-default", "--cd-spacing-timeline-margin", "--cd-spacing-timeline-padding", "--cd-spacing-timeline-tail-top", "--cd-spacing-timeline-tail-left", "--cd-spacing-timeline-head-top", "--cd-spacing-timeline-head-custom-top", "--cd-spacing-timeline-head-custom-left", "--cd-spacing-timeline-content-marginleft", "--cd-spacing-timeline-time-margintop", "--cd-spacing-timeline-time-top", "--cd-spacing-timeline-item-margin", "--cd-spacing-timeline-item-paddingbottom", "--cd-spacing-timeline-item-content-time-marginleft", "--cd-spacing-timeline-item-right-item-left", "--cd-spacing-timeline-item-right-item-content", "--cd-spacing-timeline-item-left-item-content-left", "--cd-spacing-timeline-item-head-custom-left", "--cd-spacing-timeline-item-head-marginleft", "--cd-width-timeline", "--cd-width-timeline-dot", "--cd-width-timeline-head-custom", "--cd-width-timeline-tail-border", "--cd-width-timeline-head-custom-border", "--cd-width-timeline-item-content-time", "--cd-width-timeline-item-right-content", "--cd-width-timeline-item-left-item-content", "--cd-width-timeline-item-right-item-content", "--cd-height-timeline-tail", "--cd-height-timeline-head-custom", "--cd-radius-timeline-head", "--cd-radius-timeline-head-custom", "--cd-motion-timeline-head-custom-transform"];
 };
 //# sourceMappingURL=meta.d.ts.map

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

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