@chenzy-design/svelte 0.1.0

package/src/image/ImagePreview.svelte

@@ -0,0 +1,309 @@
+<!--
+  ImagePreview — 预览浮层（portal 到 body）。
+  被 Image（单图）与 ImagePreviewGroup（多图）共享，统一缩放/旋转/键盘/导航逻辑。
+  红线 #3：portal、keydown 监听、focus 命令式 + cleanup；当前索引由父级以 $state 传入。
+  红线 #2：变换/导航可用性派生纯函数。
+-->
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import { useFocusTrap, useLiveAnnouncer } from '@chenzy-design/core';
+  import { useLocale } from '../locale-provider/index.js';
+
+  interface PreviewImage {
+    src: string;
+    alt: string;
+  }
+
+  interface Props {
+    images: PreviewImage[];
+    /** 当前展示的图片索引（受控，由父级 $state 维护）。 */
+    current: number;
+    onClose: () => void;
+    onChange: (index: number) => void;
+  }
+
+  let { images, current, onClose, onChange }: Props = $props();
+
+  const loc = useLocale();
+  // 单例 live region（polite）：灯箱翻页时播报「第 m 张，共 n 张」（红线 #3：命令式，在切换 effect 内）。
+  const announcer = useLiveAnnouncer();
+
+  const count = $derived(images.length);
+  const safeIndex = $derived(Math.min(Math.max(current, 0), Math.max(count - 1, 0)));
+  const active = $derived(images[safeIndex]);
+  const showNav = $derived(count > 1);
+  const canPrev = $derived(safeIndex > 0);
+  const canNext = $derived(safeIndex < count - 1);
+
+  // 预览变换状态：缩放倍数 + 旋转角度。切换图片时重置（见下方 $effect）。
+  let scale = $state(1);
+  let rotate = $state(0);
+  const SCALE_STEP = 0.25;
+  const SCALE_MIN = 0.25;
+  const SCALE_MAX = 4;
+  const transform = $derived(`scale(${scale}) rotate(${rotate}deg)`);
+
+  function resetTransform() {
+    scale = 1;
+    rotate = 0;
+  }
+  function zoomIn() {
+    scale = Math.min(SCALE_MAX, scale + SCALE_STEP);
+  }
+  function zoomOut() {
+    scale = Math.max(SCALE_MIN, scale - SCALE_STEP);
+  }
+  function rotateLeft() {
+    rotate -= 90;
+  }
+  function rotateRight() {
+    rotate += 90;
+  }
+
+  function goPrev() {
+    if (canPrev) onChange(safeIndex - 1);
+  }
+  function goNext() {
+    if (canNext) onChange(safeIndex + 1);
+  }
+
+  // 切换到不同图片时把变换复位（每张图从 1x/0° 开始）。
+  let lastIndex = $state(untrack(() => safeIndex));
+  $effect(() => {
+    if (safeIndex !== lastIndex) {
+      lastIndex = safeIndex;
+      resetTransform();
+      // 翻页（上一张/下一张）后 polite 播报当前序号；多图时才有意义。
+      if (count > 1) {
+        announcer.announce(
+          loc().t('Image.previewCount', { index: safeIndex + 1, total: count }),
+        );
+      }
+    }
+  });
+
+  // 浮层根节点：portal 到 body + focus trap（焦点锁定灯箱内 + 关闭归还触发元素），
+  // 命令式 + cleanup。复用 core useFocusTrap（与 Modal/Drawer 同一原语，不重造）。
+  // activate() 会记下打开前的触发元素并聚焦灯箱内首个可聚焦项（关闭按钮）；
+  // deactivate() 拦截 Tab 循环、归还焦点给触发元素。
+  let overlay = $state<HTMLDivElement | null>(null);
+  $effect(() => {
+    const node = overlay;
+    if (!node) return;
+    const body = document.body;
+    body.appendChild(node);
+    const trap = useFocusTrap(node);
+    trap.activate();
+    return () => {
+      trap.deactivate();
+      if (node.parentNode === body) body.removeChild(node);
+    };
+  });
+
+  // 全局键盘：Esc 关闭、左右切换。命令式绑定 + cleanup 解绑。
+  $effect(() => {
+    function onKeydown(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        onClose();
+      } else if (e.key === 'ArrowLeft') {
+        e.preventDefault();
+        goPrev();
+      } else if (e.key === 'ArrowRight') {
+        e.preventDefault();
+        goNext();
+      }
+    }
+    window.addEventListener('keydown', onKeydown);
+    return () => window.removeEventListener('keydown', onKeydown);
+  });
+
+  // 仅点击遮罩自身（非内部图片/按钮）才关闭。
+  function onOverlayClick(e: MouseEvent) {
+    if (e.target === e.currentTarget) onClose();
+  }
+
+  // 遮罩获得焦点时的键盘兜底（a11y：与 click 配对）；全局键盘在上方 $effect 内统一处理。
+  function onOverlayKeydown(e: KeyboardEvent) {
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      onClose();
+    }
+  }
+</script>
+
+<div
+  bind:this={overlay}
+  class="cd-image__preview"
+  role="dialog"
+  aria-modal="true"
+  aria-label={active?.alt || loc().t('Image.previewAlt')}
+  tabindex="-1"
+  onclick={onOverlayClick}
+  onkeydown={onOverlayKeydown}
+>
+  <button
+    type="button"
+    class="cd-image__preview-close"
+    aria-label={loc().t('Image.closePreview')}
+    onclick={onClose}
+  >
+    ×
+  </button>
+
+  {#if showNav}
+    <button
+      type="button"
+      class="cd-image__preview-nav cd-image__preview-nav--prev"
+      aria-label={loc().t('Image.prev')}
+      disabled={!canPrev}
+      onclick={goPrev}
+    >
+      ‹
+    </button>
+    <button
+      type="button"
+      class="cd-image__preview-nav cd-image__preview-nav--next"
+      aria-label={loc().t('Image.next')}
+      disabled={!canNext}
+      onclick={goNext}
+    >
+      ›
+    </button>
+  {/if}
+
+  <img
+    class="cd-image__preview-img"
+    src={active?.src}
+    alt={active?.alt}
+    style="transform:{transform}"
+  />
+
+  <div class="cd-image__preview-toolbar">
+    {#if showNav}
+      <span class="cd-image__preview-counter" aria-hidden="true">{safeIndex + 1} / {count}</span>
+    {/if}
+    <button type="button" class="cd-image__preview-tool" aria-label={loc().t('Image.zoomOut')} onclick={zoomOut}>−</button>
+    <button type="button" class="cd-image__preview-tool" aria-label={loc().t('Image.zoomIn')} onclick={zoomIn}>+</button>
+    <button type="button" class="cd-image__preview-tool" aria-label={loc().t('Image.rotateLeft')} onclick={rotateLeft}>⟲</button>
+    <button type="button" class="cd-image__preview-tool" aria-label={loc().t('Image.rotateRight')} onclick={rotateRight}>⟳</button>
+    <button type="button" class="cd-image__preview-tool" aria-label={loc().t('Image.reset')} onclick={resetTransform}>⤢</button>
+  </div>
+</div>
+
+<style>
+  .cd-image__preview {
+    position: fixed;
+    inset: 0;
+    z-index: var(--cd-image-preview-z);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: var(--cd-image-preview-overlay);
+    line-height: normal;
+  }
+  .cd-image__preview-img {
+    max-inline-size: 90vw;
+    max-block-size: 90vh;
+    object-fit: contain;
+    transition: transform var(--cd-motion-duration-mid, 0.2s) var(--cd-motion-ease-standard);
+  }
+  .cd-image__preview-close {
+    position: absolute;
+    inset-block-start: 16px;
+    inset-inline-end: 16px;
+    inline-size: 36px;
+    block-size: 36px;
+    padding: 0;
+    border: 0;
+    border-radius: var(--cd-radius-full);
+    background: var(--cd-image-mask-bg);
+    color: var(--cd-image-mask-color);
+    font-size: 24px;
+    cursor: pointer;
+  }
+  .cd-image__preview-close:focus-visible {
+    outline: var(--cd-focus-ring);
+  }
+
+  .cd-image__preview-nav {
+    position: absolute;
+    inset-block-start: 50%;
+    transform: translateY(-50%);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 44px;
+    block-size: 44px;
+    padding: 0;
+    border: 0;
+    border-radius: var(--cd-radius-full);
+    background: var(--cd-image-mask-bg);
+    color: var(--cd-image-mask-color);
+    font-size: 28px;
+    line-height: 1;
+    cursor: pointer;
+  }
+  .cd-image__preview-nav--prev {
+    inset-inline-start: 16px;
+  }
+  .cd-image__preview-nav--next {
+    inset-inline-end: 16px;
+  }
+  .cd-image__preview-nav:hover:not(:disabled) {
+    background: rgb(255 255 255 / 0.15);
+  }
+  .cd-image__preview-nav:disabled {
+    opacity: 0.35;
+    cursor: not-allowed;
+  }
+  .cd-image__preview-nav:focus-visible {
+    outline: var(--cd-focus-ring);
+  }
+
+  .cd-image__preview-toolbar {
+    position: absolute;
+    inset-block-end: 24px;
+    inset-inline-start: 50%;
+    transform: translateX(-50%);
+    display: flex;
+    align-items: center;
+    gap: var(--cd-spacing-2);
+    padding: var(--cd-spacing-2);
+    border-radius: var(--cd-radius-full);
+    background: var(--cd-image-mask-bg);
+  }
+  .cd-image__preview-counter {
+    padding-inline: var(--cd-spacing-2);
+    color: var(--cd-image-mask-color);
+    font-size: 13px;
+    line-height: 1;
+  }
+  .cd-image__preview-tool {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 32px;
+    block-size: 32px;
+    padding: 0;
+    border: 0;
+    border-radius: var(--cd-radius-full);
+    background: transparent;
+    color: var(--cd-image-mask-color);
+    font-size: 18px;
+    line-height: 1;
+    cursor: pointer;
+  }
+  .cd-image__preview-tool:hover {
+    background: rgb(255 255 255 / 0.15);
+  }
+  .cd-image__preview-tool:focus-visible {
+    outline: var(--cd-focus-ring);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .cd-image__preview-img {
+      transition: none;
+    }
+  }
+</style>

package/src/image/ImagePreviewGroup.svelte

@@ -0,0 +1,93 @@
+<!--
+  ImagePreviewGroup — 图片预览组（复合组件 Image.PreviewGroup）。
+  包裹多个 <Image preview>，共享一个预览浮层：点任一图进入组预览，可左右切换。
+  红线 #3：当前索引 / 打开态以 $state 维护；浮层 portal、键盘监听在 ImagePreview 内命令式 + cleanup。
+  红线 #1：current/visible 受控时不回写，仅经 onChange/onVisibleChange 回调。
+  红线 #2：派生项列表为纯函数。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { setImageGroupContext, type PreviewItem } from './context.js';
+  import ImagePreview from './ImagePreview.svelte';
+
+  interface Props {
+    /** 受控：当前预览图索引。传入则受控，不回写，仅经 onChange 回调。 */
+    current?: number;
+    /** 受控：预览是否可见。 */
+    visible?: boolean;
+    onChange?: (index: number) => void;
+    onVisibleChange?: (visible: boolean) => void;
+    children?: Snippet;
+  }
+
+  let { current, visible, onChange, onVisibleChange, children }: Props = $props();
+
+  // 已注册子图（注册顺序即索引）。槽位卸载置 null，避免索引漂移。
+  let items = $state<(PreviewItem | null)[]>([]);
+
+  // 非受控本地态。
+  let innerCurrent = $state(0);
+  let innerVisible = $state(false);
+
+  const isCurrentControlled = $derived(current !== undefined);
+  const isVisibleControlled = $derived(visible !== undefined);
+
+  const activeCurrent = $derived(isCurrentControlled ? (current as number) : innerCurrent);
+  const activeVisible = $derived(isVisibleControlled ? (visible as boolean) : innerVisible);
+
+  // 派生纯函数：紧凑后的预览图列表（过滤已卸载槽位）+ 槽位索引→列表索引映射。
+  const previewList = $derived(
+    items
+      .map((it, slot) => (it ? { src: it.getSrc(), alt: it.getAlt(), slot } : null))
+      .filter((v): v is { src: string; alt: string; slot: number } => v !== null),
+  );
+  const images = $derived(previewList.map(({ src, alt }) => ({ src, alt })));
+
+  function setCurrent(index: number) {
+    if (!isCurrentControlled) innerCurrent = index;
+    onChange?.(index);
+  }
+  function setVisible(next: boolean) {
+    if (!isVisibleControlled) innerVisible = next;
+    onVisibleChange?.(next);
+  }
+
+  setImageGroupContext({
+    register(item) {
+      const slot = items.length;
+      items = [...items, item];
+      return slot;
+    },
+    unregister(slot) {
+      if (slot < items.length) {
+        const next = items.slice();
+        next[slot] = null;
+        items = next;
+      }
+    },
+    open(slot) {
+      // 槽位索引 → 紧凑列表索引。
+      const listIndex = previewList.findIndex((p) => p.slot === slot);
+      setCurrent(listIndex < 0 ? 0 : listIndex);
+      setVisible(true);
+    },
+  });
+
+  function handleClose() {
+    setVisible(false);
+  }
+  function handleChange(index: number) {
+    setCurrent(index);
+  }
+</script>
+
+{@render children?.()}
+
+{#if activeVisible && images.length > 0}
+  <ImagePreview
+    {images}
+    current={activeCurrent}
+    onClose={handleClose}
+    onChange={handleChange}
+  />
+{/if}

package/src/image/ImagePreviewKbdFixture.svelte

@@ -0,0 +1,32 @@
+<!--
+  仅供 ImagePreview.kbd.test.ts（browser project）使用的灯箱 e2e 夹具。
+  直接渲染 ImagePreview（多图）：真实图片加载在 headless 下不可靠，故跳过 Image 触发链，
+  直接控制灯箱挂载（show $state）。trigger 按钮先获焦作为焦点归还锚点：
+  测试先聚焦 trigger 再开灯箱，验证 focus trap（焦点入灯箱）、←→ 翻页、Esc 关闭归还 trigger。
+  current 由父级 $state 维护（受控），onChange 更新它（左右键翻页）。
+-->
+<script lang="ts">
+  import { LocaleProvider } from '../locale-provider/index.js';
+  import ImagePreview from './ImagePreview.svelte';
+
+  const images = [
+    { src: 'data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==', alt: 'image one' },
+    { src: 'data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==', alt: 'image two' },
+    { src: 'data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==', alt: 'image three' },
+  ];
+
+  let show = $state(false);
+  let current = $state(0);
+</script>
+
+<LocaleProvider locale="en_US">
+  <button type="button" data-testid="trigger" onclick={() => (show = true)}>open lightbox</button>
+  {#if show}
+    <ImagePreview
+      {images}
+      {current}
+      onClose={() => (show = false)}
+      onChange={(i) => (current = i)}
+    />
+  {/if}
+</LocaleProvider>

package/src/image/context.ts

@@ -0,0 +1,26 @@
+import { getContext, setContext } from 'svelte';
+
+/** 组内单张图片的预览数据。src 用 getter 以保持对子 Image prop 变化的响应性。 */
+export interface PreviewItem {
+  getSrc: () => string;
+  getAlt: () => string;
+}
+
+export interface ImageGroupContext {
+  /** 子 Image 注册自身进预览组，返回该图在组内的稳定索引（注册顺序）。 */
+  register: (item: PreviewItem) => number;
+  /** 子 Image 卸载时注销。 */
+  unregister: (index: number) => void;
+  /** 子 Image 被点击时请求打开组预览，定位到自身索引。 */
+  open: (index: number) => void;
+}
+
+const KEY = Symbol('cd-image-group');
+
+export function setImageGroupContext(ctx: ImageGroupContext): void {
+  setContext(KEY, ctx);
+}
+
+export function getImageGroupContext(): ImageGroupContext | undefined {
+  return getContext<ImageGroupContext | undefined>(KEY);
+}

package/src/image/index.ts

@@ -0,0 +1,15 @@
+import Image_ from './Image.svelte';
+import ImagePreviewGroup from './ImagePreviewGroup.svelte';
+
+export const Image: typeof Image_ & {
+  PreviewGroup: typeof ImagePreviewGroup;
+} = Object.assign(Image_, { PreviewGroup: ImagePreviewGroup });
+
+export { ImagePreviewGroup };
+export { meta as imageMeta } from './meta.js';
+export {
+  getImageGroupContext,
+  setImageGroupContext,
+  type ImageGroupContext,
+  type PreviewItem,
+} from './context.js';

package/src/image/meta.ts

@@ -0,0 +1,131 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * Image — see specs/components/show/Image.spec.md
+ */
+export const meta = {
+  name: 'Image',
+  category: 'show',
+  description:
+    '图片：支持懒加载（原生 loading=lazy 或 IntersectionObserver）、object-fit/position、占位（骨架或 LQIP 模糊占位图 + 主图淡入）、加载失败降级（降级图/默认破图/自定义 slot）与点击全屏预览（portal 遮罩 + 缩放/旋转 + Esc 关闭）。配合 Image.PreviewGroup 包裹多张图可在预览态左右切换（← → 按钮 + 键盘箭头）。',
+  exports: ['Image', 'Image.PreviewGroup'],
+  props: [
+    { name: 'src', type: 'string', default: '—', desc: '图片地址（必填）' },
+    { name: 'alt', type: 'string', default: "''", desc: '替代文本' },
+    { name: 'width', type: 'number|string', default: 'undefined', desc: '容器宽，number 视为 px' },
+    { name: 'height', type: 'number|string', default: 'undefined', desc: '容器高，number 视为 px' },
+    {
+      name: 'fit',
+      type: "'fill'|'contain'|'cover'|'none'|'scale-down'",
+      default: "'fill'",
+      desc: 'object-fit',
+    },
+    { name: 'position', type: 'string', default: "'center'", desc: 'object-position' },
+    {
+      name: 'crossorigin',
+      type: "'anonymous'|'use-credentials'",
+      default: 'undefined',
+      desc: '原生 crossorigin 属性透传（跨域取图 CORS 模式）',
+    },
+    {
+      name: 'srcset',
+      type: 'string',
+      default: 'undefined',
+      desc: '原生 srcset 响应式图源集透传（observer 懒加载下与 src 同步延迟设置）',
+    },
+    {
+      name: 'sizes',
+      type: 'string',
+      default: 'undefined',
+      desc: '原生 sizes 属性透传，配合 srcset 声明视口对应的图片显示尺寸',
+    },
+    { name: 'lazy', type: 'boolean', default: 'true', desc: '是否懒加载' },
+    {
+      name: 'lazyMode',
+      type: "'native'|'observer'",
+      default: "'native'",
+      desc: '懒加载方式：原生属性或 IntersectionObserver',
+    },
+    { name: 'rootMargin', type: 'string', default: "'200px'", desc: 'observer 模式预加载边距' },
+    {
+      name: 'placeholder',
+      type: 'string|boolean',
+      default: 'true',
+      desc: 'true=骨架占位；string=LQIP 低质占位图 src（CSS blur 模糊，主图加载完成后淡入清晰）；false=无占位',
+    },
+    {
+      name: 'fallback',
+      type: 'string|boolean',
+      default: 'true',
+      desc: 'true=默认破图占位；string=降级图 src；false=用 errorSlot',
+    },
+    { name: 'preview', type: 'boolean', default: 'false', desc: '点击图片打开全屏预览' },
+    { name: 'class', type: 'string', default: "''", desc: '根类名透传' },
+    { name: 'errorSlot', type: 'Snippet', default: 'undefined', desc: 'fallback=false 时的错误内容' },
+    { name: 'placeholderSlot', type: 'Snippet', default: 'undefined', desc: '自定义占位内容' },
+  ],
+  events: [],
+  subComponents: [
+    {
+      name: 'Image.PreviewGroup',
+      desc: '预览组：包裹多个 <Image preview>，共享一个预览浮层，点任一图进入组预览可左右切换。',
+      props: [
+        { name: 'current', type: 'number', default: 'undefined', desc: '受控：当前预览图索引（不回写，仅 onChange 回调）' },
+        { name: 'visible', type: 'boolean', default: 'undefined', desc: '受控：预览是否可见（不回写，仅 onVisibleChange 回调）' },
+        { name: 'onChange', type: '(index: number) => void', default: 'undefined', desc: '当前预览图索引变化回调' },
+        { name: 'onVisibleChange', type: '(visible: boolean) => void', default: 'undefined', desc: '预览开关变化回调' },
+        { name: 'children', type: 'Snippet', default: 'undefined', desc: '组内的 <Image> 列表' },
+      ],
+    },
+  ],
+  slots: [
+    { name: 'errorSlot', desc: '加载失败自定义内容（fallback=false 时）' },
+    { name: 'placeholderSlot', desc: '加载中自定义占位内容' },
+  ],
+  a11y: {
+    role: 'img',
+    keyboard: ['Enter', 'Space', 'Escape', 'ArrowLeft', 'ArrowRight'],
+    focusable: true,
+    notes: [
+      'img 必传 alt 语义；默认破图占位用 role=img + aria-label',
+      'preview 触发器为原生 button，可键盘聚焦与触发',
+      '预览遮罩 role=dialog、aria-modal=true，portal 到 body；useFocusTrap 锁定焦点（Tab 循环不外泄）、进入聚焦关闭按钮、关闭后焦点归还触发元素；Esc 关闭，关闭按钮有 aria-label',
+      '组预览左右切换：← → 按钮（aria-label 经 locale）+ 键盘左右箭头，到边界按钮 disabled',
+      '装饰性占位/遮罩文案、页码计数器 aria-hidden=true',
+    ],
+  },
+  tokens: [
+    '--cd-image-bg',
+    '--cd-image-radius',
+    '--cd-image-placeholder-color',
+    '--cd-image-mask-bg',
+    '--cd-image-mask-color',
+    '--cd-image-preview-overlay',
+    '--cd-image-preview-z',
+    '--cd-focus-ring',
+    '--cd-radius-full',
+    '--cd-motion-duration-fast',
+  ],
+  examples: [
+    { title: '基础', code: '<Image src="/a.jpg" alt="示例" width={200} />' },
+    {
+      title: '懒加载 observer + 预览',
+      code: '<Image src="/big.jpg" alt="大图" lazy lazyMode="observer" preview />',
+    },
+    {
+      title: 'LQIP 模糊占位',
+      code: '<Image src="/hi-res.jpg" placeholder="/lqip-tiny.jpg" alt="高清图" />',
+    },
+    {
+      title: '响应式图源 srcset/sizes',
+      code: '<Image\n  src="/img-800.jpg"\n  srcset="/img-400.jpg 400w, /img-800.jpg 800w, /img-1600.jpg 1600w"\n  sizes="(max-width: 600px) 400px, 800px"\n  alt="响应式图"\n/>',
+    },
+    {
+      title: '跨域 crossorigin',
+      code: '<Image src="https://cdn.example.com/a.jpg" crossorigin="anonymous" alt="跨域图" />',
+    },
+    {
+      title: '预览组多图切换',
+      code: '<Image.PreviewGroup>\n  <Image src="/a.jpg" alt="A" preview />\n  <Image src="/b.jpg" alt="B" preview />\n  <Image src="/c.jpg" alt="C" preview />\n</Image.PreviewGroup>',
+    },
+  ],
+} as const;