From f8e84f9f8dd2c7ce0dcad06903ddc6af30c1051b Mon Sep 17 00:00:00 2001 From: alicesaidhi <166900055+alicesaidhi@users.noreply.github.com> Date: Sun, 3 Nov 2024 18:32:19 +0100 Subject: [PATCH 01/22] Improve Documentation Site (#41) * update css and snippets * Add banner * improve home page * Update Banner * cleanup * Update font to JetBrains Mono * Add a quick look to Home * Simplify Home Page * Removed banner, removed copyright notice, reduced home page --- README.md | 2 +- docs/.vitepress/config.ts | 155 ++++++++++-------- docs/.vitepress/theme/home.css | 19 +++ docs/.vitepress/theme/index.js | 12 +- docs/.vitepress/theme/vars.css | 49 +++++- docs/api/animation.md | 2 +- docs/api/creation.md | 16 +- docs/api/reactivity-core.md | 14 +- docs/api/reactivity-flow.md | 14 +- docs/api/reactivity-utility.md | 16 +- docs/api/strict-mode.md | 2 +- docs/index.md | 14 +- docs/package.json | 26 ++- docs/public/full_logo.svg | 2 +- docs/public/logo.svg | 40 ++--- docs/tut/advanced/nested-scoping.md | 6 +- docs/tut/crash-course/10-cleanup.md | 2 +- docs/tut/crash-course/11-control-flow.md | 4 +- docs/tut/crash-course/12-actions.md | 6 +- docs/tut/crash-course/13-strict-mode.md | 2 +- docs/tut/crash-course/14-concepts.md | 2 +- docs/tut/crash-course/2-creation.md | 2 +- docs/tut/crash-course/3-components.md | 4 +- docs/tut/crash-course/4-source.md | 6 +- docs/tut/crash-course/5-effect.md | 4 +- docs/tut/crash-course/6-scope.md | 4 +- docs/tut/crash-course/7-stateful-component.md | 4 +- docs/tut/crash-course/8-implicit-effect.md | 4 +- docs/tut/crash-course/9-derived-source.md | 6 +- 29 files changed, 255 insertions(+), 184 deletions(-) create mode 100644 docs/.vitepress/theme/home.css diff --git a/README.md b/README.md index 8ce077b..13e41b6 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ for a quick introduction to the library. ## Code sample -```lua +```luau local create = vide.create local source = vide.source diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 7708fdf..cde7870 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,70 +1,85 @@ -//import { defineConfig } from "vitepress" -import { withMermaid } from "vitepress-plugin-mermaid"; - -// https://vitepress.dev/reference/site-config -export default withMermaid({ - title: "Vide", - titleTemplate: ":title - A reactive UI library for Luau", - description: "A reactive UI library for Luau.", - base: "/vide/", - head: [["link", { rel: "icon", href: "/vide/logo.svg" }]], - - themeConfig: { - logo: "/logo.svg", - - // https://vitepress.dev/reference/default-theme-config - nav: [ - { text: "Home", link: "/" }, - { text: "Tutorials", link: "/tut/crash-course/1-introduction" }, - { text: "API", link: "/api/reactivity-core"}, - ], - - sidebar: { - "/api/": [ - { - text: "API", - items: [ - { text: "Reactivity: Core", link: "/api/reactivity-core" }, - { text: "Reactivity: Utility", link: "/api/reactivity-utility" }, - { text: "Reactivity: Control Flow", link: "/api/reactivity-flow" }, - { text: "Element Creation", link: "/api/creation" }, - { text: "Animation", link: "/api/animation" }, - { text: "Strict Mode", link: "/api/strict-mode" }, - ] - } - ], - - "/tut/": [ - { - text: "Crash Course", - items: [ - { text: "Introduction", link: "/tut/crash-course/1-introduction" }, - { text: "Element Creation", link: "/tut/crash-course/2-creation" }, - { text: "Components", link: "/tut/crash-course/3-components" }, - { text: "Sources", link: "/tut/crash-course/4-source" }, - { text: "Effects", link: "/tut/crash-course/5-effect" }, - { text: "Scopes", link: "/tut/crash-course/6-scope" }, - { text: "Stateful Components", link: "/tut/crash-course/7-stateful-component" }, - { text: "Implicit Effects", link: "/tut/crash-course/8-implicit-effect" }, - { text: "Derived Sources", link: "/tut/crash-course/9-derived-source" }, - { text: "Cleanup", link: "/tut/crash-course/10-cleanup" }, - { text: "Control Flow", link: "/tut/crash-course/11-control-flow" }, - { text: "Actions", link: "/tut/crash-course/12-actions" }, - { text: "Strict Mode", link: "/tut/crash-course/13-strict-mode" }, - { text: "Concepts Summary", link: "/tut/crash-course/14-concepts" } - ] - }, - { - text: "Advanced Reactivity", - items: [ - { text: "Nested Scopes", link: "/tut/advanced/nested-scoping.md"} - ] - } - ], - }, - - socialLinks: [ - { icon: "github", link: "https://github.com/centau/vide" } - ] - } -}) +//import { defineConfig } from "vitepress" +import { withMermaid } from "vitepress-plugin-mermaid"; +import { tabsMarkdownPlugin } from "vitepress-plugin-tabs" + +// https://vitepress.dev/reference/site-config +export default withMermaid({ + title: "Vide", + titleTemplate: ":title - A reactive UI library for Luau", + description: "A reactive UI library for Luau.", + base: "/vide/", + head: [["link", { rel: "icon", href: "/vide/logo.svg" }]], + + markdown: { + config(md) { + md.use(tabsMarkdownPlugin) + } + }, + + themeConfig: { + logo: "/logo.svg", + + search: { + provider: "local" + }, + + footer: { + message: 'Released under the MIT License.', + }, + + // https://vitepress.dev/reference/default-theme-config + nav: [ + { text: "Home", link: "/" }, + { text: "Tutorials", link: "/tut/crash-course/1-introduction" }, + { text: "API", link: "/api/reactivity-core"}, + ], + + sidebar: { + "/api/": [ + { + text: "API", + items: [ + { text: "Reactivity: Core", link: "/api/reactivity-core" }, + { text: "Reactivity: Utility", link: "/api/reactivity-utility" }, + { text: "Reactivity: Control Flow", link: "/api/reactivity-flow" }, + { text: "Element Creation", link: "/api/creation" }, + { text: "Animation", link: "/api/animation" }, + { text: "Strict Mode", link: "/api/strict-mode" }, + ] + } + ], + + "/tut/": [ + { + text: "Crash Course", + items: [ + { text: "Introduction", link: "/tut/crash-course/1-introduction" }, + { text: "Element Creation", link: "/tut/crash-course/2-creation" }, + { text: "Components", link: "/tut/crash-course/3-components" }, + { text: "Sources", link: "/tut/crash-course/4-source" }, + { text: "Effects", link: "/tut/crash-course/5-effect" }, + { text: "Scopes", link: "/tut/crash-course/6-scope" }, + { text: "Stateful Components", link: "/tut/crash-course/7-stateful-component" }, + { text: "Implicit Effects", link: "/tut/crash-course/8-implicit-effect" }, + { text: "Derived Sources", link: "/tut/crash-course/9-derived-source" }, + { text: "Cleanup", link: "/tut/crash-course/10-cleanup" }, + { text: "Control Flow", link: "/tut/crash-course/11-control-flow" }, + { text: "Actions", link: "/tut/crash-course/12-actions" }, + { text: "Strict Mode", link: "/tut/crash-course/13-strict-mode" }, + { text: "Concepts Summary", link: "/tut/crash-course/14-concepts" } + ] + }, + { + text: "Advanced Reactivity", + items: [ + { text: "Nested Scopes", link: "/tut/advanced/nested-scoping.md"} + ] + } + ], + }, + + socialLinks: [ + { icon: "github", link: "https://github.com/centau/vide" } + ] + } +}) diff --git a/docs/.vitepress/theme/home.css b/docs/.vitepress/theme/home.css new file mode 100644 index 0000000..c5f042c --- /dev/null +++ b/docs/.vitepress/theme/home.css @@ -0,0 +1,19 @@ +.home > * > .VPNavBar:not(.top) { + backdrop-filter: blur(0.5rem); + background-color: transparent !important; +} + +.home > * > .VPNavBar > .divider { + opacity: 0; +} + +.home > .VPContent { + display: flex; + justify-content: center; + flex-direction: column; +} + +.VPHome { + margin-top: auto !important; + margin-bottom: auto !important; +} \ No newline at end of file diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js index b8b9aa6..7f7e9a7 100644 --- a/docs/.vitepress/theme/index.js +++ b/docs/.vitepress/theme/index.js @@ -1,4 +1,8 @@ -// .vitepress/theme/index.js -import DefaultTheme from 'vitepress/theme' -import './vars.css' -export default DefaultTheme +// .vitepress/theme/index.js +import DefaultTheme from 'vitepress/theme' +import './vars.css' +import './home.css' + +export default { + extends: DefaultTheme, +} \ No newline at end of file diff --git a/docs/.vitepress/theme/vars.css b/docs/.vitepress/theme/vars.css index 64df54f..6556617 100644 --- a/docs/.vitepress/theme/vars.css +++ b/docs/.vitepress/theme/vars.css @@ -1,3 +1,46 @@ -:root { - --vp-c-brand-1: #3086ff; -} +/* Colors */ + +:root { + --vp-c-brand-1: #3086ff; + --vp-c-brand-2: #75aeff; + + --vp-button-brand-bg: #3661a2; + --vp-button-brand-hover-bg: #24447f; + --vp-button-brand-press-bg: #4896f3; + + --vp-home-hero-name-color: transparent; + --vp-home-hero-name-background: -webkit-linear-gradient( + 120deg, + #3661a2, + #4896f3 + ); + --vp-home-hero-logo-background: -webkit-linear-gradient( + 120deg, + #3661a2, + #4896f3 + ); + + --vp-home-hero-image-filter: blur(96px); + + --vp-c-bg: #f2f5f8; + --vp-c-bg-alt: #dfe8f5; + --vp-c-bg-elv: #dde7f4; + --vp-c-bg-soft: #e8f1fe; + + --vp-c-border: #c0c3c6; + --vp-c-divider: #dfe2e6; + --vp-c-gutter: #dfe2e6; + --vp-plugin-tabs-tab-bg: var(--vp-c-bg); +} + +.dark { + --vp-c-brand-2: #234782; + --vp-c-bg: #0d131b; + --vp-c-bg-alt: #111720; + --vp-c-bg-elv: #182231; + --vp-c-bg-soft: #182231; + + --vp-c-border: #111720; + --vp-c-divider: #1d273c; + --vp-c-gutter: #181d27; +} \ No newline at end of file diff --git a/docs/api/animation.md b/docs/api/animation.md index 6481cc3..9f3b805 100644 --- a/docs/api/animation.md +++ b/docs/api/animation.md @@ -6,7 +6,7 @@ Returns a new source with a value always moving torwards the input source value. - **Type** - ```lua + ```luau function spring( source: () -> T & Animatable, period: number = 1, diff --git a/docs/api/creation.md b/docs/api/creation.md index 539967d..528b4fb 100644 --- a/docs/api/creation.md +++ b/docs/api/creation.md @@ -9,7 +9,7 @@ target instance. - **Type** - ```lua + ```luau function mount(component: () -> T, target: Instance?): () -> () ``` @@ -25,7 +25,7 @@ target instance. - **Example** - ```lua + ```luau local function App() return create "ScreenGui" { create "TextLabel" { Text = "Vide" } @@ -41,7 +41,7 @@ Creates a new UI element, applying any given properties. - **Type** - ```lua + ```luau function create(class: string): (Properties) -> Instance function create(instance: Instance): (Properties) -> Instance @@ -76,7 +76,7 @@ Creates a new UI element, applying any given properties. Basic element creation. - ```lua + ```luau local frame = create "Frame" { Name = "NewFrame", Position = UDim2.fromScale(1, 0) @@ -85,7 +85,7 @@ Creates a new UI element, applying any given properties. A component using property nesting. - ```lua + ```luau type Layout = { Layout = { Position: UDim2?, @@ -116,7 +116,7 @@ instances. - **Type** - ```lua + ```luau function action((Instance) -> (), priority: number = 1): Action ``` @@ -133,7 +133,7 @@ instances. An action to listen to changed properties: - ```lua + ```luau local function changed(property: string, callback: (new) -> ()) return action(function(instance) local con - instance:GetPropertyChangedSignal(property):Connect(function() @@ -161,7 +161,7 @@ A wrapper for `action()` to listen for property changes. - **Type** - ```lua + ```luau function changed(property: string, callback: (...unknown) -> ()): Action ``` diff --git a/docs/api/reactivity-core.md b/docs/api/reactivity-core.md index 861e0e1..b68911c 100644 --- a/docs/api/reactivity-core.md +++ b/docs/api/reactivity-core.md @@ -13,7 +13,7 @@ Creates and runs a function in a new stable scope. - **Type** - ```lua + ```luau function root(fn: (() -> ()) -> T...): (() -> (), T...) ``` @@ -30,7 +30,7 @@ Creates a new source with the given value. - **Type** - ```lua + ```luau function source(value: T): Source type Source = @@ -45,7 +45,7 @@ Creates a new source with the given value. - **Example** - ```lua + ```luau local count = source(0) count() -- 0 @@ -59,7 +59,7 @@ Runs a side-effect in a new reactive scope on source update. - **Type** - ```lua + ```luau function effect(callback: () -> ()) ``` @@ -72,7 +72,7 @@ Runs a side-effect in a new reactive scope on source update. - **Example** - ```lua + ```luau local num = source(1) effect(function() @@ -92,7 +92,7 @@ Derives a new source in a new reactive scope from existing sources. - **Type** - ```lua + ```luau function derive(source: () -> T): () -> T ``` @@ -108,7 +108,7 @@ Derives a new source in a new reactive scope from existing sources. - **Example** - ```lua + ```luau local count = source(0) local text = derive(function() return `count: {count()}` end) diff --git a/docs/api/reactivity-flow.md b/docs/api/reactivity-flow.md index 6870367..03aea97 100644 --- a/docs/api/reactivity-flow.md +++ b/docs/api/reactivity-flow.md @@ -8,7 +8,7 @@ Shows one of two components depending on an input source. - **Type** - ```lua + ```luau function show(source: () -> unknown, component: () -> T): () -> T? function show(source: () -> unknown, component: () -> T, fallback: () -> U): () -> T | U ``` @@ -32,7 +32,7 @@ Shows one of a set of components depending on an input source and a mapping tabl - **Type** - ```lua + ```luau function switch(source: () -> K): (map: Map V>) -> V? ``` @@ -49,7 +49,7 @@ Shows one of a set of components depending on an input source and a mapping tabl - **Example** - ```lua + ```luau local logged = source(false) local button = switch(logged) { @@ -69,7 +69,7 @@ Maps each index in a table source to an object. - **Type** - ```lua + ```luau function indexes( source: () -> Map, transform: (value: () -> VI, index: KI) -> VO @@ -102,7 +102,7 @@ Maps each index in a table source to an object. The intended purpose of this function is to map each index in a table to a UI element. - ```lua + ```luau type Item = { name: string, icon: number @@ -129,7 +129,7 @@ Maps each value in a table source to an object. - **Type** - ```lua + ```luau function values( source: () -> Map, transform: (value: VI, index: () -> KI) -> VO @@ -169,7 +169,7 @@ Maps each value in a table source to an object. The intended purpose of this function is to map each value in a table to a UI element. - ```lua + ```luau type Item = { name: string, icon: number diff --git a/docs/api/reactivity-utility.md b/docs/api/reactivity-utility.md index 824fe35..6f719e1 100644 --- a/docs/api/reactivity-utility.md +++ b/docs/api/reactivity-utility.md @@ -6,7 +6,7 @@ Runs a callback anytime a scope is reran or destroyed. - **Type** - ```lua + ```luau function cleanup(callback: () -> ()) function cleanup(obj: Destroyable) function cleanup(obj: Disconnectable) @@ -17,7 +17,7 @@ Runs a callback anytime a scope is reran or destroyed. - **Example** - ```lua + ```luau local data = source(1) effect(function() @@ -35,7 +35,7 @@ Runs a given function in a new stable scope. - **Type** - ```lua + ```luau function untrack(source: () -> T): T ``` @@ -46,7 +46,7 @@ Runs a given function in a new stable scope. - **Example** - ```lua + ```luau local a = source(0) local b = source(0) @@ -68,7 +68,7 @@ read can still be tracked inside a reactive scope. - **Type** - ```lua + ```luau function read(value: T | () -> T): T ``` @@ -79,7 +79,7 @@ trigger effects until after the function finishes running. - **Type** - ```lua + ```luau function batch(fn: () -> ()) ``` @@ -96,7 +96,7 @@ Creates a new context. - **Type** - ```lua + ```luau function context(default: T): Context type Context = @@ -113,7 +113,7 @@ Creates a new context. - **Example** - ```lua + ```luau local theme = context() local function Button() diff --git a/docs/api/strict-mode.md b/docs/api/strict-mode.md index 570108b..b3cae5b 100644 --- a/docs/api/strict-mode.md +++ b/docs/api/strict-mode.md @@ -2,7 +2,7 @@ Strict mode is library-wide and can get set by doing: -```lua +```luau vide.strict = true ``` diff --git a/docs/index.md b/docs/index.md index 6fe3a4a..21f0227 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,24 +1,22 @@ --- # https://vitepress.dev/reference/default-theme-home-page layout: home +pageClass: home +next: + text: 'Introduction' + link: '/tut/crash-course/1-introduction' hero: - name: Vide - text: "" + name: "Vide" tagline: A reactive UI library for Luau. image: src: /logo.svg - alt: Vide actions: - theme: brand - text: Tutorials + text: Crash Course link: /tut/crash-course/1-introduction - theme: alt text: API Reference link: /api/reactivity-core -features: - - title: In Development - details: Not recommended for production use. --- - diff --git a/docs/package.json b/docs/package.json index 5dce993..5e3035b 100644 --- a/docs/package.json +++ b/docs/package.json @@ -1,14 +1,12 @@ -{ - "type": "module", - - "scripts": { - "docs:dev": "vitepress dev", - "docs:build": "vitepress build", - "docs:preview": "vitepress preview" - }, - - "devDependencies": { - "vitepress": "1.0.0-rc.25", - "vitepress-plugin-mermaid": "2.0.14" - } -} +{ + "type": "module", + "scripts": { + "docs:dev": "vitepress dev", + "docs:build": "vitepress build", + "docs:preview": "vitepress preview" + }, + "devDependencies": { + "vitepress": "1.4.1", + "vitepress-plugin-mermaid": "2.0.17" + } +} diff --git a/docs/public/full_logo.svg b/docs/public/full_logo.svg index 85488e0..1962800 100644 --- a/docs/public/full_logo.svg +++ b/docs/public/full_logo.svg @@ -1,4 +1,4 @@ - + diff --git a/docs/public/logo.svg b/docs/public/logo.svg index 92b06c1..22d840a 100644 --- a/docs/public/logo.svg +++ b/docs/public/logo.svg @@ -1,37 +1,31 @@ - - - - - + + + + + - + + - - - + + + - + - - - + + + - - - - - - - - + - + - + diff --git a/docs/tut/advanced/nested-scoping.md b/docs/tut/advanced/nested-scoping.md index c5e6b4b..0542ccc 100644 --- a/docs/tut/advanced/nested-scoping.md +++ b/docs/tut/advanced/nested-scoping.md @@ -6,7 +6,7 @@ most common cases, but they do not cover all of them. This tutorial will demonstrate how to implement a `show()` control flow function using just sources and effects. -```lua +```luau local mount = vide.mount local source = vide.source local show = vide.show @@ -61,7 +61,7 @@ effect's reactive scope is destroyed whenever the show effect is rerun. The same can be achieved without the use of `show()`: -```lua +```luau local mount = vide.mount local source = vide.source local effect = vide.effect @@ -126,7 +126,7 @@ may be rerun needlessly and recreate the counter. Alternatively, instead of using `root()`: -```lua +```luau local mount = vide.mount local source = vide.source local effect = vide.effect diff --git a/docs/tut/crash-course/10-cleanup.md b/docs/tut/crash-course/10-cleanup.md index f6ca5f3..e498c23 100644 --- a/docs/tut/crash-course/10-cleanup.md +++ b/docs/tut/crash-course/10-cleanup.md @@ -5,7 +5,7 @@ a side-effect from a source update. Vide provides a function `cleanup()` which is used to queue a callback for the next time a reactive scope is rerun or destroyed, or when a stable scope is destroyed. -```lua +```luau local root = vide.root local source = vide.source local effect = vide.effect diff --git a/docs/tut/crash-course/11-control-flow.md b/docs/tut/crash-course/11-control-flow.md index b206915..298ce93 100644 --- a/docs/tut/crash-course/11-control-flow.md +++ b/docs/tut/crash-course/11-control-flow.md @@ -14,7 +14,7 @@ instance. update to display the current value at that index. Each table index is given a single corresponding UI element. -```lua +```luau local list = source { "finish the crash course", "star Vide's GitHub" @@ -90,7 +90,7 @@ end When you edit a table in a source, you must set that table again to actually update the source. -```lua +```luau local src = source { 1, 2 } local data = src() table.insert(data, 3) -- no effects will run diff --git a/docs/tut/crash-course/12-actions.md b/docs/tut/crash-course/12-actions.md index 176c12e..64d3fce 100644 --- a/docs/tut/crash-course/12-actions.md +++ b/docs/tut/crash-course/12-actions.md @@ -3,11 +3,11 @@ Actions in Vide are special callbacks that you can pass along with properties, to run some code on an instance receiving them. -```lua +```luau local action = vide.action ``` -```lua +```luau create "TextLabel" { Text = "test", @@ -22,7 +22,7 @@ create "TextLabel" { Actions can be wrapped with functions for reuse. Below is an example of an action used to listen for property changes: -```lua +```luau local action = vide.action local effect = vide.effect local cleanup = vide.cleanup diff --git a/docs/tut/crash-course/13-strict-mode.md b/docs/tut/crash-course/13-strict-mode.md index 6efa1c3..f2b30fe 100644 --- a/docs/tut/crash-course/13-strict-mode.md +++ b/docs/tut/crash-course/13-strict-mode.md @@ -13,7 +13,7 @@ Strict mode will run derived sources and effects twice each time they update. This is to help ensure that derived source computations are pure, and that any cleanups made in derived sources or effects are done properly. -```lua +```luau local source = vide.source local effect = vide.effect diff --git a/docs/tut/crash-course/14-concepts.md b/docs/tut/crash-course/14-concepts.md index 24ca703..77e9e7f 100644 --- a/docs/tut/crash-course/14-concepts.md +++ b/docs/tut/crash-course/14-concepts.md @@ -73,7 +73,7 @@ relationships between effects and the sources they depend on. ### Code -```lua +```luau local count = source(0) root(function() diff --git a/docs/tut/crash-course/2-creation.md b/docs/tut/crash-course/2-creation.md index 5e76173..668a470 100644 --- a/docs/tut/crash-course/2-creation.md +++ b/docs/tut/crash-course/2-creation.md @@ -5,7 +5,7 @@ Instances are created using `create()`. Parentheses `()` can be omitted when calling functions with string or table literals for brevity. -```lua +```luau local create = vide.create return create "ScreenGui" { diff --git a/docs/tut/crash-course/3-components.md b/docs/tut/crash-course/3-components.md index 8e5890f..0b803ca 100644 --- a/docs/tut/crash-course/3-components.md +++ b/docs/tut/crash-course/3-components.md @@ -10,7 +10,7 @@ together. ::: code-group -```lua [Button.luau] +```luau [Button.luau] local create = vide.create local function Button(props: { @@ -34,7 +34,7 @@ end return Button ``` -```lua [Menu.luau] +```luau [Menu.luau] local create = vide.create local Button = require(Button) diff --git a/docs/tut/crash-course/4-source.md b/docs/tut/crash-course/4-source.md index 08da45c..d862156 100644 --- a/docs/tut/crash-course/4-source.md +++ b/docs/tut/crash-course/4-source.md @@ -5,7 +5,7 @@ Vide's reactivity. A source can be created using `source()`. -```lua +```luau local source = vide.source local count = source(0) @@ -16,13 +16,13 @@ The value passed to `source()` is the initial value of the source. The value of a source can be set by calling it with an argument, and can be read by calling it with no arguments. -```lua +```luau count(count() + 1) -- increment count by 1 ``` Sources can be *derived* by wrapping them in functions. -```lua +```luau local count = source(0) local text = function() diff --git a/docs/tut/crash-course/5-effect.md b/docs/tut/crash-course/5-effect.md index 5e6043c..29e6358 100644 --- a/docs/tut/crash-course/5-effect.md +++ b/docs/tut/crash-course/5-effect.md @@ -5,7 +5,7 @@ A source and effect is analogous to a signal and connection. Effects are created using `effect()`. -```lua +```luau local source = vide.source local effect = vide.effect @@ -26,7 +26,7 @@ that source is updated. Derived sources are also tracked, it doesn't matter how deeply nested inside a function a source is. -```lua +```luau local source = vide.source local effect = vide.effect diff --git a/docs/tut/crash-course/6-scope.md b/docs/tut/crash-course/6-scope.md index 2853fff..6c12088 100644 --- a/docs/tut/crash-course/6-scope.md +++ b/docs/tut/crash-course/6-scope.md @@ -22,7 +22,7 @@ destroyed, and so on. This is why all scopes must be created within another scope, except `root()` which is used to create the initial scope that you can manually destroy. -```lua +```luau local root = vide.root local source = vide.source local effect = vide.effect @@ -45,7 +45,7 @@ count(1) -- prints "1" The scope created by `root()` can be destroyed. -```lua +```luau local function setup() local count = source(0) diff --git a/docs/tut/crash-course/7-stateful-component.md b/docs/tut/crash-course/7-stateful-component.md index 493f9bc..5126c73 100644 --- a/docs/tut/crash-course/7-stateful-component.md +++ b/docs/tut/crash-course/7-stateful-component.md @@ -5,7 +5,7 @@ store the data, and effects to display the data. ## Internal State -```lua +```luau local create = vide.create local source = vide.source local effect = vide.effect @@ -37,7 +37,7 @@ count source is created inside the component. External sources can also be passed into components for them to use. -```lua +```luau local function Counter(props: { count: () -> number }) local count = props.count diff --git a/docs/tut/crash-course/8-implicit-effect.md b/docs/tut/crash-course/8-implicit-effect.md index bbd92d4..cdb75fb 100644 --- a/docs/tut/crash-course/8-implicit-effect.md +++ b/docs/tut/crash-course/8-implicit-effect.md @@ -3,7 +3,7 @@ Explicitly creating effects to update properties is tedious. You can *implicitly* create an effect to update properties instead. -```lua +```luau local create = vide.create local source = vide.source @@ -34,7 +34,7 @@ with a number key instead of string key) can return an instance or an array of instances. An effect is automatically created to unparent removed instances and parent new instances on source update. -```lua +```luau local items = source { create "TextLabel" { Text = "A" } } diff --git a/docs/tut/crash-course/9-derived-source.md b/docs/tut/crash-course/9-derived-source.md index 12a89b2..19a6a5d 100644 --- a/docs/tut/crash-course/9-derived-source.md +++ b/docs/tut/crash-course/9-derived-source.md @@ -2,7 +2,7 @@ We have seen the basic way to derive a source: -```lua +```luau local count = source(0) local text = function() @@ -18,7 +18,7 @@ However, in some cases where this source could be used by multiple effects at the same time, the function wrapping the source will needlessly rerun to convert the count into a string for each effect using it. -```lua +```luau local source = vide.source local effect = vide.effect @@ -39,7 +39,7 @@ To avoid this, you can use `derive()` to derive a new source instead. This will run a function in a reactive scope only when a source used inside updated. Reading this derived source multiple times will just return a cached result. -```lua +```luau local source = vide.source local effect = vide.effect local derive = vide.derive From 1edcd6516638b536bbd6d969f08f70a39f9db2e9 Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Sun, 3 Nov 2024 17:37:41 +0000 Subject: [PATCH 02/22] Update docs --- docs/.vitepress/config.ts | 7 ------- docs/index.md | 2 +- 2 files changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index cde7870..1b30a51 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,6 +1,5 @@ //import { defineConfig } from "vitepress" import { withMermaid } from "vitepress-plugin-mermaid"; -import { tabsMarkdownPlugin } from "vitepress-plugin-tabs" // https://vitepress.dev/reference/site-config export default withMermaid({ @@ -9,12 +8,6 @@ export default withMermaid({ description: "A reactive UI library for Luau.", base: "/vide/", head: [["link", { rel: "icon", href: "/vide/logo.svg" }]], - - markdown: { - config(md) { - md.use(tabsMarkdownPlugin) - } - }, themeConfig: { logo: "/logo.svg", diff --git a/docs/index.md b/docs/index.md index 21f0227..295d137 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,7 +13,7 @@ hero: src: /logo.svg actions: - theme: brand - text: Crash Course + text: Tutorials link: /tut/crash-course/1-introduction - theme: alt text: API Reference From 94add5d452ff3baaa0d696dda9df7b89f655ba63 Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Sun, 3 Nov 2024 17:46:45 +0000 Subject: [PATCH 03/22] Update vitepress version --- docs/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/package.json b/docs/package.json index 5e3035b..a329007 100644 --- a/docs/package.json +++ b/docs/package.json @@ -6,7 +6,7 @@ "docs:preview": "vitepress preview" }, "devDependencies": { - "vitepress": "1.4.1", + "vitepress": "^1.4.5", "vitepress-plugin-mermaid": "2.0.17" } } From a3cc2dfbdaa1e19fea1e363f7be01a32423678b9 Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Mon, 4 Nov 2024 23:18:04 +0000 Subject: [PATCH 04/22] Update docs --- docs/.vitepress/config.ts | 15 +- docs/.vitepress/theme/{home.css => index.css} | 8 +- docs/.vitepress/theme/index.js | 4 +- docs/.vitepress/theme/vars.css | 8 +- docs/api/animation.md | 11 +- docs/api/creation.md | 142 +++++------- docs/api/reactivity-core.md | 109 ++++++--- docs/api/reactivity-dynamic.md | 212 +++++++++++++++++ docs/api/reactivity-flow.md | 218 ------------------ docs/api/reactivity-utility.md | 78 ++++--- docs/api/strict-mode.md | 22 +- docs/tut/advanced/nested-scoping.md | 192 --------------- docs/tut/control-flow/1-intro.md | 0 docs/tut/control-flow/2-show.md | 1 - docs/tut/control-flow/3-switch.md | 1 - docs/tut/control-flow/4-indexes.md | 1 - docs/tut/control-flow/5-values.md | 1 - docs/tut/crash-course/1-introduction.md | 16 +- docs/tut/crash-course/10-cleanup.md | 2 +- docs/tut/crash-course/11-control-flow.md | 98 -------- docs/tut/crash-course/11-dynamic-scope.md | 158 +++++++++++++ docs/tut/crash-course/12-actions.md | 7 +- docs/tut/crash-course/13-strict-mode.md | 1 + docs/tut/crash-course/14-concepts.md | 34 +-- docs/tut/crash-course/5-effect.md | 26 ++- docs/tut/crash-course/6-scope.md | 58 ++--- ...l-component.md => 7-reactive-component.md} | 8 +- docs/tut/crash-course/8-implicit-effect.md | 32 ++- docs/tut/crash-course/9-derived-source.md | 13 +- docs/tut/dynamic-scoping/custom.md | 144 ++++++++++++ 30 files changed, 850 insertions(+), 770 deletions(-) rename docs/.vitepress/theme/{home.css => index.css} (83%) create mode 100644 docs/api/reactivity-dynamic.md delete mode 100644 docs/api/reactivity-flow.md delete mode 100644 docs/tut/advanced/nested-scoping.md delete mode 100644 docs/tut/control-flow/1-intro.md delete mode 100644 docs/tut/control-flow/2-show.md delete mode 100644 docs/tut/control-flow/3-switch.md delete mode 100644 docs/tut/control-flow/4-indexes.md delete mode 100644 docs/tut/control-flow/5-values.md delete mode 100644 docs/tut/crash-course/11-control-flow.md create mode 100644 docs/tut/crash-course/11-dynamic-scope.md rename docs/tut/crash-course/{7-stateful-component.md => 7-reactive-component.md} (91%) create mode 100644 docs/tut/dynamic-scoping/custom.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 1b30a51..380542a 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -34,7 +34,7 @@ export default withMermaid({ items: [ { text: "Reactivity: Core", link: "/api/reactivity-core" }, { text: "Reactivity: Utility", link: "/api/reactivity-utility" }, - { text: "Reactivity: Control Flow", link: "/api/reactivity-flow" }, + { text: "Reactivity: Dynamic Scoping", link: "/api/reactivity-dynamic" }, { text: "Element Creation", link: "/api/creation" }, { text: "Animation", link: "/api/animation" }, { text: "Strict Mode", link: "/api/strict-mode" }, @@ -52,20 +52,25 @@ export default withMermaid({ { text: "Sources", link: "/tut/crash-course/4-source" }, { text: "Effects", link: "/tut/crash-course/5-effect" }, { text: "Scopes", link: "/tut/crash-course/6-scope" }, - { text: "Stateful Components", link: "/tut/crash-course/7-stateful-component" }, + { text: "Reactive Components", link: "/tut/crash-course/7-reactive-component" }, { text: "Implicit Effects", link: "/tut/crash-course/8-implicit-effect" }, { text: "Derived Sources", link: "/tut/crash-course/9-derived-source" }, { text: "Cleanup", link: "/tut/crash-course/10-cleanup" }, - { text: "Control Flow", link: "/tut/crash-course/11-control-flow" }, + { text: "Dynamic Scoping", link: "/tut/crash-course/11-dynamic-scope" }, { text: "Actions", link: "/tut/crash-course/12-actions" }, { text: "Strict Mode", link: "/tut/crash-course/13-strict-mode" }, { text: "Concepts Summary", link: "/tut/crash-course/14-concepts" } ] }, { - text: "Advanced Reactivity", + text: "Dynamic Scoping", + items: [ + { text: "Custom Scopes", link: "/tut/dynamic-scoping/custom"} + ] + }, + { + text: "Design Patterns", items: [ - { text: "Nested Scopes", link: "/tut/advanced/nested-scoping.md"} ] } ], diff --git a/docs/.vitepress/theme/home.css b/docs/.vitepress/theme/index.css similarity index 83% rename from docs/.vitepress/theme/home.css rename to docs/.vitepress/theme/index.css index c5f042c..9c3ca9a 100644 --- a/docs/.vitepress/theme/home.css +++ b/docs/.vitepress/theme/index.css @@ -16,4 +16,10 @@ .VPHome { margin-top: auto !important; margin-bottom: auto !important; -} \ No newline at end of file +} + +.VPBadge a { + text-decoration: none; + color: inherit + } + \ No newline at end of file diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js index 7f7e9a7..54a4c62 100644 --- a/docs/.vitepress/theme/index.js +++ b/docs/.vitepress/theme/index.js @@ -1,8 +1,8 @@ // .vitepress/theme/index.js import DefaultTheme from 'vitepress/theme' import './vars.css' -import './home.css' +import './index.css' export default { extends: DefaultTheme, -} \ No newline at end of file +} diff --git a/docs/.vitepress/theme/vars.css b/docs/.vitepress/theme/vars.css index 6556617..7fbf3b5 100644 --- a/docs/.vitepress/theme/vars.css +++ b/docs/.vitepress/theme/vars.css @@ -31,6 +31,11 @@ --vp-c-divider: #dfe2e6; --vp-c-gutter: #dfe2e6; --vp-plugin-tabs-tab-bg: var(--vp-c-bg); + + --vp-badge-info-bg: #122d26; + --vp-badge-info-text: #6bdbbd; + --vp-badge-tip-bg: #132741; + --vp-badge-tip-text: #70abfa; } .dark { @@ -43,4 +48,5 @@ --vp-c-border: #111720; --vp-c-divider: #1d273c; --vp-c-gutter: #181d27; -} \ No newline at end of file +} + diff --git a/docs/api/animation.md b/docs/api/animation.md index 9f3b805..8b84ce9 100644 --- a/docs/api/animation.md +++ b/docs/api/animation.md @@ -1,6 +1,6 @@ -# Animation API +# Animation -## spring() +## spring() REACTIVE Returns a new source with a value always moving torwards the input source value. @@ -18,8 +18,7 @@ Returns a new source with a value always moving torwards the input source value. - **Details** - An effect is created to update the new source every frame based on the input - source value. + Creates a reactive scope internally to detect source updates. The movement is physically simulated according to a [spring](https://en.wikipedia.org/wiki/Simple_harmonic_motion). @@ -39,3 +38,7 @@ Returns a new source with a value always moving torwards the input source value. You can change when the solver runs by calling `vide.step(dt)`, which will advance the simulation time by `dt` seconds and automatically stop the solver running in heartbeat. + + ::: warning + Large periods or damping ratios can break the spring. + ::: diff --git a/docs/api/creation.md b/docs/api/creation.md index 528b4fb..578b10f 100644 --- a/docs/api/creation.md +++ b/docs/api/creation.md @@ -1,39 +1,4 @@ -# Element Creation API - -
- -## mount() - -Runs a function in a new stable scope and optionally applies its result to a -target instance. - -- **Type** - - ```luau - function mount(component: () -> T, target: Instance?): () -> () - ``` - -- **Details** - - The result of the function is applied to a target in the same way - properties are using `create()`. - - The function is ran in a new stable scope, just like - [root()](reactivity-core.md#root). - - Returns a function that when called will destroy the stable scope. - -- **Example** - - ```luau - local function App() - return create "ScreenGui" { - create "TextLabel" { Text = "Vide" } - } - end - - mount(App, game.StarterGui) - ``` +# Element Creation ## create() @@ -45,7 +10,7 @@ Creates a new UI element, applying any given properties. function create(class: string): (Properties) -> Instance function create(instance: Instance): (Properties) -> Instance - type Properties = Map + type Properties = Map ``` - **Details** @@ -77,42 +42,22 @@ Creates a new UI element, applying any given properties. Basic element creation. ```luau - local frame = create "Frame" { - Name = "NewFrame", - Position = UDim2.fromScale(1, 0) + local frame = create "TextButton" { + Name = "Button", + Size = UDim2.fromOffset(200, 160), + + Activated = function() + print "clicked" + end, + + create "UICorner" {} } ``` - A component using property nesting. - - ```luau - type Layout = { - Layout = { - Position: UDim2?, - Size: UDim2?, - AnchorPoint: Vector2? - } - } - - type Children = { - Children = Array - } - - function Background(props: Layout & Children & { - Color: Color3 - }) - return create "Frame" { - BackgroundColor3 = props.Color, - props.Layout, - props.Children - } - end - ``` - ## action() -Creates a callback that can be passed to `create()` to invoke custom actions on -instances. +Creates a special object that can be passed to `create()` to invoke custom +actions on instances. - **Type** @@ -122,27 +67,27 @@ instances. - **Details** - When passed to `create()`, the given callback is called with the instance - being created as the only argument. Actions take precedence over property - and child assignments. + When passed to `create()`, the function is called with the instance being + created as the only argument. Actions take precedence over property and + child assignments. A priority can be optionally specified to ensure certain actions run after - other actions. Higher priority numbers are ran after lower priority numbers. + other actions. Lower priority values are ran first. - **Example** An action to listen to changed properties: ```luau - local function changed(property: string, callback: (new) -> ()) + local function changed(property: string, fn: (new) -> ()) return action(function(instance) - local con - instance:GetPropertyChangedSignal(property):Connect(function() - callback(instance[property]) + local cn = instance:GetPropertyChangedSignal(property):Connect(function() + fn(instance[property]) end) - -- disconnect on reactive scope destruction to allow gc of instance + -- disconnect on scope destruction to allow gc of instance cleanup(function() - con:Disconnect() + cn:Disconnect() end) end) end @@ -150,7 +95,7 @@ instances. local output = source "" create "TextBox" { - -- will update the `output` source anytime the text property is changed + -- will update the output source anytime the text property is changed changed("Text", output) } ``` @@ -162,15 +107,46 @@ A wrapper for `action()` to listen for property changes. - **Type** ```luau - function changed(property: string, callback: (...unknown) -> ()): Action + function changed(property: string, fn: (unknown) -> ()): Action ``` - **Details** - Will run the given callback any time the property is changed, as well as - when the action is initially run. + Will run the given function immediately and whenever the property updates. - The changed connection is disconnected when the scope the action is ran in - is destroyed. + The function is called with the updated property value. Runs with an action priority of 1. + +## mount() STABLE + +Runs a function in a new stable scope and optionally applies its result to a +target instance. + +- **Type** + + ```luau + function mount(component: () -> T, target: Instance?): () -> () + ``` + +- **Details** + + This is a utility for `root()` when parenting a component to an existing + instance. + + The result of the function is applied to a target in the same way + properties are using `create()`. + + Returns a function that when called will destroy the stable scope. + +- **Example** + + ```luau + local function App() + return create "ScreenGui" { + create "TextLabel" { Text = "Vide" } + } + end + + local destroy = mount(App, game.StarterGui) + ``` diff --git a/docs/api/reactivity-core.md b/docs/api/reactivity-core.md index b68911c..ebbc5dd 100644 --- a/docs/api/reactivity-core.md +++ b/docs/api/reactivity-core.md @@ -1,32 +1,40 @@ -# Reactivity API: Core +# Reactivity: Core -
+## Scopes + +Vide code can run in one of two scopes: STABLE or REACTIVE. + +- Reactive scopes rerun if a source read within updates. +- Stable scopes never rerun. +- Reactive scopes cannot be created directly within another reactive scope. +- When a scope is destroyed, all scopes created within are also destroyed. + +Different functions in Vide's API will run code in different scopes. :::warning Yielding is not allowed in any stable or reactive scope. Strict mode will check for this. ::: -## root() +## root() STABLE -Creates and runs a function in a new stable scope. +Runs a function in a new stable scope. - **Type** ```luau - function root(fn: (() -> ()) -> T...): (() -> (), T...) + function root(fn: (Destructor) -> T...): (Destructor, T...) + + type Destructor = () -> () ``` - **Details** - Returns a function to destroy the root scope. Also passes this function as - the first argument into its callback. - - All values returned by the callback are also returned following the destructor. + Returns a destructor and any values returned by the callback. ## source() -Creates a new source with the given value. +Creates a new source. - **Type** @@ -40,71 +48,64 @@ Creates a new source with the given value. - **Details** - Calling the returned source with no argument will return its stored value, - calling with an argument will set a new value. + Call the returned source with no argument to read its value. + Call the returned source with an argument to set its value. - **Example** ```luau local count = source(0) - - count() -- 0 - - count(count() + 1) -- 1 + print(count())-- 0 + count(count() + 1) + print(count()) -- 1 ``` -## effect() +## effect() REACTIVE -Runs a side-effect in a new reactive scope on source update. +Runs a function in a new reactive scope. - **Type** ```luau - function effect(callback: () -> ()) + function effect(fn: () -> ()) ``` - **Details** - Any time a source referenced in the callback is updated, the callback will - be reran. - - The callback is ran once immediately. + The function is ran once immediately. - **Example** ```luau - local num = source(1) + local count = source(1) effect(function() - print(num()) + print(count()) end) -- prints 1 - num(num() + 1) + count(2) -- prints 2 ``` -## derive() +## derive() REACTIVE -Derives a new source in a new reactive scope from existing sources. +Runs a function in a new reactive scope to compute a value for new source. - **Type** ```luau - function derive(source: () -> T): () -> T + function derive(fn: () -> T): () -> T ``` - **Details** - The derived source will have its value recalculated when any source source - it derives from is updated. + Anytime the reactive scope reruns, the output source value is set to what is + returned. - Anytime its value is recalculated it is also cached, subsequent calls will - retun this cached value until it recalculates again. - - The callback is ran once immediately. + The function is ran once immediately. - **Example** @@ -112,11 +113,43 @@ Derives a new source in a new reactive scope from existing sources. local count = source(0) local text = derive(function() return `count: {count()}` end) - text() -- "count: 0" + print(text()) -- "count: 0" count(1) - text() -- "count: 1" + print(text()) -- "count: 1" ``` --------------------------------------------------------------------------------- + A `derive()` should be used instead of a pure function when you expect it to + be read multiple times between updates, because `derive()` will cache the + result to prevent recomputing it on every read. + + ::: code-group + + ```luau [Pure Function] + local count = source(0) + + local text = function() + print "ran" + return `count: {count()}` + end + + count(1) + print(text()) -- prints "ran" followed by "count: 1" + print(text()) -- prints "ran" followed by "count: 1" + ``` + + ```luau [Derived Source] + local count = source(0) + + local text = derive(function() -- [!code highlight] + print "ran" + return `count: {count()}` + end) -- [!code highlight] + + count(1) -- prints "ran" + print(text()) -- prints "count: 1" + print(text()) -- prints "count: 1" + ``` + + ::: diff --git a/docs/api/reactivity-dynamic.md b/docs/api/reactivity-dynamic.md new file mode 100644 index 0000000..a3e5168 --- /dev/null +++ b/docs/api/reactivity-dynamic.md @@ -0,0 +1,212 @@ +# Reactivity: Dynamic Scoping + +Dynamic scoping is the act of creating and destroying new scopes in response to +source updates. Vide provides functions for some common use-cases to do this. + +## show() REACTIVE + +Shows a component if the source is truthy. Optionally shows a fallback component +if the source is falsey. + +- **Type** + + ```luau + function show(source: () -> unknown, component: () -> T): () -> T? + function show(source: () -> unknown, component: () -> T, fallback: () -> U): () -> T | U + ``` + +- **Details** + + Creates a reactive scope internally to detect source updates. + + The component is run in a stable scope when truthy, otherwise the stable + scope is destroyed. + + Returns a source holding an instance of the currently shown component or + `nil` if no component is currently shown. + +## switch() REACTIVE + +Shows one of a set of components depending on a source and a mapping table. + +- **Type** + + ```luau + function switch(source: () -> K): (map: Map V>) () -> V? + ``` + +- **Details** + + Creates a reactive scope internally to detect source updates. + + When the source updates, its value is inputted into a map to get a component + constructor. This component is then run in a stable scope. The previous + stable scope is destroyed. + + Returns a source holding an instance of the currently shown component or + `nil` if no component is currently shown. + +- **Example** + + ```luau + local logged = source(false) + + local button = switch(logged) { + [true] = function() + return Button { Text = "Log out", Toggle = logged } + end, + + [false] = function() + return Button { Text = "Log in", Toggle = logged } + end + } + ``` + +## indexes() REACTIVE + +Shows a component for each index in a table. + +- **Type** + + ```luau + function indexes( + source: () -> Map, + transform: (value: () -> VI, index: KI) -> VO + ): Array + +- **Details** + + Creates a reactive scope internally to detect source updates. + + When the source table updates, a component is generated for each index in + the table. + + - For any added index, the `transform` function is run in a new stable + scope to produce an instance that is cached. + - For any removed index, the stable scope for that index is destroyed. + + The `transform` function is called with: + + 1. A *source containing the index's value*. + 2. The *index itself*. + + Anytime an existing index's value changes, the `transform` function is not + rerun, instead, that index's corresponding source is updated with the new + value. + + Returns a source holding an array of instances currently shown. + +- **Example** + + ```luau + type Item = { + name: string, + icon: number + } + + local items = source {} :: () -> Array + + local displays = indexes(items, function(item, i) + return ItemDisplay { + Name = function() + return i .. ": " .. item().name + end, + + Image = function() + return "rbxassetid://" .. item().icon + end, + } + end) + ``` + +## values() REACTIVE + +Shows a component for each value in a table. + +- **Type** + + ```luau + function values( + source: () -> Map, + transform: (value: VI, index: () -> KI) -> VO + ): Array + +- **Details** + + Operates with the same idea as `indexes()`, but applied to values instead of + indexes. + + Creates a reactive scope internally to detect source updates. + + When the source table updates, a component is generated for each value in + the table. + + - For any added value, the `transform` function is run in a new stable scope + to produce an instance that is cached. + - For any removed value, the stable scope for that value is destroyed. + + The `transform` function is called with: + + 1. The *value itself*. + 2. A *source containing the value's index*. + + Anytime an existing value's index changes, the `transform` function is not + rerun, instead, that value's corresponding source is updated with the new + index. + + Returns a source holding an array of instances currently shown. + + ::: warning + Having the same values appear multiple times in the input source table can + cause unexpected behavior. Strict mode has checks for this. + ::: + +- **Example** + + ```luau + type Item = { + name: string, + icon: number + } + + local items = source {} :: () -> Array + + local displays = values(items, function(item, i) + return ItemDisplay { + Name = function() + return i() .. ": " .. item.Name + end + + Image = "rbxassetid://" .. item.icon, + } + end) + ``` + +- **Extra** + + When should you use `indexes()` and `values()`? + + `values()` should be used when you have a fixed set of objects where the + same objects can be re-arranged in the source table. It maps a value to a + UI element. + + e.g. + - List of all players. + - Inventory of items. + - Chat message history. + - Toast notifications. + + `indexes()` should be used in other cases, especially when your source table + has primitive values. It maps an index to a UI element. + + e.g. + - List of character or weapon stats. + + In most cases, both functions will produce the same observed result. + The main difference is performance, picking the right function to use can + result in less property updates and less re-renders. One case to note is + that `values()` works nicely when animating re-ordering of instances, since + the source index can be used to animate a change in position for the UI + element. + +-------------------------------------------------------------------------------- diff --git a/docs/api/reactivity-flow.md b/docs/api/reactivity-flow.md deleted file mode 100644 index 03aea97..0000000 --- a/docs/api/reactivity-flow.md +++ /dev/null @@ -1,218 +0,0 @@ -# Reactivity API: Control Flow - -
- -## show() - -Shows one of two components depending on an input source. - -- **Type** - - ```luau - function show(source: () -> unknown, component: () -> T): () -> T? - function show(source: () -> unknown, component: () -> T, fallback: () -> U): () -> T | U - ``` - -- **Details** - - Returns a source holding an instance of the currently shown component. - - When the input source changes from a falsey to a truthy value, the - component will be reran under a new stable scope. If it changes from a - truthy to falsey value, the stable scope the component was created in will - be destroyed, and the returned source will output `nil`, or a fallback - component if given. - - The fallback component is also ran under a new stable scope, and destroyed - when the input source switches back to truthy. - -## switch() - -Shows one of a set of components depending on an input source and a mapping table. - -- **Type** - - ```luau - function switch(source: () -> K): (map: Map V>) -> V? - ``` - -- **Details** - - Returns a source holding an instance of the currently shown component. - - When the input source changes, the new value will be used to lookup a given - mapping table to get a component, which will be ran under a new stable - scope. If the input source changes, the stable scope the component was - created in will be destroyed, and a new component created under a new - stable scope. If no component is found for an input value, the switch will - output `nil`. - -- **Example** - - ```luau - local logged = source(false) - - local button = switch(logged) { - [true] = function() - return Button { Text = "Log out", Toggle = logged } - end, - - [false] = function() - return Button { Text = "Log in", Toggle = logged } - end - } - ``` - -## indexes() - -Maps each index in a table source to an object. - -- **Type** - - ```luau - function indexes( - source: () -> Map, - transform: (value: () -> VI, index: KI) -> VO - ): Array - -- **Details** - - Returns a source holding an array of instances currently shown. - - When the input source changes, each *index* in the new table is compared with - the last input table. - - - For any new index, the `transform` function is ran under a new stable - scope to produce a new instance. - - For any removed index, the stable scope for that index is destroyed. - - Unchanged indexes are untouched. - - The transform function is called only ever *once* for each index in the - source table. - - 1. First argument is a *source containing the index's value*. - 2. Second argument is the *index itself*. - - Anytime an existing index's value changes, the transform function is not - rerun, instead the source value for that index will update, causing anything - depending on it to update too. - -- **Example** - - The intended purpose of this function is to map each index in a table to - a UI element. - - ```luau - type Item = { - name: string, - icon: number - } - - local items = source {} :: () -> Array - - local displays = indexes(items, function(item, i) - return ItemDisplay { - Name = function() - return i .. ": " .. item().name - end, - - Image = function() - return "rbxassetid://" .. item().icon - end, - } - end) - ``` - -## values() - -Maps each value in a table source to an object. - -- **Type** - - ```luau - function values( - source: () -> Map, - transform: (value: VI, index: () -> KI) -> VO - ): Array - -- **Details** - - Returns a source holding an array of instances currently shown. - - When the input source changes, each *value* in the new table is compared with - the last input table. Similar to `indexes()` but for values instead of indexes. - - - For any new value, the `transform` function is ran under a new stable - scope to produce a new instance. - - For any removed value, the stable scope for that value is destroyed. - - Unchanged values are untouched. - - The transform function is only ever called *once* for each value in the - source table. - - 1. First argument is the *value itself*. - 2. Second argument is a *source containing the value's index*. - - Anytime an existing value's index changes, the transform function is not - rerun, instead the source index for that value will update, causing anything - depending on it to update too. - - ::: warning - Having primitive values in the input source table can cause unexpected - behavior, as duplicate values can result in multiple tranforms being ran for - a single value, meaning there can be multiple source indexes bound to the - same UI element. Strict mode has checks for this. - ::: - -- **Example** - - The intended purpose of this function is to map each value in a table to - a UI element. - - ```luau - type Item = { - name: string, - icon: number - } - - local items = source {} :: () -> Array - - local displays = values(items, function(item, i) - return ItemDisplay { - Name = function() - return i() .. ": " .. item.Name - end - - Image = "rbxassetid://" .. item.icon, - } - end) - ``` - -- **Extra** - - When should you use `indexes()` and `values()`? - - `values()` should be used when you have a fixed set of objects where the - same objects can be re-arranged in the source table. It maps a value to a - UI element. - - e.g. - - List of all players. - - Inventory of items. - - Chat message history. - - Toast notifications. - - `indexes()` should be used in other cases, especially when your source table - has primitive values. It maps an index to a UI element. - - e.g. - - List of character or weapon stats. - - In most cases, both functions will appear to have the same behavior. - The main difference is performance, picking the right function to use can - result in less property updates and less re-renders. One case to note is - that `values()` works nicely when animating re-ordering of instances, since - the value is not destroyed when indexes are changed, and the source index - can be used to animate a change in position for the UI element. - --------------------------------------------------------------------------------- diff --git a/docs/api/reactivity-utility.md b/docs/api/reactivity-utility.md index 6f719e1..d084976 100644 --- a/docs/api/reactivity-utility.md +++ b/docs/api/reactivity-utility.md @@ -1,16 +1,15 @@ -# Reactivity API: Utility +# Reactivity: Utility ## cleanup() -Runs a callback anytime a scope is reran or destroyed. +Queues a callback to run when a scope is reran or destroyed. - **Type** ```luau - function cleanup(callback: () -> ()) - function cleanup(obj: Destroyable) - function cleanup(obj: Disconnectable) + function cleanup(v: Function | Disconnectable | Destroyable) + type Function = () -> () type Destroyable = { destroy: () -> () } type Disconnectable = { disconnect: () -> () } ``` @@ -18,20 +17,27 @@ Runs a callback anytime a scope is reran or destroyed. - **Example** ```luau - local data = source(1) + local count = source(0) - effect(function() - local label = create "TextLabel" { Text = data() } + local destroy = root(function() + effect(function() + count() - cleanup(function() - label:Destroy() + cleanup(function() + print "cleaned" + end) end) - end) + end + + -- nothing printed yet + count(1) -- prints "cleaned" + count(2) -- prints "cleaned" + destroy() -- prints "cleaned" ``` -## untrack() +## untrack() STABLE -Runs a given function in a new stable scope. +Runs a function in a new stable scope. - **Type** @@ -55,16 +61,15 @@ Runs a given function in a new stable scope. end) print(sum()) -- 0 - b(1) + b(1) -- untracked so reactive scope created by derive() does not rerun print(sum()) -- 0 - a(1) + a(1) -- reactive scope created by derive() reruns print(sum()) -- 2 ``` ## read() -Utility used to read a value that is either a primitive or a source. Sources -read can still be tracked inside a reactive scope. +Utility used to read a value that is either a primitive or a source. - **Type** @@ -74,8 +79,8 @@ read can still be tracked inside a reactive scope. ## batch() -Runs a given function where any source updates made within the function do not -trigger effects until after the function finishes running. +Runs a function where any source updates made within the function do not +trigger effects until after the function ends. - **Type** @@ -86,11 +91,29 @@ trigger effects until after the function finishes running. - **Details** Improves performance when an effect depends on multiple sources, and those - sources need to be updated. Updating those sources inside a batch call will - only cause the effect to run once after the batch call ends instead of after - each time a source is updated. + sources need to be updated. -## context() +- **Example** + + ```luau + local a = source(0) + local b = source(0) + + effect(function() + print(a() + b()) + end) + + -- prints "0" + + batch(function() + a(1) -- no print + b(2) -- no print + end) + + -- prints "3" + ``` + +## context() STABLE Creates a new context. @@ -101,15 +124,17 @@ Creates a new context. type Context = () -> T -- get - & (T, () -> ()) -> () -- set + & (T, () -> U) -> U -- set ``` - **Details** Calling `context()` returns a new context function. Call this function with no arguments to get the context value. - Call this function with a value and a callback to set a new context with the - given value. + Call this function with a value and a function to create a new context with + the given value. + + The new context is run under a stable scope. - **Example** @@ -131,4 +156,3 @@ Creates a new context. end) ``` --------------------------------------------------------------------------------- diff --git a/docs/api/strict-mode.md b/docs/api/strict-mode.md index b3cae5b..d3ce5cb 100644 --- a/docs/api/strict-mode.md +++ b/docs/api/strict-mode.md @@ -14,25 +14,23 @@ and identifying improper usage. Currently, strict mode will: -1. Run derived sources twice a source updates. -2. Run effects twice when a source updates. -3. Throw an error if yields occur where they are not allowed. -4. Checks for `indexes()` and `values()` returning primitive values. -5. Checks for `values()` input having duplicate values. -6. Checks for duplicate nested properties at same depth. -7. Better error reporting and stack traces + creation traces of property bindings. +1. Run reactive scopes twice when a source updates. +2. Throw an error if yields occur where they are not allowed. +3. Checks for `indexes()` and `values()` outputting primitive values. +4. Checks for `values()` input having duplicate values. +5. Checks for duplicate nested properties at same depth. +6. Better error reporting and stack traces + creation traces of property bindings. -By rerunning derived sources and effects twice each time they update, it helps -ensure that derived source computations are pure, and that any -cleanups made in derived sources or effects are done correctly. +By rerunning reactive scopes twice each time they update, it helps ensure that +computations are pure, and that any cleanup is done correctly. Accidental yielding within reactive scopes can break Vide's reactive graph, which strict mode will catch. As well as additional safety checks, Vide will dedicate extra resources to recording and better emitting stack traces where errors occur, particularly -when binding properties to sources. +when implicit effects are created for instance property updating. It is recommended to develop UI with strict mode and to disable it when pushing to -production. In Roblox, production code compiles at O2 by default, so you don't +production. In Roblox, production code compiles at O2 by default, so you do not need to worry about disabling strict mode unless you have manually enabled it. diff --git a/docs/tut/advanced/nested-scoping.md b/docs/tut/advanced/nested-scoping.md deleted file mode 100644 index 0542ccc..0000000 --- a/docs/tut/advanced/nested-scoping.md +++ /dev/null @@ -1,192 +0,0 @@ -# Nested Scopes - -Nesting scopes gives you finer control over the reactive graph, but needs more work to do. The built-in control flow functions try to cover the -most common cases, but they do not cover all of them. - -This tutorial will demonstrate how to implement a `show()` control flow function -using just sources and effects. - -```luau -local mount = vide.mount -local source = vide.source -local show = vide.show - -local function Counter() - local count = source(0) - - return create "TextButton" { - Text = count, - Activated = function() count(count() + 1) end - } -end - -root(function() - local toggled = source(true) - - show(toggled, Button) -end) -``` - -```mermaid -%%{init: { - "theme": "base", - "themeVariables": { - "primaryColor": "#1B1B1F", - "primaryTextColor": "#fff", - "primaryBorderColor": "#1B1B1F", - "lineColor": "#79B8FF", - "tertiaryColor": "#161618", - "tertiaryBorderColor": "#1C1C1F" - } -}}%% - -graph - -subgraph mount - direction LR - toggle --> show - - subgraph show[show effect] - text[Text effect] - end -end -``` - -Above is the reactive graph for `show()`. It creates a new effect depending on -`toggle` where anytime `toggle` is truthy, it will create a new `Counter`. The -`show` effect calls `Counter`, which creates a new reactive scope to update its -text whenever `count` changes. As per the rules of reactive scopes, a reactive -scope rerunning will destroy any scopes created within it. So the text -effect's reactive scope is destroyed whenever the show effect is rerun. - -The same can be achieved without the use of `show()`: - -```luau -local mount = vide.mount -local source = vide.source -local effect = vide.effect -local cleanup = vide.cleanup - -local function Counter() - local count = source(0) - - return create "TextButton" { - Text = count, - Activated = function() count(count() + 1) end - } -end - -mount(function() - local toggled = source(true) - - effect(function() - if toggled() then - local destroy = root(function() - Counter() - end) - cleanup(destroy) - end - end) -end) -``` - -```mermaid -%%{init: { - "theme": "base", - "themeVariables": { - "primaryColor": "#1B1B1F", - "primaryTextColor": "#fff", - "primaryBorderColor": "#1B1B1F", - "lineColor": "#79B8FF", - "tertiaryColor": "#161618", - "tertiaryBorderColor": "#1C1C1F" - } -}}%% - -graph - -subgraph mount - direction LR - toggle --> effect - - subgraph effect - subgraph mount2[inner mount] - text[Text effect] - end - end -end -``` - -This is another way to achieve the same. Here we use `root()` within the effect -to manually create and destroy a new stable scope whenever the effect reruns. - -The reason for creating a stable scope is to prevent the effect from tracking -any sources that may be read inside the `Counter()` call. Otherwise, the effect -may be rerun needlessly and recreate the counter. - -Alternatively, instead of using `root()`: - -```luau -local mount = vide.mount -local source = vide.source -local effect = vide.effect -local untrack = vide.untrack - -local function Counter() - local count = source(0) - - return create "TextButton" { - Text = count, - Activated = function() count(count() + 1) end - } -end - -mount(function() - local toggled = source(true) - - effect(function() - if toggled() then - untrack(Button) - end - end) -end) -``` - -```mermaid -%%{init: { - "theme": "base", - "themeVariables": { - "primaryColor": "#1B1B1F", - "primaryTextColor": "#fff", - "primaryBorderColor": "#1B1B1F", - "lineColor": "#79B8FF", - "tertiaryColor": "#161618", - "tertiaryBorderColor": "#1C1C1F" - } -}}%% - -graph - -subgraph mount - direction LR - toggle --> effect - - subgraph effect - text[Text effect] - end -end -``` - -Without the use of `untrack()`, an error would occur, since Vide does not allow -the creation of reactive scopes inside reactive scopes. `untrack()` creates a -stable scope inside the reactive scope, and we can create another reactive scope -inside that stable scope. The -reason for this, is because if the `Counter` component reads from a source -internally, that can cause the reactive scope calling `Counter()` to track that -source, causing unintentional reruns. As a guard against this, you are forced to -use `untrack()` to create nested reactive scopes. - -The final result is the same as using the `show()` component. An effect is -created which creates the counter, which creates its own reactive scope. The -effect rerunning causes the counter's internal reactive scope to be destroyed, -making sure everything is cleaned up. diff --git a/docs/tut/control-flow/1-intro.md b/docs/tut/control-flow/1-intro.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/tut/control-flow/2-show.md b/docs/tut/control-flow/2-show.md deleted file mode 100644 index 8628e45..0000000 --- a/docs/tut/control-flow/2-show.md +++ /dev/null @@ -1 +0,0 @@ -# show() diff --git a/docs/tut/control-flow/3-switch.md b/docs/tut/control-flow/3-switch.md deleted file mode 100644 index 647835a..0000000 --- a/docs/tut/control-flow/3-switch.md +++ /dev/null @@ -1 +0,0 @@ -# switch() diff --git a/docs/tut/control-flow/4-indexes.md b/docs/tut/control-flow/4-indexes.md deleted file mode 100644 index aad2c90..0000000 --- a/docs/tut/control-flow/4-indexes.md +++ /dev/null @@ -1 +0,0 @@ -# indexes() diff --git a/docs/tut/control-flow/5-values.md b/docs/tut/control-flow/5-values.md deleted file mode 100644 index 8909904..0000000 --- a/docs/tut/control-flow/5-values.md +++ /dev/null @@ -1 +0,0 @@ -# values() diff --git a/docs/tut/crash-course/1-introduction.md b/docs/tut/crash-course/1-introduction.md index 983f51b..564aa2d 100644 --- a/docs/tut/crash-course/1-introduction.md +++ b/docs/tut/crash-course/1-introduction.md @@ -6,10 +6,16 @@ Vide is heavily inspired by [Solid](https://www.solidjs.com/). ## Why Vide? -Vide provides a reactive and declarative API to simplify managing UI. +Vide's reactive and declarative API aims to let you program UI as simply as +possible, with a strong focus on how data flows through your application. -Some of the main focuses behind Vide's design choices: +Some of Vide's main design choices: -- Minimal syntax -- Complete typechecking -- Independence from instances +- Syntax minimal. +- Data oriented. +- Typechecking compatible. +- Instance independent. + +Vide's reactivity operates with the concept +of scopes which carries a learning curve, though is what makes Vide's minimal +syntax possible. The crash course will introduce these concepts gradually. diff --git a/docs/tut/crash-course/10-cleanup.md b/docs/tut/crash-course/10-cleanup.md index e498c23..e25d451 100644 --- a/docs/tut/crash-course/10-cleanup.md +++ b/docs/tut/crash-course/10-cleanup.md @@ -9,10 +9,10 @@ destroyed, or when a stable scope is destroyed. local root = vide.root local source = vide.source local effect = vide.effect +local cleanup = vide.cleanup local count = source(0) - local destroy = root(function() effect(function() local x = count() diff --git a/docs/tut/crash-course/11-control-flow.md b/docs/tut/crash-course/11-control-flow.md deleted file mode 100644 index 298ce93..0000000 --- a/docs/tut/crash-course/11-control-flow.md +++ /dev/null @@ -1,98 +0,0 @@ -# Control Flow - -Eventually you may need a way to dynamically create and destroy UI elements -resulting from source updates. Vide provides functions to help you do this, -known as *control flow* functions. - -These functions return new sources, which hold the instances to be displayed. -The new sources can be used in `create()` to update the children of a container -instance. - -## indexes() - -`indexes()` *maps* each table index to a new UI element that can -update to display the current value at that index. Each table index is given a -single corresponding UI element. - -```luau -local list = source { - "finish the crash course", - "star Vide's GitHub" -} - -local function TodoList(props: { list: () -> Array }) - return create "Frame" { - create "UIListLayout" {}, - - indexes(list, function(todo, i) - return create "TextLabel" { - Text = function() - return i .. ": " .. todo() - end, - - LayoutOrder = i - } - end) - } -end - -TodoList { list = list } -``` - -For each index in the given source table, the given function to `indexes()` will -be run in a new stable scope with: - -1. a source containing the value at the index -2. the index itself - -When the value at an index is changed, the function is not reran. Instead, the -given source for that index is updated. - -Any time the input source table is updated, the given function will be ran for -any newly added indexes, while any removed indexes (indexes now with a `nil` -value), will have its corresponding stable scope destroyed. - - - -The reactive graph for the above example: - -```mermaid -%%{init: { - "theme": "base", - "themeVariables": { - "primaryColor": "#1B1B1F", - "primaryTextColor": "#fff", - "primaryBorderColor": "#1B1B1F", - "lineColor": "#79B8FF", - "tertiaryColor": "#161618", - "tertiaryBorderColor": "#1C1C1F" - } -}}%% - -graph - -subgraph root ["root scope"] - direction LR - todoList --> indexes -.- subroot1 & subroot2 - - subgraph subroot1 ["indexes scope 1"] - direction LR - value1[todo] --> prop1["prop binding"] - end - - subgraph subroot2 ["indexes scope 2"] - direction LR - value2[todo] --> prop2[prop binding] - end -end -``` - -When you edit a table in a source, you must set that table again to actually -update the source. - -```luau -local src = source { 1, 2 } -local data = src() -table.insert(data, 3) -- no effects will run -src(data) -- effects will run -``` diff --git a/docs/tut/crash-course/11-dynamic-scope.md b/docs/tut/crash-course/11-dynamic-scope.md new file mode 100644 index 0000000..aa2695b --- /dev/null +++ b/docs/tut/crash-course/11-dynamic-scope.md @@ -0,0 +1,158 @@ +# Dynamic Scoping + +Eventually you may need a way to dynamically create and destroy UI elements +resulting from source updates. Vide provides functions to help you do this, +known as *dynamic scope* functions. + +These functions create and destroy components for you in response to source +updates. They return a source containing the created component. This source can +be parented as a child which will update the shown children whenever the source +updates. + +The simplest example is using `show()`. + +```luau +local source = vide.source +local create = vide.create +local show = vide.show +local root = vide.root + +function Button(props: { Text: string, Activated: () -> () }) + return create "TextButton" { + Text = props.Text, + Activated = props.Activated + } +end + +function Menu() + return create "TextLabel" { + Text = "This is a menu" + } +end + +function App() + local toggled = source(false) + + return create "ScreenGui" { + Button { + Text = "Toggle Menu", + Activated = function() + toggled(not toggled()) + end + }, + + show(toggled, Menu) -- [!code highlight] + } +end + +root(function() + App().Parent = game.StarterGui +end) +``` + +This is a complete example of rendering UI which has a single button that +toggles the opening of a menu. + +-------------------------------------------------------------------------------- + +Another common function is `indexes()`. This function creates a component for +each index in a table. + +Each component created is done so in a new and independent stable scope. The +indexes of the table are checked each source update to prevent redunant +destruction and recreation of UI elements. + +```luau +local source = vide.source +local create = vide.create +local indexes = vide.indexes +local root = vide.root + +local function Todo(props: { + Text: () -> string, + Position: number, + Activated: () -> () +}) + return create "TextButton" { + Text = function() return props.Position .. ": " .. props.Text() end, + LayoutOrder = props.Position, + Activated = Activated + } +end + +local function TodoList(props: { List: () -> Array }) + return create "Frame" { + create "UIListLayout" {}, + + indexes(props.List, function(text, i) -- [!code highlight] + return Todo { + Text = text, + Position = i, + Activated = function() -- remove the todo when clicked + local list = props.List() + table.remove(list, i) + props.List(list) + end + } + end) + } +end + +function App() + local list = source { + "finish the crash course", + "star Vide's GitHub" + } + + return create "ScreenGui" { + TodoList { List = list }, + } +end + +root(function() + App().Parent = game.StarterGui +end) +``` + +The reactive graph for the above example: + +```mermaid +%%{init: { + "theme": "base", + "themeVariables": { + "primaryColor": "#111720", + "primaryTextColor": "#fff", + "primaryBorderColor": "#111720", + "lineColor": "#79B8FF", + "tertiaryColor": "#0d131b", + "tertiaryBorderColor": "#0d131b" + } +}}%% + +graph + +subgraph root ["root"] + direction LR + todoList --> indexes -.- subroot1 & subroot2 + + subgraph subroot1 ["indexes scope 1"] + direction LR + value1[todo] --> prop1["prop binding"] + end + + subgraph subroot2 ["indexes scope 2"] + direction LR + value2[todo] --> prop2[prop binding] + end +end +``` + +When you edit a table in a source, you must set that table again to actually +update the source. + +```luau +local src = source { 1, 2 } +local data = src() +table.insert(data, 3) -- no effects will run +src(data) -- effects will run +``` diff --git a/docs/tut/crash-course/12-actions.md b/docs/tut/crash-course/12-actions.md index 64d3fce..ba02618 100644 --- a/docs/tut/crash-course/12-actions.md +++ b/docs/tut/crash-course/12-actions.md @@ -1,13 +1,11 @@ # Actions -Actions in Vide are special callbacks that you can pass along with properties, +Actions are special callbacks that you can pass along with properties, to run some code on an instance receiving them. ```luau local action = vide.action -``` -```luau create "TextLabel" { Text = "test", @@ -24,6 +22,7 @@ action used to listen for property changes: ```luau local action = vide.action +local source = vide.source local effect = vide.effect local cleanup = vide.cleanup @@ -49,7 +48,7 @@ effect(function() print(output()) end) -instance.Text = "foo" -- "foo" will be printed from the effect +instance.Text = "foo" -- "foo" will be printed by the effect ``` The source `output` will be updated with the new property value any time it is diff --git a/docs/tut/crash-course/13-strict-mode.md b/docs/tut/crash-course/13-strict-mode.md index f2b30fe..0de8887 100644 --- a/docs/tut/crash-course/13-strict-mode.md +++ b/docs/tut/crash-course/13-strict-mode.md @@ -23,6 +23,7 @@ local count = source(0) local ran = 0 effect(function() + count() ran += 1 end) diff --git a/docs/tut/crash-course/14-concepts.md b/docs/tut/crash-course/14-concepts.md index 77e9e7f..8ed6a1a 100644 --- a/docs/tut/crash-course/14-concepts.md +++ b/docs/tut/crash-course/14-concepts.md @@ -30,7 +30,7 @@ Created by: - `root()` - `untrack()` -- `switch()` +- `show()` - `indexes()` Stable scopes do not track sources and never rerun. @@ -47,23 +47,14 @@ Created by: Reactive scopes do track sources and will rerun when those sources update. Reactive scopes cannot be created within a reactive scope, but stable scopes -can. +can be created within a reactive scope. -## Scope Owners +## Scope Cleanup -A scope created within another scope is *owned* by the other scope, with the -exception of the scope created by `root()`. +When a scope is rerun or destroyed, all scopes created within it are +automatically destroyed. -When a scope is rerun or destroyed, all scopes owned by it are automatically -destroyed. - -`root()` creates a stable scope with no owner, instead it is destroyed manually. - -## Cleanup - -Arbitrary code to run whenever a stable or reactive scope is rerun or destroyed. - -Queue a function to run using `cleanup()`. +Any functions queued by `cleanup()` are also ran. ## Reactive Graph @@ -93,12 +84,12 @@ end) %%{init: { "theme": "base", "themeVariables": { - "primaryColor": "#1B1B1F", + "primaryColor": "#111720", "primaryTextColor": "#fff", - "primaryBorderColor": "#1B1B1F", + "primaryBorderColor": "#111720", "lineColor": "#79B8FF", - "tertiaryColor": "#161618", - "tertiaryBorderColor": "#1C1C1F" + "tertiaryColor": "#0d131b", + "tertiaryBorderColor": "#202530" } }}%% @@ -118,6 +109,5 @@ Notes: - An update to `count` will cause `text` to rerun, which then causes `effect` to rerun. - When the root scope is destroyed, `text` and - `effect` will be destroyed alongside it, since they are - owned by it. `count` will be untouched and future updates - to `count` will have no effect. + `effect` will be destroyed alongside it, since they were created within it. + `count` will be untouched and future updates to `count` will have no effect. diff --git a/docs/tut/crash-course/5-effect.md b/docs/tut/crash-course/5-effect.md index 29e6358..e435034 100644 --- a/docs/tut/crash-course/5-effect.md +++ b/docs/tut/crash-course/5-effect.md @@ -1,6 +1,6 @@ # Effects -Effects are functions that are ran in response to source updates. They are +Effects are functions that are ran in response to source updates. A source and effect is analogous to a signal and connection. Effects are created using `effect()`. @@ -23,7 +23,10 @@ count(1) Any source read inside an effect is tracked and will rerun the effect when that source is updated. -Derived sources are also tracked, it doesn't matter how deeply nested +The effect runs its callback once immediately to initially figure out what +sources are being read. + +Derived sources are also tracked, it does not matter how deeply nested inside a function a source is. ```luau @@ -47,3 +50,22 @@ count(2) If a source is updated with the same value it already had, it will not rerun effects depending on it. + +You can also read from a source within an effect without the effect tracking it. + +```lua +local source = vide.source +local effect = vide.effect +local untrack = vide.untrack + +local a = source(0) +local b = source(0) + +effect(function() + print(`a: {a()} b: {untrack(b)}`) +end) + +a(1) -- prints "a: 1 b: 0" +b(1) -- prints nothing +a(2) -- prints "a: 2 b: 1" +``` diff --git a/docs/tut/crash-course/6-scope.md b/docs/tut/crash-course/6-scope.md index 6c12088..a222e50 100644 --- a/docs/tut/crash-course/6-scope.md +++ b/docs/tut/crash-course/6-scope.md @@ -7,29 +7,31 @@ But the disconnecting of many signals and connections is tedious and verbose. Vide instead operates on the concept of scopes which provides a much cleaner API, given that you follow a few rules. -Scopes come in two flavors; stable and reactive. +Thre are two types of scopes: stable and reactive. -- All scopes must be created within another scope with the exception of `root()` -- Stable scopes never rerun -- Reactive scopes can rerun -- A reactive scope cannot be created within another reactive scope +- A scope must be created within another scope. +- Stable scopes never rerun. +- Reactive scopes can rerun. +- A reactive scope cannot be created within another reactive scope, only within + a stable scope. + +An exception to the first rule is `root()`, which creates the initial scope that +you destroy manually with a destructor function it returns. -`effect()` creates a reactive scope. `root()` creates a stable scope. +`effect()` creates a reactive scope. Whenever a scope is destroyed, any scope created within that scope is also -destroyed, and so on. This is why all scopes must be created within another -scope, except `root()` which is used to create the initial scope that you can -manually destroy. +destroyed, and so on. ```luau local root = vide.root local source = vide.source local effect = vide.effect -local function setup() - local count = source(0) +local count = source(0) +local function setup() effect(function() print(count()) end) @@ -37,32 +39,16 @@ local function setup() return count end -setup() -- will error since effect() tries to create a reactive scope outside of a stable scope +setup() -- error, effect() tried to create a reactive scope with no stable scope -local count = root(setup) -- ok since effect() was called within a stable scope -count(1) -- prints "1" -``` - -The scope created by `root()` can be destroyed. - -```luau -local function setup() - local count = source(0) - - effect(function() - print(count()) - end) - - return count -end - -local destroy, count = root(setup) +local destroy = root(setup) -- ok since effect() was called in a stable scope count(1) -- prints "1" +count(2) -- prints "2" destroy() -count(2) -- effect is destroyed; no longer prints +count(3) -- reactive scope created by effect() is destroyed, it does not rerun ``` Vide's reactivity can be represented graphically, as a *reactive graph*. @@ -73,12 +59,12 @@ The reactive graph for the above example looks like so: %%{init: { "theme": "base", "themeVariables": { - "primaryColor": "#1B1B1F", + "primaryColor": "#111720", "primaryTextColor": "#fff", - "primaryBorderColor": "#1B1B1F", + "primaryBorderColor": "#111720", "lineColor": "#79B8FF", - "tertiaryColor": "#161618", - "tertiaryBorderColor": "#161618" + "tertiaryColor": "#0d131b", + "tertiaryBorderColor": "#0d131b" } }}%% @@ -90,7 +76,7 @@ subgraph root end ``` -When the stable `root()` is destroyed, the reactive `effect()` +When the stable `root()` scope is destroyed, the reactive `effect()` scope will also be destroyed since it was created within it. This is important because you may have an effect that updates the property of a diff --git a/docs/tut/crash-course/7-stateful-component.md b/docs/tut/crash-course/7-reactive-component.md similarity index 91% rename from docs/tut/crash-course/7-stateful-component.md rename to docs/tut/crash-course/7-reactive-component.md index 5126c73..ff67ec8 100644 --- a/docs/tut/crash-course/7-stateful-component.md +++ b/docs/tut/crash-course/7-reactive-component.md @@ -1,10 +1,8 @@ -# Stateful Components +# Reactive Components -Stateful components in Vide are created using sources and effects - sources to +Reactive components in Vide are created using sources and effects - sources to store the data, and effects to display the data. -## Internal State - ```luau local create = vide.create local source = vide.source @@ -33,8 +31,6 @@ its internal count, and automatically update its text to reflect that count. Each instance of `Counter()` will maintain its own independent count, since the count source is created inside the component. -## External State - External sources can also be passed into components for them to use. ```luau diff --git a/docs/tut/crash-course/8-implicit-effect.md b/docs/tut/crash-course/8-implicit-effect.md index cdb75fb..3363bf6 100644 --- a/docs/tut/crash-course/8-implicit-effect.md +++ b/docs/tut/crash-course/8-implicit-effect.md @@ -3,7 +3,9 @@ Explicitly creating effects to update properties is tedious. You can *implicitly* create an effect to update properties instead. -```luau +::: code-group + +```luau [Implicit Effect] local create = vide.create local source = vide.source @@ -22,6 +24,30 @@ local function Counter() end ``` +```luau [Explicit Effect] +local create = vide.create +local source = vide.source +local effect = vide.effect + +local function Counter() + local count = source(0) + + local instance = create "TextButton" { + Activated = function() + count(count() + 1) + end + } + + effect(function() + instance.Text = "count: " .. count() + end) + + return instance +end +``` + +::: + This example is equivalent to the example seen on the previous page. Instead of explicitly creating an effect, assigning a (non-event) property a @@ -46,12 +72,12 @@ local function List(props: { children: () -> { Instance } }) } end -local list = List { children = items } -- creates a list with a single text label "A" +local list = List { children = items } -- creates a list with text label "A" items { create "TextLabel" { Text = "B" }, create "TextLabel" { Text = "C" } } --- this will automatically unparent the text label "A", and parent the labels "B" and "C" +-- this will automatically unparent text label "A", and parent labels "B" and "C" ``` diff --git a/docs/tut/crash-course/9-derived-source.md b/docs/tut/crash-course/9-derived-source.md index 19a6a5d..694d90b 100644 --- a/docs/tut/crash-course/9-derived-source.md +++ b/docs/tut/crash-course/9-derived-source.md @@ -57,7 +57,8 @@ effect(function() text() end) count(1) -- prints "ran" x1 ``` -`derive()` must also be called within a stable scope, just like `effect()`. +Because `derive()` creates a reactive scope, it must be called within a stable +scope, just like `effect()`. If the recalculated value is the same as the old value, the derived source will not rerun the effects using it. @@ -68,12 +69,12 @@ The reactive graph for the above example: %%{init: { "theme": "base", "themeVariables": { - "primaryColor": "#1B1B1F", + "primaryColor": "#111720", "primaryTextColor": "#fff", - "primaryBorderColor": "#1B1B1F", + "primaryBorderColor": "#111720", "lineColor": "#79B8FF", - "tertiaryColor": "#161618", - "tertiaryBorderColor": "#161618" + "tertiaryColor": "#0d131b", + "tertiaryBorderColor": "#0d131b" } }}%% @@ -86,7 +87,7 @@ end ``` Deriving a source in this manner is similar to creating an effect to update -another source. You should never manually do this using an effect however. +another source. You should avoid doing this using an effect however. Improper usage could accidently create infinite loops in the reactive graph. Always favour deriving when you need one source to update based on another source. diff --git a/docs/tut/dynamic-scoping/custom.md b/docs/tut/dynamic-scoping/custom.md new file mode 100644 index 0000000..fc4258b --- /dev/null +++ b/docs/tut/dynamic-scoping/custom.md @@ -0,0 +1,144 @@ +# Dynamic Scoping + +Dynamic scoping is the act of creating and destroying new scopes in response to +source updates. This is needed for conditionally rendering parts of your UI, +such as opening and closing menus. + +While Vide provides functions for common ways to do this, this section will +show how you can implement them yourself so you are not limited by only what is +provided. + +## Recreating [`show()`](/api/reactivity-dynamic#show-reactive) + +The most basic one, `show()`, can be +implemented yourself like so: + +```luau +local function show(toggle: () -> unknown, component: () -> Instance) + return derive(function() + return if toggle() then untrack(component) else nil + end) +end +``` + +The main thing to note here is the use of `untrack()`. This function runs its +callback in a new stable scope. Without this, if the component were to create +a reactive scope, an error would occur since a reactive scope cannot be created +within a reactive scope. + +```mermaid +%%{init: { + "theme": "base", + "themeVariables": { + "primaryColor": "#111720", + "primaryTextColor": "#fff", + "primaryBorderColor": "#444455", + "lineColor": "#79B8FF", + "tertiaryColor": "#0d131b", + "tertiaryBorderColor": "#444455" + } +}}%% + +graph + +subgraph derive ["derive (reactive)"] + + subgraph untrack ["untrack (stable)"] + subgraph effect ["effect (reactive)"] + + end + end +end +``` + +You can see from the above graph how the effect would not be created directly +inside the derive, there is a stable scope between them. This requirement exists +as a guard against unintentional rerendering of UI. + +## Recreating [`switch()`](/api/reactivity-dynamic#switch-reactive) + +```lua +local function switch(key) + return function(map) + return derive(function() + local component = map[key()] + return if component then untrack(component) else nil + end) + end +end +``` + +## Recreating [`indexes()`](/api/reactivity-dynamic#indexes-reactive) + +This is a more complicated function because it manages multiple scopes at the +same time, unlike the previous functions. Because some scopes may persist +between reruns, we cannot use `untrack()` anymore which automatically destroys +on rerun; we must use `root()` where the lifetime of each scope is managed +manually and independently. + + +```lua +local function indexes( + input: () -> Map, + transform: (value: () -> VI, index: I) -> VO +) + local index_caches = {} :: Map VI, + destroy: () -> () + }?> + + return derive(function() + local new_input = input() + + -- destroy scopes of removed indexes + for i, cache in index_caches do + if new_input[i] == nil then + assert(cache).destroy() + index_caches[i] = nil + end + end + + -- create scopes or update sources of added or changed index values + for i, v in new_input do + local cache = index_caches[i] + + if cache == nil then -- no scope created for this index, create one + local src = source(v) + + local destroy, result = root(function() + return transform(src, i) + end) + + index_caches[i] = { + destroy = destroy, + source = src, + output = result, + previous_input = v + } + elseif cache.previous_input ~= v then -- scope exists, update source + cache.previous_input = v + cache.source(v) + else -- scope exists and value has not changed; do nothing + end + end + + -- return the cached output values as an array + local array = table.create(#index_caches) + + for _, cache in index_caches do + table.insert(array, assert(cache).output) + end + + return array + end) +end +``` + +-------------------------------------------------------------------------------- + +Though the above functions are already provided to you by Vide, this serves as +an example for how you may create your own dynamic scope functions. + + From baf308ccf34370ea13107319e646e621900c50f3 Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Mon, 4 Nov 2024 23:27:28 +0000 Subject: [PATCH 05/22] Fix bug in code example --- docs/tut/dynamic-scoping/custom.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/tut/dynamic-scoping/custom.md b/docs/tut/dynamic-scoping/custom.md index fc4258b..7a2ee62 100644 --- a/docs/tut/dynamic-scoping/custom.md +++ b/docs/tut/dynamic-scoping/custom.md @@ -76,7 +76,6 @@ between reruns, we cannot use `untrack()` anymore which automatically destroys on rerun; we must use `root()` where the lifetime of each scope is managed manually and independently. - ```lua local function indexes( input: () -> Map, @@ -89,6 +88,13 @@ local function indexes( destroy: () -> () }?> + -- destroy all scopes if the parent scope is destroyed + cleanup(function() + for _, cache in index_caches do + assert(cache).destroy() + end + end) + return derive(function() local new_input = input() @@ -140,5 +146,3 @@ end Though the above functions are already provided to you by Vide, this serves as an example for how you may create your own dynamic scope functions. - - From bacb4fa0f0d8e407fe2467f7819798ba0f28fd02 Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Tue, 12 Nov 2024 15:08:12 +0000 Subject: [PATCH 06/22] Fix mistakes in docs --- docs/.vitepress/config.ts | 2 +- docs/api/reactivity-dynamic.md | 2 +- docs/tut/{dynamic-scoping => advanced}/custom.md | 4 ++-- docs/tut/crash-course/12-actions.md | 4 ++-- docs/tut/crash-course/14-concepts.md | 2 +- docs/tut/crash-course/5-effect.md | 2 +- docs/tut/crash-course/6-scope.md | 2 -- docs/tut/crash-course/7-reactive-component.md | 12 ++++-------- 8 files changed, 12 insertions(+), 18 deletions(-) rename docs/tut/{dynamic-scoping => advanced}/custom.md (99%) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 380542a..633059e 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -65,7 +65,7 @@ export default withMermaid({ { text: "Dynamic Scoping", items: [ - { text: "Custom Scopes", link: "/tut/dynamic-scoping/custom"} + { text: "Custom Scopes", link: "/tut/advanced/custom"} ] }, { diff --git a/docs/api/reactivity-dynamic.md b/docs/api/reactivity-dynamic.md index a3e5168..875c12f 100644 --- a/docs/api/reactivity-dynamic.md +++ b/docs/api/reactivity-dynamic.md @@ -32,7 +32,7 @@ Shows one of a set of components depending on a source and a mapping table. - **Type** ```luau - function switch(source: () -> K): (map: Map V>) () -> V? + function switch(source: () -> K): (map: Map V>): () -> V? ``` - **Details** diff --git a/docs/tut/dynamic-scoping/custom.md b/docs/tut/advanced/custom.md similarity index 99% rename from docs/tut/dynamic-scoping/custom.md rename to docs/tut/advanced/custom.md index 7a2ee62..99fe746 100644 --- a/docs/tut/dynamic-scoping/custom.md +++ b/docs/tut/advanced/custom.md @@ -57,7 +57,7 @@ as a guard against unintentional rerendering of UI. ## Recreating [`switch()`](/api/reactivity-dynamic#switch-reactive) -```lua +```luau local function switch(key) return function(map) return derive(function() @@ -76,7 +76,7 @@ between reruns, we cannot use `untrack()` anymore which automatically destroys on rerun; we must use `root()` where the lifetime of each scope is managed manually and independently. -```lua +```luau local function indexes( input: () -> Map, transform: (value: () -> VI, index: I) -> VO diff --git a/docs/tut/crash-course/12-actions.md b/docs/tut/crash-course/12-actions.md index ba02618..60e5c30 100644 --- a/docs/tut/crash-course/12-actions.md +++ b/docs/tut/crash-course/12-actions.md @@ -26,9 +26,9 @@ local source = vide.source local effect = vide.effect local cleanup = vide.cleanup -local function changed(prop: string, callback: (new) -> ()) +local function changed(property: string, callback: (new) -> ()) return action(function(instance) - local connection = instance:GetPropertyChangedSignal(prop):Connect(function() + local connection = instance:GetPropertyChangedSignal(property):Connect(function() callback(instance[property]) end) diff --git a/docs/tut/crash-course/14-concepts.md b/docs/tut/crash-course/14-concepts.md index 8ed6a1a..f33d043 100644 --- a/docs/tut/crash-course/14-concepts.md +++ b/docs/tut/crash-course/14-concepts.md @@ -69,7 +69,7 @@ local count = source(0) root(function() local text = derive(function() - return "count: " .. text() + return "count: " .. count() end) effect(function() diff --git a/docs/tut/crash-course/5-effect.md b/docs/tut/crash-course/5-effect.md index e435034..82768dc 100644 --- a/docs/tut/crash-course/5-effect.md +++ b/docs/tut/crash-course/5-effect.md @@ -53,7 +53,7 @@ effects depending on it. You can also read from a source within an effect without the effect tracking it. -```lua +```luau local source = vide.source local effect = vide.effect local untrack = vide.untrack diff --git a/docs/tut/crash-course/6-scope.md b/docs/tut/crash-course/6-scope.md index a222e50..7775647 100644 --- a/docs/tut/crash-course/6-scope.md +++ b/docs/tut/crash-course/6-scope.md @@ -35,8 +35,6 @@ local function setup() effect(function() print(count()) end) - - return count end setup() -- error, effect() tried to create a reactive scope with no stable scope diff --git a/docs/tut/crash-course/7-reactive-component.md b/docs/tut/crash-course/7-reactive-component.md index ff67ec8..339ee4f 100644 --- a/docs/tut/crash-course/7-reactive-component.md +++ b/docs/tut/crash-course/7-reactive-component.md @@ -34,14 +34,10 @@ count source is created inside the component. External sources can also be passed into components for them to use. ```luau -local function Counter(props: { count: () -> number }) +local function CountDisplay(props: { count: () -> number }) local count = props.count - local instance = create "TextButton" { - Activated = function() - count(count() + 1) - end - } + local instance = create "TextLabel" {} effect(function() instance.Text = "count: " .. count() @@ -52,11 +48,11 @@ end local count = source(0) -Counter { +CountDisplay { count = count } -count(1) -- the Counter component will update to display this count +count(1) -- the CountDisplay component will update to display this count ``` Sources can be created internally or passed in from externally, there are no From a1552402cb696c0087b06bcc36d648d1be4ec3fd Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Tue, 12 Nov 2024 15:15:16 +0000 Subject: [PATCH 07/22] Rename tutorial sections --- docs/.vitepress/config.ts | 6 +++--- docs/tut/advanced/{custom.md => dynamic-scopes.md} | 0 .../{11-dynamic-scope.md => 11-dynamic-scopes.md} | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) rename docs/tut/advanced/{custom.md => dynamic-scopes.md} (100%) rename docs/tut/crash-course/{11-dynamic-scope.md => 11-dynamic-scopes.md} (99%) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 633059e..37918e8 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -56,16 +56,16 @@ export default withMermaid({ { text: "Implicit Effects", link: "/tut/crash-course/8-implicit-effect" }, { text: "Derived Sources", link: "/tut/crash-course/9-derived-source" }, { text: "Cleanup", link: "/tut/crash-course/10-cleanup" }, - { text: "Dynamic Scoping", link: "/tut/crash-course/11-dynamic-scope" }, + { text: "Dynamic Scopes", link: "/tut/crash-course/11-dynamic-scopes" }, { text: "Actions", link: "/tut/crash-course/12-actions" }, { text: "Strict Mode", link: "/tut/crash-course/13-strict-mode" }, { text: "Concepts Summary", link: "/tut/crash-course/14-concepts" } ] }, { - text: "Dynamic Scoping", + text: "Advanced", items: [ - { text: "Custom Scopes", link: "/tut/advanced/custom"} + { text: "Dynamic Scopes", link: "/tut/advanced/dynamic-scopes"} ] }, { diff --git a/docs/tut/advanced/custom.md b/docs/tut/advanced/dynamic-scopes.md similarity index 100% rename from docs/tut/advanced/custom.md rename to docs/tut/advanced/dynamic-scopes.md diff --git a/docs/tut/crash-course/11-dynamic-scope.md b/docs/tut/crash-course/11-dynamic-scopes.md similarity index 99% rename from docs/tut/crash-course/11-dynamic-scope.md rename to docs/tut/crash-course/11-dynamic-scopes.md index aa2695b..bede8d8 100644 --- a/docs/tut/crash-course/11-dynamic-scope.md +++ b/docs/tut/crash-course/11-dynamic-scopes.md @@ -1,4 +1,4 @@ -# Dynamic Scoping +# Dynamic Scopes Eventually you may need a way to dynamically create and destroy UI elements resulting from source updates. Vide provides functions to help you do this, From 0897821e1fa3847b43d278fb6a287540ff55c3ea Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Wed, 13 Nov 2024 21:56:22 +0000 Subject: [PATCH 08/22] Add check for destruction of active scope --- docs/api/strict-mode.md | 3 ++- src/graph.luau | 8 ++++++- test/tests.luau | 53 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 62 insertions(+), 2 deletions(-) diff --git a/docs/api/strict-mode.md b/docs/api/strict-mode.md index d3ce5cb..630a7bd 100644 --- a/docs/api/strict-mode.md +++ b/docs/api/strict-mode.md @@ -19,7 +19,8 @@ Currently, strict mode will: 3. Checks for `indexes()` and `values()` outputting primitive values. 4. Checks for `values()` input having duplicate values. 5. Checks for duplicate nested properties at same depth. -6. Better error reporting and stack traces + creation traces of property bindings. +6. Checks for destruction of an active scope. +7. Better error reporting and stack traces + creation traces of property bindings. By rerunning reactive scopes twice each time they update, it helps ensure that computations are pure, and that any cleanup is done correctly. diff --git a/src/graph.luau b/src/graph.luau index 9648180..1495a59 100644 --- a/src/graph.luau +++ b/src/graph.luau @@ -108,6 +108,10 @@ local function unparent(node: Node) end local function destroy(node: Node) + if flags.strict and table.find(scopes, node) then + throw("attempt to destroy an active scope") + end + flush_cleanups(node) unparent(node) @@ -296,5 +300,7 @@ return table.freeze { flush_update_queue = flush_update_queue, get_update_queue_length = get_update_queue_length, set_context = set_context, - scopes = scopes + scopes = scopes, + + q = update_queue } diff --git a/test/tests.luau b/test/tests.luau index 45aa41f..395b568 100644 --- a/test/tests.luau +++ b/test/tests.luau @@ -2483,11 +2483,14 @@ end)) TEST("strict", wrap_root(function() vide.strict = true + local root = vide.root + local show = vide.show local create = vide.create local source = vide.source local derive = vide.derive local effect = vide.effect local indexes, values = vide.indexes, vide.values + local untrack = vide.untrack do CASE "error on derived callback yield" local src = source(1) @@ -2627,6 +2630,56 @@ TEST("strict", wrap_root(function() CHECK(count == 4) end + + do CASE "destruction of active scope" + local src = source(false) + + root(function() + show(src, function() + src(false) + return {} + end) + end) + + local ok = pcall(function() + src(true) + end) + + CHECK(not ok) + end + + -- todo: review intended behavior here + -- do CASE "destruction of active scope in indexes" + -- local src = source {} + + -- local tmp + -- root(function() + -- effect(function() + -- untrack(function() + -- tmp = indexes(src, function() + -- vide.cleanup(function() print "test" end) + -- src {} + -- print "updated" + -- vide.cleanup(function() print "test2" end) + -- print "end" + -- return {} + -- end) + -- return nil + -- end) + -- end) + -- end) + + -- print "setting" + + -- local ok = pcall(function() + -- src { 1 } + -- print "done" + -- end) + + -- print(#tmp()) + + -- CHECK(not ok) + -- end end)) local ok = FINISH() From 5abd5eee91ad01a79afacdba802766180d965ed2 Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Wed, 13 Nov 2024 22:19:20 +0000 Subject: [PATCH 09/22] Update require paths to relative string --- src/apply.luau | 17 ++++++++--------- src/batch.luau | 8 +++----- src/bind.luau | 4 +--- src/changed.luau | 6 ++---- src/cleanup.luau | 7 +++---- src/context.luau | 6 +++--- src/create.luau | 12 ++++++------ src/defaults.luau | 6 +++--- src/derive.luau | 4 +--- src/effect.luau | 4 +--- src/graph.luau | 6 ++---- src/init.luau | 42 ++++++++++++++++++++---------------------- src/maps.luau | 8 +++----- src/mount.luau | 6 ++---- src/read.luau | 2 -- src/root.luau | 6 ++---- src/show.luau | 4 +--- src/source.luau | 4 +--- src/spring.luau | 7 +++---- src/switch.luau | 6 ++---- src/throw.luau | 2 -- src/untrack.luau | 4 +--- test/benchmark.luau | 20 ++++++++++---------- test/spring-test.luau | 4 ++-- test/tests.luau | 18 +++++++++--------- 25 files changed, 89 insertions(+), 124 deletions(-) diff --git a/src/apply.luau b/src/apply.luau index 0f4586e..abb482c 100644 --- a/src/apply.luau +++ b/src/apply.luau @@ -1,13 +1,12 @@ -if not game then script = require "test/relative-string" end -local typeof = game and typeof or require "test/mock".typeof :: never -local Vector2 = game and Vector2 or require "test/mock".Vector2 :: never -local UDim2 = game and UDim2 or require "test/mock".UDim2 :: never +local typeof = game and typeof or require "../test/mock".typeof :: never +local Vector2 = game and Vector2 or require "../test/mock".Vector2 :: never +local UDim2 = game and UDim2 or require "../test/mock".UDim2 :: never -local flags = require(script.Parent.flags) -local throw = require(script.Parent.throw) -local bind = require(script.Parent.bind) -local _, is_action = require(script.Parent.action)() -local graph = require(script.Parent.graph) +local flags = require "./flags" +local throw = require "./throw" +local bind = require "./bind" +local _, is_action = require "./action"() +local graph = require "./graph" type Node = graph.Node type Array = { V } diff --git a/src/batch.luau b/src/batch.luau index 45ab038..4cd7581 100644 --- a/src/batch.luau +++ b/src/batch.luau @@ -1,8 +1,6 @@ -if not game then script = require "test/relative-string" end - -local flags = require(script.Parent.flags) -local throw = require(script.Parent.throw) -local graph = require(script.Parent.graph) +local flags = require "./flags" +local throw = require "./throw" +local graph = require "./graph" local function batch(setter: () -> ()) local already_batching = flags.batch diff --git a/src/bind.luau b/src/bind.luau index 3a016a6..ff32bcb 100644 --- a/src/bind.luau +++ b/src/bind.luau @@ -1,6 +1,4 @@ -if not game then script = require "test/relative-string" end - -local graph = require(script.Parent.graph) +local graph = require "./graph" type Node = graph.Node local create_node = graph.create_node local assert_stable_scope = graph.assert_stable_scope diff --git a/src/changed.luau b/src/changed.luau index 519a554..063f7e9 100644 --- a/src/changed.luau +++ b/src/changed.luau @@ -1,7 +1,5 @@ -if not game then script = require "test/relative-string" end - -local action = require(script.Parent.action)() -local cleanup = require(script.Parent.cleanup) +local action = require "./action"() +local cleanup = require "./cleanup" local function changed(property: string, callback: (T) -> ()) return action(function(instance) diff --git a/src/cleanup.luau b/src/cleanup.luau index 8449fcc..54195fb 100644 --- a/src/cleanup.luau +++ b/src/cleanup.luau @@ -1,8 +1,7 @@ -if not game then script = require "test/relative-string" end -local typeof = game and typeof or require "test/mock".typeof :: never +local typeof = game and typeof or require "../test/mock".typeof :: never -local throw = require(script.Parent.throw) -local graph = require(script.Parent.graph) +local throw = require "./throw" +local graph = require "./graph" local get_scope = graph.get_scope local push_cleanup = graph.push_cleanup diff --git a/src/context.luau b/src/context.luau index 6c571d0..882b838 100644 --- a/src/context.luau +++ b/src/context.luau @@ -1,7 +1,7 @@ -if not game then script = require "test/relative-string" end +if not game then script = require "../test/relative-string" end -local throw = require(script.Parent.throw) -local graph = require(script.Parent.graph) +local throw = require "./throw" +local graph = require "./graph" type Node = graph.Node local create_node = graph.create_node local get_scope = graph.get_scope diff --git a/src/create.luau b/src/create.luau index 7adfc68..5b6c9df 100644 --- a/src/create.luau +++ b/src/create.luau @@ -1,10 +1,10 @@ -if not game then script = require "test/relative-string" end -local typeof = game and typeof or require "test/mock".typeof:: never -local Instance = game and Instance or require "test/mock".Instance :: never +if not game then script = require "../test/relative-string" end +local typeof = game and typeof or require "../test/mock".typeof :: never +local Instance = game and Instance or require "../test/mock".Instance :: never -local throw = require(script.Parent.throw) -local defaults = require(script.Parent.defaults) -local apply = require(script.Parent.apply) +local throw = require "./throw" +local defaults = require "./defaults" +local apply = require "./apply" local ctor_cache = {} :: { [string]: () -> Instance } diff --git a/src/defaults.luau b/src/defaults.luau index 03badd6..ff2a256 100644 --- a/src/defaults.luau +++ b/src/defaults.luau @@ -1,6 +1,6 @@ -local Enum = game and Enum or require "test/mock".Enum :: never -local Color3 = game and Color3 or require "test/mock".Color3 :: never -local Vector3 = game and Vector3 or require "test/mock".Vector3 :: never +local Enum = game and Enum or require "../test/mock".Enum :: never +local Color3 = game and Color3 or require "../test/mock".Color3 :: never +local Vector3 = game and Vector3 or require "../test/mock".Vector3 :: never return { Part = { diff --git a/src/derive.luau b/src/derive.luau index fb824a4..73bbfeb 100644 --- a/src/derive.luau +++ b/src/derive.luau @@ -1,6 +1,4 @@ -if not game then script = require "test/relative-string" end - -local graph = require(script.Parent.graph) +local graph = require "./graph" local create_node = graph.create_node local push_child_to_scope = graph.push_child_to_scope local assert_stable_scope = graph.assert_stable_scope diff --git a/src/effect.luau b/src/effect.luau index 3acab21..5a2cd25 100644 --- a/src/effect.luau +++ b/src/effect.luau @@ -1,6 +1,4 @@ -if not game then script = require "test/relative-string" end - -local graph = require(script.Parent.graph) +local graph = require "./graph" local create_node = graph.create_node local assert_stable_scope = graph.assert_stable_scope local evaluate_node = graph.evaluate_node diff --git a/src/graph.luau b/src/graph.luau index 1495a59..be58b15 100644 --- a/src/graph.luau +++ b/src/graph.luau @@ -1,7 +1,5 @@ -if not game then script = require "test/relative-string" end - -local throw = require(script.Parent.throw) -local flags = require(script.Parent.flags) +local throw = require "./throw" +local flags = require "./flags" export type SourceNode = { cache: T, diff --git a/src/init.luau b/src/init.luau index 3bcc7ad..79cbf75 100644 --- a/src/init.luau +++ b/src/init.luau @@ -4,28 +4,26 @@ local version = { major = 0, minor = 3, patch = 1 } -if not game then script = require "test/relative-string" end - -local root = require(script.root) -local mount = require(script.mount) -local create = require(script.create) -local apply = require(script.apply) -local source = require(script.source) -local effect = require(script.effect) -local derive = require(script.derive) -local cleanup = require(script.cleanup) -local untrack = require(script.untrack) -local read = require(script.read) -local batch = require(script.batch) -local context = require(script.context) -local switch = require(script.switch) -local show = require(script.show) -local indexes, values = require(script.maps)() -local spring, update_springs = require(script.spring)() -local action = require(script.action)() -local changed = require(script.changed) -local throw = require(script.throw) -local flags = require(script.flags) +local root = require "./root" +local mount = require "./mount" +local create = require "./create" +local apply = require "./apply" +local source = require "./source" +local effect = require "./effect" +local derive = require "./derive" +local cleanup = require "./cleanup" +local untrack = require "./untrack" +local read = require "./read" +local batch = require "./batch" +local context = require "./context" +local switch = require "./switch" +local show = require "./show" +local indexes, values = require "./maps"() +local spring, update_springs = require "./spring"() +local action = require "./action"() +local changed = require "./changed" +local throw = require "./throw" +local flags = require "./flags" export type Source = source.Source export type source = Source diff --git a/src/maps.luau b/src/maps.luau index 23c1eb3..5fea836 100644 --- a/src/maps.luau +++ b/src/maps.luau @@ -1,8 +1,6 @@ -if not game then script = require "test/relative-string" end - -local throw = require(script.Parent.throw) -local flags = require(script.Parent.flags) -local graph = require(script.Parent.graph) +local throw = require "./throw" +local flags = require "./flags" +local graph = require "./graph" type Node = graph.Node type SourceNode = graph.SourceNode local create_node = graph.create_node diff --git a/src/mount.luau b/src/mount.luau index b9d0ace..567d3d9 100644 --- a/src/mount.luau +++ b/src/mount.luau @@ -1,7 +1,5 @@ -if not game then script = require "test/relative-string" end - -local root = require(script.Parent.root) -local apply = require(script.Parent.apply) +local root = require "./root" +local apply = require "./apply" local function mount(component: () -> T, target: Instance?): () -> () return root(function() diff --git a/src/read.luau b/src/read.luau index d3a2fb7..3764315 100644 --- a/src/read.luau +++ b/src/read.luau @@ -1,5 +1,3 @@ -if not game then script = require "test/relative-string" end - local function read(value: T | () -> T): T return if type(value) == "function" then value() else value end diff --git a/src/root.luau b/src/root.luau index bc5904d..d8dc230 100644 --- a/src/root.luau +++ b/src/root.luau @@ -1,7 +1,5 @@ -if not game then script = require "test/relative-string" end - -local throw = require(script.Parent.throw) -local graph = require(script.Parent.graph) +local throw = require "./throw" +local graph = require "./graph" type Node = graph.Node local create_node = graph.create_node local push_scope = graph.push_scope diff --git a/src/show.luau b/src/show.luau index 1cf60ca..b3c3fef 100644 --- a/src/show.luau +++ b/src/show.luau @@ -1,6 +1,4 @@ -if not game then script = require "test/relative-string" end - -local switch = require(script.Parent.switch) +local switch = require "./switch" local function show(source: () -> any, component: () -> T, fallback: (() -> T)?): () -> T? local function truthy() diff --git a/src/source.luau b/src/source.luau index e326815..0b89637 100644 --- a/src/source.luau +++ b/src/source.luau @@ -1,6 +1,4 @@ -if not game then script = require "test/relative-string" end - -local graph = require(script.Parent.graph) +local graph = require "./graph" type Node = graph.Node local create_source_node = graph.create_source_node local push_child_to_scope = graph.push_child_to_scope diff --git a/src/spring.luau b/src/spring.luau index a01ac1c..063b186 100644 --- a/src/spring.luau +++ b/src/spring.luau @@ -1,5 +1,4 @@ -if not game then script = require "test/relative-string" end -local Vector3 = game and Vector3 or require "test/mock".Vector3 :: never +local Vector3 = game and Vector3 or require "../test/mock".Vector3 :: never --[[ @@ -21,8 +20,8 @@ Unsupported datatypes: ]] -local throw = require(script.Parent.throw) -local graph = require(script.Parent.graph) +local throw = require "./throw" +local graph = require "./graph" type Node = graph.Node type SourceNode = graph.SourceNode local create_node = graph.create_node diff --git a/src/switch.luau b/src/switch.luau index 99edd3c..cb7cba4 100644 --- a/src/switch.luau +++ b/src/switch.luau @@ -1,7 +1,5 @@ -if not game then script = require "test/relative-string" end - -local throw = require(script.Parent.throw) -local graph = require(script.Parent.graph) +local throw = require "./throw" +local graph = require "./graph" type Node = graph.Node type SourceNode = graph.SourceNode local create_node = graph.create_node diff --git a/src/throw.luau b/src/throw.luau index 954f3e2..4135f69 100644 --- a/src/throw.luau +++ b/src/throw.luau @@ -1,5 +1,3 @@ -if not game then script = require "test/relative-string" end - local function VIDE_ASSERT(msg): any error(msg, 0) end diff --git a/src/untrack.luau b/src/untrack.luau index 86cdb7b..90ceee2 100644 --- a/src/untrack.luau +++ b/src/untrack.luau @@ -1,6 +1,4 @@ -if not game then script = require "test/relative-string" end - -local graph = require(script.Parent.graph) +local graph = require "./graph" type Node = graph.Node local get_scope = graph.get_scope diff --git a/test/benchmark.luau b/test/benchmark.luau index 05fe3ef..e61f05b 100644 --- a/test/benchmark.luau +++ b/test/benchmark.luau @@ -1,7 +1,7 @@ -local testkit = require("test/testkit") +local testkit = require("./testkit") local BENCH, START = testkit.benchmark() -local vide = require "src/init" +local vide = require "../src/init" local source = vide.source local derive = vide.derive local effect = vide.effect @@ -200,7 +200,7 @@ end) TITLE "property apply" ROOT_BENCH("apply 0 properties", function() - local apply = require "src/apply" + local apply = require "../src/apply" local instance = create("Frame") {} for i = 1, START(N) do @@ -209,7 +209,7 @@ ROOT_BENCH("apply 0 properties", function() end) ROOT_BENCH("apply 8 properties", function() - local apply = require "src/apply" + local apply = require "../src/apply" local instance = create("Frame") {} for i = 1, START(N) do @@ -227,7 +227,7 @@ ROOT_BENCH("apply 8 properties", function() end) ROOT_BENCH("bind property", function() - local apply = require "src/apply" + local apply = require "../src/apply" local instance = create("Frame") {} local src = source(1) @@ -242,7 +242,7 @@ ROOT_BENCH("bind property", function() end) ROOT_BENCH("update binding", function() - local apply = require "src/apply" + local apply = require "../src/apply" local instance = create("Frame") {} local src = source(1) @@ -512,8 +512,8 @@ do -- the purpose of the two following benchmarks is to measure the overhead of -- aggregate construction ROOT_BENCH("set explicit mock vector2", function() - local apply = require "src/apply" - local Vector2 = require "test/mock".Vector2 + local apply = require "../src/apply" + local Vector2 = require "../test/mock".Vector2 local label = create "TextLabel" { AnchorPoint = Vector2.new(1, 1) @@ -527,8 +527,8 @@ do end) ROOT_BENCH("set aggregate mock vector2", function() - local apply = require "src/apply" - local Vector2 = require "test/mock".Vector2 + local apply = require "../src/apply" + local Vector2 = require "../test/mock".Vector2 local label = create "TextLabel" { AnchorPoint = Vector2.new(1, 1) diff --git a/test/spring-test.luau b/test/spring-test.luau index 2e3bc9b..a849598 100644 --- a/test/spring-test.luau +++ b/test/spring-test.luau @@ -1,5 +1,5 @@ -local vide = require "src/init" -local testkit = require("test/testkit") +local vide = require "../src/init" +local testkit = require("../test/testkit") local program_time = os.clock() diff --git a/test/tests.luau b/test/tests.luau index 395b568..42f9563 100644 --- a/test/tests.luau +++ b/test/tests.luau @@ -1,12 +1,12 @@ -local testkit = require("test/testkit") +local testkit = require "./testkit" local TEST, CASE, CHECK, FINISH = testkit.test() -local mock = require "test/mock" +local mock = require "./mock" local Instance, Signal = mock.Instance, mock.Signal local Vector2, UDim2 = mock.Vector2, mock.UDim2 -local vide = require "src/init" -local graph = require "src/graph" +local vide = require "../src/init" +local graph = require "../src/graph" type Node = graph.Node type Map = { [K] : V } @@ -722,7 +722,7 @@ TEST("create()", wrap_root(function() local cleanup = vide.cleanup do CASE "apply default properties" - local defaults = require("src/defaults") + local defaults = require "../src/defaults" local frame = create "Frame" {} :: Instance & { BorderSizePixel: any, BorderColor3: any } CHECK(frame.BorderSizePixel == defaults.Frame.BorderSizePixel) CHECK(frame.BorderColor3 == defaults.Frame.BorderColor3) @@ -1169,7 +1169,7 @@ TEST("switch()", wrap_root(function() end do CASE "reactive stack resets after error" - local scopes = require "src/graph".scopes + local scopes = require "../src/graph".scopes local input = source(1) local n0 = scopes.n @@ -1328,7 +1328,7 @@ TEST("indexes()", wrap_root(function() end do CASE "reactive stack resets after error" - local scopes = require "src/graph".scopes + local scopes = require "../src/graph".scopes local input = source { 1 } @@ -1507,7 +1507,7 @@ TEST("values()", wrap_root(function() end do CASE "reactive stack resets after error" - local scopes = require "src/graph".scopes + local scopes = require "../src/graph".scopes local input = source { 1 } @@ -2260,7 +2260,7 @@ TEST("context()", function() end) TEST("nested effects cases", function() - local vide = require "src/init" + local vide = require "../src/init" local source = vide.source local effect = vide.effect local untrack = vide.untrack From 49cc55149387dd0df5fb9a1afd690bc0563b0782 Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Wed, 13 Nov 2024 22:35:16 +0000 Subject: [PATCH 10/22] Switch from mock Vector3 to native vector lib --- src/apply.luau | 4 +- src/defaults.luau | 3 +- src/spring.luau | 8 ++-- test/benchmark.luau | 97 +++++++++++++++++++++------------------------ test/mock.luau | 35 ---------------- 5 files changed, 52 insertions(+), 95 deletions(-) diff --git a/src/apply.luau b/src/apply.luau index abb482c..1598f3b 100644 --- a/src/apply.luau +++ b/src/apply.luau @@ -70,12 +70,14 @@ for name, class in { UDim = UDim, UDim2 = UDim2, Vector2 = Vector2, - Vector3 = Vector3, Rect = Rect } :: Map do aggregates[name] = class.new end +aggregates.Vector3 = vector.create +aggregates.vector = vector.create + -- applies table of nested properties to an instance using full vide semantics local function apply(instance: T & Instance, properties: { [unknown]: unknown }): T if not properties then diff --git a/src/defaults.luau b/src/defaults.luau index ff2a256..bcdabaf 100644 --- a/src/defaults.luau +++ b/src/defaults.luau @@ -1,11 +1,10 @@ local Enum = game and Enum or require "../test/mock".Enum :: never local Color3 = game and Color3 or require "../test/mock".Color3 :: never -local Vector3 = game and Vector3 or require "../test/mock".Vector3 :: never return { Part = { Material = Enum.Material.SmoothPlastic, - Size = Vector3.new(1, 1, 1), + Size = vector.create(1, 1, 1), Anchored = true }, diff --git a/src/spring.luau b/src/spring.luau index 063b186..acb50ac 100644 --- a/src/spring.luau +++ b/src/spring.luau @@ -1,5 +1,3 @@ -local Vector3 = game and Vector3 or require "../test/mock".Vector3 :: never - --[[ Supported datatypes: @@ -36,8 +34,8 @@ local TOLERANCE = 0.0001 type Vec3 = Vector3 -local function Vec3(x: number?, y: number?, z: number?) - return Vector3.new(x, y, z) +local function Vec3(x: number?, y: number?, z: number?): Vec3 + return vector.create(x, y, z) end local ZERO = Vec3(0, 0, 0) @@ -276,7 +274,7 @@ local function update_spring_sources() x0_456 - x1_456 -- todo: can this false positive? - if (v_123 + v_456 + dx_123 + dx_456).Magnitude < TOLERANCE then + if vector.magnitude(v_123 + v_456 + dx_123 + dx_456) < TOLERANCE then -- close enough to target, unshedule spring and set value to target table.insert(remove_queue, data) output.cache = data.source_value diff --git a/test/benchmark.luau b/test/benchmark.luau index e61f05b..0177e58 100644 --- a/test/benchmark.luau +++ b/test/benchmark.luau @@ -504,85 +504,78 @@ ROOT_BENCH(`get context (depth={depth})`, function() end) end) -N *= 1024 +TITLE "spring()" + +ROOT_BENCH("spring update", function() + local root, source, spring = vide.root, vide.source, vide.spring + + local src = source(0) + + root(function() + for i = 1, N do + spring(src) + end + + START(N) + + src(1) + + return nil + end) +end) + +ROOT_BENCH("spring step", function() + local root, source, spring = vide.root, vide.source, vide.spring + + local src = source(0) + + root(function() + for i = 1, N do + spring(src) + end + + src(1) + + START(N) + + vide.step(1/60) + + return nil + end) +end) TITLE "aggregate" do -- the purpose of the two following benchmarks is to measure the overhead of -- aggregate construction - ROOT_BENCH("set explicit mock vector2", function() + ROOT_BENCH("set explicit vector", function() local apply = require "../src/apply" - local Vector2 = require "../test/mock".Vector2 local label = create "TextLabel" { - AnchorPoint = Vector2.new(1, 1) + AnchorPoint = vector.create(1, 1, 1) } for i = 1, START(N) do apply(label, { - AnchorPoint = Vector2.new(i, i) + AnchorPoint = vector.create(i, i, i) }) end end) - ROOT_BENCH("set aggregate mock vector2", function() + ROOT_BENCH("set aggregate vector", function() local apply = require "../src/apply" - local Vector2 = require "../test/mock".Vector2 local label = create "TextLabel" { - AnchorPoint = Vector2.new(1, 1) + AnchorPoint = vector.create(1, 1, 1) } for i = 1, START(N) do apply(label, { - AnchorPoint = { i, i } + AnchorPoint = { i, i, i } }) end end) end --- innacurate due to no Vector3 in vanilla Luau --- mock vector is 200x slower than native vector - --- ROOT_BENCH("spring update", function() --- local root, source, spring = vide.root, vide.source, vide.spring - --- local src = source(0) - --- root(function() --- for i = 1, N do --- spring(src) --- end - --- START(N) - --- src(1) - --- return nil --- end) --- end) - --- N /= 1024 - --- ROOT_BENCH("spring step", function() --- local root, source, spring = vide.root, vide.source, vide.spring - --- local src = source(0) - --- root(function() --- for i = 1, N do --- spring(src) --- end - --- src(1) - --- START(N) - --- vide.step(1/60) - --- return nil --- end) --- end) - return nil diff --git a/test/mock.luau b/test/mock.luau index 1dfb9bc..34564e6 100644 --- a/test/mock.luau +++ b/test/mock.luau @@ -257,40 +257,6 @@ local Vector2 = { __type = "Vector2" } :: any do end end -local Vector3 = { __type = "Vector3" } :: any do - local function new(x, y, z) - return setmetatable({ X = x, Y = y, Z = z }, Vector3) - end - - function Vector3.new(x, y, z) - return new(x or 0, y or 0, z or 0) - end - - function Vector3.__add(a, b) - return new(a.X + b.X, a.Y + b.Y, a.Z + b.Z) - end - - function Vector3.__sub(a, b) - return new(a.X - b.X, a.Y - b.Y, a.Z - b.Z) - end - - function Vector3.__mul(a, b) - return new(a.X * b, a.Y * b, a.Z * b) - end - - function Vector3.__unm(v) - return new(-v.X, -v.Y, -v.Z) - end - - function Vector3.__eq(a, b) - return a.X == b.X and a.Y == b.Y - end - - function Vector3.__index(v) - return (v.X^2 + v.Y^2 + v.Z^2)^0.5 - end -end - local UDim2 = { __type = "UDim2" } :: any do function UDim2.new(sx, ox, sy, oy) return table_to_proxy(setmetatable({ x = { scale = sx, offset = ox }, y = { scale = sy, offset = oy } }, UDim2)) @@ -330,7 +296,6 @@ return { Instance = Instance :: typeof(Instance), Color3 = Color3 :: typeof(Color3), Vector2 = Vector2 :: typeof(Vector2), - Vector3 = Vector3 :: typeof(Vector3), UDim2 = UDim2 :: typeof(UDim2), Enum = Enum :: typeof(Enum), typeof = typeof :: typeof(typeof) From f7e996191138d14fbdbd413b7fbdb95f22fe332a Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Sat, 16 Nov 2024 18:38:23 +0000 Subject: [PATCH 11/22] Fix library require --- init.luau | 8 ++++ src/init.luau | 121 +++----------------------------------------------- src/lib.luau | 115 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 129 insertions(+), 115 deletions(-) create mode 100644 init.luau create mode 100644 src/lib.luau diff --git a/init.luau b/init.luau new file mode 100644 index 0000000..5ef336f --- /dev/null +++ b/init.luau @@ -0,0 +1,8 @@ +local vide = require "./src/lib" + +export type source = vide.source +export type Source = vide.Source +export type context = vide.context +export type Context = vide.Context + +return vide diff --git a/src/init.luau b/src/init.luau index 79cbf75..11d1bd2 100644 --- a/src/init.luau +++ b/src/init.luau @@ -1,119 +1,10 @@ --------------------------------------------------------------------------------- --- vide.luau --------------------------------------------------------------------------------- +assert(game, "when using vide outside of Roblox, require lib.luau instead") -local version = { major = 0, minor = 3, patch = 1 } +local vide = require(script.lib) -local root = require "./root" -local mount = require "./mount" -local create = require "./create" -local apply = require "./apply" -local source = require "./source" -local effect = require "./effect" -local derive = require "./derive" -local cleanup = require "./cleanup" -local untrack = require "./untrack" -local read = require "./read" -local batch = require "./batch" -local context = require "./context" -local switch = require "./switch" -local show = require "./show" -local indexes, values = require "./maps"() -local spring, update_springs = require "./spring"() -local action = require "./action"() -local changed = require "./changed" -local throw = require "./throw" -local flags = require "./flags" - -export type Source = source.Source -export type source = Source -export type Context = context.Context -export type context = Context - -local function step(dt: number) - if game then - debug.profilebegin("VIDE STEP") - debug.profilebegin("VIDE SPRING") - end - - update_springs(dt) - - if game then - debug.profileend() - debug.profileend() - end -end - -local stepped = game and game:GetService("RunService").Heartbeat:Connect(function(dt: number) - task.defer(step, dt) -end) - -local vide = { - version = version, - - -- core - root = root, - mount = mount, - create = create, - source = source, - effect = effect, - derive = derive, - switch = switch, - show = show, - indexes = indexes, - values = values, - - -- util - cleanup = cleanup, - untrack = untrack, - read = read, - batch = batch, - context = context, - - -- animations - spring = spring, - - -- actions - action = action, - changed = changed, - - -- flags - strict = (nil :: any) :: boolean, - - -- temporary - apply = function(instance: Instance) - return function(props: { [any]: any }) - apply(instance, props) - return instance - end - end, - - -- runtime - step = function(dt: number) - if stepped then - stepped:Disconnect() - stepped = nil - end - step(dt) - end -} - -setmetatable(vide :: any, { - __index = function(_, index: unknown): () - if index == "strict" then - return flags.strict - else - throw(`{tostring(index)} is not a valid member of vide`) - end - end, - - __newindex = function(_, index: unknown, value: unknown) - if index == "strict" then - flags.strict = value :: boolean - else - throw(`{tostring(index)} is not a valid member of vide`) - end - end -}) +export type source = vide.source +export type Source = vide.Source +export type context = vide.context +export type Context = vide.Context return vide diff --git a/src/lib.luau b/src/lib.luau new file mode 100644 index 0000000..d3e526f --- /dev/null +++ b/src/lib.luau @@ -0,0 +1,115 @@ +local version = { major = 0, minor = 3, patch = 1 } + +local root = require "./root" +local mount = require "./mount" +local create = require "./create" +local apply = require "./apply" +local source = require "./source" +local effect = require "./effect" +local derive = require "./derive" +local cleanup = require "./cleanup" +local untrack = require "./untrack" +local read = require "./read" +local batch = require "./batch" +local context = require "./context" +local switch = require "./switch" +local show = require "./show" +local indexes, values = require "./maps"() +local spring, update_springs = require "./spring"() +local action = require "./action"() +local changed = require "./changed" +local throw = require "./throw" +local flags = require "./flags" + +export type Source = source.Source +export type source = Source +export type Context = context.Context +export type context = Context + +local function step(dt: number) + if game then + debug.profilebegin("VIDE STEP") + debug.profilebegin("VIDE SPRING") + end + + update_springs(dt) + + if game then + debug.profileend() + debug.profileend() + end +end + +local stepped = game and game:GetService("RunService").Heartbeat:Connect(function(dt: number) + task.defer(step, dt) +end) + +local vide = { + version = version, + + -- core + root = root, + mount = mount, + create = create, + source = source, + effect = effect, + derive = derive, + switch = switch, + show = show, + indexes = indexes, + values = values, + + -- util + cleanup = cleanup, + untrack = untrack, + read = read, + batch = batch, + context = context, + + -- animations + spring = spring, + + -- actions + action = action, + changed = changed, + + -- flags + strict = (nil :: any) :: boolean, + + -- temporary + apply = function(instance: Instance) + return function(props: { [any]: any }) + apply(instance, props) + return instance + end + end, + + -- runtime + step = function(dt: number) + if stepped then + stepped:Disconnect() + stepped = nil + end + step(dt) + end +} + +setmetatable(vide :: any, { + __index = function(_, index: unknown): () + if index == "strict" then + return flags.strict + else + throw(`{tostring(index)} is not a valid member of vide`) + end + end, + + __newindex = function(_, index: unknown, value: unknown) + if index == "strict" then + flags.strict = value :: boolean + else + throw(`{tostring(index)} is not a valid member of vide`) + end + end +}) + +return vide From fdb4a137a841ddaa38ddb660d0e96bc2c9c412f7 Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Sat, 16 Nov 2024 18:41:27 +0000 Subject: [PATCH 12/22] Fix test require --- src/context.luau | 2 -- src/create.luau | 1 - test/benchmark.luau | 2 +- test/relative-string.luau | 9 --------- test/spring-test.luau | 2 +- test/tests.luau | 6 +++--- 6 files changed, 5 insertions(+), 17 deletions(-) delete mode 100644 test/relative-string.luau diff --git a/src/context.luau b/src/context.luau index 882b838..a46ad5a 100644 --- a/src/context.luau +++ b/src/context.luau @@ -1,5 +1,3 @@ -if not game then script = require "../test/relative-string" end - local throw = require "./throw" local graph = require "./graph" type Node = graph.Node diff --git a/src/create.luau b/src/create.luau index 5b6c9df..2711511 100644 --- a/src/create.luau +++ b/src/create.luau @@ -1,4 +1,3 @@ -if not game then script = require "../test/relative-string" end local typeof = game and typeof or require "../test/mock".typeof :: never local Instance = game and Instance or require "../test/mock".Instance :: never diff --git a/test/benchmark.luau b/test/benchmark.luau index 0177e58..524cea7 100644 --- a/test/benchmark.luau +++ b/test/benchmark.luau @@ -1,7 +1,7 @@ local testkit = require("./testkit") local BENCH, START = testkit.benchmark() -local vide = require "../src/init" +local vide = require "../../vide" local source = vide.source local derive = vide.derive local effect = vide.effect diff --git a/test/relative-string.luau b/test/relative-string.luau deleted file mode 100644 index 232215c..0000000 --- a/test/relative-string.luau +++ /dev/null @@ -1,9 +0,0 @@ -local function dir(directory: string) - return setmetatable({} :: { [string]: any }, - { __index = function(_, path) return directory .. path end }) -end - -local script = dir "src/" -script.Parent = dir "src/" - -return script diff --git a/test/spring-test.luau b/test/spring-test.luau index a849598..17175f5 100644 --- a/test/spring-test.luau +++ b/test/spring-test.luau @@ -1,4 +1,4 @@ -local vide = require "../src/init" +local vide = require "../../vide" local testkit = require("../test/testkit") local program_time = os.clock() diff --git a/test/tests.luau b/test/tests.luau index 42f9563..25e5157 100644 --- a/test/tests.luau +++ b/test/tests.luau @@ -5,8 +5,8 @@ local mock = require "./mock" local Instance, Signal = mock.Instance, mock.Signal local Vector2, UDim2 = mock.Vector2, mock.UDim2 -local vide = require "../src/init" -local graph = require "../src/graph" +local vide = require "../../vide" +local graph = require "../../vide/src/graph" type Node = graph.Node type Map = { [K] : V } @@ -2260,7 +2260,7 @@ TEST("context()", function() end) TEST("nested effects cases", function() - local vide = require "../src/init" + local vide = require "../../vide" local source = vide.source local effect = vide.effect local untrack = vide.untrack From 8799988851e9f672c476479508b88c60bbd408b7 Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Sat, 16 Nov 2024 18:55:37 +0000 Subject: [PATCH 13/22] Update github workflow Luau version --- .github/workflows/unit-test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/unit-test.yml b/.github/workflows/unit-test.yml index 4a9db7f..69bed32 100644 --- a/.github/workflows/unit-test.yml +++ b/.github/workflows/unit-test.yml @@ -14,7 +14,7 @@ jobs: uses: robinraju/release-downloader@v1.6 with: repository: Roblox/luau - tag: "0.620" + tag: "0.651" fileName: luau-ubuntu.zip out-file-path: bin From 44fe65ee5e140c92cac0476e08031bfd697bdf61 Mon Sep 17 00:00:00 2001 From: 11poe <404johnnydoe@gmail.com> Date: Sat, 16 Nov 2024 21:20:49 +0100 Subject: [PATCH 14/22] Add create(a, { props }) syntax (#42) * Add new create syntax * Add new create syntax to changelog * Fix new create syntax test --- CHANGELOG.md | 8 +++++ src/create.luau | 89 +++++++++++++++++++++++++++---------------------- test/tests.luau | 13 ++++++++ 3 files changed, 70 insertions(+), 40 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 17e7087..617ae1f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). -------------------------------------------------------------------------------- +## [Unreleased] + +### Added + +- `create("ClassName", { props })` and `create(Instance, { props })` syntax. + +-------------------------------------------------------------------------------- + ## [0.3.1] - 2024-10-09 ### Added diff --git a/src/create.luau b/src/create.luau index 2711511..dea8ca7 100644 --- a/src/create.luau +++ b/src/create.luau @@ -20,8 +20,8 @@ setmetatable(ctor_cache :: any, { end local function ctor(properties: Props): Instance - return apply(instance:Clone(), properties) - end + return apply(instance:Clone(), properties) + end self[class] = ctor return ctor @@ -40,44 +40,53 @@ local function clone_instance(instance: Instance) end end -local function create(class_or_instance: string|Instance): (Props) -> Instance - if type(class_or_instance) == "string" then - return create_instance(class_or_instance) - elseif typeof(class_or_instance) == "Instance" then - return clone_instance(class_or_instance) - else - throw("bad argument #1, expected string or instance, got " .. typeof(class_or_instance)) - return nil :: never - end +local function create(class_or_instance: string | Instance, props: Props?): ((Props) -> Instance) | Instance + local result: (Props) -> Instance + if type(class_or_instance) == "string" then + result = create_instance(class_or_instance) + elseif typeof(class_or_instance) == "Instance" then + result = clone_instance(class_or_instance) + else + throw("bad argument #1, expected string or instance, got " .. typeof(class_or_instance)) + return nil :: never + end + if props then + return result(props) + end + return result end type Props = { [any]: any } -return (create :: any) :: -( (T & Instance) -> (Props) -> T ) & -( ("Folder") -> (Props) -> Folder ) & -( ("BillboardGui") -> (Props) -> BillboardGui ) & -( ("CanvasGroup") -> (Props) -> CanvasGroup ) & -( ("Frame") -> (Props) -> Frame ) & -( ("ImageButton") -> (Props) -> ImageButton ) & -( ("ImageLabel") -> (Props) -> ImageLabel ) & -( ("ScreenGui") -> (Props) -> ScreenGui ) & -( ("ScrollingFrame") -> (Props) -> ScrollingFrame ) & -( ("SurfaceGui") -> (Props) -> SurfaceGui ) & -( ("TextBox") -> (Props) -> TextBox ) & -( ("TextButton") -> (Props) -> TextButton ) & -( ("TextLabel") -> (Props) -> TextLabel ) & -( ("UIAspectRatioConstraint") -> (Props) -> UIAspectRatioConstraint ) & -( ("UICorner") -> (Props) -> UICorner ) & -( ("UIGradient") -> (Props) -> UIGradient ) & -( ("UIGridLayout") -> (Props) -> UIGridLayout ) & -( ("UIListLayout") -> (Props) -> UIListLayout ) & -( ("UIPadding") -> (Props) -> UIPadding ) & -( ("UIPageLayout") -> (Props) -> UIPageLayout ) & -( ("UIScale") -> (Props) -> UIScale ) & -( ("UISizeConstraint") -> (Props) -> UISizeConstraint ) & -( ("UIStroke") -> (Props) -> UIStroke ) & -( ("UITableLayout") -> (Props) -> UITableLayout ) & -( ("UITextSizeConstraint") -> (Props) -> UITextSizeConstraint ) & -( ("VideoFrame") -> (Props) -> VideoFrame ) & -( ("ViewportFrame") -> (Props) -> ViewportFrame ) & -( (string) -> (Props) -> Instance ) + +type Create = ((Name, Props) -> Instance) & ((Name) -> (Props) -> Instance) + +return (create :: any) :: + & ( (T & Instance) -> (Props) -> T ) + & ( (T & Instance, Props) -> T ) + & Create<"Folder", Folder> + & Create<"BillboardGui", BillboardGui> + & Create<"CanvasGroup", CanvasGroup> + & Create<"Frame", Frame> + & Create<"ImageButton", ImageButton> + & Create<"ImageLabel", ImageLabel> + & Create<"ScreenGui", ScreenGui> + & Create<"ScrollingFrame", ScrollingFrame> + & Create<"SurfaceGui", SurfaceGui> + & Create<"TextBox", TextBox> + & Create<"TextButton", TextButton> + & Create<"TextLabel", TextLabel> + & Create<"UIAspectRatioConstraint", UIAspectRatioConstraint> + & Create<"UICorner", UICorner> + & Create<"UIGradient", UIGradient> + & Create<"UIGridLayout", UIGridLayout> + & Create<"UIListLayout", UIListLayout> + & Create<"UIPadding", UIPadding> + & Create<"UIPageLayout", UIPageLayout> + & Create<"UIScale", UIScale> + & Create<"UISizeConstraint", UISizeConstraint> + & Create<"UIStroke", UIStroke> + & Create<"UITableLayout", UITableLayout> + & Create<"UITextSizeConstraint", UITextSizeConstraint> + & Create<"VideoFrame", VideoFrame> + & Create<"ViewportFrame", ViewportFrame> + & Create diff --git a/test/tests.luau b/test/tests.luau index 25e5157..8f30a82 100644 --- a/test/tests.luau +++ b/test/tests.luau @@ -721,6 +721,19 @@ TEST("create()", wrap_root(function() local source = vide.source local cleanup = vide.cleanup + do CASE "create(\"ClassName\", props) syntax" + local frame = create("Frame", { BackgroundTransparency = 0.5, Name = "Foo" }) + CHECK(frame.BackgroundTransparency == 0.5) + CHECK(frame.Name == "Foo") + end + + do CASE "create(Instance, props) syntax" + local frame0 = create("Frame", { BackgroundTransparency = 0.5, Name = "Foo" }) + local frame = create(frame0, { BackgroundTransparency = 1 }) + CHECK(frame.BackgroundTransparency == 1) + CHECK(frame.Name == "Foo") + end + do CASE "apply default properties" local defaults = require "../src/defaults" local frame = create "Frame" {} :: Instance & { BorderSizePixel: any, BorderColor3: any } From e60aa57ca260f1a8899f1e15c590ec79d44f9fd8 Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Wed, 27 Nov 2024 19:43:51 +0000 Subject: [PATCH 15/22] Fix edge case with map functions --- src/maps.luau | 4 +-- test/tests.luau | 77 ++++++++++++++++++++++++++++++++----------------- 2 files changed, 52 insertions(+), 29 deletions(-) diff --git a/src/maps.luau b/src/maps.luau index 5fea836..bd59a6c 100644 --- a/src/maps.luau +++ b/src/maps.luau @@ -61,6 +61,8 @@ local function indexes(input: () -> Map, transform: (() -> VI, local cv = input_cache[i] if cv ~= v then + input_cache[i] = v + if cv == nil then -- create new scope and run transform local scope = create_node(subowner, false, false) scopes[i] = scope :: Node @@ -87,8 +89,6 @@ local function indexes(input: () -> Map, transform: (() -> VI, input_nodes[i].cache = v update_descendants(input_nodes[i]) end - - input_cache[i] = v end end diff --git a/test/tests.luau b/test/tests.luau index 8f30a82..a0ba2ff 100644 --- a/test/tests.luau +++ b/test/tests.luau @@ -2646,10 +2646,12 @@ TEST("strict", wrap_root(function() do CASE "destruction of active scope" local src = source(false) + local count = 0 root(function() show(src, function() src(false) + vide.cleanup(function() count += 1 end) return {} end) end) @@ -2661,38 +2663,59 @@ TEST("strict", wrap_root(function() CHECK(not ok) end - -- todo: review intended behavior here - -- do CASE "destruction of active scope in indexes" - -- local src = source {} + do CASE "destruction of active scope in indexes" + local src = source {} - -- local tmp - -- root(function() - -- effect(function() - -- untrack(function() - -- tmp = indexes(src, function() - -- vide.cleanup(function() print "test" end) - -- src {} - -- print "updated" - -- vide.cleanup(function() print "test2" end) - -- print "end" - -- return {} - -- end) - -- return nil - -- end) - -- end) - -- end) + local count_1 = 0 + local count_2 = 0 - -- print "setting" + root(function() + effect(function() + untrack(function() + indexes(src, function() + vide.cleanup(function() count_1 += 1 end) + src {} + vide.cleanup(function() count_2 += 1 end) + return {} + end) + return nil + end) + end) + end) - -- local ok = pcall(function() - -- src { 1 } - -- print "done" - -- end) + local ok = pcall(function() + src { 1 } + end) - -- print(#tmp()) + CHECK(not ok) + end - -- CHECK(not ok) - -- end + do CASE "destruction of active scope in values" + local src = source {} + + local count_1 = 0 + local count_2 = 0 + + root(function() + effect(function() + untrack(function() + values(src, function() + vide.cleanup(function() count_1 += 1 end) + src {} + vide.cleanup(function() count_2 += 1 end) + return {} + end) + return nil + end) + end) + end) + + local ok = pcall(function() + src { {} } + end) + + CHECK(not ok) + end end)) local ok = FINISH() From caa9eaf733b1c6e889fe6c71755dafcace8492da Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Thu, 28 Nov 2024 01:00:11 +0000 Subject: [PATCH 16/22] Add thread cleanup helper --- CHANGELOG.md | 6 ++++++ docs/api/reactivity-utility.md | 2 +- src/cleanup.luau | 2 ++ 3 files changed, 9 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 617ae1f..ca9bbb8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added - `create("ClassName", { props })` and `create(Instance, { props })` syntax. +- `cleanup()` now accepts `thread` types. + +### Changed + +- A scope can no longer be destroyed while it is active. Strict mode will check + for this. -------------------------------------------------------------------------------- diff --git a/docs/api/reactivity-utility.md b/docs/api/reactivity-utility.md index d084976..b8bff4d 100644 --- a/docs/api/reactivity-utility.md +++ b/docs/api/reactivity-utility.md @@ -7,7 +7,7 @@ Queues a callback to run when a scope is reran or destroyed. - **Type** ```luau - function cleanup(v: Function | Disconnectable | Destroyable) + function cleanup(v: Function | Disconnectable | Destroyable | thread) type Function = () -> () type Destroyable = { destroy: () -> () } diff --git a/src/cleanup.luau b/src/cleanup.luau index 54195fb..20d188b 100644 --- a/src/cleanup.luau +++ b/src/cleanup.luau @@ -8,6 +8,7 @@ local push_cleanup = graph.push_cleanup local function helper(obj: any) return if typeof(obj) == "RBXScriptConnection" then function() obj:Disconnect() end + elseif type(obj) == "thread" then function() task.cancel(obj) end elseif typeof(obj) == "Instance" then function() obj:Destroy() end elseif obj.destroy then function() obj:destroy() end elseif obj.disconnect then function() obj:disconnect() end @@ -35,6 +36,7 @@ type Disconnectable = { disconnect: (any) -> () } | { Disconnect: (any) -> () } return cleanup :: ( (callback: () -> ()) -> () ) & + ( (thread: thread) -> () ) & ( (instance: Destroyable) -> () ) & ( (connection: Disconnectable) -> () ) & ( (instance: Instance) -> () ) & From 3b8d9098c0cc710f6facace8ccb8d4cb44c063cc Mon Sep 17 00:00:00 2001 From: richard <56808540+littensy@users.noreply.github.com> Date: Wed, 4 Dec 2024 18:00:37 -0800 Subject: [PATCH 17/22] Use `vector.max` to check spring activity (#44) * Use `vector.max` to check spring activity * Revert unnecessary changes --- src/spring.luau | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/src/spring.luau b/src/spring.luau index acb50ac..bcd5789 100644 --- a/src/spring.luau +++ b/src/spring.luau @@ -30,11 +30,12 @@ local update_descendants = graph.update_descendants local push_child_to_scope = graph.push_child_to_scope local UPDATE_RATE = 120 -local TOLERANCE = 0.0001 +local TOLERANCE = 0.001 +local TOLERANCE_VECTOR = vector.create(TOLERANCE, TOLERANCE, TOLERANCE) type Vec3 = Vector3 -local function Vec3(x: number?, y: number?, z: number?): Vec3 +local function Vec3(x: number, y: number, z: number): Vec3 return vector.create(x, y, z) end @@ -268,13 +269,16 @@ local function update_spring_sources() x0_456, x1_456, v_456 = data.x0_123, data.x1_123, data.v_123, data.x0_456, data.x1_456, data.v_456 - - local dx_123, dx_456 = - x0_123 - x1_123, - x0_456 - x1_456 - -- todo: can this false positive? - if vector.magnitude(v_123 + v_456 + dx_123 + dx_456) < TOLERANCE then + local max_difference = vector.max( + vector.abs(x0_123 - x1_123 :: any), + vector.abs(x0_456 - x1_456 :: any), + vector.abs(v_123 :: any), + vector.abs(v_456 :: any), + TOLERANCE_VECTOR + ) + + if max_difference == TOLERANCE_VECTOR then -- close enough to target, unshedule spring and set value to target table.insert(remove_queue, data) output.cache = data.source_value From ccaeb030f32283d3dd189c007524259f72d8a4cc Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Thu, 26 Dec 2024 21:17:14 +0000 Subject: [PATCH 18/22] Remove aggregate construction --- CHANGELOG.md | 4 ++++ src/apply.luau | 24 +----------------------- test/benchmark.luau | 34 ---------------------------------- test/tests.luau | 15 --------------- 4 files changed, 5 insertions(+), 72 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ca9bbb8..83b4399 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - A scope can no longer be destroyed while it is active. Strict mode will check for this. +### Removed + +- Aggregate construction when setting properties with `create()`. + -------------------------------------------------------------------------------- ## [0.3.1] - 2024-10-09 diff --git a/src/apply.luau b/src/apply.luau index 1598f3b..15246a6 100644 --- a/src/apply.luau +++ b/src/apply.luau @@ -62,22 +62,6 @@ local function return_caches(caches: typeof(free_caches) ) free_caches = caches end --- map of datatype names to class default constructor for aggregate init -local aggregates = {} -for name, class in { - CFrame = CFrame, - Color3 = Color3, - UDim = UDim, - UDim2 = UDim2, - Vector2 = Vector2, - Rect = Rect -} :: Map do - aggregates[name] = class.new -end - -aggregates.Vector3 = vector.create -aggregates.vector = vector.create - -- applies table of nested properties to an instance using full vide semantics local function apply(instance: T & Instance, properties: { [unknown]: unknown }): T if not properties then @@ -109,13 +93,7 @@ local function apply(instance: T & Instance, properties: { [unknown]: unknown nested_debug[depth][property] = true end - if type(value) == "table" then -- attempt aggregate init - local ctor = aggregates[typeof((instance :: any)[property])] - if ctor == nil then - throw(`cannot aggregate type {typeof(value)} for property {property}`) - end - (instance :: any)[property] = ctor(unpack(value :: {})) - elseif type(value) == "function" then + if type(value) == "function" then if typeof((instance :: any)[property]) == "RBXScriptSignal" then events[property] = value :: () -> () -- add event to buffer else diff --git a/test/benchmark.luau b/test/benchmark.luau index 524cea7..690c8b9 100644 --- a/test/benchmark.luau +++ b/test/benchmark.luau @@ -544,38 +544,4 @@ ROOT_BENCH("spring step", function() end) end) -TITLE "aggregate" - -do - -- the purpose of the two following benchmarks is to measure the overhead of - -- aggregate construction - ROOT_BENCH("set explicit vector", function() - local apply = require "../src/apply" - - local label = create "TextLabel" { - AnchorPoint = vector.create(1, 1, 1) - } - - for i = 1, START(N) do - apply(label, { - AnchorPoint = vector.create(i, i, i) - }) - end - end) - - ROOT_BENCH("set aggregate vector", function() - local apply = require "../src/apply" - - local label = create "TextLabel" { - AnchorPoint = vector.create(1, 1, 1) - } - - for i = 1, START(N) do - apply(label, { - AnchorPoint = { i, i, i } - }) - end - end) -end - return nil diff --git a/test/tests.luau b/test/tests.luau index a0ba2ff..85f5357 100644 --- a/test/tests.luau +++ b/test/tests.luau @@ -759,21 +759,6 @@ TEST("create()", wrap_root(function() CHECK(text.Text == "test") end - do CASE "aggregate construction" - local template = create "TextLabel" { - AnchorPoint = Vector2.new(), - Position = UDim2.new() - } - - local text = create(template) { - AnchorPoint = { 1, 2 }, - Position = { 3, 4 } - } - - CHECK(text.AnchorPoint == Vector2.new(1, 2)) - CHECK(text.Position == UDim2.new(3, 4)) - end - do CASE "nested precedence" local text = create "TextLabel" { { From 4c639f838881798cd775c5932628cb025457adce Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Thu, 26 Dec 2024 22:36:58 +0000 Subject: [PATCH 19/22] Add flag to disable deferral of nested properties --- src/apply.luau | 121 +++++++++++++++++++++++++----------------------- src/flags.luau | 6 ++- src/lib.luau | 13 +++--- test/tests.luau | 23 +++++++-- 4 files changed, 95 insertions(+), 68 deletions(-) diff --git a/src/apply.luau b/src/apply.luau index 15246a6..754c0d2 100644 --- a/src/apply.luau +++ b/src/apply.luau @@ -13,11 +13,11 @@ type Array = { V } type ArrayOrV = {ArrayOrV} | V type Map = { [K]: V } -local free_caches: { +type Cache = { -- event listeners to connect after properties are set - events: Map< - string, -- event name - () -> () -- listener + events: Array< + | string -- 1. event name + | () -> () -- 2. listener >, -- actions to run after events are connected @@ -32,18 +32,18 @@ local free_caches: { Map -- set of property names >, - -- use stack instead of recursive function to process nesting layers one at time - -- deeper-nested properties take precedence over shallower-nested ones -- each nested layer occupies two indexes: 1. table ref 2. nested depth -- e.g. { t1 = { t3 = {} }, t2 = {} } -> { t1, 1, t2, 1, t3, 2 } nested_stack: { {} | number } -}? +} -local function borrow_caches(): typeof(assert(free_caches)) - if free_caches then - local caches = free_caches :: typeof(assert(free_caches)) - free_caches = nil - return caches +local free_cache: Cache? + +local function borrow_cache(): Cache + if free_cache then + local cache = free_cache + free_cache = nil + return cache else return { events = {}, @@ -58,8 +58,49 @@ local function borrow_caches(): typeof(assert(free_caches)) end end -local function return_caches(caches: typeof(free_caches) ) - free_caches = caches +local function return_cache(cache: Cache ) + free_cache = cache +end + +local function process_properties(properties: Map, instance: Instance, cache: Cache, depth: number) + for property, value in properties do + if property == "Parent" then continue end + + if type(property) == "string" then + if flags.strict then -- check for duplicate property assignment at nesting depth + if cache.nested_debug[depth][property] then + throw(`duplicate property {property} at depth {depth}`) + end + cache.nested_debug[depth][property] = true + end + + if type(value) == "function" then + if typeof((instance :: any)[property]) == "RBXScriptSignal" then + table.insert(cache.events, property) -- add event name to buffer + table.insert(cache.events, value :: () -> ()) -- add event listener to buffer + else + bind.property(instance, property, value :: () -> ()) -- create implicit effect for property + end + else + (instance :: any)[property] = value -- set property + end + elseif type(property) == "number" then + if type(value) == "function" then + bind.children(instance, value :: () -> ArrayOrV) -- bind children + elseif type(value) == "table" then + if is_action(value) then + table.insert(cache.actions[(value :: any).priority], (value :: any).callback :: () -> ()) -- add action to buffer + elseif flags.defer_nested_properties then + table.insert(cache.nested_stack, value :: {}) + table.insert(cache.nested_stack, depth + 1) -- push table to stack for later processing + else + process_properties(value :: Map, instance, cache, depth + 1) + end + else + (value :: Instance).Parent = instance -- parent child + end + end + end end -- applies table of nested properties to an instance using full vide semantics @@ -68,12 +109,10 @@ local function apply(instance: T & Instance, properties: { [unknown]: unknown throw("attempt to call a constructor returned by create() with no properties") end - local strict = flags.strict - -- queue parent assignment if any for last local parent: unknown = properties.Parent - local caches = borrow_caches() + local caches = borrow_cache() local events = caches.events local actions = caches.actions local nested_debug = caches.nested_debug @@ -82,49 +121,15 @@ local function apply(instance: T & Instance, properties: { [unknown]: unknown -- process all properties local depth = 1 repeat - for property, value in properties do - if property == "Parent" then continue end - - if type(property) == "string" then - if strict then -- check for duplicate prop assignment at nesting depth - if nested_debug[depth][property] then - throw(`duplicate property {property} at depth {depth}`) - end - nested_debug[depth][property] = true - end - - if type(value) == "function" then - if typeof((instance :: any)[property]) == "RBXScriptSignal" then - events[property] = value :: () -> () -- add event to buffer - else - bind.property(instance, property, value :: () -> ()) -- bind property - end - else - (instance :: any)[property] = value -- set property - end - elseif type(property) == "number" then - if type(value) == "function" then - bind.children(instance, value :: () -> ArrayOrV) -- bind children - elseif type(value) == "table" then - if is_action(value) then - table.insert(actions[(value :: any).priority], (value :: any).callback :: () -> ()) -- add action to buffer - else - table.insert(nested_stack, value :: {}) - table.insert(nested_stack, depth + 1) -- push table to stack for later processing - end - else - (value :: Instance).Parent = instance -- parent child - end - end - end - + process_properties(properties, instance, caches, depth) depth = table.remove(nested_stack) :: number properties = table.remove(nested_stack) :: {} - until not properties - for event, listener in next, events do - (instance :: any)[event]:Connect(listener) + for i = 1, #events, 2 do + local event_name = events[i] + local event_listener = events[i + 1] + ;(instance :: any)[event_name]:Connect(event_listener) end for _, queued in next, actions do @@ -145,10 +150,10 @@ local function apply(instance: T & Instance, properties: { [unknown]: unknown -- clear caches table.clear(events) for _, queued in next, actions do table.clear(queued) end - if strict then table.clear(nested_debug) end + if flags.strict then table.clear(nested_debug) end table.clear(nested_stack) - return_caches(caches) + return_cache(caches) return instance end diff --git a/src/flags.luau b/src/flags.luau index cc2d2f8..bc9424c 100644 --- a/src/flags.luau +++ b/src/flags.luau @@ -4,4 +4,8 @@ end local is_O2 = inline_test() ~= "inline_test" -return { strict = not is_O2, batch = false } +return { + strict = not is_O2, + batch = false, + defer_nested_properties = true +} diff --git a/src/lib.luau b/src/lib.luau index d3e526f..a54bd32 100644 --- a/src/lib.luau +++ b/src/lib.luau @@ -75,6 +75,7 @@ local vide = { -- flags strict = (nil :: any) :: boolean, + defer_nested_properties = (nil :: any) :: boolean, -- temporary apply = function(instance: Instance) @@ -96,18 +97,18 @@ local vide = { setmetatable(vide :: any, { __index = function(_, index: unknown): () - if index == "strict" then - return flags.strict - else + if flags[index] == nil then throw(`{tostring(index)} is not a valid member of vide`) + else + return flags[index] end end, __newindex = function(_, index: unknown, value: unknown) - if index == "strict" then - flags.strict = value :: boolean - else + if flags[index] == nil then throw(`{tostring(index)} is not a valid member of vide`) + else + flags[index] = value end end }) diff --git a/test/tests.luau b/test/tests.luau index 85f5357..b11e47a 100644 --- a/test/tests.luau +++ b/test/tests.luau @@ -759,18 +759,35 @@ TEST("create()", wrap_root(function() CHECK(text.Text == "test") end - do CASE "nested precedence" + do CASE "nested deferred" local text = create "TextLabel" { { + { Text = "2" }, Text = "1", - - { Text = "2" } } } CHECK(text.Text == "2") end + do CASE "nested not deferred" + vide.defer_nested_properties = false + + local t = {} + + create "TextLabel" { + { + { function() table.insert(t, 1) end } :: any, + function() table.insert(t, 2) end, + } + } + + CHECK(t[1] == 1) + CHECK(t[2] == 2) + + vide.defer_nested_properties = true + end + do CASE "independent" local frame = create "Frame" CHECK(frame {} ~= frame {}) From b44b9ef2baa0de0138567fa2ea9cb7460a3f7fdf Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Fri, 27 Dec 2024 01:00:45 +0000 Subject: [PATCH 20/22] Add implicit effects recursively creating more implicit effects for children --- CHANGELOG.md | 4 ++ docs/api/strict-mode.md | 2 +- src/apply.luau | 12 ++-- src/bind.luau | 103 --------------------------------- src/implicit_effect.luau | 119 +++++++++++++++++++++++++++++++++++++++ test/tests.luau | 42 ++++++++++++++ 6 files changed, 170 insertions(+), 112 deletions(-) delete mode 100644 src/bind.luau create mode 100644 src/implicit_effect.luau diff --git a/CHANGELOG.md b/CHANGELOG.md index 83b4399..61b8fd7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,11 +12,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - `create("ClassName", { props })` and `create(Instance, { props })` syntax. - `cleanup()` now accepts `thread` types. +- Implicit effects to set children can now recursively create more implicit + effects to set children. ### Changed - A scope can no longer be destroyed while it is active. Strict mode will check for this. +- Implicit effects to set children now unparent all children when the effect is + destroyed. ### Removed diff --git a/docs/api/strict-mode.md b/docs/api/strict-mode.md index 630a7bd..6f9ee80 100644 --- a/docs/api/strict-mode.md +++ b/docs/api/strict-mode.md @@ -20,7 +20,7 @@ Currently, strict mode will: 4. Checks for `values()` input having duplicate values. 5. Checks for duplicate nested properties at same depth. 6. Checks for destruction of an active scope. -7. Better error reporting and stack traces + creation traces of property bindings. +7. Better error reporting and stack traces. By rerunning reactive scopes twice each time they update, it helps ensure that computations are pure, and that any cleanup is done correctly. diff --git a/src/apply.luau b/src/apply.luau index 754c0d2..2b30ba6 100644 --- a/src/apply.luau +++ b/src/apply.luau @@ -1,10 +1,8 @@ local typeof = game and typeof or require "../test/mock".typeof :: never -local Vector2 = game and Vector2 or require "../test/mock".Vector2 :: never -local UDim2 = game and UDim2 or require "../test/mock".UDim2 :: never local flags = require "./flags" local throw = require "./throw" -local bind = require "./bind" +local implicit_effect = require "./implicit_effect" local _, is_action = require "./action"() local graph = require "./graph" type Node = graph.Node @@ -79,14 +77,14 @@ local function process_properties(properties: Map, instance: I table.insert(cache.events, property) -- add event name to buffer table.insert(cache.events, value :: () -> ()) -- add event listener to buffer else - bind.property(instance, property, value :: () -> ()) -- create implicit effect for property + implicit_effect.property(instance, property, value :: () -> ()) -- create implicit effect for property end else (instance :: any)[property] = value -- set property end elseif type(property) == "number" then if type(value) == "function" then - bind.children(instance, value :: () -> ArrayOrV) -- bind children + implicit_effect.children(instance, value :: () -> ArrayOrV) -- bind children elseif type(value) == "table" then if is_action(value) then table.insert(cache.actions[(value :: any).priority], (value :: any).callback :: () -> ()) -- add action to buffer @@ -138,16 +136,14 @@ local function apply(instance: T & Instance, properties: { [unknown]: unknown end end - -- finally set parent if any if parent then if type(parent) == "function" then - bind.parent(instance, parent :: () -> Instance) + implicit_effect.parent(instance, parent :: () -> Instance) else instance.Parent = parent :: Instance end end - -- clear caches table.clear(events) for _, queued in next, actions do table.clear(queued) end if flags.strict then table.clear(nested_debug) end diff --git a/src/bind.luau b/src/bind.luau deleted file mode 100644 index ff32bcb..0000000 --- a/src/bind.luau +++ /dev/null @@ -1,103 +0,0 @@ -local graph = require "./graph" -type Node = graph.Node -local create_node = graph.create_node -local assert_stable_scope = graph.assert_stable_scope -local evaluate_node = graph.evaluate_node - -function create_implicit_effect(updater: (T) -> T, binding: T) - evaluate_node(create_node(assert_stable_scope(), updater, binding)) -end - -type PropertyBinding = { - instance: Instance, - property: string, - source: () -> unknown -} - -local function update_property_effect(p: PropertyBinding) - (p.instance :: any)[p.property] = p.source() - return p -end - -type ParentBinding = { - instance: Instance, - parent: () -> Instance -} - -local function update_parent_effect(p: ParentBinding) - p.instance.Parent = p.parent() - return p -end - -type ChildrenBinding = { - instance: Instance, - cur_children_set: { [Instance]: true }, - new_children_set: { [Instance]: true }, - children: () -> Instance | { Instance } -} - -type ArrayOrV = V | { V } -local function update_children_effect(p: ChildrenBinding) - local cur_children_set: { [Instance]: true } = p.cur_children_set -- cache of all children parented before update - local new_child_set: { [Instance]: true } = p.new_children_set -- cache of all children parented after update - - local new_children = p.children() -- all (and only) children that should be parented after this update - - if type(new_children) ~= "table" then - new_children = { new_children } - end - - local function process_child(child: ArrayOrV) - if type(child) == "table" then - for _, child in next, child do - process_child(child) - end - else - if new_child_set[child] then return end -- stops redundant reparenting - - new_child_set[child] = true -- record child set from this update - if not cur_children_set[child] then - child.Parent = p.instance -- if child wasn't already parented then parent it - else - cur_children_set[child] = nil -- remove child from cache if it was already in cache - end - end - end - - process_child(new_children) - - for child in next, cur_children_set do - child.Parent = nil -- unparent all children that weren't in the new children set - end - - table.clear(cur_children_set) -- clear cache, preserve capacity - p.cur_children_set, p.new_children_set = new_child_set, cur_children_set - - return p -end - -return { - property = function(instance, property, source) - return create_implicit_effect(update_property_effect, { - instance = instance, - property = property, - source = source - }) - end, - - parent = function(instance, parent) - return create_implicit_effect(update_parent_effect, { - instance = instance, - parent = parent - }) - end, - - children = function(instance, children) - return create_implicit_effect(update_children_effect, { - instance = instance, - cur_children_set = {}, - new_children_set = {}, - children = children - }) - end -} diff --git a/src/implicit_effect.luau b/src/implicit_effect.luau new file mode 100644 index 0000000..5332662 --- /dev/null +++ b/src/implicit_effect.luau @@ -0,0 +1,119 @@ +local graph = require "./graph" +type Node = graph.Node +local create_node = graph.create_node +local assert_stable_scope = graph.assert_stable_scope +local get_scope = graph.get_scope +local evaluate_node = graph.evaluate_node +local push_cleanup = graph.push_cleanup + +local function update_property_effect(p: { + instance: Instance, + property: string, + source: () -> unknown +}) + (p.instance :: any)[p.property] = p.source() + return p +end + +local function update_parent_effect(p: { + instance: Instance, + source: () -> Instance +}) + p.instance.Parent = p.source() + return p +end + +local function update_children_effect(p: { + instance: Instance, + cur_children_set: { [Instance]: true }, + new_children_set: { [Instance]: true }, + source: () -> Instance | { Instance } +}) + local cur_children_set: { [Instance]: true } = p.cur_children_set -- cache of all children parented before update + local new_children_set: { [Instance]: true } = p.new_children_set -- cache of all children parented after update + + local new_children = p.source() -- all (and only) children that should be parented after this update + + local function process_child(child: Instance | { Instance }) + if type(child) == "userdata" then + if new_children_set[child] then return end -- stops redundant reparenting + + new_children_set[child] = true -- record child set from this update + if not cur_children_set[child] then + child.Parent = p.instance -- if child wasn't already parented then parent it + else + cur_children_set[child] = nil -- remove child from cache if it was already in cache + end + elseif type(child) == "table" then + for _, child in next, child do + process_child(child) + end + elseif type(child) == "function" then + local node = create_node(assert(get_scope()), update_children_effect, { + instance = p.instance, + cur_children_set = {}, + new_children_set = {}, + source = child + }) + + evaluate_node(node) + + push_cleanup(assert(get_scope()), function() + for child in node.cache.cur_children_set do + child.Parent = nil + end + end) + end + end + + process_child(new_children) + + for child in next, cur_children_set do + child.Parent = nil -- unparent all children that weren't in the new children set + end + + table.clear(cur_children_set) -- clear cache, preserve capacity + p.cur_children_set, p.new_children_set = new_children_set, cur_children_set + + return p +end + +return { + property = function(instance, property, source) + local node = create_node(assert_stable_scope(), update_property_effect, { + instance = instance, + property = property, + source = source + }) + evaluate_node(node) + return node + end, + + parent = function(instance, parent) + local node = create_node(assert_stable_scope(), update_parent_effect, { + instance = instance, + source = parent + }) + evaluate_node(node) + return node + end, + + children = function(instance, children) + local node = create_node(assert_stable_scope(), update_children_effect, { + instance = instance, + cur_children_set = {}, + new_children_set = {}, + source = children + }) + + evaluate_node(node) + + push_cleanup(assert_stable_scope(), function() + for child in node.cache.cur_children_set do + child.Parent = nil + end + end) + + return node + end +} diff --git a/test/tests.luau b/test/tests.luau index b11e47a..d4c95ae 100644 --- a/test/tests.luau +++ b/test/tests.luau @@ -996,6 +996,48 @@ TEST("create()", wrap_root(function() CHECK(not obj:FindFirstChild("e")) end + do CASE "nested children source effect" + local a = create "Frame" { Name = "a" } :: Instance + local b = create "Frame" { Name = "b" } :: Instance + local c = create "Frame" { Name = "c" } :: Instance + + local nested_children = source { b, c } + local children = source { a :: Instance | () -> { Instance }, nested_children } + + local parent = create "Frame" { + Name = "parent", + children + } + + CHECK(parent:FindFirstChild "a") + CHECK(parent:FindFirstChild "b") + CHECK(parent:FindFirstChild "c") + nested_children {} + CHECK(parent:FindFirstChild "a") + CHECK(not parent:FindFirstChild "b") + CHECK(not parent:FindFirstChild "c") + nested_children { b } + CHECK(parent:FindFirstChild "a") + CHECK(parent:FindFirstChild "b") + CHECK(not parent:FindFirstChild "c") + children { a } + CHECK(parent:FindFirstChild "a") + CHECK(not parent:FindFirstChild "b") + CHECK(not parent:FindFirstChild "c") + nested_children { b, c } + CHECK(parent:FindFirstChild "a") + CHECK(not parent:FindFirstChild "b") + CHECK(not parent:FindFirstChild "c") + children { a :: Instance | () -> { Instance }, nested_children } + CHECK(parent:FindFirstChild "a") + CHECK(parent:FindFirstChild "b") + CHECK(parent:FindFirstChild "c") + nested_children { c } + CHECK(parent:FindFirstChild "a") + CHECK(not parent:FindFirstChild "b") + CHECK(parent:FindFirstChild "c") + end + do CASE "garbage collection test" local wref From 3b22f6ccf937fa327819caf1006c73fcb1f47717 Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Fri, 27 Dec 2024 02:34:31 +0000 Subject: [PATCH 21/22] Add spring setter --- CHANGELOG.md | 2 + docs/api/animation.md | 8 +- src/spring.luau | 136 +++++++++++------------ test/{benchmark.luau => benchmarks.luau} | 0 4 files changed, 75 insertions(+), 71 deletions(-) rename test/{benchmark.luau => benchmarks.luau} (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 61b8fd7..7c6303b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - `cleanup()` now accepts `thread` types. - Implicit effects to set children can now recursively create more implicit effects to set children. +- `spring()` returns a second value, a setter to set position, velocity and + impulse. ### Changed diff --git a/docs/api/animation.md b/docs/api/animation.md index 8b84ce9..8719753 100644 --- a/docs/api/animation.md +++ b/docs/api/animation.md @@ -11,9 +11,15 @@ Returns a new source with a value always moving torwards the input source value. source: () -> T & Animatable, period: number = 1, damping_ratio: number = 1 - ): () -> T + ): (() -> T, Setter) type Animatable = number | CFrame | Color3 | UDim | UDim2 | Vector2 | Vector3 | Rect + + type Setter = ({ + position: T?, + velocity: T?, + impulse: T? + }) -> () ``` - **Details** diff --git a/src/spring.luau b/src/spring.luau index bcd5789..053c945 100644 --- a/src/spring.luau +++ b/src/spring.luau @@ -1,23 +1,3 @@ ---[[ - -Supported datatypes: -- number -- CFrame -- Color3 -- UDim -- UDim2 -- Vector2 -- Vector3 -- Rect - -Unsupported datatypes: -- bool -- Vector2int16 -- Vector3int16 -- EnumItem - -]] - local throw = require "./throw" local graph = require "./graph" type Node = graph.Node @@ -33,68 +13,68 @@ local UPDATE_RATE = 120 local TOLERANCE = 0.001 local TOLERANCE_VECTOR = vector.create(TOLERANCE, TOLERANCE, TOLERANCE) -type Vec3 = Vector3 - -local function Vec3(x: number, y: number, z: number): Vec3 - return vector.create(x, y, z) -end - -local ZERO = Vec3(0, 0, 0) - type Animatable = number | CFrame | Color3 | UDim | UDim2 | Vector2 | Vector3 -type SpringData = { +--[[ +Unsupported datatypes: +- bool +- Vector2int16 +- Vector3int16 +- EnumItem +]] + +type SpringState = { k: number, -- spring constant c: number, -- damping coeff - -- dimensions 1-3 - x0_123: Vec3, - x1_123: Vec3, - v_123: Vec3, - - -- dimensions 4-6 - x0_456: Vec3, - x1_456: Vec3, - v_456: Vec3, + x0_123: vector, x0_456: vector, -- current position + x1_123: vector, x1_456: vector, -- target position + v_123: vector, v_456: vector, -- current velocity source_value: T -- current value of spring input source } -type TypeToVec6 = (T) -> (Vec3, Vec3) -type Vec6ToType = (Vec3, Vec3) -> T +type SpringSettings = ({ + position: T?, + velocity: T?, + impulse: T? +}) -> () + +type TypeToVec6 = (T) -> (vector, vector) +type Vec6ToType = (vector, vector) -> T local type_to_vec6 = { number = function(v) - return Vec3(v, 0, 0), ZERO + return vector.create(v, 0, 0), vector.zero end :: TypeToVec6, CFrame = function(v) - return v.Position, Vec3(v:ToEulerAnglesXYZ()) + return v.Position, vector.create(v:ToEulerAnglesXYZ()) end :: TypeToVec6, Color3 = function(v) -- todo: hsv, oklab? - return Vec3(v.R, v.G, v.B), ZERO + return vector.create(v.R, v.G, v.B), vector.zero end :: TypeToVec6, UDim = function(v) - return Vec3(v.Scale, v.Offset, 0), ZERO + return vector.create(v.Scale, v.Offset, 0), vector.zero end :: TypeToVec6, UDim2 = function(v) - return Vec3(v.X.Scale, v.X.Offset, v.Y.Scale), Vec3(v.Y.Offset, 0, 0) + return vector.create(v.X.Scale, v.X.Offset, v.Y.Scale), vector.create(v.Y.Offset, 0, 0) end :: TypeToVec6, Vector2 = function(v) - return Vec3(v.X, v.Y, 0), ZERO + return vector.create(v.X, v.Y, 0), vector.zero end :: TypeToVec6, Vector3 = function(v) - return v, ZERO + return v, vector.zero end :: TypeToVec6, Rect = function(v) - return Vec3(v.Min.X, v.Min.Y, v.Max.X), Vec3(v.Max.Y, 0, 0) + return vector.create(v.Min.X, v.Min.Y, v.Max.X), vector.create(v.Max.Y, 0, 0) end :: TypeToVec6 } @@ -143,10 +123,10 @@ setmetatable(vec6_to_type, invalid_type) -- maps spring data to its corresponding output node -- lifetime of spring data is tied to output node -local springs: { [SpringData]: SourceNode } = {} -setmetatable(springs, { __mode = "v" }) +local springs: { [SpringState]: SourceNode } = {} +setmetatable(springs :: any, { __mode = "v" }) -local function spring(source: () -> T, period: number?, damping_ratio: number?): () -> T +local function spring(source: () -> T, period: number?, damping_ratio: number?): (() -> T, SpringSettings) local owner = assert_stable_scope() -- https://en.wikipedia.org/wiki/Damping @@ -164,17 +144,17 @@ local function spring(source: () -> T, period: number?, damping_ratio: number throw("spring damping too high, consider reducing damping or increasing period") end - local data: SpringData = { + local data: SpringState = { k = k, c = c, - x0_123 = ZERO, - x1_123 = ZERO, - v_123 = ZERO, + x0_123 = vector.zero, + x1_123 = vector.zero, + v_123 = vector.zero, - x0_456 = ZERO, - x1_456 = ZERO, - v_456 = ZERO, + x0_456 = vector.zero, + x1_456 = vector.zero, + v_456 = vector.zero, source_value = false :: any, } @@ -185,7 +165,7 @@ local function spring(source: () -> T, period: number?, damping_ratio: number local value = source() data.x1_123, data.x1_456 = type_to_vec6[typeof(value)](value) data.source_value = value - springs[data] = output -- todo: investigate why insertion is not O(1) at ~20k springs + springs[data] = output return value end @@ -199,6 +179,28 @@ local function spring(source: () -> T, period: number?, damping_ratio: number -- set output to goal output.cache = data.source_value + local setter = function(p) + local x = p.position + local v = p.velocity + local dv = p.impulse + + if x then + data.x0_123, data.x0_456 = type_to_vec6[typeof(x)](x) + end + + if v then + data.v_123, data.v_456 = type_to_vec6[typeof(v)](v) + end + + if dv then + local dv_123, dv_456 = type_to_vec6[typeof(dv)](dv) + data.v_123 += dv_123 + data.v_456 += dv_456 + end + + springs[data] = output + end :: SpringSettings + return function(...) if select("#", ...) == 0 then -- no args were given push_child_to_scope(output) @@ -210,8 +212,8 @@ local function spring(source: () -> T, period: number?, damping_ratio: number data.x0_123, data.x0_456 = type_to_vec6[typeof(v)](v) -- reset velocity - data.v_123 = ZERO - data.v_456 = ZERO + data.v_123 = vector.zero + data.v_456 = vector.zero -- schedule spring springs[data] = output @@ -220,7 +222,7 @@ local function spring(source: () -> T, period: number?, damping_ratio: number output.cache = v return v - end + end, setter end local function step_springs(dt: number) @@ -264,7 +266,7 @@ end local remove_queue = {} local function update_spring_sources() - for data, output in next, springs do + for data, output in springs do local x0_123, x1_123, v_123, x0_456, x1_456, v_456 = data.x0_123, data.x1_123, data.v_123, @@ -280,7 +282,7 @@ local function update_spring_sources() if max_difference == TOLERANCE_VECTOR then -- close enough to target, unshedule spring and set value to target - table.insert(remove_queue, data) + springs[data] = nil output.cache = data.source_value else output.cache = vec6_to_type[typeof(data.source_value)](x0_123, x0_456) @@ -288,12 +290,6 @@ local function update_spring_sources() update_descendants(output) end - - for _, data in next, remove_queue do - springs[data] = nil - end - - table.clear(remove_queue) end return function() diff --git a/test/benchmark.luau b/test/benchmarks.luau similarity index 100% rename from test/benchmark.luau rename to test/benchmarks.luau From 58a31a1b329e922dc86c554e8220012ab7238f1b Mon Sep 17 00:00:00 2001 From: aaron <83140718+centau@users.noreply.github.com> Date: Fri, 27 Dec 2024 22:43:01 +0000 Subject: [PATCH 22/22] Try improve error reporting --- CHANGELOG.md | 2 + src/apply.luau | 5 +- src/batch.luau | 5 +- src/cleanup.luau | 5 +- src/context.luau | 7 ++- src/create.luau | 7 ++- src/graph.luau | 31 +++++++---- src/lib.luau | 5 +- src/maps.luau | 9 ++-- src/root.luau | 8 ++- src/source.luau | 4 +- src/spring.luau | 7 +-- src/switch.luau | 5 +- src/throw.luau | 5 -- src/untrack.luau | 4 +- test/stacktrace-test.luau | 110 ++++++++++++++++++++++++++++++++++++++ 16 files changed, 164 insertions(+), 55 deletions(-) delete mode 100644 src/throw.luau create mode 100644 test/stacktrace-test.luau diff --git a/CHANGELOG.md b/CHANGELOG.md index 7c6303b..ef49bb2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). for this. - Implicit effects to set children now unparent all children when the effect is destroyed. +- Error reporting should be improved with better formatting when effects invoke + other effects and no more loss of stack traces. ### Removed diff --git a/src/apply.luau b/src/apply.luau index 2b30ba6..95645da 100644 --- a/src/apply.luau +++ b/src/apply.luau @@ -1,7 +1,6 @@ local typeof = game and typeof or require "../test/mock".typeof :: never local flags = require "./flags" -local throw = require "./throw" local implicit_effect = require "./implicit_effect" local _, is_action = require "./action"() local graph = require "./graph" @@ -67,7 +66,7 @@ local function process_properties(properties: Map, instance: I if type(property) == "string" then if flags.strict then -- check for duplicate property assignment at nesting depth if cache.nested_debug[depth][property] then - throw(`duplicate property {property} at depth {depth}`) + error(`duplicate property {property} at depth {depth}`, 0) end cache.nested_debug[depth][property] = true end @@ -104,7 +103,7 @@ end -- applies table of nested properties to an instance using full vide semantics local function apply(instance: T & Instance, properties: { [unknown]: unknown }): T if not properties then - throw("attempt to call a constructor returned by create() with no properties") + error "attempt to call a constructor returned by create() with no properties" end -- queue parent assignment if any for last diff --git a/src/batch.luau b/src/batch.luau index 4cd7581..e3e6d40 100644 --- a/src/batch.luau +++ b/src/batch.luau @@ -1,5 +1,4 @@ local flags = require "./flags" -local throw = require "./throw" local graph = require "./graph" local function batch(setter: () -> ()) @@ -11,14 +10,14 @@ local function batch(setter: () -> ()) from = graph.get_update_queue_length() end - local ok, err: string? = pcall(setter) + local ok, err: string? = xpcall(setter, debug.traceback) if not already_batching then flags.batch = false graph.flush_update_queue(from) end - if not ok then throw(`error occured while batching updates: {err}`) end + if not ok then error(`error occured while batching updates: {err}`, 0) end end return batch diff --git a/src/cleanup.luau b/src/cleanup.luau index 20d188b..6c46bbf 100644 --- a/src/cleanup.luau +++ b/src/cleanup.luau @@ -1,6 +1,5 @@ local typeof = game and typeof or require "../test/mock".typeof :: never -local throw = require "./throw" local graph = require "./graph" local get_scope = graph.get_scope local push_cleanup = graph.push_cleanup @@ -14,14 +13,14 @@ local function helper(obj: any) elseif obj.disconnect then function() obj:disconnect() end elseif obj.Destroy then function() obj:Destroy() end elseif obj.Disconnect then function() obj:Disconnect() end - else throw("cannot cleanup given object") + else error "cannot cleanup given object" end local function cleanup(value: unknown) local scope = get_scope() if not scope then - throw "cannot cleanup outside a stable or reactive scope" + error "cannot cleanup outside a stable or reactive scope" end; assert(scope) if type(value) == "function" then diff --git a/src/context.luau b/src/context.luau index a46ad5a..2ce3eff 100644 --- a/src/context.luau +++ b/src/context.luau @@ -1,4 +1,3 @@ -local throw = require "./throw" local graph = require "./graph" type Node = graph.Node local create_node = graph.create_node @@ -44,10 +43,10 @@ local function context(...: T): Context if has_default ~= nil then return default_value else - throw("attempt to get context when no context is set and no default context is set") + error("attempt to get context when no context is set and no default context is set", 0) end else -- set - if not scope then return throw("attempt to set context outside of a vide scope") end + if not scope then return error("attempt to set context outside of a vide scope", 0) end local value, component = ... @@ -62,7 +61,7 @@ local function context(...: T): Context pop_scope() if not ok then - throw(`error while running context:\n\n{result}`) + error(`error while running context:\n\n{result}`, 0) end return result diff --git a/src/create.luau b/src/create.luau index dea8ca7..ebcbf54 100644 --- a/src/create.luau +++ b/src/create.luau @@ -1,7 +1,6 @@ local typeof = game and typeof or require "../test/mock".typeof :: never local Instance = game and Instance or require "../test/mock".Instance :: never -local throw = require "./throw" local defaults = require "./defaults" local apply = require "./apply" @@ -10,7 +9,7 @@ local ctor_cache = {} :: { [string]: () -> Instance } setmetatable(ctor_cache :: any, { __index = function(self, class) local ok, instance: Instance = pcall(Instance.new, class :: any) - if not ok then throw(`invalid class name, could not create instance of class { class }`) end + if not ok then error(`invalid class name, could not create instance of class { class }`, 0) end local default: { [string]: unknown }? = defaults[class] if default then @@ -35,7 +34,7 @@ end local function clone_instance(instance: Instance) return function(properties: Props): Instance local clone = instance:Clone() - if not clone then throw "attempt to clone a non-archivable instance" end + if not clone then error "attempt to clone a non-archivable instance" end return apply(clone, properties) end end @@ -47,7 +46,7 @@ local function create(class_or_instance: string | Instance, props: Props?): ((Pr elseif typeof(class_or_instance) == "Instance" then result = clone_instance(class_or_instance) else - throw("bad argument #1, expected string or instance, got " .. typeof(class_or_instance)) + error("bad argument #1, expected string or instance, got " .. typeof(class_or_instance), 0) return nil :: never end if props then diff --git a/src/graph.luau b/src/graph.luau index be58b15..360c0cb 100644 --- a/src/graph.luau +++ b/src/graph.luau @@ -1,4 +1,3 @@ -local throw = require "./throw" local flags = require "./flags" export type SourceNode = { @@ -22,9 +21,23 @@ export type Node = { local scopes = { n = 0 } :: { [number]: Node, n: number } -- scopes stack +local function efn(err: string) + local trace = debug.traceback(err, 2) + + if string.find(err, "^effect error stacktrace") then -- if effect error is nested + trace = string.gsub(" " .. trace, "\n", function() -- indent entire error + return "\n " + end) + end + + trace ..= "\nsource update stacktrace:" +return trace +end + local function ycall(fn: (T) -> U, arg: T): (boolean, string|U) + local thread = coroutine.create(xpcall) - local function efn(err: string) return debug.traceback(err, 3) end + --local function efn(err: string) return debug.traceback(err, 3) end local resume_ok, run_ok, result = coroutine.resume(thread, fn, efn, arg) assert(resume_ok) @@ -45,9 +58,9 @@ local function assert_stable_scope(): Node if not scope then local caller_name = debug.info(2, "n") - return throw(`cannot use {caller_name}() outside a stable or reactive scope`) + return error(`cannot use {caller_name}() outside a stable or reactive scope`, 0) elseif scope.effect then - throw("cannot create a new reactive scope inside another reactive scope") + error("cannot create a new reactive scope inside another reactive scope", 0) end return scope @@ -81,8 +94,8 @@ end local function flush_cleanups(node: Node) if node.cleanups then for _, fn in next, node.cleanups do - local ok, err: string? = pcall(fn) - if not ok then throw(`cleanup error: {err}`) end + local ok, err: string? = xpcall(fn, debug.traceback) + if not ok then error(`cleanup error: {err}`, 0) end end table.clear(node.cleanups) @@ -107,7 +120,7 @@ end local function destroy(node: Node) if flags.strict and table.find(scopes, node) then - throw("attempt to destroy an active scope") + error("attempt to destroy an active scope", 0) end flush_cleanups(node) @@ -150,7 +163,7 @@ local function evaluate_node(node: Node) if not ok then table.clear(update_queue) update_queue.n = 0 - throw(`effect stacktrace:\n{new_value :: string}`) + error(`effect error stacktrace\n{new_value :: string}`, 0) end node.cache = new_value :: T @@ -170,7 +183,7 @@ local function evaluate_node(node: Node) if not ok then table.clear(update_queue) update_queue.n = 0 - throw(`effect stacktrace:\n{new_value}\n`) + error(`effect error:\n{new_value}\n`, 0) end node.cache = new_value diff --git a/src/lib.luau b/src/lib.luau index a54bd32..3d7f3be 100644 --- a/src/lib.luau +++ b/src/lib.luau @@ -18,7 +18,6 @@ local indexes, values = require "./maps"() local spring, update_springs = require "./spring"() local action = require "./action"() local changed = require "./changed" -local throw = require "./throw" local flags = require "./flags" export type Source = source.Source @@ -98,7 +97,7 @@ local vide = { setmetatable(vide :: any, { __index = function(_, index: unknown): () if flags[index] == nil then - throw(`{tostring(index)} is not a valid member of vide`) + error(`{tostring(index)} is not a valid member of vide`, 0) else return flags[index] end @@ -106,7 +105,7 @@ setmetatable(vide :: any, { __newindex = function(_, index: unknown, value: unknown) if flags[index] == nil then - throw(`{tostring(index)} is not a valid member of vide`) + error(`{tostring(index)} is not a valid member of vide, 0`) else flags[index] = value end diff --git a/src/maps.luau b/src/maps.luau index bd59a6c..0f95695 100644 --- a/src/maps.luau +++ b/src/maps.luau @@ -1,4 +1,3 @@ -local throw = require "./throw" local flags = require "./flags" local graph = require "./graph" type Node = graph.Node @@ -20,7 +19,7 @@ local function check_primitives(t: {}) for _, v in next, t do if type(v) == "table" or type(v) == "userdata" or type(v) == "function" then continue end - throw("table source map cannot return primitives") + error("table source map cannot return primitives", 0) end end @@ -71,7 +70,7 @@ local function indexes(input: () -> Map, transform: (() -> VI, push_scope(scope) - local ok, result = pcall(transform, function() + local ok, result = xpcall(transform, debug.traceback, function() push_child_to_scope(node) return node.cache end, i) @@ -132,7 +131,7 @@ local function values(input: () -> Map, transform: (VI, () -> local cache = {} for _, v in next, data do if cache[v] ~= nil then - throw "duplicate table value detected" + error "duplicate table value detected" end cache[v] = true end @@ -154,7 +153,7 @@ local function values(input: () -> Map, transform: (VI, () -> push_scope(scope) - local ok, result = pcall(transform, v, function() + local ok, result = xpcall(transform, debug.traceback, v, function() push_child_to_scope(node) return node.cache end) diff --git a/src/root.luau b/src/root.luau index d8dc230..bc9c2fc 100644 --- a/src/root.luau +++ b/src/root.luau @@ -1,4 +1,3 @@ -local throw = require "./throw" local graph = require "./graph" type Node = graph.Node local create_node = graph.create_node @@ -14,21 +13,20 @@ local function root(fn: (destroy: () -> ()) -> T...): (() -> (), T...) refs[node] = true -- prevent gc of root node local destroy = function() - if not refs[node] then throw "root already destroyed" end + if not refs[node] then error "root already destroyed" end refs[node] = nil destroy(node) end push_scope(node) - local function efn(err: string) return debug.traceback(err, 3) end - local result = { xpcall(fn, efn, destroy) } + local result = { xpcall(fn, debug.traceback, destroy) } pop_scope() if not result[1] then destroy() - throw(`error while running root():\n\n{result[2]}`) + error(`error while running root():\n\n{result[2]}`, 0) end return destroy, unpack(result :: any, 2) diff --git a/src/source.luau b/src/source.luau index 0b89637..d7aa53d 100644 --- a/src/source.luau +++ b/src/source.luau @@ -9,7 +9,7 @@ export type Source = (() -> T) & ((value: T) -> T) local function source(initial_value: T): Source local node = create_source_node(initial_value) - return function(...): T + local function update_source(...): T if select("#", ...) == 0 then -- no args were given push_child_to_scope(node) return node.cache @@ -24,6 +24,8 @@ local function source(initial_value: T): Source update_descendants(node) return v end + + return update_source end return source :: ((initial_value: T) -> Source) & (() -> Source) diff --git a/src/spring.luau b/src/spring.luau index 053c945..aaf6789 100644 --- a/src/spring.luau +++ b/src/spring.luau @@ -1,4 +1,3 @@ -local throw = require "./throw" local graph = require "./graph" type Node = graph.Node type SourceNode = graph.SourceNode @@ -114,7 +113,7 @@ local vec6_to_type = { local invalid_type = { __index = function(_, t: string) - throw(`cannot spring type {t}`) + error(`cannot spring type {t}`, 0) end } @@ -141,7 +140,7 @@ local function spring(source: () -> T, period: number?, damping_ratio: number -- todo: is there a solution other than reducing step size? -- todo: this does not catch all solver exploding cases if c > UPDATE_RATE*2 then -- solver will explode if this is true - throw("spring damping too high, consider reducing damping or increasing period") + error("spring damping too high, consider reducing damping or increasing period", 0) end local data: SpringState = { @@ -263,8 +262,6 @@ local function step_springs(dt: number) end end -local remove_queue = {} - local function update_spring_sources() for data, output in springs do local x0_123, x1_123, v_123, diff --git a/src/switch.luau b/src/switch.luau index cb7cba4..547fc80 100644 --- a/src/switch.luau +++ b/src/switch.luau @@ -1,4 +1,3 @@ -local throw = require "./throw" local graph = require "./graph" type Node = graph.Node type SourceNode = graph.SourceNode @@ -32,7 +31,7 @@ local function switch(source: () -> T): (map: Map U)?)>) -> () if component == nil then return nil end if type(component) ~= "function" then - throw "map must map a value to a function" + error "map must map a value to a function" end local new_scope = create_node(owner, false, false) @@ -40,7 +39,7 @@ local function switch(source: () -> T): (map: Map U)?)>) -> () push_scope(new_scope) - local ok, result = pcall(component) + local ok, result = xpcall(component, debug.traceback) pop_scope() diff --git a/src/throw.luau b/src/throw.luau deleted file mode 100644 index 4135f69..0000000 --- a/src/throw.luau +++ /dev/null @@ -1,5 +0,0 @@ -local function VIDE_ASSERT(msg): any - error(msg, 0) -end - -return VIDE_ASSERT diff --git a/src/untrack.luau b/src/untrack.luau index 90ceee2..577da25 100644 --- a/src/untrack.luau +++ b/src/untrack.luau @@ -10,13 +10,13 @@ local function untrack(source: () -> T): T local effect = scope.effect scope.effect = false - local ok, result = pcall(source) + local ok, result = xpcall(source, debug.traceback) scope.effect = effect :: () -> () if not ok then error(result, 0) end - return result + return result :: T else return source() end diff --git a/test/stacktrace-test.luau b/test/stacktrace-test.luau new file mode 100644 index 0000000..e24c314 --- /dev/null +++ b/test/stacktrace-test.luau @@ -0,0 +1,110 @@ +local vide = require "../" + +do + print "=============================================================" + + local a = vide.source(1) + + local cause_error = false + + local function try_error() + if cause_error then error("uh oh") end + end + + vide.root(function() + vide.effect(function() + a() + try_error() + end) + end) + + cause_error = true + + local ok, result = pcall(function() a(2) end) + print(result) + + print "=============================================================" +end + +do + print "=============================================================" + + local a = vide.source(1) + local b = vide.source(1) + local c = vide.source(1) + + local cause_error = false + + local function try_error() + if cause_error then error("uh oh") end + end + + vide.root(function() + vide.effect(function() + a() + b(vide.untrack(b) + 1) + end) + + vide.effect(function() + b() + c(vide.untrack(c) + 1) + end) + + + vide.effect(function() + c() + try_error() + end) + end) + + cause_error = true + + local ok, result = pcall(function() a(2) end) + print(result) + + print "=============================================================" +end + +do + print "=============================================================" + + local a = vide.source(1) + local b = vide.source(1) + local c = vide.source(1) + + local cause_error = false + + local function try_error() + if cause_error then error("uh oh") end + end + + vide.root(function() + vide.effect(function() + a() + vide.untrack(function() -- todo: this trace appearing twice + b(b() + 1) + return nil + end) + end) + + vide.effect(function() + b() + vide.batch(function() + c(vide.untrack(c) + 1) + end) + end) + + + vide.effect(function() + c() + try_error() + end) + end) + + cause_error = true + + local ok, result = pcall(function() a(2) end) + print(result) + + print "=============================================================" +end