@lattice-ui/progress 0.3.0

package/README.md

@@ -0,0 +1,16 @@
+# @lattice-ui/progress
+
+Headless progress and spinner primitives for Roblox UI.
+
+## Exports
+
+- `Progress`
+- `Progress.Root`
+- `Progress.Indicator`
+- `Progress.Spinner`
+
+## Notes
+
+- `Progress` supports `value`/`max` and clamps out-of-range values.
+- `indeterminate` mode uses a fixed indicator ratio.
+- `Spinner` defaults to `spinning=true` and rotates on heartbeat.

package/out/Progress/ProgressIndicator.d.ts

@@ -0,0 +1,3 @@
+import { React } from "@lattice-ui/core";
+import type { ProgressIndicatorProps } from "./types";
+export declare function ProgressIndicator(props: ProgressIndicatorProps): React.JSX.Element;

package/out/Progress/ProgressIndicator.luau

@@ -0,0 +1,30 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _core = TS.import(script, TS.getModule(script, "@lattice-ui", "core").out)
+local React = _core.React
+local Slot = _core.Slot
+local useProgressContext = TS.import(script, script.Parent, "context").useProgressContext
+local function ProgressIndicator(props)
+	local progressContext = useProgressContext()
+	local widthScale = if progressContext.indeterminate then 0.35 else progressContext.ratio
+	local xScale = if progressContext.indeterminate then 0 else 0
+	if props.asChild then
+		local child = props.children
+		if not child then
+			error("[ProgressIndicator] `asChild` requires a child element.")
+		end
+		return React.createElement(Slot, {
+			Position = UDim2.fromScale(xScale, 0),
+			Size = UDim2.fromScale(widthScale, 1),
+		}, child)
+	end
+	return React.createElement("frame", {
+		BackgroundColor3 = Color3.fromRGB(102, 156, 255),
+		BorderSizePixel = 0,
+		Position = UDim2.fromScale(xScale, 0),
+		Size = UDim2.fromScale(widthScale, 1),
+	}, props.children)
+end
+return {
+	ProgressIndicator = ProgressIndicator,
+}

package/out/Progress/ProgressRoot.d.ts

@@ -0,0 +1,4 @@
+import { React } from "@lattice-ui/core";
+import type { ProgressProps } from "./types";
+export declare function ProgressRoot(props: ProgressProps): React.JSX.Element;
+export { ProgressRoot as Progress };

package/out/Progress/ProgressRoot.luau

@@ -0,0 +1,46 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _core = TS.import(script, TS.getModule(script, "@lattice-ui", "core").out)
+local React = _core.React
+local useControllableState = _core.useControllableState
+local ProgressContextProvider = TS.import(script, script.Parent, "context").ProgressContextProvider
+local _math = TS.import(script, script.Parent, "math")
+local clampProgressValue = _math.clampProgressValue
+local resolveProgressRatio = _math.resolveProgressRatio
+local function ProgressRoot(props)
+	local _condition = props.max
+	if _condition == nil then
+		_condition = 100
+	end
+	local max = math.max(1, _condition)
+	local indeterminate = props.indeterminate == true
+	local _object = {
+		value = props.value,
+	}
+	local _left = "defaultValue"
+	local _condition_1 = props.defaultValue
+	if _condition_1 == nil then
+		_condition_1 = 0
+	end
+	_object[_left] = _condition_1
+	_object.onChange = props.onValueChange
+	local _binding = useControllableState(_object)
+	local value = _binding[1]
+	local clampedValue = clampProgressValue(value, max)
+	local ratio = resolveProgressRatio(clampedValue, max, indeterminate)
+	local contextValue = React.useMemo(function()
+		return {
+			value = clampedValue,
+			max = max,
+			ratio = ratio,
+			indeterminate = indeterminate,
+		}
+	end, { clampedValue, indeterminate, max, ratio })
+	return React.createElement(ProgressContextProvider, {
+		value = contextValue,
+	}, props.children)
+end
+return {
+	ProgressRoot = ProgressRoot,
+	Progress = ProgressRoot,
+}

