@rbxts/uiblox 0.2.0-alpha.0 → 0.2.0-alpha.10

package/README.md

@@ -2,35 +2,13 @@
 
 # uiblox-rbxts
 
-> This package is a work in progress.
-
 UI library and theming for roblox-ts projects.
 
-## Background
-
-Roblox has their own internal design system, coined "uiblox-web", that it uses for its new
-web-facing products. This system offers reusable components, implemented in
-React Typescript, that are derived from material UI (MUI). As well, it offers a
-common theme/pallete for consistent UI/UX.
-
-Anyone is able to view their design system as
-[UIBlox-Web](https://uiblox.roblox.com). You can see that they leverage
-[Storybook](https://storybook.js.org), a UI component explorer for frontend
-developers, to render component previews.
-
-Design systems all help engineers cut down on implementation time and ensure
-consitent UX across products.
-
 ## Overview
 
-So what is uiblox-rbxts? Simply put, its my stab at a design system that mimics
-uiblox-web for games written using roblox-ts.
+Uiblox is a roblox-ts UI kit: semantic themes, `makeStyles` / `createStyles`, and typed React components for Studio and games. Public APIs aim for familiar Material UI–style capability (props and behavior), implemented independently for Roblox Instances, input modes, and performance.
 
-UIBlox-rbxts aims to provide extensible components that can be reusable by
-anyone who installs this npm package. It also offers a theme and styling system
-that aids UI/UX consistentency.
-
-How does it do this? Well, there are two main exports from this package:
+Main exports from `@rbxts/uiblox`:
 
 -   @rbxts/uiblox -> theme
     -   An extensible Theme type + default Dark (default) and Light themes
@@ -46,9 +24,47 @@ How does it do this? Well, there are two main exports from this package:
 
 ### Installation
 
-Install the package to get started.
+```
+npm install @rbxts/uiblox
+```
+
+## Quickstart
+
+1. Wrap your app (or a subtree) in `ThemeProvider` with `DarkTheme` or `LightTheme`.
+2. Build styles with `makeStyles` / `createStyles` (or `componentStyles`) and spread them onto Instances.
+3. For hover/press/focus/disabled (and list `_first` / `_last`), put `_hover`-style keys on the style table and call `resolveStyle(style, state)` before spreading.
+4. Use packaged components from `@rbxts/uiblox` (`Button`, `Input`, `Select`, …).
+5. Preview components in [Storyblox](https://github.com/bjlarouche/storyblox) with `*.stories` modules.
+
+Token reference (spacing, density, typography, shape, palette, `resolveStyle`): [docs/STYLING.md](docs/STYLING.md).
+
+```tsx
+import React from "@rbxts/react";
+import { Button, DarkTheme, ThemeProvider } from "@rbxts/uiblox";
+
+export function App() {
+	return (
+		<ThemeProvider theme={DarkTheme}>
+			<Button text="Continue" onLeftClick={() => {}} />
+		</ThemeProvider>
+	);
+}
+```
+
+## Parity checklist
+
+Capability parity, not pixel parity. For each public component, expect:
+
+- [ ] Typed controlled props where interaction needs state
+- [ ] Theme tokens (light/dark) via `ThemeProvider`
+- [ ] Style slots / variants through the styling helpers
+- [ ] Disabled / loading / error when the control type warrants it
+- [ ] Mouse, touch, and gamepad-friendly activation where interactive
+- [ ] Cleanup and focused unit checks in-repo
+- [ ] `stateMatrix` rows for visual capture planning
+- [ ] A Storyblox story (dev fixtures OK)
 
-`npm install @rbxts/uiblox`
+Skipped on purpose: browser-only addons (MDX, iframes, hosted visual-review clouds).
 
 ## Example
 
@@ -253,14 +269,15 @@ keeps the spinner still.
 
 `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.
+`focus`). Rows are built in small helper functions and concatenated so the
+compiled Luau chunk stays under the 200-local register limit. `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
 

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

@@ -1,6 +1,8 @@
-import { IconSizes } from "../interfaces/index";
-export declare const SPACING_BASE = 12;
+import { IconSizes } from "../interfaces/iconSizes/index";
+export declare const SPACING_BASE = 8;
 export declare const PADDING_BASE = 4;
 export declare const BORDER_RADIUS = 4;
+/** UICorner scale for pill/capsule controls (1 = fully round). */
+export declare const PILL_SCALE = 1;
 export declare const CONTENT_WIDTH = 1024;
 export declare const ICON_SIZES: IconSizes;

package/out/theme/constants/NumberConstants.luau

@@ -1,18 +1,20 @@
 -- Compiled with roblox-ts v3.0.0
-local SPACING_BASE = 12
+local SPACING_BASE = 8
 local PADDING_BASE = 4
--- align with UIBlox design
 local BORDER_RADIUS = 4
+--* UICorner scale for pill/capsule controls (1 = fully round). 
+local PILL_SCALE = 1
 local CONTENT_WIDTH = 1024
 local ICON_SIZES = {
 	small = 16,
-	medium = 36,
-	large = 48,
+	medium = 24,
+	large = 32,
 }
 return {
 	SPACING_BASE = SPACING_BASE,
 	PADDING_BASE = PADDING_BASE,
 	BORDER_RADIUS = BORDER_RADIUS,
+	PILL_SCALE = PILL_SCALE,
 	CONTENT_WIDTH = CONTENT_WIDTH,
 	ICON_SIZES = ICON_SIZES,
 }

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

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

package/out/theme/hooks/useTheme.d.ts

@@ -1,4 +1,4 @@
-import { Theme } from "../interfaces/index";
+import { Theme } from "../interfaces/theme/index";
 declare const useTheme: () => {
     theme: Theme;
     setTheme: (theme: Theme) => void;

package/out/theme/interfaces/palette/colorTokens/ColorTokens.d.ts

@@ -1,4 +1,4 @@
-import { Tokens } from "../../../index";
+import { Tokens } from "../../tokens/index";
 export type ColorTokens = {
     [key in Tokens]: Color3;
 };

package/out/theme/interfaces/spacing/Shape.d.ts

@@ -1,3 +1,6 @@
 export default interface Shape {
+    /** Pixel radius for squared controls (Button, Input, Paper). */
     borderRadius: number;
+    /** UICorner scale for capsules (Switch, Chip). Use `new UDim(pillScale, 0)`. */
+    pillScale: number;
 }

package/out/theme/interfaces/typography/FontSizes.d.ts

@@ -1,3 +1,3 @@
 import { FontSizeOptions } from "./FontSizeOptions";
-export declare const baseFontSize = 16;
+export declare const baseFontSize: number;
 export declare const allFontSizes: FontSizeOptions;

package/out/theme/interfaces/typography/FontSizes.luau

@@ -1,13 +1,20 @@
 -- Compiled with roblox-ts v3.0.0
-local baseFontSize = 16
+local TS = _G[script]
+local allTypographyVariants = TS.import(script, script.Parent, "Variants").allTypographyVariants
+local baseFontSize = allTypographyVariants.body.size
 local allFontSizes = {
-	h1 = baseFontSize * 2,
-	h2 = baseFontSize * 1.5,
-	h3 = baseFontSize * 1.25,
-	body = baseFontSize,
-	caption = baseFontSize * 0.75,
-	overline = baseFontSize * 0.625,
-	button = baseFontSize * 0.875,
+	h1 = allTypographyVariants.h1.size,
+	h2 = allTypographyVariants.h2.size,
+	h3 = allTypographyVariants.h3.size,
+	h4 = allTypographyVariants.h4.size,
+	h5 = allTypographyVariants.h5.size,
+	h6 = allTypographyVariants.h6.size,
+	subtitle1 = allTypographyVariants.subtitle1.size,
+	subtitle2 = allTypographyVariants.subtitle2.size,
+	body = allTypographyVariants.body.size,
+	caption = allTypographyVariants.caption.size,
+	overline = allTypographyVariants.overline.size,
+	button = allTypographyVariants.button.size,
 }
 return {
 	baseFontSize = baseFontSize,

package/out/theme/interfaces/typography/ThemeTypography.d.ts

@@ -1,7 +1,10 @@
 import { FontFamilyOptions } from "./FontFamilyOptions";
 import { FontSizeOptions } from "./FontSizeOptions";
+import { FontSizeVariant } from "./FontSizeOptions";
+import { TypographyVariantSpec } from "./Variants";
 interface ThemeTypography {
     fontSizes: FontSizeOptions;
     fontFamilies: FontFamilyOptions;
+    variants: Record<FontSizeVariant, TypographyVariantSpec>;
 }
 export default ThemeTypography;

package/out/theme/interfaces/typography/Variants.d.ts

@@ -1,18 +1,17 @@
-import { Tokens } from "../tokens/Tokens";
-export type TypographyTokens = {
-    [key in Tokens]: string;
-};
-export interface TypographyWeights {
+import { FontFamilyVariant } from "./FontFamilyOptions";
+import { FontSizeVariant } from "./FontSizeOptions";
+export interface TypographyVariantSpec {
+    size: number;
+    family: FontFamilyVariant;
+    /** Approx CSS weight; Roblox TextLabel uses `family` / FontFace */
+    weight: number;
+}
+export type TypographyVariants = FontSizeVariant;
+/** Size + family + weight per typography variant. */
+export declare const allTypographyVariants: Record<FontSizeVariant, TypographyVariantSpec>;
+/** @deprecated prefer allTypographyVariants[*].weight */
+export declare const TypographyWeights: {
     title: number;
     heading: number;
     body: number;
-    xl?: number;
-    lg?: number;
-    md?: number;
-    sm?: number;
-    xs?: number;
-    default?: number;
-}
-export type TypographyVariants = keyof TypographyWeights;
-export declare const TypographyWeights: TypographyWeights;
-export declare const TypographyTokens: TypographyTokens;
+};

package/out/theme/interfaces/typography/Variants.luau

@@ -1,24 +1,74 @@
 -- Compiled with roblox-ts v3.0.0
-local TypographyWeights = {
-	title = 800,
-	heading = 500,
-	body = 300,
+--* Size + family + weight per typography variant. 
+local allTypographyVariants = {
+	h1 = {
+		size = 28,
+		family = "bold",
+		weight = 700,
+	},
+	h2 = {
+		size = 22,
+		family = "bold",
+		weight = 700,
+	},
+	h3 = {
+		size = 18,
+		family = "semibold",
+		weight = 600,
+	},
+	h4 = {
+		size = 16,
+		family = "semibold",
+		weight = 600,
+	},
+	h5 = {
+		size = 14,
+		family = "semibold",
+		weight = 600,
+	},
+	h6 = {
+		size = 14,
+		family = "semibold",
+		weight = 600,
+	},
+	subtitle1 = {
+		size = 16,
+		family = "default",
+		weight = 400,
+	},
+	subtitle2 = {
+		size = 14,
+		family = "semibold",
+		weight = 600,
+	},
+	body = {
+		size = 14,
+		family = "default",
+		weight = 400,
+	},
+	button = {
+		size = 13,
+		family = "semibold",
+		weight = 600,
+	},
+	caption = {
+		size = 12,
+		family = "default",
+		weight = 400,
+	},
+	overline = {
+		size = 10,
+		family = "default",
+		weight = 400,
+	},
 }
-local TypographyTokens = {
-	[120] = "64px",
-	[110] = "48px",
-	[100] = "40px",
-	[90] = "32px",
-	[80] = "28px",
-	[70] = "24px",
-	[60] = "20px",
-	[50] = "18px",
-	[40] = "16px",
-	[30] = "14px",
-	[20] = "12px",
-	[10] = "10px",
+--* @deprecated prefer allTypographyVariants[*].weight 
+local TypographyWeights = {
+	title = 700,
+	heading = 600,
+	body = 400,
 }
 return {
-	TypographyTokens = TypographyTokens,
+	allTypographyVariants = allTypographyVariants,
 	TypographyWeights = TypographyWeights,
 }

package/out/theme/styles/utilities/index.d.ts

@@ -4,4 +4,4 @@ export { default as classNames, cx } from "./classNames";
 export { applyVariants, CompoundVariant } from "./variants";
 export { default as componentStyles } from "./componentStyles";
 export { resolveResponsive, Responsive } from "../../../hooks/breakpoints";
-export { interactionStyle, InteractionSlots, InteractionState } from "./interaction";
+export { interactionStyle, InteractionSlots, InteractionState, resolveStyle, StyleSelectorKey, StyleState, StyleWithSelectors, } from "./resolveStyle";

package/out/theme/styles/utilities/init.luau

@@ -9,5 +9,7 @@ exports.cx = _classNames.cx
 exports.applyVariants = TS.import(script, script, "variants").applyVariants
 exports.componentStyles = TS.import(script, script, "componentStyles").default
 exports.resolveResponsive = TS.import(script, script.Parent.Parent.Parent, "hooks", "breakpoints").resolveResponsive
-exports.interactionStyle = TS.import(script, script, "interaction").interactionStyle
+local _resolveStyle = TS.import(script, script, "resolveStyle")
+exports.interactionStyle = _resolveStyle.interactionStyle
+exports.resolveStyle = _resolveStyle.resolveStyle
 return exports

package/out/theme/styles/utilities/resolveStyle.d.ts

@@ -0,0 +1,32 @@
+export type StyleSelectorKey = "_hover" | "_pressed" | "_focus" | "_disabled" | "_selected" | "_checked" | "_first" | "_last";
+export interface StyleState {
+    hover?: boolean;
+    pressed?: boolean;
+    focused?: boolean;
+    disabled?: boolean;
+    selected?: boolean;
+    checked?: boolean;
+    first?: boolean;
+    last?: boolean;
+}
+export type StyleWithSelectors<T extends object = object> = T & {
+    _hover?: Partial<T>;
+    _pressed?: Partial<T>;
+    _focus?: Partial<T>;
+    _disabled?: Partial<T>;
+    _selected?: Partial<T>;
+    _checked?: Partial<T>;
+    _first?: Partial<T>;
+    _last?: Partial<T>;
+};
+export interface InteractionSlots<T extends object = object> {
+    hover?: T;
+    pressed?: T;
+    focused?: T;
+    disabled?: T;
+}
+export type InteractionState = Pick<StyleState, "hover" | "pressed" | "focused" | "disabled">;
+/** Peels `_hover` / `_pressed` / `_focus` / … and merges active ones onto the Instance props. */
+export declare function resolveStyle<T extends object>(style: StyleWithSelectors<T>, state?: StyleState): T;
+/** Prefer `resolveStyle` with `_hover` keys. Kept for existing call sites. */
+export declare function interactionStyle<T extends object>(base: T, slots: InteractionSlots<T>, state: InteractionState): T;

package/out/theme/styles/utilities/resolveStyle.luau

@@ -0,0 +1,66 @@
+-- Compiled with roblox-ts v3.0.0
+--* Order matters: later keys win. Structural first, then interaction; `_disabled` last. 
+local SELECTORS = { { "_first", "first" }, { "_last", "last" }, { "_selected", "selected" }, { "_checked", "checked" }, { "_hover", "hover" }, { "_pressed", "pressed" }, { "_focus", "focused" }, { "_disabled", "disabled" } }
+local SELECTOR_FLAGS = {
+	_hover = true,
+	_pressed = true,
+	_focus = true,
+	_selected = true,
+	_checked = true,
+	_first = true,
+	_last = true,
+	_disabled = true,
+}
+--* Peels `_hover` / `_pressed` / `_focus` / … and merges active ones onto the Instance props. 
+local function resolveStyle(style, state)
+	if state == nil then
+		state = {}
+	end
+	local base = {}
+	local patches = {}
+	for key, value in pairs(style) do
+		local name = key
+		if SELECTOR_FLAGS[name] == true then
+			patches[name] = value
+		else
+			base[name] = value
+		end
+	end
+	local painted = base
+	for _, _binding in SELECTORS do
+		local selector = _binding[1]
+		local flag = _binding[2]
+		local patch = patches[selector]
+		if state[flag] == true and patch ~= nil then
+			local _object = {}
+			if painted then
+				for _k, _v in painted do
+					_object[_k] = _v
+				end
+			end
+			for _k, _v in patch do
+				_object[_k] = _v
+			end
+			painted = _object
+		end
+	end
+	return painted
+end
+--* Prefer `resolveStyle` with `_hover` keys. Kept for existing call sites. 
+local function interactionStyle(base, slots, state)
+	local _object = {}
+	if base then
+		for _k, _v in base do
+			_object[_k] = _v
+		end
+	end
+	_object._hover = slots.hover
+	_object._pressed = slots.pressed
+	_object._focus = slots.focused
+	_object._disabled = slots.disabled
+	return resolveStyle(_object, state)
+end
+return {
+	resolveStyle = resolveStyle,
+	interactionStyle = interactionStyle,
+}

package/out/theme/themes/DarkTheme.luau

@@ -6,9 +6,11 @@ local BORDER_RADIUS = _NumberConstants.BORDER_RADIUS
 local CONTENT_WIDTH = _NumberConstants.CONTENT_WIDTH
 local ICON_SIZES = _NumberConstants.ICON_SIZES
 local PADDING_BASE = _NumberConstants.PADDING_BASE
+local PILL_SCALE = _NumberConstants.PILL_SCALE
 local SPACING_BASE = _NumberConstants.SPACING_BASE
 local DEFAULT_BORDERS = TS.import(script, script.Parent.Parent, "constants", "ColorConstants").DEFAULT_BORDERS
 local allFontFamilies = TS.import(script, script.Parent.Parent, "interfaces", "typography", "FontFamilies").allFontFamilies
+local allTypographyVariants = TS.import(script, script.Parent.Parent, "interfaces", "typography", "Variants").allTypographyVariants
 local createDarkPalette = TS.import(script, script.Parent, "createPalette").createDarkPalette
 local DarkTheme = {
 	type = "Dark",
@@ -28,10 +30,12 @@ local DarkTheme = {
 	},
 	shape = {
 		borderRadius = BORDER_RADIUS,
+		pillScale = PILL_SCALE,
 	},
 	typography = {
 		fontSizes = allFontSizes,
 		fontFamilies = allFontFamilies,
+		variants = allTypographyVariants,
 	},
 	options = {
 		constants = {

package/out/theme/themes/LightTheme.luau

@@ -6,9 +6,11 @@ local BORDER_RADIUS = _NumberConstants.BORDER_RADIUS
 local CONTENT_WIDTH = _NumberConstants.CONTENT_WIDTH
 local ICON_SIZES = _NumberConstants.ICON_SIZES
 local PADDING_BASE = _NumberConstants.PADDING_BASE
+local PILL_SCALE = _NumberConstants.PILL_SCALE
 local SPACING_BASE = _NumberConstants.SPACING_BASE
 local DEFAULT_BORDERS = TS.import(script, script.Parent.Parent, "constants", "ColorConstants").DEFAULT_BORDERS
 local allFontFamilies = TS.import(script, script.Parent.Parent, "interfaces", "typography", "FontFamilies").allFontFamilies
+local allTypographyVariants = TS.import(script, script.Parent.Parent, "interfaces", "typography", "Variants").allTypographyVariants
 local createLightPalette = TS.import(script, script.Parent, "createPalette").createLightPalette
 local LightTheme = {
 	type = "Light",
@@ -28,10 +30,12 @@ local LightTheme = {
 	},
 	shape = {
 		borderRadius = BORDER_RADIUS,
+		pillScale = PILL_SCALE,
 	},
 	typography = {
 		fontSizes = allFontSizes,
 		fontFamilies = allFontFamilies,
+		variants = allTypographyVariants,
 	},
 	options = {
 		constants = {

package/out/theme/types/types.d.ts

@@ -1,5 +1,5 @@
 import React, { PropsWithChildren } from "@rbxts/react";
-import { WriteableStyle } from "../interfaces/index";
+import { WriteableStyle } from "../styles/index";
 export interface CommonProps<T extends Instance> extends PropsWithChildren {
     className?: WriteableStyle<T>;
     sx?: WriteableStyle<T>;

package/out/ui/packages/accordion/components/Accordion.d.ts

@@ -4,6 +4,7 @@ export interface AccordionProps {
     title: string;
     open?: boolean;
     defaultOpen?: boolean;
+    disabled?: boolean;
     onChange?: (open: boolean) => void;
     children?: React.ReactNode;
 }

package/out/ui/packages/accordion/components/Accordion.luau

@@ -10,6 +10,7 @@ local function Accordion(props)
 	local title = _binding.title
 	local controlled = _binding.open
 	local defaultOpen = _binding.defaultOpen
+	local disabled = _binding.disabled
 	local onChange = _binding.onChange
 	local children = _binding.children
 	local className = _binding.className
@@ -20,8 +21,12 @@ local function Accordion(props)
 	local open = accordionOpen(localOpen, controlled)
 	local styles = useAccordionStyles({
 		open = open,
+		disabled = disabled,
 	})
 	local toggle = function()
+		if disabled == true then
+			return nil
+		end
 		local nextOpen = not open
 		if controlled == nil then
 			setLocalOpen(nextOpen)

package/out/ui/packages/accordion/components/Accordion.styles.d.ts

@@ -1,4 +1,5 @@
 declare const useAccordionStyles: (props: {
     open?: boolean;
+    disabled?: boolean;
 }) => import("../../../../theme/index").ClassNameMap<string>;
 export default useAccordionStyles;

package/out/ui/packages/accordion/components/Accordion.styles.luau

@@ -8,6 +8,7 @@ local useAccordionStyles = componentStyles("Accordion", function(theme, _param)
 	if open == nil then
 		open = false
 	end
+	local disabled = _param.disabled
 	return createStyles({
 		root = {
 			AutomaticSize = Enum.AutomaticSize.Y,
@@ -27,8 +28,8 @@ local useAccordionStyles = componentStyles("Accordion", function(theme, _param)
 			BorderSizePixel = 0,
 			AutoButtonColor = false,
 			Text = "",
-			Active = true,
-			Selectable = true,
+			Active = disabled ~= true,
+			Selectable = disabled ~= true,
 		},
 		title = {
 			AutomaticSize = Enum.AutomaticSize.XY,
@@ -38,6 +39,7 @@ local useAccordionStyles = componentStyles("Accordion", function(theme, _param)
 			Font = theme.typography.fontFamilies.default,
 			TextSize = theme.typography.fontSizes.body,
 			TextColor3 = theme.palette.text.primary,
+			TextTransparency = if disabled == true then 0.5 else 0,
 			TextXAlignment = Enum.TextXAlignment.Left,
 		},
 		padding = {

package/out/ui/packages/alert/components/Alert.d.ts

@@ -0,0 +1,10 @@
+import { CustomizedProps } from "../../../../theme/index";
+import { AlertSeverity } from "./alertTone";
+export interface AlertProps {
+    severity?: AlertSeverity;
+    title?: string;
+    message: string;
+    onClose?: () => void;
+}
+declare function Alert(props: CustomizedProps<Frame, AlertProps>): JSX.Element;
+export default Alert;