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

package/src/ts/index.d.ts

@@ -0,0 +1,60 @@
+import { Response } from "@rbxts/centurion";
+
+export interface Options {
+	hide_on_lost_focus: boolean;
+	activation_keys: Enum.KeyCode[];
+	theme: Theme;
+	font: Font;
+	icon: string;
+	transparency: number;
+	format_date: (log: Log) => string;
+	max_suggestions: number;
+
+	text_size: number;
+	subtext_size: number;
+
+	anchor: Vector2;
+	width: UDim;
+	position: UDim2;
+}
+
+export interface Theme {
+	background: Color3;
+	surface: Color3;
+	text: Color3;
+	subtext: Color3;
+	highlight: Color3;
+	success: Color3;
+	error: Color3;
+}
+
+export interface Log {
+	command: string;
+	response: Response;
+}
+
+export namespace CenturionUI {
+	export function mount(keys?: Enum.KeyCode[]): void;
+
+	export function configure(options: Partial<Options>): void;
+
+	export function register_commands(options?: { exclude?: string[]; prefix?: string }): void;
+
+	export function clear(): void;
+
+	export function open(): void;
+
+	export function close(): void;
+
+	export function toggle(): void;
+
+	export function is_open(): boolean;
+
+	export const themes: {
+		frappe: Theme;
+		macchiato: Theme;
+		latte: Theme;
+		mocha: Theme;
+		roblox: Theme;
+	};
+}

package/src/ts/init.luau

@@ -0,0 +1,5 @@
+local ui = require("./.")
+
+return {
+	CenturionUI = ui,
+}

package/src/types.luau

@@ -0,0 +1,85 @@
+local centurion = require("../centurion")
+export type Suggestion = {
+	name: string,
+	type: string,
+	description: string?,
+}
+
+export type Options = {
+	hide_on_lost_focus: boolean,
+	activation_keys: { Enum.KeyCode },
+	theme: Theme,
+	font: Font,
+	icon: string,
+	transparency: number,
+	format_date: (log: Log) -> string,
+	max_suggestions: number,
+
+	text_size: number,
+	subtext_size: number,
+
+	anchor: Vector2,
+	width: UDim,
+	position: UDim2,
+}
+
+export type OptionsPartial = {
+	hide_on_lost_focus: boolean?,
+	activation_keys: { Enum.KeyCode }?,
+	theme: Theme?,
+	font: Font?,
+	icon: string?,
+	transparency: number?,
+	format_date: ((log: Log) -> string)?,
+	max_suggestions: number?,
+
+	text_size: number?,
+	subtext_size: number?,
+
+	anchor: Vector2?,
+	width: UDim?,
+	position: UDim2?,
+}
+
+export type Theme = {
+	background: Color3,
+	surface: Color3,
+	text: Color3,
+	subtext: Color3,
+	highlight: Color3,
+	success: Color3,
+	error: Color3,
+}
+
+export type AnalysisSuggestion = {
+	kind: "command" | "argument",
+	name: string,
+	description: string?,
+	-- ranges of `name` that match the input
+	matches: { vector },
+
+	span: vector,
+	replace: string,
+}
+
+export type AnalysisArgument = {
+	index: number,
+	type: string,
+	kind: "single" | "list",
+}
+
+export type AnalysisResult = {
+	result: centurion.Result<unknown>,
+	command: string?,
+	argument: AnalysisArgument?,
+	suggestions: { AnalysisSuggestion },
+}
+
+export type Log = {
+	command: string,
+	response: centurion.Response,
+}
+
+export type TextStyle = "normal" | "error" | "subtext" | "bg" | "highlight"
+
+return nil

package/vide/init.luau

@@ -0,0 +1,8 @@
+local vide = require "@self/src/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/action.luau

@@ -0,0 +1,25 @@
+type Action = {
+    priority: number,
+    callback: (Instance) -> ()
+}
+
+local ActionMT = table.freeze {}
+
+local function is_action(v: any)
+    return getmetatable(v) == ActionMT
+end
+
+local function action(callback: (Instance) -> (), priority: number?): Action
+    local a = {
+        priority = priority or 1,
+        callback = callback
+    }
+
+    setmetatable(a :: any, ActionMT)
+
+    return table.freeze(a)
+end
+
+return function()
+    return action, is_action
+end

