@xihan-ui/styles 3.1.0 → 4.0.0

package/dist/css/editable.css

@@ -0,0 +1,269 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* Editable 独立皮肤同时传递引入字段视觉盒与字段内动作；full bundle 递归去重。 */
+@import '../family/field-chrome.css';
+@import '../family/action-control.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-editable {
+    --xh-editable-skin: 1;
+  }
+
+  /* 与 NumberField 同构：标题独占一行，control 是下面唯一的视觉盒；
+     预览/输入占据盒内左侧，编辑或确认/取消动作收在同一盒的逻辑末端。
+     组件层只把既有公开槽映射到家族合同；形态三档由家族按 control 上的 data-variant 生成，皮肤不再声明。 */
+  .xh-scope-editable[data-part='root'] {
+    --xh-icon-size: var(--xh-editable-icon-size, var(--xh-glyph-size-md));
+
+    /* 尺寸档只换这三个私有槽，预览区、输入框与动作钮都从 root 继承它们，
+       换档不必给每个部件各写一条选择器。 */
+    --xh-_editable-h: var(--xh-control-h-md);
+    --xh-_editable-px: var(--xh-control-px-md);
+    --xh-_editable-font-size: var(--xh-control-font-md);
+    --xh-_editable-control-gap: 0;
+
+    display: inline-flex;
+    flex-direction: column;
+    gap: var(--xh-editable-gap, var(--xh-space-1));
+    /* 不传尺寸时一律这么宽，宽度不随内容走；父容器给不出这么宽时整件跟着收，地板同步让步，不越出父容器。
+       地板不高过缺省宽：使用者把缺省宽钉到底线以下时不必再放开底线 */
+    inline-size: var(--xh-editable-control-w, var(--xh-control-w));
+    min-inline-size: min(var(--xh-editable-control-w, var(--xh-control-w)), var(--xh-editable-control-min-w, var(--xh-control-min-w)), 100%);
+    max-inline-size: 100%;
+  }
+
+  /* —— 尺寸 —— */
+  /* 缺省档写在上面的基础规则里 */
+  .xh-scope-editable[data-part='root'][data-size='sm'] {
+    --xh-icon-size: var(--xh-editable-icon-size, var(--xh-glyph-size-sm));
+    --xh-_editable-h: var(--xh-control-h-sm);
+    --xh-_editable-px: var(--xh-control-px-sm);
+    --xh-_editable-font-size: var(--xh-control-font-sm);
+  }
+
+  .xh-scope-editable[data-part='root'][data-size='lg'] {
+    --xh-icon-size: var(--xh-editable-icon-size, var(--xh-glyph-size-lg));
+    --xh-_editable-h: var(--xh-control-h-lg);
+    --xh-_editable-px: var(--xh-control-px-lg);
+    --xh-_editable-font-size: var(--xh-control-font-lg);
+  }
+
+  /* 只要声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去 */
+  .xh-scope-editable[data-part='root'][hidden] {
+    display: none;
+  }
+
+  .xh-scope-editable[data-part='label'] {
+    /* 竖排时标签与控件之间的距离：根的 gap 之上补一段差值，--xh-editable-label-gap 给多少最终就是多少 */
+    margin-block-end: calc(var(--xh-editable-label-gap, var(--xh-space-2)) - var(--xh-editable-gap, var(--xh-space-1)));
+    color: var(--xh-editable-label-fg, var(--xh-fg-muted));
+    font-size: var(--xh-editable-label-font-size, var(--xh-text-label-size));
+    font-weight: var(--xh-editable-label-font-weight, var(--xh-text-label-weight));
+    /* 点标题会把人送进编辑态（预览态下 for 指着的输入框是收起的，点了没反应），
+       所以光标要说明它可点 */
+    cursor: pointer;
+  }
+
+  .xh-scope-editable[data-part='label'][data-disabled] {
+    color: var(--xh-editable-label-fg-disabled, var(--xh-fg-muted));
+  }
+
+  /* 预览区只是 control 里的内容段，不再自成一只带圆角的盒子。 */
+  .xh-scope-editable[data-part='preview'] {
+    display: inline-flex;
+    flex: 1 1 auto;
+    align-items: center;
+    inline-size: auto;
+    min-inline-size: 0;
+    min-block-size: var(--xh-editable-preview-min-h, var(--xh-_editable-h));
+    padding-inline: var(--xh-editable-preview-px, var(--xh-_editable-px));
+    padding-block: 0;
+    border: 0;
+    border-radius: 0;
+    background: transparent;
+    box-shadow: none;
+    color: var(--xh-editable-preview-fg, var(--xh-fg-default));
+    font-size: var(--xh-editable-preview-font-size, var(--xh-_editable-font-size));
+    line-height: var(--xh-leading-normal);
+    /* 值里的换行与连续空格照原样显示，过长的行断开而不撑破弹性行 */
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+  }
+
+  /* 编辑态由连接层给 hidden；上面那条 display 会盖掉 UA 规则，少了这条就收不起来 */
+  .xh-scope-editable[data-part='preview'][hidden] {
+    display: none;
+  }
+
+  /* 认交互的预览区才给文字光标与悬停底色：
+     activation-mode=none 或整块不可编辑时，它就只是一段文字，别装成能点 */
+  .xh-scope-editable[data-part='preview']:not(
+    [data-activation-mode='none'],
+    [data-disabled],
+    [data-readonly]
+  ) {
+    cursor: text;
+  }
+
+  /* 显示的是占位文字而不是真值，压淡以示区别 */
+  .xh-scope-editable[data-part='preview'][data-placeholder] {
+    color: var(--xh-editable-placeholder-fg, var(--xh-fg-subtle));
+  }
+
+  .xh-scope-editable[data-part='preview'][data-disabled] {
+    color: var(--xh-fg-disabled);
+  }
+
+  /* 盒内 input：无边框无底无圆角无落影由家族重置，hover、focus 与 invalid 全交给 control；
+     行内内衬留给它自己（control 不给内衬），占位与自动填充的颜色经桥接槽下发 */
+  .xh-scope-editable[data-part='input'] {
+    --xh-field-input-fg: var(--xh-editable-input-fg, var(--xh-fg-default));
+    --xh-field-input-font-size: var(--xh-editable-input-font-size, var(--xh-_editable-font-size));
+    --xh-field-placeholder-fg: var(--xh-editable-placeholder-fg, var(--xh-fg-subtle));
+    --xh-field-autofill-bg: var(--xh-editable-input-autofill-bg, var(--xh-bg-canvas));
+    --xh-field-autofill-fg: var(--xh-editable-input-autofill-fg, var(--xh-fg-default));
+
+    flex: 1 1 auto;
+    inline-size: auto;
+    min-inline-size: 0;
+    padding-inline: var(--xh-editable-input-px, var(--xh-_editable-px));
+  }
+
+  /* 预览态由连接层给 hidden；家族给了 display 以外的盒声明但没给 display，
+     UA 的 [hidden]{display:none} 仍然管用——这里补一条是防作者层另给 display */
+  .xh-scope-editable[data-part='input'][hidden] {
+    display: none;
+  }
+
+  /* 宽度跟着内容走时交给原生 size 说了算，别再用 100% 把它撑满 */
+  .xh-scope-editable[data-part='input'][data-auto-resize] {
+    flex: 0 1 auto;
+    inline-size: auto;
+  }
+
+  /* 唯一视觉盒：描边、底色、圆角、聚焦环、五态与悬停由 Field Chrome 家族画在 control 上；
+     预览/输入和右侧动作只是盒内分段。控件不给内衬：内衬走预览区、input 与钮各自的盒。
+     不写 overflow: hidden——家族的粗指针热区伪元素会被它裁掉，且钮已不贴控件边 */
+  .xh-scope-editable[data-part='control'] {
+    --xh-field-control-height: var(--xh-editable-control-h, var(--xh-_editable-h));
+    --xh-field-control-padding-inline: var(--xh-editable-control-px, 0);
+    --xh-field-control-gap: var(--xh-editable-control-gap, var(--xh-_editable-control-gap));
+    --xh-field-control-min-inline-size: var(--xh-editable-control-min-w, var(--xh-control-min-w));
+    --xh-field-control-radius: var(--xh-editable-control-radius, var(--xh-shape-control));
+    --xh-field-bg-rest: var(--xh-editable-control-bg, var(--xh-_field-variant-bg-rest));
+    --xh-field-bg-hover: var(--xh-editable-control-bg-hover, var(--xh-_field-variant-bg-hover));
+    --xh-field-bg-read-only: var(--xh-editable-control-bg-readonly, var(--xh-_field-variant-bg-read-only));
+    --xh-field-bg-disabled: var(--xh-editable-control-bg-disabled, var(--xh-_field-variant-bg-disabled));
+    --xh-field-fg-rest: var(--xh-editable-control-fg, var(--xh-fg-default));
+    --xh-field-border-rest: var(--xh-editable-control-border, var(--xh-_field-variant-border-rest));
+    --xh-field-border-hover: var(--xh-editable-control-border-hover, var(--xh-_field-variant-border-hover));
+    --xh-field-border-focus: var(--xh-editable-control-border-focus, var(--xh-_field-variant-border-focus));
+    --xh-field-border-invalid: var(--xh-editable-control-border-invalid, var(--xh-_field-variant-border-invalid));
+    --xh-field-border-disabled: var(--xh-editable-control-border-disabled, var(--xh-_field-variant-border-disabled));
+    --xh-field-shadow-rest: var(--xh-editable-control-shadow, none);
+    /* 家族 chrome 会重写 --xh-icon-size，使用者图标槽必须经桥接槽下发才能在盒内生效 */
+    --xh-field-glyph-size: var(--xh-editable-icon-size, var(--xh-_field-size-glyph-size));
+
+    position: relative;
+    inline-size: 100%;
+  }
+
+  .xh-scope-editable[data-part='control'][hidden] {
+    display: none;
+  }
+
+  /* 三颗动作是 control 内部的分段：inset 圆角、按承载面取的悬停 / 按下阶梯、粗指针热区、
+     :focus-visible 关环与禁用面全由 Action Control 的 field-inset ghost 档给，组件只映射既有覆盖槽。
+     视觉盒按字段内钮尺寸表随字段档（sm 取控件内动作档、md 取 control-h-sm、lg 取 control-h-md），
+     由 field-inset 档按 data-xh-action-size 给；常态只剩符号、取次要前景，悬停与按下才浮出底色 */
+  .xh-scope-editable[data-part='edit-trigger'],
+  .xh-scope-editable[data-part='submit-trigger'],
+  .xh-scope-editable[data-part='cancel-trigger'] {
+    --xh-action-visual-size: var(--xh-editable-trigger-size, var(--xh-_action-profile-visual-size));
+    --xh-action-min-inline-size: var(--xh-editable-trigger-size, var(--xh-_action-profile-visual-size));
+    --xh-action-radius: var(--xh-editable-trigger-radius, var(--xh-shape-inset));
+    /* 底色阶梯由 ghost 档给（透明 → 100 → 200），使用者槽只作覆盖入口 */
+    --xh-action-bg-rest: var(--xh-editable-trigger-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-editable-trigger-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-editable-trigger-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-bg-disabled: var(--xh-editable-trigger-bg-disabled, var(--xh-_action-variant-bg-disabled));
+    --xh-action-fg-rest: var(--xh-editable-trigger-fg, var(--xh-fg-muted));
+    --xh-action-fg-hover: var(--xh-editable-trigger-fg-hover, var(--xh-fg-default));
+    --xh-action-border-rest: transparent;
+    --xh-action-highlight-rest: transparent;
+    --xh-action-shadow-rest: none;
+    --xh-action-shadow-hover: none;
+    --xh-action-shadow-pressed: none;
+    --xh-action-font-size: var(--xh-editable-trigger-font-size, var(--xh-text-secondary-size));
+    /* 配方尚未把 profile 字形档灌进 --xh-icon-size，钮内字形先按 field-inset 档逐钮取值 */
+    --xh-icon-size: var(--xh-_action-profile-glyph-size);
+
+    border-width: 0;
+  }
+
+  /* 每个状态的第一颗动作把整组推到逻辑末端；取消钮紧跟确认钮。 */
+  .xh-scope-editable[data-part='edit-trigger'],
+  .xh-scope-editable[data-part='submit-trigger'] {
+    margin-inline-start: auto;
+  }
+
+  /* 确认与取消两颗挨着：紧凑 sm 档钮只有 20px，两钮中心距凑不够 24px 就落不进 SC 2.5.8 的间距例外，
+     两颗之间隔一格 --xh-space-1；其余档钮不低于 24px，这一格只把两块悬停面分开 */
+  .xh-scope-editable[data-part='cancel-trigger'] {
+    margin-inline-start: var(--xh-space-1);
+  }
+
+  /* 三颗动作默认是纯图标按钮；作者放了自己的图标后 :empty 不命中，不会叠两层。 */
+  .xh-scope-editable:is([data-part='edit-trigger'], [data-part='submit-trigger'], [data-part='cancel-trigger']):empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-md));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-md));
+    background-color: currentColor;
+    -webkit-mask: var(--xh-_editable-trigger-glyph) center / contain no-repeat;
+    mask: var(--xh-_editable-trigger-glyph) center / contain no-repeat;
+  }
+
+  .xh-scope-editable[data-part='edit-trigger'] {
+    --xh-_editable-trigger-glyph: var(--xh-glyph-mark-edit);
+  }
+
+  .xh-scope-editable[data-part='submit-trigger'] {
+    --xh-_editable-trigger-glyph: var(--xh-glyph-mark-check);
+  }
+
+  .xh-scope-editable[data-part='cancel-trigger'] {
+    --xh-_editable-trigger-glyph: var(--xh-glyph-mark-close);
+  }
+
+  /* 三颗按钮按形态轮流收起，连接层给的是 hidden 属性；
+     家族那条 display 已把 UA 规则盖掉，少了这里三条按钮就一直杵着 */
+  .xh-scope-editable[data-part='edit-trigger'][hidden],
+  .xh-scope-editable[data-part='submit-trigger'][hidden],
+  .xh-scope-editable[data-part='cancel-trigger'][hidden] {
+    display: none;
+  }
+
+  @media (forced-colors: active) {
+    /* 兜底字形是 mask 挖出来的一块底色，这一档里底色被系统换成 Canvas，字形跟着消失。
+       字形退出强制换色、直接写系统色（不能取 currentColor：退出强制换色的伪元素读到的是被系统换掉之前的作者色）：
+       按钮面上取 ButtonText，悬停与按下时家族把按钮涂成 Highlight、字形换 HighlightText；
+       禁用取 GrayText */
+    .xh-scope-editable:is([data-part='edit-trigger'], [data-part='submit-trigger'], [data-part='cancel-trigger']):empty::before {
+      forced-color-adjust: none;
+      background-color: ButtonText;
+    }
+
+    .xh-scope-editable:is([data-part='edit-trigger'], [data-part='submit-trigger'], [data-part='cancel-trigger']):not([data-disabled]):not([data-loading]):is(:hover, :active, [data-pressed]):empty::before {
+      background-color: HighlightText;
+    }
+
+    .xh-scope-editable:is([data-part='edit-trigger'], [data-part='submit-trigger'], [data-part='cancel-trigger'])[data-disabled]:empty::before {
+      background-color: GrayText;
+    }
+  }
+}

