@chenzy-design/svelte 0.1.0

package/src/rating/Rating.svelte

@@ -0,0 +1,407 @@
+<!--
+  Rating — see specs/components/input/Rating.spec.md
+  Star rating with half-star, hover preview, keyboard. APG slider pattern.
+  Controlled / uncontrolled; variation only via onChange. hoverValue is local-only.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { useId } from '@chenzy-design/core';
+  import { useLocale } from '../locale-provider/index.js';
+
+  type Size = 'small' | 'default' | 'large' | number;
+  type Status = 'default' | 'warning' | 'error';
+  type ItemState = 'empty' | 'half' | 'full';
+  type CharCtx = { index: number; state: ItemState; value: number };
+  // 自定义字符：字符串（统一字符）或 Snippet（按 {index,state,value} 渲染不同节点，
+  // 取代 spec 中的 (index,state)=>node 函数形式——Svelte 5 用带参 Snippet 表达）。
+  type Character = string | Snippet<[CharCtx]>;
+
+  interface Props {
+    value?: number;
+    defaultValue?: number;
+    count?: number;
+    allowHalf?: boolean;
+    allowClear?: boolean;
+    /** 自定义字符/图标：字符串 或 带 {index,state,value} 的 Snippet。不传则默认星形。 */
+    character?: Character;
+    size?: Size;
+    disabled?: boolean;
+    readonly?: boolean;
+    status?: Status;
+    /** 逐项提示文案（native title），长度应等于 count。 */
+    tooltips?: string[];
+    /** 挂载时聚焦。 */
+    autoFocus?: boolean;
+    name?: string;
+    /** 根元素 id，关联 aria；不传自动生成。 */
+    id?: string;
+    ariaLabel?: string;
+    onChange?: (v: number) => void;
+    onHoverChange?: (v: number) => void;
+  }
+
+  let {
+    value = $bindable(),
+    defaultValue = 0,
+    count = 5,
+    allowHalf = false,
+    allowClear = true,
+    character,
+    size = 'default',
+    disabled = false,
+    readonly = false,
+    status = 'default',
+    tooltips,
+    autoFocus = false,
+    name,
+    id,
+    ariaLabel,
+    onChange,
+    onHoverChange,
+  }: Props = $props();
+
+  const loc = useLocale();
+  const autoId = useId('cd-rating');
+  const rootId = $derived(id ?? autoId);
+
+  const isSnippet = (c: unknown): c is Snippet<[CharCtx]> => typeof c === 'function';
+
+  const isControlled = $derived(value !== undefined);
+  let inner = $state(getInitialValue());
+  const current = $derived(isControlled ? (value ?? 0) : inner);
+
+  function getInitialValue(): number {
+    return defaultValue;
+  }
+
+  // hoverValue is purely local preview state; null means "no hover".
+  let hoverValue = $state<number | null>(null);
+  const displayValue = $derived(hoverValue ?? current);
+
+  const interactive = $derived(!disabled && !readonly);
+  const minStep = $derived(allowHalf ? 0.5 : 1);
+
+  const sizePx = $derived(typeof size === 'number' ? `${size}px` : undefined);
+  const sizeClass = $derived(typeof size === 'number' ? 'cd-rating--custom' : `cd-rating--${size}`);
+
+  // Per-star fill: 0 = empty, 0.5 = half, 1 = full.
+  function fillFor(index: number): number {
+    const starValue = index + 1;
+    if (displayValue >= starValue) return 1;
+    if (displayValue >= starValue - 0.5) return 0.5;
+    return 0;
+  }
+
+  // 三态语义（供 character Snippet 上下文）：纯派生函数（红线 #2）。
+  function stateFor(index: number): ItemState {
+    const fill = fillFor(index);
+    return fill === 1 ? 'full' : fill === 0.5 ? 'half' : 'empty';
+  }
+
+  function commit(next: number) {
+    // Controlled: never write the prop; propagate via onChange only.
+    if (!isControlled) inner = next;
+    onChange?.(next);
+    announce(next);
+  }
+
+  // 值变更播报 live region（命令式写入，render 期只读 $state）。
+  let announceText = $state('');
+  function announce(next: number) {
+    announceText = '';
+    queueMicrotask(() => {
+      announceText = next === 0 ? loc().t('Rating.cleared') : textFor(next);
+    });
+  }
+
+  function valueAt(index: number, isHalf: boolean): number {
+    return allowHalf && isHalf ? index + 0.5 : index + 1;
+  }
+
+  function isLeftHalf(e: { currentTarget: HTMLElement; clientX: number }): boolean {
+    if (!allowHalf) return false;
+    const rect = e.currentTarget.getBoundingClientRect();
+    const rtl = getComputedStyle(e.currentTarget).direction === 'rtl';
+    const offset = e.clientX - rect.left;
+    const leftHalf = offset < rect.width / 2;
+    return rtl ? !leftHalf : leftHalf;
+  }
+
+  function handleMove(index: number, e: MouseEvent & { currentTarget: HTMLElement }) {
+    if (!interactive) return;
+    const next = valueAt(index, isLeftHalf(e));
+    if (next !== hoverValue) {
+      hoverValue = next;
+      onHoverChange?.(next);
+    }
+  }
+
+  function handleLeave() {
+    if (hoverValue !== null) {
+      hoverValue = null;
+      // 移出复位至当前 value（spec：hoverChange 移出时为当前 value）。
+      onHoverChange?.(current);
+    }
+  }
+
+  function handleClick(index: number, e: MouseEvent & { currentTarget: HTMLElement }) {
+    if (!interactive) return;
+    const next = valueAt(index, isLeftHalf(e));
+    if (allowClear && next === current) {
+      commit(0);
+    } else {
+      commit(next);
+    }
+    hoverValue = null;
+  }
+
+  function handleKeydown(e: KeyboardEvent) {
+    if (!interactive) return;
+    let next = current;
+    switch (e.key) {
+      case 'ArrowRight':
+      case 'ArrowUp':
+        next = Math.min(count, current + minStep);
+        break;
+      case 'ArrowLeft':
+      case 'ArrowDown':
+        next = Math.max(0, current - minStep);
+        break;
+      case 'Home':
+        next = 0;
+        break;
+      case 'End':
+        next = count;
+        break;
+      case 'Delete':
+      case 'Backspace':
+        if (allowClear) next = 0;
+        break;
+      default: {
+        // 数字键 1–9：直接定位到对应整数分值（钳到 [1, count]）。
+        if (e.key >= '1' && e.key <= '9') {
+          const n = Number(e.key);
+          if (n <= count) next = n;
+          else return;
+        } else {
+          return;
+        }
+      }
+    }
+    e.preventDefault();
+    if (next !== current) commit(next);
+  }
+
+  const cls = $derived(
+    [
+      'cd-rating',
+      sizeClass,
+      `cd-rating--${status}`,
+      disabled && 'cd-rating--disabled',
+      readonly && 'cd-rating--readonly',
+    ]
+      .filter(Boolean)
+      .join(' '),
+  );
+
+  // aria-valuetext / 播报文案：i18n + Intl 数字格式（红线 #2 纯派生）。
+  function textFor(v: number): string {
+    if (v === 0) return loc().t('Rating.unrated');
+    return loc().t('Rating.valueText', {
+      value: loc().formatNumber(v),
+      count: loc().formatNumber(count),
+    });
+  }
+  const valueText = $derived(textFor(current));
+  const resolvedAriaLabel = $derived(ariaLabel ?? loc().t('Rating.ariaLabel'));
+
+  // 单项 title：tooltips[index]（长度可不足，缺省为 undefined）。
+  function titleFor(index: number): string | undefined {
+    return tooltips?.[index];
+  }
+
+  let rootEl: HTMLDivElement | undefined;
+  // autoFocus：命令式聚焦一次（红线 #3，SSR 安全）。
+  $effect(() => {
+    if (autoFocus && rootEl && interactive) rootEl.focus();
+  });
+</script>
+
+<div
+  bind:this={rootEl}
+  id={rootId}
+  class={cls}
+  role="slider"
+  aria-label={resolvedAriaLabel}
+  aria-valuenow={current}
+  aria-valuemin={0}
+  aria-valuemax={count}
+  aria-valuetext={valueText}
+  aria-disabled={disabled || undefined}
+  aria-readonly={readonly || undefined}
+  aria-invalid={status === 'error' || undefined}
+  tabindex={interactive ? 0 : -1}
+  style={sizePx ? `--cd-rating-size-active: ${sizePx}` : undefined}
+  onkeydown={handleKeydown}
+  onmouseleave={handleLeave}
+>
+  {#if name}<input type="hidden" {name} value={current} />{/if}
+
+  {#each Array(count) as _, i (i)}
+    {@const fill = fillFor(i)}
+    <span
+      class="cd-rating__star"
+      class:cd-rating__star--full={fill === 1}
+      class:cd-rating__star--half={fill === 0.5}
+      class:cd-rating__star--char={character !== undefined}
+      role="presentation"
+      title={titleFor(i)}
+      onmousemove={(e) => handleMove(i, e)}
+      onclick={(e) => handleClick(i, e)}
+    >
+      {#if typeof character === 'string'}
+        <!-- 自定义字符（字符串）：双层裁剪，与星形同结构。 -->
+        <span class="cd-rating__icon cd-rating__icon--bg cd-rating__text">{character}</span>
+        <span class="cd-rating__fg" style={`inline-size: ${fill * 100}%`}>
+          <span class="cd-rating__icon cd-rating__icon--fg cd-rating__text">{character}</span>
+        </span>
+      {:else if isSnippet(character)}
+        <!-- 自定义 Snippet：调用方按 {index,state,value} 自渲染（含半态）。 -->
+        {@render character({ index: i, state: stateFor(i), value: displayValue })}
+      {:else}
+        <svg class="cd-rating__icon cd-rating__icon--bg" viewBox="0 0 24 24" aria-hidden="true">
+          <path
+            fill="currentColor"
+            d="M12 2.5 14.9 8.4 21.4 9.3 16.7 13.9 17.8 20.4 12 17.3 6.2 20.4 7.3 13.9 2.6 9.3 9.1 8.4 12 2.5Z"
+          />
+        </svg>
+        <span class="cd-rating__fg" style={`inline-size: ${fill * 100}%`}>
+          <svg class="cd-rating__icon cd-rating__icon--fg" viewBox="0 0 24 24" aria-hidden="true">
+            <path
+              fill="currentColor"
+              d="M12 2.5 14.9 8.4 21.4 9.3 16.7 13.9 17.8 20.4 12 17.3 6.2 20.4 7.3 13.9 2.6 9.3 9.1 8.4 12 2.5Z"
+            />
+          </svg>
+        </span>
+      {/if}
+    </span>
+  {/each}
+</div>
+
+<!-- 值变更播报 live region：视觉隐藏，仅供辅助技术读取（render 期只读 $state）。 -->
+<div class="cd-rating__sr-live" role="status" aria-live="polite" aria-atomic="true">
+  {announceText}
+</div>
+
+<style>
+  .cd-rating {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cd-rating-gap);
+    color: var(--cd-rating-color-inactive);
+    cursor: pointer;
+    outline: none;
+  }
+  .cd-rating:focus-visible {
+    box-shadow: var(--cd-focus-ring);
+    border-radius: var(--cd-radius-1);
+  }
+  .cd-rating--disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+  .cd-rating--readonly {
+    cursor: default;
+  }
+  .cd-rating__star {
+    position: relative;
+    display: inline-flex;
+    inline-size: var(--cd-rating-size-default);
+    block-size: var(--cd-rating-size-default);
+    color: var(--cd-rating-color-inactive);
+  }
+  .cd-rating--small .cd-rating__star {
+    inline-size: var(--cd-rating-size-small);
+    block-size: var(--cd-rating-size-small);
+  }
+  .cd-rating--large .cd-rating__star {
+    inline-size: var(--cd-rating-size-large);
+    block-size: var(--cd-rating-size-large);
+  }
+  .cd-rating--custom .cd-rating__star {
+    inline-size: var(--cd-rating-size-active);
+    block-size: var(--cd-rating-size-active);
+  }
+  .cd-rating__icon {
+    inline-size: 100%;
+    block-size: 100%;
+    display: block;
+  }
+  .cd-rating__fg {
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: 0;
+    block-size: 100%;
+    inline-size: 0;
+    overflow: hidden;
+    color: var(--cd-rating-color-active);
+    transition: color var(--cd-motion-duration-fast) var(--cd-motion-ease-standard);
+  }
+  .cd-rating__icon--fg {
+    inline-size: var(--cd-rating-size-default);
+    block-size: 100%;
+  }
+  .cd-rating--small .cd-rating__icon--fg {
+    inline-size: var(--cd-rating-size-small);
+  }
+  .cd-rating--large .cd-rating__icon--fg {
+    inline-size: var(--cd-rating-size-large);
+  }
+  .cd-rating--custom .cd-rating__icon--fg {
+    inline-size: var(--cd-rating-size-active);
+  }
+  .cd-rating--warning .cd-rating__fg {
+    color: var(--cd-color-warning);
+  }
+  .cd-rating--error .cd-rating__fg {
+    color: var(--cd-color-danger);
+  }
+  /* 自定义字符（字符串）：以文本承载，撑满星位，垂直水平居中。 */
+  .cd-rating__text {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 100%;
+    block-size: 100%;
+    font-size: var(--cd-rating-size-default);
+    line-height: 1;
+    white-space: nowrap;
+  }
+  .cd-rating--small .cd-rating__text {
+    font-size: var(--cd-rating-size-small);
+  }
+  .cd-rating--large .cd-rating__text {
+    font-size: var(--cd-rating-size-large);
+  }
+  .cd-rating--custom .cd-rating__text {
+    font-size: var(--cd-rating-size-active);
+  }
+  /* 视觉隐藏但对辅助技术可见（不可用 display:none / visibility:hidden）。 */
+  .cd-rating__sr-live {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .cd-rating__fg {
+      transition: none;
+    }
+  }
+</style>

package/src/rating/RatingKbdFixture.svelte

@@ -0,0 +1,15 @@
+<!--
+  仅供 Rating.kbd.test.ts（browser project）使用的键盘 e2e 夹具。
+  Rating 根元素是 role=slider（tabindex=0），焦点落在根上：
+  方向键调评分、数字键 1–9 定位、Home/End 到 0/count，aria-valuenow 真实变化。
+  before 按钮验证 Tab 真实聚焦到 slider 根。
+-->
+<script lang="ts">
+  import { LocaleProvider } from '../locale-provider/index.js';
+  import Rating from './Rating.svelte';
+</script>
+
+<LocaleProvider locale="en_US">
+  <button type="button" data-testid="before">before</button>
+  <Rating defaultValue={3} count={5} ariaLabel="Score" />
+</LocaleProvider>

package/src/rating/index.ts

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

package/src/rating/meta.ts

@@ -0,0 +1,40 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export const meta = {
+  name: 'Rating',
+  category: 'input',
+  description: '评分组件，支持半星、hover 预览、点击清零与键盘操作，遵循 APG Slider 模式。',
+  props: [
+    { name: 'value', type: 'number', default: 'undefined', desc: '受控值；提供则为受控' },
+    { name: 'defaultValue', type: 'number', default: '0', desc: '非受控初始值' },
+    { name: 'count', type: 'number', default: '5', desc: '图标总数' },
+    { name: 'allowHalf', type: 'boolean', default: 'false', desc: '允许半星（步进 0.5）' },
+    { name: 'allowClear', type: 'boolean', default: 'true', desc: '点击当前值清零' },
+    { name: 'character', type: 'string | Snippet<[{index,state,value}]>', default: 'undefined', desc: '自定义字符/图标；不传则默认星形' },
+    { name: 'size', type: "'small'|'default'|'large'|number", default: 'default' },
+    { name: 'disabled', type: 'boolean', default: 'false' },
+    { name: 'readonly', type: 'boolean', default: 'false' },
+    { name: 'status', type: "'default'|'warning'|'error'", default: 'default' },
+    { name: 'tooltips', type: 'string[]', default: 'undefined', desc: '逐项提示文案（native title），长度应等于 count' },
+    { name: 'autoFocus', type: 'boolean', default: 'false', desc: '挂载时聚焦' },
+    { name: 'name', type: 'string', default: 'undefined' },
+    { name: 'id', type: 'string', default: '自动生成', desc: '根元素 id，关联 aria' },
+    { name: 'ariaLabel', type: 'string', default: 'i18n 默认', desc: '无可视标签时的辅助名' },
+    { name: 'onChange', type: '(v: number) => void', default: 'undefined' },
+    { name: 'onHoverChange', type: '(v: number) => void', default: 'undefined', desc: '悬停预览值变化；移出时为当前 value' },
+  ],
+  i18nKeys: ['Rating.ariaLabel', 'Rating.valueText', 'Rating.cleared', 'Rating.unrated'],
+  a11y: {
+    role: 'slider',
+    keyboard: ['ArrowRight/Up', 'ArrowLeft/Down', 'Home', 'End', 'Delete', 'Backspace'],
+    notes: [
+      'role=slider + aria-valuenow/valuemin/valuemax/valuetext',
+      'hover 预览为纯本地状态，不影响受控值',
+      'allowHalf 时按指针落在星左/右半决定 .5',
+      'disabled→aria-disabled，readonly→aria-readonly，error→aria-invalid',
+    ],
+  },
+  tokens: ['--cd-rating-*', '--cd-color-warning', '--cd-color-danger', '--cd-focus-ring', '--cd-motion-*'],
+} as const;

package/src/resize-observer/ResizeObserver.svelte

@@ -0,0 +1,169 @@
+<!--
+  ResizeObserver — see specs/components/other/ResizeObserver.spec.md
+  Renderless 工具组件：渲染一个无样式包裹元素作为观测容器，
+  通过 @chenzy-design/core 的 createResizeObserver 监听其尺寸，
+  slot 暴露归一化的 width/height/entry。
+
+  盒模型：content-box / border-box / device-pixel-content-box，
+  单目标 + 多目标（multiple）+ throttle/debounce 节流去抖，包裹元素标签可经 tag 自定义。
+  fallbackToWindow 降级（原生不可用或显式开启时监听 window.resize 近似重测），
+  onResizeStart/onResizeEnd 边界事件（连续变化首帧 / 静默结束，core 纯状态机驱动）。
+
+  ⚠️ 死循环红线：
+    - 红线 #1：无受控回写，尺寸只向 slot / 回调单向分发。
+    - 红线 #3：observer 在 $effect 内命令式创建 + observe，
+      cleanup 时 disconnect；不使用响应式 attachment 读 DOM 几何。
+    - 包裹元素必须有真实盒子（默认 display:block），
+      绝不用 display:contents —— 该元素不生成盒子，ResizeObserver 无法观测其尺寸。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import {
+    createResizeObserver,
+    type CDResizeEntry,
+    type ResizeBox,
+  } from '@chenzy-design/core';
+
+  interface Props {
+    /** 观测盒模型，默认 'content-box'（另支持 border-box / device-pixel-content-box） */
+    box?: ResizeBox;
+    /** 暂停尺寸分发，默认 false（observer 仍在监听，仅不向外通知） */
+    disabled?: boolean;
+    /**
+     * 节流间隔(ms)，leading+trailing，默认 0 即原生即时回调。
+     * 与 debounce 互斥（同时 >0 时 debounce 优先）。
+     */
+    throttle?: number;
+    /** 防抖等待(ms)，trailing-only，默认 0 关闭。与 throttle 互斥（优先）。 */
+    debounce?: number;
+    /**
+     * 多目标：true 时观测包裹元素内所有直接子元素（而非包裹元素本身），
+     * onResize 逐个抛出，用 entry.target 区分。默认 false（观测包裹元素）。
+     * 注意：多目标模式下 slot 的 width/height 反映最后一次变化的目标。
+     */
+    multiple?: boolean;
+    /** 挂载后立即测量一次，默认 true（ResizeObserver 原生在 observe 时触发首次回调，天然满足） */
+    observeOnMount?: boolean;
+    /** 包裹元素标签，默认 'div'。须为可生成盒子的元素（勿用 display:contents 类标签）。 */
+    tag?: string;
+    /**
+     * 原生 ResizeObserver 不可用（SSR/老环境）或显式开启时，降级监听 window.resize，
+     * 用 getBoundingClientRect 近似重测（精度较低）。默认 false：不支持环境静默降级。
+     */
+    fallbackToWindow?: boolean;
+    /** 尺寸变化回调（归一化 entry） */
+    onResize?: (entry: CDResizeEntry) => void;
+    /** 首次测量回调 */
+    onFirstMeasure?: (entry: CDResizeEntry) => void;
+    /** 一段连续尺寸变化的首帧触发（"调整中"态） */
+    onResizeStart?: (entry: CDResizeEntry) => void;
+    /** 连续变化结束后（静默一段时间）触发，payload 为最后一帧（"调整完成"） */
+    onResizeEnd?: (entry: CDResizeEntry) => void;
+    /** slot 作用域参数：{ width, height, entry } */
+    children?: Snippet<
+      [{ width: number; height: number; entry: CDResizeEntry | null }]
+    >;
+    class?: string;
+  }
+
+  let {
+    box = 'content-box',
+    disabled = false,
+    throttle = 0,
+    debounce = 0,
+    multiple = false,
+    observeOnMount = true,
+    tag = 'div',
+    fallbackToWindow = false,
+    onResize,
+    onFirstMeasure,
+    onResizeStart,
+    onResizeEnd,
+    children,
+    class: className,
+  }: Props = $props();
+
+  // 包裹元素普通引用（bind:this），即被观测对象。
+  let el = $state<HTMLElement | null>(null);
+
+  // 本地响应式状态：仅由 observer 回调（非 render 期）写入，render 期只读以驱动 slot。
+  let width = $state(0);
+  let height = $state(0);
+  let entry = $state<CDResizeEntry | null>(null);
+
+  // 普通（非响应式）变量：标记是否已触发首次测量。
+  let firstFired = false;
+
+  // observer 命令式创建 + observe + cleanup disconnect（红线 #3）。
+  // 依赖 el + box + throttle + debounce + multiple：变更时重建 observer。
+  // disabled 不进依赖（避免暂停/恢复时丢失监听重建）——在回调内读最新 prop 值。
+  $effect(() => {
+    if (!el) return;
+
+    const node = el;
+    const ro = createResizeObserver({
+      box,
+      throttle,
+      debounce,
+      fallbackToWindow,
+      // 仅在使用方监听时挂 start/end，避免无谓的静默计时器（向后兼容）。
+      onResizeStart: onResizeStart
+        ? (e) => {
+            if (disabled) return;
+            onResizeStart?.(e);
+          }
+        : undefined,
+      onResizeEnd: onResizeEnd
+        ? (e) => {
+            if (disabled) return;
+            onResizeEnd?.(e);
+          }
+        : undefined,
+      onResize: (e) => {
+        // disabled 在回调内读 prop 最新值（Svelte 5 解构 prop 在闭包内访问是响应式最新值）。
+        if (disabled) return;
+        width = e.width;
+        height = e.height;
+        entry = e;
+        if (!firstFired) {
+          firstFired = true;
+          onFirstMeasure?.(e);
+        }
+        onResize?.(e);
+      },
+    });
+
+    // SSR / 无原生 RO 且未开启 window 降级：静默不监听。
+    // 降级模式 supported 仍为 false，但内部已挂 window.resize，故需放行。
+    if (!ro.supported && !fallbackToWindow) return;
+
+    if (multiple) {
+      // 多目标：观测包裹元素的所有直接子元素（同一 observer 实例复用）。
+      const targets = Array.from(node.children);
+      for (const child of targets) ro.observe(child);
+    } else {
+      ro.observe(node);
+    }
+
+    return () => ro.disconnect();
+  });
+
+  const cls = $derived(
+    ['cd-resize-observer', className].filter(Boolean).join(' '),
+  );
+</script>
+
+<svelte:element this={tag} class={cls} bind:this={el}>
+  {#if children}{@render children({ width, height, entry })}{/if}
+</svelte:element>
+
+<style>
+  /*
+    必须有真实盒子供 ResizeObserver 观测 —— 不可用 display:contents。
+    无任何视觉样式（无 padding/border/background），仅作透明观测容器；
+    使用方可通过 class/style 控制其尺寸。
+  */
+  .cd-resize-observer {
+    display: block;
+  }
+</style>