@filip.mazev/blocks 1.4.14 → 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.14",
+  "version": "1.4.16",
   "license": "MIT",
   "schematics": "./schematics/collection.json",
   "exports": {

package/schematics/ng-add/index.d.ts

@@ -1,14 +1,5 @@
 import { Rule } from '@angular-devkit/schematics';
-declare const LEGACY_PALETTES: {
-    readonly white: "graphite-sky-blue";
-    readonly blue: "azure-coral";
-    readonly purple: "violet-teal";
-    readonly orange: "tangerine-indigo";
-    readonly red: "scarlet-cyan";
-    readonly green: "lime-violet";
-};
 export interface NgAddOptions {
-    theme?: 'graphite-sky-blue' | 'azure-coral' | 'violet-teal' | 'tangerine-indigo' | 'scarlet-cyan' | 'lime-violet' | 'cyberpunk' | keyof typeof LEGACY_PALETTES;
+    theme?: 'carbon-cobalt' | 'azure-ember' | 'violet-teal' | 'tangerine-indigo' | 'brick-rose-cyan' | 'lime-violet' | 'cyberpunk';
 }
 export declare function ngAdd(options: NgAddOptions): Rule;
-export {};

package/schematics/ng-add/index.js

@@ -1,19 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ngAdd = ngAdd;
-const LEGACY_PALETTES = {
-    white: 'graphite-sky-blue',
-    blue: 'azure-coral',
-    purple: 'violet-teal',
-    orange: 'tangerine-indigo',
-    red: 'scarlet-cyan',
-    green: 'lime-violet'
-};
 function ngAdd(options) {
     return (tree, context) => {
         var _a;
-        const selected = (_a = options.theme) !== null && _a !== void 0 ? _a : 'graphite-sky-blue';
-        const theme = Object.prototype.hasOwnProperty.call(LEGACY_PALETTES, selected) ? LEGACY_PALETTES[selected] : selected;
+        const theme = (_a = options.theme) !== null && _a !== void 0 ? _a : 'carbon-cobalt';
         injectStyles(tree, context, { theme });
         return tree;
     };
@@ -70,8 +61,8 @@ function injectStyles(tree, context, options) {
         context.logger.info('Blocks SCSS configuration already exists. Skipping style injection.');
         return;
     }
-    const lightThemeVar = `$${(_f = options.theme) !== null && _f !== void 0 ? _f : 'graphite-sky-blue'}-light-theme`;
-    const darkThemeVar = `$${(_g = options.theme) !== null && _g !== void 0 ? _g : 'graphite-sky-blue'}-dark-theme`;
+    const lightThemeVar = `$${(_f = options.theme) !== null && _f !== void 0 ? _f : 'carbon-cobalt'}-light-theme`;
+    const darkThemeVar = `$${(_g = options.theme) !== null && _g !== void 0 ? _g : 'carbon-cobalt'}-dark-theme`;
     const blocksThemeSnippet = `
 @use '@filip.mazev/blocks' as *;
 
@@ -86,5 +77,5 @@ function injectStyles(tree, context, options) {
 }
 `;
     tree.overwrite(targetStylePath, blocksThemeSnippet + '\n' + content);
-    context.logger.info(`Successfully injected the ${(_h = options.theme) !== null && _h !== void 0 ? _h : 'graphite-sky-blue'} Blocks theme configuration into ${targetStylePath}.`);
+    context.logger.info(`Successfully injected the ${(_h = options.theme) !== null && _h !== void 0 ? _h : 'carbon-cobalt'} Blocks theme configuration into ${targetStylePath}.`);
 }

package/schematics/ng-add/schema.json

@@ -8,31 +8,25 @@
             "type": "string",
             "description": "Select a Blocks palette for your UI.",
             "enum": [
-                "graphite-sky-blue",
-                "azure-coral",
+                "carbon-cobalt",
+                "azure-ember",
                 "violet-teal",
                 "tangerine-indigo",
-                "scarlet-cyan",
+                "brick-rose-cyan",
                 "lime-violet",
-                "cyberpunk",
-                "white",
-                "blue",
-                "purple",
-                "orange",
-                "red",
-                "green"
+                "cyberpunk"
             ],
             "x-prompt": {
                 "message": "Which palette would you like to use?",
                 "type": "list",
                 "items": [
                     {
-                        "value": "graphite-sky-blue",
-                        "label": "Graphite / Sky Blue"
+                        "value": "carbon-cobalt",
+                        "label": "Carbon / Cobalt"
                     },
                     {
-                        "value": "azure-coral",
-                        "label": "Azure / Coral"
+                        "value": "azure-ember",
+                        "label": "Azure / Ember"
                     },
                     {
                         "value": "violet-teal",
@@ -43,8 +37,8 @@
                         "label": "Tangerine / Indigo"
                     },
                     {
-                        "value": "scarlet-cyan",
-                        "label": "Scarlet / Cyan"
+                        "value": "brick-rose-cyan",
+                        "label": "Brick Rose / Cyan"
                     },
                     {
                         "value": "lime-violet",
@@ -56,7 +50,7 @@
                     }
                 ]
             },
-            "default": "graphite-sky-blue"
+            "default": "carbon-cobalt"
         }
     }
 }

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