package/dist/css/empty-state.css

@@ -0,0 +1,181 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 empty state 样式。 */
+
+/* 共享关键帧由 family/motion.css 提供，本皮肤 @import 它，单独引入仍成立。 */
+@import '../family/motion.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-empty-state {
+    --xh-empty-state-skin: 1;
+  }
+
+  .xh-scope-empty-state[data-part='root'] {
+    /* 三个尺寸档只换这几个私有槽，图标与标题都从 root 继承它们，
+       换档不必给每个部件各写一条选择器 */
+    --xh-_empty-state-gap: var(--xh-stack-gap-md);
+    --xh-_empty-state-py: var(--xh-section-py-md);
+    --xh-_empty-state-icon-size: var(--xh-glyph-size-2xl);
+    /* 标题走小面标题档 14/500；sm 同档只缩图形与留白，lg 升到区块标题 heading-3 */
+    --xh-_empty-state-title-size: var(--xh-text-label-size);
+    /* 图标区的强调色：由 data-status（状态码）或 data-tone（语气）换掉；两样都没写就退成中性 */
+    --xh-_empty-state-accent: var(--xh-fg-subtle);
+
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: var(--xh-empty-state-gap, var(--xh-_empty-state-gap));
+    padding-block: var(--xh-empty-state-py, var(--xh-_empty-state-py));
+    padding-inline: var(--xh-empty-state-px, var(--xh-space-6));
+    color: var(--xh-empty-state-fg, var(--xh-fg-default));
+    text-align: center;
+  }
+
+  /* 活区节点常挂、靠 hidden 收起，上面声明了 display 会盖掉 UA 的 [hidden] 规则 */
+  .xh-scope-empty-state[data-part='root'][hidden] {
+    display: none;
+  }
+
+  .xh-scope-empty-state[data-part='root'][data-size='sm'] {
+    --xh-_empty-state-gap: var(--xh-stack-gap-sm);
+    --xh-_empty-state-py: var(--xh-section-py-sm);
+    --xh-_empty-state-icon-size: var(--xh-glyph-size-xl);
+  }
+
+  .xh-scope-empty-state[data-part='root'][data-size='lg'] {
+    --xh-_empty-state-gap: var(--xh-stack-gap-lg);
+    --xh-_empty-state-py: var(--xh-section-py-lg);
+    --xh-_empty-state-icon-size: var(--xh-glyph-size-3xl);
+    --xh-_empty-state-title-size: var(--xh-text-heading-3-size);
+  }
+
+  /* —— 状态码 —— */
+  /* 三个状态码各并进最接近的一族：找不到=提示，没权限=警示，服务出错=危险。
+     用 500 档而不是 600：500 是装饰性强调档，600 是给实心底与文字用的。
+     成功 / 警示 / 出错 / 提示这类通用结果不在这儿：那是语气，走下面的 data-tone */
+  .xh-scope-empty-state[data-part='root'][data-status='403'] {
+    --xh-_empty-state-accent: var(--xh-color-warning-500);
+  }
+
+  .xh-scope-empty-state[data-part='root'][data-status='500'] {
+    --xh-_empty-state-accent: var(--xh-color-danger-500);
+  }
+
+  .xh-scope-empty-state[data-part='root'][data-status='404'] {
+    --xh-_empty-state-accent: var(--xh-color-info-500);
+  }
+
+  /* 语气轴：写了 tone 就把强调色接到语气层派生好的前景档上。
+     排在状态码之后：两者都写时以显式的语气为准；不写 tone 时上面几条一字不变 */
+  .xh-scope-empty-state[data-part='root'][data-tone] {
+    --xh-_empty-state-accent: var(--xh-_tone-fg);
+  }
+
+  /* 结果页（写了语气）：图标坐进一枚 44px 语气淡底圆，字形收到 20px；淡底由语气层按 data-tone 给 */
+  .xh-scope-empty-state[data-part='root'][data-tone] .xh-scope-empty-state[data-part='indicator'] {
+    --xh-icon-size: var(--xh-empty-state-icon-size, var(--xh-glyph-size-md));
+
+    inline-size: var(--xh-empty-state-indicator-box, var(--xh-control-box-lg));
+    block-size: var(--xh-empty-state-indicator-box, var(--xh-control-box-lg));
+    border-radius: var(--xh-empty-state-indicator-radius, var(--xh-shape-circle));
+    background: var(--xh-empty-state-indicator-bg, var(--xh-_tone-subtle));
+    font-size: var(--xh-empty-state-icon-size, var(--xh-glyph-size-md));
+  }
+
+  /*
+   * 插画槽。它与图标槽二选一，尺寸另走一档：插画塞进按字形量的图标槽会被压到 40px 以下，
+   * 而空状态的插画通常是这个尺度的两倍。默认由图标档翻一倍派生，跟着三个尺寸档一起走。
+   */
+  .xh-scope-empty-state[data-part='media'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex: none;
+    max-inline-size: 100%;
+    block-size: var(--xh-empty-state-media-size, calc(var(--xh-_empty-state-icon-size) * 2));
+    color: var(--xh-empty-state-media-fg, var(--xh-_empty-state-accent));
+  }
+
+  .xh-scope-empty-state[data-part='indicator'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex: none;
+    /* 作者塞进图标槽的 XhIcon 与皮肤画的字形同一把尺，都按展示档的图标框量 */
+    --xh-icon-size: var(--xh-empty-state-icon-size, var(--xh-_empty-state-icon-size));
+
+    block-size: var(--xh-empty-state-icon-size, var(--xh-_empty-state-icon-size));
+    inline-size: var(--xh-empty-state-icon-size, var(--xh-_empty-state-icon-size));
+    color: var(--xh-empty-state-indicator-fg, var(--xh-_empty-state-accent));
+    /* 图标常是一个字形，字号跟着图标框走，line-height 不再另占高度 */
+    font-size: var(--xh-empty-state-indicator-font-size, var(--xh-_empty-state-icon-size));
+    line-height: var(--xh-leading-none);
+  }
+
+  .xh-scope-empty-state[data-part='title'] {
+    margin: 0;
+    color: var(--xh-empty-state-title-fg, var(--xh-fg-default));
+    font-size: var(--xh-empty-state-title-font-size, var(--xh-_empty-state-title-size));
+    font-weight: var(--xh-empty-state-title-font-weight, var(--xh-font-weight-medium));
+    line-height: var(--xh-empty-state-title-leading, var(--xh-leading-normal));
+  }
+
+  /* 标题与说明是一组：两者之间只留 4px，图形与它们、它们与动作之间才是整档间距 */
+  .xh-scope-empty-state[data-part='title'] + .xh-scope-empty-state[data-part='description'] {
+    margin-block-start: calc(var(--xh-space-1) - var(--xh-empty-state-gap, var(--xh-_empty-state-gap)));
+  }
+
+  .xh-scope-empty-state[data-part='description'] {
+    margin: 0;
+    max-inline-size: var(--xh-empty-state-description-max-w, var(--xh-measure-prose));
+    color: var(--xh-empty-state-description-fg, var(--xh-fg-muted));
+    font-size: var(--xh-empty-state-description-font-size, var(--xh-text-secondary-size));
+    line-height: var(--xh-empty-state-description-leading, var(--xh-leading-normal));
+  }
+
+  .xh-scope-empty-state[data-part='action'] {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: center;
+    gap: var(--xh-empty-state-action-gap, var(--xh-space-2));
+    /* 动作区比图文之间多让出 4px，操作与说明分得开 */
+    margin-block-start: var(--xh-space-1);
+  }
+
+  /* 图标、标题、说明、动作按次序开幕，间隔由交错步长派生。
+     backwards 不能省：等待期间起帧不生效的话，后三段会先露一下再跳回去。
+     随页面首屏就在的空状态带 data-instant 直接呈现，之后每一次出现才开幕 */
+  .xh-scope-empty-state[data-part='media']:not([data-instant]),
+  .xh-scope-empty-state[data-part='indicator']:not([data-instant]),
+  .xh-scope-empty-state[data-part='title']:not([data-instant]),
+  .xh-scope-empty-state[data-part='description']:not([data-instant]),
+  .xh-scope-empty-state[data-part='action']:not([data-instant]) {
+    animation: xh-rise-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong) backwards;
+  }
+
+  .xh-scope-empty-state[data-part='title'] {
+    animation-delay: calc(var(--xh-motion-stagger-step) * 1);
+  }
+
+  .xh-scope-empty-state[data-part='description'] {
+    animation-delay: calc(var(--xh-motion-stagger-step) * 2);
+  }
+
+  .xh-scope-empty-state[data-part='action'] {
+    animation-delay: calc(var(--xh-motion-stagger-step) * 3);
+  }
+
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  .xh-scope-empty-state[data-part='media'][hidden],
+  .xh-scope-empty-state[data-part='indicator'][hidden],
+  .xh-scope-empty-state[data-part='action'][hidden] {
+    display: none;
+  }
+}

