spiderly 19.8.4 → 19.8.5

package/agent/docs/angular-customization/SKILL.md

@@ -0,0 +1,389 @@
+---
+name: angular-customization
+description: Build, compose, or style any Spiderly Angular admin-panel UI — pages, cards, panels, dashboards, buttons, tables, dialogs, empty/loading states. Use to reuse existing Spiderly/PrimeNG components instead of hand-writing Tailwind/HTML, and when extending generated components, overriding form save behavior, configuring data tables, customizing layout/theme, or adding validators. For translating UI strings (Transloco, assets/i18n), use the frontend-localization skill.
+---
+
+# Angular Customization
+
+> **Scope:** Angular admin panel only — not storefront apps (Next.js + shadcn/Tailwind), where plain Tailwind is correct.
+
+## Reuse components before hand-writing UI
+
+Before building or restyling any admin UI, check for an existing component first. Prefer: **Spiderly (`spiderly-*`) → PrimeNG (`p-*`) → raw Tailwind/HTML.** Spiderly is built on PrimeNG, so the theme applies to both. See the catalogs below; unsure a wrapper exists? `grep -rE "selector:.*spiderly-" projects/spiderly/src/lib`.
+
+**Look before you build — don't force-fit a component you'd have to hack.** Raw Tailwind/HTML is correct for pure layout/spacing, one-off widgets with no component analog, or when forcing a component means fighting it. When you hand-roll, state in one line why no component fit.
+
+**Same rule for utility functions.** Before writing a formatting / date / file / dropdown-option helper, check the shared catalog — see [references/helper-functions.generated.md](references/helper-functions.generated.md) (from `helper-functions.ts`). Re-implementing `exportListToExcel`, `getPrimengDropdownNamebookOptions`, `kebabToTitleCase`, and friends is a common, avoidable duplication.
+
+Keep admin UI **responsive and mobile-first**, matching the layout/grid conventions of surrounding pages rather than inventing a new one.
+
+## Global loading & error handling — don't hand-roll either
+
+Two cross-cutting behaviors ship with every Spiderly admin and cover **every** generated-client call automatically. Re-implementing them per call is the most common needless boilerplate in admin code:
+
+- **Loading:** an HTTP interceptor shows the global full-screen blocking spinner for every request and hides it when the request settles. Read-shaped responses (autocomplete, dropdowns, table pagination, bare-scalar GETs) are exempted server-side via `[SkipSpinner]` inference — see the `custom-endpoints` skill to tune that per endpoint. Don't add per-component spinners around API calls; for layout placeholders use `card-skeleton` (catalog below).
+- **Errors:** an HTTP interceptor toasts every failed request — server-unreachable warning, the server's `BusinessException` message on 400, login/permission/not-found messages on 401/403/404, a generic error toast for the rest — then **rethrows**, so callers only ever run their success path. Uncaught non-HTTP runtime errors get a generic toast from the global `ErrorHandler`. So: **subscribe to the success path only** — no per-call `catchError` toasts, no `try/catch` around generated client calls. Add `catchError` only when you need to *react* to a specific failure (e.g. roll back optimistic UI state); the user-facing message has already been shown by the time your handler runs.
+
+## Generated File Structure
+
+```
+Frontend/src/app/business/
+├── entities/entities.generated.ts         # TypeScript DTOs
+├── services/api/api.service.generated.ts  # Typed API methods
+├── components/base-details.generated.ts   # Entity form components
+├── services/validators/validators.generated.ts
+└── enums/enums.generated.ts
+```
+
+Never modify `.generated.ts` files — they regenerate on build.
+
+## Form System
+
+### Inheritance Chain
+
+```
+BaseFormComponent<TMainUIForm, TSaveBody>  (Spiderly library)
+        ↓
+{Entity}BaseDetailsComponent          (generated)
+        ↓
+{Entity}DetailsComponent              (your code)
+```
+
+### Save Flow (execution order)
+
+```
+1. onSave(rerouteToParentSlugAfterSave)
+2.   → Build saveBody from form raw values
+3.   → onBeforeSave(saveBody)        ← mutate saveBody here
+4.   → baseFormService.isControlValid()
+5.   → saveObservableMethod(saveBody)  (HTTP PUT)
+6.   → onAfterSaveRequest()
+7.   → Success toast + reroute
+8.   → onAfterSave()
+```
+
+### Overridable Hooks
+
+```typescript
+export class ProductDetailsComponent
+  extends BaseFormComponent<ProductMainUIForm, ProductSaveBody>
+  implements OnInit
+{
+  override mainUIFormClass = ProductMainUIForm;
+  override saveBodyClass = ProductSaveBody;
+
+  override onBeforeSave = (saveBody?: ProductSaveBody) => {
+    saveBody.productDTO.stock =
+      saveBody.orderedProductVariantsSaveBodyDTO.reduce(
+        (sum, v) => sum + (v.productVariantDTO.stock ?? 0),
+        0,
+      );
+  };
+
+  override onAfterSave = () => {
+    this.refreshRelatedData();
+  };
+
+  override rerouteToSavedObject = (rerouteId: number | string) => {
+    this.router.navigateByUrl(`/custom-path/${rerouteId}`);
+  };
+}
+```
+
+### Key Form Classes
+
+```typescript
+SpiderlyFormControl<T> extends FormControl<T>
+  label: string              // Untranslated name
+  labelForDisplay: string    // Translated label
+  required: boolean
+  type: string               // 'number', 'Date', 'Namebook[]'
+  validator: SpiderlyValidatorFn | null
+
+SpiderlyFormGroup<T> extends FormGroup
+  controls: SpiderlyControlsOfType<T>
+  targetClass: SchemaAwareConstructor<T>
+  getControl(formControlName): SpiderlyFormControl
+
+SpiderlyFormArray<T> extends FormArray
+  formGroupInitialValues: Partial<T>
+  targetClass: SchemaAwareConstructor<T>
+  getCrudMenuForOrderedData(): MenuItem[]  // Remove, AddAbove, AddBelow
+  addNewFormGroup(index)
+  getFormGroups(): SpiderlyFormGroup<T>[]
+```
+
+### DTO Mapping
+
+- `MainUIFormDTO` — what the API returns (read)
+- `SaveBodyDTO` — what you send to API (write)
+- `baseFormService.mapMainUIFormToSaveBody()` handles conversion automatically
+- Naming convention: `orderedItemsMainUIFormDTO` → `orderedItemsSaveBodyDTO`
+
+### Conditional visibility (`show*` inputs)
+
+Every property block the generator emits into `{Entity}BaseDetailsComponent` is wrapped in `*ngIf="show{PropertyName}For{EntityName}"`, and each is exposed as an `@Input()` defaulting to `true`. Bind it from your `{Entity}DetailsComponent` template to show/hide a field — conditionally or statically — without editing generated code:
+
+```html
+<user-base-details
+  [parentFormGroup]="parentFormGroup"
+  [showIsDisabledForUser]="isAdmin"          <!-- show a field only when a condition holds -->
+  [showEmailForUser]="false"                 <!-- hide a field outright -->
+  [showTimeOnBirthDateForUser]="true"        <!-- calendar control: also render the time picker -->
+  (onSave)="onSave()"
+></user-base-details>
+```
+
+Names are PascalCase: `show{PropertyName}For{EntityName}` (plus `showTimeOn{PropertyName}For{EntityName}` for calendar controls).
+
+Library components/controls also expose their own `show*` `@Input()`s (e.g. `showLabel` on every control, `showAddButton` on the data table, `showPanelHeader` on the panel) — each a plain boolean, bound the same way: `[showAddButton]="canCreate"`. See the *UI Controls Reference* and *Presentational & Layout Components* tables below for the available inputs.
+
+## Data Table
+
+### Lazy Load Mode (server-side pagination, default)
+
+```html
+<spiderly-data-table
+  [cols]="cols"
+  [getPaginatedListObservableMethod]="getPaginatedProductListMethod"
+  [additionalFilterIdLong]="categoryId"
+  [navigateOnRowClick]="true"
+  [rowNavigationPath]="'/product-list'"
+>
+</spiderly-data-table>
+```
+
+### Client-Side Mode
+
+```html
+<spiderly-data-table [cols]="cols" [items]="localItems" [hasLazyLoad]="false">
+</spiderly-data-table>
+```
+
+### Column Definition
+
+```typescript
+cols: Column<ProductDTO>[] = [
+  new Column({ field: 'title', name: 'Title', filterType: 'text' }),
+  new Column({ field: 'price', name: 'Price', filterType: 'numeric', showMatchModes: true, decimalPlaces: 2 }),
+  new Column({ field: 'createdAt', name: 'Created', filterType: 'date', showTime: true }),
+  new Column({ field: 'isActive', name: 'Active', filterType: 'boolean' }),
+  new Column({ field: 'categoryDisplayName', name: 'Category', filterType: 'multiselect',
+    dropdownOrMultiselectValues: this.categoryOptions }),
+  new Column({
+    actions: [
+      new Action({ field: 'Details', icon: 'pi pi-pencil' }),
+      new Action({ field: 'Delete' }),
+      new Action({ field: 'custom', name: 'Clone', icon: 'pi pi-copy', onClick: (e) => this.clone(e.id) }),
+    ]
+  }),
+];
+```
+
+The `onClick` callback receives an `ActionClickEvent` — `{ id, row, element, originalEvent }`. Use `element` (or `originalEvent`) to anchor an overlay/popover to the clicked action; `row` gives you the full row object. It fires only for custom `field` values (never `'Details'` / `'Delete'`).
+
+### Key Inputs
+
+| Input                              | Type                     | Default | Purpose                 |
+| ---------------------------------- | ------------------------ | ------- | ----------------------- |
+| `cols`                             | `Column[]`               | —       | Column definitions      |
+| `getPaginatedListObservableMethod` | `(filter) => Observable` | —       | Server-side data source |
+| `additionalFilterIdLong`           | `number`                 | —       | Parent entity filter    |
+| `hasLazyLoad`                      | `boolean`                | `true`  | Server vs client mode   |
+| `items`                            | `any[]`                  | —       | Client-side data        |
+| `selectionMode`                    | `'single' \| 'multiple'` | —       | Selection mode          |
+| `navigateOnRowClick`               | `boolean`                | `false` | Click row → details     |
+| `rowNavigationPath`                | `string`                 | —       | Base path for row click |
+| `showAddButton`                    | `boolean`                | `true`  | Show "New" button       |
+| `showExportToExcelButton`          | `boolean`                | `true`  | Show Excel export       |
+| `readonly`                         | `boolean`                | `false` | Disable mutations       |
+
+### Key Outputs
+
+| Output                  | Payload         | Purpose               |
+| ----------------------- | --------------- | --------------------- |
+| `onRowSelect`           | `RowClickEvent` | Row selected          |
+| `onRowUnselect`         | `RowClickEvent` | Row deselected        |
+| `onIsAllSelectedChange` | `AllClickEvent` | Select-all toggled    |
+| `onTotalRecordsChange`  | `number`        | Total records updated |
+
+## Service Overrides
+
+### ConfigServiceBase
+
+```typescript
+@Injectable({ providedIn: "root" })
+export class ConfigService extends ConfigServiceBase {
+  override logoPath = "assets/images/my-logo.png";
+  override companyName = "My Company";
+  override primaryColor = "#3B82F6";
+  override defaultPageSize = 25;
+  override loginSlug = "sign-in";
+  override showGoogleAuth = true;
+}
+```
+
+Key properties: `apiUrl`, `frontendUrl`, `GoogleClientId`, `companyName`, `primaryColor`, `logoPath`, `defaultPageSize`, `loginSlug`, `showGoogleAuth`.
+
+### AuthServiceBase
+
+Override hooks for custom post-auth behavior:
+
+```typescript
+export class AuthService extends AuthServiceBase {
+  override onAfterLoginExternal = () => {
+    this.analyticsService.trackLogin("google");
+  };
+
+  override onAfterLogout = () => {
+    this.cacheService.clear();
+  };
+
+  override onAfterRefreshToken = () => {
+    this.syncPermissions();
+  };
+}
+```
+
+Key observables: `user$` (current user), `currentUserPermissionCodes$` (permission codes).
+
+### LayoutServiceBase
+
+```typescript
+export class LayoutService extends LayoutServiceBase {
+  override initTopBarData(): Observable<InitTopBarData> {
+    return this.apiService.getTopBarData().pipe(
+      map(data => new InitTopBarData({ ... }))
+    );
+  }
+}
+```
+
+#### Theme Configuration (AppConfig)
+
+```typescript
+layoutConfig: AppConfig = {
+  inputStyle: "outlined", // 'outlined' | 'filled'
+  colorScheme: "light", // 'light' | 'dark'
+  menuMode: "static", // 'static' | 'overlay'
+  scale: 14, // Font scale
+  ripple: false,
+  theme: "lara-light-indigo",
+  color: "var(--p-primary-color)",
+};
+```
+
+## Layout & Menu
+
+### SpiderlyMenuItem
+
+```typescript
+interface SpiderlyMenuItem extends PrimeNG.MenuItem {
+  hasPermission?: (permissionCodes: string[]) => boolean;
+  showPartnerDialog?: boolean;
+}
+```
+
+### Menu Setup
+
+```typescript
+// In layout.component.ts:
+menu: SpiderlyMenuItem[] = [
+  {
+    label: this.translocoService.translate('Dashboard'),
+    icon: 'pi pi-fw pi-home',
+    routerLink: ['/dashboard'],
+  },
+  {
+    label: this.translocoService.translate('Products'),
+    icon: 'pi pi-fw pi-box',
+    items: [
+      { label: 'All Products', routerLink: ['/product-list'] },
+      { label: 'Categories', routerLink: ['/category-list'] },
+    ],
+  },
+];
+```
+
+### Layout Template
+
+```html
+<!-- Side menu (default) -->
+<spiderly-layout [menu]="menu" [isSideMenuLayout]="true">
+  <router-outlet></router-outlet>
+</spiderly-layout>
+
+<!-- Top menu -->
+<spiderly-layout [menu]="menu" [isSideMenuLayout]="false">
+  <router-outlet></router-outlet>
+</spiderly-layout>
+```
+
+## Validation
+
+### ValidatorAbstractService
+
+Subclass to add custom validators per entity/field:
+
+```typescript
+@Injectable({ providedIn: "root" })
+export class MyValidatorService extends ValidatorAbstractService {
+  setValidator(
+    control: SpiderlyFormControl,
+    className: string,
+  ): SpiderlyValidatorFn {
+    if (className === "Product" && control.label === "sku") {
+      const validator: SpiderlyValidatorFn = (): ValidationErrors | null => {
+        const value = control.value as string;
+        if (value && !value.match(/^[A-Z0-9]{6,12}$/))
+          return { _: this.translocoService.translate("InvalidSKU") };
+        return null;
+      };
+      control.validator = validator;
+    }
+    return control.validator;
+  }
+
+  setFormArrayValidator(formArray: SpiderlyFormArray, className: string): void {
+    if (className === "OrderItems") {
+      this.isFormArrayEmpty(formArray);
+    }
+  }
+}
+```
+
+### Built-in Validators
+
+The built-in validators on `ValidatorAbstractService` (with signatures) are generated from the class: see [references/validators.generated.md](references/validators.generated.md).
+
+## Translations
+
+UI string translation — Transloco setup, `assets/i18n/{lang}.json` files, `translocoService.translate` / the `*transloco` template directive, and form label auto-translation (`getTranslatedLabel`) — is covered by the dedicated **frontend-localization** skill. For server-side (.NET) strings, see **backend-localization**.
+
+## UI Controls Reference
+
+Two generated references cover the controls:
+
+- **Control type codes** — what you pass to `[UIControlType(nameof(UIControlTypeCodes.X))]`, and the property type each is auto-selected for: [references/ui-control-types.generated.md](references/ui-control-types.generated.md).
+- **Control components** — each `spiderly-*` selector, its component class, control-specific `@Input()`s, and the shared `BaseControl` inputs: [references/controls.generated.md](references/controls.generated.md).
+
+## Presentational & Layout Components
+
+Reach for these before hand-rolling cards, panels, buttons, lists, or empty/loading states.
+
+| Component           | Selector                                     | Purpose                                                                 | Key inputs                                                                                                                    |
+| ------------------- | -------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Card                | `spiderly-card`                              | Titled content container with icon                                      | `title`, `icon`                                                                                                               |
+| Panel               | `spiderly-panel`                             | Collapsible section, supports multi-panel grouping + CRUD menu          | `toggleable`, `collapsed`, `crudMenu`, `showRemoveIcon`, `isFirstMultiplePanel`/`isMiddleMultiplePanel`/`isLastMultiplePanel` |
+| Panel parts         | `panel-header`, `panel-body`, `panel-footer` | Compose a panel's regions                                               | (slotted content)                                                                                                             |
+| Info card           | `info-card`                                  | Inline informational/callout box                                        | `header`, `icon`, `showSmallIcon`, `textColor`                                                                                |
+| Index card          | `index-card`                                 | Ordered list item with index + CRUD menu                                | `index`, `header`, `description`, `crudMenu`, `showRemoveIcon`, `last`                                                        |
+| Card skeleton       | `card-skeleton`                              | **Loading placeholder** — use instead of a hand-rolled spinner/skeleton | `height`                                                                                                                      |
+| Button              | `spiderly-button`                            | Themed button                                                           | `type` (`button`/`submit`/`reset`)                                                                                            |
+| Split button        | `spiderly-split-button`                      | Button with dropdown menu                                               | `dropdownItems`                                                                                                               |
+| Return button       | `return-button`                              | Back-navigation button                                                  | `navigateUrl`                                                                                                                 |
+| Data view           | `spiderly-data-view`                         | Card/grid list with filters + pagination (vs. table)                    | `items`, `rows`, `filters`, `getPaginatedListObservableMethod`, `showCardWrapper`                                             |
+| Delete confirmation | `spiderly-delete-confirmation`               | Standard delete-confirm dialog                                          | —                                                                                                                             |
+| Not found           | `not-found`                                  | **Empty / 404 state** — use instead of a hand-rolled empty state        | —                                                                                                                             |
+
+For data lists, use `spiderly-data-table` (tabular — see Data Table section) or `spiderly-data-view` (card/grid) — don't build either from scratch.