@@ -136,16 +136,7 @@ export interface BxAppearanceConfig {
   reducedTransparency: boolean;
 }
 export declare const DEFAULT_APPEARANCE_CONFIG: Readonly<BxAppearanceConfig>;
-export type BxThemeId = 'graphite-sky-blue' | 'azure-coral' | 'violet-teal' | 'tangerine-indigo' | 'scarlet-cyan' | 'lime-violet' | 'cyberpunk';
-export declare const LEGACY_THEME_IDS: {
-  readonly white: "graphite-sky-blue";
-  readonly blue: "azure-coral";
-  readonly purple: "violet-teal";
-  readonly orange: "tangerine-indigo";
-  readonly red: "scarlet-cyan";
-  readonly green: "lime-violet";
-};
-export type LegacyBxThemeId = keyof typeof LEGACY_THEME_IDS;
+export type BxThemeId = 'carbon-cobalt' | 'azure-ember' | 'violet-teal' | 'tangerine-indigo' | 'brick-rose-cyan' | 'lime-violet' | 'cyberpunk';
 export declare const THEME_PALETTES: ReadonlyArray<{
   id: BxThemeId;
   label: string;
@@ -183,7 +174,7 @@ export declare class ThemingService implements OnDestroy {
   constructor();
   ngOnDestroy(): void;
   setApplicationTheme(theme: DeviceTheme): void;
-  setPalette(palette: BxThemeId | LegacyBxThemeId): void;
+  setPalette(palette: BxThemeId): void;
   setHighContrast(enabled: boolean): void;
   setAppearance(settings: Partial<BxAppearanceConfig>): void;
   resetAppearance(): void;
@@ -225,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>;
@@ -237,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;
@@ -249,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, {
@@ -287,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;
@@ -306,7 +315,7 @@ export interface IBxI18nAdapter {
 export declare const DEFAULT_DEBOUNCE_TIME = 300;
 export declare const SCROLL_LOCK_INSTANCE_IDENTIFIER = "scroll_lock_instance_";
 export type SemanticColorToken = 'bg-canvas' | 'bg-surface' | 'bg-surface-alt' | 'bg-element' | 'bg-element-hover' | 'bg-element-active' | 'bg-neutral' | 'bg-neutral-hover' | 'bg-neutral-active' | 'primary' | 'primary-hover' | 'primary-active' | 'primary-subtle' | 'on-primary' | 'on-primary-hover' | 'on-primary-active' | 'accent' | 'accent-hover' | 'accent-active' | 'accent-subtle' | 'on-accent' | 'on-accent-hover' | 'on-accent-active' | 'text-accent' | 'border-accent' | 'text-heading' | 'text-primary' | 'text-secondary' | 'text-brand' | 'text-inverse' | 'text-info' | 'text-warn' | 'text-success' | 'text-danger' | 'border-subtle' | 'border-default' | 'border-strong' | 'border-brand' | 'border-info' | 'border-success' | 'border-warn' | 'border-danger' | 'bg-info' | 'bg-info-hover' | 'bg-info-active' | 'bg-info-disabled' | 'bg-info-subtle' | 'bg-success' | 'bg-success-hover' | 'bg-success-active' | 'bg-success-disabled' | 'bg-success-subtle' | 'bg-warn' | 'bg-warn-hover' | 'bg-warn-active' | 'bg-warn-disabled' | 'bg-warn-subtle' | 'bg-danger' | 'bg-danger-hover' | 'bg-danger-active' | 'bg-danger-disabled' | 'bg-danger-subtle' | 'scroll-bg' | 'scroll-thumb' | 'scroll-thumb-hover' | 'meta-brand-palette' | 'meta-accent-palette';
-export declare const PALETTE_NAMES: readonly ["primary", "accent", "graphite", "sky-blue", "azure", "coral", "violet", "teal", "tangerine", "indigo", "scarlet", "cyan", "lime", "cool-violet", "cyber-yellow", "cyber-slate", "blue", "orange", "purple", "red", "green", "danger", "warn", "success", "information", "neutral"];
+export declare const PALETTE_NAMES: readonly ["primary", "accent", "carbon", "cobalt", "ember", "brick-rose", "azure", "violet", "teal", "tangerine", "indigo", "cyan", "lime", "cool-violet", "cyber-yellow", "cyber-slate", "blue", "orange", "purple", "red", "green", "danger", "warn", "success", "information", "neutral"];
 export declare const SHADE_NUMBERS: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000];
 export declare const TOKEN_PREFIX = "bx";
 export declare const TOKEN_DELIMITER = "-";
@@ -358,8 +367,10 @@ export declare function getComplementaryToken(token: Color): Color;
  * Provides the inverted value of a given token color
  */
 export declare function invertPaletteToken(token: Color): Color;
-/** Resolve persisted and pre-rename palette IDs without resetting a user's selection. */
+/** Accept only current palette IDs when restoring a saved selection. */
 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;