package/out/Progress/Spinner.d.ts

@@ -0,0 +1,3 @@
+import { React } from "@lattice-ui/core";
+import type { SpinnerProps } from "./types";
+export declare function Spinner(props: SpinnerProps): React.JSX.Element;

package/out/Progress/Spinner.luau

@@ -0,0 +1,68 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _core = TS.import(script, TS.getModule(script, "@lattice-ui", "core").out)
+local React = _core.React
+local Slot = _core.Slot
+local RunService = game:GetService("RunService")
+local function toGuiObject(instance)
+	if not instance or not instance:IsA("GuiObject") then
+		return nil
+	end
+	return instance
+end
+local function Spinner(props)
+	local _condition = props.spinning
+	if _condition == nil then
+		_condition = true
+	end
+	local spinning = _condition
+	local _condition_1 = props.speedDegPerSecond
+	if _condition_1 == nil then
+		_condition_1 = 180
+	end
+	local speedDegPerSecond = _condition_1
+	local spinnerRef = React.useRef()
+	local setSpinnerRef = React.useCallback(function(instance)
+		spinnerRef.current = toGuiObject(instance)
+	end, {})
+	React.useEffect(function()
+		if not spinning then
+			return nil
+		end
+		local connection = RunService.Heartbeat:Connect(function(deltaSeconds)
+			local spinner = spinnerRef.current
+			if not spinner then
+				return nil
+			end
+			spinner.Rotation += speedDegPerSecond * deltaSeconds
+		end)
+		return function()
+			connection:Disconnect()
+		end
+	end, { spinning, speedDegPerSecond })
+	if props.asChild then
+		local child = props.children
+		if not child then
+			error("[Spinner] `asChild` requires a child element.")
+		end
+		return React.createElement(Slot, {
+			Visible = spinning,
+			ref = setSpinnerRef,
+		}, child)
+	end
+	return React.createElement("frame", {
+		BackgroundTransparency = 1,
+		BorderSizePixel = 0,
+		Size = UDim2.fromOffset(22, 22),
+		Visible = spinning,
+		ref = setSpinnerRef,
+	}, React.createElement("uicorner", {
+		CornerRadius = UDim.new(1, 0),
+	}), React.createElement("uistroke", {
+		Color = Color3.fromRGB(102, 156, 255),
+		Thickness = 2,
+	}))
+end
+return {
+	Spinner = Spinner,
+}

package/out/Progress/context.d.ts

@@ -0,0 +1,3 @@
+import type { ProgressContextValue } from "./types";
+declare const ProgressContextProvider: import("@rbxts/react").Provider<ProgressContextValue | undefined>, useProgressContext: () => ProgressContextValue;
+export { ProgressContextProvider, useProgressContext };

package/out/Progress/context.luau

@@ -0,0 +1,10 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local createStrictContext = TS.import(script, TS.getModule(script, "@lattice-ui", "core").out).createStrictContext
+local _binding = createStrictContext("Progress")
+local ProgressContextProvider = _binding[1]
+local useProgressContext = _binding[2]
+return {
+	ProgressContextProvider = ProgressContextProvider,
+	useProgressContext = useProgressContext,
+}

package/out/Progress/math.d.ts

@@ -0,0 +1,2 @@
+export declare function clampProgressValue(value: number, max: number): number;
+export declare function resolveProgressRatio(value: number, max: number, indeterminate?: boolean): number;

package/out/Progress/math.luau

@@ -0,0 +1,17 @@
+-- Compiled with roblox-ts v3.0.0
+local function clampProgressValue(value, max)
+	local safeMax = math.max(1, max)
+	return math.clamp(value, 0, safeMax)
+end
+local function resolveProgressRatio(value, max, indeterminate)
+	if indeterminate == true then
+		return 0.25
+	end
+	local safeMax = math.max(1, max)
+	local clamped = clampProgressValue(value, safeMax)
+	return clamped / safeMax
+end
+return {
+	clampProgressValue = clampProgressValue,
+	resolveProgressRatio = resolveProgressRatio,
+}

