This commit is contained in:
Manuel 2022-03-26 18:21:13 +00:00 committed by GitHub
commit 029ba1ff37
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
17 changed files with 574 additions and 68 deletions

View file

@ -1,6 +1,6 @@
# Component Index # Component Index
> 171 components exported from carbon-components-svelte@0.62.2. > 173 components exported from carbon-components-svelte@0.62.2.
## Components ## Components
@ -116,6 +116,7 @@
- [`SelectItemGroup`](#selectitemgroup) - [`SelectItemGroup`](#selectitemgroup)
- [`SelectSkeleton`](#selectskeleton) - [`SelectSkeleton`](#selectskeleton)
- [`SelectableTile`](#selectabletile) - [`SelectableTile`](#selectabletile)
- [`SessionStorage`](#sessionstorage)
- [`SideNav`](#sidenav) - [`SideNav`](#sidenav)
- [`SideNavDivider`](#sidenavdivider) - [`SideNavDivider`](#sidenavdivider)
- [`SideNavItems`](#sidenavitems) - [`SideNavItems`](#sidenavitems)
@ -175,6 +176,7 @@
- [`TreeView`](#treeview) - [`TreeView`](#treeview)
- [`Truncate`](#truncate) - [`Truncate`](#truncate)
- [`UnorderedList`](#unorderedlist) - [`UnorderedList`](#unorderedlist)
- [`WebStorage`](#webstorage)
--- ---
@ -2241,11 +2243,11 @@ None.
### Props ### Props
| Prop name | Kind | Reactive | Type | Default value | Description | | Prop name | Kind | Reactive | Type | Default value | Description |
| :-------- | :-------------------- | :------- | :---------------------- | ---------------------------------------------------- | --------------------------------------------------------------- | | :-------- | :-------------------- | :------- | :---------------------- | ----------------------------------------------- | --------------------------------------------------------------- |
| value | <code>let</code> | Yes | <code>any</code> | <code>""</code> | Provide a value to persist | | value | <code>let</code> | Yes | <code>any</code> | <code>""</code> | Provide a value to persist |
| key | <code>let</code> | No | <code>string</code> | <code>"local-storage-key"</code> | Specify the local storage key | | key | <code>let</code> | Yes | <code>string</code> | <code>"local-storage-key"</code> | Specify the local storage key |
| clearItem | <code>function</code> | No | <code>() => void</code> | <code>() => { localStorage.removeItem(key); }</code> | Remove the persisted key value from the browser's local storage | | clearItem | <code>function</code> | No | <code>() => void</code> | <code>() => { storage.removeItem(key); }</code> | Remove the persisted key value from the browser's local storage |
| clearAll | <code>function</code> | No | <code>() => void</code> | <code>() => { localStorage.clear(); }</code> | Clear all key values from the browser's local storage | | clearAll | <code>function</code> | No | <code>() => void</code> | <code>() => { storage.clear(); }</code> | Clear all key values from the browser's local storage |
### Slots ### Slots
@ -2254,9 +2256,10 @@ None.
### Events ### Events
| Event name | Type | Detail | | Event name | Type | Detail |
| :--------- | :--------- | :------------------------------------------- | | :--------- | :-------- | :----- |
| save | dispatched | <code>null</code> | | save | forwarded | -- |
| update | dispatched | <code>{ prevValue: any; value: any; }</code> | | update | forwarded | -- |
| updateKey | forwarded | -- |
## `Modal` ## `Modal`
@ -3348,6 +3351,29 @@ None.
| mouseleave | forwarded | -- | | mouseleave | forwarded | -- |
| keydown | forwarded | -- | | keydown | forwarded | -- |
## `SessionStorage`
### Props
| Prop name | Kind | Reactive | Type | Default value | Description |
| :-------- | :-------------------- | :------- | :---------------------- | ----------------------------------------------- | --------------------------------------------------------------- |
| value | <code>let</code> | Yes | <code>any</code> | <code>""</code> | Provide a value to persist |
| key | <code>let</code> | Yes | <code>string</code> | <code>"session-storage-key"</code> | Specify the local storage key |
| clearItem | <code>function</code> | No | <code>() => void</code> | <code>() => { storage.removeItem(key); }</code> | Remove the persisted key value from the browser's local storage |
| clearAll | <code>function</code> | No | <code>() => void</code> | <code>() => { storage.clear(); }</code> | Clear all key values from the browser's local storage |
### Slots
None.
### Events
| Event name | Type | Detail |
| :--------- | :-------- | :----- |
| save | forwarded | -- |
| update | forwarded | -- |
| updateKey | forwarded | -- |
## `SideNav` ## `SideNav`
### Props ### Props
@ -4847,3 +4873,27 @@ None.
| mouseover | forwarded | -- | | mouseover | forwarded | -- |
| mouseenter | forwarded | -- | | mouseenter | forwarded | -- |
| mouseleave | forwarded | -- | | mouseleave | forwarded | -- |
## `WebStorage`
### Props
| Prop name | Kind | Reactive | Type | Default value | Description |
| :-------- | :-------------------- | :------- | :---------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------- |
| value | <code>let</code> | Yes | <code>any</code> | <code>""</code> | Provide a value to persist |
| key | <code>let</code> | No | <code>string</code> | <code>"storage-key"</code> | Specify the local storage key |
| storage | <code>let</code> | No | <code>"local"&#124;"session"</code> | <code>"local"</code> | Select WebStorage to use |
| clearItem | <code>function</code> | No | <code>() => void</code> | <code>() => { webStorage.removeItem(key); }</code> | Remove the persisted key value from the browser's selected WebStorage |
| clearAll | <code>function</code> | No | <code>() => void</code> | <code>() => { webStorage.clear(); }</code> | Clear all key values from the browser's selected WebStorage |
### Slots
None.
### Events
| Event name | Type | Detail |
| :--------- | :--------- | :------------------------------------------- |
| save | dispatched | <code>null</code> |
| updateKey | dispatched | <code>{ prevKey: any; key: any; }</code> |
| update | dispatched | <code>{ prevValue: any; value: any; }</code> |

View file

@ -1,5 +1,5 @@
{ {
"total": 171, "total": 173,
"components": [ "components": [
{ {
"moduleName": "Accordion", "moduleName": "Accordion",
@ -5995,7 +5995,7 @@
"isFunction": false, "isFunction": false,
"isFunctionDeclaration": false, "isFunctionDeclaration": false,
"constant": false, "constant": false,
"reactive": false "reactive": true
}, },
{ {
"name": "value", "name": "value",
@ -6013,7 +6013,7 @@
"kind": "function", "kind": "function",
"description": "Remove the persisted key value from the browser's local storage", "description": "Remove the persisted key value from the browser's local storage",
"type": "() => void", "type": "() => void",
"value": "() => { localStorage.removeItem(key); }", "value": "() => { storage.removeItem(key); }",
"isFunction": true, "isFunction": true,
"isFunctionDeclaration": true, "isFunctionDeclaration": true,
"constant": false, "constant": false,
@ -6024,7 +6024,7 @@
"kind": "function", "kind": "function",
"description": "Clear all key values from the browser's local storage", "description": "Clear all key values from the browser's local storage",
"type": "() => void", "type": "() => void",
"value": "() => { localStorage.clear(); }", "value": "() => { storage.clear(); }",
"isFunction": true, "isFunction": true,
"isFunctionDeclaration": true, "isFunctionDeclaration": true,
"constant": false, "constant": false,
@ -6034,12 +6034,9 @@
"moduleExports": [], "moduleExports": [],
"slots": [], "slots": [],
"events": [ "events": [
{ "type": "dispatched", "name": "save", "detail": "null" }, { "type": "forwarded", "name": "save", "element": "WebStorage" },
{ { "type": "forwarded", "name": "update", "element": "WebStorage" },
"type": "dispatched", { "type": "forwarded", "name": "updateKey", "element": "WebStorage" }
"name": "update",
"detail": "{ prevValue: any; value: any; }"
}
], ],
"typedefs": [] "typedefs": []
}, },
@ -9950,6 +9947,64 @@
"typedefs": [], "typedefs": [],
"rest_props": { "type": "Element", "name": "label" } "rest_props": { "type": "Element", "name": "label" }
}, },
{
"moduleName": "SessionStorage",
"filePath": "src/LocalStorage/SessionStorage.svelte",
"props": [
{
"name": "key",
"kind": "let",
"description": "Specify the local storage key",
"type": "string",
"value": "\"session-storage-key\"",
"isFunction": false,
"isFunctionDeclaration": false,
"constant": false,
"reactive": true
},
{
"name": "value",
"kind": "let",
"description": "Provide a value to persist",
"type": "any",
"value": "\"\"",
"isFunction": false,
"isFunctionDeclaration": false,
"constant": false,
"reactive": true
},
{
"name": "clearItem",
"kind": "function",
"description": "Remove the persisted key value from the browser's local storage",
"type": "() => void",
"value": "() => { storage.removeItem(key); }",
"isFunction": true,
"isFunctionDeclaration": true,
"constant": false,
"reactive": false
},
{
"name": "clearAll",
"kind": "function",
"description": "Clear all key values from the browser's local storage",
"type": "() => void",
"value": "() => { storage.clear(); }",
"isFunction": true,
"isFunctionDeclaration": true,
"constant": false,
"reactive": false
}
],
"moduleExports": [],
"slots": [],
"events": [
{ "type": "forwarded", "name": "save", "element": "WebStorage" },
{ "type": "forwarded", "name": "update", "element": "WebStorage" },
{ "type": "forwarded", "name": "updateKey", "element": "WebStorage" }
],
"typedefs": []
},
{ {
"moduleName": "SideNav", "moduleName": "SideNav",
"filePath": "src/UIShell/SideNav/SideNav.svelte", "filePath": "src/UIShell/SideNav/SideNav.svelte",
@ -13838,6 +13893,83 @@
], ],
"typedefs": [], "typedefs": [],
"rest_props": { "type": "Element", "name": "ul" } "rest_props": { "type": "Element", "name": "ul" }
},
{
"moduleName": "WebStorage",
"filePath": "src/LocalStorage/WebStorage.svelte",
"props": [
{
"name": "key",
"kind": "let",
"description": "Specify the local storage key",
"type": "string",
"value": "\"storage-key\"",
"isFunction": false,
"isFunctionDeclaration": false,
"constant": false,
"reactive": false
},
{
"name": "value",
"kind": "let",
"description": "Provide a value to persist",
"type": "any",
"value": "\"\"",
"isFunction": false,
"isFunctionDeclaration": false,
"constant": false,
"reactive": true
},
{
"name": "storage",
"kind": "let",
"description": "Select WebStorage to use",
"type": "\"local\"|\"session\"",
"value": "\"local\"",
"isFunction": false,
"isFunctionDeclaration": false,
"constant": false,
"reactive": false
},
{
"name": "clearItem",
"kind": "function",
"description": "Remove the persisted key value from the browser's selected WebStorage",
"type": "() => void",
"value": "() => { webStorage.removeItem(key); }",
"isFunction": true,
"isFunctionDeclaration": true,
"constant": false,
"reactive": false
},
{
"name": "clearAll",
"kind": "function",
"description": "Clear all key values from the browser's selected WebStorage",
"type": "() => void",
"value": "() => { webStorage.clear(); }",
"isFunction": true,
"isFunctionDeclaration": true,
"constant": false,
"reactive": false
}
],
"moduleExports": [],
"slots": [],
"events": [
{ "type": "dispatched", "name": "save", "detail": "null" },
{
"type": "dispatched",
"name": "updateKey",
"detail": "{ prevKey: any; key: any; }"
},
{
"type": "dispatched",
"name": "update",
"detail": "{ prevValue: any; value: any; }"
}
],
"typedefs": []
} }
] ]
} }

View file

@ -0,0 +1,23 @@
<script>
import Preview from "../../components/Preview.svelte";
</script>
This utility component wraps the [Window.sessionStorage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) and is useful for persisting ephemeral data (e.g., color theme) at the browser level for the duration of the current tab session.
### Reactive example
In the example below, toggle the switch and reload the page. The updated theme should be persisted locally.
<FileSource src="/framed/LocalStorage/SessionStorage" />
### Clear item, clear all
Use the `bind:this` directive to access the `clearItem` and `clearAll` methods.
Invoking `clearItem` will remove the persisted key value from the browser's session storage.
Invoking `clearAll` will remove all key values.
In the following example, toggle the switch and reload the page. Then, click the "Clear storage" button. Refresh the page; the theme should be reset to the untoggled state.
<FileSource src="/framed/LocalStorage/SessionStorageClear" />

View file

@ -0,0 +1,24 @@
<script>
import Preview from "../../components/Preview.svelte";
</script>
This utility component wraps the [Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API) and is useful for persisting ephemeral data (e.g., color theme) at the browser level
either in localStorage or sessionStorage.
### Reactive example
In the example below, toggle the switch and reload the page. The updated theme should be persisted locally.
<FileSource src="/framed/LocalStorage/WebStorage" />
### Clear item, clear all
Use the `bind:this` directive to access the `clearItem` and `clearAll` methods.
Invoking `clearItem` will remove the persisted key value from the browser's session storage.
Invoking `clearAll` will remove all key values.
In the following example, toggle the switch and reload the page. Then, click the "Clear storage" button. Refresh the page; the theme should be reset to the untoggled state.
<FileSource src="/framed/LocalStorage/WebStorageClear" />

View file

@ -0,0 +1,27 @@
<script>
import { SessionStorage, Toggle } from "carbon-components-svelte";
let toggled = false;
let events = [];
$: document.documentElement.setAttribute("theme", toggled ? "g100" : "white");
</script>
<SessionStorage
key="dark-mode"
bind:value="{toggled}"
on:save="{() => {
events = [...events, { event: 'on:save' }];
}}"
on:update="{({ detail }) => {
events = [...events, { event: 'on:update', detail }];
}}"
/>
<Toggle size="sm" labelText="Dark mode" bind:toggled />
<br />
<pre>
{JSON.stringify(events, null, 2)}
</pre>

View file

@ -0,0 +1,17 @@
<script>
import { SessionStorage, Toggle, Button } from "carbon-components-svelte";
let storage;
let toggled = false;
$: document.documentElement.setAttribute("theme", toggled ? "g100" : "white");
</script>
<SessionStorage bind:this="{storage}" bind:value="{toggled}" />
<Toggle size="sm" labelText="Dark mode" bind:toggled />
<br />
<br />
<Button size="small" on:click="{storage.clearAll}">Clear storage</Button>

View file

@ -0,0 +1,28 @@
<script>
import { WebStorage, Toggle } from "carbon-components-svelte";
let toggled = false;
let events = [];
$: document.documentElement.setAttribute("theme", toggled ? "g100" : "white");
</script>
<WebStorage
key="dark-mode"
bind:value="{toggled}"
storage="local"
on:save="{() => {
events = [...events, { event: 'on:save' }];
}}"
on:update="{({ detail }) => {
events = [...events, { event: 'on:update', detail }];
}}"
/>
<Toggle size="sm" labelText="Dark mode" bind:toggled />
<br />
<pre>
{JSON.stringify(events, null, 2)}
</pre>

