@lattice-ui/avatar 0.3.0

package/README.md

@@ -0,0 +1,16 @@
+# @lattice-ui/avatar
+
+Headless avatar primitives for Roblox UI with delayed fallback rendering.
+
+## Exports
+
+- `Avatar`
+- `Avatar.Root`
+- `Avatar.Image`
+- `Avatar.Fallback`
+
+## Notes
+
+- `delayMs` controls fallback reveal timing (default: `250`).
+- Missing image sources immediately show fallback content.
+- Fallback visibility logic is exported for unit testing.

package/out/Avatar/AvatarFallback.d.ts

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

package/out/Avatar/AvatarFallback.luau

@@ -0,0 +1,34 @@
+-- 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 useAvatarContext = TS.import(script, script.Parent, "context").useAvatarContext
+local resolveAvatarFallbackVisible = TS.import(script, script.Parent, "state").resolveAvatarFallbackVisible
+local function AvatarFallback(props)
+	local avatarContext = useAvatarContext()
+	local visible = resolveAvatarFallbackVisible(avatarContext.status, avatarContext.delayElapsed)
+	if props.asChild then
+		local child = props.children
+		if not child then
+			error("[AvatarFallback] `asChild` requires a child element.")
+		end
+		return React.createElement(Slot, {
+			Visible = visible,
+		}, child)
+	end
+	return React.createElement("textlabel", {
+		BackgroundColor3 = Color3.fromRGB(65, 72, 89),
+		BorderSizePixel = 0,
+		Size = UDim2.fromOffset(40, 40),
+		Text = "AB",
+		TextColor3 = Color3.fromRGB(235, 240, 248),
+		TextSize = 14,
+		Visible = visible,
+	}, React.createElement("uicorner", {
+		CornerRadius = UDim.new(1, 0),
+	}), props.children)
+end
+return {
+	AvatarFallback = AvatarFallback,
+}

package/out/Avatar/AvatarImage.d.ts

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

package/out/Avatar/AvatarImage.luau

@@ -0,0 +1,81 @@
+-- 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 useAvatarContext = TS.import(script, script.Parent, "context").useAvatarContext
+local function toImageLabel(instance)
+	if not instance or not instance:IsA("ImageLabel") then
+		return nil
+	end
+	return instance
+end
+local function AvatarImage(props)
+	local avatarContext = useAvatarContext()
+	local _condition = props.src
+	if _condition == nil then
+		_condition = avatarContext.src
+	end
+	local source = _condition
+	local imageRef = React.useRef()
+	local setImageRef = React.useCallback(function(instance)
+		imageRef.current = toImageLabel(instance)
+	end, {})
+	React.useEffect(function()
+		if source == nil or #source == 0 then
+			avatarContext.setStatus("error")
+			return nil
+		end
+		avatarContext.setStatus("loading")
+	end, { avatarContext, source })
+	React.useEffect(function()
+		local image = imageRef.current
+		if not image then
+			return nil
+		end
+		if image.IsLoaded then
+			avatarContext.setStatus("loaded")
+		end
+		local connection = image:GetPropertyChangedSignal("IsLoaded"):Connect(function()
+			if image.IsLoaded then
+				avatarContext.setStatus("loaded")
+			end
+		end)
+		return function()
+			connection:Disconnect()
+		end
+	end, { avatarContext, source })
+	if props.asChild then
+		local child = props.children
+		if not child then
+			error("[AvatarImage] `asChild` requires a child element.")
+		end
+		local _attributes = {}
+		local _condition_1 = source
+		if _condition_1 == nil then
+			_condition_1 = ""
+		end
+		_attributes.Image = _condition_1
+		_attributes.Visible = avatarContext.status == "loaded"
+		_attributes.ref = setImageRef
+		return React.createElement(Slot, _attributes, child)
+	end
+	local _attributes = {
+		BackgroundTransparency = 1,
+		BorderSizePixel = 0,
+	}
+	local _condition_1 = source
+	if _condition_1 == nil then
+		_condition_1 = ""
+	end
+	_attributes.Image = _condition_1
+	_attributes.Size = UDim2.fromOffset(40, 40)
+	_attributes.Visible = avatarContext.status == "loaded"
+	_attributes.ref = setImageRef
+	return React.createElement("imagelabel", _attributes, React.createElement("uicorner", {
+		CornerRadius = UDim.new(1, 0),
+	}))
+end
+return {
+	AvatarImage = AvatarImage,
+}

