veryfront 0.1.1237 → 0.1.1239

package/esm/src/react/components/ui/dropdown-menu.js

@@ -9,8 +9,8 @@ import * as React from "react";
 import { cx as cn } from "./cva.js";
 import { getPolymorphicButtonType, Slot } from "./slot.js";
 import { createAnchoredSurfaceParts, } from "./anchored-surface.js";
-import { focusWithoutScroll, getFocusableElements } from "./focus-management.js";
-const TYPEAHEAD_RESET_MS = 700;
+import { focusWithoutScroll } from "./focus-management.js";
+import { useMenuContentKeyboard } from "./menu-keyboard.js";
 // Per-skin context + machinery -- distinct from Popover's instance so a
 // Popover nested inside a DropdownMenu cannot accidentally close the menu.
 const { Context: _ctx, AnchoredRoot: _Root, AnchoredTrigger: _Trigger, AnchoredContent: _Content } = createAnchoredSurfaceParts();
@@ -27,79 +27,11 @@ export function DropdownMenuContent({ children, className, align = "start", onKe
     if (!ctx) {
         throw new Error("DropdownMenuContent must be used within <DropdownMenu>");
     }
-    const typeaheadRef = React.useRef({ buffer: "", lastTypedAt: 0 });
-    const handleKeyDown = (event) => {
-        onKeyDown?.(event);
-        if (event.defaultPrevented ||
-            event.nativeEvent.isComposing ||
-            event.nativeEvent.keyCode === 229) {
-            return;
-        }
-        const items = [...event.currentTarget.querySelectorAll("[role='menuitem']:not([aria-disabled='true'])")];
-        const activeIndex = items.indexOf(event.currentTarget.ownerDocument.activeElement);
-        const focusAt = (index) => {
-            const item = items[(index + items.length) % items.length];
-            if (item)
-                focusWithoutScroll(item);
-        };
-        switch (event.key) {
-            case "ArrowDown":
-                event.preventDefault();
-                focusAt(activeIndex + 1);
-                return;
-            case "ArrowUp":
-                event.preventDefault();
-                focusAt(activeIndex < 0 ? items.length - 1 : activeIndex - 1);
-                return;
-            case "Home":
-                event.preventDefault();
-                focusAt(0);
-                return;
-            case "End":
-                event.preventDefault();
-                focusAt(items.length - 1);
-                return;
-            case "Tab": {
-                event.preventDefault();
-                const trigger = ctx.triggerRef.current;
-                const document = event.currentTarget.ownerDocument;
-                const candidates = getFocusableElements(document.body).filter((element) => !event.currentTarget.contains(element));
-                const triggerIndex = trigger ? candidates.indexOf(trigger) : -1;
-                const next = event.shiftKey ? candidates[triggerIndex - 1] : candidates[triggerIndex + 1];
-                ctx.setOpen(false);
-                queueMicrotask(() => {
-                    if (next?.isConnected)
-                        focusWithoutScroll(next);
-                    else if (trigger?.isConnected)
-                        focusWithoutScroll(trigger);
-                });
-                return;
-            }
-        }
-        if (event.key.length !== 1 || event.altKey || event.ctrlKey ||
-            event.metaKey) {
-            return;
-        }
-        const now = Date.now();
-        const previous = typeaheadRef.current;
-        const buffer = now - previous.lastTypedAt > TYPEAHEAD_RESET_MS
-            ? event.key
-            : previous.buffer + event.key;
-        typeaheadRef.current = { buffer, lastTypedAt: now };
-        const normalizedBuffer = buffer.normalize("NFKC").toLocaleLowerCase();
-        const repeatedCharacter = [...normalizedBuffer].every((character) => character === normalizedBuffer[0]);
-        const query = repeatedCharacter ? normalizedBuffer[0] : normalizedBuffer;
-        for (let offset = 1; offset <= items.length; offset += 1) {
-            const item = items[(activeIndex + offset + items.length) % items.length];
-            const text = item?.textContent?.normalize("NFKC").trim()
-                .replace(/\s+/g, " ").toLocaleLowerCase();
-            if (item && text?.startsWith(query)) {
-                event.preventDefault();
-                focusWithoutScroll(item);
-                break;
-            }
-        }
-    };
+    const handleKeyDown = useMenuContentKeyboard({
+        onKeyDown,
+        setOpen: ctx.setOpen,
+        triggerRef: ctx.triggerRef,
+    });
     return (React.createElement(_Content, { ...props, role: "menu", "aria-orientation": "vertical", align: align, initialFocus: "[role='menuitem']:not([aria-disabled='true'])", onKeyDown: handleKeyDown, className: cn("min-w-[260px] p-2.5", className) }, children));
 }
 /** Groups related items with a tight inner gap (Studio: `gap-px p-0.5`). */

package/esm/src/react/components/ui/field.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Field: a form-field wrapper that wires a label, description, and error to a
+ * single control for accessibility. `<Field>` derives a stable base id with
+ * `React.useId()` and shares it (plus derived description/error ids and the
+ * `invalid` flag) through context, so `<FieldLabel>` targets the control via
+ * `htmlFor`, `<FieldControl>` clones its child with the matching `id` +
+ * `aria-describedby` + `aria-invalid`, and `<FieldDescription>` / `<FieldError>`
+ * expose the referenced ids. Self-contained; skinned with the veryfront theme
+ * tokens.
+ *
+ * @example
+ * ```tsx
+ * import { Field, FieldLabel, FieldControl, FieldDescription, FieldError } from "veryfront/ui";
+ * import { Input } from "veryfront/ui";
+ *
+ * <Field invalid>
+ *   <FieldLabel>Email</FieldLabel>
+ *   <FieldControl><Input type="email" /></FieldControl>
+ *   <FieldDescription>Veryfront never shares it.</FieldDescription>
+ *   <FieldError>Enter a valid email.</FieldError>
+ * </Field>;
+ * ```
+ *
+ * @module react/components/ui/field
+ */
+import * as React from "react";
+/** Props accepted by `<Field>`. */
+export interface FieldProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Mark the field invalid: flags the label/control/error via context. @default false */
+    invalid?: boolean;
+    /** React 19: ref is a regular prop. */
+    ref?: React.Ref<HTMLDivElement>;
+}
+/** The field wrapper: derives ids and provides them to its sub-parts. */
+export declare function Field({ invalid, className, children, ref, ...props }: FieldProps): React.ReactElement;
+/** Props accepted by `<FieldLabel>`. */
+export interface FieldLabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
+    /** React 19: ref is a regular prop. */
+    ref?: React.Ref<HTMLLabelElement>;
+}
+/** The field's label: wired to the control with `htmlFor`. */
+export declare function FieldLabel({ className, children, ref, ...props }: FieldLabelProps): React.ReactElement;
+/** Props accepted by `<FieldControl>`. */
+export interface FieldControlProps {
+    /** The single form control element to wire: its `id`/`aria-*` are set for you. */
+    children: React.ReactElement;
+    /** React 19: ref is forwarded onto the cloned child control (not a wrapper node). */
+    ref?: React.Ref<HTMLElement>;
+}
+/**
+ * Wiring wrapper: renders no node of its own; clones its single child control
+ * with the shared `id`, `aria-describedby` (the description, plus the error id
+ * when invalid), and `aria-invalid`.
+ */
+export declare function FieldControl({ children, ref }: FieldControlProps): React.ReactElement;
+/** Props accepted by `<FieldDescription>`. */
+export interface FieldDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {
+    /** React 19: ref is a regular prop. */
+    ref?: React.Ref<HTMLParagraphElement>;
+}
+/** Helper text describing the field: referenced by the control's `aria-describedby`. */
+export declare function FieldDescription({ className, children, id, ref, ...props }: FieldDescriptionProps): React.ReactElement;
+/** Props accepted by `<FieldError>`. */
+export interface FieldErrorProps extends React.HTMLAttributes<HTMLParagraphElement> {
+    /** React 19: ref is a regular prop. */
+    ref?: React.Ref<HTMLParagraphElement>;
+}
+/** The field's error message: a live `role="alert"`; renders nothing when empty. */
+export declare function FieldError({ className, children, id, ref, ...props }: FieldErrorProps): React.ReactElement | null;
+//# sourceMappingURL=field.d.ts.map

