@heliosgraphics/fx 0.0.1-alpha.0

package/components/PropsTable/PropsTable.utils.tsx

@@ -0,0 +1,81 @@
+import { BooleanEditor } from "./_components/BooleanEditor"
+import { EnumEditor } from "./_components/EnumEditor"
+import { NumberEditor } from "./_components/NumberEditor"
+import { StringEditor } from "./_components/StringEditor"
+import type { ReactElement } from "react"
+import type { KnobRegistry } from "../../types/knobs"
+import type { WorkshopProviderProps } from "../../contexts/WorkshopProvider/WorkshopProvider.types"
+
+export const getEditorComponent = (
+	name: string,
+	type: string,
+	knobField: string | undefined,
+	knobs: KnobRegistry,
+	context: WorkshopProviderProps,
+	isDisabled: boolean,
+): ReactElement | null => {
+	if (knobField && knobs[knobField] && !knobs[knobField].isInternal) {
+		const knobDef = knobs[knobField]
+		const value = context.knobValues[knobField] ?? knobDef.defaultValue
+		const setter = context.knobSetters[knobField]
+
+		if (!setter) return null
+
+		return (
+			<EnumEditor
+				knobName={knobDef.label}
+				values={knobDef.values}
+				value={value}
+				onChange={setter}
+				isDisabled={isDisabled}
+			/>
+		)
+	}
+
+	if (!knobField && knobs[name] && !knobs[name].isInternal) {
+		const knobDef = knobs[name]
+		const value = context.knobValues[name] ?? knobDef.defaultValue
+		const setter = context.knobSetters[name]
+
+		if (!setter) return null
+
+		return (
+			<EnumEditor
+				knobName={knobDef.label}
+				values={knobDef.values}
+				value={value}
+				onChange={setter}
+				isDisabled={isDisabled}
+			/>
+		)
+	}
+
+	if (type === "boolean" || name.startsWith("is") || name.startsWith("has")) {
+		const boolValue = (context.knobValues[name] as boolean) ?? false
+		const boolSetter = context.knobSetters[name]
+
+		if (!boolSetter) return null
+
+		return <BooleanEditor label={name} value={boolValue} onChange={(v) => boolSetter(v)} isDisabled={isDisabled} />
+	}
+
+	if (type === "number") {
+		const numValue = Number(context.knobValues[name] ?? 0)
+		const numSetter = context.knobSetters[name]
+
+		if (!numSetter) return null
+
+		return <NumberEditor label={name} value={numValue} onChange={(v) => numSetter(v)} isDisabled={isDisabled} />
+	}
+
+	if (type === "string") {
+		const strValue = String(context.knobValues[name] ?? "")
+		const strSetter = context.knobSetters[name]
+
+		if (!strSetter) return null
+
+		return <StringEditor label={name} value={strValue} onChange={(v) => strSetter(v)} isDisabled={isDisabled} />
+	}
+
+	return null
+}

package/components/PropsTable/_components/BooleanEditor/BooleanEditor.tsx

@@ -0,0 +1,23 @@
+"use client"
+
+import { Flex, Toggle } from "@heliosgraphics/ui"
+import type { FC } from "react"
+import type { BooleanEditorProps } from "./BooleanEditor.types"
+
+export const BooleanEditor: FC<BooleanEditorProps> = ({ label, value, onChange, isDisabled }) => {
+	const onToggle = (): void => onChange(!value)
+
+	return (
+		<Flex isCentered={true}>
+			<Toggle
+				intent="neutral"
+				isChecked={value}
+				label={label}
+				isSmall={true}
+				onChange={onToggle}
+				isLabelHidden={true}
+				{...(isDisabled !== undefined && { isDisabled })}
+			/>
+		</Flex>
+	)
+}

package/components/PropsTable/_components/BooleanEditor/BooleanEditor.types.ts

@@ -0,0 +1,6 @@
+export interface BooleanEditorProps {
+	label: string
+	value: boolean
+	onChange: (value: boolean) => void
+	isDisabled?: boolean
+}

package/components/PropsTable/_components/BooleanEditor/index.ts

@@ -0,0 +1,2 @@
+export { BooleanEditor } from "./BooleanEditor"
+export type { BooleanEditorProps } from "./BooleanEditor.types"

