@djangocfg/ui-tools 2.1.130 → 2.1.131

package/src/tools/CronScheduler/context/hooks.ts

@@ -0,0 +1,86 @@
+'use client';
+
+/**
+ * CronScheduler Hooks
+ *
+ * Selective subscription hooks for optimal re-renders.
+ * Each hook returns only the data it needs, preventing
+ * unnecessary re-renders when unrelated state changes.
+ */
+
+import { useMemo } from 'react';
+import { useCronSchedulerContext } from './CronSchedulerContext';
+
+/**
+ * Hook for schedule type selection
+ * Re-renders only when type changes
+ */
+export function useCronType() {
+  const { type, setType } = useCronSchedulerContext();
+  return useMemo(() => ({ type, setType }), [type, setType]);
+}
+
+/**
+ * Hook for time selection
+ * Re-renders only when hour/minute changes
+ */
+export function useCronTime() {
+  const { hour, minute, setTime } = useCronSchedulerContext();
+  return useMemo(() => ({ hour, minute, setTime }), [hour, minute, setTime]);
+}
+
+/**
+ * Hook for week days selection
+ * Re-renders only when weekDays changes
+ */
+export function useCronWeekDays() {
+  const { weekDays, toggleWeekDay, setWeekDays } = useCronSchedulerContext();
+  return useMemo(
+    () => ({ weekDays, toggleWeekDay, setWeekDays }),
+    [weekDays, toggleWeekDay, setWeekDays]
+  );
+}
+
+/**
+ * Hook for month days selection
+ * Re-renders only when monthDays changes
+ */
+export function useCronMonthDays() {
+  const { monthDays, toggleMonthDay, setMonthDays } = useCronSchedulerContext();
+  return useMemo(
+    () => ({ monthDays, toggleMonthDay, setMonthDays }),
+    [monthDays, toggleMonthDay, setMonthDays]
+  );
+}
+
+/**
+ * Hook for custom cron input
+ * Re-renders only when customCron/isValid changes
+ */
+export function useCronCustom() {
+  const { customCron, isValid, setCustomCron } = useCronSchedulerContext();
+  return useMemo(
+    () => ({ customCron, isValid, setCustomCron }),
+    [customCron, isValid, setCustomCron]
+  );
+}
+
+/**
+ * Hook for preview display
+ * Re-renders only when computed values change
+ */
+export function useCronPreview() {
+  const { cronExpression, humanDescription, isValid } = useCronSchedulerContext();
+  return useMemo(
+    () => ({ cronExpression, humanDescription, isValid }),
+    [cronExpression, humanDescription, isValid]
+  );
+}
+
+/**
+ * Full context access
+ * Use sparingly - causes re-render on any state change
+ */
+export function useCronScheduler() {
+  return useCronSchedulerContext();
+}

package/src/tools/CronScheduler/context/index.ts

@@ -0,0 +1,18 @@
+/**
+ * CronScheduler Context
+ */
+
+export {
+  CronSchedulerProvider,
+  useCronSchedulerContext,
+} from './CronSchedulerContext';
+
+export {
+  useCronType,
+  useCronTime,
+  useCronWeekDays,
+  useCronMonthDays,
+  useCronCustom,
+  useCronPreview,
+  useCronScheduler,
+} from './hooks';

package/src/tools/CronScheduler/index.tsx

