@heliosgraphics/ui 2.0.0-alpha.100

package/hooks/useChatScroll.tsx

@@ -0,0 +1,98 @@
+"use client"
+
+import { useCallback, useEffect, useRef, useState, type RefObject } from "react"
+
+const SCROLL_THRESHOLD = 1
+
+type ScrollPosition = {
+	top: number
+	bottom: number
+	height: number
+}
+
+export const useChatScroll = (
+	deps: unknown,
+): {
+	ref: RefObject<HTMLDivElement | null>
+	isManual: boolean
+	scrollPos: ScrollPosition
+	onResetManual: () => void
+} => {
+	const [isManual, setManual] = useState<boolean>(false)
+	const [scrollPos, setScrollPos] = useState<ScrollPosition>(() => ({
+		top: 0,
+		bottom: 0,
+		height: 0,
+	}))
+	const ref = useRef<HTMLDivElement>(null)
+	const wasAtBottom = useRef<boolean>(true)
+
+	const scrollToBottom = useCallback((behavior: ScrollBehavior = "auto") => {
+		const element = ref.current
+		if (!element) return
+
+		const { scrollHeight, clientHeight } = element
+		element.scrollTo({
+			top: scrollHeight - clientHeight,
+			behavior,
+		})
+	}, [])
+
+	const onResetManual = useCallback(() => {
+		setManual(false)
+		scrollToBottom("smooth")
+	}, [scrollToBottom])
+
+	const checkScrollable = useCallback(() => {
+		const element = ref.current
+		if (!element) return false
+
+		return element.scrollHeight > element.clientHeight
+	}, [])
+
+	const onScroll = useCallback(() => {
+		const element = ref.current
+		if (!element) return
+
+		const { scrollTop, scrollHeight, clientHeight } = element
+		const distanceFromBottom = scrollHeight - (scrollTop + clientHeight)
+		const atBottom = distanceFromBottom <= SCROLL_THRESHOLD
+
+		setScrollPos({
+			top: scrollTop,
+			bottom: distanceFromBottom,
+			height: scrollHeight,
+		})
+
+		wasAtBottom.current = atBottom
+		setManual(!atBottom && checkScrollable())
+	}, [checkScrollable])
+
+	useEffect(() => {
+		const element = ref.current
+		if (!element) return
+
+		const resizeObserver = new ResizeObserver(() => {
+			if (!checkScrollable()) {
+				setManual(false)
+			}
+			onScroll()
+		})
+
+		resizeObserver.observe(element)
+		element.addEventListener("scroll", onScroll)
+
+		return (): void => {
+			resizeObserver.disconnect()
+			element.removeEventListener("scroll", onScroll)
+		}
+	}, [onScroll, checkScrollable])
+
+	useEffect(() => {
+		if (wasAtBottom.current) {
+			scrollToBottom()
+		}
+	}, [deps, scrollToBottom])
+
+	return { ref, onResetManual, isManual, scrollPos }
+}

package/hooks/useDebounce.tsx

@@ -0,0 +1,19 @@
+"use client"
+
+import { useState, useEffect } from "react"
+
+export const useDebounce = <T,>(value: T, delay: number): T => {
+	const [debouncedValue, setDebouncedValue] = useState<T>(value)
+
+	useEffect(() => {
+		const handler: ReturnType<typeof setTimeout> = setTimeout(() => {
+			setDebouncedValue(value)
+		}, delay)
+
+		return (): void => {
+			globalThis.clearTimeout(handler)
+		}
+	}, [value, delay])
+
+	return debouncedValue
+}

package/hooks/useIntersection.tsx

@@ -0,0 +1,19 @@
+"use client"
+
+import { useState, useEffect, type RefObject } from "react"
+
+export const useIntersection = (ref: RefObject<HTMLElement>): boolean => {
+	const [isIntersecting, setIntersecting] = useState<boolean>(false)
+
+	useEffect(() => {
+		if (!ref?.current) return
+
+		const observer = new IntersectionObserver(([entry]) => setIntersecting(!!entry?.isIntersecting))
+
+		observer.observe(ref.current)
+
+		return (): void => observer.disconnect()
+	}, [ref])
+
+	return isIntersecting
+}