package/components/PropsTable/_components/EnumEditor/EnumEditor.tsx

@@ -0,0 +1,64 @@
+"use client"
+
+import { Flex, Select, ButtonGroup, Button } from "@heliosgraphics/ui"
+import { useRef, type FC, type ChangeEvent } from "react"
+import type { EnumEditorProps } from "./EnumEditor.types"
+
+export const EnumEditor: FC<EnumEditorProps> = ({
+	knobName,
+	values,
+	value,
+	onChange,
+	hasUnsetOption = true,
+	hasRandom = true,
+	isDisabled,
+}) => {
+	const lastValueRef = useRef<string | number | boolean>(value)
+
+	const items = hasUnsetOption
+		? [{ name: "unset", value: "" }, ...values.map((v) => ({ name: String(v), value: String(v) }))]
+		: values.map((v) => ({ name: String(v), value: String(v) }))
+
+	const onSelectChange = (event: ChangeEvent<HTMLSelectElement>): void => {
+		const raw: string = event.target.value
+		const original = values.find((v) => String(v) === raw)
+
+		onChange(original ?? raw)
+	}
+
+	const onRandom = (): void => {
+		let next: string | number | boolean = value
+
+		do {
+			next = values[Math.floor(Math.random() * values.length)] ?? value
+		} while (next === lastValueRef.current && values.length > 1)
+
+		lastValueRef.current = next
+		onChange(next)
+	}
+
+	return (
+		<Flex gap={4}>
+			<Select
+				label={`${knobName} Selector`}
+				isLabelHidden={true}
+				isSmall={true}
+				items={items}
+				onChange={onSelectChange}
+				selectedValue={String(value ?? "")}
+				{...(isDisabled !== undefined && { isDisabled })}
+			/>
+			{hasRandom && (
+				<ButtonGroup>
+					<Button
+						intent="neutral"
+						value="Random"
+						onClick={onRandom}
+						size="small"
+						{...(isDisabled !== undefined && { isDisabled })}
+					/>
+				</ButtonGroup>
+			)}
+		</Flex>
+	)
+}

package/components/PropsTable/_components/EnumEditor/EnumEditor.types.ts

@@ -0,0 +1,9 @@
+export interface EnumEditorProps {
+	knobName: string
+	values: Array<string | number | boolean>
+	value: string | number | boolean
+	onChange: (value: string | number | boolean) => void
+	hasUnsetOption?: boolean
+	hasRandom?: boolean
+	isDisabled?: boolean
+}

package/components/PropsTable/_components/EnumEditor/index.ts

@@ -0,0 +1,2 @@
+export { EnumEditor } from "./EnumEditor"
+export type { EnumEditorProps } from "./EnumEditor.types"

package/components/PropsTable/_components/NumberEditor/NumberEditor.tsx

@@ -0,0 +1,26 @@
+"use client"
+
+import { Flex, Input } from "@heliosgraphics/ui"
+import type { FC, ChangeEvent } from "react"
+import type { NumberEditorProps } from "./NumberEditor.types"
+
+export const NumberEditor: FC<NumberEditorProps> = ({ label, value, onChange, isDisabled }) => {
+	const onInputChange = (event?: ChangeEvent<HTMLInputElement>): void => {
+		const parsed: number = Number(event?.target?.value ?? 0)
+
+		if (!Number.isNaN(parsed)) onChange(parsed)
+	}
+
+	return (
+		<Flex isCentered={true}>
+			<Input
+				value={String(value)}
+				onChange={onInputChange}
+				placeholder={label}
+				label={label}
+				isLabelHidden={true}
+				{...(isDisabled !== undefined && { isDisabled })}
+			/>
+		</Flex>
+	)
+}

package/components/PropsTable/_components/NumberEditor/NumberEditor.types.ts

@@ -0,0 +1,9 @@
+export interface NumberEditorProps {
+	label: string
+	value: number
+	onChange: (value: number) => void
+	min?: number
+	max?: number
+	step?: number
+	isDisabled?: boolean
+}

package/components/PropsTable/_components/NumberEditor/index.ts

