@heliosgraphics/ui 2.0.0-alpha.62

package/css/feat.responsive.css

@@ -0,0 +1,162 @@
+@media (min-width: 641px) and (max-width: 960px) {
+	.tablet\:hidden {
+		display: none !important;
+	}
+	.tablet\:p-0 {
+		padding: 0 !important;
+	}
+	.tablet\:p-1 {
+		padding: var(--space-1) !important;
+	}
+	.tablet\:p-2 {
+		padding: var(--space-2) !important;
+	}
+	.tablet\:p-3 {
+		padding: var(--space-3) !important;
+	}
+	.tablet\:p-4 {
+		padding: var(--space-4) !important;
+	}
+	.tablet\:p-5 {
+		padding: var(--space-5) !important;
+	}
+	.tablet\:p-6 {
+		padding: var(--space-6) !important;
+	}
+	.tablet\:p-7 {
+		padding: var(--space-7) !important;
+	}
+	.tablet\:p-8 {
+		padding: var(--space-8) !important;
+	}
+	.tablet\:p-9 {
+		padding: var(--space-9) !important;
+	}
+	.tablet\:p-10 {
+		padding: var(--space-10) !important;
+	}
+	.tablet\:p-11 {
+		padding: var(--space-11) !important;
+	}
+	.tablet\:p-12 {
+		padding: var(--space-12) !important;
+	}
+	.tablet\:p-13 {
+		padding: var(--space-13) !important;
+	}
+	.tablet\:p-14 {
+		padding: var(--space-14) !important;
+	}
+	.tablet\:p-15 {
+		padding: var(--space-15) !important;
+	}
+	.tablet\:p-16 {
+		padding: var(--space-16) !important;
+	}
+	.tablet\:p-24 {
+		padding: var(--space-24) !important;
+	}
+	.tablet\:p-32 {
+		padding: var(--space-32) !important;
+	}
+	.tablet\:p-40 {
+		padding: var(--space-40) !important;
+	}
+	.tablet\:p-48 {
+		padding: var(--space-48) !important;
+	}
+
+	.tablet\:radius-none {
+		border-radius: var(--radius-none) !important;
+	}
+	.tablet\:radius-small {
+		border-radius: var(--radius-small) !important;
+	}
+	.tablet\:radius-normal {
+		border-radius: var(--radius-normal) !important;
+	}
+	.tablet\:radius-large {
+		border-radius: var(--radius-large) !important;
+	}
+}
+
+@media (min-width: 0) and (max-width: 640px) {
+	.mobile\:hidden {
+		display: none !important;
+	}
+	.mobile\:p-0 {
+		padding: 0 !important;
+	}
+	.mobile\:p-1 {
+		padding: var(--space-1) !important;
+	}
+	.mobile\:p-2 {
+		padding: var(--space-2) !important;
+	}
+	.mobile\:p-3 {
+		padding: var(--space-3) !important;
+	}
+	.mobile\:p-4 {
+		padding: var(--space-4) !important;
+	}
+	.mobile\:p-5 {
+		padding: var(--space-5) !important;
+	}
+	.mobile\:p-6 {
+		padding: var(--space-6) !important;
+	}
+	.mobile\:p-7 {
+		padding: var(--space-7) !important;
+	}
+	.mobile\:p-8 {
+		padding: var(--space-8) !important;
+	}
+	.mobile\:p-9 {
+		padding: var(--space-9) !important;
+	}
+	.mobile\:p-10 {
+		padding: var(--space-10) !important;
+	}
+	.mobile\:p-11 {
+		padding: var(--space-11) !important;
+	}
+	.mobile\:p-12 {
+		padding: var(--space-12) !important;
+	}
+	.mobile\:p-13 {
+		padding: var(--space-13) !important;
+	}
+	.mobile\:p-14 {
+		padding: var(--space-14) !important;
+	}
+	.mobile\:p-15 {
+		padding: var(--space-15) !important;
+	}
+	.mobile\:p-16 {
+		padding: var(--space-16) !important;
+	}
+	.mobile\:p-24 {
+		padding: var(--space-24) !important;
+	}
+	.mobile\:p-32 {
+		padding: var(--space-32) !important;
+	}
+	.mobile\:p-40 {
+		padding: var(--space-40) !important;
+	}
+	.mobile\:p-48 {
+		padding: var(--space-48) !important;
+	}
+	.mobile\:radius-none {
+		border-radius: var(--radius-none) !important;
+	}
+	.mobile\:radius-small {
+		border-radius: var(--radius-small) !important;
+	}
+	.mobile\:radius-normal {
+		border-radius: var(--radius-normal) !important;
+	}
+	.mobile\:radius-large {
+		border-radius: var(--radius-large) !important;
+	}
+}

