@djangocfg/ui-core 2.1.227 → 2.1.228

package/README.md

@@ -45,12 +45,14 @@ pnpm add @djangocfg/ui-core
 ### Specialized (13)
 `ButtonGroup` `Empty` `Spinner` `Preloader` `Kbd` `TokenIcon` `InputGroup` `Item` `ImageWithFallback` `OgImage` `CopyButton` `CopyField` `StaticPagination`
 
-## Hooks (13)
+## Hooks (16)
 
 | Hook | Description |
 |------|-------------|
-| `useMediaQuery` | Responsive breakpoints |
-| `useIsMobile` | Mobile detection |
+| `useMediaQuery(query)` | Raw media query — pass any CSS query string. Exports `BREAKPOINTS` constants (Tailwind v4 defaults) |
+| `useIsPhone()` | `< 640px` — phones only |
+| `useIsMobile()` | `< 768px` — phones + small tablets |
+| `useIsTabletOrBelow()` | `< 1024px` — phones + tablets |
 | `useCopy` | Copy to clipboard |
 | `useCountdown` | Countdown timer |
 | `useDebounce` | Debounce values |
@@ -62,6 +64,19 @@ pnpm add @djangocfg/ui-core
 | `useHotkey` | Keyboard shortcuts (react-hotkeys-hook) |
 | `useBrowserDetect` | Browser detection (Chrome, Safari, in-app browsers, etc.) |
 | `useDeviceDetect` | Device detection (mobile, tablet, desktop, OS, etc.) |
+| `useResolvedTheme` | Current resolved theme (light/dark/system) |
+
+```tsx
+import { useMediaQuery, useIsPhone, useIsMobile, BREAKPOINTS } from '@djangocfg/ui-core/hooks'
+
+// semantic
+const isPhone  = useIsPhone()   // < 640px
+const isMobile = useIsMobile()  // < 768px
+
+// custom with constants
+const isNarrow = useMediaQuery(`(max-width: ${BREAKPOINTS.sm - 1}px)`)
+const isDark   = useMediaQuery('(prefers-color-scheme: dark)')
+```
 
 ## Theme Palette Hooks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.227",
+  "version": "2.1.228",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -81,12 +81,12 @@
     "playground": "playground dev"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.227",
-    "react-device-detect": "^2.2.3",
+    "@djangocfg/i18n": "^2.1.228",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
     "react": "^19.1.0",
+    "react-device-detect": "^2.2.3",
     "react-dom": "^19.1.0",
     "react-hook-form": "^7.69.0",
     "tailwindcss": "^4.1.18",
@@ -134,18 +134,18 @@
     "input-otp": "1.4.2",
     "libphonenumber-js": "^1.12.24",
     "react-day-picker": "9.11.1",
+    "react-hotkeys-hook": "^4.6.1",
     "react-resizable-panels": "3.0.6",
     "react-sticky-box": "^2.0.5",
     "recharts": "2.15.4",
     "sonner": "2.0.7",
-    "react-hotkeys-hook": "^4.6.1",
     "tailwind-merge": "^3.3.1",
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.227",
+    "@djangocfg/i18n": "^2.1.228",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.227",
+    "@djangocfg/typescript-config": "^2.1.228",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

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

@@ -4,7 +4,7 @@ import { format } from 'date-fns';
 import { CalendarIcon } from 'lucide-react';
 import * as React from 'react';
 
-import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useAppT } from '@djangocfg/i18n';
 import { cn } from '../../lib/utils';
 import { Button } from '../button';
 import { Popover, PopoverContent, PopoverTrigger } from '../popover';