package/vide/src/apply.luau

@@ -0,0 +1,162 @@
+local typeof = game and typeof or require "../test/mock".typeof :: never
+
+local flags = require "./flags"
+local implicit_effect = require "./implicit_effect"
+local _, is_action = require "./action"()
+local graph = require "./graph"
+type Node<T> = graph.Node<T>
+
+type Array<V> = { V }
+type ArrayOrV<V> = {ArrayOrV<V>} | V
+type Map<K, V> = { [K]: V }
+
+type Cache = {
+    -- event listeners to connect after properties are set
+    events: Array<
+        | string -- 1. event name
+        | () -> () -- 2. listener
+    >,
+
+    -- actions to run after events are connected
+    actions: Map<
+        number, -- priority
+        Array<(Instance) -> ()> -- action callbacks
+    >,
+
+    -- what to parent the instance to after running actions
+    parent: unknown,
+
+    -- cache to detect duplicate property setting at same nesting depth
+    nested_debug: Map<
+        number, -- depth
+        Map<string, true> -- set of property names
+    >,
+
+    -- 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 free_cache: Cache?
+
+local function borrow_cache(): Cache
+    if free_cache then
+        local cache = free_cache
+        free_cache = nil
+        return cache
+    else
+        return {
+            events = {},
+            actions = setmetatable({} :: any, { -- lazy init
+                __index = function(self, i) self[i] = {}; return self[i] end
+            }),
+            parent = nil,
+            nested_debug = setmetatable({} :: any, {
+                __index = function(self, i: number) self[i] = {}; return self[i] end
+            }),
+            nested_stack = {}
+        }
+    end
+end
+
+local function return_cache(cache: Cache )
+    free_cache = cache
+end
+
+local function process_properties(properties: Map<unknown, unknown>, instance: Instance, cache: Cache, depth: number)
+    for property, value in properties do
+        if type(property) == "string" then
+            if flags.strict then -- check for duplicate property assignment at nesting depth
+                if cache.nested_debug[depth][property] then
+                    error(`duplicate property {property} at depth {depth}`, 0)
+                end
+                cache.nested_debug[depth][property] = true
+            end
+
+            if property == "Parent" then
+                cache.parent = value
+                continue
+            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
+                    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
+                implicit_effect.children(instance, value :: () -> ArrayOrV<Instance>) -- 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<unknown, unknown>, instance, cache, depth + 1)
+                end
+            elseif type(value) == "userdata" then
+                (value :: Instance).Parent = instance -- parent child
+            end
+        end
+    end
+end
+
+-- applies table of nested properties to an instance using full vide semantics
+local function apply<T>(instance: T & Instance, properties: { [unknown]: unknown }): T
+    if not properties then
+        error "attempt to call a constructor returned by create() with no properties"
+    end
+
+    local caches = borrow_cache()
+    local events = caches.events
+    local actions = caches.actions
+    local nested_debug = caches.nested_debug
+    local nested_stack = caches.nested_stack
+
+    -- process all properties
+    local depth = 1
+    repeat
+        process_properties(properties, instance, caches, depth)
+        depth = table.remove(nested_stack) :: number
+        properties = table.remove(nested_stack) :: {}
+    until not properties
+
+    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 actions do
+        for _, callback in queued do
+            callback(instance)
+        end
+    end
+
+    local parent = caches.parent
+    if parent then
+        if type(parent) == "function" then
+            implicit_effect.parent(instance, parent :: () -> Instance)
+        else
+            instance.Parent = parent :: Instance
+        end
+    end
+
+    table.clear(events)
+    for _, queued in actions do table.clear(queued) end
+    caches.parent = nil
+    if flags.strict then table.clear(nested_debug) end
+    table.clear(nested_stack)
+
+    return_cache(caches)
+
+    return instance
+end
+
+return apply

package/vide/src/batch.luau

