Skip to content

Commit 4eae915

Browse files
author
Quang Phan
committed
feat(shorcut): add ambient types
1 parent 2dfde9e commit 4eae915

9 files changed

Lines changed: 202 additions & 69 deletions

File tree

‎.changeset/brown-dryers-look.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@svelte-put/shortcut': patch
3+
---
4+
5+
add ambient types

‎packages/actions/shortcut/api/docs/shortcut.md‎

Lines changed: 29 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,29 @@
1-
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2-
3-
[Home](./index.md) &gt; [@svelte-put/shortcut](./shortcut.md)
4-
5-
## shortcut package
6-
7-
svelte action - `use:shortcut` add keyboard shortcut to node
8-
9-
## Functions
10-
11-
| Function | Description |
12-
| --- | --- |
13-
| [shortcut(node, params)](./shortcut.shortcut.md) | Listen for keyboard event and trigger <code>shortcut</code> [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) |
14-
15-
## Interfaces
16-
17-
| Interface | Description |
18-
| --- | --- |
19-
| [ShortcutEventDetails](./shortcut.shortcuteventdetails.md) | <code>detail</code> payload for 'shortcut' [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) |
20-
| [ShortcutParameters](./shortcut.shortcutparameters.md) | svelte action parameters to config behavior of <code>shortcut</code> |
21-
| [ShortcutTrigger](./shortcut.shortcuttrigger.md) | A definition of a shortcut trigger |
22-
23-
## Type Aliases
24-
25-
| Type Alias | Description |
26-
| --- | --- |
27-
| [ShortcutModifier](./shortcut.shortcutmodifier.md) | Supported modifier keys, map to [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent)<!-- -->'s [altkey](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/altKey)<!-- -->, [ctrlKey](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/ctrlKey)<!-- -->, [shiftKey](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/shiftKey)<!-- -->, [metaKey](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/metaKey)<!-- -->. |
28-
| [ShortcutModifierDefinition](./shortcut.shortcutmodifierdefinition.md) | Possible variations for modifier definition |
29-
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@svelte-put/shortcut](./shortcut.md)
4+
5+
## shortcut package
6+
7+
svelte action - `use:shortcut` add keyboard shortcut to node
8+
9+
## Functions
10+
11+
| Function | Description |
12+
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
13+
| [shortcut(node, params)](./shortcut.shortcut.md) | Listen for keyboard event and trigger <code>shortcut</code> [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) |
14+
15+
## Interfaces
16+
17+
| Interface | Description |
18+
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
19+
| [ShortcutAttributes](./shortcut.shortcutattributes.md) | Additional attributes extended from <code>svelte-put/shortcut</code> |
20+
| [ShortcutEventDetails](./shortcut.shortcuteventdetails.md) | <code>detail</code> payload for 'shortcut' [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) |
21+
| [ShortcutParameters](./shortcut.shortcutparameters.md) | svelte action parameters to config behavior of <code>shortcut</code> |
22+
| [ShortcutTrigger](./shortcut.shortcuttrigger.md) | A definition of a shortcut trigger |
23+
24+
## Type Aliases
25+
26+
| Type Alias | Description |
27+
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
28+
| [ShortcutModifier](./shortcut.shortcutmodifier.md) | Supported modifier keys, map to [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent)<!-- -->'s [altkey](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/altKey)<!-- -->, [ctrlKey](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/ctrlKey)<!-- -->, [shiftKey](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/shiftKey)<!-- -->, [metaKey](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/metaKey)<!-- -->. |
29+
| [ShortcutModifierDefinition](./shortcut.shortcutmodifierdefinition.md) | Possible variations for modifier definition |

‎packages/actions/shortcut/api/docs/shortcut.shortcut.md‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ Either way, only use `callback` or `on:shortcut` and not both to avoid handler d
5555

5656
Typical usage
5757

