@filip.mazev/blocks 1.4.15 → 1.4.16

package/forms/README.md

@@ -0,0 +1,80 @@
+# Forms
+
+Blocks fields use Angular 22 native signal control contracts and support Signal Forms, Reactive Forms, Template-driven Forms and standalone models. The library supplies presentation, interaction and accessible feedback; Angular owns validation and submission.
+
+## Import and basic usage
+
+```ts
+import { signal } from '@angular/core';
+import { form, FormField as SignalFormField, FormRoot, required, email } from '@angular/forms/signals';
+import { Button, InputField } from '@filip.mazev/blocks/forms';
+
+readonly accountModel = signal({ email: '' });
+readonly account = form(this.accountModel, (p) => {
+  required(p.email, { message: 'Email is required.' });
+  email(p.email, { message: 'Enter a valid email address.' });
+}, {
+  submission: {
+    ignoreValidators: 'none',
+    action: async (field) => { await this.api.save(field().value()); }
+  }
+});
+```
+
+Import `SignalFormField`, `FormRoot`, and the used Blocks controls into the standalone component. Alias Angular's directive because Blocks also exports its frame component as `FormField`.
+
+```html
+<form [formRoot]="account">
+  <bx-input-field label="Email" type="email" [formField]="account.email" />
+  <button bx-button type="submit" [disabled]="!account().valid()" [loading]="account().submitting()">Save</button>
+</form>
+```
+
+## Validation and state
+
+Schema validation supplies `required`, numeric and length limits, pattern metadata, errors, pending, disabled and readonly state to compatible controls. `valid()` is false while asynchronous validation is pending; `!invalid()` alone does not guarantee readiness.
+
+Use `ignoreValidators: 'none'` to gate the submission handler as well as the visible button while async validation is pending. Submission marks interactive fields touched, prevents duplicate submissions, and applies returned server errors to their target fields.
+
+Read field state through the Angular field tree. Derive UI with `computed()` and use `effect()` for side effects when validity or pending state changes. Cross-field validators belong in the schema and can read related values. Blocks does not implement a second validation engine.
+
+## Custom messages and visibility
+
+Shared inputs include `errorMessages`, `errorPriority`, `errorMode` (`first` or `all`), and `errorPolicy` (`touched`, `dirty`, `submitted`, `always`, or a function receiving `IErrorState`). The default reveals invalid fields after touch or submission. A function can include custom group or application state. The submitted policy tracks native form submission; when invoking submission programmatically outside the form element, pass the shared `submitted` input from application state.
+
+Message resolution prefers projected `bx-error` content, then field message overrides, schema messages, and configured defaults. `minlength`/`maxlength` Reactive Forms keys and `minLength`/`maxLength` Signal Forms kinds are recognized. Resolvers receive the original error plus its parameter payload.
+
+```ts
+readonly messages: ValidationMessages = {
+  minLength: ({ params }) => `Use at least ${params['minLength'] ?? params['requiredLength']} characters.`,
+  required: { key: 'validation.required' }
+};
+```
+
+Put this declaration in the appropriate constants or types-supporting module according to the house rules. Translation-key overrides receive error parameters through the existing adapter. Default messages can be replaced application-wide using `FormSettingsService.update()`; instance inputs take precedence. No error-message map is mandatory when the schema supplies messages.
+
+Projected `bx-error` supports rich content. `bx-hint`, `hint`, `hintEnd`, `bxPrefix`, and `bxSuffix` provide composable support and adornments. Supporting text and errors are associated automatically through `aria-describedby`. Custom error regions announce changes politely.
+
+## Compatibility and migration
+
+Existing `[formControl]`, `formControlName`, and `[(ngModel)]` component bindings remain supported. Text edits honor Reactive Forms blur and submit update strategies. `reset()` on the owning field/form clears component interaction and parse state. Standalone value controls expose `[(value)]`; checkbox-style controls expose `[(checked)]`.
+
+`BxBaseControl` remains available for existing external CVA subclasses; repeated touch reporting and schema error-message handling are corrected. New Blocks controls use native signal contracts, without implementing CVA on the same component. The legacy individually bound radio remains available, while new forms should bind a `RadioGroup` once around its options.
+
+Native `input`, `textarea` and `select` elements can use `bxInput` inside `bx-form-field`. Consumer components can provide `BX_FORM_FIELD_CONTROL` with `IFormFieldControl` to integrate their own state and focus behavior.
+
+## Asynchronous options
+
+Single select and multiselect support application-owned requests, comparison, templates, incremental loading and error/retry behavior. Their scroll wrappers use `LoadMoreDirective`, which can also be used by future paginated components. See the [load-more guide](directives/load-more/README.md) and [multiselect guide](components/multi-select/README.md).
+
+## Appearance and accessibility
+
+Controls follow Blocks semantic tokens, global theme/appearance configuration, reduced motion through `BxA11yService`, and reactive text resolution through `BX_I18N`. Configuration supports filled/outlined appearance, label placement, required markers, floating-label behavior and supporting-text sizing. Readonly and disabled states remain distinct in form state. All applicable controls accept `readOnly` as well as Angular Signal Forms' lowercase `readonly` contract. Either true value prevents edits while retaining focusability. Readonly controls use the default cursor and suppress pointer hover/click highlights and interactive glass lighting while preserving their static appearance and keyboard focus styling. Focus origin uses the shared Angular CDK focus monitor. Changes to readonly state update mounted surfaces, including projected native controls and grouped radios. Native select integration prevents interaction without binding a nonexistent native readOnly property.
+
+All existing form ellipsis and full-selection fit measurement use the public `TruncateDirective` from `@filip.mazev/blocks/primitives`. Set `[tooltipOnTruncate]="false"` on an input, search, select, or multiselect to retain truncation while supplying your own tooltip. `FormSettingsService.update({ tooltipOnTruncate: false })` changes the application default; instance inputs take precedence. Tag and menu controls expose the same opt-out. The public `TruncatedTextPipe` (`bxTruncatedText`) and `truncatedText()` helper support custom feedback. See the [shared truncation guide](../primitives/directives/truncate/README.md).
+
+## Playground
+
+Open `/components/signal-forms` for multiple controls, sync/async/cross-field rules, pending state, custom messages, server errors, disabled submission, dynamic disabled/readonly, reset and reactive validation status. Use Fill valid data to exercise submission, or an email containing `server-error` to see a server rejection.
+
+The load-more and selection pages include fake APIs, failed requests, retry and small pages without scrollbars.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@filip.mazev/blocks",
-  "version": "1.4.15",
+  "version": "1.4.16",
   "license": "MIT",
   "schematics": "./schematics/collection.json",
   "exports": {

package/types/filip.mazev-blocks-core.d.ts

@@ -216,10 +216,13 @@ export declare class BxShortcutService {
   static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
 export declare abstract class BxBaseControl<T> implements ControlValueAccessor, OnInit {
-  protected readonly isFieldRequired: import("@angular/core").Signal<boolean>;
+  private readonly focusMonitor;
+  private readonly focusElement;
+  private readonly destroyRef;
   protected readonly internalValue: import("@angular/core").WritableSignal<T | null>;
   protected readonly isTouched: import("@angular/core").WritableSignal<boolean>;
   protected readonly isDisabled: import("@angular/core").WritableSignal<boolean>;
+  protected readonly keyboardFocused: import("@angular/core").WritableSignal<boolean>;
   readonly ngControl: NgControl | null;
   readonly label: import("@angular/core").InputSignal<ResolvableText | undefined>;
   readonly placeholder: import("@angular/core").InputSignal<ResolvableText | undefined>;
@@ -228,6 +231,9 @@ export declare abstract class BxBaseControl<T> implements ControlValueAccessor,
   readonly ariaLabel: import("@angular/core").InputSignal<string | undefined>;
   readonly errorMessages: import("@angular/core").InputSignal<Partial<Record<ValidatorKey, ResolvableText>>>;
   readonly required: import("@angular/core").InputSignal<boolean>;
+  readonly readonly: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  readonly readOnly: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  readonly isReadonly: import("@angular/core").Signal<boolean>;
   readonly loading: import("@angular/core").InputSignal<boolean>;
   readonly disabled: import("@angular/core").InputSignal<boolean>;
   protected onChange: (value: T | null) => void;
@@ -240,6 +246,8 @@ export declare abstract class BxBaseControl<T> implements ControlValueAccessor,
   setDisabledState(isDisabled: boolean): void;
   protected updateValue(value: T | null): void;
   protected markAsTouched(): void;
+  protected onControlPointerDown(): void;
+  protected isFieldRequired(): boolean;
   protected get errorMessage(): ResolvableText | undefined;
   static ɵfac: i0.ɵɵFactoryDeclaration<BxBaseControl<any>, never>;
   static ɵdir: i0.ɵɵDirectiveDeclaration<BxBaseControl<any>, never, never, {
@@ -278,6 +286,16 @@ export declare abstract class BxBaseControl<T> implements ControlValueAccessor,
       "required": false;
       "isSignal": true;
     };
+    "readonly": {
+      "alias": "readonly";
+      "required": false;
+      "isSignal": true;
+    };
+    "readOnly": {
+      "alias": "readOnly";
+      "required": false;
+      "isSignal": true;
+    };
     "loading": {
       "alias": "loading";
       "required": false;
@@ -353,4 +371,6 @@ export declare function invertPaletteToken(token: Color): Color;
 export declare function resolveThemeId(value: string | null | undefined): BxThemeId | undefined;
 export declare function uuidv4(): string;
 export declare function inheritOverlayTheme(source: HTMLElement, pane: HTMLElement): () => void;
-export declare function trackOverlayOrigin(overlay: OverlayRef, origin: HTMLElement): () => void;
+export declare function trackOverlayOrigin(overlay: OverlayRef, origin: HTMLElement): () => void;
+/** Resolves text and tracks the adapter's language signal in the calling computation. */
+export declare function resolveText(text: ResolvableText | undefined, adapter: IBxI18nAdapter | null, params?: Record<string, unknown>): string;

package/types/filip.mazev-blocks-effects.d.ts

@@ -47,7 +47,7 @@ export declare class BxSurfaceDirective implements AfterViewInit {
   }, {}, never, never, true, never>;
 }
 /** Internal component integration. An explicit bxSurface directive takes precedence. */
-export declare function injectComponentSurface(options?: () => SurfaceOptions$1): void;
+export declare function injectComponentSurface(options?: () => SurfaceOptions$1, enabled?: () => boolean): void;
 export interface BxGlassLight {
   update(light: GlassLight): void;
   destroy(): void;