From a64a0b2938b05d33ef137f140085c8adb708710b Mon Sep 17 00:00:00 2001
From: adro <a.schlett@gmx.de>
Date: Fri, 3 Nov 2023 19:35:45 +0100
Subject: [PATCH] Added Structural Documentation - Also renamed some
 directories for consistency - Moved all components into corresponding
 subdirectories - Minor Text Changes

---
 client/README.md                              | 35 +++++++++++--------
 .../components/{ => display}/NiceTable.vue    |  0
 client/src/components/display/README.md       |  2 ++
 .../components/{ => display}/TableView.vue    |  0
 .../components/{inputs => input}/CheckBox.vue |  0
 .../{inputs => input}/DropdownInput.vue       |  0
 .../{inputs => input}/EnumInput.vue           |  0
 .../{inputs => input}/MultiSelect.vue         |  0
 .../{inputs => input}/MultilineTextBox.vue    |  0
 .../src/components/{ => input}/NiceForm.vue   |  0
 .../{inputs => input}/NicerForm.vue           |  0
 .../{inputs => input}/NumberBox.vue           |  0
 .../components/{inputs => input}/PillBar.vue  |  0
 client/src/components/input/README.md         |  3 ++
 .../{inputs => input}/SingleSelect.vue        |  0
 .../components/{inputs => input}/TextBox.vue  |  0
 client/src/components/layout/README.md        |  3 ++
 client/src/components/meta/README.md          | 11 ++++++
 client/src/definitions.ts                     |  2 +-
 client/src/global-styles/README.md            | 17 +++++++++
 client/src/global-styles/mlfe.css             |  2 +-
 client/src/global-styles/transitions.css      |  1 +
 client/src/main.ts                            | 18 +++++-----
 client/src/pages/test.vue                     |  2 +-
 client/vite.config.ts                         |  4 +--
 25 files changed, 72 insertions(+), 28 deletions(-)
 rename client/src/components/{ => display}/NiceTable.vue (100%)
 create mode 100644 client/src/components/display/README.md
 rename client/src/components/{ => display}/TableView.vue (100%)
 rename client/src/components/{inputs => input}/CheckBox.vue (100%)
 rename client/src/components/{inputs => input}/DropdownInput.vue (100%)
 rename client/src/components/{inputs => input}/EnumInput.vue (100%)
 rename client/src/components/{inputs => input}/MultiSelect.vue (100%)
 rename client/src/components/{inputs => input}/MultilineTextBox.vue (100%)
 rename client/src/components/{ => input}/NiceForm.vue (100%)
 rename client/src/components/{inputs => input}/NicerForm.vue (100%)
 rename client/src/components/{inputs => input}/NumberBox.vue (100%)
 rename client/src/components/{inputs => input}/PillBar.vue (100%)
 create mode 100644 client/src/components/input/README.md
 rename client/src/components/{inputs => input}/SingleSelect.vue (100%)
 rename client/src/components/{inputs => input}/TextBox.vue (100%)
 create mode 100644 client/src/components/layout/README.md
 create mode 100644 client/src/components/meta/README.md
 create mode 100644 client/src/global-styles/README.md

diff --git a/client/README.md b/client/README.md
index ef72fd5..e701022 100644
--- a/client/README.md
+++ b/client/README.md
@@ -1,18 +1,25 @@
-# Vue 3 + TypeScript + Vite
+# nfSense Web Client
+This folder contains the standard client for the nfSense firewall.
 
-This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+## Goals and Priorities
+The nfSense web client should be...
+- As reliable as possible
+- Pleasing to the eye and intuitive to new users
+- Fast, and not get in your way.
 
-## Recommended IDE Setup
+## Technology
+### General Structure
+The nfSense web client is a monolithic Single-Page Web-Application.
 
-- [VS Code](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin).
+### Critical Dependencies
+We encourage any potential contributor to familiarize themselves with these tools and libraries before making changes, as they lie at the heart of the project.
+- Vue 3: Frontend Framework
+- Vite: Dev and Build Tool
+- Typescript: Adds Type Information to JS
+- Vue Macros: Replacement for the deprecated experimental Reactivity Transform feature of Vue 3
 
