@comms-id/australian-address-autocomplete-react 0.0.0-stage → 0.2.3

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 COMMS.ID PTY LTD. Proprietary software; not open source.
+
+Subject to the Comms.ID policy agreement, you may install, copy, bundle, run and
+deliver this client or component within your applications, adapt the supplied
+component source, and use the designated local functions and fixtures offline.
+Hosted operations are provided by the Comms.ID service.
+
+You may keep replies for your own customers and transactions, and your registered
+application may relay requests for its own users.
+
+You may not republish these packages as a standalone offering, resell access, offer
+a substitute lookup service, or harvest replies to reconstruct or redistribute a
+source dataset.
+
+Preserve this notice and any applicable third-party notices.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# @comms-id/australian-address-autocomplete-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A React hook and a finished component for Comms.ID Address autocomplete. Accessible, no layout shift, with the data attribution always shown. React 18 or later; it depends on `@comms-id/australian-address-autocomplete` and nothing else.
+
+```tsx
+import { createAustralianAddressAutocompleteBrowserClient } from "@comms-id/australian-address-autocomplete/browser";
+import { AustralianAddressAutocomplete } from "@comms-id/australian-address-autocomplete-react";
+
+const client = createAustralianAddressAutocompleteBrowserClient({ relayUrl: "/api/comms-id/address" });
+
+export const Checkout = () => (
+  <AustralianAddressAutocomplete
+    client={client}
+    label="Delivery address"
+    onSelect={(address, timing) => console.log(address.displayAddress, `${timing.ms} ms`)}
+  />
+);
+```
+
+`relayUrl` is your own server route, set up with `@comms-id/relay`: your server signs the call as your registered app, so the browser holds no credential.
+
+## Your own markup: `useAustralianAddressAutocomplete`
+
+```tsx
+const address = useAustralianAddressAutocomplete({ client, onSelect });
+return (
+  <>
+    <input {...address.getInputProps()} />
+    <ul {...address.getListboxProps("Matches")} hidden={!address.state.open}>
+      {address.state.suggestions.map((s, i) => (
+        <li key={s.id} {...address.getOptionProps(i)}>{s.label}</li>
+      ))}
+    </ul>
+    <p {...address.getStatusProps()}>{address.state.announcement}</p>
+  </>
+);
+```
+
+The prop getters carry the WAI-ARIA combobox contract: roles, `aria-expanded`, `aria-controls`, `aria-activedescendant`, key handling (arrows, Enter, Escape, Tab) and a polite live region. Render the attribution yourself when you use the hook: `import { ATTRIBUTION } from "@comms-id/australian-address-autocomplete-react"`.
+
+## The component
+
+Props: `client` and `label` (required), `onSelect`, `minChars` (3), `debounceMs` (400), `limit` (8), `within`, `idPrefix`, `name`, `placeholder`, `disabled`, `required`, `className`, `listLabel`, `showTiming` (true), `renderOption`.
+
+Style it with the custom properties `--comms-id-text`, `--comms-id-surface`, `--comms-id-border`, `--comms-id-active`, `--comms-id-radius` or the `comms-id-australian-address-autocomplete__*` class names. It needs no stylesheet.
+
+- The list floats under the input; opening it moves nothing. The status line has a reserved height.
+- A failed lookup says why (`Address search is unavailable`) and offers "Try again"; it is never shown as "no match".
+- It renders on the server with the same structure, and works under StrictMode.
+
+## Data attribution
+
+Address data is G-NAF. The component always shows the required wording. Do not hide it.
+
+`LICENSE` is the consumer client licence.

package/dist/address-autocomplete.d.ts

@@ -0,0 +1,21 @@
+import { type AddressSuggestion } from "@comms-id/australian-address-autocomplete/controller";
+import type { ReactNode } from "react";
+import { type UseAddressOptions } from "./use-address.js";
+export interface AustralianAddressAutocompleteProps extends UseAddressOptions {
+    readonly className?: string;
+    readonly disabled?: boolean;
+    /** The visible label of the field. Required: a field without a label is not accessible. */
+    readonly label: string;
+    /** The accessible name of the list of suggestions. */
+    readonly listLabel?: string;
+    readonly name?: string;
+    readonly placeholder?: string;
+    /** Your own content for one suggestion. */
+    readonly renderOption?: (suggestion: AddressSuggestion, state: {
+        readonly active: boolean;
+    }) => ReactNode;
+    readonly required?: boolean;
+    /** Show how long the chosen address took to resolve. True by default. */
+    readonly showTiming?: boolean;
+}
+export declare const AustralianAddressAutocomplete: (props: AustralianAddressAutocompleteProps) => ReactNode;

