@reqquest/ui 1.10.0 → 1.12.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export type * from './api.js';
 export * from './components/index.js';
+export * from './keys.js';
 export * from './registry.js';
 export * from './types.js';
 export * from './typed-client/index.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './components/index.js';
+export * from './keys.js';
 export * from './registry.js';
 export * from './types.js';
 export * from './typed-client/index.js';

package/dist/keys.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Downstream projects augment this interface to teach the UI which keys their API registers. Once
+ * augmented, `UIConfig` rejects a component registered under an unknown key, and requires one for
+ * every prompt the API defines.
+ *
+ * This is a separate interface from the one in '@reqquest/api' by necessity: `@reqquest/ui` cannot
+ * depend on the API package without pulling fastify, mysql2 and type-graphql into a browser build.
+ * The generated declaration is plain string literals with no dependencies, so the same analyzer can
+ * emit one file augmenting each package:
+ *
+ * ```
+ * node node_modules/@reqquest/api/dist/analysis/cli.js <api-project> \
+ *   --emit-keys src/keys.generated.d.ts --module '@reqquest/ui'
+ * ```
+ *
+ * ```ts
+ * // src/keys.generated.d.ts - GENERATED, commit it
+ * export {}
+ * declare module '@reqquest/ui' {
+ *   interface ReqQuestKeys {
+ *     prompts: 'state_residence_prompt' | 'ssn_value_prompt'
+ *     requirements: 'state_residence_req'
+ *     programs: 'adopt_a_pet_program'
+ *   }
+ * }
+ * ```
+ *
+ * The `export {}` is load-bearing - without a top-level import or export the file is a global script
+ * and `declare module` REPLACES '@reqquest/ui' rather than augmenting it - and the file has to fall
+ * inside your tsconfig `include`, or it augments nothing and keys silently stay `string`.
+ *
+ * Regenerate when definitions change and gate it with `--check-keys`; a stale declaration offers keys
+ * the API no longer has.
+ *
+ * Leaving a slot unaugmented degrades its key type to `string`, so augmenting is entirely optional.
+ */
+export interface ReqQuestKeys {
+}
+type Slot<S extends keyof any> = ReqQuestKeys extends Record<S, infer T> ? T : never;
+type SlotUnion<S extends keyof any> = [Slot<S>] extends [never] ? string : Extract<Slot<S>, string>;
+/** Every prompt key in this application, or `string` when the `prompts` slot is not augmented. */
+export type PromptKey = SlotUnion<'prompts'>;
+/** Every requirement key in this application, or `string` when the `requirements` slot is not augmented. */
+export type RequirementKey = SlotUnion<'requirements'>;
+/** Every program key in this application, or `string` when the `programs` slot is not augmented. */
+export type ProgramKey = SlotUnion<'programs'>;
+export {};

package/dist/keys.js

@@ -0,0 +1 @@
+export {};

package/dist/registry.d.ts

@@ -1,5 +1,6 @@
 import type { LayoutStructureNode, LayoutStructureNodeRoot, UserProfile } from '@txstate-mws/carbon-svelte';
 import type { Component } from 'svelte';
