27 |
28 | 
29 |
30 |
39 | 40 |
29 | 30 |
%sveltekit.body%
11 |
12 |
13 |
--------------------------------------------------------------------------------
/packages/runed/src/index.test.ts:
--------------------------------------------------------------------------------
1 | import { describe, expect, it } from "vitest";
2 |
3 | describe("sum test", () => {
4 | it("adds 1 + 2 to equal 3", () => {
5 | expect(1 + 2).toBe(3);
6 | });
7 | });
8 |
--------------------------------------------------------------------------------
/packages/runed/src/lib/index.ts:
--------------------------------------------------------------------------------
1 | export * from "./utilities/index.js";
2 | export type { MaybeGetter, Getter, Setter } from "./internal/types.js";
3 |
--------------------------------------------------------------------------------
/packages/runed/src/lib/internal/configurable-globals.ts:
--------------------------------------------------------------------------------
1 | import { BROWSER } from "esm-env";
2 |
3 | export type ConfigurableWindow = {
4 | /** Provide a custom `window` object to use in place of the global `window` object. */
5 | window?: typeof globalThis & Window;
6 | };
7 |
8 | export type ConfigurableDocument = {
9 | /** Provide a custom `document` object to use in place of the global `document` object. */
10 | document?: Document;
11 | };
12 |
13 | export type ConfigurableDocumentOrShadowRoot = {
14 | /*
15 | * Specify a custom `document` instance or a shadow root, e.g. working with iframes or in testing environments.
16 | */
17 | document?: DocumentOrShadowRoot;
18 | };
19 |
20 | export type ConfigurableNavigator = {
21 | /** Provide a custom `navigator` object to use in place of the global `navigator` object. */
22 | navigator?: Navigator;
23 | };
24 |
25 | export type ConfigurableLocation = {
26 | /** Provide a custom `location` object to use in place of the global `location` object. */
27 | location?: Location;
28 | };
29 |
30 | export const defaultWindow = BROWSER && typeof window !== "undefined" ? window : undefined;
31 | export const defaultDocument =
32 | BROWSER && typeof window !== "undefined" ? window.document : undefined;
33 | export const defaultNavigator =
34 | BROWSER && typeof window !== "undefined" ? window.navigator : undefined;
35 | export const defaultLocation =
36 | BROWSER && typeof window !== "undefined" ? window.location : undefined;
37 |
--------------------------------------------------------------------------------
/packages/runed/src/lib/internal/types.ts:
--------------------------------------------------------------------------------
1 | export type Getter
25 | *
26 | *
28 | */
29 | export class DebouncedYou searched for: {debounced.current}
27 | *%sveltekit.body%
11 |
12 |
13 |
--------------------------------------------------------------------------------
/sites/docs/src/content/getting-started.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Getting Started
3 | description: Learn how to install and use Runed in your projects.
4 | category: Anchor
5 | ---
6 |
7 | ## Installation
8 |
9 | Install Runed using your favorite package manager:
10 |
11 | ```bash
12 | npm install runed
13 | ```
14 |
15 | ## Usage
16 |
17 | Import one of the utilities you need to either a `.svelte` or `.svelte.js|ts` file and start using
18 | it:
19 |
20 | ```svelte title="component.svelte"
21 |
26 |
27 |
28 |
29 | {#if activeElement.current === inputElement}
30 | The input element is active!
31 | {/if}
32 | ```
33 |
34 | or
35 |
36 | ```ts title="some-module.svelte.ts"
37 | import { activeElement } from "runed";
38 |
39 | function logActiveElement() {
40 | $effect(() => {
41 | console.log("Active element is ", activeElement.current);
42 | });
43 | }
44 |
45 | logActiveElement();
46 | ```
47 |
--------------------------------------------------------------------------------
/sites/docs/src/content/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Introduction
3 | description: Runes are magic, but what good is magic if you don't have a wand?
4 | category: Anchor
5 | ---
6 |
7 | Runed is a collection of utilities for Svelte 5 that make composing powerful applications and
8 | libraries a breeze, leveraging the power of [Svelte Runes](https://svelte.dev/blog/runes).
9 |
10 | ## Why Runed?
11 |
12 | Svelte 5 Runes unlock immense power by providing a set of primitives that allow us to build
13 | impressive applications and libraries with ease. However, building complex applications often
14 | requires more than just the primitives provided by Svelte Runes.
15 |
16 | Runed takes those primitives to the next level by providing:
17 |
18 | - **Powerful Utilities**: A set of carefully crafted utility functions and classes that simplify
19 | common tasks and reduce boilerplate.
20 | - **Collective Efforts**: We often find ourselves writing the same utility functions over and over
21 | again. Runed aims to provide a single source of truth for these utilities, allowing the community
22 | to contribute, test, and benefit from them.
23 | - **Consistency**: A consistent set of APIs and behaviors across all utilities, so you can focus on
24 | building your projects instead of constantly learning new APIs.
25 | - **Reactivity First**: Powered by Svelte 5's new reactivity system, Runed utilities are designed to
26 | handle reactive state and side effects with ease.
27 | - **Type Safety**: Full TypeScript support to catch errors early and provide a better developer
28 | experience.
29 |
30 | ## Ideas and Principles
31 |
32 | #### Embrace the Magic of Runes
33 |
34 | Svelte Runes are a powerful new paradigm. Runed fully embraces this concept and explores its
35 | potential. Our goal is to make working with Runes feel as natural and intuitive as possible.
36 |
37 | #### Enhance, Don't Replace
38 |
39 | Runed is not here to replace Svelte's core functionality, but to enhance and extend it. Our
40 | utilities should feel like a natural extension of Svelte, not a separate framework.
41 |
42 | #### Progressive Complexity
43 |
44 | Simple things should be simple, complex things should be possible. Runed provides easy-to-use
45 | defaults while allowing for advanced customization when needed.
46 |
47 | #### Open Source and Community Collaboration
48 |
49 | Runed is an open-source, MIT licensed project that welcomes all forms of contributions from the
50 | community. Whether it's bug reports, feature requests, or code contributions, your input will help
51 | make Runed the best it can be.
52 |
--------------------------------------------------------------------------------
/sites/docs/src/content/utilities/active-element.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: activeElement
3 | description: Track and access the currently focused DOM element
4 | category: Elements
5 | ---
6 |
7 |
10 |
11 | `activeElement` provides reactive access to the currently focused DOM element in your application,
12 | similar to `document.activeElement` but with reactive updates.
13 |
14 | - Updates synchronously with DOM focus changes
15 | - Returns `null` when no element is focused
16 | - Safe to use with SSR (Server-Side Rendering)
17 | - Lightweight alternative to manual focus tracking
18 | - Searches through Shadow DOM boundaries for the true active element
19 |
20 | ## Demo
21 |
22 | 32 | Currently active element: 33 | {activeElement.current?.localName ?? "No active element found"} 34 |
35 | ``` 36 | 37 | ## Custom Document 38 | 39 | If you wish to scope the focus tracking within a custom document or shadow root, you can pass a 40 | `DocumentOrShadowRoot` to the `ActiveElement` options: 41 | 42 | ```svelte 43 | 50 | ``` 51 | 52 | ## Type Definition 53 | 54 | ```ts 55 | interface ActiveElement { 56 | readonly current: Element | null; 57 | } 58 | ``` 59 | -------------------------------------------------------------------------------- /sites/docs/src/content/utilities/animation-frames.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: AnimationFrames 3 | description: A wrapper for requestAnimationFrame with FPS control and frame metrics 4 | category: Animation 5 | --- 6 | 7 | 10 | 11 | `AnimationFrames` provides a declarative API over the browser's 12 | [`requestAnimationFrame`](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame), 13 | offering FPS limiting capabilities and frame metrics while handling cleanup automatically. 14 | 15 | ## Demo 16 | 17 |{stats}
43 |
46 | 47 | FPS limit: {fpsLimit}{fpsLimit === 0 ? " (not limited)" : ""} 48 |
49 |
29 |
30 |
32 | ```
33 |
34 | You may cancel the pending update, run it immediately, or set a new value. Setting a new value
35 | immediately also cancels any pending updates.
36 |
37 | ```ts
38 | let count = $state(0);
39 | const debounced = new Debounced(() => count, 500);
40 | count = 1;
41 | debounced.cancel();
42 | // after a while...
43 | console.log(debounced.current); // Still 0!
44 |
45 | count = 2;
46 | console.log(debounced.current); // Still 0!
47 | debounced.setImmediately(count);
48 | console.log(debounced.current); // 2
49 |
50 | count = 3;
51 | console.log(debounced.current); // 2
52 | await debounced.updateImmediately();
53 | console.log(debounced.current); // 3
54 | ```
55 |
--------------------------------------------------------------------------------
/sites/docs/src/content/utilities/element-rect.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: ElementRect
3 | description: Track element dimensions and position reactively
4 | category: Elements
5 | ---
6 |
7 |
10 |
11 | `ElementRect` provides reactive access to an element's dimensions and position information,
12 | automatically updating when the element's size or position changes.
13 |
14 | ## Demo
15 |
16 | You searched for: {debounced.current}
31 |Width: {rect.width} Height: {rect.height}
31 | 32 |{JSON.stringify(rect.current, null, 2)}
33 | ```
34 |
35 | ## Type Definition
36 |
37 | ```ts
38 | type Rect = OmitWidth: {size.width} Height: {size.height}
31 | ``` 32 | 33 | ## Type Definition 34 | 35 | ```ts 36 | interface ElementSize { 37 | readonly width: number; 38 | readonly height: number; 39 | } 40 | ``` 41 | -------------------------------------------------------------------------------- /sites/docs/src/content/utilities/extract.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: extract 3 | description: Resolve the value of a getter or static variable 4 | category: Reactivity 5 | --- 6 | 7 | In libraries like Runed, it's common to pass state reactively using getters (functions that return a 8 | value), a common pattern to pass reactivity across boundaries. 9 | 10 | ```ts 11 | // For example... 12 | import { Previous } from "runed"; 13 | 14 | let count = $state(0); 15 | const previous = new Previous(() => count); 16 | ``` 17 | 18 | However, some APIs accept either a reactive getter or a static value (including `undefined`): 19 | 20 | ```ts 21 | let search = $state(""); 22 | let debounceTime = $stateFocus within form: {focusWithinForm.current}
31 | 35 | ``` 36 | 37 | ## Type Definition 38 | 39 | ```ts 40 | class IsFocusWithin { 41 | constructor(node: MaybeGetterIdle: {idle.current}
28 |29 | Last active: {new Date(idle.lastActive).toLocaleTimeString()} 30 |
31 | ``` 32 | 33 | ## Type Definitions 34 | 35 | ```ts 36 | interface IsIdleOptions { 37 | /** 38 | * The events that should set the idle state to `true` 39 | * 40 | * @default ['mousemove', 'mousedown', 'resize', 'keydown', 'touchstart', 'wheel'] 41 | */ 42 | events?: MaybeGetter<(keyof WindowEventMap)[]>; 43 | /** 44 | * The timeout in milliseconds before the idle state is set to `true`. Defaults to 60 seconds. 45 | * 46 | * @default 60000 47 | */ 48 | timeout?: MaybeGetterTarget node
32 | 33 |Target node in viewport: {inViewport.current}
34 | ``` 35 | 36 | ## Type Definition 37 | 38 | ```ts 39 | import { type UseIntersectionObserverOptions } from "runed"; 40 | export type IsInViewportOptions = UseIntersectionObserverOptions; 41 | 42 | export declare class IsInViewport { 43 | constructor(node: MaybeGetter
37 |
38 |
39 |
40 |
42 | ```
43 |
44 | ## Configuration Options
45 |
46 | `PersistedState` includes an `options` object that allows you to customize the behavior of the state
47 | manager.
48 |
49 | ```ts
50 | const state = new PersistedState("user-preferences", initialValue, {
51 | // Use sessionStorage instead of localStorage (default: 'local')
52 | storage: "session",
53 |
54 | // Disable cross-tab synchronization (default: true)
55 | syncTabs: false,
56 |
57 | // Custom serialization handlers
58 | serializer: {
59 | serialize: superjson.stringify,
60 | deserialize: superjson.parse
61 | }
62 | });
63 | ```
64 |
65 | ### Storage Options
66 |
67 | - `'local'`: Data persists until explicitly cleared
68 | - `'session'`: Data persists until the browser session ends
69 |
70 | ### Cross-Tab Synchronization
71 |
72 | When `syncTabs` is enabled (default), changes are automatically synchronized across all browser tabs
73 | using the storage event.
74 |
75 | ### Custom Serialization
76 |
77 | Provide custom `serialize` and `deserialize` functions to handle complex data types:
78 |
79 | ```ts
80 | import superjson from "superjson";
81 |
82 | // Example with Date objects
83 | const lastAccessed = new PersistedState("last-accessed", new Date(), {
84 | serializer: {
85 | serialize: superjson.stringify,
86 | deserialize: superjson.parse
87 | }
88 | });
89 | ```
90 |
--------------------------------------------------------------------------------
/sites/docs/src/content/utilities/pressed-keys.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: PressedKeys
3 | description: Tracks which keys are currently pressed
4 | category: Sensors
5 | ---
6 |
7 |
10 |
11 | ## Demo
12 |
13 | Count: {count.current}
41 |
30 |
31 |
33 | ```
34 |
35 | ## Type Definition
36 |
37 | ```ts
38 | class PreviousPrevious: {`${previous.current}`}
32 |
44 |
45 |
46 | ```
47 |
48 | You can now access:
49 |
50 | - `scroll.x` and `scroll.y` — current scroll positions (reactive, get/set)
51 |
52 | - `scroll.directions` — active scroll directions
53 |
54 | - `scroll.arrived` — whether the scroll has reached each edge
55 |
56 | - `scroll.scrollTo(x, y)` — programmatic scroll
57 |
58 | - `scroll.scrollToTop()` and `scroll.scrollToBottom()` — helpers
59 |
60 | ## Options
61 |
62 | You can configure `ScrollState` via the following options:
63 |
64 | | Option | Type | Description |
65 | | ---------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- |
66 | | `element` | `MaybeGetter{count}
41 | 42 | 43 | 44 | 45 | 46 | 47 | ``` 48 | -------------------------------------------------------------------------------- /sites/docs/src/content/utilities/textarea-autosize.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: TextareaAutosize 3 | description: Automatically adjust a textarea's height based on its content. 4 | category: Elements 5 | --- 6 | 7 | 10 | 11 | ## Demo 12 | 13 |
8 | {@render children?.()}
9 |
10 |
--------------------------------------------------------------------------------
/sites/docs/src/lib/components/demos/active-element.svelte:
--------------------------------------------------------------------------------
1 |
5 |
6 |
8 | Currently active element:
9 |
10 | {activeElement.current?.localName ?? "No active element found"}
11 |
12 |
{stats}
34 |
45 |
53 |
54 | 55 | FPS limit: {fpsLimit}{fpsLimit === 0 ? " (not limited)" : ""} 56 |
57 |67 | Mouse sprite extracted from Animal Well 72 |
73 |12 | {#if debounced.current} 13 | You searched for: {debounced.current} 14 | {:else} 15 | Search for something above! 16 | {/if} 17 |
18 |
39 | Now: {f.current}
40 |
41 | {descriptionText}
42 |
43 | f.send("toggleEnabled")}
47 | />
48 |
61 |
62 | {#if f.current === "running"}
63 |
68 |
64 |
65 |
66 | {/if}
67 | 33 | Focus is within form: 34 | 35 | {formFocused.current} 36 | 37 |
38 |17 | Idle: {idle.current} 21 |
22 |23 | Last active: {secondsElapsed}s ago 24 |
25 |By default, the time of inactivity before marking the user as idle is 1 minute.
28 |In this demo, it's 1 second.
29 |Target node
11 |Scroll down to observe the behavior
12 |
17 |
27 |
--------------------------------------------------------------------------------
/sites/docs/src/lib/components/demos/is-mounted.svelte:
--------------------------------------------------------------------------------
1 |
7 |
8 | 18 | Target node is 24 | viewport 25 |
26 |Mounted: {isMounted.current ? "true" : "false"}
10 |
16 |
19 | container
20 |
21 |
35 | {containerText}
22 |23 | Status: {clickOutside.enabled ? "Enabled" : "Disabled"} 26 |
27 |
28 |
29 |
30 |
33 |
34 |
10 |
11 |
12 |
13 |
14 | Count: {`${count.current}`}
15 |
36 | {#if allPressed}
37 |
66 |
41 |
43 | {/if}
44 | {#each toPress as key, i (`key-${i}`)}
45 |
46 |
47 | (triedInputting = true)}
54 | >
55 | {#if keys.has(key)}
56 |
60 | {key}
61 |
62 | {/if}
63 |
64 | {/each}
65 | {guessedCorrectly ? "You did it! 🎉" : "Try and guess the password 👀"}
67 | 68 | {#if !guessedCorrectly && triedInputting} 69 |73 | Press any key to start, no need to select anything 74 |
75 | {/if} 76 |Previous: {`${previous.current}`}
15 |
19 | Post id:
20 |
21 |
22 |
23 |
39 |
40 |
43 |
24 |
38 |
25 | Status: {searchResource.loading ? "Loading..." : "Ready"}
26 |
27 | {#if searchResource.error}
28 |
29 | Error: {searchResource.error.message}
30 |
31 | {/if}
32 |
33 | {#each searchResource.current ?? [] as result, i (`result-${i}`)}
34 |
37 | {JSON.stringify(result, null, 2)}
35 | {/each}
36 |
21 |
90 |
91 |
111 |
--------------------------------------------------------------------------------
/sites/docs/src/lib/components/demos/state-history.svelte:
--------------------------------------------------------------------------------
1 |
16 |
17 |
22 |
23 |
24 |
25 | Scroll me
26 |
27 |
28 |
71 | 72 |
81 |
89 | Controls & State
29 |
30 |
37 |
44 |
45 | {#snippet info(label: string, condition: boolean)}
46 |
47 | {label}
48 |
54 | {condition ? "Yes" : "No"}
55 |
56 |
57 | {/snippet}
58 |
59 |
60 |
67 | {@render info("isScrolling", scroll.isScrolling)}
68 |
69 |
70 | 71 | 72 |
Arrived
73 |
74 | {@render info("top", scroll.arrived.top)}
75 | {@render info("right", scroll.arrived.right)}
76 | {@render info("bottom", scroll.arrived.bottom)}
77 | {@render info("left", scroll.arrived.left)}
78 |
79 |
80 | 81 |
Directions
82 |
83 | {@render info("top", scroll.directions.top)}
84 | {@render info("right", scroll.directions.right)}
85 | {@render info("bottom", scroll.directions.bottom)}
86 | {@render info("left", scroll.directions.left)}
87 |
88 | Count: {count}
19 |
20 |
21 |
22 | /
23 |
26 |
29 |
30 |
31 |
32 |
42 | History (limited to 10 records for demo)
33 |
34 | {#each history.log.toReversed() as event, i (`${event}-${i}`)}
35 |
41 |
36 | {format(event.timestamp)}
37 | {`{ value: ${event.snapshot} }`}
38 |
39 | {/each}
40 |
31 |
32 |
33 |
34 |
35 |
36 |
42 |
45 |
46 | {logged || "Press the button!"}
47 |You've clicked the document {count} {count === 1 ? "time" : "times"}
15 |Coords: {JSON.stringify(location.position.coords, null, 2)}
10 | Located at: {location.position.timestamp}
11 | Error: {JSON.stringify(location.error, null, 2)}
12 | Is Supported: {location.isSupported}
13 |
14 |
15 |
16 |
17 |
27 | {
31 | if (v) {
32 | observer.resume();
33 | } else {
34 | observer.pause();
35 | }
36 | }}
37 | />
38 |
39 |
40 |
44 |
49 | Scroll down 👇
45 |
46 |
48 | I'm the target! 🎯
47 |
50 | Element
51 |
54 | {isVisible ? "inside" : "outside"}
55 |
56 | the viewport
57 |
58 |
33 | {#each messages as text, i (`${text}-${i}`)}
34 |
41 |
35 | Mutation Attribute: {text}
36 |
37 | {:else}
38 | No mutations yet
39 | {/each}
40 |