@fictjs/hooks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fict
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# @fictjs/hooks
+
+[![Node CI](https://github.com/fictjs/hooks/actions/workflows/nodejs.yml/badge.svg)](https://github.com/fictjs/hooks/actions/workflows/nodejs.yml)
+[![npm](https://img.shields.io/npm/v/@fictjs/hooks.svg)](https://www.npmjs.com/package/@fictjs/hooks)
+![license](https://img.shields.io/npm/l/@fictjs/hooks)
+
+Official hooks package for Fict.
+
+`@fictjs/hooks` provides official, production-ready hooks built for Fict signal/lifecycle semantics.
+
+## Install
+
+For application usage:
+
+```bash
+pnpm add @fictjs/hooks @fictjs/runtime
+```
+
+For repository development:
+
+```bash
+pnpm install
+```
+
+## Requirements
+
+- Node.js >= 18
+- Peer dependency: `@fictjs/runtime@^0.8.0`
+
+## Quick Start
+
+```ts
+import { useCounter, useMount } from '@fictjs/hooks';
+
+export function CounterExample() {
+  const { count, inc, dec, reset } = useCounter(0);
+
+  useMount(() => {
+    inc();
+  });
+
+  return { count, inc, dec, reset };
+}
+```
+
+In plain TypeScript/JavaScript usage (without Fict compile transforms), read reactive values via accessors, for example `count()`.
+
+## Import Policy
+
+- Only import from `@fictjs/hooks`; deep imports are unsupported
+- Tree shaking is supported through ESM exports and `"sideEffects": false`
+
+## Runtime Semantics
+
+- Hooks follow Fict top-level hook rules (`useX` in component/hook top-level scope)
+- Effects/listeners/timers are auto-cleaned on root dispose
+- Browser hooks are SSR-safe and provide unsupported fallbacks
+- Browser globals can be injected with options like `window`, `document`, or `navigator` when needed
+
+## Hook Docs
+
+- Lifecycle
+  - `useMount` -> `docs/hooks/useMount.md`
+  - `useUnmount` -> `docs/hooks/useUnmount.md`
+- Event
+  - `useEventListener` -> `docs/hooks/useEventListener.md`
+  - `useClickOutside` -> `docs/hooks/useClickOutside.md`
+  - `useHover` -> `docs/hooks/useHover.md`
+  - `useFocusWithin` -> `docs/hooks/useFocusWithin.md`
+  - `useKeyPress` -> `docs/hooks/useKeyPress.md`
+- Timing
+  - `useDebounceFn` -> `docs/hooks/useDebounceFn.md`
+  - `useThrottleFn` -> `docs/hooks/useThrottleFn.md`
+  - `useTimeoutFn` -> `docs/hooks/useTimeoutFn.md`
+  - `useIntervalFn` -> `docs/hooks/useIntervalFn.md`
+  - `useRafFn` -> `docs/hooks/useRafFn.md`
+- State
+  - `useToggle` -> `docs/hooks/useToggle.md`
+  - `useCounter` -> `docs/hooks/useCounter.md`
+  - `usePrevious` -> `docs/hooks/usePrevious.md`
+  - `useVirtualList` -> `docs/hooks/useVirtualList.md`
+- Browser
+  - `useScroll` -> `docs/hooks/useScroll.md`
+  - `useWindowScroll` -> `docs/hooks/useWindowScroll.md`
+  - `useWindowSize` -> `docs/hooks/useWindowSize.md`
+  - `useTitle` -> `docs/hooks/useTitle.md`
+  - `useFullscreen` -> `docs/hooks/useFullscreen.md`
+  - `usePermission` -> `docs/hooks/usePermission.md`
+  - `useGeolocation` -> `docs/hooks/useGeolocation.md`
+  - `useIdle` -> `docs/hooks/useIdle.md`
+  - `useSize` -> `docs/hooks/useSize.md`
+  - `useWebSocket` -> `docs/hooks/useWebSocket.md`
+  - `useMediaQuery` -> `docs/hooks/useMediaQuery.md`
+  - `useDocumentVisibility` -> `docs/hooks/useDocumentVisibility.md`
+  - `useNetwork` -> `docs/hooks/useNetwork.md`
+- Storage
+  - `useStorage` -> `docs/hooks/useStorage.md`
+  - `useLocalStorage` -> `docs/hooks/useLocalStorage.md`
+  - `useSessionStorage` -> `docs/hooks/useSessionStorage.md`
+- Observer
+  - `useIntersectionObserver` -> `docs/hooks/useIntersectionObserver.md`
+  - `useResizeObserver` -> `docs/hooks/useResizeObserver.md`
+  - `useMutationObserver` -> `docs/hooks/useMutationObserver.md`
+- Async
+  - `useAsyncState` -> `docs/hooks/useAsyncState.md`
+  - `useFetch` -> `docs/hooks/useFetch.md`
+  - `useRequest` -> `docs/hooks/useRequest.md`
+- Clipboard
+  - `useClipboard` -> `docs/hooks/useClipboard.md`
+
+## Demo Website
+
+Run interactive hook demos:
+
+```bash
+pnpm demo:dev
+```
+
+Build static demo site:
+
+```bash
+pnpm demo:build
+```
+
+## Quality Gates
+
+Before publish, these checks must pass:
+
+1. `pnpm lint`
+2. `pnpm typecheck`
+3. `pnpm test:types`
+4. `pnpm test`
+5. `pnpm build`
+
+`prepublishOnly` already enforces this pipeline.
+
+## Scripts
+
+- `pnpm dev`: watch mode build with tsup
+- `pnpm build`: build ESM + CJS + d.ts to `dist`
+- `pnpm demo:dev`: run Vite demo website (`playground/`)
+- `pnpm demo:build`: build Vite demo website
+- `pnpm demo:preview`: preview built demo website
+- `pnpm typecheck`: TypeScript type checking
+- `pnpm test:types`: API type assertion tests
+- `pnpm lint`: ESLint check
+- `pnpm test`: run unit tests with Vitest
+- `pnpm test:coverage`: run tests with coverage threshold checks
+- `pnpm format`: format files with Prettier
+
+## Package Entry
+
+Package entry is `src/index.ts`.