@inui/design-system 0.0.0-stage → 1.22.0

package/dist/components/ui/field.js

@@ -0,0 +1,254 @@
+"use client";
+import { cn } from "../../lib/utils.js";
+import { Separator } from "./separator.js";
+import { Label, OptionalHint, RequiredDot } from "./label.js";
+import * as React from "react";
+import { useMemo } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cva } from "class-variance-authority";
+//#region src/components/ui/field.tsx
+/**
+* Field — form field wrapper (label + control + description + error).
+*
+* A composite family, not a single component: Field lays out one control
+* with its label/description/error slots; FieldSet+FieldLegend group
+* several Fields for assistive tech; FieldGroup stacks Fields together;
+* FieldSeparator divides sections. Invalid state is driven by
+* `data-invalid` on Field plus `aria-invalid` on the control.
+*/
+var FieldIdContext = React.createContext(null);
+var FieldSetIdContext = React.createContext(null);
+function FieldSet({ className, "aria-labelledby": ariaLabelledby, ...props }) {
+	const [legendId, setLegendId] = React.useState(null);
+	const idContext = React.useMemo(() => ({
+		legendId,
+		setLegendId
+	}), [legendId]);
+	return /* @__PURE__ */ jsx(FieldSetIdContext.Provider, {
+		value: idContext,
+		children: /* @__PURE__ */ jsx("fieldset", {
+			"data-slot": "field-set",
+			"aria-labelledby": ariaLabelledby ?? legendId ?? void 0,
+			className: cn("flex flex-col gap-4 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3 has-[>[data-slot=field-legend-row]]:!gap-0", className),
+			...props
+		})
+	});
+}
+function FieldLegend({ className, id, variant = "legend", required = false, optional = false, children, aiLabel, aiLabelAlign = "inline", ...props }) {
+	const generatedId = React.useId();
+	const legendId = id ?? generatedId;
+	const idContext = React.useContext(FieldSetIdContext);
+	React.useLayoutEffect(() => {
+		idContext?.setLegendId(legendId);
+		return () => idContext?.setLegendId(null);
+	}, [legendId]);
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "field-legend-row",
+		className: cn("group/field-legend flex h-6 w-full items-start gap-2", aiLabel && aiLabelAlign === "end" && "justify-between"),
+		children: [/* @__PURE__ */ jsxs("legend", {
+			id: legendId,
+			"data-slot": "field-legend",
+			"data-variant": variant,
+			"data-required": required || void 0,
+			"data-optional": optional && !required || void 0,
+			className: cn("font-medium data-[variant=label]:text-sm data-[variant=legend]:text-base", className),
+			...props,
+			children: [children, required ? /* @__PURE__ */ jsx(RequiredDot, { className: "ml-1 align-top" }) : optional ? /* @__PURE__ */ jsx(OptionalHint, { className: "ml-1" }) : null]
+		}), aiLabel]
+	});
+}
+function FieldGroup({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "field-group",
+		className: cn("group/field-group @container/field-group flex w-full flex-col gap-5 data-[slot=checkbox-group]:gap-3 *:data-[slot=field-group]:gap-4", className),
+		...props
+	});
+}
+var fieldVariants = cva("group/field flex w-full gap-2 data-[invalid=true]:text-destructive", {
+	variants: { orientation: {
+		vertical: "flex-col *:w-full [&>.sr-only]:w-auto",
+		horizontal: "flex-row items-center has-[>[data-slot=field-content]]:items-start *:data-[slot=field-label]:flex-auto has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
+		responsive: "flex-col *:w-full @md/field-group:flex-row @md/field-group:items-center @md/field-group:*:w-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:*:data-[slot=field-label]:flex-auto [&>.sr-only]:w-auto @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px"
+	} },
+	defaultVariants: { orientation: "vertical" }
+});
+function Field({ className, orientation = "vertical", ...props }) {
+	const [titleId, setTitleId] = React.useState(null);
+	const [descriptionId, setDescriptionId] = React.useState(null);
+	const [errorId, setErrorId] = React.useState(null);
+	const idContext = React.useMemo(() => ({
+		titleId,
+		setTitleId,
+		descriptionId,
+		setDescriptionId,
+		errorId,
+		setErrorId
+	}), [
+		titleId,
+		descriptionId,
+		errorId
+	]);
+	return /* @__PURE__ */ jsx(FieldIdContext.Provider, {
+		value: idContext,
+		children: /* @__PURE__ */ jsx("div", {
+			role: "group",
+			"data-slot": "field",
+			"data-orientation": orientation,
+			className: cn(fieldVariants({ orientation }), className),
+			...props
+		})
+	});
+}
+function FieldContent({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "field-content",
+		className: cn("group/field-content flex flex-1 flex-col gap-0.5 leading-snug", className),
+		...props
+	});
+}
+function FieldLabel({ className, aiLabel, aiLabelAlign = "end", ...props }) {
+	const label = /* @__PURE__ */ jsx(Label, {
+		"data-slot": aiLabel ? void 0 : "field-label",
+		className: cn("group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:text-disabled-foreground has-data-[state=checked]:border-primary/30 has-data-[state=checked]:bg-primary/5 has-[>[data-slot=field]]:rounded-xl has-[>[data-slot=field]]:border *:data-[slot=field]:p-2.5 dark:has-data-[state=checked]:border-primary/20 dark:has-data-[state=checked]:bg-primary/10", "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col", !aiLabel && className),
+		...props
+	});
+	if (!aiLabel) return label;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "field-label",
+		className: cn("group/field-label flex h-6 w-full items-start gap-2 -mb-2", aiLabelAlign === "end" && "justify-between", className),
+		children: [label, aiLabel]
+	});
+}
+function FieldTitle({ className, id, ...props }) {
+	const generatedId = React.useId();
+	const titleId = id ?? generatedId;
+	const idContext = React.useContext(FieldIdContext);
+	React.useLayoutEffect(() => {
+		idContext?.setTitleId(titleId);
+		return () => idContext?.setTitleId(null);
+	}, [titleId]);
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "field-label",
+		id: titleId,
+		className: cn("flex w-fit items-center gap-2 text-sm font-medium group-data-[disabled=true]/field:text-disabled-foreground", className),
+		...props
+	});
+}
+function FieldDescription({ className, id, ...props }) {
+	const generatedId = React.useId();
+	const descriptionId = id ?? generatedId;
+	const idContext = React.useContext(FieldIdContext);
+	React.useLayoutEffect(() => {
+		idContext?.setDescriptionId(descriptionId);
+		return () => idContext?.setDescriptionId(null);
+	}, [descriptionId]);
+	return /* @__PURE__ */ jsx("p", {
+		"data-slot": "field-description",
+		id: descriptionId,
+		className: cn("text-left text-sm leading-normal font-normal text-muted-foreground group-has-data-horizontal/field:text-balance [[data-variant=legend]+&]:-mt-1.5", "last:mt-0 nth-last-2:-mt-1", "[&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary", className),
+		...props
+	});
+}
+function FieldSeparator({ children, className, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "field-separator",
+		"data-content": !!children,
+		className: cn("relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2", className),
+		...props,
+		children: [/* @__PURE__ */ jsx(Separator, { className: "absolute inset-0 top-1/2" }), children && /* @__PURE__ */ jsx("span", {
+			className: "relative mx-auto block w-fit bg-background px-2 text-muted-foreground",
+			"data-slot": "field-separator-content",
+			children
+		})]
+	});
+}
+function FieldError({ className, children, errors, id, ...props }) {
+	const generatedId = React.useId();
+	const errorId = id ?? generatedId;
+	const idContext = React.useContext(FieldIdContext);
+	const content = useMemo(() => {
+		if (children) return children;
+		if (!errors?.length) return null;
+		const uniqueErrors = [...new Map(errors.map((error) => [error?.message, error])).values()];
+		if (uniqueErrors?.length == 1) return uniqueErrors[0]?.message;
+		return /* @__PURE__ */ jsx("ul", {
+			className: "ml-4 flex list-disc flex-col gap-1",
+			children: uniqueErrors.map((error, index) => error?.message && /* @__PURE__ */ jsx("li", { children: error.message }, index))
+		});
+	}, [children, errors]);
+	React.useLayoutEffect(() => {
+		idContext?.setErrorId(content ? errorId : null);
+		return () => idContext?.setErrorId(null);
+	}, [errorId, !!content]);
+	if (!content) return null;
+	return /* @__PURE__ */ jsx("div", {
+		role: "alert",
+		"data-slot": "field-error",
+		id: errorId,
+		className: cn("text-sm font-normal text-destructive", className),
+		...props,
+		children: content
+	});
+}
+/**
+* WHEN TO USE
+* - Any labelled form field that needs help text or validation messaging — wraps any input primitive (Input, Textarea, Checkbox, ...)
+* - `orientation="horizontal"` for label-beside-control rows (e.g. a Checkbox with title/description via FieldContent + FieldTitle)
+* - FieldSet + FieldLegend to group related Fields for assistive tech; FieldGroup to stack them with consistent spacing
+* - FieldSeparator to divide sections within a FieldGroup, optionally with a label (e.g. "OR")
+*
+* NOT WHEN
+* - A bare label with no description or error text — use Label directly, it's lighter
+* - Display-only key/value pairs with no input — this is a form-control wrapper, not a data display
+*
+* KEY RULES
+* - orientation: vertical (default), horizontal, responsive (stacks on narrow, horizontal at @md container width)
+* - Required/optional are marked on the label, nowhere else: `<FieldLabel required>` (red dot) or `<FieldLabel optional>` (muted "(optional)"), and the same two props on FieldLegend for a whole group. Visual only — the control still carries `required`/`aria-required` for assistive tech. Pick one convention per form: mark the required fields or the optional ones, not both.
+* - Mark invalid state with `data-invalid` on Field AND `aria-invalid` on the control — Field's red text styling depends on `data-invalid`, the control's border/ring styling depends on `aria-invalid`
+* - FieldError accepts either `children` (a fixed message) or an `errors` array of `{ message }` objects (react-hook-form shape) — duplicates are deduped by message, renders a single line for one error or a bulleted list for multiple; renders nothing if there's no content
+* - FieldDescription/FieldError generate an id and register it on Field's context; Checkbox reads that context and defaults its own `aria-describedby`/`aria-labelledby` (to FieldTitle's id) whenever the consumer hasn't already set one — for every other control, still give each element an explicit `id` and set the control's `aria-describedby` to match (see USAGE below), or a screen reader user who tabs to the control never hears the hint/error
+* - FieldLabel wraps Label — use it (not FieldTitle) when the row has an actual form control; use FieldTitle for the horizontal FieldContent pattern where the "label" is really a heading beside a standalone control. FieldTitle is a plain heading-styled `<div>`, not a `<label>` — for controls other than Checkbox, give the control its own `aria-label`/`aria-labelledby` matching FieldTitle's text (see USAGE below) or it ships with no accessible name at all.
+*
+* USAGE
+* <Field>
+*   <FieldLabel htmlFor="email">Email</FieldLabel>
+*   <Input id="email" type="email" aria-describedby="email-hint" />
+*   <FieldDescription id="email-hint">We'll never share your address.</FieldDescription>
+* </Field>
+*
+* // With validation — aria-describedby lists both ids so an invalid field
+* // still announces its hint alongside the error, not just one or the other
+* <Field data-invalid={!!error}>
+*   <FieldLabel htmlFor="email">Email</FieldLabel>
+*   <Input id="email" type="email" aria-invalid={!!error} aria-describedby="email-hint email-error" />
+*   <FieldDescription id="email-hint">We'll never share your address.</FieldDescription>
+*   <FieldError id="email-error">{error}</FieldError>
+* </Field>
+*
+* <Field data-invalid orientation="horizontal">
+*   <FieldContent>
+*     <FieldTitle>Marketing emails</FieldTitle>
+*     <FieldDescription>Receive product news and updates.</FieldDescription>
+*   </FieldContent>
+*   <Checkbox />
+* </Field>
+* // Checkbox picks up FieldTitle as its aria-labelledby and
+* // FieldDescription/FieldError as its aria-describedby automatically —
+* // pass an explicit aria-label/aria-labelledby/aria-describedby yourself
+* // only to override that default. Any other control in this position
+* // (there's no `<label>` wrapping it) still needs its own aria-label/
+* // aria-labelledby matching FieldTitle's text.
+*
+* <FieldSet>
+*   <FieldLegend>Project details</FieldLegend>
+*   <FieldGroup>
+*     <Field>...</Field>
+*     <FieldSeparator />
+*     <Field>...</Field>
+*   </FieldGroup>
+* </FieldSet>
+*/
+//#endregion
+export { Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldIdContext, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle };
+
+//# sourceMappingURL=field.js.map

