diff --git a/COMPONENT_INDEX.md b/COMPONENT_INDEX.md index 082c9066..53442b4e 100644 --- a/COMPONENT_INDEX.md +++ b/COMPONENT_INDEX.md @@ -1,6 +1,6 @@ # Component Index -> 171 components exported from carbon-components-svelte@0.62.2. +> 173 components exported from carbon-components-svelte@0.62.2. ## Components @@ -116,6 +116,7 @@ - [`SelectItemGroup`](#selectitemgroup) - [`SelectSkeleton`](#selectskeleton) - [`SelectableTile`](#selectabletile) +- [`SessionStorage`](#sessionstorage) - [`SideNav`](#sidenav) - [`SideNavDivider`](#sidenavdivider) - [`SideNavItems`](#sidenavitems) @@ -175,6 +176,7 @@ - [`TreeView`](#treeview) - [`Truncate`](#truncate) - [`UnorderedList`](#unorderedlist) +- [`WebStorage`](#webstorage) --- @@ -2240,12 +2242,12 @@ None. ### Props -| Prop name | Kind | Reactive | Type | Default value | Description | -| :-------- | :-------------------- | :------- | :---------------------- | ---------------------------------------------------- | --------------------------------------------------------------- | -| value | let | Yes | any | "" | Provide a value to persist | -| key | let | No | string | "local-storage-key" | Specify the local storage key | -| clearItem | function | No | () => void | () => { localStorage.removeItem(key); } | Remove the persisted key value from the browser's local storage | -| clearAll | function | No | () => void | () => { localStorage.clear(); } | Clear all key values from the browser's local storage | +| Prop name | Kind | Reactive | Type | Default value | Description | +| :-------- | :-------------------- | :------- | :---------------------- | ----------------------------------------------- | --------------------------------------------------------------- | +| value | let | Yes | any | "" | Provide a value to persist | +| key | let | Yes | string | "local-storage-key" | Specify the local storage key | +| clearItem | function | No | () => void | () => { storage.removeItem(key); } | Remove the persisted key value from the browser's local storage | +| clearAll | function | No | () => void | () => { storage.clear(); } | Clear all key values from the browser's local storage | ### Slots @@ -2253,10 +2255,11 @@ None. ### Events -| Event name | Type | Detail | -| :--------- | :--------- | :------------------------------------------- | -| save | dispatched | null | -| update | dispatched | { prevValue: any; value: any; } | +| Event name | Type | Detail | +| :--------- | :-------- | :----- | +| save | forwarded | -- | +| update | forwarded | -- | +| updateKey | forwarded | -- | ## `Modal` @@ -3348,6 +3351,29 @@ None. | mouseleave | forwarded | -- | | keydown | forwarded | -- | +## `SessionStorage` + +### Props + +| Prop name | Kind | Reactive | Type | Default value | Description | +| :-------- | :-------------------- | :------- | :---------------------- | ----------------------------------------------- | --------------------------------------------------------------- | +| value | let | Yes | any | "" | Provide a value to persist | +| key | let | Yes | string | "session-storage-key" | Specify the local storage key | +| clearItem | function | No | () => void | () => { storage.removeItem(key); } | Remove the persisted key value from the browser's local storage | +| clearAll | function | No | () => void | () => { storage.clear(); } | Clear all key values from the browser's local storage | + +### Slots + +None. + +### Events + +| Event name | Type | Detail | +| :--------- | :-------- | :----- | +| save | forwarded | -- | +| update | forwarded | -- | +| updateKey | forwarded | -- | + ## `SideNav` ### Props @@ -4847,3 +4873,27 @@ None. | mouseover | forwarded | -- | | mouseenter | forwarded | -- | | mouseleave | forwarded | -- | + +## `WebStorage` + +### Props + +| Prop name | Kind | Reactive | Type | Default value | Description | +| :-------- | :-------------------- | :------- | :---------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------- | +| value | let | Yes | any | "" | Provide a value to persist | +| key | let | No | string | "storage-key" | Specify the local storage key | +| storage | let | No | "local"|"session" | "local" | Select WebStorage to use | +| clearItem | function | No | () => void | () => { webStorage.removeItem(key); } | Remove the persisted key value from the browser's selected WebStorage | +| clearAll | function | No | () => void | () => { webStorage.clear(); } | Clear all key values from the browser's selected WebStorage | + +### Slots + +None. + +### Events + +| Event name | Type | Detail | +| :--------- | :--------- | :------------------------------------------- | +| save | dispatched | null | +| updateKey | dispatched | { prevKey: any; key: any; } | +| update | dispatched | { prevValue: any; value: any; } | diff --git a/docs/src/COMPONENT_API.json b/docs/src/COMPONENT_API.json index eb7625f3..3cb4ad8d 100644 --- a/docs/src/COMPONENT_API.json +++ b/docs/src/COMPONENT_API.json @@ -1,5 +1,5 @@ { - "total": 171, + "total": 173, "components": [ { "moduleName": "Accordion", @@ -5995,7 +5995,7 @@ "isFunction": false, "isFunctionDeclaration": false, "constant": false, - "reactive": false + "reactive": true }, { "name": "value", @@ -6013,7 +6013,7 @@ "kind": "function", "description": "Remove the persisted key value from the browser's local storage", "type": "() => void", - "value": "() => { localStorage.removeItem(key); }", + "value": "() => { storage.removeItem(key); }", "isFunction": true, "isFunctionDeclaration": true, "constant": false, @@ -6024,7 +6024,7 @@ "kind": "function", "description": "Clear all key values from the browser's local storage", "type": "() => void", - "value": "() => { localStorage.clear(); }", + "value": "() => { storage.clear(); }", "isFunction": true, "isFunctionDeclaration": true, "constant": false, @@ -6034,12 +6034,9 @@ "moduleExports": [], "slots": [], "events": [ - { "type": "dispatched", "name": "save", "detail": "null" }, - { - "type": "dispatched", - "name": "update", - "detail": "{ prevValue: any; value: any; }" - } + { "type": "forwarded", "name": "save", "element": "WebStorage" }, + { "type": "forwarded", "name": "update", "element": "WebStorage" }, + { "type": "forwarded", "name": "updateKey", "element": "WebStorage" } ], "typedefs": [] }, @@ -9950,6 +9947,64 @@ "typedefs": [], "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", "filePath": "src/UIShell/SideNav/SideNav.svelte", @@ -13838,6 +13893,83 @@ ], "typedefs": [], "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": [] } ] } diff --git a/docs/src/pages/components/SessionStorage.svx b/docs/src/pages/components/SessionStorage.svx new file mode 100644 index 00000000..b92748e8 --- /dev/null +++ b/docs/src/pages/components/SessionStorage.svx @@ -0,0 +1,23 @@ + + +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. + + + +### 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. + + diff --git a/docs/src/pages/components/WebStorage.svx b/docs/src/pages/components/WebStorage.svx new file mode 100644 index 00000000..e350169a --- /dev/null +++ b/docs/src/pages/components/WebStorage.svx @@ -0,0 +1,24 @@ + + +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. + + + +### 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. + + diff --git a/docs/src/pages/framed/LocalStorage/SessionStorage.svelte b/docs/src/pages/framed/LocalStorage/SessionStorage.svelte new file mode 100644 index 00000000..7a1dcc93 --- /dev/null +++ b/docs/src/pages/framed/LocalStorage/SessionStorage.svelte @@ -0,0 +1,27 @@ + + + + + + +
+ +
+  {JSON.stringify(events, null, 2)}
+
diff --git a/docs/src/pages/framed/LocalStorage/SessionStorageClear.svelte b/docs/src/pages/framed/LocalStorage/SessionStorageClear.svelte new file mode 100644 index 00000000..af273ac7 --- /dev/null +++ b/docs/src/pages/framed/LocalStorage/SessionStorageClear.svelte @@ -0,0 +1,17 @@ + + + + + + +
+
+ + diff --git a/docs/src/pages/framed/LocalStorage/WebStorage.svelte b/docs/src/pages/framed/LocalStorage/WebStorage.svelte new file mode 100644 index 00000000..304461df --- /dev/null +++ b/docs/src/pages/framed/LocalStorage/WebStorage.svelte @@ -0,0 +1,28 @@ + + + + + + +
+ +
+  {JSON.stringify(events, null, 2)}
+
diff --git a/docs/src/pages/framed/LocalStorage/WebStorageClear.svelte b/docs/src/pages/framed/LocalStorage/WebStorageClear.svelte new file mode 100644 index 00000000..17fd75a9 --- /dev/null +++ b/docs/src/pages/framed/LocalStorage/WebStorageClear.svelte @@ -0,0 +1,17 @@ + + + + + + +
+
+ + diff --git a/src/LocalStorage/LocalStorage.svelte b/src/LocalStorage/LocalStorage.svelte index 823d8894..93415f33 100644 --- a/src/LocalStorage/LocalStorage.svelte +++ b/src/LocalStorage/LocalStorage.svelte @@ -1,8 +1,5 @@ + + diff --git a/src/LocalStorage/SessionStorage.svelte b/src/LocalStorage/SessionStorage.svelte new file mode 100644 index 00000000..adb343b3 --- /dev/null +++ b/src/LocalStorage/SessionStorage.svelte @@ -0,0 +1,43 @@ + + + diff --git a/src/LocalStorage/WebStorage.svelte b/src/LocalStorage/WebStorage.svelte new file mode 100644 index 00000000..2560a616 --- /dev/null +++ b/src/LocalStorage/WebStorage.svelte @@ -0,0 +1,90 @@ + diff --git a/src/LocalStorage/index.js b/src/LocalStorage/index.js index 5ea56755..e7e9d815 100644 --- a/src/LocalStorage/index.js +++ b/src/LocalStorage/index.js @@ -1 +1,3 @@ export { default as LocalStorage } from "./LocalStorage.svelte"; +export { default as SessionStorage } from "./SessionStorage.svelte"; +export { default as WebStorage } from "./WebStorage.svelte"; diff --git a/src/index.js b/src/index.js index d6f040b3..3e3514c1 100644 --- a/src/index.js +++ b/src/index.js @@ -68,7 +68,7 @@ export { } from "./ListBox"; export { ListItem } from "./ListItem"; export { Loading } from "./Loading"; -export { LocalStorage } from "./LocalStorage"; +export { LocalStorage, SessionStorage, WebStorage } from "./LocalStorage"; export { MultiSelect } from "./MultiSelect"; export { Modal } from "./Modal"; export { diff --git a/types/LocalStorage/LocalStorage.svelte.d.ts b/types/LocalStorage/LocalStorage.svelte.d.ts index 03fdb83b..a1638efc 100644 --- a/types/LocalStorage/LocalStorage.svelte.d.ts +++ b/types/LocalStorage/LocalStorage.svelte.d.ts @@ -18,8 +18,9 @@ export interface LocalStorageProps { export default class LocalStorage extends SvelteComponentTyped< LocalStorageProps, { - save: CustomEvent; - update: CustomEvent<{ prevValue: any; value: any }>; + save: WindowEventMap["save"]; + update: WindowEventMap["update"]; + updateKey: WindowEventMap["updateKey"]; }, {} > { diff --git a/types/LocalStorage/SessionStorage.svelte.d.ts b/types/LocalStorage/SessionStorage.svelte.d.ts new file mode 100644 index 00000000..20e8509b --- /dev/null +++ b/types/LocalStorage/SessionStorage.svelte.d.ts @@ -0,0 +1,36 @@ +/// +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; +} diff --git a/types/LocalStorage/WebStorage.svelte.d.ts b/types/LocalStorage/WebStorage.svelte.d.ts new file mode 100644 index 00000000..0ca6d41b --- /dev/null +++ b/types/LocalStorage/WebStorage.svelte.d.ts @@ -0,0 +1,42 @@ +/// +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; + 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; +} diff --git a/types/index.d.ts b/types/index.d.ts index 2958b98a..341292b0 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -75,6 +75,8 @@ export { default as ListBoxSelection } from "./ListBox/ListBoxSelection.svelte"; export { default as ListItem } from "./ListItem/ListItem.svelte"; export { default as Loading } from "./Loading/Loading.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 Modal } from "./Modal/Modal.svelte"; export { default as ToastNotification } from "./Notification/ToastNotification.svelte";