srcdev-nuxt-components 8.0.2 → 9.0.0

package/README.md

@@ -1,5 +1,9 @@
 # SRCDEV Nuxt Components
 
+[![Tests](https://github.com/srcdev/nuxt-components/workflows/Tests/badge.svg)](https://github.com/srcdev/nuxt-components/actions/workflows/test.yml)
+[![npm version](https://badge.fury.io/js/srcdev-nuxt-components.svg)](https://badge.fury.io/js/srcdev-nuxt-components)
+[![License](https://img.shields.io/github/license/srcdev/nuxt-components.svg)](https://github.com/srcdev/nuxt-components/blob/main/LICENSE)
+
 ## NOTE
 
 Althought this repo is public and feel free to do what you wish with it, this has been developed for use with websites we develop.
@@ -13,127 +17,20 @@ npm install --save srcdev-nuxt-components
 ```ts
 defineNuxtConfig({
   extends: "srcdev-nuxt-components",
-})
+});
 ```
 
-## Styles Architecture
-
-The `/assets/styles` directory contains a modular CSS architecture designed for scalability and maintainability. The styles are organized into the following structure:
-
-### Main Entry Point
-
-- **`main.css`** - Primary entry point that imports all style modules
-
-### Setup Layer (`/setup`)
-
-The setup layer provides the foundational styles and utilities:
-
-#### Core Configuration
-
-- **`_head.css`** - Root-level CSS custom properties including:
-  - Font size and line height defaults
-  - Primary font family stack (futura-pt, Seravek, 'Gill Sans Nova', Ubuntu, Calibri, 'DejaVu Sans', source-sans-pro, sans-serif)
-
-#### Variables (`/variables`)
-
-- **Color System** - Comprehensive color palette with semantic naming:
-  - `_blue.css` - Blue color scale (--blue-0 to --blue-12)
-  - `_gray.css` - Gray color scale
-  - `_green.css` - Green color scale
-  - `_orange.css` - Orange color scale
-  - `_red.css` - Red color scale
-  - `_yellow.css` - Yellow color scale
-
-#### Typography (`/typography`)
-
-- **Responsive Font Sizes** - Fluid typography using clamp() functions:
-  - `--step-8` to `--step-1` providing 8 responsive font size steps
-- **Utility Classes** - Pre-built typography classes:
-  - `.page-heading-1` through `.page-heading-5` - Semantic heading styles
-  - Generic font weight and variation settings
-- **Font Variation Settings** - Advanced typography controls
-
-#### Utility Classes (`/utility-classes`)
-
-- **Spacing Helpers**:
-  - `_margin-helpers.css` - Comprehensive margin utilities (`.mi-auto`, `.mb-0`, etc.)
-  - `_padding-helpers.css` - Padding utility classes
-- **Page Layout** - Base page styling (`_page.css`)
-
-#### Accessibility (`/a11y`)
-
-- **Screen Reader Utilities** - `.sr-only` class for accessible hidden content
-- **A11y Variables** - Accessibility-focused CSS custom properties
-- **Utility Functions** - Helper classes for improved accessibility
-
-### Component Layer (`/extends-layer/srcdev-components`)
-
-Component-specific styles for the included components:
-
-#### Display Prompt Component
-
-- **`_scaffolding.css`** - Core component structure with CSS custom properties:
-  - Wrapper styling (border-radius, layout)
-  - Inner content styling (margin, padding, gap)
-  - Icon sizing and positioning
-  - Content spacing and typography
-- **Themes** - Pre-built component variants:
-  - `_error.css` - Error state styling
-  - `_info.css` - Information state styling
-  - `_success.css` - Success state styling
-  - `_warning.css` - Warning state styling
-
-### Import Structure
-
-The styles follow a cascading import pattern:
-
-```text
-main.css
-├── setup/
-│   ├── index.css
-│   ├── _head.css
-│   ├── utility-classes/
-│   │   ├── index.css
-│   │   ├── _margin-helpers.css
-│   │   ├── _padding-helpers.css
-│   │   └── _page.css
-│   ├── a11y/
-│   │   ├── index.css
-│   │   ├── _utils.css
-│   │   └── _variables.css
-│   ├── variables/
-│   │   ├── index.css
-│   │   └── colors/
-│   │       ├── index.css
-│   │       ├── _blue.css
-│   │       ├── _gray.css
-│   │       ├── _green.css
-│   │       ├── _orange.css
-│   │       ├── _red.css
-│   │       └── _yellow.css
-│   └── typography/
-│       ├── index.css
-│       ├── utility-classes/
-│       │   ├── index.css
-│       │   ├── _generic-font-classes.css
-│       │   ├── _generic-font-variation-settings.css
-│       │   └── _generic-font-weights.css
-│       └── vars/
-│           ├── index.css
-│           └── _reponsive-font-sizes.css
-└── extends-layer/srcdev-components/
-    ├── index.css
-    ├── display-prompt-core/
-    │   └── index.css
-    └── themes/
-        ├── index.css
-        ├── _error.css
-        ├── _info.css
-        ├── _success.css
-        └── _warning.css
-```
+## Known Dev Server Warnings
+
+### `[request error] [GET] http://localhost:3000/_nuxt/` (404)
+
+This error appears in the terminal when running `npm run dev` and is **harmless** — it does not affect dev server operation.
+
+**Cause**: The Vue/Nuxt browser DevTools extension probes `/_nuxt/` to detect if the page is a Nuxt app. Since `/_nuxt/` is a directory (not a file), the server returns 404 and logs it.
 
-This architecture ensures proper CSS cascade order and allows for easy customization through CSS custom properties.
+**Resolution**: It cannot be suppressed without disabling the browser extension. Since the DevTools extension is useful for inspecting Pinia stores and component state, the recommended approach is to ignore this warning.
+
+---
 
 ## Development Environment (`.vscode`)
 
@@ -162,6 +59,161 @@ The `.vscode` directory contains Visual Studio Code configuration files to ensur
 
 The `.vscode` directory includes comprehensive code snippets for rapid component development:
 
+## Contact Form — Resend Setup
+
+The contact form at `/ui/contact-section` sends enquiries via [Resend](https://resend.com).
+No extra packages are required — the server route calls the Resend REST API directly.
+
+### 1. Create a Resend account
+
+Sign up at [resend.com](https://resend.com). The free tier allows 3,000 emails/month (100/day),
+which is more than sufficient for a contact form.
+
+### 2. Verify a sending domain
+
+In the Resend dashboard go to **Domains → Add Domain** and follow the DNS instructions for your
+domain. This is required before you can send from a custom `from` address in production.
+
+> **Local development shortcut:** you can skip domain verification and use Resend's shared sandbox
+> address `onboarding@resend.dev` as the `from` address. Emails will only be delivered to the
+> email address registered on your Resend account, so it is safe for testing.
+
+### 3. Create an API key
+
+In the Resend dashboard go to **API Keys → Create API Key**. Copy the key — it is only shown once.
+
+### 4. Configure environment variables
+
+Copy `.env.example` to `.env` and fill in the three values:
+
+```bash
+cp .env.example .env
+```
+
+```env
+NUXT_RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
+NUXT_CONTACT_EMAIL_TO=you@yourdomain.com
+NUXT_CONTACT_EMAIL_FROM=Enquiries <hello@yourdomain.com>
+```
+
+| Variable                  | Description                                                                |
+| ------------------------- | -------------------------------------------------------------------------- |
+| `NUXT_RESEND_API_KEY`     | API key from the Resend dashboard                                          |
+| `NUXT_CONTACT_EMAIL_TO`   | The inbox that receives enquiries                                          |
+| `NUXT_CONTACT_EMAIL_FROM` | The "from" address shown to recipients — must use a verified Resend domain |
+
+Nuxt maps `NUXT_*` variables to `runtimeConfig` automatically at runtime. The values are
+**server-only** and never included in the client bundle.
+
+### 5. Vercel deployment
+
+Rather than committing a `.env` file, add the variables directly in the Vercel dashboard:
+
+1. Open your project in [vercel.com](https://vercel.com)
+2. Go to **Settings → Environment Variables**
+3. Add each of the three `NUXT_*` variables, setting the environment to **Production**
+   (and **Preview** if you want the form to work on preview deployments too)
+4. Redeploy — Vercel injects the variables at build and runtime automatically
+
+> `.env` is listed in `.gitignore` and should never be committed to the repository.
+
+---
+
+## Testing
+
+This project has two test layers that run independently.
+
+---
+
+### Unit & Snapshot Tests (Vitest)
+
+Runs component logic, HTML structure, and snapshot regression tests. No browser or running server required.
+
+```bash
+# Run in watch mode (development)
+npm run test
+
+# Run once (CI / pre-commit)
+npm run test:run
+
+# Open the Vitest UI (browser-based test explorer)
+npm run test:ui
+
+# Update snapshots after an intentional component change
+npm run test:update
+```
+
+---
+
+### Visual Regression Tests (Playwright)
+
+Runs pixel-level screenshot comparisons against Storybook. Requires Storybook to be running first.
+
+```bash
+# 1. Start Storybook
+npm run storybook:serve
+
+# 2. In a separate terminal, run visual tests
+npm run playwright
+
+# Update visual baselines after an intentional visual change
+npm run playwright:update
+
+# View Playwright test report
+npx playwright show-report
+```
+
+> Visual tests run across Chromium, Firefox, and WebKit. Snapshot baselines are stored per browser — expect three PNG files per component test.
+
+---
+
+### What Each Layer Catches
+
+| Change                                | Unit tests | Visual tests |
+| ------------------------------------- | ---------- | ------------ |
+| Class added / removed                 | ✅         | ✅           |
+| HTML structure changed                | ✅         | ✅           |
+| Font weight / color / spacing changed | ❌         | ✅           |
+| Prop or slot logic broken             | ✅         | ❌           |
+| Accessibility attribute missing       | ✅         | ❌           |
+
+---
+
+## Storybook
+
+Storybook is used for isolated component development and as the target for visual regression tests. It runs as a separate Vite-based dev server.
+
+### Scripts
+
+```bash
+# Start Storybook dev server (http://localhost:6006)
+npm run storybook
+
+# Build a static Storybook (outputs to storybook-static/)
+npm run storybook:build
+
+# Build and serve locally — used before running Playwright visual tests
+npm run storybook:serve
+
+# Clear Storybook and Vite caches — run this if styles appear stale after changes
+npm run storybook:cache:clean
+```
+
+> After clearing the cache, restart with `npm run storybook`. The cache clear is particularly
+> useful when changes inside `@layer` CSS blocks are not reflected in the running dev server.
+
+### Fonts
+
+`@nuxt/fonts` is disabled in Storybook (detected via `process.env.STORYBOOK` in `nuxt.config.ts`).
+Fonts are served instead from local files in `.storybook/public/_fonts/`, declared in `.storybook/fonts.css` and imported in `.storybook/preview.ts`.
+
+| Font             | Format | Source                                       |
+| ---------------- | ------ | -------------------------------------------- |
+| Poppins          | TTF    | `.storybook/public/_fonts/poppins/`          |
+| Playfair Display | woff2  | `.storybook/public/_fonts/playfair-display/` |
+
+To add a new font, see [.claude/skills/storybook-add-font.md](.claude/skills/storybook-add-font.md).
+
 #### Core Components
 
 - **`srcdev-nuxt3-component-boilerplate.code-snippets`** - Base component template with prop validation

package/app/assets/styles/extends-layer/srcdev-components/components/_display-prompt-core.css

@@ -0,0 +1,94 @@
+.srcdev-components-extended {
+  .display-prompt-core {
+    .display-prompt-wrapper {
+      background-color: var(--colour-theme-8);
+      border: 0px solid transparent;
+      border-radius: 4px;
+      border-start-start-radius: 8px;
+      border-end-start-radius: 8px;
+      padding-inline-start: 8px;
+
+      &:not(.dark) {
+        &.outlined {
+          border: 1px solid var(--colour-theme-8);
+        }
+      }
+
+      &.dark {
+        border-width: 0;
+
+        .display-prompt-inner {
+          background-color: var(--slate-10);
+        }
+
+        &.outlined {
+          border: 1px solid var(--colour-theme-8);
+        }
+      }
+
+      .display-prompt-inner {
+        align-items: center;
+        gap: 12px;
+        padding-block: 1rem;
+        padding-inline: 1.5rem;
+
+        border-start-start-radius: 8px;
+        border-end-start-radius: 8px;
+        background-color: var(--colour-theme-10);
+
+        .display-prompt-icon {
+          .icon {
+            color: var(--colour-theme-0);
+            font-size: 3rem;
+            font-style: normal;
+            font-weight: normal;
+          }
+        }
+
+        .display-prompt-content {
+          gap: 1rem;
+          margin: 0;
+          padding: 0.2rem;
+
+          .title {
+            font-size: var(--step-5);
+            font-weight: bold;
+            line-height: 1.3;
+            color: var(--colour-theme-0);
+            margin: 0;
+            padding: 0;
+          }
+
+          .text {
+            font-size: var(--step-4);
+            font-weight: normal;
+            line-height: 1.3;
+            color: var(--colour-theme-0);
+            margin: 0;
+            padding: 0;
+          }
+        }
+        .display-prompt-action {
+          background-color: transparent;
+          align-items: center;
+          margin: 1rem;
+          padding: 0.5rem;
+          border: 0.1rem solid var(--colour-theme-8);
+          border-radius: 50%;
+          outline: 1px solid var(--colour-theme-3);
+
+          &:hover {
+            cursor: pointer;
+          }
+
+          .icon {
+            color: var(--colour-theme-0);
+            font-size: var(--step-5);
+            border: 1px solid green;
+            padding: 1rem;
+          }
+        }
+      }
+    }
+  }
+}

package/app/assets/styles/extends-layer/srcdev-components/components/_display-toast.css

@@ -0,0 +1,5 @@
+.srcdev-components-extended {
+  .display-toast {
+    /* Extend styles for the display toast component */
+  }
+}

package/app/assets/styles/extends-layer/srcdev-components/components/_expanding-panel.css

@@ -0,0 +1,37 @@
+.srcdev-components-extended {
+  .expanding-panel {
+    .expanding-panel-details {
+      .expanding-panel-summary {
+        &::-webkit-details-marker,
+        &::marker {
+          display: none;
+        }
+
+        .label-wrapper {
+        }
+        .icon-wrapper {
+          .icon {
+          }
+        }
+      }
+
+      &[open] {
+        .expanding-panel-summary {
+          .icon-wrapper {
+            .icon {
+            }
+          }
+        }
+        + .expanding-panel-content {
+          .inner {
+          }
+        }
+      }
+    }
+
+    .expanding-panel-content {
+      .inner {
+      }
+    }
+  }
+}

package/app/assets/styles/extends-layer/srcdev-components/components/index.css

@@ -0,0 +1,3 @@
+@import "./_display-prompt-core";
+@import "./_expanding-panel";
+@import "./_display-toast";

package/app/assets/styles/extends-layer/srcdev-components/index.css

@@ -0,0 +1 @@
+@import "./components";

package/app/assets/styles/extends-layer/srcdev-forms/components/_form-fieldset.css

@@ -0,0 +1,38 @@
+.srcdev-forms-extended {
+  .form-fieldset {
+    margin: 0;
+    padding: 0;
+    border: 0;
+
+    &.single-checkbox-fieldset {
+    }
+
+    &.multiple-checkboxes-fieldset {
+    }
+
+    &.multiple-radiobuttons-fieldset {
+    }
+
+    .form-fieldset-legend {
+      color: var(--form-fieldset-legend-color);
+      margin-block: 0.8rem;
+      font-size: var(--step-5);
+      font-weight: normal;
+      line-height: 1.5;
+
+      &.has-description {
+        margin-bottom: 0;
+      }
+    }
+
+    .form-fieldset-description {
+      font-size: 1.6rem;
+      margin-top: 1.2rem;
+    }
+
+    .form-fieldset-content {
+      margin-block-start: 0;
+      margin-block-end: 0;
+    }
+  }
+}

package/app/assets/styles/extends-layer/srcdev-forms/components/_input-button.css

@@ -0,0 +1,67 @@
+.srcdev-forms-extended {
+  .input-button-core {
+    gap: var(--form-button-icon-gap);
+    border-radius: var(--form-input-border-radius);
+
+    padding-inline: var(--form-button-padding-inline);
+    padding-block-start: var(--form-element-padding-block-start);
+    padding-block-end: var(--form-element-padding-block-end);
+
+    box-shadow: var(--box-shadow-off);
+    background-color: var(--theme-button-surface);
+    border: var(--form-element-border-width) solid var(--theme-button-border);
+    color: var(--theme-button-text);
+    outline: var(--form-element-outline-width) solid var(--theme-button-outline);
+    outline-offset: var(--form-element-outline-offset-focus);
+
+    &:hover {
+      background-color: var(--theme-button-surface-hover);
+      border-color: var(--theme-button-border-hover);
+      color: var(--theme-button-text-hover);
+      outline-color: var(--theme-button-outline-hover);
+      outline-offset: var(--form-element-outline-offset-focus);
+    }
+
+    &:focus-visible {
+      background-color: var(--theme-button-surface-hover);
+      border-color: var(--theme-button-border-hover);
+      color: var(--theme-button-text-focus);
+      outline-color: var(--theme-button-outline-focus);
+      outline-offset: var(--form-element-outline-offset-focus);
+    }
+
+    &[readonly] {
+      opacity: 0.5;
+      &:hover,
+      &:focus-visible {
+        cursor: not-allowed;
+      }
+    }
+
+    &.icon-only {
+      aspect-ratio: 1;
+      height: var(--form-icon-only-button-size);
+      width: var(--form-icon-only-button-size);
+      margin: 0;
+      padding: 0;
+    }
+
+    .btn-text {
+      display: inline-block;
+      white-space: nowrap;
+      font-size: var(--form-element-font-size);
+      line-height: var(--input-element-line-height);
+    }
+
+    .btn-icon {
+      display: flex;
+      .icon {
+        aspect-ratio: 1;
+        display: inline-block;
+        height: var(--form-icon-size);
+        width: var(--form-icon-size);
+        color: var(--theme-button-icon-color);
+      }
+    }
+  }
+}

package/app/assets/styles/extends-layer/srcdev-forms/components/_input-checkbox-radio-core.css

@@ -0,0 +1,87 @@
+.srcdev-forms-extended {
+  .input-checkbox-radio-wrapper {
+    background-color: var(--theme-checkbox-symbol-surface);
+    border: var(--form-element-border-width) solid var(--theme-input-border);
+    outline: var(--form-element-outline-width) solid var(--theme-input-outline);
+    box-shadow: var(--_box-shadow);
+
+    &.x-small {
+      --input-checked-element-size: var(--step-3);
+      --input-checked-icon-size: var(--step-2);
+    }
+
+    &.small {
+      --input-checked-element-size: var(--step-4);
+      --input-checked-icon-size: var(--step-3);
+    }
+
+    &.default {
+      --input-checked-element-size: var(--step-7);
+      --input-checked-icon-size: var(--step-6);
+    }
+
+    &.medium {
+      --input-checked-element-size: var(--step-6);
+      --input-checked-icon-size: var(--step-5);
+    }
+
+    &.large {
+      --input-checked-element-size: var(--step-6);
+      --input-checked-icon-size: var(--step-5);
+    }
+
+    &.checkbox {
+      border-radius: var(--form-input-border-radius);
+      &.button {
+        &.display-as-disc {
+          border-radius: 50%;
+        }
+      }
+    }
+
+    &.radio {
+      border-radius: 50%;
+    }
+
+    &:hover {
+      /* Duplicate within _input-checkbox-radio-with-label.css */
+      background-color: var(--theme-input-surface-hover);
+      outline-color: var(--theme-input-outline-hover);
+      outline-offset: var(--form-element-outline-offset-hover);
+    }
+
+    &:has(.input-checkbox-radio-core:checked) {
+      .input-checked-icon-slot {
+        .input-checked-icon-checked {
+          color: var(--theme-checkbox-symbol-color);
+        }
+      }
+    }
+
+    /* focus-visible */
+    &:not(.button):focus-within {
+      background-color: var(--theme-input-surface-focus);
+      outline-color: var(--theme-input-outline-focus);
+      outline-offset: var(--form-element-outline-offset-focus);
+    }
+
+    .input-checked-icon-checked,
+    .icon {
+      color: var(--theme-checkbox-symbol-color);
+      box-shadow: var(--_box-shadow);
+    }
+
+    .input-checkbox-radio-core {
+      margin: 0;
+      opacity: 0;
+
+      &:not(.is-button) {
+        &:focus-visible {
+          /* background-color: var(--theme-input-surface-focus);
+          outline-color: var(--theme-input-outline-focus);
+          outline-offset: var(--form-element-outline-offset-focus); */
+        }
+      }
+    }
+  }
+}