package/dist/address-autocomplete.js

@@ -0,0 +1,80 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// <AustralianAddressAutocomplete>: the Address field as one component. It is accessible (WAI-ARIA combobox),
+// it never shifts the page (the list floats, every other line has a fixed place), and it always
+// shows the data attribution. Style it with the --comms-id-* variables or the comms-id-australian-address-autocomplete
+// class names; it needs no stylesheet.
+import { ATTRIBUTION, } from "@comms-id/australian-address-autocomplete/controller";
+import { highlight } from "./highlight.js";
+import { useAustralianAddressAutocomplete } from "./use-address.js";
+const HIDDEN_FROM_SIGHT = {
+    position: "absolute",
+    width: 1,
+    height: 1,
+    margin: -1,
+    padding: 0,
+    overflow: "hidden",
+    clip: "rect(0 0 0 0)",
+    whiteSpace: "nowrap",
+    border: 0,
+};
+const ROOT = { position: "relative", color: "var(--comms-id-text, inherit)", font: "inherit" };
+const LABEL = { display: "block", marginBottom: 4 };
+const FIELD = { position: "relative" };
+const INPUT = {
+    boxSizing: "border-box",
+    width: "100%",
+    padding: "0.5rem 0.75rem",
+    font: "inherit",
+    color: "inherit",
+    background: "var(--comms-id-surface, #fff)",
+    border: "1px solid var(--comms-id-border, #767676)",
+    borderRadius: "var(--comms-id-radius, 4px)",
+};
+// The list floats under the input, so opening and closing it moves nothing else on the page.
+const LIST = {
+    position: "absolute",
+    top: "100%",
+    left: 0,
+    right: 0,
+    zIndex: 1000,
+    maxHeight: "16rem",
+    overflowY: "auto",
+    margin: "4px 0 0",
+    padding: 0,
+    listStyle: "none",
+    background: "var(--comms-id-surface, #fff)",
+    color: "var(--comms-id-text, #111)",
+    border: "1px solid var(--comms-id-border, #767676)",
+    borderRadius: "var(--comms-id-radius, 4px)",
+    boxShadow: "0 4px 12px rgb(0 0 0 / 15%)",
+};
+const OPTION = { padding: "0.5rem 0.75rem", cursor: "pointer" };
+const NOTE = { minHeight: "1.6em", margin: "4px 0 0", fontSize: "0.85em", lineHeight: "1.5em" };
+const ATTRIBUTION_TEXT = { margin: "2px 0 0", fontSize: "0.75em", lineHeight: 1.4, opacity: 0.8 };
+const FOOTER = {
+    ...ATTRIBUTION_TEXT,
+    padding: "0.5rem 0.75rem",
+    borderTop: "1px solid var(--comms-id-border, #767676)",
+};
+const defaultOption = (suggestion) => (_jsxs(_Fragment, { children: [suggestion.unitLabel === undefined ? null : (_jsxs("span", { className: "comms-id-australian-address-autocomplete__unit", children: [suggestion.unitLabel, " "] })), _jsx("span", { className: "comms-id-australian-address-autocomplete__label-text", children: highlight(suggestion.label, suggestion.matchedRanges) }), suggestion.secondaryLabel === undefined ? null : (_jsx("span", { className: "comms-id-australian-address-autocomplete__secondary", style: { display: "block", fontSize: "0.85em", opacity: 0.75 }, children: suggestion.secondaryLabel }))] }));
+const noteFor = (state, showTiming, retry) => {
+    if (state.status === "error" && state.error !== undefined) {
+        return (_jsxs(_Fragment, { children: [state.error.message, " ", state.error.retryable ? (_jsx("button", { className: "comms-id-australian-address-autocomplete__retry", onClick: retry, type: "button", children: "Try again" })) : null] }));
+    }
+    if (state.status === "resolved" && state.resolved !== undefined && showTiming) {
+        return `Resolved in ${state.resolved.timing.ms} ms by Comms.ID address search.`;
+    }
+    return null;
+};
+export const AustralianAddressAutocomplete = (props) => {
+    const { label, name, placeholder, disabled, required, className, listLabel, showTiming, renderOption, ...options } = props;
+    const address = useAustralianAddressAutocomplete(options);
+    const { state } = address;
+    const note = noteFor(state, showTiming !== false, address.retry);
+    return (_jsxs("div", { className: className === undefined
+            ? "comms-id-australian-address-autocomplete"
+            : `comms-id-australian-address-autocomplete ${className}`, style: ROOT, children: [_jsx("label", { className: "comms-id-australian-address-autocomplete__label", htmlFor: address.ids.input, style: LABEL, children: label }), _jsxs("div", { style: FIELD, children: [_jsx("input", { ...address.getInputProps(), className: "comms-id-australian-address-autocomplete__input", disabled: disabled, name: name, placeholder: placeholder, required: required, style: INPUT }), _jsxs("ul", { ...address.getListboxProps(listLabel ?? "Address suggestions"), className: "comms-id-australian-address-autocomplete__list", hidden: !state.open, style: LIST, children: [state.suggestions.map((suggestion, index) => {
+                                const active = index === state.activeIndex;
+                                return (_jsx("li", { ...address.getOptionProps(index), className: "comms-id-australian-address-autocomplete__option", style: { ...OPTION, background: active ? "var(--comms-id-active, #e8f0fe)" : "transparent" }, children: renderOption === undefined ? defaultOption(suggestion) : renderOption(suggestion, { active }) }, suggestion.id));
+                            }), _jsx("li", { "aria-hidden": "true", className: "comms-id-australian-address-autocomplete__list-attribution", style: FOOTER, children: ATTRIBUTION })] })] }), _jsx("span", { ...address.getStatusProps(), style: HIDDEN_FROM_SIGHT, children: state.announcement }), _jsx("p", { "aria-hidden": "true", className: "comms-id-australian-address-autocomplete__note", style: NOTE, children: note }), _jsx("p", { className: "comms-id-australian-address-autocomplete__attribution", style: ATTRIBUTION_TEXT, children: ATTRIBUTION })] }));
+};

