ng-hub-ui-forms 22.12.2 → 22.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-hub-ui-forms",
-  "version": "22.12.2",
+  "version": "22.14.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/_field.scss

@@ -146,3 +146,69 @@
 		color: var(--hub-form-valid-feedback-color);
 	}
 }
+
+/**
+ * Read-only fields.
+ *
+ * Applied from the field's own `readonly` state, so nothing has to be remembered at
+ * the call site: mark a field read-only and it looks read-only.
+ *
+ * The border, the background and the focus ring exist to say "you can type here".
+ * On a field that refuses input they are a promise the field then breaks — and next
+ * to an editable neighbour there was nothing at all to tell the two apart.
+ *
+ * Deliberately not the disabled treatment. Disabled means "not applicable now" and
+ * fades to make that plain; read-only means "this is the value, it is simply not
+ * yours to change here", so the text stays at full contrast and remains selectable —
+ * copying a tax id out of a document is the whole point of showing it.
+ *
+ * The padding stays, so a read-only field keeps the same box and the same baseline
+ * as the editable ones beside it in a grid.
+ */
+.hub-field--readonly {
+	.hub-field__control,
+	.hub-input__control,
+	.hub-textarea__control,
+	.hub-select__control {
+		background-color: var(--hub-input-readonly-bg);
+		border-color: var(--hub-input-readonly-border-color);
+		color: var(--hub-input-readonly-color);
+		cursor: var(--hub-input-readonly-cursor);
+		box-shadow: none;
+	}
+
+	// No focus affordance either: nothing here answers to being focused.
+	.hub-field__control:focus,
+	.hub-field__control:focus-visible,
+	.hub-input__control:focus,
+	.hub-textarea__control:focus,
+	.hub-select__control.ng-select-focused {
+		border-color: var(--hub-input-readonly-border-color);
+		box-shadow: none;
+		outline: none;
+	}
+
+	// A caret, a clear cross and a calendar all promise a choice that is not on
+	// offer. The datepicker already hides its own clear when read-only; the icon it
+	// opens with is the same promise.
+	.hub-select__control {
+		.ng-arrow-wrapper,
+		.ng-clear-wrapper {
+			display: none;
+		}
+	}
+
+	.hub-datepicker__icon {
+		display: none;
+	}
+
+	// The error border survives. Dropping the chrome is about not promising input;
+	// an invalid value is a different message, and one the user still has to see —
+	// the feedback text alone is easy to miss in a long form. Needs the explicit
+	// exception because the rules above outrank `--invalid` on their own.
+	.hub-field__control--invalid,
+	.hub-field__control--invalid:focus,
+	.hub-select__control--invalid {
+		border-color: var(--hub-form-invalid-border-color);
+	}
+}

package/styles/_tokens.scss