package/esm/src/react/components/ui/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../../../../src/src/react/components/ui/field.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAmE/B,mCAAmC;AACnC,MAAM,WAAW,UAAW,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IACtE,wFAAwF;IACxF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uCAAuC;IACvC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;CACjC;AAED,yEAAyE;AACzE,wBAAgB,KAAK,CAAC,EACpB,OAAe,EACf,SAAS,EACT,QAAQ,EACR,GAAG,EACH,GAAG,KAAK,EACT,EAAE,UAAU,GAAG,KAAK,CAAC,YAAY,CAoDjC;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAgB,SAAQ,KAAK,CAAC,mBAAmB,CAAC,gBAAgB,CAAC;IAClF,uCAAuC;IACvC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;CACnC;AAED,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,EACzB,SAAS,EACT,QAAQ,EACR,GAAG,EACH,GAAG,KAAK,EACT,EAAE,eAAe,GAAG,KAAK,CAAC,YAAY,CAiBtC;AAED,0CAA0C;AAC1C,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,QAAQ,EAAE,KAAK,CAAC,YAAY,CAAC;IAC7B,qFAAqF;IACrF,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,iBAAiB,GAAG,KAAK,CAAC,YAAY,CAuBrF;AAED,8CAA8C;AAC9C,MAAM,WAAW,qBAAsB,SAAQ,KAAK,CAAC,cAAc,CAAC,oBAAoB,CAAC;IACvF,uCAAuC;IACvC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;CACvC;AAED,wFAAwF;AACxF,wBAAgB,gBAAgB,CAAC,EAC/B,SAAS,EACT,QAAQ,EACR,EAAE,EACF,GAAG,EACH,GAAG,KAAK,EACT,EAAE,qBAAqB,GAAG,KAAK,CAAC,YAAY,CAiB5C;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAgB,SAAQ,KAAK,CAAC,cAAc,CAAC,oBAAoB,CAAC;IACjF,uCAAuC;IACvC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;CACvC;AAED,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,EACzB,SAAS,EACT,QAAQ,EACR,EAAE,EACF,GAAG,EACH,GAAG,KAAK,EACT,EAAE,eAAe,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAqB7C"}