package/out/Avatar/AvatarRoot.d.ts

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

package/out/Avatar/AvatarRoot.luau

@@ -0,0 +1,48 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local React = TS.import(script, TS.getModule(script, "@lattice-ui", "core").out).React
+local AvatarContextProvider = TS.import(script, script.Parent, "context").AvatarContextProvider
+local function AvatarRoot(props)
+	local _condition = props.delayMs
+	if _condition == nil then
+		_condition = 250
+	end
+	local delayMs = math.max(0, _condition)
+	local hasSource = props.src ~= nil and #props.src > 0
+	local status, setStatus = React.useState(if hasSource then "loading" else "error")
+	local delayElapsed, setDelayElapsed = React.useState(not hasSource)
+	local sequenceRef = React.useRef(0)
+	React.useEffect(function()
+		sequenceRef.current += 1
+		local sequence = sequenceRef.current
+		if props.src == nil or #props.src == 0 then
+			setStatus("error")
+			setDelayElapsed(true)
+			return nil
+		end
+		setStatus("loading")
+		setDelayElapsed(false)
+		local delaySeconds = delayMs / 1000
+		task.delay(delaySeconds, function()
+			if sequenceRef.current ~= sequence then
+				return nil
+			end
+			setDelayElapsed(true)
+		end)
+	end, { delayMs, props.src })
+	local contextValue = React.useMemo(function()
+		return {
+			src = props.src,
+			status = status,
+			setStatus = setStatus,
+			delayElapsed = delayElapsed,
+		}
+	end, { delayElapsed, props.src, status })
+	return React.createElement(AvatarContextProvider, {
+		value = contextValue,
+	}, props.children)
+end
+return {
+	AvatarRoot = AvatarRoot,
+	Avatar = AvatarRoot,
+}

package/out/Avatar/context.d.ts

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

package/out/Avatar/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("Avatar")
+local AvatarContextProvider = _binding[1]
+local useAvatarContext = _binding[2]
+return {
+	AvatarContextProvider = AvatarContextProvider,
+	useAvatarContext = useAvatarContext,
+}

package/out/Avatar/state.d.ts

@@ -0,0 +1,2 @@
+export type AvatarStatus = "idle" | "loading" | "loaded" | "error";
+export declare function resolveAvatarFallbackVisible(status: AvatarStatus, delayElapsed: boolean): boolean;

package/out/Avatar/state.luau

@@ -0,0 +1,13 @@
+-- Compiled with roblox-ts v3.0.0
+local function resolveAvatarFallbackVisible(status, delayElapsed)
+	if status == "loaded" then
+		return false
+	end
+	if status == "error" then
+		return true
+	end
+	return delayElapsed
+end
+return {
+	resolveAvatarFallbackVisible = resolveAvatarFallbackVisible,
+}

package/out/Avatar/types.d.ts

@@ -0,0 +1,22 @@
+import type React from "@rbxts/react";
+import type { AvatarStatus } from "./state";
+export type AvatarContextValue = {
+    src?: string;
+    status: AvatarStatus;
+    setStatus: (status: AvatarStatus) => void;
+    delayElapsed: boolean;
+};
+export type AvatarProps = {
+    src?: string;
+    delayMs?: number;
+    children?: React.ReactNode;
+};
+export type AvatarImageProps = {
+    asChild?: boolean;
+    src?: string;
+    children?: React.ReactElement;
+};
+export type AvatarFallbackProps = {
+    asChild?: boolean;
+    children?: React.ReactElement;
+};

package/out/Avatar/types.luau

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

package/out/index.d.ts

@@ -0,0 +1,11 @@
+import { AvatarFallback } from "./Avatar/AvatarFallback";
+import { AvatarImage } from "./Avatar/AvatarImage";
+import { AvatarRoot } from "./Avatar/AvatarRoot";
+export declare const Avatar: {
+    readonly Root: typeof AvatarRoot;
+    readonly Image: typeof AvatarImage;
+    readonly Fallback: typeof AvatarFallback;
+};
+export type { AvatarStatus } from "./Avatar/state";
+export { resolveAvatarFallbackVisible } from "./Avatar/state";
+export type { AvatarContextValue, AvatarFallbackProps, AvatarImageProps, AvatarProps } from "./Avatar/types";

