@hoardodile/ui 0.1.2 → 0.1.4

package/src/components/special/rainbow.tsx

@@ -0,0 +1,63 @@
+import { cn } from "@hoardodile/ui/lib/utils"
+
+import type { SpecialTagStyleConfig } from "./types"
+
+function RainbowSurface({
+	id,
+	active,
+}: {
+	readonly id: string
+	readonly active?: boolean
+}) {
+	const gradientId = `${id}-rainbow-gradient`
+	return (
+		<svg
+			className={cn(
+				"size-full",
+				!active && "group-hover:[filter:brightness(1.08)]",
+			)}
+			width="100%"
+			height="100%"
+			viewBox="0 0 100 100"
+			preserveAspectRatio="none"
+		>
+			<defs>
+				<linearGradient
+					id={gradientId}
+					x1="0%"
+					y1="0%"
+					x2="100%"
+					y2="0%"
+					gradientTransform="rotate(30, 0.5, 0.5)"
+				>
+					<stop offset="0%" stopColor="#fbffca" />
+					<stop offset="33%" stopColor="#baffbf" />
+					<stop offset="66%" stopColor="#a7efff" />
+					<stop offset="100%" stopColor="#ffabff" />
+				</linearGradient>
+			</defs>
+			<rect
+				width="100"
+				height="100"
+				fill={active ? "#005458" : `url(#${gradientId})`}
+			/>
+		</svg>
+	)
+}
+
+export const rainbowConfig: SpecialTagStyleConfig = {
+	render: RainbowSurface,
+	default: {
+		className: "font-bold dark:[text-shadow:0_0_5px_rgba(0,0,0,0.5)]",
+		style: {
+			color: "#ffffff",
+			textShadow: "0 0 5px rgba(0, 0, 0, 0.2)",
+			boxShadow: "inset 0 0 0 1px rgba(0, 247, 255, 0.1)",
+		},
+	},
+	active: {
+		style: {
+			color: "#ffffff",
+		},
+	},
+}

package/src/components/special/silver.tsx

@@ -0,0 +1,73 @@
+import { cn } from "@hoardodile/ui/lib/utils"
+
+import type { SpecialTagStyleConfig } from "./types"
+
+function SilverSurface({
+	id,
+	active,
+}: {
+	readonly id: string
+	readonly active?: boolean
+}) {
+	const gradientId = `${id}-silver-gradient`
+	return (
+		<svg
+			className={cn(
+				"size-full",
+				!active &&
+					"[filter:brightness(1.1)] group-hover:[filter:brightness(1.16)]",
+			)}
+			width="100%"
+			height="100%"
+			viewBox="0 0 100 100"
+			preserveAspectRatio="none"
+		>
+			<defs>
+				<linearGradient
+					id={gradientId}
+					x1="0%"
+					y1="0%"
+					x2="100%"
+					y2="0%"
+					gradientTransform="rotate(30, 0.5, 0.5)"
+				>
+					<stop offset="10%" stopColor="#afaeae" />
+					<stop offset="30%" stopColor="#d6d6d6" />
+					<stop offset="50%" stopColor="#eeeeee" />
+					<stop offset="70%" stopColor="#d6d6d6" />
+					<stop offset="90%" stopColor="#afaeae" />
+				</linearGradient>
+			</defs>
+			<rect
+				width="100"
+				height="100"
+				fill={active ? "#5a5a5a" : `url(#${gradientId})`}
+			/>
+			{!active && (
+				<rect
+					x="0"
+					y="0"
+					width="100"
+					height="8"
+					fill="#ffffff"
+					opacity="0.16"
+				/>
+			)}
+		</svg>
+	)
+}
+
+export const silverConfig: SpecialTagStyleConfig = {
+	render: SilverSurface,
+	default: {
+		style: {
+			color: "#2a2a2a",
+			boxShadow: "inset 0 0 0 1px rgba(0, 0, 0, 0.08)",
+		},
+	},
+	active: {
+		style: {
+			color: "#ffffff",
+		},
+	},
+}

package/src/components/special/types.ts

