@comms-id/company 0.2.0 → 0.3.0

package/README.md

@@ -28,3 +28,17 @@ Every operation is a read, safe to repeat, and is retried after a retryable fail
 Entries: `.` (types and errors, safe in a browser), `./server` (signs each call), `./browser` (your relay route; never signs), `./fixtures` (LOCAL FIXTURES, no network), `./descriptor` (what `@comms-id/relay` may forward).
 
 The package is private until the publishing path exists (#515). `LICENSE` is the consumer client licence.
+
+## The field
+
+`@comms-id/company/controller` is the headless controller of a company name or ACN field: input, debounce, suggestions, identifier checks, choice and errors, with the WAI-ARIA combobox attributes and key handler. It has no framework and no DOM. `@comms-id/company-react` (a hook and a component) and `<comms-id-company>` (a web element) run on it, and so can your own UI.
+
+```ts
+import { createCompanyController } from "@comms-id/company/controller";
+
+const controller = createCompanyController({ client, onSelect: (record, timing) => console.log(record, timing.ms) });
+controller.subscribe(() => render(controller.getState()));
+controller.setQuery("…");
+```
+
+`src/local/profile.ts` is the only product-specific part: it reads the typed text, calls the client and reduces every reply to the text the UIs show and the record `onSelect` receives. Everything else is generated.

package/dist/controller.d.ts

@@ -0,0 +1,15 @@
+import type { CompanyClient } from "./generated/client.js";
+import type { FieldController, FieldControllerOptions, FieldState } from "./runtime/field-types.js";
+import { type ProductRecord, profile } from "./local/profile.js";
+export type { Attributes, FieldIds } from "./runtime/field-aria.js";
+export { handleKey, inputAttributes, listboxAttributes, optionAttributes, optionId, statusAttributes, } from "./runtime/field-aria.js";
+export { DEFAULT_DEBOUNCE_MS, DEFAULT_LIMIT, DEFAULT_MIN_CHARS, idleState } from "./runtime/field-controller.js";
+export type { Chosen, FieldError, FieldProfile, FieldStatus, FieldTiming, Found, Looked, Reading, ReadContext, Run, Searched, Suggestion, SuggestionView, } from "./runtime/field-types.js";
+export type { CompanyClient } from "./generated/client.js";
+export { profile };
+export type { ProductRecord as CompanyRecord };
+export type CompanyController = FieldController<ProductRecord>;
+export type CompanyControllerOptions = Omit<FieldControllerOptions<CompanyClient, ProductRecord>, "profile">;
+export type CompanyState = FieldState<ProductRecord>;
+/** Creates the controller. Nothing is called until the first `setQuery`. */
+export declare const createCompanyController: (options: CompanyControllerOptions) => CompanyController;

package/dist/controller.js

@@ -0,0 +1,11 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// Controller entry: the headless controller of the Comms.ID Company field, its WAI-ARIA attributes
+// and key handler, and the product's profile. No framework, no DOM. The React package and the
+// web element run on it.
+import { createFieldController } from "./runtime/field-controller.js";
+import { profile } from "./local/profile.js";
+export { handleKey, inputAttributes, listboxAttributes, optionAttributes, optionId, statusAttributes, } from "./runtime/field-aria.js";
+export { DEFAULT_DEBOUNCE_MS, DEFAULT_LIMIT, DEFAULT_MIN_CHARS, idleState } from "./runtime/field-controller.js";
+export { profile };
+/** Creates the controller. Nothing is called until the first `setQuery`. */
+export const createCompanyController = (options) => createFieldController({ ...options, profile });

package/dist/generated/operations.js

@@ -669,6 +669,6 @@ export const operations = {
 };
 /** The error codes the contract documents for each operation. */
 export const errorCodes = {
-    lookup: ["INVALID_INPUT", "UNAUTHORIZED", "RESIDENCY_INGRESS", "NOT_FOUND", "METHOD_NOT_ALLOWED", "LIMIT_REACHED", "CANCELLED", "INTERNAL_ERROR", "UNAVAILABLE", "RESIDENCY_UNAVAILABLE"],
-    search: ["INVALID_INPUT", "UNAUTHORIZED", "RESIDENCY_INGRESS", "NOT_FOUND", "METHOD_NOT_ALLOWED", "LIMIT_REACHED", "CANCELLED", "INTERNAL_ERROR", "UNAVAILABLE", "RESIDENCY_UNAVAILABLE"],
+    lookup: ["INVALID_INPUT", "UNAUTHORIZED", "RESIDENCY_INGRESS", "NOT_FOUND", "METHOD_NOT_ALLOWED", "LIMIT_REACHED", "FAIR_USE_CEILING", "CANCELLED", "INTERNAL_ERROR", "UNAVAILABLE", "RESIDENCY_UNAVAILABLE"],
+    search: ["INVALID_INPUT", "UNAUTHORIZED", "RESIDENCY_INGRESS", "NOT_FOUND", "METHOD_NOT_ALLOWED", "LIMIT_REACHED", "FAIR_USE_CEILING", "CANCELLED", "INTERNAL_ERROR", "UNAVAILABLE", "RESIDENCY_UNAVAILABLE"],
 };

package/dist/local/profile.d.ts

@@ -0,0 +1,11 @@
+import type { CompanyClient } from "../generated/client.js";
+import type { LookupResponse } from "../generated/types.js";
+import type { FieldProfile } from "../runtime/field-types.js";
+/** One company record of the ASIC register snapshot. */
+export type ProductRecord = LookupResponse["records"][number];
+export declare const ATTRIBUTION = "Company data: Australian Securities and Investments Commission, via data.gov.au (CC BY 3.0 AU).";
+/** "001234567" as "001 234 567"; anything else is shown as it is. */
+export declare const formatAcn: (acn: string) => string;
+/** One line for a found company: name, ACN and status. The full record is in `onSelect`. */
+export declare const describeCompany: (record: ProductRecord) => string;
+export declare const profile: FieldProfile<CompanyClient, ProductRecord>;

package/dist/local/profile.js

@@ -0,0 +1,94 @@
+// The Company field's profile: the only company-specific code of the field. It reads the typed
+// text (a nine-digit ACN is looked up, anything else is searched by name), calls the client, and
+// reduces every reply to the text the UIs show and the record the consumer receives. The
+// controller, the React package and the web element are generated and know nothing else.
+import { isCommsIdError } from "../runtime/errors.js";
+export const ATTRIBUTION = "Company data: Australian Securities and Investments Commission, via data.gov.au (CC BY 3.0 AU).";
+const ACN_DIGITS = 9;
+/** The contract allows ten rows at most. */
+const MAX_LIMIT = 10;
+const NUMBER_TEXT = /^[\d\s-]+$/;
+const SEPARATORS = /[\s-]/g;
+/** "001234567" as "001 234 567"; anything else is shown as it is. */
+export const formatAcn = (acn) => acn.length === ACN_DIGITS ? `${acn.slice(0, 3)} ${acn.slice(3, 6)} ${acn.slice(6)}` : acn;
+const nameOf = (record) => record.name ?? record.currentName ?? "Unnamed company";
+const compact = (parts) => parts.filter((part) => part !== null && part !== undefined && part !== "");
+/** One line for a found company: name, ACN and status. The full record is in `onSelect`. */
+export const describeCompany = (record) => compact([nameOf(record), record.acn === null ? undefined : `ACN ${formatAcn(record.acn)}`, record.status]).join(" · ");
+const foundOf = (reply, record) => ({
+    record,
+    summary: describeCompany(record),
+    asAt: reply.activatedAt ?? reply.source.observedAt,
+    attribution: reply.attribution,
+});
+/** The service answers an unknown name or ACN with NOT_FOUND: that is "no match", not a failure. */
+const orNothing = async (call) => {
+    try {
+        return await call;
+    }
+    catch (cause) {
+        if (isCommsIdError(cause) && cause.code === "NOT_FOUND") {
+            return;
+        }
+        throw cause;
+    }
+};
+export const profile = {
+    attribution: ATTRIBUTION,
+    label: "Company name or ACN",
+    listLabel: "Company suggestions",
+    noun: "company",
+    notFound: "No company found.",
+    service: "Company search",
+    settings: ["status"],
+    working: "Looking up the company",
+    read: (text, context) => {
+        const trimmed = text.trim();
+        if (NUMBER_TEXT.test(trimmed)) {
+            const acn = trimmed.replace(SEPARATORS, "");
+            if (acn.length < ACN_DIGITS) {
+                return { kind: "incomplete" };
+            }
+            if (acn.length > ACN_DIGITS) {
+                return { kind: "invalid", reason: "LENGTH", message: "An ACN has 9 digits." };
+            }
+            return {
+                kind: "lookup",
+                run: async (client, options) => {
+                    const reply = await orNothing(client.lookup({ acn }, options));
+                    const record = reply?.records[0];
+                    return {
+                        found: reply === undefined || record === undefined ? undefined : foundOf(reply, record),
+                        attribution: reply?.attribution,
+                    };
+                },
+            };
+        }
+        if (trimmed.length < context.minChars) {
+            return { kind: "incomplete" };
+        }
+        const status = context.settings.status;
+        return {
+            kind: "search",
+            run: async (client, options) => {
+                const request = {
+                    namePrefix: trimmed,
+                    limit: Math.min(context.limit, MAX_LIMIT),
+                    ...(status === undefined ? {} : { status }),
+                };
+                const reply = await orNothing(client.search(request, options));
+                if (reply === undefined) {
+                    return { suggestions: [], attribution: undefined };
+                }
+                const suggestions = reply.records.map((record, index) => ({
+                    key: `${record.acn ?? "none"}-${index}`,
+                    primary: nameOf(record),
+                    secondary: compact([record.acn === null ? undefined : `ACN ${formatAcn(record.acn)}`, record.status]).join(" · "),
+                    // The search already returned the whole record: choosing it needs no second call.
+                    choose: { kind: "found", found: foundOf(reply, record) },
+                }));
+                return { suggestions, attribution: reply.attribution };
+            },
+        };
+    },
+};

package/dist/runtime/field-aria.d.ts

@@ -0,0 +1,19 @@
+import type { FieldController, FieldState } from "./field-types.js";
+export interface FieldIds {
+    readonly input: string;
+    readonly listbox: string;
+    readonly status: string;
+}
+/** Attribute name to value; an undefined value means the attribute is left off. */
+export type Attributes = Readonly<Record<string, string | undefined>>;
+export declare const optionId: (ids: FieldIds, index: number) => string;
+export declare const inputAttributes: (state: FieldState<unknown>, ids: FieldIds) => Attributes;
+export declare const listboxAttributes: (ids: FieldIds, label: string) => Attributes;
+export declare const optionAttributes: (state: FieldState<unknown>, ids: FieldIds, index: number) => Attributes;
+/** The polite live region that says what just happened. */
+export declare const statusAttributes: (ids: FieldIds) => Attributes;
+/**
+ * Handles one key press in the input. Returns true when the key was used, so the caller prevents
+ * its default action: Enter in an open list must pick the option, not submit the form.
+ */
+export declare const handleKey: (controller: FieldController<unknown>, key: string) => boolean;

package/dist/runtime/field-aria.js

@@ -0,0 +1,72 @@
+// Runtime template: copied into a generated client package as src/runtime/field-aria.ts.
+// The accessibility contract of the field, as plain attributes and one key handler. It follows
+// the WAI-ARIA Authoring Practices combobox with a listbox popup (list autocomplete, focus stays
+// in the input, the highlighted option is named by aria-activedescendant). The React package and
+// the web element render these attributes and call the handler unchanged.
+export const optionId = (ids, index) => `${ids.listbox}-option-${index}`;
+export const inputAttributes = (state, ids) => ({
+    id: ids.input,
+    role: "combobox",
+    type: "text",
+    autocomplete: "off",
+    autocapitalize: "off",
+    spellcheck: "false",
+    "aria-autocomplete": "list",
+    "aria-haspopup": "listbox",
+    "aria-expanded": state.open ? "true" : "false",
+    "aria-controls": ids.listbox,
+    "aria-activedescendant": state.open && state.activeIndex >= 0 ? optionId(ids, state.activeIndex) : undefined,
+    "aria-describedby": ids.status,
+    "aria-busy": state.status === "loading" || state.status === "resolving" ? "true" : undefined,
+    "aria-invalid": state.status === "error" || state.status === "invalid" ? "true" : undefined,
+});
+export const listboxAttributes = (ids, label) => ({
+    id: ids.listbox,
+    role: "listbox",
+    "aria-label": label,
+});
+export const optionAttributes = (state, ids, index) => ({
+    id: optionId(ids, index),
+    role: "option",
+    "aria-selected": index === state.activeIndex ? "true" : "false",
+});
+/** The polite live region that says what just happened. */
+export const statusAttributes = (ids) => ({
+    id: ids.status,
+    role: "status",
+    "aria-live": "polite",
+    "aria-atomic": "true",
+});
+/**
+ * Handles one key press in the input. Returns true when the key was used, so the caller prevents
+ * its default action: Enter in an open list must pick the option, not submit the form.
+ */
+export const handleKey = (controller, key) => {
+    const state = controller.getState();
+    switch (key) {
+        case "ArrowDown":
+        case "ArrowUp":
+            if (state.suggestions.length === 0) {
+                return false;
+            }
+            controller.moveActive(key === "ArrowDown" ? 1 : -1);
+            return true;
+        case "Enter":
+            if (state.open && state.activeIndex >= 0) {
+                controller.select();
+                return true;
+            }
+            return false;
+        case "Escape":
+            if (state.open) {
+                controller.close();
+                return true;
+            }
+            return false;
+        case "Tab":
+            controller.close();
+            return false;
+        default:
+            return false;
+    }
+};

package/dist/runtime/field-controller.d.ts

@@ -0,0 +1,8 @@
+import type { FieldController, FieldControllerOptions, FieldState } from "./field-types.js";
+export declare const DEFAULT_MIN_CHARS = 3;
+export declare const DEFAULT_DEBOUNCE_MS = 200;
+export declare const DEFAULT_LIMIT = 8;
+/** The state of a controller that has not been used. */
+export declare const idleState: <R>(attribution: string) => FieldState<R>;
+/** Creates the controller. Nothing is called until the first `setQuery`. */
+export declare const createFieldController: <C, R>(options: FieldControllerOptions<C, R>) => FieldController<R>;

package/dist/runtime/field-controller.js

@@ -0,0 +1,324 @@
+// Runtime template: copied into a generated client package as src/runtime/field-controller.ts.
+// The headless controller of a field: input, debounce, suggestions, choice, identifier checks and
+// errors, with no framework and no markup. The React package and the web element both run on it.
+//
+// The product-specific part is the profile (src/local/profile.ts): it reads the typed text and
+// says whether to search, look up, wait or refuse. A search shows suggestions, and a chosen
+// suggestion is either used as it is (the search already returned the record) or looked up.
+import { isCommsIdError, outcomeOf } from "./errors.js";
+export const DEFAULT_MIN_CHARS = 3;
+export const DEFAULT_DEBOUNCE_MS = 200;
+export const DEFAULT_LIMIT = 8;
+const NO_SETTINGS = {};
+/** The state of a controller that has not been used. */
+export const idleState = (attribution) => ({
+    query: "",
+    status: "idle",
+    suggestions: [],
+    activeIndex: -1,
+    open: false,
+    error: undefined,
+    invalid: undefined,
+    resolved: undefined,
+    announcement: "",
+    attribution,
+});
+const plural = (count, noun) => `${count} ${noun}${count === 1 ? "" : "s"}`;
+const errorMessage = (service, code, outcome) => {
+    if (code === "FAIR_USE_CEILING") {
+        return `The ${service.toLowerCase()} limit is reached. Try again later.`;
+    }
+    if (outcome === "source-unavailable") {
+        return `${service} is unavailable. Try again later.`;
+    }
+    return `${service} failed. Try again.`;
+};
+const toError = (service, cause) => {
+    const outcome = outcomeOf(cause);
+    const base = isCommsIdError(cause)
+        ? { code: cause.code, detail: cause.message, outcome, retryable: cause.retryable, requestId: cause.requestId }
+        : {
+            code: "UNKNOWN",
+            detail: cause instanceof Error ? cause.message : String(cause),
+            outcome,
+            retryable: false,
+            requestId: undefined,
+        };
+    return { ...base, message: errorMessage(service, base.code, outcome) };
+};
+/** Starts a task whose own try/catch handles every failure; nothing is left unhandled. */
+const run = (task) => {
+    task.catch(() => undefined);
+};
+const isOurAbort = (cause) => isCommsIdError(cause) && cause.code === "ABORTED";
+/** Creates the controller. Nothing is called until the first `setQuery`. */
+export const createFieldController = (options) => {
+    const { client, profile } = options;
+    const minChars = options.minChars ?? DEFAULT_MIN_CHARS;
+    const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    const settings = options.settings ?? NO_SETTINGS;
+    const now = options.now ?? (() => performance.now());
+    let state = idleState(profile.attribution);
+    let entries = [];
+    const listeners = new Set();
+    let sequence = 0;
+    let timer;
+    let inFlight;
+    let retryAction;
+    let disposed = false;
+    const notify = () => {
+        for (const listener of [...listeners]) {
+            listener();
+        }
+    };
+    const set = (patch) => {
+        state = { ...state, ...patch };
+        notify();
+    };
+    /** Starts a new generation: anything still waiting or in flight becomes stale. */
+    const supersede = () => {
+        sequence += 1;
+        clearTimeout(timer);
+        timer = undefined;
+        inFlight?.abort();
+        inFlight = undefined;
+        return sequence;
+    };
+    const fail = (cause) => {
+        const error = toError(profile.service, cause);
+        entries = [];
+        set({ status: "error", suggestions: [], activeIndex: -1, open: false, error, announcement: error.message });
+    };
+    const search = async (generation, reading) => {
+        const controller = new AbortController();
+        inFlight = controller;
+        retryAction = () => {
+            const next = supersede();
+            set({ status: "loading", error: undefined });
+            run(search(next, reading));
+        };
+        try {
+            const reply = await reading.run(client, { signal: controller.signal });
+            if (generation !== sequence || disposed) {
+                return;
+            }
+            entries = reply.suggestions;
+            const found = entries.length > 0;
+            set({
+                status: found ? "results" : "empty",
+                suggestions: entries.map(({ key, primary, secondary }) => ({ key, primary, secondary })),
+                activeIndex: -1,
+                open: found,
+                error: undefined,
+                attribution: reply.attribution ?? profile.attribution,
+                announcement: found ? `${plural(entries.length, `${profile.noun} suggestion`)} available.` : profile.notFound,
+            });
+        }
+        catch (cause) {
+            if (generation !== sequence || disposed || isOurAbort(cause)) {
+                return;
+            }
+            fail(cause);
+        }
+    };
+    const finish = (found, started) => {
+        const timing = { ms: Math.round(now() - started) };
+        set({
+            status: "resolved",
+            open: false,
+            activeIndex: -1,
+            error: undefined,
+            invalid: undefined,
+            resolved: { found, timing },
+            attribution: found.attribution ?? profile.attribution,
+            announcement: `Found ${found.summary}.`,
+        });
+        try {
+            options.onSelect?.(found.record, timing);
+        }
+        catch (thrown) {
+            // The consumer's callback must not corrupt the state; surface its error to the page.
+            queueMicrotask(() => {
+                throw thrown;
+            });
+        }
+    };
+    const lookup = async (generation, call) => {
+        const controller = new AbortController();
+        inFlight = controller;
+        retryAction = () => {
+            const next = supersede();
+            set({ status: "resolving", error: undefined });
+            run(lookup(next, call));
+        };
+        const started = now();
+        let reply;
+        try {
+            reply = await call(client, { signal: controller.signal });
+        }
+        catch (cause) {
+            if (generation !== sequence || disposed || isOurAbort(cause)) {
+                return;
+            }
+            fail(cause);
+            return;
+        }
+        if (generation !== sequence || disposed) {
+            return;
+        }
+        if (reply.found === undefined) {
+            entries = [];
+            set({
+                status: "empty",
+                suggestions: [],
+                activeIndex: -1,
+                open: false,
+                error: undefined,
+                attribution: reply.attribution ?? profile.attribution,
+                announcement: profile.notFound,
+            });
+            return;
+        }
+        finish(reply.found, started);
+    };
+    const setQuery = (text) => {
+        if (disposed || text === state.query) {
+            return;
+        }
+        const generation = supersede();
+        const reading = profile.read(text, { limit, minChars, settings });
+        if (reading.kind === "incomplete") {
+            entries = [];
+            state = { ...idleState(profile.attribution), query: text, attribution: state.attribution };
+            notify();
+            return;
+        }
+        if (reading.kind !== "search") {
+            entries = [];
+        }
+        set({
+            query: text,
+            status: "loading",
+            error: undefined,
+            invalid: undefined,
+            resolved: undefined,
+            announcement: "",
+            ...(reading.kind === "search" ? {} : { suggestions: [], activeIndex: -1, open: false }),
+        });
+        timer = setTimeout(() => {
+            timer = undefined;
+            if (reading.kind === "invalid") {
+                set({
+                    status: "invalid",
+                    invalid: { reason: reading.reason, message: reading.message },
+                    announcement: reading.message,
+                });
+            }
+            else if (reading.kind === "lookup") {
+                set({ status: "resolving", announcement: `${profile.working}.` });
+                run(lookup(generation, reading.run));
+            }
+            else {
+                run(search(generation, reading));
+            }
+        }, debounceMs);
+    };
+    const setActive = (index) => {
+        if (disposed || !state.open || index < -1 || index >= state.suggestions.length || index === state.activeIndex) {
+            return;
+        }
+        set({ activeIndex: index });
+    };
+    const moveActive = (delta) => {
+        const count = state.suggestions.length;
+        if (disposed || count === 0 || delta === 0) {
+            return;
+        }
+        if (!state.open) {
+            set({ open: true, activeIndex: delta > 0 ? 0 : count - 1 });
+            return;
+        }
+        const from = state.activeIndex;
+        let next = from + delta;
+        if (from === -1) {
+            next = delta > 0 ? 0 : count - 1;
+        }
+        else if (next >= count) {
+            next = 0;
+        }
+        else if (next < 0) {
+            next = count - 1;
+        }
+        set({ activeIndex: next });
+    };
+    const choose = (chosen, generation, text) => {
+        if (chosen.kind === "found") {
+            entries = [];
+            set({ query: text, suggestions: [], open: false, activeIndex: -1 });
+            finish(chosen.found, now());
+            return;
+        }
+        set({
+            query: text,
+            status: "resolving",
+            open: false,
+            activeIndex: -1,
+            error: undefined,
+            invalid: undefined,
+            announcement: `${profile.working}.`,
+        });
+        run(lookup(generation, chosen.run));
+    };
+    const select = (index) => {
+        if (disposed) {
+            return;
+        }
+        const chosen = entries[index ?? state.activeIndex];
+        if (chosen === undefined) {
+            return;
+        }
+        const generation = supersede();
+        choose(chosen.choose, generation, chosen.primary);
+    };
+    const close = () => {
+        if (disposed || (!state.open && state.activeIndex === -1)) {
+            return;
+        }
+        set({ open: false, activeIndex: -1 });
+    };
+    const open = () => {
+        if (disposed || state.open || state.suggestions.length === 0) {
+            return;
+        }
+        set({ open: true });
+    };
+    const retry = () => {
+        if (disposed || state.status !== "error") {
+            return;
+        }
+        retryAction?.();
+    };
+    const dispose = () => {
+        disposed = true;
+        supersede();
+        listeners.clear();
+    };
+    return {
+        getState: () => state,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        setQuery,
+        moveActive,
+        setActive,
+        select,
+        close,
+        open,
+        retry,
+        dispose,
+    };
+};

package/dist/runtime/field-types.d.ts

@@ -0,0 +1,180 @@
+import type { Outcome } from "./errors.js";
+import type { CallOptions } from "./http.js";
+/** A call the profile prepared: it runs against the client when the typing has paused. */
+export type Run<C, T> = (client: C, options: CallOptions) => Promise<T>;
+/** One thing the service found, reduced to the text every UI shows and the record the consumer receives. */
+export interface Found<R> {
+    /** The date or time of the data, when the reply says. */
+    readonly asAt: string | undefined;
+    /** The attribution this reply asks for, when it carries one. */
+    readonly attribution: string | undefined;
+    readonly record: R;
+    /** One line: what was found. */
+    readonly summary: string;
+}
+/** What choosing a suggestion does: use the record the search already returned, or look it up. */
+export type Chosen<C, R> = {
+    readonly kind: "found";
+    readonly found: Found<R>;
+} | {
+    readonly kind: "lookup";
+    readonly run: Run<C, Looked<R>>;
+};
+export interface Suggestion<C, R> {
+    readonly choose: Chosen<C, R>;
+    /** Unique in one list. */
+    readonly key: string;
+    readonly primary: string;
+    readonly secondary: string;
+}
+export interface Searched<C, R> {
+    readonly attribution: string | undefined;
+    readonly suggestions: readonly Suggestion<C, R>[];
+}
+export interface Looked<R> {
+    readonly attribution: string | undefined;
+    /** Undefined means the service answered and has no such record. */
+    readonly found: Found<R> | undefined;
+}
+/** What the profile makes of the typed text. */
+export type Reading<C, R> = 
+/** Too little typed to ask. */
+{
+    readonly kind: "incomplete";
+}
+/** A whole identifier was typed and it is not valid. Nothing is sent. */
+ | {
+    readonly kind: "invalid";
+    readonly message: string;
+    readonly reason: string;
+} | {
+    readonly kind: "search";
+    readonly run: Run<C, Searched<C, R>>;
+} | {
+    readonly kind: "lookup";
+    readonly run: Run<C, Looked<R>>;
+};
+export interface ReadContext {
+    /** Suggestions asked for. */
+    readonly limit: number;
+    /** Typed characters needed before a name search starts. */
+    readonly minChars: number;
+    /** Product settings the page gave (an attribute of the element, a prop of the component). */
+    readonly settings: Readonly<Record<string, string | undefined>>;
+}
+/** The only product-specific part of a field: written by hand in the package (src/local/profile.ts). */
+export interface FieldProfile<C, R> {
+    /** The standard attribution, shown until a reply carries its own. */
+    readonly attribution: string;
+    /** The default visible label of the field. */
+    readonly label: string;
+    /** The accessible name of the list of suggestions. */
+    readonly listLabel: string;
+    /** What a reply that has no record says: "No company found." */
+    readonly notFound: string;
+    /** Singular, lower case: "company". Used in "3 company suggestions available." */
+    readonly noun: string;
+    readonly read: (text: string, context: ReadContext) => Reading<C, R>;
+    /** The service in a failure message: "Company search" gives "Company search is unavailable." */
+    readonly service: string;
+    /** Names of the settings the profile reads. The element observes them as attributes. */
+    readonly settings: readonly string[];
+    /** One word for the lookup in announcements: "Looking up the company." */
+    readonly working: string;
+}
+export type FieldStatus = 
+/** Nothing typed, or too little to ask. */
+"idle"
+/** Waiting for the typing to pause, or for a search. */
+ | "loading"
+/** Suggestions are available. */
+ | "results"
+/** The service answered and found nothing. */
+ | "empty"
+/** A suggestion was chosen, or a whole identifier was typed, and the lookup is running. */
+ | "resolving"
+/** A record was found. */
+ | "resolved"
+/** A whole identifier was typed and it is not valid. Nothing was sent. */
+ | "invalid"
+/** The call failed; `error` says how. */
+ | "error";
+export interface FieldError {
+    readonly code: string;
+    /** What the technical error said, for a developer: never shown to the end user. */
+    readonly detail: string;
+    readonly message: string;
+    /** A lookup that failed is never shown as "no match". */
+    readonly outcome: Outcome;
+    readonly requestId: string | undefined;
+    readonly retryable: boolean;
+}
+export interface FieldTiming {
+    /** Milliseconds the lookup took, measured in the browser. */
+    readonly ms: number;
+}
+/** A suggestion as the UI shows it. */
+export interface SuggestionView {
+    readonly key: string;
+    readonly primary: string;
+    readonly secondary: string;
+}
+export interface FieldState<R> {
+    /** Index of the highlighted suggestion, or -1. */
+    readonly activeIndex: number;
+    /** One sentence for assistive technology: what just happened. Empty when nothing needs saying. */
+    readonly announcement: string;
+    /** The attribution to show now: the one the last reply carried, or the standard one. */
+    readonly attribution: string;
+    readonly error: FieldError | undefined;
+    /** Set with the status "invalid": why the typed identifier is not valid. */
+    readonly invalid: {
+        readonly message: string;
+        readonly reason: string;
+    } | undefined;
+    /** Whether the list of suggestions is shown. */
+    readonly open: boolean;
+    readonly query: string;
+    readonly resolved: {
+        readonly found: Found<R>;
+        readonly timing: FieldTiming;
+    } | undefined;
+    readonly status: FieldStatus;
+    readonly suggestions: readonly SuggestionView[];
+}
+export interface FieldControllerOptions<C, R> {
+    /** Any client of the product's API: server, browser (relay) or fixtures. */
+    readonly client: C;
+    /** Pause after typing before a call starts, in milliseconds. 200 by default. */
+    readonly debounceMs?: number;
+    /** Suggestions asked for. 8 by default. */
+    readonly limit?: number;
+    /** Typed characters needed before a name search starts. 3 by default. */
+    readonly minChars?: number;
+    /** Milliseconds, for timing. performance.now by default. */
+    readonly now?: () => number;
+    /** Called once when a record has been found, after the state is updated. */
+    readonly onSelect?: (record: R, timing: FieldTiming) => void;
+    readonly profile: FieldProfile<C, R>;
+    /** Product settings (see `profile.settings`). */
+    readonly settings?: Readonly<Record<string, string | undefined>>;
+}
+export interface FieldController<R> {
+    close: () => void;
+    /** Stops every timer and call. The controller does nothing afterwards. */
+    dispose: () => void;
+    /** The current state. The same object until the state changes. */
+    getState: () => FieldState<R>;
+    /** Moves the highlight by `delta`, wrapping; opens the list first when it is closed. */
+    moveActive: (delta: number) => void;
+    open: () => void;
+    /** Runs again whatever failed last. */
+    retry: () => void;
+    /** Chooses the suggestion at `index`, or the highlighted one. */
+    select: (index?: number) => void;
+    setActive: (index: number) => void;
+    /** Text typed. */
+    setQuery: (text: string) => void;
+    /** Calls the listener after every change. Returns the function that stops it. */
+    subscribe: (listener: () => void) => () => void;
+}

package/dist/runtime/field-types.js

@@ -0,0 +1,4 @@
+// Runtime template: copied into a generated client package as src/runtime/field-types.ts, with
+// field-controller.ts and field-aria.ts, when the product has a field UI (generate.config.json,
+// "ui"). The types of the headless field controller and of the per-product profile.
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comms-id/company",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Typed client for the Comms.ID Company API: Australian companies from ASIC's public registers: search by name, look up one by ACN",
   "type": "module",
   "sideEffects": false,
@@ -19,6 +19,10 @@
       "types": "./dist/browser.d.ts",
       "default": "./dist/browser.js"
     },
+    "./controller": {
+      "types": "./dist/controller.d.ts",
+      "default": "./dist/controller.js"
+    },
     "./fixtures": {
       "types": "./dist/fixtures.d.ts",
       "default": "./dist/fixtures.js"