@djangocfg/ui-core 2.1.3 → 2.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -102,7 +102,7 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.3",
+    "@djangocfg/typescript-config": "^2.1.5",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/components/@old/calendar.tsx

@@ -0,0 +1,213 @@
+"use client"
+
+import * as React from "react"
+import {
+  ChevronDownIcon,
+  ChevronLeftIcon,
+  ChevronRightIcon,
+} from "lucide-react"
+import { DayButton, DayPicker, getDefaultClassNames } from "react-day-picker"
+
+import { cn } from "../../lib/utils"
+import { Button, buttonVariants } from "../../components/button"
+
+function Calendar({
+  className,
+  classNames,
+  showOutsideDays = true,
+  captionLayout = "label",
+  buttonVariant = "ghost",
+  formatters,
+  components,
+  ...props
+}: React.ComponentProps<typeof DayPicker> & {
+  buttonVariant?: React.ComponentProps<typeof Button>["variant"]
+}) {
+  const defaultClassNames = getDefaultClassNames()
+
+  return (
+    <DayPicker
+      showOutsideDays={showOutsideDays}
+      className={cn(
+        "bg-background group/calendar p-3 [--cell-size:2rem] [[data-slot=card-content]_&]:bg-transparent [[data-slot=popover-content]_&]:bg-transparent",
+        String.raw`rtl:**:[.rdp-button\_next>svg]:rotate-180`,
+        String.raw`rtl:**:[.rdp-button\_previous>svg]:rotate-180`,
+        className
+      )}
+      captionLayout={captionLayout}
+      formatters={{
+        formatMonthDropdown: (date) =>
+          date.toLocaleString("default", { month: "short" }),
+        ...formatters,
+      }}
+      classNames={{
+        root: cn("w-fit", defaultClassNames.root),
+        months: cn(
+          "relative flex flex-col gap-4 md:flex-row",
+          defaultClassNames.months
+        ),
+        month: cn("flex w-full min-w-[calc(var(--cell-size)*7)] flex-col gap-4", defaultClassNames.month),
+        nav: cn(
+          "absolute inset-x-0 top-0 flex w-full items-center justify-between gap-1",
+          defaultClassNames.nav
+        ),
+        button_previous: cn(
+          buttonVariants({ variant: buttonVariant }),
+          "h-[--cell-size] w-[--cell-size] select-none p-0 aria-disabled:opacity-50",
+          defaultClassNames.button_previous
+        ),
+        button_next: cn(
+          buttonVariants({ variant: buttonVariant }),
+          "h-[--cell-size] w-[--cell-size] select-none p-0 aria-disabled:opacity-50",
+          defaultClassNames.button_next
+        ),
+        month_caption: cn(
+          "flex h-[--cell-size] w-full items-center justify-center px-[--cell-size]",
+          defaultClassNames.month_caption
+        ),
+        dropdowns: cn(
+          "flex h-[--cell-size] w-full items-center justify-center gap-1.5 text-sm font-medium",
+          defaultClassNames.dropdowns
+        ),
+        dropdown_root: cn(
+          "has-focus:border-ring border-input shadow-xs has-focus:ring-ring/50 has-focus:ring-[3px] relative rounded-md border",
+          defaultClassNames.dropdown_root
+        ),
+        dropdown: cn(
+          "bg-popover absolute inset-0 opacity-0",
+          defaultClassNames.dropdown
+        ),
+        caption_label: cn(
+          "select-none font-medium",
+          captionLayout === "label"
+            ? "text-sm"
+            : "[&>svg]:text-muted-foreground flex h-8 items-center gap-1 rounded-md pl-2 pr-1 text-sm [&>svg]:size-3.5",
+          defaultClassNames.caption_label
+        ),
+        table: "w-full border-collapse",
+        weekdays: cn("flex", defaultClassNames.weekdays),
+        weekday: cn(
+          "text-muted-foreground flex-1 select-none rounded-md text-[0.8rem] font-normal",
+          defaultClassNames.weekday
+        ),
+        week: cn("mt-2 flex w-full", defaultClassNames.week),
+        week_number_header: cn(
+          "w-[--cell-size] select-none",
+          defaultClassNames.week_number_header
+        ),
+        week_number: cn(
+          "text-muted-foreground select-none text-[0.8rem]",
+          defaultClassNames.week_number
+        ),
+        day: cn(
+          "group/day relative aspect-square h-full w-full select-none p-0 text-center [&:first-child[data-selected=true]_button]:rounded-l-md [&:last-child[data-selected=true]_button]:rounded-r-md",
+          defaultClassNames.day
+        ),
+        range_start: cn(
+          "bg-accent rounded-l-md",
+          defaultClassNames.range_start
+        ),
+        range_middle: cn("rounded-none", defaultClassNames.range_middle),
+        range_end: cn("bg-accent rounded-r-md", defaultClassNames.range_end),
+        today: cn(
+          "bg-accent text-accent-foreground rounded-md data-[selected=true]:rounded-none",
+          defaultClassNames.today
+        ),
+        outside: cn(
+          "text-muted-foreground aria-selected:text-muted-foreground",
+          defaultClassNames.outside
+        ),
+        disabled: cn(
+          "text-muted-foreground opacity-50",
+          defaultClassNames.disabled
+        ),
+        hidden: cn("invisible", defaultClassNames.hidden),
+        ...classNames,
+      }}
+      components={{
+        Root: ({ className, rootRef, ...props }) => {
+          return (
+            <div
+              data-slot="calendar"
+              ref={rootRef}
+              className={cn(className)}
+              {...props}
+            />
+          )
+        },
+        Chevron: ({ className, orientation, ...props }) => {
+          if (orientation === "left") {
+            return (
+              <ChevronLeftIcon className={cn("size-4", className)} {...props} />
+            )
+          }
+
+          if (orientation === "right") {
+            return (
+              <ChevronRightIcon
+                className={cn("size-4", className)}
+                {...props}
+              />
+            )
+          }
+
+          return (
+            <ChevronDownIcon className={cn("size-4", className)} {...props} />
+          )
+        },
+        DayButton: CalendarDayButton,
+        WeekNumber: ({ children, ...props }) => {
+          return (
+            <td {...props}>
+              <div className="flex size-[--cell-size] items-center justify-center text-center">
+                {children}
+              </div>
+            </td>
+          )
+        },
+        ...components,
+      }}
+      {...props}
+    />
+  )
+}
+
+function CalendarDayButton({
+  className,
+  day,
+  modifiers,
+  ...props
+}: React.ComponentProps<typeof DayButton>) {
+  const defaultClassNames = getDefaultClassNames()
+
+  const ref = React.useRef<HTMLButtonElement>(null)
+  React.useEffect(() => {
+    if (modifiers.focused) ref.current?.focus()
+  }, [modifiers.focused])
+
+  return (
+    <Button
+      ref={ref}
+      variant="ghost"
+      size="icon"
+      data-day={day.date.toLocaleDateString()}
+      data-selected-single={
+        modifiers.selected &&
+        !modifiers.range_start &&
+        !modifiers.range_end &&
+        !modifiers.range_middle
+      }
+      data-range-start={modifiers.range_start}
+      data-range-end={modifiers.range_end}
+      data-range-middle={modifiers.range_middle}
+      className={cn(
+        "data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground data-[range-middle=true]:bg-accent data-[range-middle=true]:text-accent-foreground data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-ring/50 flex aspect-square h-auto w-full min-w-[--cell-size] flex-col gap-1 font-normal leading-none data-[range-end=true]:rounded-md data-[range-middle=true]:rounded-none data-[range-start=true]:rounded-md group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:ring-[3px] [&>span]:text-xs [&>span]:opacity-70",
+        defaultClassNames.day,
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Calendar, CalendarDayButton }

package/src/components/@old/date-picker.tsx

@@ -0,0 +1,191 @@
+'use client'
+
+import * as React from 'react'
+import { format } from 'date-fns'
+import { CalendarIcon } from 'lucide-react'
+import type { SelectSingleEventHandler } from 'react-day-picker'
+
+import { cn } from '../../lib/utils'
+import { Button } from '../../components/button'
+import { Calendar } from './calendar'
+import { Popover, PopoverContent, PopoverTrigger } from '../../components/popover'
+
+// =============================================================================
+// DatePicker - Single date selection with popover
+// =============================================================================
+
+export interface DatePickerProps {
+  /** Selected date */
+  value?: Date
+  /** Callback when date changes */
+  onChange?: (date: Date | undefined) => void
+  /** Placeholder text when no date selected */
+  placeholder?: string
+  /** Date format string (date-fns format) */
+  dateFormat?: string
+  /** Disable the picker */
+  disabled?: boolean
+  /** Minimum selectable date */
+  fromDate?: Date
+  /** Maximum selectable date */
+  toDate?: Date
+  /** Additional class names for the trigger button */
+  className?: string
+  /** Button variant */
+  variant?: 'default' | 'outline' | 'ghost'
+  /** Align popover */
+  align?: 'start' | 'center' | 'end'
+}
+
+const DatePicker = React.forwardRef<HTMLButtonElement, DatePickerProps>(
+  (
+    {
+      value,
+      onChange,
+      placeholder = 'Pick a date',
+      dateFormat = 'PPP',
+      disabled = false,
+      fromDate,
+      toDate,
+      className,
+      variant = 'outline',
+      align = 'start',
+    },
+    ref
+  ) => {
+    const [open, setOpen] = React.useState(false)
+
+    const handleSelect: SelectSingleEventHandler = (date) => {
+      onChange?.(date)
+      setOpen(false)
+    }
+
+    return (
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <Button
+            ref={ref}
+            variant={variant}
+            disabled={disabled}
+            className={cn(
+              'w-full justify-start text-left font-normal',
+              !value && 'text-muted-foreground',
+              className
+            )}
+          >
+            <CalendarIcon className="mr-2 h-4 w-4" />
+            {value ? format(value, dateFormat) : placeholder}
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent className="w-auto p-0" align={align}>
+          <Calendar
+            mode="single"
+            selected={value}
+            onSelect={handleSelect}
+            disabled={disabled}
+            fromDate={fromDate}
+            toDate={toDate}
+            initialFocus
+          />
+        </PopoverContent>
+      </Popover>
+    )
+  }
+)
+DatePicker.displayName = 'DatePicker'
+
+// =============================================================================
+// DateRangePicker - Date range selection with popover
+// =============================================================================
+
+export interface DateRange {
+  from?: Date
+  to?: Date
+}
+
+export interface DateRangePickerProps {
+  /** Selected date range */
+  value?: DateRange
+  /** Callback when range changes */
+  onChange?: (range: DateRange | undefined) => void
+  /** Placeholder text when no range selected */
+  placeholder?: string
+  /** Date format string (date-fns format) */
+  dateFormat?: string
+  /** Disable the picker */
+  disabled?: boolean
+  /** Minimum selectable date */
+  fromDate?: Date
+  /** Maximum selectable date */
+  toDate?: Date
+  /** Number of months to display */
+  numberOfMonths?: number
+  /** Additional class names for the trigger button */
+  className?: string
+  /** Button variant */
+  variant?: 'default' | 'outline' | 'ghost'
+  /** Align popover */
+  align?: 'start' | 'center' | 'end'
+}
+
+const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePickerProps>(
+  (
+    {
+      value,
+      onChange,
+      placeholder = 'Pick a date range',
+      dateFormat = 'LLL dd, y',
+      disabled = false,
+      fromDate,
+      toDate,
+      numberOfMonths = 2,
+      className,
+      variant = 'outline',
+      align = 'start',
+    },
+    ref
+  ) => {
+    const [open, setOpen] = React.useState(false)
+
+    const formatRange = () => {
+      if (!value?.from) return placeholder
+      if (!value.to) return format(value.from, dateFormat)
+      return `${format(value.from, dateFormat)} - ${format(value.to, dateFormat)}`
+    }
+
+    return (
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <Button
+            ref={ref}
+            variant={variant}
+            disabled={disabled}
+            className={cn(
+              'w-full justify-start text-left font-normal',
+              !value?.from && 'text-muted-foreground',
+              className
+            )}
+          >
+            <CalendarIcon className="mr-2 h-4 w-4" />
+            {formatRange()}
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent className="w-auto p-0" align={align}>
+          <Calendar
+            mode="range"
+            selected={value?.from ? { from: value.from, to: value.to } : undefined}
+            onSelect={onChange}
+            disabled={disabled}
+            fromDate={fromDate}
+            toDate={toDate}
+            numberOfMonths={numberOfMonths}
+            initialFocus
+          />
+        </PopoverContent>
+      </Popover>
+    )
+  }
+)
+DateRangePicker.displayName = 'DateRangePicker'
+
+export { DatePicker, DateRangePicker }

package/src/components/{calendar.tsx → calendar/calendar.tsx}

@@ -8,8 +8,8 @@ import {
 } from "lucide-react"
 import { DayButton, DayPicker, getDefaultClassNames } from "react-day-picker"
 
-import { cn } from "../lib/utils"
-import { Button, buttonVariants } from "./button"
+import { cn } from "../../lib/utils"
+import { Button, buttonVariants } from "../button"
 
 function Calendar({
   className,
@@ -41,12 +41,12 @@ function Calendar({
         ...formatters,
       }}
       classNames={{
-        root: cn("w-full", defaultClassNames.root),
+        root: cn("w-fit", defaultClassNames.root),
         months: cn(
           "relative flex flex-col gap-4 md:flex-row",
           defaultClassNames.months
         ),
-        month: cn("flex w-full flex-col gap-4", defaultClassNames.month),
+        month: cn("flex w-full min-w-[calc(var(--cell-size)*7)] flex-col gap-4", defaultClassNames.month),
         nav: cn(
           "absolute inset-x-0 top-0 flex w-full items-center justify-between gap-1",
           defaultClassNames.nav

package/src/components/calendar/date-picker.tsx

@@ -0,0 +1,189 @@
+'use client'
+
+import * as React from 'react'
+import { format } from 'date-fns'
+import { CalendarIcon } from 'lucide-react'
+import type { SelectSingleEventHandler, DateRange as RDPDateRange } from 'react-day-picker'
+
+import { cn } from '../../lib/utils'
+import { Button } from '../button'
+import { Calendar } from './calendar'
+import { Popover, PopoverContent, PopoverTrigger } from '../popover'
+
+// =============================================================================
+// DatePicker - Single date selection with popover
+// =============================================================================
+
+export interface DatePickerProps {
+  /** Selected date */
+  value?: Date
+  /** Callback when date changes */
+  onChange?: (date: Date | undefined) => void
+  /** Placeholder text when no date selected */
+  placeholder?: string
+  /** Date format string (date-fns format) */
+  dateFormat?: string
+  /** Disable the picker */
+  disabled?: boolean
+  /** Minimum selectable date */
+  fromDate?: Date
+  /** Maximum selectable date */
+  toDate?: Date
+  /** Additional class names for the trigger button */
+  className?: string
+  /** Button variant */
+  variant?: 'default' | 'outline' | 'ghost'
+  /** Align popover */
+  align?: 'start' | 'center' | 'end'
+}
+
+const DatePicker = React.forwardRef<HTMLButtonElement, DatePickerProps>(
+  (
+    {
+      value,
+      onChange,
+      placeholder = 'Pick a date',
+      dateFormat = 'PPP',
+      disabled = false,
+      fromDate,
+      toDate,
+      className,
+      variant = 'outline',
+      align = 'start',
+    },
+    ref
+  ) => {
+    const [open, setOpen] = React.useState(false)
+
+    const handleSelect: SelectSingleEventHandler = (date) => {
+      onChange?.(date)
+      setOpen(false)
+    }
+
+    return (
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <Button
+            ref={ref}
+            variant={variant}
+            disabled={disabled}
+            className={cn(
+              'w-full justify-start text-left font-normal',
+              !value && 'text-muted-foreground',
+              className
+            )}
+          >
+            <CalendarIcon className="mr-2 h-4 w-4" />
+            {value ? format(value, dateFormat) : placeholder}
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent className="w-auto p-0" align={align}>
+          <Calendar
+            mode="single"
+            selected={value}
+            onSelect={handleSelect}
+            disabled={disabled}
+            fromDate={fromDate}
+            toDate={toDate}
+            initialFocus
+          />
+        </PopoverContent>
+      </Popover>
+    )
+  }
+)
+DatePicker.displayName = 'DatePicker'
+
+// =============================================================================
+// DateRangePicker - Date range selection with popover
+// =============================================================================
+
+/** Date range type - re-exported from react-day-picker for convenience */
+export type DateRange = RDPDateRange
+
+export interface DateRangePickerProps {
+  /** Selected date range */
+  value?: DateRange
+  /** Callback when range changes */
+  onChange?: (range: DateRange | undefined) => void
+  /** Placeholder text when no range selected */
+  placeholder?: string
+  /** Date format string (date-fns format) */
+  dateFormat?: string
+  /** Disable the picker */
+  disabled?: boolean
+  /** Minimum selectable date */
+  fromDate?: Date
+  /** Maximum selectable date */
+  toDate?: Date
+  /** Number of months to display */
+  numberOfMonths?: number
+  /** Additional class names for the trigger button */
+  className?: string
+  /** Button variant */
+  variant?: 'default' | 'outline' | 'ghost'
+  /** Align popover */
+  align?: 'start' | 'center' | 'end'
+}
+
+const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePickerProps>(
+  (
+    {
+      value,
+      onChange,
+      placeholder = 'Pick a date range',
+      dateFormat = 'LLL dd, y',
+      disabled = false,
+      fromDate,
+      toDate,
+      numberOfMonths = 2,
+      className,
+      variant = 'outline',
+      align = 'start',
+    },
+    ref
+  ) => {
+    const [open, setOpen] = React.useState(false)
+
+    const formatRange = () => {
+      if (!value?.from) return placeholder
+      if (!value.to) return format(value.from, dateFormat)
+      return `${format(value.from, dateFormat)} - ${format(value.to, dateFormat)}`
+    }
+
+    return (
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <Button
+            ref={ref}
+            variant={variant}
+            disabled={disabled}
+            className={cn(
+              'w-full justify-start text-left font-normal',
+              !value?.from && 'text-muted-foreground',
+              className
+            )}
+          >
+            <CalendarIcon className="mr-2 h-4 w-4" />
+            {formatRange()}
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent className="w-auto p-0" align={align}>
+          <Calendar
+            mode="range"
+            selected={value}
+            onSelect={onChange}
+            disabled={disabled}
+            fromDate={fromDate}
+            toDate={toDate}
+            numberOfMonths={numberOfMonths}
+            initialFocus
+          />
+        </PopoverContent>
+      </Popover>
+    )
+  }
+)
+DateRangePicker.displayName = 'DateRangePicker'
+
+export { DatePicker, DateRangePicker }

package/src/components/calendar/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Calendar Components
+ *
+ * @module calendar
+ */
+
+export { Calendar, CalendarDayButton } from './calendar'
+export { DatePicker, DateRangePicker } from './date-picker'
+export type { DatePickerProps, DateRangePickerProps, DateRange } from './date-picker'

package/src/components/index.ts

@@ -49,7 +49,9 @@ export { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from './
 export { Collapsible, CollapsibleContent, CollapsibleTrigger } from './collapsible';
 export { Progress } from './progress';
 export { Avatar, AvatarFallback, AvatarImage } from './avatar';
-export { Calendar } from './calendar';
+export { Calendar, CalendarDayButton } from './calendar';
+export { DatePicker, DateRangePicker } from './calendar';
+export type { DatePickerProps, DateRangePickerProps, DateRange } from './calendar';
 export { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from './carousel';
 export { TokenIcon, getAllTokenSymbols, searchTokens, getTokensByCategory } from './token-icon';
 export type { TokenIconProps, TokenSymbol, TokenCategory } from './token-icon';
@@ -76,6 +78,7 @@ export { Spinner } from './spinner';
 export { Preloader, PreloaderSkeleton } from './preloader';
 export type { PreloaderProps, PreloaderSkeletonProps } from './preloader';
 export { Kbd, KbdGroup } from './kbd';
+export type { KbdProps, KbdSize } from './kbd';
 export { InputGroup, InputGroupAddon, InputGroupButton, InputGroupText, InputGroupInput, InputGroupTextarea } from './input-group';
 export { Item, ItemMedia, ItemContent, ItemActions, ItemGroup, ItemSeparator, ItemTitle, ItemDescription, ItemHeader, ItemFooter } from './item';
 export { Field, FieldLabel, FieldDescription, FieldError, FieldGroup, FieldLegend, FieldSeparator, FieldSet, FieldContent, FieldTitle } from './field';

package/src/components/kbd.tsx

@@ -1,13 +1,26 @@
 import { cn } from "../lib/utils"
 
-function Kbd({ className, ...props }: React.ComponentProps<"kbd">) {
+type KbdSize = "xs" | "sm" | "default" | "lg";
+
+interface KbdProps extends React.ComponentProps<"kbd"> {
+  size?: KbdSize;
+}
+
+const kbdSizeStyles: Record<KbdSize, string> = {
+  xs: "h-4 min-w-4 px-0.5 text-[10px] [&_svg:not([class*='size-'])]:size-2.5",
+  sm: "h-5 min-w-5 px-1 text-xs [&_svg:not([class*='size-'])]:size-3",
+  default: "h-6 min-w-6 px-1.5 text-xs [&_svg:not([class*='size-'])]:size-3.5",
+  lg: "h-7 min-w-7 px-2 text-sm [&_svg:not([class*='size-'])]:size-4",
+};
+
+function Kbd({ className, size = "default", ...props }: KbdProps) {
   return (
     <kbd
       data-slot="kbd"
       className={cn(
-        "bg-muted text-muted-foreground pointer-events-none inline-flex h-5 w-fit min-w-5 select-none items-center justify-center gap-1 rounded-sm px-1 font-sans text-xs font-medium",
-        "[&_svg:not([class*='size-'])]:size-3",
+        "bg-muted text-muted-foreground pointer-events-none inline-flex w-fit select-none items-center justify-center gap-1 rounded-sm font-mono font-medium border border-border/50",
         "[[data-slot=tooltip-content]_&]:bg-background/20 [[data-slot=tooltip-content]_&]:text-background dark:[[data-slot=tooltip-content]_&]:bg-background/10",
+        kbdSizeStyles[size],
         className
       )}
       {...props}
@@ -26,3 +39,4 @@ function KbdGroup({ className, ...props }: React.ComponentProps<"div">) {
 }
 
 export { Kbd, KbdGroup }
+export type { KbdProps, KbdSize }

package/src/components/toast.tsx

@@ -16,7 +16,7 @@ const ToastViewport = React.forwardRef<
   <ToastPrimitives.Viewport
     ref={ref}
     className={cn(
-      "fixed top-0 z-9999 flex max-h-screen w-full flex-col-reverse p-4 sm:bottom-0 sm:right-0 sm:top-auto sm:flex-col md:max-w-md",
+      "fixed bottom-0 right-0 z-9999 flex max-h-screen w-full flex-col p-4 md:max-w-md",
       className
     )}
     {...props}
@@ -25,7 +25,7 @@ const ToastViewport = React.forwardRef<
 ToastViewport.displayName = ToastPrimitives.Viewport.displayName
 
 const toastVariants = cva(
-  "group pointer-events-auto relative flex w-full items-center justify-between space-x-4 overflow-hidden rounded-md border p-6 pr-8 shadow-lg transition-all data-[swipe=cancel]:translate-x-0 data-[swipe=end]:translate-x-[var(--radix-toast-swipe-end-x)] data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)] data-[swipe=move]:transition-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[swipe=end]:animate-out data-[state=closed]:fade-out-80 data-[state=closed]:slide-out-to-right-full data-[state=open]:slide-in-from-top-full data-[state=open]:sm:slide-in-from-bottom-full",
+  "group pointer-events-auto relative flex w-full items-center justify-between space-x-4 overflow-hidden rounded-md border p-6 pr-8 shadow-lg transition-all data-[swipe=cancel]:translate-x-0 data-[swipe=end]:translate-x-[var(--radix-toast-swipe-end-x)] data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)] data-[swipe=move]:transition-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[swipe=end]:animate-out data-[state=closed]:fade-out-80 data-[state=closed]:slide-out-to-right-full data-[state=open]:slide-in-from-bottom-full",
   {
     variants: {
       variant: {

package/src/hooks/useToast.ts

@@ -9,13 +9,15 @@ import type {
 } from "../components/toast"
 
 const TOAST_LIMIT = 1
-const TOAST_REMOVE_DELAY = 1000000
+const TOAST_DEFAULT_DURATION = 5000 // 5 seconds default auto-dismiss
+const TOAST_DISMISS_DELAY = 300 // Animation delay before removing from DOM
 
 type ToasterToast = ToastProps & {
   id: string
   title?: React.ReactNode
   description?: React.ReactNode
   action?: ToastActionElement
+  duration?: number // Auto-dismiss duration in ms
 }
 
 const actionTypes = {
@@ -57,8 +59,10 @@ interface State {
 }
 
 const toastTimeouts = new Map<string, ReturnType<typeof setTimeout>>()
+const autoDismissTimeouts = new Map<string, ReturnType<typeof setTimeout>>()
 
-const addToRemoveQueue = (toastId: string) => {
+// Queue toast for removal after animation
+const addToRemoveQueue = (toastId: string, delay: number = TOAST_DISMISS_DELAY) => {
   if (toastTimeouts.has(toastId)) {
     return
   }
@@ -69,11 +73,36 @@ const addToRemoveQueue = (toastId: string) => {
       type: "REMOVE_TOAST",
       toastId: toastId,
     })
-  }, TOAST_REMOVE_DELAY)
+  }, delay)
 
   toastTimeouts.set(toastId, timeout)
 }
 
+// Schedule auto-dismiss after duration
+const scheduleAutoDismiss = (toastId: string, duration: number) => {
+  // Clear existing auto-dismiss if any
+  const existing = autoDismissTimeouts.get(toastId)
+  if (existing) {
+    clearTimeout(existing)
+  }
+
+  const timeout = setTimeout(() => {
+    autoDismissTimeouts.delete(toastId)
+    dispatch({ type: "DISMISS_TOAST", toastId })
+  }, duration)
+
+  autoDismissTimeouts.set(toastId, timeout)
+}
+
+// Clear auto-dismiss timeout (e.g., on manual dismiss)
+const clearAutoDismiss = (toastId: string) => {
+  const timeout = autoDismissTimeouts.get(toastId)
+  if (timeout) {
+    clearTimeout(timeout)
+    autoDismissTimeouts.delete(toastId)
+  }
+}
+
 export const reducer = (state: State, action: Action): State => {
   switch (action.type) {
     case "ADD_TOAST":
@@ -93,12 +122,13 @@ export const reducer = (state: State, action: Action): State => {
     case "DISMISS_TOAST": {
       const { toastId } = action
 
-      // ! Side effects ! - This could be extracted into a dismissToast() action,
-      // but I'll keep it here for simplicity
+      // Clear auto-dismiss timer and queue for removal
       if (toastId) {
+        clearAutoDismiss(toastId)
         addToRemoveQueue(toastId)
       } else {
         state.toasts.forEach((toast) => {
+          clearAutoDismiss(toast.id)
           addToRemoveQueue(toast.id)
         })
       }
@@ -142,7 +172,7 @@ function dispatch(action: Action) {
 
 type Toast = Omit<ToasterToast, "id">
 
-function toast({ ...props }: Toast) {
+function toast({ duration = TOAST_DEFAULT_DURATION, ...props }: Toast) {
   const id = genId()
 
   const update = (props: ToasterToast) =>
@@ -164,6 +194,11 @@ function toast({ ...props }: Toast) {
     },
   })
 
+  // Schedule auto-dismiss after duration (0 means no auto-dismiss)
+  if (duration > 0) {
+    scheduleAutoDismiss(id, duration)
+  }
+
   return {
     id: id,
     dismiss,

package/src/styles/README.md

@@ -0,0 +1,229 @@
+# Tailwind CSS v4 Styles Guide
+
+This directory contains the CSS architecture for `@djangocfg/ui-core` using **Tailwind CSS v4**.
+
+## Directory Structure
+
+```
+styles/
+├── index.css        # Main entry point (import order is critical!)
+├── theme.css        # Theme imports
+├── base.css         # Base element styles
+├── utilities.css    # Custom utility classes
+├── sources.css      # Source detection for Tailwind v4 monorepo
+└── theme/
+    ├── tokens.css   # @theme block with CSS custom properties
+    ├── light.css    # Light theme variables
+    ├── dark.css     # Dark theme variables
+    └── animations.css # Animation keyframes
+```
+
+## Key Changes in Tailwind v4
+
+1. **CSS-First Configuration**: Theme is now defined using CSS custom properties in an `@theme` block instead of JavaScript
+2. **New Import Syntax**: Use `@import "tailwindcss"` instead of `@tailwind` directives
+3. **Simplified PostCSS Setup**: Use `@tailwindcss/postcss` plugin
+4. **Performance Improvements**: 10x faster build times, significantly smaller CSS bundles
+5. **Modern Browser Support**: Optimized for Safari 16.4+, Chrome 111+, Firefox 128+
+6. **Source Detection Required**: Tailwind v4 requires explicit `@source` directives to scan files in monorepo packages
+
+## App Setup (globals.css) - CRITICAL!
+
+When creating a new app that uses UI packages, your `globals.css` MUST follow this pattern:
+
+```css
+/**
+ * CRITICAL: Import order matters for Tailwind CSS v4!
+ * 1. Theme variables MUST come BEFORE @import "tailwindcss"
+ * 2. @source directives MUST be added for each package with Tailwind classes
+ */
+
+/* 1. Import UI package styles FIRST (contains @theme variables) */
+@import "@djangocfg/ui-nextjs/styles";
+
+/* 2. Import other package styles (layouts, etc.) */
+@import "@djangocfg/layouts/styles";
+
+/* 3. Import Tailwind CSS v4 (AFTER theme variables!) */
+@import "tailwindcss";
+
+/* 4. Load plugins */
+@plugin "tailwindcss-animate";
+
+/* 5. Source detection for packages NOT included in ui-nextjs/styles */
+/* This tells Tailwind where to scan for utility classes */
+@source "../../../packages/your-package/src/**/*.{ts,tsx}";
+```
+
+### Why @source is Required
+
+In Tailwind v4 monorepo, automatic class detection doesn't work across packages. Each package with Tailwind classes needs:
+
+1. **Either** a `@source` directive in the consuming app's `globals.css`
+2. **Or** a `sources.css` file in the package that's imported via the styles entry point
+
+**Example**: If you have `playground-ui` package with components using `pb-20`, `grid-cols-5`, etc., and these classes don't work:
+
+```css
+/* Add this to your app's globals.css */
+@source "../../../packages/playground-ui/src/**/*.{ts,tsx}";
+```
+
+### Common Symptoms of Missing @source
+
+- Tailwind classes don't apply (but inline styles work)
+- Grid classes like `grid-cols-3`, `grid-cols-5` don't work
+- Spacing classes like `pb-20`, `mt-10` have no effect
+- Classes work in some packages but not others
+
+## Import Order (Critical!)
+
+```css
+/* 1. Theme variables MUST come first */
+@import "./theme.css";
+
+/* 2. Source detection for Tailwind v4 monorepo */
+@import "./sources.css";
+
+/* 3. Base styles */
+@import "./base.css";
+
+/* 4. Custom utilities */
+@import "./utilities.css";
+```
+
+## Best Practices
+
+### Spacing & Sizing
+
+- Use standard Tailwind classes: `py-16 sm:py-20 md:py-24 lg:py-32`
+- Responsive patterns: `px-4 sm:px-6 lg:px-8`
+- Container pattern: `container max-w-7xl mx-auto`
+
+### Arbitrary Values
+
+**IMPORTANT**: Arbitrary values like `h-[80px]`, `z-[100]` may NOT work in v4!
+
+```tsx
+// ❌ May not work in Tailwind v4
+<div className="h-[80px] z-[100]">
+
+// ✅ Define tokens in @theme instead
+@theme {
+  --spacing-80: 20rem;
+  --z-index-100: 100;
+}
+
+// ✅ Or use inline styles (always reliable)
+<div style={{ height: '80px', zIndex: 100 }}>
+```
+
+### Opacity with HSL Colors
+
+**CRITICAL**: `bg-background/80` does NOT work with HSL colors in v4!
+
+```tsx
+// ❌ BROKEN - does not work in Tailwind v4
+<nav className="bg-background/80 border-border/30">
+
+// ✅ WORKING - use inline styles for opacity
+<nav
+  className="sticky top-0 z-100 backdrop-blur-xl"
+  style={{
+    backgroundColor: 'hsl(var(--background) / 0.8)',
+    borderColor: 'hsl(var(--border) / 0.3)'
+  }}
+>
+```
+
+### Fixed Sizes
+
+```tsx
+// ✅ Inline styles for fixed sizes (always reliable)
+<Avatar
+  className="aspect-square rounded-full overflow-hidden"
+  style={{ width: '80px', height: '80px' }}
+>
+  <AvatarImage src={avatar} alt="User" />
+</Avatar>
+```
+
+### Spacing Requirements
+
+Spacing utilities (`h-20`, `p-4`, etc.) require `--spacing-*` variables defined in `@theme` block:
+
+```css
+@theme {
+  --spacing: 0.25rem; /* Base unit: 4px */
+  --spacing-0: 0;
+  --spacing-1: 0.25rem;   /* 4px */
+  --spacing-2: 0.5rem;    /* 8px */
+  --spacing-4: 1rem;      /* 16px */
+  --spacing-8: 2rem;      /* 32px */
+  --spacing-13: 3.25rem;  /* 52px - for min-h-13 */
+  /* ... */
+}
+```
+
+### Z-Index Requirements
+
+Z-index utilities (`z-50`, `z-100`) require `--z-index-*` variables:
+
+```css
+@theme {
+  --z-index-50: 50;
+  --z-index-100: 100;
+  --z-index-9999: 9999;
+}
+```
+
+## Common Patterns
+
+### Responsive Design (Mobile-First)
+
+```tsx
+<div className="px-4 sm:px-6 lg:px-8">
+  <div className="py-16 sm:py-20 md:py-24 lg:py-32">
+    Content
+  </div>
+</div>
+```
+
+### Breakpoints
+
+- `sm:` - 640px (40rem)
+- `md:` - 768px (48rem)
+- `lg:` - 1024px (64rem)
+- `xl:` - 1280px (80rem)
+- `2xl:` - 1536px (96rem)
+
+### Circles
+
+```tsx
+// ✅ Perfect circle
+<div className="aspect-square rounded-full overflow-hidden w-10 h-10">
+```
+
+## What to Avoid
+
+- Custom utilities like: `section-padding`, `animate-*`, `shadow-brand`
+- Arbitrary values without checking if they work: `h-[53px]`, `min-h-[100px]`
+- Opacity modifiers with HSL colors: `bg-background/80`
+- Assuming spacing values exist without defining them in `@theme`
+
+## CSS Variables
+
+Use CSS variables for dynamic values:
+
+```tsx
+<div style={{ color: 'var(--color-primary)' }}>
+```
+
+Or in CSS:
+
+```css
+.my-class {
+  background-color: hsl(var(--background));
+  color: hsl(var(--foreground));
+}
+```

package/src/styles/theme/tokens.css

@@ -67,6 +67,7 @@
   --spacing-10: 2.5rem;   /* 40px */
   --spacing-11: 2.75rem;  /* 44px */
   --spacing-12: 3rem;     /* 48px */
+  --spacing-13: 3.25rem;  /* 52px */
   --spacing-14: 3.5rem;   /* 56px */
   --spacing-16: 4rem;     /* 64px */
   --spacing-20: 5rem;     /* 80px */