@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/user-experience/interest-triggered-tooltips.md

@@ -0,0 +1,132 @@
+# Show a tooltip when hovering
+
+Users expect to see additional related information without completely changing their context. Showing a tooltip when a user is interested in more information can be useful to provide definitions for a term, clarifying the action an icon-only button will take, or provide additional form field guidance.
+
+## Creating the tooltip
+
+You can create a popover with the required behavior by adding the `popover="hint"` attribute to a `<div>` or other semantically appropriate element. When the user opens the tooltip, this hides other `popover="hint"` tooltips, but doesn't hide `auto` or `manual` tooltips. It also handles dismissing nested tooltips.
+
+It also provides light dismiss behavior, so when a user clicks or otherwise focuses outside of the popover, the popover is dismissed.
+
+The tooltip element must have an `id` attribute with a unique value:
+
+```html
+<!-- MANDATORY: The tooltip container `<div>` must have a `popover` attribute.
+     the value of `"hint"` ensures it can be "light dismissed". -->
+<div popover="hint" id="tooltip">Tooltip content</div>
+```
+
+A user expresses interest in the additional information by hovering or focusing on an `<a>` or `<button>` element. The element must have an `interestfor` attribute that matches the `id` attribute of the tooltip.
+
+```html
+<!-- The `interestfor` attribute can be applied to a `<button>` element: -->
+<button interestfor="tooltip">Tooltip trigger</button>
+
+<!-- The `interestfor` attribute can also be applied to an `<a>` element: -->
+<a interestfor="tooltip" href="">Tooltip trigger</a>
+```
+
+The trigger must have a visual indicator to indicate that there is additional information available by interacting with the trigger.
+
+### Accessibility built in to `interestfor`
+
+`interestfor` handles the assistive-technology wiring for you, so you generally do not need to add ARIA attributes manually:
+
+- A target with `popover="hint"` gains an implicit minimum role of `tooltip`. **DO NOT** set `role="tooltip"` yourself.
+- The browser implicitly associates the source element with the target via `aria-describedby` when the target is plaintext, or via `aria-details` when the target contains interactive content. **DO NOT** add `aria-describedby` or `aria-details` to the trigger.
+- Because the association switches to `aria-details` when needed, the target IS allowed to contain interactive content (e.g. a link inside an "interest card").
+
+### Accessibility Constraints (WCAG 1.4.13)
+
+Even with `interestfor` handling the semantics above, your implementation MUST still satisfy WCAG 1.4.13 (Content on Hover or Focus):
+- **Dismissible:** Users must be able to dismiss the tooltip without moving pointer hover or keyboard focus (e.g., by pressing the `Escape` key). The native `popover` attribute manages this binding automatically.
+- **Hoverable:** The pointer must be able to move over the tooltip content itself without the tooltip disappearing. This allows users with magnification tools to read the tooltip text safely.
+- **Persistent:** The tooltip must remain visible until the hover or focus trigger is removed, the user explicitly dismisses it, or its content is no longer valid.
+
+### Positioning the tooltip
+
+The tooltip can be positioned using anchor positioning. When the tooltip is opened using `interestfor`, the trigger becomes an implicit anchor for the tooltip, meaning you don't have to add `anchor-name` or `position-anchor` CSS properties. However, to support browsers without anchor positioning you must use the anchor positioning polyfill, which has several limitations for popovers. **MANDATORY:** Implicit anchors are NOT supported by the polyfill, so YOU MUST explicitly set an `anchor-name` on the trigger and `position-anchor` on the popover.
+
+
+```css
+/* MANDATORY: use explicit anchor names for compatibility with the polyfill */
+button[interestfor="tooltip-dom"] {
+  anchor-name: --tooltip-dom;
+}
+#tooltip-dom {
+  position-anchor: --tooltip-dom;
+}
+```
+
+Also, the polyfill does not support `position-area` on popovers, so **MANDATORY:** DO position using `anchor()` functions, and **YOU MUST** include a `position-try` fallback (e.g. `flip-block` or `flip-inline`).
+
+```css
+[popover]{
+  /* MANDATORY: use anchor functions and a position-try fallback for the polyfill */
+  top: anchor(bottom);
+  left: anchor(center);
+  position-try: flip-block;
+  margin: unset;
+}
+```
+
+
+### Fallback strategies
+
+Interest invokers has limited availability.
+Supported by: Chrome 142 (Oct 2025) and Edge 142 (Oct 2025).
+Unsupported in: Firefox and Safari.
+
+Interest invokers must be conditionally polyfilled using the `interestfor` polyfill package from NPM. Do prefer bundling the polyfill over using the CDN.
+
+```html
+<script type="module">
+  if(!HTMLButtonElement.prototype.hasOwnProperty("interestForElement")){
+    // CDN link only used for example, prefer bundling.
+    await import("https://unpkg.com/interestfor@latest");
+  }
+</script>
+```
+
+Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27.
+Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).
+popover="hint" has limited availability.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), and Firefox 149 (Mar 2026).
+Unsupported in: Safari.
+
+Popover and popover hint must conditionally be polyfilled with the `@oddbird/popover-polyfill` polyfill. The hint behavior will not be polyfilled in browsers that support `popover` but not `popover="hint"`. For those browsers, a tooltip opened via focus may stay open when a second tooltip opened via hover.
+
+```html
+<script type="module">
+  if(!HTMLElement.prototype.hasOwnProperty("popover")){
+    await import("https://unpkg.com/@oddbird/popover-polyfill@latest");
+  }
+</script>
+```
+
+Anchor positioning is not natively supported by any major browser yet.
+
+**MANDATORY:** To support browsers without anchor positioning, you MUST use the `@oddbird/css-anchor-positioning` polyfill. It does not support implicit anchors, so you MUST add anchor names to the trigger. Additionally, `position-area` is not supported on popovers by the polyfill, so you MUST use `anchor()` on the desired insets. 
+
+```html
+<!-- MANDATORY: Conditionally install the anchor positioning polyfill -->
+<script type="module">
+  if (!("anchorName" in document.documentElement.style)) {
+    await import("https://unpkg.com/@oddbird/css-anchor-positioning");
+  }
+</script>
+```
+
+```css
+button[interestfor="tooltip-attrs"] {
+  /* MANDATORY: Each trigger and popover pair must have a unique anchor name, referenced by `anchor-name` on the trigger and `position-anchor` on the popover. */
+  anchor-name: --tooltip-attrs;
+}
+#tooltip-attrs {
+  position-anchor: --tooltip-attrs;
+  /* If using the anchor positioning polyfill with a popover, DO use `anchor()` functions, and not `position-area. */
+  top: anchor(bottom);
+  left: anchor(right);
+  margin: unset;
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/light-dismiss-a-dialog.md