package/dist/components/ui/field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.js","names":[],"sources":["../../../src/components/ui/field.tsx"],"sourcesContent":["\"use client\"\n\n/**\n * Field — form field wrapper (label + control + description + error).\n *\n * A composite family, not a single component: Field lays out one control\n * with its label/description/error slots; FieldSet+FieldLegend group\n * several Fields for assistive tech; FieldGroup stacks Fields together;\n * FieldSeparator divides sections. Invalid state is driven by\n * `data-invalid` on Field plus `aria-invalid` on the control.\n */\n\nimport * as React from \"react\"\nimport { useMemo } from \"react\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\n\nimport { cn } from \"@/lib/utils\"\nimport { Label, OptionalHint, RequiredDot } from \"@/components/ui/label\"\nimport { Separator } from \"@/components/ui/separator\"\n\n// FieldTitle (unlike FieldLabel) is a plain heading `<div>`, not a `<label>`,\n// for the horizontal FieldContent pattern where the control is a standalone\n// sibling rather than something a `<label>` wraps — so it carries no\n// `htmlFor`/id wiring of its own. Without this context, that documented\n// pattern shipped controls (Checkbox, ...) with no accessible name at all.\n// Consumer-supplied `aria-label`/`aria-labelledby`/`aria-describedby` on the\n// control always wins; this only fills the gap when none was given.\nconst FieldIdContext = React.createContext<{\n  titleId: string | null\n  setTitleId: (id: string | null) => void\n  descriptionId: string | null\n  setDescriptionId: (id: string | null) => void\n  errorId: string | null\n  setErrorId: (id: string | null) => void\n} | null>(null)\n\n// FieldLegend now always renders `<legend>` inside a row `<div>` (so it can\n// sit next to an optional `aiLabel` at a fixed height — see FieldLegend\n// below), which means `<legend>` is no longer FieldSet's literal direct\n// child. That breaks the native fieldset/legend accessible-name link (the\n// browser only picks up `<legend>` as the fieldset's name when it's a\n// direct child), so FieldSet has to restore it explicitly via\n// `aria-labelledby` — this context is how FieldLegend's id reaches it.\nconst FieldSetIdContext = React.createContext<{\n  legendId: string | null\n  setLegendId: (id: string | null) => void\n} | null>(null)\n\nfunction FieldSet({\n  className,\n  \"aria-labelledby\": ariaLabelledby,\n  ...props\n}: React.ComponentProps<\"fieldset\">) {\n  const [legendId, setLegendId] = React.useState<string | null>(null)\n  const idContext = React.useMemo(\n    () => ({ legendId, setLegendId }),\n    [legendId]\n  )\n\n  return (\n    <FieldSetIdContext.Provider value={idContext}>\n      <fieldset\n        data-slot=\"field-set\"\n        aria-labelledby={ariaLabelledby ?? legendId ?? undefined}\n        className={cn(\n          // `field-legend-row` (FieldLegend's own wrapper) forces gap to 0:\n          // FieldLegend's row is a fixed h-6 (24px) and that height is the\n          // whole label-to-control gap by design, so FieldSet must not\n          // stack its own gap on top. `!` because this has to win over the\n          // checkbox-group/radio-group gap-3 rules below when a FieldSet\n          // has both a legend row AND one of those as its two children —\n          // same `:has()` specificity, so source order alone can't be\n          // trusted (see RadioGroup's AI story, which hit exactly this).\n          \"flex flex-col gap-4 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3 has-[>[data-slot=field-legend-row]]:!gap-0\",\n          className\n        )}\n        {...props}\n      />\n    </FieldSetIdContext.Provider>\n  )\n}\n\nfunction FieldLegend({\n  className,\n  id,\n  variant = \"legend\",\n  required = false,\n  optional = false,\n  children,\n  aiLabel,\n  aiLabelAlign = \"inline\",\n  ...props\n}: React.ComponentProps<\"legend\"> & {\n  variant?: \"legend\" | \"label\"\n  /** Red dot after the legend — the group (checkboxes, radios) is mandatory. Visual only: put `required`/`aria-required` on the group's control(s) too. */\n  required?: boolean\n  /** Muted \"(optional)\" after the legend. Mutually exclusive with `required`. */\n  optional?: boolean\n  /** An `AILabel` rendered in the same fixed-height row as the legend — a sibling, never nested inside `<legend>` (AILabelTrigger is a button; a button inside a legend/label is invalid HTML). */\n  aiLabel?: React.ReactNode\n  /** \"inline\" (default) places `aiLabel` immediately after the legend text — the usual placement for a per-group AI marker (Checkbox/RadioGroup's own AI-flavored stories). \"end\" pushes it to the row's far end instead. */\n  aiLabelAlign?: \"inline\" | \"end\"\n}) {\n  const generatedId = React.useId()\n  const legendId = id ?? generatedId\n  const idContext = React.useContext(FieldSetIdContext)\n\n  React.useLayoutEffect(() => {\n    idContext?.setLegendId(legendId)\n    return () => idContext?.setLegendId(null)\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [legendId])\n\n  return (\n    <div\n      data-slot=\"field-legend-row\"\n      className={cn(\n        \"group/field-legend flex h-6 w-full items-start gap-2\",\n        aiLabel && aiLabelAlign === \"end\" && \"justify-between\"\n      )}\n    >\n      <legend\n        id={legendId}\n        data-slot=\"field-legend\"\n        data-variant={variant}\n        data-required={required || undefined}\n        data-optional={(optional && !required) || undefined}\n        className={cn(\n          \"font-medium data-[variant=label]:text-sm data-[variant=legend]:text-base\",\n          className\n        )}\n        {...props}\n      >\n        {children}\n        {required ? (\n          <RequiredDot className=\"ml-1 align-top\" />\n        ) : optional ? (\n          <OptionalHint className=\"ml-1\" />\n        ) : null}\n      </legend>\n      {aiLabel}\n    </div>\n  )\n}\n\nfunction FieldGroup({ className, ...props }: React.ComponentProps<\"div\">) {\n  return (\n    <div\n      data-slot=\"field-group\"\n      className={cn(\n        \"group/field-group @container/field-group flex w-full flex-col gap-5 data-[slot=checkbox-group]:gap-3 *:data-[slot=field-group]:gap-4\",\n        className\n      )}\n      {...props}\n    />\n  )\n}\n\nconst fieldVariants = cva(\n  \"group/field flex w-full gap-2 data-[invalid=true]:text-destructive\",\n  {\n    variants: {\n      orientation: {\n        vertical: \"flex-col *:w-full [&>.sr-only]:w-auto\",\n        horizontal:\n          \"flex-row items-center has-[>[data-slot=field-content]]:items-start *:data-[slot=field-label]:flex-auto has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px\",\n        responsive:\n          \"flex-col *:w-full @md/field-group:flex-row @md/field-group:items-center @md/field-group:*:w-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:*:data-[slot=field-label]:flex-auto [&>.sr-only]:w-auto @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px\",\n      },\n    },\n    defaultVariants: {\n      orientation: \"vertical\",\n    },\n  }\n)\n\nfunction Field({\n  className,\n  orientation = \"vertical\",\n  ...props\n}: React.ComponentProps<\"div\"> & VariantProps<typeof fieldVariants>) {\n  const [titleId, setTitleId] = React.useState<string | null>(null)\n  const [descriptionId, setDescriptionId] = React.useState<string | null>(\n    null\n  )\n  const [errorId, setErrorId] = React.useState<string | null>(null)\n  const idContext = React.useMemo(\n    () => ({\n      titleId,\n      setTitleId,\n      descriptionId,\n      setDescriptionId,\n      errorId,\n      setErrorId,\n    }),\n    [titleId, descriptionId, errorId]\n  )\n\n  return (\n    <FieldIdContext.Provider value={idContext}>\n      <div\n        role=\"group\"\n        data-slot=\"field\"\n        data-orientation={orientation}\n        className={cn(fieldVariants({ orientation }), className)}\n        {...props}\n      />\n    </FieldIdContext.Provider>\n  )\n}\n\nfunction FieldContent({ className, ...props }: React.ComponentProps<\"div\">) {\n  return (\n    <div\n      data-slot=\"field-content\"\n      className={cn(\n        \"group/field-content flex flex-1 flex-col gap-0.5 leading-snug\",\n        className\n      )}\n      {...props}\n    />\n  )\n}\n\nfunction FieldLabel({\n  className,\n  aiLabel,\n  aiLabelAlign = \"end\",\n  ...props\n}: React.ComponentProps<typeof Label> & {\n  /** An `AILabel` rendered in the same row as the label — a sibling, never\n   * nested inside `<label>` (AILabelTrigger is a button; a button inside a\n   * label is invalid HTML). Passing this switches FieldLabel to a fixed\n   * `h-6` (24px) row, so a grid mixing AI and non-AI fields still aligns —\n   * plain FieldLabel (no `aiLabel`) keeps its normal auto height, since\n   * forcing every label to a fixed row would also force the unrelated\n   * \"FieldLabel wrapping a nested Field\" option-card pattern (see\n   * `has-[>[data-slot=field]]` below) into that same fixed height, which\n   * needs to stay auto/flex-col instead. */\n  aiLabel?: React.ReactNode\n  /** \"end\" (default) pushes `aiLabel` to the row's far end — Input/Textarea/Select's own AI-flavored stories. \"inline\" places it immediately after the label text instead. */\n  aiLabelAlign?: \"inline\" | \"end\"\n}) {\n  const label = (\n    <Label\n      data-slot={aiLabel ? undefined : \"field-label\"}\n      className={cn(\n        \"group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:text-disabled-foreground has-data-[state=checked]:border-primary/30 has-data-[state=checked]:bg-primary/5 has-[>[data-slot=field]]:rounded-xl has-[>[data-slot=field]]:border *:data-[slot=field]:p-2.5 dark:has-data-[state=checked]:border-primary/20 dark:has-data-[state=checked]:bg-primary/10\",\n        \"has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col\",\n        !aiLabel && className\n      )}\n      {...props}\n    />\n  )\n\n  if (!aiLabel) {\n    return label\n  }\n\n  return (\n    <div\n      data-slot=\"field-label\"\n      className={cn(\n        // `-mb-2` cancels Field's own `gap-2` after this row, so the whole\n        // gap to the control is this row's own height (24px) — one source\n        // of spacing, not two stacked ones. Field's `gap-2` itself stays\n        // untouched (it still spaces the control from FieldDescription/\n        // FieldError below), so nothing else using Field regresses.\n        \"group/field-label flex h-6 w-full items-start gap-2 -mb-2\",\n        aiLabelAlign === \"end\" && \"justify-between\",\n        className\n      )}\n    >\n      {label}\n      {aiLabel}\n    </div>\n  )\n}\n\nfunction FieldTitle({\n  className,\n  id,\n  ...props\n}: React.ComponentProps<\"div\">) {\n  const generatedId = React.useId()\n  const titleId = id ?? generatedId\n  const idContext = React.useContext(FieldIdContext)\n\n  React.useLayoutEffect(() => {\n    idContext?.setTitleId(titleId)\n    return () => idContext?.setTitleId(null)\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [titleId])\n\n  return (\n    <div\n      data-slot=\"field-label\"\n      id={titleId}\n      className={cn(\n        \"flex w-fit items-center gap-2 text-sm font-medium group-data-[disabled=true]/field:text-disabled-foreground\",\n        className\n      )}\n      {...props}\n    />\n  )\n}\n\nfunction FieldDescription({\n  className,\n  id,\n  ...props\n}: React.ComponentProps<\"p\">) {\n  const generatedId = React.useId()\n  const descriptionId = id ?? generatedId\n  const idContext = React.useContext(FieldIdContext)\n\n  React.useLayoutEffect(() => {\n    idContext?.setDescriptionId(descriptionId)\n    return () => idContext?.setDescriptionId(null)\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [descriptionId])\n\n  return (\n    <p\n      data-slot=\"field-description\"\n      id={descriptionId}\n      className={cn(\n        \"text-left text-sm leading-normal font-normal text-muted-foreground group-has-data-horizontal/field:text-balance [[data-variant=legend]+&]:-mt-1.5\",\n        \"last:mt-0 nth-last-2:-mt-1\",\n        \"[&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary\",\n        className\n      )}\n      {...props}\n    />\n  )\n}\n\nfunction FieldSeparator({\n  children,\n  className,\n  ...props\n}: React.ComponentProps<\"div\"> & {\n  children?: React.ReactNode\n}) {\n  return (\n    <div\n      data-slot=\"field-separator\"\n      data-content={!!children}\n      className={cn(\n        \"relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2\",\n        className\n      )}\n      {...props}\n    >\n      <Separator className=\"absolute inset-0 top-1/2\" />\n      {children && (\n        <span\n          className=\"relative mx-auto block w-fit bg-background px-2 text-muted-foreground\"\n          data-slot=\"field-separator-content\"\n        >\n          {children}\n        </span>\n      )}\n    </div>\n  )\n}\n\nfunction FieldError({\n  className,\n  children,\n  errors,\n  id,\n  ...props\n}: React.ComponentProps<\"div\"> & {\n  errors?: Array<{ message?: string } | undefined>\n}) {\n  const generatedId = React.useId()\n  const errorId = id ?? generatedId\n  const idContext = React.useContext(FieldIdContext)\n\n  const content = useMemo(() => {\n    if (children) {\n      return children\n    }\n\n    if (!errors?.length) {\n      return null\n    }\n\n    const uniqueErrors = [\n      ...new Map(errors.map((error) => [error?.message, error])).values(),\n    ]\n\n    if (uniqueErrors?.length == 1) {\n      return uniqueErrors[0]?.message\n    }\n\n    return (\n      <ul className=\"ml-4 flex list-disc flex-col gap-1\">\n        {uniqueErrors.map(\n          (error, index) =>\n            error?.message && <li key={index}>{error.message}</li>\n        )}\n      </ul>\n    )\n  }, [children, errors])\n\n  React.useLayoutEffect(() => {\n    idContext?.setErrorId(content ? errorId : null)\n    return () => idContext?.setErrorId(null)\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [errorId, !!content])\n\n  if (!content) {\n    return null\n  }\n\n  return (\n    <div\n      role=\"alert\"\n      data-slot=\"field-error\"\n      id={errorId}\n      className={cn(\"text-sm font-normal text-destructive\", className)}\n      {...props}\n    >\n      {content}\n    </div>\n  )\n}\n\nexport {\n  Field,\n  FieldLabel,\n  FieldDescription,\n  FieldError,\n  FieldGroup,\n  FieldLegend,\n  FieldSeparator,\n  FieldSet,\n  FieldContent,\n  FieldTitle,\n  FieldIdContext,\n}\n\n/**\n * WHEN TO USE\n * - Any labelled form field that needs help text or validation messaging — wraps any input primitive (Input, Textarea, Checkbox, ...)\n * - `orientation=\"horizontal\"` for label-beside-control rows (e.g. a Checkbox with title/description via FieldContent + FieldTitle)\n * - FieldSet + FieldLegend to group related Fields for assistive tech; FieldGroup to stack them with consistent spacing\n * - FieldSeparator to divide sections within a FieldGroup, optionally with a label (e.g. \"OR\")\n *\n * NOT WHEN\n * - A bare label with no description or error text — use Label directly, it's lighter\n * - Display-only key/value pairs with no input — this is a form-control wrapper, not a data display\n *\n * KEY RULES\n * - orientation: vertical (default), horizontal, responsive (stacks on narrow, horizontal at @md container width)\n * - Required/optional are marked on the label, nowhere else: `<FieldLabel required>` (red dot) or `<FieldLabel optional>` (muted \"(optional)\"), and the same two props on FieldLegend for a whole group. Visual only — the control still carries `required`/`aria-required` for assistive tech. Pick one convention per form: mark the required fields or the optional ones, not both.\n * - Mark invalid state with `data-invalid` on Field AND `aria-invalid` on the control — Field's red text styling depends on `data-invalid`, the control's border/ring styling depends on `aria-invalid`\n * - FieldError accepts either `children` (a fixed message) or an `errors` array of `{ message }` objects (react-hook-form shape) — duplicates are deduped by message, renders a single line for one error or a bulleted list for multiple; renders nothing if there's no content\n * - FieldDescription/FieldError generate an id and register it on Field's context; Checkbox reads that context and defaults its own `aria-describedby`/`aria-labelledby` (to FieldTitle's id) whenever the consumer hasn't already set one — for every other control, still give each element an explicit `id` and set the control's `aria-describedby` to match (see USAGE below), or a screen reader user who tabs to the control never hears the hint/error\n * - FieldLabel wraps Label — use it (not FieldTitle) when the row has an actual form control; use FieldTitle for the horizontal FieldContent pattern where the \"label\" is really a heading beside a standalone control. FieldTitle is a plain heading-styled `<div>`, not a `<label>` — for controls other than Checkbox, give the control its own `aria-label`/`aria-labelledby` matching FieldTitle's text (see USAGE below) or it ships with no accessible name at all.\n *\n * USAGE\n * <Field>\n *   <FieldLabel htmlFor=\"email\">Email</FieldLabel>\n *   <Input id=\"email\" type=\"email\" aria-describedby=\"email-hint\" />\n *   <FieldDescription id=\"email-hint\">We'll never share your address.</FieldDescription>\n * </Field>\n *\n * // With validation — aria-describedby lists both ids so an invalid field\n * // still announces its hint alongside the error, not just one or the other\n * <Field data-invalid={!!error}>\n *   <FieldLabel htmlFor=\"email\">Email</FieldLabel>\n *   <Input id=\"email\" type=\"email\" aria-invalid={!!error} aria-describedby=\"email-hint email-error\" />\n *   <FieldDescription id=\"email-hint\">We'll never share your address.</FieldDescription>\n *   <FieldError id=\"email-error\">{error}</FieldError>\n * </Field>\n *\n * <Field data-invalid orientation=\"horizontal\">\n *   <FieldContent>\n *     <FieldTitle>Marketing emails</FieldTitle>\n *     <FieldDescription>Receive product news and updates.</FieldDescription>\n *   </FieldContent>\n *   <Checkbox />\n * </Field>\n * // Checkbox picks up FieldTitle as its aria-labelledby and\n * // FieldDescription/FieldError as its aria-describedby automatically —\n * // pass an explicit aria-label/aria-labelledby/aria-describedby yourself\n * // only to override that default. Any other control in this position\n * // (there's no `<label>` wrapping it) still needs its own aria-label/\n * // aria-labelledby matching FieldTitle's text.\n *\n * <FieldSet>\n *   <FieldLegend>Project details</FieldLegend>\n *   <FieldGroup>\n *     <Field>...</Field>\n *     <FieldSeparator />\n *     <Field>...</Field>\n *   </FieldGroup>\n * </FieldSet>\n */\n"],"mappings":";;;;;;;;;;;;;;;;;;AA2BA,IAAM,iBAAiB,MAAM,cAOnB,IAAI;AASd,IAAM,oBAAoB,MAAM,cAGtB,IAAI;AAEd,SAAS,SAAS,EAChB,WACA,mBAAmB,gBACnB,GAAG,SACgC;CACnC,MAAM,CAAC,UAAU,eAAe,MAAM,SAAwB,IAAI;CAClE,MAAM,YAAY,MAAM,eACf;EAAE;EAAU;CAAY,IAC/B,CAAC,QAAQ,CACX;CAEA,OACE,oBAAC,kBAAkB,UAAnB;EAA4B,OAAO;EACjC,UAAA,oBAAC,YAAD;GACE,aAAU;GACV,mBAAiB,kBAAkB,YAAY,KAAA;GAC/C,WAAW,GAST,+IACA,SACF;GACA,GAAI;EACL,CAAA;CACyB,CAAA;AAEhC;AAEA,SAAS,YAAY,EACnB,WACA,IACA,UAAU,UACV,WAAW,OACX,WAAW,OACX,UACA,SACA,eAAe,UACf,GAAG,SAWF;CACD,MAAM,cAAc,MAAM,MAAM;CAChC,MAAM,WAAW,MAAM;CACvB,MAAM,YAAY,MAAM,WAAW,iBAAiB;CAEpD,MAAM,sBAAsB;EAC1B,WAAW,YAAY,QAAQ;EAC/B,aAAa,WAAW,YAAY,IAAI;CAE1C,GAAG,CAAC,QAAQ,CAAC;CAEb,OACE,qBAAC,OAAD;EACE,aAAU;EACV,WAAW,GACT,wDACA,WAAW,iBAAiB,SAAS,iBACvC;EALF,UAAA,CAOE,qBAAC,UAAD;GACE,IAAI;GACJ,aAAU;GACV,gBAAc;GACd,iBAAe,YAAY,KAAA;GAC3B,iBAAgB,YAAY,CAAC,YAAa,KAAA;GAC1C,WAAW,GACT,4EACA,SACF;GACA,GAAI;GAVN,UAAA,CAYG,UACA,WACC,oBAAC,aAAD,EAAa,WAAU,iBAAkB,CAAA,IACvC,WACF,oBAAC,cAAD,EAAc,WAAU,OAAQ,CAAA,IAC9B,IACE;EACP,CAAA,GAAA,OACE;;AAET;AAEA,SAAS,WAAW,EAAE,WAAW,GAAG,SAAsC;CACxE,OACE,oBAAC,OAAD;EACE,aAAU;EACV,WAAW,GACT,wIACA,SACF;EACA,GAAI;CACL,CAAA;AAEL;AAEA,IAAM,gBAAgB,IACpB,sEACA;CACE,UAAU,EACR,aAAa;EACX,UAAU;EACV,YACE;EACF,YACE;CACJ,EACF;CACA,iBAAiB,EACf,aAAa,WACf;AACF,CACF;AAEA,SAAS,MAAM,EACb,WACA,cAAc,YACd,GAAG,SACgE;CACnE,MAAM,CAAC,SAAS,cAAc,MAAM,SAAwB,IAAI;CAChE,MAAM,CAAC,eAAe,oBAAoB,MAAM,SAC9C,IACF;CACA,MAAM,CAAC,SAAS,cAAc,MAAM,SAAwB,IAAI;CAChE,MAAM,YAAY,MAAM,eACf;EACL;EACA;EACA;EACA;EACA;EACA;CACF,IACA;EAAC;EAAS;EAAe;CAAO,CAClC;CAEA,OACE,oBAAC,eAAe,UAAhB;EAAyB,OAAO;EAC9B,UAAA,oBAAC,OAAD;GACE,MAAK;GACL,aAAU;GACV,oBAAkB;GAClB,WAAW,GAAG,cAAc,EAAE,YAAY,CAAC,GAAG,SAAS;GACvD,GAAI;EACL,CAAA;CACsB,CAAA;AAE7B;AAEA,SAAS,aAAa,EAAE,WAAW,GAAG,SAAsC;CAC1E,OACE,oBAAC,OAAD;EACE,aAAU;EACV,WAAW,GACT,iEACA,SACF;EACA,GAAI;CACL,CAAA;AAEL;AAEA,SAAS,WAAW,EAClB,WACA,SACA,eAAe,OACf,GAAG,SAcF;CACD,MAAM,QACJ,oBAAC,OAAD;EACE,aAAW,UAAU,KAAA,IAAY;EACjC,WAAW,GACT,yYACA,qEACA,CAAC,WAAW,SACd;EACA,GAAI;CACL,CAAA;CAGH,IAAI,CAAC,SACH,OAAO;CAGT,OACE,qBAAC,OAAD;EACE,aAAU;EACV,WAAW,GAMT,6DACA,iBAAiB,SAAS,mBAC1B,SACF;EAXF,UAAA,CAaG,OACA,OACE;;AAET;AAEA,SAAS,WAAW,EAClB,WACA,IACA,GAAG,SAC2B;CAC9B,MAAM,cAAc,MAAM,MAAM;CAChC,MAAM,UAAU,MAAM;CACtB,MAAM,YAAY,MAAM,WAAW,cAAc;CAEjD,MAAM,sBAAsB;EAC1B,WAAW,WAAW,OAAO;EAC7B,aAAa,WAAW,WAAW,IAAI;CAEzC,GAAG,CAAC,OAAO,CAAC;CAEZ,OACE,oBAAC,OAAD;EACE,aAAU;EACV,IAAI;EACJ,WAAW,GACT,+GACA,SACF;EACA,GAAI;CACL,CAAA;AAEL;AAEA,SAAS,iBAAiB,EACxB,WACA,IACA,GAAG,SACyB;CAC5B,MAAM,cAAc,MAAM,MAAM;CAChC,MAAM,gBAAgB,MAAM;CAC5B,MAAM,YAAY,MAAM,WAAW,cAAc;CAEjD,MAAM,sBAAsB;EAC1B,WAAW,iBAAiB,aAAa;EACzC,aAAa,WAAW,iBAAiB,IAAI;CAE/C,GAAG,CAAC,aAAa,CAAC;CAElB,OACE,oBAAC,KAAD;EACE,aAAU;EACV,IAAI;EACJ,WAAW,GACT,qJACA,8BACA,qEACA,SACF;EACA,GAAI;CACL,CAAA;AAEL;AAEA,SAAS,eAAe,EACtB,UACA,WACA,GAAG,SAGF;CACD,OACE,qBAAC,OAAD;EACE,aAAU;EACV,gBAAc,CAAC,CAAC;EAChB,WAAW,GACT,6EACA,SACF;EACA,GAAI;EAPN,UAAA,CASE,oBAAC,WAAD,EAAW,WAAU,2BAA4B,CAAA,GAChD,YACC,oBAAC,QAAD;GACE,WAAU;GACV,aAAU;GAET;EACG,CAAA,CAEL;;AAET;AAEA,SAAS,WAAW,EAClB,WACA,UACA,QACA,IACA,GAAG,SAGF;CACD,MAAM,cAAc,MAAM,MAAM;CAChC,MAAM,UAAU,MAAM;CACtB,MAAM,YAAY,MAAM,WAAW,cAAc;CAEjD,MAAM,UAAU,cAAc;EAC5B,IAAI,UACF,OAAO;EAGT,IAAI,CAAC,QAAQ,QACX,OAAO;EAGT,MAAM,eAAe,CACnB,GAAG,IAAI,IAAI,OAAO,KAAK,UAAU,CAAC,OAAO,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CACpE;EAEA,IAAI,cAAc,UAAU,GAC1B,OAAO,aAAa,EAAE,EAAE;EAG1B,OACE,oBAAC,MAAD;GAAI,WAAU;GACX,UAAA,aAAa,KACX,OAAO,UACN,OAAO,WAAW,oBAAC,MAAD,EAAA,UAAiB,MAAM,QAAY,GAA1B,KAA0B,CACzD;EACE,CAAA;CAER,GAAG,CAAC,UAAU,MAAM,CAAC;CAErB,MAAM,sBAAsB;EAC1B,WAAW,WAAW,UAAU,UAAU,IAAI;EAC9C,aAAa,WAAW,WAAW,IAAI;CAEzC,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC;CAEvB,IAAI,CAAC,SACH,OAAO;CAGT,OACE,oBAAC,OAAD;EACE,MAAK;EACL,aAAU;EACV,IAAI;EACJ,WAAW,GAAG,wCAAwC,SAAS;EAC/D,GAAI;EAEH,UAAA;CACE,CAAA;AAET"}

