@vielzeug/refine 1.3.1 → 1.4.0

package/dist/headless/field-base.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"field-base.cjs","names":[],"sources":["../../src/headless/field-base.ts"],"sourcesContent":["import { createStableId } from '@vielzeug/ore';\nimport { computed, type Readable } from '@vielzeug/ripple';\n\n// ── Validation / context types ────────────────────────────────────────────────\n\nexport type ValidationTrigger = 'blur' | 'change' | 'input' | 'submit';\nexport type ControlValidationMode = ValidationTrigger | undefined;\n\n// ── Field options + handle ───────────────────────────────────────────────────\n\n/** Options shared by both `createTextField` and `createChoiceField`. */\nexport type FieldOptions = {\n  disabled?: Readable<boolean | undefined>;\n  error?: Readable<string | undefined>;\n  /**\n   * Returns the underlying form field object used for validation triggering.\n   * Called lazily — safe to return `null` before the first render.\n   */\n  getFormField?: () => { reportValidity(): void } | null;\n  /**\n   * Override for label visibility that takes precedence over deriving it from\n   * the `label` text signal. Pass a computed signal that checks both prop and\n   * slot presence to enable slot-first composition.\n   *\n   * @example\n   * ```ts\n   * const hasLabel = computed(() => !!props.label.value || slots.has('label').value);\n   * const field = createField({ ...options, hasLabel });\n   * ```\n   */\n  hasLabel?: Readable<boolean>;\n  helper?: Readable<string | undefined>;\n  /**\n   * When provided, used directly as `fieldId` instead of generating one via\n   * `createStableId`. Useful in tests for deterministic ID assertions.\n   */\n  id?: string;\n  /**\n   * Label text signal. When provided, `labelVisible` and `ariaLabelledBy` are\n   * computed reactively from this value (see `hasLabel` for the slot-first override).\n   */\n  label?: Readable<string | undefined>;\n  /**\n   * Label placement signal. Defaults to `'inset'`.\n   *\n   * Not currently consumed by `createField()` itself — visibility is driven\n   * solely by `hasLabel`/`label`. Threaded through so component authors can\n   * apply placement-specific styling (`label-placement` attribute) without a\n   * second prop; if placement-dependent visibility is ever needed, wire it\n   * into `labelVisible$` in `createField()` instead of adding a new option.\n   */\n  labelPlacement?: Readable<LabelPlacement>;\n  prefix?: string;\n  validateOn?: Readable<ControlValidationMode>;\n};\n\n// ── Error/helper assistive state ──────────────────────────────────────────────\n\nexport type ErrorHelperState = {\n  errorText: string;\n  helperText: string;\n};\n\nexport type ErrorHelperOptions = {\n  error?: Readable<string | undefined>;\n  helper?: Readable<string | undefined>;\n};\n\nexport const createErrorHelperState = (options: ErrorHelperOptions): Readable<ErrorHelperState> =>\n  computed(() => ({\n    errorText: options.error?.value ?? '',\n    helperText: options.helper?.value ?? '',\n  }));\n\n// ── Counter state (opt-in) ─────────────────────────────────────────────────────\n\n/** Counter state for text fields with `maxLength`. */\nexport type CounterState = {\n  counterAtLimit: boolean;\n  counterNearLimit: boolean;\n  counterText: string;\n};\n\nexport type CounterOptions = {\n  maxLength?: Readable<number | undefined>;\n  value: Readable<string | undefined>;\n};\n\n/**\n * Creates a reactive counter state signal for text fields with `maxLength`.\n * Only call this when `maxLength` may be set — the state is genuinely opt-in.\n *\n * @example\n * ```ts\n * const counter = createCounterState({ value: tf.value, maxLength: props.maxlength });\n * ```\n */\nexport const createCounterState = (options: CounterOptions): Readable<CounterState> =>\n  computed<CounterState>(() => {\n    const value = options.value?.value ?? '';\n    const maxLength = options.maxLength?.value;\n    const parsedMaxLength = Number(maxLength);\n    const validMaxLength = Number.isFinite(parsedMaxLength) && parsedMaxLength > 0 ? parsedMaxLength : null;\n    const hasCounter = validMaxLength !== null;\n    const counterText = hasCounter ? `${value.length} / ${validMaxLength}` : '';\n    const ratio = hasCounter ? value.length / validMaxLength : 0;\n\n    return {\n      counterAtLimit: hasCounter ? ratio >= 1 : false,\n      counterNearLimit: hasCounter ? ratio >= 0.9 && ratio < 1 : false,\n      counterText,\n    };\n  });\n\n// ── Label placement ───────────────────────────────────────────────────────────\n\nexport type LabelPlacement = 'inset' | 'outside' | undefined;\n\n// ── Field handle ──────────────────────────────────────────────────────────────\n\n/**\n * Common handle returned by `createField` — the base for both `TextFieldHandle`\n * and `ChoiceFieldHandle`.\n *\n * ARIA signals and label state are flat on the handle — no nested `aria` or\n * `label` sub-objects.\n *\n * @example\n * ```html\n * <label id=\"${labelId}\" ?hidden=\"${() => !labelVisible.value}\">...</label>\n * <input\n *   :aria-labelledby=\"${ariaLabelledBy}\"\n *   :aria-describedby=\"${ariaDescribedBy}\"\n *   :aria-invalid=\"${ariaInvalid}\" />\n * ```\n */\n/** Flat ARIA attribute bag ready to spread into a template bind call. */\nexport type AriaProps = {\n  'aria-describedby': string | null;\n  'aria-errormessage': string | null;\n  'aria-invalid': 'true' | null;\n  'aria-labelledby': string | null;\n};\n\nexport type FieldHandle = {\n  /** `aria-describedby` value. Non-null when helper or error text is present. */\n  ariaDescribedBy: Readable<string | null>;\n  /** `aria-errormessage` value. Non-null when error text is present. */\n  ariaErrorMessage: Readable<string | null>;\n  /** `aria-invalid` value. `'true'` when error text is present, otherwise `null`. */\n  ariaInvalid: Readable<'true' | null>;\n  /** `aria-labelledby` value. Non-null when a label is visible. */\n  ariaLabelledBy: Readable<string | null>;\n  /**\n   * Returns a snapshot of the four ARIA attributes as a plain object.\n   * Spread into a template bind call to avoid repeating each signal individually.\n   *\n   * @example\n   * ```ts\n   * bind(inputEl, { attr: field.ariaProps() });\n   * ```\n   */\n  ariaProps(): AriaProps;\n  /**\n   * The stable `id` used for `aria-describedby` on the input. Points at the\n   * assistive-text region (covers both helper text and error text per WAI-ARIA).\n   */\n  assistiveId: string;\n  disabled: Readable<boolean>;\n  /** Stable `id` for the inline error message element (`aria-errormessage`). */\n  errorId: string;\n  /** Reactive error text. Empty string when no error is set. */\n  errorText: Readable<string>;\n  fieldId: string;\n  /** Reactive helper text. Empty string when no helper is set. */\n  helperText: Readable<string>;\n  /** Stable `id` for the label element. Stamp this on your `<label id=\"...\">`. */\n  labelId: string;\n  /** Whether the label should be visible. Use to toggle `hidden` on the `<label>`. */\n  labelVisible: Readable<boolean>;\n  triggerValidation: (on: Extract<ValidationTrigger, 'blur' | 'change'>) => void;\n};\n\n/**\n * Composes the field triad — IDs, assistive state, and label state — into a\n * single `FieldHandle`. Both `createTextField` and `createChoiceField` build\n * on top of this.\n */\nexport const createField = (options: FieldOptions): FieldHandle => {\n  // ── Core ──────────────────────────────────────────────────────────────────\n  const disabled = computed(() => Boolean(options.disabled?.value));\n  const validateOn = options.validateOn;\n  const fieldId = options.id ?? createStableId(options.prefix ?? 'field');\n  const assistiveId = createStableId('helper');\n\n  const triggerValidation = (on: Extract<ValidationTrigger, 'blur' | 'change'>): void => {\n    if (validateOn?.value === on) options.getFormField?.()?.reportValidity();\n  };\n\n  // ── Label + ARIA state ────────────────────────────────────────────────────\n  const labelId = createStableId('label');\n  const errorId = createStableId('error');\n\n  const label$ = options.label ?? computed(() => undefined);\n\n  // Slot-first composition: if the caller provides `hasLabel`, use it instead\n  // of deriving visibility purely from the label text signal. This allows\n  // components with a `<slot name=\"label\">` to stay visible even when the\n  // `label` prop is empty but a slotted label element is present.\n  const labelVisible$ = options.hasLabel ?? computed(() => Boolean(label$.value));\n\n  const resolvedAssistive = createErrorHelperState({ error: options.error, helper: options.helper });\n\n  const ariaDescribedBy = computed(() =>\n    resolvedAssistive.value.errorText || resolvedAssistive.value.helperText ? assistiveId : null,\n  );\n  const ariaErrorMessage = computed(() => (resolvedAssistive.value.errorText ? errorId : null));\n  const ariaInvalid = computed<'true' | null>(() => (resolvedAssistive.value.errorText ? 'true' : null));\n  const ariaLabelledBy = computed(() => (labelVisible$.value ? labelId : null));\n\n  return {\n    ariaDescribedBy,\n    ariaErrorMessage,\n    ariaInvalid,\n    ariaLabelledBy,\n    ariaProps: () => ({\n      'aria-describedby': ariaDescribedBy.value,\n      'aria-errormessage': ariaErrorMessage.value,\n      'aria-invalid': ariaInvalid.value,\n      'aria-labelledby': ariaLabelledBy.value,\n    }),\n    assistiveId,\n    disabled,\n    errorId,\n    errorText: computed(() => resolvedAssistive.value.errorText),\n    fieldId,\n    helperText: computed(() => resolvedAssistive.value.helperText),\n    labelId,\n    labelVisible: labelVisible$,\n    triggerValidation,\n  };\n};\n"],"mappings":"6DAoEA,IAAa,EAA0B,IAAA,EAAA,EAAA,SAAA,MACrB,CACd,UAAW,EAAQ,OAAO,OAAS,GACnC,WAAY,EAAQ,QAAQ,OAAS,EACvC,EAAE,EAyBS,EAAsB,IAAA,EAAA,EAAA,SAAA,KACJ,CAC3B,IAAM,EAAQ,EAAQ,OAAO,OAAS,GAChC,EAAY,EAAQ,WAAW,MAC/B,EAAkB,OAAO,CAAS,EAClC,EAAiB,OAAO,SAAS,CAAe,GAAK,EAAkB,EAAI,EAAkB,KAC7F,EAAa,IAAmB,KAChC,EAAc,EAAa,GAAG,EAAM,OAAO,KAAK,IAAmB,GACnE,EAAQ,EAAa,EAAM,OAAS,EAAiB,EAE3D,MAAO,CACL,eAAgB,EAAa,GAAS,EAAI,GAC1C,iBAAkB,EAAa,GAAS,IAAO,EAAQ,EAAI,GAC3D,aACF,CACF,CAAC,EA4EU,EAAe,GAAuC,CAEjE,IAAM,GAAA,EAAA,EAAA,SAAA,KAA0B,EAAQ,EAAQ,UAAU,KAAM,EAC1D,EAAa,EAAQ,WACrB,EAAU,EAAQ,KAAA,EAAA,EAAA,eAAA,CAAqB,EAAQ,QAAU,OAAO,EAChE,GAAA,EAAA,EAAA,eAAA,CAA6B,QAAQ,EAErC,EAAqB,GAA4D,CACjF,GAAY,QAAU,GAAI,EAAQ,eAAe,CAAC,EAAE,eAAe,CACzE,EAGM,GAAA,EAAA,EAAA,eAAA,CAAyB,OAAO,EAChC,GAAA,EAAA,EAAA,eAAA,CAAyB,OAAO,EAEhC,EAAS,EAAQ,QAAA,EAAA,EAAA,SAAA,KAAwB,IAAA,EAAS,EAMlD,EAAgB,EAAQ,WAAA,EAAA,EAAA,SAAA,KAA2B,EAAQ,EAAO,KAAM,EAExE,EAAoB,EAAuB,CAAE,MAAO,EAAQ,MAAO,OAAQ,EAAQ,MAAO,CAAC,EAE3F,GAAA,EAAA,EAAA,SAAA,KACJ,EAAkB,MAAM,WAAa,EAAkB,MAAM,WAAa,EAAc,IAC1F,EACM,GAAA,EAAA,EAAA,SAAA,KAAmC,EAAkB,MAAM,UAAY,EAAU,IAAK,EACtF,GAAA,EAAA,EAAA,SAAA,KAA6C,EAAkB,MAAM,UAAY,OAAS,IAAK,EAC/F,GAAA,EAAA,EAAA,SAAA,KAAiC,EAAc,MAAQ,EAAU,IAAK,EAE5E,MAAO,CACL,kBACA,mBACA,cACA,iBACA,eAAkB,CAChB,mBAAoB,EAAgB,MACpC,oBAAqB,EAAiB,MACtC,eAAgB,EAAY,MAC5B,kBAAmB,EAAe,KACpC,GACA,cACA,WACA,UACA,WAAA,EAAA,EAAA,SAAA,KAA0B,EAAkB,MAAM,SAAS,EAC3D,UACA,YAAA,EAAA,EAAA,SAAA,KAA2B,EAAkB,MAAM,UAAU,EAC7D,UACA,aAAc,EACd,mBACF,CACF"}
+{"version":3,"file":"field-base.cjs","names":[],"sources":["../../src/headless/field-base.ts"],"sourcesContent":["import { createStableId } from '@vielzeug/ore';\nimport { computed, type Readable } from '@vielzeug/ripple';\n\nimport { warn } from '../_dev';\n\n// ── Validation / context types ────────────────────────────────────────────────\n\nexport type ValidationTrigger = 'blur' | 'change' | 'input' | 'submit';\nexport type ControlValidationMode = ValidationTrigger | undefined;\n\n// ── Error/helper assistive state ──────────────────────────────────────────────\n\nexport type ErrorHelperState = {\n  errorText: string;\n  helperText: string;\n};\n\nexport type ErrorHelperOptions = {\n  error?: Readable<string | undefined>;\n  helper?: Readable<string | undefined>;\n};\n\nexport const createErrorHelperState = (options: ErrorHelperOptions): Readable<ErrorHelperState> =>\n  computed(() => ({\n    errorText: options.error?.value ?? '',\n    helperText: options.helper?.value ?? '',\n  }));\n\n// ── Counter state (opt-in) ─────────────────────────────────────────────────────\n\n/** Counter state for text fields with `maxLength`. */\nexport type CounterState = {\n  counterAtLimit: boolean;\n  counterNearLimit: boolean;\n  counterText: string;\n};\n\nexport type CounterOptions = {\n  maxLength?: Readable<number | undefined>;\n  value: Readable<string | undefined>;\n};\n\n/**\n * Creates a reactive counter state signal for text fields with `maxLength`.\n * Only call this when `maxLength` may be set — the state is genuinely opt-in.\n *\n * @example\n * ```ts\n * const counter = createCounterState({ value: tf.value, maxLength: props.maxlength });\n * ```\n */\nexport const createCounterState = (options: CounterOptions): Readable<CounterState> =>\n  computed<CounterState>(() => {\n    const value = options.value?.value ?? '';\n    const maxLength = options.maxLength?.value;\n    const parsedMaxLength = Number(maxLength);\n    const validMaxLength = Number.isFinite(parsedMaxLength) && parsedMaxLength > 0 ? parsedMaxLength : null;\n    const hasCounter = validMaxLength !== null;\n    const counterText = hasCounter ? `${value.length} / ${validMaxLength}` : '';\n    const ratio = hasCounter ? value.length / validMaxLength : 0;\n\n    return {\n      counterAtLimit: hasCounter ? ratio >= 1 : false,\n      counterNearLimit: hasCounter ? ratio >= 0.9 && ratio < 1 : false,\n      counterText,\n    };\n  });\n\n/**\n * The single implementation of \"which modifier class does this counter state map to\" —\n * every field with a character counter (`ore-input`, `ore-textarea`, `ore-message-composer`)\n * renders the identical near-limit/at-limit styling, so this is the one place that decides it.\n *\n * @example\n * ```ts\n * html`<span class=\"${() => counterClassName(counter?.value)}\">...</span>`\n * ```\n */\nexport const counterClassName = (counter: CounterState | undefined, base = 'counter'): string => {\n  if (!counter) return base;\n\n  if (counter.counterAtLimit) return `${base} at-limit`;\n\n  if (counter.counterNearLimit) return `${base} near-limit`;\n\n  return base;\n};\n\n// ── Label placement ───────────────────────────────────────────────────────────\n\nexport type LabelPlacement = 'inset' | 'outside' | undefined;\n\n// ── Assistive state (error/helper text, describedby/errormessage/invalid) ─────\n\n/**\n * A field's error/helper/disabled/validation-trigger state — everything an input\n * needs *except* a visible `<label>`. Split out from label state (below) because\n * not every field has one: `ore-message-composer` names itself via `aria-label`\n * (a chat composer's accessible name conventionally comes from context/placeholder,\n * not a floating `<label>`), so it composes this directly instead of pulling in\n * label plumbing it can't use. `createField()` composes both for fields that do\n * render a `<label>`.\n */\nexport type AssistiveStateHandle = {\n  /** `aria-describedby` value. Non-null when helper or error text is present. */\n  ariaDescribedBy: Readable<string | null>;\n  /** `aria-errormessage` value. Non-null when error text is present. */\n  ariaErrorMessage: Readable<string | null>;\n  /** `aria-invalid` value. `'true'` when error text is present, otherwise `null`. */\n  ariaInvalid: Readable<'true' | null>;\n  /**\n   * The stable `id` used for `aria-describedby` on the input. Points at the\n   * assistive-text region (covers both helper text and error text per WAI-ARIA).\n   */\n  assistiveId: string;\n  /**\n   * Registers the real form field handle (the return value of `useField()`) so that\n   * `triggerValidation()` can call its `reportValidity()`. See `TextFieldHandle.attachFormField`\n   * for why this is a post-hoc call instead of a constructor option — the same forward\n   * reference applies here for choice fields.\n   */\n  attachFormField: (formField: { reportValidity(): void }) => void;\n  disabled: Readable<boolean>;\n  /** Stable `id` for the inline error message element (`aria-errormessage`). */\n  errorId: string;\n  /** Reactive error text. Empty string when no error is set. */\n  errorText: Readable<string>;\n  /** Reactive helper text. Empty string when no helper is set. */\n  helperText: Readable<string>;\n  triggerValidation: (on: Extract<ValidationTrigger, 'blur' | 'change'>) => void;\n};\n\nexport type AssistiveStateOptions = {\n  disabled?: Readable<boolean | undefined>;\n  error?: Readable<string | undefined>;\n  helper?: Readable<string | undefined>;\n  validateOn?: Readable<ControlValidationMode>;\n};\n\nexport const createAssistiveState = (options: AssistiveStateOptions): AssistiveStateHandle => {\n  const disabled = computed(() => Boolean(options.disabled?.value));\n  const assistiveId = createStableId('helper');\n  const errorId = createStableId('error');\n  const resolvedAssistive = createErrorHelperState({ error: options.error, helper: options.helper });\n\n  const ariaDescribedBy = computed(() =>\n    resolvedAssistive.value.errorText || resolvedAssistive.value.helperText ? assistiveId : null,\n  );\n  const ariaErrorMessage = computed(() => (resolvedAssistive.value.errorText ? errorId : null));\n  const ariaInvalid = computed<'true' | null>(() => (resolvedAssistive.value.errorText ? 'true' : null));\n\n  let formField: { reportValidity(): void } | null = null;\n  const attachFormField = (nextFormField: { reportValidity(): void }): void => {\n    formField = nextFormField;\n  };\n\n  const triggerValidation = (on: Extract<ValidationTrigger, 'blur' | 'change'>): void => {\n    if (options.validateOn?.value !== on) return;\n\n    if (!formField) {\n      // Not user-facing — this only fires when a component author wired `validateOn` but\n      // forgot the matching `attachFormField(useField(...))` call, so validation silently\n      // never runs instead of erroring where the mistake actually is.\n      warn(\n        \"triggerValidation() called before attachFormField() — validation will not run. See createTextField()/createChoiceField()/createCheckable()'s attachFormField doc comment.\",\n      );\n\n      return;\n    }\n\n    formField.reportValidity();\n  };\n\n  return {\n    ariaDescribedBy,\n    ariaErrorMessage,\n    ariaInvalid,\n    assistiveId,\n    attachFormField,\n    disabled,\n    errorId,\n    errorText: computed(() => resolvedAssistive.value.errorText),\n    helperText: computed(() => resolvedAssistive.value.helperText),\n    triggerValidation,\n  };\n};\n\n// ── Label state (visible `<label>` + `aria-labelledby`) ────────────────────────\n\nexport type LabelStateHandle = {\n  /** `aria-labelledby` value. Non-null when a label is visible. */\n  ariaLabelledBy: Readable<string | null>;\n  /** Stable `id` for the underlying form control — the `<label for=\"...\">` target. */\n  fieldId: string;\n  /** Stable `id` for the label element. Stamp this on your `<label id=\"...\">`. */\n  labelId: string;\n  /** Whether the label should be visible. Use to toggle `hidden` on the `<label>`. */\n  labelVisible: Readable<boolean>;\n};\n\nexport type LabelStateOptions = {\n  /**\n   * Override for label visibility that takes precedence over deriving it from\n   * the `label` text signal. Pass a computed signal that checks both prop and\n   * slot presence to enable slot-first composition.\n   *\n   * @example\n   * ```ts\n   * const hasLabel = computed(() => !!props.label.value || slots.has('label').value);\n   * const label = createLabelState({ ...options, hasLabel });\n   * ```\n   */\n  hasLabel?: Readable<boolean>;\n  /**\n   * When provided, used directly as `fieldId` instead of generating one via\n   * `createStableId`. Useful in tests for deterministic ID assertions.\n   */\n  id?: string;\n  /**\n   * Label text signal. When provided, `labelVisible` and `ariaLabelledBy` are\n   * computed reactively from this value (see `hasLabel` for the slot-first override).\n   */\n  label?: Readable<string | undefined>;\n  /**\n   * Label placement signal. Defaults to `'inset'`.\n   *\n   * Not consumed by `createLabelState()` itself — visibility is driven solely by\n   * `hasLabel`/`label`. Threaded through so component authors can apply\n   * placement-specific styling (`label-placement` attribute) without a second\n   * option; if placement-dependent visibility is ever needed, wire it into\n   * `labelVisible` here instead of adding a new option.\n   */\n  labelPlacement?: Readable<LabelPlacement>;\n  prefix?: string;\n};\n\nexport const createLabelState = (options: LabelStateOptions): LabelStateHandle => {\n  const fieldId = options.id ?? createStableId(options.prefix ?? 'field');\n  const labelId = createStableId('label');\n  const label$ = options.label ?? computed(() => undefined);\n\n  // Slot-first composition: if the caller provides `hasLabel`, use it instead\n  // of deriving visibility purely from the label text signal. This allows\n  // components with a `<slot name=\"label\">` to stay visible even when the\n  // `label` prop is empty but a slotted label element is present.\n  const labelVisible = options.hasLabel ?? computed(() => Boolean(label$.value));\n  const ariaLabelledBy = computed(() => (labelVisible.value ? labelId : null));\n\n  return { ariaLabelledBy, fieldId, labelId, labelVisible };\n};\n\n// ── Field handle (assistive + label, composed) ──────────────────────────────\n\n/**\n * Common handle returned by `createField` — the base for both `TextFieldHandle`\n * and `ChoiceFieldHandle`. Composes `createAssistiveState` + `createLabelState`;\n * call those directly instead if a field has no visible `<label>` (see\n * `createAssistiveState`'s doc comment).\n *\n * ARIA signals and label state are flat on the handle — no nested `aria` or\n * `label` sub-objects. `labelId`/`labelVisible`/`ariaLabelledBy` are always\n * present but only meaningful when `label`/`hasLabel` was passed — omit both\n * and they resolve to an always-hidden, unreferenced label.\n *\n * @example\n * ```html\n * <label id=\"${labelId}\" ?hidden=\"${() => !labelVisible.value}\">...</label>\n * <input\n *   :aria-labelledby=\"${ariaLabelledBy}\"\n *   :aria-describedby=\"${ariaDescribedBy}\"\n *   :aria-invalid=\"${ariaInvalid}\" />\n * ```\n */\nexport type FieldHandle = AssistiveStateHandle & LabelStateHandle;\n\n/** Options shared by both `createTextField` and `createChoiceField`. */\nexport type FieldOptions = AssistiveStateOptions & LabelStateOptions;\n\nexport const createField = (options: FieldOptions): FieldHandle => ({\n  ...createAssistiveState(options),\n  ...createLabelState(options),\n});\n"],"mappings":"4FAsBA,IAAa,EAA0B,IAAA,EAAA,EAAA,SAAA,MACrB,CACd,UAAW,EAAQ,OAAO,OAAS,GACnC,WAAY,EAAQ,QAAQ,OAAS,EACvC,EAAE,EAyBS,EAAsB,IAAA,EAAA,EAAA,SAAA,KACJ,CAC3B,IAAM,EAAQ,EAAQ,OAAO,OAAS,GAChC,EAAY,EAAQ,WAAW,MAC/B,EAAkB,OAAO,CAAS,EAClC,EAAiB,OAAO,SAAS,CAAe,GAAK,EAAkB,EAAI,EAAkB,KAC7F,EAAa,IAAmB,KAChC,EAAc,EAAa,GAAG,EAAM,OAAO,KAAK,IAAmB,GACnE,EAAQ,EAAa,EAAM,OAAS,EAAiB,EAE3D,MAAO,CACL,eAAgB,EAAa,GAAS,EAAI,GAC1C,iBAAkB,EAAa,GAAS,IAAO,EAAQ,EAAI,GAC3D,aACF,CACF,CAAC,EAYU,GAAoB,EAAmC,EAAO,YACpE,EAED,EAAQ,eAAuB,GAAG,EAAK,WAEvC,EAAQ,iBAAyB,GAAG,EAAK,aAEtC,EANc,EA4DV,EAAwB,GAAyD,CAC5F,IAAM,GAAA,EAAA,EAAA,SAAA,KAA0B,EAAQ,EAAQ,UAAU,KAAM,EAC1D,GAAA,EAAA,EAAA,eAAA,CAA6B,QAAQ,EACrC,GAAA,EAAA,EAAA,eAAA,CAAyB,OAAO,EAChC,EAAoB,EAAuB,CAAE,MAAO,EAAQ,MAAO,OAAQ,EAAQ,MAAO,CAAC,EAE3F,GAAA,EAAA,EAAA,SAAA,KACJ,EAAkB,MAAM,WAAa,EAAkB,MAAM,WAAa,EAAc,IAC1F,EACM,GAAA,EAAA,EAAA,SAAA,KAAmC,EAAkB,MAAM,UAAY,EAAU,IAAK,EACtF,GAAA,EAAA,EAAA,SAAA,KAA6C,EAAkB,MAAM,UAAY,OAAS,IAAK,EAEjG,EAA+C,KAsBnD,MAAO,CACL,kBACA,mBACA,cACA,cACA,gBA1BuB,GAAoD,CAC3E,EAAY,CACd,EAyBE,WACA,UACA,WAAA,EAAA,EAAA,SAAA,KAA0B,EAAkB,MAAM,SAAS,EAC3D,YAAA,EAAA,EAAA,SAAA,KAA2B,EAAkB,MAAM,UAAU,EAC7D,kBA3ByB,GAA4D,CACjF,KAAQ,YAAY,QAAU,EAElC,IAAI,CAAC,EAAW,CAId,EAAA,KACE,2KACF,EAEA,MACF,CAEA,EAAU,eAAe,CAFzB,CAGF,CAaA,CACF,EAmDa,EAAoB,GAAiD,CAChF,IAAM,EAAU,EAAQ,KAAA,EAAA,EAAA,eAAA,CAAqB,EAAQ,QAAU,OAAO,EAChE,GAAA,EAAA,EAAA,eAAA,CAAyB,OAAO,EAChC,EAAS,EAAQ,QAAA,EAAA,EAAA,SAAA,KAAwB,IAAA,EAAS,EAMlD,EAAe,EAAQ,WAAA,EAAA,EAAA,SAAA,KAA2B,EAAQ,EAAO,KAAM,EAG7E,MAAO,CAAE,gBAAA,EAAA,EAAA,SAAA,KAF8B,EAAa,MAAQ,EAAU,IAE7D,EAAgB,UAAS,UAAS,cAAa,CAC1D,EA6Ba,EAAe,IAAwC,CAClE,GAAG,EAAqB,CAAO,EAC/B,GAAG,EAAiB,CAAO,CAC7B"}