@@ -0,0 +1,84 @@
+Modern modal dialogs often support "light-dismiss," allowing users to close a dialog by clicking or tapping the backdrop (the area outside the dialog). The `closedby` attribute provides a declarative way to enable this behavior without custom JavaScript.
+
+## Implementation
+
+To enable light-dismiss:
+
+1. Add `closedby="any"` to the `<dialog>` element.
+2. Open the dialog using `dialog.showModal()`.
+
+### Attribute Values
+
+- `any`: Enables light-dismiss (clicking the backdrop), "close requests" (the `Esc` key), and developer mechanisms (e.g., `dialog.close()`).
+- `closerequest`: Enables "close requests" and developer mechanisms only. This is the default for modal dialogs.
+- `none`: Only developer mechanisms can close the dialog.
+
+### Styling the Backdrop
+When a dialog is opened as a modal using `showModal()`, the browser generates a `::backdrop` pseudo-element. This backdrop covers the entire viewport and sits directly behind the dialog.
+
+```css
+/* Style the backdrop to indicate the dialog is modal */
+dialog::backdrop {
+  background-color: rgba(0, 0, 0, 0.5);
+  backdrop-filter: blur(2px); /* Optional: add blur for modern browsers */
+}
+```
+
+## Example
+
+```html
+<!-- MANDATORY: Use closedby="any" to enable light-dismiss behavior -->
+<dialog id="myDialog" closedby="any" aria-labelledby="dialogTitle">
+  <form method="dialog">
+    <h2 id="dialogTitle">Feedback</h2>
+    <p>Click outside this box or press Esc to dismiss.</p>
+    <button type="submit">Close</button>
+  </form>
+</dialog>
+
+<button onclick="document.getElementById('myDialog').showModal()">Open Dialog</button>
+```
+
+## Constraints & Accessibility
+
+- **MANDATORY**: Use `closedby="any"` to enable light-dismiss declaratively.
+- **MANDATORY**: Always open modal dialogs with `showModal()`. This ensures the dialog is in the top layer, focus is trapped, and the `Esc` key is handled.
+- **DO**: Use `aria-labelledby` or `aria-label` to provide an accessible name for the dialog.
+- **DO NOT**: Use `closedby` for non-modal dialogs (opened with `show()`), as they do not have a backdrop and won't trigger light-dismiss.
+- **DO NOT**: Use the `click` event for critical logic that should happen *before* closing; instead, listen for the `close` or `cancel` events.
+
+## Fallback strategies
+
+<dialog closedby> has limited availability.
+Supported by: Chrome 134 (Mar 2025), Edge 134 (Mar 2025), and Firefox 141 (Jul 2025).
+Unsupported in: Safari.
+
+**MANDATORY**: For browsers that do not yet support `closedby`, you **must** implement a fallback for light-dismiss by checking if a click occurred outside the dialog content's boundaries using the following script:
+
+```javascript
+const dialog = document.querySelector('dialog');
+
+// Fallback for browsers without closedby support
+if (!('closedBy' in HTMLDialogElement.prototype)) {
+  dialog.addEventListener('click', (event) => {
+    // 1. When clicking the backdrop, the event target is the dialog element itself.
+    // Ignore clicks where the target is a child element inside the dialog.
+    if (event.target !== dialog) return;
+
+    // 2. Check if the click coordinates fall within the dialog's content box.
+    // This distinguishes between a click on the backdrop vs a click on the dialog's background/padding.
+    const rect = dialog.getBoundingClientRect();
+    const isDialogContent = (
+      rect.top <= event.clientY &&
+      event.clientY <= rect.top + rect.height &&
+      rect.left <= event.clientX &&
+      event.clientX <= rect.left + rect.width
+    );
+
+    if (isDialogContent) return;
+
+    // 3. Since the click was outside the content area (on the backdrop), manually close the dialog.
+    dialog.close();
+  });
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/manage-recurring-intervals.md

@@ -0,0 +1,73 @@
+# Managing Recurring Intervals with Temporal
+
+Calculating recurring intervals, such as subscription billing cycles or payroll periods, has historically been error-prone with the legacy `Date` object. Adding a month to a date like January 31st is ambiguous (should it be February 28th/29th or March 3rd?).
+
+The `Temporal` API provides a clean solution with `Temporal.PlainDate` and its `.add()` method, which handles month-end transitions predictably using configurable overflow strategies.
+
+## How to Implement
+
+1. **MANDATORY:** **Parse the starting date**: Use `Temporal.PlainDate.from()` to create a date object.
+2. **MANDATORY:** **Add the duration**: Use the `.add()` method with a duration object (e.g., `{ months: 1 }`).
+3. **OPTIONAL:** **Specify overflow behavior**: Use the `overflow` option to control how invalid dates (like Feb 31) are handled.
+    - `'constrain'` (default): Clamps to the last valid day of the month.
+    - `'reject'`: Throws a `RangeError`.
+
+### Example: Subscription Billing Cycle
+
+```javascript
+// 1. Parse the start date (e.g., billing starts on Jan 31st)
+const startDate = Temporal.PlainDate.from('2024-01-31');
+
+// 2. Add 1 month with default 'constrain' overflow
+// Jan 31 + 1 month -> Feb 29 (2024 is a leap year)
+const nextBillingDate = startDate.add({ months: 1 });
+console.log(`Next billing: ${nextBillingDate.toString()}`); // 2024-02-29
+
+// 3. Add 1 month to Feb 29
+// Feb 29 + 1 month -> Mar 29
+// Note: Day is preserved if valid, otherwise constrained.
+const thirdBillingDate = nextBillingDate.add({ months: 1 });
+console.log(`Third billing: ${thirdBillingDate.toString()}`); // 2024-03-29
+
+// Example with 'reject' strategy
+try {
+  // Jan 31 + 1 month with 'reject' throws because Feb 31 is invalid
+  const invalidDate = startDate.add({ months: 1 }, { overflow: 'reject' });
+} catch (e) {
+  console.log("Caught expected error:", e.name); // RangeError
+}
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `Temporal.PlainDate` for calculations that do not depend on specific times or time zones (like calendar dates or billing cycles).
+- **DO** understand the default `constrain` behavior. It is usually what users expect for billing (e.g., Jan 31 -> Feb 28/29 -> Mar 28/29).
+- **DO NOT** modify instances directly; `Temporal` objects are **immutable**. Operations return a new instance.
+- **DO** use `overflow: 'reject'` if you need to enforce that the resulting date must exist in the calendar and handle failures explicitly.
+
+### Fallback strategies
+
+Temporal has limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 139 (May 2025).
+Unsupported in: Safari.
+
+For browsers that do not yet support the native `Temporal` API, use feature detection and a polyfill. The standard reference polyfill is `@js-temporal/polyfill`.
+
+```javascript
+// Check if Temporal is supported natively
+(async () => {
+  if (typeof Temporal === 'undefined') {
+    // Load the polyfill conditionally
+    const module = await import("https://esm.sh/@js-temporal/polyfill");
+    globalThis.Temporal = module.Temporal;
+    // Extend Date.prototype if needed
+    Date.prototype.toTemporalInstant = module.toTemporalInstant;
+    initializeApp();
+  }
+})();
+
+function initializeApp() {
+  const date = Temporal.PlainDate.from('2024-01-31');
+  console.log(date.add({ months: 1 }).toString());
+}
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/model-partial-time-concepts.md

@@ -0,0 +1,96 @@
+# Modeling Partial Time Concepts with Temporal
+
+Modeling date concepts that lack a full calendar date—such as credit card expirations, annual renewals, or daily alarms—has historically been error-prone with the legacy `Date` object. Developers often resort to using arbitrary days (like the 1st of the month) or parsing strings, leading to "day leakage" or incorrect calculations due to leap years and varying month lengths.
+
+The `Temporal` API provides dedicated types for these partial concepts: `Temporal.PlainYearMonth`, `Temporal.PlainMonthDay`, and `Temporal.PlainTime`. These types ensure precision and avoid leaking irrelevant date components.
+
+## Implementation Examples
+
+### Monthly Expirations (Credit Cards, Billing Cycles)
+Use `Temporal.PlainYearMonth` to represent a year and a month.
+
+```javascript
+// Create a PlainYearMonth from values
+// Use explicit calendar to avoid mismatch issues in polyfill environments
+const expiry = Temporal.PlainYearMonth.from({ year: 2027, month: 12, calendar: 'iso8601' });
+
+// Get the current year/month
+const currentMonth = Temporal.Now.plainDateISO().toPlainYearMonth();
+
+// Calculate duration until expiry
+// largestUnit ensures the difference is expressed in years if applicable
+const duration = currentMonth.until(expiry, { largestUnit: 'years' });
+
+if (duration.sign < 0) {
+  console.log("Expired");
+} else if (duration.sign === 0) {
+  console.log("Expires this month");
+} else {
+  console.log(`Expires in ${duration.years} years and ${duration.months} months`);
+}
+```
+
+### Annual Recurring Dates (Birthdays, Renewals)
+Use `Temporal.PlainMonthDay` to represent a month and a day without a year.
+
+```javascript
+// Create a PlainMonthDay for an annual event
+// Include explicit calendar for polyfill safety
+const birthday = Temporal.PlainMonthDay.from({ month: 10, day: 31, calendar: 'iso8601' });
+
+// Check if it matches today's date components
+const today = Temporal.Now.plainDateISO();
+const isBirthdayToday = birthday.equals(today.toPlainMonthDay());
+
+// To perform arithmetic (like days until next occurrence), convert to a full PlainDate
+// by providing a specific year.
+const birthdayThisYear = birthday.toPlainDate({ year: today.year });
+```
+
+### Wall-Clock Time (Alarms, Store Hours)
+Use `Temporal.PlainTime` to represent a time of day without a date.
+
+```javascript
+// Create a PlainTime from a string
+const alarmTime = Temporal.PlainTime.from("08:00:00");
+
+// Add a duration to a PlainTime
+const snoozedTime = alarmTime.add({ minutes: 10 });
+
+console.log(`Original alarm: ${alarmTime.toString()}`);
+console.log(`Snoozed alarm: ${snoozedTime.toString()}`);
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `Temporal.PlainYearMonth` for values that only specify a month and year (like credit card expiry) to avoid leaking arbitrary day values.
+- **DO** use `Temporal.PlainMonthDay` for annual events that ignore the year (like birthdays or anniversaries).
+- **DO** use `Temporal.PlainTime` for daily schedules or alarms that are independent of the date.
+- **DO NOT** try to perform arithmetic directly on `PlainMonthDay`. Convert it to a `PlainDate` first by providing a year, as the length of months varies by year.
+- **DO** use explicit calendar properties (like `calendar: 'iso8601'`) when creating instances from objects to ensure safety across polyfill implementations.
+
+## Fallback Strategy
+
+### Fallbacks & browser support for Temporal
+
+Temporal has limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 139 (May 2025).
+Unsupported in: Safari.
+
+For browsers that do not yet support the native `Temporal` API, use feature detection and a polyfill. The standard reference polyfill is `@js-temporal/polyfill`.
+
+Note that the polyfill does not automatically assign the `Temporal` object to the global scope to avoid conflicts. You must manually assign it if your code relies on the global `Temporal` object.
+
+```javascript
+// Check if Temporal is supported natively
+(async () => {
+  if (typeof Temporal === 'undefined') {
+    // Load the polyfill conditionally
+    const module = await import("https://esm.sh/@js-temporal/polyfill");
+    globalThis.Temporal = module.Temporal;
+    // Extend Date.prototype if needed
+    Date.prototype.toTemporalInstant = module.toTemporalInstant;
+    initializeApp();
+  }
+})();
+```

