@heliosgraphics/fx 0.0.1-alpha.0

package/components/LiveComponents/LiveComponents.tsx

@@ -0,0 +1,116 @@
+"use client"
+
+import { Segments, Flex, Separator, Toggle } from "@heliosgraphics/ui"
+import { LiveComponent } from "./_components/LiveComponent"
+import { GridBackground } from "./_components/GridBackground"
+import { PermutationsGrid } from "./_components/PermutationsGrid"
+import { useContext, useEffect, useMemo } from "react"
+import { LayoutContext, DEFAULT_DEMO_PATTERN } from "../../contexts/LayoutProvider"
+import { WorkshopContext } from "../../contexts/WorkshopProvider"
+import type { FC, ReactNode } from "react"
+import type { LiveComponentsProps } from "./LiveComponents.types"
+import { toScreamingCase } from "./LiveComponents.utils"
+
+export const LiveComponents: FC<LiveComponentsProps> = ({ demoComponent, demoMeta, knobs }) => {
+	const { activeDemoPattern, setActiveDemoPattern, isPermutationsMode, setIsPermutationsMode } =
+		useContext(LayoutContext)
+	const { knobValues, knobSetters, componentScope } = useContext(WorkshopContext)
+
+	const isDefaultPattern: boolean = activeDemoPattern === DEFAULT_DEMO_PATTERN
+	const hasWorkshopBackground = knobValues["hasWorkshopBackground"] === true
+	const canShowPermutations: boolean = !isDefaultPattern
+
+	const onBackgroundToggle = (): void => {
+		const setter = knobSetters["hasWorkshopBackground"]
+
+		if (setter) setter(!hasWorkshopBackground)
+	}
+
+	const onTogglePermutations = (): void => {
+		if (isDefaultPattern) return
+
+		setIsPermutationsMode((prev) => !prev)
+	}
+
+	const onSelectDemo = (): void => {
+		setActiveDemoPattern(DEFAULT_DEMO_PATTERN)
+		setIsPermutationsMode(false)
+	}
+
+	const hasDemoComponent: boolean = !!demoComponent
+	const firstPatternContent: string | undefined = demoMeta._patterns[0]?.content
+
+	useEffect(() => {
+		if (!hasDemoComponent && firstPatternContent) {
+			setActiveDemoPattern(firstPatternContent)
+		}
+
+		return (): void => {
+			setActiveDemoPattern(DEFAULT_DEMO_PATTERN)
+			setIsPermutationsMode(false)
+		}
+	}, [hasDemoComponent, firstPatternContent, setActiveDemoPattern, setIsPermutationsMode])
+
+	const fullScope = useMemo<Record<string, unknown>>(() => {
+		const scope: Record<string, unknown> = { ...componentScope }
+
+		for (const [key, value] of Object.entries(knobValues)) {
+			if (knobs[key]?.isInternal) continue
+
+			scope[toScreamingCase(key)] = value
+		}
+
+		return scope
+	}, [componentScope, knobValues, knobs])
+
+	const renderContent = (): ReactNode => {
+		if (isDefaultPattern) return demoComponent
+
+		if (isPermutationsMode) {
+			return <PermutationsGrid code={activeDemoPattern} scope={fullScope} knobs={knobs} knobValues={knobValues} />
+		}
+
+		return <LiveComponent code={activeDemoPattern} scope={fullScope} />
+	}
+
+	return (
+		<Flex isColumn={true}>
+			<Flex gap={8} padding={8} isYCentered={true} isBetween={true}>
+				<Flex gap={8} isYCentered={true}>
+					<Segments isSmall={true}>
+						{demoComponent && (
+							<Segments.Button
+								key="demoComponent"
+								value="demo"
+								iconLeft="arrow-4way"
+								isActive={isDefaultPattern && !isPermutationsMode}
+								onClick={onSelectDemo}
+							/>
+						)}
+						{demoMeta._patterns.map((p, key) => {
+							const onSelectPattern = (): void => setActiveDemoPattern(p.content)
+							const isActive: boolean = !isDefaultPattern && !isPermutationsMode && activeDemoPattern === p.content
+
+							return <Segments.Button key={key} value={p.description} isActive={isActive} onClick={onSelectPattern} />
+						})}
+					</Segments>
+					{canShowPermutations && (
+						<Segments isSmall={true}>
+							<Segments.Button
+								value="Permutations"
+								iconLeft="layout-bottom"
+								isActive={isPermutationsMode}
+								onClick={onTogglePermutations}
+							/>
+						</Segments>
+					)}
+				</Flex>
+				{knobSetters["hasWorkshopBackground"] && (
+					<Toggle label="Show grid" isChecked={hasWorkshopBackground} isSmall={true} onChange={onBackgroundToggle} />
+				)}
+			</Flex>
+			<Separator emphasis="secondary" />
+			<GridBackground>{renderContent()}</GridBackground>
+		</Flex>
+	)
+}

