@bagelink/vue 1.15.207 → 1.15.211

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bagelink/vue",
   "type": "module",
-  "version": "1.15.207",
+  "version": "1.15.211",
   "description": "Bagel core sdk packages",
   "author": {
     "name": "Bagel Studio",

package/src/components/charts/MapChart.vue

@@ -5,21 +5,38 @@
  *
  *   <MapChart :data="[{ id: 'US', value: 4200 }, { id: 'IL', label: 'Israel', value: 900 }]" />
  *   <MapChart :data="rows" color="green" :height="280" />
+ *   <MapChart :data="rows" :zoomable="false" />
  */
 import { computed, ref } from 'vue'
 import type { ThemeType } from '../../types'
+import Btn from '../Btn.vue'
 import ChartTooltip from './ChartTooltip.vue'
 import { formatValue, type ValueFormat } from './core/format'
 import { resolveColor } from './core/palette'
 import { useChartAnim } from './core/useChartAnim'
 import { tipFollowStyle, trackLocalPointer } from './core/useChartTip'
-import { WORLD_NAMES, WORLD_PATHS, WORLD_VIEWBOX } from './core/world-paths'
+import { WORLD_NAMES, WORLD_PATHS } from './core/world-paths'
 import type { MapDatum } from './mapTypes'
 
 defineOptions({ name: 'BglMapChart' })
 
 export type { MapDatum }
 
+/**
+ * Crop empty ocean padding from Natural Earth sphere-fit (paths leave ~16%
+ * empty at the bottom and thin side margins inside 960×480).
+ */
+const MAP_VIEW = {
+	x: 16,
+	y: 0,
+	width: 928,
+	height: 412,
+} as const
+
+const MIN_ZOOM = 1
+const MAX_ZOOM = 8
+const ZOOM_STEP = 1.35
+
 const props = withDefaults(defineProps<{
 	data: MapDatum[]
 	/** Base tone for the value ramp (low → high intensity). */
@@ -27,6 +44,8 @@ const props = withDefaults(defineProps<{
 	height?: number
 	/** Show min→max legend strip under the map. */
 	legend?: boolean
+	/** Wheel + button zoom / drag-to-pan. */
+	zoomable?: boolean
 	currency?: string
 	prefix?: string
 	suffix?: string
@@ -35,10 +54,12 @@ const props = withDefaults(defineProps<{
 	color: 'primary',
 	height: 280,
 	legend: true,
+	zoomable: true,
 	animated: true,
 })
 
 const el = ref<HTMLElement>()
+const svgEl = ref<SVGSVGElement>()
 const { progress } = useChartAnim({ el, enabled: props.animated, duration: 700 })
 
 const fmt = computed<ValueFormat>(() => ({
@@ -64,8 +85,8 @@ const byId = computed(() => {
 const maxValue = computed(() => Math.max(0, ...[...byId.value.values()].map(d => d.value)))
 
 const baseColor = computed(() => resolveColor(props.color))
-const emptyFill = 'color-mix(in srgb, var(--bgl-gray) 12%, var(--bgl-box-bg))'
-const strokeColor = 'color-mix(in srgb, var(--bgl-gray) 28%, var(--bgl-box-bg))'
+const emptyFill = 'var(--bgl-bg)'
+const strokeColor = 'var(--bgl-border-color)'
 
 /** Continuous ramp: empty → light tint → full base color by value share. */
 function fillFor(value: number | undefined): string {
@@ -103,12 +124,17 @@ const hoverId = ref<string | null>(null)
 const tipX = ref(0)
 const tipY = ref(0)
 
-function onEnter(id: string) { hoverId.value = id }
+function onEnter(id: string) {
+	if (dragging.value) return
+	hoverId.value = id
+}
 function onLeave() { hoverId.value = null }
-function onMove(e: MouseEvent) { trackLocalPointer(e, tipX, tipY) }
+function onMove(e: MouseEvent) {
+	if (!dragging.value) trackLocalPointer(e, tipX, tipY)
+}
 
 const hover = computed(() => {
-	if (!hoverId.value) return null
+	if (!hoverId.value || dragging.value) return null
 	const c = countries.value.find(x => x.id === hoverId.value)
 	return c?.hasData ? c : null
 })
@@ -121,41 +147,178 @@ const tooltipStyle = tipFollowStyle(tipX, tipY)
 
 const legendMin = computed(() => formatValue(0, fmt.value))
 const legendMax = computed(() => formatValue(maxValue.value, fmt.value))
+
+// ── Zoom / pan ──────────────────────────────────────────────────────────────
+const scale = ref(1)
+const tx = ref(0)
+const ty = ref(0)
+const dragging = ref(false)
+const dragOrigin = ref<{ x: number; y: number; tx: number; ty: number } | null>(null)
+
+const mapTransform = computed(() =>
+	`translate(${tx.value} ${ty.value}) scale(${scale.value})`,
+)
+
+const isZoomed = computed(() => scale.value > MIN_ZOOM + 0.001)
+
+function clamp(n: number, min: number, max: number) {
+	return Math.min(max, Math.max(min, n))
+}
+
+/** Client → SVG user coords (cropped viewBox space). */
+function clientToSvg(clientX: number, clientY: number) {
+	const svg = svgEl.value
+	if (!svg) return { x: 0, y: 0 }
+	const pt = svg.createSVGPoint()
+	pt.x = clientX
+	pt.y = clientY
+	const ctm = svg.getScreenCTM()?.inverse()
+	if (!ctm) return { x: 0, y: 0 }
+	const p = pt.matrixTransform(ctm)
+	return { x: p.x, y: p.y }
+}
+
+function zoomAt(clientX: number, clientY: number, next: number) {
+	const newScale = clamp(next, MIN_ZOOM, MAX_ZOOM)
+	if (newScale === scale.value) return
+	const { x, y } = clientToSvg(clientX, clientY)
+	const k = newScale / scale.value
+	tx.value = x - (x - tx.value) * k
+	ty.value = y - (y - ty.value) * k
+	scale.value = newScale
+	if (newScale <= MIN_ZOOM) {
+		tx.value = 0
+		ty.value = 0
+		scale.value = MIN_ZOOM
+	}
+}
+
+function onWheel(e: WheelEvent) {
+	if (!props.zoomable) return
+	e.preventDefault()
+	const factor = e.deltaY < 0 ? ZOOM_STEP : 1 / ZOOM_STEP
+	zoomAt(e.clientX, e.clientY, scale.value * factor)
+}
+
+function zoomBy(factor: number) {
+	const svg = svgEl.value
+	if (!svg) return
+	const r = svg.getBoundingClientRect()
+	zoomAt(r.left + r.width / 2, r.top + r.height / 2, scale.value * factor)
+}
+
+function resetZoom() {
+	scale.value = MIN_ZOOM
+	tx.value = 0
+	ty.value = 0
+}
+
+function onPointerDown(e: PointerEvent) {
+	if (!props.zoomable || !isZoomed.value || e.button !== 0) return
+	dragging.value = true
+	hoverId.value = null
+	const p = clientToSvg(e.clientX, e.clientY)
+	dragOrigin.value = { x: p.x, y: p.y, tx: tx.value, ty: ty.value }
+	;(e.currentTarget as HTMLElement).setPointerCapture?.(e.pointerId)
+}
+
+function onPointerMove(e: PointerEvent) {
+	if (!dragging.value || !dragOrigin.value) return
+	const p = clientToSvg(e.clientX, e.clientY)
+	tx.value = dragOrigin.value.tx + (p.x - dragOrigin.value.x)
+	ty.value = dragOrigin.value.ty + (p.y - dragOrigin.value.y)
+}
+
+function onPointerUp(e: PointerEvent) {
+	if (!dragging.value) return
+	dragging.value = false
+	dragOrigin.value = null
+	;(e.currentTarget as HTMLElement).releasePointerCapture?.(e.pointerId)
+}
+
+const croppedViewBox = `${MAP_VIEW.x} ${MAP_VIEW.y} ${MAP_VIEW.width} ${MAP_VIEW.height}`
 </script>
 
 <template>
 	<div ref="el" class="bgl-map w-100p flex column gap-075">
 		<div
-			class="bgl-map__plot relative w-100p"
+			class="bgl-map__plot relative w-100p overflow-hidden"
+			:class="{
+				'bgl-map__plot--zoomable': zoomable,
+				'bgl-map__plot--zoomed': zoomable && isZoomed,
+				'bgl-map__plot--dragging': dragging,
+			}"
 			:style="{ height: `${height}px` }"
 			@mousemove="onMove"
 			@mouseleave="onLeave"
+			@wheel="onWheel"
+			@pointerdown="onPointerDown"
+			@pointermove="onPointerMove"
+			@pointerup="onPointerUp"
+			@pointercancel="onPointerUp"
 		>
 			<svg
+				ref="svgEl"
 				class="bgl-map__svg"
 				dir="ltr"
-				:viewBox="`0 0 ${WORLD_VIEWBOX.width} ${WORLD_VIEWBOX.height}`"
+				:viewBox="croppedViewBox"
 				preserveAspectRatio="xMidYMid meet"
 				width="100%"
 				height="100%"
 			>
-				<path
-					v-for="c in countries"
-					:key="c.id"
-					:d="c.d"
-					:fill="c.fill"
-					:stroke="strokeColor"
-					stroke-width="0.6"
-					vector-effect="non-scaling-stroke"
-					class="bgl-map__country"
-					:class="{
-						'opacity-5': hoverId != null && hoverId !== c.id,
-						'bgl-map__country--hot': hoverId === c.id && c.hasData,
-					}"
-					@mouseenter="onEnter(c.id)"
-				/>
+				<g :transform="mapTransform">
+					<path
+						v-for="c in countries"
+						:key="c.id"
+						:d="c.d"
+						:fill="c.fill"
+						:stroke="strokeColor"
+						stroke-width="0.6"
+						vector-effect="non-scaling-stroke"
+						class="bgl-map__country"
+						:class="{
+							'opacity-5': hoverId != null && hoverId !== c.id,
+							'bgl-map__country--hot': hoverId === c.id && c.hasData,
+						}"
+						@mouseenter="onEnter(c.id)"
+					/>
+				</g>
 			</svg>
 
+			<div
+				v-if="zoomable"
+				class="bgl-map__zoom flex column gap-025 absolute bottom-05 end-025 z-1 p-025 round bg-box shadow-10 border"
+				@pointerdown.stop
+			>
+				<Btn
+					flat
+					thin
+					round
+					size="xs"
+					icon="add"
+					:disabled="scale >= MAX_ZOOM"
+					@click="zoomBy(ZOOM_STEP)"
+				/>
+				<Btn
+					flat
+					thin
+					round
+					size="xs"
+					icon="remove"
+					:disabled="scale <= MIN_ZOOM"
+					@click="zoomBy(1 / ZOOM_STEP)"
+				/>
+				<Btn
+					:disabled="!isZoomed"
+					flat
+					thin
+					round
+					size="xs"
+					icon="zoom_out_map"
+					@click="resetZoom"
+				/>
+			</div>
+
 			<ChartTooltip
 				v-if="hover"
 				prefer="above"
@@ -183,12 +346,16 @@ const legendMax = computed(() => formatValue(maxValue.value, fmt.value))
 
 <style scoped>
 .bgl-map__plot { min-height: 0; }
-.bgl-map__svg { display: block; overflow: visible; }
+.bgl-map__plot--zoomable { touch-action: none; }
+.bgl-map__plot--zoomed { cursor: grab; }
+.bgl-map__plot--dragging { cursor: grabbing; }
+.bgl-map__svg { display: block; overflow: hidden; }
 .bgl-map__country {
 	cursor: default;
 	transition: opacity 0.15s ease, fill 0.15s ease;
 	outline: none;
 }
+.bgl-map__plot--zoomed .bgl-map__country { cursor: inherit; }
 .bgl-map__country--hot { stroke: var(--bgl-gray); stroke-width: 1.2; }
 .bgl-map__ramp {
 	height: 0.5rem;

package/src/components/dataTable/DataTable.vue

@@ -32,6 +32,8 @@ const slots: SetupContext['slots'] = useSlots()
 
 const loading = defineModel('loading', { default: false })
 const itemHeight = defineModel('itemHeight', { default: 50 })
+/** Cell font size. Number = px; string = any CSS size (e.g. '0.875rem'). */
+const fontSize = defineModel<number | string | undefined>('fontSize', { default: undefined })
 const selectedItems = defineModel<string[]>('selectedItems', { default: [] as string[] })
 
 const {
@@ -126,9 +128,14 @@ const computedItemHeight = computed(() => `${itemHeight.value}px`)
 
 watch(
 	() => loading.value,
-	(newLoadingVal, oldLoadingVal) => {
+	async (newLoadingVal, oldLoadingVal) => {
 		if (newLoadingVal === oldLoadingVal) { return }
-		if (!newLoadingVal) { registerLastItemObserver() }
+		if (!newLoadingVal) {
+			registerLastItemObserver()
+			scrollTo(0)
+			await nextTick()
+			scrollTo(0)
+		}
 	},
 	{ immediate: true }
 )
@@ -139,9 +146,14 @@ watch(
 )
 
 watch(
-	() => computedData.value,
-	(newData, oldData) => {
-		if (newData.length === oldData.length || props.onLastItemVisible !== undefined) { return }
+	() => computedData.value.length,
+	async (newLen, oldLen) => {
+		// Infinite-scroll appends: keep position. First load (0 → n) still resets.
+		const isAppend = props.onLastItemVisible !== undefined && (oldLen ?? 0) > 0
+		if (newLen === oldLen || isAppend) return
+
+		scrollTo(0)
+		await nextTick()
 		scrollTo(0)
 	}
 )
@@ -150,12 +162,26 @@ const showLoading = computed(() => loading.value)
 
 // Show the empty state only once loading has settled and there are no rows.
 const isEmpty = computed(() => !showLoading.value && computedData.value.length === 0)
+
+const resolvedFontSize = computed(() => {
+	const size = fontSize.value
+	if (size == null || size === '') return null
+	return typeof size === 'number' ? `${size}px` : String(size)
+})
+
+/** Applied to body cells — falls back to the historical default. */
+const bodyFontSize = computed(() => resolvedFontSize.value ?? '0.88em')
+/** Header is slightly smaller than body when a custom size is set. */
+const headerFontSize = computed(() => {
+	if (!resolvedFontSize.value) return '0.8rem'
+	return `calc(${resolvedFontSize.value} * 0.9)`
+})
 </script>
 
 <template>
 	<div class="table-list-wrap h-100p" v-bind="containerProps" :class="{ overflowHiddenLoading: showLoading }">
 		<Loading v-if="showLoading" class="h100p" />
-		<div v-bind="wrapperProps" :class="{ 'pointer-events-none': showLoading }">
+		<div v-if="!isEmpty" v-bind="wrapperProps" :class="{ 'pointer-events-none': showLoading }">
 			<table class="infinite-wrapper" :class="{ selecting: computedSelectedItems.length }">
 				<thead class="row first-row">
 					<th v-if="isSortable" class="col-drag" />
@@ -202,16 +228,16 @@ const isEmpty = computed(() => !showLoading.value && computedData.value.length =
 					<tr v-if="props.onLastItemVisible !== undefined" ref="lastItemEl" style="height: 1px;" />
 				</tbody>
 			</table>
-			<!-- Built-in empty state (overridable via the #empty slot) -->
-			<slot v-if="isEmpty" name="empty">
-				<EmptyState
-					:icon="props.emptyIcon ?? 'inbox'"
-					:title="props.emptyTitle ?? 'No results'"
-					:description="props.emptyDescription"
-					compact
-				/>
-			</slot>
 		</div>
+		<!-- Outside the virtualized wrapper so EmptyState doesn't inflate scroll height -->
+		<slot v-if="isEmpty" name="empty">
+			<EmptyState
+				:icon="props.emptyIcon ?? 'inbox'"
+				:title="props.emptyTitle ?? 'No results'"
+				:description="props.emptyDescription"
+				compact
+			/>
+		</slot>
 	</div>
 </template>
 
@@ -238,6 +264,9 @@ cursor: grab;
 
 .table-list-wrap {
 min-height: 150px;
+/* Prevent browser scroll anchoring from pushing content to the bottom
+   when rows mount and the virtual list height jumps. */
+overflow-anchor: none;
 }
 
 .selected {
@@ -292,7 +321,7 @@ width: 100%;
 }
 
 th {
-font-size: 0.8rem;
+font-size: v-bind(headerFontSize);
 color: var(--bgl-black-tint);
 position: sticky;
 top: 0;
@@ -315,7 +344,7 @@ cursor: pointer;
 }
 
 .row.first-row {
-font-size: 0.8rem;
+font-size: v-bind(headerFontSize);
 color: var(--bgl-black-tint);
 position: sticky;
 top: 0;
@@ -377,7 +406,7 @@ margin-top: -2px;
 }
 
 .rows {
-font-size: 0.88em;
+font-size: v-bind(bodyFontSize);
 }
 
 .table-list {
@@ -476,7 +505,7 @@ line-height: 1;
 }
 
 tbody tr {
-font-size: 0.88em;
+font-size: v-bind(bodyFontSize);
 height: v-bind(computedItemHeight);
 transition: all 200ms ease;
 }

package/src/components/form/inputs/ArrayInput.vue

@@ -11,7 +11,7 @@ import { useBagelInputShell } from './bagelInputShell'
 
 const props = defineProps<{
 	label?: string
-	helpText?: string
+	helptext?: string
 	modelValue: T[]
 	allowAdd?: boolean
 	allowDelete?: boolean
@@ -176,8 +176,8 @@ function getItemRef(i: number) {
 		<label v-if="label" class="txt12 txt-gray-90 mb-025 block">
 			{{ resolveI18n(label) }}
 		</label>
-		<p v-if="helpText" class="txt12 txt-gray-50 mb-05">
-			{{ helpText }}
+		<p v-if="helptext" class="helptext">
+			{{ helptext }}
 		</p>
 		<template v-if="!collapsible">
 			<div v-for="(_, i) in items" :key="i" class="array-input-row grid align-items-center" :class="{ 'simpleArray': isSimple, 'pb-1': !isSimple }">

package/src/components/form/inputs/EmailInput.vue

@@ -351,7 +351,7 @@ onMounted(() => {
 		<label :for="id">
 			<span v-if="label || (underlined && placeholder)" class="label-text">{{ resolveI18n(label) || resolveI18n(placeholder) }}<span v-if="required"> *</span></span>
 			<div v-if="!underlined" class="flex">
-				<span v-if="helptext" class="opacity-7 light">{{ helptext }}</span>
+				<span v-if="helptext" class="helptext">{{ helptext }}</span>
 				<span
 					v-if="suggestedCorrection" class="pointer nowrap inline-block ms-auto color-red txt-10px p-0"
 					@click.prevent="applyCorrection"

package/src/components/form/inputs/NumberInput.vue

@@ -217,7 +217,7 @@ const hasValue = computed(() => formattedValue.value.length > 0)
 					:class="[{ 'bgl-big-ctrl-num-btn': layout === 'vertical' }]" tabindex="-1" @click="decrement"
 				/>
 			</div>
-			<p v-if="helptext" class="opacity-7 light">
+			<p v-if="helptext" class="helptext">
 				{{ helptext }}
 			</p>
 		</div>

package/src/components/form/inputs/SelectInput.vue

@@ -36,7 +36,7 @@ interface PropTypes extends BagelInputShellProps {
 	icon?: IconType
 	hideLabel?: boolean
 	defaultValue?: Option
-	helpText?: string
+	helptext?: string
 	clearable?: boolean
 	placement?: AlignedPlacement
 	searchPlaceholder?: string
@@ -315,8 +315,8 @@ onMounted(() => {
 					{{ error }}
 				</div>
 			</label>
-			<p v-if="helpText" class="opacity-7 txt-small light">
-				{{ helpText }}
+			<p v-if="helptext" class="helptext">
+				{{ helptext }}
 			</p>
 		</template>
 		<Skeleton v-if="isLoading" :count="6" width="200px" height="25px" class="mx-1 my-1" />

package/src/components/form/inputs/SignaturePad.vue

@@ -294,13 +294,6 @@ font-size: var(--bgl-label-font-size);
 margin-bottom: 0.25rem;
 }
 
-.bgl_input.signature-pad > .helptext {
-font-size: var(--bgl-label-font-size);
-margin: 0 0 0.25rem 0;
-line-height: 1.4;
-opacity: 0.7;
-}
-
 .bgl_input.signature-pad .canvas[disabled] {
 background: var(--input-disabled-bg);
 border: 1px solid var(--bgl-gray);

package/src/components/form/inputs/TextInput.vue

@@ -186,10 +186,10 @@ onMounted(async () => {
 				:placeholder="underlined ? ' ' : (resolveI18n(placeholder) || resolveI18n(label))" :disabled :required
 				v-bind="nativeInputAttrs" :pattern="normalizedPattern" @input="updateInputVal" @focusout="onFocusout"
 			/>
-			<p v-if="helptext" class="opacity-7 light">{{ helptext }}</p>
 			<Icon v-if="iconStart" :class="{ ' -top-025 line-height-0 ': underlined }" class="iconStart" :icon="iconStart" />
 			<Icon v-if="icon" :class="{ ' -top-025 line-height-0 ': underlined }" :icon />
 		</label>
+		<p v-if="helptext" class="helptext">{{ helptext }}</p>
 		<div v-if="error" class="error-message">
 			{{ error }}
 		</div>

package/src/components/form/inputs/ToggleInput.vue

@@ -8,6 +8,7 @@ const props = withDefaults(defineProps<{
 	label?: string
 	id?: string
 	title?: string
+	helptext?: string
 	small?: boolean
 	required?: boolean
 	defaultValue?: boolean
@@ -47,6 +48,10 @@ onMounted(() => {
 				{{ resolveI18n(label) }}
 			</slot>
 		</label>
+
+		<p v-if="helptext" class="helptext">
+			{{ helptext }}
+		</p>
 	</div>
 </template>
 
@@ -58,6 +63,9 @@ display: unset !important;
 .bagel-input.bgl-toggle *{
   cursor: pointer !important;
 }
+.bagel-input.bgl-toggle .helptext {
+  cursor: default !important;
+}
 .bagel-input.bgl-toggle input{
 padding:  unset !important;
 min-width:  unset !important;

package/src/composables/useSchemaField.ts

@@ -26,6 +26,16 @@ const SLOT_VALUE_COMPONENTS = new Set(['div', 'span', 'p'])
 
 const SRC_VALUE_COMPONENTS = new Set(['img', 'iframe'])
 
+/** Display components that take content via `value` (not `modelValue`). */
+const VALUE_PROP_NAMES = new Set(['BglBadge', 'Badge', 'BglPill', 'Pill'])
+
+function usesValueProp(Component: unknown): boolean {
+	if (!Component || typeof Component === 'string') return false
+	const name = (Component as { name?: string, __name?: string }).name
+		?? (Component as { __name?: string }).__name
+	return !!name && VALUE_PROP_NAMES.has(name)
+}
+
 export interface UseSchemaFieldOptions<T, SFP extends Path<T>> {
 	mode?: 'form' | 'preview' | 'table'
 	getFormData?: () => T
@@ -217,6 +227,9 @@ export function useSchemaField<T extends { [key: string]: any }>(optns: UseSchem
 				// Slot components don't need a value prop
 			} else if (isSrcValueComponent) {
 				props.src = transformedValue
+			} else if (usesValueProp(Component)) {
+				// Badge etc. read `value`, not modelValue — empty outline pills otherwise
+				props.value = transformedValue != null ? String(transformedValue) : transformedValue
 			} else {
 				props.modelValue = transformedValue
 			}

package/src/form-flow/FormFlow.vue

@@ -293,12 +293,15 @@ const mergedErrors = computed(() => {
 
 function getFieldProps(field: FieldBuilder, key: string) {
 	const label = generateLabel(key, field)
+	const { helpText, ...configRest } = field._config
 	const baseProps: any = {
 		label,
 		'modelValue': getFieldValue(key),
 		'onUpdate:modelValue': (val: any) => { updateField(key, val, field) },
 		'error': mergedErrors.value[key],
-		...field._config,
+		...configRest,
+		// Inputs use `helptext`; FormFlow schema API keeps `helpText`
+		...(helpText != null ? { helptext: helpText } : {}),
 		name: field._config.name ?? key,
 	}
 
@@ -326,14 +329,16 @@ function getFieldProps(field: FieldBuilder, key: string) {
 
 	if (field._type === 'array') {
 		// `default` / `schema` are form-schema metadata — never pass them through to ArrayInput
-		// (and the earlier `...field._config` spread may have already set them).
+		// (and the earlier config spread may have already set them).
 		delete baseProps.default
 		delete baseProps.schema
 		delete baseProps.itemType
-		const configWithoutSchema = Object.fromEntries(
+		const { helpText: arrayHelpText, ...arrayConfigRest } = Object.fromEntries(
 			Object.entries(field._config).filter(([k]) => k !== 'schema' && k !== 'itemType' && k !== 'default')
 		)
-		Object.assign(baseProps, configWithoutSchema)
+		Object.assign(baseProps, arrayConfigRest)
+		if (arrayHelpText != null) baseProps.helptext = arrayHelpText
+		delete baseProps.helpText
 		// Re-apply binding after config spread so handlers never get overwritten.
 		baseProps.modelValue = getFieldValue(key)
 		baseProps['onUpdate:modelValue'] = (val: any) => { updateField(key, val, field) }

package/src/styles/inputs.css

@@ -59,6 +59,24 @@ select {
     color: var(--bgl-input-label-active-color);
 }
 
+.helptext {
+    display: block;
+    margin: 0.15rem 0 0.25rem;
+    line-height: 1.4;
+    font-size: var(--bgl-label-font-size);
+    font-weight: 300;
+    color: var(--bgl-label-color);
+    cursor: default;
+    user-select: text;
+}
+
+/* Keep helptext muted even when nested inside a focused/active label */
+.bagel-input:focus-within .helptext,
+.bagel-input.open .helptext,
+.bagel-input:has(:checked) .helptext {
+    color: var(--bgl-label-color);
+}
+
 .bagel-input input,
 .bagel-input select,
 .custom-select .input {