@@ -0,0 +1,2 @@
+export { NumberEditor } from "./NumberEditor"
+export type { NumberEditorProps } from "./NumberEditor.types"

package/components/PropsTable/_components/StringEditor/StringEditor.tsx

@@ -0,0 +1,22 @@
+"use client"
+
+import { Flex, Input } from "@heliosgraphics/ui"
+import type { FC, ChangeEvent } from "react"
+import type { StringEditorProps } from "./StringEditor.types"
+
+export const StringEditor: FC<StringEditorProps> = ({ label, value, onChange, isDisabled }) => {
+	const onInputChange = (event?: ChangeEvent<HTMLInputElement>): void => onChange(event?.target?.value ?? "")
+
+	return (
+		<Flex isCentered={true}>
+			<Input
+				value={value}
+				onChange={onInputChange}
+				placeholder={label}
+				label={label}
+				isLabelHidden={true}
+				{...(isDisabled !== undefined && { isDisabled })}
+			/>
+		</Flex>
+	)
+}

package/components/PropsTable/_components/StringEditor/StringEditor.types.ts

@@ -0,0 +1,6 @@
+export interface StringEditorProps {
+	label: string
+	value: string
+	onChange: (value: string) => void
+	isDisabled?: boolean
+}

package/components/PropsTable/_components/StringEditor/index.ts

@@ -0,0 +1,2 @@
+export { StringEditor } from "./StringEditor"
+export type { StringEditorProps } from "./StringEditor.types"

package/components/PropsTable/index.ts

@@ -0,0 +1,2 @@
+export { PropsTable } from "./PropsTable"
+export type { PropsTableProps } from "./PropsTable.types"

package/components/WorkshopAside/WorkshopAside.tsx

@@ -0,0 +1,103 @@
+"use client"
+
+import { useContext, useState, useMemo, type FC, type ChangeEvent } from "react"
+import Link from "next/link"
+import { Menu, Layout, Flex, Text } from "@heliosgraphics/ui"
+import { usePathname } from "next/navigation"
+import { WorkshopContext } from "../../contexts/WorkshopProvider"
+import type { WorkshopAsideProps } from "./WorkshopAside.types"
+import type { WorkshopComponentStatus } from "../../types/meta"
+
+export const WorkshopAside: FC<WorkshopAsideProps> = ({ name, components }) => {
+	const pathname = usePathname()
+	const { knobValues, visibleStatuses, pages } = useContext(WorkshopContext)
+	const hasMenu = knobValues["hasMenu"] !== false
+	const [filter, setFilter] = useState<string>("")
+
+	const visibleComponents = useMemo(
+		() =>
+			Object.keys(components).filter((c) => {
+				const status: WorkshopComponentStatus = components[c]?._status ?? "experimental"
+
+				return visibleStatuses.includes(status)
+			}),
+		[components, visibleStatuses],
+	)
+
+	const filteredComponents = useMemo(
+		() =>
+			filter ? visibleComponents.filter((c) => c.toLowerCase().includes(filter.toLowerCase())) : visibleComponents,
+		[visibleComponents, filter],
+	)
+
+	const onValueChange = (event?: ChangeEvent<HTMLInputElement>): void => {
+		setFilter(event?.target?.value ?? "")
+	}
+
+	const onClear = (): void => setFilter("")
+
+	const groupedComponents: Record<string, Array<string>> = filteredComponents.reduce<Record<string, Array<string>>>(
+		(acc, component) => {
+			const category: string = components[component]?._category ?? "uncategorized"
+
+			acc[category] = acc[category] || []
+			acc[category].push(component)
+
+			return acc
+		},
+		{},
+	)
+
+	if (!hasMenu) return null
+
+	return (
+		<Layout.Aside>
+			<Layout.Navigation gap={8} isBetween={true}>
+				<Flex gap={6} isYCentered={true}>
+					<Link href="/" className="flex">
+						<Text type="small" fontWeight="semibold">
+							{name}
+						</Text>
+					</Link>
+				</Flex>
+				<Layout.Aside.Toggle />
+			</Layout.Navigation>
+			<Layout.Aside.Content>
+				<Menu>
+					<Menu.Filter value={filter} onChange={onValueChange} {...(filter && { onClear })} />
+					{!filter && (
+						<Menu.Category category="Workshop" isFolder={true}>
+							<Link href="/">
+								<Menu.Item icon="home" title="Dashboard" isActive={pathname === "/"} />
+							</Link>
+							{pages.map((page) => (
+								<Link href={page.href} key={page.href}>
+									<Menu.Item
+										{...(page.icon && { icon: page.icon })}
+										title={page.title}
+										isActive={pathname === page.href}
+									/>
+								</Link>
+							))}
+						</Menu.Category>
+					)}
+					{Object.entries(groupedComponents).map(([category, items]) => (
+						<Menu.Category
+							key={`${category}-${Boolean(filter)}`}
+							category={category}
+							isFolder={true}
+							isInitiallyClosed={!filter}
+							{...(filter && { isOpen: true })}
+						>
+							{items.map((component) => (
+								<Link href={`/components/${component}`} key={component}>
+									<Menu.Item title={component} isActive={pathname === `/components/${component}`} />
+								</Link>
+							))}
+						</Menu.Category>
+					))}
+				</Menu>
+			</Layout.Aside.Content>
+		</Layout.Aside>
+	)
+}

