From 7a32a1a3c650257a125acb297a4b0d1b3eefed71 Mon Sep 17 00:00:00 2001
From: Christopher Byrd <chrabyrd@gmail.com>
Date: Wed, 23 Apr 2025 16:28:24 -0500
Subject: [PATCH 01/11] adds Vue styleguide #481

---
 docs/developing/vue/arches-vue-styleguide.rst | 88 +++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 docs/developing/vue/arches-vue-styleguide.rst

diff --git a/docs/developing/vue/arches-vue-styleguide.rst b/docs/developing/vue/arches-vue-styleguide.rst
new file mode 100644
index 0000000..e19b553
--- /dev/null
+++ b/docs/developing/vue/arches-vue-styleguide.rst
@@ -0,0 +1,88 @@
+######################
+Arches Vue Style Guide
+######################
+
+This document extends the official Vue style guide with additional conventions and best practices tailored for our projects.
+
+Project Structure
+=================
+
+Naming Convention
+~~~~~~~~~~~~~~~~~
+
+- **Arches entity directories**  
+    Use plural, lowercase names (e.g., `cards/`, `widgets/`, `reports/`)
+
+- **Vue component directories**
+    `PascalCase/` (e.g., `CustomComponent/`)
+
+- **Non-Vue component directories**  
+    `kebab-case/` (e.g., `custom-utility/`, `custom-type/`)
+
+- **Vue components**  
+    `PascalCase.vue` (e.g., `CustomComponent.vue`)
+
+- **Utilities**  
+    `kebab-case.js` or `kebab-case.ts` (e.g., `custom-utility.js`)
+
+- **Type files**  
+    `kebab-case.ts` (e.g., `custom-type.ts`)
+
+
+Top-Level Structure
+~~~~~~~~~~~~~~~~~~~
+
+Top-level directories **must** align with Arches concepts (e.g., cards, widgets, reports) when such delineation is required. Otherwise, consolidate everything under a single app-level directory.
+
+
+.. code-block:: shell
+
+    # good
+
+    src/
+    └── project_name/
+        ├── plugins
+        ├── reports/
+        │   └── CustomReport/
+        │       ├── components
+        │       └── CustomReport.vue
+        ├── widgets
+        └── types
+        └── utils
+
+    # good
+
+    src/
+    └── project_name/
+        ├── components/
+        │   └── CustomComponent.vue
+        ├── CustomApplication.vue
+        ├── types
+        └── utils
+
+
+Component Folder Hierarchy
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At every level:
+
+- **Component files with sub-components** **must** reside in a folder named after the component.
+- **Dependent components** **must** live in a `components/` subdirectory within their **parent component's** folder.
+- **Shared components** (used by more than one parent) **must** be elevated to the `components/` directory at the level of the **highest parent component** that uses them.
+
+.. code-block:: shell
+
+    # good
+
+    src/project_name/
+    ├── CustomApplication.vue
+    └── components/
+        └── CustomDashboard/
+            ├── CustomDashboard.vue
+            └── components/
+                └── DashboardTable/
+                    └── DashboardTable.vue/
+                        └── components/
+                            ├── CustomHeader.vue
+                            ├── TableSection.vue
+                            └── UpdatedFooter.vue
\ No newline at end of file

From bcae1d73f9053b6845e14ac8e0026f5e23f6e959 Mon Sep 17 00:00:00 2001
From: Christopher Byrd <chrabyrd@gmail.com>
Date: Thu, 24 Apr 2025 15:42:09 -0500
Subject: [PATCH 02/11] cbyrd update vue styleguide and arches vue integration
 #481

---
 docs/developing/vue/arches-vue-integration.md | 425 ----------
 .../developing/vue/arches-vue-integration.rst | 104 +++
 docs/developing/vue/arches-vue-styleguide.rst | 761 +++++++++++++++++-
 3 files changed, 841 insertions(+), 449 deletions(-)
 delete mode 100644 docs/developing/vue/arches-vue-integration.md
 create mode 100644 docs/developing/vue/arches-vue-integration.rst