package/agent/docs/angular-customization/references/controls.generated.md

@@ -0,0 +1,23 @@
+<!-- GENERATED FROM framework-metadata.json — DO NOT EDIT.
+     Regenerate: `dotnet run --project Spiderly.MetadataExporter -- --out framework-metadata.json && node tools/extract-ts-metadata.mjs && node tools/gen-skill-docs.mjs` -->
+
+# Form control components
+
+Every control also accepts the shared `BaseControl` inputs: `control`, `controlValid`, `disabled`, `label`, `placeholder`, `showLabel`, `showRequired`, `showTooltip`, `tooltipIcon`, `tooltipText`.
+
+| Selector | Component | Control-specific inputs |
+| --- | --- | --- |
+| `spiderly-autocomplete` | `SpiderlyAutocompleteComponent` | `appendTo`, `showClear`, `emptyMessage`, `displayName` |
+| `spiderly-calendar` | `SpiderlyCalendarComponent` | `showTime`, `dateOnly`, `timeOnly` |
+| `spiderly-checkbox` | `SpiderlyCheckboxComponent` | `fakeLabel`, `initializeToFalse`, `inlineLabel` |
+| `spiderly-colorpicker` | `SpiderlyColorPickerComponent` | `showInputTextField` |
+| `spiderly-dropdown` | `SpiderlyDropdownComponent` | `isBooleanPicker` |
+| `spiderly-editor` | `SpiderlyEditorComponent` | `uploadImageMethod`, `objectId` |
+| `spiderly-file` | `SpiderlyFileComponent` | `objectId`, `fileData`, `acceptedFileTypes`, `required`, `multiple`, `isUrlFileData`, `imageWidth`, `imageHeight`, `maxFileSize`, `files` |
+| `spiderly-markdown` | `SpiderlyMarkdownComponent` | `uploadImageMethod`, `objectId` |
+| `spiderly-multiautocomplete` | `SpiderlyMultiAutocompleteComponent` | — |
+| `spiderly-multiselect` | `SpiderlyMultiSelectComponent` | — |
+| `spiderly-number` | `SpiderlyNumberComponent` | `prefix`, `showButtons`, `decimal`, `maxFractionDigits` |
+| `spiderly-password` | `SpiderlyPasswordComponent` | `showPasswordStrength` |
+| `spiderly-textarea` | `SpiderlyTextareaComponent` | — |
+| `spiderly-textbox` | `SpiderlyTextboxComponent` | `showButton`, `buttonIcon` |