package/out/Progress/types.d.ts

@@ -0,0 +1,25 @@
+import type React from "@rbxts/react";
+export type ProgressContextValue = {
+    value: number;
+    max: number;
+    ratio: number;
+    indeterminate: boolean;
+};
+export type ProgressProps = {
+    value?: number;
+    defaultValue?: number;
+    onValueChange?: (value: number) => void;
+    max?: number;
+    indeterminate?: boolean;
+    children?: React.ReactNode;
+};
+export type ProgressIndicatorProps = {
+    asChild?: boolean;
+    children?: React.ReactElement;
+};
+export type SpinnerProps = {
+    asChild?: boolean;
+    spinning?: boolean;
+    speedDegPerSecond?: number;
+    children?: React.ReactElement;
+};

package/out/Progress/types.luau

@@ -0,0 +1,2 @@
+-- Compiled with roblox-ts v3.0.0
+return nil

package/out/index.d.ts

@@ -0,0 +1,10 @@
+import { ProgressIndicator } from "./Progress/ProgressIndicator";
+import { ProgressRoot } from "./Progress/ProgressRoot";
+import { Spinner } from "./Progress/Spinner";
+export declare const Progress: {
+    readonly Root: typeof ProgressRoot;
+    readonly Indicator: typeof ProgressIndicator;
+    readonly Spinner: typeof Spinner;
+};
+export { clampProgressValue, resolveProgressRatio } from "./Progress/math";
+export type { ProgressContextValue, ProgressIndicatorProps, ProgressProps, SpinnerProps } from "./Progress/types";

package/out/init.luau

@@ -0,0 +1,16 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+local ProgressIndicator = TS.import(script, script, "Progress", "ProgressIndicator").ProgressIndicator
+local ProgressRoot = TS.import(script, script, "Progress", "ProgressRoot").ProgressRoot
+local Spinner = TS.import(script, script, "Progress", "Spinner").Spinner
+local Progress = {
+	Root = ProgressRoot,
+	Indicator = ProgressIndicator,
+	Spinner = Spinner,
+}
+local _math = TS.import(script, script, "Progress", "math")
+exports.clampProgressValue = _math.clampProgressValue
+exports.resolveProgressRatio = _math.resolveProgressRatio
+exports.Progress = Progress
+return exports

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@lattice-ui/progress",
+  "version": "0.3.0",
+  "private": false,
+  "main": "out/init.luau",
+  "types": "out/index.d.ts",
+  "dependencies": {
+    "@lattice-ui/core": "0.3.0"
+  },
+  "devDependencies": {
+    "@rbxts/react": "17.3.7-ts.1",
+    "@rbxts/react-roblox": "17.3.7-ts.1"
+  },
+  "peerDependencies": {
+    "@rbxts/react": "^17",
+    "@rbxts/react-roblox": "^17"
+  },
+  "scripts": {
+    "build": "rbxtsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "watch": "rbxtsc -p tsconfig.json -w"
+  }
+}

package/src/Progress/ProgressIndicator.tsx

@@ -0,0 +1,34 @@
+import { React, Slot } from "@lattice-ui/core";
+import { useProgressContext } from "./context";
+import type { ProgressIndicatorProps } from "./types";
+
+export function ProgressIndicator(props: ProgressIndicatorProps) {
+  const progressContext = useProgressContext();
+
+  const widthScale = progressContext.indeterminate ? 0.35 : progressContext.ratio;
+  const xScale = progressContext.indeterminate ? 0 : 0;
+
+  if (props.asChild) {
+    const child = props.children;
+    if (!child) {
+      error("[ProgressIndicator] `asChild` requires a child element.");
+    }
+
+    return (
+      <Slot Position={UDim2.fromScale(xScale, 0)} Size={UDim2.fromScale(widthScale, 1)}>
+        {child}
+      </Slot>
+    );
+  }
+
+  return (
+    <frame
+      BackgroundColor3={Color3.fromRGB(102, 156, 255)}
+      BorderSizePixel={0}
+      Position={UDim2.fromScale(xScale, 0)}
+      Size={UDim2.fromScale(widthScale, 1)}
+    >
+      {props.children}
+    </frame>
+  );
+}