View file

@ -0,0 +1,17 @@
<script>
import { WebStorage, Toggle, Button } from "carbon-components-svelte";
let storage;
let toggled = false;
$: document.documentElement.setAttribute("theme", toggled ? "g100" : "white");
</script>
<WebStorage bind:this="{storage}" bind:value="{toggled}" storage="local" />
<Toggle size="sm" labelText="Dark mode" bind:toggled />
<br />
<br />
<Button size="small" on:click="{storage.clearAll}">Clear storage</Button>

View file

@ -1,8 +1,5 @@
<script> <script>
/** import WebStorage from "./WebStorage.svelte";
* @event {null} save
* @event {{ prevValue: any; value: any; }} update
*/
/** /**
* Specify the local storage key * Specify the local storage key
@ -15,12 +12,15 @@
*/ */
export let value = ""; export let value = "";
/** Obtain a reference to the WebStorage element */
let storage = null;
/** /**
* Remove the persisted key value from the browser's local storage * Remove the persisted key value from the browser's local storage
* @type {() => void} * @type {() => void}
*/ */
export function clearItem() { export function clearItem() {
localStorage.removeItem(key); storage.removeItem(key);
} }
/** /**
@ -28,44 +28,16 @@
* @type {() => void} * @type {() => void}
*/ */
export function clearAll() { export function clearAll() {
localStorage.clear(); storage.clear();
} }
import { onMount, afterUpdate, createEventDispatcher } from "svelte";
const dispatch = createEventDispatcher();
let prevValue = value;
function setItem() {
if (typeof value === "object") {
localStorage.setItem(key, JSON.stringify(value));
} else {
localStorage.setItem(key, value);
}
}
onMount(() => {
const item = localStorage.getItem(key);
if (item != null) {
try {
value = JSON.parse(item);
} catch (e) {
value = item;
}
} else {
setItem(value);
dispatch("save");
}
});
afterUpdate(() => {
if (prevValue !== value) {
setItem(value);
dispatch("update", { prevValue, value });
}
prevValue = value;
});
</script> </script>
<WebStorage
bind:this="{storage}"
bind:key
bind:value
storage="local"
on:save
on:update
on:updateKey
/>

