@praxisui/cron-builder/README.md

Cron expression builder utilities and components for Praxis UI.

# @praxisui/cron-builder

Angular cron expression builder component with validation, humanized description and preview of next occurrences. Ships as a standalone component.

## 🔰 Exemplos / Quickstart

Para ver esta biblioteca em funcionamento em uma aplicação completa, utilize o projeto de exemplo (Quickstart):

- Repositório: https://github.com/codexrodrigues/praxis-ui-quickstart
- O Quickstart demonstra a integração das bibliotecas `@praxisui/*` em um app Angular, incluindo instalação, configuração e uso em telas reais.

## Install

```bash
npm i @praxisui/cron-builder
```

Peer dependencies (Angular v20):
- `@angular/core` `^20.1.0`
- `@angular/common` `^20.1.0`
- `@angular/forms` `^20.1.0`
- `@angular/cdk` `^20.1.0`
- `@angular/material` `^20.1.0`
- `@praxisui/core` `^0.0.1`

Runtime dependencies (installed automatically):
- `cron-parser`, `cronstrue`, `cron-validator`, `luxon`

## Quick Start

Import the standalone component and use it in your template.

```ts
// Any standalone component or NgModule-enabled component
import { Component } from '@angular/core';
import { PdxCronBuilderComponent } from '@praxisui/cron-builder';

@Component({
  selector: 'app-schedule-form',
  standalone: true,
  imports: [PdxCronBuilderComponent],
  template: `
    <pdx-cron-builder
      [metadata]="metadata"
      (ngModelChange)="onCronChange($event)"
    ></pdx-cron-builder>
  `,
})
export class ScheduleFormComponent {
  metadata = {
    mode: 'both',
    timezone: 'UTC',
    presets: [
      { label: 'Every 5 minutes', cron: '*/5 * * * *' },
      { label: 'Daily at midnight', cron: '0 0 * * *' },
    ],
    previewOccurrences: 5,
  } satisfies CronBuilderMetadata;

  onCronChange(cron: string) {
    console.log('Selected CRON:', cron);
  }
}
```

Template-only example:

```html
<pdx-cron-builder [metadata]="{ mode: 'advanced', timezone: 'UTC', previewOccurrences: 3 }"></pdx-cron-builder>
```

## API (Quick Reference)

Exports:
- `PdxCronBuilderComponent`
- Types: `CronBuilderMetadata`, `SimpleCronFormValue`, `AdvancedCronFormValue`, `CronPresetType`

Inputs/Outputs:
- `metadata: CronBuilderMetadata` – configure fields, timezone, locale, presets, preview.
- Implements `ControlValueAccessor` – bind with `[(ngModel)]` or reactive forms.

`CronBuilderMetadata` (key fields):
- `mode?: 'simple' | 'advanced' | 'both'` – enabled UI tabs.
- `fields?: { seconds?: boolean; ... }` – show seconds field.
- `timezone?: string` – IANA tz used for preview (e.g. `UTC`, `America/Sao_Paulo`).
- `locale?: string` – locale used by humanized text.
- `presets?: Array<{ label: string; cron: string }>` – quick-pick presets.
- `previewOccurrences?: number` – number of preview dates to show.
- `validators?: { invalidCronMessage?: string }` – customize error messages.

## CommonJS/ESM Notes

This component dynamically imports `cron-parser`, `cronstrue` and `cron-validator`. Some versions of these, or their transitive deps (e.g. `luxon`), may emit CommonJS warnings in Angular builds.

If you want to suppress warnings in your app build, add them to `allowedCommonJsDependencies`:

```json
// angular.json
{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "allowedCommonJsDependencies": [
              "cron-parser",
              "cronstrue",
              "cron-validator",
              "luxon"
            ]
          }
        }
      }
    }
  }
}
```

Note: Depending on your Angular CLI version, the warning behavior can vary. The above option is supported in current CLI releases when using the application builder.

## Compatibility

- Angular: v20.x
- Module format: ESM2022, partial Ivy metadata

## License

Apache-2.0 – see `LICENSE` packaged with this library or the repository root.