@reqquest/ui 1.12.1 → 1.14.0

package/dist/registry.d.ts

@@ -1,4 +1,4 @@
-import type { LayoutStructureNode, LayoutStructureNodeRoot, UserProfile } from '@txstate-mws/carbon-svelte';
+import type { LayoutStructureNode, LayoutStructureNodeRoot, ShellItem, UserProfile } from '@txstate-mws/carbon-svelte';
 import type { Component } from 'svelte';
 import type { ProgramKey, PromptKey, RequirementKey } from './keys.js';
 export interface PromptLoader {
@@ -10,7 +10,31 @@ export interface PromptLoader {
     delay?: number;
 }
 export type Loader = PromptLoader | boolean;
-export interface ProgramDefinition {
+/**
+ * The panels the reviewer screen renders by default, grouped by requirement type. A program's
+ * `reviewSections` may place any of them by name.
+ *
+ * - `GENERAL` - "General Questions": PREQUAL requirements no custom panel claimed
+ * - `PROGRAM` - the panel titled with the program name: QUALIFICATION and POSTQUAL requirements no custom panel claimed
+ * - `REVIEWER` - "Reviewer Questions": PREAPPROVAL and APPROVAL requirements no custom panel claimed
+ * - `ACCEPTANCE` - "Acceptance": ACCEPTANCE requirements no custom panel claimed
+ */
+export type ReviewDefaultSection = 'GENERAL' | 'PROGRAM' | 'REVIEWER' | 'ACCEPTANCE';
+export type ReviewSection<RK extends string = RequirementKey> = 
+/** A custom panel showing exactly these requirements, in this order. */
+{
+    title: string;
+    requirementKeys: RK[];
+}
+/** The panel for one of the program's workflow stages, titled by the stage. */
+ | {
+    workflowStage: string;
+}
+/** One of the default type-based panels, holding the requirements no custom panel claimed. */
+ | {
+    section: ReviewDefaultSection;
+};
+export interface ProgramDefinition<RK extends string = RequirementKey> {
     /**
      * The key of the program this decorates. Autocompletes and rejects unknown keys once the project
      * generates a key declaration; plain `string` until then.
@@ -20,6 +44,11 @@ export interface ProgramDefinition {
      * An icon to represent this program in the navigation.
      */
     icon?: Component;
+    /**
+     * Lay out the reviewer screen. Without this, the reviewer sees one panel per requirement type,
+     * in this order, each omitted when it has nothing to show
+     */
+    reviewSections?: ReviewSection<RK>[];
 }
 export interface RequirementDefinition {
     /**
@@ -187,8 +216,8 @@ export interface Terminologies {
  * `UIConfig<SimplePromptKey, SimpleRequirementKey, SimpleProgramKey>`.
  */
 export interface UIConfig<PK extends string = PromptKey, RK extends string = RequirementKey, GK extends string = ProgramKey> {
-    programs: ProgramDefinition[] | {
-        [K in GK]?: Omit<ProgramDefinition, 'key'>;
+    programs: ProgramDefinition<RK>[] | {
+        [K in GK]?: Omit<ProgramDefinition<RK>, 'key'>;
     };
     requirements: RequirementDefinition[] | {
         [K in RK]?: Omit<RequirementDefinition, 'key'>;
@@ -242,6 +271,11 @@ export interface UIConfig<PK extends string = PromptKey, RK extends string = Req
      */
     supportUrl?: string;
     extraNavItems?: LayoutStructureNodeRoot<LayoutStructureNode>[];
+    /**
+     * Extra entries for the user-profile menu in the header. Same shape as carbon-svelte's
+     * UIShell `profilelinks`. These appear before the built-in Logout entry, which is always present.
+     */
+    profileLinks?: ShellItem[];
     /**
      * This is where you should describe what kind of attributes app users will be able to search users by.
      * Displayed on user management page /roles/users.
@@ -333,6 +367,11 @@ export declare class UIRegistry {
      */
     config: AnyUIConfig;
     constructor(config: AnyUIConfig);
+    /**
+     * `reviewSections` is pure layout, so a mistake in it surfaces as a silently missing or doubled
+     * panel on the reviewer screen.
+    */
+    protected validateReviewSections(program: ProgramDefinition): void;
     getWord(key: keyof Terminologies, count?: number, inclusive?: boolean): string;
     getPlural(key: keyof Terminologies): string;
     getPrompt(key: string): PromptDefinition | undefined;

package/dist/registry.js

@@ -1,4 +1,5 @@
 import { plural } from 'txstate-utils';
+const reviewDefaultSections = ['GENERAL', 'PROGRAM', 'REVIEWER', 'ACCEPTANCE'];
 /**
  * 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
@@ -38,6 +39,8 @@ export class UIRegistry {
         this.promptMap = toDefinitionMap(config.prompts);
         this.requirementMap = toDefinitionMap(config.requirements);
         this.programMap = toDefinitionMap(config.programs);
+        for (const program of Object.values(this.programMap))
+            this.validateReviewSections(program);
         this.userLookup = config.userLookup;
         this.lang = {
             appRequest: config.terminology?.appRequest ?? (Object.keys(this.programMap).length > 1 ? 'App Request' : 'Application'),
@@ -49,6 +52,37 @@ export class UIRegistry {
             this.plural[key] = config.terminology?.plural?.[key] ?? plural(this.lang[key]);
         }
     }
+    /**
+     * `reviewSections` is pure layout, so a mistake in it surfaces as a silently missing or doubled
+     * panel on the reviewer screen.
+    */
+    validateReviewSections(program) {
+        const where = `[reqquest] reviewSections of program \`${program.key}\``;
+        const placed = new Set();
+        const usedStages = new Set();
+        const usedSections = new Set();
+        for (const entry of program.reviewSections ?? []) {
+            if ('requirementKeys' in entry) {
+                for (const requirementKey of entry.requirementKeys) {
+                    if (placed.has(requirementKey))
+                        console.error(`${where}: \`${requirementKey}\` is placed in more than one panel.`);
+                    placed.add(requirementKey);
+                }
+            }
+            else if ('workflowStage' in entry) {
+                if (usedStages.has(entry.workflowStage))
+                    console.error(`${where}: workflow stage \`${entry.workflowStage}\` is placed more than once.`);
+                usedStages.add(entry.workflowStage);
+            }
+            else {
+                if (!reviewDefaultSections.includes(entry.section))
+                    console.error(`${where}: \`${String(entry.section)}\` is not a default section. Use one of ${reviewDefaultSections.join(', ')}.`);
+                if (usedSections.has(entry.section))
+                    console.error(`${where}: default section \`${entry.section}\` is placed more than once.`);
+                usedSections.add(entry.section);
+            }
+        }
+    }
     getWord(key, count = 1, inclusive = false) {
         return (inclusive ? count + ' ' : '') + (count !== 1 ? this.plural[key] : this.lang[key]);
     }

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

@@ -8,8 +8,6 @@ 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. */
@@ -18,12 +16,12 @@ 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'];
+    /** Current user is permitted to manage site-wide announcements: create, update, and delete them. */
+    manageAnnouncements: Scalars['Boolean'];
     /** The current user, if any. */
     user: (AccessUser | null);
+    /** Current user is permitted to view the announcement management page, whether or not they may change anything. */
+    viewAnnouncementManagement: Scalars['Boolean'];
     /** Current user is permitted to view the app request list. */
     viewAppRequestList: Scalars['Boolean'];
     /** Current user is permitted to view the applicant dashboard. */
@@ -169,6 +167,8 @@ export interface Announcement {
     /** The announcement will not display after this date. Null means it displays until it is disabled. */
     end: (Scalars['DateTime'] | null);
     id: Scalars['ID'];
+    /** Whether the announcement should be displaying right now: enabled and inside whatever date bounds it has. */
+    isActive: Scalars['Boolean'];
     /** URL the announcement directs the user to for more information. */
     link: (Scalars['String'] | null);
     /** The text to display for the link. */
@@ -719,7 +719,7 @@ 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. */
+    /** Retrieve site-wide announcements. Any authenticated user may retrieve any announcement, including ones that are disabled or outside their date range; pass filter.active to limit the result to the announcements that should be displaying right now. */
     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[];
@@ -767,7 +767,7 @@ 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. */
+    /** True when this row exists only because its requirement listed the prompt in `promptKeysNoDisplay` */
     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. */
@@ -837,8 +837,6 @@ 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. */
@@ -847,12 +845,12 @@ 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;
+    /** Current user is permitted to manage site-wide announcements: create, update, and delete them. */
+    manageAnnouncements?: boolean | number;
     /** The current user, if any. */
     user?: AccessUserGenqlSelection;
+    /** Current user is permitted to view the announcement management page, whether or not they may change anything. */
+    viewAnnouncementManagement?: boolean | number;
     /** Current user is permitted to view the app request list. */
     viewAppRequestList?: boolean | number;
     /** Current user is permitted to view the applicant dashboard. */
@@ -1072,6 +1070,8 @@ export interface AnnouncementGenqlSelection {
     /** The announcement will not display after this date. Null means it displays until it is disabled. */
     end?: boolean | number;
     id?: boolean | number;
+    /** Whether the announcement should be displaying right now: enabled and inside whatever date bounds it has. */
+    isActive?: boolean | number;
     /** URL the announcement directs the user to for more information. */
     link?: boolean | number;
     /** The text to display for the link. */
@@ -1086,7 +1086,7 @@ export interface AnnouncementGenqlSelection {
     __scalar?: boolean | number;
 }
 export interface AnnouncementFilters {
-    /** Return only the announcements that should be displayed at this moment: enabled OR within their date range. */
+    /** Return only the announcements that should be displaying right now (true) or only those that should not (false). Omit to return all announcements regardless of state. */
     active?: (Scalars['Boolean'] | null);
     /** Return only enabled (true) or only disabled (false) announcements. */
     enabled?: (Scalars['Boolean'] | null);
@@ -2018,7 +2018,7 @@ 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. */
+    /** Retrieve site-wide announcements. Any authenticated user may retrieve any announcement, including ones that are disabled or outside their date range; pass filter.active to limit the result to the announcements that should be displaying right now. */
     announcements?: (AnnouncementGenqlSelection & {
         __args?: {
             filter?: (AnnouncementFilters | null);
@@ -2124,7 +2124,7 @@ 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. */
+    /** True when this row exists only because its requirement listed the prompt in `promptKeysNoDisplay` */
     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. */

package/dist/typed-client/schema.graphql

@@ -1,7 +1,4 @@
 type Access {
-  """Current user is permitted to create announcements."""
-  createAnnouncement: 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.
   """
@@ -22,15 +19,19 @@ type Access {
   """
   createRole: Boolean!
 
-  """Current user is permitted to delete announcements."""
-  deleteAnnouncement: Boolean!
-
-  """Current user is permitted to update announcements."""
-  updateAnnouncement: Boolean!
+  """
+  Current user is permitted to manage site-wide announcements: create, update, and delete them.
+  """
+  manageAnnouncements: Boolean!
 
   """The current user, if any."""
   user: AccessUser
 
+  """
+  Current user is permitted to view the announcement management page, whether or not they may change anything.
+  """
+  viewAnnouncementManagement: Boolean!
+
   """Current user is permitted to view the app request list."""
   viewAppRequestList: Boolean!
 
@@ -303,6 +304,11 @@ type Announcement {
   end: DateTime
   id: ID!
 
+  """
+  Whether the announcement should be displaying right now: enabled and inside whatever date bounds it has.
+  """
+  isActive: Boolean!
+
   """URL the announcement directs the user to for more information."""
   link: String
 
@@ -323,7 +329,7 @@ type Announcement {
 
 input AnnouncementFilters {
   """
-  Return only the announcements that should be displayed at this moment: enabled OR within their date range.
+  Return only the announcements that should be displaying right now (true) or only those that should not (false). Omit to return all announcements regardless of state.
   """
   active: Boolean
 
@@ -1831,7 +1837,7 @@ type Query {
   accessUsers(filter: AccessUserFilter, paged: Pagination): [AccessUser!]!
 
   """
-  Retrieve site-wide announcements. Applicants only ever see currently active announcements; users with the Announcement view control see them all.
+  Retrieve site-wide announcements. Any authenticated user may retrieve any announcement, including ones that are disabled or outside their date range; pass filter.active to limit the result to the announcements that should be displaying right now.
   """
   announcements(filter: AnnouncementFilters): [Announcement!]!
 
@@ -1956,7 +1962,7 @@ type RequirementPrompt {
   navTitle: 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.
+  True when this row exists only because its requirement listed the prompt in `promptKeysNoDisplay`
   """
   noDisplay: Boolean!
   optOut: Boolean!

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

@@ -2,14 +2,13 @@ declare const _default: {
     scalars: number[];
     types: {
         Access: {
-            createAnnouncement: number[];
             createAppRequestOther: number[];
             createAppRequestSelf: number[];
             createPeriod: number[];
             createRole: number[];
-            deleteAnnouncement: number[];
-            updateAnnouncement: number[];
+            manageAnnouncements: number[];
             user: number[];
+            viewAnnouncementManagement: number[];
             viewAppRequestList: number[];
             viewApplicantDashboard: number[];
             viewMetrics: number[];
@@ -168,6 +167,7 @@ declare const _default: {
             enabled: number[];
             end: number[];
             id: number[];
+            isActive: number[];
             link: number[];
             linkText: number[];
             start: number[];

package/dist/typed-client/types.js

@@ -21,9 +21,6 @@ export default {
     ],
     "types": {
         "Access": {
-            "createAnnouncement": [
-                45
-            ],
             "createAppRequestOther": [
                 45
             ],
@@ -36,15 +33,15 @@ export default {
             "createRole": [
                 45
             ],
-            "deleteAnnouncement": [
-                45
-            ],
-            "updateAnnouncement": [
+            "manageAnnouncements": [
                 45
             ],
             "user": [
                 17
             ],
+            "viewAnnouncementManagement": [
+                45
+            ],
             "viewAppRequestList": [
                 45
             ],
@@ -431,6 +428,9 @@ export default {
             "id": [
                 53
             ],
+            "isActive": [
+                45
+            ],
             "link": [
                 89
             ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reqquest/ui",
-  "version": "1.12.1",
+  "version": "1.14.0",
   "overrides": {
     "esrap": "2.3.2"
   },
@@ -23,6 +23,8 @@
     "prepublishOnly": "npm run package",
     "check": "svelte-check --tsconfig ./tsconfig.json",
     "check:registry": "node check-registry.js",
+    "docs:components": "node scripts/build-components-md.js",
+    "docs:components:check": "node scripts/build-components-md.js --check",
     "check:watch": "svelte-check --tsconfig ./tsconfig.json --watch"
   },
   "peerDependencies": {