@react-md/core 1.0.0-next.2 → 1.0.0-next.21

package/dist/form/utils.js

@@ -15,11 +15,10 @@
  * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/requestSubmit
  * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit
  * @internal
- * @remarks
- * \@since 2.7.0
- * \@since 6.0.0 No longer returns a boolean, added the `formId` parameter, and
+ * @since 2.7.0
+ * @since 6.0.0 No longer returns a boolean, added the `formId` parameter, and
  * moved into the form package.
- * \@since 6.0.0 Uses `form.requestSubmit` instead of clicking the submit button
+ * @since 6.0.0 Uses `form.requestSubmit` instead of clicking the submit button
  */ export function tryToSubmitRelatedForm(event, formId) {
     const { currentTarget } = event;
     let form = null;
@@ -38,12 +37,18 @@
     }
     form.requestSubmit(submit);
 }
+/**
+ * @internal
+ * @since 6.0.0
+ */ export function isChangeableHTMLElement(element) {
+    return !!element && "value" in element;
+}
 /**
  * This is used to trigger a change event for a form element.
  *
  * @internal
  * @see https://stackoverflow.com/a/46012210
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */ export function triggerManualChangeEvent(element, value) {
     if (!element) {
         return;

package/dist/form/utils.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/form/utils.ts"],"sourcesContent":["import { type KeyboardEvent } from \"react\";\n\n/**\n * This util should be used to implement the native \"Enter\" keypress behavior\n * for \"fake\" form components to submit the form if exists.\n *\n * The way this will work will be:\n * - attempt to find a form by querying for a parent form element. if no parent\n *   form element can be found, try to use the `formId` in a\n *   `document.getElementById`\n * - if a form element is found, find the submit button within the form. If\n *   there are no submit buttons within the form, try to find a submit button in\n *   the document that is linked to this form by `form={formId}`\n * - if the submit button was found, click it to trigger the form submit\n *   behavior\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/requestSubmit\n * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit\n * @internal\n * @remarks\n * \\@since 2.7.0\n * \\@since 6.0.0 No longer returns a boolean, added the `formId` parameter, and\n * moved into the form package.\n * \\@since 6.0.0 Uses `form.requestSubmit` instead of clicking the submit button\n */\nexport function tryToSubmitRelatedForm<E extends HTMLElement>(\n  event: KeyboardEvent<E>,\n  formId: string | undefined\n): void {\n  const { currentTarget } = event;\n  let form: HTMLElement | null = null;\n  if (formId) {\n    form = document.getElementById(formId);\n  } else {\n    form = currentTarget.closest(\"form\");\n  }\n\n  if (!form || !(form instanceof HTMLFormElement)) {\n    return;\n  }\n\n  formId = formId || form.id;\n  let submit = form.querySelector<HTMLButtonElement>('[type=\"submit\"]');\n  if (!submit && formId) {\n    submit = document.querySelector<HTMLButtonElement>(\n      `[type=\"submit\"][form=\"${formId}\"]`\n    );\n  }\n\n  form.requestSubmit(submit);\n}\n\n/**\n * @internal\n * @remarks \\@since 6.0.0\n */\nexport type ChangeableHTMLElement =\n  | HTMLInputElement\n  | HTMLTextAreaElement\n  | HTMLSelectElement;\n\n/**\n * This is used to trigger a change event for a form element.\n *\n * @internal\n * @see https://stackoverflow.com/a/46012210\n * @remarks \\@since 6.0.0\n */\nexport function triggerManualChangeEvent(\n  element: ChangeableHTMLElement | null,\n  value: string | number\n): void {\n  if (!element) {\n    return;\n  }\n\n  const prototype = Object.getPrototypeOf(element);\n  const setter = Object.getOwnPropertyDescriptor(prototype, \"value\")?.set;\n  if (!setter) {\n    return;\n  }\n\n  setter.call(element, value);\n  const event = new Event(\"input\", { bubbles: true });\n  element.dispatchEvent(event);\n}\n"],"names":["tryToSubmitRelatedForm","event","formId","currentTarget","form","document","getElementById","closest","HTMLFormElement","id","submit","querySelector","requestSubmit","triggerManualChangeEvent","element","value","prototype","Object","getPrototypeOf","setter","getOwnPropertyDescriptor","set","call","Event","bubbles","dispatchEvent"],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;CAsBC,GACD,OAAO,SAASA,uBACdC,KAAuB,EACvBC,MAA0B;IAE1B,MAAM,EAAEC,aAAa,EAAE,GAAGF;IAC1B,IAAIG,OAA2B;IAC/B,IAAIF,QAAQ;QACVE,OAAOC,SAASC,cAAc,CAACJ;IACjC,OAAO;QACLE,OAAOD,cAAcI,OAAO,CAAC;IAC/B;IAEA,IAAI,CAACH,QAAQ,CAAEA,CAAAA,gBAAgBI,eAAc,GAAI;QAC/C;IACF;IAEAN,SAASA,UAAUE,KAAKK,EAAE;IAC1B,IAAIC,SAASN,KAAKO,aAAa,CAAoB;IACnD,IAAI,CAACD,UAAUR,QAAQ;QACrBQ,SAASL,SAASM,aAAa,CAC7B,CAAC,sBAAsB,EAAET,OAAO,EAAE,CAAC;IAEvC;IAEAE,KAAKQ,aAAa,CAACF;AACrB;AAWA;;;;;;CAMC,GACD,OAAO,SAASG,yBACdC,OAAqC,EACrCC,KAAsB;IAEtB,IAAI,CAACD,SAAS;QACZ;IACF;IAEA,MAAME,YAAYC,OAAOC,cAAc,CAACJ;IACxC,MAAMK,SAASF,OAAOG,wBAAwB,CAACJ,WAAW,UAAUK;IACpE,IAAI,CAACF,QAAQ;QACX;IACF;IAEAA,OAAOG,IAAI,CAACR,SAASC;IACrB,MAAMd,QAAQ,IAAIsB,MAAM,SAAS;QAAEC,SAAS;IAAK;IACjDV,QAAQW,aAAa,CAACxB;AACxB"}
+{"version":3,"sources":["../../src/form/utils.ts"],"sourcesContent":["import { type KeyboardEvent } from \"react\";\n\n/**\n * This util should be used to implement the native \"Enter\" keypress behavior\n * for \"fake\" form components to submit the form if exists.\n *\n * The way this will work will be:\n * - attempt to find a form by querying for a parent form element. if no parent\n *   form element can be found, try to use the `formId` in a\n *   `document.getElementById`\n * - if a form element is found, find the submit button within the form. If\n *   there are no submit buttons within the form, try to find a submit button in\n *   the document that is linked to this form by `form={formId}`\n * - if the submit button was found, click it to trigger the form submit\n *   behavior\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/requestSubmit\n * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit\n * @internal\n * @since 2.7.0\n * @since 6.0.0 No longer returns a boolean, added the `formId` parameter, and\n * moved into the form package.\n * @since 6.0.0 Uses `form.requestSubmit` instead of clicking the submit button\n */\nexport function tryToSubmitRelatedForm<E extends HTMLElement>(\n  event: KeyboardEvent<E>,\n  formId: string | undefined\n): void {\n  const { currentTarget } = event;\n  let form: HTMLElement | null = null;\n  if (formId) {\n    form = document.getElementById(formId);\n  } else {\n    form = currentTarget.closest(\"form\");\n  }\n\n  if (!form || !(form instanceof HTMLFormElement)) {\n    return;\n  }\n\n  formId = formId || form.id;\n  let submit = form.querySelector<HTMLButtonElement>('[type=\"submit\"]');\n  if (!submit && formId) {\n    submit = document.querySelector<HTMLButtonElement>(\n      `[type=\"submit\"][form=\"${formId}\"]`\n    );\n  }\n\n  form.requestSubmit(submit);\n}\n\n/**\n * @internal\n * @since 6.0.0\n */\nexport type EditableHTMLElement = HTMLInputElement | HTMLTextAreaElement;\n\n/**\n * @internal\n * @since 6.0.0\n */\nexport type ChangeableHTMLElement = EditableHTMLElement | HTMLSelectElement;\n\n/**\n * @internal\n * @since 6.0.0\n */\nexport function isChangeableHTMLElement(\n  element: Element | null\n): element is ChangeableHTMLElement {\n  return !!element && \"value\" in element;\n}\n\n/**\n * This is used to trigger a change event for a form element.\n *\n * @internal\n * @see https://stackoverflow.com/a/46012210\n * @since 6.0.0\n */\nexport function triggerManualChangeEvent(\n  element: ChangeableHTMLElement | null,\n  value: string | number\n): void {\n  if (!element) {\n    return;\n  }\n\n  const prototype = Object.getPrototypeOf(element);\n  const setter = Object.getOwnPropertyDescriptor(prototype, \"value\")?.set;\n  if (!setter) {\n    return;\n  }\n\n  setter.call(element, value);\n  const event = new Event(\"input\", { bubbles: true });\n  element.dispatchEvent(event);\n}\n"],"names":["tryToSubmitRelatedForm","event","formId","currentTarget","form","document","getElementById","closest","HTMLFormElement","id","submit","querySelector","requestSubmit","isChangeableHTMLElement","element","triggerManualChangeEvent","value","prototype","Object","getPrototypeOf","setter","getOwnPropertyDescriptor","set","call","Event","bubbles","dispatchEvent"],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;CAqBC,GACD,OAAO,SAASA,uBACdC,KAAuB,EACvBC,MAA0B;IAE1B,MAAM,EAAEC,aAAa,EAAE,GAAGF;IAC1B,IAAIG,OAA2B;IAC/B,IAAIF,QAAQ;QACVE,OAAOC,SAASC,cAAc,CAACJ;IACjC,OAAO;QACLE,OAAOD,cAAcI,OAAO,CAAC;IAC/B;IAEA,IAAI,CAACH,QAAQ,CAAEA,CAAAA,gBAAgBI,eAAc,GAAI;QAC/C;IACF;IAEAN,SAASA,UAAUE,KAAKK,EAAE;IAC1B,IAAIC,SAASN,KAAKO,aAAa,CAAoB;IACnD,IAAI,CAACD,UAAUR,QAAQ;QACrBQ,SAASL,SAASM,aAAa,CAC7B,CAAC,sBAAsB,EAAET,OAAO,EAAE,CAAC;IAEvC;IAEAE,KAAKQ,aAAa,CAACF;AACrB;AAcA;;;CAGC,GACD,OAAO,SAASG,wBACdC,OAAuB;IAEvB,OAAO,CAAC,CAACA,WAAW,WAAWA;AACjC;AAEA;;;;;;CAMC,GACD,OAAO,SAASC,yBACdD,OAAqC,EACrCE,KAAsB;IAEtB,IAAI,CAACF,SAAS;QACZ;IACF;IAEA,MAAMG,YAAYC,OAAOC,cAAc,CAACL;IACxC,MAAMM,SAASF,OAAOG,wBAAwB,CAACJ,WAAW,UAAUK;IACpE,IAAI,CAACF,QAAQ;QACX;IACF;IAEAA,OAAOG,IAAI,CAACT,SAASE;IACrB,MAAMf,QAAQ,IAAIuB,MAAM,SAAS;QAAEC,SAAS;IAAK;IACjDX,QAAQY,aAAa,CAACzB;AACxB"}

package/dist/form/validation.d.ts

@@ -1,7 +1,7 @@
 import { type InputHTMLAttributes, type ReactNode } from "react";
 /**
- * @remarks \@since 2.5.6
- * @remarks \@since 6.0.0 Renamed from `TextConstraints` to
+ * @since 2.5.6
+ * @since 6.0.0 Renamed from `TextConstraints` to
  * `TextFieldValidationOptions`
  */
 export type TextFieldValidationOptions = Pick<InputHTMLAttributes<HTMLInputElement>, "minLength" | "maxLength" | "required" | "pattern">;
@@ -24,13 +24,14 @@ export type TextFieldValidationOptions = Pick<InputHTMLAttributes<HTMLInputEleme
  *
  * @see {@link RECOMMENDED_STATE_KEYS}
  * @see {@link RECOMMENDED_NUMBER_STATE_KEYS}
- * @remarks \@since 2.5.6
- * @remarks \@since 6.0.0 Renamed from `ChangeValidationBehavior` to
+ * @since 2.5.6
+ * @since 6.0.0 Renamed from `ChangeValidationBehavior` to
  * `TextFieldValidationType`
  */
 export type TextFieldValidationType = "blur" | "change" | "recommended" | keyof ValidityState | readonly (keyof ValidityState)[];
 /**
- * @remarks \@since 2.5.0
+ * @since 2.5.0
+ * @since 6.0.0 Renamed `validateOnChange` to `validationType`
  */
 export interface ErrorMessageOptions extends TextFieldValidationOptions {
     /**
@@ -67,17 +68,17 @@ export interface ErrorMessageOptions extends TextFieldValidationOptions {
  * @param options - An object containing metadata that can be used to create an
  * error message for your `TextField` or `TextArea`.
  * @returns An error message to display or an empty string.
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export type GetErrorMessage = (options: ErrorMessageOptions) => string;
 /**
  * @internal
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export declare const RECOMMENDED_STATE_KEYS: readonly (keyof ValidityState)[];
 /**
  * @internal
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export declare const RECOMMENDED_NUMBER_STATE_KEYS: readonly (keyof ValidityState)[];
 /**
@@ -85,11 +86,11 @@ export declare const RECOMMENDED_NUMBER_STATE_KEYS: readonly (keyof ValidityStat
  * or `TextArea` components that relies on the behavior of the
  * {@link ChangeValidationBehavior}
  *
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export declare const defaultGetErrorMessage: GetErrorMessage;
 /**
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export interface IsErroredOptions extends ErrorMessageOptions {
     /**
@@ -104,7 +105,7 @@ export interface IsErroredOptions extends ErrorMessageOptions {
  * @param options - All the current options that can be used to determine the
  * error state.
  * @returns True if the component is considered to be in an errored state.
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export type IsErrored = (options: IsErroredOptions) => boolean;
 /**
@@ -113,11 +114,11 @@ export type IsErrored = (options: IsErroredOptions) => boolean;
  * value is not within the `minLength` and `maxLength` constraints when they
  * exist.
  *
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export declare const defaultIsErrored: IsErrored;
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface GetErrorIconOptions {
     /**
@@ -139,14 +140,14 @@ export interface GetErrorIconOptions {
  *
  * @param options - The {@link GetErrorIconOptions}
  * @returns An icon to render or falsey to render nothing.
- * @remarks \@since 2.5.0
- * @remarks \@since 6.0.0 Updated to accept a single object argument
+ * @since 2.5.0
+ * @since 6.0.0 Updated to accept a single object argument
  */
 export type GetErrorIcon = (options: GetErrorIconOptions) => ReactNode;
 /**
  * The default implementation for showing an error icon in `TextField` and
  * `TextArea` components that will only display when the error flag is enabled.
  *
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export declare const defaultGetErrorIcon: GetErrorIcon;

package/dist/form/validation.js

@@ -1,6 +1,7 @@
 /**
  * @internal
- * @remarks \@since 2.5.0
+ * @since 2.5.0
+ * @since 6.0.0 Added `"valid"` since it exists in the type definition
  */ const VALIDITY_STATE_KEYS = [
     "badInput",
     "customError",
@@ -11,11 +12,12 @@
     "tooLong",
     "tooShort",
     "typeMismatch",
+    "valid",
     "valueMissing"
 ];
 /**
  * @internal
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */ export const RECOMMENDED_STATE_KEYS = [
     "badInput",
     "tooLong",
@@ -23,7 +25,7 @@
 ];
 /**
  * @internal
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */ export const RECOMMENDED_NUMBER_STATE_KEYS = [
     ...RECOMMENDED_STATE_KEYS,
     "rangeOverflow",
@@ -39,7 +41,7 @@
  * of errors.
  *
  * @internal
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */ const isRecommended = (validity, isNumber)=>{
     const errorable = isNumber ? RECOMMENDED_NUMBER_STATE_KEYS : RECOMMENDED_STATE_KEYS;
     return VALIDITY_STATE_KEYS.every((key)=>{
@@ -52,7 +54,7 @@
  * or `TextArea` components that relies on the behavior of the
  * {@link ChangeValidationBehavior}
  *
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */ export const defaultGetErrorMessage = (options)=>{
     const { isNumber, isBlurEvent, validity, validationMessage, validationType: validate } = options;
     if (isBlurEvent || !validationMessage || validate === "change") {
@@ -75,7 +77,7 @@
  * value is not within the `minLength` and `maxLength` constraints when they
  * exist.
  *
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */ export const defaultIsErrored = (options)=>{
     const { value, errorMessage, minLength, maxLength, isBlurEvent } = options;
     return !!errorMessage || typeof maxLength === "number" && value.length > maxLength || isBlurEvent && typeof minLength === "number" && value.length < minLength;
@@ -84,7 +86,7 @@
  * The default implementation for showing an error icon in `TextField` and
  * `TextArea` components that will only display when the error flag is enabled.
  *
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */ export const defaultGetErrorIcon = (options)=>{
     const { error, errorIcon } = options;
     return error && errorIcon;

package/dist/form/validation.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/form/validation.ts"],"sourcesContent":["import { type InputHTMLAttributes, type ReactNode } from \"react\";\n\n/**\n * @remarks \\@since 2.5.6\n * @remarks \\@since 6.0.0 Renamed from `TextConstraints` to\n * `TextFieldValidationOptions`\n */\nexport type TextFieldValidationOptions = Pick<\n  InputHTMLAttributes<HTMLInputElement>,\n  \"minLength\" | \"maxLength\" | \"required\" | \"pattern\"\n>;\n\n/**\n * Since the default validation messages can be verbose, this type is used to\n * configure when/how to display the native browser messages when the validation\n * state changes during the `change` event phase. The validation message will\n * always be shown on blur.\n *\n * When this is:\n *\n * - `true` -&gt; always show the browser message when it exists\n * - `false` -&gt; never show the browser message\n * - `\"recommended\"` -&gt; only shows the browser message if it is one of the\n *   `RECOMMENDED_STATE_KEYS`/`RECOMMENDED_NUMBER_STATE_KEYS` validation errors\n * - `keyof ValidityState` -&gt; only shows the browser message if it is not the\n *   specific validation error\n * - `(keyof ValidityState)[]` -&gt; only shows the browser message if it is not\n *   the specific validation errors\n *\n * @see {@link RECOMMENDED_STATE_KEYS}\n * @see {@link RECOMMENDED_NUMBER_STATE_KEYS}\n * @remarks \\@since 2.5.6\n * @remarks \\@since 6.0.0 Renamed from `ChangeValidationBehavior` to\n * `TextFieldValidationType`\n */\nexport type TextFieldValidationType =\n  | \"blur\"\n  | \"change\"\n  | \"recommended\"\n  | keyof ValidityState\n  | readonly (keyof ValidityState)[];\n\n/**\n * @remarks \\@since 2.5.0\n */\nexport interface ErrorMessageOptions extends TextFieldValidationOptions {\n  /**\n   * The current input or textarea's validity state.\n   */\n  validity: ValidityState;\n\n  /**\n   * The browser defined validation message based on the validity state. This\n   * will be the empty string when there are no errors.\n   */\n  validationMessage: string;\n\n  /**\n   * The current `TextField` or `TextArea` value.\n   */\n  value: string;\n\n  /**\n   * This will only be `true` if called by the `useNumberField` hook.\n   */\n  isNumber: boolean;\n\n  /**\n   * Boolean if this is triggered from a blur event instead of a change event.\n   */\n  isBlurEvent: boolean;\n\n  /**\n   * The validation type defined by the `useTextField` hook.\n   */\n  validationType: TextFieldValidationType;\n}\n\n/**\n * A function to get a custom error message for specific errors. This is really\n * useful when using the `pattern` attribute to give additional information or\n * changing the native \"language translated\" error message.\n *\n * @param options - An object containing metadata that can be used to create an\n * error message for your `TextField` or `TextArea`.\n * @returns An error message to display or an empty string.\n * @remarks \\@since 2.5.0\n */\nexport type GetErrorMessage = (options: ErrorMessageOptions) => string;\n\n/**\n * @internal\n * @remarks \\@since 2.5.0\n */\nconst VALIDITY_STATE_KEYS: readonly (keyof ValidityState)[] = [\n  \"badInput\",\n  \"customError\",\n  \"patternMismatch\",\n  \"rangeOverflow\",\n  \"rangeUnderflow\",\n  \"stepMismatch\",\n  \"tooLong\",\n  \"tooShort\",\n  \"typeMismatch\",\n  \"valueMissing\",\n];\n\n/**\n * @internal\n * @remarks \\@since 2.5.0\n */\nexport const RECOMMENDED_STATE_KEYS: readonly (keyof ValidityState)[] = [\n  \"badInput\",\n  \"tooLong\",\n  \"valueMissing\",\n];\n\n/**\n * @internal\n * @remarks \\@since 2.5.0\n */\nexport const RECOMMENDED_NUMBER_STATE_KEYS: readonly (keyof ValidityState)[] = [\n  ...RECOMMENDED_STATE_KEYS,\n  \"rangeOverflow\",\n  \"rangeUnderflow\",\n  \"tooShort\",\n  \"typeMismatch\",\n];\n\n/**\n * The validation message is actually kind of weird since it's possible for a\n * form element to have multiple errors at once. The validation message will be\n * the first error that appears, so need to make sure that the first error is\n * one of the recommended state keys so the message appears for only those types\n * of errors.\n *\n * @internal\n * @remarks \\@since 2.5.0\n */\nconst isRecommended = (validity: ValidityState, isNumber: boolean): boolean => {\n  const errorable = isNumber\n    ? RECOMMENDED_NUMBER_STATE_KEYS\n    : RECOMMENDED_STATE_KEYS;\n\n  return VALIDITY_STATE_KEYS.every((key) => {\n    const errored = validity[key];\n    return !errored || errorable.includes(key);\n  });\n};\n\n/**\n * The default implementation for getting an error message for the `TextField`\n * or `TextArea` components that relies on the behavior of the\n * {@link ChangeValidationBehavior}\n *\n * @remarks \\@since 2.5.0\n */\nexport const defaultGetErrorMessage: GetErrorMessage = (options) => {\n  const {\n    isNumber,\n    isBlurEvent,\n    validity,\n    validationMessage,\n    validationType: validate,\n  } = options;\n\n  if (isBlurEvent || !validationMessage || validate === \"change\") {\n    return validationMessage;\n  }\n\n  if (validate === \"blur\") {\n    return \"\";\n  }\n\n  if (validate === \"recommended\") {\n    return isRecommended(validity, isNumber) ? validationMessage : \"\";\n  }\n\n  const keys = typeof validate === \"string\" ? [validate] : validate;\n\n  return keys.length &&\n    VALIDITY_STATE_KEYS.some((key) => validity[key] && keys.includes(key))\n    ? validationMessage\n    : \"\";\n};\n\n/**\n * @remarks \\@since 2.5.0\n */\nexport interface IsErroredOptions extends ErrorMessageOptions {\n  /**\n   * The current error message or an empty string.\n   */\n  errorMessage: string;\n}\n\n/**\n * A function that is used to determine if a `TextField` or `TextArea` is in an\n * errored state.\n *\n * @param options - All the current options that can be used to determine the\n * error state.\n * @returns True if the component is considered to be in an errored state.\n * @remarks \\@since 2.5.0\n */\nexport type IsErrored = (options: IsErroredOptions) => boolean;\n\n/**\n * The default implementation for checking if a `TextField` or `TextArea` is\n * errored by returning `true` if the `errorMessage` string is truthy or the\n * value is not within the `minLength` and `maxLength` constraints when they\n * exist.\n *\n * @remarks \\@since 2.5.0\n */\nexport const defaultIsErrored: IsErrored = (options) => {\n  const { value, errorMessage, minLength, maxLength, isBlurEvent } = options;\n\n  return (\n    !!errorMessage ||\n    (typeof maxLength === \"number\" && value.length > maxLength) ||\n    (isBlurEvent && typeof minLength === \"number\" && value.length < minLength)\n  );\n};\n\n/**\n * @remarks \\@since 6.0.0\n */\nexport interface GetErrorIconOptions {\n  /**\n   * This will be `true` if the `TextField` or `TextArea` is in an errored state.\n   */\n  error: boolean;\n\n  /**\n   * The current error icon that was provided.\n   */\n  errorIcon: ReactNode;\n\n  /**\n   * The current error message or an empty string.\n   */\n  errorMessage: string;\n}\n\n/**\n * A function that can be used to dynamically get an error icon based on the\n * current visible error.\n *\n * @param options - The {@link GetErrorIconOptions}\n * @returns An icon to render or falsey to render nothing.\n * @remarks \\@since 2.5.0\n * @remarks \\@since 6.0.0 Updated to accept a single object argument\n */\nexport type GetErrorIcon = (options: GetErrorIconOptions) => ReactNode;\n\n/**\n * The default implementation for showing an error icon in `TextField` and\n * `TextArea` components that will only display when the error flag is enabled.\n *\n * @remarks \\@since 2.5.0\n */\nexport const defaultGetErrorIcon: GetErrorIcon = (options) => {\n  const { error, errorIcon } = options;\n\n  return error && errorIcon;\n};\n"],"names":["VALIDITY_STATE_KEYS","RECOMMENDED_STATE_KEYS","RECOMMENDED_NUMBER_STATE_KEYS","isRecommended","validity","isNumber","errorable","every","key","errored","includes","defaultGetErrorMessage","options","isBlurEvent","validationMessage","validationType","validate","keys","length","some","defaultIsErrored","value","errorMessage","minLength","maxLength","defaultGetErrorIcon","error","errorIcon"],"mappings":"AA0FA;;;CAGC,GACD,MAAMA,sBAAwD;IAC5D;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED;;;CAGC,GACD,OAAO,MAAMC,yBAA2D;IACtE;IACA;IACA;CACD,CAAC;AAEF;;;CAGC,GACD,OAAO,MAAMC,gCAAkE;OAC1ED;IACH;IACA;IACA;IACA;CACD,CAAC;AAEF;;;;;;;;;CASC,GACD,MAAME,gBAAgB,CAACC,UAAyBC;IAC9C,MAAMC,YAAYD,WACdH,gCACAD;IAEJ,OAAOD,oBAAoBO,KAAK,CAAC,CAACC;QAChC,MAAMC,UAAUL,QAAQ,CAACI,IAAI;QAC7B,OAAO,CAACC,WAAWH,UAAUI,QAAQ,CAACF;IACxC;AACF;AAEA;;;;;;CAMC,GACD,OAAO,MAAMG,yBAA0C,CAACC;IACtD,MAAM,EACJP,QAAQ,EACRQ,WAAW,EACXT,QAAQ,EACRU,iBAAiB,EACjBC,gBAAgBC,QAAQ,EACzB,GAAGJ;IAEJ,IAAIC,eAAe,CAACC,qBAAqBE,aAAa,UAAU;QAC9D,OAAOF;IACT;IAEA,IAAIE,aAAa,QAAQ;QACvB,OAAO;IACT;IAEA,IAAIA,aAAa,eAAe;QAC9B,OAAOb,cAAcC,UAAUC,YAAYS,oBAAoB;IACjE;IAEA,MAAMG,OAAO,OAAOD,aAAa,WAAW;QAACA;KAAS,GAAGA;IAEzD,OAAOC,KAAKC,MAAM,IAChBlB,oBAAoBmB,IAAI,CAAC,CAACX,MAAQJ,QAAQ,CAACI,IAAI,IAAIS,KAAKP,QAAQ,CAACF,QAC/DM,oBACA;AACN,EAAE;AAuBF;;;;;;;CAOC,GACD,OAAO,MAAMM,mBAA8B,CAACR;IAC1C,MAAM,EAAES,KAAK,EAAEC,YAAY,EAAEC,SAAS,EAAEC,SAAS,EAAEX,WAAW,EAAE,GAAGD;IAEnE,OACE,CAAC,CAACU,gBACD,OAAOE,cAAc,YAAYH,MAAMH,MAAM,GAAGM,aAChDX,eAAe,OAAOU,cAAc,YAAYF,MAAMH,MAAM,GAAGK;AAEpE,EAAE;AAiCF;;;;;CAKC,GACD,OAAO,MAAME,sBAAoC,CAACb;IAChD,MAAM,EAAEc,KAAK,EAAEC,SAAS,EAAE,GAAGf;IAE7B,OAAOc,SAASC;AAClB,EAAE"}
+{"version":3,"sources":["../../src/form/validation.ts"],"sourcesContent":["import { type InputHTMLAttributes, type ReactNode } from \"react\";\n\n/**\n * @since 2.5.6\n * @since 6.0.0 Renamed from `TextConstraints` to\n * `TextFieldValidationOptions`\n */\nexport type TextFieldValidationOptions = Pick<\n  InputHTMLAttributes<HTMLInputElement>,\n  \"minLength\" | \"maxLength\" | \"required\" | \"pattern\"\n>;\n\n/**\n * Since the default validation messages can be verbose, this type is used to\n * configure when/how to display the native browser messages when the validation\n * state changes during the `change` event phase. The validation message will\n * always be shown on blur.\n *\n * When this is:\n *\n * - `true` -&gt; always show the browser message when it exists\n * - `false` -&gt; never show the browser message\n * - `\"recommended\"` -&gt; only shows the browser message if it is one of the\n *   `RECOMMENDED_STATE_KEYS`/`RECOMMENDED_NUMBER_STATE_KEYS` validation errors\n * - `keyof ValidityState` -&gt; only shows the browser message if it is not the\n *   specific validation error\n * - `(keyof ValidityState)[]` -&gt; only shows the browser message if it is not\n *   the specific validation errors\n *\n * @see {@link RECOMMENDED_STATE_KEYS}\n * @see {@link RECOMMENDED_NUMBER_STATE_KEYS}\n * @since 2.5.6\n * @since 6.0.0 Renamed from `ChangeValidationBehavior` to\n * `TextFieldValidationType`\n */\nexport type TextFieldValidationType =\n  | \"blur\"\n  | \"change\"\n  | \"recommended\"\n  | keyof ValidityState\n  | readonly (keyof ValidityState)[];\n\n/**\n * @since 2.5.0\n * @since 6.0.0 Renamed `validateOnChange` to `validationType`\n */\nexport interface ErrorMessageOptions extends TextFieldValidationOptions {\n  /**\n   * The current input or textarea's validity state.\n   */\n  validity: ValidityState;\n\n  /**\n   * The browser defined validation message based on the validity state. This\n   * will be the empty string when there are no errors.\n   */\n  validationMessage: string;\n\n  /**\n   * The current `TextField` or `TextArea` value.\n   */\n  value: string;\n\n  /**\n   * This will only be `true` if called by the `useNumberField` hook.\n   */\n  isNumber: boolean;\n\n  /**\n   * Boolean if this is triggered from a blur event instead of a change event.\n   */\n  isBlurEvent: boolean;\n\n  /**\n   * The validation type defined by the `useTextField` hook.\n   */\n  validationType: TextFieldValidationType;\n}\n\n/**\n * A function to get a custom error message for specific errors. This is really\n * useful when using the `pattern` attribute to give additional information or\n * changing the native \"language translated\" error message.\n *\n * @param options - An object containing metadata that can be used to create an\n * error message for your `TextField` or `TextArea`.\n * @returns An error message to display or an empty string.\n * @since 2.5.0\n */\nexport type GetErrorMessage = (options: ErrorMessageOptions) => string;\n\n/**\n * @internal\n * @since 2.5.0\n * @since 6.0.0 Added `\"valid\"` since it exists in the type definition\n */\nconst VALIDITY_STATE_KEYS: readonly (keyof ValidityState)[] = [\n  \"badInput\",\n  \"customError\",\n  \"patternMismatch\",\n  \"rangeOverflow\",\n  \"rangeUnderflow\",\n  \"stepMismatch\",\n  \"tooLong\",\n  \"tooShort\",\n  \"typeMismatch\",\n  \"valid\",\n  \"valueMissing\",\n];\n\n/**\n * @internal\n * @since 2.5.0\n */\nexport const RECOMMENDED_STATE_KEYS: readonly (keyof ValidityState)[] = [\n  \"badInput\",\n  \"tooLong\",\n  \"valueMissing\",\n];\n\n/**\n * @internal\n * @since 2.5.0\n */\nexport const RECOMMENDED_NUMBER_STATE_KEYS: readonly (keyof ValidityState)[] = [\n  ...RECOMMENDED_STATE_KEYS,\n  \"rangeOverflow\",\n  \"rangeUnderflow\",\n  \"tooShort\",\n  \"typeMismatch\",\n];\n\n/**\n * The validation message is actually kind of weird since it's possible for a\n * form element to have multiple errors at once. The validation message will be\n * the first error that appears, so need to make sure that the first error is\n * one of the recommended state keys so the message appears for only those types\n * of errors.\n *\n * @internal\n * @since 2.5.0\n */\nconst isRecommended = (validity: ValidityState, isNumber: boolean): boolean => {\n  const errorable = isNumber\n    ? RECOMMENDED_NUMBER_STATE_KEYS\n    : RECOMMENDED_STATE_KEYS;\n\n  return VALIDITY_STATE_KEYS.every((key) => {\n    const errored = validity[key];\n    return !errored || errorable.includes(key);\n  });\n};\n\n/**\n * The default implementation for getting an error message for the `TextField`\n * or `TextArea` components that relies on the behavior of the\n * {@link ChangeValidationBehavior}\n *\n * @since 2.5.0\n */\nexport const defaultGetErrorMessage: GetErrorMessage = (options) => {\n  const {\n    isNumber,\n    isBlurEvent,\n    validity,\n    validationMessage,\n    validationType: validate,\n  } = options;\n\n  if (isBlurEvent || !validationMessage || validate === \"change\") {\n    return validationMessage;\n  }\n\n  if (validate === \"blur\") {\n    return \"\";\n  }\n\n  if (validate === \"recommended\") {\n    return isRecommended(validity, isNumber) ? validationMessage : \"\";\n  }\n\n  const keys = typeof validate === \"string\" ? [validate] : validate;\n\n  return keys.length &&\n    VALIDITY_STATE_KEYS.some((key) => validity[key] && keys.includes(key))\n    ? validationMessage\n    : \"\";\n};\n\n/**\n * @since 2.5.0\n */\nexport interface IsErroredOptions extends ErrorMessageOptions {\n  /**\n   * The current error message or an empty string.\n   */\n  errorMessage: string;\n}\n\n/**\n * A function that is used to determine if a `TextField` or `TextArea` is in an\n * errored state.\n *\n * @param options - All the current options that can be used to determine the\n * error state.\n * @returns True if the component is considered to be in an errored state.\n * @since 2.5.0\n */\nexport type IsErrored = (options: IsErroredOptions) => boolean;\n\n/**\n * The default implementation for checking if a `TextField` or `TextArea` is\n * errored by returning `true` if the `errorMessage` string is truthy or the\n * value is not within the `minLength` and `maxLength` constraints when they\n * exist.\n *\n * @since 2.5.0\n */\nexport const defaultIsErrored: IsErrored = (options) => {\n  const { value, errorMessage, minLength, maxLength, isBlurEvent } = options;\n\n  return (\n    !!errorMessage ||\n    (typeof maxLength === \"number\" && value.length > maxLength) ||\n    (isBlurEvent && typeof minLength === \"number\" && value.length < minLength)\n  );\n};\n\n/**\n * @since 6.0.0\n */\nexport interface GetErrorIconOptions {\n  /**\n   * This will be `true` if the `TextField` or `TextArea` is in an errored state.\n   */\n  error: boolean;\n\n  /**\n   * The current error icon that was provided.\n   */\n  errorIcon: ReactNode;\n\n  /**\n   * The current error message or an empty string.\n   */\n  errorMessage: string;\n}\n\n/**\n * A function that can be used to dynamically get an error icon based on the\n * current visible error.\n *\n * @param options - The {@link GetErrorIconOptions}\n * @returns An icon to render or falsey to render nothing.\n * @since 2.5.0\n * @since 6.0.0 Updated to accept a single object argument\n */\nexport type GetErrorIcon = (options: GetErrorIconOptions) => ReactNode;\n\n/**\n * The default implementation for showing an error icon in `TextField` and\n * `TextArea` components that will only display when the error flag is enabled.\n *\n * @since 2.5.0\n */\nexport const defaultGetErrorIcon: GetErrorIcon = (options) => {\n  const { error, errorIcon } = options;\n\n  return error && errorIcon;\n};\n"],"names":["VALIDITY_STATE_KEYS","RECOMMENDED_STATE_KEYS","RECOMMENDED_NUMBER_STATE_KEYS","isRecommended","validity","isNumber","errorable","every","key","errored","includes","defaultGetErrorMessage","options","isBlurEvent","validationMessage","validationType","validate","keys","length","some","defaultIsErrored","value","errorMessage","minLength","maxLength","defaultGetErrorIcon","error","errorIcon"],"mappings":"AA2FA;;;;CAIC,GACD,MAAMA,sBAAwD;IAC5D;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED;;;CAGC,GACD,OAAO,MAAMC,yBAA2D;IACtE;IACA;IACA;CACD,CAAC;AAEF;;;CAGC,GACD,OAAO,MAAMC,gCAAkE;OAC1ED;IACH;IACA;IACA;IACA;CACD,CAAC;AAEF;;;;;;;;;CASC,GACD,MAAME,gBAAgB,CAACC,UAAyBC;IAC9C,MAAMC,YAAYD,WACdH,gCACAD;IAEJ,OAAOD,oBAAoBO,KAAK,CAAC,CAACC;QAChC,MAAMC,UAAUL,QAAQ,CAACI,IAAI;QAC7B,OAAO,CAACC,WAAWH,UAAUI,QAAQ,CAACF;IACxC;AACF;AAEA;;;;;;CAMC,GACD,OAAO,MAAMG,yBAA0C,CAACC;IACtD,MAAM,EACJP,QAAQ,EACRQ,WAAW,EACXT,QAAQ,EACRU,iBAAiB,EACjBC,gBAAgBC,QAAQ,EACzB,GAAGJ;IAEJ,IAAIC,eAAe,CAACC,qBAAqBE,aAAa,UAAU;QAC9D,OAAOF;IACT;IAEA,IAAIE,aAAa,QAAQ;QACvB,OAAO;IACT;IAEA,IAAIA,aAAa,eAAe;QAC9B,OAAOb,cAAcC,UAAUC,YAAYS,oBAAoB;IACjE;IAEA,MAAMG,OAAO,OAAOD,aAAa,WAAW;QAACA;KAAS,GAAGA;IAEzD,OAAOC,KAAKC,MAAM,IAChBlB,oBAAoBmB,IAAI,CAAC,CAACX,MAAQJ,QAAQ,CAACI,IAAI,IAAIS,KAAKP,QAAQ,CAACF,QAC/DM,oBACA;AACN,EAAE;AAuBF;;;;;;;CAOC,GACD,OAAO,MAAMM,mBAA8B,CAACR;IAC1C,MAAM,EAAES,KAAK,EAAEC,YAAY,EAAEC,SAAS,EAAEC,SAAS,EAAEX,WAAW,EAAE,GAAGD;IAEnE,OACE,CAAC,CAACU,gBACD,OAAOE,cAAc,YAAYH,MAAMH,MAAM,GAAGM,aAChDX,eAAe,OAAOU,cAAc,YAAYF,MAAMH,MAAM,GAAGK;AAEpE,EAAE;AAiCF;;;;;CAKC,GACD,OAAO,MAAME,sBAAoC,CAACb;IAChD,MAAM,EAAEc,KAAK,EAAEC,SAAS,EAAE,GAAGf;IAE7B,OAAOc,SAASC;AAClB,EAAE"}

package/dist/hoverMode/useHoverMode.d.ts

@@ -1,8 +1,8 @@
-import type { MouseEvent } from "react";
-import type { UseStateInitializer, UseStateSetter } from "../types.js";
-import type { SimpleHoverModeContext } from "./useHoverModeProvider.js";
+import { type MouseEvent } from "react";
+import { type UseStateInitializer, type UseStateSetter } from "../types.js";
+import { type SimpleHoverModeContext } from "./useHoverModeProvider.js";
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface HoverModeConfigurationOptions extends SimpleHoverModeContext {
     /** @defaultValue `false` */
@@ -17,45 +17,105 @@ export interface HoverModeConfigurationOptions extends SimpleHoverModeContext {
     leaveTimeout?: number;
 }
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ControlledHoverModeOptions extends HoverModeConfigurationOptions {
     setVisible: UseStateSetter<boolean>;
 }
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ControlledHoverModeImplementation {
-    startShowFlow(id?: string | MouseEvent): void;
-    startHideFlow(): void;
-    clearVisibilityTimeout(): void;
+    startShowFlow: (id?: string | MouseEvent) => void;
+    startHideFlow: () => void;
+    clearVisibilityTimeout: () => void;
 }
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface UncontrolledHoverModeOptions extends HoverModeConfigurationOptions {
     defaultVisible?: UseStateInitializer<boolean>;
 }
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface UncontrolledHoverModeImplementation extends ControlledHoverModeImplementation {
     visible: boolean;
     setVisible: UseStateSetter<boolean>;
 }
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface HoverModeImplementation extends ControlledHoverModeImplementation {
     visible?: boolean;
     setVisible?: UseStateSetter<boolean>;
 }
 /**
- * @remarks
- * \@since 2.8.0
- * \@since 5.0.0 This hook no longer returns `handlers` or
+ * The `useHoverMode` hook is used to implement an immediate hover state after
+ * hovering related elements for a short duration. The main use-case is for
+ * showing tooltips immediately after hovering another tooltipped element.
+ *
+ * This relies on creating a context provider using {@link useHoverModeProvider}
+ * to link related elements together.
+ *
+ * @example Example Usage
+ * ```ts
+ * import { type MouseEvent } from "react";
+ *
+ * import {
+ *   type CustomHoverContext,
+ *   useCustomHoverContext,
+ * } from "./useCustomHoverContext.jsx";
+ *
+ * interface CustomHoverModeImplementation {
+ *   onMouseEnter: <E extends HTMLElement>(event: MouseEvent<E>) => void;
+ *   onMouseLeave: <E extends HTMLElement>(event: MouseEvent<E>) => void;
+ * }
+ *
+ * function useCustomHoverMode(): CustomHoverModeImplementation {
+ *   const {
+ *     animatedOnceRef,
+ *     hoverTimeoutRef,
+ *     leaveTimeoutRef,
+ *     enableHoverMode,
+ *     disableHoverMode,
+ *     startDisableTimer,
+ *     clearDisableTimer,
+ *   } = useCustomHoverContext();
+ *   const {
+ *     visible,
+ *     setVisible,
+ *     startShowFlow,
+ *     startHideFlow,
+ *     clearVisibilityTimeout,
+ *   } = useHoverMode({
+ *     hoverTimeout,
+ *     hoverTimeoutRef,
+ *     leaveTimeout,
+ *     leaveTimeoutRef,
+ *     enableHoverMode,
+ *     disableHoverMode,
+ *     startDisableTimer,
+ *     clearDisableTimer,
+ *   });
+ *
+ *   return {
+ *     onMouseEnter(event) {
+ *       startShowFlow(event.currentTarget.id);
+ *     },
+ *     onMouseLeave(event) {
+ *       startHideFlow();
+ *     },
+ *   };
+ * }
+ * ```
+ *
+ * @see The `useTooltip` source code for a real world example.
+ *
+ * @since 2.8.0
+ * @since 5.0.0 This hook no longer returns `handlers` or
  * `stickyHandlers` and does not hide when an element on the page is clicked.
- * \@since 6.0.0 Requires passing the custom hover mode context to
+ * @since 6.0.0 Requires passing the custom hover mode context to
  * work.
  */
 export declare function useHoverMode(options: ControlledHoverModeOptions): ControlledHoverModeImplementation;

package/dist/hoverMode/useHoverMode.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/hoverMode/useHoverMode.ts"],"sourcesContent":["\"use client\";\nimport type { MouseEvent } from \"react\";\nimport { useCallback, useEffect, useRef, useState } from \"react\";\nimport type { UseStateInitializer, UseStateSetter } from \"../types.js\";\nimport type { SimpleHoverModeContext } from \"./useHoverModeProvider.js\";\n\n/**\n * @remarks \\@since 6.0.0\n */\nexport interface HoverModeConfigurationOptions extends SimpleHoverModeContext {\n  /** @defaultValue `false` */\n  disabled?: boolean;\n\n  /**\n   * This can be used to override the `HoverModeContext`'s hover time.\n   */\n  hoverTimeout?: number;\n\n  /**\n   * This can be used to override the `HoverModeContext`'s leave time.\n   */\n  leaveTimeout?: number;\n}\n\n/**\n * @remarks \\@since 6.0.0\n */\nexport interface ControlledHoverModeOptions\n  extends HoverModeConfigurationOptions {\n  setVisible: UseStateSetter<boolean>;\n}\n\n/**\n * @remarks \\@since 6.0.0\n */\nexport interface ControlledHoverModeImplementation {\n  startShowFlow(id?: string | MouseEvent): void;\n  startHideFlow(): void;\n  clearVisibilityTimeout(): void;\n}\n\n/**\n * @remarks \\@since 6.0.0\n */\nexport interface UncontrolledHoverModeOptions\n  extends HoverModeConfigurationOptions {\n  defaultVisible?: UseStateInitializer<boolean>;\n}\n\n/**\n * @remarks \\@since 6.0.0\n */\nexport interface UncontrolledHoverModeImplementation\n  extends ControlledHoverModeImplementation {\n  visible: boolean;\n  setVisible: UseStateSetter<boolean>;\n}\n\n/**\n * @remarks \\@since 6.0.0\n */\nexport interface HoverModeImplementation\n  extends ControlledHoverModeImplementation {\n  visible?: boolean;\n  setVisible?: UseStateSetter<boolean>;\n}\n\n/**\n * @remarks\n * \\@since 2.8.0\n * \\@since 5.0.0 This hook no longer returns `handlers` or\n * `stickyHandlers` and does not hide when an element on the page is clicked.\n * \\@since 6.0.0 Requires passing the custom hover mode context to\n * work.\n */\nexport function useHoverMode(\n  options: ControlledHoverModeOptions\n): ControlledHoverModeImplementation;\nexport function useHoverMode(\n  options: UncontrolledHoverModeOptions\n): UncontrolledHoverModeImplementation;\nexport function useHoverMode(\n  options: ControlledHoverModeOptions | UncontrolledHoverModeOptions\n): HoverModeImplementation {\n  const {\n    disabled,\n    hoverTimeout: hoverTime,\n    hoverTimeoutRef,\n    leaveTimeout: leaveTime,\n    leaveTimeoutRef,\n    enableHoverMode,\n    disableHoverMode,\n    startDisableTimer,\n    clearDisableTimer,\n    setVisible: propSetVisible,\n    defaultVisible = false,\n  } = options as ControlledHoverModeOptions & UncontrolledHoverModeOptions;\n\n  const state = useState(defaultVisible);\n  let visible: boolean | undefined;\n  let setVisible: UseStateSetter<boolean>;\n  if (typeof propSetVisible !== \"undefined\") {\n    setVisible = propSetVisible;\n  } else {\n    [visible, setVisible] = state;\n  }\n\n  const visibilityTimeout = useRef<number | undefined>();\n  const clearVisibilityTimeout = useCallback(() => {\n    window.clearTimeout(visibilityTimeout.current);\n  }, []);\n\n  // if the element is near the viewport edge, the mouseleave event might not\n  // trigger correctly. for these cases, just clear any timeouts to be safe.\n  // do not hide the visibility so that you can still inspect things in the\n  // devtools\n  useEffect(() => {\n    if (disabled) {\n      return;\n    }\n\n    const handler = (): void => {\n      window.clearTimeout(visibilityTimeout.current);\n\n      // might need to play with this more or make it configurable. if the mouse\n      // leaves the window, you're _normally_ not interacting with the app\n      // anymore and state should reset.\n      disableHoverMode();\n    };\n\n    document.addEventListener(\"mouseleave\", handler);\n    return () => {\n      document.removeEventListener(\"mouseleave\", handler);\n    };\n  }, [disableHoverMode, disabled]);\n\n  useEffect(() => {\n    return () => {\n      window.clearTimeout(visibilityTimeout.current);\n    };\n  }, []);\n\n  return {\n    visible,\n    setVisible: setVisible === propSetVisible ? undefined : setVisible,\n    startShowFlow: useCallback(\n      (eventOrId) => {\n        const hoverTimeout = hoverTime ?? hoverTimeoutRef.current;\n        if (disabled || typeof hoverTimeout === \"undefined\") {\n          return;\n        }\n\n        let id: string;\n        if (typeof eventOrId === \"string\" || typeof eventOrId === \"undefined\") {\n          id = eventOrId || \"\";\n        } else {\n          id = eventOrId.currentTarget.id;\n        }\n\n        clearDisableTimer();\n        clearVisibilityTimeout();\n        visibilityTimeout.current = window.setTimeout(() => {\n          enableHoverMode(id);\n          setVisible(true);\n        }, hoverTimeout);\n      },\n      [\n        clearDisableTimer,\n        clearVisibilityTimeout,\n        disabled,\n        enableHoverMode,\n        hoverTime,\n        hoverTimeoutRef,\n        setVisible,\n      ]\n    ),\n    startHideFlow: useCallback(() => {\n      if (disabled) {\n        return;\n      }\n\n      startDisableTimer();\n      clearVisibilityTimeout();\n      visibilityTimeout.current = window.setTimeout(() => {\n        setVisible(false);\n      }, leaveTime ?? leaveTimeoutRef.current);\n    }, [\n      clearVisibilityTimeout,\n      disabled,\n      leaveTime,\n      leaveTimeoutRef,\n      setVisible,\n      startDisableTimer,\n    ]),\n    clearVisibilityTimeout,\n  };\n}\n"],"names":["useCallback","useEffect","useRef","useState","useHoverMode","options","disabled","hoverTimeout","hoverTime","hoverTimeoutRef","leaveTimeout","leaveTime","leaveTimeoutRef","enableHoverMode","disableHoverMode","startDisableTimer","clearDisableTimer","setVisible","propSetVisible","defaultVisible","state","visible","visibilityTimeout","clearVisibilityTimeout","window","clearTimeout","current","handler","document","addEventListener","removeEventListener","undefined","startShowFlow","eventOrId","id","currentTarget","setTimeout","startHideFlow"],"mappings":"AAAA;AAEA,SAASA,WAAW,EAAEC,SAAS,EAAEC,MAAM,EAAEC,QAAQ,QAAQ,QAAQ;AA+EjE,OAAO,SAASC,aACdC,OAAkE;IAElE,MAAM,EACJC,QAAQ,EACRC,cAAcC,SAAS,EACvBC,eAAe,EACfC,cAAcC,SAAS,EACvBC,eAAe,EACfC,eAAe,EACfC,gBAAgB,EAChBC,iBAAiB,EACjBC,iBAAiB,EACjBC,YAAYC,cAAc,EAC1BC,iBAAiB,KAAK,EACvB,GAAGd;IAEJ,MAAMe,QAAQjB,SAASgB;IACvB,IAAIE;IACJ,IAAIJ;IACJ,IAAI,OAAOC,mBAAmB,aAAa;QACzCD,aAAaC;IACf,OAAO;QACL,CAACG,SAASJ,WAAW,GAAGG;IAC1B;IAEA,MAAME,oBAAoBpB;IAC1B,MAAMqB,yBAAyBvB,YAAY;QACzCwB,OAAOC,YAAY,CAACH,kBAAkBI,OAAO;IAC/C,GAAG,EAAE;IAEL,2EAA2E;IAC3E,0EAA0E;IAC1E,yEAAyE;IACzE,WAAW;IACXzB,UAAU;QACR,IAAIK,UAAU;YACZ;QACF;QAEA,MAAMqB,UAAU;YACdH,OAAOC,YAAY,CAACH,kBAAkBI,OAAO;YAE7C,0EAA0E;YAC1E,oEAAoE;YACpE,kCAAkC;YAClCZ;QACF;QAEAc,SAASC,gBAAgB,CAAC,cAAcF;QACxC,OAAO;YACLC,SAASE,mBAAmB,CAAC,cAAcH;QAC7C;IACF,GAAG;QAACb;QAAkBR;KAAS;IAE/BL,UAAU;QACR,OAAO;YACLuB,OAAOC,YAAY,CAACH,kBAAkBI,OAAO;QAC/C;IACF,GAAG,EAAE;IAEL,OAAO;QACLL;QACAJ,YAAYA,eAAeC,iBAAiBa,YAAYd;QACxDe,eAAehC,YACb,CAACiC;YACC,MAAM1B,eAAeC,aAAaC,gBAAgBiB,OAAO;YACzD,IAAIpB,YAAY,OAAOC,iBAAiB,aAAa;gBACnD;YACF;YAEA,IAAI2B;YACJ,IAAI,OAAOD,cAAc,YAAY,OAAOA,cAAc,aAAa;gBACrEC,KAAKD,aAAa;YACpB,OAAO;gBACLC,KAAKD,UAAUE,aAAa,CAACD,EAAE;YACjC;YAEAlB;YACAO;YACAD,kBAAkBI,OAAO,GAAGF,OAAOY,UAAU,CAAC;gBAC5CvB,gBAAgBqB;gBAChBjB,WAAW;YACb,GAAGV;QACL,GACA;YACES;YACAO;YACAjB;YACAO;YACAL;YACAC;YACAQ;SACD;QAEHoB,eAAerC,YAAY;YACzB,IAAIM,UAAU;gBACZ;YACF;YAEAS;YACAQ;YACAD,kBAAkBI,OAAO,GAAGF,OAAOY,UAAU,CAAC;gBAC5CnB,WAAW;YACb,GAAGN,aAAaC,gBAAgBc,OAAO;QACzC,GAAG;YACDH;YACAjB;YACAK;YACAC;YACAK;YACAF;SACD;QACDQ;IACF;AACF"}
+{"version":3,"sources":["../../src/hoverMode/useHoverMode.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  type MouseEvent,\n  useCallback,\n  useEffect,\n  useRef,\n  useState,\n} from \"react\";\n\nimport { type UseStateInitializer, type UseStateSetter } from \"../types.js\";\nimport {\n  type SimpleHoverModeContext,\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  type useHoverModeProvider,\n} from \"./useHoverModeProvider.js\";\n\n/**\n * @since 6.0.0\n */\nexport interface HoverModeConfigurationOptions extends SimpleHoverModeContext {\n  /** @defaultValue `false` */\n  disabled?: boolean;\n\n  /**\n   * This can be used to override the `HoverModeContext`'s hover time.\n   */\n  hoverTimeout?: number;\n\n  /**\n   * This can be used to override the `HoverModeContext`'s leave time.\n   */\n  leaveTimeout?: number;\n}\n\n/**\n * @since 6.0.0\n */\nexport interface ControlledHoverModeOptions\n  extends HoverModeConfigurationOptions {\n  setVisible: UseStateSetter<boolean>;\n}\n\n/**\n * @since 6.0.0\n */\nexport interface ControlledHoverModeImplementation {\n  startShowFlow: (id?: string | MouseEvent) => void;\n  startHideFlow: () => void;\n  clearVisibilityTimeout: () => void;\n}\n\n/**\n * @since 6.0.0\n */\nexport interface UncontrolledHoverModeOptions\n  extends HoverModeConfigurationOptions {\n  defaultVisible?: UseStateInitializer<boolean>;\n}\n\n/**\n * @since 6.0.0\n */\nexport interface UncontrolledHoverModeImplementation\n  extends ControlledHoverModeImplementation {\n  visible: boolean;\n  setVisible: UseStateSetter<boolean>;\n}\n\n/**\n * @since 6.0.0\n */\nexport interface HoverModeImplementation\n  extends ControlledHoverModeImplementation {\n  visible?: boolean;\n  setVisible?: UseStateSetter<boolean>;\n}\n\n/**\n * The `useHoverMode` hook is used to implement an immediate hover state after\n * hovering related elements for a short duration. The main use-case is for\n * showing tooltips immediately after hovering another tooltipped element.\n *\n * This relies on creating a context provider using {@link useHoverModeProvider}\n * to link related elements together.\n *\n * @example Example Usage\n * ```ts\n * import { type MouseEvent } from \"react\";\n *\n * import {\n *   type CustomHoverContext,\n *   useCustomHoverContext,\n * } from \"./useCustomHoverContext.jsx\";\n *\n * interface CustomHoverModeImplementation {\n *   onMouseEnter: <E extends HTMLElement>(event: MouseEvent<E>) => void;\n *   onMouseLeave: <E extends HTMLElement>(event: MouseEvent<E>) => void;\n * }\n *\n * function useCustomHoverMode(): CustomHoverModeImplementation {\n *   const {\n *     animatedOnceRef,\n *     hoverTimeoutRef,\n *     leaveTimeoutRef,\n *     enableHoverMode,\n *     disableHoverMode,\n *     startDisableTimer,\n *     clearDisableTimer,\n *   } = useCustomHoverContext();\n *   const {\n *     visible,\n *     setVisible,\n *     startShowFlow,\n *     startHideFlow,\n *     clearVisibilityTimeout,\n *   } = useHoverMode({\n *     hoverTimeout,\n *     hoverTimeoutRef,\n *     leaveTimeout,\n *     leaveTimeoutRef,\n *     enableHoverMode,\n *     disableHoverMode,\n *     startDisableTimer,\n *     clearDisableTimer,\n *   });\n *\n *   return {\n *     onMouseEnter(event) {\n *       startShowFlow(event.currentTarget.id);\n *     },\n *     onMouseLeave(event) {\n *       startHideFlow();\n *     },\n *   };\n * }\n * ```\n *\n * @see The `useTooltip` source code for a real world example.\n *\n * @since 2.8.0\n * @since 5.0.0 This hook no longer returns `handlers` or\n * `stickyHandlers` and does not hide when an element on the page is clicked.\n * @since 6.0.0 Requires passing the custom hover mode context to\n * work.\n */\nexport function useHoverMode(\n  options: ControlledHoverModeOptions\n): ControlledHoverModeImplementation;\nexport function useHoverMode(\n  options: UncontrolledHoverModeOptions\n): UncontrolledHoverModeImplementation;\nexport function useHoverMode(\n  options: ControlledHoverModeOptions | UncontrolledHoverModeOptions\n): HoverModeImplementation {\n  const {\n    disabled,\n    hoverTimeout: hoverTime,\n    hoverTimeoutRef,\n    leaveTimeout: leaveTime,\n    leaveTimeoutRef,\n    enableHoverMode,\n    disableHoverMode,\n    startDisableTimer,\n    clearDisableTimer,\n    setVisible: propSetVisible,\n    defaultVisible = false,\n  } = options as ControlledHoverModeOptions & UncontrolledHoverModeOptions;\n\n  const state = useState(defaultVisible);\n  let visible: boolean | undefined;\n  let setVisible: UseStateSetter<boolean>;\n  if (typeof propSetVisible !== \"undefined\") {\n    setVisible = propSetVisible;\n  } else {\n    [visible, setVisible] = state;\n  }\n\n  const visibilityTimeout = useRef<number | undefined>();\n  const clearVisibilityTimeout = useCallback(() => {\n    window.clearTimeout(visibilityTimeout.current);\n  }, []);\n\n  // if the element is near the viewport edge, the mouseleave event might not\n  // trigger correctly. for these cases, just clear any timeouts to be safe.\n  // do not hide the visibility so that you can still inspect things in the\n  // devtools\n  useEffect(() => {\n    if (disabled) {\n      return;\n    }\n\n    const handler = (): void => {\n      window.clearTimeout(visibilityTimeout.current);\n\n      // might need to play with this more or make it configurable. if the mouse\n      // leaves the window, you're _normally_ not interacting with the app\n      // anymore and state should reset.\n      disableHoverMode();\n    };\n\n    document.addEventListener(\"mouseleave\", handler);\n    return () => {\n      document.removeEventListener(\"mouseleave\", handler);\n    };\n  }, [disableHoverMode, disabled]);\n\n  useEffect(() => {\n    return () => {\n      window.clearTimeout(visibilityTimeout.current);\n    };\n  }, []);\n\n  return {\n    visible,\n    setVisible: setVisible === propSetVisible ? undefined : setVisible,\n    startShowFlow: useCallback(\n      (eventOrId) => {\n        const hoverTimeout = hoverTime ?? hoverTimeoutRef.current;\n        if (disabled || typeof hoverTimeout === \"undefined\") {\n          return;\n        }\n\n        let id: string;\n        if (typeof eventOrId === \"string\" || typeof eventOrId === \"undefined\") {\n          id = eventOrId || \"\";\n        } else {\n          id = eventOrId.currentTarget.id;\n        }\n\n        clearDisableTimer();\n        clearVisibilityTimeout();\n        visibilityTimeout.current = window.setTimeout(() => {\n          enableHoverMode(id);\n          setVisible(true);\n        }, hoverTimeout);\n      },\n      [\n        clearDisableTimer,\n        clearVisibilityTimeout,\n        disabled,\n        enableHoverMode,\n        hoverTime,\n        hoverTimeoutRef,\n        setVisible,\n      ]\n    ),\n    startHideFlow: useCallback(() => {\n      if (disabled) {\n        return;\n      }\n\n      startDisableTimer();\n      clearVisibilityTimeout();\n      visibilityTimeout.current = window.setTimeout(() => {\n        setVisible(false);\n      }, leaveTime ?? leaveTimeoutRef.current);\n    }, [\n      clearVisibilityTimeout,\n      disabled,\n      leaveTime,\n      leaveTimeoutRef,\n      setVisible,\n      startDisableTimer,\n    ]),\n    clearVisibilityTimeout,\n  };\n}\n"],"names":["useCallback","useEffect","useRef","useState","useHoverMode","options","disabled","hoverTimeout","hoverTime","hoverTimeoutRef","leaveTimeout","leaveTime","leaveTimeoutRef","enableHoverMode","disableHoverMode","startDisableTimer","clearDisableTimer","setVisible","propSetVisible","defaultVisible","state","visible","visibilityTimeout","clearVisibilityTimeout","window","clearTimeout","current","handler","document","addEventListener","removeEventListener","undefined","startShowFlow","eventOrId","id","currentTarget","setTimeout","startHideFlow"],"mappings":"AAAA;AAEA,SAEEA,WAAW,EACXC,SAAS,EACTC,MAAM,EACNC,QAAQ,QACH,QAAQ;AAgJf,OAAO,SAASC,aACdC,OAAkE;IAElE,MAAM,EACJC,QAAQ,EACRC,cAAcC,SAAS,EACvBC,eAAe,EACfC,cAAcC,SAAS,EACvBC,eAAe,EACfC,eAAe,EACfC,gBAAgB,EAChBC,iBAAiB,EACjBC,iBAAiB,EACjBC,YAAYC,cAAc,EAC1BC,iBAAiB,KAAK,EACvB,GAAGd;IAEJ,MAAMe,QAAQjB,SAASgB;IACvB,IAAIE;IACJ,IAAIJ;IACJ,IAAI,OAAOC,mBAAmB,aAAa;QACzCD,aAAaC;IACf,OAAO;QACL,CAACG,SAASJ,WAAW,GAAGG;IAC1B;IAEA,MAAME,oBAAoBpB;IAC1B,MAAMqB,yBAAyBvB,YAAY;QACzCwB,OAAOC,YAAY,CAACH,kBAAkBI,OAAO;IAC/C,GAAG,EAAE;IAEL,2EAA2E;IAC3E,0EAA0E;IAC1E,yEAAyE;IACzE,WAAW;IACXzB,UAAU;QACR,IAAIK,UAAU;YACZ;QACF;QAEA,MAAMqB,UAAU;YACdH,OAAOC,YAAY,CAACH,kBAAkBI,OAAO;YAE7C,0EAA0E;YAC1E,oEAAoE;YACpE,kCAAkC;YAClCZ;QACF;QAEAc,SAASC,gBAAgB,CAAC,cAAcF;QACxC,OAAO;YACLC,SAASE,mBAAmB,CAAC,cAAcH;QAC7C;IACF,GAAG;QAACb;QAAkBR;KAAS;IAE/BL,UAAU;QACR,OAAO;YACLuB,OAAOC,YAAY,CAACH,kBAAkBI,OAAO;QAC/C;IACF,GAAG,EAAE;IAEL,OAAO;QACLL;QACAJ,YAAYA,eAAeC,iBAAiBa,YAAYd;QACxDe,eAAehC,YACb,CAACiC;YACC,MAAM1B,eAAeC,aAAaC,gBAAgBiB,OAAO;YACzD,IAAIpB,YAAY,OAAOC,iBAAiB,aAAa;gBACnD;YACF;YAEA,IAAI2B;YACJ,IAAI,OAAOD,cAAc,YAAY,OAAOA,cAAc,aAAa;gBACrEC,KAAKD,aAAa;YACpB,OAAO;gBACLC,KAAKD,UAAUE,aAAa,CAACD,EAAE;YACjC;YAEAlB;YACAO;YACAD,kBAAkBI,OAAO,GAAGF,OAAOY,UAAU,CAAC;gBAC5CvB,gBAAgBqB;gBAChBjB,WAAW;YACb,GAAGV;QACL,GACA;YACES;YACAO;YACAjB;YACAO;YACAL;YACAC;YACAQ;SACD;QAEHoB,eAAerC,YAAY;YACzB,IAAIM,UAAU;gBACZ;YACF;YAEAS;YACAQ;YACAD,kBAAkBI,OAAO,GAAGF,OAAOY,UAAU,CAAC;gBAC5CnB,WAAW;YACb,GAAGN,aAAaC,gBAAgBc,OAAO;QACzC,GAAG;YACDH;YACAjB;YACAK;YACAC;YACAK;YACAF;SACD;QACDQ;IACF;AACF"}

package/dist/hoverMode/useHoverModeProvider.d.ts

@@ -1,9 +1,8 @@
-import type { NonNullMutableRef, NonNullRef } from "../types.js";
-/** @remarks \@since 6.0.0 */
+import { type NonNullMutableRef, type NonNullRef } from "../types.js";
+/** @since 6.0.0 */
 export interface SimpleHoverModeContext {
     /**
-     * @example
-     * Main Usage
+     * @example Main Usage
      * ```ts
      * onMouseEnter(event) {
      *   const hoverTimeout = hoverTimeoutRef.current;
@@ -23,8 +22,7 @@ export interface SimpleHoverModeContext {
      */
     hoverTimeoutRef: NonNullRef<number | undefined>;
     /**
-     * @example
-     * Main Usage
+     * @example Main Usage
      * ```ts
      * onMouseLeave() {
      *   if (mode === "touch") {
@@ -46,25 +44,24 @@ export interface SimpleHoverModeContext {
      *
      * @see {@link hoverTimeoutRef} for an example.
      */
-    enableHoverMode(activeId: string): void;
+    enableHoverMode: (activeId: string) => void;
     /**
      * Disables all hover mode behavior by clearing all timeouts and resetting
      * internal state.
      */
-    disableHoverMode(): void;
+    disableHoverMode: () => void;
     /**
      * @see {@link leaveTimeoutRef} for an example.
      */
-    startDisableTimer(): void;
+    startDisableTimer: () => void;
     /**
      * @see {@link hoverTimeoutRef} for an example.
      */
-    clearDisableTimer(): void;
+    clearDisableTimer: () => void;
 }
 /**
- * @remarks
- * \@since 2.8.0
- * \@since 6.0.0 Uses refs to increase performance by preventing unneeded
+ * @since 2.8.0
+ * @since 6.0.0 Uses refs to increase performance by preventing unneeded
  * re-renders of the entire hover mode provider's component tree. The API also
  * changed to support custom hover mode providers.
  */
@@ -92,7 +89,7 @@ export interface HoverModeContext extends SimpleHoverModeContext {
     animatedOnceRef: NonNullMutableRef<boolean>;
 }
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface CreateHoverModeContextOptions {
     /**
@@ -114,16 +111,16 @@ export interface CreateHoverModeContextOptions {
      * visibility to `false`.
      *
      * @defaultValue `0`
-     * @remarks \@since 6.0.0 This was renamed from `exitVisibilityDelay` and the
+     * @since 6.0.0 This was renamed from `exitVisibilityDelay` and the
      * default value changed from `300` to `0`.
      */
     leaveTimeout?: number;
 }
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export declare function createHoverModeContext(options?: CreateHoverModeContextOptions): Readonly<HoverModeContext>;
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface HoverModeConfiguration extends CreateHoverModeContextOptions {
     /**
      * The amount of time to wait before disabling the hover mode behavior if none
@@ -140,25 +137,34 @@ export interface HoverModeConfiguration extends CreateHoverModeContextOptions {
     forceRerender?: boolean;
 }
 /**
- * @example
- * Creating a Hover Mode Group
+ * @example Creating a Hover Mode Group
  * ```tsx
- * import type {
- *   HoverModeConfiguration,
- *   HoverModeContext,
- * } from "@react-md/core";
  * import {
+ *   type HoverModeContext,
  *   createHoverModeContext,
  *   useHoverModeProvider,
- * } from "@react-md/core";
- * import type { ReactElement } from "react";
- * import { createContext, useContext } from "react";
+ * } from "@react-md/core/hoverMode/useHoverModeProvider";
+ * import {
+ *   type ReactElement,
+ *   type ReactNode,
+ *   createContext,
+ *   useContext,
+ * } from "react";
  *
- * // extend as needed
- * type CustomHoverMode = HoverModeContext;
+ * export interface CustomHoverContext extends HoverModeContext {
+ *   // any additional fields in the context
+ * }
  *
- * // you can also add defaults if there is no parent provider.
- * const context = createContext<CustomHoverMode>(createHoverModeContext());
+ * const context = createContext<CustomHoverContext>(
+ *   createHoverModeContext()
+ *   // you can also provide default values if needed when the context provider
+ *   // isn't a parent component. the following are the defaults
+ *   // createHoverModeContext({
+ *   //    hoverTimeout: undefined,
+ *   //    leaveTimeout: 0,
+ *   //    defaultActiveId: "",
+ *   // })
+ * );
  * const { Provider } = context;
  *
  * interface Props extends HoverModeConfiguration {
@@ -186,7 +192,7 @@ export interface HoverModeConfiguration extends CreateHoverModeContextOptions {
  *
  * @see {@link CreateHoverModeContextOptions}
  * @see {@link useHoverMode}
- * @remarks \@since 6.0.0 The `HoverModeProvider` component was replaced by this
+ * @since 6.0.0 The `HoverModeProvider` component was replaced by this
  * hook implementation. After developing the `MenuBar`, I realized the hover
  * mode should normally be grouped by related components or types instead of a
  * top-level catch all.

package/dist/hoverMode/useHoverModeProvider.js

@@ -4,7 +4,7 @@ const noop = ()=>{
 // do nothing
 };
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */ export function createHoverModeContext(options = {}) {
     const { defaultActiveId = "", hoverTimeout, leaveTimeout = 0 } = options;
     return {
@@ -28,25 +28,34 @@ const noop = ()=>{
     };
 }
 /**
- * @example
- * Creating a Hover Mode Group
+ * @example Creating a Hover Mode Group
  * ```tsx
- * import type {
- *   HoverModeConfiguration,
- *   HoverModeContext,
- * } from "@react-md/core";
  * import {
+ *   type HoverModeContext,
  *   createHoverModeContext,
  *   useHoverModeProvider,
- * } from "@react-md/core";
- * import type { ReactElement } from "react";
- * import { createContext, useContext } from "react";
+ * } from "@react-md/core/hoverMode/useHoverModeProvider";
+ * import {
+ *   type ReactElement,
+ *   type ReactNode,
+ *   createContext,
+ *   useContext,
+ * } from "react";
  *
- * // extend as needed
- * type CustomHoverMode = HoverModeContext;
+ * export interface CustomHoverContext extends HoverModeContext {
+ *   // any additional fields in the context
+ * }
  *
- * // you can also add defaults if there is no parent provider.
- * const context = createContext<CustomHoverMode>(createHoverModeContext());
+ * const context = createContext<CustomHoverContext>(
+ *   createHoverModeContext()
+ *   // you can also provide default values if needed when the context provider
+ *   // isn't a parent component. the following are the defaults
+ *   // createHoverModeContext({
+ *   //    hoverTimeout: undefined,
+ *   //    leaveTimeout: 0,
+ *   //    defaultActiveId: "",
+ *   // })
+ * );
  * const { Provider } = context;
  *
  * interface Props extends HoverModeConfiguration {
@@ -74,7 +83,7 @@ const noop = ()=>{
  *
  * @see {@link CreateHoverModeContextOptions}
  * @see {@link useHoverMode}
- * @remarks \@since 6.0.0 The `HoverModeProvider` component was replaced by this
+ * @since 6.0.0 The `HoverModeProvider` component was replaced by this
  * hook implementation. After developing the `MenuBar`, I realized the hover
  * mode should normally be grouped by related components or types instead of a
  * top-level catch all.