# Upgrading the Charity element

Hand-written, next to the generated reference. The generator keeps this file and does not check it. Newest first.

## 1.1.0 to 1.1.1

This patch preserves the service error when its retry wait cannot fit the request deadline. A rate-limit response with a 60-second Retry-After and the default 10-second deadline now reports FAIR_USE_CEILING instead of TIMEOUT. No retry is sent early.

Update the exact script URL and integrity together:

```html
<script
  src="https://cdn.comms.id/charity/1.1.1.js"
  integrity="sha384-nsUh4bY9nqDcsDIKPJse7z3mXMkTyY2fHjACC6M8SdS/Eh+VtXJ1f0NPygI+gCov"
  crossorigin="anonymous"
></script>
```

The bundle is 38,362 bytes (10,829 bytes gzipped). Attributes, events and theme defaults are unchanged. Earlier exact-version files remain available with their original bytes; the major alias takes this patch when the CDN is deployed.

## 1.0.0 to 1.1.0

The element now uses the shared Comms.ID theme for default colours, borders, focus and corner radius. It inherits light/dark tokens when the host imports `@comms-id/theme/tokens.css`; without that stylesheet it uses the light defaults. Existing `--comms-id-*` overrides and `::part()` styles keep priority. Fonts still inherit from the host page.

The public attributes, events, requests and shadow isolation are unchanged. Review the new default appearance before updating a version-pinned script. The major alias `https://cdn.comms.id/charity/v1.js` takes this release when the CDN is deployed; older exact-version files stay unchanged.

```html
<script
  src="https://cdn.comms.id/charity/1.1.0.js"
  integrity="sha384-pX9D5EsDbTrVkyh8oa3tWEINa39+kzTQ6QQPAqnGPGmEIAqrDNExvq8KWA7HtHLv"
  crossorigin="anonymous"
></script>
```

The new file is 38,294 bytes (10,751 bytes gzipped, below the 15,000-byte limit). The element remains a CDN asset; the theme dependency is bundled into it, so a plain script install needs no npm step.

## 0.1.0 to 1.0.0

### In one line

Change the script's version and its integrity hash. Nothing else on your page changes.

### What changed

- **One behaviour you can see: the element waits 400 ms after the last key before it checks or looks up the ABN (it was 200 ms).** Charity has no suggestions, so the field does not send a request for each key; only the pause before the check and the lookup is longer. To keep the old wait, add `debounce="200"` to the element.
- **Nothing else changed.** The two files differ in one character, the default wait (200 became 400 in the bundled controller). The attributes (the `debounce` attribute still overrides the default), events, properties, parts, custom properties and content security policy needs are the same as in 0.1.0. 1.0.0 is the launch release; the 0.x releases were prereleases. The size is the same (35,750 bytes; gzipped 10,065 to 10,067 of the 15,000 allowed).
- **New URLs.** `https://cdn.comms.id/charity/1.0.0.js` is new, and so is the major alias `https://cdn.comms.id/charity/v1.js`, which follows the newest 1.x release (1.0.0 now). The alias `https://cdn.comms.id/charity/v0.js` is not changed by this release and keeps serving 0.1.0.

### Script tag

Before (0.1.0):

```html
<script
  src="https://cdn.comms.id/charity/0.1.0.js"
  integrity="sha384-Wgc1qrX3Y2V1KoNOu7MonVErAPDKWsbkZyM/C1Gd2ZEJ/hVtQxRMmgSGIEHH4Gi3"
  crossorigin="anonymous"
></script>
```

After (1.0.0):

```html
<script
  src="https://cdn.comms.id/charity/1.0.0.js"
  integrity="sha384-G0Wi9/1Ev4L3WT3GQ/aQhA+oJ+8HJKM1vZQZQMtw0VD8RT7+oJz7NJiWva9UmLD/"
  crossorigin="anonymous"
></script>
```

If you use the major alias `https://cdn.comms.id/charity/v0.js`, change it to `https://cdn.comms.id/charity/v1.js` to take 1.0.0. The alias cannot carry an integrity hash, because its bytes change with each release. `0.1.0.js` stays served and unchanged, so a page that is not upgraded keeps working as before.

### npm

No npm change is needed for the element: `@comms-id/charity-element` is not published to npm, the element is served from the CDN only. The default wait comes from the controller, so the npm packages that run it get the same default in their next minor release: `@comms-id/charity` (0.3.0 now, then 0.4.0) and, as a patch, `@comms-id/charity-react` (0.2.0 now). The API does not change: only the default of `debounceMs` (200 became 400); pass `debounceMs: 200` to keep the old wait. A range such as `^0.3.0` stays on 0.3.x for a 0.x package, so to take the new default change the range to `^0.4.0`.

## Check a release yourself

The CDN manifest lists every released version with the hash of its exact bytes:

```sh
curl -s https://cdn.comms.id/manifest.json
curl -s https://cdn.comms.id/charity/1.0.0.js | openssl dgst -sha384 -binary | openssl base64 -A
```

The second command, for the version you are moving to, must print the hash in that version's script tag above (for 1.0.0: `G0Wi9/1Ev4L3WT3GQ/aQhA+oJ+8HJKM1vZQZQMtw0VD8RT7+oJz7NJiWva9UmLD/`). A released file never changes, so a page that has not been upgraded keeps working.

After the change, the element must still be defined and answer: open the page and use the field, and the element works as before. A wrong hash blocks the script; the browser console names the integrity failure.