package/.agents/skills/modern-web-guidance/guides/user-experience/move-dom-element-without-losing-state.md

@@ -0,0 +1,57 @@
+When reparenting DOM elements using traditional methods like `appendChild()` or `insertBefore()`, the browser implicitly removes the element from the DOM and then inserts it into its new location. This "remove and insert" operation resets many internal states, causing `<iframe>` elements to reload, CSS animations to restart, and input fields to lose focus.
+
+To move an element while preserving its state, use the `moveBefore()` API. This method performs an atomic move, completely bypassing the removal and insertion steps.
+
+### Moving an element with state
+
+Use `moveBefore()` exactly as you would use `insertBefore()`. It requires two arguments: the node to move, and a reference node to insert before (or `null` to append to the end of the new parent).
+
+```javascript
+const newParent = document.getElementById('new-parent');
+const elementWithState = document.getElementById('iframe-or-focused-input');
+
+// MANDATORY: Use moveBefore to preserve state. 
+// Passing null as the second argument appends the element to the end of newParent.
+newParent.moveBefore(elementWithState, null);
+```
+
+### Moving custom elements (Web Components)
+
+If you are moving custom elements using `moveBefore()`, their `connectedCallback` and `disconnectedCallback` lifecycle methods will **not** be fired.
+
+If your custom element needs to perform specific logic when moved, implement the `connectedMoveCallback()` method inside the custom element definition.
+
+```javascript
+class MyCustomElement extends HTMLElement {
+  connectedCallback() {
+    // Runs on initial insertion.
+  }
+  
+  connectedMoveCallback() {
+    // Runs when the element is moved via moveBefore().
+    // Use this to update state that depends on the new DOM location.
+  }
+}
+```
+
+### Fallback strategies
+
+moveBefore() has limited availability.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), and Firefox 144 (Oct 2025).
+Unsupported in: Safari.
+
+Since `moveBefore()` is a progressive enhancement, you MUST use feature detection before calling it, falling back to traditional `insertBefore()` or `appendChild()` operations for older browsers. 
+
+```javascript
+const targetParent = document.getElementById('target-container');
+const nodeToMove = document.getElementById('moving-element');
+
+// Check if moveBefore is supported on the Element prototype
+if ('moveBefore' in Element.prototype) {
+  targetParent.moveBefore(nodeToMove, null);
+} else {
+  // Fallback: traditional move. 
+  // Note: This WILL reset <iframe>, animation, and focus state in unsupported browsers.
+  targetParent.insertBefore(nodeToMove, null);
+}
+```