ngx-strata 0.5.2 → 0.6.1

package/package.json

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

package/skills/ngx-strata/SKILL.md

@@ -89,7 +89,7 @@ for each component are stored in separate files.
 
 - **Accordion** (`st-accordion-group`): Read
   [`components/accordion.md`](components/accordion.md)
-- **Action-menu** (`st-action-menu`): Read
+- **Action-menu** (`st-action-menu`, `[stContextMenu]`): Read
   [`components/action-menu.md`](components/action-menu.md)
 - **Alert** (`st-alert`): Read [`components/alert.md`](components/alert.md)
 - **Avatar** (`st-avatar`): Read [`components/avatar.md`](components/avatar.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,8 @@ 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)
+- **Timepicker** (`st-timepicker`): Read
+  [`components/timepicker.md`](components/timepicker.md)
+- **Time-stepper** (`st-time-stepper`): Read
+  [`components/time-stepper.md`](components/time-stepper.md)
 - **Toggle** (`st-toggle`): Read [`components/toggle.md`](components/toggle.md)

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

@@ -6,8 +6,15 @@ This file contains the AI documentation for the `action-menu` feature and its re
 - **Selector**: `st-action-menu`
 - **Imports**: `StrataActionMenuComponent`
 - **Inputs**:
-  - `[placement] (Placement)`
-  - `[closeOnOutsideClick] (boolean)`
+  - `[placement] (Placement)`: Defaults to `'bottom-end'`.
+  - `[buttonSize] (ButtonSize)`: Defaults to `'md'`.
+  - `[closeOnOutsideClick] (boolean)`: Defaults to `true`.
+  - `[trigger] (boolean)`: Defaults to `true`. When `false`, the button trigger is not rendered (useful for context-only menus).
+- **Methods**:
+  - `open()`: Opens the action menu.
+  - `close()`: Closes the action menu.
+  - `toggle()`: Toggles the action menu state.
+  - `openAt(position: { x: number; y: number } | MouseEvent | PointerEvent, placement?: Placement)`: Opens the menu at mouse/virtual element coordinates.
 
 ## ActionMenuItem (`<st-action-menu-item>`)
 - **Selector**: `st-action-menu-item`
@@ -18,6 +25,16 @@ This file contains the AI documentation for the `action-menu` feature and its re
 - **Outputs**:
   - `(menuItemClicked)`
 
+## ContextMenu Directive (`[stContextMenu]`)
+- **Selector**: `[stContextMenu]`
+- **Imports**: `StrataContextMenuDirective`
+- **Inputs**:
+  - `[stContextMenu] (StrataActionMenuComponent)`: The target action menu to open on right-click.
+  - `[stContextMenuDisabled] (boolean)`: Disables context menu behavior (allows native browser context menu).
+  - `[stContextMenuPlacement] (Placement)`: Placement of menu relative to cursor (defaults to `'bottom-start'`).
+- **Outputs**:
+  - `(contextMenuOpened)`: Emitted with `MouseEvent` when the context menu opens.
+
 ## Usage Example
 
 ```html
@@ -41,6 +58,22 @@ This file contains the AI documentation for the `action-menu` feature and its re
     Export
   </st-action-menu-item>
 </st-action-menu>
+
+<!-- Context Menu Trigger on Element -->
+<div [stContextMenu]="contextMenu" class="right-click-zone">
+  Right-click here to view actions
+</div>
+
+<st-action-menu #contextMenu [trigger]="false">
+  <st-action-menu-item (menuItemClicked)="copy()">
+    <st-icon name="copy" area="start"></st-icon>
+    Copy
+  </st-action-menu-item>
+  <st-action-menu-item (menuItemClicked)="delete()">
+    <st-icon name="trash" area="start"></st-icon>
+    Delete
+  </st-action-menu-item>
+</st-action-menu>
 ```
 
 

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/file-upload.md

@@ -39,6 +39,9 @@ The File Upload component provides a stylish, accessible dropzone for selecting
 | `disabled` | `input<boolean>` | `false` | Disable interactions |
 | `label` | `input<string>` | `'Choose a file or drag & drop it here'` | Primary prompt text |
 | `hint` | `input<string \| undefined>` | `undefined` | Secondary help text |
+| `camera` | `input<boolean \| undefined>` | `undefined` | Tri-state flag: `undefined` auto-enables camera button for image uploads, `false` disables it, `true` forces it |
+| `choosePhotoLabel` | `input<string>` | `'Choose Photo'` | Accessible text label for the gallery/browse button |
+| `takePhotoLabel` | `input<string>` | `'Take Photo'` | Accessible text label for the camera button |
 
 ### Outputs
 