package/agent/docs/angular-customization/references/helper-functions.generated.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM framework-metadata.json — DO NOT EDIT.
+     Regenerate: `dotnet run --project Spiderly.MetadataExporter -- --out framework-metadata.json && node tools/extract-ts-metadata.mjs && node tools/gen-skill-docs.mjs` -->
+
+# Shared helper functions
+
+Reusable helpers exported from `helper-functions.ts`. Import the one you need instead of re-implementing it.
+
+| Signature | Description |
+| --- | --- |
+| `ReflectProp(target: any, propertyKey: string)` |  |
+| `adjustColor(color: string, percent: number): string` |  |
+| `capitalizeFirstChar(str: string): string` |  |
+| `deleteAction(cols: Column[], actionField: string): void` |  |
+| `exportListToExcel(exportListToExcelObservableMethod: (filter: Filter) => Observable<any>, filter: Filter)` |  |
+| `firstCharToUpper(input: string): string` |  |
+| `getFileNameFromContentDisposition(resp: HttpResponse<Blob>, defaultName: string): string` |  |
+| `getHtmlImgDisplayString64(base64String: string)` |  |
+| `getImageDimensions(file: File): Promise<{ width: number; height: number }>` |  |
+| `getMimeTypeForFileName(fileName: string): string` |  |
+| `getMonth(numberOfTheMonth: number): string` |  |
+| `getParentUrl(currentUrl: string)` |  |
+| `getPrimengAutocompleteCodebookOptions(getAutocompleteListObservable: ( limit: number, query: string, ) => Observable<Codebook[]>, limit: number, query: string): Observable<PrimengOption[]>` |  |
+| `getPrimengAutocompleteNamebookOptions(getAutocompleteListObservable: ( limit: number, query: string, parentEntityId?: number, ) => Observable<Namebook[]>, limit: number, query: string, parentEntityId?: number): Observable<PrimengOption[]>` |  |
+| `getPrimengDropdownCodebookOptions(getDropdownListObservable: () => Observable<Codebook[]>): Observable<PrimengOption[]>` |  |
+| `getPrimengDropdownNamebookOptions(getDropdownListObservable: ( parentEntityId?: number, ) => Observable<Namebook[]>, parentEntityId?: number): Observable<PrimengOption[]>` |  |
+| `getPrimengNamebookOptions(namebookList: Namebook[]): PrimengOption[]` |  |
+| `isExcelFileType(mimeType: string): boolean` |  |
+| `isFileImageType(mimeType: string): boolean` |  |
+| `isNullOrEmpty(input: string)` |  |
+| `kebabToTitleCase(input: string): string` |  |
+| `nameOf<TObject extends { name: S }, S extends string>(funcOrClass: TObject): S` |  |
+| `nameof(key1: any, key2?: any): any` |  |
+| `parseDateOnlyLocal(s: string): Date \| null` |  |
+| `pushAction(cols: Column[], action: Action)` |  |
+| `selectedTab(tabs: SpiderlyTab[]): number` |  |
+| `singleOrDefault<T>(array: T[], predicate: (item: T) => boolean): T \| undefined` |  |
+| `splitPascalCase(input: string)` |  |
+| `toCommaSeparatedString<T>(input: T[]): string` |  |
+| `validatePrecisionScale(value: any, precision: number, scale: number, ignoreTrailingZeros: boolean): boolean` |  |

