@cxxi-lab/hub-ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Louis-Antoine Lumet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,45 @@
 {
-  "name": "@cxxi-lab/hub-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@cxxi-lab/hub-ui",
+	"version": "0.1.0",
+	"description": "hub's design system: React components, design tokens and fonts.",
+	"license": "MIT",
+	"type": "module",
+	"sideEffects": [
+		"*.css"
+	],
+	"exports": {
+		".": "./src/index.ts",
+		"./theme.css": "./styles/theme.css",
+		"./fonts.css": "./styles/fonts.css"
+	},
+	"files": [
+		"src",
+		"styles",
+		"fonts",
+		"LICENSE"
+	],
+	"scripts": {
+		"typecheck": "tsc --noEmit"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/cxxi-lab/hub-ui.git"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"tailwind-merge": "^3.6.0",
+		"tailwind-variants": "^3.2.2"
+	},
+	"peerDependencies": {
+		"@fortawesome/fontawesome-svg-core": "^7.2.0",
+		"@fortawesome/free-solid-svg-icons": "^7.2.0",
+		"@fortawesome/react-fontawesome": "^3.3.1",
+		"react": "^19.2.4",
+		"react-dom": "^19.2.4",
+		"react-router": "^7.18.3",
+		"tailwind-scrollbar": "^4.0.2",
+		"tailwindcss": "^4.3.0"
+	}
+}

package/src/Brand/Brand.tsx

@@ -0,0 +1,23 @@
+import { Link } from 'react-router'
+import { HubLogo } from './HubLogo'
+import { type BrandProps } from './Brand.types'
+import { styles } from './Brand.variants'
+
+export function Brand({ to, onClick }: BrandProps) {
+	const content = (
+		<>
+			<HubLogo className={styles.icon()} />
+			<span className={styles.text()}>hub</span>
+		</>
+	)
+
+	if (to) {
+		return (
+			<Link to={to} onClick={onClick} className={`${styles.wrap()} cursor-pointer`}>
+				{content}
+			</Link>
+		)
+	}
+
+	return <div className={styles.wrap()}>{content}</div>
+}

package/src/Brand/Brand.types.ts

@@ -0,0 +1,6 @@
+import type { MouseEvent } from 'react'
+
+export interface BrandProps {
+	to?: string
+	onClick?: (e: MouseEvent<HTMLAnchorElement>) => void
+}

package/src/Brand/Brand.variants.ts

@@ -0,0 +1,9 @@
+import { tv } from 'tailwind-variants'
+
+export const styles = {
+	wrap: tv({
+		base: 'inline-flex items-center gap-1 px-1 text-2xl font-["Sofia"] select-none outline-none'
+	}),
+	icon: tv({ base: 'size-6' }),
+	text: tv({ base: 'brand-gradient font-bold mx-1 lowercase' })
+}

package/src/Brand/HubLogo.tsx

@@ -0,0 +1,22 @@
+import { useId } from 'react'
+
+/** The hub mark (inline: the package needs no SVG loader in its consumers' bundler). */
+export function HubLogo({ className }: { className?: string }) {
+	const gradient = `hub-logo-${useId()}`
+	return (
+		<svg className={className} width="200" height="200" viewBox="0 0 200 200" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+			<path
+				fillRule="evenodd"
+				clipRule="evenodd"
+				d="M32 100.641C32 68.391 54.1651 41.3515 84 34.1102V1.28125C36.3772 8.98855 0 50.5392 0 100.641C0 150.742 36.3772 192.293 84 200V167.171C54.1651 159.93 32 132.89 32 100.641ZM200 100.641C200 150.742 163.623 192.293 116 200V167.171C145.835 159.93 168 132.89 168 100.641C168 68.391 145.835 41.3515 116 34.1102V1.28125C163.623 8.98855 200 50.5392 200 100.641Z"
+				fill={`url(#${gradient})`}
+			/>
+			<defs>
+				<linearGradient id={gradient} x1="157.5" y1="33.0763" x2="44.7421" y2="148.561" gradientUnits="userSpaceOnUse">
+					<stop offset="0.0509862" stopColor="oklch(77.48% 0.11579287893479469 256.78266516146084)" />
+					<stop offset="1" stopColor="oklch(69.57% 0.16115444413200178 257.18469838826445)" />
+				</linearGradient>
+			</defs>
+		</svg>
+	)
+}

package/src/Brand/index.ts

@@ -0,0 +1,2 @@
+export { Brand } from './Brand'
+export * from './Brand.types'

