@open-rlb/ng-bootstrap 3.3.24 → 3.3.26

package/schematics/ng-add/claude-skills/rlb-design/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: rlb-design
+description: Bootstrap 5.3 + @open-rlb/ng-bootstrap design guidance for layout, spacing, typography, color palette, and responsive design. Use when making visual or design decisions for UIs in this project.
+---
+
+# RLB Bootstrap 5.3 Design Skill
+
+You are an expert in designing Angular UIs using **Bootstrap 5.3** with the **@open-rlb/ng-bootstrap** component library. This skill guides layout, spacing, typography, color, and responsive design decisions.
+
+## Bootstrap 5.3 Color Palette
+
+The library uses a typed `Color` union:
+```typescript
+type Color = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'light' | 'dark';
+```
+
+All components that accept a `color` input use this type.
+
+## Layout & Grid
+
+Use Bootstrap's 12-column grid system:
+```html
+<div class="container">
+  <div class="row">
+    <div class="col-12 col-md-6 col-lg-4">...</div>
+  </div>
+</div>
+```
+
+Breakpoints: `xs` (default), `sm` (576px), `md` (768px), `lg` (992px), `xl` (1200px), `xxl` (1400px).
+
+## Spacing
+
+Use Bootstrap spacing utilities `m-{size}`, `p-{size}`, `gap-{size}` (0–5, auto).
+Directional: `mt`, `mb`, `ms`, `me`, `mx`, `my`, `pt`, `pb`, `ps`, `pe`, `px`, `py`.
+
+## Typography
+
+- Headings: `h1`–`h6`, `.display-1`–`.display-6`
+- Text utilities: `fw-bold`, `fw-semibold`, `fst-italic`, `text-{color}`, `text-{align}`
+- Size: `fs-1`–`fs-6`
+- Truncation: `text-truncate`, `text-break`
+
+## Flexbox & Grid Utilities
+
+```html
+<div class="d-flex align-items-center justify-content-between gap-2">...</div>
+<div class="d-grid gap-2">...</div>
+```
+
+## Background & Border
+
+- Background: `bg-{color}`, `bg-opacity-{10|25|50|75|100}`
+- Border: `border`, `border-{color}`, `border-{size}`, `rounded`, `rounded-{size}`, `rounded-pill`
+- Shadow: `shadow-sm`, `shadow`, `shadow-lg`
+
+## Sizing Utilities
+
+- Width: `w-25`, `w-50`, `w-75`, `w-100`, `w-auto`, `mw-100`, `vw-100`
+- Height: `h-25`, `h-50`, `h-75`, `h-100`, `h-auto`, `vh-100`, `min-vh-100`
+
+## Overflow & Position
+
+- `overflow-auto`, `overflow-hidden`, `overflow-scroll`
+- `position-relative`, `position-absolute`, `position-fixed`, `position-sticky`
+- `top-0`, `start-0`, `bottom-0`, `end-0`, `translate-middle`
+
+## Visibility & Display
+
+- `d-none`, `d-{bp}-block`, `d-{bp}-flex`, `d-{bp}-none`
+- `visible`, `invisible`
+
+## RLB Theme Conventions
+
+- Use `color="primary"` for main actions, `color="secondary"` for secondary.
+- Use `color="danger"` for destructive actions (delete, remove).
+- Use `color="success"` / `color="warning"` / `color="info"` for status feedback.
+- Prefer `outline` buttons for secondary actions inside cards or toolbars.
+- Use `size="sm"` for table rows and dense UIs; `size="lg"` for hero sections.
+
+## Page Layout Pattern
+
+```html
+<div class="container-fluid p-0 d-flex flex-column min-vh-100">
+  <rlb-navbar>...</rlb-navbar>
+  <div class="d-flex flex-grow-1 overflow-hidden">
+    <rlb-sidebar>...</rlb-sidebar>
+    <main class="flex-grow-1 overflow-auto p-3">
+      <!-- page content -->
+    </main>
+  </div>
+</div>
+```
+
+## Card-based Sections
+
+```html
+<div class="row g-3">
+  <div class="col-12 col-md-6 col-xl-4">
+    <rlb-card>
+      <rlb-card-header>Title</rlb-card-header>
+      <rlb-card-body>Content</rlb-card-body>
+    </rlb-card>
+  </div>
+</div>
+```
+
+## Responsive Helpers
+
+- Hide on mobile: `d-none d-md-block`
+- Show only on mobile: `d-block d-md-none`
+- Stack to row on md+: `flex-column flex-md-row`
+
+## Design Principles
+
+1. Mobile-first: design for small screens, enhance for larger ones.
+2. Prefer utility classes over custom CSS.
+3. Use semantic HTML (`main`, `section`, `nav`, `aside`).
+4. Keep component `color` consistent with the app's design tokens.
+5. Use `gap-*` on flex/grid containers instead of margin on children.

