docs: polish README, add CONTRIBUTING and CoC, TypeDoc config, generate API docs, docs workflow; move tests/

Author: gawry

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - 'typedoc.json'
+      - 'package.json'
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - run: pnpm install --frozen-lockfile=false
+      - run: pnpm docs:build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/api
+  deploy:
+    needs: build-docs
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+
+

CODE_OF_CONDUCT.md

@@ -0,0 +1,11 @@
+# Code of Conduct
+
+We are committed to a welcoming and inclusive community. Be respectful.
+
+- Be kind and patient.
+- Be considerate.
+- Be respectful of differing viewpoints and experiences.
+- Gracefully accept constructive criticism.
+- Focus on what is best for the community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainers.

CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Thanks for your interest in contributing!
+
+## Development setup
+
+```bash
+pnpm install
+pnpm test
+pnpm dev # build in watch via tsup
+```
+
+- Tests: Vitest + jsdom in `tests/`
+- Lint/format: `pnpm lint` / `pnpm format`
+- Type-check: `pnpm typecheck`
+
+## Commit and release
+
+- Conventional commits are appreciated (e.g., `feat:`, `fix:`)
+- Use Changesets for versioning:
+  - `pnpm changeset` to add a changeset
+  - `pnpm version-packages` to bump versions
+  - `pnpm publish-packages` to publish
+
+## Pull requests
+
+- Include tests for changes
+- Update docs/README when API changes
+- Keep diffs focused and small when possible
+
+## Code style
+
+- TypeScript strict, avoid `any`
+- Prefer explicit names and early returns
+
+## Getting help
+
+Open an issue if you’re unsure about an approach before investing time.

README.md

@@ -1,6 +1,18 @@
 # use-query-state
 
-A tiny React hook for typed URL query string state.
+Tiny, typed React URL query state. Co-locate state with your components and keep it in sync with the URL for shareable, deep‑linkable UIs.
+
+[![npm version](https://img.shields.io/npm/v/use-query-state.svg)](https://www.npmjs.com/package/use-query-state)
+[![CI](https://github.com/gawryco/use-query-state/actions/workflows/ci.yml/badge.svg)](https://github.com/gawryco/use-query-state/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## Features
+
+- Typed builders: number, string, boolean, date, enum, json, custom
+- One-liner setup per key; React‑style setters with URL sync
+- Back/forward navigation support via `popstate`
+- Tiny API, framework‑agnostic URL handling, SSR‑safe guards
+- ESM+CJS builds with type declarations
 
 ## Install
 
@@ -12,32 +24,87 @@ npm i use-query-state
 yarn add use-query-state
 ```
 
-## Usage
+Peer dependency: `react >= 17`.
+
+## Quick start
 
 ```tsx
 import { useQueryState } from 'use-query-state';
 
-export function Example() {
-  const [page, setPage] = useQueryState<number>('page', {
-    parse: (v) => (v ? Number(v) : undefined),
-    serialize: (v) => (v == null ? null : String(v)),
-    defaultValue: 1,
-    history: 'push',
-  });
-
-  return (
-    <button onClick={() => setPage((p) => (p ?? 1) + 1)}>Page: {page}</button>
-  );
+export function Counter() {
+  const [n, setN] = useQueryState('n').number(0);
+  return <button onClick={() => setN((v) => v + 1)}>Count: {n}</button>;
 }
 ```
 
-## API
+- Initializes from `?n=...` if present; otherwise seeds the URL with the default.
+- Calling the setter updates both state and the URL.
+
+## API overview
+
+`useQueryState(key)` returns a set of builder methods. Each returns `[value, setValue]`.
+
+- `number(defaultValue, opts?)`
+  - `opts`: `{ min?: number; max?: number; step?: number }`
+- `string(defaultValue, opts?)`
+  - `opts`: `{ minLength?: number; maxLength?: number }`
+- `boolean(defaultValue)`
+  - Stored as `'1' | '0'` and accepts common truthy/falsy strings
+- `date(defaultValue, opts?)`
+  - Format `yyyy-MM-dd` (UTC); `{ min?: Date; max?: Date }`
+- `enum(allowed, defaultValue)`
+  - `allowed: readonly string[]`
+- `json(defaultValue, opts?)`
+  - `opts`: `{ validate?, omitEmpty?, stringify?, parse? }`
+- `custom(defaultValue, parse, format)`
+  - Bring your own parsing/formatting logic
+
+See full JSDoc/API in `docs/`.
+
+## Examples
+
+```tsx
+// String
+const [q, setQ] = useQueryState('q').string('');
+
+// Boolean
+const [open, setOpen] = useQueryState('open').boolean(false);
+
+// Date (UTC yyyy-MM-dd)
+const [start, setStart] = useQueryState('start').date(new Date('2024-01-01'));
+
+// Enum
+type Theme = 'light' | 'dark';
+const [t, setT] = useQueryState('t').enum<Theme>(['light', 'dark'], 'light');
+
+// JSON with omitEmpty
+const [filters, setFilters] = useQueryState('f').json({ q: '' }, {
+  omitEmpty: (v) => v.q === '',
+});
+```
+
+## SSR and environments
+
+The hook guards access to `window`/`document`. During SSR it returns the default value and no URL edits occur until hydration.
+
+## Navigation and events
+
+- Listens for `popstate` and re-parses the URL to update state.
+- Dispatches a `CustomEvent` named `qs:changed` on `window` with `{ key, prev, next, params, source, ts }` for diagnostics.
+
+## Type safety
+
+The builders are typed. For advanced types use `custom` or `json` with a type guard.
+
+## Docs
+
+- API docs: `docs/api/` (generated from JSDoc)
+- Overview: `docs/README.md`
+
+## Contributing
 
-- `useQueryState(key, options)` returns `[value, setValue]`.
-- `options.parse` and `options.serialize` let you adapt non-string types.
-- `options.history`: `'replace' | 'push'` (default `'replace'`).
-- `options.defaultValue`: used when param is absent.
+See [CONTRIBUTING.md](CONTRIBUTING.md). Please note our [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## License
 
-MIT
+MIT — Copyright (c) 2025 Gawry & Co

docs/README.md

@@ -0,0 +1,11 @@
+# use-query-state Docs
+
+This folder contains the documentation for use-query-state.
+
+- Overview: see the project README for a high-level introduction.
+- API: generated from JSDoc into `docs/api/`.
+
+## Local development
+
+- Update code comments (JSDoc) in `src/`.
+- Regenerate docs with the scripts in `package.json`.

docs/api/README.md

@@ -0,0 +1,9 @@
+**use-query-state**
+
+***
+
+# use-query-state
+
+## Functions
+
+- [useQueryState](functions/useQueryState.md)