@xihan-ui/styles 3.1.0 → 4.0.0

package/dist/css/description.css

@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/*
+ * 字段族说明与错误文案的公共层，按 [data-part='description'] / [data-part='error-text']
+ * 匹配下面逐个列出的 scope。
+ *
+ * 收在这里的是逐值相同的角色规则：说明 = --xh-text-caption-size / --xh-fg-subtle /
+ * --xh-leading-normal；错误文案 = --xh-text-caption-size / --xh-fg-danger / --xh-leading-normal；
+ * 两者外边距归零、紧贴控件（字段根的 gap 缺省为 0），最小高 --xh-space-5：这一行辅助行在表单里
+ * 就是字段之间的项距，有它的字段不再另留项距。挂了 --xh-<组件>-description-* /
+ * --xh-<组件>-error-* 覆盖槽的组件在各自皮肤里只另写带槽的 color / font-size 压过这里，
+ * margin 与 line-height 不再重写。
+ *
+ * 说明与错误文案落在控件下方的同一处：无效时收起说明，那一行只剩错误。两段同时在场
+ * 会把辅助区撑成两行，整表的字段高度随之参差。
+ *
+ * 收起只收视觉。说明的 id 仍挂在控件的 aria-describedby 上，读屏两段都念得到——
+ * 直接被 aria-describedby 指到的节点，隐藏与否都计入可及描述。
+ *
+ * scope 逐个列出，不写成 [data-part='description']：这个部件名在提示、气泡、
+ * 空状态、说明列表上指的是另一段文字，通配规则会把它们在无效态下一并收起。
+ * 要接进来的组件把自己的几条加进列表。
+ *
+ * 收起限定到直接子节点：字段集无效时收起的是它自己那段说明，不是组内各字段的说明。
+ * 引入顺序排在全部组件皮肤之前，组件要另作安排照写同样的无效态限定即可压过。
+ */
+@layer xihan.components {
+  .xh-scope-field[data-part='description'],
+  .xh-scope-fieldset[data-part='description'] {
+    margin: 0;
+    min-block-size: var(--xh-space-5);
+    font-size: var(--xh-text-caption-size);
+    line-height: var(--xh-leading-normal);
+    color: var(--xh-fg-subtle);
+  }
+
+  /* 错误文案出现时淡入。不 invalid 时节点带 hidden，但不交给浏览器的 [hidden] 规则收成 display: none：
+     从不生成盒到生成盒没有过渡的起点，淡入播不出来。收起态改成不占位（绝对定位、零高、裁切）、
+     不可见也不进可及树（visibility: hidden）的盒，露面时回到流里淡入；首帧就在的错误文案没有过渡起点，
+     直接呈现。收起那一下不占位的盒当场让位，不留淡出——同一行随即交还说明或整行收起，淡出只会叠在
+     别的内容上；Field 下方为错误文案预留了一行时，退场在那一行里淡出（见 field.css） */
+  .xh-scope-field[data-part='error-text'],
+  .xh-scope-fieldset[data-part='error-text'] {
+    margin: 0;
+    min-block-size: var(--xh-space-5);
+    font-size: var(--xh-text-caption-size);
+    line-height: var(--xh-leading-normal);
+    color: var(--xh-fg-danger);
+    transition: opacity var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+  }
+
+  .xh-scope-field[data-part='error-text'][hidden],
+  .xh-scope-fieldset[data-part='error-text'][hidden] {
+    display: block;
+    position: absolute;
+    block-size: 0;
+    min-block-size: 0;
+    overflow: clip;
+    visibility: hidden;
+    opacity: 0;
+    transition: none;
+  }
+
+  .xh-scope-field[data-part='root'][data-invalid] > .xh-scope-field[data-part='description'],
+  .xh-scope-fieldset[data-part='root'][data-invalid] > .xh-scope-fieldset[data-part='description'] {
+    display: none;
+  }
+}

