@vantageos/mosaic 0.2.2 → 0.3.0-alpha.1

package/dist/forms.d.ts

@@ -0,0 +1,159 @@
+import { M as MosaicFormMode, F as FieldErrorShape, I as InputType, a as MultiSelectOption, S as SelectOption } from './index-CwXVgtGb.js';
+export { C as Checkbox, b as CheckboxPropsSchema, c as CheckboxPropsValidated, D as DEFAULT_TEXTAREA_ROWS, E as ErrorDisplay, d as ErrorDisplayPropsSchema, e as FieldArray, f as FieldArrayPropsSchema, g as FieldErrorShapeSchema, h as FormField, i as FormFieldPropsSchema, j as FormProvider, k as FormProviderPropsSchema, l as Input, m as InputPropsSchema, n as InputPropsValidated, o as InputTypeSchema, p as MosaicFormModeSchema, q as MultiSelect, r as MultiSelectOptionSchema, s as MultiSelectPropsSchema, R as RadioGroup, t as RadioGroupOption, u as RadioGroupOptionSchema, v as RadioGroupPropsSchema, w as RadioGroupPropsValidated, x as RadioOrientation, y as Select, z as SelectOptionSchema, A as SelectPropsSchema, B as SelectPropsValidated, G as SubmitButton, H as SubmitButtonPropsSchema, T as Textarea, J as TextareaPropsSchema, K as TextareaPropsValidated, U as UseFieldArrayOptionsSchema, L as UseMosaicFormOptions, N as UseMosaicFormOptionsSchema, O as UseMosaicFormReturn, P as buildAddAriaLabel, Q as buildListAriaLabel, V as buildRemoveAriaLabel, W as clampToMaxLength, X as computeAutoResizeHeight, Y as findFirstEnabledIndex, Z as findLastEnabledIndex, _ as findNextEnabledIndex, $ as findSelectedIndex, a0 as getGroupClasses, a1 as getGroupLabelId, a2 as getNavKeys, a3 as getOptionDescriptionId, a4 as getOptionLabelId, a5 as getOptionRowClasses, a6 as getRadioControlClasses, a7 as getRovingTabIndex, a8 as isActivationKey, a9 as nextFocusIndexAfterRemove, aa as resolveAriaChecked, ab as resolveDescribedBy, ac as resolveRows, ad as useFieldArray, ae as useMosaicForm, af as useMosaicFormContext, ag as validateCheckboxProps, ah as validateOptions, ai as validateRadioGroupProps, aj as validateSelectProps, ak as validateSubmitButtonProps, al as validateTextareaProps } from './index-CwXVgtGb.js';
+import 'react-hook-form';
+import 'zod';
+import 'react/jsx-runtime';
+import 'react';
+
+/**
+ * Map Mosaic public mode → react-hook-form `mode` config value.
+ *
+ * RHF accepts the same three strings (`"onBlur" | "onChange" | "onSubmit"`)
+ * but a future Mosaic mode could be aliased here (e.g. `"realtime"` →
+ * `"onChange"`). Keeping the mapping in pure logic makes the hook itself
+ * trivial and unit-testable without a renderer.
+ */
+declare function toRhfMode(mode: MosaicFormMode): "onBlur" | "onChange" | "onSubmit";
+
+/**
+ * Shared error messages for the FormProvider runtime layer.
+ */
+declare const FORM_PROVIDER_CONTEXT_MISSING = "useMosaicFormContext must be used inside <FormProvider>. Wrap your tree with <FormProvider form={...}> from @vantageos/mosaic/{react,preact}/forms.";
+
+/**
+ * Pure helpers for FormField. Currently a placeholder for future
+ * cross-runtime logic (e.g. ARIA id generation, error aggregation).
+ */
+declare function buildFieldId(formName: string | undefined, fieldName: string): string;
+
+/**
+ * Pure formatter shared by React + Preact runtimes.
+ *
+ * Priority order:
+ *   1. `error.message` set by Zod/RHF → win (explicit wins).
+ *   2. `messageMap[error.type]` → consumer-controlled i18n fallback.
+ *   3. Generic fallback string ("Invalid value").
+ */
+declare function formatErrorMessage(error: FieldErrorShape | undefined, messageMap: Record<string, string> | undefined): string | undefined;
+
+/**
+ * Pure state machine for SubmitButton, shared by React + Preact runtimes.
+ *
+ *  | isValid | isSubmitting | disabled | loading |
+ *  |---------|--------------|----------|---------|
+ *  | false   | false        | true     | false   |
+ *  | false   | true         | true     | true    |
+ *  | true    | false        | false    | false   |
+ *  | true    | true         | true     | true    |
+ *
+ * `loading` reflects the submit-in-flight state regardless of validity, so
+ * consumers can show a spinner even if downstream validation rejects.
+ */
+declare function computeSubmitButtonState(input: {
+    isValid: boolean;
+    isSubmitting: boolean;
+}): {
+    disabled: boolean;
+    loading: boolean;
+};
+
+/**
+ * Pure helpers for Input. Runtime-agnostic — shared between React and Preact
+ * runtimes via the `src/components/forms/` co-location pattern (Standard §18.2).
+ */
+
+/**
+ * Build the deterministic input element id from form name + field name.
+ * Used to wire `<label htmlFor>`, `aria-describedby` and the error element id.
+ *
+ * Mirrors `buildFieldId` from `FormField.logic.ts` but namespaced for Input so
+ * future primitives (Textarea, Select) can compose their own id conventions.
+ */
+declare function buildInputId(formName: string | undefined, fieldName: string): string;
+/**
+ * `aria-describedby` value — the id of the error element, only emitted when an
+ * error exists. Otherwise undefined (omit the attribute entirely).
+ */
+declare function buildErrorDescribedBy(inputId: string, hasError: boolean): string | undefined;
+/**
+ * Map our public `type` prop to the HTML `type` attribute. Currently a 1:1
+ * passthrough — the indirection exists so future types (e.g. `search`,
+ * `tel`) can be widened without touching the runtime components.
+ */
+declare function resolveHtmlType(type: InputType | undefined): InputType;
+
+/**
+ * Returns the list of options that are still available for selection.
+ * Filters out options already present in `selected` so they don't appear
+ * twice in the dropdown.
+ */
+declare function getAvailableOptions(options: ReadonlyArray<MultiSelectOption>, selected: ReadonlyArray<string>): MultiSelectOption[];
+/**
+ * Returns the matching `MultiSelectOption` records for the currently selected
+ * values, preserving the order of `selected`. Unknown values are silently
+ * dropped (graceful — schema may have shrunk under the field).
+ */
+declare function getSelectedOptions(options: ReadonlyArray<MultiSelectOption>, selected: ReadonlyArray<string>): MultiSelectOption[];
+/**
+ * Search filter applied when `searchable=true`. Case-insensitive substring
+ * match on both `label` and `value`. Empty query returns the input as-is.
+ */
+declare function filterBySearch(options: ReadonlyArray<MultiSelectOption>, query: string): MultiSelectOption[];
+/**
+ * Adds a value to the selected list, enforcing `maxItems` (when set) and
+ * de-duplicating. Returns the same array reference when the value is already
+ * present OR the cap is reached — callers can compare identity to detect
+ * the no-op.
+ */
+declare function addValue(current: ReadonlyArray<string>, value: string, maxItems?: number): string[];
+/**
+ * Removes a value from the selected list. Returns a fresh array even when
+ * the value is absent so callers always see a stable shape.
+ */
+declare function removeValue(current: ReadonlyArray<string>, value: string): string[];
+/**
+ * True when the cap is reached. Used to gate further selections AND to
+ * announce the locked state to the dropdown trigger via `aria-disabled`
+ * semantics (the trigger itself stays focusable to preserve removal flows).
+ */
+declare function isAtMaxItems(current: ReadonlyArray<string>, maxItems: number | undefined): boolean;
+
+/**
+ * Select.logic.ts — pure, framework-agnostic logic for the Select primitive.
+ * Shared between React 19 and Preact 10 runtimes.
+ *
+ * WCAG-AA Combobox-with-listbox-popup pattern (APG 2024):
+ * - Trigger: role=combobox + aria-haspopup=listbox + aria-expanded + aria-controls
+ * - Popup:   role=listbox  + aria-activedescendant pointing at active option
+ * - Option:  role=option   + aria-selected=true on the selected one
+ * - Keyboard:
+ *     ArrowDown → next enabled option (wrap)
+ *     ArrowUp   → prev enabled option (wrap)
+ *     Home      → first enabled option
+ *     End       → last enabled option
+ *     Enter     → commit active option, close popup
+ *     Esc       → close popup, restore value, focus trigger
+ *     Printable type-ahead → jump to first option whose label starts with the buffer
+ */
+
+/**
+ * Filters options by case-insensitive substring on `label`. Empty query → all.
+ * Disabled flags are preserved (they're still rendered, just not selectable).
+ */
+declare function filterOptions(options: SelectOption[], query: string): SelectOption[];
+/**
+ * Finds the index of the option with `value`, or -1.
+ */
+declare function indexOfValue(options: SelectOption[], value: string | null | undefined): number;
+/**
+ * Type-ahead: given a buffer string, find first option whose label starts with
+ * the buffer (case-insensitive). Skips disabled options.
+ */
+declare function findByTypeAhead(options: SelectOption[], buffer: string): number;
+/**
+ * Resolves the label of the currently selected option for display in the trigger.
+ * Returns null when no value selected (caller shows placeholder).
+ */
+declare function resolveSelectedLabel(options: SelectOption[], value: string | null | undefined): string | null;
+
+export { FORM_PROVIDER_CONTEXT_MISSING, FieldErrorShape, InputType, MosaicFormMode, MultiSelectOption, SelectOption, addValue, buildErrorDescribedBy, buildFieldId, buildInputId, computeSubmitButtonState, filterBySearch, filterOptions, findByTypeAhead, formatErrorMessage, getAvailableOptions, getSelectedOptions, indexOfValue, isAtMaxItems, removeValue, resolveHtmlType, resolveSelectedLabel, toRhfMode };