@daffodil/design 0.89.0 → 0.91.0

package/form-field/README.md

@@ -2,13 +2,14 @@
 Form field is a wrapping component that provides consistent styling and behavior for form control elements.
 
 ## Overview
-It's used to style certain controls that would otherwise be impossible to style with normal css and organize labels, hints, and error messages alongside their associated form controls.
+It's used to style certain controls that would otherwise be impossible to style with normal CSS and organize labels, hints, and error messages alongside their associated form controls.
 
 The following Daffodil Design components are designed to work inside a form field:
 
 - [Native Input](/libs/design/input/README.md)
 - [Native Select](/libs/design/native-select/README.md)
 - [Native Textarea](/libs/design/textarea/README.md)
+- [Custom Select](/libs/design/select/README.md)
 
 ## Usage
 
@@ -50,17 +51,13 @@ import { CustomComponent } from './custom.component';
 export class CustomComponentModule { }
 ```
 
-> Deprecation notice: This method is deprecated. It's recommended to update all custom components to standalone.
+> **Warning**
+>
+> This method is deprecated. It's recommended to update all custom components to standalone.
 
-## Appearances
-Form field supports two `appearances`: `fluid` and `fixed`. It will default to `fluid` if an `appearance` is not specified.
-
-- `fluid`: alternate, stylized UI where the label is placed inside of the form control.
-- `fixed`: corresponds with a traditional style where the label is positioned outside and above the form control.
+## Anatomy
 
-<design-land-example-viewer-container example="form-field-appearances"></design-land-example-viewer-container>
-
-## Labels
+### Labels
 Use `<daff-form-label>` to help users understand what information to enter into a form control. Form fields should always have labels. If a form control is marked as required, an asterisk will be attached to the label to indicate that it's a required field.
 
 ```html
@@ -70,21 +67,11 @@ Use `<daff-form-label>` to help users understand what information to enter into
 </daff-form-field>
 ```
 
-> Deprecation notice: The `DaffFormLabelDirective` (using `daffFormLabel` on `<label>`) is deprecated and will be removed in `v1.0.0`. Use `<daff-form-label>` instead for new implementations.
-
-## Setting a custom ID
-The `id` property allows you to set a custom identifier for the form field. While auto-labelling is supported for native HTML form elements (e.g. `<input>`, `<select>`, and `<textarea>`) to ensure that accessibility is baked into the component, it's recommended to set meaningful, custom IDs for better accessibility and form management.
+> **Warning**
+>
+> The `DaffFormLabelDirective` (using `daffFormLabel` on `<label>`) is deprecated and will be removed in `v1.0.0`. Use `<daff-form-label>` instead for new implementations.
 
-```html
-<daff-form-field id="user-email-address">
-  <daff-form-label>Email Address</daff-form-label>
-  <input daff-input type="email" />
-</daff-form-field>
-```
-
-> When you provide a custom `id`, the `<daff-form-label>` automatically gets the correct `for` attribute that matches the control's `id`.
-
-## Hints
+### Hints
 Hints are shown below the form field and are used to provide helpful information that assists users in correctly completing a field.
 
 ```html
@@ -95,7 +82,6 @@ Hints are shown below the form field and are used to provide helpful information
 </daff-form-field>
 ```
 
-### Validated hints
 Use the `validated` property to show hints with validation styling:
 
 ```html
@@ -106,7 +92,7 @@ Use the `validated` property to show hints with validation styling:
 </daff-form-field>
 ```
 
-## Errors
+### Errors
 Error messages are used to display validation errors. They are shown under the form field and are placed last if hints are also used.
 
 ```html
