@djangocfg/ui-tools 2.1.129 → 2.1.131

package/src/tools/CronScheduler/CronScheduler.client.tsx

@@ -0,0 +1,140 @@
+'use client';
+
+/**
+ * CronScheduler Client Component
+ *
+ * Compact cron expression builder following Apple HIG principles.
+ * Uses context-based architecture for state management.
+ */
+
+import { cn } from '@djangocfg/ui-core/lib';
+import { CronSchedulerProvider } from './context/CronSchedulerContext';
+import { useCronType } from './context/hooks';
+import {
+  ScheduleTypeSelector,
+  TimeSelector,
+  DayChips,
+  MonthDayGrid,
+  CustomInput,
+  SchedulePreview,
+} from './components';
+import type { CronSchedulerProps } from './types';
+
+// ============================================================================
+// Inner Component (uses context)
+// ============================================================================
+
+interface CronSchedulerInnerProps {
+  showPreview: boolean;
+  showCronExpression: boolean;
+  allowCopy: boolean;
+  timeFormat: '12h' | '24h';
+  disabled: boolean;
+  className?: string;
+}
+
+function CronSchedulerInner({
+  showPreview,
+  showCronExpression,
+  allowCopy,
+  timeFormat,
+  disabled,
+  className,
+}: CronSchedulerInnerProps) {
+  const { type } = useCronType();
+
+  return (
+    <div className={cn('space-y-3', className)}>
+      {/* Schedule Type Selector */}
+      <ScheduleTypeSelector disabled={disabled} />
+
+      {/* Time Selector (shown for daily, weekly, monthly) */}
+      {type !== 'custom' && (
+        <TimeSelector format={timeFormat} disabled={disabled} />
+      )}
+
+      {/* Day Chips (weekly only) */}
+      {type === 'weekly' && (
+        <DayChips disabled={disabled} showPresets />
+      )}
+
+      {/* Month Day Grid (monthly only) */}
+      {type === 'monthly' && (
+        <MonthDayGrid disabled={disabled} showPresets />
+      )}
+
+      {/* Custom Input (custom only) */}
+      {type === 'custom' && (
+        <CustomInput disabled={disabled} />
+      )}
+
+      {/* Preview - always show cron expression */}
+      {showPreview && (
+        <SchedulePreview
+          showCronExpression
+          allowCopy={allowCopy}
+        />
+      )}
+    </div>
+  );
+}
+
+// ============================================================================
+// Main Component (with Provider)
+// ============================================================================
+
+/**
+ * CronScheduler - Compact cron expression builder
+ *
+ * A user-friendly interface for creating cron schedules without
+ * needing to know cron syntax. Follows Apple HIG design principles.
+ *
+ * @example
+ * // Basic usage
+ * <CronScheduler
+ *   value={cronExpression}
+ *   onChange={setCronExpression}
+ * />
+ *
+ * @example
+ * // With all options
+ * <CronScheduler
+ *   value="0 9 * * 1-5"
+ *   onChange={handleChange}
+ *   defaultType="weekly"
+ *   showPreview
+ *   showCronExpression
+ *   allowCopy
+ *   timeFormat="24h"
+ * />
+ */
+export function CronScheduler({
+  value,
+  onChange,
+  defaultType = 'daily',
+  showPreview = true,
+  showCronExpression = false,
+  allowCopy = false,
+  timeFormat = '24h',
+  disabled = false,
+  className,
+}: CronSchedulerProps) {
+  return (
+    <CronSchedulerProvider
+      value={value}
+      onChange={onChange}
+      defaultType={defaultType}
+    >
+      <CronSchedulerInner
+        showPreview={showPreview}
+        showCronExpression={showCronExpression}
+        allowCopy={allowCopy}
+        timeFormat={timeFormat}
+        disabled={disabled}
+        className={className}
+      />
+    </CronSchedulerProvider>
+  );
+}
+
+export default CronScheduler;

package/src/tools/CronScheduler/CronScheduler.story.tsx

