ngx-strata 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-strata",
-  "version": "0.3.0",
+  "version": "0.4.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

@@ -13,21 +13,30 @@ you need.
 
 ### 1. Style Setup
 
-Ensure the core Strata CSS is included in your global styles (e.g.,
-\`styles.scss\` or \`angular.json\`): \`\`\`scss @import
-'ngx-strata/strata.css'; \`\`\`
+Ensure the core Strata CSS is included in your global styles (e.g., `styles.scss` or `angular.json`):
+
+```scss
+@use 'ngx-strata/style';
+```
 
 ### 2. Provider Setup
 
-The application should be configured with Strata. Use the global provider in
-\`app.config.ts\`:
+The application should be configured with Strata. Use the global provider in `app.config.ts`:
 
-\`\`\`typescript import { provideStrata } from 'ngx-strata';
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideStrata } from 'ngx-strata';
 
-export const appConfig: ApplicationConfig = { providers: [ provideStrata({
-includeBaseIcons: true, tooltipDelayMs: 500 }) ] };
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideStrata({
+      includeBaseIcons: true,
+      tooltipDelayMs: 500
+    })
+  ]
+};
+```
 
-````
 Custom icons should be registered using the `provideIcons()` provider during bootstrap.
 
 ### 3. Application Shell
@@ -38,7 +47,7 @@ Wrap your root application component (usually `app.component.html`) in the Strat
   <!-- Main Content -->
   <router-outlet></router-outlet>
 </st-shell>
-````
+```
 
 ---
 
@@ -49,16 +58,25 @@ variables to ensure the app matches the active theme (light/dark mode).
 
 **Key Color Variables:**
 
-- `--st-color-bg-default`: Standard background.
-- `--st-color-bg-raised`: Slightly elevated background (cards, modals).
-- `--st-color-text-primary`: Standard text.
+- `--st-color-bg-default`: Standard background (default for page canvas and standard modals).
+- `--st-color-bg-raised`: Elevated background (cards, alerts, raised modals, dropdowns).
+- `--st-color-bg-subtle`: Subtle background surface.
+- `--st-color-bg-inverse`: High-contrast / inverted background (tooltips, active segments).
+- `--st-color-border-default`: Standard border.
+- `--st-color-border-subtle`: Subtle divider / inner border.
+- `--st-color-text-primary`: Primary body and heading text.
 - `--st-color-text-secondary`: Muted/secondary text.
-- `--st-color-text-tertiary`: Disabled/faded text.
-- `--st-color-accent-default`: Primary brand accent color.
+- `--st-color-text-tertiary`: Disabled/placeholder text.
+- `--st-color-text-inverse`: Inverted text on inverse surfaces.
+- `--st-color-text-on-accent`: Text on accent-colored elements.
+- `--st-color-accent-default`: Primary brand / interactive accent color.
+- `--st-color-accent-hover`: Hover state for accent actions.
+- `--st-color-control-bg`: Secondary control / button background.
+- `--st-color-control-primary-bg`: Primary control / button background.
 
-**Key Spacing Variables:**
+**Key Spacing Variables (4px base grid):**
 
-- `--st-space-1` (4px) to `--st-space-10` (40px)
+- `--st-space-1` (4px) to `--st-space-16` (64px)
 
 ---
 
@@ -75,6 +93,7 @@ for each component are stored in separate files.
   [`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)
+- **Badge** (`st-badge`): Read [`components/badge.md`](components/badge.md)
 - **Breadcrumb** (`st-breadcrumb`): Read
   [`components/breadcrumb.md`](components/breadcrumb.md)
 - **Button** (`[stButton]`): Read [`components/button.md`](components/button.md)
@@ -83,14 +102,18 @@ for each component are stored in separate files.
   [`components/checkbox.md`](components/checkbox.md)
 - **Divider** (`st-divider`): Read
   [`components/divider.md`](components/divider.md)
+- **File-upload** (`st-file-upload`): Read
+  [`components/file-upload.md`](components/file-upload.md)
 - **Icon** (`st-icon`): Read [`components/icon.md`](components/icon.md)