diff --git a/docs/developing/vue/arches-vue-integration.md b/docs/developing/vue/arches-vue-integration.md
deleted file mode 100644
index 47e08e8..0000000
--- a/docs/developing/vue/arches-vue-integration.md
+++ /dev/null
@@ -1,425 +0,0 @@
-# Arches Vue Integration Styleguide
-
-## Table of Contents
-
-- [Purpose](#purpose)
-- [Audience](#audience)
-- [Basis for this Style Guide](#basis-for-this-style-guide)
-- [Contributions](#contributions)
-- [Integrating a Vue Component](#integrating-a-vue-component)
-- [Single-Responsibility Principle and Component Decomposition](#single-responsibility-principle-and-component-decomposition)
-- [Directory Structure](#directory-structure)
-- [Cascading Style Sheets (CSS)](#cascading-style-sheets-css)
-- [Importing Components and Component Pathing Shorthand](#importing-components-and-component-pathing-shorthand)
-- [TypeScript and ESLint](#typescript-and-eslint)
-- [Internationalization (i18n)](#internationalization-i18n)
-- [Composition API and Single-file Components](#composition-api-and-single-file-components)
-- [Testing](#testing)
-- [Example Arches Vue Component Integration](#example-arches-vue-component-integration)
-
----
-
-## Purpose
-
-The purpose of this style guide is to establish a unified coding style and set of conventions that all contributors should adhere to when writing code for Arches. By following these guidelines, we aim to:
-
-- Improve code readability and maintainability
-- Facilitate collaboration among developers
-- Enhance the overall quality and consistency of Arches software, Arches projects, and Arches applications
-
-## Audience
-
-This style guide is intended for developers of all levels who contribute to Arches. Whether you are a seasoned developer or a newcomer to the project, this document will provide you with the necessary guidance to write clean, consistent, and high-quality code.
-
-## Basis for this Style Guide
-
-This style guide for Arches is built on top of the standard Vue.js and TypeScript style guides. As such, it inherits and extends the conventions and best practices outlined in those guides. 
-
-Any coding style, formatting, or conventions not explicitly covered in this document should be referenced from the official Vue.js and TypeScript style guides. It's important to maintain consistency with these standard guidelines to ensure compatibility and familiarity for developers working with Vue.js and TypeScript projects.
-
-For Vue.js, you can refer to the official style guide [here](https://vuejs.org/style-guide/). Similarly, for TypeScript, you can refer to the official TypeScript style guide [here](https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html).
-
-Please consult these references for any conventions or guidelines not addressed in this style guide.
-
-## Contributions
-
-This style guide is a living document that evolves over time. We welcome contributions from the community to improve and expand this guide further. If you have suggestions, feedback, or would like to contribute to the style guide, please reach out to us via the [Arches Forum](https://community.archesproject.org/).
-
----
-
-## Integrating a Vue Component
-
-When integrating Vue-based views, plugins, or reports into the Arches framework, developers should utilize the `createVueApplication` function provided at `utils/create-vue-application`. This function is specifically designed to facilitate the integration of Vue components within the Arches environment, ensuring seamless compatibility and optimal performance by abstracting interactions with the i18n API and various current and future Vue plugins, such as PrimeVue.
-
-However, it's important to note that while the `createVueApplication` function is suitable for integrating most Vue-based components, widgets require different render states and are not yet supported. As such, developers should exercise caution when attempting to integrate widgets using this function. We hope to resolve this in the near future.
-
-Example:
-
-```js
-import createVueApplication from 'utils/create-vue-application';
-import MyVueApplication from '@/MyVueApplication.vue';
-
-createVueApplication(MyVueApplication).then(vueApp => {
-    vueApp.mount('#my-vue-application-mounting-point');
-});
-```
-
-In the provided example, the createVueApplication function, imported from `utils/create-vue-application`, streamlines the integration process by handling the necessary setup and configuration steps, allowing developers to focus on building the core functionality of their Vue application.
-
-The `createVueApplication` function takes a Vue component (`MyVueApplication` in this case) as its argument, representing the root component of the Vue application. This component encapsulates the entire application logic and user interface.
-
-Once the Vue application is created using `createVueApplication`, it returns a Vue application instance (`vueApp`), which can then be further manipulated or customized as needed. In the example, the `vueApp` instance is mounted to a specific element in the DOM with the mount method, using the CSS selector `#my-vue-application-mounting-point` to identify the mounting point.
-
----
-
-## Single-Responsibility Principle and Component Decomposition
-
-In Vue development, it's crucial to adhere to the Single Responsibility Principle (SRP) and practice component decomposition to ensure that Vue components remain maintainable and scalable. The SRP dictates that each Vue component should have a single responsibility or purpose. By focusing on doing one thing and doing it well, components become easier to understand, modify, and maintain. Following the SRP leads to more modular, reusable, and testable code. 
-
-Component decomposition involves breaking down complex Vue components into smaller, more focused units, with each unit responsible for a specific task or feature. This practice aligns with the SRP and promotes clean, maintainable codebases.
-
-Example:
-
-```vue
-<script setup>
-import { ref } from 'vue';
-import { User } from '@/types/User';
-
-import UserProfileActions from '@/UserProfileActions.vue';
-import UserProfileBio from '@/UserProfileBio.vue';
-import UserProfileHeader from '@/UserProfileHeader.vue';
-
-const user = ref<User>({
-  name: 'John Doe',
-  email: 'john@example.com',
-  bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
-});
-</script>
-
-<template>
-  <div>
-    <UserProfileHeader :name="user.name" :email="user.email" />
-    <UserProfileBio :bio="user.bio" />
-    <UserProfileActions />
-  </div>
-</template>
-```
-
-In this example:
-
-- The `UserProfile` component is decomposed into three smaller components: `UserProfileHeader`, `UserProfileBio`, and `UserProfileActions`.
-- Each smaller component has a specific responsibility:
-    - `UserProfileHeader`: Renders the user's name and email.
-    - `UserProfileBio`: Renders the user's bio.
-    - `UserProfileActions`: Renders user actions (e.g., buttons for editing the profile).
-- The user reactive reference is defined using ref() within the `<script setup>` block and is accessible to all components within the template.
-- The `UserProfile` component integrates these smaller components directly in the template.
-- By decomposing the `UserProfile` component into smaller, focused components, we achieve better maintainability and reusability in our Vue application.
-
----
-
-## Directory Structure
-
-A well-organized directory structure provides clarity on where to find specific files and components, making it easier for developers to navigate the codebase, understand its architecture, and make modifications efficiently. In Arches Vue applications, we utilize a non-standard directory structure to organize components. 
-
-Example:
-
-- src/
-    - components/
-        - UserProfile/
-            - UserProfile.vue
-            - UserProfileActions.vue
-            - UserProfileBio.vue
-            - UserProfileHeader.vue
-        - Map/
-            - Map.vue
-            - MapHeader.vue
-            - MapSidebar.vue
-    - views
-        - UserProfileView.vue
-    - reports
-        - MapReport.vue
-    - widgets
-        - MapWidget.vue
-
-As Arches moves forward with integrating components from Vue into Knockout, we find it essential to adopt a non-standard directory structure to accommodate this scenario. For instance it's standard practice for most Vue applications to have a top-level `App.vue` file which has one or many child components that exist in the `components` directory. However since Arches will have multiple Vue applications running per project, possibly even per page, there must be some delineation between these top-level components. The pattern exemplified above illustrates a way to have such delineation while maintaining a scalable and navigable structure. Essentially, top-level components live in `views`, `reports`, `widgets`, etc, while their child components live in the `components` directory. The `components` subdirectories each contain a root component which is named the same as the subdirectory.
-
-By utilizing this directory structure, we ensure that components from Vue can seamlessly integrate with Knockout components while maintaining clarity and organization in our codebase. 
-
----
-
-## Cascading Style Sheets (CSS)
-
-TBD - This will be included once PrimeVue stylesheets and theme-switching have been enabled.
-
----
-
-## Importing Components and Component Pathing Shorthand
-
-In Vue projects, the `@` symbol serves as a special alias that represents the root directory, typically the `src` directory. Arches is no different. This shorthand notation allows us to eliminate relative pathing and reference files or modules within the `src` directory more succinctly and consistently. 
-
-For example, instead of specifying the relative path to a file like this:
-```
-import MyComponent from '../../components/MyComponent.vue';
-import MyTypeScriptFunction from '../../typescript/MyTypeScriptFunction.ts';
-```
-
-We instead use @ to reference the root directory and import the file like this:
-```
-import MyComponent from '@/components/MyComponent.vue';
-import MyTypeScriptFunction from '@/components/MyTypeScriptFunction.ts';
-```
-
-**It's important to note that Vue and TypeScript components must be imported with their file extensions (e.g., .vue or .ts).**
-
----
-
-## TypeScript and ESLint
-
-### Rationale
-
-We have integrated TypeScript and ESLint linting as essential components of our Vue development environment to enhance code quality, maintainability, and developer productivity. TypeScript provides strong typing capabilities, allowing for more robust code by catching errors during development and providing better IDE support with type inference and autocompletion. ESLint, on the other hand, enforces consistent coding styles and identifies potential errors or anti-patterns in the codebase, ensuring adherence to best practices and coding standards.
-
-### Enforcement
-
-While this integration brings significant benefits to our Vue projects, it's important to note that newly written components will be affected by TypeScript and ESLint linting rules. Developers will need to adhere to TypeScript typing conventions and ESLint rules when writing new components to ensure consistency and compliance with the established coding standards. This enforcement takes place in the `build_development`, `build_test`, and `build_production` npm processes. Previously written components will not be affected.
-
-We have also added the `eslint:check`, `eslint:fix`, `eslint:watch`, `ts:check`, and `ts:watch` npm scripts.
-
-### Separate Processes
-
-During development, developers should run the TypeScript and ESLint `:watch` linters in separate processes to ensure efficient linting of the current project. By running these linters in separately, each process is dedicated to linting the current project or application. However, it's important to note that if you're running multiple projects or applications concurrently, you'll need a separate process for each project to ensure accurate linting results. 
-
-For instance, if you're developing an Arches project and an Arches application, you will now likely have six concurrent processes: The project-level Django server, the project-level webpack development server, the project-level typescript watcher, the project-level eslint watcher, the application-level typescript watcher, and the application-level eslint watcher. Alternatively you could not run the eslint watcher nor the typescript watcher, and rely on the `build_development` and `build_production` for enforcement.
-
-### Frontend dependency declaration
-
-When adding any new frontend dependencies to your Arches project or application, it's important to declare their types in the `declarations.d.ts` file **if they do not already have TypeScript typing**. An reliable way to discern whether or not a dependency has typescript typing is to visit the [npm page](www.npmjs.com) for the dependency and look for the `TS` TypeScript badge. 
-
-This file serves as a central location for declaring global types and interfaces that are used across your project or application. Declaring types for frontend dependencies in `declarations.d.ts` ensures that TypeScript recognizes and understands the types provided by these modules, enabling accurate type checking and providing better IntelliSense support in your editor. 
-
-Example:
-```json
-# package.json
-    ...
-    "dependencies": {
-        "foo": "0.0.1",
-        ...
-    }
-    ...
-```
-
-```ts
-# src/declarations.d.ts
-    ...
-    declare module 'foo';
-
-```
-
----
-
-## Internationalization (i18n)
-
-We utilize the vue3-gettext library for internationalization (i18n) in Vue components. This library provides a convenient way to manage translations and localization within Arches.
-
-Below is an example code snippet demonstrating how we use vue3-gettext for i18n:
-
-```vue
-<script setup lang="ts">
-import { useGettext } from 'vue3-gettext';
-const { $gettext } = useGettext();
-
-console.log($gettext('Foo!'))
-</script>
-
-<template>
-    <h1 class="foo">{{ $gettext("Bar!") }}</h1>
-</template>
-```
-
-In this example, we import the `useGettext` function from vue3-gettext and destructure the `$gettext` method from the returned object. We then use `$gettext` to translate strings within our template, such as "Foo!" and "Bar!". The translations are managed by vue3-gettext and the `create-vue-application` component, and are dynamically loaded based on the selected locale.
-
-Before using internationalization features, it's important to run the following commands to extract and compile translations:
-
-Extract Translations: Run `npm run gettext:extract` to extract translations from the source code and generate template .pot files.
-Compile Translations: Run `npm run gettext:compile` to compile translated .po files into machine-readable .json files that can be used by the application.
-
-For further information, please reference the [vue3-gettext documentation](https://github.com/jshmrtn/vue3-gettext)
-
----
-
-## Composition API and Single-file Components
-
-We strongly suggest utilizing the Composition API and Single-file Components for building new features or rewriting existing components into Vue.
-
-### Composition API
-
-The Composition API is a way of organizing and reusing logic within Vue components. It allows developers to encapsulate related logic into reusable composition functions, making it easier to manage complex component logic and share code between components.
-
-
-### Single-file Components
-
-Single-file Components are a feature of Vue that allows developers to define templates, script, and styles in a single `.vue` file. This approach promotes a more modular and cohesive structure for Vue components, making it easier to manage component-specific logic, styles, and templates in a single file. 
-
-### Example
-Here's an example of a Single-file Component that uses the Composition API, notice the <script>, <template>, and <style> tags for a component exist in the same file:
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue';
-
-const count = ref(0);
-const increment = () => {
-  count.value++;
-};
-</script>
-
-<template>
-  <button @click="increment">Increment</button>
-  <p class="counter">Count: {{ count }}</p>
-</template>
-
-<style scoped>
-.counter {
-    color: red;
-}
-</style>
-
-```
-
----
-
-## Testing
-
-To ensure the reliability and functionality of our Vue components, we use `vitest` for our testing framework. `vitest` is a fast, modern testing framework that provides a comprehensive suite of tools for writing, running, and debugging tests.
-
-### Why Vitest?
-
-- **Speed**: `vitest` is designed to be fast, reducing the time it takes to run tests and increasing productivity.
-- **Integration**: We plan on eventually migrating our frontend bundler to `vite`, and already having `vitest` in-place will ensure a smooth transition.
-- **Modern Features**: `vitest` supports the latest JavaScript features, ensuring compatibility with contemporary development practices.
-
-### Writing Tests
-**Ensure your tests are placed alongside your components, and have a `.spec.ts` suffix.**
-
-When writing tests for your Vue components, consider the following best practices:
-
-- **Isolation**: Test each component in isolation to ensure that issues can be traced back to specific units of code.
-- **Coverage**: Aim for high test coverage to ensure all paths, including edge cases, are tested.
-- **Readability**: Write clear and concise tests that are easy to understand and maintain.
-
-Here is an example of how to write your tests:
-
-```vue
-<!-- src/ExampleComponent.vue -->
-
-<script setup lang="ts">
-import { useGettext } from 'vue3-gettext';
-const { $gettext } = useGettext();
-
-console.log($gettext('Hello from the <script> tag!'));
-</script>
-
-<template>
-   <h1 class="header">
-       {{ $gettext("Hello from the template!") }}
-   </h1>
-</template>
-
-<style scoped>
-.header {
-   color: red;
-}
-</style>
-```
-
-```js
-// src/ExampleComponent.spec.ts
-
-import { describe, it, expect } from 'vitest';
-import { mount } from '@vue/test-utils';
-
-import ExampleComponent from '@/ExampleComponent.vue';
-
-describe('ExampleComponent', () => {
-   it('renders correctly', () => {
-       const wrapper = mount(ExampleComponent);
-       expect(wrapper.exists()).toBeTruthy();
-   });
-
-   it('renders h1 element with correct text', () => {
-       const wrapper = mount(ExampleComponent);
-       expect(wrapper.find('h1').text()).toBe('Hello from the template!');
-   });
-
-   it('applies scoped styles to h1 element', () => {
-       const wrapper = mount(ExampleComponent);
-       const h1 = wrapper.find('h1');
-       expect(h1.classes()).toContain('header');
-   });
-});
-
-```
-
-### Running tests
-
-To run your tests, use the vitest command in your terminal:
-
-```bash
-npm run vitest
-```
-
-**By following this documentation, you can set up and maintain comprehensive unit and component testing that catches bugs early and improves code quality. For further details, refer to the [Vitest documentation](https://vitest.dev/).**
-
----
-
-## Example Arches Vue Component Integration
-
-Below is an example of creating a new plugin for Arches. This example includes import patterns, TypeScript patterns, internationalization, the composition API, single-file components, and Vue/Knockout integration
-
-```js
-// media/js/views/components/plugins/my-plugin.js
-
-import ko from 'knockout';
-import MyPlugin from '@/plugins/MyPlugin.vue';
-import createVueApplication from 'utils/create-vue-application';
-import MyPluginTemplate from 'templates/views/components/plugins/my-plugin.htm';
-
-
-ko.components.register('my-plugin', {
-    viewModel: function() {
-        createVueApplication(MyPlugin).then(vueApp => {
-            vueApp.mount('#my-plugin-mounting-point');
-        });
-    },
-    template: MyPluginTemplate,
-});
-
-```
-
-```htm
-// templates/views/components/plugins/my-plugin.htm
-
-<div id="my-plugin-mounting-point"></div>
-```
-
-```vue
-// src/plugins/MyPlugin.vue
-
-<script setup lang="ts">
-import { useGettext } from 'vue3-gettext';
-const { $gettext } = useGettext();
-
-console.log($gettext('Foo!'))
-</script>
-
-<template>
-    <h1 class="foo">{{ $gettext("Bar!") }}</h1>
-</template>
-
-<style scoped>
-.foo {
-    color: red;
-}
-</style>
-```
diff --git a/docs/developing/vue/arches-vue-integration.rst b/docs/developing/vue/arches-vue-integration.rst
new file mode 100644
index 0000000..296901e
--- /dev/null
+++ b/docs/developing/vue/arches-vue-integration.rst
@@ -0,0 +1,104 @@
+Arches Vue Integration Guide
+============================
+
+This guide explains how to embed a Vue 3 application into Arches using the
+``createVueApplication`` helper. This function bootstraps your app with:
+
+- Arches i18n (via vue3-gettext)  
+- PrimeVue + default theme  
+- Common services (confirmation, dialogs, toasts)  
+- Shared directives (tooltips, focus trap, scroll animations)  
+- Automatic dark-mode theme switching
+
+Supported Use Cases
+~~~~~~~~~~~~~~~~~~~
+
+- **Full-page views** (reports, dashboards)  
+- **Standalone plugins**  
+- **Knockout-embedded components**  
+
+Not yet supported: Arches “widgets” that require specialized render context.
+
+Quick Start
+~~~~~~~~~~~
+
+1. **Import** your root component and the helper:
+
+   .. code-block:: js
+
+       import createVueApplication from 'utils/create-vue-application'
+       import MyVueApp from '@/my_project/MyVueApp.vue'
+
+2. **Initialize** and **mount**:
+
+   .. code-block:: js
+
+       createVueApplication(MyVueApp)
+            .then(app => {
+                // Optional: register extra plugins or globalProperties here
+                app.mount('#my-vue-mount-point');
+            })
+            .catch(err => {
+                console.error('Vue integration failed:', err);
+            })
+
+3. **Ensure** your Arches template contains the mount point:
+
+   .. code-block:: html
+
+       <!-- In your Django/Knockout template -->
+       <div id="my-vue-mount-point"></div>
+
+Knockout Integration Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: js
+
+    // src/my_project/MyPlugin.vue
+
+    <script setup lang="ts">
+    import { onMounted } from 'vue';
+    import { useGettext } from 'vue3-gettext';
+
+    const { $gettext } = useGettext();
+
+    onMounted(() => {
+        console.log($gettext('Hello from the <script> tag!'));
+    });
+    </script>
+
+    <template>
+        <h1 class="header">
+            {{ $gettext("Hello from the template!") }}
+        </h1>
+    </template>
+
+    <style scoped>
+    .header {
+        color: red;
+    }
+    </style>
+
+.. code-block:: js
+
+    // media/js/views/components/plugins/my-plugin.js
+
+    import ko from 'knockout';
+    import createVueApplication from 'utils/create-vue-application';
+    import MyPlugin from '@/my_project/MyPlugin.vue';
+    import template from 'templates/views/components/plugins/my-plugin.htm';
+
+    ko.components.register('my-plugin', {
+        viewModel: function() {
+            createVueApplication(MyPlugin)
+                .then(vueApp => vueApp.mount('#my-plugin-mount'))
+                .catch(console.error)
+        },
+        template: template
+    });
+
+.. code-block:: html
+
+    <!-- templates/views/components/plugins.htm -->
+    
+    <div id="my-plugin-mount"></div>
\ No newline at end of file
diff --git a/docs/developing/vue/arches-vue-styleguide.rst b/docs/developing/vue/arches-vue-styleguide.rst
index e19b553..c9084ac 100644
--- a/docs/developing/vue/arches-vue-styleguide.rst
+++ b/docs/developing/vue/arches-vue-styleguide.rst
@@ -2,32 +2,64 @@
 Arches Vue Style Guide
 ######################
 
-This document extends the official Vue style guide with additional conventions and best practices tailored for our projects.
+This document extends and enhances the official Vue style guide, providing additional conventions and best practices tailored specifically for our Arches projects.
+
+Refer to the `official Vue style guide <https://vuejs.org/style-guide/>`_ for baseline standards.
+
+Purpose
+=======
+
+The purpose of this style guide is to establish a unified coding style and set of conventions that all contributors should adhere to when writing code for Arches. By following these guidelines, we aim to:
+
+- Improve code readability and maintainability
+- Facilitate collaboration among developers
+- Enhance the overall quality and consistency of Arches software, Arches projects, and Arches applications
+
+Basis for Style Guide
+=====================
+
+This style guide for Arches is built on top of the standard Vue.js and TypeScript style guides. As such, it inherits and extends the conventions and best practices outlined in those guides. 
+
+Any coding style, formatting, or conventions not explicitly covered in this document should be referenced from the official Vue.js and TypeScript style guides. It's important to maintain consistency with these standard guidelines to ensure compatibility and familiarity for developers working with Vue.js and TypeScript projects.
+
+For Vue.js, you can refer to the `official Vue style guide <https://vuejs.org/style-guide/>`_. 
+
+Similarly, for TypeScript, you can refer to the `official TypeScript style guide <https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html>`_.
+
+Contributions
+=============
+
+This style guide is a living document that evolves over time. We welcome contributions from the community to improve and expand this guide further. If you have suggestions, feedback, or would like to contribute to the style guide, please reach out to us via the `Arches Forum <https://community.archesproject.org/>`_.
 
 Project Structure
 =================
 
-Naming Convention
-~~~~~~~~~~~~~~~~~
-
-- **Arches entity directories**  
-    Use plural, lowercase names (e.g., `cards/`, `widgets/`, `reports/`)
+Naming Conventions
+~~~~~~~~~~~~~~~~~~
 
-- **Vue component directories**
-    `PascalCase/` (e.g., `CustomComponent/`)
+- **Arches entity directories**:
+  Use plural, lowercase names to reflect domain concepts.  
+  e.g. ``cards/``, ``widgets/``, ``reports/``
 
-- **Non-Vue component directories**  
-    `kebab-case/` (e.g., `custom-utility/`, `custom-type/`)
+- **Vue component directories**:  
+  One folder per component, named in PascalCase.  
+  e.g. ``CustomComponent/``
 
-- **Vue components**  
-    `PascalCase.vue` (e.g., `CustomComponent.vue`)
+- **Non-Vue component directories**:  
+  Utility or helper folders in kebab-case.  
+  e.g. ``custom-utility/``, ``date-utils/``
 
-- **Utilities**  
-    `kebab-case.js` or `kebab-case.ts` (e.g., `custom-utility.js`)
+- **Vue components**:  
+  File names in PascalCase with a ``.vue`` extension.  
+  e.g. ``UserCard.vue``, ``MapViewer.vue``
 
-- **Type files**  
-    `kebab-case.ts` (e.g., `custom-type.ts`)
+- **Utilities & helpers**:  
+  Use kebab-case, file extension ``.js`` or ``.ts``.  
+  e.g. ``fetch-api.ts``, ``format-date.js``
 
+- **Type files**:  
+  Single-purpose type definitions in kebab-case, ``.ts``.  
+  e.g. ``user-profile.ts``, ``map-types.ts``
 
 Top-Level Structure
 ~~~~~~~~~~~~~~~~~~~
@@ -37,8 +69,6 @@ Top-level directories **must** align with Arches concepts (e.g., cards, widgets,
 
 .. code-block:: shell
 
-    # good
-
     src/
     └── project_name/
         ├── plugins
@@ -48,9 +78,9 @@ Top-level directories **must** align with Arches concepts (e.g., cards, widgets,
         │       └── CustomReport.vue
         ├── widgets
         └── types
-        └── utils
+        └── utils.ts
 
-    # good
+.. code-block:: shell
 
     src/
     └── project_name/
@@ -58,7 +88,7 @@ Top-level directories **must** align with Arches concepts (e.g., cards, widgets,
         │   └── CustomComponent.vue
         ├── CustomApplication.vue
         ├── types
-        └── utils
+        └── utils.ts
 
 
 Component Folder Hierarchy
@@ -72,8 +102,6 @@ At every level:
 
 .. code-block:: shell
 
-    # good
-
     src/project_name/
     ├── CustomApplication.vue
     └── components/
@@ -85,4 +113,689 @@ At every level:
                         └── components/
                             ├── CustomHeader.vue
                             ├── TableSection.vue
-                            └── UpdatedFooter.vue
\ No newline at end of file
+                            └── UpdatedFooter.vue
+
+
+Component Structure
+===================
+
+Single-File Components
+~~~~~~~~~~~~~~~~~~~~~~
+
+Single-File Components (SFCs) are the preferred way to define Vue components. They encapsulate the template, script, and style in a single file, making it easier to manage and understand the component's structure.
+
+.. code-block:: js
+
+    <script setup lang="ts">
+    import { onMounted } from 'vue';
+    import { useGettext } from 'vue3-gettext';
+
+    const { $gettext } = useGettext();
+
+    onMounted(() => {
+        console.log($gettext('Hello from the <script> tag!'));
+    });
+    </script>
+
+    <template>
+        <h1 class="header">
+            {{ $gettext("Hello from the template!") }}
+        </h1>
+    </template>
+
+    <style scoped>
+    .header {
+        color: red;
+    }
+    </style>
+
+Component Decomposition
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Components should be decomposed into smaller, reusable components whenever possible. This promotes reusability and maintainability. Aim for a single responsibility per component.
+
+.. code-block:: shell
+
+    widgets/
+    └── CustomWidget/
+        ├── components/
+        │   ├── CustomWidgetEditor.vue
+        │   └── CustomWidgetViewer.vue
+        └── CustomWidget.vue
+
+Passing Data
+~~~~~~~~~~~~
+
+- **Fetch Proximity**:  
+  Fetch data in the component that actually renders it—don't lift network calls higher than needed.
+
+.. code-block:: js
+
+    <!-- Bad: fetching at a high-level parent when only the table needs it -->
+
+    <!-- Dashboard.vue -->
+    <script setup lang="ts">
+    import { ref, onMounted } from 'vue'
+    import UserTable from '@/my_project/Dashboard/components/UserTable.vue'
+
+    // Parent fetches users even if only UserTable displays them
+    const users = ref([])
+    onMounted(async () => {
+        users.value = await fetch('/api/users').then(resp => resp.json())
+    })
+    </script>
+
+    <template>
+        <div class="dashboard">
+            <h1>Dashboard</h1>
+            <!-- Data passed down via prop -->
+            <UserTable :users="users" />
+        </div>
+    </template>
+
+
+    <!-- Good: fetching as close as possible to where data is rendered -->
+
+    <!-- Dashboard.vue -->
+    <script setup lang="ts">
+    // Parent no longer fetches users
+    </script>
+
+    <template>
+        <div class="dashboard">
+            <h1>Dashboard</h1>
+            <!-- Child responsible for its own data -->
+            <UserTable />
+        </div>
+    </template>
+
+
+    <!-- UserTable.vue -->
+    <script setup lang="ts">
+    import { ref, onMounted } from 'vue'
+    import type { User } from '@/types'
+
+    // Fetch proximity: fetch here since this component renders the list
+    const users = ref<User[]>([])
+    onMounted(async () => {
+        users.value = await fetch('/api/users').then(resp => resp.json())
+    })
+    </script>
+
+    <template>
+        <table>
+            <tbody>
+                <tr v-for="user in users" :key="user.id">
+                    <td>{{ user.name }}</td>
+                    <td>{{ user.email }}</td>
+                </tr>
+            </tbody>
+        </table>
+    </template>
+
+- **Primitives First**:  
+  Pass simple values (strings, numbers, booleans, small arrays/objects) instead of entire model objects whenever possible.
+
+.. code-block:: html
+
+    <!-- Bad: passing entire model objects -->
+    <UserProfile :user="currentUser" />
+
+    <!-- Good: passing only primitive values -->
+    <UserProfile
+        :user-id="currentUser.id"
+        :user-name="currentUser.name"
+        :is-admin="currentUser.isAdmin"
+    />
+
+- **Derived State**:  
+  Compute any summaries or transformations in the consumer component and pass those primitives down.
+
+.. code-block:: js
+
+    <!-- ParentComponent.vue -->
+    <script setup lang="ts">
+    import { ref, computed, onMounted } from 'vue'
+    import type { Order } from '@/types'
+
+    // Raw data fetched here
+    const orders = ref<Order[]>([])
+    onMounted(async () => {
+        orders.value = await fetch('/api/orders').then(r => r.json())
+    })
+
+    // Derived state: compute primitives
+    const orderCount = computed(() => orders.value.length)
+    const totalSales = computed(() =>
+        orders.value.reduce((sum, order) => sum + order.amount, 0)
+    )
+    </script>
+
+    <template>
+        <!-- Pass only the computed primitives -->
+        <OrderSummary
+            :count="orderCount"
+            :total-sales="totalSales"
+        />
+    </template>
+
+    <!-- OrderSummary.vue -->
+    <script setup lang="ts">
+    const props = defineProps<{
+        count: number
+        totalSales: number
+    }>()
+    </script>
+
+    <template>
+        <div class="order-summary">
+            <p>Total Orders: {{ props.count }}</p>
+            <p>Total Sales: {{ props.totalSales }}</p>
+        </div>
+    </template>
+
+- **Event Emission**:  
+  Emit semantic events (kebab-case) with typed payloads:
+
+.. code-block:: js
+
+    <script setup lang="ts">
+    interface RowSelectedEvent { rowId: number }
+
+    defineEmits<{
+        (e: 'row-selected', payload: RowSelectedEvent): void
+    }>()
+
+    function onRowClick(id: number) {
+        emit('row-selected', { rowId: id })
+    }
+    </script>
+
+- **Slots**:  
+  Use scoped slots for maximum flexibility; name them clearly
+
+.. code-block:: html
+
+    <MyTable>
+        <template #header>
+            {{ $gettext('Table Header') }}
+        </template>
+        <template #row="{ row }">
+            <MyRow :data="row" />
+        </template>
+    </MyTable>
+
+
+The `<script>` Tag
+==================
+
+This block defines a component's logic. Follow these rules for clarity, consistency, and maintainability.
+
+Coding Standards
+~~~~~~~~~~~~~~~~
+
+- **Script Scope**:  
+  All component logic **must** reside within `<script setup>`—no module-scope side-effects.
+
+- **Function Declarations**:  
+    - Use named `function` declarations for component methods; **do not** use anonymous functions or function expressions.
+    - Use of anonymous functions is allowed within parent functions (eg `setTimeout`, `Promise.then`, `filter`, `onMounted`, `computed`, etc.).
+
+- **Constants & Literals**:  
+    - Declare fixed values in `SCREAMING_SNAKE_CASE`.  
+    - Extract all string literals and magic numbers into named constants.
+
+- **Naming Conventions**:  
+  Use descriptive identifiers; avoid single-letter names.
+
+- **Modularity & Reuse**:  
+  Extract non-UI logic (data transformations, business rules) into composables or utility modules.  
+
+- **Side-Effects & Async Handling**:  
+    - No side-effects in the `<script>` tag. Encapsulate API calls, formatting logic, and other side-effects in lifecycle hooks or composables.
+    - Wrap all async operations in `try/catch`, and surface or display errors appropriately.
+
+- **Type Safety**:  
+  Import and use explicit types; avoid `any`. Annotate all function return types.
+
+Import Pathing
+~~~~~~~~~~~~~~
+
+**Use project alias** (`@/…`) for all local imports; avoid raw relative paths. e.g. 
+
+.. code-block:: js
+
+    // Bad: raw relative path
+    import { fetchData } from '../../utils/fetch-data.ts'
+    
+    // Good: project alias
+    import { fetchData } from '@/project_name/utils/fetch-data.ts' 
+
+Import Order
+~~~~~~~~~~~~~
+
+Import lines should be grouped and ordered as follows:
+
+1. **Vue core**  
+2. **Third-party modules**  
+3. **Third-party Vue components**  
+4. **Local Vue components**  
+5. **Local utilities/composables**  
+6. **Third-party types**  
+7. **Local types**  
+
+.. code-block:: js
+
+    <script setup lang="ts">
+    // 1. Vue core
+    import { ref, computed } from 'vue'
+
+    // 2. Third-party modules
+    import { useGettext } from 'vue3-gettext'
+
+    // 3. Third-party Vue components
+    import { ProgressSpinner } from 'primevue/progressspinner'
+
+    // 4. Local Vue components
+    import MyComponent from '@/project_name/components/MyComponent.vue'
+
+    // 5. Local utilities/composables
+    import { fetchData } from '@/project_name/utils/fetchData.ts'
+
+    // 6. Third-party types
+    import type { Component } from 'vue'
+
+    // 7. Local types
+    import type { UserProfile } from '@/project_name/types.ts'
+
+    // Your component logic here
+    </script>
+
+Declaration Order
+~~~~~~~~~~~~~~~~~
+
+Within your `<script setup>` block, organize declarations in this sequence. Omit any steps that don’t apply.
+
+1. **`defineProps`**  
+2. **`defineEmits` / `defineExpose`**  
+3. **Composables instantiation**:  
+   e.g. `const { $gettext } = useGettext()`  
+4. **Dependency injection**:  
+   e.g. `const api = inject('apiClient')!`  
+5. **Constants & configuration**:  
+   - SCREAMING_SNAKE_CASE for truly constant values  
+6. **Reactive state**:  
+   - `const foo = ref(...)`  
+7. **Computed properties**  
+8. **Watches**  
+9. **Lifecycle hooks**:  
+   e.g. `onMounted()`, `onBeforeUnmount()`  
+10. **Methods / functions**  
+
+.. code-block:: js
+
+    <script setup lang="ts">
+    import { ref, computed, watch, onMounted, inject } from 'vue';
+    import { useGettext } from 'vue3-gettext';
+    import type { Item } from '@/project_name/types';
+
+    // 1. defineProps
+    const props = defineProps<{ id: number }>();
+
+    // 2. defineEmits
+    const emit = defineEmits<{ (e: 'loaded'): void }>();
+
+    // 3. Composables instantiation
+    const { $gettext } = useGettext();
+
+    // 4. Dependency injection
+    const api = inject('apiClient')!;
+
+    // 5. Constants & configuration
+    const POLL_MS = 5000;
+
+    // 6. Reactive state
+    const data = ref<Item[]>([]);
+    const isLoading = ref(true);
+
+    // 7. Computed properties
+    const hasData = computed(() => data.value.length > 0);
+
+    // 8. Watches
+    watch(() => props.id, loadData, { immediate: true });
+
+    // 9. Lifecycle hooks
+    onMounted(() => {
+      loadData();
+    });
+
+    // 10. Methods / functions
+    async function loadData() {
+      try {
+        isLoading.value = true;
+        data.value = await api.fetchItems(props.id);
+      } catch (err) {
+        console.error(err);
+      } finally {
+        isLoading.value = false;
+        emit('loaded');
+      }
+    }
+    </script>
+
+
+The `<template>` Tag
+====================
+
+Defines the component's UI. Keep templates clear, consistent, and easy to scan.
+
+Attribute Ordering & Formatting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When declaring attributes in your `<template>`, group and order them as follows. Within each group, sort attributes alphabetically.
+
+1. **Directives** (e.g. `v-for`, `v-if`)  
+2. **Slots** (e.g. `v-slot:header="…"` )
+3. **Static attributes** (e.g. `id`, `class`)  
+4. **Dynamic props** (e.g. `:prop="…"` )  
+5. **Event listeners** (e.g. `@click="…"` )  
+6. **Modifiers** (e.g. `@click.prevent="…"` )  
+
+Formatting rules:
+
+- **Inline vs. Multiline**  
+    - **One attribute** → keep on the same line as the tag.  
+    - **Multiple attributes** → one per line, indented under the tag.  
+- **Explicit assignment**  
+    - Always write `prop="value"` or `:prop="value"`.  
+    - Do **not** use shorthand (`:prop` without value) or omit values.  
+- **Kebab-case**  
+    - All attribute names (including custom props and events) **must** use kebab-case.
+
+.. code-block:: html
+
+    <!-- Good: grouped, ordered, multiline, kebab-case -->
+    <UserCard
+        v-if="isVisible"
+        v-slot:default="{ user }"
+        id="user-card"
+        class="card highlight"
+        :avatar-url="user.avatarUrl"
+        :is-active="user.isActive"
+        @mouseover="onHover"
+        @submit.prevent="onSubmit"
+    />
+
+    <!-- Bad: unordered, inline, camelCase -->
+    <UserCard id="userCard" :avatarUrl="user.avatarUrl" @submit.prevent="onSubmit" v-if="isVisible"/>
+
+Self-Closing Tags
+~~~~~~~~~~~~~~~~~
+
+Use self-closing syntax for elements or components without children:
+
+.. code-block:: html
+
+    <template>
+        <LogoIcon />
+        <img src="@/assets/logo.png" alt="Logo" />
+    </template>
+
+Logic in Templates
+~~~~~~~~~~~~~~~~~~
+
+- **No complex logic**  
+    - Avoid ternaries, chained method calls, or heavy expressions.  
+    - Move conditions and transformations into `computed` or methods.  
+
+.. code-block:: html
+
+    <!-- Good: simple v-if, logic lives in computed -->
+    <template>
+        <div v-if="isVisible">{{ displayText }}</div>
+    </template>
+
+    <!-- Bad: inline ternary and method call -->
+    <template>
+        <div>{{ isVisible ? formatText(user.name) : '—' }}</div>
+    </template>
+
+Text in Templates
+~~~~~~~~~~~~~~~~~
+
+- **Internationalization**  
+  - Wrap all user-facing strings with `$gettext()`.  
+  - Avoid string concatenation; use formatting placeholders.
+
+- **No loose text nodes**  
+  - Surround plain text with an inline element (e.g., `<span>`) or semantic tag.  
+
+.. code-block:: html
+
+    <!-- Good -->
+    <template>
+        <div>
+            <span>{{ $gettext('Hello, world!') }}</span>
+            
+            <Button @click="handleClick">
+                {{ $gettext('Click me!') }}
+            </Button>
+        </div>
+    </template>
+
+    <!-- Bad: unwrapped text node -->
+    <template>
+        <div>
+            {{ $gettext('Hello, world!') }}
+
+            <Button @click="handleClick">
+                {{ $gettext('Click me!') }}
+            </Button>
+        </div>
+    </template>
+
+The `<style>` Tag
+=================
+
+Defines component-scoped CSS. Follow these rules for responsive, maintainable, and themeable styles.
+
+Scope
+~~~~~
+
+- **Scoped styles**  
+    - Prefer to use `<style scoped>` to ensure styles are applied only to the component.  
+    - Reserve global styles and design tokens for your global CSS or theme files unless absolutely necessary.
+
+Layout Patterns
+~~~~~~~~~~~~~~~
+
+- **Flexbox & Grid only**  
+    Use `display: flex` for one-dimensional layouts and `display: grid` for two-dimensional arrangements.  
+- **Use `gap`**  
+    Space items with `gap`; do **not** rely on margins for core layout.  
+- **No legacy hacks**  
+    Never use `float`, `inline-block`, or other outdated techniques.
+
+Units & Sizing
+~~~~~~~~~~~~~~
+
+- **`rem` for nearly everything**  
+    Use `rem` units for spacing, typography, gaps, borders, and other dimensional values.
+
+- **Viewport units sparingly**  
+    Reserve `vh`/`vw` for elements that must span the viewport (e.g., full-screen sections or modals).
+
+- **Percentages for fluid layouts**  
+    Apply `%` when you need relative sizing (e.g., fluid widths in responsive grids).
+
+- **No `px`**  
+    Avoid `px` units entirely to ensure scalability, accessibility, and consistent theming.
+
+Offsets & Positioning
+~~~~~~~~~~~~~~~~~~~~~
+- **No hard-coding single-side offsets**  
+    Instead of using `margin-left`, `margin-top`, etc., use logical properties like `margin-inline-start` and `margin-block-start`. This ensures proper alignment in different writing modes.
+
+.. code-block:: css
+
+    /* Bad */
+    .Overlay {
+        margin-right: 2rem;
+    }
+
+    /* Good */
+    <style scoped>
+        .Overlay {
+            margin-inline-end: 2rem;
+        }
+    </style>
+
+- **No negative margins**  
+    Negative `margin-*` values are forbidden.
+
+No `calc()`
+~~~~~~~~~~~
+
+- The `calc()` function is forbidden in component styles.
+
+Theming & Colors
+~~~~~~~~~~~~~~~~
+
+- **No hard-coded colors or shadows**  
+    Prefer to reference design tokens, e.g. `var(--theme-primary)`, `var(--shadow-level-1)`.  
+- **Centralize tokens**  
+    Define colors, typography, spacing scales, and breakpoints in your theme files.
+
+Selector Naming
+~~~~~~~~~~~~~~~
+
+- **Dot-delineated hierarchy**  
+    Prefix selectors with the component's root class, then chain child class names:
+
+.. code-block:: css
+
+    <style scoped>
+        .user-card {
+            display: flex;
+            flex-direction: column;
+            gap: 1rem;
+        }
+        .user-card.header {
+            display: grid;
+            grid-template-columns: 1fr auto;
+            gap: 0.5rem;
+        }
+        .user-card.header.title {
+            font-size: 1.5rem;
+            color: var(--theme-primary);
+        }
+    </style>
+
+
+Testing
+=======
+
+To ensure the reliability and functionality of our Vue components, we use **Vitest** together with **Vue Test Utils**. Vitest is a fast, modern test runner that integrates seamlessly with Vite, while Vue Test Utils provides utilities to mount components and inspect their rendered output.
+
+Test Location & Naming
+~~~~~~~~~~~~~~~~~~~~~~
+
+- Co-locate tests next to components, in the same directory.  
+- Test files must end with a ``.spec.ts`` suffix.  
+- Example structure:
+
+  .. code-block:: shell
+
+      src/
+      └── my_project/
+            ├── CustomApplication.vue
+            ├── CustomApplication.spec.ts
+            ├── utils.ts
+            ├── utils.spec.ts
+            ├── widgets/
+            │   └── CustomWidget/
+            │       ├── CustomWidget.vue
+            │       └── CustomWidget.spec.ts
+            └── reports/
+                └── CustomReport/
+                    ├── CustomReport.vue
+                    └── CustomReport.spec.ts
+
+Writing Tests
+~~~~~~~~~~~~~
+
+When crafting your tests, adhere to these best practices:
+
+- **Isolation**  
+  Mount each component on its own—stub or mock child components to pinpoint issues precisely.
+
+- **Coverage**  
+  Cover all code paths, including edge cases (error states, conditional rendering, emitted events).
+
+- **Readability**  
+  Use clear, descriptive test names and group related tests with ``describe`` blocks.
+
+- **Async Handling**  
+  Use ``flushPromises`` or ``await nextTick()`` after triggering asynchronous updates.
+
+- **Cleanup**  
+  Unmount or destroy wrappers if they persist between tests (though Vitest's JSDOM resets per test by default).
+
+.. code-block:: js
+
+    <!-- src/components/CounterButton.vue -->
+    <script setup lang="ts">
+    import { ref } from 'vue';
+
+    const count = ref(0);
+    function increment() {
+        count.value++;
+    }
+    </script>
+
+    <template>
+        <button @click="increment" class="counter">
+            Count: {{ count }}
+        </button>
+    </template>
+
+    <style scoped>
+    .counter { padding: 0.5rem 1rem; }
+    </style>
+
+.. code-block:: js
+
+    // src/components/CounterButton.spec.ts
+    import { describe, it, expect } from 'vitest'
+    import { mount, flushPromises } from '@vue/test-utils'
+    import CounterButton from './CounterButton.vue'
+
+    describe('CounterButton.vue', () => {
+        it('mounts and displays initial count', () => {
+            const wrapper = mount(CounterButton);
+            expect(wrapper.text()).toContain('Count: 0');
+        });
+
+        it('increments count on click', async () => {
+            const wrapper = mount(CounterButton);
+            const button = wrapper.find('button');
+            await button.trigger('click');
+            await flushPromises();
+            expect(wrapper.text()).toContain('Count: 1');
+        });
+    });
+
+Running Tests
+~~~~~~~~~~~~~
+
+Use the following npm scripts in your terminal:
+
+.. code-block:: shell
+
+    # Run all tests once
+    npm run vitest
+
+    # Run a specific test file
+    npm run vitest -- src/components/CounterButton.spec.ts
+
+Coverage output will appear under ``coverage/``, showing per-file metrics and highlighting untested lines.

From 24b108f7d78243295362e05b93d5feeec606ce98 Mon Sep 17 00:00:00 2001
From: Christopher Byrd <chrabyrd@gmail.com>
Date: Thu, 24 Apr 2025 16:19:37 -0500
Subject: [PATCH 03/11] nit #481

---
 docs/developing/vue/arches-vue-styleguide.rst | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/docs/developing/vue/arches-vue-styleguide.rst b/docs/developing/vue/arches-vue-styleguide.rst
index c9084ac..ea4c299 100644
--- a/docs/developing/vue/arches-vue-styleguide.rst
+++ b/docs/developing/vue/arches-vue-styleguide.rst
@@ -2,10 +2,6 @@
 Arches Vue Style Guide
 ######################
 
-This document extends and enhances the official Vue style guide, providing additional conventions and best practices tailored specifically for our Arches projects.
-
-Refer to the `official Vue style guide <https://vuejs.org/style-guide/>`_ for baseline standards.
-
 Purpose
 =======
 

From 2c1c1a51963f32b0e92ec1aacc3a6fa9ee349786 Mon Sep 17 00:00:00 2001
From: Christopher Byrd <chrabyrd@gmail.com>
Date: Thu, 24 Apr 2025 16:21:13 -0500
Subject: [PATCH 04/11] nit #481

---
 docs/developing/vue/arches-vue-integration.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/developing/vue/arches-vue-integration.rst b/docs/developing/vue/arches-vue-integration.rst
index 296901e..aabd307 100644
--- a/docs/developing/vue/arches-vue-integration.rst
+++ b/docs/developing/vue/arches-vue-integration.rst
@@ -1,5 +1,6 @@
+############################
 Arches Vue Integration Guide
-============================
+############################
 
 This guide explains how to embed a Vue 3 application into Arches using the
 ``createVueApplication`` helper. This function bootstraps your app with:
@@ -11,7 +12,7 @@ This guide explains how to embed a Vue 3 application into Arches using the
 - Automatic dark-mode theme switching
 
 Supported Use Cases
-~~~~~~~~~~~~~~~~~~~
+===================
 
 - **Full-page views** (reports, dashboards)  
 - **Standalone plugins**  
@@ -20,7 +21,7 @@ Supported Use Cases
 Not yet supported: Arches “widgets” that require specialized render context.
 
 Quick Start
-~~~~~~~~~~~
+===========
 
 1. **Import** your root component and the helper:
 
@@ -50,7 +51,7 @@ Quick Start
        <div id="my-vue-mount-point"></div>
 
 Knockout Integration Example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============================
 
 .. code-block:: js
 

From 1196c70cd52e77cf9ce66183de2dca8778e4e630 Mon Sep 17 00:00:00 2001
From: Christopher Byrd <chrabyrd@gmail.com>
Date: Thu, 24 Apr 2025 16:25:14 -0500
Subject: [PATCH 05/11] nit #481

---
 docs/developing/vue/arches-vue-styleguide.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/developing/vue/arches-vue-styleguide.rst b/docs/developing/vue/arches-vue-styleguide.rst
index ea4c299..596155d 100644
--- a/docs/developing/vue/arches-vue-styleguide.rst
+++ b/docs/developing/vue/arches-vue-styleguide.rst
@@ -657,8 +657,8 @@ No `calc()`
 Theming & Colors
 ~~~~~~~~~~~~~~~~
 
-- **No hard-coded colors or shadows**  
-    Prefer to reference design tokens, e.g. `var(--theme-primary)`, `var(--shadow-level-1)`.  
+- **No hard-coded colors**  
+    Prefer to reference design tokens, e.g. `var(--theme-primary)`.  
 - **Centralize tokens**  
     Define colors, typography, spacing scales, and breakpoints in your theme files.
 
@@ -764,7 +764,7 @@ When crafting your tests, adhere to these best practices:
     // src/components/CounterButton.spec.ts
     import { describe, it, expect } from 'vitest'
     import { mount, flushPromises } from '@vue/test-utils'
-    import CounterButton from './CounterButton.vue'
+    import CounterButton from '@/my_project/components/CounterButton.vue'
 
     describe('CounterButton.vue', () => {
         it('mounts and displays initial count', () => {

From bdc49bccddcc1f06efe6c181b86587e9aa7c5338 Mon Sep 17 00:00:00 2001
From: Christopher Byrd <chrabyrd@gmail.com>
Date: Thu, 24 Apr 2025 16:34:29 -0500
Subject: [PATCH 06/11] nit #481

---
 docs/developing/vue/arches-vue-styleguide.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/developing/vue/arches-vue-styleguide.rst b/docs/developing/vue/arches-vue-styleguide.rst
index 596155d..6722471 100644
--- a/docs/developing/vue/arches-vue-styleguide.rst
+++ b/docs/developing/vue/arches-vue-styleguide.rst
@@ -163,7 +163,7 @@ Passing Data
 ~~~~~~~~~~~~
 
 - **Fetch Proximity**:  
-  Fetch data in the component that actually renders it—don't lift network calls higher than needed.
+  Fetch data in the component that actually renders it. Don't lift network calls higher than needed.
 
 .. code-block:: js
 
@@ -339,7 +339,8 @@ Coding Standards
 
 - **Constants & Literals**:  
     - Declare fixed values in `SCREAMING_SNAKE_CASE`.  
-    - Extract all string literals and magic numbers into named constants.
+    - Declare all string literals and magic numbers as named constants.
+      eg `const POLL_MS = 5000;` 
 
 - **Naming Conventions**:  
   Use descriptive identifiers; avoid single-letter names.

From 5e02af1928fdbe17a2390570416bafcb4d3734ee Mon Sep 17 00:00:00 2001
From: Christopher Byrd <chrabyrd@gmail.com>
Date: Thu, 24 Apr 2025 16:39:04 -0500
Subject: [PATCH 07/11] nit #481

---
 docs/developing/vue/arches-vue-styleguide.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/developing/vue/arches-vue-styleguide.rst b/docs/developing/vue/arches-vue-styleguide.rst
index 6722471..262b516 100644
--- a/docs/developing/vue/arches-vue-styleguide.rst
+++ b/docs/developing/vue/arches-vue-styleguide.rst
@@ -335,12 +335,12 @@ Coding Standards
 
 - **Function Declarations**:  
     - Use named `function` declarations for component methods; **do not** use anonymous functions or function expressions.
-    - Use of anonymous functions is allowed within parent functions (eg `setTimeout`, `Promise.then`, `filter`, `onMounted`, `computed`, etc.).
+    - Use of anonymous functions is allowed within parent functions (e.g., `setTimeout`, `Promise.then`, `filter`, `onMounted`, `computed`, etc.).
 
 - **Constants & Literals**:  
     - Declare fixed values in `SCREAMING_SNAKE_CASE`.  
     - Declare all string literals and magic numbers as named constants.
-      eg `const POLL_MS = 5000;` 
+      e.g. `const POLL_MS = 5000;` 
 
 - **Naming Conventions**:  
   Use descriptive identifiers; avoid single-letter names.
@@ -420,9 +420,9 @@ Within your `<script setup>` block, organize declarations in this sequence. Omit
 4. **Dependency injection**:  
    e.g. `const api = inject('apiClient')!`  
 5. **Constants & configuration**:  
-   - SCREAMING_SNAKE_CASE for truly constant values  
+   e.g. `const POLL_MS = 5000`
 6. **Reactive state**:  
-   - `const foo = ref(...)`  
+   e.g. `const foo = ref(...)`  
 7. **Computed properties**  
 8. **Watches**  
 9. **Lifecycle hooks**:  

From 18ec35aa7d10a372628b45d642bf0108ccfcaa25 Mon Sep 17 00:00:00 2001
From: Christopher Byrd <chrabyrd@gmail.com>
Date: Mon, 19 May 2025 15:27:42 -0700
Subject: [PATCH 08/11] PR feedback #481

---
 docs/developing/index.rst                     |    7 +
 .../developing/vue/arches-vue-integration.rst |    4 +-
 docs/developing/vue/arches-vue-styleguide.rst | 1021 +++++++++++------
 requirements.txt                              |    1 +
 4 files changed, 679 insertions(+), 354 deletions(-)

diff --git a/docs/developing/index.rst b/docs/developing/index.rst
index 10a94f7..17075c8 100644
--- a/docs/developing/index.rst
+++ b/docs/developing/index.rst
@@ -20,6 +20,13 @@ If you are considering software development to customize Arches, please read the
 
     django-devs/orm-start
 
+.. toctree::
+    :caption: Orientation for Frontend Developers
+    :maxdepth: 2
+
+    vue/arches-vue-integration
+    vue/arches-vue-styleguide
+
 .. toctree::
     :caption: Reference Guide
     :maxdepth: 2
diff --git a/docs/developing/vue/arches-vue-integration.rst b/docs/developing/vue/arches-vue-integration.rst
index aabd307..5794340 100644
--- a/docs/developing/vue/arches-vue-integration.rst
+++ b/docs/developing/vue/arches-vue-integration.rst
@@ -5,7 +5,7 @@ Arches Vue Integration Guide
 This guide explains how to embed a Vue 3 application into Arches using the
 ``createVueApplication`` helper. This function bootstraps your app with:
 
-- Arches i18n (via vue3-gettext)  
+- Arches frontend internationalization (i18n) via vue3-gettext
 - PrimeVue + default theme  
 - Common services (confirmation, dialogs, toasts)  
 - Shared directives (tooltips, focus trap, scroll animations)  
@@ -53,7 +53,7 @@ Quick Start
 Knockout Integration Example
 ============================
 
-.. code-block:: js
+.. code-block:: vue
 
     // src/my_project/MyPlugin.vue
 
diff --git a/docs/developing/vue/arches-vue-styleguide.rst b/docs/developing/vue/arches-vue-styleguide.rst
index 262b516..d29e9bd 100644
--- a/docs/developing/vue/arches-vue-styleguide.rst
+++ b/docs/developing/vue/arches-vue-styleguide.rst
@@ -27,41 +27,40 @@ Contributions
 
 This style guide is a living document that evolves over time. We welcome contributions from the community to improve and expand this guide further. If you have suggestions, feedback, or would like to contribute to the style guide, please reach out to us via the `Arches Forum <https://community.archesproject.org/>`_.
 
-Project Structure
-=================
+Frontend Structure
+==================
 
-Naming Conventions
-~~~~~~~~~~~~~~~~~~
+File and Folder Naming Conventions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- **Arches entity directories**:
-  Use plural, lowercase names to reflect domain concepts.  
-  e.g. ``cards/``, ``widgets/``, ``reports/``
+- **Arches entity directories**
+    - Use plural, lowercase names to reflect domain concepts.  
+    - e.g. ``cards/``, ``widgets/``, ``reports/``
 
-- **Vue component directories**:  
-  One folder per component, named in PascalCase.  
-  e.g. ``CustomComponent/``
+- **Vue component directories**
+    - One folder per component, named in PascalCase.  
+    - e.g. ``CustomComponent/``
 
-- **Non-Vue component directories**:  
-  Utility or helper folders in kebab-case.  
-  e.g. ``custom-utility/``, ``date-utils/``
+- **Non-Vue component directories**
+    - Utility or helper folders in kebab-case.  
+    - e.g. ``custom-utility/``, ``date-utils/``
 
-- **Vue components**:  
-  File names in PascalCase with a ``.vue`` extension.  
-  e.g. ``UserCard.vue``, ``MapViewer.vue``
+- **Vue components**
+    - File names in PascalCase with a ``.vue`` extension.  
+    - e.g. ``UserCard.vue``, ``MapViewer.vue``
 
-- **Utilities & helpers**:  
-  Use kebab-case, file extension ``.js`` or ``.ts``.  
-  e.g. ``fetch-api.ts``, ``format-date.js``
+- **Utilities & helpers** 
+    - Use kebab-case, file extension ``.js`` or ``.ts``.  
+    - e.g. ``fetch-api.ts``, ``format-date.js``
 
-- **Type files**:  
-  Single-purpose type definitions in kebab-case, ``.ts``.  
-  e.g. ``user-profile.ts``, ``map-types.ts``
+- **Type files** 
+    - Single-purpose type definitions in kebab-case, ``.ts``.  
+    - e.g. ``user-profile.ts``, ``map-types.ts``
 
 Top-Level Structure
 ~~~~~~~~~~~~~~~~~~~
 
-Top-level directories **must** align with Arches concepts (e.g., cards, widgets, reports) when such delineation is required. Otherwise, consolidate everything under a single app-level directory.
-
+- Top-level directories **must** align with Arches concepts (e.g., cards, widgets, reports) when such delineation is required. Otherwise, consolidate everything under a single app-level directory.
 
 .. code-block:: shell
 
@@ -86,15 +85,17 @@ Top-level directories **must** align with Arches concepts (e.g., cards, widgets,
         ├── types
         └── utils.ts
 
+- **Why?**
+    - **Standardization**: Consistent naming and structure make it easier for developers to navigate the codebase.
+    - **Organization**: Grouping related components together makes it easier to find and manage them.
 
 Component Folder Hierarchy
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-At every level:
-
-- **Component files with sub-components** **must** reside in a folder named after the component.
-- **Dependent components** **must** live in a `components/` subdirectory within their **parent component's** folder.
-- **Shared components** (used by more than one parent) **must** be elevated to the `components/` directory at the level of the **highest parent component** that uses them.
+- At every level:
+    - **Component files with sub-components** **must** reside in a folder named after the component.
+    - **Dependent components** **must** live in a `components/` subdirectory within their **parent component's** folder.
+    - **Shared components** (used by more than one parent) **must** be elevated to the `components/` directory at the level of the **highest parent component** that uses them.
 
 .. code-block:: shell
 
@@ -111,6 +112,9 @@ At every level:
                             ├── TableSection.vue
                             └── UpdatedFooter.vue
 
+- **Why?**
+    - **Clarity**: Each component's folder contains everything it needs, making it easier to understand and navigate.
+    - **Encapsulation**: Keeps related components together, reducing the risk of naming conflicts and improving modularity.
 
 Component Structure
 ===================
@@ -118,9 +122,9 @@ Component Structure
 Single-File Components
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Single-File Components (SFCs) are the preferred way to define Vue components. They encapsulate the template, script, and style in a single file, making it easier to manage and understand the component's structure.
+- Single-File Components (SFCs) are the preferred way to define Vue components. 
 
-.. code-block:: js
+.. code-block:: vue
 
     <script setup lang="ts">
     import { onMounted } from 'vue';
@@ -145,10 +149,14 @@ Single-File Components (SFCs) are the preferred way to define Vue components. Th
     }
     </style>
 
+- **Why?**
+    - **Encapsulation**: All component-related code is in one place, making it easier to understand and maintain.
+    - **Separation of concerns**: Each section (template, script, style) has its own purpose, improving readability.
+
 Component Decomposition
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Components should be decomposed into smaller, reusable components whenever possible. This promotes reusability and maintainability. Aim for a single responsibility per component.
+- Components should be decomposed into smaller, reusable components whenever possible. Aim for a single responsibility per component.
 
 .. code-block:: shell
 
@@ -159,168 +167,207 @@ Components should be decomposed into smaller, reusable components whenever possi
         │   └── CustomWidgetViewer.vue
         └── CustomWidget.vue
 
+- **Why?**
+    - **Reusability**: Smaller components can be reused in different contexts, reducing code duplication.
+    - **Maintainability**: Easier to understand and modify smaller components than large monolithic ones.
+    - **Testing**: Smaller components are easier to test in isolation.
+
 Passing Data
 ~~~~~~~~~~~~
 
-- **Fetch Proximity**:  
-  Fetch data in the component that actually renders it. Don't lift network calls higher than needed.
+- **Fetch Proximity**
+    - Fetch data in the component that actually renders it. Don't lift network calls higher than needed.
 
-.. code-block:: js
+    .. code-block:: vue
 
-    <!-- Bad: fetching at a high-level parent when only the table needs it -->
+        <!-- Bad: fetching at a high-level parent when only the table needs it -->
 
-    <!-- Dashboard.vue -->
-    <script setup lang="ts">
-    import { ref, onMounted } from 'vue'
-    import UserTable from '@/my_project/Dashboard/components/UserTable.vue'
-
-    // Parent fetches users even if only UserTable displays them
-    const users = ref([])
-    onMounted(async () => {
-        users.value = await fetch('/api/users').then(resp => resp.json())
-    })
-    </script>
+        <!-- Dashboard.vue -->
+        <script setup lang="ts">
+        import { ref, watchEffect } from 'vue';
+        import UserTable from '@/my_project/Dashboard/components/UserTable.vue';
 
-    <template>
-        <div class="dashboard">
-            <h1>Dashboard</h1>
-            <!-- Data passed down via prop -->
-            <UserTable :users="users" />
-        </div>
-    </template>
+        // Parent fetches users even if only UserTable displays them
+        const users = ref([]);
+        watchEffect(async () => {
+            users.value = await fetch('/api/users').then(resp => resp.json());
+        });
+        </script>
+
+        <template>
+            <div class="dashboard">
+                <h1>Dashboard</h1>
+                <!-- Data passed down via prop -->
+                <UserTable :users="users" />
+            </div>
+        </template>
 
 
-    <!-- Good: fetching as close as possible to where data is rendered -->
+        <!-- Good: fetching as close as possible to where data is rendered -->
 
-    <!-- Dashboard.vue -->
-    <script setup lang="ts">
-    // Parent no longer fetches users
-    </script>
+        <!-- Dashboard.vue -->
+        <script setup lang="ts">
+        // Parent no longer fetches users
+        </script>
 
-    <template>
-        <div class="dashboard">
-            <h1>Dashboard</h1>
-            <!-- Child responsible for its own data -->
-            <UserTable />
-        </div>
-    </template>
+        <template>
+            <div class="dashboard">
+                <h1>Dashboard</h1>
+                <!-- Child responsible for its own data -->
+                <UserTable />
+            </div>
+        </template>
 
 
-    <!-- UserTable.vue -->
-    <script setup lang="ts">
-    import { ref, onMounted } from 'vue'
-    import type { User } from '@/types'
-
-    // Fetch proximity: fetch here since this component renders the list
-    const users = ref<User[]>([])
-    onMounted(async () => {
-        users.value = await fetch('/api/users').then(resp => resp.json())
-    })
-    </script>
+        <!-- UserTable.vue -->
+        <script setup lang="ts">
+        import { ref, watchEffect } from 'vue';
+        import type { User } from '@/types';
 
-    <template>
-        <table>
-            <tbody>
-                <tr v-for="user in users" :key="user.id">
-                    <td>{{ user.name }}</td>
-                    <td>{{ user.email }}</td>
-                </tr>
-            </tbody>
-        </table>
-    </template>
+        // Fetch proximity: fetch here since this component renders the list
+        const users = ref<User[]>([]);
+        watchEffect(async () => {
+            users.value = await fetch('/api/users').then(resp => resp.json());
+        });
+        </script>
+
+        <template>
+            <table>
+                <tbody>
+                    <tr v-for="user in users" :key="user.id">
+                        <td>{{ user.name }}</td>
+                        <td>{{ user.email }}</td>
+                    </tr>
+                </tbody>
+            </table>
+        </template>
 
-- **Primitives First**:  
-  Pass simple values (strings, numbers, booleans, small arrays/objects) instead of entire model objects whenever possible.
+      
+    - **Why?** 
+        - **Encapsulation**: Data-fetch logic lives alongside the view that consumes it.  
+        - **Limited prop drilling**: Minimizes passing data through unrelated parents.   
+        - **Error isolation**: Failures are handled locally, without cascading side effects.  
 
-.. code-block:: html
+- **Primitives First**
+    - Pass simple values (strings, numbers, booleans, small arrays/objects) instead of entire model objects whenever possible.
 
-    <!-- Bad: passing entire model objects -->
-    <UserProfile :user="currentUser" />
+    .. code-block:: vue
 
-    <!-- Good: passing only primitive values -->
-    <UserProfile
-        :user-id="currentUser.id"
-        :user-name="currentUser.name"
-        :is-admin="currentUser.isAdmin"
-    />
+        <!-- Bad: passing entire model objects -->
+        <UserProfile :user="currentUser" />
 
-- **Derived State**:  
-  Compute any summaries or transformations in the consumer component and pass those primitives down.
+        <!-- Good: passing only primitive values -->
+        <UserProfile
+            :user-id="currentUser.id"
+            :user-name="currentUser.name"
+            :is-admin="currentUser.isAdmin"
+        />
+    
+    - **Why?** 
+        - **Explicit API**: Readers, tools, and developers see exactly which fields the component needs.  
+        - **Immutable flow**: Primitives can't be mutated in place, preserving one-way data flow.  
+        - **Efficient updates**: Changes to unused object properties won't force re-renders.  
 
-.. code-block:: js
+- **Derived State**
+    - If a component's sole responsibility is to derive or summarize data pass the raw data and let it compute internally.
 
-    <!-- ParentComponent.vue -->
-    <script setup lang="ts">
-    import { ref, computed, onMounted } from 'vue'
-    import type { Order } from '@/types'
-
-    // Raw data fetched here
-    const orders = ref<Order[]>([])
-    onMounted(async () => {
-        orders.value = await fetch('/api/orders').then(r => r.json())
-    })
-
-    // Derived state: compute primitives
-    const orderCount = computed(() => orders.value.length)
-    const totalSales = computed(() =>
-        orders.value.reduce((sum, order) => sum + order.amount, 0)
-    )
-    </script>
+    .. code-block:: vue
 
-    <template>
-        <!-- Pass only the computed primitives -->
-        <OrderSummary
-            :count="orderCount"
-            :total-sales="totalSales"
-        />
-    </template>
+        <script setup lang="ts">
+        import { ref, computed, watchEffect } from 'vue';
 
-    <!-- OrderSummary.vue -->
-    <script setup lang="ts">
-    const props = defineProps<{
-        count: number
-        totalSales: number
-    }>()
-    </script>
+        import OrderSummary from '@/my_project/OrderSummary.vue';
 
-    <template>
-        <div class="order-summary">
-            <p>Total Orders: {{ props.count }}</p>
-            <p>Total Sales: {{ props.totalSales }}</p>
-        </div>
-    </template>
+        import type { Order } from '@/my_project/types.ts';
 
-- **Event Emission**:  
-  Emit semantic events (kebab-case) with typed payloads:
+        // Raw data fetched here
+        const orders = ref<Order[]>([]);
+        watchEffect(async () => {
+            orders.value = await fetch('/api/orders').then(response => response.json());
+        });
+        </script>
 
-.. code-block:: js
+        <template>
+            <!-- OrderSummary receives the full list and does its own computing -->
+            <OrderSummary :orders="orders" />
+        </template>
 
-    <script setup lang="ts">
-    interface RowSelectedEvent { rowId: number }
+    - When multiple children need the same computed value, derive once in the parent and pass primitives to avoid duplication and ensure consistency.
 
-    defineEmits<{
-        (e: 'row-selected', payload: RowSelectedEvent): void
-    }>()
+    .. code-block:: vue
 
-    function onRowClick(id: number) {
-        emit('row-selected', { rowId: id })
-    }
-    </script>
+        <script setup lang="ts">
+        import { ref, computed, watchEffect } from 'vue';
+
+        import OrderSummary from '@/my_project/OrderSummary.vue';
+        import OrderDetails from '@/my_project/OrderDetails.vue';
 
-- **Slots**:  
-  Use scoped slots for maximum flexibility; name them clearly
+        import type { Order } from '@/my_project/types.ts';
 
-.. code-block:: html
+        // Raw data fetched here
+        const orders = ref<Order[]>([]);
+        watchEffect(async () => {
+            orders.value = await fetch('/api/orders').then(response => response.json());
+        });
 
-    <MyTable>
-        <template #header>
-            {{ $gettext('Table Header') }}
+        // Derived state: compute once in the parent
+        const totalOrders = computed(() => orders.value.length);
+        </script>
+
+        <template>
+            <!-- Pass the computed value to both children -->
+            <OrderSummary :total-orders="totalOrders" />
+            <OrderDetails :total-orders="totalOrders" />
         </template>
-        <template #row="{ row }">
-            <MyRow :data="row" />
+
+    - **Why?**  
+        - **Performance**: Avoids recomputing derived values in multiple components.
+        - **Predictable props**: Child components receive only the exact values they need.  
+        - **Consistency**: Ensures every consumer uses the same computed values, preventing drift. 
+
+- **Event Emission** 
+    - Emit semantic events (kebab-case) with typed payloads:
+
+    .. code-block:: vue
+
+        <script setup lang="ts">
+        interface RowSelectedEvent { rowId: number }
+
+        defineEmits<{
+            (e: 'row-selected', payload: RowSelectedEvent): void
+        }>();
+
+        function onRowClick(id: number) {
+            emit('row-selected', { rowId: id });
+        }
+        </script>
+
+    - **Why?**  
+        - **Explicit contracts**: Consumers know exactly what events to expect and how to handle them.  
+        - **Type safety**: TypeScript ensures the payload matches the expected structure.  
+
+- **Slots**
+    - Use scoped slots for maximum flexibility; name them clearly to indicate their purpose.
+
+    .. code-block:: vue
+
+        <template>
+            <MyTable>
+                <!-- Can also use shorthand #header -->
+                <template v-slot:header>
+                    {{ $gettext('Table Header') }}
+                </template>
+
+                <!-- Can also use shorthand #row="{ row }" -->
+                <template v-slot:row="{ row }">
+                    <MyRow :data="row" />
+                </template>
+            </MyTable>
         </template>
-    </MyTable>
 
+    - **Why?**  
+        - **Flexibility**: Consumers can customize the rendering of specific parts of the component.  
+        - **Separation of concerns**: Slots allow for a clear distinction between the component's structure and its content.  
 
 The `<script>` Tag
 ==================
@@ -330,80 +377,228 @@ This block defines a component's logic. Follow these rules for clarity, consiste
 Coding Standards
 ~~~~~~~~~~~~~~~~
 
-- **Script Scope**:  
-  All component logic **must** reside within `<script setup>`—no module-scope side-effects.
+- **Script Scope**
+    - All component logic must be declared inside <script setup>, and <script setup> should always have typescript as the defined language.
+
+    .. code-block:: vue
+
+        <!-- Good: all logic inside <script setup>, with typescript -->
+        <script setup lang="ts">
+        import { ref } from 'vue';
+
+        const count = ref(0);
+        function incrementCount() { count.value++ }
+        </script>
+
+        <!-- Bad: logic outside of <script setup> -->
+        <script>
+            const count = 0;
+            function incrementCount() { count++; }
+        </script>
+
+    - **Why?**
+        - **TypeScript support**: Enables full TypeScript support directly within each component.
+        - **Scope safety**: All variables and functions are scoped to the component, preventing accidental global pollution.
+
+- **Function Declarations**
+    - Use named `function` declarations for component methods; **do not** use anonymous/arrow functions or function expressions.
+    - Use of anonymous/arrow functions is allowed for inline callbacks (e.g., `setTimeout`, `Promise.then`, `filter`, `onMounted`, `computed`, etc.).
+
+    .. code-block:: js
+
+        <!-- Bad: arrow function for component method -->
+        const incrementCount = () => { count.value++ };
+
+        <!-- Bad: function declaration for component method -->
+        const incrementCount = function() { count.value++ };
+
+        <!-- Good: named function declaration for component method -->
+        function incrementCount() { count.value++ }
+
+        <!-- Good: arrow function used for inline callback -->
+        setTimeout(() => { count.value++ }, 1000);
 
-- **Function Declarations**:  
-    - Use named `function` declarations for component methods; **do not** use anonymous functions or function expressions.
-    - Use of anonymous functions is allowed within parent functions (e.g., `setTimeout`, `Promise.then`, `filter`, `onMounted`, `computed`, etc.).
+    - **Why?**
+        - **Hoisting**: Named functions are hoisted, allowing them to be called before their declaration in the code. This can help avoid issues with function order and improve readability.
+        - **Debugging**: Named functions provide better stack traces and error
 
-- **Constants & Literals**:  
+- **Constants & Literals**
     - Declare fixed values in `SCREAMING_SNAKE_CASE`.  
     - Declare all string literals and magic numbers as named constants.
-      e.g. `const POLL_MS = 5000;` 
 
-- **Naming Conventions**:  
-  Use descriptive identifiers; avoid single-letter names.
+    .. code-block:: js
+
+        // Bad: magic number and string literal
+        function calculateTotal(price) {
+            return price * 0.0825;
+        }
+
+        function isOrderComplete(order) {
+            return order.status === 'PENDING';
+        }
+
+        // Good: named constants
+        const TAX_RATE = 0.0825;
+        const ORDER_STATUS_PENDING = 'PENDING';
+
+        function calculateTotal(price) {
+            return price * TAX_RATE;
+        }
+
+        function isOrderComplete(order) {
+            return order.status === ORDER_STATUS_PENDING;
+        }
+
+    - **Why?**
+        - **Readability**: Named constants make the code more self-explanatory and easier to understand and debug.
+        - **Maintainability**: Changing a single constant is easier than searching for all occurrences of a magic number or string literal.
+
+- **Naming Conventions**
+    - Use descriptive identifiers; avoid single-letter names.
+
+    .. code-block:: js
+
+        // Bad: single-letter naming
+        function doubleValue(x) { return x * 2; }
+
+        // Good: descriptive naming
+        function doubleValue(value) { return value * 2; }
+
+    - **Why?**
+        - **Clarity**: Descriptive names provide context and meaning, making the code easier to read and understand.
+        - **Maintainability**: Clear names help future developers (or yourself) quickly grasp the purpose of variables and functions.
+
+- **Modularity & Reuse**
+    - Extract non-UI logic (data transformations, business rules) into composables or utility modules.  
+
+    .. code-block:: js
+
+        // Bad: non-UI logic in component
+        function calculateDiscount(price, discount) {
+            return price - (price * discount);
+        }
+
+        // Good: non-UI logic in utility module
+        import { calculateDiscount } from '@/my_project/utils/discounts.ts';
+
+    - **Why?**
+        - **Separation of concerns**: Keeps UI logic separate from business logic, making components easier to read and maintain.
+        - **Reusability**: Composables and utility modules can be reused across multiple components, reducing code duplication.
+
+- **Side-Effects & Async Handling**
+    - Avoid performing side-effects (API calls, timers, storage access, data formatting, etc.) at module import in <script>.
+        - Trigger them inside lifecycle hooks (e.g. onMounted, onBeforeUnmount) or within reactive effect functions (e.g. watchEffect, computed).
+
+    - Always wrap your async/await operations in try/catch, handle errors explicitly, and ensure failures are surfaced to the UI or calling code.
+
+    .. code-block:: vue
 
-- **Modularity & Reuse**:  
-  Extract non-UI logic (data transformations, business rules) into composables or utility modules.  
+        <script setup lang="ts">
 
-- **Side-Effects & Async Handling**:  
-    - No side-effects in the `<script>` tag. Encapsulate API calls, formatting logic, and other side-effects in lifecycle hooks or composables.
-    - Wrap all async operations in `try/catch`, and surface or display errors appropriately.
+        const count = ref(0);
+        function incrementCount() { count.value++ }
 
-- **Type Safety**:  
-  Import and use explicit types; avoid `any`. Annotate all function return types.
+        <!-- Bad: module scope side-effects -->
+        incrementCount(); // This runs immediately when the module is loaded
+
+        <!-- Good: side-effects in lifecycle hooks -->
+        onMounted(() => {
+            incrementCount();
+        });
+        </script>
+
+    - **Why?**
+        - **Predictability**: Side-effects should only occur in controlled environments (e.g. lifecycle hooks) to avoid unexpected behavior.
+        - **Error handling**: Wrapping async operations in try/catch allows for graceful error handling and user feedback.
+
+- **Type Safety**
+    - Import and use explicit types; avoid use of the `any` type. Annotate all function return types.
+
+    .. code-block:: js
+
+        // Bad: using any type
+        function fetchData(): any {
+            return fetch('/api/data').then(response => response.json());
+        }
+
+        // Good: explicit type annotation
+        interface User {
+            id: number;
+            name: string;
+        }
+
+        function fetchData(): Promise<User[]> {
+            return fetch('/api/data').then(response => response.json());
+        }
+
+    - **Why?**
+        - **Type safety**: Using explicit types helps catch errors at compile time, reducing runtime issues.
+        - **Documentation**: Type annotations serve as documentation for function behavior and expected input/output.
 
 Import Pathing
 ~~~~~~~~~~~~~~
 
-**Use project alias** (`@/…`) for all local imports; avoid raw relative paths. e.g. 
+- **Use project alias** (`@/…`) for all local imports; avoid raw relative paths. e.g. 
 
-.. code-block:: js
+    .. code-block:: js
 
-    // Bad: raw relative path
-    import { fetchData } from '../../utils/fetch-data.ts'
-    
-    // Good: project alias
-    import { fetchData } from '@/project_name/utils/fetch-data.ts' 
+        // Bad: raw relative path
+        import { fetchData } from '../../utils/fetch-data.ts';
+        
+        // Good: project alias
+        import { fetchData } from '@/project_name/utils/fetch-data.ts';
 
-Import Order
-~~~~~~~~~~~~~
+- **Why?**
+    - **Readability**: Project aliases make it clear where the module is located without needing to trace relative paths.
+    - **Maintainability**: Avoids issues with deep nesting and makes it easier to refactor or reorganize the project structure.
 
-Import lines should be grouped and ordered as follows:
+Import Order
+~~~~~~~~~~~~
 
-1. **Vue core**  
-2. **Third-party modules**  
-3. **Third-party Vue components**  
-4. **Local Vue components**  
-5. **Local utilities/composables**  
-6. **Third-party types**  
-7. **Local types**  
+- Import lines should be grouped and ordered as follows:
+    1. **Vue core**  
+    2. **Third-party modules**  
+    3. **Third-party Vue components**  
+    4. **External Arches Vue components**
+    5. **Local Vue components**  
+    6. **External Arches utilities/composables**
+    7. **Local utilities/composables**  
+    8. **Third-party types**  
+    9. **External Arches types**
+    10. **Local types**  
 
-.. code-block:: js
+.. code-block:: vue
 
     <script setup lang="ts">
     // 1. Vue core
-    import { ref, computed } from 'vue'
+    import { ref, computed } from 'vue';
 
     // 2. Third-party modules
-    import { useGettext } from 'vue3-gettext'
+    import { useGettext } from 'vue3-gettext';
 
     // 3. Third-party Vue components
-    import { ProgressSpinner } from 'primevue/progressspinner'
+    import { ProgressSpinner } from 'primevue/progressspinner';
 
-    // 4. Local Vue components
-    import MyComponent from '@/project_name/components/MyComponent.vue'
+    // 4. External Arches Vue components
+    import ExternalComponent from '@/external_project/ExternalComponent.vue';
 
-    // 5. Local utilities/composables
-    import { fetchData } from '@/project_name/utils/fetchData.ts'
+    // 5. Local Vue components
+    import MyComponent from '@/project_name/components/MyComponent.vue';
 
-    // 6. Third-party types
-    import type { Component } from 'vue'
+    // 6. External Arches utilities/composables
+    import { doSomeBusinessLogic } from '@/external_project/utils/do-some-business-logic.ts';
 
-    // 7. Local types
-    import type { UserProfile } from '@/project_name/types.ts'
+    // 7. Local utilities/composables
+    import { fetchData } from '@/project_name/utils/fetch-data.ts';
+
+    // 8. Third-party types
+    import type { Component } from 'vue';
+
+    // 9. External Arches types
+    import type { ExternalType } from '@/external_project/types.ts';
+
+    // 10. Local types
+    import type { UserProfile } from '@/project_name/types.ts';
 
     // Your component logic here
     </script>
@@ -411,25 +606,19 @@ Import lines should be grouped and ordered as follows:
 Declaration Order
 ~~~~~~~~~~~~~~~~~
 
-Within your `<script setup>` block, organize declarations in this sequence. Omit any steps that don’t apply.
-
-1. **`defineProps`**  
-2. **`defineEmits` / `defineExpose`**  
-3. **Composables instantiation**:  
-   e.g. `const { $gettext } = useGettext()`  
-4. **Dependency injection**:  
-   e.g. `const api = inject('apiClient')!`  
-5. **Constants & configuration**:  
-   e.g. `const POLL_MS = 5000`
-6. **Reactive state**:  
-   e.g. `const foo = ref(...)`  
-7. **Computed properties**  
-8. **Watches**  
-9. **Lifecycle hooks**:  
-   e.g. `onMounted()`, `onBeforeUnmount()`  
-10. **Methods / functions**  
+- Within your `<script setup>` block, organize declarations in this sequence.
+    1. **`defineProps`**  
+    2. **`defineExpose`/`defineEmits`**  
+    3. **Set up composables/utilities**
+    4. **Dependency injection**
+    5. **Constants & configuration**
+    6. **Reactive state**
+    7. **Computed properties**  
+    8. **Watchers**  
+    9. **Lifecycle hooks** 
+    10. **Methods/functions**  
 
-.. code-block:: js
+.. code-block:: vue
 
     <script setup lang="ts">
     import { ref, computed, watch, onMounted, inject } from 'vue';
@@ -439,10 +628,11 @@ Within your `<script setup>` block, organize declarations in this sequence. Omit
     // 1. defineProps
     const props = defineProps<{ id: number }>();
 
-    // 2. defineEmits
+    // 2. defineExpose/defineEmits
+    defineExpose({ myMethod: myMethod });
     const emit = defineEmits<{ (e: 'loaded'): void }>();
 
-    // 3. Composables instantiation
+    // 3. Set up composables/utilities
     const { $gettext } = useGettext();
 
     // 4. Dependency injection
@@ -458,29 +648,28 @@ Within your `<script setup>` block, organize declarations in this sequence. Omit
     // 7. Computed properties
     const hasData = computed(() => data.value.length > 0);
 
-    // 8. Watches
-    watch(() => props.id, loadData, { immediate: true });
+    // 8. Watchers
+    watch(() => props.id, myFunction, { immediate: true });
 
     // 9. Lifecycle hooks
     onMounted(() => {
-      loadData();
+        myFunction();
     });
 
-    // 10. Methods / functions
+    // 10. Methods/functions
     async function loadData() {
-      try {
-        isLoading.value = true;
-        data.value = await api.fetchItems(props.id);
-      } catch (err) {
-        console.error(err);
-      } finally {
-        isLoading.value = false;
-        emit('loaded');
-      }
+        try {
+            isLoading.value = true;
+            data.value = await api.fetchItems(props.id);
+        } catch (error) {
+            console.error(error);
+        } finally {
+            isLoading.value = false;
+            emit('loaded');
+        }
     }
     </script>
 
-
 The `<template>` Tag
 ====================
 
@@ -489,55 +678,63 @@ Defines the component's UI. Keep templates clear, consistent, and easy to scan.
 Attribute Ordering & Formatting
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When declaring attributes in your `<template>`, group and order them as follows. Within each group, sort attributes alphabetically.
-
-1. **Directives** (e.g. `v-for`, `v-if`)  
-2. **Slots** (e.g. `v-slot:header="…"` )
-3. **Static attributes** (e.g. `id`, `class`)  
-4. **Dynamic props** (e.g. `:prop="…"` )  
-5. **Event listeners** (e.g. `@click="…"` )  
-6. **Modifiers** (e.g. `@click.prevent="…"` )  
-
-Formatting rules:
-
-- **Inline vs. Multiline**  
-    - **One attribute** → keep on the same line as the tag.  
-    - **Multiple attributes** → one per line, indented under the tag.  
-- **Explicit assignment**  
-    - Always write `prop="value"` or `:prop="value"`.  
-    - Do **not** use shorthand (`:prop` without value) or omit values.  
-- **Kebab-case**  
-    - All attribute names (including custom props and events) **must** use kebab-case.
-
-.. code-block:: html
-
-    <!-- Good: grouped, ordered, multiline, kebab-case -->
-    <UserCard
-        v-if="isVisible"
-        v-slot:default="{ user }"
-        id="user-card"
-        class="card highlight"
-        :avatar-url="user.avatarUrl"
-        :is-active="user.isActive"
-        @mouseover="onHover"
-        @submit.prevent="onSubmit"
-    />
-
-    <!-- Bad: unordered, inline, camelCase -->
-    <UserCard id="userCard" :avatarUrl="user.avatarUrl" @submit.prevent="onSubmit" v-if="isVisible"/>
+- When declaring attributes in your `<template>`, group and order them as follows. Within each group, sort attributes alphabetically.
+    1. **Directives** (e.g. `v-for`, `v-if`)  
+    2. **Slots** (e.g. `v-slot:header="…"` )
+    3. **Static attributes** (e.g. `id`, `class`)  
+    4. **Dynamic props** (e.g. `:prop="…"` )  
+    5. **Event listeners** (e.g. `@click="…"` )  
+    6. **Modifiers** (e.g. `@click.prevent="…"` )  
+
+- Formatting rules:
+    - **Inline vs. Multiline**  
+        - **One attribute**: keep on the same line as the tag.  
+        - **Multiple attributes**: one per line, indented under the tag.  
+    - **Explicit assignment**  
+        - Always write `prop="value"` or `:prop="value"`.  
+        - Do **not** use shorthand (`:prop` without value) or omit values.  
+    - **Kebab-case**  
+        - All attribute names (including custom props and events) **must** use kebab-case.
+
+.. code-block:: vue
+    
+    <template>
+        <!-- Good: grouped, ordered, multiline, kebab-case -->
+        <UserCard
+            v-if="isVisible"
+            v-slot:default="{ user }"
+            id="user-card"
+            class="card highlight"
+            :avatar-url="user.avatarUrl"
+            :is-active="user.isActive"
+            @mouseover="onHover"
+            @submit.prevent="onSubmit"
+        />
+
+        <!-- Bad: unordered, inline, camelCase -->
+        <UserCard id="userCard" :avatarUrl="user.avatarUrl" @submit.prevent="onSubmit" v-if="isVisible"/>
+    </template>
+
+- **Why?**
+    - **Readability**: Consistent ordering and formatting make it easier to scan and understand the template.
+    - **Maintainability**: Clear structure helps future developers (or yourself) quickly grasp the component's purpose and behavior.
 
 Self-Closing Tags
 ~~~~~~~~~~~~~~~~~
 
-Use self-closing syntax for elements or components without children:
+- Use self-closing syntax for elements or components without children:
 
-.. code-block:: html
+.. code-block:: vue
 
     <template>
         <LogoIcon />
         <img src="@/assets/logo.png" alt="Logo" />
     </template>
 
+- **Why?**
+    - **Clarity**: Self-closing tags clearly indicate that the element has no children, improving readability.
+    - **Consistency**: Using self-closing syntax for void elements (e.g., `<img>`, `<input>`) maintains a consistent style throughout the codebase.
+
 Logic in Templates
 ~~~~~~~~~~~~~~~~~~
 
@@ -545,7 +742,7 @@ Logic in Templates
     - Avoid ternaries, chained method calls, or heavy expressions.  
     - Move conditions and transformations into `computed` or methods.  
 
-.. code-block:: html
+.. code-block:: vue
 
     <!-- Good: simple v-if, logic lives in computed -->
     <template>
@@ -557,40 +754,48 @@ Logic in Templates
         <div>{{ isVisible ? formatText(user.name) : '—' }}</div>
     </template>
 
+- **Why?**
+    - **Readability**: Templates should be easy to read and understand at a glance.  
+    - **Performance**: Heavy computations in templates can lead to unnecessary re-renders and performance issues.
+
 Text in Templates
 ~~~~~~~~~~~~~~~~~
 
 - **Internationalization**  
-  - Wrap all user-facing strings with `$gettext()`.  
-  - Avoid string concatenation; use formatting placeholders.
+    - Wrap all user-facing strings with `$gettext()`.  
+    - Never concatenate translated strings together; use placeholders instead.
 
 - **No loose text nodes**  
-  - Surround plain text with an inline element (e.g., `<span>`) or semantic tag.  
+    - Surround plain text with an inline element (e.g., `<span>`) or semantic tag.  
 
-.. code-block:: html
+.. code-block:: vue
 
-    <!-- Good -->
+    <!-- Bad: unwrapped text node, string concatination, some strings without i18n -->
     <template>
         <div>
-            <span>{{ $gettext('Hello, world!') }}</span>
-            
+            {{ $gettext('Hello,') }}{{ user.name }}!
+
             <Button @click="handleClick">
-                {{ $gettext('Click me!') }}
+                Click me!
             </Button>
         </div>
     </template>
 
-    <!-- Bad: unwrapped text node -->
+    <!-- Good: wrapped text node, placeholders instead of concatination, all strings have i18n -->
     <template>
         <div>
-            {{ $gettext('Hello, world!') }}
-
+            <span>{{ $gettext('Hello, %{user.name}!') }}</span>
+            
             <Button @click="handleClick">
                 {{ $gettext('Click me!') }}
             </Button>
         </div>
     </template>
 
+- **Why?**
+    - **Internationalization**: Correctly wrapping strings with `$gettext()` ensures they are translatable and can be easily localized.
+    - **Semantic HTML**: Using inline elements or semantic tags improves accessibility and SEO by providing context to screen readers and search engines.
+
 The `<style>` Tag
 =================
 
@@ -603,71 +808,173 @@ Scope
     - Prefer to use `<style scoped>` to ensure styles are applied only to the component.  
     - Reserve global styles and design tokens for your global CSS or theme files unless absolutely necessary.
 
+.. code-block:: vue
+
+    <!-- Bad: global styles -->
+    <style>
+        .header {
+            color: var(--theme-primary);
+        }
+    </style>
+
+    <!-- Good: scoped styles -->
+    <style scoped>
+        .header {
+            color: var(--theme-primary);
+        }
+    </style>
+
+- **Why?**
+    - **Isolation**: Scoped styles prevent unintended side effects on other components, ensuring consistent styling.
+    - **Maintainability**: Changes to a component's styles won't affect other components, reducing the risk of introducing undesired behavior.
+
 Layout Patterns
 ~~~~~~~~~~~~~~~
 
 - **Flexbox & Grid only**  
-    Use `display: flex` for one-dimensional layouts and `display: grid` for two-dimensional arrangements.  
+    - Use `display: flex` for one-dimensional layouts and `display: grid` for two-dimensional arrangements.  
 - **Use `gap`**  
-    Space items with `gap`; do **not** rely on margins for core layout.  
+    - Space items with `gap`; do **not** rely on margins for core layout.  
 - **No legacy hacks**  
-    Never use `float`, `inline-block`, or other outdated techniques.
+    - Never use `float`, `inline-block`, or other outdated techniques.
+- **Single-line vs multi-line selectors**
+    - Use single-line selectors for enforcing exactly one style rule.
+    - Use multi-line selectors for grouping multiple rules together.
+
+.. code-block:: vue
+
+    <style scoped>
+
+        /* Bad: single-line selector for multiple rules */
+        .item { display: flex; gap: 1rem; }
+
+        /* Good: single-line selector for one rule */
+        .item { display: flex; }
+
+        /* Good: multi-line selector for multiple rules */
+        .item {
+            display: flex;
+            gap: 1rem;
+        }
+    </style>
+
+- **Why?**
+    - **Flexibility**: Flexbox and Grid provide powerful layout capabilities for modern web applications.
+    - **Maintainability**: Using `gap` simplifies spacing management and reduces the need for complex margin calculations.
 
 Units & Sizing
 ~~~~~~~~~~~~~~
 
 - **`rem` for nearly everything**  
-    Use `rem` units for spacing, typography, gaps, borders, and other dimensional values.
+    - Use `rem` units for spacing, typography, gaps, borders, and other dimensional values.
 
 - **Viewport units sparingly**  
-    Reserve `vh`/`vw` for elements that must span the viewport (e.g., full-screen sections or modals).
+    - Reserve `vh`/`vw` for elements that must span the viewport (e.g., full-screen sections or modals).
 
 - **Percentages for fluid layouts**  
-    Apply `%` when you need relative sizing (e.g., fluid widths in responsive grids).
+    - Apply `%` when you need relative sizing (e.g., fluid widths in responsive grids).
 
 - **No `px`**  
-    Avoid `px` units entirely to ensure scalability, accessibility, and consistent theming.
+    - Avoid `px` units entirely to ensure scalability, accessibility, and consistent theming.
+
+.. code-block:: css
+
+    /* Bad: using px units */
+    .container { width: 800px; padding: 20px; }
+
+    /* Good: using rem units */
+    .container { width: 50rem; padding: 1.25rem; }
+
+    /* Good: using percentage for fluid layout */
+    .container { width: 100%; }
+
+- **Why?**
+    - **Scalability**: Using `rem` and `%` units allows for better scaling across different screen sizes and resolutions.
+    - **Accessibility**: Relative units ensure that text and elements can be resized according to user preferences, improving accessibility.
 
 Offsets & Positioning
 ~~~~~~~~~~~~~~~~~~~~~
 - **No hard-coding single-side offsets**  
-    Instead of using `margin-left`, `margin-top`, etc., use logical properties like `margin-inline-start` and `margin-block-start`. This ensures proper alignment in different writing modes.
+    - Instead of using `margin-left`, `margin-top`, etc., use logical properties like `margin-inline-start` and `margin-block-start`.
 
-.. code-block:: css
+- **No negative margins**  
+    - Negative `margin-*` values are forbidden.
 
-    /* Bad */
-    .Overlay {
-        margin-right: 2rem;
-    }
+.. code-block:: vue
 
-    /* Good */
     <style scoped>
-        .Overlay {
-            margin-inline-end: 2rem;
-        }
+        /* Bad: negative margin, not using logical properties */
+        .container .item { margin-left: -1rem; }
+
+        /* Good: no negative margin, using logical properties */
+        .container { padding-inline-start: 1rem; }
+        .item { margin-inline-start: 0; }
     </style>
 
-- **No negative margins**  
-    Negative `margin-*` values are forbidden.
+- **Why?**
+    - **Logical properties**: Using logical properties ensures consistent behavior across different language displays (e.g. left-to-right vs. right-to-left).
+    - **Avoiding layout shifts**: Negative margins can lead to unexpected layout shifts and make it harder to maintain a consistent design.
 
 No `calc()`
 ~~~~~~~~~~~
 
 - The `calc()` function is forbidden in component styles.
 
+.. code-block:: css
+
+    /* Bad: using calc() */
+    .container { width: calc(100% - 2rem); }
+
+    /* Good: using rem units */
+    .container { width: 50rem; }
+
+- **Why?**  
+    - It complicates the CSS and makes it harder to read.  
+    - It can cause unexpected layout shifts, especially in responsive designs.
+
 Theming & Colors
 ~~~~~~~~~~~~~~~~
 
-- **No hard-coded colors**  
-    Prefer to reference design tokens, e.g. `var(--theme-primary)`.  
-- **Centralize tokens**  
-    Define colors, typography, spacing scales, and breakpoints in your theme files.
+- **Design Tokens Only**  
+    - Always reference your design tokens instead of raw values. 
+
+- **Centralize & Document**  
+    - Keep all tokens (colors, typography scales, breakpoints, etc.) in a single theme file.
+
+- **Semantic Layers**  
+    - Build on top of raw palette entries with semantic tokens (e.g. ``--color-success``) so UI intent drives your choices.
+
+- **Light/Dark Support**  
+    - Define variants for both modes in your theme preset.
+
+.. code-block:: js
+
+    import { definePreset } from '@primevue/themes';
+    import { DEFAULT_THEME } from "@/arches/themes/default.ts";
+
+    export const MyTheme = definePreset(DEFAULT_THEME, {
+        semantic: {
+            colorScheme: {
+                light: {
+                    primary: { color: '{primary.500}', contrast: '{primary.50}' },
+                    success: { color: 'green', contrast: '{surface.900}' }
+                },
+                dark: {
+                    primary: { color: '{primary.300}', contrast: '{surface.900}' }
+                }
+            }
+        }
+    });
+
+- **Why?**
+    - **Consistency**: Using design tokens ensures a consistent look and feel across the application.
+    - **Maintainability**: Centralizing tokens makes it easier to update and manage styles.
 
 Selector Naming
 ~~~~~~~~~~~~~~~
 
 - **Dot-delineated hierarchy**  
-    Prefix selectors with the component's root class, then chain child class names:
+    - Prefix selectors with the component's root class, then chain child class names:
 
 .. code-block:: css
 
@@ -677,17 +984,20 @@ Selector Naming
             flex-direction: column;
             gap: 1rem;
         }
-        .user-card.header {
+        .user-card .header {
             display: grid;
             grid-template-columns: 1fr auto;
             gap: 0.5rem;
         }
-        .user-card.header.title {
+        .user-card .header .title {
             font-size: 1.5rem;
             color: var(--theme-primary);
         }
     </style>
 
+- **Why?**
+    - **Clarity**: Dot-delineated selectors make it clear which component the styles belong to, improving readability.
+    - **Avoiding conflicts**: Using a unique prefix reduces the risk of style conflicts with other components.
 
 Testing
 =======
@@ -699,46 +1009,49 @@ Test Location & Naming
 
 - Co-locate tests next to components, in the same directory.  
 - Test files must end with a ``.spec.ts`` suffix.  
-- Example structure:
-
-  .. code-block:: shell
-
-      src/
-      └── my_project/
-            ├── CustomApplication.vue
-            ├── CustomApplication.spec.ts
-            ├── utils.ts
-            ├── utils.spec.ts
-            ├── widgets/
-            │   └── CustomWidget/
-            │       ├── CustomWidget.vue
-            │       └── CustomWidget.spec.ts
-            └── reports/
-                └── CustomReport/
-                    ├── CustomReport.vue
-                    └── CustomReport.spec.ts
-
-Writing Tests
-~~~~~~~~~~~~~
+
+.. code-block:: shell
+
+    src/
+    └── my_project/
+        ├── CustomApplication.vue
+        ├── CustomApplication.spec.ts
+        ├── utils.ts
+        ├── utils.spec.ts
+        ├── widgets/
+        │   └── CustomWidget/
+        │       ├── CustomWidget.vue
+        │       └── CustomWidget.spec.ts
+        └── reports/
+            └── CustomReport/
+                ├── CustomReport.vue
+                └── CustomReport.spec.ts
+
+- **Why?**
+    - **Organization**: Grouping tests by component or utility helps maintain a clean project structure.
+    - **Ease of navigation**: Developers can quickly locate tests related to a specific component or utility without searching through a separate test directory.
+
+Writing Frontend Tests
+~~~~~~~~~~~~~~~~~~~~~~
 
 When crafting your tests, adhere to these best practices:
 
 - **Isolation**  
-  Mount each component on its own—stub or mock child components to pinpoint issues precisely.
+    - Mount each component on its own—stub or mock child components to pinpoint issues precisely.
 
 - **Coverage**  
-  Cover all code paths, including edge cases (error states, conditional rendering, emitted events).
+    - Cover all code paths, including edge cases (error states, conditional rendering, emitted events).
 
 - **Readability**  
-  Use clear, descriptive test names and group related tests with ``describe`` blocks.
+    - Use clear, descriptive test names and group related tests with ``describe`` blocks.
 
 - **Async Handling**  
-  Use ``flushPromises`` or ``await nextTick()`` after triggering asynchronous updates.
+    - Use ``flushPromises`` or ``await nextTick()`` after triggering asynchronous updates.
 
 - **Cleanup**  
-  Unmount or destroy wrappers if they persist between tests (though Vitest's JSDOM resets per test by default).
+    - Unmount or destroy wrappers if they persist between tests (though Vitest's JSDOM resets per test by default).
 
-.. code-block:: js
+.. code-block:: vue
 
     <!-- src/components/CounterButton.vue -->
     <script setup lang="ts">
@@ -752,7 +1065,7 @@ When crafting your tests, adhere to these best practices:
 
     <template>
         <button @click="increment" class="counter">
-            Count: {{ count }}
+            {{ count }}
         </button>
     </template>
 
@@ -763,14 +1076,14 @@ When crafting your tests, adhere to these best practices:
 .. code-block:: js
 
     // src/components/CounterButton.spec.ts
-    import { describe, it, expect } from 'vitest'
-    import { mount, flushPromises } from '@vue/test-utils'
-    import CounterButton from '@/my_project/components/CounterButton.vue'
+    import { describe, it, expect } from 'vitest';
+    import { mount, flushPromises } from '@vue/test-utils';
+    import CounterButton from '@/my_project/components/CounterButton.vue';
 
     describe('CounterButton.vue', () => {
         it('mounts and displays initial count', () => {
             const wrapper = mount(CounterButton);
-            expect(wrapper.text()).toContain('Count: 0');
+            expect(wrapper.text()).toContain('0');
         });
 
         it('increments count on click', async () => {
@@ -778,14 +1091,20 @@ When crafting your tests, adhere to these best practices:
             const button = wrapper.find('button');
             await button.trigger('click');
             await flushPromises();
-            expect(wrapper.text()).toContain('Count: 1');
+            expect(wrapper.text()).toContain('1');
         });
     });
 
-Running Tests
-~~~~~~~~~~~~~
+- **Why?**
+    - **Isolation**: Testing components in isolation helps identify issues more easily and ensures that tests are not affected by other components.
+    - **Readability**: Clear and descriptive test names make it easier for developers to understand the purpose of each test.
+    - **Maintainability**: Well-structured tests are easier to maintain and update as the codebase evolves.
 
-Use the following npm scripts in your terminal:
+Running Frontend Tests
+~~~~~~~~~~~~~~~~~~~~~~
+
+- Use the following npm scripts in your terminal:
+    - Coverage output will appear under ``coverage/``, showing per-file metrics and highlighting untested lines.
 
 .. code-block:: shell
 
@@ -794,5 +1113,3 @@ Use the following npm scripts in your terminal:
 
     # Run a specific test file
     npm run vitest -- src/components/CounterButton.spec.ts
-
-Coverage output will appear under ``coverage/``, showing per-file metrics and highlighting untested lines.
diff --git a/requirements.txt b/requirements.txt
index bd0109a..139b9fd 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -3,3 +3,4 @@ pydata-sphinx-theme==0.12.0
 readthedocs-sphinx-ext==2.1.4
 sphinxcontrib-httpdomain
 requests[security]
+vue-lexer==0.0.4

From bb5e39a5d7ab1596f5585ba72e184e5ed67baf7c Mon Sep 17 00:00:00 2001
From: Christopher Byrd <chrabyrd@gmail.com>
Date: Mon, 19 May 2025 15:55:27 -0700
Subject: [PATCH 09/11] nit #481

---
 docs/developing/vue/arches-vue-styleguide.rst | 201 +++++++++---------
 1 file changed, 96 insertions(+), 105 deletions(-)

diff --git a/docs/developing/vue/arches-vue-styleguide.rst b/docs/developing/vue/arches-vue-styleguide.rst
index d29e9bd..99b9641 100644
--- a/docs/developing/vue/arches-vue-styleguide.rst
+++ b/docs/developing/vue/arches-vue-styleguide.rst
@@ -14,13 +14,10 @@ The purpose of this style guide is to establish a unified coding style and set o
 Basis for Style Guide
 =====================
 
-This style guide for Arches is built on top of the standard Vue.js and TypeScript style guides. As such, it inherits and extends the conventions and best practices outlined in those guides. 
+This style guide for Arches is built on top of the standard Vue.js and TypeScript style guides. As such, it inherits and extends the conventions and best practices outlined in those guides. Any coding style, formatting, or conventions not explicitly covered in this document should be referenced from the official Vue.js and TypeScript style guides. It's important to maintain consistency with these standard guidelines to ensure compatibility and familiarity for developers working with Vue.js and TypeScript projects.
 
-Any coding style, formatting, or conventions not explicitly covered in this document should be referenced from the official Vue.js and TypeScript style guides. It's important to maintain consistency with these standard guidelines to ensure compatibility and familiarity for developers working with Vue.js and TypeScript projects.
-
-For Vue.js, you can refer to the `official Vue style guide <https://vuejs.org/style-guide/>`_. 
-
-Similarly, for TypeScript, you can refer to the `official TypeScript style guide <https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html>`_.
+- For Vue.js, you can refer to the `official Vue style guide <https://vuejs.org/style-guide/>`_. 
+- For TypeScript, you can refer to the `official TypeScript style guide <https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html>`_.
 
 Contributions
 =============
@@ -31,7 +28,7 @@ Frontend Structure
 ==================
 
 File and Folder Naming Conventions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------
 
 - **Arches entity directories**
     - Use plural, lowercase names to reflect domain concepts.  
@@ -58,59 +55,60 @@ File and Folder Naming Conventions
     - e.g. ``user-profile.ts``, ``map-types.ts``
 
 Top-Level Structure
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 - Top-level directories **must** align with Arches concepts (e.g., cards, widgets, reports) when such delineation is required. Otherwise, consolidate everything under a single app-level directory.
 
-.. code-block:: shell
-
-    src/
-    └── project_name/
-        ├── plugins
-        ├── reports/
-        │   └── CustomReport/
-        │       ├── components
-        │       └── CustomReport.vue
-        ├── widgets
-        └── types
-        └── utils.ts
-
-.. code-block:: shell
-
-    src/
-    └── project_name/
-        ├── components/
-        │   └── CustomComponent.vue
-        ├── CustomApplication.vue
-        ├── types
-        └── utils.ts
+    .. code-block:: shell
+
+        src/
+        └── project_name/
+            ├── plugins
+            ├── reports/
+            │   └── CustomReport/
+            │       ├── components
+            │       └── CustomReport.vue
+            ├── widgets
+            └── types
+            └── utils.ts
+
+    .. code-block:: shell
+
+        src/
+        └── project_name/
+            ├── components/
+            │   └── CustomComponent.vue
+            ├── CustomApplication.vue
+            ├── types
+            └── utils.ts
 
 - **Why?**
     - **Standardization**: Consistent naming and structure make it easier for developers to navigate the codebase.
     - **Organization**: Grouping related components together makes it easier to find and manage them.
 
 Component Folder Hierarchy
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 - At every level:
     - **Component files with sub-components** **must** reside in a folder named after the component.
     - **Dependent components** **must** live in a `components/` subdirectory within their **parent component's** folder.
     - **Shared components** (used by more than one parent) **must** be elevated to the `components/` directory at the level of the **highest parent component** that uses them.
 
-.. code-block:: shell
+    .. code-block:: shell
 
-    src/project_name/
-    ├── CustomApplication.vue
-    └── components/
-        └── CustomDashboard/
-            ├── CustomDashboard.vue
+        src/
+        └── project_name/
+            ├── CustomApplication.vue
             └── components/
-                └── DashboardTable/
-                    └── DashboardTable.vue/
-                        └── components/
-                            ├── CustomHeader.vue
-                            ├── TableSection.vue
-                            └── UpdatedFooter.vue
+                └── CustomDashboard/
+                    ├── CustomDashboard.vue
+                    └── components/
+                        └── DashboardTable/
+                            └── DashboardTable.vue/
+                                └── components/
+                                    ├── CustomHeader.vue
+                                    ├── TableSection.vue
+                                    └── UpdatedFooter.vue
 
 - **Why?**
     - **Clarity**: Each component's folder contains everything it needs, making it easier to understand and navigate.
@@ -120,52 +118,54 @@ Component Structure
 ===================
 
 Single-File Components
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 - Single-File Components (SFCs) are the preferred way to define Vue components. 
 
-.. code-block:: vue
+    .. code-block:: vue
 
-    <script setup lang="ts">
-    import { onMounted } from 'vue';
-    import { useGettext } from 'vue3-gettext';
+        <script setup lang="ts">
+        import { onMounted } from 'vue';
+        import { useGettext } from 'vue3-gettext';
 
-    const { $gettext } = useGettext();
+        const { $gettext } = useGettext();
 
-    onMounted(() => {
-        console.log($gettext('Hello from the <script> tag!'));
-    });
-    </script>
+        onMounted(() => {
+            console.log($gettext('Hello from the <script> tag!'));
+        });
+        </script>
 
-    <template>
-        <h1 class="header">
-            {{ $gettext("Hello from the template!") }}
-        </h1>
-    </template>
+        <template>
+            <h1 class="header">
+                {{ $gettext("Hello from the template!") }}
+            </h1>
+        </template>
 
-    <style scoped>
-    .header {
-        color: red;
-    }
-    </style>
+        <style scoped>
+        .header {
+            color: red;
+        }
+        </style>
 
 - **Why?**
     - **Encapsulation**: All component-related code is in one place, making it easier to understand and maintain.
     - **Separation of concerns**: Each section (template, script, style) has its own purpose, improving readability.
 
 Component Decomposition
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 - Components should be decomposed into smaller, reusable components whenever possible. Aim for a single responsibility per component.
 
-.. code-block:: shell
+    .. code-block:: shell
 
-    widgets/
-    └── CustomWidget/
-        ├── components/
-        │   ├── CustomWidgetEditor.vue
-        │   └── CustomWidgetViewer.vue
-        └── CustomWidget.vue
+        src/
+        └── project_name/
+            └── widgets/
+            └── CustomWidget/
+                ├── components/
+                │   ├── CustomWidgetEditor.vue
+                │   └── CustomWidgetViewer.vue
+                └── CustomWidget.vue
 
 - **Why?**
     - **Reusability**: Smaller components can be reused in different contexts, reducing code duplication.
@@ -173,7 +173,7 @@ Component Decomposition
     - **Testing**: Smaller components are easier to test in isolation.
 
 Passing Data
-~~~~~~~~~~~~
+------------
 
 - **Fetch Proximity**
     - Fetch data in the component that actually renders it. Don't lift network calls higher than needed.
@@ -186,9 +186,9 @@ Passing Data
         <script setup lang="ts">
         import { ref, watchEffect } from 'vue';
         import UserTable from '@/my_project/Dashboard/components/UserTable.vue';
+        import type { User } from '@/my_project/types.ts';
 
-        // Parent fetches users even if only UserTable displays them
-        const users = ref([]);
+        const users = ref<User[]>([]);
         watchEffect(async () => {
             users.value = await fetch('/api/users').then(resp => resp.json());
         });
@@ -196,12 +196,11 @@ Passing Data
 
         <template>
             <div class="dashboard">
-                <h1>Dashboard</h1>
-                <!-- Data passed down via prop -->
                 <UserTable :users="users" />
             </div>
         </template>
 
+    .. code-block:: vue
 
         <!-- Good: fetching as close as possible to where data is rendered -->
 
@@ -212,8 +211,6 @@ Passing Data
 
         <template>
             <div class="dashboard">
-                <h1>Dashboard</h1>
-                <!-- Child responsible for its own data -->
                 <UserTable />
             </div>
         </template>
@@ -222,9 +219,8 @@ Passing Data
         <!-- UserTable.vue -->
         <script setup lang="ts">
         import { ref, watchEffect } from 'vue';
-        import type { User } from '@/types';
+        import type { User } from '@/my_project/types.ts';
 
-        // Fetch proximity: fetch here since this component renders the list
         const users = ref<User[]>([]);
         watchEffect(async () => {
             users.value = await fetch('/api/users').then(resp => resp.json());
@@ -241,7 +237,6 @@ Passing Data
                 </tbody>
             </table>
         </template>
-
       
     - **Why?** 
         - **Encapsulation**: Data-fetch logic lives alongside the view that consumes it.  
@@ -275,9 +270,7 @@ Passing Data
 
         <script setup lang="ts">
         import { ref, computed, watchEffect } from 'vue';
-
         import OrderSummary from '@/my_project/OrderSummary.vue';
-
         import type { Order } from '@/my_project/types.ts';
 
         // Raw data fetched here
@@ -298,10 +291,8 @@ Passing Data
 
         <script setup lang="ts">
         import { ref, computed, watchEffect } from 'vue';
-
         import OrderSummary from '@/my_project/OrderSummary.vue';
         import OrderDetails from '@/my_project/OrderDetails.vue';
-
         import type { Order } from '@/my_project/types.ts';
 
         // Raw data fetched here
@@ -375,14 +366,14 @@ The `<script>` Tag
 This block defines a component's logic. Follow these rules for clarity, consistency, and maintainability.
 
 Coding Standards
-~~~~~~~~~~~~~~~~
+----------------
 
 - **Script Scope**
     - All component logic must be declared inside <script setup>, and <script setup> should always have typescript as the defined language.
 
     .. code-block:: vue
 
-        <!-- Good: all logic inside <script setup>, with typescript -->
+        <!-- Good: scoped to component, using typescript -->
         <script setup lang="ts">
         import { ref } from 'vue';
 
@@ -390,7 +381,7 @@ Coding Standards
         function incrementCount() { count.value++ }
         </script>
 
-        <!-- Bad: logic outside of <script setup> -->
+        <!-- Bad: global scope pollution, no typescript -->
         <script>
             const count = 0;
             function incrementCount() { count++; }
@@ -536,7 +527,7 @@ Coding Standards
         - **Documentation**: Type annotations serve as documentation for function behavior and expected input/output.
 
 Import Pathing
-~~~~~~~~~~~~~~
+--------------
 
 - **Use project alias** (`@/…`) for all local imports; avoid raw relative paths. e.g. 
 
@@ -553,7 +544,7 @@ Import Pathing
     - **Maintainability**: Avoids issues with deep nesting and makes it easier to refactor or reorganize the project structure.
 
 Import Order
-~~~~~~~~~~~~
+------------
 
 - Import lines should be grouped and ordered as follows:
     1. **Vue core**  
@@ -604,7 +595,7 @@ Import Order
     </script>
 
 Declaration Order
-~~~~~~~~~~~~~~~~~
+-----------------
 
 - Within your `<script setup>` block, organize declarations in this sequence.
     1. **`defineProps`**  
@@ -676,7 +667,7 @@ The `<template>` Tag
 Defines the component's UI. Keep templates clear, consistent, and easy to scan.
 
 Attribute Ordering & Formatting
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 - When declaring attributes in your `<template>`, group and order them as follows. Within each group, sort attributes alphabetically.
     1. **Directives** (e.g. `v-for`, `v-if`)  
@@ -720,7 +711,7 @@ Attribute Ordering & Formatting
     - **Maintainability**: Clear structure helps future developers (or yourself) quickly grasp the component's purpose and behavior.
 
 Self-Closing Tags
-~~~~~~~~~~~~~~~~~
+-----------------
 
 - Use self-closing syntax for elements or components without children:
 
@@ -736,7 +727,7 @@ Self-Closing Tags
     - **Consistency**: Using self-closing syntax for void elements (e.g., `<img>`, `<input>`) maintains a consistent style throughout the codebase.
 
 Logic in Templates
-~~~~~~~~~~~~~~~~~~
+------------------
 
 - **No complex logic**  
     - Avoid ternaries, chained method calls, or heavy expressions.  
@@ -759,7 +750,7 @@ Logic in Templates
     - **Performance**: Heavy computations in templates can lead to unnecessary re-renders and performance issues.
 
 Text in Templates
-~~~~~~~~~~~~~~~~~
+-----------------
 
 - **Internationalization**  
     - Wrap all user-facing strings with `$gettext()`.  
@@ -802,7 +793,7 @@ The `<style>` Tag
 Defines component-scoped CSS. Follow these rules for responsive, maintainable, and themeable styles.
 
 Scope
-~~~~~
+-----
 
 - **Scoped styles**  
     - Prefer to use `<style scoped>` to ensure styles are applied only to the component.  
@@ -829,7 +820,7 @@ Scope
     - **Maintainability**: Changes to a component's styles won't affect other components, reducing the risk of introducing undesired behavior.
 
 Layout Patterns
-~~~~~~~~~~~~~~~
+---------------
 
 - **Flexbox & Grid only**  
     - Use `display: flex` for one-dimensional layouts and `display: grid` for two-dimensional arrangements.  
@@ -863,7 +854,7 @@ Layout Patterns
     - **Maintainability**: Using `gap` simplifies spacing management and reduces the need for complex margin calculations.
 
 Units & Sizing
-~~~~~~~~~~~~~~
+--------------
 
 - **`rem` for nearly everything**  
     - Use `rem` units for spacing, typography, gaps, borders, and other dimensional values.
@@ -893,7 +884,7 @@ Units & Sizing
     - **Accessibility**: Relative units ensure that text and elements can be resized according to user preferences, improving accessibility.
 
 Offsets & Positioning
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 - **No hard-coding single-side offsets**  
     - Instead of using `margin-left`, `margin-top`, etc., use logical properties like `margin-inline-start` and `margin-block-start`.
 
@@ -916,7 +907,7 @@ Offsets & Positioning
     - **Avoiding layout shifts**: Negative margins can lead to unexpected layout shifts and make it harder to maintain a consistent design.
 
 No `calc()`
-~~~~~~~~~~~
+-----------
 
 - The `calc()` function is forbidden in component styles.
 
@@ -933,7 +924,7 @@ No `calc()`
     - It can cause unexpected layout shifts, especially in responsive designs.
 
 Theming & Colors
-~~~~~~~~~~~~~~~~
+----------------
 
 - **Design Tokens Only**  
     - Always reference your design tokens instead of raw values. 
@@ -971,7 +962,7 @@ Theming & Colors
     - **Maintainability**: Centralizing tokens makes it easier to update and manage styles.
 
 Selector Naming
-~~~~~~~~~~~~~~~
+---------------
 
 - **Dot-delineated hierarchy**  
     - Prefix selectors with the component's root class, then chain child class names:
@@ -1005,7 +996,7 @@ Testing
 To ensure the reliability and functionality of our Vue components, we use **Vitest** together with **Vue Test Utils**. Vitest is a fast, modern test runner that integrates seamlessly with Vite, while Vue Test Utils provides utilities to mount components and inspect their rendered output.
 
 Test Location & Naming
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 - Co-locate tests next to components, in the same directory.  
 - Test files must end with a ``.spec.ts`` suffix.  
@@ -1032,7 +1023,7 @@ Test Location & Naming
     - **Ease of navigation**: Developers can quickly locate tests related to a specific component or utility without searching through a separate test directory.
 
 Writing Frontend Tests
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 When crafting your tests, adhere to these best practices:
 
@@ -1101,7 +1092,7 @@ When crafting your tests, adhere to these best practices:
     - **Maintainability**: Well-structured tests are easier to maintain and update as the codebase evolves.
 
 Running Frontend Tests
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 - Use the following npm scripts in your terminal:
     - Coverage output will appear under ``coverage/``, showing per-file metrics and highlighting untested lines.

From c8d0bf53d2a2c6d0fdbdf1dad5fb0724c7512e41 Mon Sep 17 00:00:00 2001
From: Christopher Byrd <chrabyrd@gmail.com>
Date: Mon, 19 May 2025 16:02:05 -0700
Subject: [PATCH 10/11] adds TOC #481

---
 docs/developing/vue/arches-vue-styleguide.rst | 42 +++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/docs/developing/vue/arches-vue-styleguide.rst b/docs/developing/vue/arches-vue-styleguide.rst
index 99b9641..fdb9ec9 100644
--- a/docs/developing/vue/arches-vue-styleguide.rst
+++ b/docs/developing/vue/arches-vue-styleguide.rst
@@ -2,6 +2,48 @@
 Arches Vue Style Guide
 ######################
 
+Table of Contents
+=================
+
+- `Purpose`_
+- `Basis for Style Guide`_
+- `Contributions`_
+- `Frontend Structure`_
+    - `File and Folder Naming Conventions`_
+    - `Top-Level Structure`_
+    - `Component Folder Hierarchy`_
+- `Component Structure`_
+    - `Single-File Components`_
+    - `Component Decomposition`_
+    - `Passing Data`_
+        - `Fetch Proximity`_
+        - `Primitives First`_
+        - `Derived State`_
+        - `Event Emission`_
+        - `Slots`_
+- `The <script> Tag`_
+    - `Coding Standards`_
+    - `Import Pathing`_
+    - `Import Order`_
+    - `Declaration Order`_
+- `The <template> Tag`_
+    - `Attribute Ordering & Formatting`_
+    - `Self-Closing Tags`_
+    - `Logic in Templates`_
+    - `Text in Templates`_
+- `The <style> Tag`_
+    - `Scope`_
+    - `Layout Patterns`_
+    - `Units & Sizing`_
+    - `Offsets & Positioning`_
+    - `No calc()`_
+    - `Theming & Colors`_
+    - `Selector Naming`_
+- `Testing`_
+    - `Test Location & Naming`_
+    - `Writing Frontend Tests`_
+    - `Running Frontend Tests`_
+
 Purpose
 =======
 

From b56ed1a370fde7a624f30f9612f2199a57de2573 Mon Sep 17 00:00:00 2001
From: Christopher Byrd <chrabyrd@gmail.com>
Date: Mon, 19 May 2025 16:07:42 -0700
Subject: [PATCH 11/11] nit #481

---
 docs/developing/vue/arches-vue-styleguide.rst | 17 ++++++-----------
 1 file changed, 6 insertions(+), 11 deletions(-)

diff --git a/docs/developing/vue/arches-vue-styleguide.rst b/docs/developing/vue/arches-vue-styleguide.rst
index fdb9ec9..f16135d 100644
--- a/docs/developing/vue/arches-vue-styleguide.rst
+++ b/docs/developing/vue/arches-vue-styleguide.rst
@@ -8,7 +8,7 @@ Table of Contents
 - `Purpose`_
 - `Basis for Style Guide`_
 - `Contributions`_
-- `Frontend Structure`_
+- `Structure and Naming`_
     - `File and Folder Naming Conventions`_
     - `Top-Level Structure`_
     - `Component Folder Hierarchy`_
@@ -16,11 +16,6 @@ Table of Contents
     - `Single-File Components`_
     - `Component Decomposition`_
     - `Passing Data`_
-        - `Fetch Proximity`_
-        - `Primitives First`_
-        - `Derived State`_
-        - `Event Emission`_
-        - `Slots`_
 - `The <script> Tag`_
     - `Coding Standards`_
     - `Import Pathing`_
@@ -66,8 +61,8 @@ Contributions
 
 This style guide is a living document that evolves over time. We welcome contributions from the community to improve and expand this guide further. If you have suggestions, feedback, or would like to contribute to the style guide, please reach out to us via the `Arches Forum <https://community.archesproject.org/>`_.
 
-Frontend Structure
-==================
+Structure and Naming
+====================
 
 File and Folder Naming Conventions
 ----------------------------------
@@ -402,7 +397,7 @@ Passing Data
         - **Flexibility**: Consumers can customize the rendering of specific parts of the component.  
         - **Separation of concerns**: Slots allow for a clear distinction between the component's structure and its content.  
 
-The `<script>` Tag
+The <script> Tag
 ==================
 
 This block defines a component's logic. Follow these rules for clarity, consistency, and maintainability.
@@ -703,7 +698,7 @@ Declaration Order
     }
     </script>
 
-The `<template>` Tag
+The <template> Tag
 ====================
 
 Defines the component's UI. Keep templates clear, consistent, and easy to scan.
@@ -829,7 +824,7 @@ Text in Templates
     - **Internationalization**: Correctly wrapping strings with `$gettext()` ensures they are translatable and can be easily localized.
     - **Semantic HTML**: Using inline elements or semantic tags improves accessibility and SEO by providing context to screen readers and search engines.
 
-The `<style>` Tag
+The <style> Tag
 =================
 
 Defines component-scoped CSS. Follow these rules for responsive, maintainable, and themeable styles.