package/dist/components/ui/hover-card.d.ts

@@ -0,0 +1,51 @@
+/**
+ * HoverCard — rich preview panel that opens on hover, with open/close delays.
+ *
+ * Pointer-driven — there is no click or
+ * keyboard-only path to the same content, so treat it as a progressive
+ * enhancement, not the only route to the information it shows.
+ */
+import * as React from "react";
+import { HoverCard as HoverCardPrimitive } from "radix-ui";
+declare function HoverCard({ ...props }: React.ComponentProps<typeof HoverCardPrimitive.Root>): React.JSX.Element;
+declare function HoverCardTrigger({ asChild, href, tabIndex, ...props }: React.ComponentProps<typeof HoverCardPrimitive.Trigger>): React.JSX.Element;
+declare function HoverCardContent({ className, align, sideOffset, ...props }: React.ComponentProps<typeof HoverCardPrimitive.Content>): React.JSX.Element;
+export { HoverCard, HoverCardTrigger, HoverCardContent };
+/**
+ * WHEN TO USE
+ * - Previewing an entity on hover without navigating away — a user profile,
+ *   a linked record's summary, a card behind a link
+ *
+ * NOT WHEN
+ * - Touch-primary interfaces — there's no hover event, so the content
+ *   becomes unreachable; don't gate essential info behind it
+ * - A short, plain-text label — use Tooltip
+ * - The panel must open on click or hold interactive controls the user
+ *   must act on — use Popover
+ *
+ * KEY RULES
+ * - Opens on hover (or focus), not click — this is the trigger mechanism
+ *   that separates it from Popover
+ * - `openDelay`/`closeDelay` default to radix's built-in delays; set both
+ *   to 0 for instant preview
+ * - HoverCardContent is 16rem (w-64) wide by default; override via className
+ * - `align` defaults to "center", `sideOffset` defaults to 4
+ *
+ * USAGE
+ * <HoverCard>
+ *   <HoverCardTrigger asChild><Button variant="link">@priya</Button></HoverCardTrigger>
+ *   <HoverCardContent className="w-72">
+ *     <div className="flex gap-3">
+ *       <Avatar><AvatarImage src="..." /><AvatarFallback>CN</AvatarFallback></Avatar>
+ *       <div className="grid gap-1">
+ *         <p className="text-sm font-medium">Priya Nair</p>
+ *         <p className="text-sm text-muted-foreground">Bio text.</p>
+ *       </div>
+ *     </div>
+ *   </HoverCardContent>
+ * </HoverCard>
+ *
+ * // Instant, for reviewing content without waiting on hover delay
+ * <HoverCard openDelay={0} closeDelay={0}>...</HoverCard>
+ */
+//# sourceMappingURL=hover-card.d.ts.map

