diff --git a/docs/content/docs/core/async-state/index.md b/docs/content/docs/core/async-state/index.md index fa4c089..57c1595 100644 --- a/docs/content/docs/core/async-state/index.md +++ b/docs/content/docs/core/async-state/index.md @@ -8,19 +8,17 @@ A reactive state that handles the loading and error states of a promise. ## Usage -```svelte - +const recipe = asyncState(() => { + const result = fetch(`https://dummyjson.com/recipes/1`); + + return result.json(); +}, null ); ``` -## Examples +### Examples A basic example where you wait for the value to be resolved. @@ -28,11 +26,11 @@ A basic example where you wait for the value to be resolved. {#if recipe.isLoading} @@ -52,8 +50,9 @@ Note that you have to set `immediate` to `false` if you are using a function tha let id = $state(1); const recipe = asyncState((id) => { - return fetch(`https://dummyjson.com/recipes/${id}`) - .then((res) => res.json()); + const result = fetch(`https://dummyjson.com/recipes/${id}`); + + return result.json(); }, null, { immediate: false }); $effect(() => { diff --git a/docs/content/docs/core/auto-reset-state/index.md b/docs/content/docs/core/auto-reset-state/index.md index 5304851..8b4040b 100644 --- a/docs/content/docs/core/auto-reset-state/index.md +++ b/docs/content/docs/core/auto-reset-state/index.md @@ -8,15 +8,13 @@ A state that automatically resets to the default value after a delay. ## Usage -```svelte - +function changeMessage() { + // Changes to the default value after 3 seconds + message.current = 'This is the new message'; +} ``` diff --git a/docs/content/docs/core/create-eye-dropper/index.md b/docs/content/docs/core/create-eye-dropper/index.md index e8752d6..2ba8d3a 100644 --- a/docs/content/docs/core/create-eye-dropper/index.md +++ b/docs/content/docs/core/create-eye-dropper/index.md @@ -10,10 +10,8 @@ Using this tool, users can sample colors from their screens, including outside o ## Usage -```svelte - +const eyeDropper = createEyeDropper(); ``` diff --git a/docs/content/docs/core/create-file-dialog/index.md b/docs/content/docs/core/create-file-dialog/index.md index e657b73..259bbb0 100644 --- a/docs/content/docs/core/create-file-dialog/index.md +++ b/docs/content/docs/core/create-file-dialog/index.md @@ -8,32 +8,30 @@ Creates a file dialog to interact with programatically. ## Usage -```svelte - +const dialog = createFileDialog(); ``` ### Examples -```svelte - +```ts +import { createFileDialog } from '@sv-use/core'; + +const dialog = createFileDialog({ + accept: 'image/*', + multiple: true, + onChange(files) { + console.log($state.snapshot(files)); + }, + onCancel() { + console.log('cancelled'); + } +}); +``` +```svelte diff --git a/docs/content/docs/core/create-share/index.md b/docs/content/docs/core/create-share/index.md index ba4ae66..8611ef0 100644 --- a/docs/content/docs/core/create-share/index.md +++ b/docs/content/docs/core/create-share/index.md @@ -10,12 +10,12 @@ URLs, or files. The available share targets depend on the device, but might include the clipboard, contacts and email applications, websites, Bluetooth, etc. -## Usage - > [!IMPORTANT] > To prevent abuse, it must be triggered off a UI event like a button click and > cannot be launched at arbitrary points by a script. +## Usage + ```js import { createShare } from '@sv-use/core'; diff --git a/docs/content/docs/core/debounce/index.md b/docs/content/docs/core/debounce/index.md index 6b398a9..f53830c 100644 --- a/docs/content/docs/core/debounce/index.md +++ b/docs/content/docs/core/debounce/index.md @@ -11,11 +11,9 @@ Debounces the update of the value after a delay. > [!TIP] > If you'd rather have them combined in one variable, check out [debouncedState](/docs/core/debounced-state). -```svelte - +let search = $state(''); +const debouncedSearch = debounce(() => search); ``` diff --git a/docs/content/docs/core/debounced-state/index.md b/docs/content/docs/core/debounced-state/index.md index de10558..99027db 100644 --- a/docs/content/docs/core/debounced-state/index.md +++ b/docs/content/docs/core/debounced-state/index.md @@ -11,10 +11,8 @@ A reactive state that updates its value after a delay. > [!TIP] > If you'd rather have them separate, check out [debounce](/docs/core/debounce). -```svelte - +const search = debouncedState('', { delay: 1000 }); ``` diff --git a/docs/content/docs/core/default-state/index.md b/docs/content/docs/core/default-state/index.md index 44197a5..d9ae67d 100644 --- a/docs/content/docs/core/default-state/index.md +++ b/docs/content/docs/core/default-state/index.md @@ -13,14 +13,14 @@ A reactive state that falls back to `defaultValue` if set to `null` or `undefine > > This is to ensure that you can set a nullable value when changing the state without TS complaining. -```svelte - +// Set the message to the fallback message +message.current = null; ``` diff --git a/docs/content/docs/core/get-active-element/index.md b/docs/content/docs/core/get-active-element/index.md index 65d1af5..54f5c9b 100644 --- a/docs/content/docs/core/get-active-element/index.md +++ b/docs/content/docs/core/get-active-element/index.md @@ -8,10 +8,8 @@ Gets the current active element in the DOM. ## Usage -```svelte - +const activeElement = getActiveElement(); ``` diff --git a/docs/content/docs/core/get-battery/Demo.svelte b/docs/content/docs/core/get-battery/Demo.svelte deleted file mode 100644 index 57ccb26..0000000 --- a/docs/content/docs/core/get-battery/Demo.svelte +++ /dev/null @@ -1,7 +0,0 @@ - - -
{JSON.stringify(battery, null, 2)}
diff --git a/docs/content/docs/core/get-battery/index.md b/docs/content/docs/core/get-battery/index.md deleted file mode 100644 index 5c9dfb5..0000000 --- a/docs/content/docs/core/get-battery/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -category: sensors ---- - -# getBattery - -Provides information about the system's battery charge level and lets you be notified by events that are sent when the battery level or charging status change. - -## Usage - -```svelte - -``` diff --git a/docs/content/docs/core/get-clipboard-text/index.md b/docs/content/docs/core/get-clipboard-text/index.md index ad60bcb..011d344 100644 --- a/docs/content/docs/core/get-clipboard-text/index.md +++ b/docs/content/docs/core/get-clipboard-text/index.md @@ -10,15 +10,13 @@ Provides write (and optionally read) access to the text clipboard. Set `options.legacyCopy: true` to keep the ability to copy if the [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API) is not available. It will handle copy with [document.execCommand](https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand) as the fallback. -```svelte - +const clipboard = getClipboardText({ + allowRead: true, + legacyCopy: true +}); ``` ## Examples diff --git a/docs/content/docs/core/get-device-motion/index.md b/docs/content/docs/core/get-device-motion/index.md index 4d7f5ba..bcbfed8 100644 --- a/docs/content/docs/core/get-device-motion/index.md +++ b/docs/content/docs/core/get-device-motion/index.md @@ -9,10 +9,8 @@ rotation rate. ## Usage -```svelte - +const deviceMotion = getDeviceMotion(); ``` diff --git a/docs/content/docs/core/get-device-orientation/index.md b/docs/content/docs/core/get-device-orientation/index.md index 16d6042..0e477df 100644 --- a/docs/content/docs/core/get-device-orientation/index.md +++ b/docs/content/docs/core/get-device-orientation/index.md @@ -9,10 +9,8 @@ device running the web page. ## Usage -```svelte - +const deviceOrientation = getDeviceOrientation(); ``` diff --git a/docs/content/docs/core/get-device-pixel-ratio/index.md b/docs/content/docs/core/get-device-pixel-ratio/index.md index 0b486ff..ac3eb41 100644 --- a/docs/content/docs/core/get-device-pixel-ratio/index.md +++ b/docs/content/docs/core/get-device-pixel-ratio/index.md @@ -9,10 +9,8 @@ pixels for the current display device. ## Usage -```svelte - +const devicePixelRatio = getDevicePixelRatio(); ``` diff --git a/docs/content/docs/core/get-document-visibility/index.md b/docs/content/docs/core/get-document-visibility/index.md index 291ba0b..5be949a 100644 --- a/docs/content/docs/core/get-document-visibility/index.md +++ b/docs/content/docs/core/get-document-visibility/index.md @@ -11,10 +11,8 @@ minimized window, or is otherwise not visible to the user. ## Usage -```svelte - +const documentVisibility = getDocumentVisibility(); ``` diff --git a/docs/content/docs/core/get-fps/index.md b/docs/content/docs/core/get-fps/index.md index ddfa52d..0a6bf3e 100644 --- a/docs/content/docs/core/get-fps/index.md +++ b/docs/content/docs/core/get-fps/index.md @@ -8,10 +8,8 @@ Get the current frames per second of the device. ## Usage -```svelte - +const fps = getFps(); ``` diff --git a/docs/content/docs/core/get-geolocation/index.md b/docs/content/docs/core/get-geolocation/index.md index bea2337..65507fc 100644 --- a/docs/content/docs/core/get-geolocation/index.md +++ b/docs/content/docs/core/get-geolocation/index.md @@ -7,15 +7,14 @@ category: sensors It allows the user to provide their location to web applications if they so desire. -For privacy reasons, the user is asked for permission to report location -information. +> [!IMPORTANT] +> For privacy reasons, the user is asked for permission to report location +> information. ## Usage -```svelte - +const geolocation = getGeolocation(); ``` diff --git a/docs/content/docs/core/get-last-changed/index.md b/docs/content/docs/core/get-last-changed/index.md index f941944..651077c 100644 --- a/docs/content/docs/core/get-last-changed/index.md +++ b/docs/content/docs/core/get-last-changed/index.md @@ -8,11 +8,9 @@ Get the last time the reactive value changed. It is returned as a number in mill ## Usage -```svelte - +let value = $state(0); +const lastChanged = getLastChanged(() => value); ``` diff --git a/docs/content/docs/core/get-mouse-pressed/index.md b/docs/content/docs/core/get-mouse-pressed/index.md index 9e73c7f..9d9521a 100644 --- a/docs/content/docs/core/get-mouse-pressed/index.md +++ b/docs/content/docs/core/get-mouse-pressed/index.md @@ -8,10 +8,8 @@ Reactive values for mouse/touch/drag pressing state. ## Usage -```svelte - +const mousePressed = getMousePressed(); ``` diff --git a/docs/content/docs/core/get-mouse/index.md b/docs/content/docs/core/get-mouse/index.md index 7f34bc1..0be390e 100644 --- a/docs/content/docs/core/get-mouse/index.md +++ b/docs/content/docs/core/get-mouse/index.md @@ -8,10 +8,8 @@ Retrieves information about the mouse. ## Usage -```svelte - +const mouse = getMouse(); ``` diff --git a/docs/content/docs/core/get-network/index.md b/docs/content/docs/core/get-network/index.md index ae9ade2..90e16aa 100644 --- a/docs/content/docs/core/get-network/index.md +++ b/docs/content/docs/core/get-network/index.md @@ -9,10 +9,8 @@ the network. ## Usage -```svelte - +const network = getNetwork(); ``` diff --git a/docs/content/docs/core/get-permission/Demo.svelte b/docs/content/docs/core/get-permission/Demo.svelte index e67b435..e198c9e 100644 --- a/docs/content/docs/core/get-permission/Demo.svelte +++ b/docs/content/docs/core/get-permission/Demo.svelte @@ -1,10 +1,48 @@
- Camera status - 
{JSON.stringify(permission, null, 2)}
+ 
{JSON.stringify(code, null, 2)}
diff --git a/docs/content/docs/core/get-permission/index.md b/docs/content/docs/core/get-permission/index.md index 9a50601..5fa015e 100644 --- a/docs/content/docs/core/get-permission/index.md +++ b/docs/content/docs/core/get-permission/index.md @@ -4,14 +4,25 @@ category: browser # getPermission -Retrieves the status of a given permission. +Reactive [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API). +It provides a consistent programmatic way to query the status of API +permissions attributed to the current context, such as a web page or worker. + +For example, it can be used to determine if permission to access a particular +feature or API has been granted, denied, or requires specific user permission. ## Usage -```svelte - +// Use the permission +if (microphoneAccess.current === "granted") { + // We have access to the microphone here +} ``` diff --git a/docs/content/docs/core/get-previous/index.md b/docs/content/docs/core/get-previous/index.md index 29e1b35..ea6e66d 100644 --- a/docs/content/docs/core/get-previous/index.md +++ b/docs/content/docs/core/get-previous/index.md @@ -6,8 +6,6 @@ category: reactivity A reactive state of a given state's previous value. -It is set to `undefined` until the first change if `initial` is not set. - ## Usage > [!TIP] @@ -15,11 +13,16 @@ It is set to `undefined` until the first change if `initial` is not set. > > It supplies the previous value in the callback. -```svelte - +// With initial value +let previousCounter = getPrevious(() => counter, -1); ``` diff --git a/docs/content/docs/core/get-scrollbar-width/index.md b/docs/content/docs/core/get-scrollbar-width/index.md index e292b08..49d79fd 100644 --- a/docs/content/docs/core/get-scrollbar-width/index.md +++ b/docs/content/docs/core/get-scrollbar-width/index.md @@ -6,8 +6,9 @@ category: sensors Gets the scrollbar width of an element. -This works in browsers that do not use absolute positioning for scrollbars, -such as Chrome on desktop. +> [!NOTE] +> This works in browsers that do not use absolute positioning for scrollbars, +> such as Chrome on desktop. ## Usage diff --git a/docs/content/docs/core/get-text-direction/index.md b/docs/content/docs/core/get-text-direction/index.md index b341303..bebaa46 100644 --- a/docs/content/docs/core/get-text-direction/index.md +++ b/docs/content/docs/core/get-text-direction/index.md @@ -7,3 +7,18 @@ category: browser Indicates the text writing directionality of the content of an element. You can set a value to change the `dir` property on the element. + +## Usage + +```svelte + + +

