@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/user-experience/style-parent-with-has.md

@@ -0,0 +1,199 @@
+# Style Parent with :has()
+
+## The Problem
+Often, an error state requires styling elements *outside* the input itself—for example, changing the color of a parent `fieldset` border, highlighting the `<label>`, or showing a global error icon in the card header. Historically, this required JavaScript to toggle classes on parent elements.
+
+## The Solution
+By combining `:has()` with `:user-invalid`, we can declaratively style any ancestor based on the validity state of a specific descendant. This keeps all presentation logic in CSS.
+
+### Implementation Strategy
+
+1.  **Selector**: Use `.parent:has(:user-invalid)` to target the container.
+2.  **Scope**: Be specific to avoid performance issues. Target `.field-group` rather than `body`.
+3.  **Fallback**: Requires JS to toggle classes on the parent if `:has()` is not supported.
+
+## Implementation Guide
+
+### 1. HTML Structure
+```html
+<form>
+  <div class="card-section">
+    <div class="header">
+      <h3>Profile Settings</h3>
+      <span class="status-icon"></span>
+    </div>
+
+    <div class="field">
+      <label for="username">Username</label>
+      <input type="text" id="username" required>
+    </div>
+  </div>
+</form>
+```
+
+### 2. CSS
+```css
+/* Default State */
+.card-section {
+  border: 1px solid #ccc;
+  border-left: 4px solid #ccc;
+}
+
+/*
+  Parent Styling Logic:
+  If the card contains ANY user-invalid input, turn the whole card's edge red.
+*/
+.card-section:has(:user-invalid) {
+  border-left-color: #d93025;
+  background-color: #fff8f8;
+}
+
+/* Change the icon too */
+.card-section:has(:user-invalid) .status-icon::after {
+  content: "⚠️";
+}
+```
+
+## 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.
+
+### CSS for Fallback
+We use a class `.has-error` on the parent to mimic the `:has()` behavior.
+
+```css
+/* Native */
+.card-section:has(:user-invalid) {
+  border-left-color: #d93025;
+}
+
+/* Fallback */
+.card-section.has-error-fallback {
+  border-left-color: #d93025;
+}
+```
+
+### 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);
+```
+
+```js
+// 1. Initialize the generic fallback
+const form = document.querySelector('#demo-form');
+UserInvalidFallback.init(form);
+
+// 2. Add specialized "parent styling" logic (Separate from fallback)
+// Listen for changes to form validity after interaction
+form.addEventListener('blur', (e) => {
+  if (!e.target.matches('input, select, textarea')) return;
+
+  // Find the container we want to style (sync with CSS)
+  const container = e.target.closest('.card-section');
+  if (!container) return;
+
+  // Check if ANY fallbacked input in this container is invalid
+  const hasError = container.querySelector('.user-invalid-fallback');
+  container.classList.toggle('has-error-fallback', !!hasError);
+}, true); // Capture phase to ensure we run after the fallback's blur listener
+
+// Also handle input events for immediate cleanup
+form.addEventListener('input', (e) => {
+  const container = e.target.closest('.card-section');
+  if (container) {
+    const hasError = container.querySelector('.user-invalid-fallback');
+    container.classList.toggle('has-error-fallback', !!hasError);
+  }
+});
+
+// Handle form resets
+form.addEventListener('reset', () => {
+  form.querySelectorAll('.has-error-fallback').forEach(el => {
+    el.classList.remove('has-error-fallback');
+  });
+});
+```
+
+## Other Considerations
+
+1.  **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/user-experience/support-global-calendar-systems.md

@@ -0,0 +1,107 @@
+# Supporting Global Calendar Systems with Temporal
+
+The traditional JavaScript `Date` object is based on a proleptic Gregorian calendar, making it challenging to build applications for users who rely on other calendar systems, such as the Islamic (lunar), Hebrew (lunisolar), or Chinese (lunisolar) calendars. Developers previously had to rely on complex third-party libraries or manual calculations to support these systems.
+
+The `Temporal` API provides first-class support for multiple calendar systems. By associating a calendar identifier with date objects, Temporal handles the complex arithmetic and formatting required for different cultural contexts natively.
+
+## How to Implement
+
+To support global calendar systems using Temporal:
+
+1. **Associate a Calendar (Mandatory):** When creating or converting a Temporal object (like `Temporal.PlainDate`), you must specify the desired calendar system using `withCalendar()` to perform calendar-sensitive operations.
+2. **Use Stable Identifiers (Mandatory for Lunisolar Calendars):** You must use `monthCode` rather than the numeric `month` index to identify specific months across years in lunisolar calendars. Only use this for calendars that use leap months, such as the Hebrew and Chinese calendars.
+3. **Respect Calendar Invariants (Mandatory):** When iterating through months or days, you must not assume fixed values (like 12 months in a year or 31 days in a month). Use properties like `monthsInYear` and `daysInMonth` to ensure your code works across all calendars.
+4. **Use Calendar-Aware Comparisons (Mandatory):** When comparing dates within a specific calendar system, you must use `Temporal.PlainDate.compare()` instead of comparing year/month/day properties manually. This correctly handles chronological ordering within the calendar rules.
+
+## Example Code: Converting and Iterating Calendars
+
+```javascript
+// 1. Helper to check calendar support
+function isCalendarSupported(calendarId) {
+  try {
+    return Intl.supportedValuesOf('calendar').includes(calendarId);
+  } catch {
+    // Fallback for environments where supportedValuesOf is not available
+    return false;
+  }
+}
+
+// 2. Get current date in default ISO 8601 calendar
+const isoDate = Temporal.Now.plainDateISO();
+
+// 3. Convert to Hebrew calendar if supported
+const calendarId = 'hebrew';
+const targetDate = isCalendarSupported(calendarId) 
+  ? isoDate.withCalendar(calendarId)
+  : isoDate; // Fallback to ISO if not supported
+
+if (targetDate.calendar.id !== calendarId) {
+  console.warn(`Calendar ${calendarId} not supported; falling back to ISO 8601`);
+}
+
+// 4. Log properties specific to the calendar
+console.log(`Calendar: ${targetDate.calendar.id}`);
+console.log(`Year: ${targetDate.year}`);
+console.log(`Month Code: ${targetDate.monthCode}`); // Stable across leap years
+
+// 5. Safely iterate through months in the current year
+for (let m = 1; m <= targetDate.monthsInYear; m++) {
+  console.log(`Month ${m} has ${targetDate.with({ month: m }).daysInMonth} days.`);
+}
+
+// 6. Compare dates within the same calendar
+const today = Temporal.Now.plainDateISO().withCalendar(calendarId);
+const comparison = Temporal.PlainDate.compare(targetDate, today);
+const relative = comparison < 0 ? 'Past' : comparison > 0 ? 'Future' : 'Today';
+console.log(`Timeline: ${relative}`);
+
+// 7. Format for display using toLocaleString
+const localizedDisplay = targetDate.toLocaleString('en-u-ca-hebrew', {
+  day: 'numeric',
+  month: 'long',
+  year: 'numeric'
+});
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `monthsInYear` as the upper bound when looping through months, rather than assuming 12.
+- **DO** use `monthCode` for identifying specific months in calendars that use leap months (e.g., Hebrew or Chinese), regardless of the year.
+- **DO NOT** assume `date.month === 12` is the last month of the year. Use `date.month === date.monthsInYear`.
+- **DO NOT** assume `inLeapYear === true` implies the year is only one day longer. In lunisolar calendars, it may add a full leap month.
+- **DO** use `Temporal.PlainDate.compare()` when comparing two dates in a specific calendar system instead of comparing Year/Month/Day properties manually.
+- **DO** use `toLocaleString()` to format dates for users instead of manual string concatenation.
+- **DO** verify that the target calendar system is supported by the environment using `Intl.supportedValuesOf('calendar')` before creating calendar-specific Temporal objects.
+- **DO** be aware that some calendars (like variants of the Islamic calendar) may rely on visual observation rather than fixed calculations. The `Temporal` API follows the environment's `Intl` implementation, which usually uses calculated approximations. For critical cultural or religious date calculations, verify with domain experts or use specialized libraries.
+- **DO** account for era names when using calendars that use eras (e.g., Japanese, Buddhist), using `toLocaleString()`.
+
+## Fallback Strategy
+
+Temporal has limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 139 (May 2025).
+Unsupported in: Safari.
+
+For production use in browsers that do not support it natively, you must use a polyfill.
+
+The recommended approach is to progressively enhance by checking for native support and dynamically loading a polyfill like `@js-temporal/polyfill` if needed.
+
+```javascript
+/**
+ * Progressive Enhancement Fallback
+ */
+async function getTemporal() {
+  if (typeof Temporal !== 'undefined') {
+    return Temporal;
+  }
+  
+  try {
+    // Load polyfill dynamically from CDN
+    const module = await import('https://esm.sh/@js-temporal/polyfill');
+    globalThis.Temporal = module.Temporal;
+    return module.Temporal;
+  } catch (e) {
+    console.error('Failed to load Temporal polyfill:', e);
+    throw e;
+  }
+}
+```