allow targeting specific elements when calling focus()

docs/src/pages/components/calendar-date.astro

@@ -166,14 +166,22 @@ import Link from "../../components/Link.astro";
   <Table>
     <tr slot="head">
       <th>Name</th>
+      <th>Parameters</th>
       <th>Description</th>
     </tr>
 
     <tr>
-      <td><code>focus</code></td>
+      <td>
+        <code>
+          focus(options?: FocusOptions & {"{"} target: "previous" | "next" | "day"
+          {"}"}) => void
+        </code>
+      </td>
+      <td><code>options</code> - controls what gets focused, and how</td>
       <td>
         Focuses the <code>&lt;calendar-month&gt;</code> containing the currently
-        focused date
+        focused date. <code>option.target</code> controls which part of the component
+        gets focused
       </td>
     </tr>
   </Table>

docs/src/pages/components/calendar-multi.astro

@@ -166,14 +166,22 @@ import Link from "../../components/Link.astro";
   <Table>
     <tr slot="head">
       <th>Name</th>
+      <th>Parameters</th>
       <th>Description</th>
     </tr>
 
     <tr>
-      <td><code>focus</code></td>
+      <td>
+        <code>
+          focus(options?: FocusOptions & {"{"} target: "previous" | "next" | "day"
+          {"}"}) => void
+        </code>
+      </td>
+      <td><code>options</code> - controls what gets focused, and how</td>
       <td>
         Focuses the <code>&lt;calendar-month&gt;</code> containing the currently
-        focused date
+        focused date. <code>option.target</code> controls which part of the component
+        gets focused
       </td>
     </tr>
   </Table>

docs/src/pages/components/calendar-range.astro

@@ -190,14 +190,22 @@ import Link from "../../components/Link.astro";
   <Table>
     <tr slot="head">
       <th>Name</th>
+      <th>Parameters</th>
       <th>Description</th>
     </tr>
 
     <tr>
-      <td><code>focus</code></td>
+      <td>
+        <code>
+          focus(options?: FocusOptions & {"{"} target: "previous" | "next" | "day"
+          {"}"}) => void
+        </code>
+      </td>
+      <td><code>options</code> - controls what gets focused, and how</td>
       <td>
         Focuses the <code>&lt;calendar-month&gt;</code> containing the currently
-        focused date
+        focused date. <code>option.target</code> controls which part of the component
+        gets focused
       </td>
     </tr>
   </Table>

index.html

@@ -89,7 +89,7 @@ <h2>date</h2>
 
     <h2>multi</h2>
     <calendar-multi
-      id="date"
+      id="multi"
       months="2"
       show-outside-days
       value="2024-05-07 2024-05-09"

src/calendar-base/useCalendarBase.ts

@@ -44,6 +44,10 @@ type UsePaginationOptions = {
   goto: (date: PlainDate) => void;
 };
 
+export interface CalendarFocusOptions extends FocusOptions {
+  target?: "day" | "next" | "previous";
+}
+
 function usePagination({
   pageBy,
   focusedDate,
@@ -133,10 +137,17 @@ export function useCalendarBase({
   });
 
   const host = useHost();
-  function focus() {
-    host.current
-      .querySelectorAll<HTMLElement>("calendar-month")
-      .forEach((m) => m.focus());
+  function focus(options?: CalendarFocusOptions) {
+    const target = options?.target ?? "day";
+    if (target === "day") {
+      host.current
+        .querySelectorAll<HTMLElement>("calendar-month")
+        .forEach((m) => m.focus(options));
+    } else {
+      host.current
+        .shadowRoot!.querySelector<HTMLButtonElement>(`[part~='${target}']`)!
+        .focus(options);
+    }
   }
 
   return {

src/calendar-date/calendar-date.test.tsx

@@ -802,4 +802,26 @@ describe("CalendarDate", () => {
       expect(firstJan).to.have.attribute("aria-pressed", "true");
     });
   });
+
+  describe("focus()", () => {
+    it("allows targeting different elements", async () => {
+      const calendar = await mount(<Fixture value="2020-01-01" />);
+      const day = getDayButton(getMonth(calendar), "1 January");
+
+      calendar.focus({ target: "previous" });
+
+      expect(getActiveElement(calendar.shadowRoot!)).to.eq(
+        getPrevPageButton(calendar)
+      );
+
+      calendar.focus();
+      expect(getActiveElement()).to.eq(day);
+
+      calendar.focus({ target: "next" });
+      expect(getActiveElement()).to.eq(getNextPageButton(calendar));
+
+      calendar.focus({ target: "day" });
+      expect(getActiveElement()).to.eq(day);
+    });
+  });
 });