@@ -119,23 +105,47 @@ Error messages are used to display validation errors. They are shown under the f
 </daff-form-field>
 ```
 
-## Action
-Use the `[daffFormFieldAction]` directive to add an action element to a form field.
+### Action
+Use the `[daffFormFieldAction]` element to add an action element to a form field.
 
 - Fluid appearance: The action is positioned within the form control's UI.
 - Fixed appearance: The action is positioned adjacent to the form control's UI.
 
 <design-land-example-viewer-container example="form-field-with-action"></design-land-example-viewer-container>
 
-## Prefix and suffix
-Use the `[daffPrefix]` and `[daffSuffix]` directives to display leading or trailing visuals, typically icons, on either side of the form control.
+### Prefix and suffix
+Use the `[daffPrefix]` and `[daffSuffix]` elements to display leading or trailing visuals, typically icons, on either side of the form control.
 
+> **Note**
+>
 > In a fluid appearance, avoid using suffix alongside an action.
 
 <design-land-example-viewer-container example="form-field-with-prefix"></design-land-example-viewer-container>
 
 <design-land-example-viewer-container example="form-field-with-suffix"></design-land-example-viewer-container>
 
+## Appearances
+Form field supports two `appearances`: `fluid` and `fixed`. It will default to `fluid` if an `appearance` is not specified.
+
+- `fluid`: alternate, stylized UI where the label is placed inside of the form control.
+- `fixed`: corresponds with a traditional style where the label is positioned outside and above the form control.
+
+<design-land-example-viewer-container example="form-field-appearances"></design-land-example-viewer-container>
+
+## Setting a custom ID
+Form fields automatically generate IDs to handle accessibility. You can override this by setting a custom `id` on the form field when needed for specific labeling requirements.
+
+```html
+<daff-form-field id="user-email-address">
+  <daff-form-label>Email Address</daff-form-label>
+  <input daff-input type="email" />
+</daff-form-field>
+```
+
+> **Note**
+>
+> When you provide a custom `id`, the `<daff-form-label>` automatically gets the correct `for` attribute that matches the control's `id`.
+
 ## Creating a custom form field control
 In addition to the controls that Daffodil Design provides, you can create your own custom control by using the `DaffFormFieldControl` interface.
 
@@ -161,14 +171,15 @@ export class CustomControlComponent implements DaffFormFieldControl<any> {}
 
 ## Accessibility
 
-### Auto-labelling support
-For controls that support auto-labelling, the component automatically:
+### Daffodil provides
 
-- Associates labels with controls using `for` and `id` attributes.
-- Provides proper ARIA relationships.
-- Warns in development mode if proper labelling is missing.
+- `<daff-hint>` and `<daff-error-message>` are linked to the form control via `aria-describedby`.
+- `<daff-error-message>` is set to `aria-live="polite"` by default so that assistive technology only announce errors when they appear.
+- For controls that support auto-labelling, the component automatically associates labels with controls using `for` and `id` attributes.
 
-If a `<daff-form-label>` is not specified, use the `label` element to associate text with form elements explicitly. The `for` attribute of the label must exactly match the `id` of the form control.
+> **Note**
+>
+> If a `<daff-form-label>` is not specified, use the `<label>` element to associate text with form elements explicitly. The `for` attribute of the label must exactly match the `id` of the form control.
 
 ```html
 <daff-form-field>