package/dist/components/ui/hover-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hover-card.d.ts","sourceRoot":"","sources":["../../../src/components/ui/hover-card.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,SAAS,IAAI,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAU1D,iBAAS,SAAS,CAAC,EACjB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,kBAAkB,CAAC,IAAI,CAAC,qBAOtD;AAED,iBAAS,gBAAgB,CAAC,EACxB,OAAO,EACP,IAAI,EACJ,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,kBAAkB,CAAC,OAAO,CAAC,qBA6BzD;AAED,iBAAS,gBAAgB,CAAC,EACxB,SAAS,EACT,KAAgB,EAChB,UAAc,EACd,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,kBAAkB,CAAC,OAAO,CAAC,qBA0CzD;AAED,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG"}

package/dist/components/ui/hover-card.js

@@ -0,0 +1,101 @@
+import { cn } from "../../lib/utils.js";
+import { getPortalContainer } from "../../lib/scope.js";
+import * as React from "react";
+import { HoverCard as HoverCard$1 } from "radix-ui";
+import { jsx } from "react/jsx-runtime";
+//#region src/components/ui/hover-card.tsx
+/**
+* HoverCard — rich preview panel that opens on hover, with open/close delays.
+*
+* Pointer-driven — there is no click or
+* keyboard-only path to the same content, so treat it as a progressive
+* enhancement, not the only route to the information it shows.
+*/
+var HoverCardIdContext = React.createContext(null);
+function HoverCard({ ...props }) {
+	const contentId = React.useId();
+	return /* @__PURE__ */ jsx(HoverCardIdContext.Provider, {
+		value: contentId,
+		children: /* @__PURE__ */ jsx(HoverCard$1.Root, {
+			"data-slot": "hover-card",
+			...props
+		})
+	});
+}
+function HoverCardTrigger({ asChild, href, tabIndex, ...props }) {
+	const contentId = React.useContext(HoverCardIdContext);
+	const needsFallbackSemantics = !asChild && !href;
+	return /* @__PURE__ */ jsx(HoverCard$1.Trigger, {
+		"data-slot": "hover-card-trigger",
+		asChild,
+		href,
+		tabIndex: tabIndex ?? (needsFallbackSemantics ? 0 : void 0),
+		role: needsFallbackSemantics ? "button" : void 0,
+		"aria-describedby": contentId ?? void 0,
+		...props
+	});
+}
+function HoverCardContent({ className, align = "center", sideOffset = 4, ...props }) {
+	const contentId = React.useContext(HoverCardIdContext);
+	const contentRef = React.useRef(null);
+	React.useEffect(() => {
+		if (process.env.NODE_ENV === "production") return;
+		const el = contentRef.current;
+		if (!el) return;
+		if (el.querySelectorAll("a[href], button, input, select, textarea, [tabindex]").length > 0) console.warn("HoverCardContent contains interactive/focusable content — HoverCard's content is never part of the tab order (it's dismissed on trigger blur), so these controls are unreachable by keyboard. Use Popover instead if the content needs to hold interactive controls.");
+	}, []);
+	return /* @__PURE__ */ jsx(HoverCard$1.Portal, {
+		"data-slot": "hover-card-portal",
+		container: getPortalContainer(),
+		children: /* @__PURE__ */ jsx(HoverCard$1.Content, {
+			ref: contentRef,
+			id: contentId ?? void 0,
+			"data-slot": "hover-card-content",
+			align,
+			sideOffset,
+			className: cn("z-50 w-64 origin-(--radix-hover-card-content-transform-origin) rounded-lg bg-popover p-2.5 text-sm text-popover-foreground shadow-popover ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95", className),
+			...props
+		})
+	});
+}
+/**
+* WHEN TO USE
+* - Previewing an entity on hover without navigating away — a user profile,
+*   a linked record's summary, a card behind a link
+*
+* NOT WHEN
+* - Touch-primary interfaces — there's no hover event, so the content
+*   becomes unreachable; don't gate essential info behind it
+* - A short, plain-text label — use Tooltip
+* - The panel must open on click or hold interactive controls the user
+*   must act on — use Popover
+*
+* KEY RULES
+* - Opens on hover (or focus), not click — this is the trigger mechanism
+*   that separates it from Popover
+* - `openDelay`/`closeDelay` default to radix's built-in delays; set both
+*   to 0 for instant preview
+* - HoverCardContent is 16rem (w-64) wide by default; override via className
+* - `align` defaults to "center", `sideOffset` defaults to 4
+*
+* USAGE
+* <HoverCard>
+*   <HoverCardTrigger asChild><Button variant="link">@priya</Button></HoverCardTrigger>
+*   <HoverCardContent className="w-72">
+*     <div className="flex gap-3">
+*       <Avatar><AvatarImage src="..." /><AvatarFallback>CN</AvatarFallback></Avatar>
+*       <div className="grid gap-1">
+*         <p className="text-sm font-medium">Priya Nair</p>
+*         <p className="text-sm text-muted-foreground">Bio text.</p>
+*       </div>
+*     </div>
+*   </HoverCardContent>
+* </HoverCard>
+*
+* // Instant, for reviewing content without waiting on hover delay
+* <HoverCard openDelay={0} closeDelay={0}>...</HoverCard>
+*/
+//#endregion
+export { HoverCard, HoverCardContent, HoverCardTrigger };
+
+//# sourceMappingURL=hover-card.js.map