package/components/LiveComponents/LiveComponents.types.ts

@@ -0,0 +1,9 @@
+import type { WorkshopAttributeMeta } from "../../types/meta"
+import type { KnobRegistry } from "../../types/knobs"
+import type { ReactNode } from "react"
+
+export interface LiveComponentsProps {
+	demoComponent?: ReactNode
+	demoMeta: WorkshopAttributeMeta<unknown>
+	knobs: KnobRegistry
+}

package/components/LiveComponents/LiveComponents.utils.ts

@@ -0,0 +1 @@
+export const toScreamingCase = (str: string): string => str.replace(/([a-z])([A-Z])/g, "$1_$2").toUpperCase()

package/components/LiveComponents/_components/GridBackground/GridBackground.module.css

@@ -0,0 +1,14 @@
+.gridBackground {
+	margin-top: -1px;
+	margin-left: -1px;
+
+	background-color: var(--ui-bg);
+	box-shadow: inset 0 0 0 8px var(--ui-bg);
+}
+
+.gridBackgroundAlt {
+	background-image:
+		linear-gradient(90deg, var(--ui-border-secondary) 0, transparent 1px),
+		linear-gradient(180deg, var(--ui-border-secondary) 0, transparent 1px);
+	background-size: 8px 8px;
+}

package/components/LiveComponents/_components/GridBackground/GridBackground.tsx

@@ -0,0 +1,18 @@
+"use client"
+
+import { getClasses } from "@heliosgraphics/utils"
+import styles from "./GridBackground.module.css"
+import { useContext, type FC } from "react"
+import type { GridBackgroundProps } from "./GridBackground.types"
+import { WorkshopContext } from "../../../../contexts/WorkshopProvider"
+
+export const GridBackground: FC<GridBackgroundProps> = ({ children }) => {
+	const { knobValues } = useContext(WorkshopContext)
+	const hasWorkshopBackground = knobValues["hasWorkshopBackground"] === true
+
+	const gridBackgroundClasses: string = getClasses(styles.gridBackground, {
+		[styles.gridBackgroundAlt]: hasWorkshopBackground,
+	})
+
+	return <div className={gridBackgroundClasses}>{children}</div>
+}

package/components/LiveComponents/_components/GridBackground/GridBackground.types.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from "react"
+
+export interface GridBackgroundProps {
+	children: ReactNode
+}

package/components/LiveComponents/_components/GridBackground/index.ts

@@ -0,0 +1 @@
+export { GridBackground } from "./GridBackground"

package/components/LiveComponents/_components/LiveComponent/LiveComponent.module.css

@@ -0,0 +1,45 @@
+.liveEditor {
+	background-color: var(--ui-bg-primary);
+}
+
+.liveEditor pre {
+	position: relative;
+
+	padding: 24px 24px 24px 0 !important;
+
+	border-top: 1px solid var(--ui-border-secondary);
+
+	counter-reset: token-line;
+}
+
+.liveEditor pre:before {
+	position: absolute;
+	top: 0;
+	left: 0;
+	z-index: 0;
+
+	height: 100%;
+	padding-block: 16px;
+	width: 40px;
+
+	background-color: var(--ui-bg-secondary);
+	border-right: 1px solid var(--ui-border-secondary);
+	content: " ";
+}
+
+.liveEditor pre > span::before {
+	position: relative;
+	z-index: 1;
+
+	justify-content: flex-end;
+	display: inline-flex;
+	margin-right: 16px;
+	min-width: 40px;
+	padding: 0 8px;
+	width: 40px;
+
+	color: var(--ui-text-tertiary);
+
+	counter-increment: token-line;
+	content: counter(token-line);
+}

