@trackunit/react-core-hooks 1.15.26 → 1.15.28

package/index.cjs.js

@@ -91,7 +91,48 @@ const useAssetSorting = () => {
 };
 
 /**
- * This is a hook to use the ConfirmationDialogContext.
+ * Shows a modal confirmation dialog and returns the user's choice as a Promise.
+ *
+ * Resolves to `"PRIMARY"`, `"SECONDARY"`, or `"CLOSE"` depending on which button
+ * (or dismiss action) the user selects.
+ *
+ * **When to use:**
+ * - Use `useConfirmationDialog` for destructive or irreversible actions (delete, discard
+ *   changes, revoke access) where you need explicit user consent before proceeding.
+ * - Use `useToast` instead when you only need to *inform* the user — toasts are
+ *   non-blocking and don't require a decision.
+ * - Do **not** build custom confirmation modals — this hook connects to the host-provided
+ *   dialog so the UX is consistent across the platform.
+ *
+ * @example
+ * ```tsx
+ * import { Button } from "@trackunit/react-components";
+ * import { useConfirmationDialog } from "@trackunit/react-core-hooks";
+ *
+ * const DeleteButton = ({ onDelete }: { onDelete: () => void }) => {
+ *   const { confirm } = useConfirmationDialog();
+ *
+ *   return (
+ *     <Button
+ *       onClick={async () => {
+ *         const response = await confirm({
+ *           title: "Delete Item",
+ *           message: "Are you sure? This action cannot be undone.",
+ *           primaryActionLabel: "Delete",
+ *           secondaryActionLabel: "Cancel",
+ *           primaryActionType: "primary-danger",
+ *         });
+ *
+ *         if (response === "PRIMARY") {
+ *           onDelete();
+ *         }
+ *       }}
+ *     >
+ *       Delete
+ *     </Button>
+ *   );
+ * };
+ * ```
  */
 const useConfirmationDialog = () => {
     const confirmationDialogContext = react.useContext(reactCoreContextsApi.ConfirmationDialogContext);
@@ -102,14 +143,19 @@ const useConfirmationDialog = () => {
 };
 
 /**
- * This is a hook to use the EnvironmentContext.
+ * Returns the host environment configuration (API keys, service URLs, build metadata).
+ *
+ * **When to use:**
+ * - Use `useEnvironment` to access platform-level configuration such as the Google Maps
+ *   API key, GraphQL endpoint URLs, auth issuer, or build version.
+ * - Use `useWidgetConfig` instead for per-widget configuration inside dashboards.
+ * - Do **not** hardcode service URLs or API keys — always read them from this hook.
  *
  * @requires EnvironmentContext
  * @example
  * import { useEnvironment } from "@trackunit/react-core-hooks";
  * const { googleMapsApiKey } = useEnvironment();
- * // use api key for something...
- * @see (@link EnvironmentState)
+ * @see EnvironmentState
  */
 const useEnvironment = () => {
     const context = react.useContext(reactCoreContextsApi.EnvironmentContext);
@@ -325,9 +371,14 @@ const useGeolocation = (options) => {
 };
 
 /**
- * This is a hook to use the TokenContext.
+ * Returns the current authentication token from the TokenContext.
+ *
+ * **When to use:**
+ * - Use `useToken` when you need the raw JWT bearer token for authenticated API calls
+ *   outside the GraphQL layer (e.g. REST endpoints, file uploads, WebSockets).
+ * - Use `useCurrentUser` instead when you need the user's identity or account info.
+ * - Do **not** use for GraphQL requests — the Apollo client already attaches the token.
  *
- * @requires TokenProvider
  * @example
  * import { useToken } from "@trackunit/react-core-hooks";
  * const { token } = useToken();
@@ -505,6 +556,16 @@ const accessReducer = (_state, action) => {
  * Hook to check if the current user has access to a navigation target.
  * Useful for conditionally rendering links based on user permissions.
  *
+ * Supports single checks, `oneOf` (any match), and `requireAll` (every match) criteria.
+ *
+ * **When to use:**
+ * - Use `useHasAccessTo` to conditionally show/hide navigation links or action buttons
+ *   based on whether the user can reach the target page or entity.
+ * - Use `useUserPermission` instead when you need a synchronous check against a
+ *   permission string on the user object rather than a navigation-target check.
+ * - Use the `hasAccessTo` method from `useNavigateInHost` for a one-off imperative
+ *   check (e.g. inside an event handler) rather than a reactive/rendered result.
+ *
  * @requires NavigationContext
  * @example
  * import { useHasAccessTo } from "@trackunit/react-core-hooks";
@@ -553,12 +614,26 @@ const useHasAccessTo = (options) => {
 };
 
 /**
- * This is a hook to use the NavigationContext.
+ * Hook to navigate programmatically within the Trackunit Manager or between Iris Apps.
+ *
+ * ### When to use
+ * Use `useNavigateInHost` when you need to navigate between Manager pages, entity home
+ * pages, or Iris Apps from component logic (e.g. after a mutation, on row click, in a
+ * redirect guard). Use the `get*Url` methods when you need an href for an `<a>` tag.
+ * Use `hasAccessTo` before showing navigation options the user may not have access to.
+ *
+ * ### When not to use
+ * Do not use for in-page anchor scrolling or query-param changes within the same
+ * Iris App — use your router directly.
  *
  * @requires NavigationContext
  * @example
  * import { useNavigateInHost } from "@trackunit/react-core-hooks";
- * @see (@link NavigationRuntimeApi)
+ * const { gotoAssetHome, gotoFleetApp } = useNavigateInHost();
+ *
+ * gotoAssetHome("abc-123", { page: "status" });
+ * gotoFleetApp({ page: "assets" });
+ * @see {@link NavigationRuntimeApi}
  */
 const useNavigateInHost = () => {
     const context = react.useContext(reactCoreContextsApi.NavigationContext);
@@ -863,20 +938,18 @@ const useTimeRange = () => {
 };
 
 /**
- * This is a hook to use the ToastContext.
+ * Hook to show toast notifications via the ToastContext.
  *
  * @requires ToastProvider
  * @example
  * import { useToast } from "@trackunit/react-core-hooks";
  * const { addToast } = useToast();
- * // use the toast
- * error &&
- *  addToast({
- *    intent: "warning",
- *    title: t("assetHome.specification.failedToSave"),
- *    description: error?.message,
- *    duration: 3000,
- *  });
+ *
+ * addToast({
+ *   intent: "success",
+ *   title: "Asset deleted",
+ *   id: "deletion-status",
+ * });
  * @see { ToastContextValue }
  */
 const useToast = () => {
@@ -888,14 +961,23 @@ const useToast = () => {
 };
 
 /**
- * This is a hook providing the CurrentUserContext.
+ * Hook providing the authenticated user's profile, account, and permission data
+ * from the CurrentUserContext.
+ *
+ * ### When to use
+ * Use `useCurrentUser` when you need the user's identity or account context — displaying
+ * the user's name, resolving the effective account ID, or branching logic based on
+ * `isAssuming` or `isTrackunitUser`.
+ *
+ * ### When not to use
+ * - If you only need a boolean check for a single permission — use `useUserPermission`.
+ * - To gate entire routes — prefer server-side access control or `hasAccessTo` from
+ *   `useNavigateInHost`.
  *
- * @requires CurrentUserProvider
  * @example
  * import { useCurrentUser } from "@trackunit/react-core-hooks";
  * const { assumedUser, accountId } = useCurrentUser();
  *
- * //use it for something
  * const { data, loading } = useGetAccountByIdQuery({
  *    variables: { accountId: assumedUser?.accountId || accountId || "" },
  * });
@@ -1041,8 +1123,31 @@ const setGlobalLanguage = (language) => {
 /**
  * Hook that checks if the current user has a given permission.
  *
+ * ### When to use
+ * Use `useUserPermission` to conditionally show or hide UI based on a single permission —
+ * delete buttons, admin panels, export actions, or any feature behind an access check.
+ *
+ * ### When not to use
+ * - When you need multiple user fields (name, account, assuming state) or need to check
+ *   several permissions at once — use `useCurrentUser`.
+ * - To gate navigation targets — use `hasAccessTo` from `useNavigateInHost`.
+ *
  * @param requiredPermission - The permission to check for typesafe string.
- * @returns {HasAccess} - true if the user has the permission, false if not and null if we could not determine.
+ * @returns {boolean} `true` if the user has the permission, `false` otherwise (including while permissions are still loading).
+ * @example
+ * ```tsx
+ * import { useUserPermission } from "@trackunit/react-core-hooks";
+ *
+ * const DeleteButton = ({ assetId }: { assetId: string }) => {
+ *   const canDelete = useUserPermission("asset:delete");
+ *
+ *   if (!canDelete) {
+ *     return null;
+ *   }
+ *
+ *   return <Button onClick={() => deleteAsset(assetId)}>Delete</Button>;
+ * };
+ * ```
  */
 const useUserPermission = (requiredPermission) => {
     const { permissions } = useCurrentUser();
@@ -1150,7 +1255,6 @@ const useSettingsUtils = () => {
 /**
  * This is a hook to use the WidgetConfigProvider.
  *
- * @requires WidgetConfigProvider
  * @example
  * import { useWidgetConfigAsync } from "@trackunit/react-core-hooks";
  *
@@ -1191,17 +1295,19 @@ const INITIAL_WIDGET_DATA_STATE = {
     title: null,
 };
 /**
- * This is a hook to use the WidgetConfigContext.
+ * Manages a dashboard widget's configuration, data, title, edit mode, filters, and time range.
+ *
+ * **When to use:**
+ * - Use `useWidgetConfig` inside any dashboard widget to read/write its persisted
+ *   configuration, respond to dashboard-level filter and time-range changes, and
+ *   manage the widget's edit-mode lifecycle.
+ * - Must be rendered inside a `WidgetConfigProvider` (provided automatically by the
+ *   dashboard host).
  *
  * @example
  * import { useWidgetConfig } from "@trackunit/react-core-hooks";
- *
- * export const useWidgetConfig = () => {
- *   const { ... } = useWidgetConfig();
- *
- *   ...
- * };
- * @see { WidgetConfigContext}
+ * const { data, setData, isEditMode, filters, timeRange } = useWidgetConfig();
+ * @see {WidgetConfigContext}
  */
 const useWidgetConfig = () => {
     const widgetConfigContext = useWidgetConfigAsync();

package/index.esm.js

@@ -89,7 +89,48 @@ const useAssetSorting = () => {
 };
 
 /**
- * This is a hook to use the ConfirmationDialogContext.
+ * Shows a modal confirmation dialog and returns the user's choice as a Promise.
+ *
+ * Resolves to `"PRIMARY"`, `"SECONDARY"`, or `"CLOSE"` depending on which button
+ * (or dismiss action) the user selects.
+ *
+ * **When to use:**
+ * - Use `useConfirmationDialog` for destructive or irreversible actions (delete, discard
+ *   changes, revoke access) where you need explicit user consent before proceeding.
+ * - Use `useToast` instead when you only need to *inform* the user — toasts are
+ *   non-blocking and don't require a decision.
+ * - Do **not** build custom confirmation modals — this hook connects to the host-provided
+ *   dialog so the UX is consistent across the platform.
+ *
+ * @example
+ * ```tsx
+ * import { Button } from "@trackunit/react-components";
+ * import { useConfirmationDialog } from "@trackunit/react-core-hooks";
+ *
+ * const DeleteButton = ({ onDelete }: { onDelete: () => void }) => {
+ *   const { confirm } = useConfirmationDialog();
+ *
+ *   return (
+ *     <Button
+ *       onClick={async () => {
+ *         const response = await confirm({
+ *           title: "Delete Item",
+ *           message: "Are you sure? This action cannot be undone.",
+ *           primaryActionLabel: "Delete",
+ *           secondaryActionLabel: "Cancel",
+ *           primaryActionType: "primary-danger",
+ *         });
+ *
+ *         if (response === "PRIMARY") {
+ *           onDelete();
+ *         }
+ *       }}
+ *     >
+ *       Delete
+ *     </Button>
+ *   );
+ * };
+ * ```
  */
 const useConfirmationDialog = () => {
     const confirmationDialogContext = useContext(ConfirmationDialogContext);
@@ -100,14 +141,19 @@ const useConfirmationDialog = () => {
 };
 
 /**
- * This is a hook to use the EnvironmentContext.
+ * Returns the host environment configuration (API keys, service URLs, build metadata).
+ *
+ * **When to use:**
+ * - Use `useEnvironment` to access platform-level configuration such as the Google Maps
+ *   API key, GraphQL endpoint URLs, auth issuer, or build version.
+ * - Use `useWidgetConfig` instead for per-widget configuration inside dashboards.
+ * - Do **not** hardcode service URLs or API keys — always read them from this hook.
  *
  * @requires EnvironmentContext
  * @example
  * import { useEnvironment } from "@trackunit/react-core-hooks";
  * const { googleMapsApiKey } = useEnvironment();
- * // use api key for something...
- * @see (@link EnvironmentState)
+ * @see EnvironmentState
  */
 const useEnvironment = () => {
     const context = useContext(EnvironmentContext);
@@ -323,9 +369,14 @@ const useGeolocation = (options) => {
 };
 
 /**
- * This is a hook to use the TokenContext.
+ * Returns the current authentication token from the TokenContext.
+ *
+ * **When to use:**
+ * - Use `useToken` when you need the raw JWT bearer token for authenticated API calls
+ *   outside the GraphQL layer (e.g. REST endpoints, file uploads, WebSockets).
+ * - Use `useCurrentUser` instead when you need the user's identity or account info.
+ * - Do **not** use for GraphQL requests — the Apollo client already attaches the token.
  *
- * @requires TokenProvider
  * @example
  * import { useToken } from "@trackunit/react-core-hooks";
  * const { token } = useToken();
@@ -503,6 +554,16 @@ const accessReducer = (_state, action) => {
  * Hook to check if the current user has access to a navigation target.
  * Useful for conditionally rendering links based on user permissions.
  *
+ * Supports single checks, `oneOf` (any match), and `requireAll` (every match) criteria.
+ *
+ * **When to use:**
+ * - Use `useHasAccessTo` to conditionally show/hide navigation links or action buttons
+ *   based on whether the user can reach the target page or entity.
+ * - Use `useUserPermission` instead when you need a synchronous check against a
+ *   permission string on the user object rather than a navigation-target check.
+ * - Use the `hasAccessTo` method from `useNavigateInHost` for a one-off imperative
+ *   check (e.g. inside an event handler) rather than a reactive/rendered result.
+ *
  * @requires NavigationContext
  * @example
  * import { useHasAccessTo } from "@trackunit/react-core-hooks";
@@ -551,12 +612,26 @@ const useHasAccessTo = (options) => {
 };
 
 /**
- * This is a hook to use the NavigationContext.
+ * Hook to navigate programmatically within the Trackunit Manager or between Iris Apps.
+ *
+ * ### When to use
+ * Use `useNavigateInHost` when you need to navigate between Manager pages, entity home
+ * pages, or Iris Apps from component logic (e.g. after a mutation, on row click, in a
+ * redirect guard). Use the `get*Url` methods when you need an href for an `<a>` tag.
+ * Use `hasAccessTo` before showing navigation options the user may not have access to.
+ *
+ * ### When not to use
+ * Do not use for in-page anchor scrolling or query-param changes within the same
+ * Iris App — use your router directly.
  *
  * @requires NavigationContext
  * @example
  * import { useNavigateInHost } from "@trackunit/react-core-hooks";
- * @see (@link NavigationRuntimeApi)
+ * const { gotoAssetHome, gotoFleetApp } = useNavigateInHost();
+ *
+ * gotoAssetHome("abc-123", { page: "status" });
+ * gotoFleetApp({ page: "assets" });
+ * @see {@link NavigationRuntimeApi}
  */
 const useNavigateInHost = () => {
     const context = useContext(NavigationContext);
@@ -861,20 +936,18 @@ const useTimeRange = () => {
 };
 
 /**
- * This is a hook to use the ToastContext.
+ * Hook to show toast notifications via the ToastContext.
  *
  * @requires ToastProvider
  * @example
  * import { useToast } from "@trackunit/react-core-hooks";
  * const { addToast } = useToast();
- * // use the toast
- * error &&
- *  addToast({
- *    intent: "warning",
- *    title: t("assetHome.specification.failedToSave"),
- *    description: error?.message,
- *    duration: 3000,
- *  });
+ *
+ * addToast({
+ *   intent: "success",
+ *   title: "Asset deleted",
+ *   id: "deletion-status",
+ * });
  * @see { ToastContextValue }
  */
 const useToast = () => {
@@ -886,14 +959,23 @@ const useToast = () => {
 };
 
 /**
- * This is a hook providing the CurrentUserContext.
+ * Hook providing the authenticated user's profile, account, and permission data
+ * from the CurrentUserContext.
+ *
+ * ### When to use
+ * Use `useCurrentUser` when you need the user's identity or account context — displaying
+ * the user's name, resolving the effective account ID, or branching logic based on
+ * `isAssuming` or `isTrackunitUser`.
+ *
+ * ### When not to use
+ * - If you only need a boolean check for a single permission — use `useUserPermission`.
+ * - To gate entire routes — prefer server-side access control or `hasAccessTo` from
+ *   `useNavigateInHost`.
  *
- * @requires CurrentUserProvider
  * @example
  * import { useCurrentUser } from "@trackunit/react-core-hooks";
  * const { assumedUser, accountId } = useCurrentUser();
  *
- * //use it for something
  * const { data, loading } = useGetAccountByIdQuery({
  *    variables: { accountId: assumedUser?.accountId || accountId || "" },
  * });
@@ -1039,8 +1121,31 @@ const setGlobalLanguage = (language) => {
 /**
  * Hook that checks if the current user has a given permission.
  *
+ * ### When to use
+ * Use `useUserPermission` to conditionally show or hide UI based on a single permission —
+ * delete buttons, admin panels, export actions, or any feature behind an access check.
+ *
+ * ### When not to use
+ * - When you need multiple user fields (name, account, assuming state) or need to check
+ *   several permissions at once — use `useCurrentUser`.
+ * - To gate navigation targets — use `hasAccessTo` from `useNavigateInHost`.
+ *
  * @param requiredPermission - The permission to check for typesafe string.
- * @returns {HasAccess} - true if the user has the permission, false if not and null if we could not determine.
+ * @returns {boolean} `true` if the user has the permission, `false` otherwise (including while permissions are still loading).
+ * @example
+ * ```tsx
+ * import { useUserPermission } from "@trackunit/react-core-hooks";
+ *
+ * const DeleteButton = ({ assetId }: { assetId: string }) => {
+ *   const canDelete = useUserPermission("asset:delete");
+ *
+ *   if (!canDelete) {
+ *     return null;
+ *   }
+ *
+ *   return <Button onClick={() => deleteAsset(assetId)}>Delete</Button>;
+ * };
+ * ```
  */
 const useUserPermission = (requiredPermission) => {
     const { permissions } = useCurrentUser();
@@ -1148,7 +1253,6 @@ const useSettingsUtils = () => {
 /**
  * This is a hook to use the WidgetConfigProvider.
  *
- * @requires WidgetConfigProvider
  * @example
  * import { useWidgetConfigAsync } from "@trackunit/react-core-hooks";
  *
@@ -1189,17 +1293,19 @@ const INITIAL_WIDGET_DATA_STATE = {
     title: null,
 };
 /**
- * This is a hook to use the WidgetConfigContext.
+ * Manages a dashboard widget's configuration, data, title, edit mode, filters, and time range.
+ *
+ * **When to use:**
+ * - Use `useWidgetConfig` inside any dashboard widget to read/write its persisted
+ *   configuration, respond to dashboard-level filter and time-range changes, and
+ *   manage the widget's edit-mode lifecycle.
+ * - Must be rendered inside a `WidgetConfigProvider` (provided automatically by the
+ *   dashboard host).
  *
  * @example
  * import { useWidgetConfig } from "@trackunit/react-core-hooks";
- *
- * export const useWidgetConfig = () => {
- *   const { ... } = useWidgetConfig();
- *
- *   ...
- * };
- * @see { WidgetConfigContext}
+ * const { data, setData, isEditMode, filters, timeRange } = useWidgetConfig();
+ * @see {WidgetConfigContext}
  */
 const useWidgetConfig = () => {
     const widgetConfigContext = useWidgetConfigAsync();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-core-hooks",
-  "version": "1.15.26",
+  "version": "1.15.28",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -8,9 +8,9 @@
   },
   "dependencies": {
     "es-toolkit": "^1.39.10",
-    "@trackunit/iris-app-runtime-core": "1.15.25",
-    "@trackunit/iris-app-runtime-core-api": "1.14.25",
-    "@trackunit/react-core-contexts-api": "1.15.25",
+    "@trackunit/iris-app-runtime-core": "1.15.27",
+    "@trackunit/iris-app-runtime-core-api": "1.14.27",
+    "@trackunit/react-core-contexts-api": "1.15.27",
     "zod": "^3.25.76"
   },
   "peerDependencies": {

package/src/confirmationDialog/useConfirmationDialog.d.ts

@@ -1,5 +1,46 @@
 import { ConfirmationDialogRuntimeApi } from "@trackunit/iris-app-runtime-core-api";
 /**
- * This is a hook to use the ConfirmationDialogContext.
+ * Shows a modal confirmation dialog and returns the user's choice as a Promise.
+ *
+ * Resolves to `"PRIMARY"`, `"SECONDARY"`, or `"CLOSE"` depending on which button
+ * (or dismiss action) the user selects.
+ *
+ * **When to use:**
+ * - Use `useConfirmationDialog` for destructive or irreversible actions (delete, discard
+ *   changes, revoke access) where you need explicit user consent before proceeding.
+ * - Use `useToast` instead when you only need to *inform* the user — toasts are
+ *   non-blocking and don't require a decision.
+ * - Do **not** build custom confirmation modals — this hook connects to the host-provided
+ *   dialog so the UX is consistent across the platform.
+ *
+ * @example
+ * ```tsx
+ * import { Button } from "@trackunit/react-components";
+ * import { useConfirmationDialog } from "@trackunit/react-core-hooks";
+ *
+ * const DeleteButton = ({ onDelete }: { onDelete: () => void }) => {
+ *   const { confirm } = useConfirmationDialog();
+ *
+ *   return (
+ *     <Button
+ *       onClick={async () => {
+ *         const response = await confirm({
+ *           title: "Delete Item",
+ *           message: "Are you sure? This action cannot be undone.",
+ *           primaryActionLabel: "Delete",
+ *           secondaryActionLabel: "Cancel",
+ *           primaryActionType: "primary-danger",
+ *         });
+ *
+ *         if (response === "PRIMARY") {
+ *           onDelete();
+ *         }
+ *       }}
+ *     >
+ *       Delete
+ *     </Button>
+ *   );
+ * };
+ * ```
  */
 export declare const useConfirmationDialog: () => ConfirmationDialogRuntimeApi;

package/src/environment/useEnvironment.d.ts

@@ -1,11 +1,16 @@
 /**
- * This is a hook to use the EnvironmentContext.
+ * Returns the host environment configuration (API keys, service URLs, build metadata).
+ *
+ * **When to use:**
+ * - Use `useEnvironment` to access platform-level configuration such as the Google Maps
+ *   API key, GraphQL endpoint URLs, auth issuer, or build version.
+ * - Use `useWidgetConfig` instead for per-widget configuration inside dashboards.
+ * - Do **not** hardcode service URLs or API keys — always read them from this hook.
  *
  * @requires EnvironmentContext
  * @example
  * import { useEnvironment } from "@trackunit/react-core-hooks";
  * const { googleMapsApiKey } = useEnvironment();
- * // use api key for something...
- * @see (@link EnvironmentState)
+ * @see EnvironmentState
  */
 export declare const useEnvironment: () => import("@trackunit/iris-app-runtime-core-api").EnvironmentState;

package/src/navigation/useHasAccessTo.d.ts

@@ -15,6 +15,16 @@ type UseHasAccessToResult = {
  * Hook to check if the current user has access to a navigation target.
  * Useful for conditionally rendering links based on user permissions.
  *
+ * Supports single checks, `oneOf` (any match), and `requireAll` (every match) criteria.
+ *
+ * **When to use:**
+ * - Use `useHasAccessTo` to conditionally show/hide navigation links or action buttons
+ *   based on whether the user can reach the target page or entity.
+ * - Use `useUserPermission` instead when you need a synchronous check against a
+ *   permission string on the user object rather than a navigation-target check.
+ * - Use the `hasAccessTo` method from `useNavigateInHost` for a one-off imperative
+ *   check (e.g. inside an event handler) rather than a reactive/rendered result.
+ *
  * @requires NavigationContext
  * @example
  * import { useHasAccessTo } from "@trackunit/react-core-hooks";

package/src/navigation/useNavigateInHost.d.ts

@@ -1,10 +1,24 @@
 import { NavigationRuntimeApi } from "@trackunit/iris-app-runtime-core-api";
 /**
- * This is a hook to use the NavigationContext.
+ * Hook to navigate programmatically within the Trackunit Manager or between Iris Apps.
+ *
+ * ### When to use
+ * Use `useNavigateInHost` when you need to navigate between Manager pages, entity home
+ * pages, or Iris Apps from component logic (e.g. after a mutation, on row click, in a
+ * redirect guard). Use the `get*Url` methods when you need an href for an `<a>` tag.
+ * Use `hasAccessTo` before showing navigation options the user may not have access to.
+ *
+ * ### When not to use
+ * Do not use for in-page anchor scrolling or query-param changes within the same
+ * Iris App — use your router directly.
  *
  * @requires NavigationContext
  * @example
  * import { useNavigateInHost } from "@trackunit/react-core-hooks";
- * @see (@link NavigationRuntimeApi)
+ * const { gotoAssetHome, gotoFleetApp } = useNavigateInHost();
+ *
+ * gotoAssetHome("abc-123", { page: "status" });
+ * gotoFleetApp({ page: "assets" });
+ * @see {@link NavigationRuntimeApi}
  */
 export declare const useNavigateInHost: () => NavigationRuntimeApi;

package/src/toast/useToast.d.ts

@@ -1,18 +1,16 @@
 /**
- * This is a hook to use the ToastContext.
+ * Hook to show toast notifications via the ToastContext.
  *
  * @requires ToastProvider
  * @example
  * import { useToast } from "@trackunit/react-core-hooks";
  * const { addToast } = useToast();
- * // use the toast
- * error &&
- *  addToast({
- *    intent: "warning",
- *    title: t("assetHome.specification.failedToSave"),
- *    description: error?.message,
- *    duration: 3000,
- *  });
+ *
+ * addToast({
+ *   intent: "success",
+ *   title: "Asset deleted",
+ *   id: "deletion-status",
+ * });
  * @see { ToastContextValue }
  */
 export declare const useToast: () => import("@trackunit/react-core-contexts-api").ToastContextValue;

package/src/token/useToken.d.ts

@@ -1,7 +1,12 @@
 /**
- * This is a hook to use the TokenContext.
+ * Returns the current authentication token from the TokenContext.
+ *
+ * **When to use:**
+ * - Use `useToken` when you need the raw JWT bearer token for authenticated API calls
+ *   outside the GraphQL layer (e.g. REST endpoints, file uploads, WebSockets).
+ * - Use `useCurrentUser` instead when you need the user's identity or account info.
+ * - Do **not** use for GraphQL requests — the Apollo client already attaches the token.
  *
- * @requires TokenProvider
  * @example
  * import { useToken } from "@trackunit/react-core-hooks";
  * const { token } = useToken();

package/src/user/useCurrentUser.d.ts

@@ -1,13 +1,22 @@
 import { CurrentUserState } from "@trackunit/iris-app-runtime-core-api";
 /**
- * This is a hook providing the CurrentUserContext.
+ * Hook providing the authenticated user's profile, account, and permission data
+ * from the CurrentUserContext.
+ *
+ * ### When to use
+ * Use `useCurrentUser` when you need the user's identity or account context — displaying
+ * the user's name, resolving the effective account ID, or branching logic based on
+ * `isAssuming` or `isTrackunitUser`.
+ *
+ * ### When not to use
+ * - If you only need a boolean check for a single permission — use `useUserPermission`.
+ * - To gate entire routes — prefer server-side access control or `hasAccessTo` from
+ *   `useNavigateInHost`.
  *
- * @requires CurrentUserProvider
  * @example
  * import { useCurrentUser } from "@trackunit/react-core-hooks";
  * const { assumedUser, accountId } = useCurrentUser();
  *
- * //use it for something
  * const { data, loading } = useGetAccountByIdQuery({
  *    variables: { accountId: assumedUser?.accountId || accountId || "" },
  * });

package/src/user/useUserPermission.d.ts

@@ -2,7 +2,30 @@ export type HasAccess = boolean | null;
 /**
  * Hook that checks if the current user has a given permission.
  *
+ * ### When to use
+ * Use `useUserPermission` to conditionally show or hide UI based on a single permission —
+ * delete buttons, admin panels, export actions, or any feature behind an access check.
+ *
+ * ### When not to use
+ * - When you need multiple user fields (name, account, assuming state) or need to check
+ *   several permissions at once — use `useCurrentUser`.
+ * - To gate navigation targets — use `hasAccessTo` from `useNavigateInHost`.
+ *
  * @param requiredPermission - The permission to check for typesafe string.
- * @returns {HasAccess} - true if the user has the permission, false if not and null if we could not determine.
+ * @returns {boolean} `true` if the user has the permission, `false` otherwise (including while permissions are still loading).
+ * @example
+ * ```tsx
+ * import { useUserPermission } from "@trackunit/react-core-hooks";
+ *
+ * const DeleteButton = ({ assetId }: { assetId: string }) => {
+ *   const canDelete = useUserPermission("asset:delete");
+ *
+ *   if (!canDelete) {
+ *     return null;
+ *   }
+ *
+ *   return <Button onClick={() => deleteAsset(assetId)}>Delete</Button>;
+ * };
+ * ```
  */
 export declare const useUserPermission: <TPermission extends string>(requiredPermission: TPermission) => HasAccess;

package/src/widgetConfig/useWidgetConfig.d.ts

@@ -2,7 +2,6 @@ import { LoadingState } from "@trackunit/iris-app-runtime-core-api";
 /**
  * This is a hook to use the WidgetConfigProvider.
  *
- * @requires WidgetConfigProvider
  * @example
  * import { useWidgetConfigAsync } from "@trackunit/react-core-hooks";
  *
@@ -15,17 +14,19 @@ import { LoadingState } from "@trackunit/iris-app-runtime-core-api";
  */
 export declare const useWidgetConfigAsync: () => import("@trackunit/iris-app-runtime-core-api").WidgetConfigContext;
 /**
- * This is a hook to use the WidgetConfigContext.
+ * Manages a dashboard widget's configuration, data, title, edit mode, filters, and time range.
+ *
+ * **When to use:**
+ * - Use `useWidgetConfig` inside any dashboard widget to read/write its persisted
+ *   configuration, respond to dashboard-level filter and time-range changes, and
+ *   manage the widget's edit-mode lifecycle.
+ * - Must be rendered inside a `WidgetConfigProvider` (provided automatically by the
+ *   dashboard host).
  *
  * @example
  * import { useWidgetConfig } from "@trackunit/react-core-hooks";
- *
- * export const useWidgetConfig = () => {
- *   const { ... } = useWidgetConfig();
- *
- *   ...
- * };
- * @see { WidgetConfigContext}
+ * const { data, setData, isEditMode, filters, timeRange } = useWidgetConfig();
+ * @see {WidgetConfigContext}
  */
 export declare const useWidgetConfig: () => {
     data: Record<string, unknown> | null;