package/src/back.ts

@@ -0,0 +1,52 @@
+import { useEffect, useRef } from 'react'
+
+/**
+ * The phone's back button (Android): it closes what is open on top (a menu, a modal, the module
+ * drawer…), most recent first; with nothing open, it goes back a page; on the home page, the app
+ * goes to the background. The host wires handleBack() to its back button (the app: window.hubBack,
+ * called by the Android shell, which does the last part itself when it answers false).
+ */
+
+const handlers: Array<{ close: () => void }> = []
+const depthListeners = new Set<(depth: number) => void>()
+const changed = () => depthListeners.forEach(l => l(handlers.length))
+
+/** How many things the back button would close, now and on each change (a hubby's frame tells its host). */
+export function onBackDepth(listener: (depth: number) => void): () => void {
+	depthListeners.add(listener)
+	listener(handlers.length)
+	return () => { depthListeners.delete(listener) }
+}
+
+/** While `open`, the back button closes this (onClose). */
+export function useBackHandler(open: boolean, onClose: () => void): void {
+	const latest = useRef(onClose)
+	latest.current = onClose
+	useEffect(() => {
+		if (!open) return
+		const entry = { close: () => latest.current() }
+		handlers.push(entry)
+		changed()
+		return () => {
+			const at = handlers.indexOf(entry)
+			if (at >= 0) handlers.splice(at, 1)
+			changed()
+		}
+	}, [open])
+}
+
+/** The back button: true when handled here (something closed, or a page back). */
+export function handleBack(): boolean {
+	const top = handlers.pop()
+	if (top) {
+		changed()
+		top.close()
+		return true
+	}
+	const at = window.location.hash.replace(/^#/, '') || '/'
+	if (at !== '/' && window.history.length > 1) {
+		window.history.back()
+		return true
+	}
+	return false
+}

package/src/buttons/Button/Button.tsx

@@ -0,0 +1,38 @@
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
+import { faCircleNotch } from '@fortawesome/free-solid-svg-icons'
+import { twMerge } from 'tailwind-merge'
+import { type ButtonProps } from './Button.types'
+import { styles } from './Button.variants'
+
+export function Button({
+	label,
+	children,
+	icon,
+	onClick,
+	className,
+	color,
+	isDisabled = false,
+	isLoading = false,
+	type = 'button',
+	...rest
+}: ButtonProps) {
+	const classList = twMerge(styles.button({ disabled: isDisabled, color }), className)
+
+	return (
+		<button
+			type={type}
+			className={classList}
+			onClick={onClick}
+			disabled={isDisabled || isLoading}
+			{...rest}
+		>
+			{isLoading
+				? <FontAwesomeIcon icon={faCircleNotch} className="animate-spin" />
+				: <>
+					{icon && <FontAwesomeIcon icon={icon} />}
+					{label ?? children}
+				</>
+			}
+		</button>
+	)
+}

package/src/buttons/Button/Button.types.ts

@@ -0,0 +1,18 @@
+import { type IconDefinition } from '@fortawesome/fontawesome-svg-core'
+import { type MouseEventHandler, type ReactNode } from 'react'
+
+export type ButtonColor = 'primary' | 'secondary' | 'danger'
+
+export interface ButtonProps {
+	label?: ReactNode
+	children?: ReactNode
+	icon?: IconDefinition
+	color?: ButtonColor
+	isDisabled?: boolean
+	isLoading?: boolean
+	className?: string
+	onClick?: MouseEventHandler<HTMLButtonElement>
+	type?: 'button' | 'submit' | 'reset'
+	title?: string
+	'aria-label'?: string
+}

package/src/buttons/Button/Button.variants.ts

@@ -0,0 +1,36 @@
+import { tv } from 'tailwind-variants'
+
+export const styles = {
+	button: tv({
+		base: [
+			'inline-flex',
+			'items-center',
+			'justify-center',
+			'gap-2',
+			'px-4',
+			'h-9',
+			'rounded',
+			'text-sm',
+			'font-semibold',
+			'leading-none',
+			// a label on one line, the button never squeezed by its neighbours (a narrow header)
+			'whitespace-nowrap',
+			'shrink-0',
+			'cursor-pointer',
+			'transition'
+		],
+		variants: {
+			color: {
+				primary: 'bg-primary-500 text-steel-950 hover:bg-primary-300',
+				secondary: 'bg-steel-800 text-steel-100 hover:bg-steel-700 hover:text-white',
+				danger: 'bg-red-500 text-steel-950 hover:bg-red-300'
+			},
+			disabled: {
+				true: 'opacity-25 pointer-events-none'
+			}
+		},
+		defaultVariants: {
+			color: 'primary'
+		}
+	})
+}

package/src/buttons/Button/index.ts

@@ -0,0 +1,2 @@
+export { Button } from './Button'
+export * from './Button.types'

package/src/buttons/FavButton/FavButton.tsx

@@ -0,0 +1,29 @@
+import { useEffect, useState } from 'react'
+import { faStar } from '@fortawesome/free-solid-svg-icons'
+import { IconButton } from '../IconButton'
+import { type FavButtonProps } from './FavButton.types'
+import { styles } from './FavButton.variants'
+
+export function FavButton({ initialState = false, onClick, size, className, ...rest }: FavButtonProps) {
+	const [favorite, setFavorite] = useState(initialState)
+
+	useEffect(() => setFavorite(initialState), [initialState])
+
+	const handleClick = () => {
+		const next = !favorite
+		setFavorite(next)
+		onClick?.(next)
+	}
+
+	return (
+		<IconButton
+			icon={faStar}
+			color="secondary"
+			shape="square"
+			size={size}
+			onClick={handleClick}
+			className={[styles.button({ favorite }), className].filter(Boolean).join(' ')}
+			{...rest}
+		/>
+	)
+}

package/src/buttons/FavButton/FavButton.types.ts

@@ -0,0 +1,10 @@
+import { type IconButtonSize } from '../IconButton/IconButton.types'
+
+export interface FavButtonProps {
+	initialState?: boolean
+	onClick?: (next: boolean) => void
+	size?: IconButtonSize
+	className?: string
+	title?: string
+	'aria-label'?: string
+}

package/src/buttons/FavButton/FavButton.variants.ts

@@ -0,0 +1,12 @@
+import { tv } from 'tailwind-variants'
+
+export const styles = {
+	button: tv({
+		variants: {
+			favorite: {
+				true: 'text-primary-500!',
+				false: 'text-steel-800!'
+			}
+		}
+	})
+}

package/src/buttons/FavButton/index.ts

@@ -0,0 +1,2 @@
+export { FavButton } from './FavButton'
+export * from './FavButton.types'

package/src/buttons/IconButton/IconButton.tsx

@@ -0,0 +1,40 @@
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
+import { faCircleNotch } from '@fortawesome/free-solid-svg-icons'
+import { twMerge } from 'tailwind-merge'
+import { type IconButtonProps } from './IconButton.types'
+import { styles } from './IconButton.variants'
+
+export function IconButton({
+	icon,
+	onClick,
+	className,
+	active = false,
+	highlighted = false,
+	isDisabled = false,
+	isLoading = false,
+	color,
+	shape,
+	size,
+	type = 'button',
+	...rest
+}: IconButtonProps) {
+	const classList = twMerge(
+		styles.button({ active, highlighted, disabled: isDisabled, color, shape, size }),
+		className
+	)
+
+	return (
+		<button
+			type={type}
+			className={classList}
+			onClick={onClick}
+			disabled={isDisabled || isLoading}
+			{...rest}
+		>
+			<FontAwesomeIcon
+				icon={isLoading ? faCircleNotch : icon}
+				className={styles.icon({ loading: isLoading })}
+			/>
+		</button>
+	)
+}

package/src/buttons/IconButton/IconButton.types.ts

@@ -0,0 +1,23 @@
+import { type IconDefinition } from '@fortawesome/fontawesome-svg-core'
+import { type MouseEventHandler } from 'react'
+
+export type IconButtonColor = 'primary' | 'secondary' | 'danger' | 'dark'
+export type IconButtonShape = 'square' | 'circle'
+export type IconButtonSize = 'xxs' | 'xs' | 'sm' | 'md' | 'xl'
+
+export interface IconButtonProps {
+	icon: IconDefinition
+	onClick?: MouseEventHandler<HTMLButtonElement>
+	className?: string
+	active?: boolean
+	highlighted?: boolean
+	isDisabled?: boolean
+	isLoading?: boolean
+	color?: IconButtonColor
+	shape?: IconButtonShape
+	size?: IconButtonSize
+	type?: 'button' | 'submit' | 'reset'
+	title?: string
+	'aria-label'?: string
+	'aria-expanded'?: boolean
+}

package/src/buttons/IconButton/IconButton.variants.ts

@@ -0,0 +1,56 @@
+import { tv } from 'tailwind-variants'
+
+export const styles = {
+	button: tv({
+		base: [
+			'inline-flex',
+			'justify-center',
+			'items-center',
+			'aspect-square',
+			'font-semibold',
+			'leading-none',
+			'cursor-pointer',
+			'transition'
+		],
+		variants: {
+			color: {
+				primary: 'text-steel-950 bg-primary-500 hover:bg-primary-300',
+				secondary: 'text-steel-300 hover:bg-steel-700 hover:text-white',
+				danger: 'text-steel-950 bg-red-500 hover:bg-red-300',
+				dark: 'text-steel-300 bg-steel-800 hover:bg-steel-700 hover:text-white'
+			},
+			active: {
+				true: 'bg-primary-700! text-primary-300!'
+			},
+			highlighted: {
+				true: 'text-primary-300!'
+			},
+			shape: {
+				square: 'rounded',
+				circle: 'rounded-full'
+			},
+			size: {
+				xxs: 'size-4 text-[11px]',
+				xs: 'size-6 text-xs',
+				sm: 'size-7 text-sm',
+				md: 'size-9 text-base',
+				xl: 'size-10 text-lg'
+			},
+			disabled: {
+				true: 'opacity-25 pointer-events-none'
+			}
+		},
+		defaultVariants: {
+			color: 'dark',
+			shape: 'circle',
+			size: 'md'
+		}
+	}),
+	icon: tv({
+		variants: {
+			loading: {
+				true: 'animate-spin'
+			}
+		}
+	})
+}

package/src/buttons/IconButton/index.ts

@@ -0,0 +1,2 @@
+export { IconButton } from './IconButton'
+export * from './IconButton.types'

package/src/buttons/index.ts

@@ -0,0 +1,3 @@
+export * from './Button'
+export * from './IconButton'
+export * from './FavButton'

package/src/contexts/FormContext.tsx

@@ -0,0 +1,57 @@
+import { createContext, useContext, useState, type ReactNode } from 'react'
+
+export type FormData = Record<string, unknown>
+export type FormErrors = Record<string, string | null>
+
+export interface FormContextValue {
+	data: FormData
+	errors: FormErrors
+	setField: (field: string, value: unknown) => void
+	setError: (field: string, message: string | null) => void
+	clearError: (field: string) => void
+	reset: () => void
+}
+
+interface FormContextProviderProps {
+	children: ReactNode
+	initialData?: FormData
+}
+
+const FormContext = createContext<FormContextValue | undefined>(undefined)
+
+export function FormContextProvider({ children, initialData = {} }: FormContextProviderProps) {
+	const [data, setData] = useState<FormData>(initialData)
+	const [errors, setErrors] = useState<FormErrors>({})
+
+	const setField = (field: string, value: unknown) => {
+		setData(prev => ({ ...prev, [field]: value }))
+		setErrors(prev => ({ ...prev, [field]: null }))
+	}
+
+	const setError = (field: string, message: string | null) => {
+		setErrors(prev => ({ ...prev, [field]: message }))
+	}
+
+	const clearError = (field: string) => {
+		setErrors(prev => ({ ...prev, [field]: null }))
+	}
+
+	const reset = () => {
+		setData(initialData)
+		setErrors({})
+	}
+
+	return (
+		<FormContext.Provider value={{ data, errors, setField, setError, clearError, reset }}>
+			{children}
+		</FormContext.Provider>
+	)
+}
+
+export function useFormContext(): FormContextValue {
+	const context = useContext(FormContext)
+	if (!context) {
+		throw new Error('useFormContext must be used within a FormContextProvider')
+	}
+	return context
+}

package/src/forms/CheckboxField/Checkbox.tsx

@@ -0,0 +1,17 @@
+import { type ReactNode } from 'react'
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
+import { faCheck } from '@fortawesome/free-solid-svg-icons'
+import { styles } from './CheckboxField.variants'
+
+/** The CheckboxField box on its own, outside a form: controlled by `checked`, its label beside it. */
+export function Checkbox({ checked, label, onChange }: { checked: boolean, label: ReactNode, onChange: (checked: boolean) => void }) {
+	return (
+		<label className="inline-flex items-center gap-2 cursor-pointer select-none">
+			<input type="checkbox" className="sr-only" checked={checked} onChange={e => onChange(e.target.checked)} />
+			<span aria-hidden className={styles.check({ checked })}>
+				<FontAwesomeIcon icon={faCheck} />
+			</span>
+			<span className="inline-flex items-center gap-2 text-sm text-steel-100">{label}</span>
+		</label>
+	)
+}