ngx-strata 0.3.0 → 0.4.0

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

@@ -1,8 +1,27 @@
 # ngx-strata: modal Feature
 
-This file contains the AI documentation for the `modal` feature and its related components.
+This file contains the AI documentation for the `modal` feature, its configuration, and related components.
 
-## AlertContent (`<st-alert-content>`)
+## Overview
+
+Modals in `ngx-strata` are opened **programmatically** using the `ModalService`. Do **NOT** use `<st-modal>` declaratively in your application templates. The `<st-modal-container>` is automatically provided by `<st-shell>`.
+
+---
+
+## Components & Directives
+
+### ModalFooter (`<st-modal-footer>`)
+- **Selector**: `st-modal-footer`
+- **Imports**: `StrataModalFooterComponent`
+- **Inputs**:
+  - `[justification] ('start' | 'center' | 'end' | 'space-between')` (defaults to `'end'`)
+- **Usage**:
+  - Place `<st-modal-footer>` at the bottom of your injected modal content template.
+  - Automatically stretches edge-to-edge against the modal borders.
+  - Pinned with `position: sticky; bottom: 0;` so it remains visible when modal content scrolls.
+  - **Always pair with `<st-button-group>`** to format buttons with built-in spacing and alignment. Avoid using raw `<div>` tags or manual margins.
+
+### AlertContent (`<st-alert-content>`)
 - **Selector**: `st-alert-content`
 - **Imports**: `StrataAlertContentComponent`
 - **Inputs**:
@@ -13,32 +32,80 @@ This file contains the AI documentation for the `modal` feature and its related
   - `[affirmativeButton] (string)`
   - `[cancelButton] (string | undefined)`
 
-## Modal (`<st-modal>`)
+### Modal (`<st-modal>`)
 - **Selector**: `st-modal`
 - **Imports**: `StrataModalComponent`
 - **Inputs**:
   - `[configuration] (ModalConfiguration)`
+  - `[size] (ModalSize)`
+  - `[variant] (ModalVariant)`
 
-## ModalContainer (`<st-modal-container>`)
+### ModalContainer (`<st-modal-container>`)
 - **Selector**: `st-modal-container`
 - **Imports**: `StrataModalContainerComponent`
+- **Note**: Handled automatically by `<st-shell>`.
 
-## ModalHeader (`<st-modal-header>`)
+### ModalHeader (`<st-modal-header>`)
 - **Selector**: `st-modal-header`
 - **Imports**: `StrataModalHeaderComponent`
 - **Inputs**:
   - `[title] (string | null | undefined)`
   - `[showCloseButton] (boolean)`
+- **Note**: Handled automatically based on `ModalConfiguration`.
+
+---
+
+## ModalConfiguration
+
+```typescript
+export interface ModalConfiguration {
+  component: Type<unknown>;
+  title?: string;
+  size?: ModalSize;                 // 'xs' | 'sm' | 'md' | 'lg' (default: 'md')
+  variant?: ModalVariant;           // 'default' | 'raised' (default: 'default')
+  hideCloseButton?: boolean;       // default: false
+  disableBackdropClosure?: boolean; // default: false
+  inputs?: Record<string, unknown>; // Inputs forwarded to injected component
+  onModalClosed?: (value?: unknown) => void;
+}
+
+export type ModalSize = 'xs' | 'sm' | 'md' | 'lg';
+export type ModalVariant = 'default' | 'raised';
+```
 
-## Usage Example
+### Choosing `variant`:
+- `'default'`: Uses `--st-color-bg-default` (the standard page background). This is the default for all modals. It allows nested components like `st-card` to sit on top with clean visual elevation and contrast.
+- `'raised'`: Uses `--st-color-bg-raised` (the elevated surface background). Used automatically by `showAlert()` and recommended when the modal is a simple dialog or confirmation prompt without nested cards.
 
