@illinois-grad/grad-vue 2.3.4 → 2.4.0

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

@@ -3,6 +3,75 @@ export interface GSearchGroup<R> {
     label: string;
     items: R[];
 }
+/**
+ * A combobox-style search that shows a list of results as an auto
+ * complete dropdown.
+ *
+ * The component doesn't perform any real searching. It emits events
+ * that can be used to trigger searches, and then the results are
+ * passed back to the component.
+ *
+ * **Events**:
+ *
+ * - `submit` event is emitted when a search should be performed.
+ * - `select` event is submitted when a user makes a selection
+ *   in the dropdown.
+ *
+ * > [!NOTE]
+ * > The `v-model` value should *not* be used to trigger a search,
+ * > but it can be used to get the current user input.
+ *
+ * **Props**:
+ *
+ * - `results` will be rendered in the dropdown. There are two options:
+ *   - Pass an array of objects that extend `{ id: string | number; title: string; }`.
+ *   - Pass an array of `GSearchGroup<T>` objects, where the `items` property extends the above type.
+ *     In this case the results are grouped.
+ * - `auto` makes search submit on user input. Defaults to `true`.
+ *   if `false`, submission happens on Enter or clicking the search button.
+ * - `loading` shows a loading indicator. Use if the search may take longer.
+ *
+ * **Slot**: `option` customizes how an option is rendered.
+ * It receives the current item as `option`.
+ *
+ * **Slot**: `group` customizes the group label for each group.
+ *
+ * Here is a minimal implementation:
+ *
+ * ```vue
+ * <script setup lang="ts">
+ * interface SearchResult {
+ *     id: string;
+ *     title: string;
+ * }
+ *
+ * const searchData = ref<SearchResult[]>([
+ *     { id: "1", title: "The Quick Fox" },
+ *     { id: "2", title: "The Lazy Dog" },
+ *     { id: "3", title: "The Brown Bear" },
+ * ]);
+ * const searchResults = ref<SearchResult[]>([]);
+ *
+ * function submit(query: string) {
+ *     searchResults.value = searchData.value.filter((result) =>
+ *         result.title.toLowerCase().includes(query.toLowerCase()),
+ *     );
+ * }
+ * function selected(item: SearchResult) {
+ *     console.log("Selected:", item);
+ * }
+ * &lt;/script>
+ * <template>
+ *     <GSearch
+ *         :results="searchResults"
+ *         @submit="submit"
+ *         @select="selected">
+ *     </GSearch>
+ * </template>
+ * ```
+ */
+declare const _default: typeof __VLS_export;
+export default _default;
 declare const __VLS_export: <T extends {
     id: string | number;
     title: string;
@@ -11,18 +80,22 @@ declare const __VLS_export: <T extends {
         results: GSearchGroup<T>[] | T[];
         /**
          * Placeholder
+         * @demo
          */
         placeholder?: string;
         /**
          * Accessible label
+         * @demo
          */
         label?: string;
         /**
          * Automatic search
+         * @demo
          */
         auto?: boolean;
         /**
          * Show search loading indicator
+         * @demo
          */
         loading?: boolean;
     } & {
@@ -53,8 +126,6 @@ declare const __VLS_export: <T extends {
 }>) => import("vue").VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;
 };