package/components/WorkshopAside/WorkshopAside.types.ts

@@ -0,0 +1,6 @@
+import type { WorkshopComponentRegistry } from "../../types/meta"
+
+export interface WorkshopAsideProps {
+	name: string
+	components: WorkshopComponentRegistry
+}

package/components/WorkshopAside/index.ts

@@ -0,0 +1,2 @@
+export { WorkshopAside } from "./WorkshopAside"
+export type { WorkshopAsideProps } from "./WorkshopAside.types"

package/components/WorkshopNavigation/WorkshopNavigation.tsx

@@ -0,0 +1,36 @@
+"use client"
+
+import { useContext, type FC } from "react"
+import { Flex, Layout, ButtonGroup, Button, useTheme, useLayoutContext } from "@heliosgraphics/ui"
+import { WorkshopContext } from "../../contexts/WorkshopProvider"
+import type { WorkshopNavigationProps } from "./WorkshopNavigation.types"
+
+export const WorkshopNavigation: FC<WorkshopNavigationProps> = () => {
+	const { isMenuVisible, isWideEnough } = useLayoutContext()
+	const { toggleTheme, isDark } = useTheme()
+	const { knobValues } = useContext(WorkshopContext)
+	const hasHeader = knobValues["hasHeader"] !== false
+	const hasSubHeader = knobValues["hasSubHeader"] === true
+
+	if (!hasHeader) return null
+
+	return (
+		<>
+			<Layout.Navigation isBetween={true}>
+				<Flex isYCentered={true} gap={8}>
+					{!isMenuVisible && !isWideEnough && <Layout.Aside.Toggle />}
+				</Flex>
+				<ButtonGroup>
+					<Button
+						intent="neutral"
+						onClick={toggleTheme}
+						value={isDark ? "Light" : "Dark"}
+						size="small"
+						icon={isDark ? "sun" : "moon"}
+					/>
+				</ButtonGroup>
+			</Layout.Navigation>
+			{hasSubHeader && <Layout.SubNavigation />}
+		</>
+	)
+}

package/components/WorkshopNavigation/WorkshopNavigation.types.ts

@@ -0,0 +1 @@
+export interface WorkshopNavigationProps {}

package/components/WorkshopNavigation/index.ts

@@ -0,0 +1,2 @@
+export { WorkshopNavigation } from "./WorkshopNavigation"
+export type { WorkshopNavigationProps } from "./WorkshopNavigation.types"

package/components/index.ts

@@ -0,0 +1,17 @@
+export { LiveComponents } from "./LiveComponents"
+export type { LiveComponentsProps } from "./LiveComponents"
+
+export { Page } from "./Page"
+export type { PageProps } from "./Page"
+
+export { PageBlock } from "./PageBlock"
+export type { PageBlockProps } from "./PageBlock"
+
+export { PropsTable } from "./PropsTable"
+export type { PropsTableProps } from "./PropsTable"
+
+export { WorkshopAside } from "./WorkshopAside"
+export type { WorkshopAsideProps } from "./WorkshopAside"
+
+export { WorkshopNavigation } from "./WorkshopNavigation"
+export type { WorkshopNavigationProps } from "./WorkshopNavigation"

