@lattice-ui/system 0.1.1

package/out/system/SystemProvider.luau

@@ -0,0 +1,43 @@
+-- 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 defaultLightTheme = TS.import(script, TS.getModule(script, "@lattice-ui", "style").out).defaultLightTheme
+local DensityProvider = TS.import(script, script.Parent.Parent, "density", "DensityProvider").DensityProvider
+local SystemBaseThemeContextProvider = TS.import(script, script.Parent, "baseThemeContext").SystemBaseThemeContextProvider
+local useSystemThemeContext = TS.import(script, script.Parent, "systemThemeContext").useSystemThemeContext
+local function SystemProvider(props)
+	-- SystemProvider owns raw/base theme state. Density is applied in DensityProvider.
+	local _binding = useControllableState({
+		value = props.theme,
+		defaultValue = props.defaultTheme or defaultLightTheme,
+		onChange = props.onThemeChange,
+	})
+	local baseThemeValue = _binding[1]
+	local setBaseThemeValue = _binding[2]
+	local setBaseTheme = React.useCallback(function(nextTheme)
+		-- Write-path contract: updates should target baseTheme, not resolved theme.
+		setBaseThemeValue(nextTheme)
+	end, { setBaseThemeValue })
+	local baseThemeContextValue = React.useMemo(function()
+		return {
+			baseTheme = baseThemeValue,
+			setBaseTheme = setBaseTheme,
+		}
+	end, { baseThemeValue, setBaseTheme })
+	return React.createElement(SystemBaseThemeContextProvider, {
+		value = baseThemeContextValue,
+	}, React.createElement(DensityProvider, {
+		defaultDensity = props.defaultDensity,
+		density = props.density,
+		onDensityChange = props.onDensityChange,
+	}, props.children))
+end
+local function useSystemTheme()
+	return useSystemThemeContext()
+end
+return {
+	SystemProvider = SystemProvider,
+	useSystemTheme = useSystemTheme,
+}

package/out/system/baseThemeContext.d.ts

@@ -0,0 +1,2 @@
+import type { SystemBaseThemeContextValue } from "./types";
+export declare const SystemBaseThemeContextProvider: import("@rbxts/react").Provider<SystemBaseThemeContextValue | undefined>, useSystemBaseThemeContext: () => SystemBaseThemeContextValue;

package/out/system/baseThemeContext.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("SystemBaseThemeContext")
+local SystemBaseThemeContextProvider = _binding[1]
+local useSystemBaseThemeContext = _binding[2]
+return {
+	SystemBaseThemeContextProvider = SystemBaseThemeContextProvider,
+	useSystemBaseThemeContext = useSystemBaseThemeContext,
+}

package/out/system/systemThemeContext.d.ts

@@ -0,0 +1,2 @@
+import type { SystemThemeContextValue } from "./types";
+export declare const SystemThemeContextProvider: import("@rbxts/react").Provider<SystemThemeContextValue | undefined>, useSystemThemeContext: () => SystemThemeContextValue;

package/out/system/systemThemeContext.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("SystemThemeContext")
+local SystemThemeContextProvider = _binding[1]
+local useSystemThemeContext = _binding[2]
+return {
+	SystemThemeContextProvider = SystemThemeContextProvider,
+	useSystemThemeContext = useSystemThemeContext,
+}

package/out/system/types.d.ts

@@ -0,0 +1,26 @@
+import type { Theme } from "@lattice-ui/style";
+import type React from "@rbxts/react";
+import type { DensityToken } from "../density/types";
+export type SystemProviderProps = {
+    theme?: Theme;
+    defaultTheme?: Theme;
+    onThemeChange?: (nextTheme: Theme) => void;
+    density?: DensityToken;
+    defaultDensity?: DensityToken;
+    onDensityChange?: (next: DensityToken) => void;
+    children?: React.ReactNode;
+};
+export type SystemThemeContextValue = {
+    /** Density-resolved theme for read usage in system-managed trees. */
+    theme: Theme;
+    /** Raw theme before density transforms. Writes must target this base theme. */
+    baseTheme: Theme;
+    density: DensityToken;
+    /** Use this to update the raw/base theme source. */
+    setBaseTheme: (next: Theme) => void;
+    setDensity: (next: DensityToken) => void;
+};
+export type SystemBaseThemeContextValue = {
+    baseTheme: Theme;
+    setBaseTheme: (nextTheme: Theme) => void;
+};