-## Type Support For `.vue` Imports in TS
-
-TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) to make the TypeScript language service aware of `.vue` types.
-
-If the standalone TypeScript plugin doesn't feel fast enough to you, Volar has also implemented a [Take Over Mode](https://github.com/johnsoncodehk/volar/discussions/471#discussioncomment-1361669) that is more performant. You can enable it by the following steps:
-
-1. Disable the built-in TypeScript Extension
-   1. Run `Extensions: Show Built-in Extensions` from VSCode's command palette
-   2. Find `TypeScript and JavaScript Language Features`, right click and select `Disable (Workspace)`
-2. Reload the VSCode window by running `Developer: Reload Window` from the command palette.
+### Important Dependencies
+These libraries aren't mandatory to be able to work on the nfSense web client, this listing is merely meant to pre-empt redundancies.
+- ESLint: The standard JS linter, which we also use to enforce some code style choices.
+- Iconify: Icons (Could be replaced with custom ones)
+- Markdown-It: We prefer markdown for informational texts, and use this to render it on the frontend.
diff --git a/client/src/components/NiceTable.vue b/client/src/components/display/NiceTable.vue
similarity index 100%
rename from client/src/components/NiceTable.vue
rename to client/src/components/display/NiceTable.vue
diff --git a/client/src/components/display/README.md b/client/src/components/display/README.md
new file mode 100644
index 0000000..d1734a3
--- /dev/null
+++ b/client/src/components/display/README.md
@@ -0,0 +1,2 @@
+# Display Components
+This folder contains components whose primary purpose it is to visually represent data that's passed in.
diff --git a/client/src/components/TableView.vue b/client/src/components/display/TableView.vue
similarity index 100%
rename from client/src/components/TableView.vue
rename to client/src/components/display/TableView.vue
diff --git a/client/src/components/inputs/CheckBox.vue b/client/src/components/input/CheckBox.vue
similarity index 100%
rename from client/src/components/inputs/CheckBox.vue
rename to client/src/components/input/CheckBox.vue
diff --git a/client/src/components/inputs/DropdownInput.vue b/client/src/components/input/DropdownInput.vue
similarity index 100%
rename from client/src/components/inputs/DropdownInput.vue
rename to client/src/components/input/DropdownInput.vue
diff --git a/client/src/components/inputs/EnumInput.vue b/client/src/components/input/EnumInput.vue
similarity index 100%
rename from client/src/components/inputs/EnumInput.vue
rename to client/src/components/input/EnumInput.vue
diff --git a/client/src/components/inputs/MultiSelect.vue b/client/src/components/input/MultiSelect.vue
similarity index 100%
rename from client/src/components/inputs/MultiSelect.vue
rename to client/src/components/input/MultiSelect.vue
diff --git a/client/src/components/inputs/MultilineTextBox.vue b/client/src/components/input/MultilineTextBox.vue
similarity index 100%
rename from client/src/components/inputs/MultilineTextBox.vue
rename to client/src/components/input/MultilineTextBox.vue
diff --git a/client/src/components/NiceForm.vue b/client/src/components/input/NiceForm.vue
similarity index 100%
rename from client/src/components/NiceForm.vue
rename to client/src/components/input/NiceForm.vue
diff --git a/client/src/components/inputs/NicerForm.vue b/client/src/components/input/NicerForm.vue
similarity index 100%
rename from client/src/components/inputs/NicerForm.vue
rename to client/src/components/input/NicerForm.vue
diff --git a/client/src/components/inputs/NumberBox.vue b/client/src/components/input/NumberBox.vue
similarity index 100%
rename from client/src/components/inputs/NumberBox.vue
rename to client/src/components/input/NumberBox.vue
diff --git a/client/src/components/inputs/PillBar.vue b/client/src/components/input/PillBar.vue
similarity index 100%
rename from client/src/components/inputs/PillBar.vue
rename to client/src/components/input/PillBar.vue
diff --git a/client/src/components/input/README.md b/client/src/components/input/README.md
new file mode 100644
index 0000000..5594f17
--- /dev/null
+++ b/client/src/components/input/README.md
@@ -0,0 +1,3 @@
+# Input Components
+This folder contains components whose primary purpose it is to accept user input, and usually provide the selection to their parent as data through their v-model.
+Convention has it that any component that can be described as an input for a specific data type should be named via the format "TypeInput", where "Type" is replaced with the types name.
diff --git a/client/src/components/inputs/SingleSelect.vue b/client/src/components/input/SingleSelect.vue
similarity index 100%
rename from client/src/components/inputs/SingleSelect.vue
rename to client/src/components/input/SingleSelect.vue
diff --git a/client/src/components/inputs/TextBox.vue b/client/src/components/input/TextBox.vue
similarity index 100%
rename from client/src/components/inputs/TextBox.vue
rename to client/src/components/input/TextBox.vue
diff --git a/client/src/components/layout/README.md b/client/src/components/layout/README.md
new file mode 100644
index 0000000..90e3883
--- /dev/null
+++ b/client/src/components/layout/README.md
@@ -0,0 +1,3 @@
+# Layout Components
+This folder contains components whose primary purpose it is to aid in laying out the GUI. The content presented by these components is generally speaking rather static.
+Unlike most other components in this project, layout components may render fragments instead of root nodes. When they do their name should be pluralized.
\ No newline at end of file
diff --git a/client/src/components/meta/README.md b/client/src/components/meta/README.md
new file mode 100644
index 0000000..720fe34
--- /dev/null
+++ b/client/src/components/meta/README.md
@@ -0,0 +1,11 @@
+# Metacomponents
+This folder contains components which don't represent specific visual elements, but rather annotate other components to add specific functionality.
+Due to their more confusing nature, their function and implementation is described here.
+
+## Portal
+This component wraps Vues standard `Teleport` component, providing semantic meaning to a `Teleport` target and not just the source.
+
+It also fixes an issue where one could not update the `Teleport` source by tracking tracking active targets and not rendering the source when there is no active target for that key.
+
+## PageHeader
+This component uses the above `Portal` imlpementation to allow updating the Page Header elsewhere in the layout, whilst also setting the title and providing a basic consistent layout.
diff --git a/client/src/definitions.ts b/client/src/definitions.ts
index e972c72..b25eec2 100644
--- a/client/src/definitions.ts
+++ b/client/src/definitions.ts
@@ -1,6 +1,6 @@
 import { toFormValidator } from '@vee-validate/zod';
 import * as zod from 'zod';
