+
+
+- **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., `{{ displayText }}
+
+
+
+
+ {{ isVisible ? formatText(user.name) : '—' }}
+
+
+- **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()`.
+ - Never concatenate translated strings together; use placeholders instead.
+
+- **No loose text nodes**
+ - Surround plain text with an inline element (e.g., ``) or semantic tag.
+
+.. code-block:: vue
+
+
+
+
+ {{ $gettext('Hello,') }}{{ user.name }}!
+
+
+
+
+
+
+
+
+ {{ $gettext('Hello, %{user.name}!') }}
+
+
+
+
+
+- **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
+
+
+
+
+- **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 `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.
+- **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
+
+
+
+- **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.
+
+- **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.
+
+.. 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`.
+
+- **No negative margins**
+ - Negative `margin-*` values are forbidden.
+
+.. code-block:: vue
+
+
+
+- **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
+----------------
+
+- **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:
+
+.. code-block:: css
+
+
+
+- **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
+=======
+
+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.
+
+.. 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.
+
+- **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:: vue
+
+
+
+
+
+
+
+
+
+
+.. 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';
+
+ describe('CounterButton.vue', () => {
+ it('mounts and displays initial count', () => {
+ const wrapper = mount(CounterButton);
+ expect(wrapper.text()).toContain('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('1');
+ });
+ });
+
+- **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.
+
+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
+
+ # Run all tests once
+ npm run vitest
+
+ # Run a specific test file
+ npm run vitest -- src/components/CounterButton.spec.ts
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