package/components/LiveComponents/_components/LiveComponent/LiveComponent.tsx

@@ -0,0 +1,63 @@
+"use client"
+
+import styles from "./LiveComponent.module.css"
+import type { LiveComponentProps } from "./LiveComponent.types"
+import type { PrismTheme } from "prism-react-renderer"
+import { LiveProvider, LiveEditor, LiveError, LivePreview } from "recat"
+import { Flex } from "@heliosgraphics/ui"
+import { getClasses } from "@heliosgraphics/utils"
+import type { FC } from "react"
+
+const PRISM_THEME: PrismTheme = {
+	plain: {
+		backgroundColor: "var(--ui-bg)",
+		color: "var(--ui-text-secondary)",
+	},
+	styles: [
+		{
+			types: ["comment", "prolog", "doctype", "cdata", "punctuation"],
+			style: { color: "var(--ui-text-secondary)" },
+		},
+		{
+			types: [
+				"boolean",
+				"string",
+				"entity",
+				"url",
+				"attr-value",
+				"keyword",
+				"control",
+				"directive",
+				"unit",
+				"statement",
+				"regex",
+				"at-rule",
+				"placeholder",
+				"variable",
+				"script",
+			],
+			style: {
+				color: "hsl(var(--orange-hue), var(--orange-saturation), 50%)",
+				fontWeight: "700",
+			},
+		},
+	],
+}
+
+export const LiveComponent: FC<LiveComponentProps> = ({ code, scope }) => {
+	const liveEditorClasses: string = getClasses(styles.liveEditor, "mono tiny", {})
+
+	if (!code) return null
+
+	return (
+		<Flex isColumn={true}>
+			<LiveProvider code={code} scope={scope} theme={PRISM_THEME}>
+				<Flex isColumn={true} gap={12} padding={16}>
+					<LiveError />
+					<LivePreview />
+				</Flex>
+				<LiveEditor className={liveEditorClasses} disabled />
+			</LiveProvider>
+		</Flex>
+	)
+}

package/components/LiveComponents/_components/LiveComponent/LiveComponent.types.ts

@@ -0,0 +1,4 @@
+export interface LiveComponentProps {
+	code?: string
+	scope: Record<string, unknown>
+}

package/components/LiveComponents/_components/LiveComponent/index.ts

@@ -0,0 +1 @@
+export { LiveComponent } from "./LiveComponent"

package/components/LiveComponents/_components/PermutationsGrid/PermutationsGrid.module.css

@@ -0,0 +1,28 @@
+.permutationsGrid {
+	display: grid;
+	grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+	gap: 1px;
+	/*background-color: var(--ui-border-secondary);*/
+}
+
+.permutationsCell {
+	display: flex;
+	flex-direction: column;
+	background-color: var(--ui-bg);
+	overflow: hidden;
+}
+
+.permutationsCellPreview {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	padding: 16px;
+	flex: 1;
+	min-height: 80px;
+}
+
+.permutationsCellLabel {
+	padding: 4px 8px;
+	background-color: var(--ui-bg-secondary);
+	border-top: 1px solid var(--ui-border-secondary);
+}

package/components/LiveComponents/_components/PermutationsGrid/PermutationsGrid.tsx