58-
```html
58+
```svelte
5959
<script lang="ts">
6060
import { shortcut, type ShortcutEventDetails } from '@svelte-put/shortcut';
6161
@@ -81,11 +81,38 @@ Typical usage
8181
}
8282
</script>
8383
84-
<svelte:window use:shortcut={{ trigger: [ { key: 'k', // trigger if either ctrl or meta is pressed
85-
modifier: ['ctrl', 'meta'], callback: onOpenCommandPalette, preventDefault: true, }, { key:
86-
'Escape', // preferably avoid arrow functions here for better performance // with arrow functions
87-
the action has to be updated more frequently callback: onCloseCommandPalette, enabled:
88-
commandPalette, preventDefault: true, }, { key: 'k', // trigger if both ctrl & shift are pressed
89-
modifier: [['ctrl', 'shift']], id: 'do-something-else', callback: doSomethingElse, }, ], }}
90-
on:shortcut={onShortcut} />
84+
<svelte:window
85+
use:shortcut={{
86+
trigger: [
87+
{
88+
key: 'k',
89+
90+
// trigger if either ctrl or meta is pressed
91+
modifier: ['ctrl', 'meta'],
92+
93+
callback: onOpenCommandPalette,
94+
preventDefault: true,
95+
},
96+
{
97+
key: 'Escape',
98+
99+
// preferably avoid arrow functions here for better performance
100+
// with arrow functions the action has to be updated more frequently
101+
callback: onCloseCommandPalette,
102+
103+
enabled: commandPalette,
104+
preventDefault: true,
105+
},
106+
{
107+
key: 'k',
108+
109+
// trigger if both ctrl & shift are pressed
110+
modifier: [['ctrl', 'shift']],
111+
id: 'do-something-else',
112+
callback: doSomethingElse,
113+
},
114+
],
115+
}}
116+
on:shortcut={onShortcut}
117+
/>
91118
```

‎packages/actions/shortcut/api/docs/shortcut.shortcutattributes.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@svelte-put/shortcut](./shortcut.md) &gt; [ShortcutAttributes](./shortcut.shortcutattributes.md)
4+
5+
## ShortcutAttributes interface
6+
7+
Additional attributes extended from `svelte-put/shortcut`
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
export interface ShortcutAttributes
13+
```
14+
15+
## Remarks
16+
17+
The ambient types for these extended attributes should be available automatically whenever `svelte-put/shorcut` is imported.
18+
19+
## Properties
20+
21+
| Property | Modifiers | Type | Description |
22+
| ---------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------- | ----------------- |
23+
| [onshortcut?](./shortcut.shortcutattributes.onshortcut.md) | | (event: CustomEvent&lt;[ShortcutEventDetails](./shortcut.shortcuteventdetails.md)<!-- -->&gt;) =&gt; void | <i>(Optional)</i> |

‎packages/actions/shortcut/api/docs/shortcut.shortcutattributes.onshortcut.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [@svelte-put/shortcut](./shortcut.md) &gt; [ShortcutAttributes](./shortcut.shortcutattributes.md) &gt; [onshortcut](./shortcut.shortcutattributes.onshortcut.md)
4+
5+
## ShortcutAttributes.onshortcut property
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
onshortcut?: (event: CustomEvent<ShortcutEventDetails>) => void;
11+
```

‎packages/actions/shortcut/api/docs/shortcut.shortcutmodifierdefinition.md‎

Lines changed: 40 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -21,47 +21,78 @@ export type ShortcutModifierDefinition =
2121

2222
Listen for a single modifier
2323

24-
```html
24+
```svelte
2525
<script>
2626
import { shortcut } from '@svelte-put/shortcut';
2727
</script>
2828
29-
<window use:shortcut={{ trigger: { key: 'k' , modifier: 'ctrl', }, }} />
29+
<window
30+
use:shortcut={{
31+
trigger: {
32+
key: 'k',
33+
modifier: 'ctrl',
34+
},
35+
}}
36+
/>
3037
```
3138

3239
## Example 2
3340

3441
Listen for one of many modifiers (or)
3542

36-
```html
43+
```svelte
3744
<script>
3845
import { shortcut } from '@svelte-put/shortcut';
3946
</script>
4047
41-
<window use:shortcut={{ trigger: { key: 'k' , modifier: ['ctrl', 'meta'], }, }} />
48+
<window
49+
use:shortcut={{
50+
trigger: {
51+
key: 'k',
52+
modifier: ['ctrl', 'meta'],
53+
},
54+
}}
55+
/>
4256
```
4357

4458
## Example 3
4559

4660
Listen for a combination of multiple modifiers (and)
4761

48-
```html
62+
```svelte
4963
<script>
5064
import { shortcut } from '@svelte-put/shortcut';
5165
</script>
5266
53-
<window use:shortcut={{ trigger: { key: 'k' , modifier: [['ctrl', 'shift']], }, }} />
67+
<window
68+
use:shortcut={{
69+
trigger: {
70+
key: 'k',
71+
modifier: [['ctrl', 'shift']],
72+
},
73+
}}
74+
/>
5475
```
5576

5677
## Example 4
5778

5879
A mix of the 3 previous examples
5980