+- **Image-cropper** (`st-image-cropper`): Read
+  [`components/image-cropper.md`](components/image-cropper.md)
 - **Input-field** (`[stAutoResize]`): Read
   [`components/input-field.md`](components/input-field.md)
 - **Item** (`st-item`): Read [`components/item.md`](components/item.md)
 - **Kbd** (`st-kbd`): Read [`components/kbd.md`](components/kbd.md)
 - **Message-state** (`st-message-state`): Read
   [`components/message-state.md`](components/message-state.md)
-- **Modal** (`st-alert-content`): Read
+- **Modal** (`ModalService`, `st-modal-footer`): Read
   [`components/modal.md`](components/modal.md)
 - **Notification** (`st-notification`): Read
   [`components/notification.md`](components/notification.md)
@@ -98,6 +121,7 @@ for each component are stored in separate files.
   [`components/number-display.md`](components/number-display.md)
 - **Overlay** (`[stOverlay]`): Read
   [`components/overlay.md`](components/overlay.md)
+- **Otp** (`st-otp`): Read [`components/otp.md`](components/otp.md)
 - **Pagination** (`st-pagination`): Read
   [`components/pagination.md`](components/pagination.md)
 - **Progress** (`st-progress-linear`): Read
@@ -113,6 +137,7 @@ for each component are stored in separate files.
 - **Slider** (`st-slider`): Read [`components/slider.md`](components/slider.md)
 - **Spinner** (`st-spinner`): Read
   [`components/spinner.md`](components/spinner.md)
+- **Stepper** (`st-stepper`): Read [`components/stepper.md`](components/stepper.md)
 - **Tabs** (`st-tab-item`): Read [`components/tabs.md`](components/tabs.md)
 - **Tag** (`st-tag`): Read [`components/tag.md`](components/tag.md)
 - **Testing** (`ngx-strata/testing`): Read [`components/testing.md`](components/testing.md)

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

@@ -6,22 +6,24 @@ This file contains the AI documentation for the `accordion` feature and its rela
 - **Selector**: `st-accordion-group`
 - **Imports**: `StrataAccordionGroupComponent`
 - **Inputs**:
-  - `[allowMultipleOpen] (boolean)`
+  - `[allowMultipleOpen] (boolean)`: Whether multiple accordion items can be open simultaneously. Defaults to `false`.
 
 ## AccordionItem (`<st-accordion-item>`)
 - **Selector**: `st-accordion-item`
 - **Imports**: `StrataAccordionItemComponent`
-- **Inputs**:
-  - `[title] (string)`
+- **Inputs / Models**:
+  - `[title] (string, required)`: Header title for the item.
+  - `[(open)] (model<boolean>)`: Two-way state for whether the accordion is expanded. Defaults to `false`.
 - **Outputs**:
-  - `(toggled)`
+  - `(toggled) (boolean)`: Emitted when expansion state changes.
+- **Accessibility**: Header uses an accessible native `<button type="button">` with `aria-expanded` and `aria-controls`. Content container has `role="region"` and `aria-labelledby`. Keyboard interaction (`Enter`, `Space`) is supported natively.
 
 ## Usage Example
 
 ```html
-<!-- Single Accordion -->
-<st-accordion-item title="Single accordion">
-  <p>With some excellent content to be revealed</p>
+<!-- Single Accordion with two-way open binding -->
+<st-accordion-item title="Details" [(open)]="isOpen">
+  <p>Expanded details content.</p>
 </st-accordion-item>
 
 <!-- Accordion Group -->

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

@@ -6,27 +6,39 @@ This file contains the AI documentation for the `avatar` feature and its related
 - **Selector**: `st-avatar`
 - **Imports**: `StrataAvatarComponent`
 - **Inputs**:
-  - `[text] (string | null)`
+  - `[src] (string | null)`: Image URL to display. If loading fails, automatically falls back to `text` initials.
+  - `[alt] (string)`: Accessible alt description for the image.
+  - `[text] (string | null)`: Initials or text fallback.
+  - `[size] (model<AvatarSize>)`: `'xs' | 'sm' | 'md' | 'lg'`. Defaults to `'md'`.
+  - `[stTheme] (Theme)`: Optional theme variant (`brand`, `success`, `info`, `warning`, `danger`).
 
 ## AvatarStack (`<st-avatar-stack>`)
 - **Selector**: `st-avatar-stack`
 - **Imports**: `StrataAvatarStackComponent`
 - **Inputs**:
-  - `[size] (AvatarSize)`
-  - `[spacing] ('loose' | 'mid' | 'tight')`
-  - `[firstOnFront] (boolean)`
+  - `[size] (AvatarSize)`: `'xs' | 'sm' | 'md' | 'lg'`. Defaults to `'md'`.
+  - `[spacing] ('loose' | 'mid' | 'tight')`: Defaults to `'mid'`.
+  - `[firstOnFront] (boolean)`: When true, stacks earlier avatars on top. Defaults to `false`.
 
-## Usage Example
+## Usage Examples
 
 ```html