package/config/index.ts

@@ -0,0 +1,24 @@
+import type { WorkshopConfig } from "../types/config"
+
+export const createWorkshopConfig = (config: WorkshopConfig): Record<string, unknown> => {
+	const nextConfig = {
+		devIndicators: false,
+		reactStrictMode: true,
+		typescript: {
+			ignoreBuildErrors: true,
+		},
+		transpilePackages: [
+			"@heliosgraphics/utils",
+			"@heliosgraphics/icons",
+			"@heliosgraphics/ui",
+			"@heliosgraphics/css",
+			"@heliosgraphics/workshop",
+			...(config.transpilePackages ?? []),
+		],
+		experimental: {
+			externalDir: true,
+		},
+	}
+
+	return nextConfig
+}

package/contexts/LayoutProvider/LayoutProvider.tsx

@@ -0,0 +1,28 @@
+"use client"
+
+import { useState, createContext, type FC, type PropsWithChildren } from "react"
+import type { LayoutProviderProps } from "./LayoutProvider.types"
+
+export const DEFAULT_DEMO_PATTERN = "default" as const
+
+const LayoutContext = createContext<LayoutProviderProps>({
+	activeDemoPattern: DEFAULT_DEMO_PATTERN,
+	setActiveDemoPattern: () => null,
+	isPermutationsMode: false,
+	setIsPermutationsMode: () => null,
+})
+
+const LayoutProvider: FC<PropsWithChildren> = ({ children }) => {
+	const [activeDemoPattern, setActiveDemoPattern] = useState<string>(DEFAULT_DEMO_PATTERN)
+	const [isPermutationsMode, setIsPermutationsMode] = useState<boolean>(false)
+
+	return (
+		<LayoutContext.Provider
+			value={{ activeDemoPattern, setActiveDemoPattern, isPermutationsMode, setIsPermutationsMode }}
+		>
+			{children}
+		</LayoutContext.Provider>
+	)
+}
+
+export { LayoutContext, LayoutProvider }

package/contexts/LayoutProvider/LayoutProvider.types.ts

@@ -0,0 +1,8 @@
+import type { Dispatch, SetStateAction } from "react"
+
+export interface LayoutProviderProps {
+	activeDemoPattern: string
+	setActiveDemoPattern: Dispatch<SetStateAction<string>>
+	isPermutationsMode: boolean
+	setIsPermutationsMode: Dispatch<SetStateAction<boolean>>
+}

package/contexts/LayoutProvider/index.ts

@@ -0,0 +1,2 @@
+export { LayoutContext, LayoutProvider, DEFAULT_DEMO_PATTERN } from "./LayoutProvider"
+export type { LayoutProviderProps } from "./LayoutProvider.types"

package/contexts/WorkshopProvider/WorkshopProvider.tsx

@@ -0,0 +1,57 @@
+"use client"
+
+import { useState, createContext, useMemo, type FC, type PropsWithChildren } from "react"
+import type { WorkshopProviderProps } from "./WorkshopProvider.types"
+import type { KnobRegistry, KnobValues, KnobSetters } from "../../types/knobs"
+import type { WorkshopComponentStatus } from "../../types/meta"
+import type { WorkshopPageConfig } from "../../types/config"
+
+const DEFAULT_VISIBLE_STATUSES: Array<WorkshopComponentStatus> = ["stable", "nominal"]
+
+interface WorkshopProviderComponentProps {
+	knobs: KnobRegistry
+	componentScope: Record<string, unknown>
+	visibleStatuses?: Array<WorkshopComponentStatus>
+	pages?: Array<WorkshopPageConfig>
+}
+
+const buildDefaultValues = (knobs: KnobRegistry): KnobValues =>
+	Object.fromEntries(Object.entries(knobs).map(([key, def]) => [key, def.defaultValue]))
+
+const WorkshopContext = createContext<WorkshopProviderProps>({
+	knobValues: {},
+	knobSetters: {},
+	componentScope: {},
+	visibleStatuses: DEFAULT_VISIBLE_STATUSES,
+	pages: [],
+})
+
+const WorkshopProvider: FC<PropsWithChildren<WorkshopProviderComponentProps>> = ({
+	knobs,
+	componentScope,
+	visibleStatuses = DEFAULT_VISIBLE_STATUSES,
+	pages = [],
+	children,
+}) => {
+	const [values, setValues] = useState<KnobValues>(() => buildDefaultValues(knobs))
+
+	const knobSetters = useMemo<KnobSetters>(() => {
+		const setters: KnobSetters = {}
+
+		for (const key of Object.keys(knobs)) {
+			setters[key] = (next: string | number | boolean): void => {
+				setValues((prev) => ({ ...prev, [key]: next }))
+			}
+		}
+
+		return setters
+	}, [knobs])
+
+	return (
+		<WorkshopContext.Provider value={{ knobValues: values, knobSetters, componentScope, visibleStatuses, pages }}>
+			{children}
+		</WorkshopContext.Provider>
+	)
+}
+
+export { WorkshopContext, WorkshopProvider }