package/dist/highlight.d.ts

@@ -0,0 +1,4 @@
+import { type MatchRange } from "@comms-id/australian-address-autocomplete/controller";
+import type { ReactNode } from "react";
+/** The label with the matched parts in <strong>. Ranges are [start, end) offsets into the label. */
+export declare const highlight: (label: string, ranges: readonly MatchRange[]) => ReactNode[];

package/dist/highlight.js

@@ -0,0 +1,4 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { splitMatches } from "@comms-id/australian-address-autocomplete/controller";
+/** The label with the matched parts in <strong>. Ranges are [start, end) offsets into the label. */
+export const highlight = (label, ranges) => splitMatches(label, ranges).map((segment, index) => segment.match ? _jsx("strong", { children: segment.text }, `${index}-${segment.text}`) : segment.text);

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { AddressState, AddressStatus, AddressSuggestion, } from "@comms-id/australian-address-autocomplete/controller";
+export { ATTRIBUTION } from "@comms-id/australian-address-autocomplete/controller";
+export type { AustralianAddressAutocompleteProps } from "./address-autocomplete.js";
+export { AustralianAddressAutocomplete } from "./address-autocomplete.js";
+export { highlight } from "./highlight.js";
+export type { UseAddressOptions, UseAddressResult } from "./use-address.js";
+export { useAustralianAddressAutocomplete } from "./use-address.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { ATTRIBUTION } from "@comms-id/australian-address-autocomplete/controller";
+export { AustralianAddressAutocomplete } from "./address-autocomplete.js";
+export { highlight } from "./highlight.js";
+export { useAustralianAddressAutocomplete } from "./use-address.js";

package/dist/use-address.d.ts

@@ -0,0 +1,23 @@
+import { type AddressControllerOptions, type AddressIds, type AddressState } from "@comms-id/australian-address-autocomplete/controller";
+export interface UseAddressOptions extends AddressControllerOptions {
+    /** Prefix of the element ids. A generated one by default; set it to name the input yourself. */
+    readonly idPrefix?: string;
+}
+type Props = Record<string, unknown>;
+export interface UseAddressResult {
+    close: () => void;
+    /** Props for the text input: role, aria-*, value and the handlers. */
+    getInputProps: () => Props;
+    /** Props for the list element (role listbox). It must always be rendered; hide it while closed. */
+    getListboxProps: (label: string) => Props;
+    /** Props for the option at `index` (role option). */
+    getOptionProps: (index: number) => Props;
+    /** Props for the polite live region that says what just happened. */
+    getStatusProps: () => Props;
+    readonly ids: AddressIds;
+    retry: () => void;
+    select: (index?: number) => void;
+    readonly state: AddressState;
+}
+export declare const useAustralianAddressAutocomplete: (options: UseAddressOptions) => UseAddressResult;
+export {};

