@comms-id/abn-react 0.2.0

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

@@ -0,0 +1,62 @@
+# @comms-id/abn-react
+
+A React hook and a finished component for Comms.ID ABN search. The user types a business name, or an ABN or ACN. Accessible, no layout shift, with the data attribution always shown. React 18 or later; it depends on `@comms-id/abn` and nothing else.
+
+```tsx
+import { createAbnBrowserClient } from "@comms-id/abn/browser";
+import { AbnAutocomplete } from "@comms-id/abn-react";
+
+const client = createAbnBrowserClient({ relayUrl: "/api/comms-id/abn" });
+
+export const Supplier = () => (
+  <AbnAutocomplete
+    client={client}
+    label="Business name or ABN"
+    onSelect={(business) => console.log(business.name, business.formattedAbn, business.status)}
+  />
+);
+```
+
+`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.
+
+## What the field does
+
+- **A name:** after the user pauses, it suggests businesses (name, ABN, state and postcode). Choosing one looks it up and calls `onSelect`.
+- **An ABN or ACN:** a whole number (9 or 11 digits, spaces and hyphens allowed) is checked in the browser first. An invalid number sends nothing, and the field says why ("This is not a valid ABN: the check digits do not match."). A valid number is looked up.
+- **No match is not an outage.** "No business found." and "Business search is unavailable" are different messages; an outage offers "Try again".
+
+`onSelect(business, timing)` gets one `AbnBusiness` whichever source answered the lookup: `abn`, `formattedAbn`, `acn`, `name`, `status`, `entityType`, `gstRegistered`, `state`, `postcode`, `source` (`live` or `snapshot`), `asAt` and `attribution`.
+
+## Your own markup: `useAbn`
+
+```tsx
+const abn = useAbn({ client, onSelect });
+return (
+  <>
+    <input {...abn.getInputProps()} />
+    <ul {...abn.getListboxProps("Matches")} hidden={!abn.state.open}>
+      {abn.state.suggestions.map((s, i) => (
+        <li key={`${s.abn}-${i}`} {...abn.getOptionProps(i)}>{describeSuggestion(s).primary}</li>
+      ))}
+    </ul>
+    <p {...abn.getStatusProps()}>{abn.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. Show the attribution yourself when you use the hook: `abn.state.attribution`.
+
+## The component
+
+Props: `client` and `label` (required), `onSelect`, `minChars` (3), `debounceMs` (200), `limit` (8), `prefer` (`{ state, postcode }`), `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-abn__*` class names. It needs no stylesheet.
+
+- The list floats under the input; opening it moves nothing. One note line has a reserved height and does not wrap: the result is a summary (name, ABN, status, GST), not a card, so the page never moves. Use `onSelect` for the whole record.
+- It renders on the server with the same structure, and works under StrictMode.
+
+## Data attribution
+
+The component always shows the attribution: the one the reply carried, or the standard text when a reply has none. Do not hide it.
+
+The package is private until the publishing path exists (#515). `LICENSE` is the consumer client licence.

package/dist/abn-autocomplete.d.ts

@@ -0,0 +1,21 @@
+import { type AbnSuggestion } from "@comms-id/abn/controller";
+import type { ReactNode } from "react";
+import { type UseAbnOptions } from "./use-abn.js";
+export interface AbnAutocompleteProps extends UseAbnOptions {
+    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: AbnSuggestion, state: {
+        readonly active: boolean;
+    }) => ReactNode;
+    readonly required?: boolean;
+    /** Show how long the lookup took. True by default. */
+    readonly showTiming?: boolean;
+}
+export declare const AbnAutocomplete: (props: AbnAutocompleteProps) => ReactNode;

package/dist/abn-autocomplete.js

@@ -0,0 +1,96 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// <AbnAutocomplete>: the ABN field as one component. The user types a business name, or an ABN
+// or ACN. 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-abn class names; it needs no stylesheet.
+import { describeBusiness, describeSuggestion } from "@comms-id/abn/controller";
+import { useAbn } from "./use-abn.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" };
+// One line with a fixed height: a found business, a message, or an error never moves what follows.
+const NOTE = {
+    minHeight: "1.6em",
+    margin: "4px 0 0",
+    fontSize: "0.85em",
+    lineHeight: "1.5em",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+};
+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) => {
+    const text = describeSuggestion(suggestion);
+    return (_jsxs(_Fragment, { children: [_jsx("span", { className: "comms-id-abn__name", children: text.primary }), _jsx("span", { className: "comms-id-abn__secondary", style: { display: "block", fontSize: "0.85em", opacity: 0.75 }, children: text.secondary })] }));
+};
+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-abn__retry", onClick: retry, type: "button", children: "Try again" })) : null] }));
+    }
+    if (state.status === "invalid" && state.invalid !== undefined) {
+        return state.invalid.message;
+    }
+    if (state.status === "empty") {
+        return "No business found.";
+    }
+    if (state.status === "resolved" && state.resolved !== undefined) {
+        const found = describeBusiness(state.resolved.business);
+        return showTiming ? `${found} (${state.resolved.timing.ms} ms)` : found;
+    }
+    return null;
+};
+export const AbnAutocomplete = (props) => {
+    const { label, name, placeholder, disabled, required, className, listLabel, showTiming, renderOption, ...options } = props;
+    const abn = useAbn(options);
+    const { state } = abn;
+    const note = noteFor(state, showTiming !== false, abn.retry);
+    return (_jsxs("div", { className: className === undefined ? "comms-id-abn" : `comms-id-abn ${className}`, style: ROOT, children: [_jsx("label", { className: "comms-id-abn__label", htmlFor: abn.ids.input, style: LABEL, children: label }), _jsxs("div", { style: FIELD, children: [_jsx("input", { ...abn.getInputProps(), className: "comms-id-abn__input", disabled: disabled, name: name, placeholder: placeholder, required: required, style: INPUT }), _jsxs("ul", { ...abn.getListboxProps(listLabel ?? "Business suggestions"), className: "comms-id-abn__list", hidden: !state.open, style: LIST, children: [state.suggestions.map((suggestion, index) => {
+                                const active = index === state.activeIndex;
+                                return (_jsx("li", { ...abn.getOptionProps(index), className: "comms-id-abn__option", style: { ...OPTION, background: active ? "var(--comms-id-active, #e8f0fe)" : "transparent" }, children: renderOption === undefined ? defaultOption(suggestion) : renderOption(suggestion, { active }) }, `${suggestion.abn}-${suggestion.nameType}-${suggestion.name}`));
+                            }), _jsx("li", { "aria-hidden": "true", className: "comms-id-abn__list-attribution", style: FOOTER, children: state.attribution })] })] }), _jsx("span", { ...abn.getStatusProps(), style: HIDDEN_FROM_SIGHT, children: state.announcement }), _jsx("p", { "aria-hidden": "true", className: "comms-id-abn__note", style: NOTE, children: note }), _jsx("p", { className: "comms-id-abn__attribution", style: ATTRIBUTION_TEXT, children: state.attribution })] }));
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { AbnBusiness, AbnState, AbnStatus, AbnSuggestion } from "@comms-id/abn/controller";
+export { ATTRIBUTION, describeBusiness, describeSuggestion } from "@comms-id/abn/controller";
+export type { AbnAutocompleteProps } from "./abn-autocomplete.js";
+export { AbnAutocomplete } from "./abn-autocomplete.js";
+export type { UseAbnOptions, UseAbnResult } from "./use-abn.js";
+export { useAbn } from "./use-abn.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { ATTRIBUTION, describeBusiness, describeSuggestion } from "@comms-id/abn/controller";
+export { AbnAutocomplete } from "./abn-autocomplete.js";
+export { useAbn } from "./use-abn.js";

package/dist/use-abn.d.ts

@@ -0,0 +1,23 @@
+import { type AbnControllerOptions, type AbnIds, type AbnState } from "@comms-id/abn/controller";
+export interface UseAbnOptions extends AbnControllerOptions {
+    /** 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 UseAbnResult {
+    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: AbnIds;
+    retry: () => void;
+    select: (index?: number) => void;
+    readonly state: AbnState;
+}
+export declare const useAbn: (options: UseAbnOptions) => UseAbnResult;
+export {};

package/dist/use-abn.js

@@ -0,0 +1,85 @@
+// The headless hook: the ABN controller as React state, plus prop getters that carry the
+// WAI-ARIA combobox contract. Use it with your own markup, or use <AbnAutocomplete>.
+import { createAbnController, handleKey, IDLE_STATE, inputAttributes, listboxAttributes, optionAttributes, statusAttributes, } from "@comms-id/abn/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 useAbn = (options) => {
+    const generated = useId().replace(COLONS, "");
+    const prefix = options.idPrefix ?? `comms-id-abn-${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 } = options;
+    const preferState = options.prefer?.state;
+    const preferPostcode = options.prefer?.postcode;
+    useEffect(() => {
+        const created = createAbnController({
+            client: {
+                suggest: (input, callOptions) => latest.current.client.suggest(input, callOptions),
+                lookup: (input, callOptions) => latest.current.client.lookup(input, callOptions),
+            },
+            ...(minChars === undefined ? {} : { minChars }),
+            ...(debounceMs === undefined ? {} : { debounceMs }),
+            ...(limit === undefined ? {} : { limit }),
+            ...(preferState === undefined && preferPostcode === undefined
+                ? {}
+                : {
+                    prefer: {
+                        ...(preferState === undefined ? {} : { state: preferState }),
+                        ...(preferPostcode === undefined ? {} : { postcode: preferPostcode }),
+                    },
+                }),
+            ...(latest.current.now === undefined ? {} : { now: () => latest.current.now?.() ?? 0 }),
+            onSelect: (business, timing) => latest.current.onSelect?.(business, timing),
+        });
+        setController(created);
+        return () => {
+            created.dispose();
+            setController(undefined);
+        };
+    }, [minChars, debounceMs, limit, preferState, preferPostcode]);
+    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

@@ -0,0 +1,57 @@
+{
+  "name": "@comms-id/abn-react",
+  "version": "0.2.0",
+  "description": "React hook and component for Comms.ID ABN search: a name or an ABN or ACN, 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/abn-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/abn": "0.2.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.0",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "happy-dom": "20.14.5",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "biome check .",
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}