src/calendar-date/calendar-date.tsx

@@ -2,14 +2,18 @@ import { c, type Host } from "atomico";
 import type { PlainDate } from "../utils/temporal.js";
 import { useDateProp } from "../utils/hooks.js";
 import { CalendarBase, styles, props } from "../calendar-base/calendar-base.js";
-import { useCalendarBase } from "../calendar-base/useCalendarBase.js";
+import {
+  useCalendarBase,
+  type CalendarFocusOptions,
+} from "../calendar-base/useCalendarBase.js";
 
 export const CalendarDate = c(
   (
     props
   ): Host<{
     onChange: Event;
     onFocusDay: CustomEvent<Date>;
+    focus: (options?: CalendarFocusOptions) => void;
   }> => {
     const [value, setValue] = useDateProp("value");
     const [focusedDate = value, setFocusedDate] = useDateProp("focusedDate");

src/calendar-multi/calendar-multi.tsx

@@ -2,14 +2,18 @@ import { c, type Host } from "atomico";
 import { PlainDate } from "../utils/temporal.js";
 import { useDateMultiProp, useDateProp } from "../utils/hooks.js";
 import { CalendarBase, styles, props } from "../calendar-base/calendar-base.js";
-import { useCalendarBase } from "../calendar-base/useCalendarBase.js";
+import {
+  useCalendarBase,
+  type CalendarFocusOptions,
+} from "../calendar-base/useCalendarBase.js";
 
 export const CalendarMulti = c(
   (
     props
   ): Host<{
     onChange: Event;
     onFocusDay: CustomEvent<Date>;
+    focus: (options?: CalendarFocusOptions) => void;
   }> => {
     const [value, setValue] = useDateMultiProp("value");
     const [focusedDate = value[0], setFocusedDate] = useDateProp("focusedDate");

src/calendar-range/calendar-range.tsx

@@ -2,7 +2,10 @@ import { c, useState, type Host, useEvent, useEffect } from "atomico";
 import { PlainDate } from "../utils/temporal.js";
 import { useDateProp, useDateRangeProp } from "../utils/hooks.js";
 import { CalendarBase, styles, props } from "../calendar-base/calendar-base.js";
-import { useCalendarBase } from "../calendar-base/useCalendarBase.js";
+import {
+  useCalendarBase,
+  type CalendarFocusOptions,
+} from "../calendar-base/useCalendarBase.js";
 import { toDate } from "../utils/date.js";
 
 const sort = (a: PlainDate, b: PlainDate): [PlainDate, PlainDate] =>
@@ -16,6 +19,7 @@ export const CalendarRange = c(
     onRangeStart: CustomEvent<Date>;
     onRangeEnd: CustomEvent<Date>;
     onFocusDay: CustomEvent<Date>;
+    focus: (options?: CalendarFocusOptions) => void;
   }> => {
     const [value, setValue] = useDateRangeProp("value");
     const [focusedDate = value[0], setFocusedDate] = useDateProp("focusedDate");

src/utils/test.ts

@@ -1,8 +1,4 @@
-import {
-  sendKeys,
-  sendMouse,
-  type SendKeysPayload,
-} from "@web/test-runner-commands";
+import { sendKeys, sendMouse } from "@web/test-runner-commands";
 import { fixture } from "atomico/test-dom";
 import type { VNodeAny } from "atomico/types/vnode.js";
 import type { CalendarDate } from "../calendar-date/calendar-date.js";