View file

@ -0,0 +1,43 @@
<script>
import WebStorage from "./WebStorage.svelte";
/**
* Specify the local storage key
*/
export let key = "session-storage-key";
/**
* Provide a value to persist
* @type {any}
*/
export let value = "";
/** Obtain a reference to the WebStorage element */
let storage = null;
/**
* Remove the persisted key value from the browser's local storage
* @type {() => void}
*/
export function clearItem() {
storage.removeItem(key);
}
/**
* Clear all key values from the browser's local storage
* @type {() => void}
*/
export function clearAll() {
storage.clear();
}
</script>
<WebStorage
bind:this="{storage}"
bind:key
bind:value
storage="session"
on:save
on:update
on:updateKey
/>

View file

@ -0,0 +1,90 @@
<script>
/**
* @event {null} save
* @event {{ prevKey: any; key: any; }} updateKey
* @event {{ prevValue: any; value: any; }} update
*/
/**
* Specify the local storage key
*/
export let key = "storage-key";
/**
* Provide a value to persist
* @type {any}
*/
export let value = "";
/**
* Select WebStorage to use
* @type {"local"|"session"}
*/
export let storage = "local";
$: webStorage = storage === "session" ? sessionStorage : localStorage;
/**
* Remove the persisted key value from the browser's selected WebStorage
* @type {() => void}
*/
export function clearItem() {
webStorage.removeItem(key);
}
/**
* Clear all key values from the browser's selected WebStorage
* @type {() => void}
*/
export function clearAll() {
webStorage.clear();
}
import { onMount, afterUpdate, createEventDispatcher } from "svelte";
const dispatch = createEventDispatcher();
let prevKey = key;
let prevValue = value;
function setItem() {
if (typeof value === "object") {
webStorage.setItem(key, JSON.stringify(value));
} else {
webStorage.setItem(key, value);
}
}
function init() {
const item = webStorage.getItem(key);
if (item != null) {
try {
value = JSON.parse(item);
} catch (e) {
value = item;
}
} else {
setItem(value);
dispatch("save");
}
}
onMount(() => {
init();
});
afterUpdate(() => {
if (prevKey !== key) {
init();
dispatch("updateKey", { prevKey, key });
prevKey = key;
}
if (prevValue !== value) {
setItem(value);
dispatch("update", { prevValue, value });
}
prevValue = value;
});
</script>