package/out/init.luau

@@ -0,0 +1,14 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+local AvatarFallback = TS.import(script, script, "Avatar", "AvatarFallback").AvatarFallback
+local AvatarImage = TS.import(script, script, "Avatar", "AvatarImage").AvatarImage
+local AvatarRoot = TS.import(script, script, "Avatar", "AvatarRoot").AvatarRoot
+local Avatar = {
+	Root = AvatarRoot,
+	Image = AvatarImage,
+	Fallback = AvatarFallback,
+}
+exports.resolveAvatarFallbackVisible = TS.import(script, script, "Avatar", "state").resolveAvatarFallbackVisible
+exports.Avatar = Avatar
+return exports

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@lattice-ui/avatar",
+  "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/Avatar/AvatarFallback.tsx

@@ -0,0 +1,33 @@
+import { React, Slot } from "@lattice-ui/core";
+import { useAvatarContext } from "./context";
+import { resolveAvatarFallbackVisible } from "./state";
+import type { AvatarFallbackProps } from "./types";
+
+export function AvatarFallback(props: AvatarFallbackProps) {
+  const avatarContext = useAvatarContext();
+  const visible = resolveAvatarFallbackVisible(avatarContext.status, avatarContext.delayElapsed);
+
+  if (props.asChild) {
+    const child = props.children;
+    if (!child) {
+      error("[AvatarFallback] `asChild` requires a child element.");
+    }
+
+    return <Slot Visible={visible}>{child}</Slot>;
+  }
+
+  return (
+    <textlabel
+      BackgroundColor3={Color3.fromRGB(65, 72, 89)}
+      BorderSizePixel={0}
+      Size={UDim2.fromOffset(40, 40)}
+      Text="AB"
+      TextColor3={Color3.fromRGB(235, 240, 248)}
+      TextSize={14}
+      Visible={visible}
+    >
+      <uicorner CornerRadius={new UDim(1, 0)} />
+      {props.children}
+    </textlabel>
+  );
+}

package/src/Avatar/AvatarImage.tsx

@@ -0,0 +1,78 @@
+import { React, Slot } from "@lattice-ui/core";
+import { useAvatarContext } from "./context";
+import type { AvatarImageProps } from "./types";
+
+function toImageLabel(instance: Instance | undefined) {
+  if (!instance || !instance.IsA("ImageLabel")) {
+    return undefined;
+  }
+
+  return instance;
+}
+
+export function AvatarImage(props: AvatarImageProps) {
+  const avatarContext = useAvatarContext();
+  const source = props.src ?? avatarContext.src;
+
+  const imageRef = React.useRef<ImageLabel>();
+
+  const setImageRef = React.useCallback((instance: Instance | undefined) => {
+    imageRef.current = toImageLabel(instance);
+  }, []);
+
+  React.useEffect(() => {
+    if (source === undefined || source.size() === 0) {
+      avatarContext.setStatus("error");
+      return;
+    }
+
+    avatarContext.setStatus("loading");
+  }, [avatarContext, source]);
+
+  React.useEffect(() => {
+    const image = imageRef.current;
+    if (!image) {
+      return;
+    }
+
+    if (image.IsLoaded) {
+      avatarContext.setStatus("loaded");
+    }
+
+    const connection = image.GetPropertyChangedSignal("IsLoaded").Connect(() => {
+      if (image.IsLoaded) {
+        avatarContext.setStatus("loaded");
+      }
+    });
+
+    return () => {
+      connection.Disconnect();
+    };
+  }, [avatarContext, source]);
+
+  if (props.asChild) {
+    const child = props.children;
+    if (!child) {
+      error("[AvatarImage] `asChild` requires a child element.");
+    }
+
+    return (
+      <Slot Image={source ?? ""} Visible={avatarContext.status === "loaded"} ref={setImageRef}>
+        {child}
+      </Slot>
+    );
+  }
+
+  return (
+    <imagelabel
+      BackgroundTransparency={1}
+      BorderSizePixel={0}
+      Image={source ?? ""}
+      Size={UDim2.fromOffset(40, 40)}
+      Visible={avatarContext.status === "loaded"}
+      ref={setImageRef}
+    >
+      <uicorner CornerRadius={new UDim(1, 0)} />
+    </imagelabel>
+  );
+}

