@keyfunc/keybricks-ds 2.4.0 → 2.4.4

package/components/data/SmartTable.jsx

@@ -4,22 +4,34 @@ import { IconButton } from "../buttons/IconButton.jsx";
 import { Checkbox } from "../forms/Checkbox.jsx";
 import { Avatar } from "../display/Avatar.jsx";
 import { SearchInput } from "../forms/SearchInput.jsx";
+import { Menu } from "../feedback/Menu.jsx";
 
 const typeIcon = { text: "type", longText: "align-left", number: "hash", select: "chevron-down", multiSelect: "tag", date: "calendar", person: "user", checkbox: "check-square", url: "link", progress: "bar-chart-2" };
 const Pill = ({ hue = "gray", children }) => <span style={{ display: "inline-flex", alignItems: "center", height: 20, padding: "0 8px", borderRadius: "var(--radius-full)", background: `var(--hue-${hue}-bg)`, color: `var(--hue-${hue}-fg)`, fontFamily: "var(--font-sans)", fontWeight: "var(--weight-medium)", fontSize: "var(--text-xs)", lineHeight: 1, whiteSpace: "nowrap" }}>{children}</span>;
 
 /** Notion/Airtable-style database grid ("smart table"): field-type icons in headers, colored select pills, person/date/checkbox/url/progress cells, row hover + expand, inline text/number editing, + New row, add-field column, per-column footer aggregates, and a view toolbar (Hide fields · Filter · Group · Sort · search). */
