@chenzy-design/svelte 0.3.1 → 0.4.1

package/dist/highlight/Highlight.svelte

@@ -1,99 +1,79 @@
 <!--
   Highlight — see specs/components/show/Highlight.spec.md
-  纯展示文本高亮：sourceString 中标记 searchWords。纯文本输出（不解析 HTML）。
-  片段分割 / 重叠区间合并为纯函数（@chenzy-design/core highlightChunks，红线 #2），
-  渲染派生：默认 <mark>，可由 highlight/chunk snippet 自定义。
-  支持单/多关键词、大小写敏感、highlightAll、autoEscape、自定义 component/类名/样式、
-  unstyled、命中片段 id + aria 关联。
+  纯展示文本高亮：镜像 Semi Highlight。sourceString 中标记 searchWords，命中片段默认用
+  <mark class="cd-highlight-tag"> 包裹，非命中片段原样输出纯文本（不解析 HTML）。
+  片段分割 / 重叠区间合并 / 差异化样式载荷为纯函数（@chenzy-design/core highlightChunks）。
+
+  对齐 Semi（semi-ui/highlight/index.tsx）：
+  - 无外层 wrapper，直接输出片段序列（Semi render 返回数组）。
+  - highlightClassName 追加到高亮 tag（Semi: cls({semi-highlight-tag:true}, highlightClassName)）。
+  - searchWords 支持对象数组 { text, className, style }（Semi v2.71 差异化样式）；每词 style/className
+    与组件级 highlightStyle/highlightClassName 合并（chunk 优先，对齐 Semi {...highlightStyle, ...chunk.style}）。
+  - component 指定高亮标签（默认 mark）。caseSensitive / autoEscape 透传匹配算法。
 -->
 <script lang="ts">
-  import type { Snippet } from 'svelte';
-  import { highlightChunks, useId } from '@chenzy-design/core';
+  import { highlightChunks, type HighlightWord } from '@chenzy-design/core';
 
   interface Props {
+    /** 源文本（纯文本，HTML 会被转义而非解析）。 */
     sourceString?: string;
-    searchWords?: string | string[];
+    /** 需高亮的关键词；string / string[]，或对象数组 { text, className, style } 差异化样式。 */
+    searchWords?: string | string[] | HighlightWord | HighlightWord[];
+    /** 是否大小写敏感匹配（默认 false）。 */
     caseSensitive?: boolean;
-    highlightAll?: boolean;
+    /** 是否对关键词做正则转义（默认 true）；关闭后 searchWords 视为正则源。 */
     autoEscape?: boolean;
+    /** 高亮片段包裹标签名（默认 mark）。 */
     component?: string;
+    /** 追加到每个高亮片段的类名。 */
     highlightClassName?: string;
+    /** 追加到每个高亮片段的内联样式（字符串）。 */
     highlightStyle?: string;
-    className?: string;
-    style?: string;
-    unstyled?: boolean;
-    /** 自定义命中片段渲染（覆盖默认 <mark>）。 */
-    highlight?: Snippet<[{ chunk: string; index: number }]>;
-    /** 自定义非命中片段渲染（默认裸文本）。 */
-    chunk?: Snippet<[{ chunk: string; index: number }]>;
-    /** 命中片段 id 前缀，用于 aria 关联；省略则自动生成。 */
-    idPrefix?: string;
-    /** 追加到每个命中片段的 aria-describedby（指向外部说明元素）。 */
-    describedById?: string;
-    /** 命中片段的 aria-label（默认不加，避免逐字播报噪音）。 */
-    highlightAriaLabel?: string;
   }
 
   let {
     sourceString = '',
     searchWords = [],
     caseSensitive = false,
-    highlightAll = true,
     autoEscape = true,
     component = 'mark',
     highlightClassName = '',
     highlightStyle = '',
-    className = '',
-    style = '',
-    unstyled = false,
-    highlight,
-    chunk,
-    idPrefix,
-    describedById,
-    highlightAriaLabel,
   }: Props = $props();
 
