// Radix UI Primitives
import { Slot } from "@radix-ui/react-slot";
import * as Dialog from "@radix-ui/react-dialog";
import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
import * as Select from "@radix-ui/react-select";

// Styling
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

// State Management
import { observer } from "mobx-react-lite";
import { makeAutoObservable, runInAction, toJS } from "mobx";

// Authentication
import { useAuth } from "@/providers/AuthProvider";
import type { IAuthProvider, Session } from "@/providers/IAuthProvider";

// React
import { forwardRef, useEffect, useRef, type ComponentPropsWithoutRef } from "react";

// Use Radix UI Dialog for modals
<Dialog.Root open={isOpen} onOpenChange={setIsOpen}>
  <Dialog.Trigger asChild>
    <button>Open Modal</button>
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay className="fixed inset-0 bg-black/50" />
    <Dialog.Content className="fixed left-1/2 top-1/2 ...">
      <Dialog.Title>Modal Title</Dialog.Title>
      <Dialog.Description>Modal description</Dialog.Description>
      {/* Content */}
      <Dialog.Close asChild>
        <button>Close</button>
      </Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

const buttonVariants = cva(
  "inline-flex items-center justify-center gap-2 rounded-md font-medium transition-colors",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent"
      },
      size: {
        default: "h-9 px-4 py-2",
        sm: "h-8 px-3 text-sm",
        lg: "h-10 px-8"
      }
    },
    defaultVariants: { variant: "default", size: "default" }
  }
);

const Button = forwardRef<HTMLButtonElement, ComponentProps>(
  ({ className, variant, size, ...props }, ref) => (
    <button
      className={cn(buttonVariants({ variant, size, className }))}
      ref={ref}
      {...props}
    />
  )
);

// ✅ Correct: Wrap with observer HOC
export const MyComponent = observer(() => {
  const store = useMyStore();
  return <div>{store.items.map(item => <Item key={item.id} {...item} />)}</div>;
});

// ✅ Correct: Never spread observable arrays
const itemsCopy = store.items.slice(); // or [...toJS(store.items)]

// ✅ Correct: Use runInAction for async updates
async fetchData() {
  const response = await api.get('/data');
  runInAction(() => {
    this.data = response.data;
    this.loading = false;
  });
}

// Get current user from unified interface
const { session, loading } = useAuth();

if (loading) return <LoadingSpinner />;
if (!session) return <Navigate to="/login" />;

// Session has JWT claims: org_id, user_role, permissions, scope_path
const { user_role, org_id, permissions } = session;

// ✅ Correct: Add ARIA labels and keyboard handling
<button
  aria-label="Delete medication"
  aria-describedby="delete-warning"
  onClick={handleDelete}
  onKeyDown={(e) => e.key === 'Enter' && handleDelete()}
>
  <TrashIcon />
</button>
<p id="delete-warning" className="sr-only">
  This action cannot be undone
</p>

// ✅ Correct: Use useEffect for focus management
const inputRef = useRef<HTMLInputElement>(null);

useEffect(() => {
  if (isOpen) {
    inputRef.current?.focus();
  }
}, [isOpen]);

return <input ref={inputRef} />;

// ✅ Correct: Use centralized timing config
import { TIMING_CONFIG } from '@/config/timing';

const toast = useToast();
toast.show({ message: 'Saved', duration: TIMING_CONFIG.TOAST_DURATION });

// ❌ Wrong: Spreading observable array
const itemsCopy = [...store.items]; // Loses reactivity

// ✅ Correct: Use slice() or toJS()
const itemsCopy = store.items.slice();
const itemsCopy2 = [...toJS(store.items)];

/**
 * Button component with variants and sizes
 *
 * @example
 * ```tsx
 * <Button variant="default" size="lg">Click Me</Button>
 * <Button variant="destructive" size="sm">Delete</Button>
 * ```
 */
export const Button = forwardRef<HTMLButtonElement, ButtonProps>(...);

// ✅ Correct: User-friendly error with accessible announcement
try {
  await saveMedication(data);
  toast.success('Medication saved successfully');
} catch (error) {
  const message = error instanceof Error ? error.message : 'Failed to save medication';
  toast.error(message, { 'aria-live': 'assertive' });
}

import { forwardRef, type ComponentPropsWithoutRef } from "react";
import { Slot } from "@radix-ui/react-slot";
import { cva, type VariantProps } from "class-variance-authority";
import { observer } from "mobx-react-lite";
import { cn } from "@/lib/utils";

/**
 * [Component Name] - [Brief description]
 *
 * @example
 * ```tsx
 * <ComponentName variant="default" size="md">
 *   Content
 * </ComponentName>
 * ```
 */

const componentVariants = cva(
  "base-classes-here",
  {
    variants: {
      variant: {
        default: "default-variant-classes",
        secondary: "secondary-variant-classes"
      },
      size: {
        default: "h-9 px-4 py-2",
        sm: "h-8 px-3 text-sm",
        lg: "h-10 px-8"
      }
    },
    defaultVariants: {
      variant: "default",
      size: "default"
    }
  }
);

interface ComponentProps
  extends ComponentPropsWithoutRef<"div">,
    VariantProps<typeof componentVariants> {
  asChild?: boolean;
}

export const ComponentName = observer(
  forwardRef<HTMLDivElement, ComponentProps>(
    ({ className, variant, size, asChild = false, ...props }, ref) => {
      const Comp = asChild ? Slot : "div";
      return (
        <Comp
          className={cn(componentVariants({ variant, size, className }))}
          ref={ref}
          {...props}
        />
      );
    }
  )
);

ComponentName.displayName = "ComponentName";

// ❌ Wrong: Material UI (this codebase uses Radix UI)
import { Button } from "@mui/material";

export const MyButton = () => (
  <Button variant="contained" color="primary">
    Click Me
  </Button>
);

// ✅ Correct: Radix UI with Tailwind + CVA
import { Slot } from "@radix-ui/react-slot";
import { cva } from "class-variance-authority";
import { cn } from "@/lib/utils";

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md font-medium",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90"
      }
    }
  }
);

export const MyButton = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, asChild = false, ...props }, ref) => {
    const Comp = asChild ? Slot : "button";
    return (
      <Comp
        className={cn(buttonVariants({ variant, className }))}
        ref={ref}
        {...props}
      />
    );
  }
);

npm run dev              # Start development server
npm run dev:auth         # Development with real OAuth
npm run dev:integration  # Same as dev:auth
npm run build            # Production build
npm run test             # Unit tests (Vitest)
npm run test:e2e         # E2E tests (Playwright)
npm run lint             # ESLint
npm run docs:check       # Validate documentation