package/hooks/useInterval.tsx

@@ -0,0 +1,27 @@
+"use client"
+
+import { useEffect, useRef } from "react"
+
+export const useInterval = (callback: () => void, delay: number): void => {
+	const savedCallback = useRef<(() => void) | null>(null)
+
+	useEffect(() => {
+		savedCallback.current = callback
+	}, [callback])
+
+	useEffect(() => {
+		const tick = (): void => {
+			savedCallback?.current?.()
+		}
+
+		let id: ReturnType<typeof globalThis.setInterval> | undefined
+
+		if (delay !== null) {
+			id = globalThis.setInterval(tick, delay)
+
+			return (): void => globalThis.clearInterval(id)
+		}
+
+		return (): void => globalThis.clearInterval(id)
+	}, [delay])
+}

package/hooks/useKeyPress.tsx

@@ -0,0 +1,33 @@
+"use client"
+
+import { useEffect, useCallback, useState } from "react"
+
+export const useKeyPress = (targetKey: string): boolean => {
+	const [keyPressed, setKeyPressed] = useState(false)
+
+	const downHandler = useCallback(
+		({ key }: { key: string }) => {
+			if (key === targetKey) setKeyPressed(true)
+		},
+		[targetKey],
+	)
+
+	const upHandler = useCallback(
+		({ key }: { key: string }) => {
+			if (key === targetKey) setKeyPressed(false)
+		},
+		[targetKey],
+	)
+
+	useEffect(() => {
+		globalThis?.addEventListener("keydown", downHandler)
+		globalThis?.addEventListener("keyup", upHandler)
+
+		return (): void => {
+			globalThis?.removeEventListener("keydown", downHandler)
+			globalThis?.removeEventListener("keyup", upHandler)
+		}
+	}, [downHandler, upHandler])
+
+	return keyPressed
+}

package/hooks/useLayoutContext.tsx

@@ -0,0 +1,23 @@
+"use client"
+
+import { useContext } from "react"
+import { LayoutContext } from "../contexts/LayoutContext"
+import type { LayoutContextProps } from "../contexts/LayoutContext"
+
+const DEFAULT_LAYOUT_CONTEXT: LayoutContextProps = {
+	asideRef: { current: null },
+	hasMounted: true,
+	isMenuVisible: true,
+	isWideEnough: true,
+	onAsideClose: () => {},
+	onNavigationToggle: () => {},
+	isNavigationVisible: true,
+}
+
+export const useLayoutContext = (): LayoutContextProps => {
+	const context = useContext(LayoutContext)
+
+	if (!context) return DEFAULT_LAYOUT_CONTEXT
+
+	return context
+}

package/hooks/usePrevious.tsx

@@ -0,0 +1,13 @@
+"use client"
+
+import { useEffect, useRef } from "react"
+
+export const usePrevious = <T,>(value: T): T => {
+	const ref = useRef<T>(value)
+
+	useEffect(() => {
+		ref.current = value
+	}, [value])
+
+	return ref.current
+}

package/hooks/usePrint.tsx

@@ -0,0 +1,31 @@
+"use client"
+
+import { useCallback, useEffect, useState } from "react"
+
+interface UsePrintReturn {
+	isPrinting: boolean
+	print: () => void
+}
+
+export const usePrint = (): UsePrintReturn => {
+	const [isPrinting, setIsPrinting] = useState<boolean>(false)
+
+	useEffect(() => {
+		const handleBeforePrint = (): void => setIsPrinting(true)
+		const handleAfterPrint = (): void => setIsPrinting(false)
+
+		globalThis.addEventListener("beforeprint", handleBeforePrint)
+		globalThis.addEventListener("afterprint", handleAfterPrint)
+
+		return (): void => {
+			globalThis.removeEventListener("beforeprint", handleBeforePrint)
+			globalThis.removeEventListener("afterprint", handleAfterPrint)
+		}
+	}, [])
+
+	const print = useCallback((): void => {
+		globalThis.print()
+	}, [])
+
+	return { isPrinting, print }
+}

