@reqquest/ui 1.11.0 → 1.12.1

package/README.md

@@ -2,7 +2,29 @@
 
 This library provides a set of Svelte components and utilities for building ReqQuest projects. You'll especially find the `api` useful for creating graphQL queries. In the future we will provide a small component library to help you build your prompts.
 
-# Developing
+## Registering your prompts
+
+Every prompt your API defines needs a Svelte component registered here, and nothing links the two
+automatically. Use the keyed form of `UIConfig` so a prompt you forget to register is a build error
+rather than a broken screen:
+
+```ts
+const config = {
+  appName: 'My Program',
+  prompts: {
+    proof_of_residence_prompt: { formComponent: ResidencePrompt, displayComponent: ResidenceDisplay }
+  }
+} satisfies UIConfig
+export const uiRegistry = new UIRegistry(config)
+```
+
+That check only has teeth once a key declaration augmenting `@reqquest/ui` is in your `src`. It is
+generated on the **API** side, by the analyzer that ships with `@reqquest/api` — see
+[docs/downstream-setup.md](../docs/downstream-setup.md). Without it, keys stay `string`, an
+unregistered prompt renders an inline "unavailable" notice at runtime, and you find out when a user
+reaches the screen.
+
+# Developing this library
 
 To develop the UI library, you'll want to work with the full demo, so `docker compose up --build` in the root of the repo. Similarly the test suite is combined with API tests, so run `./test.sh` in the root of the repo.
 

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;
     }
 }

package/dist/typed-client/schema.d.ts