@@ -50,7 +50,16 @@
 	// ── Input ─────────────────────────────────────────────────────────────────
 	--hub-input-color: var(--hub-sys-text-primary, #212529);
 	--hub-input-bg: var(--hub-sys-surface-page, #fff);
-	--hub-input-font-family: var(--hub-ref-font-family-base, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif);
+	--hub-input-font-family: var(
+		--hub-ref-font-family-base,
+		system-ui,
+		-apple-system,
+		'Segoe UI',
+		Roboto,
+		'Helvetica Neue',
+		Arial,
+		sans-serif
+	);
 	--hub-input-font-size: var(--hub-ref-font-size-base, 1rem);
 	--hub-input-font-weight: var(--hub-ref-font-weight-base, 400);
 	--hub-input-line-height: var(--hub-ref-line-height-base, 1.5);
@@ -62,6 +71,14 @@
 	--hub-input-focus-border-color: var(--hub-sys-color-primary, #0d6efd);
 	--hub-input-focus-box-shadow: 0 0 0 var(--hub-form-focus-ring-width) var(--hub-form-focus-ring-color);
 	--hub-input-placeholder-color: var(--hub-sys-text-muted, #6c757d);
+
+	// Read-only fields. Not a faded variant of disabled: a read-only value is there
+	// to be read, so it keeps full contrast and loses only the chrome that promises
+	// you can type in it.
+	--hub-input-readonly-bg: transparent;
+	--hub-input-readonly-border-color: transparent;
+	--hub-input-readonly-color: var(--hub-input-color);
+	--hub-input-readonly-cursor: default;
 	--hub-input-transition: var(--hub-form-transition);
 	--hub-input-wrapper-gap: var(--hub-ref-space-2, 0.5rem);
 

package/styles/mixins/_file-input-theme.scss

@@ -34,47 +34,82 @@
 // scss-docs-start hub-file-input-theme
 @mixin hub-file-input-theme(
 	// ── Dropzone surface ──
-	$bg: null,                        // dropzone background
-	$color: null,                     // dropzone text colour
-	$border-width: null,              // dropzone border width
-	$border-style: null,              // dropzone border style (defaults to `dashed`)
-	$border-color: null,              // dropzone border colour at rest
-	$border-radius: null,             // dropzone corner radius
-	$padding-x: null,                 // dropzone horizontal padding
-	$padding-y: null,                 // dropzone vertical padding
-	$min-height: null,                // dropzone minimum height
-	$gap: null,                       // gutter between icon, prompt and hint
+	$bg: null,
+	// dropzone background
+	$color: null,
+	// dropzone text colour
+	$border-width: null,
+	// dropzone border width
+	$border-style: null,
+	// dropzone border style (defaults to `dashed`)
+	$border-color: null,
+	// dropzone border colour at rest
+	$border-radius: null,
+	// dropzone corner radius
+	$padding-x: null,
+	// dropzone horizontal padding
+	$padding-y: null,
+	// dropzone vertical padding
+	$min-height: null,
+	// dropzone minimum height
+	$gap: null,
+	// gutter between icon, prompt and hint
 	// ── States ──
-	$hover-bg: null,                  // background on hover
-	$hover-border-color: null,        // border colour on hover
-	$dragover-bg: null,               // background while a drag hovers the zone
-	$dragover-border-color: null,     // border colour while a drag hovers the zone
+	$hover-bg: null,
+	// background on hover
+	$hover-border-color: null,
+	// border colour on hover
+	$dragover-bg: null,
+	// background while a drag hovers the zone
+	$dragover-border-color: null,
+	// border colour while a drag hovers the zone
 	// ── Copy ──
-	$prompt-color: null,              // "drag files here" colour
-	$browse-color: null,              // "browse files" colour
-	$hint-color: null,                // constraints-hint colour
+	$prompt-color: null,
+	// "drag files here" colour
+	$browse-color: null,
+	// "browse files" colour
+	$hint-color: null,
+	// constraints-hint colour
 	// ── Glyphs (CSS masks) ──
-	$icon: null,                      // upload glyph shown in the dropzone
-	$icon-size: null,                 // upload glyph size
-	$icon-color: null,                // upload glyph tint
-	$file-icon: null,                 // per-file glyph, for files with no thumbnail
-	$file-icon-color: null,           // per-file glyph tint
-	$remove-icon: null,               // remove-button glyph
-	$cancel-icon: null,               // cancel-upload glyph
-	$retry-icon: null,                // retry-upload glyph
-	$done-icon: null,                 // finished-upload tick
-	$done-color: null,                // finished-upload tick + item border colour
+	$icon: null,
+	// upload glyph shown in the dropzone
+	$icon-size: null,
+	// upload glyph size
+	$icon-color: null,
+	// upload glyph tint
+	$file-icon: null,
+	// per-file glyph, for files with no thumbnail
+	$file-icon-color: null,
+	// per-file glyph tint
+	$remove-icon: null,
+	// remove-button glyph
+	$cancel-icon: null,
+	// cancel-upload glyph
+	$retry-icon: null,
+	// retry-upload glyph
+	$done-icon: null,
+	// finished-upload tick
+	$done-color: null,
+	// finished-upload tick + item border colour
 	// ── File list ──
-	$item-bg: null,                   // background of a file row / tile
-	$item-border-color: null,         // border of a file row / tile
-	$item-border-radius: null,        // corner radius of a file row / tile
-	$thumb-size: null,                // thumbnail size in list preview
-	$grid-min-width: null,            // minimum tile width in grid preview
-	$grid-thumb-height: null,         // thumbnail height in grid preview
+	$item-bg: null,
+	// background of a file row / tile
+	$item-border-color: null,
+	// border of a file row / tile
+	$item-border-radius: null,
+	// corner radius of a file row / tile
+	$thumb-size: null,
+	// thumbnail size in list preview
+	$grid-min-width: null,
+	// minimum tile width in grid preview
+	$grid-thumb-height: null,
+	// thumbnail height in grid preview
 	// ── Upload progress ──
-	$progress-height: null,           // progress-bar thickness
-	$progress-track-bg: null,         // progress-bar track colour
-	$progress-bar-bg: null            // progress-bar fill colour
+	$progress-height: null,
+	// progress-bar thickness
+	$progress-track-bg: null,
+	// progress-bar track colour
+	$progress-bar-bg: null // progress-bar fill colour
 ) {
 	// Dropzone surface
 	@if $bg != null {

package/styles/mixins/_forms-theme.scss

@@ -26,15 +26,20 @@
 // scss-docs-start hub-forms-theme
 @mixin hub-forms-theme(
 	// ── Focus ring (shared by every control) ──
-	$focus-ring-color: null,   // focus-ring colour
-	$focus-ring-width: null,   // focus-ring width
+	$focus-ring-color: null,
+	// focus-ring colour
+	$focus-ring-width: null,
+	// focus-ring width
 	// ── Validation accents ──
-	$invalid-color: null,      // invalid text + border colour
-	$valid-color: null,        // valid text + border colour
+	$invalid-color: null,
+	// invalid text + border colour
+	$valid-color: null,
+	// valid text + border colour
 	// ── State ──
-	$disabled-opacity: null,   // opacity applied to a disabled control
+	$disabled-opacity: null,
+	// opacity applied to a disabled control
 	// ── Motion ──
-	$transition: null          // border/box-shadow transition shared by inputs
+	$transition: null // border/box-shadow transition shared by inputs
 ) {
 	// Focus ring
 	@if $focus-ring-color != null {

package/styles/mixins/_segmented-theme.scss

@@ -26,15 +26,21 @@
 // scss-docs-start hub-segmented-theme
 @mixin hub-segmented-theme(
 	// ── Colour ──
-	$bg: null,                // the bar (track) surface
-	$selected-bg: null,       // selected pill / sliding-indicator fill
-	$selected-color: null,    // selected option text colour
+	$bg: null,
+	// the bar (track) surface
+	$selected-bg: null,
+	// selected pill / sliding-indicator fill
+	$selected-color: null,
+	// selected option text colour
 	// ── Shape ──
-	$radius: null,            // bar corner radius (pill radius derives from it)
+	$radius: null,
+	// bar corner radius (pill radius derives from it)
 	// ── Density / spacing ──
-	$gap: null,               // padding around, and gutter between, the options
-	$padding-x: null,         // option horizontal padding
-	$padding-y: null          // option vertical padding
+	$gap: null,
+	// padding around, and gutter between, the options
+	$padding-x: null,
+	// option horizontal padding
+	$padding-y: null // option vertical padding
 ) {
 	// Colour
 	@if $bg != null {

package/styles/readonly-theme.spec.ts

@@ -0,0 +1,71 @@
+import { Component, provideZonelessChangeDetection, signal } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { FormControl, ReactiveFormsModule } from '@angular/forms';
+import { provideHubForms } from '../services/forms-config';
+import { HubDatepickerComponent } from '../components/datepicker/datepicker.component';
+import { HubInputComponent } from '../components/input/input.component';
+import { HubTextareaComponent } from '../components/textarea/textarea.component';
+import { HubSelectComponent } from '../select/select.component';
+
+/**
+ * A read-only field has to look read-only.
+ *
+ * `readonly` reached the native attributes and stopped there, so the field went on
+ * drawing the border, the background and the focus affordance of something you can
+ * type in. It invites the click it then refuses — and next to a genuinely editable
+ * field there was nothing to tell the two apart.
+ *
+ * Read-only is not disabled, and the theme keeps them distinct on purpose: disabled
+ * says "not applicable now" and fades; read-only says "this is the value, just not
+ * yours to change here" and stays at full contrast, because it is there to be read.
+ */
+@Component({
+	standalone: true,
+	imports: [HubInputComponent, HubTextareaComponent, HubSelectComponent, HubDatepickerComponent, ReactiveFormsModule],
+	template: `
+		<hub-input [formControl]="ctrl" [readonly]="ro()" label="Text" />
+		<hub-textarea [formControl]="ctrl" [readonly]="ro()" label="Notes" />
+		<hub-select [formControl]="ctrl" [readonly]="ro()" label="Pick" />
+		<hub-datepicker [formControl]="ctrl" [readonly]="ro()" label="Date" />
+	`
+})
+class ReadonlyHostComponent {
+	readonly ctrl = new FormControl<any>('Something');
+	readonly ro = signal(false);
+}
+
+describe('read-only field theme', () => {
+	let fixture: any;
+
+	beforeEach(async () => {
+		TestBed.resetTestingModule();
+		await TestBed.configureTestingModule({
+			imports: [ReadonlyHostComponent],
+			providers: [provideZonelessChangeDetection(), provideHubForms()]
+		}).compileComponents();
+
+		fixture = TestBed.createComponent(ReadonlyHostComponent);
+		await fixture.whenStable();
+	});
+
+	const roots = (): HTMLElement[] => Array.from(fixture.nativeElement.querySelectorAll('.hub-field'));
+
+	it('marks nothing while the fields are editable', () => {
+		expect(roots().length).toBe(4);
+		expect(roots().every((el) => !el.classList.contains('hub-field--readonly'))).toBe(true);
+	});
+
+	it('marks every field when it turns read-only', async () => {
+		fixture.componentInstance.ro.set(true);
+		await fixture.whenStable();
+
+		expect(roots().every((el) => el.classList.contains('hub-field--readonly'))).toBe(true);
+	});
+
+	it('does not confuse read-only with disabled', async () => {
+		fixture.componentInstance.ro.set(true);
+		await fixture.whenStable();
+
+		expect(roots().some((el) => el.classList.contains('hub-field--disabled'))).toBe(false);
+	});
+});