@@ -0,0 +1,117 @@
+"use client"
+
+import styles from "./PermutationsGrid.module.css"
+import { LiveProvider, LivePreview, LiveError } from "recat"
+import { Checkbox, Flex, Text } from "@heliosgraphics/ui"
+import { useState, useEffect, useMemo, useCallback } from "react"
+import type { FC, ChangeEvent } from "react"
+import type { PermutationsGridProps } from "./PermutationsGrid.types"
+import type { Combination } from "./PermutationsGrid.utils"
+import { DEFAULT_AXIS_COUNT, getPatternKnobNames, getCartesianProduct } from "./PermutationsGrid.utils"
+import { toScreamingCase } from "../../LiveComponents.utils"
+
+export const PermutationsGrid: FC<PermutationsGridProps> = ({ code, scope, knobs }) => {
+	const relevantKnobNames: Array<string> = useMemo(
+		() =>
+			getPatternKnobNames(
+				code,
+				Object.keys(knobs).filter((k) => !knobs[k]?.isInternal),
+			),
+		[code, knobs],
+	)
+
+	const [activeAxes, setActiveAxes] = useState<Array<string>>(() => relevantKnobNames.slice(0, DEFAULT_AXIS_COUNT))
+
+	useEffect(() => {
+		const validAxes: Array<string> = activeAxes.filter((axis) => relevantKnobNames.includes(axis))
+
+		if (validAxes.length !== activeAxes.length) {
+			const nextAxes: Array<string> = validAxes.length ? validAxes : relevantKnobNames.slice(0, DEFAULT_AXIS_COUNT)
+			setActiveAxes(nextAxes)
+		}
+	}, [relevantKnobNames, activeAxes])
+
+	const onToggleAxis = useCallback(
+		(name: string) =>
+			(_event: ChangeEvent<HTMLInputElement>): void => {
+				setActiveAxes((prev) => {
+					if (prev.includes(name)) {
+						if (prev.length <= 1) return prev
+						return prev.filter((axis) => axis !== name)
+					}
+
+					return [...prev, name]
+				})
+			},
+		[],
+	)
+
+	const combinations: Array<Combination> = useMemo(() => {
+		const axes = activeAxes.map((name) => ({ name, values: knobs[name]?.values ?? [] }))
+		return getCartesianProduct(axes)
+	}, [activeAxes, knobs])
+
+	const buildCellScope = useCallback(
+		(combination: Combination): Record<string, unknown> => {
+			const cellScope: Record<string, unknown> = { ...scope }
+
+			for (const [key, value] of Object.entries(combination)) {
+				cellScope[toScreamingCase(key)] = value
+			}
+
+			return cellScope
+		},
+		[scope],
+	)
+
+	const getCombinationLabel = useCallback(
+		(combination: Combination): string => activeAxes.map((axis) => String(combination[axis])).join(" · "),
+		[activeAxes],
+	)
+
+	if (!relevantKnobNames.length) {
+		return (
+			<Flex padding={16}>
+				<Text emphasis="secondary" type="small">
+					No permutable knobs detected in this pattern.
+				</Text>
+			</Flex>
+		)
+	}
+
+	return (
+		<Flex isColumn={true}>
+			<Flex padding={8} gap={8} isYCentered={true} isWrapped={true}>
+				<Text type="tiny" emphasis="secondary">
+					Axes:
+				</Text>
+				{relevantKnobNames.map((name) => (
+					<Checkbox
+						key={name}
+						label={knobs[name]?.label ?? name}
+						isChecked={activeAxes.includes(name)}
+						onChange={onToggleAxis(name)}
+						isSmall={true}
+					/>
+				))}
+			</Flex>
+			<div className={styles.permutationsGrid}>
+				{combinations.map((combination, index) => (
+					<div key={index} className={styles.permutationsCell}>
+						<div className={styles.permutationsCellPreview}>
+							<LiveProvider code={code} scope={buildCellScope(combination)}>
+								<LiveError />
+								<LivePreview />
+							</LiveProvider>
+						</div>
+						<div className={styles.permutationsCellLabel}>
+							<Text type="tiny" emphasis="secondary">
+								{getCombinationLabel(combination)}
+							</Text>
+						</div>
+					</div>
+				))}
+			</div>
+		</Flex>
+	)
+}

package/components/LiveComponents/_components/PermutationsGrid/PermutationsGrid.types.ts

