@rbxts/centurion-ui 1.0.7 → 2.0.0-rc.1

package/vide/src/indexes.luau

@@ -0,0 +1,121 @@
+local flags = require "./flags"
+local branch = require "./branch"
+local source = require "./source"
+local effect = require "./effect"
+local timeout = require "./timeout" ()
+
+type Array<T> = { T }
+type Map<K, V> = { [K]: V }
+type Source<T> = () -> T
+
+local function indexes<K, V, Obj>(
+    input: Source<Map<K, V>>,
+    component: (Source<V>, K, Source<boolean>) -> (Obj, ...number)
+): Source<Array<Obj>>
+    local update_count = 0
+    local scopes = {} :: Map<K, {
+        destroy: () -> (),
+        object: Obj,
+        value: V?,
+        value_source: (V?) -> V,
+        count: number,
+        delay: number,
+        present: (boolean?) -> boolean,
+        timeout: { cancel: boolean }?,
+    }>
+
+    local output = source({} :: Array<Obj>)
+    local function update_output()
+        local objects = table.create(4)
+
+        for _, scope in scopes do
+            table.insert(objects, scope.object)
+        end
+
+        output(objects)
+    end
+
+    effect(function()
+        local data = input()
+
+        local count = update_count
+        update_count += 1
+
+        local children_need_update = false -- set to true if a scope is created or destroyed
+
+        -- create or update scopes
+        for i, v in data do
+            local scope = scopes[i]
+
+            if scope == nil then -- create new scope and create component
+                local value_source = source(v)
+                local present = source(false)
+
+                local delay = nil :: number?
+                local destroy, object = branch(function()
+                    local object, t = component(value_source, i, present)
+                    delay = t
+                    return object
+                end)
+
+                present(true)
+                
+                children_need_update = true
+
+                scopes[i] = {
+                    destroy = destroy,
+                    object = object,
+                    value = v,
+                    value_source = value_source,
+                    count = count,
+                    delay = delay or 0,
+                    present = present,
+                    timeout = nil,
+                }
+            else -- update scope
+                scope.count = count
+
+                if scope.value ~= v then
+                    if scope.timeout then -- index is in input table again; cancel destruction
+                        scope.timeout.cancel = true
+                        scope.timeout = nil
+                        scope.present(true)
+                    end
+                    
+                    scope.value = v
+                    scope.value_source(v)
+                end
+            end
+        end
+
+        -- destroy scopes
+        for i, scope in scopes do
+            if scope.count < count then -- if count is not latest then index is no longer in the input table
+                scope.present(false)
+
+                if scope.delay == 0 then
+                    scope.destroy()
+                    scopes[i] = nil
+                    children_need_update = true
+                else
+                    scope.value = nil -- set to nil for the `scope.value ~= v` check
+                    if scope.timeout == nil then
+                        scope.timeout = timeout(scope.delay, function() -- todo: possible redundant updates
+                            scope.destroy()
+                            scopes[i] = nil
+                            update_output()
+                        end)
+                    end
+                end
+            end
+        end
+
+        if children_need_update then
+            update_output()
+        end
+    end)
+
+    return output
+end
+
+return indexes

package/vide/src/init.luau

@@ -0,0 +1,10 @@
+assert(game, "when using vide outside of Roblox, require lib.luau instead")
+
+local vide = require(script.lib)
+
+export type source<T> = vide.source<T>
+export type Source<T> = vide.Source<T>
+export type context<T> = vide.context<T>
+export type Context<T> = vide.Context<T>
+
+return vide

package/vide/src/lib.luau

@@ -0,0 +1,120 @@
+local version = { major = 0, minor = 4, patch = 1 }
+
+local root = require "./root"
+local branch = require "./branch"
+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 = require "./indexes"
+local values = require "./values"
+local spring, update_springs = require "./spring"()
+local action = require "./action"()
+local changed = require "./changed"
+local timeout, update_timeouts = require "./timeout"()
+local flags = require "./flags"
+
+export type Source<T> = source.Source<T>
+export type source<T> = Source<T>
+export type Context<T> = context.Context<T>
+export type context<T> = Context<T>
+
+local function step(dt: number)
+    if game then debug.profilebegin("VIDE STEP") end
+
+    if game then debug.profilebegin("VIDE SPRING") end
+    update_springs(dt)
+    if game then debug.profileend() end
+
+    if game then debug.profilebegin("VIDE SCHEDULER") end
+    update_timeouts(dt)
+    if game then debug.profileend() end
+
+    if game then 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,
+    --branch = branch,
+    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,
+    defaults = (nil :: any) :: boolean,
+    defer_nested_properties = (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 flags[index] == nil then
+            error(`{tostring(index)} is not a valid member of vide`, 0)
+        else
+            return flags[index]
+        end
+    end,
+
+    __newindex = function(_, index: unknown, value: unknown)
+        if flags[index] == nil then
+            error(`{tostring(index)} is not a valid member of vide, 0`)
+        else
+            flags[index] = value
+        end
+    end
+})
+
+return vide

