@airelogic/cron-builder

Cron Builder

Cron Builder is a flexible and user-friendly library for creating and managing cron expressions. Whether you're a novice or an expert, Cron Builder offers a visual editor for easy creation of simple cron schedules, and a direct editor for those who need more complex cron configurations.

Features

• Visual Editor: Simplify cron expression creation with an intuitive visual interface.
• Direct Editor: Advanced users can directly input and edit raw cron expressions.
• Human-Readable Output: Convert cron expressions into a comprehensible format to understand the schedule easily.
• Validation: Ensure the correctness of your cron expression with built-in validation.
• Custom Styling: Style the cron editor according to your application's theme using Material-UI's theming capabilities.
• React Hook Form Integration: Leverage the power of React Hook Form for managing form states, validations, and more. Easily fetch, set, or manipulate cron expression values within your forms.

Under the Hood

Cron Builder is built using modern technologies:

• React
• Material-UI
• React Hook Form

Installation

npm @airelogic/install cron-builder

Usage

Here's a simple usage example:

import { CronBuilder, useCronBuilderFormState } from 'cron-builder';
import { Box, createTheme } from '@mui/material';

const App = () => {
  const cronBuilderFormMethods = useCronBuilderFormState(); // bring in the React Hook Form methods

  const schedule = cronBuilderFormMethods.expression; // access your cron expression

  const demoTheme = createTheme({
    // ... your custom theme configurations
  });

  return (
    <Box sx={{ background: "white", padding: "25px", width: "800px", border: "solid red"}}>
      <CronBuilder
        theme={demoTheme}
        methods={cronBuilderFormMethods}
      />
    </Box>
  );
};

Hydrating with Initial Value

You can pre-populate the CronBuilder with an initial cron expression using the defaultScheduleOverride prop. This is particularly useful when you want to edit a previously saved cron expression.

For example:

<CronBuilder
    defaultScheduleOverride='1 1 1 * *'
    theme={demoTheme}
    methods={cronBuilderFormMethods}
/>

Custom Styling

Cron Builder allows you to inject your custom styles via Material-UI's ThemeProvider. Here's an example:

const demoTheme = createTheme({
    typography: {
        htmlFontSize: 16,
        fontFamily: "'Hind', sans-serif"
    },
    components: {
        // ... your custom component styles
    }
});

Pass in your custom theme prop:

    <CronBuilder theme={demoTheme} methods={cronBuilderFormMethods} />

Integration with React Hook Form

Cron Builder seamlessly integrates with React Hook Form. This allows for a robust form management experience, especially when dealing with cron expressions.

Using the useCronBuilderFormState Hook

To easily integrate and use Cron Builder within your application, the library provides the useCronBuilderFormState hook. This hook exposes various React Hook Form methods, making it effortless to work with form states and cron expressions:

import { useCronBuilderFormState } from 'cron-builder';

const MyComponent = () => {
  const cronMethods = useCronBuilderFormState();

  // Access the generated cron expression
  const scheduleExpression = cronMethods.expression;

  // Other React Hook Form methods are also available
  const { control, watch, setValue, formState, trigger, reset } = cronMethods;
  
  // ... rest of your component
};

Exposed Methods:

• control: Object for React Hook Form's Controller.
• watch: Function to watch specific input/inputs.
• setValue: Function to manually set form values.
• formState: Object containing form state information.
• trigger: Function to manually trigger form validation.
• reset: Function to reset the form values.
• expression: Directly watch the generated cron expression value.

Utilizing these methods, you can deeply integrate Cron Builder's functionalities within your application's form logic.

Peer Dependencies

Ensure that the following peer dependencies are installed in your project:

• @emotion/react
• @emotion/styled
• @mui/icons-material
• @mui/material
• react
• react-dom

Development

For development purposes, you can use the following commands:

• npm run dev: Start the development server.
• npm run build: Build the library for production.
• npm run lint: Lint the codebase.
• npm run preview: Preview the built library.
• npm run test: Run tests with coverage.

If you want to test the package in another project locally, you can use the .tgz file generated by npm.

First, navigate to the library directory and run the following commands:

npm run build
npm pack

This will generate a .tgz file, something like cron-builder-0.0.0.tgz.

In another project where you want to test the library, you can install the package directly from the .tgz file:

npm install /path-to-your-library/cron-builder-0.0.0.tgz

Make sure to replace /path-to-your-library/ with the actual path to where your .tgz file is located.

Once installed, you can import and use the library in your project just like any other npm package.

Helpful Resources

If you're looking to dive deeper into some of the technologies and tools used in cron-builder, these resources will be beneficial:

• React Hook Form: Understand the integration and capabilities of React Hook Form with our library. The useForm documentation provides a comprehensive overview.
• Material-UI Theming: Customizing the look and feel of the cron editor is made easy with Material-UI's theming. Learn more about how you can apply your app's theme with the theming guide.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.