@comms-id/oric-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/oric-react
+
+A React hook and a finished component for the Comms.ID Indigenous corporation field: the user types the name, ICN or ABN of an Aboriginal and Torres Strait Islander corporation. Accessible, no layout shift, with the data attribution always shown. React 18 or later; it depends on `@comms-id/oric` and nothing else.
+
+```tsx
+import { createOricBrowserClient } from "@comms-id/oric/browser";
+import { OricLookup } from "@comms-id/oric-react";
+
+const client = createOricBrowserClient({ relayUrl: "/api/comms-id/oric" });
+
+export const Form = () => (
+  <OricLookup
+    client={client}
+    onSelect={(record, timing) => console.log(record, `${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.
+
+## What the field does
+
+- **A name:** after the user pauses, it suggests corporations (name, ICN, state and postcode, status) from the ORIC dataset snapshot. The search already returns each whole record, so choosing one needs no second call.
+- **An ICN:** up to eight digits are looked up at once. Longer numbers that are not an ABN wait for more digits; more than eleven digits is refused in the browser.
+- **An ABN:** eleven digits are looked up. An ABN can match more than one corporation, so the matches are listed as suggestions and the user chooses an ICN; the service never guesses a record.
+- The result is one summary line (name, ICN, place, status) on a fixed note line, so the page never moves.
+- "No corporation found." and "Corporation search is unavailable" are different messages; an outage offers "Try again".
+
+## Your own markup: `useOric`
+
+```tsx
+const field = useOric({ client, onSelect });
+return (
+  <>
+    <input {...field.getInputProps()} />
+    <ul {...field.getListboxProps("Matches")} hidden={!field.state.open}>
+      {field.state.suggestions.map((s, i) => (
+        <li key={s.key} {...field.getOptionProps(i)}>{s.primary}</li>
+      ))}
+    </ul>
+    <p {...field.getStatusProps()}>{field.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: it is `field.state.attribution`.
+
+## The component
+
+Props: `client` (required), `label` (default "Corporation name, ICN or ABN"), `onSelect`, `minChars` (3), `debounceMs` (200), `limit` (8), `settings`, `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-oric__*` class names. It needs no stylesheet.
+
+- The list floats under the input; opening it moves nothing. The note line has a reserved height.
+- A failed lookup says why 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
+
+Source: Aboriginal and Torres Strait Islander corporations dataset, Office of the Registrar of Indigenous Corporations (ORIC), via data.gov.au (CC BY 3.0 AU). The component always shows the attribution. Do not hide it.
+
+The package is private until the publishing path exists (#515). `LICENSE` is the consumer client licence. `src/` is generated by `@comms-id/forge-transformers` and is never edited by hand.

package/dist/generated/field.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+import { type SuggestionView } from "./product.js";
+import { type UseFieldOptions } from "./use-field.js";
+export interface FieldProps extends UseFieldOptions {
+    readonly className?: string;
+    readonly disabled?: boolean;
+    /** The visible label of the field. The product's own wording by default. */
+    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: SuggestionView, state: {
+        readonly active: boolean;
+    }) => ReactNode;
+    readonly required?: boolean;
+    /** Show how long the lookup took. True by default. */
+    readonly showTiming?: boolean;
+}
+export declare const Field: (props: FieldProps) => ReactNode;

package/dist/generated/field.js

@@ -0,0 +1,90 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PRODUCT, PROFILE } from "./product.js";
+import { useField } from "./use-field.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 record, 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) => (_jsxs(_Fragment, { children: [_jsx("span", { className: `comms-id-${PRODUCT}__name`, children: suggestion.primary }), _jsx("span", { className: `comms-id-${PRODUCT}__secondary`, style: { display: "block", fontSize: "0.85em", opacity: 0.75 }, children: suggestion.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-${PRODUCT}__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 PROFILE.notFound;
+    }
+    if (state.status === "resolved" && state.resolved !== undefined) {
+        const found = state.resolved.found.summary;
+        return showTiming ? `${found} (${state.resolved.timing.ms} ms)` : found;
+    }
+    return null;
+};
+export const Field = (props) => {
+    const { label, name, placeholder, disabled, required, className, listLabel, showTiming, renderOption, ...options } = props;
+    const field = useField(options);
+    const { state } = field;
+    const note = noteFor(state, showTiming !== false, field.retry);
+    const base = `comms-id-${PRODUCT}`;
+    return (_jsxs("div", { className: className === undefined ? base : `${base} ${className}`, style: ROOT, children: [_jsx("label", { className: `${base}__label`, htmlFor: field.ids.input, style: LABEL, children: label ?? PROFILE.label }), _jsxs("div", { style: FIELD, children: [_jsx("input", { ...field.getInputProps(), className: `${base}__input`, disabled: disabled, name: name, placeholder: placeholder, required: required, style: INPUT }), _jsxs("ul", { ...field.getListboxProps(listLabel ?? PROFILE.listLabel), className: `${base}__list`, hidden: !state.open, style: LIST, children: [state.suggestions.map((suggestion, index) => {
+                                const active = index === state.activeIndex;
+                                return (_jsx("li", { ...field.getOptionProps(index), className: `${base}__option`, style: { ...OPTION, background: active ? "var(--comms-id-active, #e8f0fe)" : "transparent" }, children: renderOption === undefined ? defaultOption(suggestion) : renderOption(suggestion, { active }) }, suggestion.key));
+                            }), _jsx("li", { "aria-hidden": "true", className: `${base}__list-attribution`, style: FOOTER, children: state.attribution })] })] }), _jsx("span", { ...field.getStatusProps(), style: HIDDEN_FROM_SIGHT, children: state.announcement }), _jsx("p", { "aria-hidden": "true", className: `${base}__note`, style: NOTE, children: note }), _jsx("p", { className: `${base}__attribution`, style: ATTRIBUTION_TEXT, children: state.attribution })] }));
+};

package/dist/generated/product.d.ts

@@ -0,0 +1,37 @@
+export type { Attributes, OricClient as Client, OricController as Controller, OricControllerOptions as ControllerOptions, OricRecord as ProductRecord, OricState as State, FieldIds as Ids, SuggestionView, } from "@comms-id/oric/controller";
+export { createOricController as createController, handleKey, idleState, inputAttributes, listboxAttributes, optionAttributes, statusAttributes, } from "@comms-id/oric/controller";
+import type { OricClient } from "@comms-id/oric/controller";
+export declare const PRODUCT = "oric";
+export declare const TAG = "comms-id-oric";
+export declare const PROFILE: import("@comms-id/oric/controller").FieldProfile<OricClient, {
+    readonly icn: string;
+    readonly name: string;
+    readonly statusReason: string | null;
+    readonly registeredOn: string | null;
+    readonly deregisteredOn: string | null;
+    readonly corporationSize: string | null;
+    readonly abn: string | null;
+    readonly state: string | null;
+    readonly postcode: string | null;
+    readonly industrySectors: readonly string[];
+    readonly acncRegistered: boolean | null;
+    readonly financials: ReadonlyArray<{
+        readonly year: number;
+        readonly totalIncome: string | null;
+        readonly totalAssets: string | null;
+        readonly employees: string | null;
+    }>;
+    readonly portalUrl: string | null;
+    readonly portalId: string | null;
+    readonly liveObservation?: {
+        readonly source: "oric-portal-observation";
+        readonly observedAt: string;
+        readonly baseGeneration: string;
+        readonly fields: readonly string[];
+        readonly fieldObservedAt: Readonly<Record<string, string>>;
+    };
+}>;
+/** The operations of Comms.ID Indigenous corporation. A capability is for one of them. */
+export type VisitorOperation = "lookup" | "search";
+/** A client that asks `get` for the client of each call: a new client, relay or key takes effect at once. */
+export declare const routeClient: (get: (operation: VisitorOperation) => OricClient) => OricClient;

package/dist/generated/product.js

@@ -0,0 +1,12 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// Names the product for the templates next to this file: they import only from here.
+import { profile } from "@comms-id/oric/controller";
+export { createOricController as createController, handleKey, idleState, inputAttributes, listboxAttributes, optionAttributes, statusAttributes, } from "@comms-id/oric/controller";
+export const PRODUCT = "oric";
+export const TAG = "comms-id-oric";
+export const PROFILE = profile;
+/** A client that asks `get` for the client of each call: a new client, relay or key takes effect at once. */
+export const routeClient = (get) => ({
+    lookup: (input, options) => get("lookup").lookup(input, options),
+    search: (input, options) => get("search").search(input, options),
+});

package/dist/generated/use-field.d.ts

@@ -0,0 +1,23 @@
+import { type ControllerOptions, type Ids, type State } from "./product.js";
+export interface UseFieldOptions extends ControllerOptions {
+    /** 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 UseFieldResult {
+    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: Ids;
+    retry: () => void;
+    select: (index?: number) => void;
+    readonly state: State;
+}
+export declare const useField: (options: UseFieldOptions) => UseFieldResult;
+export {};

package/dist/generated/use-field.js

@@ -0,0 +1,76 @@
+// Template: copied unchanged into a generated React package as src/generated/use-field.ts.
+// The headless hook: the field controller as React state, plus prop getters that carry the
+// WAI-ARIA combobox contract. Use it with your own markup, or use the finished component.
+import { useEffect, useId, useRef, useState, useSyncExternalStore, } from "react";
+import { createController, handleKey, idleState, inputAttributes, listboxAttributes, optionAttributes, PRODUCT, PROFILE, routeClient, statusAttributes, } from "./product.js";
+const EMPTY = { getState: () => idleState(PROFILE.attribution), 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 useField = (options) => {
+    const generated = useId().replace(COLONS, "");
+    const prefix = options.idPrefix ?? `comms-id-${PRODUCT}-${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 settingsKey = JSON.stringify(options.settings ?? {});
+    useEffect(() => {
+        const created = createController({
+            // Every call goes to the client of the moment.
+            client: routeClient(() => latest.current.client),
+            ...(minChars === undefined ? {} : { minChars }),
+            ...(debounceMs === undefined ? {} : { debounceMs }),
+            ...(limit === undefined ? {} : { limit }),
+            settings: JSON.parse(settingsKey),
+            ...(latest.current.now === undefined ? {} : { now: () => latest.current.now?.() ?? 0 }),
+            onSelect: (record, timing) => latest.current.onSelect?.(record, timing),
+        });
+        setController(created);
+        return () => {
+            created.dispose();
+            setController(undefined);
+        };
+    }, [minChars, debounceMs, limit, settingsKey]);
+    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/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { OricRecord, OricState, SuggestionView as OricSuggestion } from "@comms-id/oric/controller";
+export type { FieldProps as OricLookupProps } from "./generated/field.js";
+export { Field as OricLookup } from "./generated/field.js";
+export type { UseFieldOptions as UseOricOptions, UseFieldResult as UseOricResult } from "./generated/use-field.js";
+export { useField as useOric } from "./generated/use-field.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+export { Field as OricLookup } from "./generated/field.js";
+export { useField as useOric } from "./generated/use-field.js";

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@comms-id/oric-react",
+  "version": "0.2.0",
+  "description": "React hook and component for the Comms.ID Indigenous corporation field: Indigenous corporation name, ICN or ABN, 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/oric-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/oric": "0.3.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"
+  }
+}