20284 Project documentation (#1445)

* add nuxt admin url to env example

* update setup instructions

* write developer documentation

* format and add table of contents to developer docs

* fix duplication

* formatting and small fix

* document components

* document `Expandable`

* document `NavLink` and rename `Container.vue`

* document more generic components

* document decision area components

* document more components

* formatting and add 'goto definition alias` as recommended extension

* link to setup section in readme in developer doc

* reword recipe/request info doc

* update version

.env.example

@@ -6,6 +6,7 @@ NUXT_SITEMINDER_LOGOUT_URL="https://logontest7.gov.bc.ca/clp-cgi/logoff.cgi"
 #vaults API
 NUXT_NAMEX_API_URL="https://namex-dev.apps.silver.devops.gov.bc.ca"
 NUXT_NAMEX_API_VERSION="/api/v1"
+NUXT_NAMEX_ADMIN_URL = "https://namex-solr-dev.apps.silver.devops.gov.bc.ca/"
 
 #vaults keycloak
 NUXT_KEYCLOAK_AUTH_URL="https://dev.loginproxy.gov.bc.ca/auth"

CONTRIBUTING.md

@@ -5,6 +5,6 @@ Government employees, public and members of the private sector are encouraged to
 
 (If you are new to GitHub, you might start with a [basic tutorial](https://help.github.com/articles/set-up-git) and  check out a more detailed guide to [pull requests](https://help.github.com/articles/using-pull-requests/).)
 
-Pull requests will be evaluated by the repository guardians on a schedule and if deemed beneficial will be committed to the master.
+Pull requests will be evaluated by the repository guardians on a schedule and if deemed beneficial will be committed to the main branch.
 
 All contributors retain the original copyright to their stuff, but by contributing to this project, you grant a world-wide, royalty-free, perpetual, irrevocable, non-exclusive, transferable license to all users **under the terms of the license under which this project is distributed.**

DEVELOPER.md

@@ -0,0 +1,85 @@
+# Developer Documentation
+
+## Table of Contents
+
+- [VS Code Environment Setup](#vs-code-environment-setup)
+- [Project Structure and Organization](#project-structure-and-organization)
+  - [`utils`](#utils)
+  - [`types`](#types)
+  - [`store`](#store)
+  - [`composables`](#composables)
+  - [`components`](#components)
+- [Coding Guide](#coding-guide)
+
+## VS Code Environment Setup
+
+After following the setup instructions in the [README](./README.md#setup), you should have a local dev server up and running.
+
+The following exensions are recommended:
+
+- [Vue](https://marketplace.visualstudio.com/items?itemName=Vue.volar)
+- [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
+- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+- [Goto definition alias](https://marketplace.visualstudio.com/items?itemName=antfu.goto-alias) - allows you to control click a component and go to its file
+
+You can create a basic chrome launch configuration in VS Code to open a browser window for debugging.
+
+## Project Structure and Organization
+
+Let's go over some of the top-level folders in the project.
+
+### `utils`
+
+This folder contains util functions that are used throughout the project. If you are creating a generic helper function that isn't super specific to the component you are working on, please consider moving it to the utils folder if it doesn't already exist.
+
+Some useful util files:
+
+- `date.ts` - Contains utils for parsing and formatting dates from the NameX API and displaying it consistently across the UI.
+- `emitter.ts` - Contains the global event bus for emitting events that other places in the code can listen for. For example, you can emit an error event anywhere in the codebase to show an error dialog to the user.
+- `index.ts` - Contains some random util functions that aren't (but probably should be) organized. There are functions for validating NR and corp numbers here.
+- `namex-api.ts` - Probably the most important util file. Contains functions for interacting with the NameX API. If you need to interact with the API in any way, use one of the functions in here, or create one here if it doesn't exist.
+
+Please check this folder first before creating a generic helper function.
+
+### `types`
+
+This folder contains the TypeScript interfaces for the entire project. If you need to create a new interface/type, please put it in here.
+
+### `store`
+
+This folder contains the Pinia stores used in the project, and it's where a lot of the heavy-lifting logic resides.
+
+`store/examine/index.ts` is where the main logic for the examine store resides. It relies on some other stores, two of which are:
+
+- `conflict-data.ts` - contains functions for retrieving detailed information about a conflict.
+- `conflicts.ts` - manages all conflicts for a particular name, and keeps track of which conflicts the user has selected for their decision or to compare in the 'Compare' tab. It does _not_ store detailed information about each conflict, but rather a small snapshot (`ConflictListItem`)
+
+### `composables`
+
+Contains reusable logic that can be used across the project. Of note:
+
+- `mnemonic.ts` - Contains logic for registering a _mnemonic_. A mnemonic is a keyboard shortcut that consists of a modifier key (alt on Windows) plus a letter, which then triggers an action in the application. In the UI, mnemonic letters are shown underlined.
+
+### `components`
+
+This folder contains all of the Vue components.
+Nuxt uses the path of the component file to form the name of the component when using it. For example, `components/app_header/NavLink.vue` would be referred to as `AppHeaderNavLink` in code.
+
+Some folders to highlight:
+
+- `examine/recipe/` - this folder contains components for the _recipe area_ of the Examine page. The recipe area is the place where all the conflicts, conditions, trademarks, and history can be browsed. It's also where the user can select conflicts for their decision.
+- `examine/request_info/` - this folder contains components for the _request info_ section of the Examine page, which are the 5 cells near the top of the Examine page that contain information about the NR currently being examined.
+
+If a component is generic enough that it can be used anywhere in the application (e.g. a button), then it can go directly under the `components` folder.
+
+## Coding Guide
+
+Here are some guidelines for contributing to the codebase:
+
+- Use inline Tailwind utility classes for styling as much as possible
+- Keep Vue files in the `pages` folder light on logic, refer to components in the `components` folder as much as possible
+- Break up Vue components when you can and keep them relatively small
+- Use Vue 3's Composition API for all Vue components
+- Use Setup syntax when creating new Pinia stores
+- Use TypeScript instead of JavaScript
+- Format your code with Prettier before committing it

README.md

@@ -1,66 +1,38 @@
-# Content v2 Minimal Starter
+# Name Examination
 
-Look at the [Content documentation](https://content-v2.nuxtjs.org/) to learn more.
+Service BC Name Examination System
+
+## Documentation
+
+For further documentation about the project for developers, see the [developer documentation](./DEVELOPER.md).
 
 ## Setup
 
 Make sure to install the dependencies:
 
 ```bash
-# pnpm
-pnpm install
-
-# yarn
-yarn install
-
-# npm
 npm install
-
+# or with pnpm:
+pnpm install
 ```
 
-## Setup Environment Variables
+### Setup Environment Variables
 
 ```bash
-
 cp .env.example .env
-
 ```
+**You will need to fill in the Firebase variables for the project to run.**
 
-## Linting
-
-```bash
-pnmp run lint
-```
-
-## Testing
-
-```Vitest
-pnmp run test
-```
-
-```Cyprus
-npx cypress open
-
-## Development Server
+### Development Server
 
 Start the development server on http://localhost:8080
 
 ```bash
-pnpm run dev
+npm run dev
 ```
 
-## Production
-
-Build the application for production:
+### Testing
 
 ```bash
-pnpm run build
+npm run test
 ```
-
-Locally preview production build:
-
-```bash
-pnpm run preview
-```
-
-Checkout the [deployment documentation](https://v3.nuxtjs.org/docs/deployment) for more information.

components/Accordion.vue

@@ -19,12 +19,17 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * Component that can show hidden content when clicked.
+ */
 import { ChevronDownIcon } from '@heroicons/vue/24/outline'
 
 const props = defineProps<{
   open: boolean
   arrow?: boolean
+  /** Tailwind class list that is passed to the header/summary element */
   buttonStyle?: any
+  /** Whether the accordion is disabled (can't be clicked) */
   disabled?: boolean
 }>()
 

components/AppBanner.vue

@@ -5,6 +5,7 @@
 </template>
 
 <script setup>
+/** Banner that shows a notification message to the user, retrieved from Firebase */
 import { useNuxtApp } from '#app'
 import { getString } from 'firebase/remote-config'
 import { FeatureFlags } from '@/util/constants'

components/Chips.vue

@@ -17,11 +17,14 @@
 </template>
 
 <script setup lang="ts">
+/** A grid of small components that represent a list of items that are deletable. */
 import { XMarkIcon } from '@heroicons/vue/24/outline'
 
 defineProps<{
   modelValue: Array<any>
+  /** Function called for retrieving a string to display for an item on a chip */
   display?: (input: any) => string
+  /** Function called for getting a key for a given chip item */
   getKey?: (input: any) => string
 }>()
 

components/ComboSelect.vue

@@ -74,6 +74,7 @@
 </template>
 
 <script setup lang="ts">
+/** Component that lets you select an item from a list of items, and allows the user to search for an item. */
 import { ref, computed } from 'vue'
 import {
   Combobox,
@@ -89,7 +90,9 @@ const { options, multiple } = withDefaults(
   defineProps<{
     modelValue: any
     options: ComputedRef<Array<any>>
+    /** Whether multiple options can be selected */
     multiple?: boolean
+    /** Function called for getting the display string for a given option */
     optionsDisplay?: (option: any) => string
   }>(),
   {

components/DateInput.vue

@@ -10,10 +10,12 @@
 </template>
 
 <script setup lang="ts">
+/** An input for selecting dates */
 import { DateTime } from 'luxon'
 
 defineProps<{
   modelValue: any
+  /** Set the minimum possible date value to today */
   minToday?: boolean
   /** Style this input to show an error */
   errorStyle?: boolean

components/EditableTextBox.vue

@@ -61,21 +61,28 @@
 </template>
 
 <script setup lang="ts">
+/** A text box that displays editable text */
 import { PopoverButton } from '@headlessui/vue'
 
 const { modelValue, characterLimit, textRequired } = defineProps<{
   modelValue: string
   placeholder?: string
+  /** Hide the submit button */
   hideSubmit?: boolean
+  /** Hide the cancel button */
   hideCancel?: boolean
+  /** Mnemonic letter for the submit button */
   submitMnemonic?: string
+  /** Mnemonic letter for the cancel button */
   cancelMnemonic?: string
+  /** Set the content to be non-editable (readonly) */
   readonly?: boolean
   /** Display the number of characters in the text area and a character limit. Does not enforce the character limit. */
   characterLimit?: number
   /** Prevents the user from submitting if the text field is empty. */
   textRequired?: boolean
-  /** Whether to use `PopoverButton`s from HeadlessUI, useful if using text box in a Popover and buttons should close Popover when clicked. */
+  /** Whether to use `PopoverButton`s from HeadlessUI for the submit/cancel buttons,
+   *  useful if using text box in a `Popover` and buttons should close `Popover` when clicked. */
   usePopoverButtons?: boolean
 }>()
 

components/GlobalErrorDialog.vue

@@ -14,6 +14,7 @@
 </template>
 
 <script setup lang="ts">
+/** Listens for errors on the global event bus and displays an error dialog */
 import { ExclamationTriangleIcon } from '@heroicons/vue/24/outline'
 import type { AppError } from '~/types/errors'
 import { emitter } from '~/util/emitter'

components/IconButton.vue

@@ -24,8 +24,11 @@
  */
 const props = defineProps<{
   text?: string
+  /** Use lighter shade of blue for background color */
   light?: boolean
+  /** Use white background */
   white?: boolean
+  /** Mnemonic letter to trigger this button's onclick event handler */
   mnemonic?: string
 }>()
 

components/ListSelect.vue

@@ -76,7 +76,7 @@
 
 <script setup lang="ts">
 /**
- * A dropdown menu to select list options.
+ * A dropdown menu to select an item from a list of options.
  */
 import {
   Listbox,
@@ -90,9 +90,12 @@ type ModelValueType = any
 defineProps<{
   modelValue: ModelValueType | Array<ModelValueType>
   options: Array<any>
+  /** Whether multiple options can be selected */
   multiple?: boolean
+  /** Whether the component is disabled (can't be clicked, grayed out) */
   disabled?: boolean
   optionsStyle?: string
+  /** Function called for getting a display string for a given option */
   optionsDisplay?: (option: ModelValueType) => string
   /** Style this input to indicate an error, useful to indicate invalid inputs */
   errorStyle?: boolean

components/NRNumber.vue

@@ -5,8 +5,10 @@
 </template>
 
 <script setup lang="ts">
+/** Displays a given NR number */
 defineProps<{
   nrNumber: string
+  /** Whether the NR is a priority or not */
   priority?: boolean
 }>()
 </script>

components/NameRequestTypeInfo.vue

@@ -10,6 +10,7 @@
 </template>
 
 <script setup lang="ts">
+/** Displays a given request type and jurisdiction (if applicable) */
 import jurisdictionsData from '~/data/jurisdictions.json'
 
 const props = defineProps<{

components/NoticeBanner.vue

@@ -17,6 +17,7 @@
 </template>
 
 <script setup lang="ts">
+/** Shows a message to the user with a styled banner. */
 import {
   ExclamationTriangleIcon,
   LockClosedIcon,

components/PopupDialog.vue

@@ -43,6 +43,7 @@
 </template>
 
 <script setup lang="ts">
+/** Generic component for showing given content as a popup to the user. */
 import {
   TransitionRoot,
   TransitionChild,

components/PriorityLabel.vue

@@ -6,8 +6,11 @@
 </template>
 
 <script setup lang="ts">
+/** Component usually used to indicate an NR is a priority. */
 import { StarIcon } from '@heroicons/vue/24/solid'
+
 defineProps<{
+  /** Tailwind style string passed to the label's icon. */
   iconStyle?: string
 }>()
 </script>