-import { SearchProvider, Options } from '~/components/inputs/DropdownInput.vue';
+import { SearchProvider, Options } from '~/components/input/DropdownInput.vue';
 import { apiCall } from './api';
 
 const GetHardwareInterfaces: SearchProvider = async (o) => {
diff --git a/client/src/global-styles/README.md b/client/src/global-styles/README.md
new file mode 100644
index 0000000..3cba1db
--- /dev/null
+++ b/client/src/global-styles/README.md
@@ -0,0 +1,17 @@
+# Global Styles
+This folder contains stylesheets which contain rules that apply to everything in the project.
+
+## atomic.css: Atomic Styles
+Utility classes which set only one or a few generic attributes.
+
+## colors.css: Color System
+Contains the definition of Base Colors, Color Palettes and Color Contexts.
+
+## components.css: Pure Style Components
+These components are meant to style DOM elements regardless of which Vue component renders them, promoting reuse.
+
+## mlfe.css: CSS Reset
+MLFE is a minimal but aggressive CSS reset that helps us with designing predictable layout.
+
+## transitions.css: Generi Transitions
+Contains transition classes for use with Vues `Transition` components.
diff --git a/client/src/global-styles/mlfe.css b/client/src/global-styles/mlfe.css
index fa1fdaf..4d7a0e7 100644
--- a/client/src/global-styles/mlfe.css
+++ b/client/src/global-styles/mlfe.css
@@ -1,4 +1,4 @@
-/* MLFE: Marginless FlexEverything (A CSS Reset for creating Layouts) */
+/* MLFE: Marginless FlexEverything (A CSS Reset for Layout) */
 :root {
   font-family: sans-serif;
   line-height: 1;
diff --git a/client/src/global-styles/transitions.css b/client/src/global-styles/transitions.css
index dc53338..da4242e 100644
--- a/client/src/global-styles/transitions.css
+++ b/client/src/global-styles/transitions.css
@@ -1,3 +1,4 @@
+/* Classes for Vue Transitions */
 .fade-enter-active, .fade-leave-active { 
   transition: all 0.2s ease-out !important;
 }
diff --git a/client/src/main.ts b/client/src/main.ts
index 55186bb..0e3a912 100644
--- a/client/src/main.ts
+++ b/client/src/main.ts
@@ -5,15 +5,15 @@ import './global-styles/mlfe.css';
 import './global-styles/transitions.css';
 import 'vue-toast-notification/dist/theme-default.css';
 
-import NicerForm from './components/inputs/NicerForm.vue';
-import PillBar from './components/inputs/PillBar.vue';
-import TextBox from './components/inputs/TextBox.vue';
-import EnumInput from './components/inputs/EnumInput.vue';
-import NumberBox from './components/inputs/NumberBox.vue';
-import MultilineTextBox from './components/inputs/MultilineTextBox.vue';
-import CheckBox from './components/inputs/CheckBox.vue';
-import SingleSelect from './components/inputs/SingleSelect.vue';
-import MultiSelect from './components/inputs/MultiSelect.vue';
+import NicerForm from './components/input/NicerForm.vue';
+import PillBar from './components/input/PillBar.vue';
+import TextBox from './components/input/TextBox.vue';
+import EnumInput from './components/input/EnumInput.vue';
+import NumberBox from './components/input/NumberBox.vue';
+import MultilineTextBox from './components/input/MultilineTextBox.vue';
+import CheckBox from './components/input/CheckBox.vue';
+import SingleSelect from './components/input/SingleSelect.vue';
+import MultiSelect from './components/input/MultiSelect.vue';
 import Heading from './components/display/Heading.vue';
 
 import { Form, Field, ErrorMessage  } from 'vee-validate';
diff --git a/client/src/pages/test.vue b/client/src/pages/test.vue
index 15f8f45..6e04a81 100644
--- a/client/src/pages/test.vue
+++ b/client/src/pages/test.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { SearchProvider, Options } from '../components/inputs/DropdownInput.vue';
+import { SearchProvider, Options } from '../components/input/DropdownInput.vue';
 
 const testValues: Options = {
   1: { display: 'Option 1' },
diff --git a/client/vite.config.ts b/client/vite.config.ts
index 29553ab..9c974cc 100644
--- a/client/vite.config.ts
+++ b/client/vite.config.ts
@@ -61,8 +61,8 @@ export default defineConfig({
       },
     }),
     Components({
-      extensions: ['vue', 'md'],
-      include: [/\.vue$/, /\.vue\?vue/, /\.md$/],
+      extensions: ['vue'],
+      include: [/\.vue$/, /\.vue\?vue/],
       dts: 'src/generated/components.d.ts',
       resolvers: [
         IconsResolver(),