- /* A size region that defaults to sm: a database grid is a dense surface, so rows are the sm bar height (36), cells and toolbar read the sm control text (12px, 13px in CJK) and the toolbar's buttons are 28px. Pass size="md" for a roomier grid. */
-export function SmartTable({ fields = [], rows = [], title = "Grid view", toolbar = true, height, rowHeight = "var(--bar-h)", size = "sm", onChange, style }) {
+ /* A size region that defaults to sm: a database grid is a dense surface, so rows are the sm bar height (36), cells and toolbar read the sm control text (12px, 13px in CJK) and the toolbar's buttons are 28px. Pass size="md" for a roomier grid.
+    density: "default" rows are --bar-h (36 / 40 / 48) with --cell-px; "compact" rows are --control-h (28 / 32 / 40, the Spreadsheet's cell height) with the Spreadsheet's 8px padding (so at sm only the height changes). Header and footer follow. The toolbar's "Row height" menu switches it; rowHeight (a raw height) overrides density.
+    Frozen edges (like Spreadsheet): the field header row is sticky to the top and the 40px row-number column to the left; the corner cell is sticky on both axes. Sticky cells keep the --bg-inset fill so body cells never show through, and the frozen edge is a --border-subtle hairline. */
+const DENSITY = { default: { h: "var(--bar-h)", px: "var(--cell-px)" }, compact: { h: "var(--control-h)", px: "8px" } };
+export function SmartTable({ fields = [], rows = [], title = "Grid view", toolbar = true, height, rowHeight, density: densityProp, defaultDensity = "default", onDensityChange, size = "sm", onChange, style }) {
   const [data, setData] = React.useState(rows);
+  const [densityState, setDensityState] = React.useState(defaultDensity);
+  const density = DENSITY[densityProp || densityState] ? (densityProp || densityState) : "default";
+  const setDensity = (d) => { if (!densityProp) setDensityState(d); onDensityChange && onDensityChange(d); };
+  const rowH = rowHeight != null ? rowHeight : DENSITY[density].h;
   const [hover, setHover] = React.useState(-1);
   const [editing, setEditing] = React.useState(null);
   const [draft, setDraft] = React.useState("");
   const setCell = (r, key, v) => { const next = data.map((row, i) => i === r ? { ...row, [key]: v } : row); setData(next); onChange && onChange(next); };
   const widths = ["40px", ...fields.map(f => (f.width || 140) + "px"), "40px"];
   const grid = { display: "grid", gridTemplateColumns: widths.join(" "), width: "fit-content", minWidth: "100%" };
-  const cellBase = { display: "flex", alignItems: "center", gap: 5, padding: "0 var(--cell-px)", borderRight: "1px solid var(--border-subtle)", borderBottom: "1px solid var(--border-subtle)", height: rowHeight, boxSizing: "border-box", overflow: "hidden", whiteSpace: "nowrap", fontFamily: "var(--font-sans)", fontSize: "var(--control-text)", lineHeight: "var(--control-leading)", letterSpacing: "var(--control-tracking)", color: "var(--text-primary)" };
+  const cellBase = { display: "flex", alignItems: "center", gap: 5, padding: "0 " + DENSITY[density].px, borderRight: "1px solid var(--border-subtle)", borderBottom: "1px solid var(--border-subtle)", height: rowH, boxSizing: "border-box", overflow: "hidden", whiteSpace: "nowrap", fontFamily: "var(--font-sans)", fontSize: "var(--control-text)", lineHeight: "var(--control-leading)", letterSpacing: "var(--control-tracking)", color: "var(--text-primary)" };
   const tierIcon = { width: "var(--control-icon)", height: "var(--control-icon)" };
+  // Frozen edges — zIndex 1 (row-number column) < 2 (header row) < 3 (corner, both axes); the editing input sits inside a body cell, under them.
+  const stickyTop = { position: "sticky", top: 0, zIndex: 2, background: "var(--bg-inset)" };
+  const stickyLeft = { position: "sticky", left: 0, zIndex: 1, background: "var(--bg-inset)" };
+  const stickyCorner = { ...stickyTop, left: 0, zIndex: 3 };
   const agg = (f) => {
     if (!f.aggregate) return "";
     const vals = data.map(r => r[f.key]);
@@ -51,21 +63,22 @@ export function SmartTable({ fields = [], rows = [], title = "Grid view", toolba
         <button type="button" data-wash="strong" style={{ display: "inline-flex", alignItems: "center", gap: 6, height: "var(--control-h)", padding: "0 var(--control-px)", border: "none", borderRadius: "var(--radius-md)", background: "var(--wash, var(--bg-active))", transition: "var(--t-hover)", cursor: "pointer", color: "var(--text-heading)", fontFamily: "var(--font-sans)", fontWeight: "var(--weight-medium)", fontSize: "var(--control-text)", letterSpacing: "var(--control-tracking)" }}><Icon name="layout-grid" size={14} style={tierIcon} />{title}<Icon name="chevron-down" size={14} style={tierIcon} /></button>
         <span style={{ width: 1, height: 16, background: "var(--border-control)", margin: "0 4px" }}></span>
         {tbBtn("eye-off", "Hide fields")}{tbBtn("funnel", "Filter")}{tbBtn("layers", "Group")}{tbBtn("arrow-down", "Sort")}
+        <Menu trigger={tbBtn("menu", "Row height")} items={[{ label: "Compact", selected: density === "compact" }, { label: "Default", selected: density === "default" }]} onSelect={(l) => setDensity(l === "Compact" ? "compact" : "default")} />
         <span style={{ flex: 1 }}></span>
         <SearchInput bare placeholder="Search..." style={{ width: 140, gap: 6 }} />
       </div>}
       <div style={{ overflow: "auto", maxHeight: height }}>
         <div style={grid}>
-          <span style={{ ...cellBase, background: "var(--bg-inset)", justifyContent: "center" }}></span>
-          {fields.map(f => <span key={f.key} style={{ ...cellBase, background: "var(--bg-inset)", color: "var(--text-secondary)", fontWeight: "var(--weight-semibold)" }}><Icon name={typeIcon[f.type] || "type"} size={14} style={{ ...tierIcon, color: "var(--text-muted)" }} />{f.label}</span>)}
-          <span style={{ ...cellBase, background: "var(--bg-inset)", justifyContent: "center", padding: 0 }}><IconButton icon="plus" muted label="Add field" /></span>
+          <span style={{ ...cellBase, ...stickyCorner, justifyContent: "center" }}></span>
+          {fields.map(f => <span key={f.key} style={{ ...cellBase, ...stickyTop, color: "var(--text-secondary)", fontWeight: "var(--weight-semibold)" }}><Icon name={typeIcon[f.type] || "type"} size={14} style={{ ...tierIcon, color: "var(--text-muted)" }} />{f.label}</span>)}
+          <span style={{ ...cellBase, ...stickyTop, justifyContent: "center", padding: 0 }}><IconButton icon="plus" muted label="Add field" /></span>
           {data.map((row, r) => [
-            <span key={"n" + r} onMouseEnter={() => setHover(r)} onMouseLeave={() => setHover(-1)} style={{ ...cellBase, justifyContent: "center", color: "var(--text-muted)", fontFamily: "var(--font-sans)", fontVariantNumeric: "tabular-nums", fontSize: "var(--text-xs)", letterSpacing: 0, background: hover === r ? "var(--bg-inset)" : "transparent", cursor: "pointer" }}>{hover === r ? <Icon name="maximize-2" size={14} style={{ ...tierIcon, color: "var(--action-primary)" }} /> : r + 1}</span>,
+            <span key={"n" + r} onMouseEnter={() => setHover(r)} onMouseLeave={() => setHover(-1)} style={{ ...cellBase, ...stickyLeft, justifyContent: "center", color: "var(--text-muted)", fontFamily: "var(--font-sans)", fontVariantNumeric: "tabular-nums", fontSize: "var(--text-xs)", letterSpacing: 0, cursor: "pointer" }}>{hover === r ? <Icon name="maximize-2" size={14} style={{ ...tierIcon, color: "var(--action-primary)" }} /> : r + 1}</span>,
             ...fields.map(f => <span key={r + f.key} onMouseEnter={() => setHover(r)} onMouseLeave={() => setHover(-1)} onDoubleClick={() => { if (f.type === "text" || f.type === "number" || f.type === "date" || f.type === "url") { setEditing({ r, key: f.key }); setDraft(String(row[f.key] == null ? "" : row[f.key])); } }} style={{ ...cellBase, position: "relative", background: hover === r ? "var(--bg-inset)" : "transparent" }}>{renderCell(f, row, r)}</span>),
             <span key={"a" + r} style={{ ...cellBase, background: hover === r ? "var(--bg-inset)" : "transparent" }}></span>,
           ])}
-          <button type="button" onClick={() => { const empty = {}; fields.forEach(f => empty[f.key] = f.type === "multiSelect" ? [] : f.type === "checkbox" ? false : ""); const next = [...data, empty]; setData(next); onChange && onChange(next); }} style={{ gridColumn: "1 / -1", display: "flex", alignItems: "center", gap: 6, height: rowHeight, padding: "0 var(--edge-pad)", border: "none", borderBottom: "1px solid var(--border-subtle)", background: "transparent", cursor: "pointer", color: "var(--text-secondary)", fontFamily: "var(--font-sans)", fontSize: "var(--control-text)", letterSpacing: "var(--control-tracking)", textAlign: "left" }} onMouseEnter={(e) => e.currentTarget.style.background = "var(--bg-inset)"} onMouseLeave={(e) => e.currentTarget.style.background = "transparent"}><Icon name="plus" size={13} />New</button>
-          <span style={{ ...cellBase, borderBottom: "none", background: "var(--bg-inset)" }}></span>
+          <button type="button" onClick={() => { const empty = {}; fields.forEach(f => empty[f.key] = f.type === "multiSelect" ? [] : f.type === "checkbox" ? false : ""); const next = [...data, empty]; setData(next); onChange && onChange(next); }} style={{ gridColumn: "1 / -1", display: "flex", alignItems: "center", gap: 6, height: rowH, padding: "0 var(--edge-pad)", border: "none", borderBottom: "1px solid var(--border-subtle)", background: "transparent", cursor: "pointer", color: "var(--text-secondary)", fontFamily: "var(--font-sans)", fontSize: "var(--control-text)", letterSpacing: "var(--control-tracking)", textAlign: "left" }} onMouseEnter={(e) => e.currentTarget.style.background = "var(--bg-inset)"} onMouseLeave={(e) => e.currentTarget.style.background = "transparent"}><Icon name="plus" size={13} />New</button>
+          <span style={{ ...cellBase, ...stickyLeft, borderBottom: "none" }}></span>
           {fields.map(f => <span key={"g" + f.key} style={{ ...cellBase, borderBottom: "none", background: "var(--bg-inset)", justifyContent: "flex-end", fontFamily: "var(--font-sans)", fontVariantNumeric: "tabular-nums", fontSize: "var(--text-xs)", letterSpacing: 0, color: "var(--text-secondary)" }}>{agg(f)}</span>)}
           <span style={{ ...cellBase, borderBottom: "none", background: "var(--bg-inset)" }}></span>
         </div>

package/components/data/SmartTable.vue

@@ -5,17 +5,29 @@ import IconButton from '../buttons/IconButton.vue'
 import Checkbox from '../forms/Checkbox.vue'
 import Avatar from '../display/Avatar.vue'
 import SearchInput from '../forms/SearchInput.vue'
+import Menu from '../feedback/Menu.vue'
 // Notion/Airtable-style database grid: field-type header icons, hue pills, person/date/checkbox/url/progress cells, row hover + expand, inline editing, + New row, footer aggregates, view toolbar.
 const typeIcon = { text: 'type', longText: 'align-left', number: 'hash', select: 'chevron-down', multiSelect: 'tag', date: 'calendar', person: 'user', checkbox: 'check-square', url: 'link', progress: 'bar-chart-2' }
-const props = defineProps({ fields: { type: Array, default: () => [] }, rows: { type: Array, default: () => [] }, title: { type: String, default: 'Grid view' }, toolbar: { type: Boolean, default: true }, height: [Number, String], rowHeight: [Number, String], size: { type: String, default: 'sm' }, style: Object })
+const props = defineProps({ fields: { type: Array, default: () => [] }, rows: { type: Array, default: () => [] }, title: { type: String, default: 'Grid view' }, toolbar: { type: Boolean, default: true }, height: [Number, String], rowHeight: [Number, String], density: String, defaultDensity: { type: String, default: 'default' }, size: { type: String, default: 'sm' }, style: Object })
 // A size region that defaults to sm: a database grid is a dense surface, so rows are the sm bar height (36), cells and toolbar read the sm control text (12px, 13px in CJK) and the toolbar's buttons are 28px. Pass size="md" for a roomier grid.
-const rowH = computed(() => props.rowHeight == null ? 'var(--bar-h)' : (typeof props.rowHeight === 'number' ? props.rowHeight + 'px' : props.rowHeight))
+// density: 'default' rows are --bar-h (36 / 40 / 48) with --cell-px; 'compact' rows are --control-h (28 / 32 / 40, the Spreadsheet's cell height) with the Spreadsheet's 8px padding (so at sm only the height changes). Header and footer follow. The toolbar's "Row height" menu switches it (emits density-change; v-model:density to control); rowHeight (a raw height) overrides density.
+// Frozen edges (like Spreadsheet): the field header row is sticky to the top and the 40px row-number column to the left; the corner cell is sticky on both axes. Sticky cells keep the --bg-inset fill so body cells never show through, and the frozen edge is a --border-subtle hairline.
+const DENSITY = { default: { h: 'var(--bar-h)', px: 'var(--cell-px)' }, compact: { h: 'var(--control-h)', px: '8px' } }
 const tierIcon = { width: 'var(--control-icon)', height: 'var(--control-icon)' }
-const emit = defineEmits(['change'])
+// Frozen edges — zIndex 1 (row-number column) < 2 (header row) < 3 (corner, both axes); the editing input sits inside a body cell, under them.
+const stickyTop = { position: 'sticky', top: 0, zIndex: 2, background: 'var(--bg-inset)' }
+const stickyLeft = { position: 'sticky', left: 0, zIndex: 1, background: 'var(--bg-inset)' }
+const stickyCorner = { ...stickyTop, left: 0, zIndex: 3 }
+const emit = defineEmits(['change', 'update:density', 'densityChange'])
+const densityState = ref(props.defaultDensity)
+const density = computed(() => DENSITY[props.density || densityState.value] ? (props.density || densityState.value) : 'default')
+function setDensity(d) { if (!props.density) densityState.value = d; emit('update:density', d); emit('densityChange', d) }
+const rowH = computed(() => props.rowHeight != null ? (typeof props.rowHeight === 'number' ? props.rowHeight + 'px' : props.rowHeight) : DENSITY[density.value].h)
+const cellPx = computed(() => DENSITY[density.value].px)
 const data = ref(props.rows.map(r => ({ ...r })))
 const hover = ref(-1), editing = ref(null), draft = ref('')
 const gridCols = computed(() => ['40px', ...props.fields.map(f => (f.width || 140) + 'px'), '40px'].join(' '))
-const cellBase = { display: 'flex', alignItems: 'center', gap: '5px', padding: '0 var(--cell-px)', borderRight: '1px solid var(--border-subtle)', borderBottom: '1px solid var(--border-subtle)', boxSizing: 'border-box', overflow: 'hidden', whiteSpace: 'nowrap', fontFamily: 'var(--font-sans)', fontSize: 'var(--control-text)', lineHeight: 'var(--control-leading)', letterSpacing: 'var(--control-tracking)', color: 'var(--text-primary)' }
+const cellBase = computed(() => ({ display: 'flex', alignItems: 'center', gap: '5px', padding: '0 ' + cellPx.value, borderRight: '1px solid var(--border-subtle)', borderBottom: '1px solid var(--border-subtle)', boxSizing: 'border-box', overflow: 'hidden', whiteSpace: 'nowrap', fontFamily: 'var(--font-sans)', fontSize: 'var(--control-text)', lineHeight: 'var(--control-leading)', letterSpacing: 'var(--control-tracking)', color: 'var(--text-primary)' }))
 function setCell(r, key, v) { data.value[r][key] = v; emit('change', data.value) }
 function commitEdit(r, f) { setCell(r, f.key, f.type === 'number' && draft.value !== '' && !isNaN(Number(draft.value)) ? Number(draft.value) : draft.value); editing.value = null }
 function startEdit(r, f, row) { if (['text', 'number', 'date', 'url'].includes(f.type || 'text')) { editing.value = { r, key: f.key }; draft.value = String(row[f.key] == null ? '' : row[f.key]) } }
@@ -35,16 +47,17 @@ function agg(f) {
       <button type="button" data-wash="strong" style="display:inline-flex;align-items:center;gap:6px;height:var(--control-h);padding:0 var(--control-px);border:none;border-radius:var(--radius-md);background:var(--wash, var(--bg-active));transition:var(--t-hover);cursor:pointer;color:var(--text-heading);font-family:var(--font-sans);font-weight:var(--weight-medium);font-size:var(--control-text);letter-spacing:var(--control-tracking)"><Icon name="layout-grid" :size="14" :style="tierIcon" />{{ title }}<Icon name="chevron-down" :size="14" :style="tierIcon" /></button>
       <span style="width:1px;height:16px;background:var(--border-control);margin:0 4px" />
       <button v-for="b in [['eye-off','Hide fields'],['funnel','Filter'],['layers','Group'],['arrow-down','Sort']]" :key="b[1]" type="button" class="kb-st-btn"><Icon :name="b[0]" :size="14" :style="tierIcon" />{{ b[1] }}</button>
+      <Menu :items="[{ label: 'Compact', selected: density === 'compact' }, { label: 'Default', selected: density === 'default' }]" @select="l => setDensity(l === 'Compact' ? 'compact' : 'default')"><template #trigger><button type="button" class="kb-st-btn"><Icon name="menu" :size="14" :style="tierIcon" />Row height</button></template></Menu>
       <span style="flex:1" />
       <SearchInput bare placeholder="Search..." style="width:140px;gap:6px" />
     </div>
     <div :style="{ overflow: 'auto', maxHeight: typeof height === 'number' ? height + 'px' : height }">
       <div :style="{ display: 'grid', gridTemplateColumns: gridCols, width: 'fit-content', minWidth: '100%' }">
-        <span :style="{ ...cellBase, height: rowH, background: 'var(--bg-inset)' }" />
-        <span v-for="f in fields" :key="f.key" :style="{ ...cellBase, height: rowH, background: 'var(--bg-inset)', color: 'var(--text-secondary)', fontWeight: 'var(--weight-semibold)' }"><Icon :name="typeIcon[f.type] || 'type'" :size="14" :style="{ ...tierIcon, color: 'var(--text-muted)' }" />{{ f.label }}</span>
-        <span :style="{ ...cellBase, height: rowH, background: 'var(--bg-inset)', justifyContent: 'center', padding: 0 }"><IconButton icon="plus" muted label="Add field" /></span>
+        <span :style="{ ...cellBase, height: rowH, ...stickyCorner }" />
+        <span v-for="f in fields" :key="f.key" :style="{ ...cellBase, height: rowH, ...stickyTop, color: 'var(--text-secondary)', fontWeight: 'var(--weight-semibold)' }"><Icon :name="typeIcon[f.type] || 'type'" :size="14" :style="{ ...tierIcon, color: 'var(--text-muted)' }" />{{ f.label }}</span>
+        <span :style="{ ...cellBase, height: rowH, ...stickyTop, justifyContent: 'center', padding: 0 }"><IconButton icon="plus" muted label="Add field" /></span>
         <template v-for="(row, r) in data" :key="r">
-          <span @mouseenter="hover = r" @mouseleave="hover = -1" :style="{ ...cellBase, height: rowH, justifyContent: 'center', color: 'var(--text-muted)', fontFamily: 'var(--font-sans)', fontVariantNumeric: 'tabular-nums', fontSize: 'var(--text-xs)', letterSpacing: 0, background: hover === r ? 'var(--bg-inset)' : 'transparent', cursor: 'pointer' }">
+          <span @mouseenter="hover = r" @mouseleave="hover = -1" :style="{ ...cellBase, height: rowH, ...stickyLeft, justifyContent: 'center', color: 'var(--text-muted)', fontFamily: 'var(--font-sans)', fontVariantNumeric: 'tabular-nums', fontSize: 'var(--text-xs)', letterSpacing: 0, cursor: 'pointer' }">
             <Icon v-if="hover === r" name="maximize-2" :size="14" :style="{ ...tierIcon, color: 'var(--action-primary)' }" /><template v-else>{{ r + 1 }}</template>
           </span>
           <span v-for="f in fields" :key="r + f.key" @mouseenter="hover = r" @mouseleave="hover = -1" @dblclick="startEdit(r, f, row)" :style="{ ...cellBase, height: rowH, position: 'relative', background: hover === r ? 'var(--bg-inset)' : 'transparent' }">
@@ -61,7 +74,7 @@ function agg(f) {
           <span :style="{ ...cellBase, height: rowH, background: hover === r ? 'var(--bg-inset)' : 'transparent' }" />
         </template>
         <button type="button" @click="addRow" class="kb-st-new" :style="{ gridColumn: '1 / -1', height: rowH }"><Icon name="plus" :size="14" :style="tierIcon" />New</button>
-        <span :style="{ ...cellBase, height: rowH, borderBottom: 'none', background: 'var(--bg-inset)' }" />
+        <span :style="{ ...cellBase, height: rowH, ...stickyLeft, borderBottom: 'none' }" />
         <span v-for="f in fields" :key="'g' + f.key" :style="{ ...cellBase, height: rowH, borderBottom: 'none', background: 'var(--bg-inset)', justifyContent: 'flex-end', fontFamily: 'var(--font-sans)', fontVariantNumeric: 'tabular-nums', fontSize: 'var(--text-xs)', letterSpacing: 0, color: 'var(--text-secondary)' }">{{ agg(f) }}</span>
         <span :style="{ ...cellBase, height: rowH, borderBottom: 'none', background: 'var(--bg-inset)' }" />
       </div>

package/components/forms/RelativeTimePicker.d.ts

@@ -0,0 +1,39 @@
+import * as React from 'react';
+
+export type RelativeTimeUnit = 'None' | 'Minute' | 'Hour' | 'Day' | 'Week' | 'Month';
+export interface RelativeTimeValue { amount: number; unit: RelativeTimeUnit }
+/** A unit label is one string (CJK: "小时前") or { one, other } for languages that inflect ("hour ago" / "hours ago"); picked with Intl.PluralRules of `locale`. */
+export type RelativeTimeUnitLabel = string | { one: string; other: string };
+export interface RelativeTimeLabels {
+  title: string;
+  amount: string;
+  unit: string;
+  preview: string;
+  unlimited: string;
+  Minute: RelativeTimeUnitLabel;
+  Hour: RelativeTimeUnitLabel;
+  Day: RelativeTimeUnitLabel;
+  Week: RelativeTimeUnitLabel;
+  Month: RelativeTimeUnitLabel;
+}
+/** Relative-time filter: a field-shaped trigger (tier height) opening a small non-modal dialog — amount input, unit select, live "From" preview. Vue: v-model + @change(value, date). */
+export interface RelativeTimePickerProps {
+  /** { amount, unit }; unlimited is { amount: 0, unit: "None" } */
+  value?: RelativeTimeValue;
+  /** Hides the unlimited option; zero still resolves to unlimited for legacy filters. */
+  allowUnlimited?: boolean;
+  disabled?: boolean;
+  /** Size tier of the trigger and its dialog; omit to inherit the region's tier. */
+  size?: 'sm' | 'md' | 'lg';
+  labels?: Partial<RelativeTimeLabels>;
+  /** Date formatting and plural rules ("1 hour ago" vs "2 hours ago"). */
+  locale?: string;
+  /** Defaults to the current time, refreshed when opened or edited. */
+  referenceDate?: Date;
+  formatDate?: (date: Date) => string;
+  formatValue?: (value: RelativeTimeValue) => string;
+  /** No mount emission. Unlimited is null. Vue: v-model + @change(value, date). */
+  onChange?: (value: RelativeTimeValue, date: Date | null) => void;
+  style?: React.CSSProperties;
+}
+export declare function RelativeTimePicker(props: RelativeTimePickerProps): React.JSX.Element;

package/components/forms/RelativeTimePicker.jsx

@@ -0,0 +1,89 @@
+import React from "react";
+import { createPortal } from "react-dom";
+import { Icon } from "../icons/Icon.jsx";
+import { Input } from "./Input.jsx";
+import { Select } from "./Select.jsx";
+import { Field } from "./Field.jsx";
+import { RELATIVE_TIME_LABELS, RELATIVE_TIME_UNITS, changeRelativeAmount, changeRelativeUnit, normalizeRelativeTime, relativeTimePosition, relativeTimeText, relativeUnitLabel, resolveRelativeTime } from "./relative-time.js";
+
+/** Relative-time filter ("1 hour ago", "any time") for log, monitoring and inbox pages: a field-shaped trigger that opens a small non-modal dialog
+ *  with an amount input and a unit select, plus a live "From" preview. Controlled: value = { amount, unit }; onChange(value, date) — unlimited resolves to null.
+ *  Tier: the trigger is a field (sm 28 · md 32 · lg 40 — omit `size` to inherit the region's tier); the dialog is portalled to <body> and copies the trigger's
+ *  tier, language and theme so it keeps the region's density. Styling is inline from tokens like every other control; hover comes from data-field.
+ *  The amount is a plain numeric text field (no native spinners); unit labels may be { one, other } and follow Intl.PluralRules of `locale`. */
+const glyph = { width: "var(--control-icon)", height: "var(--control-icon)", color: "var(--text-secondary)", flexShrink: 0 };
+export function RelativeTimePicker({ value = { amount: 1, unit: "Hour" }, onChange, allowUnlimited = true, disabled, size, labels, locale, referenceDate, formatDate, formatValue, style }) {
+  const [open, setOpen] = React.useState(false);
+  const [now, setNow] = React.useState(() => new Date());
+  const [position, setPosition] = React.useState({});
+  const trigger = React.useRef(null);
+  const panel = React.useRef(null);
+  const current = normalizeRelativeTime(value);
+  const text = { ...RELATIVE_TIME_LABELS, ...labels };
+  const units = allowUnlimited ? ["None", ...RELATIVE_TIME_UNITS] : RELATIVE_TIME_UNITS;
+  const unitLabel = (unit) => unit === "None" ? text.unlimited : relativeUnitLabel(text, unit, undefined, locale);
+  const options = units.map(unitLabel);
+  const summary = relativeTimeText(current, text, formatValue, locale);
+  const date = resolveRelativeTime(current, referenceDate || now);
+  const preview = !date ? text.unlimited : formatDate ? formatDate(date) : new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeStyle: "medium" }).format(date);
+
+  function close(restoreFocus = false) { setOpen(false); if (restoreFocus) trigger.current?.focus(); }
+  function update(next) {
+    const reference = referenceDate || new Date();
+    if (next.unit !== "None" && !resolveRelativeTime(next, reference)) return;
+    setNow(reference);
+    onChange?.(next, resolveRelativeTime(next, reference));
+  }
+  React.useEffect(() => { if (disabled) setOpen(false); }, [disabled]);
+  React.useEffect(() => {
+    if (!open) return;
+    const place = () => setPosition(relativeTimePosition(trigger.current, panel.current));
+    const contains = (t) => trigger.current?.contains(t) || panel.current?.contains(t);
+    const outside = (e) => { if (!contains(e.target)) close(); };
+    const keydown = (e) => { if (e.key === "Escape") { e.preventDefault(); close(true); } };
+    place();
+    panel.current?.querySelector("input")?.focus();
+    document.addEventListener("pointerdown", outside, true);
+    document.addEventListener("focusin", outside);
+    document.addEventListener("keydown", keydown);
+    window.addEventListener("resize", place);
+    window.addEventListener("scroll", place, true);
+    return () => {
+      document.removeEventListener("pointerdown", outside, true);
+      document.removeEventListener("focusin", outside);
+      document.removeEventListener("keydown", keydown);
+      window.removeEventListener("resize", place);
+      window.removeEventListener("scroll", place, true);
+    };
+  }, [open]);
+
+  const themeRoot = trigger.current?.closest("[data-theme]");
+  return (
+    <div data-size={size} style={{ display: "inline-flex", width: "100%", minWidth: 0, ...style }}>
+      <button ref={trigger} type="button" data-field={disabled ? undefined : ""} disabled={disabled} aria-haspopup="dialog" aria-expanded={open} aria-label={`${text.title}: ${summary}`}
+        onClick={() => { if (open) return close(); setNow(new Date()); setPosition(relativeTimePosition(trigger.current)); setOpen(true); }}
+        style={{ display: "flex", alignItems: "center", gap: "var(--control-gap)", height: "var(--control-h)", width: "100%", padding: "0 var(--control-px)", borderRadius: "var(--radius-md)",
+          border: `1px solid ${open ? "var(--focus-border)" : "var(--field-border, var(--border-control))"}`, background: disabled ? "var(--bg-inset)" : "var(--bg-surface)", color: "var(--text-primary)",
+          fontFamily: "var(--font-sans)", fontSize: "var(--control-text)", lineHeight: "var(--control-leading)", letterSpacing: "var(--control-tracking)", textAlign: "start",
+          cursor: disabled ? "not-allowed" : "pointer", opacity: disabled ? .5 : 1, transition: "var(--t-hover)", boxSizing: "border-box", outline: "none" }}>
+        <Icon name="clock" size={16} style={glyph} />
+        <span style={{ flex: 1, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>{summary}</span>
+        <Icon name="chevron-down" size={16} style={{ ...glyph, color: "var(--text-muted)" }} />
+      </button>
+      {open && createPortal(
+        <div ref={panel} role="dialog" aria-label={text.title} lang={trigger.current?.closest("[lang]")?.lang} data-theme={themeRoot && themeRoot !== document.documentElement ? themeRoot.dataset.theme : undefined}
+          style={{ position: "fixed", zIndex: "var(--z-menu)", maxHeight: "calc(100vh - 16px)", overflowY: "auto", padding: "var(--edge-pad)", border: "1px solid var(--border-card)", borderRadius: "var(--radius-lg)",
+            background: "var(--bg-raised)", boxShadow: "var(--shadow-menu)", color: "var(--text-body)", fontFamily: "var(--font-sans)", fontSize: "var(--control-text)", lineHeight: "var(--control-leading)", letterSpacing: "var(--control-tracking)", boxSizing: "border-box", ...position }}>
+          <h3 style={{ margin: "0 0 var(--control-gap)", color: "var(--text-heading)", fontSize: "var(--control-text)", lineHeight: "var(--control-leading)", fontWeight: "var(--weight-medium)" }}>{text.title}</h3>
+          <div style={{ display: "grid", gridTemplateColumns: "minmax(0, 1fr) minmax(0, 1.4fr)", gap: "var(--group-gap)" }}>
+            <Field label={text.amount}><Input inputMode="numeric" pattern="[0-9]*" value={current.amount} onChange={(e) => { const v = e.target.value.replace(/\D/g, ""); if (v !== "" || e.target.value === "") update(changeRelativeAmount(current, v)); }} aria-label={text.amount} /></Field>
+            <Field label={text.unit}><Select options={options} value={unitLabel(current.unit)} onChange={(e) => { const i = options.indexOf(e.target.value); if (i >= 0) update(changeRelativeUnit(current, units[i])); }} /></Field>
+          </div>
+          <div style={{ display: "flex", flexWrap: "wrap", justifyContent: "space-between", gap: "var(--control-gap)", marginTop: "var(--group-gap)", paddingTop: "var(--control-gap)", borderTop: "1px solid var(--border-subtle)", color: "var(--text-secondary)" }}>
+            <span>{text.preview}</span>
+            <span style={{ color: "var(--text-body)", fontVariantNumeric: "tabular-nums", overflowWrap: "anywhere" }}>{preview}</span>
+          </div>
+        </div>, document.body)}
+    </div>
+  );
+}

package/components/forms/RelativeTimePicker.prompt.md

@@ -0,0 +1,72 @@
+# RelativeTimePicker 相对时间筛选器
+
+适用于日志、监控、站内信等按“过去多久”筛选的数据页面。它不是具体日期选择器，也不负责查询或保存业务数据。
+
+## 数据契约
+
+- 值为 `{ amount: number, unit: 'None' | 'Minute' | 'Hour' | 'Day' | 'Week' | 'Month' }`。
+- 数值为非负整数；0、空值、非法数值归一为 `{ amount: 0, unit: 'None' }`。
+- 从不限时间输入正数时恢复为小时；从不限切换为具体单位时，数值恢复为 1。
+- `allowUnlimited=false` 仅隐藏“不限时间”选项；为兼容原筛选器，输入 0 仍表示不限时间。
+- 分钟、小时按经过的毫秒计算；天、周按本地日历计算；月按日历月计算并夹到目标月的最后一天。
+- 无时区转换；按浏览器所在时区计算。`referenceDate` 可提供固定的计算基准，默认在打开或编辑时取当前时间。
+- `resolveRelativeTime(value, referenceDate?)` 返回 `Date | null`，不修改传入的 Date；不限返回 null。业务系统需要 `Date(0)` 等哨兵值时，在业务适配层转换。
+- 组件挂载不发出变更事件；只在编辑时输出新值和计算日期。父组件更新值时，界面同步回显。
+
+## Vue 3
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import RelativeTimePicker from '@keyfunc/keybricks-ds/components/forms/RelativeTimePicker.vue';
+import '@keyfunc/keybricks-ds/styles.css';
+
+const range = ref({ amount: 1, unit: 'Hour' });
+const labels = {
+    title: '相对时间', amount: '数量', unit: '单位', preview: '起始时间', unlimited: '不限时间',
+    Minute: '分钟前', Hour: '小时前', Day: '天前', Week: '周前', Month: '个月前',
+};
+
+function onChange(value, date) {
+    // 在此处更新业务筛选条件；date 为 null 表示不限时间。
+}
+</script>
+
+<template>
+    <div data-size="md">
+        <RelativeTimePicker v-model="range" :labels="labels" locale="zh-CN" @change="onChange" />
+    </div>
+</template>
+```
+
+Vue 事件为 `update:modelValue(value)` 与 `change(value, date)`。`disabled` 禁止打开并关闭已有弹层。
+
+## React
+
+```jsx
+import React from 'react';
+import { RelativeTimePicker } from '@keyfunc/keybricks-ds';
+import '@keyfunc/keybricks-ds/styles.css';
+
+export function LogFilter() {
+    const [range, setRange] = React.useState({ amount: 1, unit: 'Hour' });
+    return <RelativeTimePicker value={range} onChange={(value, date) => setRange(value)} />;
+}
+```
+
+## 外观与可访问性
+
+优先在工具栏或表单区域统一设置 `data-size`，单个控件独立使用时可传 `size`。
+尺寸、字体、边框、状态色和浮层阴影均读取语义 Token，样式与其他控件一样内联（2.4.1 起不再有独立的 relative-time.css）。弹层复制触发区域的字体、尺寸、语言及主题，避免挂到 body 后丢失区域密度。悬停与其他输入框一致，来自 `data-field`；字段标签使用 `Field`。
+
+触发器是原生 button，支持键盘打开；打开后焦点进入数值输入框。Esc 关闭并将焦点送回触发器；点击外部或 Tab 离开关闭弹层。输入框和单位选择器具有可见标签，弹层使用非模态 dialog 语义。
+
+所有文案可通过 `labels` 局部覆盖，单位文案应彼此不同。单位文案可以是一个字符串（中文"小时前"，不分单复数），也可以是 `{ one, other }`（英文 "hour ago" / "hours ago"），组件按 `locale` 的复数规则选择；单位下拉框显示 `other` 形式。数量输入是纯数字文本框（`inputmode="numeric"`，无原生上下箭头），非数字字符会被去掉。`formatValue(value)` 可自定义触发器摘要，便于复数或不同语序；`formatDate(date)` 可覆盖默认 Intl 日期格式。组件不依赖业务 i18n、Element Plus、Vuex 或 date-fns。
+
+## 本次迁移及验证边界
+
+前端 `foundation/timeSelect.vue` 暂时通过同级 UI 仓库源码引用本组件。发布包后，将该文件中的组件、计算函数及类型导入改为对应的 `@keyfunc/keybricks-ds/components/forms/` 路径即可。
+
+业务层保留 `initNum`、`initUnit`、`disableUnLimited`、`fromDate` 参数，`onDateChange`、`update:fromDate` 事件，挂载立即通知、`Date(0)` 不限时间语义，以及监控页面读取的 `ref.num` / `ref.timeUnit`。
+
+按本次任务约定未执行测试、类型检查或构建，功能及浏览器效果仍需人工验证。重点检查：不限与具体单位切换、月末及跨夏令时日期、父组件回显、sm/md/lg 密度、区域语言及深浅主题、滚动和窗口边缘定位、键盘退出及业务旧事件。

package/components/forms/RelativeTimePicker.vue

@@ -0,0 +1,81 @@
+<script setup>
+import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue'
+import Icon from '../icons/Icon.vue'
+import Input from './Input.vue'
+import Select from './Select.vue'
+import Field from './Field.vue'
+import { RELATIVE_TIME_LABELS, RELATIVE_TIME_UNITS, changeRelativeAmount, changeRelativeUnit, normalizeRelativeTime, relativeTimePosition, relativeTimeText, relativeUnitLabel, resolveRelativeTime } from './relative-time.js'
+// Relative-time filter ("1 hour ago", "any time") for log, monitoring and inbox pages: a field-shaped trigger that opens a small non-modal dialog
+// with an amount input and a unit select, plus a live "From" preview. v-model = { amount, unit }; @change(value, date) — unlimited resolves to null.
+// Tier: the trigger is a field (sm 28 · md 32 · lg 40 — omit `size` to inherit the region's tier); the dialog teleports to <body> and copies the trigger's
+// tier, language and theme so it keeps the region's density. Styling is inline from tokens like every other control; hover comes from data-field.
+// The amount is a plain numeric text field (no native spinners); unit labels may be { one, other } and follow Intl.PluralRules of `locale`.
+const props = defineProps({ modelValue: { type: Object, default: () => ({ amount: 1, unit: 'Hour' }) }, allowUnlimited: { type: Boolean, default: true }, disabled: Boolean, size: String, labels: Object, locale: String, referenceDate: Date, formatDate: Function, formatValue: Function, style: Object })
+const emit = defineEmits(['update:modelValue', 'change'])
+const trigger = ref(null), panel = ref(null), open = ref(false), position = ref({}), now = ref(new Date()), lang = ref(undefined), theme = ref(undefined)
+const value = computed(() => normalizeRelativeTime(props.modelValue))
+const text = computed(() => ({ ...RELATIVE_TIME_LABELS, ...props.labels }))
+const units = computed(() => props.allowUnlimited ? ['None', ...RELATIVE_TIME_UNITS] : RELATIVE_TIME_UNITS)
+const unitLabel = (unit) => unit === 'None' ? text.value.unlimited : relativeUnitLabel(text.value, unit, undefined, props.locale)
+const options = computed(() => units.value.map(unitLabel))
+const summary = computed(() => relativeTimeText(value.value, text.value, props.formatValue, props.locale))
+const date = computed(() => resolveRelativeTime(value.value, props.referenceDate || now.value))
+const preview = computed(() => !date.value ? text.value.unlimited : props.formatDate ? props.formatDate(date.value) : new Intl.DateTimeFormat(props.locale, { dateStyle: 'medium', timeStyle: 'medium' }).format(date.value))
+const glyph = { width: 'var(--control-icon)', height: 'var(--control-icon)', color: 'var(--text-secondary)', flexShrink: 0 }
+const triggerStyle = computed(() => ({ display: 'flex', alignItems: 'center', gap: 'var(--control-gap)', height: 'var(--control-h)', width: '100%', padding: '0 var(--control-px)', borderRadius: 'var(--radius-md)',
+  border: `1px solid ${open.value ? 'var(--focus-border)' : 'var(--field-border, var(--border-control))'}`, background: props.disabled ? 'var(--bg-inset)' : 'var(--bg-surface)', color: 'var(--text-primary)',
+  fontFamily: 'var(--font-sans)', fontSize: 'var(--control-text)', lineHeight: 'var(--control-leading)', letterSpacing: 'var(--control-tracking)', textAlign: 'start',
+  cursor: props.disabled ? 'not-allowed' : 'pointer', opacity: props.disabled ? .5 : 1, transition: 'var(--t-hover)', boxSizing: 'border-box', outline: 'none' }))
+const panelStyle = computed(() => ({ position: 'fixed', zIndex: 'var(--z-menu)', maxHeight: 'calc(100vh - 16px)', overflowY: 'auto', padding: 'var(--edge-pad)', border: '1px solid var(--border-card)', borderRadius: 'var(--radius-lg)',
+  background: 'var(--bg-raised)', boxShadow: 'var(--shadow-menu)', color: 'var(--text-body)', fontFamily: 'var(--font-sans)', fontSize: 'var(--control-text)', lineHeight: 'var(--control-leading)', letterSpacing: 'var(--control-tracking)', boxSizing: 'border-box', ...position.value }))
+function update(next) {
+  now.value = new Date()
+  if (next.unit !== 'None' && !resolveRelativeTime(next, props.referenceDate || now.value)) return
+  emit('update:modelValue', next); emit('change', next, resolveRelativeTime(next, props.referenceDate || now.value))
+}
+function updateAmount(raw) { const digits = String(raw).replace(/\D/g, ''); if (digits !== '' || raw === '') update(changeRelativeAmount(value.value, digits)) }
+function updateUnit(label) { const i = options.value.indexOf(label); if (i >= 0) update(changeRelativeUnit(value.value, units.value[i])) }
+function place() { if (trigger.value) position.value = relativeTimePosition(trigger.value, panel.value) }
+function close(restoreFocus = false) { open.value = false; if (restoreFocus) trigger.value?.focus() }
+async function toggle() {
+  if (props.disabled) return
+  if (open.value) return close()
+  now.value = new Date()
+  lang.value = trigger.value.closest('[lang]')?.lang
+  const themeRoot = trigger.value.closest('[data-theme]'); theme.value = themeRoot === document.documentElement ? undefined : themeRoot?.dataset.theme
+  place(); open.value = true
+  await nextTick(); place(); panel.value?.querySelector('input')?.focus()
+}
+function outside(e) { if (!trigger.value?.contains(e.target) && !panel.value?.contains(e.target)) close() }
+function keydown(e) { if (e.key === 'Escape') { e.preventDefault(); close(true) } }
+function focusout() { nextTick(() => { if (!trigger.value?.contains(document.activeElement) && !panel.value?.contains(document.activeElement)) close() }) }
+function listen(add) {
+  const m = add ? 'addEventListener' : 'removeEventListener'
+  document[m]('pointerdown', outside, true); document[m]('keydown', keydown); document[m]('focusin', focusout); window[m]('resize', place); window[m]('scroll', place, true)
+}
+watch(open, listen)
+watch(() => props.disabled, (d) => { if (d) close() })
+onBeforeUnmount(() => listen(false))
+</script>
+<template>
+  <div :data-size="size" :style="{ display: 'inline-flex', width: '100%', minWidth: 0, ...style }">
+    <button ref="trigger" type="button" :data-field="disabled ? undefined : ''" :disabled="disabled" aria-haspopup="dialog" :aria-expanded="open" :aria-label="`${text.title}: ${summary}`" :style="triggerStyle" @click="toggle">
+      <Icon name="clock" :size="16" :style="glyph" />
+      <span style="flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap">{{ summary }}</span>
+      <Icon name="chevron-down" :size="16" :style="{ ...glyph, color: 'var(--text-muted)' }" />
+    </button>
+    <Teleport to="body">
+      <div v-if="open" ref="panel" role="dialog" :aria-label="text.title" :lang="lang" :data-theme="theme" :style="panelStyle">
+        <h3 style="margin:0 0 var(--control-gap);color:var(--text-heading);font-size:var(--control-text);line-height:var(--control-leading);font-weight:var(--weight-medium)">{{ text.title }}</h3>
+        <div style="display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1.4fr);gap:var(--group-gap)">
+          <Field :label="text.amount"><Input inputmode="numeric" pattern="[0-9]*" :model-value="String(value.amount)" :aria-label="text.amount" @update:model-value="updateAmount" /></Field>
+          <Field :label="text.unit"><Select :options="options" :model-value="unitLabel(value.unit)" @update:model-value="updateUnit" /></Field>
+        </div>
+        <div style="display:flex;flex-wrap:wrap;justify-content:space-between;gap:var(--control-gap);margin-top:var(--group-gap);padding-top:var(--control-gap);border-top:1px solid var(--border-subtle);color:var(--text-secondary)">
+          <span>{{ text.preview }}</span>
+          <span style="color:var(--text-body);font-variant-numeric:tabular-nums;overflow-wrap:anywhere">{{ preview }}</span>
+        </div>
+      </div>
+    </Teleport>
+  </div>
+</template>

package/components/forms/forms.prompt.md

@@ -24,3 +24,6 @@ Everything is 12px text in 36px controls; readOnly inputs go #fafafa; disabled =
 <RadioGroup options={["New","Overwrite","Skip"]} value={v} onChange={setV}/>
 <RadioGroup variant="cards" row value={m} onChange={setM} options={[{label:"Merge",value:"merge",description:"Keep target values, add new keys"},{label:"Overwrite",value:"overwrite",description:"Target takes source values"}]}/>
 ```
+
+## RelativeTimePicker
+Filter by "how long ago" (logs, monitoring, inbox): `<RelativeTimePicker value={{amount:1,unit:"Hour"}} onChange={(v, date) => …}/>` — a field-shaped trigger at the tier height; the dialog has an amount input and a unit select (`allowUnlimited` adds "Any time", which resolves to `null`). `labels` localises every string (unit labels: one string, or `{ one, other }` for plural languages); `formatValue` / `formatDate` override the summary and the preview. Vue: `v-model` + `@change(value, date)`.

package/components/forms/relative-time.d.ts

@@ -0,0 +1,12 @@
+import type { RelativeTimeLabels, RelativeTimeUnit, RelativeTimeValue } from './RelativeTimePicker';
+
+export declare const RELATIVE_TIME_UNITS: Exclude<RelativeTimeUnit, 'None'>[];
+export declare const RELATIVE_TIME_LABELS: RelativeTimeLabels;
+export declare function normalizeRelativeTime(value?: { amount?: unknown; unit?: unknown }): RelativeTimeValue;
+export declare function changeRelativeAmount(value: RelativeTimeValue, amount: number | string): RelativeTimeValue;
+export declare function changeRelativeUnit(value: RelativeTimeValue, unit: RelativeTimeUnit): RelativeTimeValue;
+export declare function resolveRelativeTime(value: RelativeTimeValue, referenceDate?: Date): Date | null;
+export declare function relativeTimeText(value: RelativeTimeValue, labels: RelativeTimeLabels, formatValue?: (value: RelativeTimeValue) => string, locale?: string): string;
+/** Unit label for an amount (Intl.PluralRules of locale); without amount, the generic form for the unit select. */
+export declare function relativeUnitLabel(labels: RelativeTimeLabels, unit: RelativeTimeUnit, amount?: number, locale?: string): string;
+export declare function relativeTimePosition(trigger: HTMLElement, panel?: HTMLElement | null): Record<string, string>;

package/components/forms/relative-time.js

@@ -0,0 +1,90 @@
+// Framework-neutral relative-time values. No application store, translations or date library.
+export const RELATIVE_TIME_UNITS = ['Minute', 'Hour', 'Day', 'Week', 'Month'];
+// A unit label is a string ("小时前" — the same for every amount) or { one, other } for languages that inflect ("1 hour ago" / "2 hours ago").
+export const RELATIVE_TIME_LABELS = {
+  title: 'Relative time', amount: 'Amount', unit: 'Unit', preview: 'From', unlimited: 'Any time',
+  Minute: { one: 'minute ago', other: 'minutes ago' }, Hour: { one: 'hour ago', other: 'hours ago' },
+  Day: { one: 'day ago', other: 'days ago' }, Week: { one: 'week ago', other: 'weeks ago' }, Month: { one: 'month ago', other: 'months ago' },
+};
+
+/** The label of a unit for a given amount (plural rules of `locale`); omit amount for the generic form shown in the unit select. */
+export function relativeUnitLabel(labels, unit, amount, locale) {
+  const l = labels[unit];
+  if (l == null || typeof l === 'string') return l;
+  if (amount == null) return l.other;
+  let rule = 'other';
+  try { rule = new Intl.PluralRules(locale).select(amount); } catch (e) { rule = amount === 1 ? 'one' : 'other'; }
+  return l[rule] || l.other || l.one;
+}
+
+export function normalizeRelativeTime(value) {
+  const amount = Math.floor(Number(value?.amount));
+  const unit = RELATIVE_TIME_UNITS.includes(value?.unit) ? value.unit : 'None';
+  return Number.isFinite(amount) && amount > 0 && unit !== 'None'
+    ? { amount, unit }
+    : { amount: 0, unit: 'None' };
+}
+
+export function changeRelativeAmount(value, amount) {
+  return normalizeRelativeTime({ amount, unit: value.unit === 'None' ? 'Hour' : value.unit });
+}
+
+export function changeRelativeUnit(value, unit) {
+  return normalizeRelativeTime({ amount: unit === 'None' ? 0 : value.amount || 1, unit });
+}
+
+/** Unlimited is null; consumers decide whether their backend needs an epoch sentinel. */
+export function resolveRelativeTime(value, referenceDate = new Date()) {
+  const { amount, unit } = normalizeRelativeTime(value);
+  if (!amount) return null;
+  const date = new Date(referenceDate);
+  if (!Number.isFinite(date.getTime())) return null;
+  if (unit === 'Minute' || unit === 'Hour') {
+    date.setTime(date.getTime() - amount * (unit === 'Minute' ? 60000 : 3600000));
+  } else if (unit === 'Month') {
+    // Match calendar-month subtraction: March 31 minus one month is February's last day.
+    const day = date.getDate();
+    date.setDate(1);
+    date.setMonth(date.getMonth() - amount);
+    const lastDay = new Date(date.getFullYear(), date.getMonth() + 1, 0).getDate();
+    date.setDate(Math.min(day, lastDay));
+  } else {
+    // Calendar days/weeks preserve local wall time across daylight-saving boundaries.
+    date.setDate(date.getDate() - amount * (unit === 'Week' ? 7 : 1));
+  }
+  return Number.isFinite(date.getTime()) ? date : null;
+}
+
+export function relativeTimeText(value, labels, formatValue, locale) {
+  return formatValue ? formatValue(value) : value.unit === 'None'
+    ? labels.unlimited : `${value.amount} ${relativeUnitLabel(labels, value.unit, value.amount, locale)}`;
+}
+
+/** Fixed, viewport-clamped placement; retain the trigger's inherited density and language. */
+export function relativeTimePosition(trigger, panel) {
+  const rect = trigger.getBoundingClientRect();
+  const computed = getComputedStyle(trigger);
+  // 弹层挂载到 body 后，需要高于触发器所在的抽屉、对话框等层叠上下文。
+  let zIndex = Number.parseFloat(computed.getPropertyValue('--z-menu')) || 0;
+  for (let element = trigger; element; element = element.parentElement) {
+    const ancestorZIndex = Number.parseFloat(getComputedStyle(element).zIndex);
+    if (Number.isFinite(ancestorZIndex)) zIndex = Math.max(zIndex, ancestorZIndex + 1);
+  }
+  const width = Math.min(336, window.innerWidth - 16);
+  const height = panel?.offsetHeight || 200;
+  const below = rect.bottom + 4;
+  const top = below + height <= window.innerHeight - 8
+    ? below : Math.max(8, rect.top - height - 4);
+  const style = {
+    zIndex: String(zIndex),
+    width: `${width}px`,
+    left: `${Math.max(8, Math.min(rect.left, window.innerWidth - width - 8))}px`,
+    top: `${top}px`,
+  };
+  for (const name of computed) {
+    if (/^--(control-|font-|weight-|leading-|tracking-|group-gap|edge-pad)/.test(name)) {
+      style[name] = computed.getPropertyValue(name);
+    }
+  }
+  return style;
+}

package/components/index.d.ts

@@ -65,6 +65,7 @@ export * from "./forms/Input";
 export * from "./forms/MultiSelect";
 export * from "./forms/NumberStepper";
 export * from "./forms/Radio";
+export * from "./forms/RelativeTimePicker";
 export * from "./forms/SearchInput";
 export * from "./forms/Select";
 export * from "./forms/Slider";

package/components/index.js

@@ -80,6 +80,7 @@ export { Input, Textarea } from "./forms/Input.jsx";
 export { MultiSelect } from "./forms/MultiSelect.jsx";
 export { NumberStepper } from "./forms/NumberStepper.jsx";
 export { Radio, RadioGroup } from "./forms/Radio.jsx";
+export { RelativeTimePicker } from "./forms/RelativeTimePicker.jsx";
 export { SearchInput } from "./forms/SearchInput.jsx";
 export { Select } from "./forms/Select.jsx";
 export { Slider } from "./forms/Slider.jsx";

package/components/navigation/Sidebar.d.ts

@@ -25,7 +25,7 @@ export interface SidebarProps {
   onToggleCollapse?: () => void;
   logo?: string;
   brand?: string;
-  /** Version line under the footer items ("Version 2.4.0"); the rail shows "v2.4.0" */
+  /** Version line under the footer items ("Version 2.4.4"); the rail shows "v2.4.4" */
   version?: string;
   tone?: "recessed" | "flush" | "contrast" | "custom";
   /** For tone "custom": a SIDEBAR_COLORS key (slate, navy, indigo, violet, plum, wine, forest, teal, umber, charcoal) or any hex */

package/components/navigation/Tree.d.ts

@@ -67,7 +67,7 @@ export interface TreeProps {
   /** Draw connector lines instead of plain indentation */
   showLine?: boolean;
   draggable?: boolean;
-  /** Also allow insert-between: a folder's outer 20% becomes a before/after rule. Off by default — a drag moves a node INTO a folder, and files are never drop targets. */
+  /** Also allow insert-between: a folder's outer 20% becomes a before/after rule, and a leaf becomes an insert target over its whole height (top half before, bottom half after) — so leaves can be reordered among themselves. Before / after draw an insert marker (2px line + 6px dot) on the gap between rows, starting at the target's indent. Off by default — a drag moves a node INTO a folder, and files are never drop targets. */
   reorder?: boolean;
   /** Highlights matches and auto-expands their ancestors */
   searchValue?: string;