@modern-admin/ui 0.1.0

package/src/components/form.tsx

@@ -0,0 +1,152 @@
+// shadcn-style Form: thin wrappers around react-hook-form's `Controller` that
+// pipe field state into accessible label/control/message slots. Apps render
+// `<Form>` (== FormProvider) at the top, then use `<FormField>` per input.
+
+import * as React from 'react'
+import { Slot } from '@radix-ui/react-slot'
+import {
+  Controller,
+  FormProvider,
+  useFormContext,
+  type ControllerProps,
+  type FieldPath,
+  type FieldValues,
+} from 'react-hook-form'
+import { cn } from '../lib/utils.js'
+import { Label } from './label.js'
+
+export const Form = FormProvider
+
+interface FormFieldContextValue<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> {
+  name: TName
+}
+
+const FormFieldContext = React.createContext<FormFieldContextValue | null>(null)
+
+export const FormField = <
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>({
+    ...props
+  }: ControllerProps<TFieldValues, TName>): React.ReactElement => (
+    <FormFieldContext.Provider value={{ name: props.name } as FormFieldContextValue}>
+      <Controller {...props} />
+    </FormFieldContext.Provider>
+  )
+
+interface FormItemContextValue {
+  id: string
+}
+
+const FormItemContext = React.createContext<FormItemContextValue | null>(null)
+
+export const useFormField = (): {
+  id: string
+  name: string
+  formItemId: string
+  formDescriptionId: string
+  formMessageId: string
+  error?: { message?: string }
+} => {
+  const fieldContext = React.useContext(FormFieldContext)
+  const itemContext = React.useContext(FormItemContext)
+  const { getFieldState, formState } = useFormContext()
+  if (!fieldContext) throw new Error('useFormField must be used within <FormField>')
+  if (!itemContext) throw new Error('useFormField must be used within <FormItem>')
+  const fieldState = getFieldState(fieldContext.name, formState)
+  const { id } = itemContext
+  return {
+    id,
+    name: fieldContext.name,
+    formItemId: `${id}-form-item`,
+    formDescriptionId: `${id}-form-item-description`,
+    formMessageId: `${id}-form-item-message`,
+    ...fieldState,
+  }
+}
+
+export const FormItem = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => {
+    const id = React.useId()
+    return (
+      <FormItemContext.Provider value={{ id }}>
+        <div ref={ref} className={cn('space-y-2', className)} {...props} />
+      </FormItemContext.Provider>
+    )
+  },
+)
+FormItem.displayName = 'FormItem'
+
+export const FormLabel = React.forwardRef<
+  React.ElementRef<typeof Label>,
+  React.ComponentPropsWithoutRef<typeof Label>
+>(({ className, ...props }, ref) => {
+  const { error, formItemId } = useFormField()
+  return (
+    <Label
+      ref={ref}
+      className={cn(error && 'text-destructive', className)}
+      htmlFor={formItemId}
+      {...props}
+    />
+  )
+})
+FormLabel.displayName = 'FormLabel'
+
+export const FormControl = React.forwardRef<
+  React.ElementRef<typeof Slot>,
+  React.ComponentPropsWithoutRef<typeof Slot>
+>(({ ...props }, ref) => {
+  const { error, formItemId, formDescriptionId, formMessageId } = useFormField()
+  return (
+    <Slot
+      ref={ref}
+      id={formItemId}
+      aria-describedby={
+        !error ? `${formDescriptionId}` : `${formDescriptionId} ${formMessageId}`
+      }
+      aria-invalid={!!error}
+      {...props}
+    />
+  )
+})
+FormControl.displayName = 'FormControl'
+
+export const FormDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => {
+  const { formDescriptionId } = useFormField()
+  return (
+    <p
+      ref={ref}
+      id={formDescriptionId}
+      className={cn('text-sm text-muted-foreground', className)}
+      {...props}
+    />
+  )
+})
+FormDescription.displayName = 'FormDescription'
+
+export const FormMessage = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, children, ...props }, ref) => {
+  const { error, formMessageId } = useFormField()
+  const body = error ? String(error.message ?? '') : children
+  if (!body) return null
+  return (
+    <p
+      ref={ref}
+      id={formMessageId}
+      className={cn('text-sm font-medium text-destructive', className)}
+      {...props}
+    >
+      {body}
+    </p>
+  )
+})
+FormMessage.displayName = 'FormMessage'