View file

@ -1 +1,3 @@
export { default as LocalStorage } from "./LocalStorage.svelte"; export { default as LocalStorage } from "./LocalStorage.svelte";
export { default as SessionStorage } from "./SessionStorage.svelte";
export { default as WebStorage } from "./WebStorage.svelte";

View file

@ -68,7 +68,7 @@ export {
} from "./ListBox"; } from "./ListBox";
export { ListItem } from "./ListItem"; export { ListItem } from "./ListItem";
export { Loading } from "./Loading"; export { Loading } from "./Loading";
export { LocalStorage } from "./LocalStorage"; export { LocalStorage, SessionStorage, WebStorage } from "./LocalStorage";
export { MultiSelect } from "./MultiSelect"; export { MultiSelect } from "./MultiSelect";
export { Modal } from "./Modal"; export { Modal } from "./Modal";
export { export {

View file

@ -18,8 +18,9 @@ export interface LocalStorageProps {
export default class LocalStorage extends SvelteComponentTyped< export default class LocalStorage extends SvelteComponentTyped<
LocalStorageProps, LocalStorageProps,
{ {
save: CustomEvent<null>; save: WindowEventMap["save"];
update: CustomEvent<{ prevValue: any; value: any }>; update: WindowEventMap["update"];
updateKey: WindowEventMap["updateKey"];
}, },
{} {}
> { > {

View file

@ -0,0 +1,36 @@
/// <reference types="svelte" />
import { SvelteComponentTyped } from "svelte";
export interface SessionStorageProps {
/**
* Specify the local storage key
* @default "session-storage-key"
*/
key?: string;
/**
* Provide a value to persist
* @default ""
*/
value?: any;
}
export default class SessionStorage extends SvelteComponentTyped<
SessionStorageProps,
{
save: WindowEventMap["save"];
update: WindowEventMap["update"];
updateKey: WindowEventMap["updateKey"];
},
{}
> {
/**
* Remove the persisted key value from the browser's local storage
*/
clearItem: () => void;
/**
* Clear all key values from the browser's local storage
*/
clearAll: () => void;
}

View file

@ -0,0 +1,42 @@
/// <reference types="svelte" />
import { SvelteComponentTyped } from "svelte";
export interface WebStorageProps {
/**
* Specify the local storage key
* @default "storage-key"
*/
key?: string;
/**
* Provide a value to persist
* @default ""
*/
value?: any;
/**
* Select WebStorage to use
* @default "local"
*/
storage?: "local" | "session";
}
export default class WebStorage extends SvelteComponentTyped<
WebStorageProps,
{
save: CustomEvent<null>;
updateKey: CustomEvent<{ prevKey: any; key: any }>;
update: CustomEvent<{ prevValue: any; value: any }>;
},
{}
> {
/**
* Remove the persisted key value from the browser's selected WebStorage
*/
clearItem: () => void;
/**
* Clear all key values from the browser's selected WebStorage
*/
clearAll: () => void;
}

2
types/index.d.ts vendored
View file

@ -75,6 +75,8 @@ export { default as ListBoxSelection } from "./ListBox/ListBoxSelection.svelte";
export { default as ListItem } from "./ListItem/ListItem.svelte"; export { default as ListItem } from "./ListItem/ListItem.svelte";
export { default as Loading } from "./Loading/Loading.svelte"; export { default as Loading } from "./Loading/Loading.svelte";
export { default as LocalStorage } from "./LocalStorage/LocalStorage.svelte"; export { default as LocalStorage } from "./LocalStorage/LocalStorage.svelte";
export { default as SessionStorage } from "./LocalStorage/SessionStorage.svelte";
export { default as WebStorage } from "./LocalStorage/WebStorage.svelte";
export { default as MultiSelect } from "./MultiSelect/MultiSelect.svelte"; export { default as MultiSelect } from "./MultiSelect/MultiSelect.svelte";
export { default as Modal } from "./Modal/Modal.svelte"; export { default as Modal } from "./Modal/Modal.svelte";
export { default as ToastNotification } from "./Notification/ToastNotification.svelte"; export { default as ToastNotification } from "./Notification/ToastNotification.svelte";