@ng-solid/design-system 22.3.0 → 22.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-solid/design-system",
-  "version": "22.3.0",
+  "version": "22.4.0",
   "license": "MIT",
   "description": "Arvisfy, the token-driven Angular design system for ng-solid.",
   "author": "Ulises Familia Rodríguez <chicromedia@hotmail.com>",

package/themes/README.md

@@ -53,11 +53,51 @@ export const ProductTheme = defineNsPreset(Arvisfy, {
 
 Tailwind utilities are composed from SCSS, never placed in ng-solid component
 templates. Consumers that want the same semantic utility bridge may import
-`@ng-solid/design-system/themes/tailwind.css` after Tailwind.
+`@ng-solid/design-system/themes/tailwind.css` after Tailwind; doing so also
+applies the box-sizing contract described below, though the kit assumes that
+contract regardless of whether the bridge is imported (see "Box model").
 
 Every component stylesheet starts with `@reference` to that bridge and reads
 only `--ns-component-*` variables for component-specific visual decisions.
 
+## Box model
+
+Arvisfy assumes `box-sizing: border-box` everywhere. `theme/tailwind.css`
+restates the `box-sizing` declaration from Tailwind v4's preflight, on that
+preflight's exact selector:
+
+```css
+*,
+::before,
+::after,
+::backdrop,
+::file-selector-button {
+  box-sizing: border-box;
+}
+```
+
+It is copied literally rather than `@import`ed, because ng-packagr ships this
+file as a plain asset — an `@import` would reach the consumer unresolved. The
+rest of preflight's box-sizing block (`margin/padding/border: 0` on every
+element) is intentionally left out: unlike this single, additive rule, it is
+destructive to markup that doesn't expect it.
+
+Three properties follow from that choice:
+
+- **Idempotent.** Applications that already load Tailwind's own preflight (or
+  any other reset that sets the same rule) see no change — selector and
+  declaration are identical.
+- **Zero added specificity.** The universal selector `*` (and the
+  pseudo-elements listed alongside it) contributes no specificity, so any
+  consumer rule, however plain, overrides it trivially. It is a default, not
+  an imposition.
+- **Opt-in scope.** Consumers who don't import the bridge are covered only
+  where a component's own SCSS declares `box-sizing` locally; the
+  workspace-wide default lives solely inside `tailwind.css`.
+
+An audit across 53 playground pages found that adopting this rule eliminated
+17 real overflow bugs and introduced none.
+
 ## HeroUI foundations
 
 Arvisfy vendors Inter Variable in `theme/fonts/InterVariable.woff2` (with its
@@ -73,3 +113,34 @@ maps to `light`. Components own their state tokens (for example
 `--ns-component-slider-*` and `--ns-component-input-search-*`) rather than
 borrowing another component's variables; use the matching family when adding
 a visual decision.
+
+## Retired tokens
+
+A token is retired when no component stylesheet reads its `--ns-component-*`
+variable anymore, but it still ships as a published field of the preset —
+removing the field outright would silently break any consumer override that
+still targets it. `NsTokenTree` has an open index signature, so an override
+of a retired (or otherwise unknown) key merges in cleanly with no type error
+and no `validateNsPreset` error; it just has no effect.
+
+To surface that instead of letting it fail silently, `theme/utils/theme.utils.ts`
+keeps a small internal `NS_RETIRED_TOKENS` map of retired token paths to a
+warning message, and `validateNsPreset` emits a `console.warn` for each one
+still present in the resolved preset. This does not throw — an inert override
+should not crash a consumer's app — and it is not deduplicated across calls,
+so it warns every time a preset containing the retired path is validated.
+
+The registry lives inside `theme.utils.ts` itself rather than its own file:
+`packages/mcp`'s data extraction transpiles that file in isolation and cannot
+resolve a relative value import from a sibling module at that point (see
+`assertNoValueImports` in `packages/mcp/scripts/lib/extract-tokens.mjs`), so a
+separate `retired-tokens.ts` imported for its data would break
+`nx run mcp:build-data`.
+
+Currently retired:
+
+- `components.imageUpload.thumbnailSize` — used to size each stack thumbnail
+  and (indirectly) the height of `ns-image-upload[layout="cover"]`. Since the
+  height fix in AVF-29, `components.imageUpload.emptyMinHeight` alone sizes
+  that layout in both its empty and filled states, and no stylesheet reads
+  `--ns-component-image-upload-thumbnail-size` anymore.

package/themes/tailwind.css

@@ -1,3 +1,18 @@
+/* This bridge ships as a raw asset (ng-package.json) and ng-packagr copies it
+   byte-for-byte to consumers, with no PostCSS pass — so it cannot `@import`
+   Tailwind's preflight (that import would reach consumers unresolved).
+   Instead this literally reproduces just the `box-sizing: border-box` line
+   from Tailwind v4's preflight (node_modules/tailwindcss/preflight.css),
+   intentionally omitting the accompanying margin/padding/border reset, which
+   would be destructive to existing markup. */
+*,
+::before,
+::after,
+::backdrop,
+::file-selector-button {
+  box-sizing: border-box;
+}
+
 @font-face {
   font-family: 'Inter Variable';
   font-style: normal;

package/types/ng-solid-design-system.d.ts

@@ -122,7 +122,7 @@ declare class NsBreadcrumbsComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsBreadcrumbsComponent, "ns-breadcrumbs", never, { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
-type NsButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'success' | 'danger';
+type NsButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'success' | 'danger' | 'dark';
 declare class NsButtonComponent {
     readonly type: _angular_core.InputSignal<"button" | "submit" | "reset">;
     readonly variant: _angular_core.InputSignal<NsButtonVariant>;
@@ -199,7 +199,7 @@ type NsChipColor = NsColor | 'info' | 'selected';
  * `ns-chip` and intentionally not added to the shared `NsVariant` union.
  */
 type NsChipVariant = Exclude<NsVariant, 'ghost'> | 'tint';
-type NsChipSize = 'md' | 'pill';
+type NsChipSize = 'md' | 'pill' | 'choice';
 declare class NsChipComponent {
     readonly color: _angular_core.InputSignal<NsChipColor>;
     readonly variant: _angular_core.InputSignal<NsChipVariant>;
@@ -505,6 +505,7 @@ declare class NsEditorColorPickerComponent implements OnInit {
     private editor;
     readonly presets: _angular_core.InputSignal<string[][]>;
     readonly type: _angular_core.InputSignal<"text_color" | "background_color">;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     showPopup: boolean;
     activeColor?: string;
     isActive: boolean;
@@ -516,10 +517,23 @@ declare class NsEditorColorPickerComponent implements OnInit {
     onColorSelect(color: string): void;
     remove(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NsEditorColorPickerComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEditorColorPickerComponent, "ns-editor-color-picker", never, { "presets": { "alias": "presets"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEditorColorPickerComponent, "ns-editor-color-picker", never, { "presets": { "alias": "presets"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+declare class NsEditorImageComponent implements OnInit {
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    formImage: FormGroup;
+    show: boolean;
+    private fb;
+    private editor;
+    ngOnInit(): void;
+    insert(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NsEditorImageComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEditorImageComponent, "ns-editor-image", never, { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 declare class NsEditorLinkComponent implements OnInit {
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     formLink: FormGroup;
     show: boolean;
     private fb;
@@ -527,7 +541,7 @@ declare class NsEditorLinkComponent implements OnInit {
     ngOnInit(): void;
     insert(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NsEditorLinkComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEditorLinkComponent, "ns-editor-link", never, {}, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEditorLinkComponent, "ns-editor-link", never, { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 declare enum Commands {
@@ -554,29 +568,32 @@ declare enum Commands {
 
 declare class NsEditorListComponent implements OnInit {
     private editor;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     commands: typeof Commands;
     ngOnInit(): void;
     command(name: Commands): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NsEditorListComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEditorListComponent, "ns-editor-list", never, {}, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEditorListComponent, "ns-editor-list", never, { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 declare class NsEditorParagraphComponent {
     private editor;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     id: string;
     private _value;
     get value(): string;
     set value(heading: string);
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NsEditorParagraphComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEditorParagraphComponent, "ns-editor-paragraph", never, {}, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEditorParagraphComponent, "ns-editor-paragraph", never, { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 declare class NsEditorToggleCommandComponent {
     private editor;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     commands: typeof Commands;
     command(name: Commands): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NsEditorToggleCommandComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEditorToggleCommandComponent, "ns-editor-toggle", never, {}, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEditorToggleCommandComponent, "ns-editor-toggle", never, { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 declare abstract class NsValueAccessor<T = string> implements ControlValueAccessor {
@@ -829,6 +846,7 @@ declare class NsInputNumberComponent extends NsValueAccessor<number | null> {
     readonly currency: _angular_core.InputSignal<string>;
     readonly format: _angular_core.InputSignal<Intl.NumberFormatOptions>;
     readonly displayValue: _angular_core.WritableSignal<string>;
+    readonly currencyPrefix: _angular_core.Signal<string>;
     writeValue(value: number | null): void;
     onInput(text: string): void;
     onInputEvent(event: Event): void;
@@ -836,6 +854,7 @@ declare class NsInputNumberComponent extends NsValueAccessor<number | null> {
     onKeydown(event: KeyboardEvent): void;
     stepBy(direction: 1 | -1): void;
     private get formatter();
+    private formatDisplayValue;
     private parse;
     private constrain;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NsInputNumberComponent, never>;
@@ -954,9 +973,16 @@ declare class NsContentEditableComponent extends NsValueAccessor<string> {
     private elementRef;
     private renderer;
     readonly maxLength: _angular_core.InputSignal<number>;
+    /**
+     * Character count of the rendered content, measured the same way the
+     * `maxlength` guard below measures it (`innerText.length`) so a consumer's
+     * counter never drifts from what actually blocks typing.
+     */
+    readonly length: _angular_core.WritableSignal<number>;
     enabled: boolean;
     writeValue(value: string): void;
     onInput(): void;
+    private updateLength;
     onBlur(): void;
     onKeyUp(event: KeyboardEvent): void;
     setDisabledState(isDisabled: boolean): void;
@@ -982,22 +1008,28 @@ declare class NsFieldDirective {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NsFieldDirective, "[nsField]", never, { "controlId": { "alias": "nsField"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+type NsEditorTool = 'paragraph' | 'format' | 'color' | 'list' | 'link' | 'image' | 'separator';
+declare const NS_EDITOR_TOOLS_DEFAULT: readonly NsEditorTool[];
 declare class NsEditorComponent extends NsValueAccessor<string> implements OnInit, OnDestroy {
     private editor;
-    readonly rows: _angular_core.InputSignal<number>;
     readonly maxLength: _angular_core.InputSignal<number>;
     readonly colorPresets: _angular_core.InputSignal<string[]>;
+    readonly tools: _angular_core.InputSignal<readonly NsEditorTool[]>;
     textArea: ElementRef<HTMLElement>;
+    private contentEditable;
+    /** Mirrors the content-editable's own counter, measured off `innerText`. */
+    readonly length: _angular_core.Signal<number>;
+    readonly hasFooter: _angular_core.Signal<boolean>;
     focused: () => void;
     ngOnInit(): void;
     get presets(): string[][];
     blur(): void;
     ngOnDestroy(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NsEditorComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEditorComponent, "ns-editor", never, { "rows": { "alias": "rows"; "required": false; "isSignal": true; }; "maxLength": { "alias": "maxLength"; "required": false; "isSignal": true; }; "colorPresets": { "alias": "colorPresets"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEditorComponent, "ns-editor", never, { "maxLength": { "alias": "maxLength"; "required": false; "isSignal": true; }; "colorPresets": { "alias": "colorPresets"; "required": false; "isSignal": true; }; "tools": { "alias": "tools"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-type NsEmptyStateSize = 'sm' | 'md';
+type NsEmptyStateSize = 'sm' | 'md' | 'lg';
 declare class NsEmptyStateComponent {
     readonly title: _angular_core.InputSignal<string>;
     readonly description: _angular_core.InputSignal<string>;
@@ -1006,31 +1038,189 @@ declare class NsEmptyStateComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsEmptyStateComponent, "ns-empty-state", never, { "title": { "alias": "title"; "required": true; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; }, {}, never, ["[empty-state-icon]", "[empty-state-actions]"], true, never>;
 }
 
+/**
+ * No structural difference from `NsFile` — the guarantee this alias
+ * documents ("already has an entry in `uidRegistry`") lives in the registry,
+ * not on the object. Kept as a distinct name at call sites (`images()`,
+ * `image()`, `retry()`, `remove()`) that specifically require an image which
+ * has already been through `assignUid`.
+ */
+type TrackedFile = NsFile;
+/**
+ * Per-file upload status, keyed by `uid` (AVF-16). Replaces the old
+ * `loading: Set<string>` — a boolean set can't distinguish "still
+ * uploading" from "upload failed", which was the actual gap this HU closes.
+ * `'ok'` is set (not deleted) on success so a file that went through this
+ * component's own upload pipeline stays traceable; a file that arrived via
+ * `writeValue`/`[value]` and never uploaded here simply has no entry, which
+ * every template check (`=== 'subiendo'` / `=== 'fallido'`) already treats
+ * as the normal/idle state.
+ */
+type NsImageUploadFileStatus = 'subiendo' | 'ok' | 'fallido';
 declare class NsImageUploadComponent extends NsValueAccessor<NsFile | NsFile[] | null> {
     private client;
     private renderer;
+    private readonly cdr;
     readonly accept: _angular_core.InputSignal<string>;
     readonly multi: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly limit: _angular_core.InputSignalWithTransform<number, unknown>;
+    readonly layout: _angular_core.InputSignal<"grid" | "cover">;
+    /**
+     * Rows the `__stack` column reserves before it starts scrolling
+     * internally, in `layout="cover"`: at most 3, and never more than
+     * `limit() - 1` (the cover itself takes one slot).
+     */
+    readonly reservedRows: _angular_core.Signal<number>;
     imgRef: ElementRef<HTMLInputElement>;
-    loading: Set<string>;
+    status: Map<string, NsImageUploadFileStatus>;
+    /**
+     * Bumped by `setStatus`/`deleteStatus` on every `status` mutation.
+     * `status` itself stays a plain, publicly-mutable `Map` — kept for the
+     * existing per-file bookkeeping and for tests that poll it to synchronise
+     * with an async upload — but a plain `Map.set()`/`.delete()` is invisible
+     * to Angular's change detection: no signal write and no `markForCheck()`,
+     * so nothing tells Angular this control needs checking again. Worse, an
+     * `OnPush` ancestor that wasn't otherwise dirtied (e.g. the "Fotografías"
+     * `<card>` wrapping this control in the product form) can skip this
+     * subtree entirely on the next tick. That is exactly why a failed upload
+     * used to get stuck showing the spinner forever, silently (AVF-18
+     * corrección de rechazo #2): `status.set(uid, 'fallido')` ran, but nothing
+     * ever told Angular to look again — unlike a successful upload, which
+     * reaches the template through `value.set()` (a real signal write) via
+     * `assignValue`/`onChange`. `statusOf()` reads this counter before reading
+     * `status`, giving every render that goes through it a real signal
+     * dependency, and `touchStatus()` also calls `markForCheck()` directly —
+     * belt and braces: the explicit call is the same, long-proven mechanism
+     * Angular has always used to announce a change made from outside its own
+     * detection cycle (an RxJS subscription callback, here), and is what
+     * reliably walks the ancestor chain and clears an `OnPush` skip, the way
+     * a signal read alone was not enough to guarantee in practice.
+     */
+    private readonly statusVersion;
+    private touchStatus;
+    private setStatus;
+    private deleteStatus;
+    /**
+     * The only path from `status` + `uid` to the template — and the one every
+     * test should use too (AVF-18 corrección de rechazo #2): reading
+     * `status.get(...)` directly, the way earlier tests did, cannot tell a
+     * status change nobody announced to Angular from one that actually
+     * rendered, which is exactly how the previous regression shipped green —
+     * the map held `'fallido'`, the DOM still showed `'subiendo'`, and the
+     * assertions that read the map straight agreed with the bug.
+     */
+    statusOf(image: NsFile): NsImageUploadFileStatus | undefined;
+    /**
+     * Active while a file dragged from outside the browser (desktop, another
+     * app) hovers a drop zone — drives the highlight ring/border (AVF-9,
+     * criteria 3-5). Never set for the internal thumbnail-reorder drag,
+     * distinguished via `isFileDrag`.
+     */
+    readonly dragActive: _angular_core.WritableSignal<boolean>;
+    /**
+     * Inline, Spanish, component-owned notice for when a selection/drop
+     * exceeds `limit()` (AVF-16). Deliberately not an `output()`: a consumer
+     * that doesn't wire one up would silently drop files again, which is
+     * exactly the defect this HU removes. Overwritten (never accumulated) on
+     * every enqueue attempt, successful or not.
+     */
+    readonly limitWarning: _angular_core.WritableSignal<string>;
     private _fromIndex;
     private _toIndex;
-    get images(): NsFile[];
-    get image(): NsFile | null;
+    /**
+     * The only path from `value()` to the template, whatever fed it: a plain
+     * `[value]="misImagenes"` binding — `value` is the public two-way `model()`
+     * from `NsValueAccessor`, so nothing forces a consumer through
+     * `writeValue`/`add` — lands here same as a file picked through the
+     * control itself. `assignUid` is idempotent (never overwrites an existing
+     * registry entry) and never mutates the `NsFile`, so re-running it every
+     * getter call is safe: the `uid` a given instance gets on its first pass
+     * through here is the one it keeps on every later change-detection cycle,
+     * and no signal write happens as a side effect of reading the template
+     * (AVF-15). Works the same whether the array/elements are frozen or not
+     * (AVF-18 corrección de rechazo).
+     */
+    get images(): TrackedFile[];
+    get image(): TrackedFile | null;
+    /**
+     * Reads the `uid` assigned to `image` — the accessor the `.ts` and the
+     * template both use instead of a `.uid` property on the `NsFile` itself,
+     * which no longer exists (AVF-18 corrección de rechazo: that property
+     * write is exactly what threw on a frozen image). Public so the
+     * template's `track` expressions can call it directly, and so `statusOf`
+     * can resolve the key it looks up. Every `NsFile` reachable from
+     * `images()`/`image()` has already been through `assignUid`, so this only
+     * ever reads — the `assignUid` call here is a safety net for a caller that
+     * hands in an image from outside that path.
+     */
+    uidOf(image: NsFile): string;
+    /**
+     * True while the single (`!multi()`) image's own upload attempt is
+     * `'fallido'` — the one flag the drag-container button needs to swap
+     * "open the file picker" for "retry this upload" (AVF-16, corrección de
+     * rechazo: criterios 5-6 no estaban cubiertos en modo single, solo en
+     * `multi`).
+     */
+    get singleFailed(): boolean;
     writeValue(value: NsFile | NsFile[] | null): void;
     onClick(): void;
+    /**
+     * Click handler for the single-mode (`!multi()`) drag-container: it is
+     * both the file picker trigger and, once the image has failed, the
+     * retry control — same dual role the `multi` grid button and the cover
+     * chip already had (AVF-16 corrección de rechazo).
+     */
+    onDragContainerClick(): void;
     load(): void;
     add(image: NsFile): void;
+    /**
+     * Re-subscribes to the same upload the failed attempt used — no new
+     * `NsUploadClient` contract needed (AVF-16 evidence: `upload(file):
+     * Observable<file>` is already re-subscribable). Shared by the first
+     * attempt (`add`) and every later retry. `uid` is passed in rather than
+     * re-derived from `image`, since `retry()` needs the *original* uid even
+     * though the `image` it holds may itself be a server response object by
+     * then.
+     */
+    private upload;
+    /**
+     * Retries a failed upload in place: same `uid`, same position in the
+     * gallery, no re-read from disk (the preview already holds the file's
+     * data).
+     */
+    retry(image: TrackedFile): void;
     private assignValue;
-    private compareWith;
-    remove(image: NsFile): void;
+    remove(image: TrackedFile): void;
     dragstart(event: DragEvent, index: number): void;
+    /**
+     * Shared by every drop target (thumbnails, the `cover` node — index 0 —
+     * and the plain drop zones). `event.dataTransfer.types` never carries
+     * `'Files'` for the internal reorder drag (it writes nothing to the
+     * clipboard today), so that check alone tells the external-file drop and
+     * the reorder drag apart without a separate state flag.
+     */
     dragover(event: DragEvent, index: number): void;
+    dragleave(event: DragEvent): void;
     dragend(event: DragEvent): void;
     drop(event: DragEvent): void;
+    private isFileDrag;
+    private isAcceptedFile;
+    private addDroppedFile;
+    /**
+     * Accepts as many of `files` as fit under `limit()`, all at once, and
+     * reports the rest inline. `limit()` is evaluated once here, against
+     * `this.images.length` as it stands *before* any of this batch's
+     * `add()` calls run — never inside a per-file callback, where it would
+     * lag behind sibling files whose `FileReader`/upload hasn't resolved yet
+     * and let more through than actually fit (AVF-16).
+     *
+     * Returns how many files were actually enqueued, so callers can decide
+     * whether to mark the control touched.
+     */
+    private enqueueFiles;
+    private buildLimitWarning;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NsImageUploadComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsImageUploadComponent, "ns-image-upload", never, { "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "multi": { "alias": "multi"; "required": false; "isSignal": true; }; "limit": { "alias": "limit"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsImageUploadComponent, "ns-image-upload", never, { "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "multi": { "alias": "multi"; "required": false; "isSignal": true; }; "limit": { "alias": "limit"; "required": false; "isSignal": true; }; "layout": { "alias": "layout"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 declare class NsLinkComponent {
@@ -1416,20 +1606,34 @@ declare class NsSkeletonComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsSkeletonComponent, "ns-skeleton", never, { "width": { "alias": "width"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "animated": { "alias": "animated"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-type NsStatCardVariant = 'default' | 'dark' | 'compact';
+type NsStatCardVariant = 'default' | 'dark' | 'compact' | 'tile';
 type NsStatCardDeltaTone = 'up' | 'down' | 'neutral';
 type NsStatCardValueTone = 'default' | 'success' | 'warning' | 'danger' | 'info';
+type NsStatCardHintTone = 'default' | 'success' | 'warning' | 'danger' | 'info';
+type NsStatCardIconTone = 'info' | 'success' | 'warning' | 'danger' | 'neutral';
 /**
  * Dashboard metric card: label, formatted value (with an optional muted
  * suffix), and an optional delta pill (`up` / `down` / `neutral`) with a
  * caption and a secondary hint. `variant="dark"` renders the emphasis
  * surface used for headline metrics; `variant="compact"` renders a smaller
- * card with a smaller value size. Set `interactive` to render the card as a
- * `<button>` and receive `(activated)` instead of a static `<div>`.
+ * card with a smaller value size; `variant="tile"` renders a compact KPI
+ * tile (icon circle beside a label/value/delta column, delta as plain
+ * colored text instead of a pill). Set `interactive` to render the card as
+ * a `<button>` and receive `(activated)` instead of a static `<div>`.
  *
  * `valueTone` colors only the headline value with the matching semantic
  * status color (`success`/`warning`/`danger`/`info`); it is ignored on
- * `variant="dark"`, where the value stays white.
+ * `variant="dark"`, where the value stays white. `hintTone` colors only the
+ * hint with the same semantic scale, independently of `valueTone`; like
+ * `valueTone`, it is ignored on `variant="dark"`, where the hint keeps the
+ * emphasis-surface foreground color instead of a status color. `iconTone`
+ * colors the icon wrapper background/foreground and applies to every
+ * variant.
+ *
+ * The hint's own `margin-inline-start: auto` (pushing it to the opposite
+ * edge from the value) only applies when it shares the meta row with a
+ * `delta` and/or `deltaLabel` — something to separate from. A lone hint
+ * (no delta, no deltaLabel) aligns to the start, under the value.
  */
 declare class NsStatCardComponent {
     readonly label: _angular_core.InputSignal<string>;
@@ -1440,13 +1644,15 @@ declare class NsStatCardComponent {
     readonly deltaLabel: _angular_core.InputSignal<string>;
     readonly hint: _angular_core.InputSignal<string>;
     readonly valueTone: _angular_core.InputSignal<NsStatCardValueTone>;
+    readonly hintTone: _angular_core.InputSignal<NsStatCardHintTone>;
+    readonly iconTone: _angular_core.InputSignal<NsStatCardIconTone>;
     readonly variant: _angular_core.InputSignal<NsStatCardVariant>;
     readonly interactive: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly activated: _angular_core.OutputEmitterRef<void>;
     protected deltaGlyph(): string;
     protected onActivate(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NsStatCardComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsStatCardComponent, "ns-stat-card", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; "suffix": { "alias": "suffix"; "required": false; "isSignal": true; }; "delta": { "alias": "delta"; "required": false; "isSignal": true; }; "deltaTone": { "alias": "deltaTone"; "required": false; "isSignal": true; }; "deltaLabel": { "alias": "deltaLabel"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "valueTone": { "alias": "valueTone"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "interactive": { "alias": "interactive"; "required": false; "isSignal": true; }; }, { "activated": "activated"; }, never, ["[stat-card-icon]", "[stat-card-footer]"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NsStatCardComponent, "ns-stat-card", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; "suffix": { "alias": "suffix"; "required": false; "isSignal": true; }; "delta": { "alias": "delta"; "required": false; "isSignal": true; }; "deltaTone": { "alias": "deltaTone"; "required": false; "isSignal": true; }; "deltaLabel": { "alias": "deltaLabel"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "valueTone": { "alias": "valueTone"; "required": false; "isSignal": true; }; "hintTone": { "alias": "hintTone"; "required": false; "isSignal": true; }; "iconTone": { "alias": "iconTone"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "interactive": { "alias": "interactive"; "required": false; "isSignal": true; }; }, { "activated": "activated"; }, never, ["[stat-card-icon]", "[stat-card-footer]"], true, never>;
 }
 
 declare class TemplateDirective {
@@ -1549,6 +1755,34 @@ declare const NS_THEME_OPTIONS: InjectionToken<NsResolvedThemeOptions>;
 declare const NS_TOAST_OPTIONS: InjectionToken<NsResolvedToastThemeOptions>;
 declare function provideNsTheme(options?: NsThemeOptions): EnvironmentProviders;
 
+/**
+ * Registry of theme tokens that used to be part of the Arvisfy preset and no
+ * longer have any effect on rendering. `NsTokenTree` has an open index
+ * signature and `mergeObjects` (below) merges unknown keys in without
+ * complaint, so a consumer overriding a retired token gets no type error and
+ * no `validateNsPreset` error -- the override is silently inert.
+ * `validateNsPreset` walks this map against the resolved preset and emits a
+ * `console.warn` for every retired path still present, so the override at
+ * least surfaces instead of doing nothing invisibly.
+ *
+ * Keys are full token paths, one of:
+ * - `primitive.<path>`
+ * - `semantic.common.<path>`
+ * - `semantic.colorScheme.<light|dark>.<path>`
+ * - `components.<path>`
+ *
+ * Values are the exact message logged for that path. Do not include a
+ * version number in a message: the published package version and this
+ * source's `package.json` version can diverge, so a hardcoded version would
+ * go stale.
+ *
+ * This lives here rather than in its own file: `packages/mcp` transpiles
+ * this module in isolation (`extract-tokens.mjs`'s `assertNoValueImports`)
+ * and cannot resolve a relative value import from a sibling module at that
+ * point, so a second file imported here for its data would break
+ * `nx run mcp:build-data`.
+ */
+declare const NS_RETIRED_TOKENS: Readonly<Record<string, string>>;
 declare function defineNsPreset(base: NsThemePreset, overrides: NsThemePresetOverrides): NsThemePreset;
 declare function validateNsPreset(preset: NsThemePreset): void;
 declare function flattenTokens<T>(tree: NsTokenTree<T>): Map<string, T>;
@@ -1742,5 +1976,5 @@ declare class NsTooltipDirective implements OnDestroy {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NsTooltipDirective, "[nsTooltip]", never, { "message": { "alias": "nsTooltip"; "required": true; "isSignal": true; }; "placement": { "alias": "nsTooltipPlacement"; "required": false; "isSignal": true; }; "delay": { "alias": "nsTooltipDelay"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-export { Arvisfy, NS_THEME_OPTIONS, NS_TOAST_OPTIONS, NsAccordionComponent, NsAccordionItemComponent, NsAlertComponent, NsAvatarComponent, NsAvatarGroupComponent, NsBadgeComponent, NsBreadcrumbItemComponent, NsBreadcrumbsComponent, NsButtonComponent, NsButtonGroupComponent, NsCardBodyComponent, NsCardComponent, NsCardFooterComponent, NsCardHeaderComponent, NsCheckboxComponent, NsChipComponent, NsCollectionController, NsCommandPaletteComponent, NsCommentComponent, NsContentEditableComponent, NsDatePickerComponent, NsDateRangePickerComponent, NsDescriptionComponent, NsDividerComponent, NsDrawerComponent, NsDrawerRef, NsDrawerService, NsDropdownComponent, NsDropdownItemDirective, NsEditorColorPickerComponent, NsEditorComponent, NsEditorLinkComponent, NsEditorListComponent, NsEditorParagraphComponent, NsEditorToggleCommandComponent, NsEmptyStateComponent, NsFieldContext, NsFieldDirective, NsImageUploadComponent, NsInputCodeComponent, NsInputComponent, NsInputGroupAddonComponent, NsInputGroupComponent, NsInputNumberComponent, NsInputSearchComponent, NsLinkComponent, NsLoadMoreComponent, NsMenuComponent, NsMenuDividerComponent, NsMenuItemComponent, NsMenuSectionComponent, NsMeterComponent, NsModalComponent, NsModalRef, NsModalService, NsOptionCardComponent, NsOverlayRef, NsOverlayService, NsPaginationComponent, NsPasswordComponent, NsPopoverComponent, NsProgressBarComponent, NsRadioComponent, NsRadioGroupComponent, NsSchedule, NsScheduleComponent, NsScheduleService, NsSchemaMarkupComponent, NsSideNavComponent, NsSideNavItemComponent, NsSideNavSectionComponent, NsSkeletonComponent, NsSliderComponent, NsStatCardComponent, NsSurfaceComponent, NsSwitchComponent, NsTabComponent, NsTabsComponent, NsTagComponent, NsTagGroupComponent, NsTextAreaComponent, NsThemeService, NsTimelineComponent, NsTimelineItemComponent, NsToastComponent, NsToastHandle, NsToastService, NsTooltipComponent, NsTooltipDirective, NsValueAccessor, TemplateDirective, defineNsPreset, flattenTokens, getNsOverlayPosition, provideNsTheme, referenceToCssVariable, tokenPathToCssVariable, validateNsPreset };
-export type { NsAlertVariant, NsBadgeMode, NsButtonGroupSelectionMode, NsButtonVariant, NsChipColor, NsChipSize, NsChipVariant, NsCollectionItem, NsColor, NsColorScheme, NsCommandGroup, NsCommandItem, NsComment, NsComponentInputs, NsDateRangeValue, NsDateView, NsDeepPartial, NsDrawerComponentInputs, NsDrawerConfig, NsDrawerOptions, NsDrawerPosition, NsDropdownItem, NsDropdownValue, NsEmptyStateSize, NsFlattenedPrimitiveTokens, NsKey, NsModalConfig, NsModalOptions, NsModalSize, NsOrientation, NsOverlayCloseReason, NsOverlayConfig, NsOverlayPosition, NsPlacement, NsPrimitiveReference, NsPrimitiveTokenValue, NsResolvedColorScheme, NsResolvedThemeOptions, NsResolvedToastThemeOptions, NsSchemaMarkup, NsSchemaType, NsSelectionMode, NsSemanticReference, NsSemanticTokens, NsSideNavColor, NsSize, NsSliderValue, NsStatCardDeltaTone, NsStatCardValueTone, NsStatCardVariant, NsTabsVariant, NsThemeOptions, NsThemePreset, NsThemePresetOverrides, NsTimelineItemColor, NsTimelineSize, NsToastAction, NsToastCloseReason, NsToastOptions, NsToastPlacement, NsToastThemeOptions, NsToastVariant, NsTokenTree, NsVariant };
+export { Arvisfy, NS_EDITOR_TOOLS_DEFAULT, NS_RETIRED_TOKENS, NS_THEME_OPTIONS, NS_TOAST_OPTIONS, NsAccordionComponent, NsAccordionItemComponent, NsAlertComponent, NsAvatarComponent, NsAvatarGroupComponent, NsBadgeComponent, NsBreadcrumbItemComponent, NsBreadcrumbsComponent, NsButtonComponent, NsButtonGroupComponent, NsCardBodyComponent, NsCardComponent, NsCardFooterComponent, NsCardHeaderComponent, NsCheckboxComponent, NsChipComponent, NsCollectionController, NsCommandPaletteComponent, NsCommentComponent, NsContentEditableComponent, NsDatePickerComponent, NsDateRangePickerComponent, NsDescriptionComponent, NsDividerComponent, NsDrawerComponent, NsDrawerRef, NsDrawerService, NsDropdownComponent, NsDropdownItemDirective, NsEditorColorPickerComponent, NsEditorComponent, NsEditorImageComponent, NsEditorLinkComponent, NsEditorListComponent, NsEditorParagraphComponent, NsEditorToggleCommandComponent, NsEmptyStateComponent, NsFieldContext, NsFieldDirective, NsImageUploadComponent, NsInputCodeComponent, NsInputComponent, NsInputGroupAddonComponent, NsInputGroupComponent, NsInputNumberComponent, NsInputSearchComponent, NsLinkComponent, NsLoadMoreComponent, NsMenuComponent, NsMenuDividerComponent, NsMenuItemComponent, NsMenuSectionComponent, NsMeterComponent, NsModalComponent, NsModalRef, NsModalService, NsOptionCardComponent, NsOverlayRef, NsOverlayService, NsPaginationComponent, NsPasswordComponent, NsPopoverComponent, NsProgressBarComponent, NsRadioComponent, NsRadioGroupComponent, NsSchedule, NsScheduleComponent, NsScheduleService, NsSchemaMarkupComponent, NsSideNavComponent, NsSideNavItemComponent, NsSideNavSectionComponent, NsSkeletonComponent, NsSliderComponent, NsStatCardComponent, NsSurfaceComponent, NsSwitchComponent, NsTabComponent, NsTabsComponent, NsTagComponent, NsTagGroupComponent, NsTextAreaComponent, NsThemeService, NsTimelineComponent, NsTimelineItemComponent, NsToastComponent, NsToastHandle, NsToastService, NsTooltipComponent, NsTooltipDirective, NsValueAccessor, TemplateDirective, defineNsPreset, flattenTokens, getNsOverlayPosition, provideNsTheme, referenceToCssVariable, tokenPathToCssVariable, validateNsPreset };
+export type { NsAlertVariant, NsBadgeMode, NsButtonGroupSelectionMode, NsButtonVariant, NsChipColor, NsChipSize, NsChipVariant, NsCollectionItem, NsColor, NsColorScheme, NsCommandGroup, NsCommandItem, NsComment, NsComponentInputs, NsDateRangeValue, NsDateView, NsDeepPartial, NsDrawerComponentInputs, NsDrawerConfig, NsDrawerOptions, NsDrawerPosition, NsDropdownItem, NsDropdownValue, NsEditorTool, NsEmptyStateSize, NsFlattenedPrimitiveTokens, NsKey, NsModalConfig, NsModalOptions, NsModalSize, NsOrientation, NsOverlayCloseReason, NsOverlayConfig, NsOverlayPosition, NsPlacement, NsPrimitiveReference, NsPrimitiveTokenValue, NsResolvedColorScheme, NsResolvedThemeOptions, NsResolvedToastThemeOptions, NsSchemaMarkup, NsSchemaType, NsSelectionMode, NsSemanticReference, NsSemanticTokens, NsSideNavColor, NsSize, NsSliderValue, NsStatCardDeltaTone, NsStatCardHintTone, NsStatCardIconTone, NsStatCardValueTone, NsStatCardVariant, NsTabsVariant, NsThemeOptions, NsThemePreset, NsThemePresetOverrides, NsTimelineItemColor, NsTimelineSize, NsToastAction, NsToastCloseReason, NsToastOptions, NsToastPlacement, NsToastThemeOptions, NsToastVariant, NsTokenTree, NsVariant };