@illinois-grad/grad-vue 2.5.2 → 2.5.4

package/custom-elements.json

@@ -1140,6 +1140,119 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "dist/web-components.js",
+      "declarations": [
+        {
+          "kind": "custom-element",
+          "name": "GMultiSelectElement",
+          "tagName": "g-multi-select",
+          "members": [
+            {
+              "kind": "field",
+              "name": "options",
+              "type": {
+                "text": "Array<string | SelectOption>"
+              },
+              "optional": false,
+              "description": "List of options to choose from"
+            },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "optional": false,
+              "description": "Accessible label"
+            },
+            {
+              "kind": "field",
+              "name": "hiddenLabel",
+              "type": {
+                "text": "boolean"
+              },
+              "optional": true,
+              "description": "Hide the label visually",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "placeholder",
+              "type": {
+                "text": "string"
+              },
+              "optional": true,
+              "description": "Placeholder text shown when no values are selected"
+            },
+            {
+              "kind": "field",
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "optional": true,
+              "description": "Disabled",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "optional": true,
+              "description": "Name for form registration"
+            },
+            {
+              "kind": "field",
+              "name": "errors",
+              "type": {
+                "text": "string[]"
+              },
+              "optional": true,
+              "description": "Error messages array (supports multiple validation errors)",
+              "default": "() => []"
+            },
+            {
+              "kind": "field",
+              "name": "instructions",
+              "type": {
+                "text": "string"
+              },
+              "optional": true,
+              "description": "Instructions shown below the label"
+            },
+            {
+              "kind": "field",
+              "name": "formKey",
+              "type": {
+                "text": "string"
+              },
+              "optional": true,
+              "description": "Form channel key for custom elements mode"
+            },
+            {
+              "kind": "field",
+              "name": "modelValue",
+              "type": {
+                "text": "Array<string | number>"
+              },
+              "optional": true
+            }
+          ],
+          "events": [
+            {
+              "name": "change",
+              "type": {
+                "text": "CustomEvent"
+              }
+            }
+          ]
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "dist/web-components.js",
@@ -1375,7 +1488,7 @@
               "kind": "field",
               "name": "options",
               "type": {
-                "text": "Array<string | OptionType>"
+                "text": "Array<string | SelectOption>"
               },
               "optional": false,
               "description": "List of options to choose from"
@@ -1424,8 +1537,7 @@
                 "text": "string"
               },
               "optional": true,
-              "description": "Name for form registration",
-              "default": "undefined"
+              "description": "Name for form registration"
             },
             {
               "kind": "field",
@@ -1473,8 +1585,7 @@
                 "text": "string"
               },
               "optional": true,
-              "description": "Form channel key for custom elements mode",
-              "default": "undefined"
+              "description": "Form channel key for custom elements mode"
             },
             {
               "kind": "field",
@@ -2665,7 +2776,7 @@
                 "text": "\"ul\" | \"ol\""
               },
               "optional": true,