@@ -0,0 +1,91 @@
+'use client';
+
+/**
+ * CronScheduler
+ *
+ * Compact cron expression builder following Apple HIG principles.
+ * Lazy-loaded for optimal bundle size (~15KB).
+ *
+ * @example
+ * import { CronScheduler } from '@djangocfg/ui-tools';
+ *
+ * <CronScheduler
+ *   value={cron}
+ *   onChange={setCron}
+ *   showPreview
+ * />
+ */
+
+import React, { lazy, Suspense } from 'react';
+import { LoadingFallback } from '../../components';
+import type { CronSchedulerProps } from './types';
+
+// Lazy load the client component
+const CronSchedulerClient = lazy(() => import('./CronScheduler.client'));
+
+/**
+ * CronScheduler with Suspense wrapper
+ */
+export function CronScheduler(props: CronSchedulerProps) {
+  return (
+    <Suspense fallback={<CronSchedulerFallback />}>
+      <CronSchedulerClient {...props} />
+    </Suspense>
+  );
+}
+
+/**
+ * Loading fallback for CronScheduler
+ */
+function CronSchedulerFallback() {
+  return (
+    <LoadingFallback
+      minHeight={120}
+      showText={false}
+      className="rounded-lg"
+    />
+  );
+}
+
+// Re-export types
+export type {
+  CronSchedulerProps,
+  ScheduleType,
+  WeekDay,
+  MonthDay,
+  CronSchedulerState,
+  CronSchedulerContextValue,
+} from './types';
+
+// Re-export context and hooks for advanced usage
+export {
+  CronSchedulerProvider,
+  useCronSchedulerContext,
+  useCronType,
+  useCronTime,
+  useCronWeekDays,
+  useCronMonthDays,
+  useCronCustom,
+  useCronPreview,
+  useCronScheduler,
+} from './context';
+
+// Re-export utilities
+export {
+  buildCron,
+  parseCron,
+  isValidCron,
+  humanizeCron,
+} from './utils';
+
+// Re-export components for custom compositions
+export {
+  ScheduleTypeSelector,
+  TimeSelector,
+  DayChips,
+  MonthDayGrid,
+  CustomInput,
+  SchedulePreview,
+} from './components';
+
+export default CronScheduler;

package/src/tools/CronScheduler/lazy.tsx

@@ -0,0 +1,67 @@
+'use client';
+
+/**
+ * Lazy-loaded CronScheduler Component
+ *
+ * CronScheduler (~15KB) is loaded only when component is rendered.
+ * Use this for automatic code-splitting with Suspense fallback.
+ *
+ * @example
+ * import { LazyCronScheduler } from '@djangocfg/ui-tools';
+ *
+ * <LazyCronScheduler
+ *   value={cron}
+ *   onChange={setCron}
+ * />
+ */
+
+import { createLazyComponent, LoadingFallback } from '../../components';
+import type { CronSchedulerProps } from './types';
+
+// Re-export types
+export type {
+  CronSchedulerProps,
+  ScheduleType,
+  WeekDay,
+  MonthDay,
+  CronSchedulerState,
+} from './types';
+
+/**
+ * LazyCronScheduler - Lazy-loaded cron expression builder
+ *
+ * Automatically shows loading state while CronScheduler loads (~15KB).
+ * Uses createLazyComponent factory for optimal code-splitting.
+ *
+ * @example
+ * // Basic usage
+ * <LazyCronScheduler
+ *   value="0 9 * * *"
+ *   onChange={handleChange}
+ * />
+ *
+ * @example
+ * // With all options
+ * <LazyCronScheduler
+ *   value={cron}
+ *   onChange={setCron}
+ *   defaultType="weekly"
+ *   showPreview
+ *   showCronExpression
+ *   allowCopy
+ *   timeFormat="24h"
+ * />
+ */
+export const LazyCronScheduler = createLazyComponent<CronSchedulerProps>(
+  () => import('./CronScheduler.client'),
+  {
+    displayName: 'LazyCronScheduler',
+    fallback: (
+      <LoadingFallback
+        minHeight={120}
+        showText={false}
+        className="rounded-lg"
+      />
+    ),
+  }
+);

package/src/tools/CronScheduler/types/index.ts