@@ -55,7 +55,7 @@ const DatePicker = React.forwardRef<HTMLButtonElement, DatePickerProps>(
     },
     ref
   ) => {
-    const t = useTypedT<I18nTranslations>()
+    const t = useAppT()
     const [open, setOpen] = React.useState(false)
 
     const resolvedPlaceholder = placeholder ?? t('ui.datetime.pickDate')
@@ -148,7 +148,7 @@ const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePickerProps
     },
     ref
   ) => {
-    const t = useTypedT<I18nTranslations>()
+    const t = useAppT()
     const [open, setOpen] = React.useState(false)
 
     const resolvedPlaceholder = placeholder ?? t('ui.datetime.pickDateRange')

package/src/components/carousel.tsx

@@ -5,7 +5,7 @@ import * as React from 'react';
 
 import { ArrowLeftIcon, ArrowRightIcon } from '@radix-ui/react-icons';
 
-import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useAppT } from '@djangocfg/i18n';
 import { cn } from '../lib/utils';
 import { Button } from './button';
 
@@ -198,7 +198,7 @@ const CarouselPrevious = React.forwardRef<
   HTMLButtonElement,
   React.ComponentProps<typeof Button>
 >(({ className, variant = "outline", size = "icon", ...props }, ref) => {
-  const t = useTypedT<I18nTranslations>()
+  const t = useAppT()
   const { orientation, scrollPrev, canScrollPrev } = useCarousel()
   const previousLabel = t('ui.actions.previousSlide')
 
@@ -229,7 +229,7 @@ const CarouselNext = React.forwardRef<
   HTMLButtonElement,
   React.ComponentProps<typeof Button>
 >(({ className, variant = "outline", size = "icon", ...props }, ref) => {
-  const t = useTypedT<I18nTranslations>()
+  const t = useAppT()
   const { orientation, scrollNext, canScrollNext } = useCarousel()
   const nextLabel = t('ui.actions.nextSlide')
 

package/src/components/checkbox.tsx

@@ -14,7 +14,11 @@ const Checkbox = React.forwardRef<
   <CheckboxPrimitive.Root
     ref={ref}
     className={cn(
-      "peer h-4 w-4 shrink-0 rounded-sm border border-primary shadow focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
+      "peer h-[1.125rem] w-[1.125rem] shrink-0 rounded-[4px] border border-input bg-background shadow-none",
+      "transition-colors duration-150",
+      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
+      "disabled:cursor-not-allowed disabled:opacity-40",
+      "data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
       className
     )}
     {...props}
@@ -22,7 +26,7 @@ const Checkbox = React.forwardRef<
     <CheckboxPrimitive.Indicator
       className={cn("flex items-center justify-center text-current")}
     >
-      <CheckIcon className="h-4 w-4" />
+      <CheckIcon className="h-3 w-3" />
     </CheckboxPrimitive.Indicator>
   </CheckboxPrimitive.Root>
 ))

package/src/components/combobox.tsx

@@ -3,7 +3,7 @@
 import { Check, ChevronsUpDown } from 'lucide-react';
 import * as React from 'react';
 
-import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useAppT } from '@djangocfg/i18n';
 import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../hooks/useStoredValue';
 import { cn } from '../lib/utils';
 import { Button } from './button';
@@ -78,7 +78,7 @@ export function Combobox({
   storageTtl,
   autoSelectFromOptions = false,
 }: ComboboxProps) {
-  const t = useTypedT<I18nTranslations>()
+  const t = useAppT()
   const [open, setOpen] = React.useState(false)
   const [search, setSearch] = React.useState("")
   const scrollRef = React.useRef<HTMLDivElement>(null)

package/src/components/copy.tsx

@@ -3,7 +3,7 @@
 import { Check, Copy } from 'lucide-react';
 import * as React from 'react';
 
-import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useAppT } from '@djangocfg/i18n';
 import { cn } from '../lib/utils';
 import { Button } from './button';
 
@@ -40,7 +40,7 @@ const CopyButton = React.forwardRef<HTMLButtonElement, CopyButtonProps>(
     iconClassName = 'h-4 w-4',
     ...props
   }, ref) => {
-    const t = useTypedT<I18nTranslations>()
+    const t = useAppT()
     const [copied, setCopied] = React.useState(false)
 
     const handleCopy = async () => {

package/src/components/effects/GlowBackground.tsx

@@ -0,0 +1,78 @@
+'use client';
+
+import * as React from 'react';
+
+export interface GlowBackgroundProps {
+  className?: string;
+}
+
+/**
+ * GlowBackground — animated mesh gradient backdrop.
+ *
+ * Renders as `position: absolute inset-0` — must be placed inside
+ * a `position: relative` container. Content goes on top with `position: relative`.
+ *
+ * @example
+ * ```tsx
+ * <div style={{ position: 'relative', minHeight: '100vh' }}>
+ *   <GlowBackground />
+ *   <div style={{ position: 'relative' }}>{content}</div>
+ * </div>
+ * ```
+ */
+export const GlowBackground = React.memo(({ className }: GlowBackgroundProps) => (
+  <div
+    aria-hidden="true"
+    style={{
+      position: 'absolute',
+      inset: 0,
+      overflow: 'hidden',
+      pointerEvents: 'none',
+      zIndex: 0,
+    }}
+    className={className}
+  >
+    {/* Blue blob — top left */}
+    <div style={{
+      position: 'absolute',
+      top: '-10%',
+      left: '-10%',
+      width: 700,
+      height: 700,
+      borderRadius: '50%',
+      background: 'radial-gradient(circle, hsl(217 91% 60% / 0.5) 0%, transparent 70%)',
+      filter: 'blur(80px)',
+      animation: 'blob 10s ease-in-out infinite',
+    }} />
+
+    {/* Purple blob — bottom right */}
+    <div style={{
+      position: 'absolute',
+      bottom: '-10%',
+      right: '-10%',
+      width: 600,
+      height: 600,
+      borderRadius: '50%',
+      background: 'radial-gradient(circle, hsl(262 83% 65% / 0.4) 0%, transparent 70%)',
+      filter: 'blur(80px)',
+      animation: 'blob 10s ease-in-out infinite',
+      animationDelay: '3s',
+    }} />
+
+    {/* Indigo blob — center top */}
+    <div style={{
+      position: 'absolute',
+      top: '10%',
+      right: '20%',
+      width: 400,
+      height: 400,
+      borderRadius: '50%',
+      background: 'radial-gradient(circle, hsl(234 89% 74% / 0.35) 0%, transparent 70%)',
+      filter: 'blur(60px)',
+      animation: 'blob 12s ease-in-out infinite',
+      animationDelay: '6s',
+    }} />
+  </div>
+));
+
+GlowBackground.displayName = 'GlowBackground';

package/src/components/effects/index.ts

@@ -0,0 +1,2 @@
+export { GlowBackground } from './GlowBackground';
+export type { GlowBackgroundProps } from './GlowBackground';

package/src/components/index.ts

@@ -96,6 +96,10 @@ export { InputGroup, InputGroupAddon, InputGroupButton, InputGroupText, InputGro
 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';
 
+// Effects / Background
+export { GlowBackground } from './effects';
+export type { GlowBackgroundProps } from './effects';
+
 export { CopyButton, CopyField } from './copy';
 export type { CopyButtonProps, CopyFieldProps } from './copy';
 export { DownloadButton } from './button-download';

package/src/components/input-otp.tsx

@@ -53,7 +53,7 @@ const InputOTPSlot = React.forwardRef<
     <div
       ref={ref}
       className={cn(
-        "relative flex h-9 w-9 items-center justify-center border-y border-r border-input text-sm shadow-sm transition-all first:rounded-l-md first:border-l last:rounded-r-md",
+        "relative flex items-center justify-center border-y border-r border-input text-sm shadow-sm transition-all first:rounded-l-md first:border-l last:rounded-r-md",
         isActive && "z-10 ring-1 ring-ring",
         className
       )}

package/src/components/multi-select-pro/async.tsx

@@ -17,7 +17,7 @@ import { cva } from 'class-variance-authority';
 import { Check, ChevronsUpDown, Loader2, X, XCircle } from 'lucide-react';
 import * as React from 'react';
 
-import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useAppT } from '@djangocfg/i18n';
 import { Badge } from '../badge';
 import { Button } from '../button';
 import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator } from '../command';
@@ -197,7 +197,7 @@ export const MultiSelectProAsync = React.forwardRef<MultiSelectProAsyncRef, Mult
     },
     ref
   ) => {
-    const t = useTypedT<I18nTranslations>()
+    const t = useAppT()
     const [open, setOpen] = React.useState(false)
     const [selectedValues, setSelectedValues] = React.useState<string[]>(defaultValue)
     const buttonRef = React.useRef<HTMLButtonElement>(null)

package/src/components/multi-select-pro/index.tsx

@@ -4,7 +4,7 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { Check, ChevronsUpDown, X, XCircle } from 'lucide-react';
 import * as React from 'react';
 
-import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useAppT } from '@djangocfg/i18n';
 import { Badge } from '../badge';
 import { Button } from '../button';
 import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator } from '../command';