-              "description": "List element type — use `ol` for numbered hierarchies like book chapters",
+              "description": "List element type - use `ol` for numbered hierarchies like book chapters",
               "default": "\"ul\""
             },
             {

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

@@ -0,0 +1,125 @@
+import { type SelectOption } from "../compose/useSelectDropdown.ts";
+/**
+ * A multi-select combobox that allows selecting multiple values with
+ * optional search/filter support.
+ *
+ * Selected values are displayed as removable chips inside the control.
+ * The dropdown listbox shows all (or filtered) options with a checkmark
+ * next to each selected option.
+ *
+ * The `options` prop accepts an array of strings or `{ label, value }`
+ * objects. The `v-model` binds to an array of `string | number` values.
+ *
+ * In standard Vue usage, this registers with the nearest parent `GForm` via
+ * injection. In custom-elements mode, use matching `form-key` values to pair
+ * with a `GForm`.
+ *
+ * Keyboard navigation:
+ * - `Down Arrow` / `Up Arrow`: move through options (opens menu if closed)
+ * - `Enter`: toggle the focused option
+ * - `Space`: toggle the focused option when the search field is empty
+ * - `Escape`: close the dropdown
+ * - `Home` / `End`: jump to first / last option
+ * - `Backspace`: remove the last chip when the search field is empty
+ */
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: import("vue").DefineComponent<{
+    /**
+     * List of options to choose from
+     */
+    options: Array<string | SelectOption>;
+    /**
+     * Accessible label
+     * @demo Select Fruits
+     */
+    label: string;
+    /**
+     * Hide the label visually
+     * @demo
+     */
+    hiddenLabel?: boolean;
+    /**
+     * Placeholder text shown when no values are selected
+     * @demo
+     */
+    placeholder?: string;
+    /**
+     * Disabled
+     * @demo
+     */
+    disabled?: boolean;
+    /**
+     * Name for form registration
+     */
+    name?: string;
+    /**
+     * Error messages array (supports multiple validation errors)
+     */
+    errors?: string[];
+    /**
+     * Instructions shown below the label
+     * @demo
+     */
+    instructions?: string;
+    /**
+     * Form channel key for custom elements mode
+     */
+    formKey?: string;
+} & {
+    modelValue?: Array<string | number>;
+}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (value: (string | number)[]) => any;
+    change: (value: (string | number)[]) => any;
+}, string, import("vue").PublicProps, Readonly<{
+    /**
+     * List of options to choose from
+     */
+    options: Array<string | SelectOption>;
+    /**
+     * Accessible label
+     * @demo Select Fruits
+     */
+    label: string;
+    /**
+     * Hide the label visually
+     * @demo
+     */
+    hiddenLabel?: boolean;
+    /**
+     * Placeholder text shown when no values are selected
+     * @demo
+     */
+    placeholder?: string;
+    /**
+     * Disabled
+     * @demo
+     */
+    disabled?: boolean;
+    /**
+     * Name for form registration
+     */
+    name?: string;
+    /**
+     * Error messages array (supports multiple validation errors)
+     */
+    errors?: string[];
+    /**
+     * Instructions shown below the label
+     * @demo
+     */
+    instructions?: string;
+    /**
+     * Form channel key for custom elements mode
+     */
+    formKey?: string;
+} & {
+    modelValue?: Array<string | number>;
+}> & Readonly<{
+    "onUpdate:modelValue"?: ((value: (string | number)[]) => any) | undefined;
+    onChange?: ((value: (string | number)[]) => any) | undefined;
+}>, {
+    errors: string[];
+    disabled: boolean;
+    hiddenLabel: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

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

@@ -1,3 +1,4 @@
+import { type SelectOption } from "../compose/useSelectDropdown.ts";
 /**
  * By default, this component behaves like a normal select element with
  * custom styling.
@@ -19,10 +20,7 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
     /**
      * List of options to choose from
      */
-    options: Array<string | {
-        label: string;
-        value: string | number;
-    }>;
+    options: Array<string | SelectOption>;
     /**
      * Accessible label
      * @demo Select Option
@@ -81,10 +79,7 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
     /**
      * List of options to choose from
      */
-    options: Array<string | {
-        label: string;
-        value: string | number;
-    }>;
+    options: Array<string | SelectOption>;
     /**
      * Accessible label
      * @demo Select Option
@@ -140,18 +135,13 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
     "onUpdate:modelValue"?: ((value: string | number | null | undefined) => any) | undefined;
     onChange?: ((...args: any[]) => any) | undefined;
 }>, {
-    name: string;
     errors: string[];
-    formKey: string;
     disabled: boolean;
     searchable: boolean;
     compact: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, {
     option?: (props: {
-        option: {
-            label: string;
-            value: string | number;
-        };
+        option: SelectOption;
         selected: boolean;
         index: number;
     }) => any;

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

@@ -6,23 +6,23 @@ import type { TreeMenuItem } from "./tree-menu/GTreeMenuList.vue";
  *
  * **Props**:
  *
- * - `title` — optional heading and accessible name for the nav landmark.
- * - `items` — array of `TreeMenuItem` objects. Each item may have:
- *   - `label` — display text (required).
- *   - `href` or `to` — link destination. When `to` is provided and `vue-router`
+ * - `title` - optional heading and accessible name for the nav landmark.
+ * - `items` - array of `TreeMenuItem` objects. Each item may have:
+ *   - `label` - display text (required).
+ *   - `href` or `to` - link destination. When `to` is provided and `vue-router`
  *     is present the link is rendered as a `<router-link>`.
- *   - `children` — nested `TreeMenuItem[]` for sub-levels (unlimited depth).
- * - `listType` — `ul` (default) or `ol`. Use `ol` for numbered
+ *   - `children` - nested `TreeMenuItem[]` for sub-levels (unlimited depth).
+ * - `listType` - `ul` (default) or `ol`. Use `ol` for numbered
  *   hierarchies such as book chapters.
- * - `theme` — `light` (default) or `dark`.
+ * - `theme` - `light` (default) or `dark`.
  *
  * **Keyboard navigation** (tree-view style):
  *
- * - `↑` / `↓` — move between visible menu items.
- * - `→` — expand a collapsed item; if already expanded, move to its first child.
- * - `←` — collapse an expanded item; if already collapsed, move focus to its
+ * - `Up Arrow` / `Down Arrow` - move between visible menu items.
+ * - `Right Arrow` - expand a collapsed item; if already expanded, move to its first child.
+ * - `Left Arrow` - collapse an expanded item; if already collapsed, move focus to its
  *   parent.
- * - `Home` / `End` — jump to the first or last visible item.
+ * - `Home` / `End` - jump to the first or last visible item.
  */
 declare const _default: typeof __VLS_export;
 export default _default;
@@ -37,7 +37,7 @@ declare const __VLS_export: import("vue").DefineComponent<{
      */
     items: TreeMenuItem[];
     /**
-     * List element type — use `ol` for numbered hierarchies like book chapters
+     * List element type - use `ol` for numbered hierarchies like book chapters
      * @demo
      */
     listType?: "ul" | "ol";
@@ -57,7 +57,7 @@ declare const __VLS_export: import("vue").DefineComponent<{
      */
     items: TreeMenuItem[];
     /**
-     * List element type — use `ol` for numbered hierarchies like book chapters
+     * List element type - use `ol` for numbered hierarchies like book chapters
      * @demo
      */
     listType?: "ul" | "ol";

package/dist/compose/useSelectDropdown.d.ts

@@ -0,0 +1,56 @@
+import { type Ref } from "vue";
+/**
+ * A normalized select option with a label and a value.
+ * Both GSelect and GMultiSelect accept `Array<string | SelectOption>` and
+ * normalize the strings to this shape internally.
+ */
+export type SelectOption = {
+    label: string;
+    value: string | number;
+};
+/**
+ * Normalizes a mixed `Array<string | SelectOption>` into a uniform
+ * `SelectOption[]`.  Strings are converted to `{ label: s, value: s }`.
+ */
+export declare function normalizeSelectOptions(options: Array<string | SelectOption>): SelectOption[];
+export interface UseSelectDropdownOptions {
+    /** Reactive flag that is `true` when the dropdown is visible. */
+    open: Ref<boolean>;
+    /**
+     * The element whose bounding rect is used to decide whether the dropdown
+     * opens above or below (the trigger / combobox control).
+     */
+    anchorRef: Ref<HTMLElement | null>;
+    /** The listbox element – used to measure its natural scroll-height. */
+    listboxRef: Ref<HTMLElement | null>;
+    /**
+     * A stable unique id that doubles as the overlay-stack entry and the
+     * prefix for option element ids (`${baseId}-option-${index}`).
+     */
+    baseId: string;
+    /** The currently-highlighted option index, used by scrollOptionIntoView. */
+    activeIndex: Ref<number>;
+}
+export interface UseSelectDropdownReturn {
+    /** Current placement of the dropdown relative to the anchor. */
+    menuPlacement: Ref<"below" | "above">;
+    /** Inline styles to apply to the listbox element. */
+    menuStyle: Readonly<Ref<Record<string, string>>>;
+    /**
+     * Whether this overlay is topmost in the global stack.
+     * Use this to guard Escape-key handling.
+     */
+    isTop: Ref<boolean>;
+    /** Scrolls the currently-active option into view. */
+    scrollOptionIntoView: () => void;
+}
+/**
+ * Shared dropdown behaviour for GSelect and GMultiSelect.
+ *
+ * Manages:
+ *  - Menu placement (above / below) and max-height constraints
+ *  - window resize / scroll listeners (added when open, removed when closed)
+ *  - Overlay-stack registration (push on open, pop on close / unmount)
+ *  - Scrolling the active option into view
+ */
+export declare function useSelectDropdown({ open, anchorRef, listboxRef, baseId, activeIndex, }: UseSelectDropdownOptions): UseSelectDropdownReturn;