package/schematics/ng-add/claude-skills/rlb-inputs/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: rlb-inputs
+description: Expert guidance for @open-rlb/ng-bootstrap form input components (ControlValueAccessor-based, integrate with reactive and template-driven forms). Use when building forms or using input components.
+---
+
+# RLB ng-Bootstrap Form Inputs Skill
+
+You are an expert in the **@open-rlb/ng-bootstrap** form input components. All inputs implement `ControlValueAccessor` and integrate seamlessly with Angular Reactive Forms and Template-driven forms. They use Angular 18+ signals and `ChangeDetectionStrategy.OnPush`.
+
+## Common Pattern
+
+All inputs share these base inputs:
+- `disabled: boolean` — disables the control
+- `readonly: boolean` — read-only display
+- `size: 'small' | 'large' | undefined` — field size variant
+- `id: string` — HTML id (auto-generated if omitted)
+- `enable-validation: boolean` — show Bootstrap validation styles (invalid/valid)
+
+All inputs bind via `formControlName` or `[(ngModel)]`.
+
+---
+
+## rlb-input — Text / Number / Date
+
+```html
+<!-- Text -->
+<rlb-input formControlName="username" placeholder="Enter username" [enable-validation]="true"></rlb-input>
+
+<!-- Number with bounds -->
+<rlb-input formControlName="age" type="number" [min]="0" [max]="120" [step]="1"></rlb-input>
+
+<!-- Date (stores as DateTz, timezone-aware) -->
+<rlb-input formControlName="birthDate" type="datetime-local" date-type="date-tz" timezone="Europe/Rome"></rlb-input>
+
+<!-- Date stored as ISO string -->
+<rlb-input formControlName="startDate" type="datetime-local" date-type="string" timezone="UTC"></rlb-input>
+
+<!-- Password -->
+<rlb-input formControlName="password" type="password" [enable-validation]="true"></rlb-input>
+```
+
+**Inputs:**
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `type` | `string` | `'text'` | HTML input type |
+| `placeholder` | `string` | — | Placeholder text |
+| `size` | `'small'\|'large'` | — | Field size |
+| `min` / `max` / `step` | `number` | — | Number constraints |
+| `date-type` | `'date'\|'string'\|'number'\|'date-tz'` | `'date-tz'` | Date value format |
+| `timezone` | `string` | `'UTC'` | Timezone for date handling |
+| `readonly` | `boolean` | `false` | — |
+| `disabled` | `boolean` | `false` | — |
+| `enable-validation` | `boolean` | `false` | Show validation state |
+| `ext-validation` | `boolean` | `false` | External validation display |
+
+---
+
+## rlb-select — Dropdown Select
+
+```html
+<!-- Single select -->
+<rlb-select formControlName="country" placeholder="Choose country" [enable-validation]="true">
+  <rlb-option value="it">Italy</rlb-option>
+  <rlb-option value="de">Germany</rlb-option>
+  <rlb-option value="fr">France</rlb-option>
+</rlb-select>
+
+<!-- Multiple select -->
+<rlb-select formControlName="roles" [multiple]="true" [display]="5">
+  <rlb-option value="admin">Admin</rlb-option>
+  <rlb-option value="editor">Editor</rlb-option>
+  <rlb-option value="viewer">Viewer</rlb-option>
+</rlb-select>
+```
+
+**Inputs:** `placeholder`, `size`, `disabled`, `readonly`, `multiple`, `display` (visible rows for multiple), `inputId`, `enable-validation`
+**Returns:** `string` (single) or `string[]` (multiple)
+
+---
+
+## rlb-checkbox — Checkbox
+
+```html
+<rlb-checkbox formControlName="accepted" id="terms">
+  I accept the terms and conditions
+</rlb-checkbox>
+
+<!-- Indeterminate state -->
+<rlb-checkbox formControlName="selectAll" [indeterminate]="someSelected" id="select-all">
+  Select all
+</rlb-checkbox>
+```
+
+**Inputs:** `disabled`, `readonly`, `indeterminate`, `id`
+**Returns:** `boolean | undefined`
+
+---
+
+## rlb-switch — Toggle Switch
+
+```html
+<rlb-switch formControlName="notifications" id="notif-toggle">
+  Enable notifications
+</rlb-switch>
+```
+
+**Inputs:** `disabled`, `readonly`, `size`, `id`
+**Returns:** `boolean`
+
+---
+
+## rlb-radio — Radio Group
+
+```html
+<rlb-radio formControlName="gender" id="gender">
+  <rlb-option value="m">Male</rlb-option>
+  <rlb-option value="f">Female</rlb-option>
+  <rlb-option value="o">Other</rlb-option>
+</rlb-radio>
+```
+
+**Inputs:** `disabled`, `readonly`, `id`
+**Returns:** `string`
+
+---
+
+## rlb-textarea — Multi-line Text
+
+```html
+<rlb-textarea formControlName="notes" placeholder="Add notes..." [rows]="5" [enable-validation]="true"></rlb-textarea>
+```
+
+**Inputs:** `disabled`, `readonly`, `placeholder`, `size`, `rows` (default: 3), `id`
+
+---
+
+## rlb-autocomplete — Searchable Input
+
+```html
+<rlb-autocomplete
+  formControlName="city"
+  placeholder="Search city..."
+  [autocomplete]="searchCities"
+  [chars-to-search]="2"
+  [loading]="isSearching"
+  [enable-validation]="true"
+  (selected)="onCitySelected($event)"
+></rlb-autocomplete>
+```
+
+```typescript
+// Search function — supports sync array, Promise, or Observable
+searchCities: AutocompleteFn = (query: string) => {
+  return this.cityService.search(query); // returns Observable<AutocompleteItem[]>
+};
+
+// AutocompleteItem interface
+interface AutocompleteItem {
+  label: string;
+  value: any;
+  icon?: string;
+}
+```
+
+**Inputs:**
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `autocomplete` | `AutocompleteFn` | — | Search function (required) |
+| `placeholder` | `string` | — | — |
+| `chars-to-search` | `number` | `3` | Min chars before search |
+| `loading` | `boolean` | `false` | Show loading indicator |
+| `max-height` | `number` | `200` | Dropdown max height (px) |
+| `type` | `string` | `'text'` | Input type |
+| `size` | `'small'\|'large'` | — | — |
+| `menu-max-width` | `number\|null` | — | Dropdown max width |
+| `input-autocomplete` | `string` | `'off'` | HTML autocomplete attr |
+| `enable-validation` | `boolean` | `false` | — |
+
+**Outputs:** `selected: AutocompleteItem`
+**Note:** Debounces search by 300ms automatically.
+
+---
+
+## rlb-file — File Upload
+
+```html
+<!-- Single file -->
+<rlb-file formControlName="document" accept=".pdf,.doc" [enable-validation]="true"></rlb-file>
+
+<!-- Multiple files -->
+<rlb-file formControlName="images" [multiple]="true" accept="image/*"></rlb-file>
+```
+
+**Inputs:** `disabled`, `readonly`, `multiple`, `size`, `accept`, `id`
+**Returns:** `File | File[] | null`
+
+---
+
+## rlb-dnd-file — Drag & Drop File
+
+```html
+<rlb-dnd-file formControlName="upload" [multiple]="true" accept="image/*"></rlb-dnd-file>
+```
+
+---
+
+## rlb-color — Color Picker
+
+```html
+<rlb-color formControlName="themeColor"></rlb-color>
+```
+
+**Returns:** `string` (hex color, e.g. `#ff0000`)
+
+---
+
+## rlb-range — Range Slider
+
+```html
+<rlb-range formControlName="volume" [min]="0" [max]="100" [step]="5"></rlb-range>
+```
+
+---
+
+## rlb-input-group — Input with Addons
+
+```html
+<rlb-input-group>
+  <span class="input-group-text">@</span>
+  <rlb-input formControlName="username"></rlb-input>
+</rlb-input-group>
+
+<rlb-input-group>
+  <rlb-input formControlName="amount" type="number"></rlb-input>
+  <span class="input-group-text">EUR</span>
+</rlb-input-group>
+```
+
+---
+
+## rlb-input-validation — Validation Messages
+
+```html
+<rlb-input-validation [control]="form.get('email')">
+  <ng-container *rlbError="'required'">Email is required</ng-container>
+  <ng-container *rlbError="'email'">Invalid email format</ng-container>
+</rlb-input-validation>
+```
+
+---
+
+## Form Field Wrapper (rlb-form-fields)
+
+```html
+<rlb-form-field label="Email" [required]="true">
+  <rlb-input formControlName="email" type="email" [enable-validation]="true"></rlb-input>
+</rlb-form-field>
+```
+
+---
+
+## Reactive Form Integration Pattern
+
+```typescript
+import { FormBuilder, Validators } from '@angular/forms';
+
+@Component({
+  template: `
+    <form [formGroup]="form" (ngSubmit)="onSubmit()">
+      <div class="mb-3">
+        <label class="form-label">Name *</label>
+        <rlb-input formControlName="name" [enable-validation]="true"></rlb-input>
+      </div>
+      <div class="mb-3">
+        <label class="form-label">Role</label>
+        <rlb-select formControlName="role" [enable-validation]="true">
+          <rlb-option value="admin">Admin</rlb-option>
+          <rlb-option value="user">User</rlb-option>
+        </rlb-select>
+      </div>
+      <div class="mb-3">
+        <rlb-checkbox formControlName="active" id="active-check">Active</rlb-checkbox>
+      </div>
+      <button rlb-button type="submit" color="primary" [disabled]="form.invalid">Save</button>
+    </form>
+  `
+})
+export class MyFormComponent {
+  form = this.fb.group({
+    name: ['', Validators.required],
+    role: ['user', Validators.required],
+    active: [true]
+  });
+
+  constructor(private fb: FormBuilder) {}
+
+  onSubmit() {
+    if (this.form.valid) {
+      console.log(this.form.value);
+    }
+  }
+}
+```
+
+---
+
+## Validators
+
+The library provides custom validators:
+```typescript
+import { RequiredAutocompleteValidator } from '@open-rlb/ng-bootstrap';
+
+form = this.fb.group({
+  city: ['', [Validators.required, RequiredAutocompleteValidator]]
+});
+```
+
+---
+
+## Best Practices
+
+1. Always set `[enable-validation]="true"` on inputs inside forms with validation.
+2. Use `rlb-autocomplete` for any remote search — pass an `Observable`-returning function.
+3. For date inputs, always specify `timezone` explicitly; default is `'UTC'`.
+4. Use `date-type="date-tz"` when the model uses `@open-rlb/date-tz` DateTz objects.
+5. Wrap inputs in a `<div class="mb-3">` with a `<label class="form-label">` for correct Bootstrap spacing.