package/dist/css/descriptions.css

@@ -0,0 +1,327 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 descriptions 样式。 */
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-descriptions {
+    --xh-descriptions-skin: 1;
+  }
+
+  .xh-scope-descriptions[data-part='root'] {
+    /* 一个尺寸档只换这几个私有槽，每一格与格内两段都从根上继承它们，
+       换档不必给每个部件各写一条选择器 */
+    /* 格与格之间行距窄、列距宽：一行里的几组左右分得开，上下读起来连成一列 */
+    --xh-_descriptions-row-gap: var(--xh-space-2);
+    --xh-_descriptions-column-gap: var(--xh-space-5);
+    /* 标签是每一格的集合标题：叠着排时与取值隔 space-2（集合标题与集合的间距）；标签在左时隔 20px */
+    --xh-_descriptions-pair-gap: var(--xh-space-2);
+    --xh-_descriptions-label-gap: var(--xh-space-5);
+    /* 描边档的单元格：上下 6px、左右 20px，单行格高约 33px */
+    --xh-_descriptions-py: var(--xh-space-1_5);
+    --xh-_descriptions-px: var(--xh-space-5);
+    /* 字号三档同为正文字号：尺寸档只换间距与格内距，不换字 */
+    --xh-_descriptions-font-size: var(--xh-control-font-md);
+    /* 标签在左时那一列的宽度：收到最长的那个标签 */
+    --xh-_descriptions-label-w: max-content;
+
+    display: grid;
+    /* 不写 columns 即每行一组；二到六列各有一条规则 */
+    grid-template-columns: minmax(0, 1fr);
+    gap: var(--xh-descriptions-gap, var(--xh-_descriptions-row-gap) var(--xh-_descriptions-column-gap));
+    /* 根可能写成 dl，UA 的上下外边距在这里清掉 */
+    margin: 0;
+    color: var(--xh-descriptions-fg, var(--xh-fg-default));
+    font-size: var(--xh-descriptions-font-size, var(--xh-_descriptions-font-size));
+    line-height: var(--xh-text-body-leading);
+  }
+
+  /* 上面声明了 display，会盖掉 UA 的 [hidden] 规则，收起态要在这里接回来 */
+  .xh-scope-descriptions[data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* —— 列数 —— */
+  .xh-scope-descriptions[data-part='root'][data-columns='2'] {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .xh-scope-descriptions[data-part='root'][data-columns='3'] {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+
+  .xh-scope-descriptions[data-part='root'][data-columns='4'] {
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+  }
+
+  .xh-scope-descriptions[data-part='root'][data-columns='5'] {
+    grid-template-columns: repeat(5, minmax(0, 1fr));
+  }
+
+  .xh-scope-descriptions[data-part='root'][data-columns='6'] {
+    grid-template-columns: repeat(6, minmax(0, 1fr));
+  }
+
+  /* —— 尺寸 —— */
+  .xh-scope-descriptions[data-part='root'][data-size='sm'] {
+    --xh-_descriptions-row-gap: var(--xh-space-1);
+    --xh-_descriptions-column-gap: var(--xh-space-4);
+    --xh-_descriptions-label-gap: var(--xh-space-4);
+    --xh-_descriptions-py: var(--xh-space-1);
+    --xh-_descriptions-px: var(--xh-space-4);
+  }
+
+  .xh-scope-descriptions[data-part='root'][data-size='lg'] {
+    --xh-_descriptions-row-gap: var(--xh-space-4);
+    --xh-_descriptions-column-gap: var(--xh-space-6);
+    --xh-_descriptions-pair-gap: var(--xh-space-2);
+    --xh-_descriptions-label-gap: var(--xh-space-6);
+    --xh-_descriptions-py: var(--xh-space-2);
+    --xh-_descriptions-px: var(--xh-space-6);
+  }
+
+  /* —— 头部 ——
+     列表之前的一行：左标题、右附加内容。它是根的兄弟，继承不到根上的私有槽，尺寸档自己再换一次 */
+  .xh-scope-descriptions[data-part='header'] {
+    --xh-_descriptions-header-mb: var(--xh-space-3);
+
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--xh-descriptions-header-gap, var(--xh-space-3));
+    margin-block-end: var(--xh-descriptions-header-mb, var(--xh-_descriptions-header-mb));
+  }
+
+  .xh-scope-descriptions[data-part='header'][data-size='sm'] {
+    --xh-_descriptions-header-mb: var(--xh-space-2);
+  }
+
+  .xh-scope-descriptions[data-part='header'][data-size='lg'] {
+    --xh-_descriptions-header-mb: var(--xh-space-4);
+  }
+
+  /* 标题是 Surface 内标题：正文字号 + 半粗；作者写成 h2 / h3 时 UA 的外边距与字号在这里清掉 */
+  .xh-scope-descriptions[data-part='title'] {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+    margin: 0;
+    color: var(--xh-descriptions-title-fg, var(--xh-fg-default));
+    font-size: var(--xh-descriptions-title-font-size, var(--xh-text-heading-3-size));
+    font-weight: var(--xh-descriptions-title-font-weight, var(--xh-text-heading-3-weight));
+    line-height: var(--xh-leading-relaxed);
+  }
+
+  /* 附加内容贴在行尾：操作钮或状态标签，一行放不下时整块换到下一行 */
+  .xh-scope-descriptions[data-part='extra'] {
+    display: flex;
+    flex: none;
+    align-items: center;
+    gap: var(--xh-descriptions-extra-gap, var(--xh-space-2));
+    margin-inline-start: auto;
+  }
+
+  /* —— 每一格 —— */
+  /* 一格自己也是网格：不写 placement 即标签一行、取值一行叠着排。
+     窄档每格横跨根上排定的所有列，一行只摆一组，作者写在格上的 span 这一档不认 */
+  .xh-scope-descriptions[data-part='item'] {
+    /* 作者写在这一格上的跨列数，由连接层落成这个槽；没写即一列 */
+    --xh-_descriptions-item-span: 1;
+
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    grid-column: 1 / -1;
+    align-content: start;
+    gap: var(--xh-descriptions-pair-gap, var(--xh-_descriptions-pair-gap));
+  }
+
+  /* 标签比取值重一档、颜色弱一档：扫读时先抓标签，读值时不被标签抢走 */
+  .xh-scope-descriptions[data-part='label'] {
+    color: var(--xh-descriptions-label-fg, var(--xh-fg-muted));
+    font-weight: var(--xh-descriptions-label-font-weight, var(--xh-font-weight-medium));
+  }
+
+  .xh-scope-descriptions[data-part='value'] {
+    /* 取值可能写成 dd，UA 的左缩进在这里清掉 */
+    margin: 0;
+    /* 网格项默认不肯收到内容以下，这行让长文本能被压窄 */
+    min-inline-size: 0;
+    color: var(--xh-descriptions-value-fg, var(--xh-fg-default));
+  }
+
+  /* —— 形态：ghost 即基础规则，不画壳；outline 画外框与网格线 —— */
+  .xh-scope-descriptions[data-part='root'][data-variant='outline'] {
+    /* 网格线由每格自己的边线拼出来，格与格之间不能再留缝 */
+    gap: 0;
+    border: var(--xh-stroke-thin) solid var(--xh-descriptions-border, var(--xh-border-default));
+    border-radius: var(--xh-descriptions-radius, var(--xh-shape-surface));
+    background: var(--xh-descriptions-bg, var(--xh-bg-surface));
+    /* 四角的格子要被圆角裁住 */
+    overflow: hidden;
+  }
+
+  /* 每格自带上边线与左边线，行首与首行那几格再各自抹掉，相邻两格之间就只剩一条 */
+  .xh-scope-descriptions[data-part='root'][data-variant='outline']
+    > .xh-scope-descriptions[data-part='item'] {
+    padding-block: var(--xh-descriptions-item-py, var(--xh-_descriptions-py));
+    padding-inline: var(--xh-descriptions-item-px, var(--xh-_descriptions-px));
+    border-block-start: var(--xh-stroke-thin) solid var(--xh-descriptions-divider, var(--xh-border-default));
+    /* 每行一组时左边没有邻居，宽度按列数补回来 */
+    border-inline-start: 0 solid var(--xh-descriptions-divider, var(--xh-border-default));
+  }
+
+  .xh-scope-descriptions[data-part='root'][data-variant='outline']
+    > .xh-scope-descriptions[data-part='item']:first-child {
+    border-block-start-width: 0;
+  }
+
+  /* 淡底档：不补网格线，surface 圆角 + subtle 底；描边留一圈透明边位，与 outline 同一几何 */
+  .xh-scope-descriptions[data-part='root'][data-variant='subtle'] {
+    border: var(--xh-stroke-thin) solid transparent;
+    border-radius: var(--xh-descriptions-radius, var(--xh-shape-surface));
+    background: var(--xh-descriptions-bg, var(--xh-bg-subtle));
+    overflow: hidden;
+  }
+
+  /* —— 逐档的列数与边线 ——
+     窄档一行只摆一组：每格的上边线就是行与行之间那条线，左边线用不上——
+     上面那两条默认规则就是这一档的写法。
+     宽起来以后逐档恢复：每一档写两件事，一是这一档一行摆几格（跨列数），
+     二是这一档的边线：不在行首的格补上左边线，首行那几格抹掉上边线。
+     两组集合逐档只增不减，宽档不必回收窄档写下的边线。 */
+  @media (min-width: 768px) {
+    /* 标签左置从这一档起生效：窄档一律标签在上，取值拿满整格的宽。
+       只认自己的直接子格，套在取值里的另一份描述由它自己的根管 */
+    .xh-scope-descriptions[data-part='root'][data-placement='left']
+      > .xh-scope-descriptions[data-part='item'] {
+      grid-template-columns: var(--xh-descriptions-label-w, var(--xh-_descriptions-label-w)) minmax(0, 1fr);
+      align-items: baseline;
+      column-gap: var(--xh-descriptions-label-gap, var(--xh-_descriptions-label-gap));
+    }
+
+    /* 描边档标签在左：标签单成一列淡底格，与取值之间一条竖线；内距从格上下放到标签与取值各自身上 */
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-placement='left']
+      > .xh-scope-descriptions[data-part='item'] {
+      align-items: stretch;
+      column-gap: 0;
+      padding: 0;
+    }
+
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-placement='left']
+      > .xh-scope-descriptions[data-part='item']
+      > :is(.xh-scope-descriptions[data-part='label'], .xh-scope-descriptions[data-part='value']) {
+      padding-block: var(--xh-descriptions-item-py, var(--xh-_descriptions-py));
+      padding-inline: var(--xh-descriptions-item-px, var(--xh-_descriptions-px));
+    }
+
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-placement='left']
+      > .xh-scope-descriptions[data-part='item']
+      > .xh-scope-descriptions[data-part='label'] {
+      border-inline-end: var(--xh-stroke-thin) solid var(--xh-descriptions-divider, var(--xh-border-default));
+      background: var(--xh-descriptions-label-bg, var(--xh-bg-muted));
+    }
+
+    /* 二列与三列在这一档按作者写的列数摆，作者写在格上的 span 从这一档起认 */
+    .xh-scope-descriptions[data-part='root'][data-columns='2']
+      > .xh-scope-descriptions[data-part='item'],
+    .xh-scope-descriptions[data-part='root'][data-columns='3']
+      > .xh-scope-descriptions[data-part='item'] {
+      grid-column: span var(--xh-_descriptions-item-span);
+    }
+
+    /* 四列与六列在这一档摆两列：一格横跨一半的轨道，作者写的 span 这一档同样不认——
+       一行只有两格时，认了 span 的那格反而比邻居窄。
+       五列没有能摆成两列等宽的跨列数，留在一列，到宽档再按作者的五列摆 */
+    .xh-scope-descriptions[data-part='root'][data-columns='4']
+      > .xh-scope-descriptions[data-part='item'] {
+      grid-column: span 2;
+    }
+
+    .xh-scope-descriptions[data-part='root'][data-columns='6']
+      > .xh-scope-descriptions[data-part='item'] {
+      grid-column: span 3;
+    }
+
+    /* 一行两格：二、四、六列在这一档共用这套边线 */
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='2']
+      > .xh-scope-descriptions[data-part='item']:not(:nth-child(2n + 1)),
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='4']
+      > .xh-scope-descriptions[data-part='item']:not(:nth-child(2n + 1)),
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='6']
+      > .xh-scope-descriptions[data-part='item']:not(:nth-child(2n + 1)) {
+      border-inline-start-width: var(--xh-stroke-thin);
+    }
+
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='2']
+      > .xh-scope-descriptions[data-part='item']:nth-child(-n + 2),
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='4']
+      > .xh-scope-descriptions[data-part='item']:nth-child(-n + 2),
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='6']
+      > .xh-scope-descriptions[data-part='item']:nth-child(-n + 2) {
+      border-block-start-width: 0;
+    }
+
+    /* 一行三格 */
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='3']
+      > .xh-scope-descriptions[data-part='item']:not(:nth-child(3n + 1)) {
+      border-inline-start-width: var(--xh-stroke-thin);
+    }
+
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='3']
+      > .xh-scope-descriptions[data-part='item']:nth-child(-n + 3) {
+      border-block-start-width: 0;
+    }
+  }
+
+  @media (min-width: 1024px) {
+    /* 四、五、六列到这一档按作者写的列数摆，作者写在格上的 span 从这一档起认 */
+    .xh-scope-descriptions[data-part='root'][data-columns='4']
+      > .xh-scope-descriptions[data-part='item'],
+    .xh-scope-descriptions[data-part='root'][data-columns='5']
+      > .xh-scope-descriptions[data-part='item'],
+    .xh-scope-descriptions[data-part='root'][data-columns='6']
+      > .xh-scope-descriptions[data-part='item'] {
+      grid-column: span var(--xh-_descriptions-item-span);
+    }
+
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='4']
+      > .xh-scope-descriptions[data-part='item']:not(:nth-child(4n + 1)) {
+      border-inline-start-width: var(--xh-stroke-thin);
+    }
+
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='4']
+      > .xh-scope-descriptions[data-part='item']:nth-child(-n + 4) {
+      border-block-start-width: 0;
+    }
+
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='5']
+      > .xh-scope-descriptions[data-part='item']:not(:nth-child(5n + 1)) {
+      border-inline-start-width: var(--xh-stroke-thin);
+    }
+
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='5']
+      > .xh-scope-descriptions[data-part='item']:nth-child(-n + 5) {
+      border-block-start-width: 0;
+    }
+
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='6']
+      > .xh-scope-descriptions[data-part='item']:not(:nth-child(6n + 1)) {
+      border-inline-start-width: var(--xh-stroke-thin);
+    }
+
+    .xh-scope-descriptions[data-part='root'][data-variant='outline'][data-columns='6']
+      > .xh-scope-descriptions[data-part='item']:nth-child(-n + 6) {
+      border-block-start-width: 0;
+    }
+  }
+
+  /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
+     写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
+  .xh-scope-descriptions[data-part='header'][hidden],
+  .xh-scope-descriptions[data-part='extra'][hidden],
+  .xh-scope-descriptions[data-part='item'][hidden] {
+    display: none;
+  }
+}