@@ -174,7 +174,7 @@ export const MultiSelectPro = React.forwardRef<MultiSelectProRef, MultiSelectPro
     },
     ref
   ) => {
-    const t = useTypedT<I18nTranslations>()
+    const t = useAppT()
     const [open, setOpen] = React.useState(false)
     const [selectedValues, setSelectedValues] = React.useState<string[]>(defaultValue)
     const [search, setSearch] = React.useState("")

package/src/components/multi-select.tsx

@@ -3,7 +3,7 @@
 import { Check, ChevronsUpDown, X } from 'lucide-react';
 import * as React from 'react';
 
-import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useAppT } from '@djangocfg/i18n';
 import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../hooks/useStoredValue';
 import { cn } from '../lib/utils';
 import { Badge } from './badge';
@@ -75,7 +75,7 @@ export function MultiSelect({
   storageTtl,
   autoSelectFromOptions = false,
 }: MultiSelectProps) {
-  const t = useTypedT<I18nTranslations>()
+  const t = useAppT()
   const [open, setOpen] = React.useState(false)
   const [search, setSearch] = React.useState("")
   const scrollRef = React.useRef<HTMLDivElement>(null)

package/src/components/otp/index.tsx

@@ -5,13 +5,16 @@ import * as React from 'react';
 
 import { InputOTP, InputOTPGroup, InputOTPSlot } from '../input-otp';
 import { cn } from '../../lib';
+import { useIsMobile } from '../../hooks/useMobile';
 
 import { createPasteHandler, useSmartOTP } from './use-otp-input';
 
 import type { SmartOTPProps } from './types'
 
 /**
- * Size variants for OTP slots
+ * Size variants for OTP slots.
+ * In fluid mode these only set font-size — width/height are driven by the container.
+ * In fixed mode they set explicit w/h dimensions.
  */
 const sizeVariants = {
   sm: 'h-8 w-8 text-sm',
@@ -19,6 +22,12 @@ const sizeVariants = {
   lg: 'h-14 w-14 text-2xl',
 }
 
+const sizeTextVariants = {
+  sm: 'text-sm',
+  default: 'text-base',
+  lg: 'text-2xl',
+}
+
 /**
  * OTP Separator Component
  */
@@ -85,13 +94,17 @@ export const OTPInput = React.forwardRef<
       slotClassName,
       separatorClassName,
       autoFocus = true,
-      size = 'default',
+      size,
       error = false,
       success = false,
+      fluid = false,
       ...props
     },
     ref
   ) => {
+    const isMobile = useIsMobile()
+    const resolvedSize = size ?? (isMobile ? 'default' : 'lg')
+
     const {
       value: otpValue,
       handleChange,
@@ -143,7 +156,9 @@ export const OTPInput = React.forwardRef<
             key={i}
             index={i}
             className={cn(
-              sizeVariants[size],
+              fluid
+                ? `flex-1 min-w-0 aspect-square ${sizeTextVariants[resolvedSize]}`
+                : sizeVariants[resolvedSize],
               error && 'border-destructive ring-destructive/20',
               success && 'border-green-500 ring-green-500/20',
               slotClassName
@@ -153,7 +168,7 @@ export const OTPInput = React.forwardRef<
       }
 
       return slotElements
-    }, [length, showSeparator, separatorPosition, separatorClassName, size, error, success, slotClassName])
+    }, [length, showSeparator, separatorPosition, separatorClassName, resolvedSize, fluid, error, success, slotClassName])
 
     return (
       <InputOTP
@@ -163,12 +178,12 @@ export const OTPInput = React.forwardRef<
         onChange={handleChange}
         onComplete={handleComplete}
         disabled={disabled}
-        containerClassName={cn('gap-2', containerClassName)}
+        containerClassName={cn('gap-2', fluid && 'w-full', containerClassName)}
         autoFocus={autoFocus}
         onPaste={pasteHandler}
         {...props}
       >
-        <InputOTPGroup>{slots}</InputOTPGroup>
+        <InputOTPGroup className={cn(fluid && 'w-full')}>{slots}</InputOTPGroup>
       </InputOTP>
     )
   }

