Add support for Roblox internal Stories and Storybooks

.lune/build.luau

@@ -48,7 +48,6 @@ if args.watch then
 	watch({
 		filePatterns = {
 			"src/.*%.luau",
-			"example/.*%.luau",
 		},
 		onChanged = build,
 	})

docs/docs/story-format.md

@@ -4,28 +4,25 @@
 
 Any ModuleScript with a `.storybook` extension will be picked up as a Storybook.
 
-:::warning
-Storybooks that do not have a `storyRoots` array will not be shown in the Flipbook UI.
-:::
-
 The properties that can be used in the module are as follows:
 
-| **Property** | **Type**             | **Description**                                                                                                                       |
-| ------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `storyRoots` | `{ Instance }`       | Locations that the Storybook manages. Each instance will have its descendants searched for Story modules.                             |
-| `name`       | `string?`            | An optional name for the Storybook. Defaults to the module name with the extension removed. i.e. `Sample.storybook` becomes `Sample`. |
-| `packages`   | `{ [string]: any }?` | An optional dictionary used for supplying the Storybook with the packages to use when rendering its Stories.                          |
+| **Property**    | **Type**                                        | **Description**                                                                                                                       |
+| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `storyRoots`    | `{ Instance }`                                  | Locations that the Storybook manages. Each instance will have its descendants searched for Story modules.                             |
+| `name`          | `string?`                                       | An optional name for the Storybook. Defaults to the module name with the extension removed. i.e. `Sample.storybook` becomes `Sample`. |
+| `packages`      | `{ [string]: any }?`                            | An optional dictionary used for supplying the Storybook with the packages to use when rendering its Stories.                          |
+| `mapDefinition` | `((story: any) -> any)?`                        |                                                                                                                                       |
+| `mapStory`      | `((story: any) -> (props: StoryProps) -> any)?` |                                                                                                                                       |
 
-This dictionary can also be supplied per-Story to change the renderer used, but it can be convenient to define your packages globally to avoid repetition. |
+This dictionary can also be supplied per-Story to change the renderer used, but it can be convenient to define your packages globally to avoid repetition.
 
-Example Storybook module:
+The most basic Storybook module can be represented as:
 