@@ -0,0 +1,220 @@
+import { useState } from 'react';
+import { defineStory, useBoolean, useSelect } from '@djangocfg/playground';
+import { CronScheduler } from './index';
+
+export default defineStory({
+  title: 'Tools/Cron Scheduler',
+  component: CronScheduler,
+  description: 'Compact cron expression builder with Apple HIG-style UI.',
+});
+
+export const Interactive = () => {
+  const [cron, setCron] = useState('0 9 * * 1-5');
+
+  const [defaultType] = useSelect('defaultType', {
+    options: ['daily', 'weekly', 'monthly', 'custom'] as const,
+    defaultValue: 'weekly',
+    label: 'Default Type',
+    description: 'Initial schedule type',
+  });
+
+  const [showPreview] = useBoolean('showPreview', {
+    defaultValue: true,
+    label: 'Show Preview',
+    description: 'Show human-readable preview',
+  });
+
+  const [showCronExpression] = useBoolean('showCronExpression', {
+    defaultValue: true,
+    label: 'Show Cron Expression',
+    description: 'Show raw cron expression in preview',
+  });
+
+  const [allowCopy] = useBoolean('allowCopy', {
+    defaultValue: true,
+    label: 'Allow Copy',
+    description: 'Enable copy to clipboard',
+  });
+
+  const [timeFormat] = useSelect('timeFormat', {
+    options: ['24h', '12h'] as const,
+    defaultValue: '24h',
+    label: 'Time Format',
+    description: 'Time display format',
+  });
+
+  const [disabled] = useBoolean('disabled', {
+    defaultValue: false,
+    label: 'Disabled',
+    description: 'Disable all interactions',
+  });
+
+  return (
+    <div className="w-[400px]">
+      <CronScheduler
+        value={cron}
+        onChange={setCron}
+        defaultType={defaultType}
+        showPreview={showPreview}
+        showCronExpression={showCronExpression}
+        allowCopy={allowCopy}
+        timeFormat={timeFormat}
+        disabled={disabled}
+      />
+    </div>
+  );
+};
+
+export const Daily = () => {
+  const [cron, setCron] = useState('0 9 * * *');
+
+  return (
+    <div className="w-[400px]">
+      <CronScheduler
+        value={cron}
+        onChange={setCron}
+        defaultType="daily"
+        showPreview
+      />
+    </div>
+  );
+};
+
+export const Weekly = () => {
+  const [cron, setCron] = useState('30 14 * * 1,3,5');
+
+  return (
+    <div className="w-[400px]">
+      <CronScheduler
+        value={cron}
+        onChange={setCron}
+        defaultType="weekly"
+        showPreview
+      />
+    </div>
+  );
+};
+
+export const Monthly = () => {
+  const [cron, setCron] = useState('0 9 1,15 * *');
+
+  return (
+    <div className="w-[400px]">
+      <CronScheduler
+        value={cron}
+        onChange={setCron}
+        defaultType="monthly"
+        showPreview
+      />
+    </div>
+  );
+};
+
+export const Custom = () => {
+  const [cron, setCron] = useState('*/15 9-17 * * 1-5');
+
+  return (
+    <div className="w-[400px]">
+      <CronScheduler
+        value={cron}
+        onChange={setCron}
+        defaultType="custom"
+        showPreview
+        showCronExpression
+      />
+    </div>
+  );
+};
+
+export const WithCronExpression = () => {
+  const [cron, setCron] = useState('0 9 * * 1-5');
+
+  return (
+    <div className="w-[400px]">
+      <CronScheduler
+        value={cron}
+        onChange={setCron}
+        showPreview
+        showCronExpression
+        allowCopy
+      />
+    </div>
+  );
+};
+
+export const TwelveHourFormat = () => {
+  const [cron, setCron] = useState('0 14 * * *');
+
+  return (
+    <div className="w-[400px]">
+      <CronScheduler
+        value={cron}
+        onChange={setCron}
+        showPreview
+        timeFormat="12h"
+      />
+    </div>
+  );
+};
+
+export const Disabled = () => (
+  <div className="w-[400px]">
+    <CronScheduler
+      value="0 9 * * 1-5"
+      showPreview
+      disabled
+    />
+  </div>
+);
+
+export const Compact = () => {
+  const [cron, setCron] = useState('0 9 * * 1-5');
+
+  return (
+    <div className="w-[400px]">
+      <CronScheduler
+        value={cron}
+        onChange={setCron}
+        defaultType="weekly"
+        showPreview={false}
+      />
+    </div>
+  );
+};
+
+export const Controlled = () => {
+  const [cron, setCron] = useState('0 9 * * *');
+
+  const presets = [
+    { label: 'Every day at 9am', value: '0 9 * * *' },
+    { label: 'Weekdays at 6pm', value: '0 18 * * 1-5' },
+    { label: 'Every Monday', value: '0 0 * * 1' },
+    { label: '1st of month', value: '0 0 1 * *' },
+  ];
+
+  return (
+    <div className="w-[400px] space-y-4">
+      <div className="flex flex-wrap gap-2">
+        {presets.map(({ label, value }) => (
+          <button
+            key={value}
+            onClick={() => setCron(value)}
+            className={`px-2 py-1 text-xs rounded-md transition-colors ${
+              cron === value
+                ? 'bg-primary text-primary-foreground'
+                : 'bg-muted hover:bg-muted/80'
+            }`}
+          >
+            {label}
+          </button>
+        ))}
+      </div>
+      <CronScheduler
+        value={cron}
+        onChange={setCron}
+        showPreview
+        allowCopy
+      />
+    </div>
+  );
+};