60-
```html
81+
```svelte
6182
<script>
6283
import { shortcut } from '@svelte-put/shortcut';
6384
</script>
6485
65-
<window use:shortcut={{ trigger: { key: 'k' , modifier: [ ['ctrl', 'shift'], // ctrl and shift // or
66-
['meta'], // meta ], }, }} />
86+
<window
87+
use:shortcut={{
88+
trigger: {
89+
key: 'k',
90+
modifier: [
91+
['ctrl', 'shift'], // ctrl and shift
92+
// or
93+
['meta'], // meta
94+
],
95+
},
96+
}}
97+
/>
6798
```

‎packages/actions/shortcut/api/shortcut.api.md‎

Lines changed: 27 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -3,40 +3,50 @@
33
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
44
55
```ts
6-
76
// @public
8-
export function shortcut(node: HTMLElement, params: ShortcutParameters): {
9-
update: (update: ShortcutParameters) => void;
10-
destroy: () => void;
7+
export function shortcut(
8+
node: HTMLElement,
9+
params: ShortcutParameters,
10+
): {
11+
update: (update: ShortcutParameters) => void;
12+
destroy: () => void;
1113
};
1214

15+
// @public
16+
export interface ShortcutAttributes {
17+
// (undocumented)
18+
onshortcut?: (event: CustomEvent<ShortcutEventDetails>) => void;
19+
}
20+
1321
// @public
1422
export interface ShortcutEventDetails {
15-
node: HTMLElement;
16-
trigger: ShortcutTrigger;
23+
node: HTMLElement;
24+
trigger: ShortcutTrigger;
1725
}
1826

1927
// @public
2028
export type ShortcutModifier = 'alt' | 'ctrl' | 'meta' | 'shift';
2129

2230
// @public
23-
export type ShortcutModifierDefinition = ShortcutModifier | ShortcutModifier[] | ShortcutModifier[][];
31+
export type ShortcutModifierDefinition =
32+
| ShortcutModifier
33+
| ShortcutModifier[]
34+
| ShortcutModifier[][];
2435

2536
// @public
2637
export interface ShortcutParameters {
27-
enabled?: boolean;
28-
trigger: Array<ShortcutTrigger> | ShortcutTrigger;
29-
type?: 'keydown' | 'keyup';
38+
enabled?: boolean;
39+
trigger: Array<ShortcutTrigger> | ShortcutTrigger;
40+
type?: 'keydown' | 'keyup';
3041
}
3142

3243
// @public
3344
export interface ShortcutTrigger {
34-
callback?: (detail: ShortcutEventDetails) => void;
35-
enabled?: boolean;
36-
id?: string;
37-
key: string;
38-
modifier?: ShortcutModifierDefinition;
39-
preventDefault?: boolean;
45+
callback?: (detail: ShortcutEventDetails) => void;
46+
enabled?: boolean;
47+
id?: string;
48+
key: string;
49+
modifier?: ShortcutModifierDefinition;
50+
preventDefault?: boolean;
4051
}
41-
4252
```

‎packages/actions/shortcut/src/shortcut.ts‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,26 @@
1-
import type { ShortcutEventDetails, ShortcutModifier, ShortcutParameters } from './types';
1+
import type {
2+
ShortcutEventDetails,
3+
ShortcutModifier,
4+
ShortcutParameters,
5+
ShortcutAttributes,
6+
} from './types';
7+
8+
// ambient typing
9+
declare global {
10+
// eslint-disable-next-line @typescript-eslint/no-namespace
11+
export namespace svelte.JSX {
12+
// eslint-disable-next-line @typescript-eslint/no-empty-interface
13+
export interface HTMLAttributes extends ShortcutAttributes {}
14+
}
15+
}
216

317
/**
418
* Listen for keyboard event and trigger `shortcut` {@link https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent | CustomEvent }
519
* @public
620
*
721
* @example Typical usage
822
*
9-
* ```html
23+
* ```svelte
1024
* <script lang="ts">
1125
* import { shortcut, type ShortcutEventDetails } from '@svelte-put/shortcut';
1226
*

‎packages/actions/shortcut/src/types/index.ts‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,15 @@
1+
/**
2+
* Additional attributes extended from `svelte-put/shortcut`
3+
* @public
4+
*
5+
* @remarks
6+
* The ambient types for these extended attributes should be available automatically
7+
* whenever `svelte-put/shorcut` is imported.
8+
*/
9+
export interface ShortcutAttributes {
10+
onshortcut?: (event: CustomEvent<ShortcutEventDetails>) => void; // on:shortcut
11+
}
12+
113
/**
214
* Supported modifier keys, map to {@link https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent | KeyboardEvent}'s
315
* {@link https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/altKey | altkey},
@@ -18,7 +30,7 @@ export type ShortcutModifier = 'alt' | 'ctrl' | 'meta' | 'shift';
1830
*
1931
* Listen for a single modifier
2032
*
21-
* ```html
33+
* ```svelte
2234
* <script>
2335
* import { shortcut } from '@svelte-put/shortcut';
2436
* </script>
@@ -36,7 +48,7 @@ export type ShortcutModifier = 'alt' | 'ctrl' | 'meta' | 'shift';
3648
*
3749
* Listen for one of many modifiers (or)
3850
*
39-
* ```html
51+
* ```svelte
4052
* <script>
4153
* import { shortcut } from '@svelte-put/shortcut';
4254
* </script>
@@ -54,7 +66,7 @@ export type ShortcutModifier = 'alt' | 'ctrl' | 'meta' | 'shift';
5466
*
5567
* Listen for a combination of multiple modifiers (and)
5668
*
57-
* ```html
69+
* ```svelte
5870
* <script>
5971
* import { shortcut } from '@svelte-put/shortcut';
6072
* </script>
@@ -73,7 +85,7 @@ export type ShortcutModifier = 'alt' | 'ctrl' | 'meta' | 'shift';
7385
*
7486
* A mix of the 3 previous examples
7587
*
76-
* ```html
88+
* ```svelte
7789
* <script>
7890
* import { shortcut } from '@svelte-put/shortcut';
7991
* </script>

0 commit comments

Comments
 (0)
⚡