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

package/src/app/suggestions.luau

@@ -0,0 +1,419 @@
+local background = require("../components/background")
+local button_name = require("../button")
+local centurion = require("../../centurion")
+local container = require("../components/container")
+local corner = require("../components/corner")
+local divider = require("../components/divider")
+local fade = require("../fade")
+local flex = require("../components/flex")
+local padding = require("../components/padding")
+local preferred_input = require("../input")
+local px = require("../px")
+local rich = require("../rich")
+local state = require("../state")
+local stroke = require("../components/stroke")
+local text = require("../components/text")
+local theme = require("../theme")
+local types = require("../types")
+local vide = require("../../vide")
+
+local create = vide.create
+local derive = vide.derive
+local indexes = vide.indexes
+local show = vide.show
+local source = vide.source
+local spring = vide.spring
+
+export type Suggestions = {
+	read analysis: () -> types.AnalysisResult,
+	read selected_suggestion: () -> number,
+	read on_select: (suggestion: types.AnalysisSuggestion) -> (),
+	read order: number?,
+
+	[number]: unknown,
+}
+
+-- e.g. <name: type>, [name: type] if optional, <name: type...> if it takes the rest of the input
+local function format_argument(arg: centurion.Argument): string
+	local label = `{arg.name}: {arg.type}`
+
+	local num_args = arg.num_args
+	if num_args == "rest" then
+		label ..= "..."
+	elseif typeof(num_args) == "number" and num_args > 1 then
+		label ..= ` x{num_args}`
+	end
+
+	return if arg.optional then `[{label}]` else `<{label}>`
+end
+
+-- small filled label, e.g. the type of an argument
+local function pill(props: { text: () -> string, color: () -> Color3, order: number? })
+	return background {
+		auto = "XY",
+		order = props.order,
+		color = props.color,
+
+		corner(px(4)),
+		padding { x = px(6), y = px(2) },
+
+		text {
+			auto = "XY",
+			text = props.text,
+			text_size = px(state.subtext_size),
+			text_style = "bg",
+			weight = Enum.FontWeight.Bold,
+		},
+	}
+end
+
+local function suggestion_row(value: () -> types.AnalysisSuggestion, i: number, props: Suggestions)
+	local function selected()
+		return props.selected_suggestion() == i
+	end
+	local hovered = source(false)
+
+	return create "TextButton" {
+		AutomaticSize = Enum.AutomaticSize.XY,
+		AutoButtonColor = false,
+		BackgroundColor3 = function()
+			return state.theme().surface
+		end,
+		BackgroundTransparency = fade.fade(spring(function()
+			if selected() then
+				return state.transparency()
+			elseif hovered() then
+				return 1 - (1 - state.transparency()) * 0.5
+			end
+			return 1
+		end, 0.1)),
+		LayoutOrder = i,
+		Text = "",
+
+		MouseEnter = function()
+			hovered(true)
+		end,
+		MouseLeave = function()
+			hovered(false)
+		end,
+		Activated = function()
+			props.on_select(value())
+		end,
+
+		corner(px(4)),
+		padding { x = px(8), y = px(5) },
+		flex():column():vertical("center"):between("horizontal"),
+
+		container {
+			auto = "XY",
+			order = 1,
+
+			flex():column():vertical("center"),
+
+			-- marks the suggestion Tab will complete
+			text {
+				size = px(UDim2.fromOffset(18, 0)),
+				auto = "Y",
+				order = 1,
+				text = ">",
+				text_style = "highlight",
+				weight = Enum.FontWeight.Bold,
+				xalignment = Enum.TextXAlignment.Left,
+				transparency = spring(function()
+					return if selected() then 0 else 1
+				end, 0.1),
+			},
+
+			text {
+				auto = "XY",
+				order = 2,
+				-- characters matching the input are emphasised
+				text = function()
+					local suggestion = value()
+					local name = suggestion.name
+					local highlight = state.theme().highlight
+
+					local out = {}
+					local pos = 1
+					for _, range in suggestion.matches do
+						table.insert(out, rich.escape(name:sub(pos, range.x - 1)))
+						table.insert(out, `<b>{rich.color(rich.escape(name:sub(range.x, range.y)), highlight)}</b>`)
+						pos = range.y + 1
+					end
+					table.insert(out, rich.escape(name:sub(pos)))
+
+					return table.concat(out)
+				end,
+				rich_text = true,
+				text_style = function()
+					return if selected() then "normal" else "subtext"
+				end,
+				xalignment = Enum.TextXAlignment.Left,
+			},
+		},
+
+		show(function()
+			return value().description ~= nil
+		end, function()
+			return text {
+				auto = "XY",
+				order = 2,
+				text = function()
+					return value().description or ""
+				end,
+				text_size = px(state.subtext_size),
+				text_style = "subtext",
+				xalignment = Enum.TextXAlignment.Right,
+
+				-- keeps the description away from the name
+				padding { left = px(32) },
+			}
+		end),
+	}
+end
+
+local function suggestions(props: Suggestions)
+	local usage = derive(function()
+		local analysis = props.analysis()
+		if analysis.argument == nil or analysis.command == nil then
+			return nil
+		end
+
+		local cmd = centurion.registry.commands[analysis.command]
+		if cmd == nil or cmd.arguments == nil then
+			return nil
+		end
+
+		local args: { centurion.Argument } = { cmd.arguments() }
+		return {
+			command = analysis.command,
+			args = args,
+			index = analysis.argument.index,
+		}
+	end)
+
+	local arg = derive(function()
+		local current = usage()
+		return current and current.args[current.index]
+	end)
+
+	local failed = derive(function()
+		return not props.analysis().result.success
+	end)
+
+	local has_suggestions = derive(function()
+		return #props.analysis().suggestions > 0
+	end)
+
+	local input = preferred_input()
+
+	-- the sections above the list, which are divided from it when both are shown
+	local has_details = derive(function()
+		return failed() or arg() ~= nil
+	end)
+
+	return background {
+		auto = "XY",
+		order = props.order,
+		color = function()
+			return state.theme().background
+		end,
+		transparency = state.transparency,
+
+		corner(px(8)),
+		stroke {
+			color = function()
+				return theme.border(state.theme())
+			end,
+		},
+		create "UISizeConstraint" {
+			MinSize = function()
+				return Vector2.new(px.convert(320), 0)
+			end,
+		},
+		flex():row():fill("horizontal"),
+
+		-- why the input can't be run as it is
+		show(failed, function()
+			return container {
+				auto = "XY",
+				order = 1,
+
+				padding { x = px(12), y = px(8) },
+				flex():column():vertical("center"):gap(8),
+
+				pill {
+					order = 1,
+					text = function()
+						return "error"
+					end,
+					color = function()
+						return state.theme().error
+					end,
+				},
+
+				text {
+					auto = "XY",
+					order = 2,
+					text = function()
+						return props.analysis().result.error or ""
+					end,
+					text_size = px(state.subtext_size),
+					text_style = "error",
+					xalignment = Enum.TextXAlignment.Left,
+				},
+			}
+		end),
+
+		-- the full signature, and details of the argument being typed
+		show(arg, function()
+			return container {
+				auto = "XY",
+				order = 2,
+
+				padding { x = px(12), y = px(8) },
+				flex():row():gap(6),
+
+				text {
+					auto = "XY",
+					order = 1,
+					text = function()
+						local current = usage()
+						if not current then
+							return ""
+						end
+
+						local colors = state.theme()
+						local parts = { `<b>{rich.escape(current.command)}</b>` }
+						for i, value in current.args do
+							local label = rich.escape(format_argument(value))
+							table.insert(
+								parts,
+								if i == current.index
+									then `<b>{rich.color(label, colors.highlight)}</b>`
+									else rich.color(label, colors.subtext)
+							)
+						end
+
+						return table.concat(parts, " ")
+					end,
+					rich_text = true,
+					text_size = px(state.subtext_size),
+					xalignment = Enum.TextXAlignment.Left,
+				},
+
+				container {
+					auto = "XY",
+					order = 2,
+
+					flex():column():vertical("center"):gap(8),
+
+					pill {
+						order = 1,
+						text = function()
+							return arg() and arg().type or ""
+						end,
+						color = function()
+							return state.theme().highlight
+						end,
+					},
+
+					text {
+						auto = "XY",
+						order = 2,
+						text = function()
+							return arg() and arg().name or ""
+						end,
+						weight = Enum.FontWeight.Bold,
+						xalignment = Enum.TextXAlignment.Left,
+					},
+
+					show(function()
+						return arg() and arg().description ~= nil
+					end, function()
+						return text {
+							auto = "XY",
+							order = 3,
+							text = function()
+								return arg() and arg().description or ""
+							end,
+							text_size = px(state.subtext_size),
+							text_style = "subtext",
+							xalignment = Enum.TextXAlignment.Left,
+						}
+					end),
+				},
+			}
+		end),
+
+		divider {
+			order = 3,
+			visible = function()
+				return has_details() and has_suggestions()
+			end,
+		},
+
+		show(has_suggestions, function()
+			return container {
+				auto = "XY",
+				order = 4,
+
+				padding(px(4)),
+				flex():row():fill("horizontal"),
+
+				indexes(function()
+					return props.analysis().suggestions
+				end, function(value: () -> types.AnalysisSuggestion, i)
+					return suggestion_row(value, i, props)
+				end),
+			}
+		end),
+
+		divider {
+			order = 5,
+			visible = has_suggestions,
+		},
+
+		show(has_suggestions, function()
+			return container {
+				auto = "XY",
+				order = 6,
+
+				padding { x = px(12), y = px(6) },
+
+				text {
+					auto = "XY",
+					text = function()
+						local key = rich.color("%s", state.theme().text)
+						if input() == Enum.PreferredInput.Touch then
+							return `<b>{key:format("Tap")}</b> a suggestion to complete it`
+						elseif input() == Enum.PreferredInput.Gamepad then
+							return table.concat({
+								`<b>{key:format(button_name(Enum.KeyCode.ButtonA))}</b> complete`,
+								`<b>{key:format("D-pad")}</b> select`,
+								`<b>{key:format(button_name(Enum.KeyCode.ButtonX))}</b> edit`,
+								`<b>{key:format(button_name(Enum.KeyCode.ButtonY))}</b> run`,
+								`<b>{key:format(button_name(Enum.KeyCode.ButtonB))}</b> close`,
+							}, "    ")
+						end
+
+						local hints = {
+							`<b>{key:format("Tab")}</b> complete`,
+							`<b>{key:format("↑↓")}</b> select`,
+							`<b>{key:format("Enter")}</b> run`,
+						}
+						return table.concat(hints, "    ")
+					end,
+					rich_text = true,
+					text_size = px(state.subtext_size),
+					text_style = "subtext",
+					xalignment = Enum.TextXAlignment.Left,
+				},
+			}
+		end),
+
+		unpack(props),
+	}
+end
+
+return suggestions

package/src/button.luau

@@ -0,0 +1,13 @@
+local UserInputService = game:GetService("UserInputService")
+
+-- name of a gamepad button for the connected controller, e.g. "A" on Xbox
+-- and "Cross" on PlayStation
+local function button_name(key: Enum.KeyCode): string
+	local name = UserInputService:GetStringForKeyCode(key)
+	if name == "" then
+		name = key.Name
+	end
+	return (name:gsub("^Button", ""))
+end
+
+return button_name

package/src/components/background.luau

@@ -0,0 +1,37 @@
+local fade = require("../fade")
+local vide = require("../../vide")
+
+local create = vide.create
+
+type Can<T> = T | () -> T
+type Background = {
+	read size: Can<UDim2>?,
+	read position: Can<UDim2>?,
+	read anchor: Can<Vector2>?,
+	read color: Can<Color3>?,
+	read zindex: Can<number>?,
+	read auto: Can<Enum.AutomaticSize | "X" | "Y" | "XY">?,
+	read order: Can<number>?,
+	read transparency: Can<number>?,
+	read visible: Can<boolean>?,
+
+	[number]: unknown,
+}
+
+return function(props: Background)
+	return create "Frame" {
+		Size = props.size,
+		BackgroundColor3 = props.color,
+		BackgroundTransparency = fade.fade(props.transparency),
+		Position = props.position,
+		AnchorPoint = props.anchor,
+		AutomaticSize = props.auto,
+		LayoutOrder = props.order,
+		ZIndex = props.zindex,
+		Visible = props.visible,
+
+		AutoLocalize = false,
+
+		unpack(props),
+	}
+end

package/src/components/container.luau

@@ -0,0 +1,33 @@
+local vide = require("../../vide")
+
+local create = vide.create
+
+type Can<T> = T | () -> T
+type Container = {
+	read size: Can<UDim2>?,
+	read position: Can<UDim2>?,
+	read anchor: Can<Vector2>?,
+	read zindex: Can<number>?,
+	read auto: Can<Enum.AutomaticSize | "X" | "Y" | "XY">?,
+	read order: Can<number>?,
+	read clip: Can<boolean>?,
+
+	[number]: unknown,
+}
+
+return function(props: Container)
+	return create "Frame" {
+		Size = props.size,
+		Position = props.position,
+		AnchorPoint = props.anchor,
+		AutomaticSize = props.auto,
+		LayoutOrder = props.order,
+		ZIndex = props.zindex,
+		ClipsDescendants = props.clip,
+
+		AutoLocalize = false,
+		BackgroundTransparency = 1,
+
+		unpack(props),
+	}
+end

package/src/components/corner.luau

@@ -0,0 +1,11 @@
+local vide = require("../../vide")
+
+local create = vide.create
+
+return function(px: number)
+	return create "UICorner" {
+		CornerRadius = function()
+			return UDim.new(0, vide.read(px))
+		end,
+	}
+end

package/src/components/divider.luau

@@ -0,0 +1,28 @@
+local fade = require("../fade")
+local state = require("../state")
+local theme = require("../theme")
+local vide = require("../../vide")
+
+local create = vide.create
+
+type Can<T> = T | () -> T
+type Divider = {
+	read order: Can<number>?,
+	read visible: Can<boolean>?,
+}
+
+-- a 1px horizontal rule. It has no width of its own and relies on the parent's
+-- list layout filling it horizontally: a scale width would make an
+-- automatically sized parent grow to fill its own parent
+return function(props: Divider?)
+	return create "Frame" {
+		Size = UDim2.fromOffset(0, 1),
+		BackgroundColor3 = function()
+			return theme.border(state.theme())
+		end,
+		BackgroundTransparency = fade.fade(),
+		BorderSizePixel = 0,
+		LayoutOrder = props and props.order,
+		Visible = props and props.visible,
+	}
+end

package/src/components/flex.luau

@@ -0,0 +1,108 @@
+local px = require("../px")
+local vide = require("../../vide")
+
+local create = vide.create
+local effect = vide.effect
+local source = vide.source
+local read = vide.read
+
+return function()
+	local gap = source(UDim.new())
+
+	local list: UIListLayout = create "UIListLayout" {
+		SortOrder = Enum.SortOrder.LayoutOrder,
+		Padding = px(gap),
+	}
+	local t = { list }
+	local mt = {}
+
+	function mt:row()
+		list.FillDirection = Enum.FillDirection.Vertical
+		return self
+	end
+
+	function mt:column()
+		list.FillDirection = Enum.FillDirection.Horizontal
+		return self
+	end
+
+	function mt:name()
+		list.SortOrder = Enum.SortOrder.Name
+		return self
+	end
+
+	function mt:none(direction: "horizontal" | "vertical"?)
+		if direction ~= "vertical" then
+			list.HorizontalFlex = Enum.UIFlexAlignment.None
+		end
+		if direction ~= "horizontal" then
+			list.VerticalFlex = Enum.UIFlexAlignment.None
+		end
+		return self
+	end
+
+	function mt:even(direction: "horizontal" | "vertical"?)
+		if direction ~= "vertical" then
+			list.HorizontalFlex = Enum.UIFlexAlignment.SpaceEvenly
+		end
+		if direction ~= "horizontal" then
+			list.VerticalFlex = Enum.UIFlexAlignment.SpaceEvenly
+		end
+		return self
+	end
+
+	function mt:around(direction: "horizontal" | "vertical"?)
+		if direction ~= "vertical" then
+			list.HorizontalFlex = Enum.UIFlexAlignment.SpaceAround
+		end
+		if direction ~= "horizontal" then
+			list.VerticalFlex = Enum.UIFlexAlignment.SpaceAround
+		end
+		return self
+	end
+
+	function mt:between(direction: "horizontal" | "vertical"?)
+		if direction ~= "vertical" then
+			list.HorizontalFlex = Enum.UIFlexAlignment.SpaceBetween
+		end
+		if direction ~= "horizontal" then
+			list.VerticalFlex = Enum.UIFlexAlignment.SpaceBetween
+		end
+		return self
+	end
+
+	function mt:fill(direction: "horizontal" | "vertical")
+		if direction ~= "vertical" then
+			list.HorizontalFlex = Enum.UIFlexAlignment.Fill
+		end
+		if direction ~= "horizontal" then
+			list.VerticalFlex = Enum.UIFlexAlignment.Fill
+		end
+		return self
+	end
+
+	function mt:horizontal(align: "left" | "right" | "center")
+		list.HorizontalAlignment = if align == "left"
+			then Enum.HorizontalAlignment.Left
+			elseif align == "right" then Enum.HorizontalAlignment.Right
+			else Enum.HorizontalAlignment.Center
+		return self
+	end
+
+	function mt:vertical(align: "top" | "bottom" | "center")
+		list.VerticalAlignment = if align == "top"
+			then Enum.VerticalAlignment.Top
+			elseif align == "bottom" then Enum.VerticalAlignment.Bottom
+			else Enum.VerticalAlignment.Center
+		return self
+	end
+
+	function mt:gap(value: number | () -> number)
+		effect(function()
+			gap(UDim.new(0, read(value)))
+		end)
+		return self
+	end
+
+	return setmetatable(t, { __index = mt })
+end

package/src/components/gap.luau

@@ -0,0 +1,25 @@
+local vide = require("../../vide")
+
+local create = vide.create
+local read = vide.read
+
+type Can<T> = T | () -> T
+type Gap = {
+	read width: Can<number>?,
+	read height: Can<number>?,
+
+	[number]: unknown,
+}
+
+return function(props: Gap)
+	return create "Frame" {
+		Name = "gap",
+		Size = function()
+			return UDim2.fromOffset(read(props.width) or 0, read(props.height) or 0)
+		end,
+
+		BackgroundTransparency = 1,
+
+		unpack(props) :: any,
+	}
+end

package/src/components/image.luau

@@ -0,0 +1,33 @@
+local fade = require("../fade")
+local vide = require("../../vide")
+
+local create = vide.create
+
+type Can<T> = T | () -> T
+type Image = {
+	read image: Can<string>,
+	read size: Can<UDim2>?,
+	read color: Can<Color3>?,
+	read transparency: Can<number>?,
+	read order: Can<number>?,
+	read visible: Can<boolean>?,
+
+	[number]: unknown,
+}
+
+return function(props: Image)
+	return create "ImageLabel" {
+		Image = props.image,
+		Size = props.size,
+		ImageColor3 = props.color,
+		ImageTransparency = fade.fade(props.transparency),
+		LayoutOrder = props.order,
+		Visible = props.visible,
+		ScaleType = Enum.ScaleType.Fit,
+
+		AutoLocalize = false,
+		BackgroundTransparency = 1,
+
+		unpack(props),
+	}
+end