package/vide/src/mount.luau

@@ -0,0 +1,11 @@
+local root = require "./root"
+local apply = require "./apply"
+
+local function mount<T>(component: () -> T, target: Instance?): () -> ()
+    return root(function()
+        local result = component()
+        if target then apply(target, { result }) end
+    end)
+end
+
+return mount :: (<T>(component: () -> T, target: Instance) -> () -> ()) & ((component: () -> ()) -> () -> ())

package/vide/src/read.luau

@@ -0,0 +1,5 @@
+local function read<T>(value: T | () -> T): T
+    return if type(value) == "function" then value() else value
+end
+
+return read

package/vide/src/root.luau

@@ -0,0 +1,35 @@
+local graph = require "./graph"
+type Node<T> = graph.Node<T>
+local create_node = graph.create_node
+local push_scope = graph.push_scope
+local pop_scope = graph.pop_scope
+local destroy = graph.destroy
+
+local refs = {}
+
+local function root<T...>(fn: (destroy: () -> ()) -> T...): (() -> (), T...)
+    local node = create_node(false, false, false)
+
+    refs[node] = true -- prevent gc of root node
+
+    local destroy = function()
+        if not refs[node] then error "root already destroyed" end
+        refs[node] = nil
+        destroy(node)
+    end
+
+    push_scope(node)
+
+    local result = { xpcall(fn, debug.traceback, destroy) }
+
+    pop_scope()
+
+    if not result[1] then
+        destroy()
+        error(`error while running root():\n\n{result[2]}`, 0)
+    end
+
+    return destroy, unpack(result :: any, 2)
+end
+
+return root :: <T...>(fn: (destroy: () -> ()) -> T...) -> (() -> (), T...)

package/vide/src/show.luau

@@ -0,0 +1,36 @@
+local source = require "./source"
+local derive = require "./derive"
+local effect = require "./effect"
+local untrack = require "./untrack"
+local switch = require "./switch"
+
+type Array<T> = { T }
+type Source<T> = () -> T
+
+local function show<T, Obj>(
+    input: Source<T?>,
+    component: (Source<T>, Source<boolean>) -> (Obj, ...number),
+    fallback: ((Source<boolean>) -> (Obj, ...number))?
+): Source<nil | Obj | Array<Obj>>
+    local filtered_input = source()
+
+    effect(function()
+        local v = input() 
+        if v then
+            filtered_input(v)
+        end
+    end)
+
+    local input_is_truthy = derive(function()
+        return not not input()
+    end)
+
+    return switch(input_is_truthy) {
+        [true] = function(present)
+            return component(filtered_input, present)
+        end,
+        [false] = fallback
+    }
+end
+
+return show

package/vide/src/source.luau

@@ -0,0 +1,31 @@
+local graph = require "./graph"
+type Node<T> = graph.Node<T>
+local create_source_node = graph.create_source_node
+local push_scope_as_child_of = graph.push_scope_as_child_of
+local update_descendants = graph.update_descendants
+
+export type Source<T> = (() -> T) & ((value: T) -> T)
+
+local function source<T>(initial_value: T): Source<T>
+    local node = create_source_node(initial_value)
+
+    local function update_source(...): T
+        if select("#", ...) == 0 then -- no args were given
+            push_scope_as_child_of(node)
+            return node.cache
+        end
+
+        local v = ... :: T
+        if node.cache == v and (type(v) ~= "table" or table.isfrozen(v)) then 
+            return v
+        end
+
+        node.cache = v
+        update_descendants(node)
+        return v
+    end
+
+    return update_source
+end
+
+return source :: (<T>(initial_value: T) -> Source<T>) & (<T>() -> Source<T>)

package/vide/src/spring.luau