package/out/system/types.luau

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

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@lattice-ui/system",
+  "version": "0.1.1",
+  "private": false,
+  "main": "out/init.luau",
+  "types": "out/index.d.ts",
+  "dependencies": {
+    "@lattice-ui/core": "0.1.1",
+    "@lattice-ui/style": "0.1.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/density/DensityProvider.tsx

@@ -0,0 +1,61 @@
+import { createStrictContext, React, useControllableState } from "@lattice-ui/core";
+import { ThemeProvider } from "@lattice-ui/style";
+import { useSystemBaseThemeContext } from "../system/baseThemeContext";
+import { SystemThemeContextProvider } from "../system/systemThemeContext";
+import type { SystemThemeContextValue } from "../system/types";
+import { applyDensity } from "./density";
+import type { DensityContextValue, DensityProviderProps, DensityToken } from "./types";
+
+const [DensityContextProvider, useDensityContext] = createStrictContext<DensityContextValue>("DensityProvider");
+const DEFAULT_DENSITY: DensityToken = "comfortable";
+
+export function DensityProvider(props: DensityProviderProps) {
+  const { baseTheme, setBaseTheme } = useSystemBaseThemeContext();
+
+  const [densityValue, setDensityValue] = useControllableState<DensityToken>({
+    value: props.density,
+    defaultValue: props.defaultDensity ?? DEFAULT_DENSITY,
+    onChange: props.onDensityChange,
+  });
+
+  // Read-path contract: resolvedTheme is derived from baseTheme + current density.
+  const resolvedTheme = React.useMemo(() => applyDensity(baseTheme, densityValue), [baseTheme, densityValue]);
+
+  const setDensity = React.useCallback(
+    (nextDensity: DensityToken) => {
+      setDensityValue(nextDensity);
+    },
+    [setDensityValue],
+  );
+
+  const densityContextValue = React.useMemo<DensityContextValue>(
+    () => ({
+      density: densityValue,
+      setDensity,
+    }),
+    [densityValue, setDensity],
+  );
+
+  const systemThemeContextValue = React.useMemo<SystemThemeContextValue>(
+    () => ({
+      theme: resolvedTheme,
+      baseTheme,
+      density: densityValue,
+      setBaseTheme,
+      setDensity,
+    }),
+    [baseTheme, densityValue, resolvedTheme, setBaseTheme, setDensity],
+  );
+
+  return (
+    <DensityContextProvider value={densityContextValue}>
+      <SystemThemeContextProvider value={systemThemeContextValue}>
+        <ThemeProvider theme={resolvedTheme}>{props.children}</ThemeProvider>
+      </SystemThemeContextProvider>
+    </DensityContextProvider>
+  );
+}
+
+export function useDensity() {
+  return useDensityContext();
+}

package/src/density/density.ts

@@ -0,0 +1,102 @@
+import type { Theme } from "@lattice-ui/style";
+import type { DensityToken } from "./types";
+
+type DensityScale = {
+  space: number;
+  radius: number;
+  typography: number;
+};
+
+const DENSITY_SCALES: Record<DensityToken, DensityScale> = {
+  compact: {
+    space: 0.85,
+    radius: 0.9,
+    typography: 0.92,
+  },
+  comfortable: {
+    space: 1,
+    radius: 1,
+    typography: 1,
+  },
+  spacious: {
+    space: 1.15,
+    radius: 1.1,
+    typography: 1.08,
+  },
+};
+
+function scaleNonNegative(value: number, factor: number) {
+  return math.max(0, math.round(value * factor));
+}
+
+function scaleTextSize(value: number, factor: number) {
+  return math.max(10, math.round(value * factor));
+}
+
+function scaleSpace(theme: Theme, factor: number): Theme["space"] {
+  return {
+    0: scaleNonNegative(theme.space[0], factor),
+    2: scaleNonNegative(theme.space[2], factor),
+    4: scaleNonNegative(theme.space[4], factor),
+    6: scaleNonNegative(theme.space[6], factor),
+    8: scaleNonNegative(theme.space[8], factor),
+    10: scaleNonNegative(theme.space[10], factor),
+    12: scaleNonNegative(theme.space[12], factor),
+    14: scaleNonNegative(theme.space[14], factor),
+    16: scaleNonNegative(theme.space[16], factor),
+    20: scaleNonNegative(theme.space[20], factor),
+    24: scaleNonNegative(theme.space[24], factor),
+    32: scaleNonNegative(theme.space[32], factor),
+  };
+}
+
+function scaleRadius(theme: Theme, factor: number): Theme["radius"] {
+  return {
+    none: scaleNonNegative(theme.radius.none, factor),
+    sm: scaleNonNegative(theme.radius.sm, factor),
+    md: scaleNonNegative(theme.radius.md, factor),
+    lg: scaleNonNegative(theme.radius.lg, factor),
+    xl: scaleNonNegative(theme.radius.xl, factor),
+    full: scaleNonNegative(theme.radius.full, factor),
+  };
+}
+
+function scaleTypography(theme: Theme, factor: number): Theme["typography"] {
+  return {
+    labelSm: {
+      font: theme.typography.labelSm.font,
+      textSize: scaleTextSize(theme.typography.labelSm.textSize, factor),
+    },
+    bodyMd: {
+      font: theme.typography.bodyMd.font,
+      textSize: scaleTextSize(theme.typography.bodyMd.textSize, factor),
+    },
+    titleMd: {
+      font: theme.typography.titleMd.font,
+      textSize: scaleTextSize(theme.typography.titleMd.textSize, factor),
+    },
+  };
+}
+
+/**
+ * M1 limitation: density is a pure theme transformer.
+ * It does not create layout or child instances.
+ */
+export function applyDensity(theme: Theme, token: DensityToken): Theme {
+  const scale = DENSITY_SCALES[token];
+
+  return {
+    colors: { ...theme.colors },
+    space: scaleSpace(theme, scale.space),
+    radius: scaleRadius(theme, scale.radius),
+    typography: scaleTypography(theme, scale.typography),
+  };
+}
+
+/**
+ * M1 limitation: this helper only returns a theme transformer.
+ * It does not modify instance graphs or perform runtime layout composition.
+ */
+export function density(token: DensityToken) {
+  return (theme: Theme) => applyDensity(theme, token);
+}

package/src/density/types.ts

@@ -0,0 +1,15 @@
+import type React from "@rbxts/react";
+
+export type DensityToken = "compact" | "comfortable" | "spacious";
+
+export type DensityProviderProps = {
+  density?: DensityToken;
+  defaultDensity?: DensityToken;
+  onDensityChange?: (next: DensityToken) => void;
+  children?: React.ReactNode;
+};
+
+export type DensityContextValue = {
+  density: DensityToken;
+  setDensity: (next: DensityToken) => void;
+};

package/src/index.ts

@@ -0,0 +1,22 @@
+export { DensityProvider, useDensity } from "./density/DensityProvider";
+export { applyDensity, density } from "./density/density";
+export type { DensityContextValue, DensityProviderProps, DensityToken } from "./density/types";
+export { Row } from "./layout/Row";
+export { Stack } from "./layout/Stack";
+export type {
+  LayoutDirection,
+  RowProps,
+  SpaceToken,
+  SpaceValue,
+  StackAlign,
+  StackAutoSize,
+  StackJustify,
+  StackPadding,
+  StackProps,
+} from "./layout/types";
+export type { SurfaceToken } from "./surface/surface";
+export { surface } from "./surface/surface";
+export type { SurfaceProps } from "./surface/surfacePrimitive";
+export { Surface } from "./surface/surfacePrimitive";
+export { SystemProvider, useSystemTheme } from "./system/SystemProvider";
+export type { SystemProviderProps, SystemThemeContextValue } from "./system/types";

package/src/layout/Row.tsx

@@ -0,0 +1,7 @@
+import { React } from "@lattice-ui/core";
+import { Stack } from "./Stack";
+import type { RowProps } from "./types";
+
+export function Row(props: RowProps) {
+  return <Stack {...props} direction="horizontal" />;
+}

package/src/layout/Stack.tsx

@@ -0,0 +1,133 @@
+import { React } from "@lattice-ui/core";
+import { mergeGuiProps, resolveSx, useTheme } from "@lattice-ui/style";
+import { resolvePadding, resolveSpace } from "./space";
+import type { LayoutDirection, StackAlign, StackAutoSize, StackJustify, StackProps } from "./types";
+
+type StyleProps = React.Attributes & Record<string, unknown>;
+
+function toHorizontalAlignment(value: StackAlign | StackJustify) {
+  switch (value) {
+    case "center":
+      return Enum.HorizontalAlignment.Center;
+    case "end":
+      return Enum.HorizontalAlignment.Right;
+    case "start":
+    default:
+      return Enum.HorizontalAlignment.Left;
+  }
+}
+
+function toVerticalAlignment(value: StackAlign | StackJustify) {
+  switch (value) {
+    case "center":
+      return Enum.VerticalAlignment.Center;
+    case "end":
+      return Enum.VerticalAlignment.Bottom;
+    case "start":
+    default:
+      return Enum.VerticalAlignment.Top;
+  }
+}
+
+function toAutomaticSize(autoSize: StackAutoSize | undefined, direction: LayoutDirection) {
+  if (autoSize === undefined || autoSize === false) {
+    return Enum.AutomaticSize.None;
+  }
+
+  if (autoSize === true) {
+    return direction === "vertical" ? Enum.AutomaticSize.Y : Enum.AutomaticSize.X;
+  }
+
+  switch (autoSize) {
+    case "x":
+      return Enum.AutomaticSize.X;
+    case "y":
+      return Enum.AutomaticSize.Y;
+    case "xy":
+      return Enum.AutomaticSize.XY;
+    default:
+      return Enum.AutomaticSize.None;
+  }
+}
+
+export function Stack(props: StackProps) {
+  const direction = props.direction ?? "vertical";
+  const gap = props.gap ?? 0;
+  const align = props.align ?? "start";
+  const justify = props.justify ?? "start";
+  const autoSize = props.autoSize;
+  const sx = props.sx;
+  const children = props.children;
+  const asChild = (props as { asChild?: unknown }).asChild;
+
+  if (asChild !== undefined) {
+    error("[Stack] `asChild` is not supported in M3.");
+  }
+
+  const restProps: StyleProps = {};
+  for (const [rawKey, value] of pairs(props as Record<string, unknown>)) {
+    if (!typeIs(rawKey, "string")) {
+      continue;
+    }
+
+    if (
+      rawKey === "direction" ||
+      rawKey === "gap" ||
+      rawKey === "align" ||
+      rawKey === "justify" ||
+      rawKey === "autoSize" ||
+      rawKey === "sx" ||
+      rawKey === "asChild" ||
+      rawKey === "padding" ||
+      rawKey === "paddingX" ||
+      rawKey === "paddingY" ||
+      rawKey === "paddingTop" ||
+      rawKey === "paddingRight" ||
+      rawKey === "paddingBottom" ||
+      rawKey === "paddingLeft" ||
+      rawKey === "children"
+    ) {
+      continue;
+    }
+
+    restProps[rawKey] = value;
+  }
+
+  const { theme } = useTheme();
+  const sxProps = resolveSx(sx, theme);
+  const baseProps: Partial<StyleProps> = {
+    BackgroundTransparency: 1,
+    BorderSizePixel: 0,
+    AutomaticSize: toAutomaticSize(autoSize, direction),
+  };
+  const mergedProps = mergeGuiProps(baseProps, sxProps, restProps);
+
+  const resolvedGap = resolveSpace(theme, gap);
+  const padding = resolvePadding(theme, props);
+  const hasPadding = padding.top > 0 || padding.right > 0 || padding.bottom > 0 || padding.left > 0;
+
+  const vertical = direction === "vertical";
+  const horizontalAlignment = vertical ? toHorizontalAlignment(align) : toHorizontalAlignment(justify);
+  const verticalAlignment = vertical ? toVerticalAlignment(justify) : toVerticalAlignment(align);
+
+  return (
+    <frame {...(mergedProps as Record<string, unknown>)}>
+      <uilistlayout
+        FillDirection={vertical ? Enum.FillDirection.Vertical : Enum.FillDirection.Horizontal}
+        HorizontalAlignment={horizontalAlignment}
+        Padding={new UDim(0, resolvedGap)}
+        SortOrder={Enum.SortOrder.LayoutOrder}
+        VerticalAlignment={verticalAlignment}
+      />
+      {hasPadding ? (
+        <uipadding
+          PaddingBottom={new UDim(0, padding.bottom)}
+          PaddingLeft={new UDim(0, padding.left)}
+          PaddingRight={new UDim(0, padding.right)}
+          PaddingTop={new UDim(0, padding.top)}
+        />
+      ) : undefined}
+      {children}
+    </frame>
+  );
+}

package/src/layout/space.ts

@@ -0,0 +1,101 @@
+import type { Theme } from "@lattice-ui/style";
+import type { SpaceValue, StackPadding } from "./types";
+
+type ResolvedPadding = {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+};
+
+function spaceTokenValue(theme: Theme, value: number) {
+  switch (value) {
+    case 0:
+      return theme.space[0];
+    case 2:
+      return theme.space[2];
+    case 4:
+      return theme.space[4];
+    case 6:
+      return theme.space[6];
+    case 8:
+      return theme.space[8];
+    case 10:
+      return theme.space[10];
+    case 12:
+      return theme.space[12];
+    case 14:
+      return theme.space[14];
+    case 16:
+      return theme.space[16];
+    case 20:
+      return theme.space[20];
+    case 24:
+      return theme.space[24];
+    case 32:
+      return theme.space[32];
+    default:
+      return undefined;
+  }
+}
+
+function clampSpace(value: number) {
+  return math.max(0, value);
+}
+
+export function resolveSpace(theme: Theme, value?: SpaceValue) {
+  if (value === undefined) {
+    return 0;
+  }
+
+  const tokenValue = spaceTokenValue(theme, value);
+  if (tokenValue !== undefined) {
+    return clampSpace(tokenValue);
+  }
+
+  return clampSpace(value);
+}
+
+export function resolvePadding(theme: Theme, value: StackPadding): ResolvedPadding {
+  const base = resolveSpace(theme, value.padding);
+
+  let top = base;
+  let right = base;
+  let bottom = base;
+  let left = base;
+
+  if (value.paddingX !== undefined) {
+    const axis = resolveSpace(theme, value.paddingX);
+    left = axis;
+    right = axis;
+  }
+
+  if (value.paddingY !== undefined) {
+    const axis = resolveSpace(theme, value.paddingY);
+    top = axis;
+    bottom = axis;
+  }
+
+  if (value.paddingTop !== undefined) {
+    top = resolveSpace(theme, value.paddingTop);
+  }
+
+  if (value.paddingRight !== undefined) {
+    right = resolveSpace(theme, value.paddingRight);
+  }
+
+  if (value.paddingBottom !== undefined) {
+    bottom = resolveSpace(theme, value.paddingBottom);
+  }
+
+  if (value.paddingLeft !== undefined) {
+    left = resolveSpace(theme, value.paddingLeft);
+  }
+
+  return {
+    top,
+    right,
+    bottom,
+    left,
+  };
+}

package/src/layout/types.ts

@@ -0,0 +1,34 @@
+import type { Sx, Theme } from "@lattice-ui/style";
+import type React from "@rbxts/react";
+
+export type LayoutDirection = "vertical" | "horizontal";
+export type StackAlign = "start" | "center" | "end";
+export type StackJustify = "start" | "center" | "end";
+export type StackAutoSize = boolean | "x" | "y" | "xy";
+export type SpaceToken = keyof Theme["space"];
+export type SpaceValue = SpaceToken | number;
+
+export type StackPadding = {
+  padding?: SpaceValue;
+  paddingX?: SpaceValue;
+  paddingY?: SpaceValue;
+  paddingTop?: SpaceValue;
+  paddingRight?: SpaceValue;
+  paddingBottom?: SpaceValue;
+  paddingLeft?: SpaceValue;
+};
+
+type StyleProps = React.Attributes & Record<string, unknown>;
+
+export type StackProps = {
+  direction?: LayoutDirection;
+  gap?: SpaceValue;
+  align?: StackAlign;
+  justify?: StackJustify;
+  autoSize?: StackAutoSize;
+  sx?: Sx<StyleProps>;
+  children?: React.ReactNode;
+} & StackPadding &
+  StyleProps;
+
+export type RowProps = Omit<StackProps, "direction">;

package/src/surface/surface.ts

@@ -0,0 +1,45 @@
+import type { Sx } from "@lattice-ui/style";
+
+type GuiPropRecord = Record<string, unknown>;
+
+export type SurfaceToken = "surface" | "elevated" | "sunken" | "overlay";
+
+function asSxProps<Props extends GuiPropRecord>(value: GuiPropRecord): Partial<Props> {
+  return value as unknown as Partial<Props>;
+}
+
+/**
+ * Props-only surface helper.
+ * Use this when you only want host props (including host border props).
+ * It does not create child instances like UICorner/UIStroke/shadow nodes.
+ */
+export function surface<Props extends GuiPropRecord>(token: SurfaceToken): Sx<Props> {
+  return (theme) => {
+    switch (token) {
+      case "surface":
+        return asSxProps<Props>({
+          BackgroundColor3: theme.colors.surface,
+          BorderColor3: theme.colors.border,
+          BorderSizePixel: 1,
+        });
+      case "elevated":
+        return asSxProps<Props>({
+          BackgroundColor3: theme.colors.surfaceElevated,
+          BorderColor3: theme.colors.border,
+          BorderSizePixel: 1,
+        });
+      case "sunken":
+        return asSxProps<Props>({
+          BackgroundColor3: theme.colors.background,
+          BorderColor3: theme.colors.border,
+          BorderSizePixel: 1,
+        });
+      case "overlay":
+        return asSxProps<Props>({
+          BackgroundColor3: theme.colors.overlay,
+          BackgroundTransparency: 0.35,
+          BorderSizePixel: 0,
+        });
+    }
+  };
+}