-<!-- Single Avatar -->
-<st-avatar text="John Doe"></st-avatar>
+<!-- Direct Image with Alt and Fallback Text -->
+<st-avatar [src]="user.avatarUrl" [alt]="user.name" [text]="user.initials"></st-avatar>
+
+<!-- Text Initials Only -->
+<st-avatar text="JD" size="md" stTheme="brand"></st-avatar>
+
+<!-- Projected Icon Avatar -->
+<st-avatar size="sm">
+  <st-icon name="question"></st-icon>
+</st-avatar>
 
 <!-- Avatar Stack -->
 <st-avatar-stack size="md" spacing="mid" [firstOnFront]="true">
-  <st-avatar text="John Doe"></st-avatar>
-  <st-avatar text="Jane Smith"></st-avatar>
-  <st-avatar text="Bob Ross"></st-avatar>
+  <st-avatar [src]="avatar1" alt="User 1" text="U1"></st-avatar>
+  <st-avatar [src]="avatar2" alt="User 2" text="U2"></st-avatar>
+  <st-avatar text="+3"></st-avatar>
 </st-avatar-stack>
 ```
 

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

@@ -0,0 +1,54 @@
+# ngx-strata: badge Feature
+
+This file contains the AI documentation for the `badge` feature and its related components.
+
+## Badge (`<st-badge>`)
+- **Selector**: `st-badge`
+- **Imports**: `StrataBadgeComponent`
+- **Inputs**:
+  - `[value] (string | number | undefined)`: Value displayed in badge. When undefined and no icon is passed, badge renders as a dot indicator.
+  - `[variant] (BadgeVariant)`: `'accent' | 'neutral' | 'success' | 'warning' | 'error' | 'info'` (default `'accent'`)
+  - `[size] (BadgeSize)`: `'xs' | 'sm' | 'md'` (default `'md'`). Note: `'xs'` (8px) exclusively supports status dots.
+  - `[placement] (BadgePlacement)`: `'inline' | 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'` (default `'inline'`)
+  - `[max] (number)`: Max numeric count before displaying `{max}+` (default `99`)
+  - `[showZero] (boolean)`: Whether to render when `value === 0` (default `false`)
+  - `[icon] (string | undefined)`: Icon name rendered via `<st-icon [name]="icon()">`. Renders as a circular badge when no text value is set.
+  - `[ariaLabel] (string | undefined)`: Accessible label for assistive tech
+
+## Usage Examples
+
+### Numeric Counter
+```html
+<st-badge [value]="5"></st-badge>
+<st-badge [value]="120" [max]="99" variant="error"></st-badge>
+```
+
+### Status Dot
+```html
+<st-badge variant="success"></st-badge>
+<st-badge variant="warning"></st-badge>
+```
+
+### Text Label
+```html
+<st-badge value="NEW" variant="accent"></st-badge>
+```
+
+### Icon Badge
+```html
+<st-badge icon="star" variant="warning"></st-badge>
+```
+
+### Anchored to Buttons or Avatars
+```html
+<button stButton variant="secondary">
+  Notifications
+  <st-badge placement="top-right" [value]="3" variant="error"></st-badge>
+</button>
+
+<st-avatar text="AM">
+  <st-badge placement="bottom-right" variant="success"></st-badge>
+</st-avatar>
+```
+
+> **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/checkbox.md

