mtrl-addons 0.3.7 → 0.3.9

package/dist/components/form/constants.d.ts

@@ -32,6 +32,8 @@ export declare const FORM_EVENTS: {
     readonly SUBMIT_ERROR: "submit:error";
     /** Fired when form is reset to initial state */
     readonly RESET: "reset";
+    /** Fired when setData is called with unsaved changes (protection enabled) */
+    readonly DATA_CONFLICT: "data:conflict";
 };
 /**
  * Form CSS class modifiers

package/dist/components/form/features/api.d.ts

@@ -21,8 +21,8 @@ interface EnhancedFormComponent extends BaseFormComponent {
     isModified: () => boolean;
     getModifiedData: () => FormData;
     snapshot: () => void;
-    reset: () => void;
-    clear: () => void;
+    reset: (force?: boolean) => boolean;
+    clear: (force?: boolean) => boolean;
     getField: (name: string) => FormField | undefined;
     getFieldNames: () => string[];
     hasField: (name: string) => boolean;

package/dist/components/form/features/data.d.ts

@@ -1,6 +1,7 @@
 /**
  * Data feature for Form component
- * Handles form data operations: get/set data, change tracking, snapshots
+ * Handles form data operations: get/set data, change tracking, snapshots,
+ * and change protection (beforeunload warning, data conflict detection)
  */
 import type { FormConfig, BaseFormComponent, FormData, FormState, FieldValue, FormFieldRegistry } from "../types";
 /**
@@ -32,8 +33,8 @@ export declare const withData: (config: FormConfig) => <T extends BaseFormCompon
     isModified: () => boolean;
     getModifiedData: () => FormData;
     snapshot: () => void;
-    reset: () => void;
-    clear: () => void;
+    reset: (force?: boolean) => boolean;
+    clear: (force?: boolean) => boolean;
 };
 export { flatToNested, getNestedValue, setNestedValue };
 export default withData;

package/dist/components/form/features/index.d.ts

@@ -7,4 +7,5 @@ export { withFields, getFieldValue, setFieldValue, updateTrackedFieldValue, sync
 export { withData, flatToNested, getNestedValue, setNestedValue } from "./data";
 export { withController } from "./controller";
 export { withSubmit, validateData, performRequest } from "./submit";
+export { withProtection } from "./protection";
 export { withAPI } from "./api";

package/dist/components/form/features/protection.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Protection feature for Form component
+ * Handles blocking overlay to prevent clicks outside the form when it has unsaved changes
+ */
+import type { FormConfig, BaseFormComponent, FormState, FormFieldRegistry } from "../types";
+/**
+ * withProtection feature
+ * Adds blocking overlay protection to prevent clicks outside the form when modified
+ */
+export declare const withProtection: (config: FormConfig) => <T extends BaseFormComponent & {
+    fields: FormFieldRegistry;
+    state: FormState;
+    emit?: (event: string, data?: unknown) => void;
+    on?: (event: string, handler: Function) => void;
+    reset?: (force?: boolean) => boolean;
+    clearErrors?: () => void;
+    disableControls?: () => void;
+}>(component: T) => T;
+export default withProtection;

package/dist/components/form/form.d.ts

@@ -5,7 +5,7 @@
  * forms from schema definitions, with built-in data management,
  * validation, and submission handling.
  */
-import type { FormConfig, FormComponent } from './types';
+import type { FormConfig, FormComponent } from "./types";
 /**
  * Creates a new Form component using functional composition
  *

package/dist/components/form/index.d.ts

@@ -4,6 +4,6 @@
  */
 export { createForm, default } from "./form";
 export { DATA_STATE, FORM_EVENTS, FORM_CLASSES, FORM_DEFAULTS, FIELD_PREFIXES, } from "./constants";
-export type { DataState, FormEvent, FieldValue, FormData, FormField, FormFieldRegistry, LayoutSchema, LayoutSchemaItem, FormSectionConfig, FormValidationRule, FormValidationResult, FormSubmitOptions, FormEventHandlers, FormConfig, FormState, FormAPI, FormComponent, BaseFormComponent, SubmitHandler, CancelHandler, } from "./types";
+export type { DataState, FormEvent, FieldValue, FormData, FormField, FormFieldRegistry, LayoutSchema, LayoutSchemaItem, FormSectionConfig, FormValidationRule, FormValidationResult, FormSubmitOptions, FormEventHandlers, FormConfig, FormState, FormAPI, FormComponent, BaseFormComponent, SubmitHandler, CancelHandler, ProtectChangesConfig, DataConflictEvent, } from "./types";
 export { createBaseConfig, createInitialState, getElementConfig, extractFieldName, getFieldPath, isFieldName, isFileName, isValueEqual, hasDataChanged, getModifiedFields, } from "./config";
 export { withLayout, withFields, withData, withController, withSubmit, withAPI, getFieldValue, setFieldValue, flatToNested, getNestedValue, setNestedValue, validateData, performRequest, } from "./features";

package/dist/components/form/types.d.ts

@@ -1,4 +1,37 @@
 import type { DATA_STATE, FORM_EVENTS } from "./constants";