package/src/Progress/ProgressRoot.tsx

@@ -0,0 +1,32 @@
+import { React, useControllableState } from "@lattice-ui/core";
+import { ProgressContextProvider } from "./context";
+import { clampProgressValue, resolveProgressRatio } from "./math";
+import type { ProgressProps } from "./types";
+
+export function ProgressRoot(props: ProgressProps) {
+  const max = math.max(1, props.max ?? 100);
+  const indeterminate = props.indeterminate === true;
+
+  const [value] = useControllableState<number>({
+    value: props.value,
+    defaultValue: props.defaultValue ?? 0,
+    onChange: props.onValueChange,
+  });
+
+  const clampedValue = clampProgressValue(value, max);
+  const ratio = resolveProgressRatio(clampedValue, max, indeterminate);
+
+  const contextValue = React.useMemo(
+    () => ({
+      value: clampedValue,
+      max,
+      ratio,
+      indeterminate,
+    }),
+    [clampedValue, indeterminate, max, ratio],
+  );
+
+  return <ProgressContextProvider value={contextValue}>{props.children}</ProgressContextProvider>;
+}
+
+export { ProgressRoot as Progress };

package/src/Progress/Spinner.tsx

@@ -0,0 +1,68 @@
+import { React, Slot } from "@lattice-ui/core";
+import type { SpinnerProps } from "./types";
+
+const RunService = game.GetService("RunService");
+
+function toGuiObject(instance: Instance | undefined) {
+  if (!instance || !instance.IsA("GuiObject")) {
+    return undefined;
+  }
+
+  return instance;
+}
+
+export function Spinner(props: SpinnerProps) {
+  const spinning = props.spinning ?? true;
+  const speedDegPerSecond = props.speedDegPerSecond ?? 180;
+
+  const spinnerRef = React.useRef<GuiObject>();
+
+  const setSpinnerRef = React.useCallback((instance: Instance | undefined) => {
+    spinnerRef.current = toGuiObject(instance);
+  }, []);
+
+  React.useEffect(() => {
+    if (!spinning) {
+      return;
+    }
+
+    const connection = RunService.Heartbeat.Connect((deltaSeconds) => {
+      const spinner = spinnerRef.current;
+      if (!spinner) {
+        return;
+      }
+
+      spinner.Rotation += speedDegPerSecond * deltaSeconds;
+    });
+
+    return () => {
+      connection.Disconnect();
+    };
+  }, [spinning, speedDegPerSecond]);
+
+  if (props.asChild) {
+    const child = props.children;
+    if (!child) {
+      error("[Spinner] `asChild` requires a child element.");
+    }
+
+    return (
+      <Slot Visible={spinning} ref={setSpinnerRef}>
+        {child}
+      </Slot>
+    );
+  }
+
+  return (
+    <frame
+      BackgroundTransparency={1}
+      BorderSizePixel={0}
+      Size={UDim2.fromOffset(22, 22)}
+      Visible={spinning}
+      ref={setSpinnerRef}
+    >
+      <uicorner CornerRadius={new UDim(1, 0)} />
+      <uistroke Color={Color3.fromRGB(102, 156, 255)} Thickness={2} />
+    </frame>
+  );
+}

package/src/Progress/context.ts

@@ -0,0 +1,6 @@
+import { createStrictContext } from "@lattice-ui/core";
+import type { ProgressContextValue } from "./types";
+
+const [ProgressContextProvider, useProgressContext] = createStrictContext<ProgressContextValue>("Progress");
+
+export { ProgressContextProvider, useProgressContext };

package/src/Progress/math.ts