package/dist/headless/field-base.d.ts

@@ -1,53 +1,6 @@
 import { type Readable } from '@vielzeug/ripple';
 export type ValidationTrigger = 'blur' | 'change' | 'input' | 'submit';
 export type ControlValidationMode = ValidationTrigger | undefined;
-/** Options shared by both `createTextField` and `createChoiceField`. */
-export type FieldOptions = {
-    disabled?: Readable<boolean | undefined>;
-    error?: Readable<string | undefined>;
-    /**
-     * Returns the underlying form field object used for validation triggering.
-     * Called lazily — safe to return `null` before the first render.
-     */
-    getFormField?: () => {
-        reportValidity(): void;
-    } | null;
-    /**
-     * Override for label visibility that takes precedence over deriving it from
-     * the `label` text signal. Pass a computed signal that checks both prop and
-     * slot presence to enable slot-first composition.
-     *
-     * @example
-     * ```ts
-     * const hasLabel = computed(() => !!props.label.value || slots.has('label').value);
-     * const field = createField({ ...options, hasLabel });
-     * ```
-     */
-    hasLabel?: Readable<boolean>;
-    helper?: Readable<string | undefined>;
-    /**
-     * When provided, used directly as `fieldId` instead of generating one via
-     * `createStableId`. Useful in tests for deterministic ID assertions.
-     */
-    id?: string;
-    /**
-     * Label text signal. When provided, `labelVisible` and `ariaLabelledBy` are
-     * computed reactively from this value (see `hasLabel` for the slot-first override).
-     */
-    label?: Readable<string | undefined>;
-    /**
-     * Label placement signal. Defaults to `'inset'`.
-     *
-     * Not currently consumed by `createField()` itself — visibility is driven
-     * solely by `hasLabel`/`label`. Threaded through so component authors can
-     * apply placement-specific styling (`label-placement` attribute) without a
-     * second prop; if placement-dependent visibility is ever needed, wire it
-     * into `labelVisible$` in `createField()` instead of adding a new option.
-     */
-    labelPlacement?: Readable<LabelPlacement>;
-    prefix?: string;
-    validateOn?: Readable<ControlValidationMode>;
-};
 export type ErrorHelperState = {
     errorText: string;
     helperText: string;
@@ -77,72 +30,132 @@ export type CounterOptions = {
  * ```
  */
 export declare const createCounterState: (options: CounterOptions) => Readable<CounterState>;
-export type LabelPlacement = 'inset' | 'outside' | undefined;
 /**
- * Common handle returned by `createField` — the base for both `TextFieldHandle`
- * and `ChoiceFieldHandle`.
- *
- * ARIA signals and label state are flat on the handle — no nested `aria` or
- * `label` sub-objects.
+ * The single implementation of "which modifier class does this counter state map to" —
+ * every field with a character counter (`ore-input`, `ore-textarea`, `ore-message-composer`)
+ * renders the identical near-limit/at-limit styling, so this is the one place that decides it.
  *
  * @example
- * ```html
- * <label id="${labelId}" ?hidden="${() => !labelVisible.value}">...</label>
- * <input
- *   :aria-labelledby="${ariaLabelledBy}"
- *   :aria-describedby="${ariaDescribedBy}"
- *   :aria-invalid="${ariaInvalid}" />
+ * ```ts
+ * html`<span class="${() => counterClassName(counter?.value)}">...</span>`
  * ```
  */
-/** Flat ARIA attribute bag ready to spread into a template bind call. */
-export type AriaProps = {
-    'aria-describedby': string | null;
-    'aria-errormessage': string | null;
-    'aria-invalid': 'true' | null;
-    'aria-labelledby': string | null;
-};
-export type FieldHandle = {
+export declare const counterClassName: (counter: CounterState | undefined, base?: string) => string;
+export type LabelPlacement = 'inset' | 'outside' | undefined;
+/**
+ * A field's error/helper/disabled/validation-trigger state — everything an input
+ * needs *except* a visible `<label>`. Split out from label state (below) because
+ * not every field has one: `ore-message-composer` names itself via `aria-label`
+ * (a chat composer's accessible name conventionally comes from context/placeholder,
+ * not a floating `<label>`), so it composes this directly instead of pulling in
+ * label plumbing it can't use. `createField()` composes both for fields that do
+ * render a `<label>`.
+ */
+export type AssistiveStateHandle = {
     /** `aria-describedby` value. Non-null when helper or error text is present. */
     ariaDescribedBy: Readable<string | null>;
     /** `aria-errormessage` value. Non-null when error text is present. */
     ariaErrorMessage: Readable<string | null>;
     /** `aria-invalid` value. `'true'` when error text is present, otherwise `null`. */
     ariaInvalid: Readable<'true' | null>;
-    /** `aria-labelledby` value. Non-null when a label is visible. */
-    ariaLabelledBy: Readable<string | null>;
-    /**
-     * Returns a snapshot of the four ARIA attributes as a plain object.
-     * Spread into a template bind call to avoid repeating each signal individually.
-     *
-     * @example
-     * ```ts
-     * bind(inputEl, { attr: field.ariaProps() });
-     * ```
-     */
-    ariaProps(): AriaProps;
     /**
      * The stable `id` used for `aria-describedby` on the input. Points at the
      * assistive-text region (covers both helper text and error text per WAI-ARIA).
      */
     assistiveId: string;
+    /**
+     * Registers the real form field handle (the return value of `useField()`) so that
+     * `triggerValidation()` can call its `reportValidity()`. See `TextFieldHandle.attachFormField`
+     * for why this is a post-hoc call instead of a constructor option — the same forward
+     * reference applies here for choice fields.
+     */
+    attachFormField: (formField: {
+        reportValidity(): void;
+    }) => void;
     disabled: Readable<boolean>;
     /** Stable `id` for the inline error message element (`aria-errormessage`). */
     errorId: string;
     /** Reactive error text. Empty string when no error is set. */
     errorText: Readable<string>;
-    fieldId: string;
     /** Reactive helper text. Empty string when no helper is set. */
     helperText: Readable<string>;
+    triggerValidation: (on: Extract<ValidationTrigger, 'blur' | 'change'>) => void;
+};
+export type AssistiveStateOptions = {
+    disabled?: Readable<boolean | undefined>;
+    error?: Readable<string | undefined>;
+    helper?: Readable<string | undefined>;
+    validateOn?: Readable<ControlValidationMode>;
+};
+export declare const createAssistiveState: (options: AssistiveStateOptions) => AssistiveStateHandle;
+export type LabelStateHandle = {
+    /** `aria-labelledby` value. Non-null when a label is visible. */
+    ariaLabelledBy: Readable<string | null>;
+    /** Stable `id` for the underlying form control — the `<label for="...">` target. */
+    fieldId: string;
     /** Stable `id` for the label element. Stamp this on your `<label id="...">`. */
     labelId: string;
     /** Whether the label should be visible. Use to toggle `hidden` on the `<label>`. */
     labelVisible: Readable<boolean>;
-    triggerValidation: (on: Extract<ValidationTrigger, 'blur' | 'change'>) => void;
 };
+export type LabelStateOptions = {
+    /**
+     * Override for label visibility that takes precedence over deriving it from
+     * the `label` text signal. Pass a computed signal that checks both prop and
+     * slot presence to enable slot-first composition.
+     *
+     * @example
+     * ```ts
+     * const hasLabel = computed(() => !!props.label.value || slots.has('label').value);
+     * const label = createLabelState({ ...options, hasLabel });
+     * ```
+     */
+    hasLabel?: Readable<boolean>;
+    /**
+     * When provided, used directly as `fieldId` instead of generating one via
+     * `createStableId`. Useful in tests for deterministic ID assertions.
+     */
+    id?: string;
+    /**
+     * Label text signal. When provided, `labelVisible` and `ariaLabelledBy` are
+     * computed reactively from this value (see `hasLabel` for the slot-first override).
+     */
+    label?: Readable<string | undefined>;
+    /**
+     * Label placement signal. Defaults to `'inset'`.
+     *
+     * Not consumed by `createLabelState()` itself — visibility is driven solely by
+     * `hasLabel`/`label`. Threaded through so component authors can apply
+     * placement-specific styling (`label-placement` attribute) without a second
+     * option; if placement-dependent visibility is ever needed, wire it into
+     * `labelVisible` here instead of adding a new option.
+     */
+    labelPlacement?: Readable<LabelPlacement>;
+    prefix?: string;
+};
+export declare const createLabelState: (options: LabelStateOptions) => LabelStateHandle;
 /**
- * Composes the field triad — IDs, assistive state, and label state — into a
- * single `FieldHandle`. Both `createTextField` and `createChoiceField` build
- * on top of this.
+ * Common handle returned by `createField` — the base for both `TextFieldHandle`
+ * and `ChoiceFieldHandle`. Composes `createAssistiveState` + `createLabelState`;
+ * call those directly instead if a field has no visible `<label>` (see
+ * `createAssistiveState`'s doc comment).
+ *
+ * ARIA signals and label state are flat on the handle — no nested `aria` or
+ * `label` sub-objects. `labelId`/`labelVisible`/`ariaLabelledBy` are always
+ * present but only meaningful when `label`/`hasLabel` was passed — omit both
+ * and they resolve to an always-hidden, unreferenced label.
+ *
+ * @example
+ * ```html
+ * <label id="${labelId}" ?hidden="${() => !labelVisible.value}">...</label>
+ * <input
+ *   :aria-labelledby="${ariaLabelledBy}"
+ *   :aria-describedby="${ariaDescribedBy}"
+ *   :aria-invalid="${ariaInvalid}" />
+ * ```
  */
+export type FieldHandle = AssistiveStateHandle & LabelStateHandle;
+/** Options shared by both `createTextField` and `createChoiceField`. */
+export type FieldOptions = AssistiveStateOptions & LabelStateOptions;
 export declare const createField: (options: FieldOptions) => FieldHandle;
 //# sourceMappingURL=field-base.d.ts.map

package/dist/headless/field-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field-base.d.ts","sourceRoot":"","sources":["../../src/headless/field-base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"field-base.d.ts","sourceRoot":"","sources":["../../src/headless/field-base.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAM3D,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AACvE,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAIlE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACvC,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,SAAS,kBAAkB,KAAG,QAAQ,CAAC,gBAAgB,CAIzF,CAAC;AAIN,sDAAsD;AACtD,MAAM,MAAM,YAAY,GAAG;IACzB,cAAc,EAAE,OAAO,CAAC;IACxB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,KAAK,EAAE,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACrC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,cAAc,KAAG,QAAQ,CAAC,YAAY,CAe9E,CAAC;AAEL;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,YAAY,GAAG,SAAS,EAAE,aAAgB,KAAG,MAQtF,CAAC;AAIF,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAI7D;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,+EAA+E;IAC/E,eAAe,EAAE,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,sEAAsE;IACtE,gBAAgB,EAAE,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1C,mFAAmF;IACnF,WAAW,EAAE,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACrC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,eAAe,EAAE,CAAC,SAAS,EAAE;QAAE,cAAc,IAAI,IAAI,CAAA;KAAE,KAAK,IAAI,CAAC;IACjE,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC5B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5B,gEAAgE;IAChE,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7B,iBAAiB,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,iBAAiB,EAAE,MAAM,GAAG,QAAQ,CAAC,KAAK,IAAI,CAAC;CAChF,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,QAAQ,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACtC,UAAU,CAAC,EAAE,QAAQ,CAAC,qBAAqB,CAAC,CAAC;CAC9C,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,SAAS,qBAAqB,KAAG,oBA8CrE,CAAC;AAIF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iEAAiE;IACjE,cAAc,EAAE,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxC,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC7B;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACrC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,SAAS,iBAAiB,KAAG,gBAa7D,CAAC;AAIF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,WAAW,GAAG,oBAAoB,GAAG,gBAAgB,CAAC;AAElE,wEAAwE;AACxE,MAAM,MAAM,YAAY,GAAG,qBAAqB,GAAG,iBAAiB,CAAC;AAErE,eAAO,MAAM,WAAW,GAAI,SAAS,YAAY,KAAG,WAGlD,CAAC"}

package/dist/headless/field-base.js

@@ -1,46 +1,57 @@
-import { createStableId as e } from "@vielzeug/ore";
-import { computed as t } from "@vielzeug/ripple";
+import { warn as e } from "../_dev.js";
+import { createStableId as t } from "@vielzeug/ore";
+import { computed as n } from "@vielzeug/ripple";
 //#region src/headless/field-base.ts
-var n = (e) => t(() => ({
+var r = (e) => n(() => ({
 	errorText: e.error?.value ?? "",
 	helperText: e.helper?.value ?? ""
-})), r = (e) => t(() => {
+})), i = (e) => n(() => {
 	let t = e.value?.value ?? "", n = e.maxLength?.value, r = Number(n), i = Number.isFinite(r) && r > 0 ? r : null, a = i !== null, o = a ? `${t.length} / ${i}` : "", s = a ? t.length / i : 0;
 	return {
 		counterAtLimit: a ? s >= 1 : !1,
 		counterNearLimit: a ? s >= .9 && s < 1 : !1,
 		counterText: o
 	};
-}), i = (r) => {
-	let i = t(() => !!r.disabled?.value), a = r.validateOn, o = r.id ?? e(r.prefix ?? "field"), s = e("helper"), c = (e) => {
-		a?.value === e && r.getFormField?.()?.reportValidity();
-	}, l = e("label"), u = e("error"), d = r.label ?? t(() => void 0), f = r.hasLabel ?? t(() => !!d.value), p = n({
-		error: r.error,
-		helper: r.helper
-	}), m = t(() => p.value.errorText || p.value.helperText ? s : null), h = t(() => p.value.errorText ? u : null), g = t(() => p.value.errorText ? "true" : null), _ = t(() => f.value ? l : null);
+}), a = (e, t = "counter") => e ? e.counterAtLimit ? `${t} at-limit` : e.counterNearLimit ? `${t} near-limit` : t : t, o = (i) => {
+	let a = n(() => !!i.disabled?.value), o = t("helper"), s = t("error"), c = r({
+		error: i.error,
+		helper: i.helper
+	}), l = n(() => c.value.errorText || c.value.helperText ? o : null), u = n(() => c.value.errorText ? s : null), d = n(() => c.value.errorText ? "true" : null), f = null;
 	return {
-		ariaDescribedBy: m,
-		ariaErrorMessage: h,
-		ariaInvalid: g,
-		ariaLabelledBy: _,
-		ariaProps: () => ({
-			"aria-describedby": m.value,
-			"aria-errormessage": h.value,
-			"aria-invalid": g.value,
-			"aria-labelledby": _.value
-		}),
-		assistiveId: s,
-		disabled: i,
-		errorId: u,
-		errorText: t(() => p.value.errorText),
-		fieldId: o,
-		helperText: t(() => p.value.helperText),
-		labelId: l,
-		labelVisible: f,
-		triggerValidation: c
+		ariaDescribedBy: l,
+		ariaErrorMessage: u,
+		ariaInvalid: d,
+		assistiveId: o,
+		attachFormField: (e) => {
+			f = e;
+		},
+		disabled: a,
+		errorId: s,
+		errorText: n(() => c.value.errorText),
+		helperText: n(() => c.value.helperText),
+		triggerValidation: (t) => {
+			if (i.validateOn?.value === t) {
+				if (!f) {
+					e("triggerValidation() called before attachFormField() — validation will not run. See createTextField()/createChoiceField()/createCheckable()'s attachFormField doc comment.");
+					return;
+				}
+				f.reportValidity();
+			}
+		}
 	};
-};
+}, s = (e) => {
+	let r = e.id ?? t(e.prefix ?? "field"), i = t("label"), a = e.label ?? n(() => void 0), o = e.hasLabel ?? n(() => !!a.value);
+	return {
+		ariaLabelledBy: n(() => o.value ? i : null),
+		fieldId: r,
+		labelId: i,
+		labelVisible: o
+	};
+}, c = (e) => ({
+	...o(e),
+	...s(e)
+});
 //#endregion
-export { r as createCounterState, n as createErrorHelperState, i as createField };
+export { a as counterClassName, o as createAssistiveState, i as createCounterState, r as createErrorHelperState, c as createField, s as createLabelState };
 
 //# sourceMappingURL=field-base.js.map

package/dist/headless/field-base.js.map

@@ -1 +1 @@
-{"version":3,"file":"field-base.js","names":[],"sources":["../../src/headless/field-base.ts"],"sourcesContent":["import { createStableId } from '@vielzeug/ore';\nimport { computed, type Readable } from '@vielzeug/ripple';\n\n// ── Validation / context types ────────────────────────────────────────────────\n\nexport type ValidationTrigger = 'blur' | 'change' | 'input' | 'submit';\nexport type ControlValidationMode = ValidationTrigger | undefined;\n\n// ── Field options + handle ───────────────────────────────────────────────────\n\n/** Options shared by both `createTextField` and `createChoiceField`. */\nexport type FieldOptions = {\n  disabled?: Readable<boolean | undefined>;\n  error?: Readable<string | undefined>;\n  /**\n   * Returns the underlying form field object used for validation triggering.\n   * Called lazily — safe to return `null` before the first render.\n   */\n  getFormField?: () => { reportValidity(): void } | null;\n  /**\n   * Override for label visibility that takes precedence over deriving it from\n   * the `label` text signal. Pass a computed signal that checks both prop and\n   * slot presence to enable slot-first composition.\n   *\n   * @example\n   * ```ts\n   * const hasLabel = computed(() => !!props.label.value || slots.has('label').value);\n   * const field = createField({ ...options, hasLabel });\n   * ```\n   */\n  hasLabel?: Readable<boolean>;\n  helper?: Readable<string | undefined>;\n  /**\n   * When provided, used directly as `fieldId` instead of generating one via\n   * `createStableId`. Useful in tests for deterministic ID assertions.\n   */\n  id?: string;\n  /**\n   * Label text signal. When provided, `labelVisible` and `ariaLabelledBy` are\n   * computed reactively from this value (see `hasLabel` for the slot-first override).\n   */\n  label?: Readable<string | undefined>;\n  /**\n   * Label placement signal. Defaults to `'inset'`.\n   *\n   * Not currently consumed by `createField()` itself — visibility is driven\n   * solely by `hasLabel`/`label`. Threaded through so component authors can\n   * apply placement-specific styling (`label-placement` attribute) without a\n   * second prop; if placement-dependent visibility is ever needed, wire it\n   * into `labelVisible$` in `createField()` instead of adding a new option.\n   */\n  labelPlacement?: Readable<LabelPlacement>;\n  prefix?: string;\n  validateOn?: Readable<ControlValidationMode>;\n};\n\n// ── Error/helper assistive state ──────────────────────────────────────────────\n\nexport type ErrorHelperState = {\n  errorText: string;\n  helperText: string;\n};\n\nexport type ErrorHelperOptions = {\n  error?: Readable<string | undefined>;\n  helper?: Readable<string | undefined>;\n};\n\nexport const createErrorHelperState = (options: ErrorHelperOptions): Readable<ErrorHelperState> =>\n  computed(() => ({\n    errorText: options.error?.value ?? '',\n    helperText: options.helper?.value ?? '',\n  }));\n\n// ── Counter state (opt-in) ─────────────────────────────────────────────────────\n\n/** Counter state for text fields with `maxLength`. */\nexport type CounterState = {\n  counterAtLimit: boolean;\n  counterNearLimit: boolean;\n  counterText: string;\n};\n\nexport type CounterOptions = {\n  maxLength?: Readable<number | undefined>;\n  value: Readable<string | undefined>;\n};\n\n/**\n * Creates a reactive counter state signal for text fields with `maxLength`.\n * Only call this when `maxLength` may be set — the state is genuinely opt-in.\n *\n * @example\n * ```ts\n * const counter = createCounterState({ value: tf.value, maxLength: props.maxlength });\n * ```\n */\nexport const createCounterState = (options: CounterOptions): Readable<CounterState> =>\n  computed<CounterState>(() => {\n    const value = options.value?.value ?? '';\n    const maxLength = options.maxLength?.value;\n    const parsedMaxLength = Number(maxLength);\n    const validMaxLength = Number.isFinite(parsedMaxLength) && parsedMaxLength > 0 ? parsedMaxLength : null;\n    const hasCounter = validMaxLength !== null;\n    const counterText = hasCounter ? `${value.length} / ${validMaxLength}` : '';\n    const ratio = hasCounter ? value.length / validMaxLength : 0;\n\n    return {\n      counterAtLimit: hasCounter ? ratio >= 1 : false,\n      counterNearLimit: hasCounter ? ratio >= 0.9 && ratio < 1 : false,\n      counterText,\n    };\n  });\n\n// ── Label placement ───────────────────────────────────────────────────────────\n\nexport type LabelPlacement = 'inset' | 'outside' | undefined;\n\n// ── Field handle ──────────────────────────────────────────────────────────────\n\n/**\n * Common handle returned by `createField` — the base for both `TextFieldHandle`\n * and `ChoiceFieldHandle`.\n *\n * ARIA signals and label state are flat on the handle — no nested `aria` or\n * `label` sub-objects.\n *\n * @example\n * ```html\n * <label id=\"${labelId}\" ?hidden=\"${() => !labelVisible.value}\">...</label>\n * <input\n *   :aria-labelledby=\"${ariaLabelledBy}\"\n *   :aria-describedby=\"${ariaDescribedBy}\"\n *   :aria-invalid=\"${ariaInvalid}\" />\n * ```\n */\n/** Flat ARIA attribute bag ready to spread into a template bind call. */\nexport type AriaProps = {\n  'aria-describedby': string | null;\n  'aria-errormessage': string | null;\n  'aria-invalid': 'true' | null;\n  'aria-labelledby': string | null;\n};\n\nexport type FieldHandle = {\n  /** `aria-describedby` value. Non-null when helper or error text is present. */\n  ariaDescribedBy: Readable<string | null>;\n  /** `aria-errormessage` value. Non-null when error text is present. */\n  ariaErrorMessage: Readable<string | null>;\n  /** `aria-invalid` value. `'true'` when error text is present, otherwise `null`. */\n  ariaInvalid: Readable<'true' | null>;\n  /** `aria-labelledby` value. Non-null when a label is visible. */\n  ariaLabelledBy: Readable<string | null>;\n  /**\n   * Returns a snapshot of the four ARIA attributes as a plain object.\n   * Spread into a template bind call to avoid repeating each signal individually.\n   *\n   * @example\n   * ```ts\n   * bind(inputEl, { attr: field.ariaProps() });\n   * ```\n   */\n  ariaProps(): AriaProps;\n  /**\n   * The stable `id` used for `aria-describedby` on the input. Points at the\n   * assistive-text region (covers both helper text and error text per WAI-ARIA).\n   */\n  assistiveId: string;\n  disabled: Readable<boolean>;\n  /** Stable `id` for the inline error message element (`aria-errormessage`). */\n  errorId: string;\n  /** Reactive error text. Empty string when no error is set. */\n  errorText: Readable<string>;\n  fieldId: string;\n  /** Reactive helper text. Empty string when no helper is set. */\n  helperText: Readable<string>;\n  /** Stable `id` for the label element. Stamp this on your `<label id=\"...\">`. */\n  labelId: string;\n  /** Whether the label should be visible. Use to toggle `hidden` on the `<label>`. */\n  labelVisible: Readable<boolean>;\n  triggerValidation: (on: Extract<ValidationTrigger, 'blur' | 'change'>) => void;\n};\n\n/**\n * Composes the field triad — IDs, assistive state, and label state — into a\n * single `FieldHandle`. Both `createTextField` and `createChoiceField` build\n * on top of this.\n */\nexport const createField = (options: FieldOptions): FieldHandle => {\n  // ── Core ──────────────────────────────────────────────────────────────────\n  const disabled = computed(() => Boolean(options.disabled?.value));\n  const validateOn = options.validateOn;\n  const fieldId = options.id ?? createStableId(options.prefix ?? 'field');\n  const assistiveId = createStableId('helper');\n\n  const triggerValidation = (on: Extract<ValidationTrigger, 'blur' | 'change'>): void => {\n    if (validateOn?.value === on) options.getFormField?.()?.reportValidity();\n  };\n\n  // ── Label + ARIA state ────────────────────────────────────────────────────\n  const labelId = createStableId('label');\n  const errorId = createStableId('error');\n\n  const label$ = options.label ?? computed(() => undefined);\n\n  // Slot-first composition: if the caller provides `hasLabel`, use it instead\n  // of deriving visibility purely from the label text signal. This allows\n  // components with a `<slot name=\"label\">` to stay visible even when the\n  // `label` prop is empty but a slotted label element is present.\n  const labelVisible$ = options.hasLabel ?? computed(() => Boolean(label$.value));\n\n  const resolvedAssistive = createErrorHelperState({ error: options.error, helper: options.helper });\n\n  const ariaDescribedBy = computed(() =>\n    resolvedAssistive.value.errorText || resolvedAssistive.value.helperText ? assistiveId : null,\n  );\n  const ariaErrorMessage = computed(() => (resolvedAssistive.value.errorText ? errorId : null));\n  const ariaInvalid = computed<'true' | null>(() => (resolvedAssistive.value.errorText ? 'true' : null));\n  const ariaLabelledBy = computed(() => (labelVisible$.value ? labelId : null));\n\n  return {\n    ariaDescribedBy,\n    ariaErrorMessage,\n    ariaInvalid,\n    ariaLabelledBy,\n    ariaProps: () => ({\n      'aria-describedby': ariaDescribedBy.value,\n      'aria-errormessage': ariaErrorMessage.value,\n      'aria-invalid': ariaInvalid.value,\n      'aria-labelledby': ariaLabelledBy.value,\n    }),\n    assistiveId,\n    disabled,\n    errorId,\n    errorText: computed(() => resolvedAssistive.value.errorText),\n    fieldId,\n    helperText: computed(() => resolvedAssistive.value.helperText),\n    labelId,\n    labelVisible: labelVisible$,\n    triggerValidation,\n  };\n};\n"],"mappings":";;;AAoEA,IAAa,KAA0B,MACrC,SAAgB;CACd,WAAW,EAAQ,OAAO,SAAS;CACnC,YAAY,EAAQ,QAAQ,SAAS;AACvC,EAAE,GAyBS,KAAsB,MACjC,QAA6B;CAC3B,IAAM,IAAQ,EAAQ,OAAO,SAAS,IAChC,IAAY,EAAQ,WAAW,OAC/B,IAAkB,OAAO,CAAS,GAClC,IAAiB,OAAO,SAAS,CAAe,KAAK,IAAkB,IAAI,IAAkB,MAC7F,IAAa,MAAmB,MAChC,IAAc,IAAa,GAAG,EAAM,OAAO,KAAK,MAAmB,IACnE,IAAQ,IAAa,EAAM,SAAS,IAAiB;CAE3D,OAAO;EACL,gBAAgB,IAAa,KAAS,IAAI;EAC1C,kBAAkB,IAAa,KAAS,MAAO,IAAQ,IAAI;EAC3D;CACF;AACF,CAAC,GA4EU,KAAe,MAAuC;CAEjE,IAAM,IAAW,QAAe,EAAQ,EAAQ,UAAU,KAAM,GAC1D,IAAa,EAAQ,YACrB,IAAU,EAAQ,MAAM,EAAe,EAAQ,UAAU,OAAO,GAChE,IAAc,EAAe,QAAQ,GAErC,KAAqB,MAA4D;EACrF,AAAI,GAAY,UAAU,KAAI,EAAQ,eAAe,CAAC,EAAE,eAAe;CACzE,GAGM,IAAU,EAAe,OAAO,GAChC,IAAU,EAAe,OAAO,GAEhC,IAAS,EAAQ,SAAS,QAAe,KAAA,CAAS,GAMlD,IAAgB,EAAQ,YAAY,QAAe,EAAQ,EAAO,KAAM,GAExE,IAAoB,EAAuB;EAAE,OAAO,EAAQ;EAAO,QAAQ,EAAQ;CAAO,CAAC,GAE3F,IAAkB,QACtB,EAAkB,MAAM,aAAa,EAAkB,MAAM,aAAa,IAAc,IAC1F,GACM,IAAmB,QAAgB,EAAkB,MAAM,YAAY,IAAU,IAAK,GACtF,IAAc,QAA+B,EAAkB,MAAM,YAAY,SAAS,IAAK,GAC/F,IAAiB,QAAgB,EAAc,QAAQ,IAAU,IAAK;CAE5E,OAAO;EACL;EACA;EACA;EACA;EACA,kBAAkB;GAChB,oBAAoB,EAAgB;GACpC,qBAAqB,EAAiB;GACtC,gBAAgB,EAAY;GAC5B,mBAAmB,EAAe;EACpC;EACA;EACA;EACA;EACA,WAAW,QAAe,EAAkB,MAAM,SAAS;EAC3D;EACA,YAAY,QAAe,EAAkB,MAAM,UAAU;EAC7D;EACA,cAAc;EACd;CACF;AACF"}
+{"version":3,"file":"field-base.js","names":[],"sources":["../../src/headless/field-base.ts"],"sourcesContent":["import { createStableId } from '@vielzeug/ore';\nimport { computed, type Readable } from '@vielzeug/ripple';\n\nimport { warn } from '../_dev';\n\n// ── Validation / context types ────────────────────────────────────────────────\n\nexport type ValidationTrigger = 'blur' | 'change' | 'input' | 'submit';\nexport type ControlValidationMode = ValidationTrigger | undefined;\n\n// ── Error/helper assistive state ──────────────────────────────────────────────\n\nexport type ErrorHelperState = {\n  errorText: string;\n  helperText: string;\n};\n\nexport type ErrorHelperOptions = {\n  error?: Readable<string | undefined>;\n  helper?: Readable<string | undefined>;\n};\n\nexport const createErrorHelperState = (options: ErrorHelperOptions): Readable<ErrorHelperState> =>\n  computed(() => ({\n    errorText: options.error?.value ?? '',\n    helperText: options.helper?.value ?? '',\n  }));\n\n// ── Counter state (opt-in) ─────────────────────────────────────────────────────\n\n/** Counter state for text fields with `maxLength`. */\nexport type CounterState = {\n  counterAtLimit: boolean;\n  counterNearLimit: boolean;\n  counterText: string;\n};\n\nexport type CounterOptions = {\n  maxLength?: Readable<number | undefined>;\n  value: Readable<string | undefined>;\n};\n\n/**\n * Creates a reactive counter state signal for text fields with `maxLength`.\n * Only call this when `maxLength` may be set — the state is genuinely opt-in.\n *\n * @example\n * ```ts\n * const counter = createCounterState({ value: tf.value, maxLength: props.maxlength });\n * ```\n */\nexport const createCounterState = (options: CounterOptions): Readable<CounterState> =>\n  computed<CounterState>(() => {\n    const value = options.value?.value ?? '';\n    const maxLength = options.maxLength?.value;\n    const parsedMaxLength = Number(maxLength);\n    const validMaxLength = Number.isFinite(parsedMaxLength) && parsedMaxLength > 0 ? parsedMaxLength : null;\n    const hasCounter = validMaxLength !== null;\n    const counterText = hasCounter ? `${value.length} / ${validMaxLength}` : '';\n    const ratio = hasCounter ? value.length / validMaxLength : 0;\n\n    return {\n      counterAtLimit: hasCounter ? ratio >= 1 : false,\n      counterNearLimit: hasCounter ? ratio >= 0.9 && ratio < 1 : false,\n      counterText,\n    };\n  });\n\n/**\n * The single implementation of \"which modifier class does this counter state map to\" —\n * every field with a character counter (`ore-input`, `ore-textarea`, `ore-message-composer`)\n * renders the identical near-limit/at-limit styling, so this is the one place that decides it.\n *\n * @example\n * ```ts\n * html`<span class=\"${() => counterClassName(counter?.value)}\">...</span>`\n * ```\n */\nexport const counterClassName = (counter: CounterState | undefined, base = 'counter'): string => {\n  if (!counter) return base;\n\n  if (counter.counterAtLimit) return `${base} at-limit`;\n\n  if (counter.counterNearLimit) return `${base} near-limit`;\n\n  return base;\n};\n\n// ── Label placement ───────────────────────────────────────────────────────────\n\nexport type LabelPlacement = 'inset' | 'outside' | undefined;\n\n// ── Assistive state (error/helper text, describedby/errormessage/invalid) ─────\n\n/**\n * A field's error/helper/disabled/validation-trigger state — everything an input\n * needs *except* a visible `<label>`. Split out from label state (below) because\n * not every field has one: `ore-message-composer` names itself via `aria-label`\n * (a chat composer's accessible name conventionally comes from context/placeholder,\n * not a floating `<label>`), so it composes this directly instead of pulling in\n * label plumbing it can't use. `createField()` composes both for fields that do\n * render a `<label>`.\n */\nexport type AssistiveStateHandle = {\n  /** `aria-describedby` value. Non-null when helper or error text is present. */\n  ariaDescribedBy: Readable<string | null>;\n  /** `aria-errormessage` value. Non-null when error text is present. */\n  ariaErrorMessage: Readable<string | null>;\n  /** `aria-invalid` value. `'true'` when error text is present, otherwise `null`. */\n  ariaInvalid: Readable<'true' | null>;\n  /**\n   * The stable `id` used for `aria-describedby` on the input. Points at the\n   * assistive-text region (covers both helper text and error text per WAI-ARIA).\n   */\n  assistiveId: string;\n  /**\n   * Registers the real form field handle (the return value of `useField()`) so that\n   * `triggerValidation()` can call its `reportValidity()`. See `TextFieldHandle.attachFormField`\n   * for why this is a post-hoc call instead of a constructor option — the same forward\n   * reference applies here for choice fields.\n   */\n  attachFormField: (formField: { reportValidity(): void }) => void;\n  disabled: Readable<boolean>;\n  /** Stable `id` for the inline error message element (`aria-errormessage`). */\n  errorId: string;\n  /** Reactive error text. Empty string when no error is set. */\n  errorText: Readable<string>;\n  /** Reactive helper text. Empty string when no helper is set. */\n  helperText: Readable<string>;\n  triggerValidation: (on: Extract<ValidationTrigger, 'blur' | 'change'>) => void;\n};\n\nexport type AssistiveStateOptions = {\n  disabled?: Readable<boolean | undefined>;\n  error?: Readable<string | undefined>;\n  helper?: Readable<string | undefined>;\n  validateOn?: Readable<ControlValidationMode>;\n};\n\nexport const createAssistiveState = (options: AssistiveStateOptions): AssistiveStateHandle => {\n  const disabled = computed(() => Boolean(options.disabled?.value));\n  const assistiveId = createStableId('helper');\n  const errorId = createStableId('error');\n  const resolvedAssistive = createErrorHelperState({ error: options.error, helper: options.helper });\n\n  const ariaDescribedBy = computed(() =>\n    resolvedAssistive.value.errorText || resolvedAssistive.value.helperText ? assistiveId : null,\n  );\n  const ariaErrorMessage = computed(() => (resolvedAssistive.value.errorText ? errorId : null));\n  const ariaInvalid = computed<'true' | null>(() => (resolvedAssistive.value.errorText ? 'true' : null));\n\n  let formField: { reportValidity(): void } | null = null;\n  const attachFormField = (nextFormField: { reportValidity(): void }): void => {\n    formField = nextFormField;\n  };\n\n  const triggerValidation = (on: Extract<ValidationTrigger, 'blur' | 'change'>): void => {\n    if (options.validateOn?.value !== on) return;\n\n    if (!formField) {\n      // Not user-facing — this only fires when a component author wired `validateOn` but\n      // forgot the matching `attachFormField(useField(...))` call, so validation silently\n      // never runs instead of erroring where the mistake actually is.\n      warn(\n        \"triggerValidation() called before attachFormField() — validation will not run. See createTextField()/createChoiceField()/createCheckable()'s attachFormField doc comment.\",\n      );\n\n      return;\n    }\n\n    formField.reportValidity();\n  };\n\n  return {\n    ariaDescribedBy,\n    ariaErrorMessage,\n    ariaInvalid,\n    assistiveId,\n    attachFormField,\n    disabled,\n    errorId,\n    errorText: computed(() => resolvedAssistive.value.errorText),\n    helperText: computed(() => resolvedAssistive.value.helperText),\n    triggerValidation,\n  };\n};\n\n// ── Label state (visible `<label>` + `aria-labelledby`) ────────────────────────\n\nexport type LabelStateHandle = {\n  /** `aria-labelledby` value. Non-null when a label is visible. */\n  ariaLabelledBy: Readable<string | null>;\n  /** Stable `id` for the underlying form control — the `<label for=\"...\">` target. */\n  fieldId: string;\n  /** Stable `id` for the label element. Stamp this on your `<label id=\"...\">`. */\n  labelId: string;\n  /** Whether the label should be visible. Use to toggle `hidden` on the `<label>`. */\n  labelVisible: Readable<boolean>;\n};\n\nexport type LabelStateOptions = {\n  /**\n   * Override for label visibility that takes precedence over deriving it from\n   * the `label` text signal. Pass a computed signal that checks both prop and\n   * slot presence to enable slot-first composition.\n   *\n   * @example\n   * ```ts\n   * const hasLabel = computed(() => !!props.label.value || slots.has('label').value);\n   * const label = createLabelState({ ...options, hasLabel });\n   * ```\n   */\n  hasLabel?: Readable<boolean>;\n  /**\n   * When provided, used directly as `fieldId` instead of generating one via\n   * `createStableId`. Useful in tests for deterministic ID assertions.\n   */\n  id?: string;\n  /**\n   * Label text signal. When provided, `labelVisible` and `ariaLabelledBy` are\n   * computed reactively from this value (see `hasLabel` for the slot-first override).\n   */\n  label?: Readable<string | undefined>;\n  /**\n   * Label placement signal. Defaults to `'inset'`.\n   *\n   * Not consumed by `createLabelState()` itself — visibility is driven solely by\n   * `hasLabel`/`label`. Threaded through so component authors can apply\n   * placement-specific styling (`label-placement` attribute) without a second\n   * option; if placement-dependent visibility is ever needed, wire it into\n   * `labelVisible` here instead of adding a new option.\n   */\n  labelPlacement?: Readable<LabelPlacement>;\n  prefix?: string;\n};\n\nexport const createLabelState = (options: LabelStateOptions): LabelStateHandle => {\n  const fieldId = options.id ?? createStableId(options.prefix ?? 'field');\n  const labelId = createStableId('label');\n  const label$ = options.label ?? computed(() => undefined);\n\n  // Slot-first composition: if the caller provides `hasLabel`, use it instead\n  // of deriving visibility purely from the label text signal. This allows\n  // components with a `<slot name=\"label\">` to stay visible even when the\n  // `label` prop is empty but a slotted label element is present.\n  const labelVisible = options.hasLabel ?? computed(() => Boolean(label$.value));\n  const ariaLabelledBy = computed(() => (labelVisible.value ? labelId : null));\n\n  return { ariaLabelledBy, fieldId, labelId, labelVisible };\n};\n\n// ── Field handle (assistive + label, composed) ──────────────────────────────\n\n/**\n * Common handle returned by `createField` — the base for both `TextFieldHandle`\n * and `ChoiceFieldHandle`. Composes `createAssistiveState` + `createLabelState`;\n * call those directly instead if a field has no visible `<label>` (see\n * `createAssistiveState`'s doc comment).\n *\n * ARIA signals and label state are flat on the handle — no nested `aria` or\n * `label` sub-objects. `labelId`/`labelVisible`/`ariaLabelledBy` are always\n * present but only meaningful when `label`/`hasLabel` was passed — omit both\n * and they resolve to an always-hidden, unreferenced label.\n *\n * @example\n * ```html\n * <label id=\"${labelId}\" ?hidden=\"${() => !labelVisible.value}\">...</label>\n * <input\n *   :aria-labelledby=\"${ariaLabelledBy}\"\n *   :aria-describedby=\"${ariaDescribedBy}\"\n *   :aria-invalid=\"${ariaInvalid}\" />\n * ```\n */\nexport type FieldHandle = AssistiveStateHandle & LabelStateHandle;\n\n/** Options shared by both `createTextField` and `createChoiceField`. */\nexport type FieldOptions = AssistiveStateOptions & LabelStateOptions;\n\nexport const createField = (options: FieldOptions): FieldHandle => ({\n  ...createAssistiveState(options),\n  ...createLabelState(options),\n});\n"],"mappings":";;;;AAsBA,IAAa,KAA0B,MACrC,SAAgB;CACd,WAAW,EAAQ,OAAO,SAAS;CACnC,YAAY,EAAQ,QAAQ,SAAS;AACvC,EAAE,GAyBS,KAAsB,MACjC,QAA6B;CAC3B,IAAM,IAAQ,EAAQ,OAAO,SAAS,IAChC,IAAY,EAAQ,WAAW,OAC/B,IAAkB,OAAO,CAAS,GAClC,IAAiB,OAAO,SAAS,CAAe,KAAK,IAAkB,IAAI,IAAkB,MAC7F,IAAa,MAAmB,MAChC,IAAc,IAAa,GAAG,EAAM,OAAO,KAAK,MAAmB,IACnE,IAAQ,IAAa,EAAM,SAAS,IAAiB;CAE3D,OAAO;EACL,gBAAgB,IAAa,KAAS,IAAI;EAC1C,kBAAkB,IAAa,KAAS,MAAO,IAAQ,IAAI;EAC3D;CACF;AACF,CAAC,GAYU,KAAoB,GAAmC,IAAO,cACpE,IAED,EAAQ,iBAAuB,GAAG,EAAK,aAEvC,EAAQ,mBAAyB,GAAG,EAAK,eAEtC,IANc,GA4DV,KAAwB,MAAyD;CAC5F,IAAM,IAAW,QAAe,EAAQ,EAAQ,UAAU,KAAM,GAC1D,IAAc,EAAe,QAAQ,GACrC,IAAU,EAAe,OAAO,GAChC,IAAoB,EAAuB;EAAE,OAAO,EAAQ;EAAO,QAAQ,EAAQ;CAAO,CAAC,GAE3F,IAAkB,QACtB,EAAkB,MAAM,aAAa,EAAkB,MAAM,aAAa,IAAc,IAC1F,GACM,IAAmB,QAAgB,EAAkB,MAAM,YAAY,IAAU,IAAK,GACtF,IAAc,QAA+B,EAAkB,MAAM,YAAY,SAAS,IAAK,GAEjG,IAA+C;CAsBnD,OAAO;EACL;EACA;EACA;EACA;EACA,kBA1BuB,MAAoD;GAC3E,IAAY;EACd;EAyBE;EACA;EACA,WAAW,QAAe,EAAkB,MAAM,SAAS;EAC3D,YAAY,QAAe,EAAkB,MAAM,UAAU;EAC7D,oBA3ByB,MAA4D;GACjF,MAAQ,YAAY,UAAU,GAElC;QAAI,CAAC,GAAW;KAId,EACE,2KACF;KAEA;IACF;IAEA,EAAU,eAAe;GAFzB;EAGF;CAaA;AACF,GAmDa,KAAoB,MAAiD;CAChF,IAAM,IAAU,EAAQ,MAAM,EAAe,EAAQ,UAAU,OAAO,GAChE,IAAU,EAAe,OAAO,GAChC,IAAS,EAAQ,SAAS,QAAe,KAAA,CAAS,GAMlD,IAAe,EAAQ,YAAY,QAAe,EAAQ,EAAO,KAAM;CAG7E,OAAO;EAAE,gBAFc,QAAgB,EAAa,QAAQ,IAAU,IAE7D;EAAgB;EAAS;EAAS;CAAa;AAC1D,GA6Ba,KAAe,OAAwC;CAClE,GAAG,EAAqB,CAAO;CAC/B,GAAG,EAAiB,CAAO;AAC7B"}

package/dist/headless/index.d.ts

@@ -1,8 +1,10 @@
 export { lifecycleSignal } from './ore';
-export { createErrorHelperState, type AriaProps, type ControlValidationMode, type CounterOptions, type CounterState, type ErrorHelperOptions, type ErrorHelperState, type FieldHandle, type FieldOptions, type LabelPlacement, type ValidationTrigger, } from './field-base';
+export { createAutoResize, type AutoResizeControl, type AutoResizeOptions } from './auto-resize';
+export { counterClassName, createAssistiveState, createErrorHelperState, createField, createLabelState, type AssistiveStateHandle, type AssistiveStateOptions, type ControlValidationMode, type CounterOptions, type CounterState, type ErrorHelperOptions, type ErrorHelperState, type FieldHandle, type FieldOptions, type LabelPlacement, type LabelStateHandle, type LabelStateOptions, type ValidationTrigger, } from './field-base';
 export { createTextField, type TextFieldDetach, type TextFieldHandle, type TextFieldOptions } from './text-field';
 export { createChoiceField, type ChoiceChangeDetail, type ChoiceFieldHandle, type ChoiceFieldOptions, } from './choice-field';
 export { createCheckable, type CheckableChangePayload, type CheckableHandle, type CheckableOptions } from './checkable';
+export { createComposerControl, type ComposerControl, type ComposerControlOptions, type SendShortcut, } from './composer';
 export { type DialogCloseReason, type DropdownCloseReason, type OverlayCloseDetail, type OverlayControl, type OverlayOpenDetail, type OverlayOpenReason, } from './overlay';
 export { createOptionList, type BaseOptionItem, type OptionListHandle, type OptionListOptions, type PlacementOptions, } from './option-list';
 export { createPaginatedList, type PaginatedListHandle, type PaginatedListOptions } from './paginated-list';

package/dist/headless/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/headless/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/headless/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAGxC,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGjG,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EACX,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGlH,OAAO,EACL,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGxH,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG5G,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAGtE,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAGlG,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAG9F,OAAO,EACL,kBAAkB,EAClB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,QAAQ,EAAE,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAGtF,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,QAAQ,GACd,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,wBAAwB,EAAE,KAAK,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAGnH,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGpE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG7E,OAAO,EACL,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,wBAAwB,EAAE,KAAK,yBAAyB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAChH,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,KAAK,qBAAqB,EAAE,MAAM,OAAO,CAAC;AACxF,OAAO,EAAE,oBAAoB,EAAE,KAAK,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAClH,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC"}

package/dist/headless/text-field.cjs

@@ -1,2 +1,2 @@
-const e=require("./field-base.cjs"),t=require("./signals.cjs");require("@vielzeug/ripple");var n=n=>{let r=t.syncedSignal(n.value,n.signal,e=>String(e??``)),i=e.createField(n),a=n.maxLength?e.createCounterState({maxLength:n.maxLength,value:r}):null,o=e=>{e?.preventDefault?.(),r.value=``,n.onInput?.(e??new InputEvent(`input`,{bubbles:!0}),``),n.onChange?.(e??new Event(`change`,{bubbles:!0}),``),i.triggerValidation(`change`)},s=(e,t)=>{let a=[],o=(t,n)=>{e.addEventListener(t,n),a.push(()=>e.removeEventListener(t,n))};n.onFocus&&o(`focus`,e=>n.onFocus(e)),o(`input`,t=>{t.stopPropagation(),n.onBeforeInput?.(t),r.value=e.value,n.onInput?.(t,e.value)}),o(`change`,t=>{t.stopPropagation(),r.value=e.value,n.onChange?.(t,e.value),i.triggerValidation(`change`)}),o(`blur`,e=>{n.onBlur?.(e),i.triggerValidation(`blur`)});let s=!1,c=()=>{if(!s){s=!0;for(let e of a)e()}};return t?.addEventListener(`abort`,c,{once:!0}),c};return{...i,clear:o,counter:a,value:r,wire:s}};exports.createTextField=n;
+const e=require("./field-base.cjs"),t=require("./signals.cjs");let n=require("@vielzeug/ripple");var r=e=>e.trim()===``,i=e=>String(e??``),a=a=>{let o=t.syncedSignal(a.value,a.signal,i),s=e.createField(a),c=a.maxLength?e.createCounterState({maxLength:a.maxLength,value:o}):null,l=(0,n.computed)(()=>!a.readonly?.value&&a.required?.value&&r(o.value)?{valueMissing:!0}:null),u=(0,n.computed)(()=>l.value?a.requiredMessage?.value||`This field is required.`:``),d=()=>{o.value=i(a.value.value),s.triggerValidation(`change`)},f=e=>{e?.preventDefault?.(),o.value=``,a.onInput?.(e??new InputEvent(`input`,{bubbles:!0}),``),a.onChange?.(e??new Event(`change`,{bubbles:!0}),``),s.triggerValidation(`change`)},p=(e,t)=>{let n=[],r=(t,r)=>{e.addEventListener(t,r),n.push(()=>e.removeEventListener(t,r))};a.onFocus&&r(`focus`,e=>a.onFocus(e)),r(`input`,t=>{t.stopPropagation(),a.onBeforeInput?.(t),o.value=e.value,a.onInput?.(t,e.value)}),r(`change`,t=>{t.stopPropagation(),o.value=e.value,a.onChange?.(t,e.value),s.triggerValidation(`change`)}),r(`blur`,e=>{a.onBlur?.(e),s.triggerValidation(`blur`)});let i=!1,c=()=>{if(!i){i=!0;for(let e of n)e()}};return t?.addEventListener(`abort`,c,{once:!0}),c};return{...s,clear:f,counter:c,reset:d,validationMessage:u,validity:l,value:o,wire:p}};exports.createTextField=a;
 //# sourceMappingURL=text-field.cjs.map

package/dist/headless/text-field.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"text-field.cjs","names":[],"sources":["../../src/headless/text-field.ts"],"sourcesContent":["import { type Readable, type Signal } from '@vielzeug/ripple';\n\nimport { type CounterState, createCounterState, createField, type FieldHandle, type FieldOptions } from './field-base';\nimport { syncedSignal } from './signals';\n\n// ── Text field ────────────────────────────────────────────────────────────────\n\n/** Detach function returned by `wire()`. Call to remove element listeners. */\nexport type TextFieldDetach = () => void;\n\nexport type TextFieldOptions = FieldOptions & {\n  maxLength?: Readable<number | undefined>;\n  /**\n   * Called synchronously before value extraction on every input event.\n   * Use only for DOM side-effects (e.g. auto-resize measurement) that must\n   * run before the reactive value is updated.\n   */\n  onBeforeInput?: (event: Event) => void;\n  onBlur?: (event: FocusEvent) => void;\n  onChange?: (event: Event, value: string) => void;\n  onFocus?: (event: FocusEvent) => void;\n  onInput?: (event: Event, value: string) => void;\n  /** `AbortSignal` from the component lifecycle. The internal value-sync watcher is disposed on abort. */\n  signal: AbortSignal;\n  value: Readable<string | undefined>;\n};\n\nexport type TextFieldHandle = FieldHandle & {\n  /** Clears the field value and fires synthetic input/change events. */\n  clear: (event?: Event) => void;\n  /**\n   * Reactive counter state. Non-null when `maxLength` was provided; `null` otherwise.\n   * Components should only render a counter element when this is non-null.\n   */\n  counter: Readable<CounterState> | null;\n  /** The local mutable field value (two-way bound to the input element via `wire()`). */\n  value: Signal<string>;\n  /**\n   * Attaches event listeners to the underlying input or textarea element.\n   *\n   * When `signal` is provided, the listeners are detached automatically when\n   * the signal's controller calls `abort()`. Without a signal the returned\n   * `TextFieldDetach` must be called manually.\n   *\n   * Safe to call multiple times — each call attaches a fresh set of listeners\n   * and returns a distinct detach function. Calling detach multiple times is\n   * a no-op (guarded internally).\n   */\n  wire: (el: HTMLInputElement | HTMLTextAreaElement, signal?: AbortSignal) => TextFieldDetach;\n};\n\nexport const createTextField = (options: TextFieldOptions): TextFieldHandle => {\n  const value = syncedSignal(options.value, options.signal, (v) => String(v ?? ''));\n\n  const field = createField(options);\n  const counter = options.maxLength ? createCounterState({ maxLength: options.maxLength, value }) : null;\n\n  const clear = (event?: Event): void => {\n    event?.preventDefault?.();\n    value.value = '';\n    options.onInput?.(event ?? new InputEvent('input', { bubbles: true }), '');\n    options.onChange?.(event ?? new Event('change', { bubbles: true }), '');\n    field.triggerValidation('change');\n  };\n\n  const wire = (element: HTMLInputElement | HTMLTextAreaElement, signal?: AbortSignal): TextFieldDetach => {\n    const cleanups: Array<() => void> = [];\n    const on = (type: string, handler: EventListener): void => {\n      element.addEventListener(type, handler);\n      cleanups.push(() => element.removeEventListener(type, handler));\n    };\n\n    if (options.onFocus) {\n      on('focus', (e) => options.onFocus!(e as FocusEvent));\n    }\n\n    on('input', (e) => {\n      e.stopPropagation();\n      options.onBeforeInput?.(e);\n      value.value = element.value;\n      options.onInput?.(e, element.value);\n    });\n\n    on('change', (e) => {\n      e.stopPropagation();\n      value.value = element.value;\n      options.onChange?.(e, element.value);\n      field.triggerValidation('change');\n    });\n\n    on('blur', (e) => {\n      options.onBlur?.(e as FocusEvent);\n      field.triggerValidation('blur');\n    });\n\n    let detached = false;\n    const detach = (): void => {\n      if (detached) return;\n\n      detached = true;\n      for (const dispose of cleanups) dispose();\n    };\n\n    signal?.addEventListener('abort', detach, { once: true });\n\n    return detach;\n  };\n\n  return { ...field, clear, counter, value, wire };\n};\n"],"mappings":"2FAmDA,IAAa,EAAmB,GAA+C,CAC7E,IAAM,EAAQ,EAAA,aAAa,EAAQ,MAAO,EAAQ,OAAS,GAAM,OAAO,GAAK,EAAE,CAAC,EAE1E,EAAQ,EAAA,YAAY,CAAO,EAC3B,EAAU,EAAQ,UAAY,EAAA,mBAAmB,CAAE,UAAW,EAAQ,UAAW,OAAM,CAAC,EAAI,KAE5F,EAAS,GAAwB,CACrC,GAAO,iBAAiB,EACxB,EAAM,MAAQ,GACd,EAAQ,UAAU,GAAS,IAAI,WAAW,QAAS,CAAE,QAAS,EAAK,CAAC,EAAG,EAAE,EACzE,EAAQ,WAAW,GAAS,IAAI,MAAM,SAAU,CAAE,QAAS,EAAK,CAAC,EAAG,EAAE,EACtE,EAAM,kBAAkB,QAAQ,CAClC,EAEM,GAAQ,EAAiD,IAA0C,CACvG,IAAM,EAA8B,CAAC,EAC/B,GAAM,EAAc,IAAiC,CACzD,EAAQ,iBAAiB,EAAM,CAAO,EACtC,EAAS,SAAW,EAAQ,oBAAoB,EAAM,CAAO,CAAC,CAChE,EAEI,EAAQ,SACV,EAAG,QAAU,GAAM,EAAQ,QAAS,CAAe,CAAC,EAGtD,EAAG,QAAU,GAAM,CACjB,EAAE,gBAAgB,EAClB,EAAQ,gBAAgB,CAAC,EACzB,EAAM,MAAQ,EAAQ,MACtB,EAAQ,UAAU,EAAG,EAAQ,KAAK,CACpC,CAAC,EAED,EAAG,SAAW,GAAM,CAClB,EAAE,gBAAgB,EAClB,EAAM,MAAQ,EAAQ,MACtB,EAAQ,WAAW,EAAG,EAAQ,KAAK,EACnC,EAAM,kBAAkB,QAAQ,CAClC,CAAC,EAED,EAAG,OAAS,GAAM,CAChB,EAAQ,SAAS,CAAe,EAChC,EAAM,kBAAkB,MAAM,CAChC,CAAC,EAED,IAAI,EAAW,GACT,MAAqB,CACrB,MAEJ,GAAW,GACX,IAAK,IAAM,KAAW,EAAU,EAAQ,CAD7B,CAEb,EAIA,OAFA,GAAQ,iBAAiB,QAAS,EAAQ,CAAE,KAAM,EAAK,CAAC,EAEjD,CACT,EAEA,MAAO,CAAE,GAAG,EAAO,QAAO,UAAS,QAAO,MAAK,CACjD"}
+{"version":3,"file":"text-field.cjs","names":[],"sources":["../../src/headless/text-field.ts"],"sourcesContent":["import { computed, type Readable, type Signal } from '@vielzeug/ripple';\n\nimport { type CounterState, createCounterState, createField, type FieldHandle, type FieldOptions } from './field-base';\nimport { syncedSignal } from './signals';\n\n// ── Text field ────────────────────────────────────────────────────────────────\n\n/** Detach function returned by `wire()`. Call to remove element listeners. */\nexport type TextFieldDetach = () => void;\n\nexport type TextFieldOptions = FieldOptions & {\n  maxLength?: Readable<number | undefined>;\n  /**\n   * Called synchronously before value extraction on every input event.\n   * Use only for DOM side-effects (e.g. auto-resize measurement) that must\n   * run before the reactive value is updated.\n   */\n  onBeforeInput?: (event: Event) => void;\n  onBlur?: (event: FocusEvent) => void;\n  onChange?: (event: Event, value: string) => void;\n  onFocus?: (event: FocusEvent) => void;\n  onInput?: (event: Event, value: string) => void;\n  /**\n   * Bars the field from constraint validation while true — matches the native HTML rule that a\n   * `readonly` field is never a candidate for constraint validation (a `readonly required`\n   * field is always valid, per spec), so `validity`/`validationMessage` don't feed a false\n   * `valueMissing` into `useField()` just because a read-only field happens to be blank.\n   */\n  readonly?: Readable<boolean | undefined>;\n  /** Marks a blank value invalid — feeds `validity`/`validationMessage` (see below). */\n  required?: Readable<boolean | undefined>;\n  /** Message for the blank+required case. Defaults to `'This field is required.'`. */\n  requiredMessage?: Readable<string | undefined>;\n  /** `AbortSignal` from the component lifecycle. The internal value-sync watcher is disposed on abort. */\n  signal: AbortSignal;\n  value: Readable<string | undefined>;\n};\n\nexport type TextFieldHandle = FieldHandle & {\n  /**\n   * Registers the real form field handle (the return value of `useField()`) so that\n   * `triggerValidation()` — called internally on blur/change — can call its\n   * `reportValidity()`. `useField()` itself needs `value` (below) to exist first, so this\n   * is a two-step wiring rather than a constructor option:\n   *\n   * ```ts\n   * const tf = createTextField({ value: props.value, ... });\n   * const formField = useField({ value: tf.value, ... });\n   * tf.attachFormField(formField);\n   * ```\n   */\n  attachFormField: (formField: { reportValidity(): void }) => void;\n  /** Clears the field value and fires synthetic input/change events. */\n  clear: (event?: Event) => void;\n  /**\n   * Reactive counter state. Non-null when `maxLength` was provided; `null` otherwise.\n   * Components should only render a counter element when this is non-null.\n   */\n  counter: Readable<CounterState> | null;\n  /**\n   * Restores the value to whatever the `value` option currently holds (native form\n   * `reset()` semantics: a `<input>` reverts to its *current* `value` content attribute,\n   * not a frozen snapshot from element creation — so setting the attribute programmatically\n   * after mount changes what a later reset reverts to). Wire into `useField({ onReset: tf.reset })`.\n   */\n  reset: () => void;\n  /** Reactive validation message paired with `validity`. Empty string when valid. */\n  validationMessage: Readable<string>;\n  /**\n   * Reactive `ValidityStateFlags` — `{ valueMissing: true }` while `required` and blank,\n   * `null` (valid) otherwise. Pass straight to `useField({ validity: tf.validity })`.\n   */\n  validity: Readable<ValidityStateFlags | null>;\n  /** The local mutable field value (two-way bound to the input element via `wire()`). */\n  value: Signal<string>;\n  /**\n   * Attaches event listeners to the underlying input or textarea element.\n   *\n   * When `signal` is provided, the listeners are detached automatically when\n   * the signal's controller calls `abort()`. Without a signal the returned\n   * `TextFieldDetach` must be called manually.\n   *\n   * Safe to call multiple times — each call attaches a fresh set of listeners\n   * and returns a distinct detach function. Calling detach multiple times is\n   * a no-op (guarded internally).\n   */\n  wire: (el: HTMLInputElement | HTMLTextAreaElement, signal?: AbortSignal) => TextFieldDetach;\n};\n\nconst isBlank = (value: string): boolean => value.trim() === '';\nconst toFieldValue = (v: string | undefined): string => String(v ?? '');\n\nexport const createTextField = (options: TextFieldOptions): TextFieldHandle => {\n  const value = syncedSignal(options.value, options.signal, toFieldValue);\n\n  const field = createField(options);\n  const counter = options.maxLength ? createCounterState({ maxLength: options.maxLength, value }) : null;\n\n  const validity = computed<ValidityStateFlags | null>(() =>\n    !options.readonly?.value && options.required?.value && isBlank(value.value) ? { valueMissing: true } : null,\n  );\n  const validationMessage = computed(() =>\n    validity.value ? options.requiredMessage?.value || 'This field is required.' : '',\n  );\n\n  const reset = (): void => {\n    value.value = toFieldValue(options.value.value);\n    field.triggerValidation('change');\n  };\n\n  const clear = (event?: Event): void => {\n    event?.preventDefault?.();\n    value.value = '';\n    options.onInput?.(event ?? new InputEvent('input', { bubbles: true }), '');\n    options.onChange?.(event ?? new Event('change', { bubbles: true }), '');\n    field.triggerValidation('change');\n  };\n\n  const wire = (element: HTMLInputElement | HTMLTextAreaElement, signal?: AbortSignal): TextFieldDetach => {\n    const cleanups: Array<() => void> = [];\n    const on = (type: string, handler: EventListener): void => {\n      element.addEventListener(type, handler);\n      cleanups.push(() => element.removeEventListener(type, handler));\n    };\n\n    if (options.onFocus) {\n      on('focus', (e) => options.onFocus!(e as FocusEvent));\n    }\n\n    on('input', (e) => {\n      e.stopPropagation();\n      options.onBeforeInput?.(e);\n      value.value = element.value;\n      options.onInput?.(e, element.value);\n    });\n\n    on('change', (e) => {\n      e.stopPropagation();\n      value.value = element.value;\n      options.onChange?.(e, element.value);\n      field.triggerValidation('change');\n    });\n\n    on('blur', (e) => {\n      options.onBlur?.(e as FocusEvent);\n      field.triggerValidation('blur');\n    });\n\n    let detached = false;\n    const detach = (): void => {\n      if (detached) return;\n\n      detached = true;\n      for (const dispose of cleanups) dispose();\n    };\n\n    signal?.addEventListener('abort', detach, { once: true });\n\n    return detach;\n  };\n\n  return { ...field, clear, counter, reset, validationMessage, validity, value, wire };\n};\n"],"mappings":"iGAyFA,IAAM,EAAW,GAA2B,EAAM,KAAK,IAAM,GACvD,EAAgB,GAAkC,OAAO,GAAK,EAAE,EAEzD,EAAmB,GAA+C,CAC7E,IAAM,EAAQ,EAAA,aAAa,EAAQ,MAAO,EAAQ,OAAQ,CAAY,EAEhE,EAAQ,EAAA,YAAY,CAAO,EAC3B,EAAU,EAAQ,UAAY,EAAA,mBAAmB,CAAE,UAAW,EAAQ,UAAW,OAAM,CAAC,EAAI,KAE5F,GAAA,EAAA,EAAA,SAAA,KACJ,CAAC,EAAQ,UAAU,OAAS,EAAQ,UAAU,OAAS,EAAQ,EAAM,KAAK,EAAI,CAAE,aAAc,EAAK,EAAI,IACzG,EACM,GAAA,EAAA,EAAA,SAAA,KACJ,EAAS,MAAQ,EAAQ,iBAAiB,OAAS,0BAA4B,EACjF,EAEM,MAAoB,CACxB,EAAM,MAAQ,EAAa,EAAQ,MAAM,KAAK,EAC9C,EAAM,kBAAkB,QAAQ,CAClC,EAEM,EAAS,GAAwB,CACrC,GAAO,iBAAiB,EACxB,EAAM,MAAQ,GACd,EAAQ,UAAU,GAAS,IAAI,WAAW,QAAS,CAAE,QAAS,EAAK,CAAC,EAAG,EAAE,EACzE,EAAQ,WAAW,GAAS,IAAI,MAAM,SAAU,CAAE,QAAS,EAAK,CAAC,EAAG,EAAE,EACtE,EAAM,kBAAkB,QAAQ,CAClC,EAEM,GAAQ,EAAiD,IAA0C,CACvG,IAAM,EAA8B,CAAC,EAC/B,GAAM,EAAc,IAAiC,CACzD,EAAQ,iBAAiB,EAAM,CAAO,EACtC,EAAS,SAAW,EAAQ,oBAAoB,EAAM,CAAO,CAAC,CAChE,EAEI,EAAQ,SACV,EAAG,QAAU,GAAM,EAAQ,QAAS,CAAe,CAAC,EAGtD,EAAG,QAAU,GAAM,CACjB,EAAE,gBAAgB,EAClB,EAAQ,gBAAgB,CAAC,EACzB,EAAM,MAAQ,EAAQ,MACtB,EAAQ,UAAU,EAAG,EAAQ,KAAK,CACpC,CAAC,EAED,EAAG,SAAW,GAAM,CAClB,EAAE,gBAAgB,EAClB,EAAM,MAAQ,EAAQ,MACtB,EAAQ,WAAW,EAAG,EAAQ,KAAK,EACnC,EAAM,kBAAkB,QAAQ,CAClC,CAAC,EAED,EAAG,OAAS,GAAM,CAChB,EAAQ,SAAS,CAAe,EAChC,EAAM,kBAAkB,MAAM,CAChC,CAAC,EAED,IAAI,EAAW,GACT,MAAqB,CACrB,MAEJ,GAAW,GACX,IAAK,IAAM,KAAW,EAAU,EAAQ,CAD7B,CAEb,EAIA,OAFA,GAAQ,iBAAiB,QAAS,EAAQ,CAAE,KAAM,EAAK,CAAC,EAEjD,CACT,EAEA,MAAO,CAAE,GAAG,EAAO,QAAO,UAAS,QAAO,oBAAmB,WAAU,QAAO,MAAK,CACrF"}

package/dist/headless/text-field.d.ts

@@ -14,11 +14,37 @@ export type TextFieldOptions = FieldOptions & {
     onChange?: (event: Event, value: string) => void;
     onFocus?: (event: FocusEvent) => void;
     onInput?: (event: Event, value: string) => void;
+    /**
+     * Bars the field from constraint validation while true — matches the native HTML rule that a
+     * `readonly` field is never a candidate for constraint validation (a `readonly required`
+     * field is always valid, per spec), so `validity`/`validationMessage` don't feed a false
+     * `valueMissing` into `useField()` just because a read-only field happens to be blank.
+     */
+    readonly?: Readable<boolean | undefined>;
+    /** Marks a blank value invalid — feeds `validity`/`validationMessage` (see below). */
+    required?: Readable<boolean | undefined>;
+    /** Message for the blank+required case. Defaults to `'This field is required.'`. */
+    requiredMessage?: Readable<string | undefined>;
     /** `AbortSignal` from the component lifecycle. The internal value-sync watcher is disposed on abort. */
     signal: AbortSignal;
     value: Readable<string | undefined>;
 };
 export type TextFieldHandle = FieldHandle & {
+    /**
+     * Registers the real form field handle (the return value of `useField()`) so that
+     * `triggerValidation()` — called internally on blur/change — can call its
+     * `reportValidity()`. `useField()` itself needs `value` (below) to exist first, so this
+     * is a two-step wiring rather than a constructor option:
+     *
+     * ```ts
+     * const tf = createTextField({ value: props.value, ... });
+     * const formField = useField({ value: tf.value, ... });
+     * tf.attachFormField(formField);
+     * ```
+     */
+    attachFormField: (formField: {
+        reportValidity(): void;
+    }) => void;
     /** Clears the field value and fires synthetic input/change events. */
     clear: (event?: Event) => void;
     /**
@@ -26,6 +52,20 @@ export type TextFieldHandle = FieldHandle & {
      * Components should only render a counter element when this is non-null.
      */
     counter: Readable<CounterState> | null;
+    /**
+     * Restores the value to whatever the `value` option currently holds (native form
+     * `reset()` semantics: a `<input>` reverts to its *current* `value` content attribute,
+     * not a frozen snapshot from element creation — so setting the attribute programmatically
+     * after mount changes what a later reset reverts to). Wire into `useField({ onReset: tf.reset })`.
+     */
+    reset: () => void;
+    /** Reactive validation message paired with `validity`. Empty string when valid. */
+    validationMessage: Readable<string>;
+    /**
+     * Reactive `ValidityStateFlags` — `{ valueMissing: true }` while `required` and blank,
+     * `null` (valid) otherwise. Pass straight to `useField({ validity: tf.validity })`.
+     */
+    validity: Readable<ValidityStateFlags | null>;
     /** The local mutable field value (two-way bound to the input element via `wire()`). */
     value: Signal<string>;
     /**