@@ -0,0 +1,23 @@
+local flags = require "./flags"
+local graph = require "./graph"
+
+local function batch(setter: () -> ())
+    local already_batching = flags.batch
+    local from
+
+    if not already_batching then
+        flags.batch = true
+        from = graph.get_update_queue_length()
+    end
+
+    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 error(`error occured while batching updates: {err}`, 0) end
+end
+
+return batch

package/vide/src/branch.luau

@@ -0,0 +1,40 @@
+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 get_scope = graph.get_scope
+
+local function branch<T>(fn: () -> T): (() -> (), T)
+    local current = get_scope()
+    if not current then
+        error(`cannot use branch() outside a stable or reactive scope`, 0)
+    end
+
+    local parent = current.owner
+    if not parent then
+        error(`current scope is not owned by a scope`, 0)
+    end
+
+    local node = create_node(parent, false, false)
+
+    local destroy = function()
+        destroy(node)
+    end
+
+    push_scope(node)
+
+    local ok, result = xpcall(fn, debug.traceback)
+
+    pop_scope()
+
+    if not ok then
+        destroy()
+        error(`error while running branch():\n\n{result}`, 0)
+    end
+
+    return destroy, result
+end
+
+return branch

package/vide/src/changed.luau

@@ -0,0 +1,18 @@
+local action = require "./action"()
+local cleanup = require "./cleanup"
+
+local function changed<T>(property: string, callback: (T) -> ())
+    return action(function(instance)
+        local con = instance:GetPropertyChangedSignal(property):Connect(function()
+            callback((instance :: any)[property])
+        end)
+
+        cleanup(function()
+            con:Disconnect()
+        end)
+
+        callback((instance :: any)[property])
+    end)
+end
+
+return changed

package/vide/src/cleanup.luau

@@ -0,0 +1,43 @@
+local typeof = game and typeof or require "../test/mock".typeof :: never
+
+local graph = require "./graph"
+local get_scope = graph.get_scope
+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
+        elseif obj.Destroy then function() obj:Destroy() end
+        elseif obj.Disconnect then function() obj:Disconnect() end
+        else error "cannot cleanup given object"
+end
+
+local function cleanup(value: unknown)
+    local scope = get_scope()
+
+    if not scope then
+        error "cannot cleanup outside a stable or reactive scope"
+    end; assert(scope)
+
+    if type(value) == "function" then
+        push_cleanup(scope, value :: () -> ())
+    else
+        push_cleanup(scope, helper(value))
+    end
+end
+
+type Destroyable = { destroy: (any) -> () } | { Destroy: (any) -> () }
+type Disconnectable = { disconnect: (any) -> () } | { Disconnect: (any) -> () }
+
+return cleanup ::
+    ( (callback: () -> ()) -> () ) &
+    ( (thread: thread) -> () ) &
+    ( (instance: Destroyable) -> () ) &
+    ( (connection: Disconnectable) -> () ) &
+    ( (instance: Instance) -> () ) &
+    ( (connection: RBXScriptConnection) -> () )
+

package/vide/src/context.luau

@@ -0,0 +1,74 @@
+local graph = require "./graph"
+type Node<T> = graph.Node<T>
+local create_node = graph.create_node
+local get_scope = graph.get_scope
+local push_scope = graph.push_scope
+local pop_scope = graph.pop_scope
+local set_context = graph.set_context
+
+export type Context<T> = (() -> T) & (<U>(T, () -> U) -> U)
+
+local nil_symbol = newproxy()
+local count = 0
+
+local function context<T>(...: T): Context<T>
+    count += 1
+    local id = count
+
+    local has_default = select("#", ...) > 0
+    local default_value = ...
+
+    return function<T>(...): any -- todo: fix type error
+        local scope: Node<unknown>? | false = get_scope()
+
+        if select("#", ...) == 0 then -- get
+            while scope do
+                local ctx = scope.context
+    
+                if not ctx then
+                    scope = scope.owner
+                    continue
+                end
+
+                local value = (ctx :: { unknown })[id]
+
+                if value == nil then
+                    scope = scope.owner
+                    continue
+                end
+                
+                return (if value ~= nil_symbol then value else nil) :: T
+            end
+
+            if has_default ~= nil then
+                return default_value
+            else
+                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 error("attempt to set context outside of a vide scope", 0) end
+
+            local value, component = ...
+            
+            local new_scope = create_node(scope, false, false)
+            set_context(new_scope, id, if value == nil then nil_symbol else value)
+
+            push_scope(new_scope)
+
+            local function efn(err: string) return debug.traceback(err, 3) end
+            local ok, result = xpcall(component, efn)
+
+            pop_scope()
+
+            if not ok then
+                error(`error while running context:\n\n{result}`, 0)
+            end
+
+            return result
+        end
+
+        return nil :: any
+    end
+end
+
+return context