-  // 稳定前缀：仅在未显式传入时生成一次，render 期只读（红线 #2）。
-  const autoPrefix = useId('cd-highlight');
-  const prefix = $derived(idPrefix || autoPrefix);
+  // 片段分割 + 重叠区间合并 + 差异化样式载荷：纯函数（core），渲染只读派生。
+  const chunks = $derived(highlightChunks(sourceString, searchWords, { caseSensitive, autoEscape }));
 
-  // 片段分割 + 重叠区间合并：纯函数（core），渲染只读派生（红线 #2）。
-  const chunks = $derived(
-    highlightChunks(sourceString, searchWords, { caseSensitive, highlightAll, autoEscape }),
-  );
+  // 高亮 tag class：cd-highlight-tag + highlightClassName + chunk 各自 className（对齐 Semi cls 拼接）。
+  function tagClass(chunkClassName?: string): string {
+    return ['cd-highlight-tag', highlightClassName, chunkClassName].filter(Boolean).join(' ');
+  }
 
-  const rootClass = $derived(['cd-highlight', className].filter(Boolean).join(' '));
-  const markClass = $derived(
-    ['cd-highlight__mark', unstyled && 'cd-highlight__mark--unstyled', highlightClassName]
-      .filter(Boolean)
-      .join(' '),
-  );
+  // style 对象（差异化样式，React camelCase）→ CSS 字符串；与 highlightStyle 合并，chunk 优先。
+  function tagStyle(chunkStyle?: Record<string, string | number>): string | undefined {
+    const parts: string[] = [];
+    if (highlightStyle) parts.push(highlightStyle.trim().replace(/;\s*$/, ''));
+    if (chunkStyle) {
+      for (const [k, v] of Object.entries(chunkStyle)) {
+        const prop = k.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+        parts.push(`${prop}: ${typeof v === 'number' ? `${v}px` : v}`);
+      }
+    }
+    return parts.length ? `${parts.join('; ')};` : undefined;
+  }
 </script>
 