package/esm/src/react/components/ui/field.js

@@ -0,0 +1,161 @@
+/**
+ * Field: a form-field wrapper that wires a label, description, and error to a
+ * single control for accessibility. `<Field>` derives a stable base id with
+ * `React.useId()` and shares it (plus derived description/error ids and the
+ * `invalid` flag) through context, so `<FieldLabel>` targets the control via
+ * `htmlFor`, `<FieldControl>` clones its child with the matching `id` +
+ * `aria-describedby` + `aria-invalid`, and `<FieldDescription>` / `<FieldError>`
+ * expose the referenced ids. Self-contained; skinned with the veryfront theme
+ * tokens.
+ *
+ * @example
+ * ```tsx
+ * import { Field, FieldLabel, FieldControl, FieldDescription, FieldError } from "veryfront/ui";
+ * import { Input } from "veryfront/ui";
+ *
+ * <Field invalid>
+ *   <FieldLabel>Email</FieldLabel>
+ *   <FieldControl><Input type="email" /></FieldControl>
+ *   <FieldDescription>Veryfront never shares it.</FieldDescription>
+ *   <FieldError>Enter a valid email.</FieldError>
+ * </Field>;
+ * ```
+ *
+ * @module react/components/ui/field
+ */
+import * as React from "react";
+import { composeRefs } from "./slot.js";
+import { cx as cn } from "./cva.js";
+import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
+/**
+ * Walks the element tree looking for a rendered `<FieldDescription>` and a
+ * non-empty `<FieldError>`.
+ *
+ * Presence is resolved synchronously from `children` rather than registered
+ * from an effect: `FieldControl` renders before any child effect runs, so an
+ * effect-based registry would emit `aria-describedby` a commit too late (and
+ * never at all in a non-`act` render).
+ */
+function findFieldParts(children, found = { description: false, error: false }) {
+    React.Children.forEach(children, (child) => {
+        if (!React.isValidElement(child))
+            return;
+        if (child.type === FieldDescription) {
+            found.description = true;
+            const props = child.props;
+            if (typeof props.id === "string")
+                found.descriptionId ??= props.id;
+        }
+        else if (child.type === FieldError) {
+            const props = child.props;
+            if (React.Children.count(props.children) > 0)
+                found.error = true;
+            if (typeof props.id === "string")
+                found.errorId ??= props.id;
+        }
+        const props = child.props;
+        if (props?.children)
+            findFieldParts(props.children, found);
+    });
+    return found;
+}
+const FieldContext = React.createContext(null);
+function useField(part) {
+    const ctx = React.useContext(FieldContext);
+    if (!ctx)
+        throw new Error(`<${part}> must be used within <Field>`);
+    return ctx;
+}
+/** The field wrapper: derives ids and provides them to its sub-parts. */
+export function Field({ invalid = false, className, children, ref, ...props }) {
+    const base = React.useId();
+    const staticParts = findFieldParts(children);
+    const [mountedDescriptionIds, setMountedDescriptionIds] = React.useState([]);
+    const [mountedErrorIds, setMountedErrorIds] = React.useState([]);
+    const descriptionId = staticParts.descriptionId ?? mountedDescriptionIds[0] ??
+        `${base}-description`;
+    const errorId = staticParts.errorId ?? mountedErrorIds[0] ?? `${base}-error`;
+    const registerDescription = React.useCallback((id) => {
+        setMountedDescriptionIds((ids) => ids.includes(id) ? ids : [...ids, id]);
+        return () => setMountedDescriptionIds((ids) => ids.filter((current) => current !== id));
+    }, []);
+    const registerError = React.useCallback((id) => {
+        setMountedErrorIds((ids) => ids.includes(id) ? ids : [...ids, id]);
+        return () => setMountedErrorIds((ids) => ids.filter((current) => current !== id));
+    }, []);
+    const descriptionPresent = staticParts.description || mountedDescriptionIds.length > 0;
+    const errorPresent = staticParts.error || mountedErrorIds.length > 0;
+    const ctx = React.useMemo(() => ({
+        id: base,
+        descriptionId,
+        errorId,
+        invalid,
+        descriptionPresent,
+        errorPresent,
+        registerDescription,
+        registerError,
+    }), [
+        base,
+        descriptionId,
+        errorId,
+        invalid,
+        descriptionPresent,
+        errorPresent,
+        registerDescription,
+        registerError,
+    ]);
+    return (React.createElement(FieldContext.Provider, { value: ctx },
+        React.createElement("div", { ref: ref, "data-invalid": invalid || undefined, className: cn("space-y-2", className), ...props }, children)));
+}
+/** The field's label: wired to the control with `htmlFor`. */
+export function FieldLabel({ className, children, ref, ...props }) {
+    const ctx = useField("FieldLabel");
+    return (React.createElement("label", { ref: ref, htmlFor: ctx.id, "data-invalid": ctx.invalid || undefined, className: cn("text-sm font-medium", ctx.invalid && "text-[var(--destructive)]", className), ...props }, children));
+}
+/**
+ * Wiring wrapper: renders no node of its own; clones its single child control
+ * with the shared `id`, `aria-describedby` (the description, plus the error id
+ * when invalid), and `aria-invalid`.
+ */
+export function FieldControl({ children, ref }) {
+    const ctx = useField("FieldControl");
+    const child = React.Children.only(children);
+    const childRef = child.props.ref;
+    // Reference an id only while its node is actually mounted, otherwise
+    // aria-describedby points at nothing and assistive tech resolves no text.
+    // The child's own aria-describedby is preserved and merged, not replaced.
+    const describedBy = [
+        typeof child.props["aria-describedby"] === "string" ? child.props["aria-describedby"] : null,
+        ctx.descriptionPresent ? ctx.descriptionId : null,
+        ctx.invalid && ctx.errorPresent ? ctx.errorId : null,
+    ]
+        .filter(Boolean)
+        .join(" ");
+    return React.cloneElement(child, {
+        id: ctx.id,
+        "aria-describedby": describedBy || undefined,
+        "aria-invalid": ctx.invalid || undefined,
+        // Compose so a ref set directly on the child control still receives the node.
+        ref: ref || childRef ? composeRefs(ref, childRef) : undefined,
+    });
+}
+/** Helper text describing the field: referenced by the control's `aria-describedby`. */
+export function FieldDescription({ className, children, id, ref, ...props }) {
+    const ctx = useField("FieldDescription");
+    const resolvedId = id ?? ctx.descriptionId;
+    useIsomorphicLayoutEffect(() => ctx.registerDescription(resolvedId), [
+        ctx.registerDescription,
+        resolvedId,
+    ]);
+    return (React.createElement("p", { ref: ref, id: resolvedId, className: cn("text-sm text-[var(--muted-foreground)]", className), ...props }, children));
+}
+/** The field's error message: a live `role="alert"`; renders nothing when empty. */
+export function FieldError({ className, children, id, ref, ...props }) {
+    const ctx = useField("FieldError");
+    const present = React.Children.count(children) > 0;
+    const resolvedId = id ?? ctx.errorId;
+    useIsomorphicLayoutEffect(() => present ? ctx.registerError(resolvedId) : undefined, [ctx.registerError, present, resolvedId]);
+    if (!present)
+        return null;
+    return (React.createElement("p", { ref: ref, id: resolvedId, role: "alert", "data-invalid": ctx.invalid || undefined, className: cn("text-sm text-[var(--destructive)]", className), ...props }, children));
+}

