@hoardodile/ui 0.1.3 → 0.1.5

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>
+		)
+	},
+)

package/src/lib/colors.test.ts

@@ -0,0 +1,94 @@
+/**
+ * @vitest-environment node
+ */
+
+import { describe, expect, it } from "vitest"
+import {
+	computeTagChipColors,
+	isBlackHex,
+	isSpecialTagStyle,
+	isWhiteHex,
+	TAG_SPECIAL_STYLES,
+} from "./colors"
+
+describe("isWhiteHex", () => {
+	it("matches common white representations", () => {
+		expect(isWhiteHex("#fff")).toBe(true)
+		expect(isWhiteHex("#FFFFFF")).toBe(true)
+		expect(isWhiteHex("white")).toBe(true)
+		expect(isWhiteHex("rgb(255,255,255)")).toBe(true)
+		expect(isWhiteHex("rgba( 255 , 255 , 255 , 0.5)")).toBe(true)
+	})
+
+	it("rejects empty and non-white colors", () => {
+		expect(isWhiteHex("")).toBe(false)
+		expect(isWhiteHex("#000")).toBe(false)
+		expect(isWhiteHex("#abcdef")).toBe(false)
+		expect(isWhiteHex("rgb(254,255,255)")).toBe(false)
+	})
+})
+
+describe("isBlackHex", () => {
+	it("matches common black representations", () => {
+		expect(isBlackHex("#000")).toBe(true)
+		expect(isBlackHex("#000000")).toBe(true)
+		expect(isBlackHex("BLACK")).toBe(true)
+		expect(isBlackHex("rgb(0, 0, 0)")).toBe(true)
+	})
+
+	it("rejects empty and non-black colors", () => {
+		expect(isBlackHex("")).toBe(false)
+		expect(isBlackHex("#fff")).toBe(false)
+		expect(isBlackHex("rgb(0,0,1)")).toBe(false)
+	})
+})
+
+describe("computeTagChipColors", () => {
+	it("falls back to muted/accent vars for empty color", () => {
+		const colors = computeTagChipColors("")
+		expect(colors.baseBg).toContain("var(--color-muted)")
+		expect(colors.hoverBg).toContain("var(--color-accent)")
+		expect(colors.fg).toContain("var(--color-foreground)")
+	})
+
+	it("returns explicit white treatment for white", () => {
+		const colors = computeTagChipColors("#ffffff")
+		expect(colors.baseBg).toBe("#ffffff")
+		expect(colors.fg).toBe("#0a0a0a")
+	})
+
+	it("returns explicit black treatment for black", () => {
+		const colors = computeTagChipColors("black")
+		expect(colors.baseBg).toBe("#0a0a0a")
+		expect(colors.fg).toBe("#ffffff")
+	})
+
+	it("uses color-mix blends for arbitrary colors", () => {
+		const colors = computeTagChipColors("#3366ff")
+		expect(colors.baseBg).toContain("color-mix")
+		expect(colors.baseBg).toContain("6%")
+		expect(colors.hoverBg).toContain("20%")
+		expect(colors.fg).toBe("#3366ff")
+	})
+
+	it("treats special style names as ordinary colors", () => {
+		const colors = computeTagChipColors("rainbow")
+		expect(colors.baseBg).toContain("color-mix")
+		expect(colors.fg).toBe("rainbow")
+	})
+})
+
+describe("isSpecialTagStyle", () => {
+	it("matches all known special styles", () => {
+		for (const style of TAG_SPECIAL_STYLES) {
+			expect(isSpecialTagStyle(style)).toBe(true)
+		}
+	})
+
+	it("rejects regular colors and empty", () => {
+		expect(isSpecialTagStyle("")).toBe(false)
+		expect(isSpecialTagStyle("#ff0000")).toBe(false)
+		expect(isSpecialTagStyle("red")).toBe(false)
+		expect(isSpecialTagStyle("rainbowish")).toBe(false)
+	})
+})

package/src/lib/colors.ts

@@ -0,0 +1,96 @@
+/**
+ * Pure color utilities used by tag/category chip rendering.
+ *
+ * Centralized here so chip components, color pickers, and tests share
+ * one definition for "looks white"/"looks black" and the color-mix
+ * blending used to keep chips subtle on cards and sidebars.
+ */
+
+export const TAG_SPECIAL_STYLES = [
+	"silver",
+	"gold",
+	"rainbow",
+	"oilslick",
+	"kintsugi",
+] as const
+
+/** Default color presets shared by every color picker in the app. */
+export const DEFAULT_COLOR_PRESETS = [
+	"#9D9D9D",
+	"#000000",
+	"#FFFFFF",
+	"#27AE60",
+	"#0070DD",
+	"#00BCD4",
+	"#8E44AD",
+	"#FF8000",
+	"#F1C40F",
+	"#E74C3C",
+] as const
+
+export type TagSpecialStyle = (typeof TAG_SPECIAL_STYLES)[number]
+
+export function isSpecialTagStyle(color: string): color is TagSpecialStyle {
+	return TAG_SPECIAL_STYLES.includes(color as TagSpecialStyle)
+}
+
+export type TagChipColors = {
+	readonly baseBg: string
+	readonly hoverBg: string
+	readonly fg: string
+}
+
+const WHITE_COLOR_PATTERN =
+	/^(?:#fff(?:fff)?|white|rgba?\(\s*255\s*,\s*255\s*,\s*255\b)/i
+const BLACK_COLOR_PATTERN =
+	/^(?:#000(?:000)?|black|rgba?\(\s*0\s*,\s*0\s*,\s*0\b)/i
+
+/**
+ * Tests whether a CSS color string visually resolves to white in any
+ * common short form (`#fff`, `#ffffff`, `white`, `rgb(255,255,255,…)`).
+ */
+export function isWhiteHex(color: string): boolean {
+	if (color === "") return false
+	return WHITE_COLOR_PATTERN.test(color.trim())
+}
+
+/** Mirror of {@link isWhiteHex} for black. */
+export function isBlackHex(color: string): boolean {
+	if (color === "") return false
+	return BLACK_COLOR_PATTERN.test(color.trim())
+}
+
+/**
+ * Resolve a chip's background/hover/foreground triple for the given
+ * `color`. White and black are special-cased so they remain visibly
+ * black/white in both light and dark themes instead of vanishing into
+ * the chip background.
+ */
+export function computeTagChipColors(color: string): TagChipColors {
+	if (color === "") {
+		return {
+			baseBg: "var(--color-muted)",
+			hoverBg: "var(--color-accent)",
+			fg: "var(--color-foreground)",
+		}
+	}
+	if (isWhiteHex(color)) {
+		return {
+			baseBg: "#ffffff",
+			hoverBg: "#f1f5f9",
+			fg: "#0a0a0a",
+		}
+	}
+	if (isBlackHex(color)) {
+		return {
+			baseBg: "#0a0a0a",
+			hoverBg: "#262626",
+			fg: "#ffffff",
+		}
+	}
+	return {
+		baseBg: `color-mix(in srgb, ${color} 6%, var(--color-card))`,
+		hoverBg: `color-mix(in srgb, ${color} 20%, var(--color-card))`,
+		fg: color,
+	}
+}