package/src/tools/CronScheduler/components/CronCheatsheet.tsx

@@ -0,0 +1,101 @@
+'use client';
+
+/**
+ * CronCheatsheet
+ *
+ * Popover with cron syntax reference.
+ */
+
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+} from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+import { HelpCircle } from 'lucide-react';
+
+export interface CronCheatsheetProps {
+  className?: string;
+}
+
+export function CronCheatsheet({ className }: CronCheatsheetProps) {
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          className={cn(
+            'p-1 rounded hover:bg-muted/50 transition-colors',
+            className
+          )}
+          aria-label="Cron syntax help"
+        >
+          <HelpCircle className="h-4 w-4 text-muted-foreground" />
+        </button>
+      </PopoverTrigger>
+      <PopoverContent className="w-72 p-3" align="end">
+        <div className="space-y-3">
+          <p className="font-medium text-sm">Cron Format</p>
+          <code className="block text-xs bg-muted px-2 py-1.5 rounded font-mono text-center">
+            min hour day month weekday
+          </code>
+
+          <div className="grid grid-cols-2 gap-x-4 gap-y-1 text-xs">
+            <div className="flex justify-between">
+              <span className="text-muted-foreground">minute</span>
+              <span>0-59</span>
+            </div>
+            <div className="flex justify-between">
+              <span className="text-muted-foreground">hour</span>
+              <span>0-23</span>
+            </div>
+            <div className="flex justify-between">
+              <span className="text-muted-foreground">day</span>
+              <span>1-31</span>
+            </div>
+            <div className="flex justify-between">
+              <span className="text-muted-foreground">month</span>
+              <span>1-12</span>
+            </div>
+            <div className="flex justify-between col-span-2">
+              <span className="text-muted-foreground">weekday</span>
+              <span>0-6 (Sun-Sat)</span>
+            </div>
+          </div>
+
+          <div className="pt-2 border-t border-border space-y-1.5">
+            <p className="text-xs font-medium">Special characters</p>
+            <div className="grid grid-cols-2 gap-1.5 text-xs">
+              <span><code className="bg-muted px-1 rounded">*</code> any value</span>
+              <span><code className="bg-muted px-1 rounded">,</code> list (1,3,5)</span>
+              <span><code className="bg-muted px-1 rounded">-</code> range (1-5)</span>
+              <span><code className="bg-muted px-1 rounded">/</code> step (*/15)</span>
+            </div>
+          </div>
+
+          <div className="pt-2 border-t border-border space-y-1.5">
+            <p className="text-xs font-medium">Examples</p>
+            <div className="space-y-1 text-xs">
+              <div className="flex justify-between font-mono">
+                <span className="text-muted-foreground">0 9 * * *</span>
+                <span>daily at 9am</span>
+              </div>
+              <div className="flex justify-between font-mono">
+                <span className="text-muted-foreground">0 9 * * 1-5</span>
+                <span>weekdays 9am</span>
+              </div>
+              <div className="flex justify-between font-mono">
+                <span className="text-muted-foreground">*/15 * * * *</span>
+                <span>every 15 min</span>
+              </div>
+              <div className="flex justify-between font-mono">
+                <span className="text-muted-foreground">0 0 1 * *</span>
+                <span>1st of month</span>
+              </div>
+            </div>
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}

package/src/tools/CronScheduler/components/CustomInput.tsx