+import type { ProgramKey, PromptKey, RequirementKey } from './keys.js';
 export interface PromptLoader {
     skeletonComponent: Component<any>;
     /**
@@ -11,10 +12,10 @@ export interface PromptLoader {
 export type Loader = PromptLoader | boolean;
 export interface ProgramDefinition {
     /**
-     * The key for the program. Allows us to match up API programs with
-     * the appropriate definition.
+     * The key of the program this decorates. Autocompletes and rejects unknown keys once the project
+     * generates a key declaration; plain `string` until then.
      */
-    key: string;
+    key: ProgramKey;
     /**
      * An icon to represent this program in the navigation.
      */
@@ -22,10 +23,10 @@ export interface ProgramDefinition {
 }
 export interface RequirementDefinition {
     /**
-     * The key for the requirement. Allows us to match up API requirements with
-     * the appropriate definition.
+     * The key of the requirement this decorates. Autocompletes and rejects unknown keys once the
+     * project generates a key declaration; plain `string` until then.
      */
-    key: string;
+    key: RequirementKey;
     /**
      * An icon to represent this requirement in the navigation. Requirements do not appear
      * in the navigation in the applicant's view.
@@ -41,7 +42,11 @@ export interface RequirementDefinition {
     configureDisplayComponent?: Component;
 }
 export interface PromptDefinition {
-    key: string;
+    /**
+     * The key of the prompt this renders. Autocompletes and rejects unknown keys once the project
+     * generates a key declaration; plain `string` until then.
+     */
+    key: PromptKey;
     /**
      * The component that will be used to render the form for this prompt.
      *
@@ -160,11 +165,37 @@ export interface Terminologies {
 /**
  * A type for the config object that should be exported from a CMS instance's admin/local/index.js
  * to configure how that instance should work.
+ *
+ * Each of the three definition lists accepts either an array or a keyed object. **Prefer the keyed
+ * object.** An array can only reject a key the API does not have; it can never require the keys the
+ * API *does* have, so a prompt added on the API side and forgotten here compiles cleanly and fails
+ * in front of an applicant. The keyed form turns that into a build error, and also rejects
+ * duplicate keys, which an array silently resolves last-wins.
+ *
+ * `prompts` is the only list whose coverage is *required*, because it is the only one that is load
+ * bearing: a `PromptDefinition` supplies the component that renders the screen. `requirements` and
+ * `programs` carry optional decoration - an icon, a configuration component - and leaving one out
+ * is a supported choice, so their keyed form is partial. Both still reject unknown keys.
+ *
+ * This degrades on its own: `PromptKey` is `string` until a project generates a key declaration
+ * (see keys.ts), and `{ [K in string]: ... }` requires nothing - so an unaugmented project keeps
+ * working exactly as before.
+ *
+ * The type parameters exist for repos holding several applications, where the generated union spans
+ * all of them and no single config could satisfy it. Generate per-application aliases with the
+ * analyzer's `--groups` flag and instantiate against one, e.g.
+ * `UIConfig<SimplePromptKey, SimpleRequirementKey, SimpleProgramKey>`.
  */
-export interface UIConfig {
-    programs: ProgramDefinition[];
-    requirements: RequirementDefinition[];
-    prompts: PromptDefinition[];
+export interface UIConfig<PK extends string = PromptKey, RK extends string = RequirementKey, GK extends string = ProgramKey> {
+    programs: ProgramDefinition[] | {
+        [K in GK]?: Omit<ProgramDefinition, 'key'>;
+    };
+    requirements: RequirementDefinition[] | {
+        [K in RK]?: Omit<RequirementDefinition, 'key'>;
+    };
+    prompts: PromptDefinition[] | {
+        [K in PK]: Omit<PromptDefinition, 'key'>;
+    };
     /**
      *
      * @param login
@@ -273,18 +304,58 @@ export interface UIConfigWithDefaults extends UIConfig {
     terminology: Required<Terminologies>;
     plural: Required<Terminologies>;
 }
+/**
+ * Any `UIConfig`, whichever key unions it was written against. `UIRegistry` accepts this rather
+ * than `UIConfig` itself: a `UIConfig<SimplePromptKey>` is not assignable to `UIConfig<PromptKey>`
+ * when the unions differ, and TypeScript does not allow a generic constructor to bridge them.
+ *
+ * Nothing is lost by widening here. Exhaustiveness is enforced where the config literal is written
+ * (`const config: UIConfig<SimplePromptKey, ...> = { ... }`), which is the only place that knows
+ * which application it belongs to.
+ */
+export type AnyUIConfig = Omit<UIConfig, 'programs' | 'requirements' | 'prompts'> & {
+    programs: ProgramDefinition[] | Record<string, Omit<ProgramDefinition, 'key'> | undefined>;
+    requirements: RequirementDefinition[] | Record<string, Omit<RequirementDefinition, 'key'> | undefined>;
+    prompts: PromptDefinition[] | Record<string, Omit<PromptDefinition, 'key'>>;
+};
 export declare class UIRegistry {
-    config: UIConfig;
     protected promptMap: Record<string, PromptDefinition>;
     protected requirementMap: Record<string, RequirementDefinition>;
     protected programMap: Record<string, ProgramDefinition>;
     protected userLookup?: (login: string) => Promise<UserProfile | undefined>;
     protected lang: Required<Terminologies>;
     protected plural: Required<Terminologies>;
-    constructor(config: UIConfig);
+    /**
+     * Widened to `AnyUIConfig` rather than `UIConfig`: a narrow `UIConfig<SimplePromptKey>` is not
+     * assignable to `UIConfig<PromptKey>` when the unions differ. Keeping the three definition lists
+     * on the type (instead of `Omit`ing them away) matters for consumers that read
+     * `uiRegistry.config.prompts` - dropping them would be a breaking change.
+     */
+    config: AnyUIConfig;
+    constructor(config: AnyUIConfig);
     getWord(key: keyof Terminologies, count?: number, inclusive?: boolean): string;
     getPlural(key: keyof Terminologies): string;
     getPrompt(key: string): PromptDefinition | undefined;
     getRequirement(key: string): RequirementDefinition | undefined;
     getProgram(key: string): ProgramDefinition | undefined;
+    /**
+     * `UIConfig` keeps this UI in step with the API it was built against.
+     *  Keys arrive here from the API at runtime, so these stay `string` rather than the key unions.
+     */
+    protected warnedMissing: Set<string>;
+    /**
+     * This is the ONLY runtime signal that the UI is missing a definition, so it is deliberately NOT
+     * gated on a dev-only build flag. Coverage is enforced at build time (see UIConfig's keyed form),
+     * but that gate lives in this repo's tooling and does not ship to downstream projects - a project
+     * that never wires its own type check has nothing but this line. Staying silent in production is
+     * how a missing prompt turns into an unexplained blank spot on an applicant's form.
+     * The `warnedMissing` set keeps it to one line per key, so a list of 200 prompts cannot spam.
+     *
+     * Severity splits by kind because the kinds are not equally load-bearing. A `PromptDefinition`
+     * supplies the component that actually renders the screen, so a missing one breaks a page.
+     * `RequirementDefinition` and `ProgramDefinition` carry only optional decoration - an icon, a
+     * configuration component - and every consumer optional-chains them. Leaving one unregistered is
+     * a supported choice, so it warns rather than errors.
+     */
+    protected warnIfMissing<T>(kind: string, key: string, definition: T | undefined): T | undefined;
 }

package/dist/registry.js

@@ -1,23 +1,46 @@
 import { plural } from 'txstate-utils';
+/**
+ * Accepts either shape of a definition list and returns a key -> definition map. The keyed form
+ * carries its key in the object key, so it is grafted back on to keep every consumer's
+ * `definition.key` working.
+ */
+function toDefinitionMap(definitions) {
+    const map = {};
+    if (Array.isArray(definitions)) {
+        for (const definition of definitions)
+            map[definition.key] = definition;
+    }
+    else {
+        // an explicit `undefined` value is a hole in a partial record, not a registration
+        for (const [key, definition] of Object.entries(definitions)) {
+            if (definition != null)
+                map[key] = { ...definition, key };
+        }
+    }
+    return map;
+}
 export class UIRegistry {
-    config;
     promptMap = {};
     requirementMap = {};
     programMap = {};
     userLookup;
     lang;
     plural;
+    /**
+     * Widened to `AnyUIConfig` rather than `UIConfig`: a narrow `UIConfig<SimplePromptKey>` is not
+     * assignable to `UIConfig<PromptKey>` when the unions differ. Keeping the three definition lists
+     * on the type (instead of `Omit`ing them away) matters for consumers that read
+     * `uiRegistry.config.prompts` - dropping them would be a breaking change.
+     */
+    config;
     constructor(config) {
         this.config = config;
-        for (const prompt of config.prompts)
-            this.promptMap[prompt.key] = prompt;
-        for (const requirement of config.requirements)
-            this.requirementMap[requirement.key] = requirement;
-        for (const program of config.programs)
-            this.programMap[program.key] = program;
+        this.promptMap = toDefinitionMap(config.prompts);
+        this.requirementMap = toDefinitionMap(config.requirements);
+        this.programMap = toDefinitionMap(config.programs);
         this.userLookup = config.userLookup;
         this.lang = {
-            appRequest: config.terminology?.appRequest ?? (config.programs.length > 1 ? 'App Request' : 'Application'),
+            appRequest: config.terminology?.appRequest ?? (Object.keys(this.programMap).length > 1 ? 'App Request' : 'Application'),
             login: config.terminology?.login ?? 'Login',
             period: config.terminology?.period ?? 'Period'
         };
@@ -33,12 +56,39 @@ export class UIRegistry {
         return this.plural[key];
     }
     getPrompt(key) {
-        return this.promptMap[key];
+        return this.warnIfMissing('prompt', key, this.promptMap[key]);
     }
     getRequirement(key) {
-        return this.requirementMap[key];
+        return this.warnIfMissing('requirement', key, this.requirementMap[key]);
     }
     getProgram(key) {
-        return this.programMap[key];
+        return this.warnIfMissing('program', key, this.programMap[key]);
+    }
+    /**
+     * `UIConfig` keeps this UI in step with the API it was built against.
+     *  Keys arrive here from the API at runtime, so these stay `string` rather than the key unions.
+     */
+    warnedMissing = new Set();
+    /**
+     * This is the ONLY runtime signal that the UI is missing a definition, so it is deliberately NOT
+     * gated on a dev-only build flag. Coverage is enforced at build time (see UIConfig's keyed form),
+     * but that gate lives in this repo's tooling and does not ship to downstream projects - a project
+     * that never wires its own type check has nothing but this line. Staying silent in production is
+     * how a missing prompt turns into an unexplained blank spot on an applicant's form.
+     * The `warnedMissing` set keeps it to one line per key, so a list of 200 prompts cannot spam.
+     *
+     * Severity splits by kind because the kinds are not equally load-bearing. A `PromptDefinition`
+     * supplies the component that actually renders the screen, so a missing one breaks a page.
+     * `RequirementDefinition` and `ProgramDefinition` carry only optional decoration - an icon, a
+     * configuration component - and every consumer optional-chains them. Leaving one unregistered is
+     * a supported choice, so it warns rather than errors.
+     */
+    warnIfMissing(kind, key, definition) {
+        if (definition == null && !this.warnedMissing.has(kind + ':' + key)) {
+            this.warnedMissing.add(kind + ':' + key);
+            const log = kind === 'prompt' ? console.error : console.warn;
+            log(`[reqquest] The API returned a ${kind} \`${key}\` that this UI has no definition for. Add it to your UIConfig, or regenerate your key declaration if the API has changed.`);
+        }
+        return definition;
     }
 }