@@ -0,0 +1,21 @@
+import type { CSSProperties, ReactElement } from "react"
+
+export type SpecialTagSurfaceRendererProps = {
+	readonly id: string
+	readonly active?: boolean
+}
+
+export type SpecialTagSurfaceRenderer = (
+	props: SpecialTagSurfaceRendererProps,
+) => ReactElement
+
+export type SpecialTagStyleAppearance = {
+	readonly className?: string
+	readonly style?: CSSProperties
+}
+
+export type SpecialTagStyleConfig = {
+	readonly render: SpecialTagSurfaceRenderer
+	readonly default: SpecialTagStyleAppearance
+	readonly active?: SpecialTagStyleAppearance
+}

package/src/components/special-tag-surface.tsx

@@ -0,0 +1,53 @@
+import { cn } from "@hoardodile/ui/lib/utils"
+import { useId } from "react"
+import type { TagSpecialStyle } from "@hoardodile/ui/lib/colors"
+import { goldConfig } from "./special/gold"
+import { kintsugiConfig } from "./special/kintsugi"
+import { oilslickConfig } from "./special/oilslick"
+import { rainbowConfig } from "./special/rainbow"
+import { silverConfig } from "./special/silver"
+import type { SpecialTagStyleConfig } from "./special/types"
+
+export type SpecialTagSurfaceProps = {
+	readonly style: TagSpecialStyle
+	readonly active?: boolean
+	readonly className?: string
+}
+
+const SPECIAL_TAG_CONFIG: Record<TagSpecialStyle, SpecialTagStyleConfig> = {
+	silver: silverConfig,
+	gold: goldConfig,
+	rainbow: rainbowConfig,
+	oilslick: oilslickConfig,
+	kintsugi: kintsugiConfig,
+}
+
+export function getSpecialTagStyleConfig(
+	style: TagSpecialStyle,
+): SpecialTagStyleConfig {
+	return SPECIAL_TAG_CONFIG[style]
+}
+
+/**
+ * SVG background surface for special tag styles.
+ *
+ * Each style owns a self-contained SVG renderer in `src/components/special/`.
+ * This component only picks the right renderer from the registry and applies
+ * positioning; all styling (filters, colors, shadows) lives in the renderer or
+ * the chip container config.
+ */
+export function SpecialTagSurface(props: SpecialTagSurfaceProps) {
+	const { style, active, className } = props
+	const config = SPECIAL_TAG_CONFIG[style]
+	const Renderer = config.render
+	const reactId = useId()
+	// React useId() can produce ids containing colons, which break SVG
+	// url(#id) references in some browsers. Replace them with a safe delimiter.
+	const safeId = reactId.replace(/:/g, "-")
+
+	return (
+		<span className={cn(className)} aria-hidden="true">
+			<Renderer id={safeId} active={active} />
+		</span>
+	)
+}

package/src/components/tag-chip.test.tsx