@@ -177,9 +188,8 @@ If a `<daff-form-label>` is not specified, use the `label` element to associate
 </daff-form-field>
 ```
 
-### ARIA support
-- `<daff-hint>` and `<daff-error-message>` are linked to the form control via `aria-describedby`.
-- `<daff-error-message>` is set to `aria-live="polite"` by default so that assistive technology only announce errors when they appear.
+### Developer responsibilities
+- Always provide labels for accessibility. Use `<daff-form-label>` within `<daff-form-field>` for the best experience with auto-labelling controls.
 
 ## Troubleshooting
 

package/form-field/index.d.ts

@@ -1,7 +1,9 @@
 import * as i0 from '@angular/core';
 import { AfterContentInit, AfterContentChecked, AfterViewInit, ElementRef, ChangeDetectorRef } from '@angular/core';
-import * as i4 from '@daffodil/design';
+import * as i3 from '@daffodil/design';
 import { DaffPrefixDirective, DaffSuffixDirective, DaffFormLabelDirective } from '@daffodil/design';
+import * as i2 from '@daffodil/design/form';
+import { DaffFormFieldLabelDirective, DaffHintComponent, DaffErrorMessageComponent } from '@daffodil/design/form';
 import { NgControl } from '@angular/forms';
 import { BehaviorSubject, Observable } from 'rxjs';
 
@@ -23,28 +25,63 @@ interface DaffFormFieldState {
 }
 
 /**
+ * An abstract class that form controls must implement to be used with the DaffFormFieldComponent.
  *
- * The class that a form control must **implement** in order to be
- * used with the DaffFormFieldComponent.
+ * > **Note**
+ * > This is an abstract class instead of an interface to support Angular's dependency injection. Interfaces are erased during TypeScript compilation and cannot be used as DI tokens.
  *
- * You may ask: "Why are you implementing an abstract class, not extending it?"
- * We do this so that the Angular DI container can match the class token. A typical
- * interface would be "more accurate" here, but since interfaces don't exist
- * in javascript, they get thrown out by the typescript compiler and cannot
- * be used for the necessary dependency injection.
+ * > By using an abstract class, the Angular DI container can match the class token for injection.
  */
 declare abstract class DaffFormFieldControl<T> {
     ngControl: NgControl | null;
+    /**
+     * The type of the control (e.g., 'input', 'select', 'textarea').
+     * Used to apply control-specific styling or behavior.
+     */
     abstract readonly controlType?: any;
+    /**
+     * Whether the control supports automatic label behavior.
+     * When `true`, the form field will associate the label with the control using `for` and `id` attributes.
+     *
+     * Defaults to `true`.
+     */
     readonly supportsAutoLabelling?: boolean;
+    /**
+     * Whether the control currently has focus.
+     */
     abstract readonly focused: boolean;
+    /**
+     * Whether the control is required for form validation.
+     */
     abstract readonly required: boolean;
+    /**
+     * Whether the control is disabled.
+     */
     abstract readonly disabled: boolean;
+    /**
+     * The unique identifier for the control element.
+     */
     readonly id?: string;
+    /**
+     * Whether the label should be in the raised position.
+     * By default, matches the focused state.
+     */
     get raised(): boolean;
+    /**
+     * Sets focus on the control.
+     *
+     * @param event - Optional event that triggers the focus.
+     */
     abstract focus(event?: Event): void;
+    /**
+     * The current value of the control.
+     */
     abstract readonly value: T;
     constructor(ngControl: NgControl | null);
+    /**
+     * Computes the current state of the form field control.
+     * Combines control properties and form validation state.
+     */
     get state(): DaffFormFieldState;
     _stateChanges: BehaviorSubject<{
         focused: boolean;
@@ -53,40 +90,27 @@ declare abstract class DaffFormFieldControl<T> {
         error: boolean;
         valid: boolean;
     }>;
+    /**
+     * Observable stream of state changes for the form field control.
+     */
     stateChanges: Observable<DaffFormFieldState>;
+    /**
+     * Emits the current state.
+     */
     emitState(deferred?: boolean): void;
 }
 
-declare class DaffFormFieldLabelDirective {
-    static ɵfac: i0.ɵɵFactoryDeclaration<DaffFormFieldLabelDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<DaffFormFieldLabelDirective, "daff-form-label", never, {}, {}, never, never, true, never>;
-}
-
 type DaffFormFieldApperanace = 'fluid' | 'fixed';
 declare class DaffFormFieldComponent implements AfterContentInit, AfterContentChecked, AfterViewInit {
     private cd;
     elementRef: ElementRef;
     /** @docs-private */
-    class: boolean;
-    /** @docs-private */
-    get isSelectField(): boolean;
-    /**
-     * @docs-private
-     */
-    get selectClass(): boolean;
+    get isNativeSelect(): boolean;
     constructor(cd: ChangeDetectorRef, elementRef: ElementRef);
     /** @docs-private */
     _prefix: DaffPrefixDirective;
-    /**
-     * @docs-private
-     */
-    get hasPrefixClass(): DaffPrefixDirective;
     /** @docs-private */
     _suffix: DaffSuffixDirective;
-    /**
-     * @docs-private
-     */
-    get hasSuffixClass(): DaffSuffixDirective | DaffFormFieldActionDirective;
     /**
      * @docs-private
      *
@@ -121,10 +145,6 @@ declare class DaffFormFieldComponent implements AfterContentInit, AfterContentCh
      * form field should be marked as error.
      */
     isError: boolean;
-    /**
-     * @docs-private
-     */
-    get errorClass(): boolean;
     /**
      * @docs-private
      *
@@ -139,10 +159,6 @@ declare class DaffFormFieldComponent implements AfterContentInit, AfterContentCh
      * form field should be marked as disabled.
      */
     isDisabled: boolean;
-    /**
-     * @docs-private
-     */
-    get disabledClass(): boolean;
     /**
      * @docs-private
      *
@@ -150,10 +166,6 @@ declare class DaffFormFieldComponent implements AfterContentInit, AfterContentCh
      * form field should be marked as valid.
      */
     isValid: boolean;
-    /**
-     * @docs-private
-     */
-    get validClass(): boolean;
     /**
      * @docs-private
      *
@@ -163,25 +175,13 @@ declare class DaffFormFieldComponent implements AfterContentInit, AfterContentCh
     /**
      * @docs-private
      */
-    get focusedClass(): boolean;
-    /**
-     * @docs-private
-     */
-    get raisedClass(): boolean;
+    get isRaised(): boolean;
     private _appearance;
     /**
-     * The appearance style of a form field, whether the label is fluid or fixed.
+     * The appearance style of a form field, whether the label is `fluid` or `fixed`.
      */
     get appearance(): DaffFormFieldApperanace;
     set appearance(value: DaffFormFieldApperanace);
-    /**
-     * @docs-private
-     */
-    get fluidClass(): boolean;
-    /**
-     * @docs-private
-     */
-    get fixedClass(): boolean;
     /**
      * @docs-private
      */
@@ -244,25 +244,7 @@ declare class DaffFormFieldComponent implements AfterContentInit, AfterContentCh
      */
     ngAfterContentChecked(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<DaffFormFieldComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<DaffFormFieldComponent, "daff-form-field", never, { "appearance": { "alias": "appearance"; "required": false; }; "id": { "alias": "id"; "required": false; }; }, {}, ["_prefix", "_suffix", "_control", "_formLabelDirective", "_formFieldLabelDirective", "_action", "_hint", "_error"], ["*", "[daffPrefix]", "*", "[daffSuffix]", "daff-hint", "daff-error-message", "[daffFormFieldAction]", "label[daffFormLabel]", "daff-form-label", "label"], true, [{ directive: typeof i4.DaffSkeletonableDirective; inputs: { "skeleton": "skeleton"; }; outputs: {}; }]>;
-}
-
-declare class DaffErrorMessageComponent {
-    static ɵfac: i0.ɵɵFactoryDeclaration<DaffErrorMessageComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<DaffErrorMessageComponent, "daff-error-message", never, {}, {}, never, ["*"], true, never>;
-}
-
-declare class DaffHintComponent {
-    /**
-     * @docs-private
-     */
-    class: boolean;
-    /**
-     * Displays a validated hint UI.
-     * */
-    validated: boolean;
-    static ɵfac: i0.ɵɵFactoryDeclaration<DaffHintComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<DaffHintComponent, "daff-hint", never, { "validated": { "alias": "validated"; "required": false; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DaffFormFieldComponent, "daff-form-field", never, { "appearance": { "alias": "appearance"; "required": false; }; "id": { "alias": "id"; "required": false; }; }, {}, ["_prefix", "_suffix", "_control", "_formLabelDirective", "_formFieldLabelDirective", "_action", "_hint", "_error"], ["*", "[daffPrefix]", "*", "[daffSuffix]", "daff-hint", "daff-error-message", "[daffFormFieldAction]", "label[daffFormLabel]", "daff-form-label", "label"], true, [{ directive: typeof i3.DaffSkeletonableDirective; inputs: { "skeleton": "skeleton"; }; outputs: {}; }]>;
 }
 
 /**
@@ -270,13 +252,13 @@ declare class DaffHintComponent {
  */
 declare class DaffFormFieldModule {
     static ɵfac: i0.ɵɵFactoryDeclaration<DaffFormFieldModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<DaffFormFieldModule, never, [typeof DaffFormFieldComponent, typeof DaffErrorMessageComponent, typeof DaffHintComponent, typeof i4.DaffFormLabelModule], [typeof DaffFormFieldComponent, typeof DaffErrorMessageComponent, typeof DaffHintComponent, typeof i4.DaffFormLabelModule]>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<DaffFormFieldModule, never, [typeof DaffFormFieldComponent, typeof i2.DaffErrorMessageComponent, typeof i2.DaffHintComponent, typeof i2.DaffFormFieldLabelDirective, typeof i3.DaffFormLabelModule], [typeof DaffFormFieldComponent, typeof i2.DaffErrorMessageComponent, typeof i2.DaffHintComponent, typeof i2.DaffFormFieldLabelDirective, typeof i3.DaffFormLabelModule]>;
     static ɵinj: i0.ɵɵInjectorDeclaration<DaffFormFieldModule>;
 }
 
 /**
  * @docs-private
  */
-declare const DAFF_FORM_FIELD_COMPONENTS: readonly [typeof DaffFormFieldComponent, typeof DaffErrorMessageComponent, typeof DaffFormLabelDirective, typeof DaffHintComponent, typeof DaffPrefixDirective, typeof DaffSuffixDirective, typeof DaffFormFieldLabelDirective, typeof DaffFormFieldActionDirective];
+declare const DAFF_FORM_FIELD_COMPONENTS: readonly [typeof DaffFormFieldComponent, typeof DaffFormLabelDirective, typeof DaffPrefixDirective, typeof DaffSuffixDirective, typeof DaffFormFieldActionDirective, typeof DaffHintComponent, typeof DaffFormFieldLabelDirective, typeof DaffErrorMessageComponent];
 
-export { DAFF_FORM_FIELD_COMPONENTS, DaffErrorMessageComponent, DaffFormFieldActionDirective, DaffFormFieldComponent, DaffFormFieldControl, DaffFormFieldLabelDirective, DaffFormFieldModule, DaffHintComponent };
+export { DAFF_FORM_FIELD_COMPONENTS, DaffFormFieldActionDirective, DaffFormFieldComponent, DaffFormFieldControl, DaffFormFieldModule };

package/image/README.md

@@ -1,15 +1,14 @@
 # Image
-Image utilizes the native HTML `<img>` element to display responsive images on a page and prevent content jumping while images are loading. 
+Image has built-in performance and accessibility optimizations that allow users to easily display responsive images.
 
 ## Overview
-`<daff-image>` is an opinionated version that encourages friendly end-user usage.
+Image builds on Angular's [`NgOptimizedImage`](https://angular.dev/guide/image-optimization) to provide responsive images with stable layouts out of the box. It helps to avoid common image-related performance and accessibility issues by:
 
-<design-land-example-viewer-container example="load-image"></design-land-example-viewer-container>
+- Preventing layout shift with required `width` and `height` attributes
+- Ensuring accessibility by requiring descriptive `alt` text
+- Maintaining proper aspect ratios for responsive designs
 
-## Attributes
-The `src`, `width`, `height`, and `alt` attributes must be defined. An error will be thrown any of these attributes are missing.
-
-`width` and `height` are required to calculate the aspect ratio of an image, used for the [aspect ratio padding trick](https://css-tricks.com/aspect-ratio-boxes/) that helps to prevent content jumping while images are loading. The `width` and `height` values are rendered as pixels.
+<design-land-example-viewer-container example="basic-image"></design-land-example-viewer-container>
 
 ## Usage
 
@@ -17,6 +16,7 @@ The `src`, `width`, `height`, and `alt` attributes must be defined. An error wil
 To use image in a standalone component, import `DAFF_IMAGE_COMPONENTS` directly into your custom component:
 
 ```ts