package/vide/src/create.luau

@@ -0,0 +1,107 @@
+local typeof = game and typeof or require "../test/mock".typeof :: never
+local Instance = game and Instance or require "../test/mock".Instance :: never
+
+local defaults = require "./defaults"
+local apply = require "./apply"
+local flags = require "./flags"
+
+local function create_constructor_for_class(class: string): ({ [unknown]: unknown }) -> Instance
+    local function constructor(properties: { [unknown]: unknown }): Instance
+        local ok, instance: Instance = pcall(Instance.new, class :: any)
+        if not ok then error(`invalid class name {class}`, 0) end
+
+        if flags.defaults then
+            local default: { [string]: unknown }? = defaults[class]
+            if default then
+                for i, v in default do
+                    (instance :: any)[i] = v
+                end
+            end
+        end
+
+        return apply(instance, properties)
+    end
+
+    return constructor
+end
+
+local constructor_cache = {} :: { [string]: ({ [unknown]: unknown }) -> Instance }
+
+-- todo: remove support for different overloads
+local function create(class_or_instance: string|Instance, properties: { [unknown]: unknown }?): unknown
+    if type(class_or_instance) ~= "string" and typeof(class_or_instance) ~= "Instance" then
+        error("bad argument #1, expected string or instance, got " .. typeof(class_or_instance), 0)
+    end
+
+    local constructor: ({ [unknown]: unknown }) -> Instance
+    if type(class_or_instance) == "string" then
+        constructor = constructor_cache[class_or_instance]
+        if not constructor then
+            constructor = create_constructor_for_class(class_or_instance)
+            constructor_cache[class_or_instance] = constructor
+        end
+    else
+        constructor = function(props)
+            local clone = assert(class_or_instance:Clone(), "attempt to clone a non-archivable instance")
+            return apply(clone, props)
+        end
+    end
+
+    return if properties
+        then constructor(properties)
+        else constructor
+end
+
+type Instances = {
+    Folder: Folder,
+    BillboardGui: BillboardGui,
+    CanvasGroup: CanvasGroup,
+    Frame: Frame,
+    ImageButton: ImageButton,
+    ImageLabel: ImageLabel,
+    ScreenGui: ScreenGui,
+    ScrollingFrame: ScrollingFrame,
+    SurfaceGui: SurfaceGui,
+    TextBox: TextBox,
+    TextButton: TextButton,
+    TextLabel: TextLabel,
+    UIAspectRatioConstraint: UIAspectRatioConstraint,
+    UICorner: UICorner,
+    UIGradient: UIGradient,
+    UIGridLayout: UIGridLayout,
+    UIListLayout: UIListLayout,
+    Camera: Camera,
+    WorldModel: WorldModel,
+}
+
+type function Properties(instance: type?)
+    local properties = types.newtable()
+
+    while instance do
+        for i, v in instance:properties() do
+            local connector = v.read and v.read.tag == "table" and v.read:readproperty(types.singleton("Connect"))
+            if connector then
+                local params = connector:parameters().head
+                if not params then continue end
+                local listener = params[2]
+                if not listener then continue end
+                properties:setproperty(i, types.optional(listener))
+            elseif v.write then
+                properties:setproperty(i, types.optional(types.unionof(
+                    v.write,
+                    types.newfunction({}, { head = { v.write } })
+                )))
+            end
+        end
+
+        instance = instance:readparent()
+    end
+
+    properties:setindexer(types.number, types.any)
+
+    return properties
+end
+
+type Create = <Name>(Name|keyof<Instances>|"") -> (Properties<index<Instances, Name>>) -> index<Instances, Name>
+
+return create :: Create