package/dist/components/ui/hover-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hover-card.js","names":[],"sources":["../../../src/components/ui/hover-card.tsx"],"sourcesContent":["/**\n * HoverCard — rich preview panel that opens on hover, with open/close delays.\n *\n * Pointer-driven — there is no click or\n * keyboard-only path to the same content, so treat it as a progressive\n * enhancement, not the only route to the information it shows.\n */\nimport * as React from \"react\"\nimport { HoverCard as HoverCardPrimitive } from \"radix-ui\"\n\nimport { cn } from \"@/lib/utils\"\nimport { getPortalContainer } from \"@/lib/scope\"\n\n// Radix's HoverCard has no Title/Description parts of its own (unlike\n// Dialog/Popover) and generates no id — this is the one thing that lets\n// Trigger and Content reference each other at all.\nconst HoverCardIdContext = React.createContext<string | null>(null)\n\nfunction HoverCard({\n  ...props\n}: React.ComponentProps<typeof HoverCardPrimitive.Root>) {\n  const contentId = React.useId()\n  return (\n    <HoverCardIdContext.Provider value={contentId}>\n      <HoverCardPrimitive.Root data-slot=\"hover-card\" {...props} />\n    </HoverCardIdContext.Provider>\n  )\n}\n\nfunction HoverCardTrigger({\n  asChild,\n  href,\n  tabIndex,\n  ...props\n}: React.ComponentProps<typeof HoverCardPrimitive.Trigger>) {\n  const contentId = React.useContext(HoverCardIdContext)\n  // Radix's Trigger renders a bare `Primitive.a` with pointer/focus\n  // handlers wired for the open/close timing, but no `href`, `role`, or\n  // `tabIndex` of its own — a plain, non-`asChild`, no-`href` trigger (the\n  // one thing the doc-comment's own USAGE example avoids by always\n  // wrapping a Button) is otherwise excluded from the tab order entirely,\n  // so keyboard/AT users never trigger the open. Only apply the fallback\n  // when `asChild` isn't wrapping something that's presumably already\n  // interactive.\n  const needsFallbackSemantics = !asChild && !href\n  return (\n    <HoverCardPrimitive.Trigger\n      data-slot=\"hover-card-trigger\"\n      asChild={asChild}\n      href={href}\n      tabIndex={tabIndex ?? (needsFallbackSemantics ? 0 : undefined)}\n      role={needsFallbackSemantics ? \"button\" : undefined}\n      // Nothing else ties the trigger to its preview content — Radix\n      // generates no id for either side to reference (confirmed: no\n      // Title/Description parts exist here, unlike Dialog/Popover).\n      // aria-describedby (not aria-labelledby: this is supplementary\n      // preview content, not the trigger's own name) is the only realistic\n      // non-visual channel, since HoverCardContentImpl deliberately pulls\n      // its interior out of the tab order.\n      aria-describedby={contentId ?? undefined}\n      {...props}\n    />\n  )\n}\n\nfunction HoverCardContent({\n  className,\n  align = \"center\",\n  sideOffset = 4,\n  ...props\n}: React.ComponentProps<typeof HoverCardPrimitive.Content>) {\n  const contentId = React.useContext(HoverCardIdContext)\n  const contentRef = React.useRef<HTMLDivElement>(null)\n\n  React.useEffect(() => {\n    if (process.env.NODE_ENV === \"production\") return\n    const el = contentRef.current\n    if (!el) return\n    // Radix force-sets tabindex=\"-1\" on every tabbable descendant here\n    // (hover-only content can't safely hold focus) — the doc comment\n    // already warns against putting interactive controls inside, but\n    // nothing enforces it; this just surfaces the mistake in dev instead\n    // of only failing silently under keyboard-only testing.\n    const focusable = el.querySelectorAll(\n      \"a[href], button, input, select, textarea, [tabindex]\"\n    )\n    if (focusable.length > 0) {\n      console.warn(\n        \"HoverCardContent contains interactive/focusable content — HoverCard's content is never part of the tab order (it's dismissed on trigger blur), so these controls are unreachable by keyboard. Use Popover instead if the content needs to hold interactive controls.\"\n      )\n    }\n  }, [])\n\n  return (\n    <HoverCardPrimitive.Portal\n      data-slot=\"hover-card-portal\"\n      container={getPortalContainer()}\n    >\n      <HoverCardPrimitive.Content\n        ref={contentRef}\n        id={contentId ?? undefined}\n        data-slot=\"hover-card-content\"\n        align={align}\n        sideOffset={sideOffset}\n        className={cn(\n          \"z-50 w-64 origin-(--radix-hover-card-content-transform-origin) rounded-lg bg-popover p-2.5 text-sm text-popover-foreground shadow-popover ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95\",\n          className\n        )}\n        {...props}\n      />\n    </HoverCardPrimitive.Portal>\n  )\n}\n\nexport { HoverCard, HoverCardTrigger, HoverCardContent }\n\n/**\n * WHEN TO USE\n * - Previewing an entity on hover without navigating away — a user profile,\n *   a linked record's summary, a card behind a link\n *\n * NOT WHEN\n * - Touch-primary interfaces — there's no hover event, so the content\n *   becomes unreachable; don't gate essential info behind it\n * - A short, plain-text label — use Tooltip\n * - The panel must open on click or hold interactive controls the user\n *   must act on — use Popover\n *\n * KEY RULES\n * - Opens on hover (or focus), not click — this is the trigger mechanism\n *   that separates it from Popover\n * - `openDelay`/`closeDelay` default to radix's built-in delays; set both\n *   to 0 for instant preview\n * - HoverCardContent is 16rem (w-64) wide by default; override via className\n * - `align` defaults to \"center\", `sideOffset` defaults to 4\n *\n * USAGE\n * <HoverCard>\n *   <HoverCardTrigger asChild><Button variant=\"link\">@priya</Button></HoverCardTrigger>\n *   <HoverCardContent className=\"w-72\">\n *     <div className=\"flex gap-3\">\n *       <Avatar><AvatarImage src=\"...\" /><AvatarFallback>CN</AvatarFallback></Avatar>\n *       <div className=\"grid gap-1\">\n *         <p className=\"text-sm font-medium\">Priya Nair</p>\n *         <p className=\"text-sm text-muted-foreground\">Bio text.</p>\n *       </div>\n *     </div>\n *   </HoverCardContent>\n * </HoverCard>\n *\n * // Instant, for reviewing content without waiting on hover delay\n * <HoverCard openDelay={0} closeDelay={0}>...</HoverCard>\n */\n"],"mappings":";;;;;;;;;;;;;AAgBA,IAAM,qBAAqB,MAAM,cAA6B,IAAI;AAElE,SAAS,UAAU,EACjB,GAAG,SACoD;CACvD,MAAM,YAAY,MAAM,MAAM;CAC9B,OACE,oBAAC,mBAAmB,UAApB;EAA6B,OAAO;EAClC,UAAA,oBAAC,YAAmB,MAApB;GAAyB,aAAU;GAAa,GAAI;EAAQ,CAAA;CACjC,CAAA;AAEjC;AAEA,SAAS,iBAAiB,EACxB,SACA,MACA,UACA,GAAG,SACuD;CAC1D,MAAM,YAAY,MAAM,WAAW,kBAAkB;CASrD,MAAM,yBAAyB,CAAC,WAAW,CAAC;CAC5C,OACE,oBAAC,YAAmB,SAApB;EACE,aAAU;EACD;EACH;EACN,UAAU,aAAa,yBAAyB,IAAI,KAAA;EACpD,MAAM,yBAAyB,WAAW,KAAA;EAQ1C,oBAAkB,aAAa,KAAA;EAC/B,GAAI;CACL,CAAA;AAEL;AAEA,SAAS,iBAAiB,EACxB,WACA,QAAQ,UACR,aAAa,GACb,GAAG,SACuD;CAC1D,MAAM,YAAY,MAAM,WAAW,kBAAkB;CACrD,MAAM,aAAa,MAAM,OAAuB,IAAI;CAEpD,MAAM,gBAAgB;EACpB,IAAA,QAAA,IAAA,aAA6B,cAAc;EAC3C,MAAM,KAAK,WAAW;EACtB,IAAI,CAAC,IAAI;EAST,IAHkB,GAAG,iBACnB,sDAEE,CAAA,CAAU,SAAS,GACrB,QAAQ,KACN,sQACF;CAEJ,GAAG,CAAC,CAAC;CAEL,OACE,oBAAC,YAAmB,QAApB;EACE,aAAU;EACV,WAAW,mBAAmB;EAE9B,UAAA,oBAAC,YAAmB,SAApB;GACE,KAAK;GACL,IAAI,aAAa,KAAA;GACjB,aAAU;GACH;GACK;GACZ,WAAW,GACT,ohBACA,SACF;GACA,GAAI;EACL,CAAA;CACwB,CAAA;AAE/B"}