-Modals in \`ngx-strata\` are opened programmatically using the \`ModalService\`. Do **NOT** use \`<st-modal>\` declaratively in your templates.
+### Responsive Behavior & Mobile Sizing:
+- **`xs` (Alerts) and `sm` modals**: Remain centered dialog boxes on all screen sizes, preserving their standard viewport margins, borders, and rounded corners.
+- **`md` (default) and `lg` modals**: Automatically adapt to **full-screen mode** (`100vw` by `100dvh`) on screens under `768px` (`< 768px`), with `border-radius: 0` and `border: none`. The content area flexes to fill available vertical space, and `<st-modal-footer>` stays pinned to the bottom of the screen.
 
-### 1. Opening a Modal (TypeScript)
-\`\`\`typescript
+---
+
+## AlertConfiguration
+
+```typescript
+export interface AlertConfiguration {
+  message: string;
+  affirmativeButton: string;
+  title?: string;
+  cancelButton?: string;
+  icon?: string;
+  theme?: Theme; // 'info' | 'success' | 'warning' | 'danger' | 'brand'
+}
+```
+
+---
+
+## Usage Examples
+
+### 1. Opening a Custom Modal with a Footer
+
+```typescript
 import { Component, inject } from '@angular/core';
 import { ModalService } from 'ngx-strata';
-import { MyModalContentComponent } from './my-modal-content.component';
+import { MySettingsModalComponent } from './my-settings-modal.component';
 
 @Component({...})
 export class MyComponent {
@@ -46,51 +113,133 @@ export class MyComponent {
 
   openSettings() {
     this.modalService.showModal({
-      component: MyModalContentComponent,
-      title: 'User Settings',
-      size: 'lg'
+      component: MySettingsModalComponent,
+      title: 'Project Settings',
+      size: 'md',
+      variant: 'default',
+      onModalClosed: (result) => {
+        if (result) {
+          // Handled result
+        }
+      }
     });
   }
 }
 ```
 
-### 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()`.
+### 2. The Modal Content Component (with `<st-modal-footer>`)
+
+Inside the injected component, inject `StrataModalRef` to trigger closing. Combine `<st-modal-footer>` with `<st-button-group>` for actions:
 
 ```typescript
 import { Component, inject } from '@angular/core';
-import { StrataModalRef } from 'ngx-strata';
+import {
+  StrataModalRef,
+  StrataModalFooterComponent,
+  StrataButtonGroupComponent,
+  StrataButtonDirective
+} 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>
-  \`
+  imports: [
+    StrataModalFooterComponent,
+    StrataButtonGroupComponent,
+    StrataButtonDirective
+  ],
+  template: `
+    <p class="st-body-m">Configure your project settings here.</p>
+
+    <!-- Standard End-Aligned Actions -->
+    <st-modal-footer>
+      <st-button-group justification="end">
+        <button stButton variant="secondary" (click)="cancel()">Cancel</button>
+        <button stButton variant="primary" (click)="save()">Save Changes</button>
+      </st-button-group>
+    </st-modal-footer>
+  `
 })
-export class MyModalContentComponent {
+export class MySettingsModalComponent {
   private modalRef = inject(StrataModalRef);
 
-  close() {
+  cancel() {
     this.modalRef.close();
   }
 
   save() {
-    // Save logic...
-    this.modalRef.close(true); // Can pass data back
+    this.modalRef.close({ saved: true });
   }
 }
 ```
 
+### 3. Split Footer Actions (Left Action + Right Group)
+
+When a secondary action (like "Delete" or "Reset") should appear on the left while primary actions sit on the right:
+
+```html
+<st-modal-footer>
+  <button stButton variant="ghost" (click)="reset()">Reset Defaults</button>
+  <st-button-group justification="end">
+    <button stButton variant="secondary" (click)="cancel()">Cancel</button>
+    <button stButton variant="primary" (click)="save()">Save</button>
+  </st-button-group>
+</st-modal-footer>
+```
+
+### 4. Opening a Standard Alert
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { ModalService } from 'ngx-strata';
+
+@Component({...})
+export class MyComponent {
+  private modalService = inject(ModalService);
+
+  confirmDelete() {
+    this.modalService.showAlert({
+      title: 'Delete Item',
+      message: 'Are you sure you want to delete this item? This cannot be undone.',
+      affirmativeButton: 'Delete',
+      cancelButton: 'Cancel',
+      theme: 'danger',
+      icon: 'warning'
+    }, (confirmed) => {
+      if (confirmed) {
+        // Proceed with deletion
+      }
+    });
+  }
+}
+```
+
+---
+
 ## 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)`).