@@ -0,0 +1,112 @@
+/**
+ * CronScheduler Types
+ *
+ * Unix 5-field cron format: minute hour day-of-month month day-of-week
+ */
+
+// ============================================================================
+// Base Types
+// ============================================================================
+
+export type ScheduleType = 'daily' | 'weekly' | 'monthly' | 'custom';
+
+/** Day of week: 0 = Sunday, 1 = Monday, ..., 6 = Saturday */
+export type WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+/** Day of month: 1-31 */
+export type MonthDay =
+  | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10
+  | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20
+  | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31;
+
+// ============================================================================
+// State Types
+// ============================================================================
+
+export interface CronSchedulerState {
+  /** Current schedule type */
+  type: ScheduleType;
+  /** Hour (0-23) */
+  hour: number;
+  /** Minute (0-59) */
+  minute: number;
+  /** Selected week days (for weekly type) */
+  weekDays: WeekDay[];
+  /** Selected month days (for monthly type) */
+  monthDays: MonthDay[];
+  /** Raw cron expression (for custom type) */
+  customCron: string;
+  /** Whether current state produces valid cron */
+  isValid: boolean;
+}
+
+export interface CronSchedulerComputed {
+  /** Generated cron expression */
+  cronExpression: string;
+  /** Human-readable description */
+  humanDescription: string;
+}
+
+// ============================================================================
+// Action Types
+// ============================================================================
+
+export interface CronSchedulerActions {
+  /** Set schedule type */
+  setType: (type: ScheduleType) => void;
+  /** Set time (hour and minute) */
+  setTime: (hour: number, minute: number) => void;
+  /** Toggle a week day selection */
+  toggleWeekDay: (day: WeekDay) => void;
+  /** Set all week days at once */
+  setWeekDays: (days: WeekDay[]) => void;
+  /** Toggle a month day selection */
+  toggleMonthDay: (day: MonthDay) => void;
+  /** Set all month days at once */
+  setMonthDays: (days: MonthDay[]) => void;
+  /** Set custom cron expression */
+  setCustomCron: (cron: string) => void;
+  /** Reset to default state */
+  reset: () => void;
+}
+
+// ============================================================================
+// Context Types
+// ============================================================================
+
+export interface CronSchedulerContextValue
+  extends CronSchedulerState,
+    CronSchedulerComputed,
+    CronSchedulerActions {}
+
+// ============================================================================
+// Component Props
+// ============================================================================
+
+export interface CronSchedulerProps {
+  /** Current cron expression (Unix 5-field format) */
+  value?: string;
+  /** Callback when schedule changes */
+  onChange?: (cron: string) => void;
+  /** Initial schedule type (default: 'daily') */
+  defaultType?: ScheduleType;
+  /** Show human-readable preview (default: true) */
+  showPreview?: boolean;
+  /** Show raw cron expression in preview (default: false) */
+  showCronExpression?: boolean;
+  /** Allow copying cron expression (default: false) */
+  allowCopy?: boolean;
+  /** 12h or 24h time format (default: '24h') */
+  timeFormat?: '12h' | '24h';
+  /** Disable all interactions */
+  disabled?: boolean;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+export interface CronSchedulerProviderProps {
+  children: React.ReactNode;
+  value?: string;
+  onChange?: (cron: string) => void;
+  defaultType?: ScheduleType;
+}

package/src/tools/CronScheduler/utils/cron-builder.ts

@@ -0,0 +1,100 @@
+/**
+ * Cron Builder
+ *
+ * Converts CronSchedulerState to Unix 5-field cron expression
+ * Format: minute hour day-of-month month day-of-week
+ */
+
+import type { CronSchedulerState } from '../types';
+
+/**
+ * Builds Unix 5-field cron expression from state
+ *
+ * @example
+ * // Daily at 9:00
+ * buildCron({ type: 'daily', hour: 9, minute: 0, ... }) // '0 9 * * *'
+ *
+ * // Weekly on Mon, Wed, Fri at 14:30
+ * buildCron({ type: 'weekly', hour: 14, minute: 30, weekDays: [1, 3, 5], ... }) // '30 14 * * 1,3,5'
+ *
+ * // Monthly on 1st and 15th at 0:00
+ * buildCron({ type: 'monthly', hour: 0, minute: 0, monthDays: [1, 15], ... }) // '0 0 1,15 * *'
+ */
+export function buildCron(state: CronSchedulerState): string {
+  const { type, hour, minute, weekDays, monthDays, customCron } = state;
+
+  // Ensure valid hour/minute
+  const h = Math.max(0, Math.min(23, hour));
+  const m = Math.max(0, Math.min(59, minute));
+
+  switch (type) {
+    case 'daily':
+      // Run every day at specified time
+      return `${m} ${h} * * *`;
+
+    case 'weekly': {
+      // Run on specified days of week at specified time
+      const sortedDays = [...weekDays].sort((a, b) => a - b);
+      const daysStr = sortedDays.length > 0 ? formatNumberList(sortedDays) : '*';
+      return `${m} ${h} * * ${daysStr}`;
+    }
+
+    case 'monthly': {
+      // Run on specified days of month at specified time
+      const sortedDays = [...monthDays].sort((a, b) => a - b);
+      const daysStr = sortedDays.length > 0 ? formatNumberList(sortedDays) : '1';
+      return `${m} ${h} ${daysStr} * *`;
+    }
+
+    case 'custom':
+      // Return user-provided expression
+      return customCron.trim() || '* * * * *';
+
+    default:
+      return '0 0 * * *';
+  }
+}
+
+/**
+ * Formats a list of numbers as ranges where possible
+ * [1,2,3,5,7,8,9] -> "1-3,5,7-9"
+ */
+function formatNumberList(nums: number[]): string {
+  if (nums.length === 0) return '';
+  if (nums.length === 1) return nums[0].toString();
+
+  const sorted = [...nums].sort((a, b) => a - b);
+  const ranges: string[] = [];
+  let start = sorted[0];
+  let end = sorted[0];
+
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i] === end + 1) {
+      // Continue the range
+      end = sorted[i];
+    } else {
+      // End current range, start new one
+      ranges.push(start === end ? `${start}` : `${start}-${end}`);
+      start = sorted[i];
+      end = sorted[i];
+    }
+  }
+
+  // Don't forget the last range
+  ranges.push(start === end ? `${start}` : `${start}-${end}`);
+
+  return ranges.join(',');
+}
+
+/**
+ * Builds cron for a specific schedule type with defaults
+ */
+export function buildDefaultCron(type: CronSchedulerState['type']): string {
+  const defaults: Record<typeof type, string> = {
+    daily: '0 9 * * *',      // Every day at 9:00
+    weekly: '0 9 * * 1-5',   // Weekdays at 9:00
+    monthly: '0 9 1 * *',    // 1st of month at 9:00
+    custom: '* * * * *',     // Every minute
+  };
+  return defaults[type];
+}

