@rbxts/uiblox 0.1.52 → 0.2.0-alpha.0

package/README.md

@@ -34,7 +34,6 @@ How does it do this? Well, there are two main exports from this package:
 
 -   @rbxts/uiblox -> theme
     -   An extensible Theme type + default Dark (default) and Light themes
-        -   ... Light theme palette is a WIP
     -   makeStyles/createStyles utilities to serve up Instance-extended property
         tables that can be applied to your React Components
     -   ThemeProvider which can wrap your application and uses Reflex to tell
@@ -196,6 +195,73 @@ const useMyComponentStyles = makeStyles<MyComponentProps>((theme: Theme, props:
 export default useMyComponentStyles;
 ```
 
+### Style precedence
+
+Components spread their own styles first, then `className`, then the props that
+carry state. Later always wins:
+
+1. Component styles from the theme
+2. `className` (merge several with `cx(a, condition && b)`; later args win, falsy
+   args are skipped)
+3. State props the component owns: `Active`, `Selectable`, `Text`, and the
+   value-driven sizes/positions of Slider, SplitPane, and so on
+
+So `className` can restyle anything except a control's state. Pass `disabled`
+instead of overriding `Active`.
+
+### Controls
+
+Inputs are controlled: `{ value, onChange, disabled? }`. They call `onChange`
+only when the value actually changes, and never while disabled.
+
+| Component | Value | Notes |
+| --- | --- | --- |
+| Checkbox | `boolean` | `mixed` shows indeterminate; activating commits `true` |
+| Switch | `boolean` | |
+| RadioGroup / Select / Tabs | `T` from `options: { label, value: T, disabled? }[]` | compared by identity; disabled options are skipped |
+| NumberInput | `number` | commits on focus lost or Enter; clamps to `min`/`max`, snaps to `step` |
+| Slider | `number` | `onChange` while dragging, `onCommit` on release |
+| SplitPane | first pane size (px) | display clamps to `min`/`max`; Escape cancels a drag |
+| Input | `text` | `onInput` while typing, `onTextChanged` on commit |
+
+Select and Tooltip render through `Popup`, which portals into the nearest
+`LayerCollector` so clipping parents do not cut them off. The popup follows its
+anchor when that anchor moves or resizes, and Select closes if the anchor leaves
+the layer. Select handles Up, Down, Enter, and Escape while it is open or
+selected, including when the pointer is not over it.
+
+### Loading
+
+`Skeleton` covers a block that is still loading. `variant` is `text`,
+`rectangular`, `rounded`, or `circular`. `width` and `height` are pixels.
+`lines` and `gap` stack text rows. `SkeletonText` is the text variant.
+`animation` is `pulse`, `shimmer`, or `false`. `reducedMotion` holds the block
+still. A later theme preference can set that prop for you.
+
+`CircularProgress` spins while `value` is omitted. A `value` from 0 to 1 draws
+an arc and stops the spin. `size`, `thickness`, and `color` restyle the ring.
+`LinearProgress` is the existing `ProgressBar`: pass `value` from 0 to 1 or
+`progress` from 0 to 100. `indeterminate` slides the bar. `disabled` and
+`reducedMotion` stop the motion and fade the fill.
+
+`Button` and `IconButton` take `loading`. The control ignores clicks, hover,
+and focus while loading, and its size stays put. `loadingLabel` replaces the
+caption. `loadingPosition` is `start`, `center`, or `end`. `reducedMotion`
+keeps the spinner still.
+
+### State captures
+
+`stateMatrix` is the gallery list for Storyblox. Each row is one shot: `theme`
+(`Dark` or `Light`), `width`, and `pointer` (`rest`, `hover`, `press`, or
+`focus`). `open` means the Select list is showing. `options` and `disabledOption`
+build RadioGroup, Select, and Tabs. `selected` and `filter` are TreeView.
+`value`, `text`, `disabled`, `loading`, `mixed`, `hasError`, and `placeholder`
+are that control's props. `variant`, `animation` (`pulse`, `shimmer`, or
+`false`), `reducedMotion`, and `indeterminate` cover skeleton and progress
+shots. Those shots stay still when `animation` is `false` or `reducedMotion`
+is set. Hover, press, and focus rows are only there when the
+control actually changes.
+
 ### Client
 
 Some sample logic for mounting app when player spawns (on client).
@@ -247,7 +313,6 @@ new AppLoader().Mount();
 # Future work
 
 -   More UI packages
--   Finish palette for LightTheme
 
 # See Also
 

package/out/foundation/guard.d.ts

@@ -0,0 +1,3 @@
+export declare function isFiniteNumber(value: unknown): value is number;
+export declare function finiteOr(value: unknown, fallback: number): number;
+export declare function positiveDimension(value: unknown, fallback: number): number;

package/out/foundation/guard.luau

@@ -0,0 +1,23 @@
+-- Compiled with roblox-ts v3.0.0
+local function isFiniteNumber(value)
+	local _value = value
+	if typeof(_value) ~= "number" then
+		return false
+	end
+	local number = value
+	return number == number and number < math.huge and number > -math.huge
+end
+local function finiteOr(value, fallback)
+	return if isFiniteNumber(value) then value else fallback
+end
+local function positiveDimension(value, fallback)
+	if not isFiniteNumber(value) or value <= 0 then
+		return fallback
+	end
+	return value
+end
+return {
+	isFiniteNumber = isFiniteNumber,
+	finiteOr = finiteOr,
+	positiveDimension = positiveDimension,
+}

package/out/foundation/index.d.ts

@@ -0,0 +1 @@
+export { isFiniteNumber, finiteOr, positiveDimension } from "./guard";

package/out/foundation/init.luau

@@ -0,0 +1,8 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+local _guard = TS.import(script, script, "guard")
+exports.isFiniteNumber = _guard.isFiniteNumber
+exports.finiteOr = _guard.finiteOr
+exports.positiveDimension = _guard.positiveDimension
+return exports

package/out/hooks/breakpoints.d.ts

@@ -0,0 +1,10 @@
+export type BreakpointName = "phone" | "tablet" | "desktop";
+export type OrientationName = "portrait" | "landscape";
+export declare function breakpointName(width: number): BreakpointName;
+export declare function orientationName(width: number, height: number): OrientationName;
+export type Responsive<T> = T | {
+    phone?: T;
+    tablet?: T;
+    desktop?: T;
+};
+export declare function resolveResponsive<T>(value: Responsive<T> | undefined, width: number): T | undefined;

package/out/hooks/breakpoints.luau

@@ -0,0 +1,60 @@
+-- Compiled with roblox-ts v3.0.0
+local function usable(value)
+	local _value = value
+	local _condition = typeof(_value) ~= "number"
+	if not _condition then
+		_condition = value ~= value or value >= math.huge or value <= -math.huge or value <= 0
+	end
+	if _condition then
+		return 0
+	end
+	return value
+end
+local function breakpointName(width)
+	local size = usable(width)
+	if size < 600 then
+		return "phone"
+	end
+	if size < 960 then
+		return "tablet"
+	end
+	return "desktop"
+end
+local function orientationName(width, height)
+	return if usable(height) > usable(width) then "portrait" else "landscape"
+end
+local function resolveResponsive(value, width)
+	local _condition = value == nil
+	if not _condition then
+		local _value = value
+		_condition = typeof(_value) ~= "table"
+	end
+	if _condition then
+		return value
+	end
+	local record = value
+	local name = breakpointName(width)
+	if name == "desktop" then
+		local _condition_1 = record.desktop
+		if _condition_1 == nil then
+			_condition_1 = record.tablet
+			if _condition_1 == nil then
+				_condition_1 = record.phone
+			end
+		end
+		return _condition_1
+	end
+	if name == "tablet" then
+		local _condition_1 = record.tablet
+		if _condition_1 == nil then
+			_condition_1 = record.phone
+		end
+		return _condition_1
+	end
+	return record.phone
+end
+return {
+	breakpointName = breakpointName,
+	orientationName = orientationName,
+	resolveResponsive = resolveResponsive,
+}

package/out/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export { breakpointName, orientationName, resolveResponsive } from "./breakpoints";
+export { BreakpointName, OrientationName, Responsive } from "./breakpoints";
+export { useBreakpoints } from "./useBreakpoints";
+export { useReducedMotion } from "./useReducedMotion";

package/out/hooks/init.luau

@@ -0,0 +1,10 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+local _breakpoints = TS.import(script, script, "breakpoints")
+exports.breakpointName = _breakpoints.breakpointName
+exports.orientationName = _breakpoints.orientationName
+exports.resolveResponsive = _breakpoints.resolveResponsive
+exports.useBreakpoints = TS.import(script, script, "useBreakpoints").useBreakpoints
+exports.useReducedMotion = TS.import(script, script, "useReducedMotion").useReducedMotion
+return exports

package/out/hooks/useBreakpoints.d.ts

@@ -0,0 +1,6 @@
+export declare function useBreakpoints(host?: GuiObject): {
+    width: number;
+    height: number;
+    name: import("./breakpoints").BreakpointName;
+    orientation: import("./breakpoints").OrientationName;
+};

package/out/hooks/useBreakpoints.luau

@@ -0,0 +1,39 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _react = TS.import(script, TS.getModule(script, "@rbxts", "react"))
+local useEffect = _react.useEffect
+local useState = _react.useState
+local _breakpoints = TS.import(script, script.Parent, "breakpoints")
+local breakpointName = _breakpoints.breakpointName
+local orientationName = _breakpoints.orientationName
+local function useBreakpoints(host)
+	local size, setSize = useState({
+		width = 0,
+		height = 0,
+	})
+	useEffect(function()
+		if host == nil then
+			return nil
+		end
+		local read = function()
+			return setSize({
+				width = host.AbsoluteSize.X,
+				height = host.AbsoluteSize.Y,
+			})
+		end
+		read()
+		local connection = host:GetPropertyChangedSignal("AbsoluteSize"):Connect(read)
+		return function()
+			return connection:Disconnect()
+		end
+	end, { host })
+	return {
+		width = size.width,
+		height = size.height,
+		name = breakpointName(size.width),
+		orientation = orientationName(size.width, size.height),
+	}
+end
+return {
+	useBreakpoints = useBreakpoints,
+}

package/out/hooks/useReducedMotion.d.ts

@@ -0,0 +1 @@
+export declare function useReducedMotion(override?: boolean): boolean;

package/out/hooks/useReducedMotion.luau

@@ -0,0 +1,12 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local useTheme = TS.import(script, script.Parent.Parent, "theme").useTheme
+local resolveReduced = TS.import(script, script.Parent.Parent, "ui", "packages", "motion", "resolveReduced").resolveReduced
+local function useReducedMotion(override)
+	local _binding = useTheme()
+	local theme = _binding.theme
+	return resolveReduced(override, theme.reducedMotion)
+end
+return {
+	useReducedMotion = useReducedMotion,
+}

package/out/index.d.ts

@@ -1,2 +1,5 @@
 export * from "./theme/index";
 export * from "./ui/index";
+export * from "./interaction/index";
+export * from "./foundation/index";
+export * from "./hooks/index";

package/out/init.luau

@@ -7,4 +7,13 @@ end
 for _k, _v in TS.import(script, script, "ui") or {} do
 	exports[_k] = _v
 end
+for _k, _v in TS.import(script, script, "interaction") or {} do
+	exports[_k] = _v
+end
+for _k, _v in TS.import(script, script, "foundation") or {} do
+	exports[_k] = _v
+end
+for _k, _v in TS.import(script, script, "hooks") or {} do
+	exports[_k] = _v
+end
 return exports

package/out/interaction/index.d.ts

@@ -0,0 +1,4 @@
+export { usePointer } from "./usePointer";
+export { PointerHandlers, UsePointerOptions } from "./usePointer";
+export { pointerRoute, isKeyKind, shouldTakeKey } from "./pointerRoute";
+export { PointerRoute } from "./pointerRoute";

package/out/interaction/init.luau

@@ -0,0 +1,9 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+exports.usePointer = TS.import(script, script, "usePointer").usePointer
+local _pointerRoute = TS.import(script, script, "pointerRoute")
+exports.pointerRoute = _pointerRoute.pointerRoute
+exports.isKeyKind = _pointerRoute.isKeyKind
+exports.shouldTakeKey = _pointerRoute.shouldTakeKey
+return exports

package/out/interaction/pointerRoute.d.ts

@@ -0,0 +1,6 @@
+export type PointerRoute = "local" | "global";
+/** Global pointer replaces local GuiObject events. Never both. */
+export declare function pointerRoute(globalPointer?: boolean): PointerRoute;
+export declare function isKeyKind(name: string): boolean;
+/** Processed keys are ignored unless the caller opts into them. */
+export declare function shouldTakeKey(gameProcessed: boolean, captureProcessed?: boolean): boolean;

package/out/interaction/pointerRoute.luau

@@ -0,0 +1,35 @@
+-- Compiled with roblox-ts v3.0.0
+--* Global pointer replaces local GuiObject events. Never both. 
+local function pointerRoute(globalPointer)
+	return if globalPointer == true then "global" else "local"
+end
+local GAMEPADS = {
+	["Gamepad1"] = true,
+	["Gamepad2"] = true,
+	["Gamepad3"] = true,
+	["Gamepad4"] = true,
+	["Gamepad5"] = true,
+	["Gamepad6"] = true,
+	["Gamepad7"] = true,
+	["Gamepad8"] = true,
+}
+local function isKeyKind(name)
+	local _condition = name == "Keyboard"
+	if not _condition then
+		local _name = name
+		_condition = GAMEPADS[_name] ~= nil
+	end
+	return _condition
+end
+--* Processed keys are ignored unless the caller opts into them. 
+local function shouldTakeKey(gameProcessed, captureProcessed)
+	if captureProcessed == nil then
+		captureProcessed = false
+	end
+	return captureProcessed or not gameProcessed
+end
+return {
+	pointerRoute = pointerRoute,
+	isKeyKind = isKeyKind,
+	shouldTakeKey = shouldTakeKey,
+}

package/out/interaction/usePointer.d.ts

@@ -0,0 +1,11 @@
+export interface PointerHandlers {
+    onDown?: (position: Vector2) => void;
+    onUp?: (position: Vector2) => void;
+    onKey?: (input: InputObject) => void;
+}
+export interface UsePointerOptions {
+    globalPointer?: boolean;
+    keyboard?: boolean;
+    captureProcessed?: boolean;
+}
+export declare function usePointer(target: GuiObject | undefined, handlers: PointerHandlers, options?: UsePointerOptions): void;

package/out/interaction/usePointer.luau

@@ -0,0 +1,99 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _react = TS.import(script, TS.getModule(script, "@rbxts", "react"))
+local useEffect = _react.useEffect
+local useRef = _react.useRef
+local UserInputService = TS.import(script, TS.getModule(script, "@rbxts", "services")).UserInputService
+local _pointerRoute = TS.import(script, script.Parent, "pointerRoute")
+local isKeyKind = _pointerRoute.isKeyKind
+local pointerRoute = _pointerRoute.pointerRoute
+local shouldTakeKey = _pointerRoute.shouldTakeKey
+local function isPointerButton(input)
+	local kind = input.UserInputType
+	return kind == Enum.UserInputType.MouseButton1 or kind == Enum.UserInputType.Touch
+end
+local function positionOf(input)
+	return Vector2.new(input.Position.X, input.Position.Y)
+end
+local function usePointer(target, handlers, options)
+	if options == nil then
+		options = {}
+	end
+	local current = useRef(handlers)
+	current.current = handlers
+	local route = pointerRoute(options.globalPointer)
+	local captureProcessed = options.captureProcessed == true
+	useEffect(function()
+		if route ~= "local" or not target then
+			return nil
+		end
+		local began = target.InputBegan:Connect(function(input)
+			if isPointerButton(input) then
+				local _result = current.current.onDown
+				if _result ~= nil then
+					_result(positionOf(input))
+				end
+			end
+		end)
+		local ended = target.InputEnded:Connect(function(input)
+			if isPointerButton(input) then
+				local _result = current.current.onUp
+				if _result ~= nil then
+					_result(positionOf(input))
+				end
+			end
+		end)
+		return function()
+			began:Disconnect()
+			ended:Disconnect()
+		end
+	end, { target, route })
+	useEffect(function()
+		if route ~= "global" then
+			return nil
+		end
+		local began = UserInputService.InputBegan:Connect(function(input)
+			if isPointerButton(input) then
+				local _result = current.current.onDown
+				if _result ~= nil then
+					_result(positionOf(input))
+				end
+			end
+		end)
+		local ended = UserInputService.InputEnded:Connect(function(input)
+			if isPointerButton(input) then
+				local _result = current.current.onUp
+				if _result ~= nil then
+					_result(positionOf(input))
+				end
+			end
+		end)
+		return function()
+			began:Disconnect()
+			ended:Disconnect()
+		end
+	end, { route })
+	useEffect(function()
+		if options.keyboard ~= true then
+			return nil
+		end
+		local connection = UserInputService.InputBegan:Connect(function(input, gameProcessed)
+			if not isKeyKind(input.UserInputType.Name) then
+				return nil
+			end
+			if not shouldTakeKey(gameProcessed, captureProcessed) then
+				return nil
+			end
+			local _result = current.current.onKey
+			if _result ~= nil then
+				_result(input)
+			end
+		end)
+		return function()
+			return connection:Disconnect()
+		end
+	end, { options.keyboard, captureProcessed })
+end
+return {
+	usePointer = usePointer,
+}

package/out/theme/constants/ColorConstants.d.ts

@@ -1,5 +1,2 @@
-import { Colors } from "../interfaces/palette/colors/index";
 import { Borders } from "../interfaces/spacing/index";
-export declare const DARK_THEME_COLORS: Colors;
-export declare const LIGHT_THEME_COLORS: Colors;
 export declare const DEFAULT_BORDERS: Borders;

package/out/theme/constants/ColorConstants.luau

@@ -1,104 +1,8 @@
 -- Compiled with roblox-ts v3.0.0
-local TS = _G[script]
-local _colors = TS.import(script, script.Parent.Parent, "interfaces", "palette", "colors")
-local Blue = _colors.Blue
-local Common = _colors.Common
-local Gray = _colors.Gray
-local Green = _colors.Green
-local Purple = _colors.Purple
-local Red = _colors.Red
-local Yellow = _colors.Yellow
--- dark theme
-local DARK_THEME_COLORS = {
-	backgroundDefault = Common.Black,
-	backgroundContrast = Gray[110],
-	backgroundMuted = Gray[90],
-	backgroundUIDefault = Gray[90],
-	backgroundUIMuted = Gray[100],
-	backgroundUIContrast = Gray[100],
-	UIDefault = Gray[70],
-	UIMuted = Gray[100],
-	UIEmphasis = Gray[80],
-	textDefault = Common.White,
-	textMuted = Gray[50],
-	textEmphasis = Common.White,
-	iconDefault = Common.White,
-	iconEmphasis = Common.White,
-	iconOnHover = Common.White,
-	systemPrimaryDefault = Common.White,
-	systemPrimaryOnHover = Gray[40],
-	systemPrimaryContent = Common.Black,
-	contextualPrimaryDefault = Green[50],
-	contextualPrimaryOnHover = Green[40],
-	contextualPrimaryContent = Common.Black,
-	secondaryDefault = Common.White,
-	secondaryOnHover = Gray[40],
-	secondaryContent = Common.White,
-	divider = Gray[70],
-	overlay = Common.Black,
-	dropShadow = Common.Black,
-	navigationBar = Gray[110],
-	badge = Common.White,
-	badgeContent = Common.Black,
-	placeholder = Gray[100],
-	online = Green[50],
-	offline = Gray[50],
-	alert = Red[60],
-	success = Green[50],
-	accent = Purple[50],
-	link = Blue[50],
-	caution = Yellow[50],
-	text = Common.White,
-	background = Common.Black,
-}
-local LIGHT_THEME_COLORS = {
-	backgroundDefault = Common.White,
-	backgroundContrast = Gray[40],
-	backgroundMuted = Gray[30],
-	backgroundUIDefault = Gray[30],
-	backgroundUIMuted = Gray[50],
-	backgroundUIContrast = Gray[50],
-	UIDefault = Gray[70],
-	UIMuted = Gray[50],
-	UIEmphasis = Gray[80],
-	textDefault = Common.Black,
-	textMuted = Gray[50],
-	textEmphasis = Common.Black,
-	iconDefault = Common.Black,
-	iconEmphasis = Common.Black,
-	iconOnHover = Common.Black,
-	systemPrimaryDefault = Common.Black,
-	systemPrimaryOnHover = Gray[40],
-	systemPrimaryContent = Common.White,
-	contextualPrimaryDefault = Green[60],
-	contextualPrimaryOnHover = Green[40],
-	contextualPrimaryContent = Common.White,
-	secondaryDefault = Common.Black,
-	secondaryOnHover = Gray[40],
-	secondaryContent = Common.Black,
-	divider = Gray[70],
-	overlay = Common.White,
-	dropShadow = Common.White,
-	navigationBar = Gray[40],
-	badge = Common.Black,
-	badgeContent = Common.White,
-	placeholder = Gray[50],
-	online = Green[60],
-	offline = Gray[50],
-	alert = Red[60],
-	success = Green[60],
-	accent = Purple[50],
-	link = Blue[50],
-	caution = Yellow[50],
-	text = Common.Black,
-	background = Common.White,
-}
 local DEFAULT_BORDERS = {
 	default = 1,
 	divider = 2,
 }
 return {
-	DARK_THEME_COLORS = DARK_THEME_COLORS,
-	LIGHT_THEME_COLORS = LIGHT_THEME_COLORS,
 	DEFAULT_BORDERS = DEFAULT_BORDERS,
 }

package/out/theme/context/ThemeProvider.d.ts

@@ -1,5 +1,8 @@
+import React from "@rbxts/react";
 import { Theme } from "../interfaces/index";
 import { CustomizedProps } from "../types/index";
+import { ThemeScope } from "./themeScope";
+export declare const ThemeContext: React.Context<ThemeScope<Theme> | undefined>;
 export interface ThemeProviderProps {
     theme?: Theme;
 }

package/out/theme/context/ThemeProvider.luau

@@ -2,11 +2,11 @@
 local TS = _G[script]
 local _react = TS.import(script, TS.getModule(script, "@rbxts", "react"))
 local React = _react
-local StrictMode = _react.StrictMode
 local useEffect = _react.useEffect
-local ReflexProvider = TS.import(script, TS.getModule(script, "@rbxts", "react-reflex")).ReflexProvider
+local useMemo = _react.useMemo
+local useState = _react.useState
 local DEFAULT_THEME = TS.import(script, script.Parent.Parent, "constants").DEFAULT_THEME
-local themeProducer = TS.import(script, script.Parent, "ThemeProducer").themeProducer
+local ThemeContext = React.createContext(nil)
 local function ThemeProvider(props)
 	local _binding = props
 	local theme = _binding.theme
@@ -14,15 +14,22 @@ local function ThemeProvider(props)
 		theme = DEFAULT_THEME
 	end
 	local children = _binding.children
-	-- When theme prop changes
+	local current, setCurrent = useState(theme)
 	useEffect(function()
-		themeProducer.setTheme(theme)
+		setCurrent(theme)
 	end, { theme })
-	return React.createElement(StrictMode, nil, React.createElement(ReflexProvider, {
-		producer = themeProducer,
-	}, children))
+	local value = useMemo(function()
+		return {
+			theme = current,
+			setTheme = setCurrent,
+		}
+	end, { current })
+	return React.createElement(ThemeContext.Provider, {
+		value = value,
+	}, children)
 end
 local default = ThemeProvider
 return {
+	ThemeContext = ThemeContext,
 	default = default,
 }

package/out/theme/context/themeScope.d.ts

@@ -0,0 +1,5 @@
+export interface ThemeScope<T> {
+    theme: T;
+    setTheme: (theme: T) => void;
+}
+export declare function readScopedTheme<T>(provided: ThemeScope<T> | undefined, fallback: ThemeScope<T>): ThemeScope<T>;

package/out/theme/context/themeScope.luau

@@ -0,0 +1,7 @@
+-- Compiled with roblox-ts v3.0.0
+local function readScopedTheme(provided, fallback)
+	return provided or fallback
+end
+return {
+	readScopedTheme = readScopedTheme,
+}