@illinois-grad/grad-vue 7.1.2 → 7.2.0

package/dist/components/GMain.vue.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The `<main>` landmark for a page, set up as the target for
+ * `GSkipLink` and `useRouteAnnouncer`.
+ *
+ * Use one per page, inside each view rather than around `<RouterView>`,
+ * so sidebars and other complementary content stay outside the landmark.
+ *
+ * ```vue
+ * <template>
+ *     <GSidebar>...</GSidebar>
+ *     <GMain class="profile">
+ *         <h1>Profile</h1>
+ *     </GMain>
+ * </template>
+ * ```
+ *
+ * ## Accessible route changes
+ *
+ * Use the `useRouteAnnouncer` composable once in the root component.
+ * After each navigation to a different page, it moves focus to the `<h1>`
+ * inside `GMain` (or `GMain` itself) and announces the new page title.
+ * Navigations that only change the query or hash are ignored.
+ *
+ * ```ts
+ * // App.vue setup
+ * import { useRouter } from "vue-router";
+ * import { useRouteAnnouncer } from "@illinois-grad/grad-vue";
+ *
+ * useRouteAnnouncer(useRouter());
+ * ```
+ *
+ * ```vue
+ * <GSkipLink />
+ * <GAppHeader>...</GAppHeader>
+ * <RouterView />
+ * ```
+ *
+ * Options can customize what counts as a new page (`isNewPage`), when focus
+ * moves (`focus`), waiting for async page data (`ready`), and the
+ * announcement text (`message`).
+ */
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
+    /**
+     * Id used by `GSkipLink` and `useRouteAnnouncer` to find the landmark
+     */
+    id?: string;
+}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{
+    /**
+     * Id used by `GSkipLink` and `useRouteAnnouncer` to find the landmark
+     */
+    id?: string;
+}> & Readonly<{}>, {
+    id: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, {
+    default?: (props: {}) => any;
+}>;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/GSkipLink.vue.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A "skip to main content" link for keyboard and screen reader users.
+ *
+ * Place it as the first focusable element in the app, before `GAppHeader`.
+ * It stays hidden until it receives keyboard focus. Activating it moves
+ * focus to the element with the `target` id (usually a `GMain`), falling
+ * back to the first `<main>` element.
+ *
+ * Focus is moved with JavaScript, so it works with client-side routers
+ * and with targets that are rendered after the link.
+ *
+ * ```vue
+ * <GSkipLink />
+ * <GAppHeader>...</GAppHeader>
+ * <RouterView />
+ * ```
+ */
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
+    /**
+     * Id of the element to move focus to
+     */
+    target?: string;
+    /**
+     * Link text
+     * @demo
+     */
+    label?: string;
+}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{
+    /**
+     * Id of the element to move focus to
+     */
+    target?: string;
+    /**
+     * Link text
+     * @demo
+     */
+    label?: string;
+}> & Readonly<{}>, {
+    label: string;
+    target: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, {
+    default?: (props: {}) => any;
+}>;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/compose/useRouteAnnouncer.d.ts

@@ -0,0 +1,87 @@
+import { type Ref } from "vue";
+/**
+ * The subset of a vue-router route location used by `useRouteAnnouncer`.
+ */
+export interface RouteAnnouncerLocation {
+    path: string;
+    hash?: string;
+    matched?: readonly unknown[];
+}
+/**
+ * The subset of a vue-router `Router` used by `useRouteAnnouncer`.
+ * grad-vue doesn't depend on vue-router, so any compatible object works.
+ */
+export interface RouteAnnouncerRouter<L extends RouteAnnouncerLocation = RouteAnnouncerLocation> {
+    afterEach(guard: (to: L, from: L, failure?: unknown) => unknown): () => void;
+}
+export interface UseRouteAnnouncerOptions<L extends RouteAnnouncerLocation = RouteAnnouncerLocation> {
+    /**
+     * Id of the main landmark (see `GMain`). Falls back to the first `<main>`.
+     * @default "main-content"
+     */
+    mainId?: string;
+    /**
+     * Whether a navigation leads to a different page. Navigations that stay
+     * on the same page (query or hash changes like filters and tabs) are
+     * ignored. By default, a different path means a different page.
+     */
+    isNewPage?: (to: L, from: L) => boolean;
+    /**
+     * Whether to move focus to the new page's `<h1>` (or main landmark).
+     * @default true
+     */
+    focus?: boolean | ((to: L, from: L) => boolean);
+    /**
+     * Waits before moving focus and announcing, for pages that load their
+     * title or heading asynchronously. Resolve when the page is ready; use a
+     * timeout so a failed load doesn't block the announcement.
+     */
+    ready?: (to: L, from: L) => unknown;
+    /**
+     * Builds the announcement. Defaults to "Navigated to {document.title}".
+     * Return an empty string to skip the announcement.
+     */
+    message?: (to: L, title: string) => string;
+}
+export interface UseRouteAnnouncerReturn {
+    /**
+     * The most recent announcement.
+     */
+    message: Readonly<Ref<string>>;
+    /**
+     * Announce a message in the polite live region.
+     */
+    announce: (text: string) => void;
+    /**
+     * Remove the router hook and live region.
+     */
+    stop: () => void;
+}
+/**
+ * Focuses the main landmark identified by `mainId` (or the first `<main>`).
+ * When `preferHeading` is set, focuses its first `<h1>` instead if possible.
+ *
+ * @returns whether focus was moved
+ */
+export declare function focusMainTarget(mainId?: string, preferHeading?: boolean): boolean;
+/**
+ * Makes client-side route changes accessible:
+ *
+ * - Moves focus to the new page's `<h1>` inside the main landmark, or the
+ *   landmark itself, so keyboard and screen reader users start at the new
+ *   content instead of the link they activated.
+ * - Announces the new page title in a polite live region.
+ *
+ * The initial page load, failed navigations, and navigations within the same
+ * page are ignored. Focus isn't moved when the route has a hash or when the
+ * new page already moved focus into its main content (for example, with
+ * autofocus).
+ *
+ * Call once, typically in the root `App.vue` setup:
+ *
+ * ```ts
+ * const router = useRouter();
+ * useRouteAnnouncer(router);
+ * ```
+ */
+export declare function useRouteAnnouncer<L extends RouteAnnouncerLocation = RouteAnnouncerLocation>(router: RouteAnnouncerRouter<L>, options?: UseRouteAnnouncerOptions<L>): UseRouteAnnouncerReturn;