@@ -0,0 +1,8 @@
+import type { KnobRegistry, KnobValues } from "../../../../types/knobs"
+
+export interface PermutationsGridProps {
+	code: string
+	scope: Record<string, unknown>
+	knobs: KnobRegistry
+	knobValues: KnobValues
+}

package/components/LiveComponents/_components/PermutationsGrid/PermutationsGrid.utils.ts

@@ -0,0 +1,24 @@
+import { toScreamingCase } from "../../LiveComponents.utils"
+
+type KnobValue = string | number | boolean
+
+export type Combination = Record<string, KnobValue>
+
+export const DEFAULT_AXIS_COUNT: number = 2
+
+export const getPatternKnobNames = (code: string, knobKeys: Array<string>): Array<string> => {
+	return knobKeys.filter((key) => {
+		const screamingKey: string = toScreamingCase(key)
+		return code.includes(`{${screamingKey}}`) || code.includes(`=${screamingKey}`)
+	})
+}
+
+export const getCartesianProduct = (axes: Array<{ name: string; values: Array<KnobValue> }>): Array<Combination> => {
+	if (!axes.length) return []
+
+	return axes.reduce<Array<Combination>>(
+		(combinations, axis) =>
+			combinations.flatMap((combo) => axis.values.map((value) => ({ ...combo, [axis.name]: value }))),
+		[{}],
+	)
+}

package/components/LiveComponents/_components/PermutationsGrid/index.ts

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

package/components/LiveComponents/index.ts

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

package/components/Page/Page.tsx

@@ -0,0 +1,52 @@
+"use client"
+
+import { Flex, Text, Heading, Separator } from "@heliosgraphics/ui"
+import type { HeliosScaleType } from "@heliosgraphics/ui"
+import type { FC } from "react"
+import type { PageProps } from "./Page.types"
+
+export const Page: FC<PageProps> = ({
+	children,
+	description,
+	breadcrumb,
+	disabledPadding,
+	footer,
+	header,
+	contentFlexProps,
+	title,
+}) => {
+	const commonFlexProps = {
+		isColumn: true as const,
+		gap: disabledPadding ? (0 as const) : (16 as const),
+		padding: disabledPadding ? (0 as const) : ([8, 16, 24] as [HeliosScaleType, HeliosScaleType, HeliosScaleType]),
+		withBackground: "primary" as const,
+		...contentFlexProps,
+	}
+
+	return (
+		<>
+			{header}
+			<Separator emphasis="tertiary" />
+			<Flex {...commonFlexProps}>
+				{title && (
+					<Flex isColumn={true} padding={disabledPadding ? 16 : 0}>
+						<Flex isYCentered={true} gap={4} isBetween={true}>
+							{breadcrumb}
+						</Flex>
+						<Heading level={0}>{title}</Heading>
+					</Flex>
+				)}
+				{description && <Text type="paragraph">{description}</Text>}
+			</Flex>
+			<Separator emphasis="tertiary" />
+			<Flex {...commonFlexProps}>{children}</Flex>
+			{footer ?? (
+				<Flex withBackground="primary" padding={16} gap={4} isBetween={true} isYCentered={true}>
+					<Text type="tiny" emphasis="tertiary">
+						&copy; {new Date().getFullYear()}
+					</Text>
+				</Flex>
+			)}
+		</>
+	)
+}

package/components/Page/Page.types.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react"
+import type { FlexProps } from "@heliosgraphics/ui"
+
+export interface PageProps {
+	breadcrumb?: ReactNode | undefined
+	children?: ReactNode | undefined
+	description?: string | undefined
+	disabledPadding?: boolean | undefined
+	footer?: ReactNode | undefined
+	header?: ReactNode | undefined
+	contentFlexProps?: Partial<FlexProps> | undefined
+	title?: string | undefined
+}

package/components/Page/index.ts

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

package/components/PageBlock/PageBlock.tsx