package/hooks/useResizeObserver.tsx

@@ -0,0 +1,38 @@
+"use client"
+
+import { useState, useCallback, useRef } from "react"
+
+export const useResizeObserver = (): readonly [(element: HTMLDivElement | null) => void, number] => {
+	const [width, setWidth] = useState(() => {
+		if (typeof globalThis !== "undefined" && "innerWidth" in globalThis) {
+			return globalThis.innerWidth
+		}
+
+		return 0
+	})
+	const resizeObserverRef = useRef<ResizeObserver | null>(null)
+
+	const ref = useCallback((element: HTMLDivElement | null) => {
+		if (resizeObserverRef.current) {
+			resizeObserverRef.current.disconnect()
+		}
+
+		if (element) {
+			resizeObserverRef.current = new ResizeObserver((entries) => {
+				if (entries[0]) {
+					const entryWidth = entries[0].contentRect.width
+					setWidth(entryWidth)
+				}
+			})
+
+			resizeObserverRef.current.observe(element)
+
+			const rect = element.getBoundingClientRect()
+			setWidth(rect.width)
+		} else {
+			setWidth(0)
+		}
+	}, [])
+
+	return [ref, width] as const
+}

package/hooks/useTheme.tsx

@@ -0,0 +1,40 @@
+"use client"
+
+import { useCallback, useEffect, useState } from "react"
+import type { HeliosFixedThemeType } from "../types/themes"
+
+export const useTheme = (): { theme: HeliosFixedThemeType; isDark: boolean; toggleTheme: () => void } => {
+	const [theme, setTheme] = useState<HeliosFixedThemeType | null>(null)
+
+	useEffect(() => {
+		setTheme(getTheme())
+	}, [])
+
+	const getTheme = (): HeliosFixedThemeType => (typeof globalThis !== "undefined" ? globalThis.__theme : "light")
+
+	const toggleTheme = useCallback(() => {
+		const currentIsDark: boolean = getTheme() === "dark"
+		globalThis.__setPreferredTheme?.(currentIsDark ? "light" : "dark")
+	}, [])
+
+	useEffect(() => {
+		if (typeof globalThis === "undefined") return
+
+		const originalOnThemeChange = globalThis.__onThemeChange
+
+		globalThis.__onThemeChange = (newTheme: HeliosFixedThemeType): void => {
+			originalOnThemeChange?.(newTheme)
+			setTheme(newTheme)
+		}
+
+		return (): void => {
+			globalThis.__onThemeChange = originalOnThemeChange
+		}
+	}, [])
+
+	return {
+		theme: theme ?? "light",
+		isDark: theme === "dark",
+		toggleTheme,
+	} as const
+}

package/index.ts