package/dist/use-address.js

@@ -0,0 +1,76 @@
+// The headless hook: the Address controller as React state, plus prop getters that carry the
+// WAI-ARIA combobox contract. Use it with your own markup, or use <AustralianAddressAutocomplete>.
+import { createAddressController, handleKey, IDLE_STATE, inputAttributes, listboxAttributes, optionAttributes, statusAttributes, } from "@comms-id/australian-address-autocomplete/controller";
+import { useEffect, useId, useRef, useState, useSyncExternalStore, } from "react";
+const EMPTY = { getState: () => IDLE_STATE, subscribe: () => () => undefined };
+// React's names for three attributes the framework-neutral helpers write in HTML case.
+const REACT_NAMES = {
+    autocomplete: "autoComplete",
+    autocapitalize: "autoCapitalize",
+    spellcheck: "spellCheck",
+};
+const toProps = (attributes) => Object.fromEntries(Object.entries(attributes)
+    .filter(([, value]) => value !== undefined)
+    .map(([name, value]) => [REACT_NAMES[name] ?? name, value]));
+const COLONS = /:/g;
+export const useAustralianAddressAutocomplete = (options) => {
+    const generated = useId().replace(COLONS, "");
+    const prefix = options.idPrefix ?? `comms-id-address-${generated}`;
+    const ids = { input: `${prefix}-input`, listbox: `${prefix}-list`, status: `${prefix}-status` };
+    // The latest options, read at call time, so a new client or callback never recreates the controller.
+    const latest = useRef(options);
+    useEffect(() => {
+        latest.current = options;
+    });
+    const [controller, setController] = useState(undefined);
+    const { minChars, debounceMs, limit, within } = options;
+    useEffect(() => {
+        const created = createAddressController({
+            client: {
+                suggest: (input, callOptions) => latest.current.client.suggest(input, callOptions),
+                resolve: (input, callOptions) => latest.current.client.resolve(input, callOptions),
+            },
+            ...(minChars === undefined ? {} : { minChars }),
+            ...(debounceMs === undefined ? {} : { debounceMs }),
+            ...(limit === undefined ? {} : { limit }),
+            ...(within === undefined ? {} : { within }),
+            ...(latest.current.now === undefined ? {} : { now: () => latest.current.now?.() ?? 0 }),
+            onSelect: (address, timing) => latest.current.onSelect?.(address, timing),
+        });
+        setController(created);
+        return () => {
+            created.dispose();
+            setController(undefined);
+        };
+    }, [minChars, debounceMs, limit, within]);
+    const store = controller ?? EMPTY;
+    const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+    return {
+        state,
+        ids,
+        getInputProps: () => ({
+            ...toProps(inputAttributes(state, ids)),
+            value: state.query,
+            onChange: (event) => controller?.setQuery(event.target.value),
+            onKeyDown: (event) => {
+                if (controller !== undefined && handleKey(controller, event.key)) {
+                    event.preventDefault();
+                }
+            },
+            onFocus: () => controller?.open(),
+            onBlur: () => controller?.close(),
+        }),
+        getListboxProps: (label) => toProps(listboxAttributes(ids, label)),
+        getOptionProps: (index) => ({
+            ...toProps(optionAttributes(state, ids, index)),
+            // The input keeps focus while the pointer chooses an option.
+            onMouseDown: (event) => event.preventDefault(),
+            onMouseMove: () => controller?.setActive(index),
+            onClick: () => controller?.select(index),
+        }),
+        getStatusProps: () => toProps(statusAttributes(ids)),
+        select: (index) => controller?.select(index),
+        retry: () => controller?.retry(),
+        close: () => controller?.close(),
+    };
+};

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@comms-id/australian-address-autocomplete-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.3",
+  "description": "React hook and component for Comms.ID Address autocomplete: accessible, no layout shift, with the data attribution",
+  "homepage": "https://comms.id",
+  "bugs": {
+    "url": "https://github.com/comms-id/platform/issues"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "COMMS.ID PTY LTD",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/comms-id/platform.git",
+    "directory": "packages/australian-address-autocomplete-react"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@comms-id/australian-address-autocomplete": "0.3.2"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "happy-dom": "21.0.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "7.0.2",
+    "vitest": "5.0.4"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "biome check .",
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }