@k9kbdev/roblox-css 0.1.0

package/out/primitives/ScrollBox.luau

@@ -0,0 +1,69 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+--[[
+	*
+	 * ScrollBox.tsx — A scrollable container component for Roblox.
+	 *
+	 * Provides a scrollable <div> equivalent that supports a web-like CSS syntax (`style` prop).
+	 * It automatically translates CSS properties (e.g., `backgroundColor: "red"`) into
+	 * Roblox engine equivalents (`BackgroundColor3`) and injects layout constraints
+	 * like `UICorner`, `UIPadding`, `UIListLayout`, and `UIGridLayout` as child instances.
+	 *
+	 * Mirrors the architecture of Box.tsx but renders a native <scrollingframe> instead
+	 * of a <frame>, with clean defaults for a modern scrolling experience.
+	 *
+	 * Usage:
+	 *   <ScrollBox style={{ width: "100%", height: "300px", display: "flex", gap: "8px" }}>
+	 *     <textlabel Text="Item 1" />
+	 *     <textlabel Text="Item 2" />
+	 *   </ScrollBox>
+	 
+]]
+local React = TS.import(script, TS.getModule(script, "@rbxts", "react"))
+local webStyle = TS.import(script, script.Parent.Parent, "styles", "webStyle").webStyle
+local ScrollBox = React.forwardRef(function(props, ref)
+	local style = props.style
+	local children = props.children
+	local defaultProps = {
+		BackgroundTransparency = 1,
+		BorderSizePixel = 0,
+		ScrollBarThickness = 4,
+		ScrollBarImageTransparency = 0.5,
+		CanvasSize = UDim2.new(0, 0, 0, 0),
+		AutomaticCanvasSize = Enum.AutomaticSize.Y,
+	}
+	local _object = table.clone(props)
+	setmetatable(_object, nil)
+	local explicitProps = _object
+	explicitProps.style = nil
+	explicitProps.children = nil
+	if style then
+		local parsedStyle = webStyle(style)
+		local _attributes = {
+			ref = ref,
+		}
+		for _k, _v in defaultProps do
+			_attributes[_k] = _v
+		end
+		for _k, _v in parsedStyle.props do
+			_attributes[_k] = _v
+		end
+		for _k, _v in explicitProps do
+			_attributes[_k] = _v
+		end
+		return React.createElement("scrollingframe", _attributes, parsedStyle.children, children)
+	end
+	local _attributes = {
+		ref = ref,
+	}
+	for _k, _v in defaultProps do
+		_attributes[_k] = _v
+	end
+	for _k, _v in explicitProps do
+		_attributes[_k] = _v
+	end
+	return React.createElement("scrollingframe", _attributes, children)
+end)
+return {
+	ScrollBox = ScrollBox,
+}

package/out/primitives/Text.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Text.tsx — <span>/<p>/<h1> equivalent for Roblox.
+ *
+ * Renders a <textlabel> with web-like style props.
+ * Extends the core webStyle translation by adding typography-specific mappings.
+ * Automatically maps primitive string/number children to the Text property,
+ * while still supporting regular React children for nested elements.
+ *
+ * Typography mapping:
+ *   CSS Property        → Roblox Output
+ *   ─────────────────────────────────────────────────────────
+ *   fontSize            → TextSize (number)
+ *   fontFamily          → FontFace (Font object, defaults to BuilderSans)
+ *   fontWeight          → FontFace weight (normal/bold/black → Regular/Bold/Heavy)
+ *   textAlign           → TextXAlignment (left/center/right)
+ *   whiteSpace          → TextWrapped (nowrap → false, otherwise true)
+ *   color               → TextColor3 (Color3) + TextTransparency
+ *
+ * Maps to: HTML <span>/<p> → Roblox <textlabel>
+ *
+ * Usage:
+ *   <Text style={{ fontSize: 24, fontWeight: "bold", color: "#FFFFFF" }}>
+ *     Hello Roblox!
+ *   </Text>
+ */
+import React from "@rbxts/react";
+import { CSSProperties } from "../styles/CSSTypes";
+import { DeepReadonly } from "../types";
+/**
+ * Branded TextProps — the `_textProps` brand ensures strict nominal typing.
+ * This prevents accidental bypasses or incorrect prop structures.
+ */
+export type TextProps = React.PropsWithChildren<React.ComponentProps<"textlabel">> & {
+    /**
+     * Web-like CSS styling object that automatically maps to Roblox properties
+     * and injects necessary UI constraints (UICorner, UIPadding, UIListLayout).
+     */
+    style?: CSSProperties;
+} & {
+    readonly _textProps?: unique symbol;
+};
+/** Helper to construct a branded TextProps. */
+export declare function makeTextProps(props: Omit<TextProps, "_textProps">): DeepReadonly<TextProps>;
+/**
+ * Text component — The primary component for rendering typography.
+ *
+ * Maps to: HTML <span>/<p>/<h1> → Roblox <textlabel>
+ * Renders a native <textlabel> while mapping web typography styles to Roblox Font properties.
+ */
+export declare const Text: React.ForwardRefExoticComponent<Omit<TextProps, "ref"> & React.RefAttributes<TextLabel>>;

package/out/primitives/Text.luau

@@ -0,0 +1,139 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+--[[
+	*
+	 * Text.tsx — <span>/<p>/<h1> equivalent for Roblox.
+	 *
+	 * Renders a <textlabel> with web-like style props.
+	 * Extends the core webStyle translation by adding typography-specific mappings.
+	 * Automatically maps primitive string/number children to the Text property,
+	 * while still supporting regular React children for nested elements.
+	 *
+	 * Typography mapping:
+	 *   CSS Property        → Roblox Output
+	 *   ─────────────────────────────────────────────────────────
+	 *   fontSize            → TextSize (number)
+	 *   fontFamily          → FontFace (Font object, defaults to BuilderSans)
+	 *   fontWeight          → FontFace weight (normal/bold/black → Regular/Bold/Heavy)
+	 *   textAlign           → TextXAlignment (left/center/right)
+	 *   whiteSpace          → TextWrapped (nowrap → false, otherwise true)
+	 *   color               → TextColor3 (Color3) + TextTransparency
+	 *
+	 * Maps to: HTML <span>/<p> → Roblox <textlabel>
+	 * 
+	 * Usage:
+	 *   <Text style={{ fontSize: 24, fontWeight: "bold", color: "#FFFFFF" }}>
+	 *     Hello Roblox!
+	 *   </Text>
+	 
+]]
+local _react = TS.import(script, TS.getModule(script, "@rbxts", "react"))
+local React = _react
+local forwardRef = _react.forwardRef
+local webStyle = TS.import(script, script.Parent.Parent, "styles", "webStyle").webStyle
+--[[
+	*
+	 * Branded TextProps — the `_textProps` brand ensures strict nominal typing.
+	 * This prevents accidental bypasses or incorrect prop structures.
+	 
+]]
+--* Helper to construct a branded TextProps. 
+local function makeTextProps(props)
+	return props
+end
+--[[
+	*
+	 * Text component — The primary component for rendering typography.
+	 *
+	 * Maps to: HTML <span>/<p>/<h1> → Roblox <textlabel>
+	 * Renders a native <textlabel> while mapping web typography styles to Roblox Font properties.
+	 
+]]
+local Text = forwardRef(function(props, ref)
+	-- 1. Extract custom styling props and children
+	local style = props.style
+	local children = props.children
+	local defaultProps = {
+		BackgroundTransparency = 1,
+		TextWrapped = true,
+		Text = "",
+	}
+	if props.Size == nil and (not style or (style.width == nil and style.height == nil)) then
+		defaultProps.AutomaticSize = Enum.AutomaticSize.XY
+	end
+	local _object = table.clone(props)
+	setmetatable(_object, nil)
+	local explicitProps = _object
+	explicitProps.style = nil
+	explicitProps.children = nil
+	-- 3. Map primitive children directly to the Text property
+	if type(children) == "string" or type(children) == "number" then
+		explicitProps.Text = tostring(children)
+	end
+	local parsedStyleProps = {}
+	local parsedStyleChildren = {}
+	-- 4. If a style object is provided, compile it and extract typography mappings
+	if style then
+		local parsed = webStyle(style)
+		parsedStyleProps = parsed.props
+		parsedStyleChildren = parsed.children
+		-- Specialized string manipulation for wordBreak
+		if style.wordBreak ~= nil then
+			if style.wordBreak == "break-all" then
+				local _text = explicitProps.Text
+				if type(_text) == "string" then
+					explicitProps.Text = table.concat(string.split(explicitProps.Text, ""), "\u{200B}")
+				end
+			elseif style.wordBreak == "keep-all" then
+				local _text = explicitProps.Text
+				if type(_text) == "string" then
+					explicitProps.Text = table.concat(string.split(explicitProps.Text, " "), "\n")
+				end
+			end
+		end
+		-- textTransform — mutate text content
+		if style.textTransform ~= nil and style.textTransform ~= "none" then
+			local _text = explicitProps.Text
+			if type(_text) == "string" then
+				if style.textTransform == "uppercase" then
+					explicitProps.Text = string.upper((explicitProps.Text))
+				elseif style.textTransform == "lowercase" then
+					explicitProps.Text = string.lower((explicitProps.Text))
+				elseif style.textTransform == "capitalize" then
+					explicitProps.Text = (string.gsub((explicitProps.Text), "%w+", function(word)
+						return string.upper(string.sub(word, 1, 1)) .. string.sub(word, 2)
+					end))
+				end
+			end
+		end
+		-- textDecoration — wrap text in rich text tags (RichText=true is set by webStyle)
+		if style.textDecoration ~= nil and style.textDecoration ~= "none" then
+			local _text = explicitProps.Text
+			if type(_text) == "string" then
+				if style.textDecoration == "underline" then
+					explicitProps.Text = `<u>{explicitProps.Text}</u>`
+				elseif style.textDecoration == "line-through" then
+					explicitProps.Text = `<s>{explicitProps.Text}</s>`
+				end
+			end
+		end
+	end
+	-- 5. Render the native textlabel with merged properties and children
+	local _attributes = {
+		ref = ref,
+	}
+	for _k, _v in defaultProps do
+		_attributes[_k] = _v
+	end
+	for _k, _v in parsedStyleProps do
+		_attributes[_k] = _v
+	end
+	for _k, _v in explicitProps do
+		_attributes[_k] = _v
+	end
+	return React.createElement("textlabel", _attributes, parsedStyleChildren, if type(children) == "string" or type(children) == "number" then nil else children)
+end)
+return {
+	makeTextProps = makeTextProps,
+	Text = Text,
+}

package/out/primitives/usePercentageConstraints.d.ts

@@ -0,0 +1,3 @@
+import React from "@rbxts/react";
+import type { CSSProperties } from "../styles/CSSTypes";
+export declare function usePercentageConstraints(style: CSSProperties | undefined): React.Element | undefined;

package/out/primitives/usePercentageConstraints.luau

@@ -0,0 +1,112 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _react = TS.import(script, TS.getModule(script, "@rbxts", "react"))
+local React = _react
+local useContext = _react.useContext
+local ParentSizeContext = TS.import(script, script.Parent.Parent, "styles", "ParentSizeContext").ParentSizeContext
+local parseDimension = TS.import(script, script.Parent.Parent, "styles", "dimensionParser").parseDimension
+local function usePercentageConstraints(style)
+	local parentSize = useContext(ParentSizeContext)
+	if not parentSize then
+		return nil
+	end
+	if not style then
+		return nil
+	end
+	-- Extract Scale and Offset components from all four constraint properties.
+	-- Scale is used for percentage axes; Offset is the pixel fallback for non-percentage axes.
+	local minW = if style.minWidth ~= nil then parseDimension(style.minWidth) else nil
+	local minH = if style.minHeight ~= nil then parseDimension(style.minHeight) else nil
+	local maxW = if style.maxWidth ~= nil then parseDimension(style.maxWidth) else nil
+	local maxH = if style.maxHeight ~= nil then parseDimension(style.maxHeight) else nil
+	local _result = minW
+	if _result ~= nil then
+		_result = _result.Scale
+	end
+	local _condition = _result
+	if _condition == nil then
+		_condition = 0
+	end
+	local minWScale = _condition
+	local _result_1 = minH
+	if _result_1 ~= nil then
+		_result_1 = _result_1.Scale
+	end
+	local _condition_1 = _result_1
+	if _condition_1 == nil then
+		_condition_1 = 0
+	end
+	local minHScale = _condition_1
+	local _result_2 = maxW
+	if _result_2 ~= nil then
+		_result_2 = _result_2.Scale
+	end
+	local _condition_2 = _result_2
+	if _condition_2 == nil then
+		_condition_2 = 0
+	end
+	local maxWScale = _condition_2
+	local _result_3 = maxH
+	if _result_3 ~= nil then
+		_result_3 = _result_3.Scale
+	end
+	local _condition_3 = _result_3
+	if _condition_3 == nil then
+		_condition_3 = 0
+	end
+	local maxHScale = _condition_3
+	-- Only activate if at least one constraint has a Scale component
+	if minWScale == 0 and minHScale == 0 and maxWScale == 0 and maxHScale == 0 then
+		return nil
+	end
+	-- When this hook activates, it takes EXCLUSIVE ownership of the <uisizeconstraint>.
+	-- For axes without a percentage, use the pixel (.Offset) fallback from parseDimension().
+	-- This handles mixed cases like { minWidth: "200px", maxWidth: "50%" }.
+	local _result_4 = minW
+	if _result_4 ~= nil then
+		_result_4 = _result_4.Offset
+	end
+	local _condition_4 = _result_4
+	if _condition_4 == nil then
+		_condition_4 = 0
+	end
+	local minWFallback = _condition_4
+	local _result_5 = minH
+	if _result_5 ~= nil then
+		_result_5 = _result_5.Offset
+	end
+	local _condition_5 = _result_5
+	if _condition_5 == nil then
+		_condition_5 = 0
+	end
+	local minHFallback = _condition_5
+	local _result_6 = maxW
+	if _result_6 ~= nil then
+		_result_6 = _result_6.Offset
+	end
+	local _condition_6 = _result_6
+	if _condition_6 == nil then
+		_condition_6 = math.huge
+	end
+	local maxWFallback = _condition_6
+	local _result_7 = maxH
+	if _result_7 ~= nil then
+		_result_7 = _result_7.Offset
+	end
+	local _condition_7 = _result_7
+	if _condition_7 == nil then
+		_condition_7 = math.huge
+	end
+	local maxHFallback = _condition_7
+	return React.createElement("uisizeconstraint", {
+		MinSize = parentSize:map(function(ps)
+			return Vector2.new(if minWScale > 0 then ps.X * minWScale else minWFallback, if minHScale > 0 then ps.Y * minHScale else minHFallback)
+		end),
+		MaxSize = parentSize:map(function(ps)
+			return Vector2.new(if maxWScale > 0 then ps.X * maxWScale else maxWFallback, if maxHScale > 0 then ps.Y * maxHScale else maxHFallback)
+		end),
+	})
+end
+return {
+	usePercentageConstraints = usePercentageConstraints,
+}

package/out/primitives/useVariantResolver.d.ts

@@ -0,0 +1,13 @@
+import React from "@rbxts/react";
+import { CSSProperties } from "../styles/webStyle";
+export interface MotionProps {
+    initial?: string;
+    animate?: string;
+    variants?: Record<string, Partial<CSSProperties> & Record<string, unknown>>;
+    transition?: TweenInfo;
+}
+export declare function isAnimatable(value: unknown): boolean;
+export declare function useVariantResolver(animate?: string, initial?: string, variants?: Record<string, Partial<CSSProperties> & Record<string, unknown>>, transition?: TweenInfo, parser?: (style: Partial<CSSProperties> & Record<string, unknown>) => Record<string, unknown>): {
+    animatedProps: Record<string, React.Binding<unknown>>;
+    staticProps: Record<string, unknown>;
+};

package/out/primitives/useVariantResolver.luau

@@ -0,0 +1,260 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _react = TS.import(script, TS.getModule(script, "@rbxts", "react"))
+local React = _react
+local useEffect = _react.useEffect
+local useMemo = _react.useMemo
+local useRef = _react.useRef
+local createMotion = TS.import(script, TS.getModule(script, "@rbxts", "ripple").src).createMotion
+local RunService = TS.import(script, TS.getModule(script, "@rbxts", "services")).RunService
+local webStyle = TS.import(script, script.Parent.Parent, "styles", "webStyle").webStyle
+local function isAnimatable(value)
+	local _value = value
+	local t = typeof(_value)
+	return t == "number" or t == "UDim" or t == "UDim2" or t == "Vector2" or t == "Vector3" or t == "Color3" or t == "CFrame" or t == "Rect"
+end
+local function useVariantResolver(animate, initial, variants, transition, parser)
+	if parser == nil then
+		parser = function(style)
+			local result = webStyle(style).props
+			for k, v in pairs(style) do
+				if type(k) == "string" and k ~= "_parsed" and result[k] == nil then
+					local firstChar = string.sub(k, 1, 1)
+					if firstChar >= "A" and firstChar <= "Z" then
+						result[k] = v
+					end
+				end
+			end
+			return result
+		end
+	end
+	-- Parse all variants once to find animatable vs static keys
+	local _binding = useMemo(function()
+		local anim = {}
+		local stat = {}
+		if variants then
+			for _, variantStyle in pairs(variants) do
+				local parsed = parser(variantStyle)
+				for key, value in pairs(parsed) do
+					if isAnimatable(value) then
+						anim[key] = true
+					else
+						stat[key] = true
+					end
+				end
+			end
+		end
+		return {
+			animatableKeys = anim,
+			staticKeys = stat,
+		}
+	end, { variants, parser })
+	local animatableKeys = _binding.animatableKeys
+	local staticKeys = _binding.staticKeys
+	-- Maintain independent motions and bindings per property
+	-- to avoid Ripple's limitation with mixed type dictionaries.
+	local motionState = useRef()
+	if not motionState.current then
+		motionState.current = {
+			bindings = {},
+			setBindings = {},
+			motions = {},
+			loopState = {},
+		}
+	end
+	-- 1. Initialize bindings for each animatable key
+	for key in animatableKeys do
+		if not (motionState.current.bindings[key] ~= nil) then
+			local initialVal = nil
+			-- Seed priority: explicit `initial` prop → "idle" key → current animate target → first found
+			local initialKey = initial
+			local _condition = initialKey
+			if _condition ~= "" and _condition then
+				_condition = variants and variants[initialKey] and parser(variants[initialKey])[key] ~= nil
+			end
+			if _condition ~= "" and _condition then
+				initialVal = parser(variants[initialKey])[key]
+			elseif variants and variants.idle and parser(variants.idle)[key] ~= nil then
+				initialVal = parser(variants.idle)[key]
+			else
+				local _condition_1 = animate
+				if _condition_1 ~= "" and _condition_1 then
+					_condition_1 = variants and variants[animate]
+				end
+				if _condition_1 ~= "" and _condition_1 then
+					local parsed = parser(variants[animate])
+					initialVal = parsed[key]
+				end
+			end
+			-- If it's missing in the initial variant, grab it from any variant
+			-- just to know its type for Ripple.
+			if initialVal == nil and variants then
+				for _, variantStyle in pairs(variants) do
+					local parsed = parser(variantStyle)
+					if parsed[key] ~= nil then
+						initialVal = parsed[key]
+						break
+					end
+				end
+			end
+			if initialVal ~= nil then
+				local binding, setBinding = React.createBinding(initialVal)
+				local motion = createMotion(initialVal)
+				motionState.current.bindings[key] = binding
+				motionState.current.setBindings[key] = setBinding
+				motionState.current.motions[key] = motion
+			end
+		end
+	end
+	-- Setup Ripple heartbeat update loop
+	useEffect(function()
+		local state = motionState.current
+		local connection = RunService.Heartbeat:Connect(function(dt)
+			for key, motion in state.motions do
+				local value = motion:step(dt)
+				local binding = state.bindings[key]
+				if value ~= (binding:getValue()) then
+					state.setBindings[key](value)
+				end
+				-- Custom loop handling for repeating/reversing animations
+				local loopData = state.loopState[key]
+				if loopData and motion:isComplete() then
+					if loopData.isReversing then
+						-- We just finished reversing back to initial value.
+						loopData.loopsDone += 1
+						if loopData.repeatCount == -1 or loopData.loopsDone <= loopData.repeatCount then
+							-- Play forward again
+							loopData.isReversing = false
+							motion:tween(loopData.targetValue, loopData.options)
+						else
+							state.loopState[key] = nil
+						end
+					else
+						-- We just finished playing forward.
+						if loopData.reverses then
+							-- Now reverse
+							loopData.isReversing = true
+							motion:tween(loopData.initialValue, loopData.options)
+						else
+							-- We don't reverse, so just snap back and play forward
+							loopData.loopsDone += 1
+							if loopData.repeatCount == -1 or loopData.loopsDone <= loopData.repeatCount then
+								motion:set(loopData.initialValue)
+								motion:tween(loopData.targetValue, loopData.options)
+							else
+								state.loopState[key] = nil
+							end
+						end
+					end
+				end
+			end
+		end)
+		return function()
+			connection:Disconnect()
+		end
+	end, {})
+	-- Animate target changes
+	useEffect(function()
+		local _condition = animate
+		if _condition ~= "" and _condition then
+			_condition = variants and variants[animate]
+		end
+		if _condition ~= "" and _condition then
+			local parsed = parser(variants[animate])
+			local options = {
+				time = 0.3,
+			}
+			local repeatCount = 0
+			local reverses = false
+			if transition then
+				local _object = {}
+				local _left = "time"
+				local _condition_1 = transition.Time
+				if _condition_1 == nil then
+					_condition_1 = 0.3
+				end
+				_object[_left] = _condition_1
+				_object.style = transition.EasingStyle
+				_object.direction = transition.EasingDirection
+				_object.delayTime = transition.DelayTime
+				options = _object
+				local _condition_2 = transition.RepeatCount
+				if _condition_2 == nil then
+					_condition_2 = 0
+				end
+				repeatCount = _condition_2
+				local _condition_3 = transition.Reverses
+				if _condition_3 == nil then
+					_condition_3 = false
+				end
+				reverses = _condition_3
+			end
+			for key in animatableKeys do
+				local targetValue = parsed[key]
+				if targetValue ~= nil then
+					local motion = motionState.current.motions[key]
+					if motion then
+						if repeatCount ~= 0 or reverses then
+							local existingLoop = motionState.current.loopState[key]
+							-- Only reset the loop if we are targeting a new value
+							-- or if we aren't currently looping this property
+							if not existingLoop or existingLoop.targetValue ~= targetValue then
+								local _loopState = motionState.current.loopState
+								local _arg1 = {
+									initialValue = motionState.current.bindings[key]:getValue(),
+									targetValue = targetValue,
+									options = options,
+									repeatCount = repeatCount,
+									reverses = reverses,
+									loopsDone = 0,
+									isReversing = false,
+								}
+								_loopState[key] = _arg1
+								motion:tween(targetValue, options)
+							end
+						else
+							-- Clear old loop state for this property to prevent conflicts
+							motionState.current.loopState[key] = nil
+							motion:tween(targetValue, options)
+						end
+					end
+				end
+			end
+		end
+	end, { animate, variants, transition, animatableKeys, parser })
+	-- Create a plain object of the bindings to spread onto the component
+	local animatedProps = useMemo(function()
+		local props = {}
+		for key, binding in motionState.current.bindings do
+			if animatableKeys[key] ~= nil then
+				props[key] = binding
+			end
+		end
+		return props
+	end, { animatableKeys })
+	-- Compute current static props
+	local staticProps = useMemo(function()
+		local props = {}
+		local _condition = animate
+		if _condition ~= "" and _condition then
+			_condition = variants and variants[animate]
+		end
+		if _condition ~= "" and _condition then
+			local parsed = parser(variants[animate])
+			for key in staticKeys do
+				if parsed[key] ~= nil then
+					props[key] = parsed[key]
+				end
+			end
+		end
+		return props
+	end, { animate, variants, staticKeys, parser })
+	return {
+		animatedProps = animatedProps,
+		staticProps = staticProps,
+	}
+end
+return {
+	isAnimatable = isAnimatable,
+	useVariantResolver = useVariantResolver,
+}