@@ -50,5 +53,6 @@ The File Upload component provides a stylish, accessible dropzone for selecting
 
 ### Methods
 
-- `browse()`: Opens the system file selection dialog.
+- `browse(event?: Event)`: Opens the system file selection dialog.
+- `browseCamera(event?: Event)`: Opens the native camera directly via `capture="environment"`.
 - `clear()`: Clears the native input value.

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`, `calendar`, `clock`, `upload`, `camera`, or `image`<!-- 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-stepper.md

@@ -0,0 +1,46 @@
+# ngx-strata: time-stepper Feature
+
+This file contains the AI documentation for the `st-time-stepper` inline component.
+
+## Time Stepper Component (`<st-time-stepper>`)
+The embedded/inline column stepper widget for selecting hours, minutes, and seconds. Ideal for embedding directly into cards, modals, or custom layouts.
+
+- **Selector**: `st-time-stepper`
+- **Imports**: `StrataTimeStepperComponent`
+- **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 notation format. Defaults to `'24h'`.
+  - `[showSeconds] (boolean)`: Whether seconds column is visible. Defaults to `false`.
+  - `[minuteStep] (number)`: Step interval for incrementing/decrementing minutes. Defaults to `1`.
+  - `[disabled] (boolean)`: Disables the time stepper controls.
+
+## Forms Integration
+`StrataTimeStepperComponent` implements `ControlValueAccessor` and seamlessly supports both `[(ngModel)]` and Reactive Forms (`formControlName` / `[formControl]`).
+
+## Usage Examples
+
+### 1. 24-Hour Time Stepper
+```html
+<st-time-stepper
+  [(value)]="selectedTime"
+  [minuteStep]="5"
+/>
+```
+
+### 2. Embedded in a Card
+```html
+<st-card>
+  <st-time-stepper [(value)]="alarmTime" />
+</st-card>
+```
+
+### 3. 12-Hour Format with Seconds
+```html
+<st-time-stepper
+  [(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.

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

@@ -0,0 +1,60 @@
+# ngx-strata: timepicker Feature
+
+This file contains the AI documentation for the `st-timepicker` form control component.
+
+## Time Picker Form Control (`<st-timepicker>`)
+A standalone form input component equipped with an input box, clock trigger icon, and dropdown overlay hosting the time selection controls.
+
+- **Selector**: `st-timepicker`
+- **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).
+  - `[label] (string | undefined)`: Label text rendered above the input.
+  - `[placeholder] (string)`: Input placeholder text. Defaults to `'Select time'`.
+  - `[format] ('12h' | '24h')`: Display format and parsing mode. Defaults to `'24h'`.
+  - `[size] ('sm' | 'md' | 'lg')`: Visual control size. Defaults to `'md'`.
+  - `[showSeconds] (boolean)`: Whether to include seconds in display and dropdown. Defaults to `false`.
+  - `[minuteStep] (number)`: Step interval for minutes. Defaults to `1`.
+  - `[clearable] (boolean)`: Shows clear button when a value is selected. Defaults to `true`.
+  - `[disabled] (boolean)`: Disables the form control. Defaults to `false`.
+  - `[readonly] (boolean)`: Read-only mode. Defaults to `false`.
+  - `[fullWidth] (boolean)`: Expands control to full container width. Defaults to `false`.
+  - `[state] ('default' | 'error' | 'success' | 'warning')`: Feedback validation state.
+  - `[message] (string | undefined)`: Helper/validation message below the input.
+  - `(timeSelected)`: Emitted when time value changes.
+
+## Forms Integration
+`StrataTimepickerComponent` implements `ControlValueAccessor` and seamlessly supports both `[(ngModel)]` and Reactive Forms (`formControlName` / `[formControl]`).
+
+## Usage Examples
+
+### 1. Basic 24-Hour Timepicker
+```html
+<st-timepicker
+  label="Departure Time"
+  placeholder="Select departure time"
+  [(value)]="departureTime"
+/>
+```
+
+### 2. 12-Hour AM/PM Timepicker with Seconds
+```html
+<st-timepicker
+  label="Appointment Time"
+  [(value)]="appointmentTime"
+  format="12h"
+  [showSeconds]="true"
+/>
+```
+
+### 3. Step Intervals and Size
+```html
+<st-timepicker
+  size="sm"
+  label="Meeting Slot"
+  [minuteStep]="15"
+  [(value)]="meetingSlot"
+/>
+```
+
+> **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.