@@ -5,13 +5,21 @@ This file contains the AI documentation for the `checkbox` feature and its relat
 ## Checkbox (`<st-checkbox>`)
 - **Selector**: `st-checkbox`
 - **Imports**: `StrataCheckboxComponent`
-- **Inputs**:
-  - `[(value)] (boolean | undefined)`
-  - `[label] (string | undefined)`
-  - `[name] (string | undefined)`
+- **Inputs & Models**:
+  - `[(value)] (model<boolean>)`: Whether the checkbox is checked (default `false`).
+  - `[label] (string | undefined)`: Label text displayed next to the checkbox.
+  - `[name] (string | undefined)`: Form field name.
+  - `[disabled] (boolean)`: Disables user interaction.
+  - `[id] (string | undefined)`: Optional custom HTML id; an accessible unique id is auto-generated if omitted.
+- **Outputs**:
+  - `(valueChange)`: Emitted whenever the checked state changes.
 
-## Usage Example
+## Form Integration
+Implements `ControlValueAccessor` (CVA). Compatible with Reactive Forms (`formControlName`, `[formControl]`) and template-driven forms (`[(ngModel)]`).
 
+## Usage Examples
+
+### 1. Basic Two-Way Binding
 ```html
 <st-checkbox 
   label="I agree to the terms and conditions" 
@@ -20,5 +28,22 @@ This file contains the AI documentation for the `checkbox` feature and its relat
 </st-checkbox>
 ```
 
+### 2. Reactive Forms Integration
+```html
+<st-checkbox 
+  label="Subscribe to newsletter" 
+  [formControl]="newsletterControl">
+</st-checkbox>
+```
+
+### 3. Disabled State
+```html
+<st-checkbox 
+  label="Option unavailable" 
+  [disabled]="true"
+  [value]="false">
+</st-checkbox>
+```
 
 > **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/file-upload.md