package/src/components/info-tooltip.tsx

@@ -0,0 +1,40 @@
+import * as React from 'react'
+import { Info } from 'lucide-react'
+import { cn } from '../lib/utils.js'
+import { Tooltip, TooltipContent, TooltipTrigger } from './tooltip.js'
+
+export interface InfoTooltipProps {
+  content: React.ReactNode
+  ariaLabel?: string
+  className?: string
+  iconClassName?: string
+  side?: React.ComponentProps<typeof TooltipContent>['side']
+}
+
+export function InfoTooltip({
+  content,
+  ariaLabel,
+  className,
+  iconClassName,
+  side = 'top',
+}: InfoTooltipProps): React.ReactElement {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          aria-label={ariaLabel}
+          className={cn(
+            'inline-flex size-4 shrink-0 items-center justify-center rounded-sm text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+            className,
+          )}
+        >
+          <Info className={cn('size-3.5', iconClassName)} />
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side={side} className="max-w-80 whitespace-pre-wrap text-left leading-relaxed">
+        {content}
+      </TooltipContent>
+    </Tooltip>
+  )
+}

package/src/components/input.tsx

@@ -0,0 +1,55 @@
+import * as React from 'react'
+import { X } from 'lucide-react'
+import { cn } from '../lib/utils.js'
+
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+  /**
+   * When provided, a clear button (×) is rendered on the right side of the
+   * input whenever it has a non-empty value. The button is hidden when the
+   * input is disabled or the value is empty.
+   */
+  onClear?: () => void
+  /** aria-label for the clear button. Defaults to "Clear". */
+  clearLabel?: string
+}
+
+export const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type, onClear, clearLabel, ...props }, ref) => {
+    const showClear = !!onClear && !!props.value && !props.disabled
+
+    const input = (
+      <input
+        type={type ?? 'text'}
+        ref={ref}
+        className={cn(
+          'flex h-9 w-full rounded-md border border-input bg-background px-3 py-1 text-sm shadow-sm transition-colors file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50',
+          // Hide native number-input spinner buttons (Firefox + WebKit/Blink).
+          '[appearance:textfield] [&::-webkit-outer-spin-button]:m-0 [&::-webkit-outer-spin-button]:appearance-none [&::-webkit-inner-spin-button]:m-0 [&::-webkit-inner-spin-button]:appearance-none',
+          showClear && 'pr-8',
+          className,
+        )}
+        {...props}
+      />
+    )
+
+    if (!onClear) return input
+
+    return (
+      <div className="relative">
+        {input}
+        {showClear && (
+          <button
+            type="button"
+            tabIndex={-1}
+            aria-label={clearLabel ?? 'Clear'}
+            onClick={onClear}
+            className="absolute right-2 top-1/2 -translate-y-1/2 rounded-sm p-0.5 text-muted-foreground opacity-50 hover:opacity-100 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+          >
+            <X className="size-3.5" />
+          </button>
+        )}
+      </div>
+    )
+  },
+)
+Input.displayName = 'Input'

package/src/components/json-editor.tsx