package/contexts/WorkshopProvider/WorkshopProvider.types.ts

@@ -0,0 +1,11 @@
+import type { KnobValues, KnobSetters } from "../../types/knobs"
+import type { WorkshopComponentStatus } from "../../types/meta"
+import type { WorkshopPageConfig } from "../../types/config"
+
+export interface WorkshopProviderProps {
+	knobValues: KnobValues
+	knobSetters: KnobSetters
+	componentScope: Record<string, unknown>
+	visibleStatuses: Array<WorkshopComponentStatus>
+	pages: Array<WorkshopPageConfig>
+}

package/contexts/WorkshopProvider/index.ts

@@ -0,0 +1,2 @@
+export { WorkshopContext, WorkshopProvider } from "./WorkshopProvider"
+export type { WorkshopProviderProps } from "./WorkshopProvider.types"

package/contexts/index.ts

@@ -0,0 +1,5 @@
+export { LayoutContext, LayoutProvider, DEFAULT_DEMO_PATTERN } from "./LayoutProvider"
+export type { LayoutProviderProps } from "./LayoutProvider"
+
+export { WorkshopContext, WorkshopProvider } from "./WorkshopProvider"
+export type { WorkshopProviderProps } from "./WorkshopProvider"

package/index.ts

@@ -0,0 +1,17 @@
+export type {
+	WorkshopAttributeItem,
+	WorkshopAttributeMeta,
+	WorkshopComponentCategory,
+	WorkshopComponentRegistry,
+	WorkshopComponentStatus,
+	WorkshopPattern,
+} from "./types/meta"
+
+export type { KnobDefinition, KnobRegistry, KnobValues, KnobSetters } from "./types/knobs"
+
+export type { WorkshopConfig, WorkshopPageConfig } from "./types/config"
+
+export { Page } from "./components/Page"
+export type { PageProps } from "./components/Page"
+export { PageBlock } from "./components/PageBlock"
+export type { PageBlockProps } from "./components/PageBlock"

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@heliosgraphics/fx",
+	"version": "0.0.1-alpha.0",
+	"author": "Chris Puska <chris@puska.org>",
+	"description": "Tool building tools",
+	"license": "MIT",
+	"type": "module",
+	"main": "./index.ts",
+	"exports": {
+		".": "./index.ts",
+		"./pages": "./pages/index.ts",
+		"./components": "./components/index.ts",
+		"./contexts": "./contexts/index.ts",
+		"./config": "./config/index.ts"
+	},
+	"files": [
+		"components/**/*",
+		"config/**/*",
+		"contexts/**/*",
+		"pages/**/*",
+		"types/**/*",
+		"index.ts"
+	],
+	"dependencies": {
+		"recat": "0.0.1"
+	},
+	"peerDependencies": {
+		"@heliosgraphics/ui": "2.0.0-alpha.93",
+		"@heliosgraphics/utils": "6.0.0-alpha.11",
+		"next": ">=16.1",
+		"react": ">=19.2",
+		"react-dom": ">=19.2"
+	},
+	"devDependencies": {
+		"@types/node": "^25",
+		"@types/react": "^19",
+		"@types/react-dom": "^19",
+		"prism-react-renderer": "^2.4.1",
+		"typescript": "^5.9.3"
+	}
+}