+
+The modal and modal footer expose internal CSS custom properties mapped to design tokens:
+
+### Modal (`st-modal`)
+- `--st-modal-bg-color`: Background color of the modal (defaults to `var(--st-color-bg-default)`).
 - `--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-padding`: Inner padding of the modal content (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.
+### Modal Footer (`st-modal-footer`)
+- `--st-modal-footer-bg`: Background color of the footer (defaults to `var(--st-modal-bg-color)`).
+- `--st-modal-footer-border-color`: Border divider color (defaults to `var(--st-border)`).
+- `--st-modal-footer-padding`: Padding inside the footer (defaults to `var(--st-size-xs) var(--st-size-sm)`).
+- `--st-modal-footer-gap`: Gap between elements in the footer (defaults to `var(--st-size-xs)`).
+
+---
+
+## Accessibility & Keyboard Navigation
+- **ARIA Roles**: `<st-modal>` automatically includes `role="dialog"` and `aria-modal="true"`.
+- **Focus Trapping**: Tabbing through interactive elements inside the modal wraps around automatically (`Tab` and `Shift + Tab`).
+- **Focus Restoration**: Focus is returned to the element that originally had focus prior to opening the modal upon closure.
+- **Escape Key Dismissal**: Pressing the `Escape` key dismisses the topmost modal unless `disableBackdropClosure: true` is configured.
 
+> **Note to AI Agents**:
+> - Always use modern Angular Signals (`input()`, `output()`) for data/event bindings.
+> - Do NOT use raw HTML `<button>`, `<input>`, or `<select>` when `ngx-strata` equivalents exist.
+> - Always use `<st-button-group>` to arrange action buttons within `<st-modal-footer>`.

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

@@ -5,17 +5,36 @@ This file contains the AI documentation for the `notification` feature and its r
 ## Notification (`<st-notification>`)
 - **Selector**: `st-notification`
 - **Imports**: `StrataNotificationComponent`
+- **Inputs**:
+  - `[message] (string, required)`: The notification message.
+  - `[icon] (string | undefined)`: Optional icon name to display.
+  - `[dismissible] (boolean)`: Whether to display a close button. Defaults to `false`.
+- **Outputs**:
+  - `(dismiss) (void)`: Emitted when the close button is clicked.
 
 ## NotificationContainer (`<st-notification-container>`)
 - **Selector**: `st-notification-container`
 - **Imports**: `StrataNotificationContainerComponent`
 
-## Usage Example
+## NotificationService
+Notifications are managed programmatically via `NotificationService`.
 
-Notifications are opened programmatically using the \`NotificationService\`. Do **NOT** use \`<st-notification>\` declaratively in your templates.
+### NotificationConfiguration
+- `message: string`
+- `icon?: string`
+- `theme?: 'info' | 'success' | 'warning' | 'danger' | 'brand'` (defaults to `'info'`)
+- `duration?: number` (defaults to `3000`ms. Set to `0` for persistent notifications)
+- `dismissible?: boolean` (defaults to `false` when duration > 0, and defaults to `true` when `duration === 0`)
 
-### Triggering a Notification (TypeScript)
-\`\`\`typescript
+### Return Handle (`StrataNotificationRef`)
+Calling `showNotification(config)` returns a `StrataNotificationRef`:
+- `id: string`
+- `dismiss(): void`
+
+## Usage Examples
+
+### 1. Standard Auto-dismissing Notification
+```typescript
 import { Component, inject } from '@angular/core';
 import { NotificationService } from 'ngx-strata';
 
@@ -24,23 +43,40 @@ export class MyComponent {
   private notificationService = inject(NotificationService);
 
   showSuccess() {
-    this.notificationService.open({
-      title: 'Upload Complete',
+    this.notificationService.showNotification({
       message: 'Your file has been successfully uploaded.',
       theme: 'success',
-      icon: 'check_circle'
+      icon: 'check'
     });
   }
+}
+```
 
-  showError() {
-    this.notificationService.open({
-      title: 'Upload Failed',
-      message: 'There was a network error during upload.',
-      theme: 'danger',
-      icon: 'error'
+### 2. Dismissible & Persistent Notification with Programmatic Handle
+```typescript
+@Component({...})
+export class UploadComponent {
+  private notificationService = inject(NotificationService);
+
+  async uploadFile() {
+    const ref = this.notificationService.showNotification({
+      message: 'Uploading file...',
+      duration: 0,
+      dismissible: true
     });
+
+    try {
+      await this.api.upload();
+      ref.dismiss();
+      this.notificationService.showNotification({
+        message: 'Upload complete!',
+        theme: 'success'
+      });
+    } catch {
+      ref.dismiss();
+    }
   }
 }
-\`\`\`
+```
 
 > **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/otp.md

@@ -0,0 +1,68 @@
+# ngx-strata: otp Feature
+
+This file contains the AI documentation for the `otp` feature and its related components.
+
+## Otp (`<st-otp>`)
+- **Selector**: `st-otp`
+- **Imports**: `StrataOtpComponent`
+- **Inputs & Models**:
+  - `[(value)] (model<string>)`: Current OTP value string.
+  - `[(state)] (model<OtpState>)`: Component state (`'idle' | 'loading' | 'success' | 'error'`).
+  - `[length] (number)`: Number of input slots (default `6`).
+  - `[type] (OtpType)`: Input character mode (`'number' | 'alphanumeric' | 'password'`). Default `'number'`.
+  - `[uppercase] (boolean)`: Automatically uppercase alphanumeric characters (default `true`).
+  - `[mask] (boolean)`: Mask characters like a password (default `false`).
+  - `[size] (OtpSize)`: Size variant (`'sm' | 'md' | 'lg'`). Default `'md'`.
+  - `[clearOnError] (boolean)`: Automatically clear input slots when entering `'error'` state (default `false`).
+  - `[clearOnErrorDelay] (number)`: Delay in milliseconds before auto-clearing on error (default `800`).
+  - `[resetErrorOnInput] (boolean)`: Automatically reset error state to `'idle'` as soon as user types or edits (default `true`).
+  - `[loading] (boolean)`: Convenience boolean flag for loading state (displays centered loading overlay without layout shift).
+  - `[error] (boolean | string)`: Convenience flag or error message for error state.
+  - `[success] (boolean)`: Convenience boolean flag for success state.
+  - `[errorMessage] (string | undefined)`: Error text displayed below slots.
+  - `[helperText] (string | undefined)`: Informational helper text displayed below slots.
+  - `[disabled] (boolean)`: Whether input slots are disabled.
+  - `[readonly] (boolean)`: Whether input slots are read-only.
+  - `[autofocus] (boolean)`: Focus the first slot on mount (default `false`).
+- **Outputs**:
+  - `(completed)`: Emitted with full string when all slots are filled.
+  - `(valueChange)`: Emitted with new string whenever value changes.
+  - `(stateChange)`: Emitted whenever state changes.
+  - `(errorReset)`: Emitted when error state resets via user typing, `clear()`, or `clearOnError`.
+
+## Form Integration
+Implements `ControlValueAccessor` (CVA). Compatible with Reactive Forms (`formControlName`, `[formControl]`) and template-driven forms (`[(ngModel)]`).
+
+## Usage Examples
+
+### 1. Basic 6-Digit Verification with Completion Handler
+```html
+<st-otp
+  [length]="6"
+  type="number"
+  (completed)="verifyCode($event)">
+</st-otp>
+```
+
+### 2. Two-Way State, Auto-Clear on Error, & Loading Overlay
+```html
+<st-otp
+  [length]="6"
+  [(state)]="otpState"
+  [clearOnError]="true"
+  [clearOnErrorDelay]="1000"
+  [errorMessage]="errorMessage()"
+  (completed)="onOtpComplete($event)">
+</st-otp>
+```
+
+### 3. Reactive Forms Integration
+```html
+<st-otp
+  [formControl]="otpControl"
+  [length]="4"
+  type="number">
+</st-otp>
+```
+
+> **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/pagination.md

@@ -6,15 +6,18 @@ This file contains the AI documentation for the `pagination` feature and its rel
 - **Selector**: `st-pagination`
 - **Imports**: `StrataPaginationComponent`
 - **Inputs**:
-  - `[totalPages] (number)`
-  - `[hideNextPreviousAtStartEnd] (any)`
+  - `[totalPages] (number, required)`: Total number of pages available.
+  - `[(currentPage)] (model<number>)`: Two-way bound current active page (1-based). Defaults to `1`.
+  - `[hideNextPreviousAtStartEnd] (boolean)`: When true, hides Previous at page 1 and Next at last page. Defaults to `false`.
 - **Outputs**:
-  - `(pageSelected)`
+  - `(pageSelected) (number)`: Emitted when the user selects a page or uses next/previous controls.
+- **Accessibility**: Host automatically exposes `role="navigation"` and `aria-label="Pagination"`. Active page button has `aria-current="page"`. Gaps are rendered as non-interactive `<span class="pagination-ellipsis" aria-hidden="true">...</span>`.
 
 ## Usage Example
 
 ```html
 <st-pagination 
+  [(currentPage)]="currentPage"
   [totalPages]="10" 
   (pageSelected)="loadPage($event)">
 </st-pagination>

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

@@ -5,25 +5,45 @@ This file contains the AI documentation for the `radio` feature and its related
 ## Radio (`<st-radio>`)
 - **Selector**: `st-radio`
 - **Imports**: `StrataRadioComponent`
-- **Inputs**:
-  - `[value] (string)`
-  - `[label] (string | undefined)`
-  - `[disabled] (any)`
+- **Inputs & Models**:
+  - `[value] (string)`: Unique value represented by this radio item. Required.
+  - `[label] (string | undefined)`: Label text displayed next to the radio circle.
+  - `[(checked)] (model<boolean>)`: Whether this radio item is active.
+  - `[disabled] (boolean)`: Disables user interaction on this specific radio.
 - **Outputs**:
-  - `(select)`
+  - `(selected)`: Emitted when the radio button is selected.
 
 ## RadioGroup (`<st-radio-group>`)
 - **Selector**: `st-radio-group`
 - **Imports**: `StrataRadioGroupComponent`
+- **Inputs & Models**:
+  - `[(value)] (model<string>)`: Current active radio value in the group.
+  - `[disabled] (boolean)`: Disables all radio buttons in the group.
+- **Outputs**:
+  - `(valueChange)`: Emitted whenever the group selection changes.
+
+## Form Integration
+Implements `ControlValueAccessor` (CVA) on `<st-radio-group>`. Compatible with Reactive Forms (`formControlName`, `[formControl]`) and template-driven forms (`[(ngModel)]`). Supports keyboard arrow navigation (Up/Down/Left/Right) across options.
 
-## Usage Example
+## Usage Examples
 
+### 1. Two-Way Binding with Radio Group
 ```html
-<st-radio-group [(ngModel)]="selectedColor">
-  <st-radio value="red" label="Red"></st-radio>
-  <st-radio value="green" label="Green"></st-radio>
-  <st-radio value="blue" label="Blue" [disabled]="true"></st-radio>
+<st-radio-group [(value)]="selectedTier">
+  <st-radio value="free" label="Free Tier"></st-radio>
+  <st-radio value="pro" label="Pro Tier"></st-radio>
+  <st-radio value="enterprise" label="Enterprise" [disabled]="true"></st-radio>
+</st-radio-group>
+```
+
+### 2. Reactive Forms Integration
+```html
+<st-radio-group [formControl]="themeControl">
+  <st-radio value="light" label="Light Mode"></st-radio>
+  <st-radio value="dark" label="Dark Mode"></st-radio>
+  <st-radio value="system" label="System Default"></st-radio>
 </st-radio-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/segmented-control.md

@@ -5,34 +5,55 @@ This file contains the AI documentation for the `segmented-control` feature and
 ## SegmentedControl (`<st-segmented-control>`)
 - **Selector**: `st-segmented-control`
 - **Imports**: `StrataSegmentedControlComponent`
-- **Inputs**:
-  - `[fullWidth] (any)`
+- **Inputs & Models**:
+  - `[(value)] (model<string>)`: Current active segment value (maps to selected child item's `value` or `text`).
+  - `[disabled] (boolean)`: Disables the entire segmented control and all child items.
+  - `[size] ('sm' | 'md' | 'lg')`: Size variant (default `'md'`).
+  - `[fullWidth] (boolean)`: Whether items stretch equally to fill the parent width.
+- **Outputs**:
+  - `(valueChange)`: Emitted whenever the active segment value changes.
 
 ## SegmentedControlItem (`<st-segmented-control-item>`)
 - **Selector**: `st-segmented-control-item`
 - **Imports**: `StrataSegmentedControlItemComponent`
-- **Inputs**:
-  - `[text] (string)`
-  - `[disabled] (any)`
+- **Inputs & Models**:
+  - `[text] (string)`: Display label text. Required.
+  - `[value] (string | undefined)`: Form value associated with item (defaults to `text` if omitted).
+  - `[(selected)] (model<boolean>)`: Whether item is selected.
+  - `[disabled] (boolean)`: Disables this individual item.
 - **Outputs**:
-  - `(selectionChanged)`
+  - `(selectionChanged)`: Emitted when the item becomes selected.
+
+## Form Integration
+Implements `ControlValueAccessor` (CVA). Compatible with Reactive Forms (`formControlName`, `[formControl]`) and template-driven forms (`[(ngModel)]`). Supports keyboard Space/Enter selection.
+
+## Usage Examples
 
-## Usage Example
+### 1. Two-Way Value Binding
+```html
+<st-segmented-control [(value)]="currentView">
+  <st-segmented-control-item text="List" value="list"></st-segmented-control-item>
+  <st-segmented-control-item text="Grid" value="grid"></st-segmented-control-item>
+  <st-segmented-control-item text="Kanban" value="kanban"></st-segmented-control-item>
+</st-segmented-control>
+```
 
+### 2. Reactive Forms Integration
 ```html
-<st-segmented-control [fullWidth]="false">
-  <st-segmented-control-item 
-    text="List View" 
-    [selected]="view === 'list'" 
-    (selectionChanged)="view = 'list'">
-  </st-segmented-control-item>
-  
-  <st-segmented-control-item 
-    text="Grid View" 
-    [selected]="view === 'grid'" 
-    (selectionChanged)="view = 'grid'">
-  </st-segmented-control-item>
+<st-segmented-control [formControl]="billingCycleControl">
+  <st-segmented-control-item text="Monthly" value="monthly"></st-segmented-control-item>
+  <st-segmented-control-item text="Annual (Save 20%)" value="annual"></st-segmented-control-item>
+</st-segmented-control>
+```
+
+### 3. Full Width with Size Variants
+```html
+<st-segmented-control [fullWidth]="true" size="sm" [(value)]="activeTab">
+  <st-segmented-control-item text="Overview" value="overview"></st-segmented-control-item>
+  <st-segmented-control-item text="Analytics" value="analytics"></st-segmented-control-item>
+  <st-segmented-control-item text="Settings" value="settings"></st-segmented-control-item>
 </st-segmented-control>
 ```
 
 > **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.
+