-declare const _default: typeof __VLS_export;
-export default _default;
 type __VLS_PrettifyLocal<T> = (T extends any ? {
     [K in keyof T]: T[K];
 } : {

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

@@ -1,71 +1,148 @@
-interface OptionType {
-    label: string;
-    value: string | number;
-}
-interface Props {
-    options: Array<string | OptionType>;
+/**
+ * By default, this component behaves like a normal select element with
+ * custom styling.
+ *
+ * The component can be marked `searchable` to enable search functionality.
+ * This turns it into a text input that filters the options. Filtering is
+ * done with a simple lower-case string search.
+ *
+ * The `options` prop can be an array of strings or objects with `label`
+ * and `value` properties.
+ */
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
+    /**
+     * List of options to choose from
+     */
+    options: Array<string | {
+        label: string;
+        value: string | number;
+    }>;
     /**
      * Accessible label
+     * @demo Select Option
      */
     label: string;
     /**
      * Hide the label visually
+     * @demo
      */
     hiddenLabel?: boolean;
     /**
      * Placeholder
      *
      * Only used if the component is searchable.
+     * @demo
      */
     placeholder?: string;
     /**
      * Disabled
+     * @demo
      */
     disabled?: boolean;
+    /**
+     * Name for form registration
+     */
     name?: string;
     /**
      * Searchable
+     * @demo
      */
     searchable?: boolean;
     /**
      * Show clear button
+     * @demo
      */
     clearButton?: boolean;
     /**
      * Compact
+     * @demo
      */
     compact?: boolean;
+    /**
+     * Error messages array (supports multiple validation errors)
+     */
     errors?: string[];
-}
-type __VLS_Props = Props;
-type __VLS_ModelProps = {
+} & {
     modelValue?: string | number | null;
-};
-type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
-declare var __VLS_1: {
-    option: OptionType;
-    selected: boolean;
-    index: number;
-};
-type __VLS_Slots = {} & {
-    option?: (props: typeof __VLS_1) => any;
-};
-declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     change: (...args: any[]) => void;
     "update:modelValue": (value: string | number | null | undefined) => void;
-}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
-    onChange?: ((...args: any[]) => any) | undefined;
+}, string, import("vue").PublicProps, Readonly<{
+    /**
+     * List of options to choose from
+     */
+    options: Array<string | {
+        label: string;
+        value: string | number;
+    }>;
+    /**
+     * Accessible label
+     * @demo Select Option
+     */
+    label: string;
+    /**
+     * Hide the label visually
+     * @demo
+     */
+    hiddenLabel?: boolean;
+    /**
+     * Placeholder
+     *
+     * Only used if the component is searchable.
+     * @demo
+     */
+    placeholder?: string;
+    /**
+     * Disabled
+     * @demo
+     */
+    disabled?: boolean;
+    /**
+     * Name for form registration
+     */
+    name?: string;
+    /**
+     * Searchable
+     * @demo
+     */
+    searchable?: boolean;
+    /**
+     * Show clear button
+     * @demo
+     */
+    clearButton?: boolean;
+    /**
+     * Compact
+     * @demo
+     */
+    compact?: boolean;
+    /**
+     * Error messages array (supports multiple validation errors)
+     */
+    errors?: string[];
+} & {
+    modelValue?: string | number | null;
+}> & Readonly<{
     "onUpdate:modelValue"?: ((value: string | number | null | undefined) => any) | undefined;
+    onChange?: ((...args: any[]) => any) | undefined;
 }>, {
     name: string;
     errors: string[];
     disabled: boolean;
     searchable: boolean;
     compact: boolean;
-}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
-declare const _default: typeof __VLS_export;
-export default _default;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, {
+    option?: (props: {
+        option: {
+            label: string;
+            value: string | number;
+        };
+        selected: boolean;
+        index: number;
+    }) => any;
+}>;
 type __VLS_WithSlots<T, S> = T & {
     new (): {
         $slots: S;

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

@@ -1,40 +1,89 @@
-interface OptionType {
-    label: string;
-    value: string | number;
-}
-interface Props {
-    options: Array<string | OptionType>;
+/**
+ * This component is just a radio button group with special styling.
+ *
+ * Use the `options` prop to provide a list of choices. Each option can
+ * be a string or an object with `label` and `value` properties.
+ *
+ * In addition to `v-model`, a `change` event is emitted when the
+ * option changes from user interaction.
+ */
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: import("vue").DefineComponent<{
+    /**
+     * List of options to select from
+     */
+    options: Array<string | {
+        label: string;
+        value: string | number;
+    }>;
     /**
      * Accessible label
+     * @demo Select Option
      */
     label: string;
     /**
      * Size
+     * @demo
      */
     size?: "small" | "medium" | "large";
+    /**
+     * Name for form registration
+     */
     name?: string;
     /**
      * Disabled
+     * @demo
      */
     disabled?: boolean;
+    /**
+     * Error messages array (supports multiple validation errors)
+     */
     errors?: string[];
-}
-type __VLS_Props = Props;
-type __VLS_ModelProps = {
+} & {
     modelValue?: string | number;
-};
-type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
-declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     change: (...args: any[]) => void;
     "update:modelValue": (value: string | number) => void;
-}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
-    onChange?: ((...args: any[]) => any) | undefined;
+}, string, import("vue").PublicProps, Readonly<{
+    /**
+     * List of options to select from
+     */
+    options: Array<string | {
+        label: string;
+        value: string | number;
+    }>;
+    /**
+     * Accessible label
+     * @demo Select Option
+     */
+    label: string;
+    /**
+     * Size
+     * @demo
+     */
+    size?: "small" | "medium" | "large";
+    /**
+     * Name for form registration
+     */
+    name?: string;
+    /**
+     * Disabled
+     * @demo
+     */
+    disabled?: boolean;
+    /**
+     * Error messages array (supports multiple validation errors)
+     */
+    errors?: string[];
+} & {
+    modelValue?: string | number;
+}> & Readonly<{
     "onUpdate:modelValue"?: ((value: string | number) => any) | undefined;
+    onChange?: ((...args: any[]) => any) | undefined;
 }>, {
     size: "small" | "medium" | "large";
     name: string;
     errors: string[];
     disabled: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-declare const _default: typeof __VLS_export;
-export default _default;

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

@@ -1,40 +1,91 @@
-interface Props {
+/**
+ * A simple sidebar that's fixed to the left side of the viewport.
+ *
+ * This includes the CSS for the `fixed` position and sizing, so the element
+ * should be fairly high in the DOM tree.
+ *
+ * If neither `top-offset` nor `top-offset-var` are defined, the sidebar will be
+ * offset by `var(--g-toolbar-height)`. If there is no toolbar, just pass
+ * `0` as the `top-offset`.
+ *
+ * The sidebar can be made collapsible by providing the `sidebar` injected
+ * object from `useSidebar`. See the [Hamburger Menu Documentation](#use-sidebar)
+ * for details.
+ */
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
     /**
      * Custom background color
+     * @demo
      */
     backgroundColor?: string;
     /**
      * Custom background image
+     * @demo none
      */
     backgroundImage?: string;
     /**
      * Sidebar theme
+     * @demo
      */
     theme?: "light" | "dark";
+    /**
+     * Offset from the top of the viewport
+     */
     topOffset?: string;
+    /**
+     * Top offset variable to use instead of topOffset
+     */
     topOffsetVar?: string;
     /**
      * Width
      *
      * Width of the sidebar
+     * @demo
      */
     width?: string;
-}
-declare var __VLS_1: {};
-type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_1) => any;
-};
-declare const __VLS_base: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{}>, {
+}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{
+    /**
+     * Custom background color
+     * @demo
+     */
+    backgroundColor?: string;
+    /**
+     * Custom background image
+     * @demo none
+     */
+    backgroundImage?: string;
+    /**
+     * Sidebar theme
+     * @demo
+     */
+    theme?: "light" | "dark";
+    /**
+     * Offset from the top of the viewport
+     */
+    topOffset?: string;
+    /**
+     * Top offset variable to use instead of topOffset
+     */
+    topOffsetVar?: string;
+    /**
+     * Width
+     *
+     * Width of the sidebar
+     * @demo
+     */
+    width?: string;
+}> & Readonly<{}>, {
     theme: "light" | "dark";
     width: string;
     backgroundColor: string;
     backgroundImage: string;
     topOffset: string;
     topOffsetVar: string;
-}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
-declare const _default: typeof __VLS_export;
-export default _default;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, {
+    default?: (props: {}) => any;
+}>;
 type __VLS_WithSlots<T, S> = T & {
     new (): {
         $slots: S;

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

@@ -1,33 +1,144 @@
-type MenuItem = {
-    label: string;
-    href?: string;
-    to?: string;
-};
-interface Props {
+/**
+ * A sidebar menu component for use with `GSidebar`. Displays a title and
+ * a list of links.
+ *
+ * This component also supports showing active links for in-page navigation.
+ *
+ * **Props**:
+ *
+ * - `items` with a list of `MenuItem` objects. The objects should have:
+ *   - `label` for the link text
+ *   - `href` or `to` for the destination. If `to` is used, the links will
+ *     be rendered as `router-link` for vue-router.
+ * - `spy` to enable tracking active links for in-page navigation
+ * - `offset` to adjust the active link tracking position
+ * - `theme` to set the menu theme
+ *
+ * For tracking the active link, the `spy` prop must be set to `true` and
+ * a `v-model` must be provided that has the ID of the target element (without #).
+ *
+ * The composable function `useActiveLinkContent` can be used to track active links.
+ * It takes the following parameters:
+ *
+ * - `Ref<HTMLElement>` Children of this element will be observed
+ * - `number` Offset from the top of the window to consider not visible
+ * - `Ref<string>` Ref to store the active element ID
+ *
+ * The direct children of the element must all have an ID to properly work with
+ * in-page navigation, and the matching menu item's `href` should be set to
+ * `#<id>`.
+ *
+ * Here's a minimal example of a page using `useActiveLinkContent`:
+ *
+ * ```vue
+ * <script setup lang="ts">
+ * import { computed, onMounted, ref, useTemplateRef } from "vue";
+ * import { useActiveLinkContent } from "@illinois-grad/grad-vue";
+ *
+ * const activeId = ref<string>("");
+ * const main = useTemplateRef("main");
+ * // onMounted is for Nuxt compatibility
+ * onMounted(() => {
+ *     useActiveLinkContent(main, 70, activeId);
+ * });
+ * &lt;/script>
+ *
+ * <template>
+ *   <GSidebar>
+ *       <GSidebarMenu
+ *           :items="[
+ *               { label: 'Buttons', href: '#buttons' },
+ *               { label: 'More Buttons', href: '#more-buttons' }
+ *           ]"
+ *           v-model="activeId"
+ *       />
+ *   </GSidebar>
+ *   <main class="main" ref="main">
+ *       <section id="buttons">
+ *           <h2>Buttons</h2>
+ *           <p>Some buttons</p>
+ *       </section>
+ *       <section id="more-buttons">
+ *           <h2>More Buttons</h2>
+ *           <p>Some more buttons</p>
+ *       </section>
+ *   </main>
+ * </template>
+ * ```
+ */
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: import("vue").DefineComponent<{
     /**
      * Title and accessible name
+     * @demo Sidebar Menu
      */
     title?: string;
-    items: MenuItem[];
+    /**
+     * Items for the menu
+     */
+    items: {
+        label: string;
+        href?: string;
+        to?: string;
+    }[];
+    /**
+     * Offset for tracking active position to account for toolbars
+     */
     offset?: number;
+    /**
+     * Track active position for in-page links
+     */
     spy?: boolean;
     /**
      * Sidebar theme
+     * @demo
      */
     theme?: "light" | "dark";
     /**
      * Use compact layout
+     * @demo
      */
     compact?: boolean;
-}
-type __VLS_Props = Props;
-type __VLS_ModelProps = {
+} & {
     modelValue?: string | null;
-};
-type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
-declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:modelValue": (value: string | null) => any;
-}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+}, string, import("vue").PublicProps, Readonly<{
+    /**
+     * Title and accessible name
+     * @demo Sidebar Menu
+     */
+    title?: string;
+    /**
+     * Items for the menu
+     */
+    items: {
+        label: string;
+        href?: string;
+        to?: string;
+    }[];
+    /**
+     * Offset for tracking active position to account for toolbars
+     */
+    offset?: number;
+    /**
+     * Track active position for in-page links
+     */
+    spy?: boolean;
+    /**
+     * Sidebar theme
+     * @demo
+     */
+    theme?: "light" | "dark";
+    /**
+     * Use compact layout
+     * @demo
+     */
+    compact?: boolean;
+} & {
+    modelValue?: string | null;
+}> & Readonly<{
     "onUpdate:modelValue"?: ((value: string | null) => any) | undefined;
 }>, {
     theme: "light" | "dark";
@@ -35,5 +146,3 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {},
     offset: number;
     spy: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
-declare const _default: typeof __VLS_export;
-export default _default;