@illinois-grad/grad-vue 7.2.7 → 7.2.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +28 -0
- package/custom-elements.json +42 -0
- package/dist/components/GAppUpdateNotice.vue.d.ts +93 -0
- package/dist/components/GCheckboxGroup.vue.d.ts +1 -1
- package/dist/components/GForm.vue.d.ts +1 -1
- package/dist/components/GSearch.vue.d.ts +60 -16
- package/dist/compose/useAppUpdateCheck.d.ts +30 -0
- package/dist/{grad-vue-COt_mmY9.js → grad-vue-CtUm1dK7.js} +981 -810
- package/dist/grad-vue-CtUm1dK7.js.map +1 -0
- package/dist/grad-vue-elements.css +29 -29
- package/dist/grad-vue-elements.d.ts +7 -1
- package/dist/grad-vue-elements.js +1442 -1348
- package/dist/grad-vue-elements.js.map +1 -1
- package/dist/grad-vue.css +1 -1
- package/dist/grad-vue.d.ts +5 -1
- package/dist/grad-vue.js +1 -1
- package/dist/plugin.d.ts +2 -1
- package/dist/plugin.js +4 -4
- package/dist/plugin.js.map +1 -1
- package/dist/vite.d.ts +22 -0
- package/dist/vite.js +38 -0
- package/dist/vite.js.map +1 -0
- package/package.json +15 -3
- package/dist/grad-vue-COt_mmY9.js.map +0 -1
package/README.md
CHANGED
|
@@ -76,6 +76,34 @@ import { GButton } from '@illinois-grad/grad-vue'
|
|
|
76
76
|
</template>
|
|
77
77
|
```
|
|
78
78
|
|
|
79
|
+
### Notify Users About New Deploys
|
|
80
|
+
|
|
81
|
+
`GAppUpdateNotice` asks users to refresh when a newer build is deployed while
|
|
82
|
+
their tab is open. Add the Vite plugin, which gives each build a unique ID and
|
|
83
|
+
emits `version.json`:
|
|
84
|
+
|
|
85
|
+
```javascript
|
|
86
|
+
// vite.config.ts
|
|
87
|
+
import { appBuildVersion } from '@illinois-grad/grad-vue/vite'
|
|
88
|
+
|
|
89
|
+
export default defineConfig({
|
|
90
|
+
plugins: [vue(), appBuildVersion()],
|
|
91
|
+
})
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Render `<GAppUpdateNotice />` once in the app's root component, and serve
|
|
95
|
+
`version.json` without caching, e.g. in nginx:
|
|
96
|
+
|
|
97
|
+
```nginx
|
|
98
|
+
location = /version.json {
|
|
99
|
+
add_header Cache-Control "no-store" always;
|
|
100
|
+
try_files $uri =404;
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Optionally call `reloadOnStaleChunks()` in `main.ts` to reload once when a
|
|
105
|
+
lazily loaded chunk was removed by a deploy.
|
|
106
|
+
|
|
79
107
|
## Development
|
|
80
108
|
|
|
81
109
|
### Bootstrapping a New Component
|
package/custom-elements.json
CHANGED
|
@@ -1554,6 +1554,36 @@
|
|
|
1554
1554
|
},
|
|
1555
1555
|
"optional": false
|
|
1556
1556
|
},
|
|
1557
|
+
{
|
|
1558
|
+
"kind": "field",
|
|
1559
|
+
"name": "actions",
|
|
1560
|
+
"type": {
|
|
1561
|
+
"text": "GSearchAction[]"
|
|
1562
|
+
},
|
|
1563
|
+
"optional": true,
|
|
1564
|
+
"description": "Actions shown in their own group after search results",
|
|
1565
|
+
"default": "() => []"
|
|
1566
|
+
},
|
|
1567
|
+
{
|
|
1568
|
+
"kind": "field",
|
|
1569
|
+
"name": "actionsLabel",
|
|
1570
|
+
"type": {
|
|
1571
|
+
"text": "string"
|
|
1572
|
+
},
|
|
1573
|
+
"optional": true,
|
|
1574
|
+
"description": "Group label for actions",
|
|
1575
|
+
"default": "\"Actions\""
|
|
1576
|
+
},
|
|
1577
|
+
{
|
|
1578
|
+
"kind": "field",
|
|
1579
|
+
"name": "actionIcon",
|
|
1580
|
+
"type": {
|
|
1581
|
+
"text": "string | false"
|
|
1582
|
+
},
|
|
1583
|
+
"optional": true,
|
|
1584
|
+
"description": "Default icon classes for a decorative leading icon on actions, or `false` to hide it. Overridden per action by `action.icon` or by the `action-icon` slot.",
|
|
1585
|
+
"default": "undefined"
|
|
1586
|
+
},
|
|
1557
1587
|
{
|
|
1558
1588
|
"kind": "field",
|
|
1559
1589
|
"name": "placeholder",
|
|
@@ -1614,6 +1644,18 @@
|
|
|
1614
1644
|
"type": {
|
|
1615
1645
|
"text": "CustomEvent"
|
|
1616
1646
|
}
|
|
1647
|
+
},
|
|
1648
|
+
{
|
|
1649
|
+
"name": "action",
|
|
1650
|
+
"type": {
|
|
1651
|
+
"text": "CustomEvent"
|
|
1652
|
+
}
|
|
1653
|
+
},
|
|
1654
|
+
{
|
|
1655
|
+
"name": "close",
|
|
1656
|
+
"type": {
|
|
1657
|
+
"text": "CustomEvent"
|
|
1658
|
+
}
|
|
1617
1659
|
}
|
|
1618
1660
|
]
|
|
1619
1661
|
}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tells users that a newer version of the app has been deployed while their tab
|
|
3
|
+
* stayed open, and offers to refresh the page.
|
|
4
|
+
*
|
|
5
|
+
* Build the app with the `appBuildVersion()` Vite plugin, which gives each build
|
|
6
|
+
* a unique ID. The notice checks the deployed version when the tab regains focus
|
|
7
|
+
* or visibility, and every 10 minutes while it is visible. It does nothing in
|
|
8
|
+
* development or without the plugin.
|
|
9
|
+
*
|
|
10
|
+
* ```ts
|
|
11
|
+
* // vite.config.ts
|
|
12
|
+
* import { appBuildVersion } from "@illinois-grad/grad-vue/vite";
|
|
13
|
+
*
|
|
14
|
+
* export default defineConfig({
|
|
15
|
+
* plugins: [vue(), appBuildVersion()],
|
|
16
|
+
* });
|
|
17
|
+
* ```
|
|
18
|
+
*
|
|
19
|
+
* ```vue
|
|
20
|
+
* <GAppUpdateNotice />
|
|
21
|
+
* ```
|
|
22
|
+
*
|
|
23
|
+
* Serve `version.json` with `Cache-Control: no-store`, and optionally call
|
|
24
|
+
* `reloadOnStaleChunks()` at startup to recover from lazily loaded chunks that
|
|
25
|
+
* a deploy removed.
|
|
26
|
+
*/
|
|
27
|
+
declare const _default: typeof __VLS_export;
|
|
28
|
+
export default _default;
|
|
29
|
+
declare const __VLS_export: import("vue").DefineComponent<{
|
|
30
|
+
/**
|
|
31
|
+
* Message shown when an update is available
|
|
32
|
+
* @demo
|
|
33
|
+
*/
|
|
34
|
+
message?: string;
|
|
35
|
+
/**
|
|
36
|
+
* Refresh button text
|
|
37
|
+
* @demo
|
|
38
|
+
*/
|
|
39
|
+
reloadLabel?: string;
|
|
40
|
+
/**
|
|
41
|
+
* Dismiss button text
|
|
42
|
+
* @demo
|
|
43
|
+
*/
|
|
44
|
+
dismissLabel?: string;
|
|
45
|
+
/**
|
|
46
|
+
* Milliseconds between checks while the tab is visible
|
|
47
|
+
*/
|
|
48
|
+
intervalMs?: number;
|
|
49
|
+
/**
|
|
50
|
+
* URL of the deployed version file, defaults to the one set by `appBuildVersion()`
|
|
51
|
+
*/
|
|
52
|
+
versionUrl?: string;
|
|
53
|
+
/**
|
|
54
|
+
* Build ID of the running app, defaults to the one set by `appBuildVersion()`
|
|
55
|
+
*/
|
|
56
|
+
currentBuildId?: string;
|
|
57
|
+
}, {
|
|
58
|
+
/** Checks for a new version immediately */
|
|
59
|
+
check: () => Promise<void>;
|
|
60
|
+
}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{
|
|
61
|
+
/**
|
|
62
|
+
* Message shown when an update is available
|
|
63
|
+
* @demo
|
|
64
|
+
*/
|
|
65
|
+
message?: string;
|
|
66
|
+
/**
|
|
67
|
+
* Refresh button text
|
|
68
|
+
* @demo
|
|
69
|
+
*/
|
|
70
|
+
reloadLabel?: string;
|
|
71
|
+
/**
|
|
72
|
+
* Dismiss button text
|
|
73
|
+
* @demo
|
|
74
|
+
*/
|
|
75
|
+
dismissLabel?: string;
|
|
76
|
+
/**
|
|
77
|
+
* Milliseconds between checks while the tab is visible
|
|
78
|
+
*/
|
|
79
|
+
intervalMs?: number;
|
|
80
|
+
/**
|
|
81
|
+
* URL of the deployed version file, defaults to the one set by `appBuildVersion()`
|
|
82
|
+
*/
|
|
83
|
+
versionUrl?: string;
|
|
84
|
+
/**
|
|
85
|
+
* Build ID of the running app, defaults to the one set by `appBuildVersion()`
|
|
86
|
+
*/
|
|
87
|
+
currentBuildId?: string;
|
|
88
|
+
}> & Readonly<{}>, {
|
|
89
|
+
message: string;
|
|
90
|
+
reloadLabel: string;
|
|
91
|
+
dismissLabel: string;
|
|
92
|
+
intervalMs: number;
|
|
93
|
+
}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
|
|
@@ -71,8 +71,8 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
|
|
|
71
71
|
"onUpdate:modelValue"?: ((value: Record<string, any>) => any) | undefined;
|
|
72
72
|
}>, {
|
|
73
73
|
action: string;
|
|
74
|
-
method: string;
|
|
75
74
|
formKey: string;
|
|
75
|
+
method: string;
|
|
76
76
|
}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, {
|
|
77
77
|
default?: (props: {
|
|
78
78
|
isSubmitting: boolean;
|
|
@@ -3,6 +3,15 @@ export interface GSearchGroup<R> {
|
|
|
3
3
|
label: string;
|
|
4
4
|
items: R[];
|
|
5
5
|
}
|
|
6
|
+
export interface GSearchAction {
|
|
7
|
+
id: string | number;
|
|
8
|
+
label: string;
|
|
9
|
+
/**
|
|
10
|
+
* Optional icon classes to render a decorative leading icon before the label
|
|
11
|
+
* (e.g., `"fa-solid fa-magnifying-glass"`), or `false` to hide the icon.
|
|
12
|
+
*/
|
|
13
|
+
icon?: string | false;
|
|
14
|
+
}
|
|
6
15
|
/**
|
|
7
16
|
* A combobox-style search that shows a list of results as an auto
|
|
8
17
|
* complete dropdown.
|
|
@@ -13,9 +22,11 @@ export interface GSearchGroup<R> {
|
|
|
13
22
|
*
|
|
14
23
|
* **Events**:
|
|
15
24
|
*
|
|
16
|
-
* - `submit` event is emitted when a search should be performed.
|
|
17
|
-
* - `select` event is
|
|
18
|
-
*
|
|
25
|
+
* - `submit` event is emitted with `string | null` when a search should be performed.
|
|
26
|
+
* - `select` event is emitted when a user selects a result in the dropdown.
|
|
27
|
+
* - `action` event is emitted with the chosen `GSearchAction` when a user
|
|
28
|
+
* activates an action in the dropdown, leaving the query and dropdown open.
|
|
29
|
+
* - `close` event is emitted when the results dropdown closes.
|
|
19
30
|
*
|
|
20
31
|
* > [!NOTE]
|
|
21
32
|
* > The `v-model` value should *not* be used to trigger a search,
|
|
@@ -27,13 +38,28 @@ export interface GSearchGroup<R> {
|
|
|
27
38
|
* - Pass an array of objects that extend `{ id: string | number; title: string; }`.
|
|
28
39
|
* - Pass an array of `GSearchGroup<T>` objects, where the `items` property extends the above type.
|
|
29
40
|
* In this case the results are grouped.
|
|
41
|
+
* - `actions` renders additional `GSearchAction` items
|
|
42
|
+
* (`{ id: string | number; label: string; icon?: string | false }`) in their own shaded
|
|
43
|
+
* group after the results with a decorative leading icon. They are reachable with the
|
|
44
|
+
* arrow keys, excluded from the result count, and announced to screen readers via a
|
|
45
|
+
* polite status region.
|
|
46
|
+
* - `actionsLabel` customizes the label of the actions group (defaults to `"Actions"`).
|
|
47
|
+
* - `actionIcon` sets default icon classes (e.g., `"fa-solid fa-arrow-right"`) for the
|
|
48
|
+
* decorative leading icon on actions, or `false` to hide it. Overridden per action by
|
|
49
|
+
* `action.icon` or by the `action-icon` slot.
|
|
30
50
|
* - `auto` makes search submit on user input. Defaults to `true`.
|
|
31
51
|
* if `false`, submission happens on Enter or clicking the search button.
|
|
32
52
|
* - `loading` shows a loading indicator. Use if the search may take longer.
|
|
33
53
|
*
|
|
34
|
-
* **Slot**: `option` customizes how
|
|
54
|
+
* **Slot**: `option` customizes how a result option is rendered.
|
|
35
55
|
* It receives the current item as `option`.
|
|
36
56
|
*
|
|
57
|
+
* **Slot**: `action` customizes how an action option is rendered.
|
|
58
|
+
* It receives the current action as `action`.
|
|
59
|
+
*
|
|
60
|
+
* **Slot**: `action-icon` customizes the decorative leading icon for an action.
|
|
61
|
+
* It receives the current action as `action`.
|
|
62
|
+
*
|
|
37
63
|
* **Slot**: `group` customizes the group label for each group.
|
|
38
64
|
*
|
|
39
65
|
* Here is a minimal implementation:
|
|
@@ -52,9 +78,10 @@ export interface GSearchGroup<R> {
|
|
|
52
78
|
* ]);
|
|
53
79
|
* const searchResults = ref<SearchResult[]>([]);
|
|
54
80
|
*
|
|
55
|
-
* function submit(query: string) {
|
|
81
|
+
* function submit(query: string | null) {
|
|
82
|
+
* const q = (query ?? "").toLowerCase();
|
|
56
83
|
* searchResults.value = searchData.value.filter((result) =>
|
|
57
|
-
* result.title.toLowerCase().includes(
|
|
84
|
+
* result.title.toLowerCase().includes(q),
|
|
58
85
|
* );
|
|
59
86
|
* }
|
|
60
87
|
* function selected(item: SearchResult) {
|
|
@@ -78,6 +105,20 @@ declare const __VLS_export: <T extends {
|
|
|
78
105
|
}>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
|
|
79
106
|
props: import("vue").PublicProps & __VLS_PrettifyLocal<({
|
|
80
107
|
results: GSearchGroup<T>[] | T[];
|
|
108
|
+
/**
|
|
109
|
+
* Actions shown in their own group after search results
|
|
110
|
+
*/
|
|
111
|
+
actions?: GSearchAction[];
|
|
112
|
+
/**
|
|
113
|
+
* Group label for actions
|
|
114
|
+
* @demo
|
|
115
|
+
*/
|
|
116
|
+
actionsLabel?: string;
|
|
117
|
+
/**
|
|
118
|
+
* Default icon classes for a decorative leading icon on actions, or `false` to hide it.
|
|
119
|
+
* Overridden per action by `action.icon` or by the `action-icon` slot.
|
|
120
|
+
*/
|
|
121
|
+
actionIcon?: string | false;
|
|
81
122
|
/**
|
|
82
123
|
* Placeholder
|
|
83
124
|
* @demo
|
|
@@ -101,8 +142,10 @@ declare const __VLS_export: <T extends {
|
|
|
101
142
|
} & {
|
|
102
143
|
modelValue?: string | null;
|
|
103
144
|
}) & {
|
|
104
|
-
onSelect?: ((
|
|
105
|
-
onSubmit?: ((
|
|
145
|
+
onSelect?: ((result: T) => any) | undefined;
|
|
146
|
+
onSubmit?: ((query: string | null) => any) | undefined;
|
|
147
|
+
onAction?: ((action: GSearchAction) => any) | undefined;
|
|
148
|
+
onClose?: (() => any) | undefined;
|
|
106
149
|
"onUpdate:modelValue"?: ((value: string | null) => any) | undefined;
|
|
107
150
|
}> & (typeof globalThis extends {
|
|
108
151
|
__VLS_PROPS_FALLBACK: infer P;
|
|
@@ -110,19 +153,20 @@ declare const __VLS_export: <T extends {
|
|
|
110
153
|
expose: (exposed: {}) => void;
|
|
111
154
|
attrs: any;
|
|
112
155
|
slots: {
|
|
113
|
-
group?: (props: {
|
|
114
|
-
group: GSearchGroup<T>;
|
|
115
|
-
}) => any;
|
|
116
|
-
} & {
|
|
117
156
|
option?: (props: {
|
|
118
157
|
option: T;
|
|
119
158
|
}) => any;
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
159
|
+
action?: (props: {
|
|
160
|
+
action: GSearchAction;
|
|
161
|
+
}) => any;
|
|
162
|
+
"action-icon"?: (props: {
|
|
163
|
+
action: GSearchAction;
|
|
164
|
+
}) => any;
|
|
165
|
+
group?: (props: {
|
|
166
|
+
group: GSearchGroup<T>;
|
|
123
167
|
}) => any;
|
|
124
168
|
};
|
|
125
|
-
emit: ((
|
|
169
|
+
emit: (((evt: "select", result: T) => void) & ((evt: "submit", query: string | null) => void) & ((evt: "action", action: GSearchAction) => void) & ((evt: "close") => void)) & ((event: "update:modelValue", value: string | null) => void);
|
|
126
170
|
}>) => import("vue").VNode & {
|
|
127
171
|
__ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
|
|
128
172
|
};
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/** Name of the `<meta>` tag that `appBuildVersion()` from `@illinois-grad/grad-vue/vite` adds to `index.html`. */
|
|
2
|
+
export declare const APP_BUILD_ID_META = "app-build-id";
|
|
3
|
+
export interface AppUpdateCheckOptions {
|
|
4
|
+
/** Milliseconds between checks while the tab is visible. Defaults to 10 minutes. */
|
|
5
|
+
intervalMs?: number;
|
|
6
|
+
/** URL of the deployed build's version file. Defaults to the one set by `appBuildVersion()`. */
|
|
7
|
+
versionUrl?: string;
|
|
8
|
+
/** Build ID of the running app. Defaults to the one set by `appBuildVersion()`. */
|
|
9
|
+
currentBuildId?: string;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Detects that a newer build was deployed while this tab stayed open, so the user can reload
|
|
13
|
+
* instead of running stale code against an updated API.
|
|
14
|
+
*
|
|
15
|
+
* Checks when the tab regains focus or visibility, and periodically while it is visible.
|
|
16
|
+
* Does nothing unless the app is built with `appBuildVersion()` from `@illinois-grad/grad-vue/vite`,
|
|
17
|
+
* or `currentBuildId` and `versionUrl` are given.
|
|
18
|
+
*/
|
|
19
|
+
export declare function useAppUpdateCheck(options?: AppUpdateCheckOptions): {
|
|
20
|
+
updateAvailable: import("vue").Ref<boolean, boolean>;
|
|
21
|
+
check: () => Promise<void>;
|
|
22
|
+
reload: () => void;
|
|
23
|
+
};
|
|
24
|
+
/**
|
|
25
|
+
* Reloads once when a lazily loaded chunk is missing because a newer build replaced it.
|
|
26
|
+
* A second failure shortly after a reload is left to surface instead of looping.
|
|
27
|
+
*
|
|
28
|
+
* Call it once at startup, e.g. in `main.ts`.
|
|
29
|
+
*/
|
|
30
|
+
export declare function reloadOnStaleChunks(): void;
|