@@ -0,0 +1,50 @@
+# File Upload (`st-file-upload`)
+
+The File Upload component provides a stylish, accessible dropzone for selecting files via file browser or drag-and-drop.
+
+## Usage
+
+```html
+<st-file-upload
+  accept="image/*"
+  hint="PNG, JPG or WEBP up to 5MB"
+  (fileSelect)="onFileSelected($event)"
+></st-file-upload>
+```
+
+### Multiple Files
+
+```html
+<st-file-upload
+  [multiple]="true"
+  accept=".pdf,.docx,.txt"
+  label="Upload documents"
+  (filesSelect)="onFilesSelected($event)"
+></st-file-upload>
+```
+
+## API
+
+### Inputs
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `accept` | `input<string>` | `'*'` | Accepted MIME types or file extensions |
+| `multiple` | `input<boolean>` | `false` | Whether multiple files can be selected |
+| `maxFileSize` | `input<number \| undefined>` | `undefined` | Maximum allowed file size in bytes |
+| `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 |
+
+### Outputs
+
+| Output | Type | Description |
+|---|---|---|
+| `fileSelect` | `output<File>` | Emitted when a single valid file is selected |
+| `filesSelect` | `output<File[]>` | Emitted when valid files are selected |
+| `fileRejected` | `output<{ file: File; reason: 'type' \| 'size' }>` | Emitted when a file fails validation |
+
+### Methods
+
+- `browse()`: Opens the system file selection dialog.
+- `clear()`: Clears the native input value.

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

@@ -6,16 +6,21 @@ This file contains the AI documentation for the `icon` feature and its related c
 - **Selector**: `st-icon`
 - **Imports**: `StrataIconComponent`
 - **Inputs**:
-  - `[name] (string)`
+  - `[name] (string)`: Name of the registered icon. Defaults to `'question'`.
+  - `[size] (model<IconSize>)`: `'xs' | 'sm' | 'md' | 'lg'`. Defaults to `'md'`.
+  - `[ariaLabel] (string | undefined)`: Optional accessible label. When omitted, `st-icon` automatically applies `aria-hidden="true"` so decorative icons are ignored by screen readers. When provided, sets `role="img"` and `aria-label`.
 
-## Usage Example
+## Usage Examples
 
-\`\`\`html
-<st-icon name="search" size="md"></st-icon>
-<st-icon name="info" size="lg"></st-icon>
-\`\`\`
+```html
+<!-- Decorative icon (default: aria-hidden="true") -->
+<st-icon name="close" size="sm"></st-icon>
+
+<!-- Semantic icon with accessible label -->
+<st-icon name="info" size="md" ariaLabel="Information notice"></st-icon>
+```
 
 > **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`, or `more`<!-- 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`, 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.
 
 > **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/image-cropper.md

@@ -0,0 +1,83 @@
+# Image Cropper (`st-image-cropper`)
+
+The Image Cropper component provides an interactive workspace for cropping images to circle (avatar) or square masks with pan, zoom, and rotation controls.
+
+## Usage
+
+### Standalone with Image URL
+
+```html
+<st-image-cropper
+  [image]="userPhotoUrl"
+  shape="circle"
+  [maskSize]="240"
+  (crop)="onCropped($event)"
+></st-image-cropper>
+```
+
+### Combined with Projected `st-file-upload`
+
+```html
+<st-image-cropper #cropper shape="circle" (crop)="onCropped($event)">
+  <st-file-upload
+    accept="image/*"
+    hint="Choose a profile photo"
+    (fileSelect)="cropper.setImage($event)"
+  ></st-file-upload>
+</st-image-cropper>
+```
+
+## CropResult Interface
+
+```typescript
+export interface CropResult {
+  blob: Blob;
+  dataUrl: string;
+  file?: File;
+  width: number;
+  height: number;
+}
+```
+
+## API
+
+### Inputs & Models
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `image` | `input<string \| File \| Blob \| null>` | `null` | Image source to crop |
+| `shape` | `input<'circle' \| 'square'>` | `'circle'` | Crop mask shape and canvas clip |
+| `maskSize` | `input<number>` | `240` | Viewport mask size in pixels |
+| `outputWidth` | `input<number>` | `400` | Width of output canvas |
+| `outputHeight` | `input<number>` | `400` | Height of output canvas |
+| `outputFormat` | `input<'image/png' \| 'image/jpeg' \| 'image/webp'>` | `'image/png'` | Export format |
+| `outputQuality` | `input<number>` | `0.92` | Quality for lossy formats |
+| `zoom` | `model<number>` | `1` | Two-way bound zoom multiplier |
+| `rotation` | `model<number>` | `0` | Two-way bound rotation degrees |
+| `minZoom` | `input<number>` | `1` | Minimum zoom |
+| `maxZoom` | `input<number>` | `3` | Maximum zoom |
+| `showZoom` | `input<boolean>` | `true` | Show zoom slider controls |
+| `showRotate` | `input<boolean>` | `true` | Show rotate 90° buttons |
+| `showClear` | `input<boolean>` | `true` | Show clear/remove button |
+| `clearLabel` | `input<string>` | `'Remove'` | Button label text for clear action |
+| `autoCrop` | `input<boolean>` | `true` | Automatically emit crop output on changes |
+| `disabled` | `input<boolean>` | `false` | Disable interactions |
+
+### Outputs
+
+| Output | Type | Description |
+|---|---|---|
+| `crop` | `output<CropResult>` | Emitted with cropped blob and dataUrl |
+| `imageLoaded` | `output<{ width: number; height: number; src: string }>` | Emitted when image loads |
+| `imageError` | `output<string>` | Emitted on image load failure |
+| `imageCleared` | `output<void>` | Emitted when image is cleared |
+
+### Methods
+
+- `cropImage(): Promise<CropResult>`: Generates canvas output and resolves with CropResult.
+- `setImage(source: string | File | Blob | null)`: Programmatically sets the image source.
+- `rotateRight()`: Rotates image 90° clockwise.
+- `rotateLeft()`: Rotates image 90° counter-clockwise.
+- `center()`: Realigns pan to center (0, 0) without resetting zoom or rotation.
+- `reset()`: Resets pan, zoom, and rotation.
+- `clear()`: Clears the loaded image.