ng-hub-ui-forms 22.6.0 → 22.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-hub-ui-forms",
-  "version": "22.6.0",
+  "version": "22.7.0",
   "license": "MIT",
   "description": "Accessible, signal-based form fields for Angular (input, textarea, slider, segmented, select, datepicker, file input with drag & drop and upload progress) with automatic error display for controls, FormGroups and FormArrays. Reactive Forms today, Signal Forms ready. Part of the ng-hub-ui family.",
   "author": "Carlos Morcillo <carlos.morcillo@me.com> (https://www.carlosmorcillo.com)",

package/styles/_tokens.scss

@@ -110,20 +110,53 @@
 	--hub-file-input-focus-border-color: var(--hub-input-focus-border-color);
 	--hub-file-input-focus-box-shadow: var(--hub-input-focus-box-shadow);
 
-	// Dropzone copy
+	// Dropzone copy. The prompt is a row by default (invitation and browse action side by
+	// side); `--hub-file-input-prompt-direction: column` stacks them, which is what a
+	// dropzone carrying a `dropSubtext` wants.
 	--hub-file-input-prompt-color: var(--hub-sys-text-muted, #6c757d);
 	--hub-file-input-prompt-font-size: var(--hub-ref-font-size-base, 1rem);
-	--hub-file-input-browse-color: var(--hub-sys-color-primary, #0d6efd);
-	--hub-file-input-browse-font-weight: var(--hub-ref-font-weight-medium, 500);
+	--hub-file-input-prompt-direction: row;
+	// `baseline` aligns a row of text; a column prompt wants `center`.
+	--hub-file-input-prompt-align: baseline;
+	--hub-file-input-prompt-gap: 0.25em;
+	--hub-file-input-drop-text-color: inherit;
+	--hub-file-input-drop-text-font-size: inherit;
+	--hub-file-input-drop-text-font-weight: inherit;
+	--hub-file-input-drop-subtext-color: var(--hub-file-input-hint-color);
+	--hub-file-input-drop-subtext-font-size: var(--hub-file-input-hint-font-size);
 	--hub-file-input-hint-color: var(--hub-sys-text-muted, #6c757d);
 	--hub-file-input-hint-font-size: var(--hub-ref-font-size-sm, 0.875rem);
 
+	// Browse action — a transparent, underlined text affordance by default. Give it a
+	// background, padding and a radius to render it as a button instead.
+	--hub-file-input-browse-color: var(--hub-sys-color-primary, #0d6efd);
+	--hub-file-input-browse-font-weight: var(--hub-ref-font-weight-medium, 500);
+	--hub-file-input-browse-font-size: inherit;
+	--hub-file-input-browse-text-decoration: underline;
+	--hub-file-input-browse-bg: transparent;
+	--hub-file-input-browse-hover-bg: var(--hub-file-input-browse-bg);
+	--hub-file-input-browse-padding-x: 0;
+	--hub-file-input-browse-padding-y: 0;
+	--hub-file-input-browse-radius: 0;
+	--hub-file-input-browse-gap: var(--hub-ref-space-2, 0.5rem);
+	--hub-file-input-browse-margin-top: 0;
+	// Optional leading glyph of the browse action — OFF until `-display` is switched on and
+	// a mask is supplied, mirroring the leading-icon contract of the rest of the family.
+	--hub-file-input-browse-icon: none;
+	--hub-file-input-browse-icon-display: none;
+	--hub-file-input-browse-icon-size: 1.125em;
+
 	// Glyphs — every icon is a swappable mask, tinted by its `-color` token. Replace the
 	// `url(…)` to change the drawing without touching the template; project an
 	// `<ng-template hubFileIcon>` to replace the per-file glyph with a component.
 	--hub-file-input-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='black' d='M.5 9.9a.5.5 0 0 1 .5.5v2.5a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-2.5a.5.5 0 0 1 1 0v2.5a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2v-2.5a.5.5 0 0 1 .5-.5'/%3E%3Cpath fill='black' d='M7.646.146a.5.5 0 0 1 .708 0l3 3a.5.5 0 0 1-.708.708L8.5 1.707V10.5a.5.5 0 0 1-1 0V1.707L5.354 3.854a.5.5 0 1 1-.708-.708z'/%3E%3C/svg%3E");
 	--hub-file-input-icon-size: 2rem;
 	--hub-file-input-icon-color: var(--hub-sys-text-muted, #6c757d);
+	// The glyph can sit on a medallion: a tinted, rounded surface behind it. Off by default
+	// (transparent, square, exactly the glyph's box), so the dropzone renders unchanged.
+	--hub-file-input-icon-bg: transparent;
+	--hub-file-input-icon-chip-size: var(--hub-file-input-icon-size);
+	--hub-file-input-icon-chip-radius: 0;
 	--hub-file-input-file-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='black' d='M4 0a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h8a2 2 0 0 0 2-2V4.414A1.5 1.5 0 0 0 13.56 3.35L10.65.44A1.5 1.5 0 0 0 9.586 0zm5.5 1.5v2a1 1 0 0 0 1 1h2z'/%3E%3C/svg%3E");
 	--hub-file-input-file-icon-size: 1.5rem;
 	--hub-file-input-file-icon-color: var(--hub-sys-text-muted, #6c757d);

package/types/ng-hub-ui-forms.d.ts

@@ -319,6 +319,12 @@ interface HubFileItem {
     readonly progress: number | null;
     /** The error thrown by the uploader, when `status` is `'error'`. */
     readonly error: unknown | null;
+    /**
+     * The body the uploader reported on `done` — typically the record the server created, whose id
+     * the application needs to reference the stored file. `null` until the upload succeeds, and
+     * again after a `retry` restarts it.
+     */
+    readonly response: unknown | null;
 }
 /** How the accepted files are previewed below the dropzone. */
 type HubFilePreview = 'none' | 'list' | 'grid';
@@ -342,6 +348,12 @@ interface HubFileInputLabels {
     browse: string;
     /** Invitation rendered inside the dropzone. */
     dropHere: string;
+    /**
+     * Second line of the invitation, under {@link dropHere}. Empty by default, so it renders
+     * nothing. A dropzone that sets it usually stacks the prompt too, with
+     * `--hub-file-input-prompt-direction: column`.
+     */
+    dropSubtext: string;
     /** Accessible name of the per-file remove button. */
     remove: string;
     /** Text + accessible name of the "remove all" button. */
@@ -1512,6 +1524,34 @@ declare class HubFileIconDirective {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<HubFileIconDirective, "[hubFileIcon]", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Projects arbitrary markup inside a `<hub-file-input>` dropzone, between the glyph and the
+ * invitation.
+ *
+ * The slot exists for a notice the consumer computes per instance — "2 documents still missing",
+ * a badge, a warning — which neither `dropText` (the invitation) nor `hint` (the constraints
+ * summary, rendered at the bottom) can express, and which is too instance-specific to live in the
+ * global labels.
+ *
+ * Renders nothing when the template is absent, so the dropzone is unchanged for every consumer
+ * that does not project one.
+ *
+ * @example
+ * ```html
+ * <hub-file-input [multiple]="true">
+ *   <ng-template hubFileDropzoneNotice>
+ *     <strong class="missing">2 documents still missing</strong>
+ *   </ng-template>
+ * </hub-file-input>
+ * ```
+ */
+declare class HubFileDropzoneNoticeDirective {
+    /** Template reference for the notice. */
+    readonly template: TemplateRef<void>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubFileDropzoneNoticeDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<HubFileDropzoneNoticeDirective, "[hubFileDropzoneNotice]", never, {}, {}, never, never, true, never>;
+}
+
 /** Context handed to a projected `hubFilePreview` template. */
 interface HubFilePreviewContext {
     /** The item being rendered. */
@@ -1644,6 +1684,10 @@ declare class HubFileInputComponent extends HubFieldControl {
     readonly autoUpload: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Overrides the "browse" button text coming from the global labels. */
     readonly buttonLabel: _angular_core.InputSignal<string | null>;
+    /** Overrides the dropzone invitation coming from the global labels. */
+    readonly dropText: _angular_core.InputSignal<string | null>;
+    /** Overrides the second invitation line coming from the global labels. Pass `''` to hide it. */
+    readonly dropSubtext: _angular_core.InputSignal<string | null>;
     /** Overrides the auto-generated hint that summarizes the active constraints. Pass `''` to hide it. */
     readonly hint: _angular_core.InputSignal<string | null>;
     /** Helper text shown below the control. */
@@ -1666,6 +1710,8 @@ declare class HubFileInputComponent extends HubFieldControl {
     protected readonly iconTpt: _angular_core.Signal<HubFileIconDirective | undefined>;
     /** Projected per-file preview template, replacing the built-in item rendering. */
     protected readonly previewTpt: _angular_core.Signal<HubFilePreviewDirective | undefined>;
+    /** Projected notice rendered between the glyph and the invitation. */
+    protected readonly noticeTpt: _angular_core.Signal<HubFileDropzoneNoticeDirective | undefined>;
     /** Whether a drag is currently hovering the dropzone. */
     protected readonly isDragging: _angular_core.WritableSignal<boolean>;
     /** Latest message for the screen-reader live region. */
@@ -1680,6 +1726,10 @@ declare class HubFileInputComponent extends HubFieldControl {
     protected readonly labels: _angular_core.Signal<ng_hub_ui_forms.HubFileInputLabels>;
     /** Text of the browse action. */
     protected readonly browseLabel: _angular_core.Signal<string>;
+    /** The dropzone invitation. */
+    protected readonly dropTextLabel: _angular_core.Signal<string>;
+    /** The second invitation line. Empty renders nothing. */
+    protected readonly dropSubtextLabel: _angular_core.Signal<string>;
     /** The hint summarizing the active constraints. */
     protected readonly constraintsHint: _angular_core.Signal<string>;
     /** Whether the dropzone currently accepts a drop. */
@@ -1770,7 +1820,7 @@ declare class HubFileInputComponent extends HubFieldControl {
      */
     protected previewContext(item: HubFileItem): HubFilePreviewContext;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubFileInputComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubFileInputComponent, "hub-file-input", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "maxSize": { "alias": "maxSize"; "required": false; "isSignal": true; }; "minSize": { "alias": "minSize"; "required": false; "isSignal": true; }; "maxTotalSize": { "alias": "maxTotalSize"; "required": false; "isSignal": true; }; "maxFiles": { "alias": "maxFiles"; "required": false; "isSignal": true; }; "dragDrop": { "alias": "dragDrop"; "required": false; "isSignal": true; }; "paste": { "alias": "paste"; "required": false; "isSignal": true; }; "preview": { "alias": "preview"; "required": false; "isSignal": true; }; "allowDuplicates": { "alias": "allowDuplicates"; "required": false; "isSignal": true; }; "capture": { "alias": "capture"; "required": false; "isSignal": true; }; "autoUpload": { "alias": "autoUpload"; "required": false; "isSignal": true; }; "buttonLabel": { "alias": "buttonLabel"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "formText": { "alias": "formText"; "required": false; "isSignal": true; }; "formTextType": { "alias": "formTextType"; "required": false; "isSignal": true; }; "classlist": { "alias": "classlist"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; "rejected": "rejected"; "fileRemoved": "fileRemoved"; "uploadStateChange": "uploadStateChange"; }, ["iconTpt", "previewTpt"], never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubFileInputComponent, "hub-file-input", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "maxSize": { "alias": "maxSize"; "required": false; "isSignal": true; }; "minSize": { "alias": "minSize"; "required": false; "isSignal": true; }; "maxTotalSize": { "alias": "maxTotalSize"; "required": false; "isSignal": true; }; "maxFiles": { "alias": "maxFiles"; "required": false; "isSignal": true; }; "dragDrop": { "alias": "dragDrop"; "required": false; "isSignal": true; }; "paste": { "alias": "paste"; "required": false; "isSignal": true; }; "preview": { "alias": "preview"; "required": false; "isSignal": true; }; "allowDuplicates": { "alias": "allowDuplicates"; "required": false; "isSignal": true; }; "capture": { "alias": "capture"; "required": false; "isSignal": true; }; "autoUpload": { "alias": "autoUpload"; "required": false; "isSignal": true; }; "buttonLabel": { "alias": "buttonLabel"; "required": false; "isSignal": true; }; "dropText": { "alias": "dropText"; "required": false; "isSignal": true; }; "dropSubtext": { "alias": "dropSubtext"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "formText": { "alias": "formText"; "required": false; "isSignal": true; }; "formTextType": { "alias": "formTextType"; "required": false; "isSignal": true; }; "classlist": { "alias": "classlist"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; "rejected": "rejected"; "fileRemoved": "fileRemoved"; "uploadStateChange": "uploadStateChange"; }, ["iconTpt", "previewTpt", "noticeTpt"], never, true, never>;
 }
 
 declare class NgOptionComponent implements OnInit {
@@ -2361,5 +2411,5 @@ interface HubFormControlAdapter {
  */
 declare const hubFormControlAdapter: HubFormControlAdapter;
 
-export { FormTextTypes, HUB_FILE_UPLOADER, HUB_FORMS_CONFIG, HubAutoresizeDirective, HubDatepickerComponent, HubFieldControl, HubFieldsetComponent, HubFileIconDirective, HubFileInputComponent, HubFilePreviewDirective, HubFormComponent, HubFormControl, HubFormTextDirective, HubGroupControl, HubInputComponent, HubInputFormats, HubInputPrefixDirective, HubInputSuffixDirective, HubInvertColorPipe, HubJoinButLastPipe, HubLabelTypes, HubLegendComponent, HubLegendDirective, HubMapPipe, HubOtpInputComponent, HubSafeUrlPipe, HubSegmentedComponent, HubSelectComponent, HubSelectFormats, HubSliderComponent, HubSnakeUpperPipe, HubTextareaComponent, HubUcfirstPipe, HubValidationErrorDirective, NgClearButtonTemplateDirective, NgFooterTemplateDirective, NgHeaderTemplateDirective, NgLabelTemplateDirective, NgLoadingSpinnerTemplateDirective, NgLoadingTextTemplateDirective, NgMultiLabelTemplateDirective, NgNotFoundTemplateDirective, NgOptgroupTemplateDirective, NgOptionComponent, NgOptionTemplateDirective, NgSelectConfig, NgTagTemplateDirective, NgTypeToSearchTemplateDirective, applyMask, areEqual, camelToSnakeUpper, controlHasMinOrMaxValidator, defaultHubDatepickerConfig, defaultHubDatepickerLabels, defaultHubFileInputLabels, defaultHubFormsConfig, defaultInvalidFeedback, fileKey, formatFileSize, get, getActiveElement, getMinOrMaxValueFromValidator, hubAcceptedFiles, hubAreEqual, hubFormControlAdapter, hubMaxFileSize, hubMaxFiles, hubMaxTotalSize, hubMinFileSize, hubMinFiles, isDefined, isMaskActive, isString, joinButLast, matchesAccept, provideHubFileUploader, provideHubForms, runInZone, toFileArray, uuid };
+export { FormTextTypes, HUB_FILE_UPLOADER, HUB_FORMS_CONFIG, HubAutoresizeDirective, HubDatepickerComponent, HubFieldControl, HubFieldsetComponent, HubFileDropzoneNoticeDirective, HubFileIconDirective, HubFileInputComponent, HubFilePreviewDirective, HubFormComponent, HubFormControl, HubFormTextDirective, HubGroupControl, HubInputComponent, HubInputFormats, HubInputPrefixDirective, HubInputSuffixDirective, HubInvertColorPipe, HubJoinButLastPipe, HubLabelTypes, HubLegendComponent, HubLegendDirective, HubMapPipe, HubOtpInputComponent, HubSafeUrlPipe, HubSegmentedComponent, HubSelectComponent, HubSelectFormats, HubSliderComponent, HubSnakeUpperPipe, HubTextareaComponent, HubUcfirstPipe, HubValidationErrorDirective, NgClearButtonTemplateDirective, NgFooterTemplateDirective, NgHeaderTemplateDirective, NgLabelTemplateDirective, NgLoadingSpinnerTemplateDirective, NgLoadingTextTemplateDirective, NgMultiLabelTemplateDirective, NgNotFoundTemplateDirective, NgOptgroupTemplateDirective, NgOptionComponent, NgOptionTemplateDirective, NgSelectConfig, NgTagTemplateDirective, NgTypeToSearchTemplateDirective, applyMask, areEqual, camelToSnakeUpper, controlHasMinOrMaxValidator, defaultHubDatepickerConfig, defaultHubDatepickerLabels, defaultHubFileInputLabels, defaultHubFormsConfig, defaultInvalidFeedback, fileKey, formatFileSize, get, getActiveElement, getMinOrMaxValueFromValidator, hubAcceptedFiles, hubAreEqual, hubFormControlAdapter, hubMaxFileSize, hubMaxFiles, hubMaxTotalSize, hubMinFileSize, hubMinFiles, isDefined, isMaskActive, isString, joinButLast, matchesAccept, provideHubFileUploader, provideHubForms, runInZone, toFileArray, uuid };
 export type { FormTextType, HubDateRange, HubDateValue, HubDatepickerConfig, HubDatepickerLabels, HubDatepickerMode, HubFileConstraints, HubFileIconContext, HubFileInputLabels, HubFileItem, HubFilePreview, HubFilePreviewContext, HubFileRejection, HubFileRejectionReason, HubFileStatus, HubFileUploadEvent, HubFileUploader, HubFileValue, HubFormControlAdapter, HubFormControlConfig, HubFormControlHandle, HubFormControlOption, HubFormsConfig, HubGroupErrorTrigger, HubInputFormat, HubLabelType, HubMaskResult, HubOtpMode, HubSegmentedOption, HubSegmentedSize, HubSelectFormat, HubSliderValue };