@@ -8,6 +8,8 @@ export type Scalars = {
     String: string;
 };
 export interface Access {
+    /** Current user is permitted to create announcements. */
+    createAnnouncement: Scalars['Boolean'];
     /** Current user may create a new app request on behalf of another user and should be shown the Create App Request button on the reviewer dashboard or main app request list. */
     createAppRequestOther: Scalars['Boolean'];
     /** Current user may create a new app request for themselves and should be shown the Create App Request button. */
@@ -16,6 +18,10 @@ export interface Access {
     createPeriod: Scalars['Boolean'];
     /** Current user is permitted to create new roles in the role management UI. */
     createRole: Scalars['Boolean'];
+    /** Current user is permitted to delete announcements. */
+    deleteAnnouncement: Scalars['Boolean'];
+    /** Current user is permitted to update announcements. */
+    updateAnnouncement: Scalars['Boolean'];
     /** The current user, if any. */
     user: (AccessUser | null);
     /** Current user is permitted to view the app request list. */
@@ -154,6 +160,27 @@ export interface AccessUserIdentifier {
     label: Scalars['String'];
     __typename: 'AccessUserIdentifier';
 }
+/** A site-wide announcement shown to users, optionally limited to a date range. */
+export interface Announcement {
+    /** The content of the announcement in HTML. */
+    body: Scalars['String'];
+    /** Whether the announcement has been turned on. A disabled announcement never displays, regardless of its date range. */
+    enabled: Scalars['Boolean'];
+    /** The announcement will not display after this date. Null means it displays until it is disabled. */
+    end: (Scalars['DateTime'] | null);
+    id: Scalars['ID'];
+    /** URL the announcement directs the user to for more information. */
+    link: (Scalars['String'] | null);
+    /** The text to display for the link. */
+    linkText: (Scalars['String'] | null);
+    /** The announcement will not display before this date. Null means it displays as soon as it is enabled. */
+    start: (Scalars['DateTime'] | null);
+    /** Short headline for the announcement. */
+    subject: Scalars['String'];
+    /** The type of announcement, toggleable or date range */
+    type: Scalars['String'];
+    __typename: 'Announcement';
+}
 /** Represents a group of applications all being applied for at the same time. As part of the request, multiple applications will be created and either eliminated as ineligible or submitted for approval. */
 export interface AppRequest {
     /** Actions the user can take on this app request. */
@@ -370,6 +397,8 @@ export type ApplicationPhase = 'ACCEPTANCE' | 'APPROVAL' | 'COMPLETE' | 'PREAPPR
 /** The specific instance of a requirement on a particular application. Stores the status of the requirement, e.g. being satisfied or not. */
 export interface ApplicationRequirement {
     application: Application;
+    /** The prompt keys the requirement named as responsible for its current status. Used to attach status indicators to the specific answers at fault instead of every prompt the requirement consults. Null when the requirement did not name any, in which case all of its prompts are implicated. */
+    blame: (Scalars['String'][] | null);
     /** The configuration data for this requirement in the app request's period. */
     configurationData: (Scalars['JsonData'] | null);
     /** An internal description of the requirement. Probably not shown to users. */
@@ -482,9 +511,13 @@ export interface Mutation {
     completeRequest: ValidatedAppRequestResponse;
     /** Make an offer on the app request. If all applications are ineligible, or if there are no acceptance requirements, the applications will advance to the non-blocking workflow, or absent that, be marked complete. */
     completeReview: ValidatedAppRequestResponse;
+    /** Create a new site-wide announcement. */
+    createAnnouncement: ValidatedAnnouncementResponse;
     /** Create a new app request. */
     createAppRequest: ValidatedAppRequestResponse;
     createPeriod: ValidatedPeriodResponse;
+    /** Delete an existing site-wide announcement. */
+    deleteAnnouncement: ValidatedResponse;
     /** Delete an existing note. */
     deleteNote: Scalars['Boolean'];
     deletePeriod: ValidatedResponse;
@@ -515,6 +548,8 @@ export interface Mutation {
     submitAppRequest: ValidatedAppRequestResponse;
     /** Toggle an existing note's persistent status. */
     togglePersistence: ValidatedNoteResponse;
+    /** Update an existing site-wide announcement. */
+    updateAnnouncement: ValidatedAnnouncementResponse;
     updateConfiguration: ValidatedConfigurationResponse;
     /** Update the content of an existing note. */
     updateNote: ValidatedNoteResponse;
@@ -684,6 +719,8 @@ export interface Query {
      */
     access: Access;
     accessUsers: AccessUser[];
+    /** Retrieve site-wide announcements. Applicants only ever see currently active announcements; users with the Announcement view control see them all. */
+    announcements: Announcement[];
     /** The activity log for this app request. This is a list of actions taken on the app request, such as submission, updating prompts, make an offer, add a note, etc. It will be sorted by the date of the activity in descending order. */
     appRequestActivity: AppRequestActivity[];
     appRequestIndexes: IndexCategory[];
@@ -730,6 +767,8 @@ export interface RequirementPrompt {
     moot: Scalars['Boolean'];
     /** A human readable title for the prompt in the navigation. You probably want it to be shorter than the full title. If not provided, the title will be used. */
     navTitle: Scalars['String'];
+    /** True when this row exists only because its requirement listed the prompt in `promptKeysNoDisplay` - a dependency it reads but does not own. Such a row must not be rendered beneath that requirement; the prompt is displayed under the requirement that does own it. This is not derivable from `visibility`: a no-display row is UNREACHABLE, but so is a prompt whose own requirement resolved before reaching it, and that one is still the requirement's to show. */
+    noDisplay: Scalars['Boolean'];
     optOut: Scalars['Boolean'];
     /** Preload data that has been generated according to the prompt definition. For example, a prompt might query the database for answers given in previous requests or query an external API to learn facts about the user. */
     preloadData: (Scalars['JsonData'] | null);
@@ -754,6 +793,14 @@ export interface RoleActions {
     update: Scalars['Boolean'];
     __typename: 'RoleActions';
 }
+export interface ValidatedAnnouncementResponse {
+    /** The created or updated announcement. Null when validateOnly was true or when validation errors prevented the operation. */
+    announcement: (Announcement | null);
+    messages: MutationMessage[];
+    /** True if the mutation succeeded (e.g. saved data or passed validation), even if there were warnings. */
+    success: Scalars['Boolean'];
+    __typename: 'ValidatedAnnouncementResponse';
+}
 export interface ValidatedAppRequestResponse {
     appRequest: (AppRequest | null);
     messages: MutationMessage[];
@@ -790,6 +837,8 @@ export interface ValidatedResponse {
     __typename: 'ValidatedResponse';
 }
 export interface AccessGenqlSelection {
+    /** Current user is permitted to create announcements. */
+    createAnnouncement?: boolean | number;
     /** Current user may create a new app request on behalf of another user and should be shown the Create App Request button on the reviewer dashboard or main app request list. */
     createAppRequestOther?: boolean | number;
     /** Current user may create a new app request for themselves and should be shown the Create App Request button. */
@@ -798,6 +847,10 @@ export interface AccessGenqlSelection {
     createPeriod?: boolean | number;
     /** Current user is permitted to create new roles in the role management UI. */
     createRole?: boolean | number;
+    /** Current user is permitted to delete announcements. */
+    deleteAnnouncement?: boolean | number;
+    /** Current user is permitted to update announcements. */
+    updateAnnouncement?: boolean | number;
     /** The current user, if any. */
     user?: AccessUserGenqlSelection;
     /** Current user is permitted to view the app request list. */
@@ -1010,6 +1063,54 @@ export interface AccessUserIdentifierInput {
     id: Scalars['ID'];
     label: Scalars['String'];
 }
+/** A site-wide announcement shown to users, optionally limited to a date range. */
+export interface AnnouncementGenqlSelection {
+    /** The content of the announcement in HTML. */
+    body?: boolean | number;
+    /** Whether the announcement has been turned on. A disabled announcement never displays, regardless of its date range. */
+    enabled?: boolean | number;
+    /** The announcement will not display after this date. Null means it displays until it is disabled. */
+    end?: boolean | number;
+    id?: boolean | number;
+    /** URL the announcement directs the user to for more information. */
+    link?: boolean | number;
+    /** The text to display for the link. */
+    linkText?: boolean | number;
+    /** The announcement will not display before this date. Null means it displays as soon as it is enabled. */
+    start?: boolean | number;
+    /** Short headline for the announcement. */
+    subject?: boolean | number;
+    /** The type of announcement, toggleable or date range */
+    type?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
+export interface AnnouncementFilters {
+    /** Return only the announcements that should be displayed at this moment: enabled OR within their date range. */
+    active?: (Scalars['Boolean'] | null);
+    /** Return only enabled (true) or only disabled (false) announcements. */
+    enabled?: (Scalars['Boolean'] | null);
+    /** Return the announcements with these IDs. */
+    ids?: (Scalars['ID'][] | null);
+}
+export interface AnnouncementUpdate {
+    /** The content of the announcement in HTML. Unsafe markup is stripped on save. */
+    body?: (Scalars['String'] | null);
+    /** Whether the announcement has been turned on. */
+    enabled?: (Scalars['Boolean'] | null);
+    /** The announcement will not display after this date. Null means it displays until it is disabled. */
+    end?: (Scalars['DateTime'] | null);
+    /** URL the announcement directs the user to for more information. */
+    link?: (Scalars['String'] | null);
+    /** The text to display for the link. Required when a link is given. */
+    linkText?: (Scalars['String'] | null);
+    /** The announcement will not display before this date. Null means it displays as soon as it is enabled. */
+    start?: (Scalars['DateTime'] | null);
+    /** Short headline for the announcement. */
+    subject?: (Scalars['String'] | null);
+    /** The type of announcement, toggleable or date range */
+    type?: (Scalars['String'] | null);
+}
 /** Represents a group of applications all being applied for at the same time. As part of the request, multiple applications will be created and either eliminated as ineligible or submitted for approval. */
 export interface AppRequestGenqlSelection {
     /** Actions the user can take on this app request. */
@@ -1308,6 +1409,8 @@ export interface ApplicationMetricTimingGenqlSelection {
 /** The specific instance of a requirement on a particular application. Stores the status of the requirement, e.g. being satisfied or not. */
 export interface ApplicationRequirementGenqlSelection {
     application?: ApplicationGenqlSelection;
+    /** The prompt keys the requirement named as responsible for its current status. Used to attach status indicators to the specific answers at fault instead of every prompt the requirement consults. Null when the requirement did not name any, in which case all of its prompts are implicated. */
+    blame?: boolean | number;
     /** The configuration data for this requirement in the app request's period. */
     configurationData?: boolean | number;
     /** An internal description of the requirement. Probably not shown to users. */
@@ -1501,6 +1604,13 @@ export interface MutationGenqlSelection {
             appRequestId: Scalars['ID'];
         };
     });
+    /** Create a new site-wide announcement. */
+    createAnnouncement?: (ValidatedAnnouncementResponseGenqlSelection & {
+        __args: {
+            announcement: AnnouncementUpdate;
+            validateOnly?: (Scalars['Boolean'] | null);
+        };
+    });
     /** Create a new app request. */
     createAppRequest?: (ValidatedAppRequestResponseGenqlSelection & {
         __args: {
@@ -1516,6 +1626,12 @@ export interface MutationGenqlSelection {
             validateOnly?: (Scalars['Boolean'] | null);
         };
     });
+    /** Delete an existing site-wide announcement. */
+    deleteAnnouncement?: (ValidatedResponseGenqlSelection & {
+        __args: {
+            announcementId: Scalars['ID'];
+        };
+    });
     /** Delete an existing note. */
     deleteNote?: {
         __args: {
@@ -1635,6 +1751,14 @@ export interface MutationGenqlSelection {
             noteId: Scalars['ID'];
         };
     });
+    /** Update an existing site-wide announcement. */
+    updateAnnouncement?: (ValidatedAnnouncementResponseGenqlSelection & {
+        __args: {
+            announcement: AnnouncementUpdate;
+            announcementId: Scalars['ID'];
+            validateOnly?: (Scalars['Boolean'] | null);
+        };
+    });
     updateConfiguration?: (ValidatedConfigurationResponseGenqlSelection & {
         __args: {
             data: Scalars['JsonData'];
@@ -1894,6 +2018,12 @@ export interface QueryGenqlSelection {
             paged?: (Pagination | null);
         };
     });
+    /** Retrieve site-wide announcements. Applicants only ever see currently active announcements; users with the Announcement view control see them all. */
+    announcements?: (AnnouncementGenqlSelection & {
+        __args?: {
+            filter?: (AnnouncementFilters | null);
+        };
+    });
     /** The activity log for this app request. This is a list of actions taken on the app request, such as submission, updating prompts, make an offer, add a note, etc. It will be sorted by the date of the activity in descending order. */
     appRequestActivity?: (AppRequestActivityGenqlSelection & {
         __args: {
@@ -1994,6 +2124,8 @@ export interface RequirementPromptGenqlSelection {
     moot?: boolean | number;
     /** A human readable title for the prompt in the navigation. You probably want it to be shorter than the full title. If not provided, the title will be used. */
     navTitle?: boolean | number;
+    /** True when this row exists only because its requirement listed the prompt in `promptKeysNoDisplay` - a dependency it reads but does not own. Such a row must not be rendered beneath that requirement; the prompt is displayed under the requirement that does own it. This is not derivable from `visibility`: a no-display row is UNREACHABLE, but so is a prompt whose own requirement resolved before reaching it, and that one is still the requirement's to show. */
+    noDisplay?: boolean | number;
     optOut?: boolean | number;
     /** Preload data that has been generated according to the prompt definition. For example, a prompt might query the database for answers given in previous requests or query an external API to learn facts about the user. */
     preloadData?: {
@@ -2040,6 +2172,15 @@ export interface RoleActionsGenqlSelection {
     __typename?: boolean | number;
     __scalar?: boolean | number;
 }
+export interface ValidatedAnnouncementResponseGenqlSelection {
+    /** The created or updated announcement. Null when validateOnly was true or when validation errors prevented the operation. */
+    announcement?: AnnouncementGenqlSelection;
+    messages?: MutationMessageGenqlSelection;
+    /** True if the mutation succeeded (e.g. saved data or passed validation), even if there were warnings. */
+    success?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
 export interface ValidatedAppRequestResponseGenqlSelection {
     appRequest?: AppRequestGenqlSelection;
     messages?: MutationMessageGenqlSelection;
@@ -2122,6 +2263,9 @@ export declare const isAccessUser: (obj?: {
 export declare const isAccessUserIdentifier: (obj?: {
     __typename?: any;
 } | null) => obj is AccessUserIdentifier;
+export declare const isAnnouncement: (obj?: {
+    __typename?: any;
+} | null) => obj is Announcement;
 export declare const isAppRequest: (obj?: {
     __typename?: any;
 } | null) => obj is AppRequest;
@@ -2224,6 +2368,9 @@ export declare const isRequirementPromptActions: (obj?: {
 export declare const isRoleActions: (obj?: {
     __typename?: any;
 } | null) => obj is RoleActions;
+export declare const isValidatedAnnouncementResponse: (obj?: {
+    __typename?: any;
+} | null) => obj is ValidatedAnnouncementResponse;
 export declare const isValidatedAppRequestResponse: (obj?: {
     __typename?: any;
 } | null) => obj is ValidatedAppRequestResponse;