@withmata/blueprints 0.3.5 → 0.5.0

package/blueprints/features/ui-shared-components/files/ui/components/ui/entity-select.tsx

@@ -0,0 +1,110 @@
+"use client";
+
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxSeparator,
+} from "#components/ui/combobox";
+import { PlusIcon } from "@phosphor-icons/react/Plus";
+import { type ReactNode, useState } from "react";
+
+export interface EntitySelectProps<T> {
+  value: string;
+  onValueChange: (value: string) => void;
+  options: T[];
+  getOptionId: (option: T) => string;
+  getOptionName: (option: T) => string;
+  renderOption: (option: T) => ReactNode;
+  renderSelected: (option: T, onRemove: () => void) => ReactNode;
+  placeholder?: string;
+  disabled?: boolean;
+  isLoading?: boolean;
+  createLabel?: string;
+  onCreateNew?: () => void;
+}
+
+export function EntitySelect<T>({
+  value,
+  onValueChange,
+  options,
+  getOptionId,
+  getOptionName,
+  renderOption,
+  renderSelected,
+  placeholder = "Select...",
+  disabled = false,
+  isLoading = false,
+  createLabel = "Create new",
+  onCreateNew,
+}: EntitySelectProps<T>) {
+  const [inputValue, setInputValue] = useState("");
+
+  const selectedOption = options.find((o) => getOptionId(o) === value);
+
+  // If a value is selected, show the selected card instead of the combobox
+  if (selectedOption) {
+    return renderSelected(selectedOption, () => {
+      onValueChange("");
+      setInputValue("");
+    });
+  }
+
+  const filteredOptions = inputValue
+    ? options.filter((o) =>
+        getOptionName(o).toLowerCase().includes(inputValue.toLowerCase()),
+      )
+    : options;
+
+  return (
+    <Combobox
+      value={value}
+      onValueChange={(val) => {
+        if (val === "__create_new__") {
+          onCreateNew?.();
+          return;
+        }
+        onValueChange(val as string);
+        setInputValue("");
+      }}
+    >
+      <ComboboxInput
+        placeholder={placeholder}
+        disabled={disabled}
+        value={inputValue}
+        onChange={(e) => setInputValue(e.target.value)}
+      />
+      <ComboboxContent>
+        <ComboboxList>
+          {isLoading && filteredOptions.length === 0 && (
+            <p className="text-muted-foreground flex items-center justify-center gap-2 py-2 text-center text-sm">
+              <span className="inline-block h-3 w-3 animate-spin rounded-full border-2 border-current border-t-transparent" />
+              Loading...
+            </p>
+          )}
+          {!isLoading && filteredOptions.length === 0 && options.length > 0 && (
+            <p className="text-muted-foreground py-2 text-center text-sm">
+              No results found
+            </p>
+          )}
+          {filteredOptions.map((option) => (
+            <ComboboxItem key={getOptionId(option)} value={getOptionId(option)}>
+              {renderOption(option)}
+            </ComboboxItem>
+          ))}
+          {onCreateNew && (
+            <>
+              {(isLoading || options.length > 0) && <ComboboxSeparator />}
+              <ComboboxItem value="__create_new__" className="py-2.5">
+                <PlusIcon className="size-4" />
+                {createLabel}
+              </ComboboxItem>
+            </>
+          )}
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  );
+}

package/blueprints/features/ui-shared-components/files/ui/components/ui/field.tsx