+ i'm a paragraph in english +

+``` diff --git a/docs/content/docs/core/handle-event-listener/Demo.svelte b/docs/content/docs/core/handle-event-listener/Demo.svelte index 67e5d0c..0b58d91 100644 --- a/docs/content/docs/core/handle-event-listener/Demo.svelte +++ b/docs/content/docs/core/handle-event-listener/Demo.svelte @@ -1,21 +1,13 @@
diff --git a/docs/content/docs/core/handle-event-listener/index.md b/docs/content/docs/core/handle-event-listener/index.md index 723b78b..e29debb 100644 --- a/docs/content/docs/core/handle-event-listener/index.md +++ b/docs/content/docs/core/handle-event-listener/index.md @@ -8,12 +8,10 @@ Convenience wrapper for event listeners. ## Usage -```svelte - +handleEventListener('click', () => { + console.log('clicked') +}); ``` diff --git a/docs/content/docs/core/handle-wake-lock/index.md b/docs/content/docs/core/handle-wake-lock/index.md index 0fc7776..160c172 100644 --- a/docs/content/docs/core/handle-wake-lock/index.md +++ b/docs/content/docs/core/handle-wake-lock/index.md @@ -14,18 +14,16 @@ You may read more about the [Screen Wake Lock API](https://developer.mozilla.org > Since it uses `$effect` internally, you must either call `handleWakeLock` in > the component initialization lifecycle or call it inside `$effect.root`. -```svelte - +// When you don't need it anymore +await wakeLock.release(); ``` diff --git a/docs/content/docs/core/has-left-page/index.md b/docs/content/docs/core/has-left-page/index.md index 2a37441..b56712d 100644 --- a/docs/content/docs/core/has-left-page/index.md +++ b/docs/content/docs/core/has-left-page/index.md @@ -8,10 +8,8 @@ Reactive value that tracks whether the mouse has left the page or not. ## Usage -```svelte - +const hasLeft = hasLeftPage(); ``` diff --git a/docs/content/docs/core/history-state/index.md b/docs/content/docs/core/history-state/index.md index 61dc6d9..3001a67 100644 --- a/docs/content/docs/core/history-state/index.md +++ b/docs/content/docs/core/history-state/index.md @@ -12,12 +12,10 @@ capabilities as well as access to the histories. > [!TIP] > If you prefer to have them separate, check out [trackHistory](/docs/core/track-history). -```svelte - +const counter = historyState(0); ``` ## Examples diff --git a/docs/content/docs/core/is-window-focused/index.md b/docs/content/docs/core/is-window-focused/index.md index be03e01..9652224 100644 --- a/docs/content/docs/core/is-window-focused/index.md +++ b/docs/content/docs/core/is-window-focused/index.md @@ -8,10 +8,8 @@ Tracks whether the window is focused or not. ## Usage -```svelte - +const isFocused = isWindowFocused(); ``` diff --git a/docs/content/docs/core/observe-performance/index.md b/docs/content/docs/core/observe-performance/index.md index f2fcee6..e01288d 100644 --- a/docs/content/docs/core/observe-performance/index.md +++ b/docs/content/docs/core/observe-performance/index.md @@ -11,12 +11,10 @@ the entry types that have been registered. ## Usage -```svelte - +observePerformance((list) => { + console.log(list.getEntries()); +}, { entryTypes: ['paint'] }); ``` diff --git a/docs/content/docs/core/track-history/index.md b/docs/content/docs/core/track-history/index.md index 1ad2a9f..1fc59c5 100644 --- a/docs/content/docs/core/track-history/index.md +++ b/docs/content/docs/core/track-history/index.md @@ -12,14 +12,12 @@ capabilities as well as access to the histories. > [!TIP] > If you prefer to have them combined, check out [historyState](/docs/core/history-state). -```svelte - +let counter = $state(0); +const counterHistory = trackHistory( + () => counter, + (v) => (counter = v) +); ``` diff --git a/docs/content/docs/core/watch/index.md b/docs/content/docs/core/watch/index.md index 54cd810..703c4ba 100644 --- a/docs/content/docs/core/watch/index.md +++ b/docs/content/docs/core/watch/index.md @@ -12,37 +12,49 @@ Provides the previous value(s) as well as the current one(s) as parameters in th You can watch changes on a single value : -```svelte - +watch(() => counter, (curr, prev) => { + console.log(`Went from ${prev} to ${curr}`); +}); ``` Or on multiple values by supplying an array : -```svelte - +watch( + [() => counter, () => search], + ([currCounter, currSearch], [prevCounter, prevSearch]) => { + // ... + } +); +``` + +You can return a function from `watch`, which will run immediately before it +re-runs, and before it is destroyed. + +```ts +import { watch } from '@sv-use/core'; + +let element = $state(); + +watch(() => element, (el) => { + const observer = new MutationObserver(callback); + observer!.observe(el, { attributes: true }); + + return () => observer.disconnect(); +}); ``` -### onMount +### Options : Immediate By default, the callback runs when the component is first mounted in the DOM, as well as when a dependency changes. @@ -50,14 +62,36 @@ as well as when a dependency changes. You might not want that and only run when a dependency changes. You can set this in the options. +```ts +import { watch } from '@sv-use/core'; + +let counter = $state(0); + +watch(() => counter, (curr, prev) => { + console.log(`Went from ${prev} to ${curr}`); +}, { immediate: false }); +``` + +### Options : Deep + +By default, the callback only re-runs when the object it reads changes, not +when a property inside it changes. + +You might also want to watch for deep changes, which you can set via the `deep` +option. + ```svelte + + ``` diff --git a/docs/content/docs/core/whenever/index.md b/docs/content/docs/core/whenever/index.md index 509b65f..8d5e29f 100644 --- a/docs/content/docs/core/whenever/index.md +++ b/docs/content/docs/core/whenever/index.md @@ -11,14 +11,30 @@ dependencies are truthy. ## Usage -```svelte - +whenever(() => isActive, () => { + console.log('Active now !'); +}); +``` + +You can return a function from `whenever`, which will run immediately before it +re-runs, and before it is destroyed. + +```ts +import { whenever } from '@sv-use/core'; + +let isActive = $state(false); +let counter = $state(0); + +whenever(() => isActive, () => { + const interval = setInterval(() => { + counter += 1; + }, 1000) + + return () => clearInterval(interval); +}); ``` diff --git a/docs/content/docs/guide/introduction.md b/docs/content/docs/guide/introduction.md index e1baaf0..2be7311 100644 --- a/docs/content/docs/guide/introduction.md +++ b/docs/content/docs/guide/introduction.md @@ -30,44 +30,3 @@ An example using a state that is persisted via local storage : counter : {counter.current} ``` - -## Best Practices - -### Cleanup - -Some utilities produce side-effects, such as invoking an event listener. By -default, they are automatically cleaned up in an `onDestroy` hook. - -However, this requires the function to be called in the component -initialization lifecycle. - -To opt out of this, every utility that produces a side-effect returns a cleanup -function that can be used to clean it manually. - -Here is an example using [handleEventListener](/docs/core/handle-event-listener) : - -```svelte - -``` - -And how to cleanup manually : - -```svelte - -``` diff --git a/docs/src/lib/utils/markdown.server.ts b/docs/src/lib/utils/markdown.server.ts index 8258461..a96dd5a 100644 --- a/docs/src/lib/utils/markdown.server.ts +++ b/docs/src/lib/utils/markdown.server.ts @@ -29,7 +29,17 @@ function extractDataFromMarkdown( async function convertMarkdownContentToHTML( content: string ): Promise, 'attributes'>> { - const { value, data } = await unified() + const { value, data } = await createProcessor().process(content); + + return { + ...extractDataFromHTML(value.toString()), + // Remove h1 from headings + headings: (data.headings as MarkdownHeading[]).slice(1) + }; +} + +function createProcessor() { + return unified() .use(remarkParse) .use(remarkHeadingId, { defaults: true, @@ -47,30 +57,16 @@ async function convertMarkdownContentToHTML( dark: 'one-dark-pro' } }) - .use(rehypeStringify) - .process(content); - - let html = value.toString(); - - const h1Regex = /(.*?)<\/h1>/; - const paragraphRegex = /

