ngx-strata 0.2.0 → 0.2.2

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "ngx-strata",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A simple UI framework for quickly prototyping angular applications with a bit of flair.",
   "license": "MIT",
   "peerDependencies": {
-    "@angular/common": "^21.2.0",
-    "@angular/core": "^21.2.0",
+    "@angular/common": ">=22.0.0",
+    "@angular/core": ">=22.0.0",
     "@floating-ui/dom": "^1.1.0"
   },
   "dependencies": {
@@ -31,5 +31,6 @@
     }
   },
   "module": "fesm2022/ngx-strata.mjs",
-  "typings": "types/ngx-strata.d.ts"
+  "typings": "types/ngx-strata.d.ts",
+  "type": "module"
 }

package/skills/ngx-strata/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: ngx-strata
+description: "Instructions for using the ngx-strata UI component library"
+---
+
+# ngx-strata Component Manual (Index)
+
+You are working in a project that uses **ngx-strata**, a modern Angular UI component library. Use this index to locate the specific component documentation you need.
+
+## Global Setup
+
+### 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';
+\`\`\`
+
+### 2. Provider Setup
+The application should be configured with Strata. Use the global provider in \`app.config.ts\`:
+
+\`\`\`typescript
+import { provideStrata } from 'ngx-strata';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideStrata({
+      includeBaseIcons: true,
+      tooltipDelayMs: 500
+    })
+  ]
+};
+```
+Custom icons should be registered using the `provideIcons()` provider during bootstrap.
+
+### 3. Application Shell
+Wrap your root application component (usually `app.component.html`) in the Strata Shell to ensure correct layout and overlay positioning. The `st-shell` automatically includes the notification and modal containers, so you do not need to add them manually.
+
+```html
+<st-shell>
+  <!-- Optional Sidebar -->
+  <st-sidemenu slot="sidebar">...</st-sidemenu>
+  
+  <!-- Main Content -->
+  <div slot="content">
+    <router-outlet></router-outlet>
+  </div>
+</st-shell>
+```
+
+---
+
+## Theming & Variables
+
+Do not hardcode colors or spacing values. Always use the built-in Strata CSS 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-text-secondary`: Muted/secondary text.
+- `--st-color-text-tertiary`: Disabled/faded text.
+- `--st-color-accent-default`: Primary brand accent color.
+
+**Key Spacing Variables:**
+- `--st-space-1` (4px) to `--st-space-10` (40px)
+
+---
+
+## Component Index
+
+To save tokens and context window space, the detailed API and usage instructions for each component are stored in separate files.
+
+**Before using a component, read its dedicated file:**
+
+- **Accordion** (`st-accordion-group`): Read [`components/accordion.md`](components/accordion.md)
+- **Action-menu** (`st-action-menu`): 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)
+- **Breadcrumb** (`st-breadcrumb`): Read [`components/breadcrumb.md`](components/breadcrumb.md)
+- **Button** (`[stButton]`): Read [`components/button.md`](components/button.md)
+- **Card** (`st-card`): Read [`components/card.md`](components/card.md)
+- **Checkbox** (`st-checkbox`): Read [`components/checkbox.md`](components/checkbox.md)
+- **Divider** (`st-divider`): Read [`components/divider.md`](components/divider.md)
+- **Icon** (`st-icon`): Read [`components/icon.md`](components/icon.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 [`components/modal.md`](components/modal.md)
+- **Notification** (`st-notification`): Read [`components/notification.md`](components/notification.md)
+- **Number-display** (`st-number-display`): Read [`components/number-display.md`](components/number-display.md)
+- **Overlay** (`[stOverlay]`): Read [`components/overlay.md`](components/overlay.md)
+- **Pagination** (`st-pagination`): Read [`components/pagination.md`](components/pagination.md)
+- **Progress** (`st-progress-linear`): Read [`components/progress.md`](components/progress.md)
+- **Radio** (`st-radio`): Read [`components/radio.md`](components/radio.md)
+- **Segmented-control** (`st-segmented-control`): Read [`components/segmented-control.md`](components/segmented-control.md)
+- **Shell** (`st-shell`): Read [`components/shell.md`](components/shell.md)
+- **Sidemenu** (`[stSidemenuItem]`): Read [`components/sidemenu.md`](components/sidemenu.md)
+- **Single-select** (`[stSelectTrigger]`): Read [`components/single-select.md`](components/single-select.md)
+- **Slider** (`st-slider`): Read [`components/slider.md`](components/slider.md)
+- **Spinner** (`st-spinner`): Read [`components/spinner.md`](components/spinner.md)
+- **Tabs** (`st-tab-item`): Read [`components/tabs.md`](components/tabs.md)
+- **Tag** (`st-tag`): Read [`components/tag.md`](components/tag.md)
+- **Text-stack** (`st-text-stack`): Read [`components/text-stack.md`](components/text-stack.md)
+- **Theming** (`[stTheme]`): Read [`components/theming.md`](components/theming.md)
+- **Toggle** (`st-toggle`): Read [`components/toggle.md`](components/toggle.md)

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

@@ -0,0 +1,38 @@
+# ngx-strata: accordion Feature
+
+This file contains the AI documentation for the `accordion` feature and its related components.
+
+## AccordionGroup (`<st-accordion-group>`)
+- **Selector**: `st-accordion-group`
+- **Imports**: `StrataAccordionGroupComponent`
+- **Inputs**:
+  - `[allowMultipleOpen] (boolean)`
+
+## AccordionItem (`<st-accordion-item>`)
+- **Selector**: `st-accordion-item`
+- **Imports**: `StrataAccordionItemComponent`
+- **Inputs**:
+  - `[title] (string)`
+- **Outputs**:
+  - `(toggled)`
+
+## Usage Example
+
+```html
+<!-- Single Accordion -->
+<st-accordion-item title="Single accordion">
+  <p>With some excellent content to be revealed</p>
+</st-accordion-item>
+
+<!-- Accordion Group -->
+<st-accordion-group [allowMultipleOpen]="false">
+  <st-accordion-item title="Section 1">
+    <p>Content for section 1</p>
+  </st-accordion-item>
+  <st-accordion-item title="Section 2">
+    <p>Content for section 2</p>
+  </st-accordion-item>
+</st-accordion-group>
+```
+
+> **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/action-menu.md

@@ -0,0 +1,36 @@
+# ngx-strata: action-menu Feature
+
+This file contains the AI documentation for the `action-menu` feature and its related components.
+
+## ActionMenu (`<st-action-menu>`)
+- **Selector**: `st-action-menu`
+- **Imports**: `StrataActionMenuComponent`
+- **Inputs**:
+  - `[placement] (Placement)`
+
+## ActionMenuItem (`<st-action-menu-item>`)
+- **Selector**: `st-action-menu-item`
+- **Imports**: `StrataActionMenuItemComponent`
+- **Inputs**:
+  - `[closeMenuOnClick] (any)`
+  - `[active] (any)`
+- **Outputs**:
+  - `(menuItemClicked)`
+
+## Usage Example
+
+```html
+<!-- Default Icon Trigger -->
+<st-action-menu>
+  <st-action-menu-item label="Edit" iconName="edit" (menuItemClicked)="edit()"></st-action-menu-item>
+  <st-action-menu-item label="Delete" iconName="trash" (menuItemClicked)="delete()"></st-action-menu-item>
+</st-action-menu>
+
+<!-- Custom Button Trigger -->
+<st-action-menu>
+  <button stButton variant="primary" trigger>Options</button>
+  <st-action-menu-item label="Export" iconName="download" (menuItemClicked)="export()"></st-action-menu-item>
+</st-action-menu>
+```
+
+> **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/alert.md

@@ -0,0 +1,28 @@
+# ngx-strata: alert Feature
+
+This file contains the AI documentation for the `alert` feature and its related components.
+
+## Alert (`<st-alert>`)
+- **Selector**: `st-alert`
+- **Imports**: `StrataAlertComponent`
+- **Inputs**:
+  - `[header] (string | undefined)`
+  - `[message] (string)`
+  - `[iconName] (string | undefined)`
+  - `[dismissible] (boolean)`
+- **Outputs**:
+  - `(dismiss)`
+
+## Usage Example
+
+```html
+<st-alert 
+  header="Update Successful" 
+  message="Your settings have been saved."
+  iconName="check_circle"
+  [dismissible]="true"
+  (dismiss)="hideAlert()">
+</st-alert>
+```
+
+> **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/avatar.md

@@ -0,0 +1,33 @@
+# ngx-strata: avatar Feature
+
+This file contains the AI documentation for the `avatar` feature and its related components.
+
+## Avatar (`<st-avatar>`)
+- **Selector**: `st-avatar`
+- **Imports**: `StrataAvatarComponent`
+- **Inputs**:
+  - `[text] (string | null)`
+
+## AvatarStack (`<st-avatar-stack>`)
+- **Selector**: `st-avatar-stack`
+- **Imports**: `StrataAvatarStackComponent`
+- **Inputs**:
+  - `[size] (AvatarSize)`
+  - `[spacing] ('loose' | 'mid' | 'tight')`
+  - `[firstOnFront] (boolean)`
+
+## Usage Example
+
+```html
+<!-- Single Avatar -->
+<st-avatar text="John Doe"></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-stack>
+```
+
+> **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/breadcrumb.md

@@ -0,0 +1,32 @@
+# ngx-strata: breadcrumb Feature
+
+This file contains the AI documentation for the `breadcrumb` feature and its related components.
+
+## Breadcrumb (`<st-breadcrumb>`)
+- **Selector**: `st-breadcrumb`
+- **Imports**: `StrataBreadcrumbComponent`
+- **Inputs**:
+  - `[separatorIcon] (string)`
+
+## BreadcrumbItem (`<st-breadcrumb-item>`)
+- **Selector**: `st-breadcrumb-item`
+- **Imports**: `StrataBreadcrumbItemComponent`
+- **Inputs**:
+  - `[text] (string)`
+  - `[icon] (string)`
+  - `[interactable] (boolean)`
+  - `[disabled] (boolean)`
+- **Outputs**:
+  - `(activated)`
+
+## Usage Example
+
+```html
+<st-breadcrumb separatorIcon="chevron_right">
+  <st-breadcrumb-item text="Home" icon="home" (activated)="goHome()"></st-breadcrumb-item>
+  <st-breadcrumb-item text="Settings" (activated)="goSettings()"></st-breadcrumb-item>
+  <st-breadcrumb-item text="Profile" [disabled]="true"></st-breadcrumb-item>
+</st-breadcrumb>
+```
+
+> **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/button.md

@@ -0,0 +1,34 @@
+# ngx-strata: button Feature
+
+This file contains the AI documentation for the `button` feature and its related components.
+
+## Button (`[stButton]`)
+- **Selector**: `[stButton]`
+- **Imports**: `StrataButtonDirective`
+- **Inputs**:
+  - `[variant] (ButtonVariant)`
+  - `[size] (ButtonSize)`
+  - `[fullWidth] (boolean)`
+
+## ButtonGroup (`<st-button-group>`)
+- **Selector**: `st-button-group`
+- **Imports**: `StrataButtonGroupComponent`
+- **Inputs**:
+  - `[justification] (ButtonGroupJustification)`
+
+## Usage Example
+
+```html
+<button stButton variant="primary" size="md">Save</button>
+<button stButton variant="secondary" size="sm">Cancel</button>
+<button stButton variant="ghost" size="lg">Help</button>
+<button stButton variant="danger" size="md">Delete</button>
+
+<!-- Button Group -->
+<st-button-group justification="center">
+  <button stButton variant="secondary">Cancel</button>
+  <button stButton variant="primary">Confirm</button>
+</st-button-group>
+```
+
+> **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/card.md

@@ -0,0 +1,30 @@
+# ngx-strata: card Feature
+
+This file contains the AI documentation for the `card` feature and its related components.
+
+## Card (`<st-card>`)
+- **Selector**: `st-card`
+- **Imports**: `StrataCardComponent`
+- **Inputs**:
+  - `[elevated] (boolean)`
+  - `[selectable] (boolean)`
+  - `[padding] (boolean)`
+  - `[variant] (CardVariant)`
+
+> **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.
+
+## CSS Custom Properties
+Every component exposes internal CSS custom properties for visual styling overrides:
+- `--st-card-shadow`: Box-shadow of the elevated card (defaults to `var(--st-shadow-1)`).
+- `--st-card-padding`: Inner padding of the card (defaults to `var(--st-size-xs)`).
+- `--st-card-background-color`: Background color of the card (defaults to `var(--st-color-bg-subtle)`).
+
+## Usage Example
+
+```html
+<st-card [elevated]="true" [selectable]="false" [padding]="true" variant="default">
+  <h3>Card Title</h3>
+  <p>This is the content inside the card.</p>
+</st-card>
+```
+

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

@@ -0,0 +1,22 @@
+# ngx-strata: checkbox Feature
+
+This file contains the AI documentation for the `checkbox` feature and its related components.
+
+## Checkbox (`<st-checkbox>`)
+- **Selector**: `st-checkbox`
+- **Imports**: `StrataCheckboxComponent`
+- **Inputs**:
+  - `[label] (string | undefined)`
+  - `[name] (string | undefined)`
+
+## Usage Example
+
+```html
+<st-checkbox 
+  label="I agree to the terms and conditions" 
+  name="terms"
+  [(ngModel)]="acceptedTerms">
+</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/divider.md

