ng-hub-ui-forms 22.29.0 → 22.31.0

package/README.md

@@ -149,6 +149,40 @@ npm install ng-hub-ui-forms @angular/cdk
 
 ## ⚙️ Usage
 
+### Helper text
+
+Every field takes `formText`, and `formTextType` says where it goes.
+
+```html
+<!-- one sentence: below, where it is read without being asked for -->
+<hub-input label="Name" formText="As it appears on the card." />
+
+<!-- more than one: behind a question mark at the end of the label row -->
+<hub-input
+	label="IBAN"
+	formTextType="tooltip"
+	formText="The account the refund is paid into. It must belong to the cardholder — a transfer to a third party is rejected by the bank."
+/>
+```
+
+The rule the product settled on is **one sentence below, more than one in the tooltip**. A paragraph
+under every field turns a form into a document, pushes the next field off the screen, and is read by
+nobody who already knew what the field was for.
+
+The mark is pushed to the end of the label row, so a column of fields lines its question marks up
+instead of scattering them wherever each label happens to stop. It is a `<button>` beside the label
+and never inside it: activating a label focuses the control it names, so a mark nested in one would
+open the tooltip _and_ jump the caret into the field. Its accessible name is the helper text itself.
+
+`formTextType="tooltip"` needs the tooltip stylesheet, which this package does not pull in for you:
+
+```scss
+@use 'ng-hub-ui-utils/styles/tooltip';
+```
+
+A projected `hubFormText` template keeps its block below even in tooltip mode. The tooltip takes a
+string, so asking it to carry markup would drop the markup silently.
+
 ### Input
 
 ```html
@@ -210,6 +244,63 @@ provideHubForms({
 });
 ```
 
+#### Plain-text fields
+
+`readonly` and `plaintext` are the two halves of a shut field, and the difference is who the
+field is for. `readonly` is a _state_ of a field somebody is still filling in, and a theme can
+give it a box — `--hub-input-readonly-bg`, `--hub-input-readonly-border-color`, `-color` and
+`-cursor` exist to be set. `plaintext` is for a value that is merely being _shown_: a record
+open for consultation, a figure the server settled, a field a plan has locked. There the box is
+noise, and having none is what `plaintext` is rather than a colour it happens to wear.
+
+> **At the shipped defaults `readonly` already draws no box** — both those token defaults are
+> `transparent`, deliberately: a read-only value is there to be read and loses only the chrome
+> that promises you can type in it. Untouched, the two differ in the horizontal padding (12px
+> against 0), the inline border width, the cursor, and the affordances. Set the two tokens and
+> read-only takes the boxed look Bootstrap's own `readonly` ships with, while `plaintext` stays
+> flat:
+>
+> ```css
+> .hub-field--readonly {
+> 	--hub-input-readonly-bg: var(--hub-sys-surface-sunken);
+> 	--hub-input-readonly-border-color: var(--hub-sys-border-subtle);
+> }
+> ```
+
+The value steps back a shade. Inside a box the box does the separating; with it gone, label and
+value were the same colour and two pixels apart in size, so a column of them read as
+undifferentiated lines. The label is left exactly as every other field's — same tokens, same
+weight, because a form's labels keep one rhythm whatever state each field is in — and
+`--hub-input-plaintext-color` moves the value instead, to `gray-700` against the editable
+`gray-900`, with `--hub-input-plaintext-font-weight` one step lighter so it does not compete
+with its own label.
+
+The vertical padding moves rather than shrinks, through `--hub-input-plaintext-padding-block`:
+none above, the field's whole vertical padding below. Nothing above puts the value directly under
+its label — a label and its value are one thing and should read as a pair — while twice the
+padding below holds the control at exactly an editable field's height, so a grid mixing the two
+still lines up. Replace it with a single value and you give up one of the two.
+
+```html
+<!-- being filled in, so it keeps the box -->
+<hub-input formControlName="reference" label="Reference" [readonly]="true" />
+
+<!-- merely being read, so the box goes -->
+<hub-input formControlName="customer" label="Customer" [plaintext]="true" />
+<hub-textarea formControlName="notes" label="Notes" [rows]="3" [plaintext]="true" />
+```
+
+Modelled on Bootstrap's `.form-control-plaintext`, deliberately: the control stays a real
+`<input>` / `<textarea>`, so the `<label for>` still points at something labelable and the text
+stays selectable. A `<span>` would have broken both while going on looking right.
+
+The horizontal padding goes and the border turns transparent **without losing its width**, so a
+plain-text value lands on the same baseline as an editable neighbour and a form mixing the two
+does not stagger. `plaintext` implies `readonly` and the two presentations are exclusive, so
+they can never be passed in disagreement. Every affordance goes with the box — the clear button,
+a projected caret, a datepicker icon, and a textarea's character counter, which tells you how
+much room is left to type and so promises typing.
+
 ### Select
 
 ```html