ngx-strata 0.5.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-strata",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "A simple UI framework for quickly prototyping angular applications with a bit of flair.",
   "license": "MIT",
   "peerDependencies": {

package/skills/ngx-strata/SKILL.md

@@ -97,9 +97,12 @@ for each component are stored in separate files.
 - **Breadcrumb** (`st-breadcrumb`): Read
   [`components/breadcrumb.md`](components/breadcrumb.md)
 - **Button** (`[stButton]`): Read [`components/button.md`](components/button.md)
+- **Calendar** (`st-calendar`): Read [`components/calendar.md`](components/calendar.md)
 - **Card** (`st-card`): Read [`components/card.md`](components/card.md)
 - **Checkbox** (`st-checkbox`): Read
   [`components/checkbox.md`](components/checkbox.md)
+- **Datepicker** (`st-datepicker`): Read [`components/datepicker.md`](components/datepicker.md)
+- **Date-range-picker** (`st-date-range-picker`): Read [`components/date-range-picker.md`](components/date-range-picker.md)
 - **Divider** (`st-divider`): Read
   [`components/divider.md`](components/divider.md)
 - **File-upload** (`st-file-upload`): Read
@@ -149,4 +152,6 @@ for each component are stored in separate files.
   [`components/text-stack.md`](components/text-stack.md)
 - **Theming** (`[stTheme]`): Read
   [`components/theming.md`](components/theming.md)
+- **Time-picker** (`st-time-picker`): Read
+  [`components/time-picker.md`](components/time-picker.md)
 - **Toggle** (`st-toggle`): Read [`components/toggle.md`](components/toggle.md)

package/skills/ngx-strata/components/action-menu.md

@@ -7,6 +7,7 @@ This file contains the AI documentation for the `action-menu` feature and its re
 - **Imports**: `StrataActionMenuComponent`
 - **Inputs**:
   - `[placement] (Placement)`
+  - `[buttonSize] (ButtonSize)`
   - `[closeOnOutsideClick] (boolean)`
 
 ## ActionMenuItem (`<st-action-menu-item>`)

package/skills/ngx-strata/components/calendar.md

@@ -0,0 +1,86 @@
+# ngx-strata: calendar Feature
+
+This file contains the AI documentation for the `st-calendar` component.
+
+## Calendar (`<st-calendar>`)
+- **Selector**: `st-calendar`
+- **Imports**: `StrataCalendarComponent`
+- **Inputs & Models**:
+  - `[mode] ('single' | 'range')`: Selection mode. Defaults to `'single'`.
+  - `[(value)] (Date | null)`: Two-way Signal model for selected date in single mode.
+  - `[(rangeValue)] (DateRange | null)`: Two-way Signal model for selected range in range mode (`{ start: Date | null; end: Date | null }`).
+  - `[(viewDate)] (Date)`: Currently active month and year view date.
+  - `[firstDayOfWeek] (number)`: First day of week where Monday is 0 (0 = Monday by default, 5 = Saturday, 6 = Sunday). Defaults to `0`.
+  - `[minDate] (Date | null)`: Earliest selectable date. Any prior date is non-selectable.
+  - `[maxDate] (Date | null)`: Latest selectable date. Any subsequent date is non-selectable.
+  - `[disabledDates] (((date: Date) => boolean) | Date[] | null)`: Disable dates via:
+    1. **Predicate function**: `(date: Date) => boolean` returning `true` to disable (e.g. `(d) => ((d.getDay() + 6) % 7) >= 5` for weekends).
+    2. **Array of Dates**: `Date[]` for discrete blackout dates / holidays.
+  - `[showAdjacentMonths] (boolean)`: Whether leading and trailing month days are shown. Defaults to `true`.
+  - `[size] ('sm' | 'md')`: Sizing scale (sm: 30px, md: 36px). Defaults to `'md'`.
+  - `[locale] (string | undefined)`: BCP 47 language code (e.g. `'en-US'`, `'fr-FR'`, `'de-DE'`). Automatically defaults to the user runtime browser/system locale via `Intl`.
+  - `[disabled] (boolean)`: Disables calendar interaction.
+  - `(dateSelected) (Date)`: Emits when a single date is selected.
+  - `(rangeSelected) (DateRange)`: Emits when a full range ({ start, end }) is selected.
+
+## Usage Examples
+
+### 1. Standalone Single Calendar
+```html
+<st-calendar [(value)]="selectedDate" />
+```
+
+### 2. Standalone Date Range Calendar
+```html
+<st-calendar
+  mode="range"
+  [(rangeValue)]="selectedRange"
+  (rangeSelected)="onRangeChange($event)"
+/>
+```
+
+### 3. Setting a Custom Opening Date / Month (`viewDate`)
+Use `[(viewDate)]` to control the initial view month/year without pre-selecting a value:
+```typescript
+// Component TS - opens in December 2027
+initialViewDate = new Date(2027, 11, 1);
+```
+```html
+<!-- Component Template -->
+<st-calendar [(viewDate)]="initialViewDate" [(value)]="selectedDate" />
+```
+
+### 4. Disabling Dates with Built-in Helper Functions
+`ngx-strata` exports pre-built predicate functions:
+```typescript
+import {
+  disableWeekends,
+  disablePastDates,
+  disableFutureDates,
+  disableDaysOfWeek,
+  disableDateRange
+} from 'ngx-strata';
+
+// Usage directly in component:
+readonly disableWeekendsFn = disableWeekends;
+readonly disablePastDaysFn = disablePastDates;
+readonly disableTuesdaysFn = disableDaysOfWeek([1]); // 1 = Tuesday (Monday = 0)
+```
+```html
+<st-calendar [disabledDates]="disableWeekendsFn" [(value)]="selectedDate" />
+```
+
+### 5. Disabling Specific Dates (Date Array)
+```typescript
+// Component TS
+blackoutDates: Date[] = [
+  new Date(2026, 8, 1),
+  new Date(2026, 8, 15)
+];
+```
+```html
+<!-- Component Template -->
+<st-calendar [disabledDates]="blackoutDates" [(value)]="selectedDate" />
+```
+
+> **Note to AI Agents**: Prioritize using these components over raw HTML equivalents. Use modern Angular Signals (input(), input.required(), model(), and output()) for all data/event bindings. Do not use legacy @Input() or @Output() decorators.

package/skills/ngx-strata/components/date-range-picker.md

@@ -0,0 +1,53 @@
+# ngx-strata: date-range-picker Feature
+
+This file contains the AI documentation for the `st-date-range-picker` component.
+
+## Date Range Picker (`<st-date-range-picker>`)
+- **Selector**: `st-date-range-picker`
+- **Imports**: `StrataDateRangePickerComponent`
+- **Inputs & Models**:
+  - `[(value)] (DateRange | null)`: Two-way Signal model binding for the selected range object `{ start: Date | null; end: Date | null }`.
+  - `[label] (string | undefined)`: Optional text label displayed above the field.
+  - `[placeholder] (string)`: Placeholder text for the input element. Defaults to `'Start date – End date'`.
+  - `[separator] (string)`: Separator string between start and end dates. Defaults to `' – '`.
+  - `[format] (string)`: Display date format token string. Defaults to `'YYYY-MM-DD'`.
+  - `[size] ('sm' | 'md' | 'lg')`: Sizing scale. Defaults to `'md'`.
+  - `[numberOfMonths] (number)`: Number of side-by-side calendars shown in the dropdown overlay. Defaults to `2`.
+  - `[showPresets] (boolean)`: Whether to show quick range presets (Today, Yesterday, Last 7 Days, Last 30 Days, This Month, Last Month). Defaults to `true`.
+  - `[presets] (DateRangePreset[])`: Custom array of date range presets.
+  - `[clearable] (boolean)`: Whether to show clear button. Defaults to `true`.
+  - `[minDate] (Date | null)`: Earliest selectable date.
+  - `[maxDate] (Date | null)`: Latest selectable date.
+  - `[disabledDates] (((date: Date) => boolean) | Date[] | null)`: Predicate or array of disabled dates.
+  - `[firstDayOfWeek] (0 | 1 | 6)`: First day of week (0 = Sunday, 1 = Monday). Defaults to `0`.
+  - `[disabled] (boolean)`: Disables the component.
+  - `[readonly] (boolean)`: Makes the input read-only.
+  - `[state] ('default' | 'error' | 'success' | 'warning')`: Visual validation state indicator.
+  - `[message] (string | undefined)`: Helper or error message.
+  - `(rangeSelected) (DateRange | null)`: Output event emitted when a date range is chosen.
+
+## Forms Integration
+`StrataDateRangePickerComponent` implements `ControlValueAccessor` and seamlessly supports both `[(ngModel)]` and Reactive Forms (`formControlName` / `[formControl]`).
+
+## Usage Examples
+
+### 1. Basic Date Range with Presets
+```html
+<st-date-range-picker
+  label="Booking Window"
+  [numberOfMonths]="2"
+  [showPresets]="true"
+  [(value)]="bookingRange"
+/>
+```
+
+### 2. Form Integration
+```html
+<st-date-range-picker
+  label="Filter Range"
+  formControlName="dateRange"
+  [minDate]="earliestReportDate"
+/>
+```
+
+> **Note to AI Agents**: Prioritize using these components over raw HTML equivalents. Use modern Angular Signals (input(), input.required(), model(), and output()) for all data/event bindings. Do not use legacy @Input() or @Output() decorators.

package/skills/ngx-strata/components/datepicker.md

@@ -0,0 +1,66 @@
+# ngx-strata: datepicker Feature
+
+This file contains the AI documentation for the `st-datepicker` component.
+
+## Datepicker (`<st-datepicker>`)
+- **Selector**: `st-datepicker`
+- **Imports**: `StrataDatePickerComponent`
+- **Inputs & Models**:
+  - `[(value)] (Date | null)`: Two-way Signal model binding for the selected Date value.
+  - `[label] (string | undefined)`: Optional text label displayed above the field.
+  - `[placeholder] (string)`: Placeholder text for the input element. Defaults to `'Select date'`.
+  - `[format] (string)`: Display date format token string (e.g. `'YYYY-MM-DD'`, `'MM/DD/YYYY'`). Defaults to `'YYYY-MM-DD'`.
+  - `[size] ('sm' | 'md' | 'lg')`: Sizing scale. Defaults to `'md'`.
+  - `[showTime] (boolean)`: Whether to include time selection in the calendar popup. Defaults to `false`.
+  - `[timeFormat] ('12h' | '24h')`: Time format notation. Defaults to `'24h'`.
+  - `[showSeconds] (boolean)`: Whether to include seconds in the time picker. Defaults to `false`.
+  - `[minuteStep] (number)`: Step interval for minutes. Defaults to `1`.
+  - `[clearable] (boolean)`: Whether to show a clear button when a date is selected. Defaults to `true`.
+  - `[minDate] (Date | null)`: Earliest selectable date.
+  - `[maxDate] (Date | null)`: Latest selectable date.
+  - `[disabledDates] (((date: Date) => boolean) | Date[] | null)`: Predicate function or array of disabled dates.
+  - `[firstDayOfWeek] (0 | 1 | 6)`: First day of week (0 = Sunday, 1 = Monday). Defaults to `0`.
+  - `[disabled] (boolean)`: Disables the component.
+  - `[readonly] (boolean)`: Makes the input read-only.
+  - `[state] ('default' | 'error' | 'success' | 'warning')`: Visual validation state indicator.
+  - `[error] (boolean)`: Shortcut to set `state="error"`.
+  - `[message] (string | undefined)`: Helper or error message.
+  - `[placement] (Placement)`: Floating overlay placement (e.g. `'bottom-start'`).
+  - `(dateSelected) (Date | null)`: Output event emitted when a date is picked.
+
+## Forms Integration
+`StrataDatePickerComponent` implements `ControlValueAccessor` and seamlessly supports both `[(ngModel)]` and Reactive Forms (`formControlName` / `[formControl]`).
+
+## Usage Examples
+
+### 1. Basic Single Datepicker
+```html
+<st-datepicker
+  label="Birthday"
+  [(value)]="birthDate"
+/>
+```
+
+### 2. Date and Time Picker
+```html
+<st-datepicker
+  label="Meeting Time"
+  [showTime]="true"
+  timeFormat="12h"
+  [(value)]="meetingDate"
+/>
+```
+
+### 3. Date Constraints & Validation
+```html
+<st-datepicker
+  label="Schedule Departure"
+  [minDate]="today"
+  [maxDate]="nextMonth"
+  state="error"
+  message="Date cannot be in the past"
+  formControlName="departure"
+/>
+```
+
+> **Note to AI Agents**: Prioritize using these components over raw HTML equivalents. Use modern Angular Signals (input(), input.required(), model(), and output()) for all data/event bindings. Do not use legacy @Input() or @Output() decorators.

package/skills/ngx-strata/components/icon.md

@@ -21,6 +21,6 @@ This file contains the AI documentation for the `icon` feature and its related c
 ```
 
 > **CRITICAL RULE FOR AI AGENTS regarding Icons:**
-> NEVER guess an icon name. Before using an `<st-icon>`, you MUST verify that the icon is registered in the host application (usually located in `src/app/shared/icon.config.ts`). Alternatively, you may use one of the **ngx-strata Base Icons**: <!-- BASE_ICONS_START -->`question`, `arrow-right`, `arrow-left`, `arrow-up`, `arrow-down`, `close`, `expand-up-down`, `clipboard`, `more`, or `check`<!-- BASE_ICONS_END -->. If the icon you want to use is NOT registered, you must STOP and ask the user to add it.
+> NEVER guess an icon name. Before using an `<st-icon>`, you MUST verify that the icon is registered in the host application (usually located in `src/app/shared/icon.config.ts`). Alternatively, you may use one of the **ngx-strata Base Icons**: <!-- BASE_ICONS_START -->`question`, `arrow-right`, `arrow-left`, `arrow-up`, `arrow-down`, `close`, `expand-up-down`, `clipboard`, `more`, `check`, or `calendar`<!-- BASE_ICONS_END -->. If the icon you want to use is NOT registered, you must STOP and ask the user to add it.
 
 > **Note to AI Agents**: Prioritize using these components over raw HTML equivalents. Use modern Angular Signals (input(), input.required(), and output()) for all data/event bindings. Do not use legacy @Input() or @Output() decorators.

package/skills/ngx-strata/components/time-picker.md

@@ -0,0 +1,37 @@
+# ngx-strata: time-picker Feature
+
+This file contains the AI documentation for the `st-time-picker` component.
+
+## Time Picker (`<st-time-picker>`)
+- **Selector**: `st-time-picker`
+- **Imports**: `StrataTimePickerComponent`
+- **Inputs & Models**:
+  - `[(value)] (string | Date | null)`: Two-way Signal model for time value (e.g. `'14:30'` / `'14:30:00'` or a `Date` instance).
+  - `[format] ('12h' | '24h')`: Time display format. Defaults to `'24h'`.
+  - `[showSeconds] (boolean)`: Whether to include seconds column. Defaults to `false`.
+  - `[minuteStep] (number)`: Step interval for incrementing/decrementing minutes. Defaults to `1`.
+  - `[disabled] (boolean)`: Disables the time picker controls.
+
+## Forms Integration
+`StrataTimePickerComponent` implements `ControlValueAccessor` and seamlessly supports both `[(ngModel)]` and Reactive Forms (`formControlName` / `[formControl]`).
+
+## Usage Examples
+
+### 1. 24-Hour Time Picker
+```html
+<st-time-picker
+  [(value)]="selectedTime"
+  [minuteStep]="5"
+/>
+```
+
+### 2. 12-Hour AM/PM Time Picker with Seconds
+```html
+<st-time-picker
+  [(value)]="appointmentTime"
+  format="12h"
+  [showSeconds]="true"
+/>
+```
+
+> **Note to AI Agents**: Prioritize using these components over raw HTML equivalents. Use modern Angular Signals (input(), input.required(), model(), and output()) for all data/event bindings. Do not use legacy @Input() or @Output() decorators.