@@ -0,0 +1,19 @@
+# ngx-strata: divider Feature
+
+This file contains the AI documentation for the `divider` feature and its related components.
+
+## Divider (`<st-divider>`)
+- **Selector**: `st-divider`
+- **Imports**: `StrataDividerComponent`
+- **Inputs**:
+  - `[label] (string)`
+  - `[margin] (any)`
+  - `[vertical] (any)`
+
+## Usage Example
+
+```html
+<st-divider label="OR" [margin]="true" [vertical]="false"></st-divider>
+```
+
+> **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/icon.md

@@ -0,0 +1,21 @@
+# ngx-strata: icon Feature
+
+This file contains the AI documentation for the `icon` feature and its related components.
+
+## Icon (`<st-icon>`)
+- **Selector**: `st-icon`
+- **Imports**: `StrataIconComponent`
+- **Inputs**:
+  - `[name] (string)`
+
+## Usage Example
+
+\`\`\`html
+<st-icon name="search" size="md"></st-icon>
+<st-icon name="info" size="lg"></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.
+
+> **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/input-field.md

@@ -0,0 +1,29 @@
+# ngx-strata: input-field Feature
+
+This file contains the AI documentation for the `input-field` feature and its related components.
+
+## AutoResize (`[stAutoResize]`)
+- **Selector**: `[stAutoResize]`
+- **Imports**: `StrataAutoResizeDirective`
+- **Inputs**:
+  - `[minimumRows] (any)`
+  - `[maximumRows] (number)`
+
+## NativeInputRef (`input[stInput], textarea[stInput]`)
+- **Selector**: `input[stInput], textarea[stInput]`
+- **Imports**: `StrataNativeInputRefDirective`
+
+## InputField (`<st-input-field>`)
+- **Selector**: `st-input-field`
+- **Imports**: `StrataInputFieldComponent`
+
+> **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.
+## Usage Example
+
+```html
+<st-input-field>
+  <input type="text" stInput placeholder="Enter your name" [(ngModel)]="userName" />
+</st-input-field>
+```
+
+> **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/item.md

@@ -0,0 +1,31 @@
+# ngx-strata: item Feature
+
+This file contains the AI documentation for the `item` feature and its related components.
+
+## Item (`<st-item>`)
+- **Selector**: `st-item`
+- **Imports**: `StrataItemComponent`
+
+## ItemList (`<st-item-list>`)
+- **Selector**: `st-item-list`
+- **Imports**: `StrataItemListComponent`
+- **Inputs**:
+  - `[items] (T[])`
+  - `[dividers] (boolean)`
+  - `[template] (TemplateRef<T)`
+
+> **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.
+## Usage Example
+
+```html
+<st-item>
+  <st-icon name="user" slot="start"></st-icon>
+  <div slot="content">
+    <h4>User Profile</h4>
+    <p>Manage your account settings</p>
+  </div>
+  <st-icon name="chevron_right" slot="end"></st-icon>
+</st-item>
+```
+
+> **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/kbd.md

@@ -0,0 +1,18 @@
+# ngx-strata: kbd Feature
+
+This file contains the AI documentation for the `kbd` feature and its related components.
+
+## Kbd (`<st-kbd>`)
+- **Selector**: `st-kbd`
+- **Imports**: `StrataKbdComponent`
+- **Inputs**:
+  - `[keys] (string | string[])`
+
+## Usage Example
+
+```html
+<st-kbd [keys]="['meta', 'k']"></st-kbd>
+<st-kbd keys="enter"></st-kbd>
+```
+
+> **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/message-state.md

@@ -0,0 +1,32 @@
+# ngx-strata: message-state Feature
+
+This file contains the AI documentation for the `message-state` feature and its related components.
+
+## MessageState (`<st-message-state>`)
+- **Selector**: `st-message-state`
+- **Imports**: `StrataMessageStateComponent`
+- **Inputs**:
+  - `[header] (string)`
+  - `[subtitle] (string | undefined)`
+  - `[primaryActionText] (string | undefined)`
+  - `[primaryActionTheme] (Theme | undefined)`
+  - `[secondaryActionText] (string | undefined)`
+- **Outputs**:
+  - `(primaryAction)`
+  - `(secondaryAction)`
+
+## Usage Example
+
+```html
+<st-message-state
+  header="No Results Found"
+  subtitle="Try adjusting your search filters."
+  primaryActionText="Clear Filters"
+  secondaryActionText="Go Home"
+  (primaryAction)="clear()"
+  (secondaryAction)="goHome()">
+  <st-icon name="search" slot="icon" size="lg"></st-icon>
+</st-message-state>
+```
+
+> **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/modal.md

@@ -0,0 +1,96 @@
+# ngx-strata: modal Feature
+
+This file contains the AI documentation for the `modal` feature and its related components.
+
+## AlertContent (`<st-alert-content>`)
+- **Selector**: `st-alert-content`
+- **Imports**: `StrataAlertContentComponent`
+- **Inputs**:
+  - `[title] (string)`
+  - `[message] (string)`
+  - `[icon] (string | undefined)`
+  - `[theme] (Theme)`
+  - `[affirmativeButton] (string)`
+  - `[cancelButton] (string | undefined)`
+
+## Modal (`<st-modal>`)
+- **Selector**: `st-modal`
+- **Imports**: `StrataModalComponent`
+- **Inputs**:
+  - `[configuration] (ModalConfiguration)`
+
+## ModalContainer (`<st-modal-container>`)
+- **Selector**: `st-modal-container`
+- **Imports**: `StrataModalContainerComponent`
+
+## ModalHeader (`<st-modal-header>`)
+- **Selector**: `st-modal-header`
+- **Imports**: `StrataModalHeaderComponent`
+- **Inputs**:
+  - `[title] (string | null | undefined)`
+  - `[showCloseButton] (boolean)`
+
+## Usage Example
+
+Modals in \`ngx-strata\` are opened programmatically using the \`ModalService\`. Do **NOT** use \`<st-modal>\` declaratively in your templates.
+
+### 1. Opening a Modal (TypeScript)
+\`\`\`typescript
+import { Component, inject } from '@angular/core';
+import { ModalService } from 'ngx-strata';
+import { MyModalContentComponent } from './my-modal-content.component';
+
+@Component({...})
+export class MyComponent {
+  private modalService = inject(ModalService);
+
+  openSettings() {
+    this.modalService.showModal({
+      component: MyModalContentComponent,
+      title: 'User Settings',
+      size: 'lg'
+    });
+  }
+}
+```
+
+### 2. The Modal Content Component
+Inside your modal content component, inject `StrataModalRef` to close it. The modal's header and close button are automatically handled by the wrapper based on the configuration passed to `showModal()`.
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { StrataModalRef } from 'ngx-strata';
+
+@Component({
+  template: \`
+    <p>Adjust your preferences here.</p>
+    <st-button-group justification="end">
+      <button stButton variant="secondary" (click)="close()">Cancel</button>
+      <button stButton variant="primary" (click)="save()">Save</button>
+    </st-button-group>
+  \`
+})
+export class MyModalContentComponent {
+  private modalRef = inject(StrataModalRef);
+
+  close() {
+    this.modalRef.close();
+  }
+
+  save() {
+    // Save logic...
+    this.modalRef.close(true); // Can pass data back
+  }
+}
+```
+
+## CSS Custom Properties
+The modal component exposes internal CSS custom properties for styling and layout overrides:
+- `--st-modal-bg-color`: Background color of the modal (defaults to `var(--st-color-bg-raised)`).
+- `--st-modal-border-radius`: Border radius of the modal (defaults to `var(--st-border-radius-sm)`).
+- `--st-modal-padding`: Inner padding of the modal (defaults to `var(--st-size-md)`).
+- `--st-modal-covered-modal-filter`: CSS filter applied to covered modals (defaults to `brightness(70%)`).
+- `--st-modal-viewport-margin`: Viewport safety margin when calculating max-height (defaults to `var(--st-size-md)`).
+
+> **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.
+