([\s\S]*?)<\/p>/; - - const title = html.match(h1Regex)?.at(2); - html = html.replace(h1Regex, ''); - - const paragraphs = []; - while (true) { - const h2Index = html.indexOf('(.*?)<\/h1>/; + const title = html.match(h1Regex)?.at(2); + + return { title, html: html.replace(h1Regex, '') }; +} + +function extractLedeFromHTML(html: string) { + const [lede, ...rest] = html.split(' { + return '( let { attributes, body } = extractDataFromMarkdown(content); if (typeDefinitionsPath) { - const typeDefinitions = await fs.readFile(typeDefinitionsPath, 'utf8'); + body = await injectTypeDefinitions(body, typeDefinitionsPath); + } - body += ` + const data = await convertMarkdownContentToHTML(body); + + return { attributes, ...data }; + } catch (error) { + throw new Error(`Error converting ${filePath} to HTML: ${(error as Error).message}`); + } +} + +async function injectTypeDefinitions(body: string, typeDefinitionsPath: string) { + const typeDefinitions = await fs.readFile(typeDefinitionsPath, 'utf8'); + + return ( + body + + ` ## Type Definitions

@@ -123,13 +151,6 @@ export async function convertMarkdownFileToHTML( \`\`\`typescript ${typeDefinitions}\`\`\` -
`; - } - - const data = await convertMarkdownContentToHTML(body); - - return { attributes, ...data }; - } catch (error) { - throw new Error(`Error converting ${filePath} to HTML: ${(error as Error).message}`); - } +` + ); } diff --git a/docs/src/routes/+layout.svelte b/docs/src/routes/+layout.svelte index cdbe477..dce6261 100644 --- a/docs/src/routes/+layout.svelte +++ b/docs/src/routes/+layout.svelte @@ -1,6 +1,5 @@ + +