@@ -0,0 +1,237 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import { useMemo } from "react";
+import { Label } from "#components/ui/label";
+import { Separator } from "#components/ui/separator";
+import { cn } from "#utils/cn";
+
+function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
+  return (
+    <fieldset
+      data-slot="field-set"
+      className={cn(
+        "gap-6 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3 flex flex-col",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function FieldLegend({
+  className,
+  variant = "legend",
+  ...props
+}: React.ComponentProps<"legend"> & { variant?: "legend" | "label" }) {
+  return (
+    <legend
+      data-slot="field-legend"
+      data-variant={variant}
+      className={cn(
+        "mb-3 font-medium data-[variant=label]:text-sm data-[variant=legend]:text-base",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="field-group"
+      className={cn(
+        "gap-7 data-[slot=checkbox-group]:gap-3 [&>[data-slot=field-group]]:gap-4 group/field-group @container/field-group flex w-full flex-col",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+const fieldVariants = cva(
+  "data-[invalid=true]:text-destructive gap-1.5 group/field flex w-full",
+  {
+    variants: {
+      orientation: {
+        vertical: "flex-col [&>*]:w-full [&>.sr-only]:w-auto",
+        horizontal:
+          "flex-row items-center [&>[data-slot=field-label]]:flex-auto has-[>[data-slot=field-content]]:items-start has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
+        responsive:
+          "flex-col [&>*]:w-full [&>.sr-only]:w-auto @md/field-group:flex-row @md/field-group:items-center @md/field-group:[&>*]:w-auto @md/field-group:[&>[data-slot=field-label]]:flex-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
+      },
+    },
+    defaultVariants: {
+      orientation: "vertical",
+    },
+  },
+);
+
+function Field({
+  className,
+  orientation = "vertical",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="field"
+      data-orientation={orientation}
+      className={cn(fieldVariants({ orientation }), className)}
+      {...props}
+    />
+  );
+}
+
+function FieldContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="field-content"
+      className={cn(
+        "gap-1 group/field-content flex flex-1 flex-col leading-snug",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function FieldLabel({
+  className,
+  ...props
+}: React.ComponentProps<typeof Label>) {
+  return (
+    <Label
+      data-slot="field-label"
+      className={cn(
+        "has-data-checked:bg-primary/5 has-data-checked:border-primary/50 dark:has-data-checked:bg-primary/10 gap-0.5 group-data-[disabled=true]/field:opacity-50 has-[>[data-slot=field]]:rounded-xl has-[>[data-slot=field]]:border [&>*]:data-[slot=field]:p-4 group/field-label peer/field-label flex w-fit leading-snug",
+        "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function FieldTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="field-label"
+      className={cn(
+        "gap-2 text-sm font-medium group-data-[disabled=true]/field:opacity-50 flex w-fit items-center leading-snug",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function FieldDescription({ className, ...props }: React.ComponentProps<"p">) {
+  return (
+    <p
+      data-slot="field-description"
+      className={cn(
+        "text-muted-foreground text-left text-xs [[data-variant=legend]+&]:-mt-1.5 leading-normal font-normal group-has-[[data-orientation=horizontal]]/field:text-balance",
+        "last:mt-0 nth-last-2:-mt-1",
+        "[&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function FieldSeparator({
+  children,
+  className,
+  ...props
+}: React.ComponentProps<"div"> & {
+  children?: React.ReactNode;
+}) {
+  return (
+    <div
+      data-slot="field-separator"
+      data-content={!!children}
+      className={cn(
+        "-my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2 relative",
+        className,
+      )}
+      {...props}
+    >
+      <Separator className="absolute inset-0 top-1/2" />
+      {children && (
+        <span
+          className="text-muted-foreground px-2 bg-background relative mx-auto block w-fit"
+          data-slot="field-separator-content"
+        >
+          {children}
+        </span>
+      )}
+    </div>
+  );
+}
+
+function FieldError({
+  className,
+  children,
+  errors,
+  ...props
+}: React.ComponentProps<"div"> & {
+  errors?: Array<{ message?: string } | undefined>;
+}) {
+  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 (
+      <ul className="ml-4 flex list-disc flex-col gap-1">
+        {uniqueErrors.map(
+          (error, index) =>
+            error?.message && <li key={index}>{error.message}</li>,
+        )}
+      </ul>
+    );
+  }, [children, errors]);
+
+  if (!content) {
+    return null;
+  }
+
+  return (
+    <div
+      role="alert"
+      data-slot="field-error"
+      className={cn("text-destructive text-sm font-normal", className)}
+      {...props}
+    >
+      {content}
+    </div>
+  );
+}
+
+export {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLegend,
+  FieldSeparator,
+  FieldSet,
+  FieldContent,
+  FieldTitle,
+};

package/blueprints/features/ui-shared-components/files/ui/components/ui/form-field.tsx

@@ -0,0 +1,217 @@
+"use client";
+
+import { Info, X } from "@phosphor-icons/react";
+import { useEffect, useRef } from "react";
+import type * as React from "react";
+import { Field, FieldDescription, FieldLabel } from "#components/ui/field";
+import {
+  Popover,
+  PopoverAnchor,
+  PopoverClose,
+  PopoverContent,
+} from "#components/ui/popover";
+
+export interface FieldHint {
+  directive: string;
+  example: string;
+  label?: string;
+}
+
+export interface FormFieldProps {
+  label: string;
+  name: string;
+  description?: string | React.ReactNode;
+  counter?: React.ReactNode;
+  required?: boolean;
+  error?: string;
+  onFocus?: (element: HTMLElement) => void;
+  hint?: FieldHint;
+  isHintOpen?: boolean;
+  onHintOpen?: (fieldName: string) => void;
+  onHintClose?: () => void;
+  showHints?: boolean;
+  autoShowOnFocus?: boolean;
+  onToggleHints?: () => void;
+  children: React.ReactNode;
+}
+
+export function FormField({
+  label,
+  name,
+  description,
+  counter,
+  required = false,
+  error,
+  onFocus,
+  hint,
+  isHintOpen = false,
+  onHintOpen,
+  onHintClose,
+  showHints = true,
+  autoShowOnFocus = true,
+  onToggleHints,
+  children,
+}: FormFieldProps) {
+  const anchorRef = useRef<HTMLDivElement>(null);
+
+  // Hide popover when anchor scrolls out of its scroll container
+  useEffect(() => {
+    if (!isHintOpen || !hint || !anchorRef.current) return;
+
+    const el = anchorRef.current;
+    // Find the nearest scrollable ancestor
+    const scrollParent = el.closest("[data-slot='scroll-area'], .overflow-y-auto, [style*='overflow']") || el.parentElement;
+    if (!scrollParent) return;
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (!entry?.isIntersecting) {
+          onHintClose?.();
+        }
+      },
+      { root: scrollParent, threshold: 0.1 },
+    );
+
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [isHintOpen, hint, onHintClose]);
+
+  const handleFocusCapture = (e: React.FocusEvent<HTMLDivElement>) => {
+    if (onFocus && e.currentTarget) {
+      onFocus(e.currentTarget);
+    }
+
+    if (hint && showHints && autoShowOnFocus && onHintOpen) {
+      onHintOpen(name);
+    }
+  };
+
+  const handleInfoClick = () => {
+    if (isHintOpen) {
+      onHintClose?.();
+    } else {
+      onHintOpen?.(name);
+    }
+  };
+
+  // The directive from the hint replaces the description when available
+  const displayDescription = hint ? hint.directive : description;
+
+  return (
+    <Field className="!gap-0">
+      {/* Label + description group — tight spacing */}
+      <div className="space-y-1.5">
+        <div className="flex items-center gap-1.5">
+          <FieldLabel htmlFor={name} className="mb-0 text-sm">
+            {label}
+            {required && <span className="text-destructive">*</span>}
+          </FieldLabel>
+          {hint && (
+            <button
+              type="button"
+              className="text-muted-foreground hover:text-foreground transition-colors"
+              onClick={handleInfoClick}
+              aria-label={`Show hint for ${label}`}
+            >
+              <Info className="size-3.5" />
+            </button>
+          )}
+        </div>
+        {(displayDescription || counter) && (
+          <div className="flex items-center justify-between gap-2">
+            {displayDescription && (
+              <FieldDescription>{displayDescription}</FieldDescription>
+            )}
+            {counter && (
+              <span className="text-xs text-muted-foreground shrink-0">
+                {counter}
+              </span>
+            )}
+          </div>
+        )}
+      </div>
+
+      {/* Field input — more space above, tight to error below */}
+      <div className="mt-3">
+      <Popover
+        open={isHintOpen && !!hint}
+        onOpenChange={(open) => {
+          if (!open) onHintClose?.();
+        }}
+      >
+        <PopoverAnchor asChild>
+          <div ref={anchorRef} onFocusCapture={handleFocusCapture}>
+            {children}
+          </div>
+        </PopoverAnchor>
+        <PopoverContent
+          side="right"
+          align="start"
+          sideOffset={20}
+          collisionPadding={16}
+          className="w-80 p-0 overflow-hidden"
+          onOpenAutoFocus={(e) => e.preventDefault()}
+          onCloseAutoFocus={(e) => e.preventDefault()}
+          onFocusOutside={(e) => e.preventDefault()}
+          hideWhenDetached
+        >
+          {/* Arrow */}
+          <div className="absolute left-0 top-4 -translate-x-full">
+            <div className="w-0 h-0 border-t-[8px] border-t-transparent border-b-[8px] border-b-transparent border-r-[8px] border-r-border" />
+            <div className="w-0 h-0 border-t-[7px] border-t-transparent border-b-[7px] border-b-transparent border-r-[7px] border-r-popover absolute top-[1px] left-[1px]" />
+          </div>
+
+          {/* Header: info icon + "Info" label + close */}
+          <div className="px-3 pt-2.5 pb-2 flex items-center gap-1.5">
+            <div className="flex items-center gap-1.5">
+              <Info className="size-4 text-primary shrink-0" />
+              <span className="text-xs text-primary leading-none translate-y-px">
+                Info
+              </span>
+            </div>
+            <div className="flex-1" />
+            <PopoverClose asChild>
+              <button
+                type="button"
+                className="text-muted-foreground hover:text-foreground transition-colors shrink-0"
+                aria-label="Close hint"
+              >
+                <X className="size-3.5" weight="bold" />
+              </button>
+            </PopoverClose>
+          </div>
+
+          {/* Example content */}
+          <div className="bg-muted px-3 py-2.5 border-t border-border/50">
+            <p className="text-[11px] font-medium text-muted-foreground mb-1">
+              {hint?.label ?? "Good example"}
+            </p>
+            <p className="text-sm leading-relaxed">{hint?.example}</p>
+          </div>
+
+          {/* Footer: toggle hints */}
+          {onToggleHints && (
+            <div className="px-3 pt-1.5 pb-2.5 border-t border-border/50">
+              <button
+                type="button"
+                className="text-[11px] text-muted-foreground hover:text-foreground hover:underline transition-colors"
+                onClick={() => {
+                  if (showHints) {
+                    onHintClose?.();
+                  }
+                  onToggleHints();
+                }}
+              >
+                {showHints
+                  ? "Don\u0027t show hints"
+                  : "Always show hints"}
+              </button>
+            </div>
+          )}
+        </PopoverContent>
+      </Popover>
+      </div>
+      {error && <p className="mt-1.5 text-sm text-destructive">{error}</p>}
+    </Field>
+  );
+}