# `default-chain.ts` — canonical detector-chain factory

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

`defaultDetectorChain(options)` builds the canonical 8-or-9 entry
detector chain consumed by `<TranslationProvider>` and
`useLocaleDetection` (and any other chain consumer that wants a
sensible default without enumerating every detector). The factory
returns a fresh `LocaleDetector[]` on every call so callers can
mutate or filter the result without affecting subsequent
invocations.

The order is deliberate: explicit user signals (querystring,
backend preference, cookie, localStorage) come first, followed by
shell-rendered hints (htmlLang), browser preferences
(acceptLanguage, navigator), geolocation (cloudflareIpGeo), and
finally the unconditional fallback.

## Features

- 8-entry chain when `userPreferenceEndpoint` is omitted; 9-entry
  chain when it is supplied. The user-preference detector slots
  in second so authenticated users' saved preferences beat every
  device-bound signal.
- Fresh array per call — callers can `.filter` / `.splice` /
  `.concat` without affecting subsequent invocations.
- Fallback always last; the factory wires
  `fallbackDetector(options.fallback)` as the terminal entry.
- Every detector is constructed with default options — consumers
  that need custom names / paths / endpoints assemble their own
  chain.

## Usage: Basic Example

```ts
import {
    createDetectorChain,
    defaultDetectorChain,
} from "@suaveplan/i18n-detector";

const chain = createDetectorChain(
    defaultDetectorChain({ fallback: "en-GB" })
);
```

## Usage: Advanced Example

```ts
import {
    createDetectorChain,
    defaultDetectorChain,
} from "@suaveplan/i18n-detector";

const chain = createDetectorChain(
    defaultDetectorChain({
        fallback: "en-GB",
        userPreferenceEndpoint: "/api/me/locale",
    }),
    { throwOnExhausted: true }
);

// Or filter to remove a detector that does not fit the deployment.
const detectors = defaultDetectorChain({ fallback: "en-GB" }).filter(
    (d) => d.name !== "cloudflareIpGeo"
);
```

## API Reference

- `defaultDetectorChain(options): LocaleDetector[]` — fresh array
  per call.
- `DefaultDetectorChainOptions.fallback: string` — required.
- `DefaultDetectorChainOptions.userPreferenceEndpoint?: string` —
  enables the user-preference detector when set.

## Implementation Notes

- The fallback is constructed via `fallbackDetector(...)` which
  validates the locale at chain-build time, so a misconfigured
  fallback surfaces immediately rather than at the first request.
- The factory makes no assumptions about cookie name, storage
  key, querystring param name, or geolocation header. Consumers
  that need custom configuration assemble their own chain by
  importing each detector directly.