-```lua
--- Sample.storybook
+```lua title="Plain.storybook.luau"
 return {
-	storyRoots = {
-		script.Parent.Components
-	},
+    storyRoots = {
+        script.Parent,
+    },
 }
 ```
 
@@ -35,80 +32,42 @@ Any ModuleScript with a `.story` extension will be picked up as a Story when it
 
 The only required member of a Story definition is the `story` property.
 
-| **Property** | **Type**                        | **Description**                                                                                                                                                                                          |
-| ------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `story`      | `<T>((props: StoryProps) -> T)` |                                                                                                                                                                                                          |
-| `name`       | `string?`                       | The name of the Story as it appears in Flipbook. Defaults to the name of the Story module. i.e. `Sample.story` becomes `Sample`                                                                          |
-| `summary`    | `string?`                       | A description of the Story that will appear above the rendered preview in Flipbook.                                                                                                                      |
-| `controls`   | `{ [string]: any }?`            | Controls allow for on-the-fly configuration of your rendered UI. Read more about how to define and use Controls here: [Controls](https://www.notion.so/Controls-12f95b7912f8804388e1d746a6617716?pvs=21) |
-
-The type of the `story` property is dependent on what kind of Story is being rendered. Flipbook does not prescribe one particular way of writing Stories, or even a particular UI library that must be used.
-Stories can be written for React, Fusion, legacy Roact, plain Roblox Instances, and anything you can think of with [Manual Stories](https://www.notion.so/Story-format-12f95b7912f880068da6d74c472bf186?pvs=21).
-
-Example Story module:
-
-```lua
-return {
-	story = function(props)
-
-	end
-}
-```
-
-Under the hood these simply map to `packages.Roact`, `packages.React`, and `packages.ReactRoblox` respectively.
+| **Property** | **Type**                        | **Description**                                                                                                                                                                                                                              |
+| ------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `story`      | `<T>((props: StoryProps) -> T)` |                                                                                                                                                                                                                                              |
+| `name`       | `string?`                       | The name of the Story as it appears in Storyteller. Defaults to the name of the Story module. i.e. `Sample.story` becomes `Sample`                                                                                                           |
+| `summary`    | `string?`                       | A description of the Story that will appear above the rendered preview in Storyteller.                                                                                                                                                       |
+| `controls`   | `{ [string]: any }?`            | Controls allow for on-the-fly configuration of your rendered UI. Read more about how to define and use controls [here](/docs/creating-stories/controls).                                                                                     |
+| `packages`   | `{ [string]: any }?`            | An optional dictionary used for supplying the Story with the packages to use when rendering. The Story inherits the packages defined by the Storybook, so this is mostly used in cases where  Story needs to deviate from the usual renderer |
+| `props`      | `{ [string]: any }?`            |                                                                                                                                                                                                                                              |
 
-## Stories for different renderers
+The type of the `story` property is dependent on what kind of Story is being rendered. Storyteller does not prescribe one particular way of writing Stories, or even a particular UI library that must be used.
 
-### Manual
+## StoryProps
 
-### React
+A Story's `story` function is passed in a `StoryProps` object that contains the following.
 
-### Roact
+| **Property** | **Type**        | **Description**                                        |
+| ------------ | --------------- | ------------------------------------------------------ |
+| `container`  | `Instance`      |                                                        |
+| `theme`      | `string`        | A string representing the current Roblox Studio theme. |
+| `controls`   | `StoryControls` | Defaults to an empty table.                            |
 
-### Fusion
+If `props` is supplied on the Story, then the key/value pairs will be merged with `StoryProps`.
 
 ## Legacy package support
 
 :::warning
 A future version of Storyteller may remove this compatibility layer. It is recommended to migrate to `packages` in the meantime.
 :::
 
-For UI libraries to be used by Flipbook it was required to pass them as properties to the Story or Storybook. For example, to use React with Flipbook you would define a Storybook like the following:
-
-```lua
-local React = require("@pkg/React")
-local ReactRoblox = require("@pkg/ReactRoblox")
-
-return {
-	storyRoots = {
-		script.Parent.Components,
-	}
-	react = React,
-	reactRoblox = ReactRoblox,
-}
-```
-
-Storyteller uses a different approach by grouping any third-party libraries used for rendering stories in a `packages` object.
-
-```lua
-local React = require("@pkg/React")
-local ReactRoblox = require("@pkg/ReactRoblox")
-
-return {
-	storyRoots = {
-		script.Parent.Components,
-	}
-	packages = {
-		React = React,
-		ReactRoblox = ReactRoblox,
-	}
-}
-```
+UI libraries used to be supplied by attaching them as properties to a Story or Storybook. This has been superseded by the `packages` object, which acts as a dedicated location to supply the packages used for rendering Stories.
 
-For convenience, Storyteller provides backwards compatibility for the following Storybook properties:
+For backwards compatibility, the following properties are migrated to their `packages` equivalent:
 
-| **Property**  | **Type** | **Description**                                             |
-| ------------- | -------- | ----------------------------------------------------------- |
-| `roact`       | `any`    | Result of `require(ReplicatedStorage.Packages.Roact)`       |
-| `react`       | `any`    | Result of `require(ReplicatedStorage.Packages.React)`       |
-| `reactRoblox` | `any`    | Result of `require(ReplicatedStorage.Packages.ReactRoblox)` |
+| **Property**  | **Mapping**            |
+| ------------- | ---------------------- |
+| `fusion`      | `packages.Fusion`      |
+| `react`       | `packages.React`       |
+| `reactRoblox` | `packages.ReactRoblox` |
+| `roact`       | `packages.Roact`       |

foreman.toml

@@ -0,0 +1,10 @@
+[tools]
+rojo = { source = "rojo-rbx/rojo", version = "7.4.3" }
+selene = { source = "Kampfkarren/selene", version = "0.27.1" }
+StyLua = { source = "JohnnyMorganz/StyLua", version = "0.20.0" }
+wally = { source = "UpliftGames/wally", version = "0.3.2" }
+luau-lsp = { source = "JohnnyMorganz/luau-lsp", version = "1.34.0" }
+wally-package-types = { source = "JohnnyMorganz/wally-package-types", version = "1.3.2" }
+lune = { source = "lune-org/lune", version = "0.8.7" }
+darklua = { source = "seaofvoices/darklua", version = "0.13.1" }
+run-in-roblox = { source = "rojo-rbx/run-in-roblox", version = "0.3.0" }

src/hooks/useStorybooks.luau

@@ -14,10 +14,7 @@ local useMemo = React.useMemo
 
 type ModuleLoader = ModuleLoader.ModuleLoader
 type LoadedStorybook = types.LoadedStorybook
-type UnavailableStorybook = {
-	problem: string,
-	storybook: types.LoadedStorybook,
-}
+type UnavailableStorybook = types.UnavailableStorybook
 
 --[=[
 	Performs all the discovery and loading of Storybook modules that would

src/init.luau

@@ -20,6 +20,7 @@ export type Story<T> = types.Story<T>
 export type LoadedStory<T> = types.LoadedStory<T>
 export type Storybook = types.Storybook
 export type LoadedStorybook = types.LoadedStorybook
+export type UnavailableStorybook = types.UnavailableStorybook
 export type StoryControls = types.StoryControls
 export type StoryProps = types.StoryProps
 export type StoryRenderer<T> = types.StoryRenderer<T>

src/loadStoryModule.luau

@@ -33,7 +33,7 @@ local function loadStoryModule<T>(storyModule: ModuleScript, storybook: LoadedSt
 	end)
 
 	if not success then
-		error(`Failed to load story {storyModule:GetFullName()}. Error: {result})`)
+		error(`Failed to load story {storyModule:GetFullName()}:\n{result})`)
 	end
 
 	local isLegacyStory = typeof(result) == "function"
@@ -48,12 +48,30 @@ local function loadStoryModule<T>(storyModule: ModuleScript, storybook: LoadedSt
 		}
 	end
 
+	do -- Roblox internal. This behavior may be substantially changed or removed
+		-- We need support for substories to be compatible with Developer
+		-- Storybook. In the meantime we're just selecting a randomly accessed
+		-- one, but ideally we should be able to render them all out
+		if result.stories and not result.story then
+			local randomSubstory
+			for _, substory in result.stories do
+				randomSubstory = substory
+				break
+			end
+			if typeof(randomSubstory) == "table" then
+				result.story = randomSubstory.story
+			else
+				result.story = randomSubstory
+			end
+		end
+	end
+
 	local isValid, message = types.IStory(result)
 
 	if not isValid then
 		error(
 			`Story is malformed. Check the source of {storyModule:GetFullName()} and make sure its properties are `
-				.. `correct. Error: {message}`
+				.. `correct.\nerr: {message}`
 		)
 	end
 

src/loadStoryModule.spec.luau

@@ -218,3 +218,32 @@ describe("legacy support", function()
 		})
 	end)
 end)
+
+describe("roblox internal", function()
+	-- Right now we don't support rendering more than one story. For now, we
+	-- pick a random one to render.
+	test("pick a single substory to show", function()
+		local storybook: types.LoadedStorybook = {
+			name = "Storybook",
+			storyRoots = {},
+			loader = ModuleLoader.new(),
+			source = Instance.new("ModuleScript"),
+			packages = {},
+		}
+
+		local storyModule = createMockStoryModule([[
+			return {
+				stories = {
+					One = function() end,
+					Two = function() end,
+					Three = function() end,
+				}
+			}
+		]])
+
+		local story = loadStoryModule(storyModule, storybook)
+
+		expect(story.story).toBeDefined()
+		expect((story :: any).substories).toBeUndefined()
+	end)
+end)

src/loadStorybookModule.luau

@@ -30,9 +30,18 @@ local function loadStorybookModule(module: ModuleScript, providedLoader: ModuleL
 
 	assert(wasRequired, `failed to load storybook {module:GetFullName()}: {result}`)
 
+	do -- Roblox internal. This behavior may be removed without notice.
+		if not result.storyRoots and result.storyRoot then
+			-- Some storybooks use `storyRoot: Instance` instead of a
+			-- `storyRoots` array.
+			result.storyRoots = { result.storyRoot }
+			result.storyRoot = nil
+		end
+	end
+
 	local isStorybook, message = types.IStorybook(result)
 
-	assert(isStorybook, `failed to load storybook {module:GetFullName()}: {message}`)
+	assert(isStorybook, `failed to load storybook {module:GetFullName()}:\n{message}`)
 
 	if not result.packages then
 		result.packages = migrateLegacyPackages(result)
@@ -47,6 +56,12 @@ local function loadStorybookModule(module: ModuleScript, providedLoader: ModuleL
 		end
 	end
 
+	do -- Roblox internal. This behavior may be removed without notice.
+		if result.group then
+			result.name = `{result.group} / {result.name}`
+		end
+	end
+
 	result.source = module
 	result.loader = loader
 

src/loadStorybookModule.spec.luau

@@ -117,3 +117,17 @@ describe("legacy support", function()
 		})
 	end)
 end)
+
+describe("roblox internal", function()
+	test("map storyRoot (single instance) to storyRoots (array of instances)", function()
+		local storybookModule = createMockStorybookModule([[
+			return {
+				storyRoot = Instance.new("Folder"),
+			}
+		]])
+
+		local storybook = loadStorybookModule(storybookModule)
+
+		expect(#storybook.storyRoots).toBe(1)
+	end)
+end)

src/matchDescendants.luau

@@ -1,3 +1,5 @@
+local Prospector = require("@pkg/Prospector")
+
 local function hasPermission(instance: Instance)
 	local success = pcall(function()
 		return instance.Name
@@ -12,17 +14,11 @@ local function matchDescendants(parent: Instance, predicate: (descendant: Instan
 		return matches
 	end
 
-	for _, descendant in parent:GetDescendants() do
-		local success, result = pcall(function()
-			return predicate(descendant)
-		end)
-
-		if success and result == true then
-			table.insert(matches, descendant)
-		end
-	end
-
-	return matches
+	-- Before Prospector we were calling parent:GetDescendants() but because we
+	-- need to support the DataModel being passed in that case would allocate a
+	-- gigantic array. Prospector will traverse the hierarchy manually, which
+	-- takes longer but won't freeze up consumers
+	return Prospector.Collect.descendantsDFS(parent, predicate)
 end
 
 return matchDescendants

src/migrateLegacyPackages.luau

@@ -1,9 +1,19 @@
+local isReact = require("@root/roblox-internal/isReact")
 local types = require("@root/types")
 
 type StoryPackages = types.StoryPackages
 
 local function migrateLegacyPackages(storyOrStorybook: { [string]: any }): StoryPackages?
 	if storyOrStorybook.roact or storyOrStorybook.react or storyOrStorybook.reactRoblox then
+		do -- Roblox internal. This behavior may be removed without notice.
+			if storyOrStorybook.roact and storyOrStorybook.reactRoblox and isReact(storyOrStorybook.roact) then
+				return {
+					React = storyOrStorybook.roact,
+					ReactRoblox = storyOrStorybook.reactRoblox,
+				}
+			end
+		end
+
 		return {
 			Roact = storyOrStorybook.roact,
 			React = storyOrStorybook.react,

src/migrateLegacyPackages.spec.luau

@@ -0,0 +1,34 @@
+local JestGlobals = require("@pkg/JestGlobals")
+local React = require("@pkg/React")
+local ReactRoblox = require("@pkg/ReactRoblox")
+local Roact = require("@pkg/Roact")
+
+local migrateLegacyPackages = require("./migrateLegacyPackages")
+
+local describe = JestGlobals.describe
+local test = JestGlobals.test
+local expect = JestGlobals.expect
+
+test("map roact key", function()
+	local packages = migrateLegacyPackages({
+		roact = Roact,
+	})
+
+	expect(packages).toEqual({
+		Roact = Roact,
+	})
+end)
+
+describe("roblox internal", function()
+	test("react can be passed as the roact key", function()
+		local packages = migrateLegacyPackages({
+			roact = React,
+			reactRoblox = ReactRoblox,
+		})
+
+		expect(packages).toEqual({
+			React = React,
+			ReactRoblox = ReactRoblox,
+		})
+	end)
+end)