package/schematics/ng-add/claude-skills/rlb-modals/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: rlb-modals
+description: Expert guidance for the @open-rlb/ng-bootstrap modal system: programmatic modals via ModalService and the declarative [rlb-modal] directive. Use when opening, building, or configuring modals.
+---
+
+# RLB ng-Bootstrap Modals Skill
+
+You are an expert in the **@open-rlb/ng-bootstrap** modal system. Modals support programmatic opening via `ModalService` and declarative usage via the `[rlb-modal]` directive.
+
+## Core Types
+
+```typescript
+type ModalCloseReason = 'ok' | 'cancel' | 'close';
+type ModalType = 'success' | 'info' | 'warning' | 'error';
+
+interface ModalOptions {
+  backdrop?: boolean | 'static';  // 'static' = click outside doesn't close
+  scrollable?: boolean;
+  verticalcentered?: boolean;
+  animation?: boolean;
+  size?: 'sm' | 'md' | 'lg' | 'xl';
+  fullscreen?: boolean | 'sm-down' | 'md-down' | 'lg-down' | 'xl-down' | 'xxl-down';
+  focus?: boolean;
+  keyboard?: boolean;             // Esc key closes modal
+}
+
+interface ModalData<T = any> {
+  data?: T;
+}
+
+interface ModalResult<T = any> {
+  reason: ModalCloseReason;
+  data?: T;
+}
+```
+
+---
+
+## ModalService — Programmatic API
+
+```typescript
+import { ModalService } from '@open-rlb/ng-bootstrap';
+
+@Component({ ... })
+export class MyComponent {
+  constructor(private modal: ModalService) {}
+
+  // Open a named modal (registered component)
+  openCustomModal() {
+    this.modal.openModal<InputData, OutputData>(
+      'my-modal-name',
+      { data: { userId: 42 } },
+      { size: 'lg', verticalcentered: true }
+    ).subscribe(result => {
+      if (result.reason === 'ok') {
+        console.log(result.data); // OutputData
+      }
+    });
+  }
+
+  // Simple info/alert modal
+  showAlert() {
+    this.modal.openSimpleModal(
+      'Title',
+      'Message body text.',
+      'Optional header',
+      'Close',          // ok button label
+      'info'            // ModalType
+    ).subscribe();
+  }
+
+  // Confirmation modal (ok + cancel)
+  confirmDelete() {
+    this.modal.openConfirmModal(
+      'Delete item?',
+      'This action cannot be undone.',
+      'Confirm',        // header
+      'Delete',         // ok label
+      'Cancel',         // cancel label
+      'warning'         // ModalType
+    ).subscribe(result => {
+      if (result.reason === 'ok') {
+        this.deleteItem();
+      }
+    });
+  }
+}
+```
+
+---
+
+## [rlb-modal] Directive — Declarative Usage
+
+```html
+<!-- Trigger button -->
+<button rlb-button color="primary" (click)="myModal.show()">Open Modal</button>
+
+<!-- Modal template -->
+<div rlb-modal id="my-modal" [data-instance]="myModal" [data-options]="modalOptions">
+  <div class="modal-header">
+    <h5 class="modal-title">Modal Title</h5>
+    <button type="button" class="btn-close" data-modal-reason="close"></button>
+  </div>
+  <div class="modal-body">
+    Modal body content here.
+  </div>
+  <div class="modal-footer">
+    <button rlb-button color="secondary" data-modal-reason="cancel">Cancel</button>
+    <button rlb-button color="primary" data-modal-reason="ok">Confirm</button>
+  </div>
+</div>
+```
+
+```typescript
+@Component({ ... })
+export class MyComponent {
+  myModal!: IModal;  // reference set by the directive
+  modalOptions: ModalOptions = {
+    size: 'md',
+    backdrop: 'static',
+    verticalcentered: true
+  };
+}
+```
+
+**Close reason attributes:** add `data-modal-reason="ok"`, `data-modal-reason="cancel"`, or `data-modal-reason="close"` to any button inside the modal to auto-close with that reason.
+
+---
+
+## Modal Events
+
+Listen to Bootstrap modal lifecycle events on the modal element:
+
+```typescript
+// 'show.bs.modal' | 'shown.bs.modal' | 'hide.bs.modal' | 'hidden.bs.modal' | 'hidePrevented.bs.modal'
+```
+
+---
+
+## Modal with Form
+
+Pattern for a modal that collects data and returns it on confirm:
+
+```typescript
+@Component({
+  template: `
+    <div rlb-modal id="edit-modal" [data-instance]="modal">
+      <div class="modal-header">
+        <h5 class="modal-title">Edit User</h5>
+        <button class="btn-close" data-modal-reason="close"></button>
+      </div>
+      <div class="modal-body">
+        <form [formGroup]="form">
+          <div class="mb-3">
+            <label class="form-label">Name</label>
+            <rlb-input formControlName="name" [enable-validation]="true"></rlb-input>
+          </div>
+        </form>
+      </div>
+      <div class="modal-footer">
+        <button rlb-button color="secondary" data-modal-reason="cancel">Cancel</button>
+        <button rlb-button color="primary" (click)="save()">Save</button>
+      </div>
+    </div>
+  `
+})
+export class EditModalComponent {
+  modal!: IModal;
+  form = new FormGroup({ name: new FormControl('') });
+
+  save() {
+    if (this.form.valid) {
+      this.modal.hide('ok');
+    }
+  }
+}
+```
+
+---
+
+## Multi-step (wizard) modal
+
+For a multi-step form inside a modal, put a **carousel driven as a controlled stepper** in the
+`modal-body` and Back / Next / Finish buttons in the `modal-footer`. The carousel runs in manual mode
+(`autoplay="none" no-touch hide-controls hide-indicators`); bind `[current-slide]` to a signal and
+update it from the buttons, gate `Next` on the current step's validity, and call `modal.hide('ok')`
+on finish. See the **Wizard pattern** in the `rlb-components` skill for the full carousel details.
+
+```html
+<div rlb-modal id="wizard-modal" [data-instance]="modal">
+  <div class="modal-header"><h5 class="modal-title">Create</h5>
+    <button class="btn-close" data-modal-reason="close"></button>
+  </div>
+  <div class="modal-body" [formGroup]="form">
+    <rlb-carousel autoplay="none" no-touch hide-controls hide-indicators
+      [current-slide]="page()" (current-slideChange)="page.set($event)"
+      (slide-count)="count.set($event)" id="wizard">
+      <rlb-carousel-slide active><div formGroupName="step1"><!-- … --></div></rlb-carousel-slide>
+      <rlb-carousel-slide><div formGroupName="step2"><!-- … --></div></rlb-carousel-slide>
+    </rlb-carousel>
+  </div>
+  <div class="modal-footer">
+    <button rlb-button [disabled]="page() === 0" (click)="prev()">Back</button>
+    @if (page() < count() - 1) {
+      <button rlb-button color="primary" [disabled]="currentStepInvalid()" (click)="next()">Next</button>
+    } @else {
+      <button rlb-button color="primary" [disabled]="form.invalid" (click)="onFinish()">Finish</button>
+    }
+  </div>
+</div>
+```
+
+---
+
+## ModalOptions Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `backdrop` | `boolean \| 'static'` | `true` | `'static'` prevents closing on backdrop click |
+| `scrollable` | `boolean` | `false` | Modal body scrolls independently |
+| `verticalcentered` | `boolean` | `false` | Vertically center modal |
+| `animation` | `boolean` | `true` | Fade animation |
+| `size` | `'sm'\|'md'\|'lg'\|'xl'` | `'md'` | Modal width |
+| `fullscreen` | `boolean\|string` | `false` | Full-screen mode |
+| `focus` | `boolean` | `true` | Auto-focus when opened |
+| `keyboard` | `boolean` | `true` | Esc closes modal |
+
+---
+
+## Best Practices
+
+1. Use `openConfirmModal()` for destructive actions — never skip a confirmation step.
+2. Use `backdrop: 'static'` for forms where accidental close would lose data.
+3. Subscribe to the modal result observable and handle all three reasons: `'ok'`, `'cancel'`, `'close'`.
+4. For complex modals with forms, use the declarative `[rlb-modal]` approach and control close programmatically after validation.
+5. Use `size: 'lg'` or `size: 'xl'` for forms with many fields; `size: 'sm'` for simple confirmations.