@@ -0,0 +1,16 @@
+import { Flex, Heading } from "@heliosgraphics/ui"
+import type { FC } from "react"
+import type { PageBlockProps } from "./PageBlock.types"
+
+export const PageBlock: FC<PageBlockProps> = ({ children, title }) => {
+	return (
+		<Flex isColumn={true} gap={8}>
+			{title && (
+				<Heading level={2} fontWeight="semibold">
+					{title}
+				</Heading>
+			)}
+			{children}
+		</Flex>
+	)
+}

package/components/PageBlock/PageBlock.types.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from "react"
+
+export interface PageBlockProps {
+	children: ReactNode
+	title?: string
+}

package/components/PageBlock/index.ts

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

package/components/PropsTable/PropsTable.tsx

@@ -0,0 +1,84 @@
+"use client"
+
+import { type ReactNode, useContext, type FC } from "react"
+import { Text, Flex, Table, Pill, Separator } from "@heliosgraphics/ui"
+import { WorkshopContext } from "../../contexts/WorkshopProvider"
+import { LayoutContext, DEFAULT_DEMO_PATTERN } from "../../contexts/LayoutProvider"
+import { getEditorComponent } from "./PropsTable.utils"
+import type { PropsTableProps } from "./PropsTable.types"
+
+export const PropsTable: FC<PropsTableProps> = ({ meta, knobs }) => {
+	const context = useContext(WorkshopContext)
+	const { activeDemoPattern } = useContext(LayoutContext)
+
+	if (!meta) return null
+
+	const renderRow = ([name, value]: [string, unknown], key: number): ReactNode => {
+		const row = value as Record<string, unknown>
+		const type: string = (row?.["type"] as string) ?? row?.toString?.() ?? "Unknown"
+		const isExtends: boolean = name === "_extends"
+		const isRequired: boolean = !isExtends && !row?.["isOptional"]
+
+		if ((name.startsWith("_") && !isExtends) || row?.["alias"] != null) return null
+
+		const isDisabled: boolean =
+			activeDemoPattern !== DEFAULT_DEMO_PATTERN && !activeDemoPattern.toLowerCase().includes(`${name}=`.toLowerCase())
+
+		const editorComponent = getEditorComponent(
+			name,
+			type,
+			row?.["knob"] as string | undefined,
+			knobs,
+			context,
+			isDisabled,
+		)
+
+		return (
+			<tr key={key} className={isExtends ? "ui-bg-secondary" : ""}>
+				<td>
+					<Flex isYCentered={true} gap={4}>
+						{isExtends ? <em>extends</em> : name}
+						{isRequired && (
+							<Flex>
+								<Pill color="orange" label="Required" size="tiny" isMono={true} />
+							</Flex>
+						)}
+					</Flex>
+				</td>
+				<td>
+					<Flex gap={8} isYCentered={true} isBetween={true}>
+						<Pill label={type} color="gray" size="tiny" isMono={true} />
+						{editorComponent}
+					</Flex>
+				</td>
+				<td>
+					<Text type="tiny" emphasis="secondary">
+						{(row?.["default"] as string) || "-"}
+					</Text>
+				</td>
+				<td>
+					<Text type="tiny" emphasis="secondary">
+						{(row?.["description"] as string) || "-"}
+					</Text>
+				</td>
+			</tr>
+		)
+	}
+
+	return (
+		<>
+			<Table isMonoHeader={true}>
+				<thead>
+					<tr>
+						<th scope="col">Name</th>
+						<th scope="col">Type</th>
+						<th scope="col">Default</th>
+						<th scope="col">Description</th>
+					</tr>
+				</thead>
+				<tbody>{Object.entries(meta).map(renderRow)}</tbody>
+			</Table>
+			<Separator emphasis="secondary" />
+		</>
+	)
+}

package/components/PropsTable/PropsTable.types.ts

@@ -0,0 +1,7 @@
+import type { WorkshopAttributeMeta } from "../../types/meta"
+import type { KnobRegistry } from "../../types/knobs"
+
+export interface PropsTableProps {
+	meta: WorkshopAttributeMeta<unknown>
+	knobs: KnobRegistry
+}