@@ -0,0 +1,180 @@
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, test, vi } from "vitest"
+import { TAG_SPECIAL_STYLES } from "@hoardodile/ui/lib/colors"
+import { TagChip } from "./tag-chip"
+
+function mockBoundingRect(width: number, height: number) {
+	const original = Element.prototype.getBoundingClientRect
+	Element.prototype.getBoundingClientRect = vi.fn(() =>
+		DOMRect.fromRect({ x: 0, y: 0, width, height }),
+	)
+	return () => {
+		Element.prototype.getBoundingClientRect = original
+	}
+}
+
+describe("TagChip", () => {
+	test("renders a plain span with a single text wrapper (no layered nesting)", () => {
+		const { container } = render(<TagChip color="">tag</TagChip>)
+		const chip = container.firstElementChild
+		expect(chip).toHaveTextContent("tag")
+		expect(chip).not.toHaveClass("border")
+		expect(chip?.querySelectorAll("span")).toHaveLength(1)
+	})
+
+	test("renders normal colored chips with the tinted fill variables", () => {
+		const { container } = render(<TagChip color="#E74C3C">tag</TagChip>)
+		const chip = container.firstElementChild as HTMLElement
+		expect(chip.style.getPropertyValue("--chip-bg")).toContain("#E74C3C")
+		expect(chip).toHaveStyle({ color: "#E74C3C" })
+	})
+
+	test("renders every registered special style with an SVG texture", () => {
+		for (const style of TAG_SPECIAL_STYLES) {
+			const { container } = render(<TagChip color={style}>tag</TagChip>)
+			expect(container.querySelector("svg")).toBeInTheDocument()
+		}
+	})
+
+	test("falls back to the default palette when color is empty", () => {
+		const { container } = render(<TagChip color="">tag</TagChip>)
+		expect(container.firstElementChild).toHaveTextContent("tag")
+	})
+
+	test("display='button' renders a real button and fires onClick", async () => {
+		const user = userEvent.setup()
+		const onClick = vi.fn()
+		render(
+			<TagChip color="" display="button" onClick={onClick} data-testid="chip">
+				hello
+			</TagChip>,
+		)
+		const el = screen.getByTestId("chip")
+		expect(el.tagName).toBe("BUTTON")
+		expect(el.className).toContain("cursor-pointer")
+		await user.click(el)
+		expect(onClick).toHaveBeenCalledTimes(1)
+	})
+
+	test("an onClick handler alone never promotes — the element stays a span", async () => {
+		const user = userEvent.setup()
+		const onClick = vi.fn()
+		render(
+			<TagChip color="" onClick={onClick} data-testid="chip">
+				hello
+			</TagChip>,
+		)
+		const el = screen.getByTestId("chip")
+		expect(el.tagName).toBe("SPAN")
+		expect(el.className).not.toContain("cursor-pointer")
+		await user.click(el)
+		expect(onClick).toHaveBeenCalledTimes(1)
+	})
+
+	test("display mode stays a span", () => {
+		render(
+			<TagChip color="" data-testid="chip">
+				hello
+			</TagChip>,
+		)
+		expect(screen.getByTestId("chip").tagName).toBe("SPAN")
+	})
+
+	test("render swaps the root element and keeps the chip's children", () => {
+		render(
+			<TagChip color="" data-testid="chip" render={<button type="button" />}>
+				label
+			</TagChip>,
+		)
+		const el = screen.getByTestId("chip")
+		expect(el.tagName).toBe("BUTTON")
+		expect(el).toHaveTextContent("label")
+	})
+
+	test("active uncolored chips take the primary palette", () => {
+		render(
+			<TagChip color="" active onClick={() => undefined} data-testid="chip">
+				x
+			</TagChip>,
+		)
+		const el = screen.getByTestId("chip")
+		expect(el.className).toContain("bg-primary")
+		expect(el.className).toContain("text-primary-foreground")
+	})
+
+	test("dashed border mode renders the quiet outline and ignores color", () => {
+		render(
+			<TagChip color="#ff0000" border="dashed" data-testid="chip">
+				x
+			</TagChip>,
+		)
+		const el = screen.getByTestId("chip")
+		expect(el.className).toContain("border-dashed")
+		expect(el.className).toContain("border-border-strong")
+		expect(el.className).toContain("text-muted-foreground")
+		expect(el.className).not.toContain("bg-primary")
+	})
+
+	test("dashed border mode active swaps in the accent fill with a transparent border", () => {
+		render(
+			<TagChip
+				color=""
+				active
+				border="dashed"
+				onClick={() => undefined}
+				data-testid="chip"
+			>
+				x
+			</TagChip>,
+		)
+		const el = screen.getByTestId("chip")
+		expect(el.className).toContain("bg-accent")
+		expect(el.className).toContain("border-transparent")
+	})
+
+	test("roundedRight=false removes the right border-radius", () => {
+		render(
+			<TagChip color="" roundedRight={false} data-testid="chip">
+				x
+			</TagChip>,
+		)
+		expect(screen.getByTestId("chip").className).toContain("rounded-r-none")
+	})
+
+	test("special style renders an SVG gradient surface", () => {
+		const restore = mockBoundingRect(100, 36)
+		render(
+			<TagChip color="rainbow" data-testid="chip">
+				rainbow
+			</TagChip>,
+		)
+		const el = screen.getByTestId("chip")
+		expect(el.querySelector("svg")).toBeInTheDocument()
+		expect(el.querySelector("linearGradient")).toBeInTheDocument()
+		restore()
+	})
+
+	test("special style active state uses the active fill", () => {
+		const restore = mockBoundingRect(100, 36)
+		render(
+			<TagChip color="gold" active data-testid="chip">
+				gold
+			</TagChip>,
+		)
+		const rect = screen.getByTestId("chip").querySelector("rect")
+		expect(rect).toHaveAttribute("fill", "#8a6d1f")
+		restore()
+	})
+
+	test("special style does not apply the regular border or tint classes", () => {
+		render(
+			<TagChip color="silver" data-testid="chip">
+				silver
+			</TagChip>,
+		)
+		const el = screen.getByTestId("chip")
+		expect(el.className).not.toContain("border-transparent")
+		expect(el.className).not.toContain(" bg-(--chip-bg)")
+	})
+})