@@ -0,0 +1,210 @@
+// JsonEditor + JsonView — editing/displaying JSON-typed property values.
+//
+// Editor: a monospace Textarea with live parse, an inline "Format" button
+// and an error band for parse failures. Calls onChange with the parsed
+// value (object/array/primitive) — never with the raw string — so the form
+// layer stores structured data.
+//
+// View: pretty-printed <pre> for show, single-line collapsed code for list.
+
+import * as React from 'react'
+import { AlertCircle, Wand2 } from 'lucide-react'
+import { cn } from '../lib/utils.js'
+import { Button } from './button.js'
+import { Textarea } from './textarea.js'
+
+const stringify = (value: unknown): string => {
+  if (value == null) return ''
+  if (typeof value === 'string') {
+    // Strings that are themselves JSON come back from some adapters.
+    // Normalize to pretty form; otherwise leave the raw string alone.
+    try {
+      return JSON.stringify(JSON.parse(value), null, 2)
+    } catch {
+      return value
+    }
+  }
+  try {
+    return JSON.stringify(value, null, 2)
+  } catch {
+    return String(value)
+  }
+}
+
+export interface JsonEditorProps {
+  value: unknown
+  onChange(next: unknown): void
+  onBlur?(): void
+  disabled?: boolean
+  placeholder?: string
+  rows?: number
+  className?: string
+  /** Translated label for the inline "Format" button. */
+  formatLabel?: string
+  /** Translated prefix for parse-error messages. */
+  invalidLabel?: string
+}
+
+// Canonical (key-stable, no whitespace) JSON serialization used to decide
+// whether an externally arriving `value` is structurally identical to what
+// the user is currently typing. Reference comparison would always fail
+// because the parent typically returns a fresh object on every re-render.
+const canonical = (value: unknown): string => {
+  if (value == null) return ''
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return ''
+  }
+}
+
+const tryParse = (text: string): { ok: true; value: unknown } | { ok: false } => {
+  if (text.trim() === '') return { ok: true, value: null }
+  try {
+    return { ok: true, value: JSON.parse(text) as unknown }
+  } catch {
+    return { ok: false }
+  }
+}
+
+export function JsonEditor({
+  value,
+  onChange,
+  onBlur,
+  disabled,
+  placeholder = '{}',
+  rows = 8,
+  className,
+  formatLabel = 'Format',
+  invalidLabel = 'Invalid JSON',
+}: JsonEditorProps): React.ReactElement {
+  const [draft, setDraft] = React.useState<string>(() => stringify(value))
+  const [error, setError] = React.useState<string | null>(null)
+
+  // Resync the textarea only when the *external* value differs structurally
+  // from what the user is currently typing. Without the canonical-form check,
+  // every keystroke that produces valid JSON would trigger
+  //   onChange(parsed) → parent re-render → useEffect → setDraft(stringify(value))
+  // and the user's in-progress text would get auto-pretty-printed on every
+  // keystroke. By comparing canonical JSON, our own emissions become no-ops
+  // here, while genuine external resets (record reload, form.reset()) still
+  // refresh the draft.
+  React.useEffect(() => {
+    const parsed = tryParse(draft)
+    const draftCanonical = parsed.ok ? canonical(parsed.value) : '__invalid__'
+    if (draftCanonical === canonical(value)) return
+    setDraft(stringify(value))
+    setError(null)
+    // Intentionally depend only on `value`. `draft` is read via closure: we
+    // only want this to fire on external changes, not when the user types.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value])
+
+  const handleChange = (next: string): void => {
+    setDraft(next)
+    if (next.trim() === '') {
+      setError(null)
+      onChange(null)
+      return
+    }
+    const parsed = tryParse(next)
+    if (parsed.ok) {
+      setError(null)
+      onChange(parsed.value)
+    } else {
+      try {
+        JSON.parse(next)
+      } catch (e) {
+        setError(e instanceof Error ? e.message : invalidLabel)
+      }
+    }
+  }
+
+  const format = (): void => {
+    if (draft.trim() === '') return
+    try {
+      const parsed = JSON.parse(draft) as unknown
+      const pretty = JSON.stringify(parsed, null, 2)
+      setDraft(pretty)
+      setError(null)
+      onChange(parsed)
+    } catch (e) {
+      setError(e instanceof Error ? e.message : invalidLabel)
+    }
+  }
+
+  return (
+    <div className={cn('space-y-2', className)}>
+      <div className="relative">
+        <Textarea
+          value={draft}
+          onChange={(e) => handleChange(e.target.value)}
+          onBlur={onBlur}
+          disabled={disabled}
+          rows={rows}
+          spellCheck={false}
+          placeholder={placeholder}
+          className={cn(
+            'pr-20 font-mono text-xs leading-relaxed',
+            error && 'border-destructive focus-visible:ring-destructive/40',
+          )}
+        />
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          onClick={format}
+          disabled={disabled || draft.trim() === ''}
+          className="absolute right-1 top-1 h-7 px-2 text-xs"
+          title={formatLabel}
+        >
+          <Wand2 className="size-3.5" />
+          <span className="hidden sm:inline">{formatLabel}</span>
+        </Button>
+      </div>
+      {error ? (
+        <p className="flex items-start gap-1.5 text-xs text-destructive">
+          <AlertCircle className="mt-0.5 size-3.5 shrink-0" />
+          <span className="break-all">
+            {invalidLabel}: {error}
+          </span>
+        </p>
+      ) : null}
+    </div>
+  )
+}
+
+export interface JsonViewProps {
+  value: unknown
+  className?: string
+  /** Render a single-line collapsed `<code>` instead of a pretty `<pre>`. */
+  inline?: boolean
+}
+
+export function JsonView({ value, className, inline }: JsonViewProps): React.ReactElement {
+  const text = React.useMemo(() => stringify(value), [value])
+  if (inline) {
+    const compact = text.replace(/\s+/g, ' ').trim()
+    return (
+      <code
+        className={cn(
+          'line-clamp-1 max-w-[24rem] truncate font-mono text-xs text-muted-foreground',
+          className,
+        )}
+        title={text || undefined}
+      >
+        {compact || '—'}
+      </code>
+    )
+  }
+  return (
+    <pre
+      className={cn(
+        'max-h-96 overflow-auto rounded-md border border-border bg-muted/40 p-3 font-mono text-xs leading-relaxed text-foreground',
+        className,
+      )}
+    >
+      <code>{text || '—'}</code>
+    </pre>
+  )
+}

package/src/components/kbd.tsx

@@ -0,0 +1,35 @@
+import * as React from 'react'
+import { cn } from '../lib/utils.js'
+
+/**
+ * Single keyboard key glyph. Renders a `<kbd>` styled like a typical
+ * key cap. Compose multiple `<Kbd>` siblings to spell out a chord:
+ * `<Kbd>Ctrl</Kbd>+<Kbd>S</Kbd>`. The cap uses `bg-muted` /
+ * `text-foreground/80` so it reads well on any neutral surface
+ * (cards, popovers, tooltips).
+ */
+export const Kbd = React.forwardRef<
+  HTMLElement,
+  React.HTMLAttributes<HTMLElement>
+>(({ className, ...props }, ref) => (
+  <kbd
+    ref={ref}
+    className={cn(
+      'inline-flex h-5 min-w-[1.25rem] items-center justify-center rounded border border-border bg-muted px-1.5 font-mono text-[10px] font-medium text-foreground/80 shadow-[0_1px_0_0_var(--border)]',
+      className,
+    )}
+    {...props}
+  />
+))
+Kbd.displayName = 'Kbd'
+
+/**
+ * Resolve the platform-appropriate label for the primary modifier
+ * key. Renders `⌘` on macOS / iOS, `Ctrl` everywhere else.
+ */
+export function getModKeyLabel(): string {
+  if (typeof navigator === 'undefined') return 'Ctrl'
+  const platform = navigator.platform || ''
+  const ua = navigator.userAgent || ''
+  return /Mac|iPhone|iPad|iPod/i.test(platform) || /Mac/i.test(ua) ? '⌘' : 'Ctrl'
+}