package/globals.d.ts

@@ -0,0 +1,2 @@
+declare module "*.module.css"
+declare module "*.css"

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 = (value: unknown, delay: number): unknown => {
+	const [debouncedValue, setDebouncedValue] = useState<unknown>(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,15 @@
+"use client"
+
+import { useContext } from "react"
+import { LayoutContext } from "../contexts/LayoutContext"
+import type { LayoutContextProps } from "../contexts/LayoutContext"
+
+export const useLayoutContext = (): LayoutContextProps => {
+	const context = useContext(LayoutContext)
+
+	if (!context) {
+		throw new Error("useLayoutContext must be used within a LayoutProvider")
+	}
+
+	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/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 width = entries[0].contentRect.width
+					setWidth(width)
+				}
+			})
+
+			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 { HeliosThemeType } from ".."
+
+export const useTheme = (): { theme: HeliosThemeType; isDark: boolean; toggleTheme: () => void } => {
+	const [theme, setTheme] = useState<HeliosThemeType | null>(null)
+
+	useEffect(() => {
+		setTheme(getTheme())
+	}, [])
+
+	const getTheme = (): HeliosThemeType => (typeof globalThis !== "undefined" ? globalThis.__theme : "light")
+
+	const toggleTheme = useCallback(() => {
+		const currentIsDark = getTheme() === "dark"
+		globalThis.__setPreferredTheme?.(currentIsDark ? "light" : "dark")
+	}, [])
+
+	useEffect(() => {
+		if (typeof globalThis === "undefined") return
+
+		const originalOnThemeChange = globalThis.__onThemeChange
+
+		globalThis.__onThemeChange = (newTheme: HeliosThemeType): 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,86 @@
+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 { 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 { useIntersection } from "./hooks/useIntersection"
+export { useLayoutContext } from "./hooks/useLayoutContext"
+export { usePrevious } from "./hooks/usePrevious"
+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 { 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,63 @@
+{
+	"name": "@heliosgraphics/ui",
+	"version": "2.0.0-alpha.62",
+	"type": "module",
+	"author": "Chris Puska <chris@puska.org>",
+	"private": false,
+	"description": "Helios UI",
+	"main": "./index.ts",
+	"files": [
+		"components/**/*.*",
+		"constants/*.*",
+		"contexts/**/*.*",
+		"css/**/*.*",
+		"hooks/*.*",
+		"types/*.*",
+		"utils/*.*",
+		"components.css",
+		"globals.d.ts",
+		"index.ts"
+	],
+	"scripts": {
+		"pub:components": "bun publish --access public",
+		"test": "NODE_ENV=test vitest run",
+		"test:coverage": "NODE_ENV=test vitest run --coverage",
+		"test:update": "NODE_ENV=test vitest run --update",
+		"test:watch": "NODE_ENV=test vitest",
+		"ts:watch": "tsc --noEmit --incremental --watch"
+	},
+	"dependencies": {
+		"@heliosgraphics/css": "1.0.0-alpha.0",
+		"@heliosgraphics/icons": "1.0.0-alpha.8",
+		"@heliosgraphics/utils": "6.0.0-alpha.5",
+		"@types/markdown-it": "^14.1.2",
+		"dayjs": "^1.11.19",
+		"markdown-it": "^14.1.0",
+		"react-plock": "^3.6.1"
+	},
+	"devDependencies": {
+		"@testing-library/react": "^16.3.0",
+		"@types/node": "^24",
+		"@typescript-eslint/eslint-plugin": "^8.48.0",
+		"@vitejs/plugin-react": "^5.1.1",
+		"@vitest/coverage-v8": "^4.0.14",
+		"esbuild": "latest",
+		"esbuild-css-modules-plugin": "latest",
+		"eslint": "^9.39.1",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-prettier": "^5.5.4",
+		"glob": "latest",
+		"jsdom": "^27.2.0",
+		"next": "^16.0.5",
+		"prettier": "^3.7.3",
+		"typescript": "^5.9.3",
+		"vite": "^7.2.4",
+		"vitest": "^4.0.14"
+	},
+	"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"