package/esm/src/react/components/ui/file-type.d.ts

@@ -1,8 +1,8 @@
 /**
- * FileType — ported 1:1 from Veryfront Studio. The canonical file-type
+ * FileType - ported 1:1 from Veryfront Studio. The canonical file-type
  * identity primitive: one distinct hue per extension. This is the single
  * sanctioned place where Tailwind named-colour utilities live (the per-file-
- * type identity palette) — every other primitive uses `[var(--token)]`. Only
+ * type identity palette) - every other primitive uses `[var(--token)]`. Only
  * the `DEFAULT` style and `vf-type`/`vf-weight` classes are remapped to
  * veryfront's vocabulary. Private to the chat module.
  *
@@ -15,12 +15,13 @@ import * as React from "react";
 /** Human label for a file extension, falling back to the media type. */
 export declare function getFileTypeLabel(ext: string, mediaType?: string): string;
 /** Props accepted by `<FileType>` / `<FileTypeThumb>`. */
-export interface FileTypeProps {
+export interface FileTypeProps extends React.HTMLAttributes<HTMLDivElement> {
     extension: string;
-    className?: string;
+    /** React 19: ref is a regular prop, forwarded to the root node. */
+    ref?: React.Ref<HTMLDivElement>;
 }
-/** Soft-fill badge — rounded square, tinted background, extension label. */
-export declare function FileType({ extension, className }: FileTypeProps): React.ReactElement;
-/** Solid-fill thumbnail — full-saturation square with white `.ext` text. */
-export declare function FileTypeThumb({ extension, className }: FileTypeProps): React.ReactElement;
+/** Soft-fill badge - rounded square, tinted background, extension label. */
+export declare function FileType({ extension, className, ref, ...props }: FileTypeProps): React.ReactElement;
+/** Solid-fill thumbnail - full-saturation square with white `.ext` text. */
+export declare function FileTypeThumb({ extension, className, ref, ...props }: FileTypeProps): React.ReactElement;
 //# sourceMappingURL=file-type.d.ts.map

package/esm/src/react/components/ui/file-type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-type.d.ts","sourceRoot":"","sources":["../../../../../src/src/react/components/ui/file-type.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA0N/B,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CACtB,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,aAAa,GACtC,KAAK,CAAC,YAAY,CAgBpB;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAC3B,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,aAAa,GACtC,KAAK,CAAC,YAAY,CAcpB"}
+{"version":3,"file":"file-type.d.ts","sourceRoot":"","sources":["../../../../../src/src/react/components/ui/file-type.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA0N/B,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAc,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;CACjC;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CACtB,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,KAAK,EAAE,EAAE,aAAa,GACrD,KAAK,CAAC,YAAY,CAkBpB;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAC3B,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,KAAK,EAAE,EAAE,aAAa,GACrD,KAAK,CAAC,YAAY,CAgBpB"}

package/esm/src/react/components/ui/file-type.js

@@ -1,8 +1,8 @@
 /**
- * FileType — ported 1:1 from Veryfront Studio. The canonical file-type
+ * FileType - ported 1:1 from Veryfront Studio. The canonical file-type
  * identity primitive: one distinct hue per extension. This is the single
  * sanctioned place where Tailwind named-colour utilities live (the per-file-
- * type identity palette) — every other primitive uses `[var(--token)]`. Only
+ * type identity palette) - every other primitive uses `[var(--token)]`. Only
  * the `DEFAULT` style and `vf-type`/`vf-weight` classes are remapped to
  * veryfront's vocabulary. Private to the chat module.
  *
@@ -219,16 +219,16 @@ export function getFileTypeLabel(ext, mediaType) {
     return EXT_STYLES[ext.toLowerCase()]?.label ??
         mediaType?.split("/").pop()?.toUpperCase() ?? "File";
 }
-/** Soft-fill badge — rounded square, tinted background, extension label. */
-export function FileType({ extension, className }) {
+/** Soft-fill badge - rounded square, tinted background, extension label. */
+export function FileType({ extension, className, ref, ...props }) {
     const { bg, text } = lookup(extension);
-    return (React.createElement("div", { className: cn("size-9 shrink-0 rounded-lg flex items-center justify-center", bg, className), "data-testid": "file-type-badge" },
+    return (React.createElement("div", { ref: ref, "data-testid": "file-type-badge", ...props, className: cn("size-9 shrink-0 rounded-lg flex items-center justify-center", bg, className) },
         React.createElement("span", { className: cn("text-xs font-medium leading-none", text) }, extension.toUpperCase())));
 }
-/** Solid-fill thumbnail — full-saturation square with white `.ext` text. */
-export function FileTypeThumb({ extension, className }) {
+/** Solid-fill thumbnail - full-saturation square with white `.ext` text. */
+export function FileTypeThumb({ extension, className, ref, ...props }) {
     const { solid } = lookup(extension);
-    return (React.createElement("div", { className: cn("flex size-10 shrink-0 items-center justify-center rounded-md text-xs font-medium text-white", solid, className), "data-testid": "file-type-thumb" },
+    return (React.createElement("div", { ref: ref, "data-testid": "file-type-thumb", ...props, className: cn("flex size-10 shrink-0 items-center justify-center rounded-md text-xs font-medium text-white", solid, className) },
         React.createElement("span", null,
             ".",
             extension)));

package/esm/src/react/components/ui/hover-card.d.ts

@@ -0,0 +1,82 @@
+/**
+ * HoverCard - a non-modal preview surface that opens when the user hovers or
+ * focuses a trigger and closes when they leave or blur it. Built on the same
+ * `Floating` portal + positioning machinery as Popover (anchored below the
+ * trigger, portalled into the nearest `[data-vf-ui]`/`[data-vf-chat]` token
+ * scope, dismisses on outside-click / `Escape`), but opens on hover intent
+ * instead of click. Ideal for rich previews - a user card on a `@mention`, a
+ * repo card on a link. Skinned entirely with veryfront theme tokens.
+ *
+ * `openDelay` / `closeDelay` gate the hover transitions so brief pointer passes
+ * don't flicker the card, and moving the pointer from the trigger onto the card
+ * keeps it open. Keyboard users get the card immediately on focus, and it
+ * closes on blur.
+ *
+ * @example
+ * ```tsx
+ * <HoverCard>
+ *   <HoverCardTrigger asChild>
+ *     <a href="/users/koji">@koji</a>
+ *   </HoverCardTrigger>
+ *   <HoverCardContent>
+ *     <div className="flex flex-col gap-1">
+ *       <span className="font-semibold">Koji</span>
+ *       <span className="text-[var(--muted-foreground)]">Design systems</span>
+ *     </div>
+ *   </HoverCardContent>
+ * </HoverCard>
+ * ```
+ *
+ * @module react/components/ui/hover-card
+ */
+import * as React from "react";
+/** Props accepted by `<HoverCard>`. */
+export interface HoverCardProps {
+    /** The trigger and content parts to compose. */
+    children: React.ReactNode;
+    /** Controlled open state (pair with `onOpenChange`). */
+    open?: boolean;
+    /** Initial open state when uncontrolled. @default false */
+    defaultOpen?: boolean;
+    /** Fires when the open state changes (hover/focus in, leave/blur out). */
+    onOpenChange?: (open: boolean) => void;
+    /** Delay in ms before the card opens after pointer enter. @default 700 */
+    openDelay?: number;
+    /** Delay in ms before the card closes after pointer leave. @default 300 */
+    closeDelay?: number;
+}
+/**
+ * HoverCard root - owns open state and the hover/focus timers. Renders no node
+ * of its own; the positioning anchor is the trigger element, carried on context.
+ */
+export declare function HoverCard({ children, open, defaultOpen, onOpenChange, openDelay, closeDelay, }: HoverCardProps): React.ReactElement;
+/** Props accepted by `<HoverCardTrigger>`. */
+export interface HoverCardTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Render as a Slot, merging the trigger behaviour onto the child element. */
+    asChild?: boolean;
+    /** React 19: ref is a regular prop; forwarded to the anchor node. */
+    ref?: React.Ref<HTMLButtonElement>;
+}
+/**
+ * Trigger - carries the positioning-anchor ref and the hover/focus intent.
+ * Opens the card on pointer enter (after `openDelay`) or immediately on focus;
+ * closes it on pointer leave (after `closeDelay`) or on blur. `asChild` merges
+ * the behaviour onto the child element, which must forward `ref` to its DOM node
+ * (a child that drops `ref` leaves the card unanchored - `Floating` warns).
+ */
+export declare function HoverCardTrigger({ children, asChild, ref, onMouseEnter, onMouseLeave, onFocus, onBlur, ...props }: HoverCardTriggerProps): React.ReactElement;
+/** Props accepted by `<HoverCardContent>`. */
+export interface HoverCardContentProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Horizontal alignment relative to the trigger. @default "start" */
+    align?: "start" | "end";
+    /** Consumer ref for the surface node (forwarded through `Floating`). */
+    ref?: React.Ref<HTMLDivElement>;
+}
+/**
+ * HoverCard surface - the portalled floating card, rendered while open. Non-modal
+ * (no `role="dialog"`, no focus trap): it's a supplementary preview, so the
+ * trigger keeps focus. Keeps itself open while the pointer is over it and closes
+ * shortly after the pointer leaves. Base classes mirror Popover's surface.
+ */
+export declare function HoverCardContent({ children, className, align, ref, onMouseEnter, onMouseLeave, ...props }: HoverCardContentProps): React.ReactElement | null;
+//# sourceMappingURL=hover-card.d.ts.map

package/esm/src/react/components/ui/hover-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hover-card.d.ts","sourceRoot":"","sources":["../../../../../src/src/react/components/ui/hover-card.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA0B/B,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,wDAAwD;IACxD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2DAA2D;IAC3D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,IAAI,EACJ,WAAW,EACX,YAAY,EACZ,SAAe,EACf,UAAgB,GACjB,EAAE,cAAc,GAAG,KAAK,CAAC,YAAY,CAoErC;AAED,8CAA8C;AAC9C,MAAM,WAAW,qBAAsB,SAAQ,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC;IAC1F,8EAA8E;IAC9E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,OAAO,EACP,GAAG,EACH,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,MAAM,EACN,GAAG,KAAK,EACT,EAAE,qBAAqB,GAAG,KAAK,CAAC,YAAY,CAgC5C;AAED,8CAA8C;AAC9C,MAAM,WAAW,qBAAsB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IACjF,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IACxB,wEAAwE;IACxE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,SAAS,EACT,KAAe,EACf,GAAG,EACH,YAAY,EACZ,YAAY,EACZ,GAAG,KAAK,EACT,EAAE,qBAAqB,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CA6BnD"}

package/esm/src/react/components/ui/hover-card.js

@@ -0,0 +1,140 @@
+/**
+ * HoverCard - a non-modal preview surface that opens when the user hovers or
+ * focuses a trigger and closes when they leave or blur it. Built on the same
+ * `Floating` portal + positioning machinery as Popover (anchored below the
+ * trigger, portalled into the nearest `[data-vf-ui]`/`[data-vf-chat]` token
+ * scope, dismisses on outside-click / `Escape`), but opens on hover intent
+ * instead of click. Ideal for rich previews - a user card on a `@mention`, a
+ * repo card on a link. Skinned entirely with veryfront theme tokens.
+ *
+ * `openDelay` / `closeDelay` gate the hover transitions so brief pointer passes
+ * don't flicker the card, and moving the pointer from the trigger onto the card
+ * keeps it open. Keyboard users get the card immediately on focus, and it
+ * closes on blur.
+ *
+ * @example
+ * ```tsx
+ * <HoverCard>
+ *   <HoverCardTrigger asChild>
+ *     <a href="/users/koji">@koji</a>
+ *   </HoverCardTrigger>
+ *   <HoverCardContent>
+ *     <div className="flex flex-col gap-1">
+ *       <span className="font-semibold">Koji</span>
+ *       <span className="text-[var(--muted-foreground)]">Design systems</span>
+ *     </div>
+ *   </HoverCardContent>
+ * </HoverCard>
+ * ```
+ *
+ * @module react/components/ui/hover-card
+ */
+import * as React from "react";
+import { cx as cn } from "./cva.js";
+import { composeRefs, Slot } from "./slot.js";
+import { Floating } from "./floating.js";
+import { useDisclosure } from "./disclosure.js";
+const HoverCardContext = React.createContext(null);
+/**
+ * HoverCard root - owns open state and the hover/focus timers. Renders no node
+ * of its own; the positioning anchor is the trigger element, carried on context.
+ */
+export function HoverCard({ children, open, defaultOpen, onOpenChange, openDelay = 700, closeDelay = 300, }) {
+    const { open: isOpen, setOpen } = useDisclosure({ open, defaultOpen, onOpenChange });
+    const anchorRef = React.useRef(null);
+    const openTimer = React.useRef(null);
+    const closeTimer = React.useRef(null);
+    // Keep `setOpen` reachable from timer callbacks without re-arming timers when
+    // a parent re-render swaps the callback identity.
+    const setOpenRef = React.useRef(setOpen);
+    setOpenRef.current = setOpen;
+    const cancelPending = React.useCallback(() => {
+        if (openTimer.current != null) {
+            clearTimeout(openTimer.current);
+            openTimer.current = null;
+        }
+        if (closeTimer.current != null) {
+            clearTimeout(closeTimer.current);
+            closeTimer.current = null;
+        }
+    }, []);
+    const scheduleOpen = React.useCallback(() => {
+        cancelPending();
+        if (openDelay <= 0) {
+            setOpenRef.current(true);
+            return;
+        }
+        openTimer.current = setTimeout(() => setOpenRef.current(true), openDelay);
+    }, [openDelay, cancelPending]);
+    const scheduleClose = React.useCallback(() => {
+        cancelPending();
+        if (closeDelay <= 0) {
+            setOpenRef.current(false);
+            return;
+        }
+        closeTimer.current = setTimeout(() => setOpenRef.current(false), closeDelay);
+    }, [closeDelay, cancelPending]);
+    const openNow = React.useCallback(() => {
+        cancelPending();
+        setOpenRef.current(true);
+    }, [cancelPending]);
+    const closeNow = React.useCallback(() => {
+        cancelPending();
+        setOpenRef.current(false);
+    }, [cancelPending]);
+    // Clear any dangling timer on unmount so a delayed open/close can't fire into
+    // an unmounted tree.
+    React.useEffect(() => cancelPending, [cancelPending]);
+    const ctx = React.useMemo(() => ({
+        open: isOpen,
+        anchorRef,
+        scheduleOpen,
+        scheduleClose,
+        cancelPending,
+        openNow,
+        closeNow,
+    }), [isOpen, scheduleOpen, scheduleClose, cancelPending, openNow, closeNow]);
+    return React.createElement(HoverCardContext.Provider, { value: ctx }, children);
+}
+/**
+ * Trigger - carries the positioning-anchor ref and the hover/focus intent.
+ * Opens the card on pointer enter (after `openDelay`) or immediately on focus;
+ * closes it on pointer leave (after `closeDelay`) or on blur. `asChild` merges
+ * the behaviour onto the child element, which must forward `ref` to its DOM node
+ * (a child that drops `ref` leaves the card unanchored - `Floating` warns).
+ */
+export function HoverCardTrigger({ children, asChild, ref, onMouseEnter, onMouseLeave, onFocus, onBlur, ...props }) {
+    const ctx = React.useContext(HoverCardContext);
+    const Comp = asChild ? Slot : "button";
+    return (React.createElement(Comp, { ...(asChild ? {} : { type: "button" }), ref: composeRefs(ctx?.anchorRef, ref), "data-state": ctx?.open ? "open" : "closed", onMouseEnter: (e) => {
+            onMouseEnter?.(e);
+            ctx?.scheduleOpen();
+        }, onMouseLeave: (e) => {
+            onMouseLeave?.(e);
+            ctx?.scheduleClose();
+        }, onFocus: (e) => {
+            onFocus?.(e);
+            ctx?.openNow();
+        }, onBlur: (e) => {
+            onBlur?.(e);
+            ctx?.closeNow();
+        }, ...props }, children));
+}
+/**
+ * HoverCard surface - the portalled floating card, rendered while open. Non-modal
+ * (no `role="dialog"`, no focus trap): it's a supplementary preview, so the
+ * trigger keeps focus. Keeps itself open while the pointer is over it and closes
+ * shortly after the pointer leaves. Base classes mirror Popover's surface.
+ */
+export function HoverCardContent({ children, className, align = "start", ref, onMouseEnter, onMouseLeave, ...props }) {
+    const ctx = React.useContext(HoverCardContext);
+    if (!ctx)
+        return null;
+    return (React.createElement(Floating, { anchorRef: ctx.anchorRef, open: ctx.open, align: align, onDismiss: ctx.closeNow, contentRef: ref, "data-state": ctx.open ? "open" : "closed", onMouseEnter: (e) => {
+            onMouseEnter?.(e);
+            ctx.cancelPending();
+        }, onMouseLeave: (e) => {
+            onMouseLeave?.(e);
+            ctx.scheduleClose();
+        }, className: cn("z-50 w-64 overflow-hidden rounded-lg border border-[var(--separator)]", "bg-[var(--popover)] p-4 text-sm text-[var(--popover-foreground)] shadow-sm outline-none", className), ...props }, children));
+}