# Hook examples and conventions Shared hooks are exported through `@/hooks`. Internal callers should import by responsibility: `template` depends on the template runtime, `components` complements component contracts, and `web` handles windows, dates, screenshots, printing, and related capabilities. Legacy `web/useI18n`, `web/useVueRouter`, and `web/usePagination` entry points still re-export their implementations. Pages use Vue 3 Composition API + TSX. Each demo includes real interaction, reactive results, and expandable, copyable usage code. | Group | Hook | Example page and actions | Regression | | ---------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | template | `useTheme` | `/template-hooks`: light/dark, toggle, follow system | [useTheme](../../../../__test__/hooks/useTheme.spec.ts) | | template | `useSpinning` | `/template-hooks`: loading indicators and page remount | [useSpinning](../../../../__test__/hooks/useSpinning.spec.ts) | | template | `useMaximize` | `/template-hooks`: maximize content, shared exit button, Esc | [useMaximize](../../../../__test__/hooks/useMaximize.spec.ts) | | template | `useBadge` | `/template-hooks`: menu badge text, icons, and visibility | [useBadge](../../../../__test__/hooks/useBadge.spec.ts) | | template | `useWatermark` | `/template-hooks`: text, show, hide, and toggle | [useWatermark](../../../../__test__/hooks/useWatermark.spec.ts) | | template | `useAppNavigation` | `/template-hooks`: full paths, indexes, nested menus, and query | [useAppNavigation](../../../../__test__/hooks/useAppNavigation.spec.ts) | | template | `useSiderBar` | `/template-hooks`: close tabs by path or close left/right/other/all tabs | [useSiderBar](../../../../__test__/hooks/useSiderBar.spec.ts) | | template | `useContentScroll` | `/template-hooks`: scroll content to top or coordinates | [useLayoutScroll](../../../../__test__/hooks/useLayoutScroll.spec.ts) | | template | `useSiderScroll` | `/template-hooks`: scroll sidebar to top or coordinates | [useLayoutScroll](../../../../__test__/hooks/useLayoutScroll.spec.ts) | | web | `useDevice` | `/web-hooks`: update breakpoint checks with window size | [useDevice](../../../../__test__/hooks/useDevice.spec.ts) | | components | `usePagination` | `/web-hooks`: paginated data, page, page size, and reset | [usePagination](../../../../__test__/hooks/usePagination.spec.ts) | | web | `useDayjs` | `/web-hooks`: date formatting, day differences, open intervals, and day boundaries | [useDayjs](../../../../__test__/hooks/useDayjs.spec.ts) | | template | `useI18n` | `/web-hooks`: namespaces, full keys, and locale switching | [useI18n](../../../../__test__/hooks/useI18n.spec.ts) | | template | `useVueRouter` | `/web-hooks`: current route, query parameters, and navigation | [useVueRouter](../../../../__test__/hooks/useVueRouter.spec.ts) | | web | `useElementFullscreen` | `/web-hooks`: CSS fullscreen and restoration for a chosen element | [useElementFullscreen](../../../../__test__/hooks/useElementFullscreen.spec.ts) | | web | `useDomToImage` | `/web-hooks`: PNG generation, preview, and failure messages | [useDomToImage](../../../../__test__/hooks/useDomToImage.spec.ts) | | web | `usePrint` | `/web-hooks`: element print preview | [usePrint](../../../../__test__/hooks/usePrint.spec.ts) | | components | `useContextmenuCoordinate` | `/web-hooks`: context-menu coordinates, selection, outside close, and listener removal; legacy `/context-menu` remains | [useContextmenuCoordinate](../../../../__test__/hooks/useContextmenuCoordinate.spec.tsx) | ## Lifecycle and state - `useAppRoot` is a deprecated compatibility accessor for stored preferences. It has no landing, tab protection, permission, or startup-validation effect and is no longer an interactive demo. Explicit navigation uses Router; closing the final/all business tabs opens the neutral `/welcome` workspace. - Create composables in `setup` or an active effect scope. Trigger DOM operations from user events or post-mount callbacks. Clean up events, subscriptions, and animation frames with the scope. - Pinia `runtime` owns global UI state, accessed through `useRuntimeGetters` / `useRuntimeActions`. It is not persisted. - `useSpinning().reload(wait)` unmounts the page. The runtime store owns the restoration timer; the latest refresh wins across repeated calls. - In the default layout, loading indicators stay centered in the visible content area, including long pages and maximized content. `reload` shows immediately; `openSpin` shows after lasting more than 120ms; `closeSpin` immediately closes manual loading indicators. - Both scroll hooks can be created during setup and read the layout instance only when invoked. Missing sidebars or unmounted instances are safely ignored. - `useMaximize` acts on layout content and shares state across callers. `useElementFullscreen` acts on one arbitrary element and owns per-instance state. Neither calls the browser Fullscreen API. - `navigationTo` indexes start at 0. Negative, fractional, non-finite, or out-of-range indexes do not navigate. Full URLs support dynamic parameters, query, and hash; additional query parameters override matching URL parameters. Successful calls return the Router navigation Promise. - `useDomToImage` return types follow the default format or the current `create(format)` call. Failures reject with Error. `finally` also runs when the target is missing, so its argument may be empty. The `created` callback receives results from runtime format overrides as well; its argument is a union of actual output types and must be narrowed first. - `useI18n('hooks').t('code')` and `.t('hooks.code')` address the same translation key. Switch application locales with `useSettingActions().updateLocale` to keep dates and component-library locales synchronized. - Development HMR reuses the internationalization instance. Translation methods created before initialization read the current instance at invocation rather than permanently retaining the fallback that returns raw keys. - `usePagination` resets to the first option in the current `pagination.value.pageSizes` and supports Naive UI object options. Default option arrays are isolated between instances. Calling `setCallback()` removes the default callback. - `useDomToImage` loads the rendering library on the first `create` call; import failures use the same error and cleanup callbacks as renderer failures. - A disposed `useElementFullscreen` instance cannot enter again; create a fresh instance in a live scope when a target is remounted. - `usePrint` unwraps its target when called. DOM targets print as HTML by default. Blob images and binary PDFs are converted first; callers can await the returned Promise. Screenshots and printing depend on real browsers. Happy DOM tests verify state and error handling; they do not replace native print-dialog or physical-output acceptance.