@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/layouts/criteria_field/CriteriaField.svelte

@@ -0,0 +1,97 @@
+<script lang="ts">
+
+    import type {Snippet} from "svelte";
+
+    interface Props {
+        style?: string;
+        theme?: string;
+        label: string;
+        label$style?: string;
+        labelSuffix?: string;
+        children: Snippet;
+        size?: '' | 'x15' | 'x20' | 'x25' | 'x30' | 'x35' | 'x40';
+    }
+
+    let {
+        style = '',
+        size = '',
+        theme,
+        label,
+        label$style,
+        labelSuffix = ':',
+        children
+    }: Props = $props();
+
+
+</script>
+<div class="uniface-filter-field {size}" data-theme={theme} {style}>
+    <div class="field-container">
+        <div class="field-label" style={label$style}>
+            <span>{label}{labelSuffix}</span>
+        </div>
+        <div class="field">
+            {@render children()}
+        </div>
+    </div>
+</div>
+<style>.uniface-filter-field {
+  box-sizing: border-box;
+  display: block;
+  position: relative;
+  padding: 0 4px;
+  width: 100px;
+}
+.uniface-filter-field.x15 {
+  width: 150px;
+}
+.uniface-filter-field.x20 {
+  width: 200px;
+}
+.uniface-filter-field.x25 {
+  width: 250px;
+}
+.uniface-filter-field.x30 {
+  width: 300px;
+}
+.uniface-filter-field.x35 {
+  width: 350px;
+}
+.uniface-filter-field.x40 {
+  width: 400px;
+}
+.uniface-filter-field .field-container {
+  width: 100%;
+  display: grid;
+  position: relative;
+  gap: 4px;
+  grid-template-columns: 1fr;
+}
+.uniface-filter-field .field-label {
+  color: var(--uniface-criteria-field-label-color);
+  font-size: 0.9em;
+  font-weight: 500;
+  width: 100%;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.uniface-filter-field .field {
+  position: relative;
+  display: flex;
+  flex-direction: row;
+  justify-items: center;
+  width: 100%;
+}
+
+.field-layout-horizontal .field-container {
+  grid-template-columns: auto 1fr;
+  align-items: center;
+  gap: 8px;
+}
+.field-layout-horizontal .field-label {
+  text-align: var(--uniface-criteria-field-label-alignment);
+  width: var(--uniface-criteria-field-label-width);
+  overflow: unset;
+  text-overflow: unset;
+  white-space: unset;
+}</style>

package/dist/layouts/criteria_field/CriteriaField.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from "svelte";
+interface Props {
+    style?: string;
+    theme?: string;
+    label: string;
+    label$style?: string;
+    labelSuffix?: string;
+    children: Snippet;
+    size?: '' | 'x15' | 'x20' | 'x25' | 'x30' | 'x35' | 'x40';
+}
+declare const CriteriaField: import("svelte").Component<Props, {}, "">;
+type CriteriaField = ReturnType<typeof CriteriaField>;
+export default CriteriaField;

package/dist/layouts/criteria_field/README.md

@@ -0,0 +1,277 @@
+# CriteriaField Component
+
+A field wrapper for filter / search forms: renders a label above a single child control (text editor, date range, select, checkbox, …) at one of seven fixed widths. The label gets an optional suffix (`:` by default) and is the only thing this component does — it does not validate, track value, or know what's inside.
+
+## Features
+
+- **Label + content slot**: a single `children` snippet for the actual control
+- **7 fixed widths**: `''` (100px) / `x15` (150px) / `x20` / `x25` / `x30` / `x35` / `x40` — pick the one that matches your control's natural size
+- **Label suffix**: `:` by default; set `labelSuffix=""` for checkboxes / radios where the colon looks wrong
+- **Label styling hook**: `label$style` for inline CSS on just the label
+- **Vertical layout only**: label above, control below. (CSS for a horizontal variant exists in the component but is **not exposed via any prop** — see "Layout" below.)
+- **Theme hook**: outer wrapper exposes `data-theme="{theme}"`
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+
+  let searchName = $state('');
+</script>
+
+<CriteriaField label="Name" size="x25">
+  <TextEditor
+    variant="outlined"
+    bind:value={searchName}
+    placeholder="Enter name to search"
+  />
+</CriteriaField>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | _(required)_ | Label text rendered above the field. The `labelSuffix` is appended directly to this string inside the same `<span>`. |
+| `size` | `'' \| 'x15' \| 'x20' \| 'x25' \| 'x30' \| 'x35' \| 'x40'` | `''` | Width preset. Empty string = 100px (see size table below). |
+| `labelSuffix` | `string` | `':'` | String appended after the label text. Pass `""` to drop the colon for non-input controls like checkboxes. |
+| `label$style` | `string \| undefined` | `undefined` | Inline CSS on the label `<div>`. The `$` is part of the prop name (Svelte 5 escapes reserved names this way). |
+| `style` | `string` | `''` | Inline CSS on the outer wrapper |
+| `theme` | `string \| undefined` | `undefined` | Set as `data-theme` on the outer wrapper |
+| `children` | `Snippet` | _(required)_ | The actual form control |
+
+> **`children` is required.** Without it the field renders an empty box.
+
+## Size Reference
+
+| `size` | Width |
+|--------|-------|
+| `''` (default) | **100px** |
+| `'x15'` | 150px |
+| `'x20'` | 200px |
+| `'x25'` | 250px |
+| `'x30'` | 300px |
+| `'x35'` | 350px |
+| `'x40'` | 400px |
+
+The outer wrapper also has `padding: 0 4px`, so the visible content area is 8px narrower than the preset.
+
+## Layout
+
+Always vertical (label above field):
+
+```text
+┌──────────────────────────┐
+│ .field-label   "Label:"  │   ← single line, ellipsis on overflow
+├──────────────────────────┤
+│ .field        {children} │   ← flex row, full width
+└──────────────────────────┘
+```
+
+Internally, `.field-container` is a CSS grid with a single column (`grid-template-columns: 1fr`) and a 4px gap.
+
+> **Horizontal layout exists in CSS but is unreachable.** The stylesheet defines `.field-layout-horizontal .field-container { grid-template-columns: auto 1fr; ... }`, but the template never adds the `field-layout-horizontal` class. There's no `layout` / `orientation` prop. If you need a horizontal label/control layout, use [FormField](../form_field/README.md) instead, or override the grid in your own CSS.
+
+## Examples
+
+### Text Search Field
+
+```svelte
+<script>
+  import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+
+  let searchText = $state('');
+</script>
+
+<CriteriaField label="Search" size="x30">
+  <TextEditor
+    variant="outlined"
+    bind:value={searchText}
+    placeholder="* is a wildcard character"
+  />
+</CriteriaField>
+```
+
+### Date Range Filter
+
+```svelte
+<script>
+  import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+  import DateRange from '@ticatec/uniface-element/DateRange';
+
+  let dateFrom = $state('');
+  let dateTo = $state('');
+</script>
+
+<CriteriaField label="Date Range" size="x35">
+  <DateRange
+    variant="outlined"
+    bind:fromValue={dateFrom}
+    bind:toValue={dateTo}
+  />
+</CriteriaField>
+```
+
+### Checkbox (no colon)
+
+```svelte
+<script>
+  import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+  import CheckBox from '@ticatec/uniface-element/CheckBox';
+
+  let includeInactive = $state(false);
+</script>
+
+<CriteriaField label="Options" size="x25" labelSuffix="">
+  <CheckBox
+    label="Include inactive customers"
+    bind:value={includeInactive}
+  />
+</CriteriaField>
+```
+
+### Custom Label Style
+
+```svelte
+<CriteriaField
+  label="Advanced Search"
+  size="x40"
+  label$style="color: #2563eb; font-weight: 600; font-size: 14px;"
+  labelSuffix=""
+>
+  <TextEditor bind:value={query} placeholder="Enter search terms..." />
+</CriteriaField>
+```
+
+### Default Size (100px)
+
+```svelte
+<!-- size omitted entirely → 100px wide -->
+<CriteriaField label="ID">
+  <TextEditor bind:value={id} />
+</CriteriaField>
+```
+
+### Complete Search Form
+
+Multiple CriteriaFields laid out with flex:
+
+```svelte
+<script>
+  import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+  import TextEditor    from '@ticatec/uniface-element/TextEditor';
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  import CheckBox      from '@ticatec/uniface-element/CheckBox';
+
+  let criteria = $state({
+    name: '', email: '', status: '', includeInactive: false
+  });
+
+  const statusOptions = [
+    { code: 'active',   text: 'Active' },
+    { code: 'inactive', text: 'Inactive' },
+    { code: 'pending',  text: 'Pending' }
+  ];
+</script>
+
+<div style="display: flex; gap: 16px; flex-wrap: wrap;">
+  <CriteriaField label="Name" size="x25">
+    <TextEditor variant="outlined" bind:value={criteria.name} placeholder="* for wildcard" />
+  </CriteriaField>
+
+  <CriteriaField label="Email" size="x30">
+    <TextEditor variant="outlined" bind:value={criteria.email} placeholder="email@domain.com" />
+  </CriteriaField>
+
+  <CriteriaField label="Status" size="x20">
+    <OptionsSelect variant="outlined" bind:value={criteria.status} options={statusOptions} />
+  </CriteriaField>
+
+  <CriteriaField label="Options" size="x25" labelSuffix="">
+    <CheckBox label="Include inactive" bind:value={criteria.includeInactive} />
+  </CriteriaField>
+</div>
+```
+
+## DOM Structure & CSS
+
+Rendered output:
+
+```html
+<div class="uniface-filter-field {size}" data-theme="..." style="...">
+  <div class="field-container">
+    <div class="field-label" style="{label$style}">
+      <span>{label}{labelSuffix}</span>
+    </div>
+    <div class="field">
+      <!-- children -->
+    </div>
+  </div>
+</div>
+```
+
+### CSS Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `--uniface-criteria-field-label-color` | Label text color |
+| `--uniface-criteria-field-label-alignment` | Horizontal-mode label text-align (unused in vertical layout) |
+| `--uniface-criteria-field-label-width` | Horizontal-mode label width (unused in vertical layout) |
+
+Only `--uniface-criteria-field-label-color` is actually consumed in the vertical layout.
+
+### Built-in label styles
+
+```css
+.field-label {
+  color: var(--uniface-criteria-field-label-color);
+  font-size: 0.9em;          /* slightly smaller than surrounding text */
+  font-weight: 500;
+  white-space: nowrap;       /* single line */
+  overflow: hidden;
+  text-overflow: ellipsis;   /* long labels show … */
+}
+```
+
+## Behavior Notes
+
+- **Label is single-line.** Long labels clip with `…`. There's no `title` attribute on the label by default, so the full text isn't discoverable on hover — keep labels short or add your own tooltip.
+- **`labelSuffix` is glued to the label inside the same `<span>`** — `label="Name"` + `labelSuffix=":"` renders `"Name:"`. There's no separator space.
+- **Outer wrapper has `padding: 0 4px`** — content is inset 4px on each side. Account for this when laying out adjacent fields.
+- **No validation, no required marker, no error state.** This is a pure layout primitive. Pair with your own validation UI.
+- **Theme is set on the outer wrapper**, not propagated inward. CSS variables defined under `[data-theme="..."]` selectors will cascade into the label.
+
+## Accessibility
+
+- The label is rendered as plain `<span>` text — **not associated with the field via `<label for="...">`**. Screen readers won't announce the label when focus moves into the wrapped control.
+- For real form-field semantics, give the inner control an `id` and add a `<label for="...">` yourself (e.g. via the `header` snippet pattern), or use [FormField](../form_field/README.md) if it offers proper label association.
+- The label is selectable text — `user-select` is not disabled.
+
+## Best Practices
+
+1. **Pick the smallest size that fits your control.** Don't default to `x40` for everything — visual rhythm matters in filter forms.
+2. **Drop the colon for non-input controls** (`labelSuffix=""` for checkboxes, radios, toggles).
+3. **Keep labels short** — they truncate with `…` and there's no hover tooltip to recover the full text.
+4. **Use flex/grid to lay out multiple CriteriaFields** — they're designed to sit in a row and wrap naturally.
+5. **Don't try to force horizontal layout here.** The CSS hook exists but isn't wired up; use FormField or your own wrapper.
+
+## Related Components
+
+- [FormField](../form_field/README.md) — sibling field wrapper (check its capabilities for label association / horizontal layout)
+- [TextEditor](../../form/text_editor/README.md) — common child control
+- [OptionsSelect](../../form/options_select/README.md) — common child control for filter dropdowns

package/dist/layouts/criteria_field/README_CN.md

@@ -0,0 +1,277 @@
+# CriteriaField 条件字段组件
+
+筛选 / 搜索表单的字段 wrapper：在单个子控件（文本框、日期范围、下拉、复选框……）上方渲染一个标签，并提供七种固定宽度。标签可带可选后缀（默认 `:`）—— 这个组件**只做这一件事**：不做校验、不跟踪值、不知道里面装的是什么。
+
+## 功能特性
+
+- **标签 + 内容槽**：单个 `children` snippet 装实际控件
+- **7 种固定宽度**：`''`（100px）/ `x15`（150px）/ `x20` / `x25` / `x30` / `x35` / `x40` —— 按控件的自然尺寸选
+- **标签后缀**：默认 `:`；复选框 / 单选按钮等设 `labelSuffix=""` 去掉冒号
+- **标签样式钩子**：`label$style` 仅作用于标签
+- **仅纵向布局**：标签在上、控件在下。（CSS 里有横向变体定义，但**没有任何 prop 暴露** —— 见"布局"）
+- **主题钩子**：外层 wrapper 暴露 `data-theme="{theme}"`
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```typescript
+import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+
+  let searchName = $state('');
+</script>
+
+<CriteriaField label="姓名" size="x25">
+  <TextEditor
+    variant="outlined"
+    bind:value={searchName}
+    placeholder="输入要搜索的姓名"
+  />
+</CriteriaField>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `label` | `string` | _(必填)_ | 字段上方的标签文字。`labelSuffix` 直接拼接到这个字符串后面，渲染在同一个 `<span>` 里 |
+| `size` | `'' \| 'x15' \| 'x20' \| 'x25' \| 'x30' \| 'x35' \| 'x40'` | `''` | 宽度预设。空字符串 = 100px（见下表） |
+| `labelSuffix` | `string` | `':'` | 标签文字后追加的字符串。非输入型控件（复选框等）传 `""` 去掉冒号 |
+| `label$style` | `string \| undefined` | `undefined` | 标签 `<div>` 的内联 CSS。`$` 是属性名的一部分（Svelte 5 用它转义保留字） |
+| `style` | `string` | `''` | 外层 wrapper 的内联 CSS |
+| `theme` | `string \| undefined` | `undefined` | 设为外层 wrapper 的 `data-theme` |
+| `children` | `Snippet` | _(必填)_ | 实际的表单控件 |
+
+> **`children` 是必填的。** 不传会渲染一个空盒子。
+
+## 尺寸对照
+
+| `size` | 宽度 |
+|--------|------|
+| `''`（默认） | **100px** |
+| `'x15'` | 150px |
+| `'x20'` | 200px |
+| `'x25'` | 250px |
+| `'x30'` | 300px |
+| `'x35'` | 350px |
+| `'x40'` | 400px |
+
+外层 wrapper 还有 `padding: 0 4px`，所以可见内容区比预设窄 8px。
+
+## 布局
+
+永远是纵向（标签在上）：
+
+```text
+┌──────────────────────────┐
+│ .field-label   "标签："  │   ← 单行，溢出加省略号
+├──────────────────────────┤
+│ .field        {children} │   ← flex row，整宽
+└──────────────────────────┘
+```
+
+内部 `.field-container` 是 CSS grid，单列（`grid-template-columns: 1fr`），间距 4px。
+
+> **横向布局的 CSS 存在但用不到。** 样式表里定义了 `.field-layout-horizontal .field-container { grid-template-columns: auto 1fr; ... }`，但模板里从不加 `field-layout-horizontal` 类，也没有 `layout` / `orientation` prop。需要横向标签 / 控件布局请用 [FormField](../form_field/README_CN.md)，或自己用 CSS 覆盖 grid。
+
+## 示例
+
+### 文本搜索字段
+
+```svelte
+<script>
+  import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+
+  let searchText = $state('');
+</script>
+
+<CriteriaField label="搜索" size="x30">
+  <TextEditor
+    variant="outlined"
+    bind:value={searchText}
+    placeholder="* 是通配符"
+  />
+</CriteriaField>
+```
+
+### 日期范围筛选
+
+```svelte
+<script>
+  import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+  import DateRange from '@ticatec/uniface-element/DateRange';
+
+  let dateFrom = $state('');
+  let dateTo = $state('');
+</script>
+
+<CriteriaField label="日期范围" size="x35">
+  <DateRange
+    variant="outlined"
+    bind:fromValue={dateFrom}
+    bind:toValue={dateTo}
+  />
+</CriteriaField>
+```
+
+### 复选框（无冒号）
+
+```svelte
+<script>
+  import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+  import CheckBox from '@ticatec/uniface-element/CheckBox';
+
+  let includeInactive = $state(false);
+</script>
+
+<CriteriaField label="选项" size="x25" labelSuffix="">
+  <CheckBox
+    label="包含未活跃客户"
+    bind:value={includeInactive}
+  />
+</CriteriaField>
+```
+
+### 自定义标签样式
+
+```svelte
+<CriteriaField
+  label="高级搜索"
+  size="x40"
+  label$style="color: #2563eb; font-weight: 600; font-size: 14px;"
+  labelSuffix=""
+>
+  <TextEditor bind:value={query} placeholder="输入搜索关键词..." />
+</CriteriaField>
+```
+
+### 默认尺寸（100px）
+
+```svelte
+<!-- 不传 size → 100px 宽 -->
+<CriteriaField label="ID">
+  <TextEditor bind:value={id} />
+</CriteriaField>
+```
+
+### 完整搜索表单
+
+多个 CriteriaField 用 flex 排版：
+
+```svelte
+<script>
+  import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+  import TextEditor    from '@ticatec/uniface-element/TextEditor';
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  import CheckBox      from '@ticatec/uniface-element/CheckBox';
+
+  let criteria = $state({
+    name: '', email: '', status: '', includeInactive: false
+  });
+
+  const statusOptions = [
+    { code: 'active',   text: '活跃' },
+    { code: 'inactive', text: '未活跃' },
+    { code: 'pending',  text: '待处理' }
+  ];
+</script>
+
+<div style="display: flex; gap: 16px; flex-wrap: wrap;">
+  <CriteriaField label="姓名" size="x25">
+    <TextEditor variant="outlined" bind:value={criteria.name} placeholder="* 表示通配符" />
+  </CriteriaField>
+
+  <CriteriaField label="邮箱" size="x30">
+    <TextEditor variant="outlined" bind:value={criteria.email} placeholder="email@domain.com" />
+  </CriteriaField>
+
+  <CriteriaField label="状态" size="x20">
+    <OptionsSelect variant="outlined" bind:value={criteria.status} options={statusOptions} />
+  </CriteriaField>
+
+  <CriteriaField label="选项" size="x25" labelSuffix="">
+    <CheckBox label="包含未活跃" bind:value={criteria.includeInactive} />
+  </CriteriaField>
+</div>
+```
+
+## DOM 结构与 CSS
+
+实际渲染：
+
+```html
+<div class="uniface-filter-field {size}" data-theme="..." style="...">
+  <div class="field-container">
+    <div class="field-label" style="{label$style}">
+      <span>{label}{labelSuffix}</span>
+    </div>
+    <div class="field">
+      <!-- children -->
+    </div>
+  </div>
+</div>
+```
+
+### CSS 变量
+
+| 变量 | 用途 |
+|------|------|
+| `--uniface-criteria-field-label-color` | 标签文字色 |
+| `--uniface-criteria-field-label-alignment` | 横向模式下的标签 text-align（纵向模式用不到） |
+| `--uniface-criteria-field-label-width` | 横向模式下的标签宽度（纵向模式用不到） |
+
+纵向布局实际只消费 `--uniface-criteria-field-label-color`。
+
+### 标签内置样式
+
+```css
+.field-label {
+  color: var(--uniface-criteria-field-label-color);
+  font-size: 0.9em;          /* 比周围文字略小 */
+  font-weight: 500;
+  white-space: nowrap;       /* 单行 */
+  overflow: hidden;
+  text-overflow: ellipsis;   /* 长标签显示 … */
+}
+```
+
+## 行为说明
+
+- **标签是单行。** 长标签用 `…` 截断。标签默认不带 `title` 属性，悬停看不到完整文字 —— 保持标签简短，或自己加 tooltip
+- **`labelSuffix` 直接粘在标签后面**，渲染在同一个 `<span>` 里 —— `label="姓名"` + `labelSuffix="："` 渲染成 `"姓名："`，中间没有空格
+- **外层 wrapper 有 `padding: 0 4px`** —— 内容两侧各缩进 4px。布局相邻字段时要算上这个
+- **不做校验、没有必填标记、没有错误状态。** 纯布局原语，校验 UI 自己搭
+- **`theme` 设在外层 wrapper**，不向内传播。在 `[data-theme="..."]` 选择器下定义的 CSS 变量会级联到标签
+
+## 无障碍访问
+
+- 标签是普通 `<span>` 文字 —— **没有通过 `<label for="...">` 与字段关联**。屏幕阅读器在焦点进入控件时不会朗读这个标签
+- 要真正的表单字段语义，给内部控件加 `id`，自己加 `<label for="...">`（比如用 header snippet 模式），或用 [FormField](../form_field/README_CN.md)（如果它支持正确的标签关联）
+- 标签是可选中文字 —— 没禁用 `user-select`
+
+## 最佳实践
+
+1. **选最小的合适尺寸。** 不要无脑 `x40`，筛选表单的视觉节奏很重要
+2. **非输入型控件去掉冒号**（`labelSuffix=""`，复选框、单选、开关等）
+3. **标签保持简短** —— 会用 `…` 截断，又没有悬停 tooltip 救场
+4. **多个 CriteriaField 用 flex/grid 排版** —— 设计成同排自然换行
+5. **不要在这里强求横向布局。** CSS 钩子存在但没接出来，需要横向就用 FormField 或自己包
+
+## 相关组件
+
+- [FormField](../form_field/README_CN.md) —— 同类字段 wrapper（看它是否支持标签关联 / 横向布局）
+- [TextEditor](../../form/text_editor/README_CN.md) —— 常用子控件
+- [OptionsSelect](../../form/options_select/README_CN.md) —— 筛选下拉的常用子控件