{"id":"jerr3n/bloxwind","name":"bloxwind","scope":"jerr3n","platform":"roblox","description":"Tailwind-inspired utility classes for Roblox React","version":"0.0.1","latest":"0.0.1","versions":["0.0.1"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{"roblox/react":{"version":"^17.3.11","alias":"React"},"roblox/react-roblox":{"version":"^17.3.11","alias":"ReactRoblox"}},"integrity":"ef69e8da720e27900f4bf2bc44f522cd5dd52cd9a25a568609c2a61bf8af1a7b","likes":0,"downloads":0,"install":"forest install jerr3n/bloxwind","url":"https://forest.dev/p/roblox/jerr3n/bloxwind","files":"https://api.forest.dev/ai/package/roblox/jerr3n/bloxwind/files","readme":"# Bloxwind\n\nBloxwind supplies Tailwind-style utility classes for Roblox React. At run time, it converts each `className` string into Roblox properties and UI modifier children.\n\nBloxwind works with Luau and Rojo. It does not require a source transform.\n\nRead the [API reference](docs/api-reference.md) for all public types, fields, utilities, and behavior.\n\n```luau\nlocal Bloxwind = require(ReplicatedStorage.Packages.Bloxwind)\nlocal tw = Bloxwind.create(require(ReplicatedStorage.Shared.BloxwindConfig))\n\nreturn React.createElement(tw.Frame, {\n    className = \"w-full h-auto bg-slate-900 rounded-xl p-4 flex-row items-center gap-2\",\n})\n```\n\n## Install\n\n1. Add Bloxwind and the matching React packages to `wally.toml`.\n\n```toml\n[dependencies]\nBloxwind = \"jerren/bloxwind@0.1.0\"\nReact = \"roblox/react@17.3.11\"\nReactRoblox = \"roblox/react-roblox@17.3.11\"\n```\n\n2. Run `wally install`.\n3. Map the `Packages` directory into `ReplicatedStorage`.\n4. Require Bloxwind.\n5. Create one configured Bloxwind instance for the application.\n\n## Configuration\n\nA configuration ModuleScript defines the theme and the custom utilities. It can replace a complete theme scale or extend individual tokens.\n\n```luau\nreturn {\n    diagnostics = \"warn\", -- \"warn\", \"strict\", or \"silent\"\n    theme = {\n        extend = {\n            colors = {\n                brand = {\n                    [500] = Color3.fromHex(\"466EFF\"),\n                    [600] = Color3.fromHex(\"3255DC\"),\n                },\n            },\n            spacing = {\n                [\"18\"] = 72,\n            },\n        },\n    },\n    utilities = {\n        card = function(theme)\n            return {\n                properties = {\n                    BackgroundColor3 = theme.colors.slate[\"900\"],\n                },\n                decorators = {\n                    outline = {\n                        className = \"UIStroke\",\n                        properties = {\n                            Color = theme.colors.slate[\"700\"],\n                            Thickness = 1,\n                        },\n                    },\n                },\n            }\n        end,\n    },\n}\n```\n\nUse `theme.colors = {...}` to replace the bundled color scale. Use `theme.extend.colors = {...}` to add or replace individual color tokens.\n\nBloxwind checks custom utilities before it checks built-in utilities. Thus, a custom utility can replace a built-in utility that has the same name.\n\nVariant prefixes also accept custom utilities. For example, `hover:card` applies the custom `card` utility during the hover state.\n\nA decorator slot name identifies a modifier. Bloxwind assigns one standard slot to each modifier class. This action prevents duplicate modifier instances.\n\nBloxwind supports these custom modifiers:\n\n- `UIPadding`\n- `UIListLayout`\n- `UICorner`\n- `UIStroke`\n- `UISizeConstraint`\n- `UIAspectRatioConstraint`\n- `UIFlexItem`\n- `UIGradient`\n\nBy default, Bloxwind reports each invalid utility once and ignores it. Set `diagnostics = \"strict\"` to stop immediately after an error.\n\nSet `diagnostics = \"silent\"` to ignore invalid utilities without a report.\n\n## Components and states\n\nA configured Bloxwind instance contains these components:\n\n- `Frame`\n- `ScrollingFrame`\n- `CanvasGroup`\n- `TextLabel`\n- `TextButton`\n- `TextBox`\n- `ImageLabel`\n- `ImageButton`\n- `ViewportFrame`\n- `VideoFrame`\n\nUse `tw.styled(\"Frame\", \"rounded-lg p-4\")` to create a component with a fixed set of base utilities.\n\nBloxwind supports the `hover:`, `pressed:`, and `disabled:` state variants. It applies active utilities from left to right.\n\nThe `disabled` wrapper property makes a button non-interactable.\n\n```luau\nReact.createElement(tw.TextButton, {\n    className = \"bg-blue-500 hover:bg-blue-600 pressed:bg-blue-700 disabled:bg-slate-800\",\n    disabled = isUnavailable,\n    Text = \"Continue\",\n})\n```\n\nBloxwind runs its interaction listener before it runs the listener from the user. Explicit Roblox properties override utility properties because Bloxwind assigns them last.\n\n## Utility reference\n\n- Sizing utilities include `w-*`, `h-*`, `w-full`, `w-1/2`, `w-auto`, `min-w-*`, `max-h-*`, `aspect-square`, and `aspect-video`.\n- Spacing utilities include `p-*`, `px-*`, `py-*`, directional padding, `gap-*`, `gap-x-*`, and `gap-y-*`.\n- Layout utilities include `flex`, `flex-row`, `flex-col`, `flex-wrap`, `justify-*`, `items-*`, `grow`, `shrink`, and `flex-1`.\n- Color utilities include `bg-*`, `text-*`, `image-*`, `border-*`, and channel opacity utilities.\n- Typography utilities control text size, font family, font weight, alignment, wrapping, and truncation.\n- Appearance utilities control corners, borders, visibility, clipping, z-index, and `CanvasGroup` opacity.\n\nThe default spacing scale uses four-pixel increments. Each bundled color family contains shades `50` through `950`.\n\n## Roblox differences\n\nBloxwind does not emulate CSS. It maps utilities to Roblox types such as `UDim2`, `UIListLayout`, `UIPadding`, `UICorner`, and `UIStroke`.\n\nThe Roblox UI model does not have a browser box model. Bloxwind does not create wrapper instances to simulate margins.\n\nUse `opacity-*` only with `CanvasGroup`. For other instances, use `bg-opacity-*`, `text-opacity-*`, or `image-opacity-*`.\n\nVersion 0.1 does not include arbitrary bracket values, responsive variants, dark variants, animations, parser plugins, or a native `StyleSheet` backend.\n\nAdd a theme token or a named custom utility when a built-in utility is not sufficient.\n\n## Develop and test\n\n1. Install the dependencies.\n\n```bash\nwally install\n```\n\n2. Build the demonstration place.\n\n```bash\nrojo build -o bloxwind.rbxlx\n```\n\n3. Build the test place.\n\n```bash\nrojo build test.project.json -o bloxwind-tests.rbxlx\n```\n\n4. Open `bloxwind-tests.rbxlx` in Roblox Studio.\n5. Run the test place.\n\nTestEZ runs the test suite when the test place starts. The default project shows a Bloxwind demonstration.\n\n## Contributors\n\nSee [CONTRIBUTORS.md](CONTRIBUTORS.md) for project credits.\n","readmeTruncated":false}