package/dist/components/ui/input-group.d.ts

@@ -0,0 +1,62 @@
+/**
+ * InputGroup — Input/Textarea with attached icons, affixes, or buttons.
+ *
+ * A composite family: InputGroup is the bordered shell; InputGroupInput /
+ * InputGroupTextarea render the actual control borderless inside it;
+ * InputGroupAddon positions icons/text/buttons at any edge.
+ * The group's focus/error rings live on the shell (InputGroup), not the
+ * inner control.
+ */
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+import { Button } from "../../components/ui/button";
+declare function InputGroup({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare const inputGroupAddonVariants: (props?: ({
+    align?: "inline-start" | "inline-end" | "block-end" | "block-start" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+declare function InputGroupAddon({ className, align, ...props }: React.ComponentProps<"div"> & VariantProps<typeof inputGroupAddonVariants>): React.JSX.Element;
+type InputGroupButtonSize = "xs" | "sm";
+/** @deprecated use `iconOnly` with "xs" | "sm" — same two-axis split as Button. */
+type InputGroupButtonIconSize = "icon-xs" | "icon-sm";
+declare function InputGroupButton({ className, type, variant, size, iconOnly, ...props }: React.ComponentProps<"button"> & Pick<React.ComponentProps<typeof Button>, "variant"> & {
+    asChild?: boolean;
+    /** Height step inside the group: "xs" (default) or "sm". Icon-only is a separate axis — `iconOnly`. */
+    size?: InputGroupButtonSize | InputGroupButtonIconSize;
+    /** Square, icon-only button at the chosen `size` step (the same split Button uses). Pass `aria-label`. */
+    iconOnly?: boolean;
+}): React.JSX.Element;
+declare function InputGroupText({ className, ...props }: React.ComponentProps<"span">): React.JSX.Element;
+declare function InputGroupInput({ className, ...props }: Omit<React.ComponentProps<"input">, "size">): React.JSX.Element;
+declare function InputGroupTextarea({ className, ...props }: React.ComponentProps<"textarea">): React.JSX.Element;
+export { InputGroup, InputGroupAddon, InputGroupButton, InputGroupText, InputGroupInput, InputGroupTextarea, };
+/**
+ * WHEN TO USE
+ * - A search field with a leading icon
+ * - A URL field with an "https://" prefix or a units suffix
+ * - A textarea with a send button beneath it (a composer) — use `align="block-end"` on the addon
+ *
+ * NOT WHEN
+ * - A plain field with no icon/affix — use Input or Textarea directly
+ * - Two or more unrelated buttons standing alone — use ButtonGroup
+ *
+ * KEY RULES
+ * - Use InputGroupInput / InputGroupTextarea inside, not the plain Input/Textarea — they strip the inner border/ring so only the InputGroup shell shows focus/error state
+ * - InputGroupAddon align: inline-start, inline-end (default row, sit beside the control), block-start, block-end (full-width row above/below the control — this is what turns the group into a multi-row composer)
+ * - Clicking an addon focuses the control automatically, unless the click target is a button inside it
+ * - InputGroupButton sizes: xs (default), sm — plus `iconOnly` for a square icon button at that step
+ *   (the old icon-xs/icon-sm values still work as deprecated aliases) — matches the group's compact height
+ *
+ * USAGE
+ * <InputGroup>
+ *   <InputGroupAddon><SearchIcon /></InputGroupAddon>
+ *   <InputGroupInput placeholder="Search..." />
+ * </InputGroup>
+ *
+ * <InputGroup>
+ *   <InputGroupTextarea placeholder="Message..." />
+ *   <InputGroupAddon align="block-end">
+ *     <InputGroupButton size="sm" iconOnly aria-label="Send"><SendIcon /></InputGroupButton>
+ *   </InputGroupAddon>
+ * </InputGroup>
+ */
+//# sourceMappingURL=input-group.d.ts.map

package/dist/components/ui/input-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-group.d.ts","sourceRoot":"","sources":["../../../src/components/ui/input-group.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAGjE,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAI/C,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,qBAYvE;AAED,QAAA,MAAM,uBAAuB;;8EAmB5B,CAAA;AAED,iBAAS,eAAe,CAAC,EACvB,SAAS,EACT,KAAsB,EACtB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,YAAY,CAAC,OAAO,uBAAuB,CAAC,qBAgB5E;AAoBD,KAAK,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAAA;AACvC,mFAAmF;AACnF,KAAK,wBAAwB,GAAG,SAAS,GAAG,SAAS,CAAA;AAMrD,iBAAS,gBAAgB,CAAC,EACxB,SAAS,EACT,IAAe,EACf,OAAiB,EACjB,IAAW,EACX,QAAgB,EAChB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,GAC/B,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,MAAM,CAAC,EAAE,SAAS,CAAC,GAAG;IACrD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,uGAAuG;IACvG,IAAI,CAAC,EAAE,oBAAoB,GAAG,wBAAwB,CAAA;IACtD,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,qBAqBF;AAED,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,qBAU5E;AAED,iBAAS,eAAe,CAAC,EACvB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,qBAW7C;AAED,iBAAS,kBAAkB,CAAC,EAC1B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,UAAU,CAAC,qBAWlC;AAED,OAAO,EACL,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,kBAAkB,GACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG"}