@@ -0,0 +1,96 @@
+// eslint-disable-next-line typescript/triple-slash-reference
+/// <reference path="./globals.d.ts" />
+
+export { Alert } from "./components/Alert"
+export { Breadcrumb } from "./components/Breadcrumb"
+export { Browser } from "./components/Browser"
+export { Button } from "./components/Button"
+export { ButtonGroup } from "./components/ButtonGroup"
+export { Checkbox } from "./components/Checkbox"
+export { Clock } from "./components/Clock"
+export { Column } from "./components/Column"
+export { Confirm } from "./components/Confirm"
+export { DatePicker } from "./components/DatePicker"
+export { Debug } from "./components/Debug"
+export { Details } from "./components/Details"
+export { Dialog } from "./components/Dialog"
+export { Donut } from "./components/Donut"
+export { Dot } from "./components/Dot"
+export { Dropdown } from "./components/Dropdown"
+export { Fieldset } from "./components/Fieldset"
+export { Flex } from "./components/Flex"
+export { Grid } from "./components/Grid"
+export { Heading } from "./components/Heading"
+export { Icon } from "./components/Icon"
+export { Input } from "./components/Input"
+export { Layout } from "./components/Layout"
+export { Loading } from "./components/Loading"
+export { Markdown } from "./components/Markdown"
+export { Masonry } from "./components/Masonry"
+export { Menu } from "./components/Menu"
+export { Overlay } from "./components/Overlay"
+export { Pie } from "./components/Pie"
+export { Pill } from "./components/Pill"
+export { Placeholder } from "./components/Placeholder"
+export { Progress } from "./components/Progress"
+export { Radio } from "./components/Radio"
+export { Range } from "./components/Range"
+export { Segments } from "./components/Segments"
+export { Select } from "./components/Select"
+export { Separator } from "./components/Separator"
+export { Setup } from "./components/Setup"
+export { Shimmer } from "./components/Shimmer"
+export { Slider } from "./components/Slider"
+export { Spacer } from "./components/Spacer"
+export { Table } from "./components/Table"
+export { Tabs } from "./components/Tabs"
+export { Text } from "./components/Text"
+export { Textarea } from "./components/Textarea"
+export { Tile } from "./components/Tile"
+export { Timestamp } from "./components/Timestamp"
+export { Toggle } from "./components/Toggle"
+export { Tooltip } from "./components/Tooltip"
+
+export type { BreadcrumbItem } from "./components/Breadcrumb"
+export type { ButtonGroupProps } from "./components/ButtonGroup"
+export type { ButtonProps } from "./components/Button"
+export type { ColumnProps } from "./components/Column"
+export type { DonutSizeType } from "./components/Donut"
+export type { DropdownProps } from "./components/Dropdown"
+export type { FlexProps, ResponsiveRadiusType } from "./components/Flex"
+export type { HeadingProps } from "./components/Heading"
+export type { MenuComposition } from "./components/Menu"
+export type { PieItem } from "./components/Pie"
+export type { ResultItem } from "./components/shared/ResultList"
+export type { SelectItem } from "./components/Select"
+export type { TextBaseProps, TextProps } from "./components/Text"
+
+export { useChatScroll } from "./hooks/useChatScroll"
+export { useDebounce } from "./hooks/useDebounce"
+export { useIntersection } from "./hooks/useIntersection"
+export { useInterval } from "./hooks/useInterval"
+export { useKeyPress } from "./hooks/useKeyPress"
+export { useLayoutContext } from "./hooks/useLayoutContext"
+export { usePrevious } from "./hooks/usePrevious"
+export { usePrint } from "./hooks/usePrint"
+export { useResizeObserver } from "./hooks/useResizeObserver"
+export { useTheme } from "./hooks/useTheme"
+
+export type { HeliosAppearanceType, HeliosColorType } from "./types/colors"
+export type { HeliosFontFamilyType } from "./types/typography"
+export type { HeliosIconType } from "./types/icons"
+export type { HeliosIntentionType, HeliosEmphasisType } from "./types/intentions"
+export type { HeliosAlignType, HeliosPositionType } from "./types/positions"
+export type { HeliosScaleType, HeliosRadiusType, HeliosSizeType } from "./types/scale"
+export type { HeliosFixedThemeType, HeliosThemeType } from "./types/themes"
+
+export { COLORS } from "./constants/colors"
+export { COMPONENTS } from "./constants/components"
+export { EMPHASES } from "./constants/emphasis"
+export { HOOKS } from "./constants/hooks"
+export { ICONS } from "./constants/icons"
+export { INTENTIONS, INTENTION_COLOR_MAP } from "./constants/intentions"
+export { POSITIONS } from "./constants/positions"
+export { SCALE } from "./constants/scale"
+export { SCOPE } from "./constants/scope"
+export type { HeliosAttributeMeta, HeliosComponentStatusType, HeliosComponentCategoryType } from "./types/meta"

package/package.json