package/src/Avatar/AvatarRoot.tsx

@@ -0,0 +1,50 @@
+import { React } from "@lattice-ui/core";
+import { AvatarContextProvider } from "./context";
+import type { AvatarStatus } from "./state";
+import type { AvatarProps } from "./types";
+
+export function AvatarRoot(props: AvatarProps) {
+  const delayMs = math.max(0, props.delayMs ?? 250);
+  const hasSource = props.src !== undefined && props.src.size() > 0;
+
+  const [status, setStatus] = React.useState<AvatarStatus>(hasSource ? "loading" : "error");
+  const [delayElapsed, setDelayElapsed] = React.useState(!hasSource);
+  const sequenceRef = React.useRef(0);
+
+  React.useEffect(() => {
+    sequenceRef.current += 1;
+    const sequence = sequenceRef.current;
+
+    if (props.src === undefined || props.src.size() === 0) {
+      setStatus("error");
+      setDelayElapsed(true);
+      return;
+    }
+
+    setStatus("loading");
+    setDelayElapsed(false);
+
+    const delaySeconds = delayMs / 1000;
+    task.delay(delaySeconds, () => {
+      if (sequenceRef.current !== sequence) {
+        return;
+      }
+
+      setDelayElapsed(true);
+    });
+  }, [delayMs, props.src]);
+
+  const contextValue = React.useMemo(
+    () => ({
+      src: props.src,
+      status,
+      setStatus,
+      delayElapsed,
+    }),
+    [delayElapsed, props.src, status],
+  );
+
+  return <AvatarContextProvider value={contextValue}>{props.children}</AvatarContextProvider>;
+}
+
+export { AvatarRoot as Avatar };

package/src/Avatar/context.ts

@@ -0,0 +1,6 @@
+import { createStrictContext } from "@lattice-ui/core";
+import type { AvatarContextValue } from "./types";
+
+const [AvatarContextProvider, useAvatarContext] = createStrictContext<AvatarContextValue>("Avatar");
+
+export { AvatarContextProvider, useAvatarContext };

package/src/Avatar/state.ts

@@ -0,0 +1,13 @@
+export type AvatarStatus = "idle" | "loading" | "loaded" | "error";
+
+export function resolveAvatarFallbackVisible(status: AvatarStatus, delayElapsed: boolean) {
+  if (status === "loaded") {
+    return false;
+  }
+
+  if (status === "error") {
+    return true;
+  }
+
+  return delayElapsed;
+}

package/src/Avatar/types.ts

@@ -0,0 +1,26 @@
+import type React from "@rbxts/react";
+import type { AvatarStatus } from "./state";
+
+export type AvatarContextValue = {
+  src?: string;
+  status: AvatarStatus;
+  setStatus: (status: AvatarStatus) => void;
+  delayElapsed: boolean;
+};
+
+export type AvatarProps = {
+  src?: string;
+  delayMs?: number;
+  children?: React.ReactNode;
+};
+
+export type AvatarImageProps = {
+  asChild?: boolean;
+  src?: string;
+  children?: React.ReactElement;
+};
+
+export type AvatarFallbackProps = {
+  asChild?: boolean;
+  children?: React.ReactElement;
+};

package/src/index.ts

@@ -0,0 +1,13 @@
+import { AvatarFallback } from "./Avatar/AvatarFallback";
+import { AvatarImage } from "./Avatar/AvatarImage";
+import { AvatarRoot } from "./Avatar/AvatarRoot";
+
+export const Avatar = {
+  Root: AvatarRoot,
+  Image: AvatarImage,
+  Fallback: AvatarFallback,
+} as const;
+
+export type { AvatarStatus } from "./Avatar/state";
+export { resolveAvatarFallbackVisible } from "./Avatar/state";
+export type { AvatarContextValue, AvatarFallbackProps, AvatarImageProps, AvatarProps } from "./Avatar/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"]
+    }
+  }
+}