package/src/tools/CronScheduler/utils/cron-humanize.ts

@@ -0,0 +1,218 @@
+/**
+ * Cron Humanize
+ *
+ * Converts cron expressions to human-readable descriptions
+ */
+
+const WEEKDAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+const WEEKDAY_SHORT = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+
+/**
+ * Converts cron expression to human-readable description
+ *
+ * Examples:
+ * - humanizeCron('0 9 * * *') returns "Every day at 09:00"
+ * - humanizeCron('30 14 * * 1,3,5') returns "Mon, Wed, Fri at 14:30"
+ * - humanizeCron('0 0 1 * *') returns "1st of every month at 00:00"
+ */
+export function humanizeCron(cron: string): string {
+  if (!cron || typeof cron !== 'string') return 'Invalid schedule';
+
+  const parts = cron.trim().split(/\s+/);
+  if (parts.length !== 5) return 'Invalid schedule';
+
+  const [minutePart, hourPart, dayOfMonthPart, monthPart, dayOfWeekPart] = parts;
+
+  // Parse time
+  const minute = parseInt(minutePart, 10);
+  const hour = parseInt(hourPart, 10);
+  const timeStr = formatTime(hour, minute);
+
+  // Every minute
+  if (minutePart === '*' && hourPart === '*' && dayOfMonthPart === '*' && monthPart === '*' && dayOfWeekPart === '*') {
+    return 'Every minute';
+  }
+
+  // Every N minutes
+  if (minutePart.startsWith('*/')) {
+    const interval = parseInt(minutePart.slice(2), 10);
+    if (hourPart === '*') {
+      return `Every ${interval} minute${interval > 1 ? 's' : ''}`;
+    }
+    return `Every ${interval} minute${interval > 1 ? 's' : ''} at hour ${hour}`;
+  }
+
+  // Hourly
+  if (!isNaN(minute) && hourPart === '*' && dayOfMonthPart === '*' && monthPart === '*' && dayOfWeekPart === '*') {
+    return `Every hour at minute ${minute}`;
+  }
+
+  // Daily
+  if (dayOfMonthPart === '*' && monthPart === '*' && dayOfWeekPart === '*') {
+    return `Every day at ${timeStr}`;
+  }
+
+  // Weekly
+  if (dayOfMonthPart === '*' && monthPart === '*' && dayOfWeekPart !== '*') {
+    const days = parseWeekDays(dayOfWeekPart);
+
+    if (days.length === 7) {
+      return `Every day at ${timeStr}`;
+    }
+
+    if (days.length === 5 && isWeekdays(days)) {
+      return `Weekdays at ${timeStr}`;
+    }
+
+    if (days.length === 2 && isWeekend(days)) {
+      return `Weekends at ${timeStr}`;
+    }
+
+    const dayNames = days.map(d => WEEKDAY_SHORT[d]).join(', ');
+    return `${dayNames} at ${timeStr}`;
+  }
+
+  // Monthly
+  if (dayOfMonthPart !== '*' && monthPart === '*' && dayOfWeekPart === '*') {
+    const days = parseMonthDays(dayOfMonthPart);
+
+    if (days.length === 1) {
+      return `${ordinal(days[0])} of every month at ${timeStr}`;
+    }
+
+    if (days.length <= 3) {
+      const dayStr = days.map(d => ordinal(d)).join(', ');
+      return `${dayStr} of every month at ${timeStr}`;
+    }
+
+    return `${days.length} days per month at ${timeStr}`;
+  }
+
+  // Complex expression - show as-is
+  return `Custom schedule`;
+}
+
+/**
+ * Formats time as HH:MM
+ */
+function formatTime(hour: number, minute: number): string {
+  const h = isNaN(hour) ? 0 : Math.max(0, Math.min(23, hour));
+  const m = isNaN(minute) ? 0 : Math.max(0, Math.min(59, minute));
+  return `${h.toString().padStart(2, '0')}:${m.toString().padStart(2, '0')}`;
+}
+
+/**
+ * Formats time in 12-hour format with AM/PM
+ */
+export function formatTime12h(hour: number, minute: number): string {
+  const h = isNaN(hour) ? 0 : Math.max(0, Math.min(23, hour));
+  const m = isNaN(minute) ? 0 : Math.max(0, Math.min(59, minute));
+  const period = h >= 12 ? 'PM' : 'AM';
+  const h12 = h % 12 || 12;
+  return `${h12}:${m.toString().padStart(2, '0')} ${period}`;
+}
+
+/**
+ * Parses week days from cron field
+ */
+function parseWeekDays(part: string): number[] {
+  const result: number[] = [];
+
+  // Handle ranges like 1-5
+  if (part.includes('-') && !part.includes(',')) {
+    const [start, end] = part.split('-').map(s => parseInt(s, 10));
+    if (!isNaN(start) && !isNaN(end)) {
+      for (let i = start; i <= end && i <= 6; i++) {
+        if (i >= 0) result.push(i);
+      }
+    }
+    return result;
+  }
+
+  // Handle comma-separated list
+  for (const segment of part.split(',')) {
+    // Handle nested ranges
+    if (segment.includes('-')) {
+      const [start, end] = segment.split('-').map(s => parseInt(s, 10));
+      if (!isNaN(start) && !isNaN(end)) {
+        for (let i = start; i <= end && i <= 6; i++) {
+          if (i >= 0) result.push(i);
+        }
+      }
+    } else {
+      const num = parseInt(segment.trim(), 10);
+      if (!isNaN(num) && num >= 0 && num <= 6) {
+        result.push(num);
+      }
+    }
+  }
+
+  return result.sort((a, b) => a - b);
+}
+
+/**
+ * Parses month days from cron field
+ */
+function parseMonthDays(part: string): number[] {
+  const result: number[] = [];
+
+  // Handle ranges
+  if (part.includes('-') && !part.includes(',')) {
+    const [start, end] = part.split('-').map(s => parseInt(s, 10));
+    if (!isNaN(start) && !isNaN(end)) {
+      for (let i = start; i <= end && i <= 31; i++) {
+        if (i >= 1) result.push(i);
+      }
+    }
+    return result;
+  }
+
+  // Handle comma-separated list
+  for (const segment of part.split(',')) {
+    const num = parseInt(segment.trim(), 10);
+    if (!isNaN(num) && num >= 1 && num <= 31) {
+      result.push(num);
+    }
+  }
+
+  return result.sort((a, b) => a - b);
+}
+
+/**
+ * Checks if days array represents weekdays (Mon-Fri)
+ */
+function isWeekdays(days: number[]): boolean {
+  const sorted = [...days].sort((a, b) => a - b);
+  return sorted.join(',') === '1,2,3,4,5';
+}
+
+/**
+ * Checks if days array represents weekend (Sat-Sun)
+ */
+function isWeekend(days: number[]): boolean {
+  const sorted = [...days].sort((a, b) => a - b);
+  return sorted.join(',') === '0,6';
+}
+
+/**
+ * Returns ordinal suffix for a number (1st, 2nd, 3rd, etc.)
+ */
+function ordinal(n: number): string {
+  const s = ['th', 'st', 'nd', 'rd'];
+  const v = n % 100;
+  return n + (s[(v - 20) % 10] || s[v] || s[0]);
+}
+
+/**
+ * Gets full weekday name
+ */
+export function getWeekdayName(day: number): string {
+  return WEEKDAY_NAMES[day] || 'Unknown';
+}
+
+/**
+ * Gets short weekday name
+ */
+export function getWeekdayShort(day: number): string {
+  return WEEKDAY_SHORT[day] || '?';
+}