@@ -0,0 +1,328 @@
+local graph = require "./graph"
+type Node<T> = graph.Node<T>
+type SourceNode<T> = graph.SourceNode<T>
+local create_node = graph.create_node
+local create_source_node = graph.create_source_node
+local assert_stable_scope = graph.assert_stable_scope
+local evaluate_node = graph.evaluate_node
+local update_descendants = graph.update_descendants
+local push_scope_as_child_of = graph.push_scope_as_child_of
+
+local UPDATE_RATE = 120
+local TOLERANCE_FACTOR = 10_000
+
+type Animatable = number | CFrame | Color3 | UDim | UDim2 | Vector2 | Vector3
+
+--[[
+Unsupported datatypes:
+- bool
+- Vector2int16
+- Vector3int16
+- EnumItem
+]]
+
+type SpringState<T> = {
+    k: number, -- spring constant
+    c: number, -- damping coeff
+
+    x0_123: vector, x0_456: vector, -- initial position
+    x_123: vector, x_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 SpringSettings<T> = ({
+    position: T?,
+    velocity: T?,
+    impulse: T?
+}) -> ()
+
+type TypeToVec6<T> = (T) -> (vector, vector)
+type Vec6ToType<T> = (vector, vector) -> T
+
+local type_to_vec6 = {
+    number = function(v)
+        return vector.create(v, 0, 0), vector.zero
+    end :: TypeToVec6<number>,
+
+    CFrame = function(v)
+        return v.Position, vector.create(v:ToEulerAnglesXYZ())
+    end :: TypeToVec6<CFrame>,
+
+    Color3 = function(v)
+        -- todo: hsv, oklab?
+        return vector.create(v.R, v.G, v.B), vector.zero
+    end :: TypeToVec6<Color3>,
+
+    UDim = function(v)
+        return vector.create(v.Scale, v.Offset, 0), vector.zero
+    end :: TypeToVec6<UDim>,
+    
+    UDim2 = function(v)
+        return vector.create(v.X.Scale, v.X.Offset, v.Y.Scale), vector.create(v.Y.Offset, 0, 0)
+    end :: TypeToVec6<UDim2>,
+
+    Vector2 = function(v)
+        return vector.create(v.X, v.Y, 0), vector.zero
+    end :: TypeToVec6<Vector2>,
+
+    Vector3 = function(v)
+        return v, vector.zero
+    end :: TypeToVec6<Vector3>,
+
+    Rect = function(v)
+        return vector.create(v.Min.X, v.Min.Y, v.Max.X), vector.create(v.Max.Y, 0, 0)
+    end :: TypeToVec6<Rect>,
+
+    table = function(v)
+        return vector.create(v[1] or 0, v[2] or 0, v[3] or 0), vector.create(v[4] or 0, 0, 0)
+    end :: TypeToVec6<{ number }>
+}
+
+local vec6_to_type = {
+    number = function(a, b)
+        return a.X
+    end :: Vec6ToType<number>,
+
+    CFrame = function(a, b)
+        return CFrame.new(a) * CFrame.fromEulerAnglesXYZ(b.X, b.Y, b.Z)
+    end :: Vec6ToType<CFrame>,
+
+    Color3 = function(v)
+        return Color3.new(math.clamp(v.X, 0, 1), math.clamp(v.Y, 0, 1), math.clamp(v.Z, 0, 1))
+    end :: Vec6ToType<Color3>,
+
+    UDim = function(v)
+        return UDim.new(v.X, math.round(v.Y))
+    end :: Vec6ToType<UDim>,
+    
+    UDim2 = function(a, b)
+        return UDim2.new(a.X, math.round(a.Y), a.Z, math.round(b.X))
+    end :: Vec6ToType<UDim2>,
+
+    Vector2 = function(v)
+        return Vector2.new(v.X, v.Y)
+    end :: Vec6ToType<Vector2>,
+
+    Vector3 = function(v)
+        return v
+    end :: Vec6ToType<Vector3>,
+
+    Rect = function(a, b)
+        return Rect.new(a.X, a.Y, a.Z, b.X)
+    end :: Vec6ToType<Rect>,
+
+    table = function(a, b)
+        return { a.X, a.Y, a.Z, b.X }
+    end :: Vec6ToType<{ number }>
+}
+
+local invalid_type = {
+    __index = function(_, t: string)
+        error(`cannot spring type {t}`, 0)
+    end
+}
+
+setmetatable(type_to_vec6, invalid_type)
+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: { [SpringState<unknown>]: SourceNode<unknown> } = {}
+setmetatable(springs :: any, { __mode = "v" })
+
+local function spring<T>(source: () -> T, period: number?, damping_ratio: number?): (() -> T, SpringSettings<T>)
+    local owner = assert_stable_scope()
+
+    -- https://en.wikipedia.org/wiki/Damping
+    local w_n = 2*math.pi / (period or 1)
+    local z = damping_ratio or 1
+    local k = w_n^2
+    local c_c = 2*w_n
+    local c = z * c_c
+
+    -- 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
+        error("spring damping too high, consider reducing damping or increasing period", 0)
+    end
+
+    local data: SpringState<T> = {
+        k = k,
+        c = c,
+
+        x0_123 = vector.zero,
+        x_123 = vector.zero,
+        x1_123 = vector.zero,
+        v_123 = vector.zero,
+
+        x0_456 = vector.zero,
+        x_456 = vector.zero,
+        x1_456 = vector.zero,
+        v_456 = vector.zero,
+
+        source_value = false :: any,
+    }
+    
+    local output = create_source_node(false :: any)
+
+    local function updater_effect()
+        local value = source()
+        data.x1_123, data.x1_456 = type_to_vec6[typeof(value)](value)
+        data.source_value = value
+        springs[data] = output
+        return value
+    end
+
+    local updater = create_node(owner, updater_effect, false :: any)
+    evaluate_node(updater)
+
+    -- set initial position to goal
+    data.x_123, data.x_456 = data.x1_123, data.x1_456
+
+    -- set output to goal
+    output.cache = data.source_value
+
+    local config = function(p)
+        local x = p.position
+        local v = p.velocity
+        local dv = p.impulse
+
+        if x then
+            local x_123, x_456 = type_to_vec6[typeof(x)](x)
+            data.x_123, data.x_456 = x_123, x_456
+            data.x0_123, data.x0_456 = x_123, x_456
+        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
+
+        -- schedule spring
+        springs[data] = output
+    end :: SpringSettings<T>
+
+    return function(...)
+        if select("#", ...) == 0 then -- no args were given
+            push_scope_as_child_of(output)
+            return output.cache
+        end
+
+        -- set current position to value
+        local v = ... :: T
+        data.x_123, data.x_456 = type_to_vec6[typeof(v)](v)
+
+        -- reset velocity
+        data.v_123 = vector.zero
+        data.v_456 = vector.zero
+
+        -- schedule spring
+        springs[data] = output
+
+        -- set output to value
+        output.cache = v
+
+        return v
+    end, config
+end
+
+-- calculates a float tolerance, based on the magnitude of the float
+local function get_min_step(x: number): number
+    return x/TOLERANCE_FACTOR
+end
+local function get_min_vector_step(direction: vector): vector
+    return vector.create(
+        get_min_step(direction.x),
+        get_min_step(direction.y),
+        get_min_step(direction.z)
+    )
+end
+
+local function step_springs(dt: number)
+    for s in springs do
+        local k = s.k
+        local c = s.c
+        local x_123, x_456 = s.x_123, s.x_456
+        local x1_123, x1_456 = s.x1_123, s.x1_456
+        local u_123, u_456 = s.v_123, s.v_456
+
+        -- calculate displacement from target
+        local dx_123 = x_123 - x1_123
+        local dx_456 = x_456 - x1_456
+
+        -- calculate spring force
+        local fs_123 = dx_123*-k
+        local fs_456 = dx_456*-k
+
+        -- calculate friction force
+        local ff_123 = u_123*-c
+        local ff_456 = u_456*-c
+
+        -- calculate acceleration
+        local a_123 = (fs_123 + ff_123)
+        local a_456 = (fs_456 + ff_456)
+
+        -- step acceleration
+        local v_123 = u_123 + a_123*dt
+        local v_456 = u_456 + a_456*dt
+
+        -- step velocity
+        local y_123 = x_123 + v_123*dt
+        local y_456 = x_456 + v_456*dt
+
+        s.x_123, s.x_456 = y_123, y_456
+        s.v_123, s.v_456 = v_123, v_456
+    end
+end
+
+local function update_spring_sources()
+    for data, output in springs do
+        local x0_123, x0_456 = data.x0_123, data.x0_456
+        local x_123, x_456 = data.x_123, data.x_456
+        local x1_123, x1_456 = data.x1_123, data.x1_456
+        local v_123, v_456 = data.v_123, data.v_456
+
+        local tol_123 = vector.abs(get_min_vector_step(x0_123 - x1_123))
+        local tol_456 = vector.abs(get_min_vector_step(x0_456 - x1_456))
+
+        if
+            -- position is at goal (within tolerance)
+            vector.max(vector.abs(x_123 - x1_123), tol_123) == tol_123
+            and vector.max(vector.abs(x_456 - x1_456), tol_456) == tol_456
+
+            -- velocity is at 0 (within tolerance)
+            and vector.max(vector.abs(v_123/10), tol_123) == tol_123
+            and vector.max(vector.abs(v_456/10), tol_456) == tol_456
+        then
+            springs[data] = nil
+            output.cache = data.source_value
+        else
+            output.cache = vec6_to_type[typeof(data.source_value)](x_123, x_456)
+        end
+
+        update_descendants(output)
+    end
+end
+
+return function()
+    local time_elapsed = 0
+
+    return spring, function(dt: number)
+        time_elapsed += dt
+
+        while time_elapsed > 1 / UPDATE_RATE do
+            time_elapsed -= 1 / UPDATE_RATE
+            step_springs(1 / UPDATE_RATE)
+        end
+
+        update_spring_sources()
+    end
+end