@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/forms/rich-media-picker.md

@@ -0,0 +1,132 @@
+# Rich Media Picker (Customizable Select)
+
+The native `<select>` element was historically difficult to style and could only contain plain text options. The `appearance: base-select` property offers a declarative, CSS-only way to opt into a customizable state for the `<select>` element. This allows developers to include rich HTML content—such as images, SVGs, and complex layouts—inside `<option>` elements, while retaining native keyboard accessibility and form integration. Use this pattern to replace heavy, custom-built select components with standard, native elements.
+
+## How to Implement
+
+To implement a rich media picker using the Customizable Select API:
+
+1. **Opt-in to base styles**: Apply `appearance: base-select` to both the `<select>` element and its internal picker using the `::picker(select)` pseudo-element. This changes the browser's HTML parser for the contents inside the `<select>`.
+2. **Define the Button Content**: Use standard `<button>` and `<selectedcontent>` elements inside the `<select>` to define what is shown when the picker is closed. The `<selectedcontent>` element automatically mirrors the content of the selected option. This is required if you want to display the currently selected rich content in the button.
+3. **Use Rich Content inside Options**: You can now place images, SVGs, and other HTML tags inside `<option>` tags. Prior to this API, the browser would strip tags from `<option>` tags and render only plain text.
+4. **Style the Popover**: Style the dropped-down options list by targeting the `::picker(select)` pseudo-element. It renders in the top layer, meaning you don't need to fight with `z-index`. Options are positioned using the Anchor Positioning API natively.
+
+## Example Code: Rich Role Picker
+
+```html
+<label for="role-picker">Select your role</label>
+<select class="custom-select" name="role" id="role-picker">
+  <button>
+    <selectedcontent></selectedcontent> <!-- Mirrors the selected option's content automatically so you do not need JS to update the button -->
+  </button>
+
+  <!-- Define concise aria-label values on options whose mirrored rich content would otherwise read awkwardly as a concatenated string -->
+  <option value="frontend" aria-label="Frontend Developer">
+    <svg aria-hidden="true" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+      <rect x="2" y="3" width="20" height="14" rx="2" ry="2"></rect>
+    </svg>
+    <div class="option-text">
+      <span class="option-title">Frontend Developer</span>
+      <span class="option-desc">React, Vue, CSS</span>
+    </div>
+  </option>
+
+  <option value="backend" aria-label="Backend Developer">
+    <svg aria-hidden="true" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+      <rect x="2" y="12" width="20" height="14" rx="2" ry="2"></rect>
+    </svg>
+    <div class="option-text">
+      <span class="option-title">Backend Developer</span>
+      <span class="option-desc">Node.js, Python</span>
+    </div>
+  </option>
+</select>
+```
+
+```css
+select.custom-select,
+select.custom-select::picker(select) {
+  appearance: base-select; /* MUST opt-in both the select and its picker to enable the customizable state, otherwise browser standard rendering applies */
+}
+
+select.custom-select {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: 12px;
+  background-color: #1e293b;
+  border: 1px solid #334155;
+  border-radius: 8px;
+  color: #f1f5f9;
+  cursor: pointer;
+}
+
+select.custom-select::picker(select) {
+  background-color: #0f172a;
+  border: 1px solid #334155;
+  border-radius: 8px;
+  padding: 8px;
+  box-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.5);
+  width: anchor-size(width); /* Uses Anchor Positioning API to keep the dropdown precisely aligned to the button trigger width */
+}
+
+select.custom-select option {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+select.custom-select option:hover {
+  background-color: #1e293b;
+}
+
+/* Remove standard OS checkmark for base-select */
+select.custom-select option::before {
+  display: none;
+}
+
+/* MANDATORY: Provide multiple visual indicators (e.g., prominent background color and bold title font) to communicate the checked state cleanly */
+select.custom-select option:checked {
+  background-color: #3b82f6;
+  color: #ffffff;
+}
+select.custom-select option:checked .option-title {
+  font-weight: 700;
+}
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `appearance: base-select` when you need complex options layouts (icons, descriptions, images) that was previously only possible with heavy JavaScript UI frameworks.
+- **DO NOT** use ad-hoc elements if you notice performance lags; the browser handles native keyboard focus natively.
+- **DO** account for top-layer rendering. The picker renders in the top-layer, meaning it overrides relative `z-index` of page content.
+- **DO** hide secondary details (like descriptions) in the button state if they take too much space, by styling `.custom-select selectedcontent .option-desc { display: none; }`.
+- **DO** test layout behavior. Setting `appearance: base-select` removes the default browser behavior of sizing the select based on its longest option width. You may need to set a fixed width or use flex/grid constraints to prevent layout shifts.
+- **DO** ensure your `<select>` has a `name` attribute and an associated `<label>`. This ensures that even with a custom UI, the component remains accessible to screen readers and works correctly with standard form submissions.
+
+## Fallback Strategies
+
+### Fallbacks & browser support for Customizable <select>
+
+Customizable <select> has limited availability.
+Supported by: Chrome 135 (Apr 2025) and Edge 135 (Apr 2025).
+Unsupported in: Firefox and Safari.
+
+For browsers that do not yet support `appearance: base-select`, the `<select>` element degrades gracefully to a standard operating system dropdown.
+
+- **Non-Text Content Ignored**: Older browsers strip HTML tags (like `<svg>` or `<div>`) inside `<option>` tags and render only the text nodes. Ensure the text content of the `<option>` is readable and meaningful on its own.
+- **HTML Structure Handling**: Standard parsers may ignore the `<button>` and `<selectedcontent>` tags inside `<select>` or treat them as invalid. No heavy JavaScript polyfills are strictly required for progressive enhancement if you view standard text as a readable fallback.
+
+
+```javascript
+document.addEventListener("DOMContentLoaded", () => {
+  // Check if browser supports base-select value
+  if (!CSS.supports("appearance", "base-select")) {
+    // Custom select overrides are not supported natively.
+  }
+});
+```

package/.agents/skills/modern-web-guidance/guides/forms/select-menu-interaction.md

@@ -0,0 +1,180 @@
+# Select Menu Interaction
+
+## The Problem
+For mandatory dropdowns (e.g., "Choose a Country"), standard validation flags the field as invalid immediately if the default option has an empty value. This can create visual noise. We want to show the error only if the user opens the menu and closes it without choosing an option, or attempts to submit the form.
+
+## The Solution
+The `:user-invalid` pseudo-class works seamlessly with `<select>` elements. It respects the user's interaction flow: simply loading the page or focusing/blurring without making a change doesn't count as an interaction, so the field stays neutral until they actively attempt a selection.
+
+### Implementation Strategy
+
+1.  **HTML Constraint**: Use a `<select>` with `required`. The first option should have `value=""` and ideally be disabled/hidden to force a valid choice.
+2.  **Visual Feedback**: Use `:user-invalid` to style the select box border.
+3.  **Timing**: The browser considers the field "interacted" if the user changes the value (even back to the default invalid state) before they blur the control, or upon form submission.
+
+## Implementation Guide
+
+### 1. HTML Structure
+The "placeholder" option is key here.
+
+```html
+<form>
+  <div class="field">
+    <label for="country">Country</label>
+    <select
+      id="country"
+      name="country"
+      required
+      aria-errormessage="country-error"
+    >
+      <option value="" disabled selected>Select a country...</option>
+      <option value="us">United States</option>
+      <option value="ca">Canada</option>
+      <option value="uk">United Kingdom</option>
+    </select>
+    <div id="country-error" class="error-msg">
+      Please select a country.
+    </div>
+  </div>
+</form>
+```
+
+### 2. CSS
+```css
+.error-msg {
+  display: none;
+  color: #d93025;
+  font-size: 0.875rem;
+  margin-top: 0.25rem;
+}
+
+/*
+  Only show error after the user visits the select menu.
+*/
+select:user-invalid {
+  border-color: #d93025;
+  background-color: #fce8e6;
+}
+
+select:user-invalid + .error-msg {
+  display: block;
+}
+
+select:user-valid {
+  border-color: #188038;
+}
+```
+
+## Fallbacking & Browser Support
+
+The `:user-invalid` pseudo-class is widely supported (Baseline 2023), but if you need to support older browsers, you must ensure consistency of the implementation.
+
+### Fallbacks & browser support for :user-valid and :user-invalid
+
+Baseline status for :user-valid and :user-invalid: Widely available. It's been Baseline since 2023-11-02.
+Supported by: Chrome 119 (Oct 2023), Edge 119 (Nov 2023), Firefox 88 (Apr 2021), and Safari 16.5 (May 2023).
+
+### CSS for Fallback
+
+```css
+input:user-invalid,
+input.user-invalid-fallback {
+  border-color: #d93025;
+  background-color: #fce8e6;
+}
+
+input:user-invalid + .error-msg,
+input.user-invalid-fallback + .error-msg {
+  display: block;
+}
+```
+
+### JavaScript Fallback
+
+Use a reusable utility that tracks interaction state using a `WeakMap`. This avoids polluting the DOM with "dirty" classes or data attributes.
+
+```javascript
+const UserInvalidFallback = (() => {
+  const dirtyState = new WeakMap();
+
+  const updateState = (input) => {
+    const isValid = input.checkValidity();
+
+    // Update both visual and ARIA state
+    input.classList.toggle('user-invalid-fallback', !isValid);
+    input.classList.toggle('user-valid-fallback', isValid);
+
+    if (!isValid) {
+      input.setAttribute('aria-invalid', 'true');
+    } else {
+      input.removeAttribute('aria-invalid');
+    }
+  };
+
+  const handleEvent = (event) => {
+    const input = event.target;
+
+    if (event.type === 'reset') {
+      const controls = input.elements || [];
+      for (const control of controls) {
+        dirtyState.delete(control);
+        control.classList.remove('user-invalid-fallback');
+        control.classList.remove('user-valid-fallback');
+        control.removeAttribute('aria-invalid');
+      }
+      return;
+    }
+
+    if (!input.checkValidity) return;
+
+    if (event.type === 'input' || event.type === 'change') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasInteracted = true;
+      dirtyState.set(input, state);
+      if (state.hasBlurred) {
+        updateState(input);
+      }
+    } else if (event.type === 'blur') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasBlurred = true;
+      dirtyState.set(input, state);
+      if (state.hasInteracted) {
+        updateState(input);
+      }
+    }
+  };
+
+  const init = (root = document) => {
+    if (CSS.supports('selector(:user-invalid)')) return;
+
+    root.addEventListener('blur', handleEvent, true); // Capture phase
+    root.addEventListener('input', handleEvent);
+    root.addEventListener('change', handleEvent);
+    root.addEventListener('reset', handleEvent, true); // Capture resets
+  };
+
+  return { init };
+})();
+
+// Initialize for a specific form
+const form = document.querySelector('#demo-form');
+UserInvalidFallback.init(form);
+```
+
+## Other Considerations
+
+1.  **Mobile behavior**: On mobile devices, "blur" might happen differently depending on the OS picker. Testing on actual devices is recommended.
+2.  **Accessibility**: Native `:user-invalid` does not automatically sync with ARIA attributes. Add the following JavaScript to keep `aria-invalid` in sync with the visual state:
+
+```javascript
+// Sync aria-invalid with the CSS :user-invalid state
+const syncAria = (el) => {
+  el.setAttribute?.('aria-invalid', el.matches(':user-invalid') ? 'true' : 'false');
+};
+
+// Update on blur (to show error) and input (to clear it)
+document.addEventListener('blur', (e) => syncAria(e.target), true);
+document.addEventListener('input', (e) => {
+  if (e.target.hasAttribute('aria-invalid')) syncAria(e.target);
+});
+```

package/.agents/skills/modern-web-guidance/guides/forms/validate-input-after-interaction.md

@@ -0,0 +1,258 @@
+# Validate Input After Interaction
+
+## The Problem
+
+Displaying validation errors the moment a user focuses on a field and starts typing is premature and distracting. For example, as a user types an email address (e.g., "user@gm") or a password with complex requirements, the field is technically invalid until completion. Standard `:invalid` styling results in an error state appearing immediately, frustrating the user.
+
+## The Solution
+
+The `:user-invalid` pseudo-class allows you to defer the error state until the user has "committed" to a value (by blurring the field) or attempted to submit the form. This ensures validation feedback is provided only after the user has finished interacting with the field.
+
+### Implementation Strategy
+
+1.  **HTML Constraint**: DO use standard HTML5 attributes like `type="email"`, `pattern`, and `required` to trigger the browser's built-in validation logic.
+2.  **Visual Feedback**: DO use `:user-invalid` to apply error styling only after interaction.
+3.  **Positive Reinforcement**: DO optionally use `:user-valid` to give a green "success" indicator once the requirements are met.
+4.  **Graceful Recovery**: As soon as the user corrects the input to a valid format, `:user-invalid` stops matching, removing the error state immediately.
+
+## Implementation Guide
+
+### Use Case 1: Email Validation
+
+MANDATORY: Rely on standard HTML5 attributes for email fields. The error message is hidden by default and only revealed when the browser determines the user has left the field in an invalid state.
+
+```html
+<form>
+  <div class="field">
+    <label for="email">Email Address</label>
+    <!-- MANDATORY: Place format hints above the input so autocomplete popovers don't cover them during editing -->
+    <span id="email-hint" class="hint">Format: you@example.com</span>
+    <!-- DO: Use standard HTML validation attributes like type="email" and required -->
+    <input
+      type="email"
+      id="email"
+      name="email"
+      required
+      autocomplete="email"
+      aria-describedby="email-hint"
+      aria-errormessage="email-error"
+    >
+    <div id="email-error" class="error-msg">
+      <span aria-hidden="true">❌</span> Please enter a valid email address.
+    </div>
+  </div>
+</form>
+```
+
+```css
+.hint {
+  display: block;
+  color: #5f6368;
+  font-size: 0.85rem;
+  margin-bottom: 0.25rem;
+}
+
+.error-msg {
+  display: none;
+  color: #d93025;
+  font-size: 0.875rem;
+  margin-top: 0.25rem;
+}
+
+/*
+  DO: Only show error styles after user interaction.
+  Use multiple indicators (border/background shift + icon/text) to avoid color-only states.
+*/
+input:user-invalid {
+  border-color: #d93025;
+  background-color: #fce8e6;
+}
+
+/* DO: Reveal the error message using the adjacent sibling selector */
+input:user-invalid + .error-msg {
+  display: block;
+}
+
+/* DO: Provide a clear success indication on :user-valid */
+input:user-valid {
+  border-color: #188038;
+}
+```
+
+### Use Case 2: Password Complexity
+
+MANDATORY: Define the complexity rule using a Regex Lookahead pattern in the `pattern` attribute. The rules list is shown above the input to guide the user, and highlighted if there's an error.
+
+```html
+<form>
+  <div class="field">
+    <label for="password">New Password</label>
+    <!-- MANDATORY: Place hints and rules above the input so mobile keyboards do not obscure them -->
+    <ul id="password-rules" class="rules-list">
+      <li>At least 8 characters</li>
+      <li>One uppercase letter</li>
+      <li>One number</li>
+      <li>One special character</li>
+    </ul>
+    <!-- DO: Use pattern and minlength for complex password validation
+         DO: Match all constraints with lookaheads via pattern attribute
+     -->
+    <input
+      type="password"
+      id="password"
+      autocomplete="new-password"
+      required
+      pattern="(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[\W_]).{8,}"
+      minlength="8"
+      aria-describedby="password-rules"
+    >
+  </div>
+</form>
+```
+
+```css
+/* DO: State the default styling as neutral */
+.rules-list { 
+  color: #5f6368; 
+  margin-bottom: 0.5rem;
+}
+
+/* DO: Show invalid state (After interaction): Error */
+input:user-invalid {
+  border-color: #d93025;
+  background-color: #fce8e6;
+}
+
+/* DO: Highlight rules list when error is shown using the modern :has() selector */
+.field:has(input:user-invalid) .rules-list {
+  color: #d93025;
+  font-weight: 600;
+}
+
+/* DO: Add success indications for :user-valid state */
+input:user-valid {
+  border-color: #188038;
+}
+
+/* DO: Hide rules once satisfied */
+.field:has(input:user-valid) .rules-list {
+  display: none;
+}
+```
+
+## Fallbacking & Browser Support
+
+### Fallbacks & browser support for :user-valid and :user-invalid
+
+Baseline status for :user-valid and :user-invalid: Widely available. It's been Baseline since 2023-11-02.
+Supported by: Chrome 119 (Oct 2023), Edge 119 (Nov 2023), Firefox 88 (Apr 2021), and Safari 16.5 (May 2023).
+
+### CSS for Fallback
+
+```css
+input:user-invalid,
+input.user-invalid-fallback {
+  border-color: #d93025;
+  background-color: #fce8e6;
+}
+
+input:user-invalid + .error-msg,
+input.user-invalid-fallback + .error-msg {
+  display: block;
+}
+```
+
+### JavaScript Fallback
+
+Use a reusable utility that tracks interaction state using a `WeakMap`. This avoids polluting the DOM with "dirty" classes or data attributes.
+
+```javascript
+const UserInvalidFallback = (() => {
+  const dirtyState = new WeakMap();
+
+  const updateState = (input) => {
+    const isValid = input.checkValidity();
+
+    // Update both visual and ARIA state
+    input.classList.toggle('user-invalid-fallback', !isValid);
+    input.classList.toggle('user-valid-fallback', isValid);
+
+    if (!isValid) {
+      input.setAttribute('aria-invalid', 'true');
+    } else {
+      input.removeAttribute('aria-invalid');
+    }
+  };
+
+  const handleEvent = (event) => {
+    const input = event.target;
+
+    if (event.type === 'reset') {
+      const controls = input.elements || [];
+      for (const control of controls) {
+        dirtyState.delete(control);
+        control.classList.remove('user-invalid-fallback');
+        control.classList.remove('user-valid-fallback');
+        control.removeAttribute('aria-invalid');
+      }
+      return;
+    }
+
+    if (!input.checkValidity) return;
+
+    if (event.type === 'input' || event.type === 'change') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasInteracted = true;
+      dirtyState.set(input, state);
+      if (state.hasBlurred) {
+        updateState(input);
+      }
+    } else if (event.type === 'blur') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasBlurred = true;
+      dirtyState.set(input, state);
+      if (state.hasInteracted) {
+        updateState(input);
+      }
+    }
+  };
+
+  const init = (root = document) => {
+    if (CSS.supports('selector(:user-invalid)')) return;
+
+    root.addEventListener('blur', handleEvent, true); // Capture phase
+    root.addEventListener('input', handleEvent);
+    root.addEventListener('change', handleEvent);
+    root.addEventListener('reset', handleEvent, true); // Capture resets
+  };
+
+  return { init };
+})();
+
+// Initialize for a specific form
+const form = document.querySelector('#demo-form');
+UserInvalidFallback.init(form);
+```
+
+## Other Considerations
+
+1.  **Accessibility**:
+    *   MANDATORY: Use `aria-describedby` to link the rules list to the input.
+    *   DO NOT: Hide rules lists entirely until the input is valid; users need to know what to type!
+2.  **Pattern Attribute Limits**: MANDATORY: The `pattern` attribute performs a full match (implied `^...$`). Ensure your password regex accounts for the entire string.
+3.  **Validation Strictness**: DO note that the browser's default `type="email"` validation is quite permissive (e.g., `user@localserver` might pass). If you need stricter validation, you may need to use a more robust validation library or a custom validation function alongside `type="email"`.
+4.  **Focus Management**: MANDATORY: If a user submits the form with an invalid field, the browser will automatically focus the first invalid field. Your `:user-invalid` styles will apply immediately because a submission attempt counts as an interaction.
+5. **Consistent ARIA Experience**: Native `:user-invalid` does not automatically sync with ARIA attributes. Add the following JavaScript to keep `aria-invalid` in sync with the visual state:
+
+```javascript
+// Sync aria-invalid with the CSS :user-invalid state
+const syncAria = (el) => {
+  el.setAttribute?.('aria-invalid', el.matches(':user-invalid') ? 'true' : 'false');
+};
+
+// Update on blur (to show error) and input (to clear it)
+document.addEventListener('blur', (e) => syncAria(e.target), true);
+document.addEventListener('input', (e) => {
+  if (e.target.hasAttribute('aria-invalid')) syncAria(e.target);
+});
+```