+/**
+ * Configuration for form change protection
+ */
+export interface ProtectChangesConfig {
+    /**
+     * Warn user when trying to close browser tab/window with unsaved changes
+     * Uses the beforeunload event
+     * @default false
+     */
+    beforeUnload?: boolean;
+    /**
+     * Emit 'data:conflict' event when setData() is called with unsaved changes
+     * Allows the caller to confirm before overwriting
+     * @default false
+     */
+    onDataOverwrite?: boolean;
+}
+/**
+ * Event data for data:conflict event
+ * Emitted when setData() is called while form has unsaved changes
+ */
+export interface DataConflictEvent {
+    /** Current form data (unsaved changes) */
+    currentData: FormData;
+    /** New data that would overwrite current data */
+    newData: FormData;
+    /** Whether the operation was cancelled */
+    cancelled: boolean;
+    /** Call this to cancel the setData operation */
+    cancel: () => void;
+    /** Call this to proceed with setData (default behavior if not cancelled) */
+    proceed: () => void;
+}
 /**
  * Data state type (pristine or dirty)
  */
@@ -119,6 +152,8 @@ export interface FormEventHandlers {
     "data:set"?: (data: FormData) => void;
     /** Called when form is reset */
     reset?: () => void;
+    /** Called when setData() is called while form has unsaved changes */
+    "data:conflict"?: (event: DataConflictEvent) => void;
 }
 /**
  * Submit button handler - called when submit button is clicked
@@ -163,6 +198,12 @@ export interface FormConfig {
     validation?: FormValidationRule[];
     /** Whether to show error messages in field helper text (default: true) */
     showFieldErrorMessages?: boolean;
+    /**
+     * Protection settings for unsaved changes
+     * Can be a boolean (enables both protections) or a config object
+     * @default false
+     */
+    protectChanges?: boolean | ProtectChangesConfig;
     /** Event handlers */
     on?: FormEventHandlers;
     /** Container element to append form to */
@@ -219,10 +260,16 @@ export interface FormAPI {
     getFieldError: (field: string) => string | undefined;
     /** Submit the form */
     submit: (options?: FormSubmitOptions) => Promise<unknown>;
-    /** Reset form to initial data */
-    reset: () => FormComponent;
-    /** Clear all form fields */
-    clear: () => FormComponent;
+    /** Reset form to initial data
+     * @param {boolean} force - If true, bypass protection and reset immediately
+     * @returns {boolean} true if reset was performed, false if cancelled by protection
+     */
+    reset: (force?: boolean) => boolean;
+    /** Clear all form fields
+     * @param {boolean} force - If true, bypass protection and clear immediately
+     * @returns {boolean} true if clear was performed, false if cancelled by protection
+     */
+    clear: (force?: boolean) => boolean;
     /** Enable all form fields */
     enable: () => FormComponent;
     /** Disable all form fields */

package/dist/components/vlist/features/keyboard.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Keyboard Navigation Feature for VList
+ *
+ * Implements Material Design 3 accessibility guidelines for lists:
+ * - Arrow keys (Up/Down/Left/Right) navigate between items with wrapping
+ * - Space/Enter activates/selects the focused item
+ * - Tab moves focus to/from the list
+ * - Home/End jump to first/last item
+ * - Page Up/Down skip multiple items
+ *
+ * @see https://m3.material.io/components/lists/accessibility
+ */
+import type { VListConfig, VListComponent, VListItem } from "../types";
+/**
+ * Adds keyboard navigation and accessibility to VList component
+ */
+export declare const withKeyboard: <T extends VListItem = VListItem>(config: VListConfig<T>) => (component: VListComponent<T>) => VListComponent<T>;
+export default withKeyboard;

package/dist/components/vlist/index.d.ts

@@ -5,4 +5,4 @@
  * feature directly without the list-manager layer.
  */
 export { createVList } from "./vlist";
-export type { RemoveItemOptions, VListConfig, VListComponent, VListItem, VListAPI, VListState, VListEvents, } from "./types";
+export type { RemoveItemOptions, VListConfig, VListComponent, VListItem, VListAPI, VListState, VListEvents, ListKeyboardConfig, } from "./types";

package/dist/components/vlist/types.d.ts

@@ -150,6 +150,34 @@ export interface ListSelectionConfig {
     /** Automatically select first item after initial load (default: false) */
     autoSelectFirst?: boolean;
 }
+/**
+ * Keyboard navigation configuration
+ *
+ * Follows Material Design 3 accessibility guidelines:
+ * - Arrow keys (Up/Down/Left/Right) navigate with wrapping
+ * - Space/Enter activates/selects items
+ * - Home/End jump to first/last
+ *
+ * @see https://m3.material.io/components/lists/accessibility
+ */
+export interface ListKeyboardConfig {
+    /** Enable keyboard navigation (default: true when selection is enabled) */
+    enabled?: boolean;
+    /** Enable Home/End keys (default: true) */
+    homeEnd?: boolean;
+    /** Enable Page Up/Down keys (default: true) */
+    pageUpDown?: boolean;
+    /** Number of items to skip with Page Up/Down (default: 10) */
+    pageSize?: number;
+    /** Enable type-ahead search (default: false) */
+    typeAhead?: boolean;
+    /** Type-ahead search timeout in ms (default: 500) */
+    typeAheadTimeout?: number;
+    /** Wrap around when reaching start/end (default: true per MD3 spec) */
+    wrap?: boolean;
+    /** Callback when keyboard navigation occurs */
+    onNavigate?: (index: number, key: string) => void;
+}
 /**
  * List orientation configuration
  */
@@ -615,6 +643,7 @@ export interface VListConfig<T extends ListItem = ListItem> {
         maintainDomOrder?: boolean;
     };
     selection?: ListSelectionConfig;
+    keyboard?: ListKeyboardConfig;
     on?: ListEventHandlers<T>;
 }
 export type VListComponent<T extends ListItem = ListItem> = ListComponent<T> & {