Merge pull request #9 from ismailza/docs/add-docs-website

docs: add the documentation website

Author: ismailza

.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "website/**"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "website/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# Allow one concurrent deployment, and let a new push cancel a running build.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: website
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - run: npm ci
+
+      - name: Type check
+        run: npm run typecheck
+
+      # Fails on broken internal links.
+      - name: Build
+        run: npm run build
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: website/build
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

README.md

@@ -1,11 +1,30 @@
-# ngx-api-client
-
-[![npm](https://img.shields.io/npm/v/@ismailza/ngx-api-client.svg)](https://www.npmjs.com/package/@ismailza/ngx-api-client)
-[![CI](https://github.com/ismailza/ngx-api-client/actions/workflows/ci.yml/badge.svg)](https://github.com/ismailza/ngx-api-client/actions/workflows/ci.yml)
-[![Release](https://github.com/ismailza/ngx-api-client/actions/workflows/release.yml/badge.svg)](https://github.com/ismailza/ngx-api-client/actions/workflows/release.yml)
-[![license](https://img.shields.io/npm/l/@ismailza/ngx-api-client.svg)](./LICENSE)
-
-A typed, interceptor-driven HTTP layer for Angular.
+<p align="center">
+  <a href="https://ismailza.github.io/ngx-api-client/">
+    <img src="https://ismailza.github.io/ngx-api-client/img/logo.svg" alt="" width="88" height="88">
+  </a>
+</p>
+
+<h1 align="center">ngx-api-client</h1>
+
+<p align="center">
+  A typed, interceptor-driven HTTP layer for Angular.
+</p>
+
+<p align="center">
+  <a href="https://ismailza.github.io/ngx-api-client/"><strong>Documentation</strong></a> ·
+  <a href="https://www.npmjs.com/package/@ismailza/ngx-api-client"><strong>npm</strong></a> ·
+  <a href="https://ismailza.github.io/ngx-api-client/docs/getting-started/quick-start"><strong>Quick start</strong></a> ·
+  <a href="https://ismailza.github.io/ngx-api-client/docs/api/provide-api"><strong>API reference</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@ismailza/ngx-api-client"><img src="https://img.shields.io/npm/v/@ismailza/ngx-api-client.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@ismailza/ngx-api-client"><img src="https://img.shields.io/npm/dm/@ismailza/ngx-api-client.svg" alt="npm downloads"></a>
+  <a href="https://ismailza.github.io/ngx-api-client/"><img src="https://img.shields.io/badge/docs-online-brightgreen.svg" alt="Documentation"></a>
+  <a href="https://github.com/ismailza/ngx-api-client/actions/workflows/ci.yml"><img src="https://github.com/ismailza/ngx-api-client/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/ismailza/ngx-api-client/actions/workflows/release.yml"><img src="https://github.com/ismailza/ngx-api-client/actions/workflows/release.yml/badge.svg" alt="Release"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@ismailza/ngx-api-client.svg" alt="License"></a>
+</p>
 
 `HttpClient` gives you a request. It doesn't give you a _policy_ — where the base
 URL comes from, how a failed response becomes something your components can
@@ -48,17 +67,23 @@ export const appConfig: ApplicationConfig = {
       retry: { maxRetries: 3, initialDelay: 1000 },
     }),
     provideHttpClient(
-      withInterceptors([retryInterceptor, apiErrorInterceptor, apiSuccessInterceptor]),
+      withInterceptors([apiErrorInterceptor, apiSuccessInterceptor, retryInterceptor]),
     ),
   ],
 };
 ```
 
 Interceptors are registered by you, not by `provideApi()`, because **order
-matters** and only you know what else is in the chain. Put an auth/bearer-token
-interceptor first so retried requests get a fresh token; keep `retryInterceptor`
-before `apiErrorInterceptor` so the error handler only sees failures that
-survived every retry.
+matters** and only you know what else is in the chain. The first interceptor in
+the array is the outermost one:
+
+- Keep `apiErrorInterceptor` **before** `retryInterceptor`. It replaces the
+  `HttpErrorResponse` with a plain `ApiError`, and `retryInterceptor` only
+  retries `HttpErrorResponse`s — nest them the other way round and retry
+  silently never fires. Outermost, it also reports one failure per operation
+  rather than one per attempt.
+- Put an auth/bearer-token interceptor **last**, inside `retryInterceptor`, so
+  each retried attempt is signed with a fresh token.
 
 ## Usage
 

eslint.config.mjs

@@ -5,7 +5,7 @@ import tseslint from 'typescript-eslint';
 
 export default tseslint.config(
   {
-    ignores: ['dist/**', 'coverage/**', '.angular/**', 'node_modules/**'],
+    ignores: ['dist/**', 'coverage/**', '.angular/**', 'node_modules/**', 'website/**'],
   },
   {
     files: ['**/*.ts'],

package.json

@@ -8,7 +8,11 @@
     "watch": "ng build --watch --configuration development",
     "test": "ng test",
     "lint": "eslint .",
-    "lint:fix": "eslint . --fix"
+    "lint:fix": "eslint . --fix",
+    "docs:install": "npm --prefix website ci",
+    "docs:start": "npm --prefix website start",
+    "docs:build": "npm --prefix website run build",
+    "docs:serve": "npm --prefix website run serve"
   },
   "private": true,
   "packageManager": "npm@11.9.0",

projects/ngx-api-client/README.md

@@ -1,6 +1,30 @@
-# ngx-api-client
-
-A typed, interceptor-driven HTTP layer for Angular.
+<p align="center">
+  <a href="https://ismailza.github.io/ngx-api-client/">
+    <img src="https://ismailza.github.io/ngx-api-client/img/logo.svg" alt="" width="88" height="88">
+  </a>
+</p>
+
+<h1 align="center">ngx-api-client</h1>
+
+<p align="center">
+  A typed, interceptor-driven HTTP layer for Angular.
+</p>
+
+<p align="center">
+  <a href="https://ismailza.github.io/ngx-api-client/"><strong>Documentation</strong></a> ·
+  <a href="https://www.npmjs.com/package/@ismailza/ngx-api-client"><strong>npm</strong></a> ·
+  <a href="https://ismailza.github.io/ngx-api-client/docs/getting-started/quick-start"><strong>Quick start</strong></a> ·
+  <a href="https://ismailza.github.io/ngx-api-client/docs/api/provide-api"><strong>API reference</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@ismailza/ngx-api-client"><img src="https://img.shields.io/npm/v/@ismailza/ngx-api-client.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@ismailza/ngx-api-client"><img src="https://img.shields.io/npm/dm/@ismailza/ngx-api-client.svg" alt="npm downloads"></a>
+  <a href="https://ismailza.github.io/ngx-api-client/"><img src="https://img.shields.io/badge/docs-online-brightgreen.svg" alt="Documentation"></a>
+  <a href="https://github.com/ismailza/ngx-api-client/actions/workflows/ci.yml"><img src="https://github.com/ismailza/ngx-api-client/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/ismailza/ngx-api-client/actions/workflows/release.yml"><img src="https://github.com/ismailza/ngx-api-client/actions/workflows/release.yml/badge.svg" alt="Release"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@ismailza/ngx-api-client.svg" alt="License"></a>
+</p>
 
 `HttpClient` gives you a request. It doesn't give you a _policy_ — where the base
 URL comes from, how a failed response becomes something your components can
@@ -43,17 +67,23 @@ export const appConfig: ApplicationConfig = {
       retry: { maxRetries: 3, initialDelay: 1000 },
     }),
     provideHttpClient(
-      withInterceptors([retryInterceptor, apiErrorInterceptor, apiSuccessInterceptor]),
+      withInterceptors([apiErrorInterceptor, apiSuccessInterceptor, retryInterceptor]),
     ),
   ],
 };
 ```
 
 Interceptors are registered by you, not by `provideApi()`, because **order
-matters** and only you know what else is in the chain. Put an auth/bearer-token
-interceptor first so retried requests get a fresh token; keep `retryInterceptor`
-before `apiErrorInterceptor` so the error handler only sees failures that
-survived every retry.
+matters** and only you know what else is in the chain. The first interceptor in
+the array is the outermost one:
+
+- Keep `apiErrorInterceptor` **before** `retryInterceptor`. It replaces the
+  `HttpErrorResponse` with a plain `ApiError`, and `retryInterceptor` only
+  retries `HttpErrorResponse`s — nest them the other way round and retry
+  silently never fires. Outermost, it also reports one failure per operation
+  rather than one per attempt.
+- Put an auth/bearer-token interceptor **last**, inside `retryInterceptor`, so
+  each retried attempt is signed with a fresh token.
 
 ## Usage
 
@@ -257,14 +287,16 @@ matrix currently covers.
 
 ## Contributing
 
-```bash
-npm install
-npm test     # 131 specs, vitest
-npm run build
-```
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) before opening an issue or pull request.
 
-Issues and pull requests are welcome.
+## Code of Conduct
+
+Please read our [Code of Conduct](CODE_OF_CONDUCT.md) to help us maintain a welcoming and inclusive community.
 
 ## License
 
-[MIT](../../LICENSE) © Ismail ZAHIR
+[MIT](./LICENSE) © Ismail ZAHIR
+
+## Support the Project
+
+If you find this library useful, consider giving it a ⭐ on GitHub. It helps others discover the project and motivates future development.

website/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

website/README.md

@@ -0,0 +1,67 @@
+# Documentation website
+
+The documentation site for [`@ismailza/ngx-api-client`](https://www.npmjs.com/package/@ismailza/ngx-api-client),
+built with [Docusaurus](https://docusaurus.io/).
+
+Published at **https://ismailza.github.io/ngx-api-client/**.
+
+## Local development
+
+From the repository root:
+
+```bash
+npm run docs:start
+```
+
+…or from this directory:
+
+```bash
+npm install
+npm run start
+```
+
+Most changes are reflected live without restarting the server.
+
+## Build
+
+```bash
+npm run build      # static output in ./build
+npm run serve      # serve the production build locally
+npm run typecheck  # type-check the site source
+```
+
+`npm run build` fails on broken internal links, so it is the check to run before
+opening a documentation pull request.
+
+## Structure
+
+```
+docs/
+  intro.md                 What the library is and what it deliberately isn't
+  getting-started/         Installation and quick start
+  guides/                  One page per concern (configuration, versioning, retry, …)
+  api/                     Reference for the public API surface
+src/
+  pages/index.tsx          Landing page
+  components/              Landing page sections
+  css/custom.css           Theme tokens
+sidebars.ts                Explicit sidebar — new pages must be added here
+docusaurus.config.ts       Site config, navbar, footer, deployment URL
+```
+
+The sidebar is defined explicitly rather than autogenerated, so **a new page is
+invisible until it is listed in `sidebars.ts`**.
+
+## Writing conventions
+
+- Document what the code does, not what it might do — check the source in
+  `projects/ngx-api-client/src/lib` before stating a default.
+- Every option table gives the type, the default, and whether it can be
+  overridden per request.
+- Code samples are complete enough to paste into an application.
+
+## Deployment
+
+`.github/workflows/docs.yml` builds the site on every pull request that touches
+`website/`, and deploys to GitHub Pages on push to `main`. No manual `npm run
+deploy` is needed.

website/docs/api/api-loading-service.mdx

@@ -0,0 +1,58 @@
+---
+id: api-loading-service
+title: ApiLoadingService
+description: API reference for ApiLoadingService, the signal-based in-flight request counter.
+---
+
+# `ApiLoadingService`
+
+```ts
+@Injectable({ providedIn: 'root' })
+class ApiLoadingService {
+  readonly loading: Signal<boolean>;
+}
+```
+
+Tracks the number of in-flight API requests and exposes a reactive signal.
+
+## `loading`
+
+```ts
+readonly loading: Signal<boolean>;
+```
+
+`true` while at least one tracked request is outstanding. It counts rather than
+flags, so two concurrent requests don't switch the indicator off when the first
+one finishes.
+
+```ts
+@Component({
+  template: `@if (loading.loading()) {
+    <my-progress-bar />
+  }`,
+})
+export class AppShell {
+  protected readonly loading = inject(ApiLoadingService);
+}
+```
+
+## Behaviour
+
+- The counter is incremented on **subscribe** and released on completion, error
+  or unsubscribe — a component destroyed mid-request never strands it.
+- It moves **once per `ApiService` call**, not once per HTTP attempt, so a
+  retried request holds the indicator for the whole operation.
+- An observable you never subscribe to never touches it.
+
+`start()` and `stop()` are internal to `ApiService` and should not be called by
+application code.
+
+## Excluding requests
+
+```ts
+this.api.get<Notification[]>('/notifications', { showLoader: false });
+```
+
+Or invert the default with `defaultShowLoader: false` in `provideApi()` and opt
+individual calls in with `showLoader: true`. See
+[Loading state](../guides/loading-state.mdx).