@@ -0,0 +1,14 @@
+export function clampProgressValue(value: number, max: number) {
+  const safeMax = math.max(1, max);
+  return math.clamp(value, 0, safeMax);
+}
+
+export function resolveProgressRatio(value: number, max: number, indeterminate?: boolean) {
+  if (indeterminate === true) {
+    return 0.25;
+  }
+
+  const safeMax = math.max(1, max);
+  const clamped = clampProgressValue(value, safeMax);
+  return clamped / safeMax;
+}

package/src/Progress/types.ts

@@ -0,0 +1,29 @@
+import type React from "@rbxts/react";
+
+export type ProgressContextValue = {
+  value: number;
+  max: number;
+  ratio: number;
+  indeterminate: boolean;
+};
+
+export type ProgressProps = {
+  value?: number;
+  defaultValue?: number;
+  onValueChange?: (value: number) => void;
+  max?: number;
+  indeterminate?: boolean;
+  children?: React.ReactNode;
+};
+
+export type ProgressIndicatorProps = {
+  asChild?: boolean;
+  children?: React.ReactElement;
+};
+
+export type SpinnerProps = {
+  asChild?: boolean;
+  spinning?: boolean;
+  speedDegPerSecond?: number;
+  children?: React.ReactElement;
+};

package/src/index.ts

@@ -0,0 +1,12 @@
+import { ProgressIndicator } from "./Progress/ProgressIndicator";
+import { ProgressRoot } from "./Progress/ProgressRoot";
+import { Spinner } from "./Progress/Spinner";
+
+export const Progress = {
+  Root: ProgressRoot,
+  Indicator: ProgressIndicator,
+  Spinner,
+} as const;
+
+export { clampProgressValue, resolveProgressRatio } from "./Progress/math";
+export type { ProgressContextValue, ProgressIndicatorProps, ProgressProps, SpinnerProps } from "./Progress/types";

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "out",
+    "declaration": true,
+    "typeRoots": [
+      "./node_modules/@rbxts",
+      "../../node_modules/@rbxts",
+      "./node_modules/@lattice-ui",
+      "../../node_modules/@lattice-ui"
+    ],
+    "types": ["types", "compiler-types"]
+  },
+  "include": ["src"]
+}

package/tsconfig.typecheck.json

@@ -0,0 +1,35 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "baseUrl": "..",
+    "rootDir": "..",
+    "paths": {
+      "@lattice-ui/accordion": ["accordion/src/index.ts"],
+      "@lattice-ui/avatar": ["avatar/src/index.ts"],
+      "@lattice-ui/checkbox": ["checkbox/src/index.ts"],
+      "@lattice-ui/combobox": ["combobox/src/index.ts"],
+      "@lattice-ui/core": ["core/src/index.ts"],
+      "@lattice-ui/dialog": ["dialog/src/index.ts"],
+      "@lattice-ui/focus": ["focus/src/index.ts"],
+      "@lattice-ui/layer": ["layer/src/index.ts"],
+      "@lattice-ui/menu": ["menu/src/index.ts"],
+      "@lattice-ui/popover": ["popover/src/index.ts"],
+      "@lattice-ui/popper": ["popper/src/index.ts"],
+      "@lattice-ui/progress": ["progress/src/index.ts"],
+      "@lattice-ui/radio-group": ["radio-group/src/index.ts"],
+      "@lattice-ui/scroll-area": ["scroll-area/src/index.ts"],
+      "@lattice-ui/select": ["select/src/index.ts"],
+      "@lattice-ui/slider": ["slider/src/index.ts"],
+      "@lattice-ui/style": ["style/src/index.ts"],
+      "@lattice-ui/switch": ["switch/src/index.ts"],
+      "@lattice-ui/system": ["system/src/index.ts"],
+      "@lattice-ui/tabs": ["tabs/src/index.ts"],
+      "@lattice-ui/text-field": ["text-field/src/index.ts"],
+      "@lattice-ui/textarea": ["textarea/src/index.ts"],
+      "@lattice-ui/toast": ["toast/src/index.ts"],
+      "@lattice-ui/toggle-group": ["toggle-group/src/index.ts"],
+      "@lattice-ui/tooltip": ["tooltip/src/index.ts"]
+    }
+  }
+}