package/dist/css/field-array.css

@@ -0,0 +1,229 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 field array 样式。 */
+
+/* FieldArray 独立皮肤同时传递引入把手的动作控件配方；full bundle 递归去重。 */
+@import '../family/action-control.css';
+/* 行的进场与退场取共享关键帧。 */
+@import '../family/motion.css';
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-field-array {
+    --xh-field-array-skin: 1;
+  }
+
+  /* 一行一条，纵向堆叠；新增把手跟在最后一行下面 */
+  .xh-scope-field-array[data-part='root'] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--xh-field-array-gap, var(--xh-space-2));
+    /* 删掉的行由替身绝对定位在原处播完退场，定位基准是根节点 */
+    position: relative;
+  }
+
+  /* 声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去 */
+  .xh-scope-field-array[data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* 内容在左、把手在右，把手那一列不随内容伸缩 */
+  .xh-scope-field-array[data-part='item'] {
+    display: flex;
+    align-items: center;
+    gap: var(--xh-field-array-item-gap, var(--xh-space-2));
+    padding: var(--xh-field-array-item-padding, var(--xh-space-0));
+    border-radius: var(--xh-field-array-item-radius, var(--xh-shape-surface));
+    /* 增删与上移下移带来的换位：由列表动效先反向补偿、再沿这条过渡滑到新位置 */
+    transition: translate var(--xh-motion-duration-move) var(--xh-motion-ease-continuous);
+  }
+
+  /* 新增的行进场，同一批按到达顺序错开；首帧就在的直接呈现（自己或根节点带 data-instant） */
+  .xh-scope-field-array[data-part='item']:not([data-instant], [data-instant] > :where(.xh-scope-field-array)) {
+    animation: xh-item-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong) backwards;
+    animation-delay: calc(var(--xh-_stagger-index, 0) * var(--xh-motion-stagger-step));
+  }
+
+  /* 删掉的行：替身留在原处淡出，播完即移除 */
+  .xh-scope-field-array[data-part='item'][data-state='closed'] {
+    animation: xh-fade-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit) forwards;
+  }
+
+  .xh-scope-field-array[data-part='item'][hidden] {
+    display: none;
+  }
+
+  /* 行前的行号或名目：不参与分宽，弱一档前景把它与行里的内容分开 */
+  .xh-scope-field-array[data-part='item-label'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    color: var(--xh-field-array-item-label-fg, var(--xh-fg-muted));
+    font-size: var(--xh-field-array-item-label-font-size, var(--xh-text-secondary-size));
+    line-height: var(--xh-leading-none);
+    white-space: nowrap;
+  }
+
+  .xh-scope-field-array[data-part='item-label'][hidden] {
+    display: none;
+  }
+
+  /* 行里放什么控件归作者，这里只给它一条能撑开也能收窄的轨道。
+     min-inline-size 归零：不写的话里面的输入框按 UA 默认宽度顶住，长内容会把整行撑破。
+     字段族控件放进来铺满这条轨道，与放进 Field 时一样；并排几个就平分，各自的压缩底线照旧 */
+  .xh-scope-field-array[data-part='item-content'] {
+    --xh-control-w: 100%;
+
+    display: flex;
+    flex: 1 1 auto;
+    align-items: center;
+    gap: var(--xh-field-array-content-gap, var(--xh-space-2));
+    min-inline-size: 0;
+  }
+
+  .xh-scope-field-array[data-part='item-action'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    gap: var(--xh-field-array-action-gap, var(--xh-space-1));
+  }
+
+  /* —— 行内三个把手 ——
+     只有字形的离散动作钮：盒几何、悬停 / 按下与 0.97 按压、粗指针热区、焦点环、禁用面全由 Action Control 的
+     icon ghost 档给（连接层投 xs：24px 正方盒，行级把手贴着一个控件高的行，取行内动作钮那一档），
+     组件只映射既有使用者槽。静息透明，白底承载 hover 100 → pressed 200。
+     按不动的把手由连接层同时打 aria-disabled 与 data-disabled，家族按后者收掉悬停与按下反馈 */
+  .xh-scope-field-array[data-part='item-delete-trigger'],
+  .xh-scope-field-array[data-part='move-up-trigger'],
+  .xh-scope-field-array[data-part='move-down-trigger'] {
+    --xh-action-visual-size: var(--xh-field-array-trigger-size, var(--xh-_action-profile-visual-size));
+    --xh-action-min-inline-size: var(--xh-field-array-trigger-size, var(--xh-_action-profile-visual-size));
+    --xh-action-radius: var(--xh-field-array-trigger-radius, var(--xh-shape-control));
+    --xh-action-bg-rest: var(--xh-field-array-trigger-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-field-array-trigger-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-field-array-trigger-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-fg-rest: var(--xh-field-array-trigger-fg, var(--xh-fg-muted));
+    --xh-action-fg-hover: var(--xh-field-array-trigger-fg-hover, var(--xh-fg-default));
+    --xh-action-fg-pressed: var(--xh-field-array-trigger-fg-hover, var(--xh-fg-default));
+    --xh-action-border-rest: transparent;
+    --xh-action-highlight-rest: transparent;
+    --xh-action-shadow-rest: none;
+    --xh-action-shadow-hover: none;
+    --xh-action-shadow-pressed: none;
+    --xh-action-font-size: var(--xh-field-array-trigger-font-size, var(--xh-text-secondary-size));
+    /* 作者塞进把手的图标与皮肤画的兜底字形同一把尺：按档取字形尺寸。
+       配方尚未把 profile 字形档灌进 --xh-icon-size，钮内字形先按 icon 档逐钮取值 */
+    --xh-icon-size: var(--xh-field-array-icon-size, var(--xh-_action-profile-glyph-size));
+
+    border-width: 0;
+  }
+
+  /* 不换序时连接层给换序把手写 hidden；家族那条 display 会把 UA 的 [hidden]{display:none}
+     盖掉，少了这条把手还留在原地。删除把手同样声明了 display，作者自己收起它时要的是同一条 */
+  .xh-scope-field-array[data-part='item-delete-trigger'][hidden],
+  .xh-scope-field-array[data-part='move-up-trigger'][hidden],
+  .xh-scope-field-array[data-part='move-down-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 删除把手悬停转危险色：它是这一行里唯一不可撤销的动作 */
+  .xh-scope-field-array[data-part='item-delete-trigger'] {
+    --xh-action-fg-hover: var(--xh-field-array-item-delete-fg-hover, var(--xh-fg-danger-hover));
+    --xh-action-fg-pressed: var(--xh-field-array-item-delete-fg-hover, var(--xh-fg-danger-hover));
+  }
+
+  /* —— 新增把手 ——
+     带文案的离散动作钮，走 text outline 档（中性描边、透明底，hover 100 → pressed 200），高一个控件；
+     虚线描边把它和行里的实心控件区分开：它加的是行，不是行里的值——家族只写 border-color，线型由这里给 */
+  .xh-scope-field-array[data-part='add-trigger'] {
+    --xh-action-visual-size: var(--xh-field-array-add-height, var(--xh-_action-profile-visual-size));
+    --xh-action-padding-inline: var(--xh-field-array-add-px, var(--xh-_action-profile-padding-inline));
+    --xh-action-gap: var(--xh-field-array-action-gap, var(--xh-space-1));
+    --xh-action-radius: var(--xh-field-array-add-radius, var(--xh-shape-control));
+    --xh-action-bg-rest: var(--xh-field-array-add-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-field-array-add-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-field-array-add-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-fg-rest: var(--xh-field-array-add-fg, var(--xh-fg-brand));
+    --xh-action-fg-hover: var(--xh-field-array-add-fg, var(--xh-fg-brand));
+    --xh-action-fg-pressed: var(--xh-field-array-add-fg, var(--xh-fg-brand));
+    --xh-action-border-rest: var(--xh-field-array-add-border, var(--xh-_action-variant-border-rest));
+    --xh-action-border-hover: var(--xh-field-array-add-border-hover, var(--xh-_action-variant-border-hover));
+    --xh-action-border-disabled: var(--xh-field-array-add-border-disabled, var(--xh-_action-variant-border-disabled));
+    --xh-action-highlight-rest: transparent;
+    --xh-action-shadow-rest: none;
+    --xh-action-shadow-hover: none;
+    --xh-action-shadow-pressed: none;
+    --xh-action-font-size: var(--xh-field-array-add-font-size, var(--xh-text-label-size));
+    --xh-icon-size: var(--xh-field-array-icon-size, var(--xh-_action-profile-glyph-size));
+
+    align-self: flex-start;
+    border-style: dashed;
+  }
+
+  .xh-scope-field-array[data-part='add-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 没写内容就由皮肤画兜底字形；作者往部件里塞了自己的图形，这几条即不命中 */
+  .xh-scope-field-array[data-part='move-up-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-chevron-up) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-chevron-up) center / contain no-repeat;
+  }
+
+  .xh-scope-field-array[data-part='move-down-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-chevron-down) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-chevron-down) center / contain no-repeat;
+  }
+
+  .xh-scope-field-array[data-part='item-delete-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-close) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-close) center / contain no-repeat;
+  }
+
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  .xh-scope-field-array[data-part='item-content'][hidden],
+  .xh-scope-field-array[data-part='item-action'][hidden] {
+    display: none;
+  }
+
+  @media (forced-colors: active) {
+    /* 兜底字形是 mask 挖出来的一块底色，这一档里底色被系统换成 Canvas，字形跟着消失。
+       字形退出强制换色、直接写系统色（不能取 currentColor：退出强制换色的伪元素读到的是被系统换掉之前的作者色）：
+       按钮面上取 ButtonText，悬停与按下时家族把按钮涂成 Highlight、字形换 HighlightText；
+       禁用取 GrayText */
+    .xh-scope-field-array:is([data-part='move-up-trigger'], [data-part='move-down-trigger'], [data-part='item-delete-trigger']):empty::before {
+      forced-color-adjust: none;
+      background-color: ButtonText;
+    }
+
+    .xh-scope-field-array:is([data-part='move-up-trigger'], [data-part='move-down-trigger'], [data-part='item-delete-trigger']):not([data-disabled]):not([data-loading]):is(:hover, :active, [data-pressed]):empty::before {
+      background-color: HighlightText;
+    }
+
+    .xh-scope-field-array:is([data-part='move-up-trigger'], [data-part='move-down-trigger'], [data-part='item-delete-trigger'])[data-disabled]:empty::before {
+      background-color: GrayText;
+    }
+  }
+}