@@ -0,0 +1,67 @@
+{
+	"name": "@heliosgraphics/ui",
+	"version": "2.0.0-alpha.100",
+	"type": "module",
+	"sideEffects": [
+		"*.css",
+		"*.module.css"
+	],
+	"author": "Chris Puska <chris@puska.org>",
+	"private": false,
+	"description": "Helios UI",
+	"main": "./index.ts",
+	"exports": {
+		".": "./index.ts",
+		"./components/*": "./components/*/index.ts",
+		"./constants/*": "./constants/*.ts",
+		"./contexts/*": "./contexts/*/index.ts",
+		"./hooks/*": "./hooks/*.tsx",
+		"./types/*": "./types/*.ts",
+		"./utils/*": "./utils/*.ts",
+		"./css/*": "./css/*.css",
+		"./components.css": "./components.css"
+	},
+	"files": [
+		"components/**/*.*",
+		"constants/*.*",
+		"contexts/**/*.*",
+		"css/**/*.*",
+		"hooks/*.*",
+		"types/*.*",
+		"utils/*.*",
+		"components.css",
+		"globals.d.ts",
+		"index.ts"
+	],
+	"scripts": {
+		"pub:components": "bun publish --access public",
+		"test": "bun test",
+		"test:watch": "bun test --watch",
+		"ts:watch": "tsc --noEmit --incremental --watch"
+	},
+	"dependencies": {
+		"@heliosgraphics/css": "^1.0.0-alpha.5",
+		"@heliosgraphics/icons": "^1.0.0-alpha.11",
+		"@heliosgraphics/utils": "^6.0.0-alpha.9",
+		"marked": "^17.0.3",
+		"marked-linkify-it": "^3.1.14",
+		"marked-xhtml": "^1.0.14"
+	},
+	"devDependencies": {
+		"@testing-library/react": "^16.3.2",
+		"@types/node": "^25",
+		"esbuild": "^0.27.3",
+		"esbuild-css-modules-plugin": "^3.1.5",
+		"glob": "^13.0.6",
+		"jsdom": "^28.1.0",
+		"next": "^16.1.6",
+		"prettier": "^3.8.1",
+		"typescript": "^5.9.3"
+	},
+	"peerDependencies": {
+		"@types/react": "^19",
+		"@types/react-dom": "^19",
+		"react": "^19",
+		"react-dom": "^19"
+	}
+}

package/types/colors.ts

@@ -0,0 +1,13 @@
+export type HeliosColorType =
+	| "aqua"
+	| "blue"
+	| "green"
+	| "orange"
+	| "pink"
+	| "purple"
+	| "red"
+	| "yellow"
+	| "gray"
+	| "olive"
+
+export type HeliosAppearanceType = "light" | "dark"

package/types/icons.ts

@@ -0,0 +1,3 @@
+import { icons } from "@heliosgraphics/icons"
+
+export type HeliosIconType = keyof typeof icons

package/types/intentions.ts

@@ -0,0 +1,13 @@
+export type HeliosIntentionType =
+	| "action"
+	| "automation"
+	| "confirmation"
+	| "danger"
+	| "highlight"
+	| "neutral"
+	| "organic"
+	| "question"
+	| "success"
+	| "warning"
+
+export type HeliosEmphasisType = "primary" | "secondary" | "tertiary" | "inherit"

package/types/meta.ts

@@ -0,0 +1,24 @@
+interface HeliosAttributeItem<T> {
+	alias?: keyof T
+	default?: number | string
+	description?: string
+	isOptional?: boolean
+	type: string
+}
+
+export type HeliosComponentStatusType = "stable" | "nominal" | "internal" | "experimental"
+export type HeliosComponentCategoryType = "core" | "layout" | "content" | "pattern" | "meta"
+
+export interface HeliosPattern {
+	id: string
+	description: string
+	content: string
+}
+
+export type HeliosAttributeMeta<T> = Record<keyof T, HeliosAttributeItem<T>> & {
+	_category: HeliosComponentCategoryType
+	_extends?: Array<string>
+	_patterns: Array<HeliosPattern>
+	_status: HeliosComponentStatusType
+	_type?: "composite" | "hoc"
+}

package/types/positions.ts

@@ -0,0 +1,3 @@
+export type HeliosAlignType = "left" | "center" | "right"
+
+export type HeliosPositionType = "top-left" | "top-right" | "bottom-right" | "bottom-left"