package/agent/docs/angular-customization/references/ui-control-types.generated.md

@@ -0,0 +1,24 @@
+<!-- GENERATED FROM framework-metadata.json — DO NOT EDIT.
+     Regenerate: `dotnet run --project Spiderly.MetadataExporter -- --out framework-metadata.json && node tools/extract-ts-metadata.mjs && node tools/gen-skill-docs.mjs` -->
+
+# UI control types
+
+Defines the UI control types used by the Angular code generator to render form fields. Each value maps to a spiderly-* Angular component built on PrimeNG. Most types are automatically picked based on the property type, but you can override them with the [UIControlType] attribute:
+
+| Name | Description |
+| --- | --- |
+| `Decimal` | Numeric input for decimal/floating-point values. Renders spiderly-number with fraction digits enabled. Auto-detected for: decimal, decimal?, float, float?, double, double? |
+| `File` | File upload control. Renders spiderly-file with support for image preview and dimension validation. Auto-detected for: properties decorated with any subclass of StorageAttribute (e.g. [DiskStorage], [S3PublicStorage], [S3PrivateStorage]). |
+| `Dropdown` | Single-selection dropdown list. Renders spiderly-dropdown. Must be set explicitly via attribute. Commonly used for many-to-one navigation properties when you want a dropdown instead of the default autocomplete. |
+| `TextArea` | Multi-line text input. Renders spiderly-textarea at full width. Must be set explicitly via attribute. Useful for longer plain-text content. |
+| `Autocomplete` | Single-selection with search/autocomplete capability. Renders spiderly-autocomplete. Auto-detected for: many-to-one navigation properties (the generator creates a search method for this field). |
+| `TextBox` | Single-line text input. Renders spiderly-textbox. Auto-detected for: string properties (default for strings). |
+| `CheckBox` | Boolean toggle control. Renders spiderly-checkbox. Auto-detected for: bool, bool? |
+| `Calendar` | Date/time picker. Renders spiderly-calendar with optional time selection. Auto-detected for: DateTime, DateTime? |
+| `Integer` | Numeric input for whole numbers. Renders spiderly-number without fraction digits. Auto-detected for: int, int?, long, long?, byte, byte? |
+| `ColorPicker` | Visual color picker. Renders spiderly-colorpicker with optional hex text input. Must be set explicitly via attribute. Stores the color as a hex string. |
+| `Editor` | Rich text HTML editor. Renders spiderly-editor (Quill-based) at full width. Must be set explicitly via attribute. The value is stored as HTML. |
+| `Markdown` | Markdown editor. Renders spiderly-markdown at full width — a plain textarea with a live "Preview" tab. The value is stored as raw Markdown text. Must be set explicitly via attribute. Pasting an image uploads it (when the property has an [S3PublicStorage] attribute) and inserts a standard ![](url) link; the preview is rendered with marked and is approximate vs. a consuming storefront's renderer. |
+| `MultiAutocomplete` | Multi-selection with search/autocomplete capability. Renders spiderly-multiautocomplete at full width. Used for many-to-many relationships where items are selected via search. |
+| `MultiSelect` | Multi-selection dropdown list. Renders spiderly-multiselect at full width. Used for many-to-many relationships where all options are shown in a dropdown. |
+| `Password` | Masked password input. Renders spiderly-password with optional strength indicator. Must be set explicitly via attribute. |

package/agent/docs/angular-customization/references/validators.generated.md

@@ -0,0 +1,13 @@
+<!-- GENERATED FROM framework-metadata.json — DO NOT EDIT.
+     Regenerate: `dotnet run --project Spiderly.MetadataExporter -- --out framework-metadata.json && node tools/extract-ts-metadata.mjs && node tools/gen-skill-docs.mjs` -->
+
+# Built-in validators
+
+Built-in validators on `ValidatorAbstractService` (call from your `setValidator` / `setFormArrayValidator` override).
+
+| Validator | Description |
+| --- | --- |
+| `isArrayEmpty(control: SpiderlyFormControl): SpiderlyValidatorFn` | Validates that a SpiderlyFormControl holding an array value (e.g., multi-select dropdown) is not empty. |
+| `isFormArrayEmpty(control: SpiderlyFormArray): void` | Validates that a SpiderlyFormArray (collection of form controls/groups) is not empty. |
+| `notEmpty(control: SpiderlyFormControl): void` |  |
+| `validateImageDimensions(file: File, imageWidth: number, imageHeight: number): Promise<ImageDimensionsValidationResult>` |  |