package/src/components/otp/types.ts

@@ -105,8 +105,7 @@ export interface SmartOTPProps {
   autoFocus?: boolean
 
   /**
-   * Slot size variant
-   * @default 'default'
+   * Slot size variant. When omitted, auto-detects: 'default' on mobile, 'lg' on desktop.
    */
   size?: 'sm' | 'default' | 'lg'
 
@@ -119,6 +118,13 @@ export interface SmartOTPProps {
    * Success state
    */
   success?: boolean
+
+  /**
+   * Fluid mode — slots stretch to fill the full container width.
+   * Useful for responsive layouts where fixed slot widths would overflow.
+   * @default false
+   */
+  fluid?: boolean
 }
 
 /**

package/src/components/phone-input.tsx

@@ -6,7 +6,7 @@ import {
 import { ChevronDown, Search } from 'lucide-react';
 import * as React from 'react';
 
-import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useAppT } from '@djangocfg/i18n';
 import { Button } from './button';
 import { Input } from './input';
 import { cn } from '../lib';
@@ -63,7 +63,7 @@ const PhoneInput = React.forwardRef<HTMLInputElement, PhoneInputProps>(
     disabled = false,
     ...props
   }, ref) => {
-    const t = useTypedT<I18nTranslations>()
+    const t = useAppT()
     const [selectedCountry, setSelectedCountry] = React.useState<CountryCode>(defaultCountry)
     const [inputValue, setInputValue] = React.useState('')
     const [isDropdownOpen, setIsDropdownOpen] = React.useState(false)

package/src/components/preloader.tsx

@@ -10,7 +10,7 @@
 import { Loader2 } from 'lucide-react';
 import React from 'react';
 
-import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useAppT } from '@djangocfg/i18n';
 import { cn } from '../lib/utils';
 // Spinner is available for future use
 // import { Spinner } from './spinner';
@@ -104,7 +104,7 @@ export function Preloader({
   className,
   spinnerClassName,
 }: PreloaderProps) {
-  const t = useTypedT<I18nTranslations>()
+  const t = useAppT()
   const loadingLabel = text || t('ui.states.loading')
   const spinnerSize = sizeMap[size];
 

package/src/components/spinner.tsx

@@ -1,10 +1,10 @@
 import { Loader2Icon } from 'lucide-react';
 
-import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useAppT } from '@djangocfg/i18n';
 import { cn } from '../lib/utils';
 
 function Spinner({ className, ...props }: React.ComponentProps<"svg">) {
-  const t = useTypedT<I18nTranslations>()
+  const t = useAppT()
   const loadingLabel = t('ui.states.loading')
 
   return (

package/src/components/tabs.tsx

@@ -7,7 +7,7 @@ import * as TabsPrimitive from '@radix-ui/react-tabs';
 
 import { useIsMobile } from '../hooks';
 import { useStoredValue, type StorageType } from '../hooks/useStoredValue';
-import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useAppT } from '@djangocfg/i18n';
 import { cn } from '../lib/utils';
 import { Button } from './button';
 import { ScrollArea, ScrollBar } from './scroll-area';
@@ -54,7 +54,7 @@ const Tabs = React.forwardRef<
   React.ElementRef<typeof TabsPrimitive.Root>,
   TabsProps
 >(({ mobileSheet = false, mobileSheetTitle, mobileTitleText, sticky = false, storageKey, storageType, children, ...props }, ref) => {
-  const t = useTypedT<I18nTranslations>()
+  const t = useAppT()
   const resolvedMobileSheetTitle = mobileSheetTitle ?? t('ui.navigation.title')
   const isMobile = useIsMobile()
   const [open, setOpen] = React.useState(false)

package/src/hooks/index.ts

@@ -5,13 +5,15 @@
 
 'use client';
 
-export { useCountdown } from './useCountdown';
+export { useCountdown, useCountdownFromSeconds } from './useCountdown';
+export type { CountdownState } from './useCountdown';
 export { useDebouncedCallback } from './useDebouncedCallback';
 export { useDebounce } from './useDebounce';
 export { useDebugTools } from './useDebugTools';
 export { useEventListener, events } from './useEventsBus';
-export { useIsMobile } from './useMobile';
-export { useMediaQuery } from './useMediaQuery';
+export { useIsMobile, useIsPhone, useIsTabletOrBelow, BREAKPOINTS } from './useMobile';
+export type { Breakpoint } from './useMobile';
+export { useMediaQuery, BREAKPOINTS as MEDIA_BREAKPOINTS } from './useMediaQuery';
 export { useCopy } from './useCopy';
 export { useImageLoader } from './useImageLoader';
 export { useToast, toast } from './useToast';

package/src/hooks/useCountdown.ts

@@ -1,73 +1,113 @@
 'use client';
 
 import moment from 'moment';
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 
-interface CountdownState {
+export interface CountdownState {
   days: number;
   hours: number;
   minutes: number;
   seconds: number;
   isExpired: boolean;
   totalSeconds: number;
+  /** Formatted MM:SS label, e.g. "19:00" */
+  label: string;
 }
 