-<span class={rootClass} style={style || undefined}
-  >{#each chunks as item, i (i)}{#if item.matched}{#if highlight}{@render highlight({ chunk: item.text, index: i })}{:else}<svelte:element
-          this={component}
-          id={`${prefix}-${i}`}
-          class={markClass}
-          style={highlightStyle || undefined}
-          aria-label={highlightAriaLabel || undefined}
-          aria-describedby={describedById || undefined}>{item.text}</svelte:element>{/if}{:else if chunk}{@render chunk({ chunk: item.text, index: i })}{:else}{item.text}{/if}{/each}</span
->
+{#each chunks as item, i (i)}{#if item.highlight}<svelte:element
+      this={component}
+      class={tagClass(item.className)}
+      style={tagStyle(item.style)}>{item.text}</svelte:element
+    >{:else}{item.text}{/if}{/each}
 
 <style>
-  .cd-highlight {
-    color: inherit;
-  }
-  .cd-highlight__mark {
-    padding-inline: 2px;
-    border-radius: var(--cd-border-radius-small);
-    background: var(--cd-highlight-bg);
+  /* 镜像 Semi .semi-highlight-tag：仅 color / background-color / font-weight，无 padding、无 radius。 */
+  :global(.cd-highlight-tag) {
     color: var(--cd-highlight-color);
-    font-weight: var(--cd-highlight-weight); /* 对齐 Semi 高亮字重 600 */
-  }
-  .cd-highlight__mark--unstyled {
-    padding-inline: 0;
-    background: transparent;
-    color: inherit;
+    background-color: var(--cd-highlight-bg);
+    font-weight: var(--cd-highlight-font-weight);
   }
 </style>

package/dist/highlight/Highlight.svelte.d.ts

@@ -1,32 +1,19 @@
-import type { Snippet } from 'svelte';
+import { type HighlightWord } from '@chenzy-design/core';
 interface Props {
+    /** 源文本（纯文本，HTML 会被转义而非解析）。 */
     sourceString?: string;
-    searchWords?: string | string[];
+    /** 需高亮的关键词；string / string[]，或对象数组 { text, className, style } 差异化样式。 */
+    searchWords?: string | string[] | HighlightWord | HighlightWord[];
+    /** 是否大小写敏感匹配（默认 false）。 */
     caseSensitive?: boolean;
-    highlightAll?: boolean;
+    /** 是否对关键词做正则转义（默认 true）；关闭后 searchWords 视为正则源。 */
     autoEscape?: boolean;
+    /** 高亮片段包裹标签名（默认 mark）。 */
     component?: string;
+    /** 追加到每个高亮片段的类名。 */
     highlightClassName?: string;
+    /** 追加到每个高亮片段的内联样式（字符串）。 */
     highlightStyle?: string;
-    className?: string;
-    style?: string;
-    unstyled?: boolean;
-    /** 自定义命中片段渲染（覆盖默认 <mark>）。 */
-    highlight?: Snippet<[{
-        chunk: string;
-        index: number;
-    }]>;
-    /** 自定义非命中片段渲染（默认裸文本）。 */
-    chunk?: Snippet<[{
-        chunk: string;
-        index: number;
-    }]>;
-    /** 命中片段 id 前缀，用于 aria 关联；省略则自动生成。 */
-    idPrefix?: string;
-    /** 追加到每个命中片段的 aria-describedby（指向外部说明元素）。 */
-    describedById?: string;
-    /** 命中片段的 aria-label（默认不加，避免逐字播报噪音）。 */
-    highlightAriaLabel?: string;
 }
 declare const Highlight: import("svelte").Component<Props, {}, "">;
 type Highlight = ReturnType<typeof Highlight>;

package/dist/highlight/Highlight.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Highlight.svelte.d.ts","sourceRoot":"","sources":["../../src/highlight/Highlight.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAIpC,UAAU,KAAK;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IACxD,yBAAyB;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IACpD,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAiDH,QAAA,MAAM,SAAS,2CAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}
+{"version":3,"file":"Highlight.svelte.d.ts","sourceRoot":"","sources":["../../src/highlight/Highlight.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGxE,UAAU,KAAK;IACb,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,aAAa,GAAG,aAAa,EAAE,CAAC;IAClE,2BAA2B;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kDAAkD;IAClD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2BAA2B;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AA4CH,QAAA,MAAM,SAAS,2CAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/highlight/meta.d.ts

@@ -1,11 +1,12 @@
 /**
  * Machine-readable component metadata for AI/docs consumption.
  * Highlight — see specs/components/show/Highlight.spec.md
+ * 镜像 Semi Highlight：纯展示文本高亮，命中片段默认 <mark class="cd-highlight-tag"> 包裹。
  */
 export declare const meta: {
     readonly name: "Highlight";
     readonly category: "show";
-    readonly description: "纯展示文本高亮：在 sourceString 中标记 searchWords，默认用 <mark> 包裹。纯文本输出（HTML 会被转义而非解析），支持大小写敏感、仅首个/全部匹配、正则转义开关与自定义包裹元素/样式。";
+    readonly description: "纯展示文本高亮：在 sourceString 中标记 searchWords，命中片段默认用 <mark> 包裹。纯文本输出（HTML 会被转义而非解析），支持大小写敏感、正则转义开关、自定义包裹元素/类名/样式，以及对象数组差异化样式（不同关键词单独 className/style）。";
     readonly exports: readonly ["Highlight"];
     readonly props: readonly [{
         readonly name: "sourceString";
@@ -14,19 +15,14 @@ export declare const meta: {
         readonly desc: "待处理原始文本（纯文本，HTML 被转义）";
     }, {
         readonly name: "searchWords";
-        readonly type: "string|string[]";
+        readonly type: "string | string[] | HighlightWord | HighlightWord[]";
         readonly default: "[]";
-        readonly desc: "需高亮关键词，空串忽略";
+        readonly desc: "需高亮关键词；字符串/字符串数组，或对象数组 { text, className, style } 差异化样式（Semi v2.71+）；空文本忽略";
     }, {
         readonly name: "caseSensitive";
         readonly type: "boolean";
         readonly default: "false";
         readonly desc: "是否大小写敏感";
-    }, {
-        readonly name: "highlightAll";
-        readonly type: "boolean";
-        readonly default: "true";
-        readonly desc: "true 高亮全部匹配，false 仅首个";
     }, {
         readonly name: "autoEscape";
         readonly type: "boolean";
@@ -41,65 +37,30 @@ export declare const meta: {
         readonly name: "highlightClassName";
         readonly type: "string";
         readonly default: "''";
-        readonly desc: "追加到高亮片段的类名";
+        readonly desc: "追加到每个高亮片段的类名";
     }, {
         readonly name: "highlightStyle";
         readonly type: "string";
         readonly default: "''";
-        readonly desc: "追加到高亮片段的内联样式";
-    }, {
-        readonly name: "className";
-        readonly type: "string";
-        readonly default: "''";
-        readonly desc: "根 span 类名";
-    }, {
-        readonly name: "style";
-        readonly type: "string";
-        readonly default: "''";
-        readonly desc: "根 span 内联样式";
-    }, {
-        readonly name: "unstyled";
-        readonly type: "boolean";
-        readonly default: "false";
-        readonly desc: "移除默认高亮视觉，仅保留语义与类名";
-    }, {
-        readonly name: "idPrefix";
-        readonly type: "string";
-        readonly default: "auto";
-        readonly desc: "命中片段 id 前缀（生成 `${prefix}-${index}`），用于 aria 关联；省略则自动生成";
-    }, {
-        readonly name: "describedById";
-        readonly type: "string";
-        readonly default: "''";
-        readonly desc: "追加到每个命中片段的 aria-describedby，指向外部说明元素";
-    }, {
-        readonly name: "highlightAriaLabel";
-        readonly type: "string";
-        readonly default: "undefined";
-        readonly desc: "命中片段的 aria-label；默认不加以避免逐字播报噪音";
+        readonly desc: "追加到每个高亮片段的内联样式";
     }];
     readonly events: readonly [];
-    readonly slots: readonly [{
-        readonly name: "highlight";
-        readonly type: "Snippet<[{ chunk: string; index: number }]>";
-        readonly desc: "自定义命中片段渲染，覆盖默认 <mark>；不传则保持默认高亮行为";
-    }, {
-        readonly name: "chunk";
-        readonly type: "Snippet<[{ chunk: string; index: number }]>";
-        readonly desc: "自定义非命中片段渲染；不传则输出裸文本";
-    }];
+    readonly slots: readonly [];
     readonly a11y: {
         readonly role: "none";
         readonly focusable: false;
-        readonly notes: readonly ["高亮片段用原生 <mark> 元素承载浏览器/AT 内建“标记”语义", "不可聚焦、无 tabindex，避免搜索结果列表产生大量 Tab 停留点", "默认不对每个高亮加 aria-label，避免逐字播报噪音；命中计数由调用方外层 live region 负责", "每个命中片段带稳定 id（idPrefix-index），可被外部 aria-describedby/控件引用以定位", "可选 describedById/highlightAriaLabel 供需要显式关联的无障碍场景按需开启", "语义+背景双通道区分，不仅靠颜色（WCAG 1.4.1）"];
+        readonly notes: readonly ["高亮片段用原生 <mark> 元素承载浏览器/AT 内建“标记”语义", "不可聚焦、无 tabindex，避免搜索结果列表产生大量 Tab 停留点", "默认不对每个高亮加 aria-label，避免逐字播报噪音；命中计数由调用方外层 live region 负责", "语义+背景双通道区分，不仅靠颜色（WCAG 1.4.1）"];
     };
-    readonly tokens: readonly ["--cd-highlight-bg", "--cd-highlight-color", "--cd-highlight-weight", "--cd-border-radius-small"];
+    readonly tokens: readonly ["--cd-highlight-color", "--cd-highlight-bg", "--cd-highlight-font-weight"];
     readonly examples: readonly [{
         readonly title: "基础";
         readonly code: "<Highlight sourceString=\"hello world\" searchWords=\"world\" />";
     }, {
         readonly title: "多词";
         readonly code: "<Highlight sourceString=\"foo bar baz\" searchWords={[\"foo\", \"baz\"]} />";
+    }, {
+        readonly title: "差异化样式";
+        readonly code: "<Highlight sourceString=\"Semi 设计系统\" searchWords={[{ text: \"Semi\", style: { backgroundColor: \"teal\" } }, { text: \"设计系统\", style: { backgroundColor: \"violet\" } }]} />";
     }];
 };
 //# sourceMappingURL=meta.d.ts.map

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

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

package/dist/highlight/meta.js

@@ -1,17 +1,22 @@
 /**
  * Machine-readable component metadata for AI/docs consumption.
  * Highlight — see specs/components/show/Highlight.spec.md
+ * 镜像 Semi Highlight：纯展示文本高亮，命中片段默认 <mark class="cd-highlight-tag"> 包裹。
  */
 export const meta = {
     name: 'Highlight',
     category: 'show',
-    description: '纯展示文本高亮：在 sourceString 中标记 searchWords，默认用 <mark> 包裹。纯文本输出（HTML 会被转义而非解析），支持大小写敏感、仅首个/全部匹配、正则转义开关与自定义包裹元素/样式。',
+    description: '纯展示文本高亮：在 sourceString 中标记 searchWords，命中片段默认用 <mark> 包裹。纯文本输出（HTML 会被转义而非解析），支持大小写敏感、正则转义开关、自定义包裹元素/类名/样式，以及对象数组差异化样式（不同关键词单独 className/style）。',
     exports: ['Highlight'],
     props: [
         { name: 'sourceString', type: 'string', default: "''", desc: '待处理原始文本（纯文本，HTML 被转义）' },
-        { name: 'searchWords', type: 'string|string[]', default: '[]', desc: '需高亮关键词，空串忽略' },
+        {
+            name: 'searchWords',
+            type: 'string | string[] | HighlightWord | HighlightWord[]',
+            default: '[]',
+            desc: '需高亮关键词；字符串/字符串数组，或对象数组 { text, className, style } 差异化样式（Semi v2.71+）；空文本忽略',
+        },
         { name: 'caseSensitive', type: 'boolean', default: 'false', desc: '是否大小写敏感' },
-        { name: 'highlightAll', type: 'boolean', default: 'true', desc: 'true 高亮全部匹配，false 仅首个' },
         {
             name: 'autoEscape',
             type: 'boolean',
@@ -19,43 +24,11 @@ export const meta = {
             desc: '是否对关键词正则转义；关闭后 searchWords 视为正则源',
         },
         { name: 'component', type: 'string', default: "'mark'", desc: '高亮片段包裹标签名' },
-        { name: 'highlightClassName', type: 'string', default: "''", desc: '追加到高亮片段的类名' },
-        { name: 'highlightStyle', type: 'string', default: "''", desc: '追加到高亮片段的内联样式' },
-        { name: 'className', type: 'string', default: "''", desc: '根 span 类名' },
-        { name: 'style', type: 'string', default: "''", desc: '根 span 内联样式' },
-        { name: 'unstyled', type: 'boolean', default: 'false', desc: '移除默认高亮视觉，仅保留语义与类名' },
-        {
-            name: 'idPrefix',
-            type: 'string',
-            default: 'auto',
-            desc: '命中片段 id 前缀（生成 `${prefix}-${index}`），用于 aria 关联；省略则自动生成',
-        },
-        {
-            name: 'describedById',
-            type: 'string',
-            default: "''",
-            desc: '追加到每个命中片段的 aria-describedby，指向外部说明元素',
-        },
-        {
-            name: 'highlightAriaLabel',
-            type: 'string',
-            default: 'undefined',
-            desc: '命中片段的 aria-label；默认不加以避免逐字播报噪音',
-        },
+        { name: 'highlightClassName', type: 'string', default: "''", desc: '追加到每个高亮片段的类名' },
+        { name: 'highlightStyle', type: 'string', default: "''", desc: '追加到每个高亮片段的内联样式' },
     ],
     events: [],
-    slots: [
-        {
-            name: 'highlight',
-            type: 'Snippet<[{ chunk: string; index: number }]>',
-            desc: '自定义命中片段渲染，覆盖默认 <mark>；不传则保持默认高亮行为',
-        },
-        {
-            name: 'chunk',
-            type: 'Snippet<[{ chunk: string; index: number }]>',
-            desc: '自定义非命中片段渲染；不传则输出裸文本',
-        },
-    ],
+    slots: [],
     a11y: {
         role: 'none',
         focusable: false,
@@ -63,22 +36,19 @@ export const meta = {
             '高亮片段用原生 <mark> 元素承载浏览器/AT 内建“标记”语义',
             '不可聚焦、无 tabindex，避免搜索结果列表产生大量 Tab 停留点',
             '默认不对每个高亮加 aria-label，避免逐字播报噪音；命中计数由调用方外层 live region 负责',
-            '每个命中片段带稳定 id（idPrefix-index），可被外部 aria-describedby/控件引用以定位',
-            '可选 describedById/highlightAriaLabel 供需要显式关联的无障碍场景按需开启',
             '语义+背景双通道区分，不仅靠颜色（WCAG 1.4.1）',
         ],
     },
-    tokens: [
-        '--cd-highlight-bg',
-        '--cd-highlight-color',
-        '--cd-highlight-weight',
-        '--cd-border-radius-small',
-    ],
+    tokens: ['--cd-highlight-color', '--cd-highlight-bg', '--cd-highlight-font-weight'],
     examples: [
         { title: '基础', code: '<Highlight sourceString="hello world" searchWords="world" />' },
         {
             title: '多词',
             code: '<Highlight sourceString="foo bar baz" searchWords={["foo", "baz"]} />',
         },
+        {
+            title: '差异化样式',
+            code: '<Highlight sourceString="Semi 设计系统" searchWords={[{ text: "Semi", style: { backgroundColor: "teal" } }, { text: "设计系统", style: { backgroundColor: "violet" } }]} />',
+        },
     ],
 };

package/dist/hotkeys/HotKeys.svelte

@@ -0,0 +1,152 @@
+<!--
+  HotKeys — 严格对齐 Semi Design hotKeys。声明一组键盘快捷键组合，绑定 keydown 监听
+  （默认全局 document.body，可局部），命中触发 onHotKey，并渲染可见键位提示。
+  匹配引擎 / 校验 / 平台侦测全部委托 @chenzy-design/core（匹配用 event.code 物理键位，
+  规避输入法/大小写，保留 Semi 优秀设计）。DOM 对齐 Semi：div.cd-hotKeys > span > span.-content
+  + span.-split "+"（用 span 非 kbd，无 aria-keyshortcuts，无 rtl 特殊处理）。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import {
+    isValidHotKeys,
+    attachHotKeys,
+    modifierSymbol,
+    isApplePlatform,
+    type HotKey,
+  } from '@chenzy-design/core';
+  import { useLocale } from '../locale-provider/index.js';
+
+  interface Props {
+    /** **必填**。快捷键组合数组，恰含 1 个普通键 + 0~多修饰键。用原生 KeyboardEvent.key 或 HotKeys.Keys.*。非法抛错。 */
+    hotKeys: HotKey[];
+    /** 命中组合时触发，透传原生 KeyboardEvent。 */
+    onHotKey?: (e: KeyboardEvent) => void;
+    /** 自定义显示的键名内容（仅影响提示 UI，不改监听）。逐项对应，未提供项回退默认渲染。 */
+    content?: (string | Snippet)[];
+    /** 完全自定义提示渲染。传 null 则不渲染任何提示 UI，仅保留监听。 */
+    render?: Snippet | null;
+    /** 命中时是否 preventDefault（拦截浏览器默认行为，如 Ctrl+S）。 */
+    preventDefault?: boolean;
+    /** 跨平台把 Cmd(Meta) 与 Ctrl 视为同一修饰键。**死 prop**：严格对齐 Semi，声明但不生效（Meta/Ctrl 仍严格区分）。 */
+    mergeMetaCtrl?: boolean;
+    /** 监听挂载节点。默认全局 document.body；返回具体元素实现局部监听。 */
+    getListenerTarget?: () => HTMLElement | null;
+    /** 禁用监听（不绑定，不触发）。 */
+    disabled?: boolean;
+    /** 根节点类名。 */
+    class?: string;
+    /** 根节点内联样式。 */
+    style?: string;
+  }
+
+  let {
+    hotKeys,
+    onHotKey,
+    content,
+    render,
+    preventDefault = false,
+    mergeMetaCtrl = false,
+    getListenerTarget,
+    disabled = false,
+    class: className,
+    style,
+  }: Props = $props();
+
+  const loc = useLocale();
+  const apple = isApplePlatform();
+
+  // 校验组合合法性（非法抛错，与 core isValidHotKeys 契约一致）；派生量，hotKeys 变即重校验。
+  const validated = $derived.by(() => {
+    isValidHotKeys(hotKeys);
+    return hotKeys;
+  });
+
+  // —— 键位显示文本：修饰键走平台符号 / i18n 文字，普通键原样（大写字母、符号） ——
+  function displayKey(key: HotKey): string {
+    const sym = modifierSymbol(key, apple);
+    if (sym !== undefined) {
+      if (apple) return sym; // Apple 平台用 ⌘⌥⌃⇧ 符号
+      // 非 Apple：用 i18n 文字（Ctrl/Win/Alt/Shift），随 locale 可覆盖。
+      switch (key) {
+        case 'Control':
+          return loc().t('HotKeys.ctrl');
+        case 'Meta':
+          return loc().t('HotKeys.meta');
+        case 'Alt':
+          return loc().t('HotKeys.alt');
+        case 'Shift':
+          return loc().t('HotKeys.shift');
+      }
+    }
+    // 普通键：单字符字母显示大写；其余原样（ArrowUp / Enter / F1 等）。
+    return key.length === 1 ? key.toUpperCase() : key;
+  }
+
+  const cls = $derived(['cd-hotKeys', className].filter(Boolean).join(' '));
+
+  // —— 监听生命周期：$effect 内绑定，返回 cleanup 解绑（防泄漏，红线 #2 安全：无同步自写 state）——
+  $effect(() => {
+    // 读取依赖：disabled / hotKeys / preventDefault / mergeMetaCtrl / target 变化即重绑。
+    if (disabled) return;
+    const target = getListenerTarget?.() ?? (typeof document !== 'undefined' ? document.body : null);
+    if (!target) return;
+    const detach = attachHotKeys(target, validated, onHotKey, {
+      preventDefault,
+      mergeMetaCtrl,
+      disabled,
+    });
+    return detach;
+  });
+</script>
+
+{#if render !== null}
+  {#if render}
+    {@render render()}
+  {:else}
+    <!-- DOM 对齐 Semi：div.cd-hotKeys > span(每键) > span.-content；分隔 span.-split "+"。 -->
+    <div class={cls} {style}>
+      {#each validated as key, i (i)}
+        {@const item = content?.[i]}
+        <span>
+          {#if i > 0}<span class="cd-hotKeys-split">+</span>{/if}
+          {#if item !== undefined && typeof item !== 'string'}
+            <span class="cd-hotKeys-content">{@render item()}</span>
+          {:else}
+            <span class="cd-hotKeys-content">{item ?? displayKey(key)}</span>
+          {/if}
+        </span>
+      {/each}
+    </div>
+  {/if}
+{/if}
+
+<style>
+  /* 严格对齐 Semi hotKeys.scss：inline-flex 居中、user-select:none、nowrap。 */
+  .cd-hotKeys {
+    box-sizing: border-box;
+    position: relative;
+    display: inline-flex;
+    justify-content: center;
+    align-items: center;
+    user-select: none;
+    white-space: nowrap;
+    vertical-align: bottom;
+  }
+  /* 键位块（对齐 Semi -content：12px/radius 2px/height 20px/padding 2px 8px/fill-0 底 text-2 字） */
+  .cd-hotKeys :global(.cd-hotKeys-content) {
+    font-size: var(--cd-font-size-small);
+    border-radius: var(--cd-radius-hotkeys);
+    height: var(--cd-height-hotkeys);
+    display: inline-flex;
+    align-items: center;
+    padding: var(--cd-spacing-hotkeys-paddingY) var(--cd-spacing-hotkeys-paddingX);
+    background: var(--cd-color-hotkeys-bg);
+    color: var(--cd-color-hotkeys-text);
+  }
+  /* 分隔符（对齐 Semi -split：12px/margin 0 3px/text-0） */
+  .cd-hotKeys :global(.cd-hotKeys-split) {
+    font-size: var(--cd-font-size-small);
+    margin: 0 3px;
+    color: var(--cd-color-hotkeys-split);
+  }
+</style>

package/dist/hotkeys/HotKeys.svelte.d.ts

@@ -0,0 +1,28 @@
+import type { Snippet } from 'svelte';
+import { type HotKey } from '@chenzy-design/core';
+interface Props {
+    /** **必填**。快捷键组合数组，恰含 1 个普通键 + 0~多修饰键。用原生 KeyboardEvent.key 或 HotKeys.Keys.*。非法抛错。 */
+    hotKeys: HotKey[];
+    /** 命中组合时触发，透传原生 KeyboardEvent。 */
+    onHotKey?: (e: KeyboardEvent) => void;
+    /** 自定义显示的键名内容（仅影响提示 UI，不改监听）。逐项对应，未提供项回退默认渲染。 */
+    content?: (string | Snippet)[];
+    /** 完全自定义提示渲染。传 null 则不渲染任何提示 UI，仅保留监听。 */
+    render?: Snippet | null;
+    /** 命中时是否 preventDefault（拦截浏览器默认行为，如 Ctrl+S）。 */
+    preventDefault?: boolean;
+    /** 跨平台把 Cmd(Meta) 与 Ctrl 视为同一修饰键。**死 prop**：严格对齐 Semi，声明但不生效（Meta/Ctrl 仍严格区分）。 */
+    mergeMetaCtrl?: boolean;
+    /** 监听挂载节点。默认全局 document.body；返回具体元素实现局部监听。 */
+    getListenerTarget?: () => HTMLElement | null;
+    /** 禁用监听（不绑定，不触发）。 */
+    disabled?: boolean;
+    /** 根节点类名。 */
+    class?: string;
+    /** 根节点内联样式。 */
+    style?: string;
+}
+declare const HotKeys: import("svelte").Component<Props, {}, "">;
+type HotKeys = ReturnType<typeof HotKeys>;
+export default HotKeys;
+//# sourceMappingURL=HotKeys.svelte.d.ts.map

package/dist/hotkeys/HotKeys.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HotKeys.svelte.d.ts","sourceRoot":"","sources":["../../src/hotkeys/HotKeys.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAKH,KAAK,MAAM,EACZ,MAAM,qBAAqB,CAAC;AAI7B,UAAU,KAAK;IACb,qFAAqF;IACrF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,CAAC;IACtC,iDAAiD;IACjD,OAAO,CAAC,EAAE,CAAC,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;IAC/B,0CAA0C;IAC1C,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,gDAAgD;IAChD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IAC7C,qBAAqB;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA6FH,QAAA,MAAM,OAAO,2CAAwC,CAAC;AACtD,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAC1C,eAAe,OAAO,CAAC"}

package/dist/hotkeys/index.d.ts

@@ -0,0 +1,12 @@
+import { HotKeysKeys, type HotKey } from '@chenzy-design/core';
+import HotKeysComponent from './HotKeys.svelte';
+/**
+ * HotKeys 组件 + 静态 `HotKeys.Keys` 键名常量枚举（对齐 spec §4 静态导出）。
+ * `Object.assign` 复合导出模式（同 Tabs.Pane / Form.Field）。
+ */
+export declare const HotKeys: typeof HotKeysComponent & {
+    Keys: typeof HotKeysKeys;
+};
+export { meta as hotKeysMeta } from './meta.js';
+export type { HotKey };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hotkeys/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,gBAAgB,MAAM,kBAAkB,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,OAAO,EAAE,OAAO,gBAAgB,GAAG;IAAE,IAAI,EAAE,OAAO,WAAW,CAAA;CAGzE,CAAC;AACF,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EAAE,MAAM,EAAE,CAAC"}

package/dist/hotkeys/index.js

@@ -0,0 +1,8 @@
+import { HotKeysKeys } from '@chenzy-design/core';
+import HotKeysComponent from './HotKeys.svelte';
+/**
+ * HotKeys 组件 + 静态 `HotKeys.Keys` 键名常量枚举（对齐 spec §4 静态导出）。
+ * `Object.assign` 复合导出模式（同 Tabs.Pane / Form.Field）。
+ */
+export const HotKeys = Object.assign(HotKeysComponent, { Keys: HotKeysKeys });
+export { meta as hotKeysMeta } from './meta.js';