@@ -0,0 +1,67 @@
+'use client';
+
+/**
+ * CustomInput
+ *
+ * Raw cron expression input with validation and help popover.
+ */
+
+import { useState, useEffect } from 'react';
+import { Input } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+import { AlertCircle, CheckCircle2 } from 'lucide-react';
+import { useCronCustom } from '../context/hooks';
+import { isValidCron } from '../utils/cron-parser';
+
+export interface CustomInputProps {
+  disabled?: boolean;
+  className?: string;
+}
+
+export function CustomInput({ disabled, className }: CustomInputProps) {
+  const { customCron, isValid, setCustomCron } = useCronCustom();
+  const [localValue, setLocalValue] = useState(customCron);
+  const [localValid, setLocalValid] = useState(isValid);
+
+  useEffect(() => {
+    setLocalValue(customCron);
+    setLocalValid(isValid);
+  }, [customCron, isValid]);
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const value = e.target.value;
+    setLocalValue(value);
+    const valid = isValidCron(value);
+    setLocalValid(valid);
+    setCustomCron(value);
+  };
+
+  return (
+    <div className={cn('space-y-2', className)}>
+      <span className="text-sm text-muted-foreground">Cron expression</span>
+
+      <div className="relative">
+        <Input
+          type="text"
+          value={localValue}
+          onChange={handleChange}
+          disabled={disabled}
+          placeholder="* * * * *"
+          className={cn(
+            'font-mono text-base pr-10 h-11',
+            !localValid && localValue.trim() && 'border-destructive focus-visible:ring-destructive/50'
+          )}
+        />
+        <div className="absolute right-3 top-1/2 -translate-y-1/2">
+          {localValue.trim() && (
+            localValid ? (
+              <CheckCircle2 className="h-5 w-5 text-green-500" />
+            ) : (
+              <AlertCircle className="h-5 w-5 text-destructive" />
+            )
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/tools/CronScheduler/components/DayChips.tsx

@@ -0,0 +1,130 @@
+'use client';
+
+/**
+ * DayChips
+ *
+ * Full-width day of week selector with clear labels.
+ * Shows abbreviated day names for clarity.
+ */
+
+import { cn } from '@djangocfg/ui-core/lib';
+import { useCronWeekDays } from '../context/hooks';
+import type { WeekDay } from '../types';
+
+const DAYS: { value: WeekDay; label: string }[] = [
+  { value: 1, label: 'Mon' },
+  { value: 2, label: 'Tue' },
+  { value: 3, label: 'Wed' },
+  { value: 4, label: 'Thu' },
+  { value: 5, label: 'Fri' },
+  { value: 6, label: 'Sat' },
+  { value: 0, label: 'Sun' },
+];
+
+export interface DayChipsProps {
+  disabled?: boolean;
+  showPresets?: boolean;
+  className?: string;
+}
+
+export function DayChips({
+  disabled,
+  showPresets = true,
+  className,
+}: DayChipsProps) {
+  const { weekDays, toggleWeekDay, setWeekDays } = useCronWeekDays();
+
+  const isWeekdays = weekDays.length === 5 && [1,2,3,4,5].every(d => weekDays.includes(d as WeekDay));
+  const isWeekend = weekDays.length === 2 && [0,6].every(d => weekDays.includes(d as WeekDay));
+  const isEveryday = weekDays.length === 7;
+
+  return (
+    <div className={cn('space-y-3', className)}>
+      {/* Day Grid - full width */}
+      <div className="grid grid-cols-7 gap-1">
+        {DAYS.map(({ value, label }) => {
+          const isSelected = weekDays.includes(value);
+          const isWeekend = value === 0 || value === 6;
+
+          return (
+            <button
+              key={value}
+              type="button"
+              disabled={disabled}
+              onClick={() => toggleWeekDay(value)}
+              aria-pressed={isSelected}
+              className={cn(
+                'flex flex-col items-center justify-center',
+                'py-2.5 rounded-lg text-xs font-medium',
+                'transition-all duration-150',
+                'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary/50',
+                'active:scale-[0.97]',
+                isSelected
+                  ? 'bg-primary text-primary-foreground shadow-sm'
+                  : cn(
+                      'bg-muted/50 hover:bg-muted',
+                      isWeekend ? 'text-muted-foreground/70' : 'text-muted-foreground'
+                    ),
+                disabled && 'opacity-50 cursor-not-allowed pointer-events-none'
+              )}
+            >
+              <span>{label}</span>
+            </button>
+          );
+        })}
+      </div>
+
+      {/* Quick Presets */}
+      {showPresets && (
+        <div className="flex gap-2">
+          <PresetButton
+            label="Weekdays"
+            isActive={isWeekdays}
+            onClick={() => setWeekDays([1, 2, 3, 4, 5] as WeekDay[])}
+            disabled={disabled}
+          />
+          <PresetButton
+            label="Weekends"
+            isActive={isWeekend}
+            onClick={() => setWeekDays([0, 6] as WeekDay[])}
+            disabled={disabled}
+          />
+          <PresetButton
+            label="Every day"
+            isActive={isEveryday}
+            onClick={() => setWeekDays([0, 1, 2, 3, 4, 5, 6] as WeekDay[])}
+            disabled={disabled}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+interface PresetButtonProps {
+  label: string;
+  isActive: boolean;
+  onClick: () => void;
+  disabled?: boolean;
+}
+
+function PresetButton({ label, isActive, onClick, disabled }: PresetButtonProps) {
+  return (
+    <button
+      type="button"
+      disabled={disabled}
+      onClick={onClick}
+      className={cn(
+        'flex-1 px-3 py-1.5 rounded-md text-xs font-medium',
+        'transition-colors duration-150',
+        'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary/50',
+        isActive
+          ? 'bg-primary/15 text-primary border border-primary/30'
+          : 'bg-muted/30 text-muted-foreground hover:bg-muted/50 border border-transparent',
+        disabled && 'opacity-50 cursor-not-allowed'
+      )}
+    >
+      {label}
+    </button>
+  );
+}