+import { Component } from '@angular/core';
 import { DAFF_IMAGE_COMPONENTS } from '@daffodil/design/image';
 
 @Component({
@@ -38,7 +38,7 @@ import { DaffImageModule } from '@daffodil/design/image';
 import { CustomComponent } from './custom.component';
 
 @NgModule({
-	declarations: [
+  declarations: [
     CustomComponent,
   ],
   exports: [
@@ -51,21 +51,29 @@ import { CustomComponent } from './custom.component';
 export class CustomComponentModule { }
 ```
 
+> **Warning**
+>
 > This method is deprecated. It's recommended to update all custom components to standalone.
 
-## Errors
+## Required attributes
+All four of the following attributes are required and will throw an error if missing:
+
+| Attribute | Description |
+| --------- | ----------- |
+| `src` | The image source URL |
+| `alt` | Alternative text describing the image |
+| `width` | The intrinsic width of the image in pixels |
+| `height` | The intrinsic height of the image in pixels |
 
-**DaffImageComponent must have a defined src attribute.**
-This error appears when `<daff-image>` is missing a `src` attribute.
+## Features
 
-**DaffImageComponent must have a defined alt attribute.**
-This error appears when `<daff-image>` is missing an `alt` attribute. The `alt` tag specifies an alternate text for an image.
+## Skeleton screen
+Use the `skeleton` property to display a placeholder skeleton screen that helps reduce load-time frustration.
 
-**DaffImageComponent must have a defined width attribute.**
-This error appears when `<daff-image>` is missing a `width` attribute. The width must be defined in order to correctly calculate the aspect ratio of the image.
+<design-land-example-viewer-container example="skeleton-image"></design-land-example-viewer-container>
 
-**DaffImageComponent must have a defined height attribute.**
-This error appears when `<daff-image>` is missing a `height` attribute. The height must be defined in order to correctly calculate the aspect ratio of the image.
+## Priority loading
+Use the `priority` property to mark an image as a priority for loading. Priority images are loaded eagerly and not lazy-loaded.
 
-## Accessbility
-Images should be given a meaningful description using the native `alt` attribute to ensure an accessible experience by default. An error will be thrown if the `alt` attribute is missing.
+## Accessibility
+Provide concise, meaningful descriptions that convey the content and purpose of the image by using the `alt` attribute. An error will be thrown if `alt` is missing.

package/image/index.d.ts

@@ -30,6 +30,11 @@ declare class DaffImageComponent implements OnInit {
      */
     get height(): number;
     set height(value: number);
+    /**
+     * Whether the image should be treated as a priority image for loading.
+     * Priority images are loaded eagerly and not lazy-loaded.
+     */
+    priority: i0.InputSignal<boolean>;
     /**
      * Emits when the image has loaded.
      */
@@ -50,7 +55,7 @@ declare class DaffImageComponent implements OnInit {
      */
     get _aspectRatio(): SafeStyle;
     static ɵfac: i0.ɵɵFactoryDeclaration<DaffImageComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<DaffImageComponent, "daff-image", never, { "src": { "alias": "src"; "required": false; }; "alt": { "alias": "alt"; "required": false; }; "width": { "alias": "width"; "required": false; }; "height": { "alias": "height"; "required": false; }; }, { "load": "load"; }, never, never, true, [{ directive: typeof i1.DaffSkeletonableDirective; inputs: { "skeleton": "skeleton"; }; outputs: {}; }]>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DaffImageComponent, "daff-image", never, { "src": { "alias": "src"; "required": false; }; "alt": { "alias": "alt"; "required": false; }; "width": { "alias": "width"; "required": false; }; "height": { "alias": "height"; "required": false; }; "priority": { "alias": "priority"; "required": false; "isSignal": true; }; }, { "load": "load"; }, never, never, true, [{ directive: typeof i1.DaffSkeletonableDirective; inputs: { "skeleton": "skeleton"; }; outputs: {}; }]>;
 }
 
 /**