-export const useCountdown = (targetDate: string | null): CountdownState => {
-  const [countdown, setCountdown] = useState<CountdownState>({
-    days: 0,
-    hours: 0,
-    minutes: 0,
-    seconds: 0,
-    isExpired: false,
-    totalSeconds: 0,
-  });
+const ZERO_STATE: CountdownState = {
+  days: 0,
+  hours: 0,
+  minutes: 0,
+  seconds: 0,
+  isExpired: true,
+  totalSeconds: 0,
+  label: '',
+};
 
-  useEffect(() => {
-    if (!targetDate) {
-      return;
-    }
+function formatLabel(diff: number): string {
+  const m = Math.floor(diff / 60);
+  const s = diff % 60;
+  return m > 0
+    ? `${m}:${String(s).padStart(2, '0')}`
+    : `${s}s`;
+}
 
-    const target = moment.utc(targetDate);
+function secondsToState(diff: number): CountdownState {
+  if (diff <= 0) return ZERO_STATE;
+  return {
+    days: Math.floor(diff / (24 * 60 * 60)),
+    hours: Math.floor((diff % (24 * 60 * 60)) / (60 * 60)),
+    minutes: Math.floor((diff % (60 * 60)) / 60),
+    seconds: diff % 60,
+    isExpired: false,
+    totalSeconds: diff,
+    label: formatLabel(diff),
+  };
+}
 
-    const updateCountdown = () => {
-      const now = moment.utc();
-      const diff = target.diff(now, 'seconds');
+/**
+ * Date-based countdown (existing API).
+ * Re-calculates every second against a UTC date string, converted to local time.
+ */
+export const useCountdown = (targetDate: string | null): CountdownState => {
+  const [countdown, setCountdown] = useState<CountdownState>(ZERO_STATE);
 
-      if (diff <= 0) {
-        setCountdown({
-          days: 0,
-          hours: 0,
-          minutes: 0,
-          seconds: 0,
-          isExpired: true,
-          totalSeconds: 0,
-        });
-        return;
-      }
-
-      const days = Math.floor(diff / (24 * 60 * 60));
-      const hours = Math.floor((diff % (24 * 60 * 60)) / (60 * 60));
-      const minutes = Math.floor((diff % (60 * 60)) / 60);
-      const seconds = diff % 60;
-
-      setCountdown({
-        days,
-        hours,
-        minutes,
-        seconds,
-        isExpired: false,
-        totalSeconds: diff,
-      });
-    };
+  useEffect(() => {
+    if (!targetDate) return;
 
-    // Update immediately
-    updateCountdown();
+    const target = moment.utc(targetDate).local();
 
-    // Update every second
-    const interval = setInterval(updateCountdown, 1000);
+    const tick = () => {
+      const diff = target.diff(moment(), 'seconds');
+      setCountdown(secondsToState(diff));
+    };
 
-    return () => clearInterval(interval);
+    tick();
+    const id = setInterval(tick, 1000);
+    return () => clearInterval(id);
   }, [targetDate]);
 
   return countdown;
 };
+
+/**
+ * Imperative seconds-based countdown with full state breakdown.
+ *
+ * @returns `[state, start]`
+ *   - `state` — current countdown state (days/hours/minutes/seconds/isExpired/totalSeconds/label)
+ *   - `start(n)` — begin/restart countdown from n seconds
+ *
+ * Alias: `useSecondsCountdown` (simple `[seconds, start]`)
+ */
+export const useCountdownFromSeconds = (): [CountdownState, (seconds: number) => void] => {
+  const [state, setState] = useState<CountdownState>(ZERO_STATE);
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const clear = useCallback(() => {
+    if (intervalRef.current !== null) {
+      clearInterval(intervalRef.current);
+      intervalRef.current = null;
+    }
+  }, []);
+
+  const start = useCallback(
+    (initial: number) => {
+      clear();
+      setState(secondsToState(initial));
+      intervalRef.current = setInterval(() => {
+        setState((prev) => {
+          if (prev.totalSeconds <= 1) {
+            clear();
+            return ZERO_STATE;
+          }
+          return secondsToState(prev.totalSeconds - 1);
+        });
+      }, 1000);
+    },
+    [clear],
+  );
+
+  useEffect(() => clear, [clear]);
+
+  return [state, start];
+};

package/src/hooks/useMediaQuery.ts

@@ -3,38 +3,41 @@
 import { useEffect, useState } from 'react';
 
 /**
- * Hook to check if a media query matches
+ * Tailwind v4 default breakpoints (rem → px at 16px base).
+ * In v4 these are CSS variables: var(--breakpoint-sm), var(--breakpoint-md), etc.
  *
- * @param query - CSS media query string
- * @returns boolean indicating if the query matches
+ * Usage with useMediaQuery:
+ *   useMediaQuery(`(max-width: ${BREAKPOINTS.md - 1}px)`) // < 768px
+ *   useMediaQuery(`(min-width: ${BREAKPOINTS.lg}px)`)     // >= 1024px
+ */
+export const BREAKPOINTS = {
+  sm: 640,    // 40rem — phones landscape
+  md: 768,    // 48rem — tablets portrait
+  lg: 1024,   // 64rem — tablets landscape / small laptops
+  xl: 1280,   // 80rem — desktops
+  '2xl': 1536, // 96rem
+} as const
+
+export type Breakpoint = keyof typeof BREAKPOINTS
+
+/**
+ * Reactive media query hook.
  *
  * @example
- * const isMobile = useMediaQuery('(max-width: 768px)');
- * const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
- * const isLandscape = useMediaQuery('(orientation: landscape)');
+ * const isPhone   = useMediaQuery('(max-width: 639px)')
+ * const isDark    = useMediaQuery('(prefers-color-scheme: dark)')
+ * const isLandscape = useMediaQuery('(orientation: landscape)')
  */
 export function useMediaQuery(query: string): boolean {
-  const [matches, setMatches] = useState<boolean>(false);
+  const [matches, setMatches] = useState<boolean>(false)
 
   useEffect(() => {
-    const mediaQuery = window.matchMedia(query);
-
-    // Set initial value
-    setMatches(mediaQuery.matches);
-
-    // Create event listener
-    const handler = (event: MediaQueryListEvent) => {
-      setMatches(event.matches);
-    };
-
-    // Add listener
-    mediaQuery.addEventListener('change', handler);
-
-    // Cleanup
-    return () => {
-      mediaQuery.removeEventListener('change', handler);
-    };
-  }, [query]);
-
-  return matches;
+    const mediaQuery = window.matchMedia(query)
+    setMatches(mediaQuery.matches)
+    const handler = (event: MediaQueryListEvent) => setMatches(event.matches)
+    mediaQuery.addEventListener('change', handler)
+    return () => mediaQuery.removeEventListener('change', handler)
+  }, [query])
+
+  return matches
 }

package/src/hooks/useMobile.tsx

@@ -1,22 +1,35 @@
 'use client';
 
-import * as React from 'react';
+/**
+ * Semantic viewport breakpoint hooks.
+ *
+ * Built on top of useMediaQuery — see useMediaQuery.ts for
+ * BREAKPOINTS constants and raw media query usage.
+ *
+ * @example
+ * import { useIsPhone, useIsMobile, useIsTabletOrBelow } from '@djangocfg/ui-core/hooks'
+ *
+ * const isPhone         = useIsPhone()         // < 640px  (sm)
+ * const isMobile        = useIsMobile()        // < 768px  (md)
+ * const isTabletOrBelow = useIsTabletOrBelow() // < 1024px (lg)
+ */
 
-// Увеличил breakpoint до 1024px чтобы включить планшеты
-const MOBILE_BREAKPOINT = 1024
+import { BREAKPOINTS, useMediaQuery } from './useMediaQuery';
 
-export function useIsMobile() {
-  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+export type { Breakpoint } from './useMediaQuery';
+export { BREAKPOINTS };
 
-  React.useEffect(() => {
-    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
-    const onChange = () => {
-      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
-    }
-    mql.addEventListener("change", onChange)
-    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
-    return () => mql.removeEventListener("change", onChange)
-  }, [])
+/** True when viewport < 640px (Tailwind sm) — phones only. */
+export function useIsPhone(): boolean {
+  return useMediaQuery(`(max-width: ${BREAKPOINTS.sm - 1}px)`)
+}
+
+/** True when viewport < 768px (Tailwind md) — phones + small tablets. */
+export function useIsMobile(): boolean {
+  return useMediaQuery(`(max-width: ${BREAKPOINTS.md - 1}px)`)
+}
 
-  return !!isMobile
+/** True when viewport < 1024px (Tailwind lg) — phones + tablets. */
+export function useIsTabletOrBelow(): boolean {
+  return useMediaQuery(`(max-width: ${BREAKPOINTS.lg - 1}px)`)
 }

package/src/styles/theme/animations.css

@@ -52,6 +52,13 @@
   }
 }
 
+/* Blob - Organic drifting movement for mesh gradient orbs */
+@keyframes blob {
+  0%, 100% { transform: translate(0, 0) scale(1); }
+  33%       { transform: translate(40px, -60px) scale(1.1); }
+  66%       { transform: translate(-30px, 30px) scale(0.9); }
+}
+
 /* Gradient Shift - Color animation with hue rotation */
 @keyframes gradient-shift {
   0%, 100% {

package/src/styles/theme/tokens.css

@@ -132,4 +132,5 @@
   --animate-float-diagonal: float-diagonal 22s ease-in-out infinite;
   --animate-morph: morph 15s ease-in-out infinite;
   --animate-gradient-shift: gradient-shift 10s ease-in-out infinite;
+  --animate-blob: blob 10s ease-in-out infinite;
 }