{"id":"nightcycle/typed-instance-components","name":"typed-instance-components","scope":"nightcycle","platform":"roblox","description":"Strictly typed React-Luau host argument builders and custom component adapters.","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.0","alias":"React"}},"integrity":"d6c689c3d0249bc006d0e647ec44086553f07edcf88a388d48125d9013a00380","likes":0,"downloads":0,"install":"forest install nightcycle/typed-instance-components","url":"https://forest.dev/p/roblox/nightcycle/typed-instance-components","files":"https://api.forest.dev/ai/package/roblox/nightcycle/typed-instance-components/files","readme":"# Typed Instance Components\n\nStrictly typed argument builders for [React-Luau](https://github.com/jsdotlua/react-lua). Merge component props into a root Roblox instance without forwarding unrelated component fields.\n\n```luau\nreturn e(RobloxComponents.TextButton({\n\tText = props.Label,\n\t[React.Event.Activated] = props.OnActivated,\n}, props, {\n\tCorner = e(RobloxComponents.UICorner({ CornerRadius = UDim.new(0, 8) }, {})),\n}))\n```\n\nThe generated builders port `open-shl/scripts/util/generate-react-roblox-types.lune.luau`: a plain optional `Properties` record, a `VALID_PROPERTIES` table, an `append` function, and a builder returning **class/component, merged props, children**. There are no per-property generics, binding unions, or React-prop intersections.\n\n## Install\n\nThe initial package version is `0.1.0`. The Wally declaration below becomes installable after the first release is published.\n\n```toml\n[dependencies]\nReact = \"jsdotlua/react@17.2.1\"\nReactRoblox = \"jsdotlua/react-roblox@17.2.1\"\nTypedInstanceComponents = \"nightcycle/typed-instance-components@0.1.0\"\n```\n\nRun `wally install`, map `Packages` into your Rojo project, and run [wally-package-types](https://github.com/JohnnyMorganz/wally-package-types) against your sourcemap to expose exported type aliases through Wally's generated modules:\n\n```sh\nrojo sourcemap default.project.json --output sourcemap.json\nwally-package-types --sourcemap sourcemap.json Packages\n```\n\n```luau\nlocal Packages = game:GetService(\"ReplicatedStorage\").Packages\nlocal React = require(Packages.React)\nlocal RobloxComponents = require(Packages.TypedInstanceComponents)\nlocal TextButton = RobloxComponents.TextButton\nlocal UICorner = RobloxComponents.UICorner\n\ntype Properties = RobloxComponents.TextButtonProperties & {\n\tLabel: string,\n\tOnActivated: () -> (),\n}\n```\n\nThe package header requires every class module and `Custom`, then returns a frozen table containing their builders directly. Each property type is re-exported from its class module, for example `export type FrameProperties = Frame.Properties`.\n\nEach class is a separate **private** ModuleScript under `Generated/Package/`. The only public import is the Wally header. Require that header first, then select builders from the returned API and types from its exported aliases:\n\n```luau\nlocal RobloxComponents = require(Packages.TypedInstanceComponents)\nlocal Frame = RobloxComponents.Frame\nlocal TextLabel = RobloxComponents.TextLabel\n\ntype Properties = RobloxComponents.FrameProperties & { Label: string }\n\nreturn e(Frame({}, props, {\n\tLabel = e(TextLabel({ Text = props.Label }, {})),\n}))\n```\n\nSee [the local-builder example](examples/Cached.luau). Wally's package header has no child modules: do not index beneath it or depend on private `_Index` paths. Abstract class property types remain available through header exports such as `RobloxComponents.GuiBase2dProperties`.\n\nThe exported table has no metatable. Normal indexing, generalized iteration, `pairs`, `next`, and `rawget` access its entries directly.\n\nFor local use before publication, run `lune run scripts/dev/setup.lune.luau` and use `dev.project.json`. It exposes a childless Wally-style forwarding header and keeps the implementation inside the private package index, with a sibling React dependency. `scripts/dev/prepare-project.lune.luau` regenerates those development headers and runs `wally-package-types` to expose their types. The package's `default.project.json` combines authored modules in `src/` with generated implementation modules in `Generated/Package/`; it is used internally by Wally. The `.rbxm` release asset likewise needs a sibling `React` dependency. Consumers use the same header-returned API in every layout.\n\n## Builders and merging\n\n```luau\nRobloxComponents.Frame(defaults, props, children?)\n-- returns: \"Frame\", mergedProperties, children\n```\n\n- Both `defaults` and `props` are required; use `{}` for an empty table. Defaults are copied last and **win** over props, exactly as in `open-shl`.\n- Incoming props retain only keys in `VALID_PROPERTIES` and non-string React keys. Component-only fields and incoming string keys such as `ref`, `key`, and `children` are filtered out.\n- Defaults are copied without filtering. Put React metadata such as `ref` or `key` there when needed. Inputs remain unchanged and values retain their identity.\n- The third argument is returned unchanged. Pass children explicitly; there is no implicit `props.children` fallback.\n- Use the builder as the final/only argument to `e` so Luau expands all three return values. Do not pass the builder itself as a component or wrap its call in another pair of parentheses.\n\nEvery generated property is a plain optional native type, for example `Size: UDim2?` or `Text: string?`. Public aliases such as `RobloxComponents.FrameProperties` are plain records. React bindings are not added to every property type; an application using a binding can explicitly cast that value at its call site. Enum properties use concrete enum types; asset URI properties such as `Image` are strings, while `ImageContent` uses `Content`. Non-string event/change/tag keys pass through unchanged.\n\n## Class coverage\n\nThe checked-in [API source configuration](api/source.json) pins both the [GuiBase2d](https://robloxapi.github.io/ref/class/GuiBase2d.html) and [UIBase](https://robloxapi.github.io/ref/class/UIBase.html) trees from the [Roblox instance tree](https://robloxapi.github.io/ref/index.html): **49 property types and 33 host builders**. Generation writes the complete class list to `Generated/classes.md`.\n\nAbstract, non-creatable, deprecated, and non-browsable classes expose property types only. Examples include `GuiBase2dProperties`, `GuiObjectProperties`, `UIBaseProperties` and `PluginGuiProperties`. There is no `RobloxComponents.GuiBase2d` constructor. Engine rollout and permissions still control availability of newer classes such as UIBlur/UIShadow.\n\nGeneration walks ancestors and excludes read-only, hidden, deprecated, non-scriptable and security-restricted properties. React owns `Parent`, so it is excluded, as are instance security controls. Unknown public property datatypes fail generation for review instead of becoming `any`.\n\n## Custom classes and components\n\n`RobloxComponents.Custom(component, project)` creates a builder for an unsupported host class or custom component. The `project` function defines the plain prop shape and selects the incoming fields. The builder copies defaults over that result and returns the explicit children argument unchanged.\n\n```luau\ntype PartProps = {\n\tColor: Color3?,\n\tAnchored: boolean?,\n}\n\nlocal Part = RobloxComponents.Custom(\"Part\", function(props: PartProps): PartProps\n\treturn {\n\t\tColor = props.Color,\n\t\tAnchored = props.Anchored,\n\t}\nend)\n\nlocal element = e(Part({ Anchored = true }, {\n\tColor = Color3.fromRGB(255, 100, 80),\n}))\n```\n\nFor a custom component, pass the component instead of a class name:\n\n```luau\ntype BadgeProps = { Title: string?, children: React.ReactNode? }\n\nlocal function Badge(props: BadgeProps)\n\treturn e(RobloxComponents.TextLabel({ Text = props.Title or \"Badge\" }, {}, props.children))\nend\n\nlocal CustomBadge = RobloxComponents.Custom(Badge, function(props: BadgeProps): BadgeProps\n\treturn { Title = props.Title, children = props.children }\nend)\n\nlocal element = e(CustomBadge({ Title = \"Ready\" }, {}))\n```\n\nThe projector selects incoming fields. Use an identity projector only when every incoming field belongs to the wrapped component. Keep mergeable fields optional; required fields must be present in both supplied tables. Pass children explicitly. A custom host name uses your declared property shape, and Roblox validates the actual class at render time.\n\nSee [the typed examples](examples) for both patterns.\n\n## Development and validation\n\nInstall [Rokit](https://github.com/rojo-rbx/rokit), then run:\n\n```sh\nrokit install\nlune run scripts/dev/setup.lune.luau\nlune run scripts/checks/run.lune.luau\nlune run scripts/build/run.lune.luau\n```\n\nRunnable Lune entry points use `.lune.luau`; imported helper modules use `.luau`. Scripts are grouped by purpose:\n\n| Directory | Purpose |\n| --- | --- |\n| `scripts/build/` | Build and verify Rojo models and the Wally archive |\n| `scripts/checks/` | Run formatting, regression tests and strict type checks |\n| `scripts/codegen/` | Generate package modules, API snapshots and class coverage |\n| `scripts/dev/` | Install dependencies, initialize the editor and serve Studio test data |\n| `scripts/release/` | Validate tags and publish Wally releases |\n| `scripts/shared/` | Shared command runner and package metadata helpers |\n\nTo check edited Luau files, run `lune run scripts/checks/files.lune.luau src/Merge.luau` (multiple file paths are supported). It runs `luau-lsp` and Selene, refreshes `Generated/sourcemap.json` for Roblox modules, and uses the Lune environment for tooling scripts. Intentional negative fixtures remain covered by the full check suite. Selene's generated Roblox standard library lives in `Generated/Selene/`; setup also installs Lune's editor definitions. The analyzer uses its default formatter because the pinned version's plain formatter can return success despite type errors.\n\nSetup installs locked React dependencies, generates the package and development headers, fixes Wally type exports, and downloads pinned Roblox type definitions. Builds and checks also run generation first, so generated files need not exist in a fresh checkout. Checks verify deterministic generation, eager module loading, direct header exports, merge/filter behavior across every generated host, API mapping/restrictions, release validation, formatting, strict analysis, and nine fixtures that must fail type checking. One fixture rejects indexing below the public header. Build verifies the flat internal module hierarchy, childless public header, compiled package modules, internal require paths and Wally archive contents. Artifacts are written to `Generated/build/`:\n\n- `typed-instance-components-0.1.0.zip`: Wally package.\n- `typed-instance-components.rbxm`: package module; requires a sibling React module.\n- `typed-instance-components-tests.rbxl`: test place with React, ReactRoblox, examples and integration tests.\n\nAll repository-generated outputs live under the gitignored `Generated/` directory: package modules in `Package/`, development forwarding headers in `Dev/`, API snapshots in `Api/`, class coverage in `classes.md`, the editor sourcemap in `sourcemap.json`, and release artifacts in `build/`. Only the runtime files in `Generated/Package/` are included in the Wally archive, alongside the authored runtime modules. Keep `api/source.json` and the generator scripts in version control.\n\nThe workspace includes a VS Code-compatible **Generate package on folder open** task and a default **Build package** task. Folder-open generation also refreshes the sourcemap when dependencies are installed. The workspace enables automatic tasks; VS Code still requires a trusted workspace. If your editor has disabled automatic tasks, use **Tasks: Manage Automatic Tasks** or run `lune run scripts/dev/editor-open.lune.luau` manually. See [VS Code's automatic-task behavior](https://code.visualstudio.com/docs/debugtest/tasks#_control-automatic-task-execution). Install the pinned Rokit tools before opening the workspace for the first time.\n\nFor the real renderer test, open the test place in Studio and run this in the command bar **before requiring React/ReactRoblox**:\n\n```luau\n_G.__DEV__ = true\n_G.__ROACT_17_MOCK_SCHEDULER__ = true\nprint(require(game.ReplicatedStorage.Tests.Integration)())\n```\n\nThis checks mounting, binding updates, change events, refs, nested UI instances, custom components and unmount cleanup. The test uses a detached container. CI runs the Lune/static/build checks; it does not claim to run Roblox Studio.\n\nTo refresh API coverage, update `api/source.json` to an immutable API-dump commit/URL, then run `lune run scripts/codegen/generate.lune.luau`. A missing snapshot is downloaded from that pinned URL and reduced into `Generated/Api/`; its cache key includes the commit and selected roots. Later generation runs use the cached snapshot without network access. Generation removes obsolete files bearing this generator's marker, including the former `Hosts.luau` and `Properties.luau` bundles; `--check` rejects stale or obsolete output. To seed the cache offline, run `lune run scripts/codegen/snapshot-api.lune.luau path/to/API-Dump.json` first. Update the pinned type-definition revision in `scripts/dev/setup.lune.luau`, `scripts/checks/run.lune.luau` and `scripts/checks/files.lune.luau` when the new API needs it. Review the generated API snapshot, modules and coverage locally; commit their inputs and generator changes.\n\n## CI and releases\n\nGitHub Actions runs workflow linting, setup, all checks and artifact builds on main-branch pushes and pull requests. Action revisions and tool versions are pinned; Dependabot maintains action pins.\n\nTo publish:\n\n1. Configure the repository secret `WALLY_AUTH_TOKEN` for an account allowed to publish under `nightcycle`.\n2. Set `wally.toml` to the release version, update `wally.lock` with `wally install`, and commit/push the validated changes.\n3. Push the matching stable tag, for example `v0.1.1` or `0.1.1`, or manually dispatch Release with either spelling. The workflow tries the exact tag first, then its alternate spelling.\n\nRelease compares versions without the optional `v` prefix, checks the exact tag commit, reruns validation, publishes Wally, then creates/uploads the GitHub release artifacts. Release lookups accept either spelling and uploads reuse the existing release's tag; new releases use the resolved Git tag. Release runs are serialized so the two input spellings cannot publish concurrently. Missing credentials and rejected Wally publication fail the release. Published Wally versions are immutable: use a new version for changed code. If Wally succeeded but GitHub asset publication failed, rerun the manual workflow for the same tag with `publish_wally` disabled. No publishing occurs during ordinary CI.\n\n## License\n\nApache-2.0. The generator pattern originated in the author's open-shl project; the pinned API data is derived from the Roblox engine API dump tracked by [Roblox-Client-Tracker](https://github.com/MaximumADHD/Roblox-Client-Tracker).\n","readmeTruncated":false}