{"id":"nightcycle/html-components","name":"html-components","scope":"nightcycle","platform":"roblox","description":"Strict React Luau HTML components with contextual CSS and native Roblox UI.","version":"0.1.1","latest":"0.1.1","versions":["0.1.0","0.1.1"],"license":"Apache-2.0","licenseRating":"safe","licenseCaveats":["Modified files must carry a notice of changes. If the package ships a NOTICE file, its attributions must be preserved."],"licenseVerified":true,"dependencies":{"jsdotlua/react":{"version":"^17.2.1","alias":"React"},"nightcycle/typed-instance-components":{"version":"^0.1.1","alias":"RobloxComponents"}},"integrity":"afd318706987962c6698a642fda5ea9d9b1a37fb30a31ff103300a6b49912c33","likes":0,"downloads":0,"install":"forest install nightcycle/html-components","url":"https://forest.dev/p/roblox/nightcycle/html-components","files":"https://api.forest.dev/ai/package/roblox/nightcycle/html-components/files","readme":"# HTML Components\n\n62 strictly typed React Luau components that map an explicit HTML/CSS subset to native Roblox UI. Includes contextual CSS, individual corners, native shadows, UI Labs stories, and a searchable development gallery.\n\nIncludes an XML-style fragment renderer with typed table input, plus an experimental whole-document HTML reader. The demo's **Documents** view previews imported structure using supported components and lists remaining gaps. See [the compatibility contract](docs/compatibility.md) and [document parsing workflow](docs/html-document.md) before translating web content.\n\n## Install\n\nThe repository is prepared for Wally release `0.1.0`; publication is a separate release step.\n\n```toml\n[dependencies]\nHTMLComponents = \"nightcycle/html-components@^0.1.0\"\nReact = \"jsdotlua/react@17.2.1\"\nReactRoblox = \"jsdotlua/react-roblox@17.2.1\"\n```\n\nThe runtime depends on `nightcycle/typed-instance-components@^0.1.1`. Import the public Wally header, not its private child modules. Run `wally-package-types` with your Rojo sourcemap to expose the exported type aliases.\n\n```luau\n--!strict\nlocal React = require(game.ReplicatedStorage.Packages.React)\nlocal HTML = require(game.ReplicatedStorage.Packages.HTMLComponents)\nlocal e = React.createElement\n\nreturn function()\n\treturn e(HTML.StyleProvider, {\n\t\tCSS = {\n\t\t\t[\".Card\"] = {\n\t\t\t\tPadding = 24, Gap = 12, BackgroundColor = \"#f1f4fb\",\n\t\t\t\tBorderTopLeftRadius = 20, BorderTopRightRadius = 6,\n\t\t\t\tBorderBottomRightRadius = 20, BorderBottomLeftRadius = 6,\n\t\t\t\tBoxShadow = \"0px 8px 20px #00000030\",\n\t\t\t},\n\t\t\t[\".Card > H2\"] = { Color = \"#315fe8\" },\n\t\t\t[\".Card Button:Hover\"] = { BackgroundColor = \"#5479ff\" },\n\t\t},\n\t}, {\n\t\tCard = e(HTML.Article, {\n\t\t\tClassName = \"Card\",\n\t\t\tSize = UDim2.fromOffset(460, 280),\n\t\t} :: HTML.ContainerProperties, {\n\t\t\tTitle = e(HTML.H2, { Text = \"Hello, Roblox\", LayoutOrder = 1 } :: HTML.TextProperties),\n\t\t\tBody = e(HTML.P, { Text = \"CSS follows the React tree.\", LayoutOrder = 2 } :: HTML.TextProperties),\n\t\t\tButton = e(HTML.Button, {\n\t\t\t\tText = \"Continue\", LayoutOrder = 3,\n\t\t\t\tOnActivated = function() print(\"Continue\") end,\n\t\t\t} :: HTML.ButtonProperties),\n\t\t}),\n\t})\nend\n```\n\n## Component conventions\n\nFollowing `open-shl`, components expose a `Properties` type, return a React element, and construct their host with the typed instance builders. Every component's properties are exported from the public Wally header as `ComponentNameProperties`: for example, `HTML.DivProperties`, `HTML.H2Properties`, `HTML.TextAreaProperties`, and `HTML.StyleProviderProperties`. The shared host-family properties remain available too. Consumers never need to index a Wally submodule for types.\n\n- Components and tag identifiers use PascalCase (`HTML.Div`, `HTML.Tags.Div`, `HTML.Tags.H1`, `HTML.TextArea`). `HTML.Tag` is the exported tag union. `HTML.Catalog` lists PascalCase tags, component names, and renderer kinds. Raw CSS selectors retain normal HTML syntax (`div`, `h1`) and normalize during parsing.\n- HTML-facing props are `Id`, `ClassName`, `CSS`, `Hidden`, `Text`, `Src`, `Href`, `Value`, and the control-specific props below. The fragment parser normalizes supported lowercase HTML attributes into this API.\n- `CSS` is a typed inline `HTML.Style` record. It is named separately from Roblox's native `Frame.Style`/`TextButton.Style` enum property.\n- Style fields and option values use PascalCase: `{ FontSize = 16, Display = \"Flex\", JustifyContent = \"SpaceBetween\" }`. Every string union has its own public type, including `HTML.Display`, `HTML.FontFamily`, `HTML.TextAlign`, `HTML.SelectorRelation`, and `HTML.RenderKind`. CSS text still uses `font-size: 16px; display: flex; justify-content: space-between`.\n- Native host properties, non-string React event/change keys, and native children are forwarded through `typed-instance-components`. Explicit native properties override CSS-derived values. `Hidden`/`display: none` and disabled controls remain enforced.\n- `Ref` reaches the actual root `GuiObject`. Use the capitalized prop; React's reserved `ref` is not forwarded by function components. Internal state listeners compose with incoming native listeners.\n- Pass text through `Text`, and UI descendants through `Children` or the third argument to `createElement`. The React boundary adapts its reserved lowercase key internally. Raw string children are unsupported by ReactRoblox. Use `LayoutOrder` for deterministic sibling flow.\n- Treat stylesheet and inline style tables as immutable. Replace them when changing styles.\n\n### Inline layout\n\n`Span`, `Strong`, `Em`, `Code`, and the other phrasing text tags now default to `Display = \"Inline\"`. Adjacent and nested text shares line boxes, collapses whitespace across component boundaries, and wraps at words. A component's `Text` precedes its children. `Br` ends the current line. Set `LayoutOrder` to preserve document order.\n\nUse `InlineBlock` when a text element needs its own width, height, padding, or size constraints:\n\n```luau\nlocal badgeStyle: HTML.Style = {\n\tDisplay = \"InlineBlock\", Width = 96, Height = 40,\n\tMinWidth = 80, MaxWidth = 120, Padding = 8,\n\tVerticalAlign = \"Middle\", BackgroundColor = \"#dbeafe\",\n}\nlocal badge: HTML.StrongProperties = { Text = \"Badge\", CSS = badgeStyle }\nlocal element = e(HTML.Strong, badge)\n```\n\nNormal inline text ignores box width/height and min/max dimensions inside a flow. Its root remains a `TextLabel`; wrapped fragments are native child labels, so nested components retain their identities and refs. `InlineBlock` remains an atomic box. `InlineFlex` combines an atomic outer box with the existing native flex layout.\n\n`LineHeight = 1.5` is a font-size multiplier; `LineHeight = \"24px\"` is an absolute line height. `WhiteSpace` accepts `Normal`, `Nowrap`, `Pre`, and `PreWrap`. Block margins support horizontal `\"Auto\"` centering, adjacent sibling collapse and final-child bottom collapse in auto-height blocks; complete CSS margin collapsing remains unfinished. Grid supports equal columns/spans, and flex supports measured intrinsic text, growth/shrinkage and baselines. Layout measurements are cached and geometry updates run outside React. See [the layout limits](docs/compatibility.md) and [the browser comparison](docs/visual-validation.md).\n\n### Markup and table content\n\n`HTML.Content` renders an ordered fragment into the surrounding HTML component. It adds no wrapper or selector ancestor. Both inputs use the same components and inline formatter:\n\n```luau\nlocal markup: HTML.ContentProperties = {\n\tSource = [[Read <strong class=\"Accent\">bold <em>and italic</em></strong>.<br/><u>Underlined <s>and struck</s></u>]],\n}\nlocal badge: HTML.ContentElement = {\n\tTag = \"Strong\", Text = \"Badge\", ClassName = \"Accent\",\n\tCSS = { Display = \"InlineBlock\", Width = 96, Height = 40, Padding = 8 },\n\tRef = React.createRef(),\n}\nlocal nodes: { HTML.ContentNode } = { \"A standalone \", badge, \" beside flowing text.\" }\nlocal content: HTML.ContentProperties = { Source = nodes }\nlocal paragraph: HTML.PProperties = { CSS = { Width = 320, LineHeight = \"24px\" } }\nlocal element = e(HTML.P, paragraph, { Content = e(HTML.Content, content) })\n-- Use markup instead of content above to render the XML-style string.\n```\n\nTable fields and tags use PascalCase; `CSS` stays uppercase. Use an explicitly typed `{ HTML.ContentNode }` variable for mixed text/element arrays. `Text` precedes `Children`. Strings in table input and ordinary component `Text` are literal text, never parsed markup. Table nodes may carry native `Ref`s; set `Display = \"InlineBlock\"` to retain independent dimensions and constraints. `OrderOffset` places a fragment after other siblings' `LayoutOrder` values.\n\nString input accepts properly nested tags, quoted `id`/`class`/`style` attributes, comments, CDATA, XML entities plus `&nbsp;`, and numeric character references. Use `<br/>`, close every paired tag, and escape literal `<`/`&`. Raw markup uses normal HTML/CSS spelling; parser output uses PascalCase. Supported tags are the text-formatting subset plus `P`, `Div`, and `Br`, listed in the compatibility contract. It does not accept arbitrary Roblox RichText tags such as `<font>` or `<stroke>`.\n\n`HTML.Markup.parse(text)` and `HTML.Markup.validate(nodes)` return `HTML.MarkupResult`: `Success`, `Nodes`, and `Diagnostics`. Failed input returns no nodes. `Content.OnDiagnostics` receives the diagnostics after a source change (an empty array on success); without it, failures warn. String diagnostics have a one-based byte offset, line and byte column; table diagnostics include a field `Path`. Unknown tags, attributes, styles, malformed input, and inline `!important` are diagnosed. External stylesheets still support `!important` through `StyleProvider.StyleSheet`.\n\nLimits are 64 nested elements, 10,000 nodes, and 1 MiB of markup input or table text/identifier content. No scripts, DTD/entity loading, resource fetching, or HTML5 recovery is performed. Replace source tables when editing them. Anonymous text inherits typography without matching `Span` selectors; nested decoration propagates through inline descendants and stops at `InlineBlock`/`InlineFlex` boundaries.\n\n`StyleProvider.CSS` accepts a selector map of type `HTML.StyleMap`. Tag names and pseudo states use PascalCase (`Button:Hover`, `Input:Focus`, `Button:Disabled`). Class names and IDs are case-sensitive identifiers that must match `ClassName` and `Id`. Nested providers append rules while retaining ancestry and inherited typography. They introduce no Roblox instance:\n\n```luau\nlocal css: HTML.StyleMap = {\n\t[\".Primary\"] = { FontSize = 16 },\n\tButton = { FontWeight = \"Bold\" },\n\t[\"Button:Hover\"] = { BackgroundColor = \"#315fe8\" },\n}\nlocal properties: HTML.StyleProviderProperties = { CSS = css }\nlocal element = e(HTML.StyleProvider, properties, children)\n```\n\nMap keys are sorted alphabetically: when two selectors have equal specificity, the alphabetically later key wins. Table insertion order and `ClassName` order do not affect the result. Use more specific selectors to express an override. Comma-separated selector groups are supported. Map declarations use the same PascalCase fields and option values as inline `CSS`; unsupported fields and selectors produce diagnostics.\n\n`HTML.CSS.fromMap(css)` compiles a map for the optional `StyleSheet` prop. For importing browser CSS, `HTML.CSS.parse(text)` remains available and preserves textual source order and `!important`; pass its returned table through `StyleSheet`. The `CSS` provider prop accepts a selector map, not a string.\n\nThe cascade is inherited typography → tag defaults → matching normal rules (specificity, then source order) → inline `CSS` → matching `!important` declarations. Native props are the final Roblox escape hatch. Unsupported CSS is omitted with diagnostics. `StyleProvider.OnDiagnostics` receives the complete `{ HTML.Diagnostic }` array when stylesheet inputs change, including an empty array when issues clear. Without a callback, the provider prints one summary with at most three short examples. `StyleSheet.Diagnostics` always retains every entry. The Documents demo displays the full list in its Diagnostics tab instead of printing it to Output.\n\nCSS text supports escaped class/ID names, comma-separated font fallback lists containing a supported generic family (`sans-serif`, `serif`, or `monospace`), and both comma and space/slash RGB colors, including percentages. Generic families map to the package's Roblox fonts; named web fonts are skipped. CSS variables, media queries, and unsupported selectors still produce diagnostics.\n\nStyle contexts hold stable subscription scopes. Stylesheet updates compare each element's resolved style field by field and schedule React updates only for changed results. Changing `.notice` leaves unrelated elements out of React rendering; inherited typography still reaches descendants that have not overridden it. Ancestor state and class changes still affect descendant selectors. A local background or padding change does not propagate to descendants.\n\nReplacing a stylesheet still runs style resolution through its subtree; rules are not yet indexed by class. These subscriptions prevent style-driven renders, not ordinary renders caused by an application's parent rebuilding children or changing props. Keep child elements stable or use `React.memo` where those parent renders matter. Continue replacing style tables instead of mutating them in place.\n\n## Controls and assets\n\n| Component | Props and behavior |\n| --- | --- |\n| `Button`, `A` | `OnActivated: () -> ()`, `Disabled`; links call `OnNavigate(Href)` when supplied. Navigation is application-owned. |\n| `Input`, `TextArea` | Text inputs. `Value` is controlled; `DefaultValue` initializes uncontrolled state. `OnInput(string)`, `OnCommit(string, enterPressed)`, `Placeholder`, `ReadOnly`, `Disabled`. `Text` is an initial-value alias; use `Value` for updates. |\n| `Img` | `Src` maps to `ImageLabel.Image`; native `ScaleType` remains available. `Alt` is metadata only. |\n| `Video` | `Src`, `AutoPlay`, `Loop`, `Muted`, plus native VideoFrame properties. Requires a permitted Roblox video asset. |\n| `Progress`, `Meter` | `Value`, `Min` (default 0), `Max` (default 1), `FillColor`. Clamps the visual fill; invalid ranges render empty. |\n\n## Development\n\nInstall Rokit, then run from this repository:\n\n```sh\nrokit install\nlune run scripts/setup\nlune run scripts/check\nlune run scripts/build\nrojo serve dev.project.json\n```\n\nOpen **`build/html-components-demo.rbxl`** in Studio and press Play for the gallery. Or connect Rojo to the dev project. In UI Labs, select **HTML Components**: every exported tag has a centered, bounded preview sized for its function, plus a CSS/provider example. Controls are specific to each component: text for labels/buttons, placeholders for text inputs, disabled state for interactive controls, value sliders for meters, and theme/corner-radius controls where applicable.\n\nOutputs:\n\n- `build/html-components-demo.rbxl`: standalone place, including dependencies, demo, stories, and Studio smoke tests.\n- `build/html-components.rbxm`: runtime ModuleScript; requires sibling `React` and `RobloxComponents` dependencies.\n- `build/html-components-0.1.0.zip`: Wally package, excluding development assets and dependencies.\n\nSource follows the `open-shl` React layout and section headings:\n\n```text\nsrc/React/\n  Component/\n    Button/\n      init.luau\n      Button.story.luau\n    StyleProvider/\n      init.luau\n      StyleProvider.story.luau\n  Context/Style.luau\n  Hook/useStyle.luau\n  Render/\n    Button.luau\n    Container.luau\n    Input.luau\n    ...\n```\n\nEach component exports `Properties` and an explicit component function. Shared rendering is split by host family; CSS remains in `src/CSS`. Stories sit alongside their components and are excluded from the runtime model and Wally archive. The dev project includes them, and `stories/HTML.storybook.luau` organizes them under **HTML Components**.\n\n`scripts/tags.luau` owns the tag catalog and default styles. Run `lune run scripts/generate` after editing it; commit the component folders, header, catalog, stories, and Wally directory list together. Generated source uses the same StyLua settings as `open-shl`; the check command detects drift.\n\nLocal checks cover CSS parsing/cascade/selector behavior, selective style notifications (including 500 subscribers), inline flow, markup/table validation, document parsing against 26 owned Chromium reference fixtures, generated story coverage, all 64 component property exports through the package header, formatting, strict runtime **and tooling** analysis, and 20 fixtures that must fail type checking. Build checks compile the runtime and demo, evaluate all 66 story factories with the installed UI Labs constructor to validate their returned metadata, and verify Wally contents. GitHub CI performs these checks; it does not run Studio or require third-party HTML downloads.\n\nThe editor uses the Luau LSP extension's automatically updated Roblox ","readmeTruncated":true,"readmeFull":"https://api.forest.dev/v1/package/nightcycle/roblox/html-components/0.1.1/readme"}