package/types/scale.ts

@@ -0,0 +1,29 @@
+export type HeliosScaleType =
+	| "px"
+	| 0
+	| 1
+	| 2
+	| 3
+	| 4
+	| 6
+	| 8
+	| 10
+	| 12
+	| 14
+	| 16
+	| 18
+	| 20
+	| 22
+	| 24
+	| 26
+	| 28
+	| 30
+	| 32
+	| 48
+	| 64
+	| 80
+	| 96
+
+export type HeliosRadiusType = "none" | "small" | "normal" | "large"
+
+export type HeliosSizeType = "normal" | "small" | "tiny"

package/types/scope.ts

@@ -0,0 +1,67 @@
+import type { BreadcrumbItem } from "../components/Breadcrumb/Breadcrumb.types"
+import type { ButtonGroupProps } from "../components/ButtonGroup/ButtonGroup.types"
+import type { DonutSizeType } from "../components/Donut/Donut.types"
+import type { PieItem } from "../components/Pie/Pie.types"
+import type { ResultItem } from "../components/shared/ResultList/ResultList.types"
+import type { SelectItem } from "../components/Select/Select.types"
+import type { HeliosColorType } from "./colors"
+import type { HeliosIconType } from "./icons"
+import type { HeliosEmphasisType, HeliosIntentionType } from "./intentions"
+import type { HeliosPositionType } from "./positions"
+import type { HeliosScaleType, HeliosSizeType } from "./scale"
+
+export interface Scope {
+	APPEARANCE: "light" | "dark"
+	BREADCRUMB_ITEMS: Array<BreadcrumbItem>
+	BUTTONGROUP_ALIGN: ButtonGroupProps["align"]
+	CHECKBOX_LABEL: string
+	CHILDREN: string
+	COLOR: HeliosColorType
+	COLOR_ACCENT: HeliosColorType
+	DATE: string
+	DATE_FORMAT: string
+	DONUT_SIZE: DonutSizeType
+	EMPHASIS: HeliosEmphasisType
+	FUNCTION: () => void
+	GAP: HeliosScaleType
+	HELPER_TEXT: string
+	ICON: HeliosIconType
+	ICON_ACCENT: HeliosIconType
+	INPUT_LABEL: string
+	INTENT: HeliosIntentionType
+	INTENT_PARAGRAPH: string
+	INTENT_TITLE: string
+	IS_ACTIVE: boolean
+	IS_CENTERED: boolean
+	IS_CHECKED: boolean
+	IS_COLUMN: boolean
+	IS_DISABLED: boolean
+	IS_LOADING: boolean
+	IS_NARROW: boolean
+	IS_OPEN: boolean
+	IS_ROUND: boolean
+	IS_ROUNDED: boolean
+	MARKDOWN: string
+	ON_RADIO_CHANGE: () => void
+	ON_SELECT_ITEM: (item: SelectItem) => void
+	ON_TEXTAREA_CHANGE: () => void
+	ON_TEXT_CHANGE: () => void
+	ON_TOGGLE_OPEN: () => void
+	PERCENTAGE: number
+	PIE_ITEMS: Array<PieItem>
+	PILL_LABEL: string
+	POSITION: HeliosPositionType
+	RADIO: string
+	RADIO_LABEL: string
+	RESULT_LIST_ITEMS: Array<ResultItem>
+	SCALE: HeliosScaleType
+	SELECT_ITEMS: Array<SelectItem>
+	SIZE: HeliosSizeType
+	TAB_ITEMS: Array<string>
+	TAB_SECTIONS: Array<unknown>
+	TEXTAREA: string
+	TEXTAREA_LABEL: string
+	TEXTAREA_PLACEHOLDER: string
+	TEXT_LABEL: string
+	TEXT_VALUE: string
+}

package/types/themes.ts

@@ -0,0 +1,2 @@
+export type HeliosFixedThemeType = "dark" | "light"
+export type HeliosThemeType = HeliosFixedThemeType | "system"