package/src/components/tag-chip.tsx

@@ -0,0 +1,221 @@
+import { cn } from "@hoardodile/ui/lib/utils"
+import {
+	type ComponentPropsWithoutRef,
+	cloneElement,
+	forwardRef,
+	type MouseEvent,
+	type ReactElement,
+	type ReactNode,
+	type Ref,
+} from "react"
+import { SpecialTagSurface } from "@hoardodile/ui/components/special-tag-surface"
+import { resolveTagChipSurface } from "@hoardodile/ui/lib/tag-surface"
+
+/** The two sanctioned chip sizes: `sm` (default, `px-2 py-1`) for cards and
+    inline rows, `md` (`px-2 py-1.5`) for the filterer facets (Categories,
+    Traits, Relations). */
+export type TagChipSize = "sm" | "md"
+
+type TagChipBaseProps = {
+	/**
+	 * Effective display color. Special names (`silver`, `gold`, `rainbow`,
+	 * ...) render their SVG texture; an empty string falls back to the
+	 * default muted chip, taking the primary fill when `active`. Ignored
+	 * when `border` is set — bordered modes never take a tint.
+	 */
+	readonly color?: string
+	/** Chip height tier — see {@link TagChipSize}. */
+	readonly size?: TagChipSize
+	/**
+	 * Border mode instead of the fill/ghost anatomies. Only `"dashed"`
+	 * exists today (add pills, unused entities): a `border-dashed` hairline
+	 * with muted ink and no color tint — `active` swaps in the accent fill
+	 * with a transparent border so the width never moves with the state.
+	 */
+	readonly border?: "dashed"
+	/** Selected: colored chips deepen to their hover tint, special styles
+	    switch to their own active appearance, uncolored chips take the
+	    primary fill. */
+	readonly active?: boolean
+	/** Leading icon; rides the chip's own gap, so no wrapper is needed. */
+	readonly icon?: ReactNode
+	/** False removes the right border-radius so the chip can glue flush
+	    against a sibling (e.g. the category rail's chevron). */
+	readonly roundedRight?: boolean
+	/**
+	 * Root element mode: `"inline"` (default) renders a plain `<span>`,
+	 * `"button"` a real `<button type="button">`. The element is chosen
+	 * only from this prop (or `render`) — passing an `onClick` never
+	 * changes the element, so interactive wrappers (hover cards,
+	 * popovers) that merge click handlers onto the chip cannot swap its
+	 * DOM node mid-interaction.
+	 */
+	readonly display?: "inline" | "button"
+	/**
+	 * Polymorphic root: pass a `render={<button ... />}` element to render
+	 * the chip as that element. The chip's own classes, style, handlers,
+	 * texture and icon merge onto it, and the chip's children become the
+	 * element's children — so the render element should carry only its own
+	 * props. Wins over `display`; `display="button"` is the plain way to
+	 * get a real button without supplying a render element.
+	 */
+	readonly render?: ReactElement<Record<string, unknown>>
+	/**
+	 * Trailing suffix, separated from the label by a middle dot (e.g. a
+	 * trait's kind "cm" or a count). Rendered at the label's own size —
+	 * same line box, so the chip height never depends on the suffix —
+	 * with muted ink and a bold dot.
+	 */
+	readonly suffix?: ReactNode
+	readonly children?: ReactNode
+	readonly onMouseDown?: (event: MouseEvent<HTMLSpanElement>) => void
+}
+
+export type TagChipProps = TagChipBaseProps &
+	Omit<ComponentPropsWithoutRef<"button">, keyof TagChipBaseProps>
+
+/** Text container: ellipsis truncation that only clips horizontally —
+    `truncate`'s `overflow: hidden` would also clip descenders (y, g, p)
+    at the tight `leading-none` line box, so the x axis clips while the y
+    axis stays visible. */
+const tagChipLabelClassName =
+	"min-w-0 overflow-x-clip text-ellipsis whitespace-nowrap"
+
+/**
+ * The one tag chip: a single rounded pill (inline-flex, `rounded-sm`,
+ * `px-2 py-1`, 12px text) that may carry an icon and a special SVG
+ * texture. It renders as a span by default; interactive surfaces pass
+ * `display="button"` (or `render={<button ... />}` for a custom root,
+ * e.g. a navigation anchor) and the chip's styling lands on that
+ * element — one element in the DOM plus a single text wrapper, no
+ * deeper nesting.
+ *
+ * The root element is decided purely by `display`/`render` — never by
+ * the presence of an `onClick`, so a chip's DOM element cannot change
+ * between renders (the hover-card trigger merge in {@link TagChipHover}
+ * relies on this).
+ *
+ * Coloring is delegated to {@link resolveTagChipSurface} so cards,
+ * pickers, the doc editor and the character pills all share one
+ * definition of "what a colored tag looks like".
+ *
+ * The chip forwards its root ref so composition wrappers (e.g. the
+ * {@link TagChipHover} preview-card trigger, which clones the chip and
+ * attaches a DOM ref for anchoring) can reach the actual element.
+ */
+export const TagChip = forwardRef<HTMLElement, TagChipProps>(
+	function TagChip(props, ref) {
+		const {
+			color,
+			size = "sm",
+			border,
+			active,
+			icon,
+			roundedRight,
+			display,
+			render,
+			suffix,
+			children,
+			className,
+			style,
+			onMouseDown,
+			...rest
+		} = props
+		const surface =
+			border !== undefined
+				? undefined
+				: resolveTagChipSurface(color ?? "", active === true)
+
+		// The root element is fixed by the display mode / render slot —
+		// an onClick merged on by an interactive wrapper must never swap
+		// the chip's element (see the component doc comment).
+		const interactiveRoot = display === "button" || render !== undefined
+
+		const stateClass =
+			border === "dashed"
+				? active === true
+					? "border border-transparent bg-accent text-foreground"
+					: "border border-dashed border-border-strong text-muted-foreground hover:text-secondary-foreground"
+				: undefined
+
+		// Texture and icon are the chip's own decoration, so they lead the
+		// children even when the root element is swapped (render / button).
+		const content = (
+			<>
+				{surface !== undefined && surface.texture !== null && (
+					<SpecialTagSurface
+						style={surface.texture}
+						active={active}
+						className="absolute inset-0 -z-10 overflow-hidden rounded-[inherit]"
+					/>
+				)}
+				{icon !== undefined && (
+					// Flex row: the slot accepts several icons as a fragment
+					// (e.g. a kind glyph + the pin), and flex keeps the
+					// blockified preflight svgs on one line.
+					<span className="flex shrink-0 items-center gap-1 text-muted-foreground">
+						{icon}
+					</span>
+				)}
+				<span className={tagChipLabelClassName}>
+					{children}
+					{suffix !== undefined ? (
+						<>
+							<span className="font-bold mx-0.5">·</span>
+							<span className="shrink-0 opacity-70">{suffix}</span>
+						</>
+					) : null}
+				</span>
+			</>
+		)
+
+		const chipClassName = cn(
+			"inline-flex min-w-0 max-w-full items-center justify-center gap-1.5 rounded-sm text-xs font-normal leading-none disabled:pointer-events-none disabled:opacity-50",
+			size === "md" ? "px-2 py-1.5" : "px-2 py-1",
+			roundedRight === false && "rounded-r-none",
+			interactiveRoot && "cursor-pointer",
+			surface?.className,
+			stateClass,
+			className,
+		)
+		const chipStyle = { ...surface?.style, ...style }
+
+		if (render !== undefined) {
+			return cloneElement(render, {
+				...rest,
+				ref,
+				className: chipClassName,
+				style: chipStyle,
+				onMouseDown,
+				children: content,
+			})
+		}
+
+		if (display === "button") {
+			return (
+				<button
+					type="button"
+					ref={ref as Ref<HTMLButtonElement>}
+					className={chipClassName}
+					style={chipStyle}
+					onMouseDown={onMouseDown}
+					{...rest}
+				>
+					{content}
+				</button>
+			)
+		}
+
+		return (
+			<span
+				ref={ref as Ref<HTMLSpanElement>}
+				className={chipClassName}
+				style={chipStyle}
+				onMouseDown={onMouseDown}
+				{...rest}
+			>
+				{content}
+			</span>
+		)
+	},
+)