@daffodil/design 0.90.0 → 0.92.3-rc.0

package/form-field/README.md

@@ -2,18 +2,20 @@
 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.
+Form field is 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.
 
+## Supported 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)
+- [Quantity Field](/libs/storefront/quantity-field/README.md)
 
 ## Usage
 
-### Within a standalone component
-To use form field in a standalone component, import `DAFF_FORM_FIELD_COMPONENTS` directly into your custom component:
+Import `DAFF_FORM_FIELD_COMPONENTS` into your component:
 
 ```ts
 import { DAFF_FORM_FIELD_COMPONENTS } from '@daffodil/design/form-field';
@@ -28,52 +30,65 @@ import { DAFF_FORM_FIELD_COMPONENTS } from '@daffodil/design/form-field';
 export class CustomComponent {}
 ```
 
-### Within a module (deprecated)
-To use form field in a module, import `DaffFormFieldModule` into your custom module:
+> **Deprecation notice:**
+> 
+> `DaffFormFieldModule` is deprecated. Use the standalone component imports instead.
 
-```ts
-import { NgModule } from '@angular/core';
-import { DaffFormFieldModule } from '@daffodil/design/form-field';
-import { CustomComponent } from './custom.component';
+## Anatomy
+A form field is composed of a wrapper, label, form control, prefix, suffix, action, hint, and error message:
 
-@NgModule({
-	declarations: [
-    CustomComponent,
-  ],
-  exports: [
-    CustomComponent,
-  ],
-  imports: [
-    DaffFormFieldModule,
-  ],
-})
-export class CustomComponentModule { }
+```html
+<daff-form-field>
+  <daff-form-label>Email</daff-form-label>
+  <fa-icon daffPrefix [icon]="faEnvelope"></fa-icon>
+  <input daff-input type="email" name="email" required />
+  <fa-icon daffSuffix [icon]="faCheck"></fa-icon>
+  <button daffFormFieldAction>Clear</button>
+  <daff-hint>We'll never share your email.</daff-hint>
+  <daff-error-message>Email is a required field.</daff-error-message>
+</daff-form-field>
 ```
 
-> Deprecation notice: This method is deprecated. It's recommended to update all custom components to standalone.
+- **`<daff-form-field>`**: The wrapper component that holds all form field content.
+- **`<daff-form-label>`**: The label for the form control. An asterisk is appended automatically when the control is required.
+- **Form control**: Any element implementing `DaffFormFieldControl` (See [supported controls](/libs/design/form-field/README.md#supported-controls))
+- **`[daffPrefix]`**: A leading visual, typically an icon, displayed before the form control.
+- **`[daffSuffix]`**: A trailing visual, typically an icon, displayed after the form control.
+- **`[daffFormFieldAction]`**: An action element, typically a button, attached to the form control.
+- **`<daff-hint>`**: Helpful information displayed below the form field.
+- **`<daff-error-message>`**: A validation error displayed below the form field, positioned after any hints.
+
+> **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.
+
+## Features
 
-## Appearances
+### 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>
+<daff-docs-example-viewer example="form-field-appearances"></daff-docs-example-viewer>
 
-## 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.
+### Action
+- 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.
 
-```html
-<daff-form-field>
-  <daff-form-label>First Name</daff-form-label>
-  <input daff-input type="text" name="first-name" required />
-</daff-form-field>
-```
+> **Note**
+>
+> In a fluid appearance, avoid using a suffix alongside an action.
 
-> 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.
+<daff-docs-example-viewer example="form-field-with-action"></daff-docs-example-viewer>
 
-## 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.
+### Validated hints
+Use the `validated` property on `<daff-hint>` to apply validation styling:
+
+<daff-docs-example-viewer example="form-field-validated-hint"></daff-docs-example-viewer>
+
+### Custom IDs
+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">
@@ -82,61 +97,11 @@ The `id` property allows you to set a custom identifier for the form field. Whil
 </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`.
 
-## Hints
-Hints are shown below the form field and are used to provide helpful information that assists users in correctly completing a field.
-
-```html
-<daff-form-field>
-  <daff-form-label>Password</daff-form-label>
-  <input daff-input type="text" name="password" />
-  <daff-hint>Password must have 8 characters.</daff-hint>
-</daff-form-field>
-```
-
-### Validated hints
-Use the `validated` property to show hints with validation styling:
-
-```html
-<daff-form-field>
-  <daff-form-label>Password</daff-form-label>
-  <input daff-input type="text" name="password" />
-  <daff-hint [validated]="isControlValid">Password must have 8 characters.</daff-hint>
-</daff-form-field>
-```
-
-## 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
-<daff-form-field>
-  <daff-form-label>Email*</daff-form-label>
-  <input daff-input type="text" name="email" />
-  @if (control.errors?.required) {
-    <daff-error-message>Email is a required field.</daff-error-message>
-  }
-</daff-form-field>
-```
-
-## Action
-Use the `[daffFormFieldAction]` directive 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.
-
-> 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>
-
-## Creating a custom form field control
+### Custom controls
 In addition to the controls that Daffodil Design provides, you can create your own custom control by using the `DaffFormFieldControl` interface.
 
 1. Your control component must implement the `DaffFormFieldControl` interface.
@@ -155,20 +120,29 @@ In addition to the controls that Daffodil Design provides, you can create your o
 export class CustomControlComponent implements DaffFormFieldControl<any> {}
 ```
 
+## Examples
+
+### Form field with prefix
+<daff-docs-example-viewer example="form-field-with-prefix"></daff-docs-example-viewer>
+
+### Form field with suffix
+<daff-docs-example-viewer example="form-field-with-suffix"></daff-docs-example-viewer>
+
 ## Best practices
 - Always provide labels for accessibility. Use `<daff-form-label>` for the best experience with auto-labelling controls.
 - Set meaningful custom IDs for form fields to improve accessibility and form management.
 
 ## Accessibility
 
-### Auto-labelling support
-For controls that support auto-labelling, the component automatically:
+### Built-in behavior
 
-- 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,11 +151,12 @@ 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
 
-### Error: A DaffFormFieldComponent must contain a DaffFormFieldControl
-This error appears when the `DaffFormFieldComponent` is missing a child control. Since form field is intended to only be used with a child component that implements `DaffFormFieldControl`, this error enforces that constraint at development time. To fix this, make sure that the form field has a child component that implements this interface.
+### Missing child control
+> A DaffFormFieldComponent must contain a DaffFormFieldControl
+
+`DaffFormFieldComponent` requires a child component that implements `DaffFormFieldControl`. To fix this, add a control like `daff-input` inside the form field.

package/form-field/index.d.ts

@@ -1,15 +1,16 @@
 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';
 
+/**
+ * DaffFormFieldActionDirective marks an element, typically a button, as an action attached to a form control inside `DaffFormFieldComponent`.
+ */
 declare class DaffFormFieldActionDirective {
-    /**
-     * @docs-private
-     */
-    class: boolean;
     static ɵfac: i0.ɵɵFactoryDeclaration<DaffFormFieldActionDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<DaffFormFieldActionDirective, "[daffFormFieldAction]", never, {}, {}, never, never, true, never>;
 }
@@ -23,28 +24,63 @@ interface DaffFormFieldState {
 }
 
 /**
+ * Form controls must extend this class to be used inside `DaffFormFieldComponent`.
  *
- * The class that a form control must **implement** in order to be
- * used with the DaffFormFieldComponent.
- *
- * 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.
+ * > **Note**
+ * > The control is defined as 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.
+ * >
+ * > 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,16 +89,20 @@ 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';
+/**
+ * DaffFormFieldComponent is a wrapping component that provides consistent styling and behavior for form control elements.
+ */
 declare class DaffFormFieldComponent implements AfterContentInit, AfterContentChecked, AfterViewInit {
     private cd;
     elementRef: ElementRef;
@@ -81,7 +121,7 @@ declare class DaffFormFieldComponent implements AfterContentInit, AfterContentCh
     _control: DaffFormFieldControl<unknown>;
     /**
      * @docs-private
-     * @deprecated Deprecated in version 0.86.0. Will be removed in v1.0.0. Deprecated in version 0.89.0. Will be removed in version 0.92.0.
+     * @deprecated Deprecated in version 0.86.0. Will be removed in version 1.0.0.
      */
     _formLabelDirective: DaffFormLabelDirective;
     /**
@@ -140,7 +180,7 @@ declare class DaffFormFieldComponent implements AfterContentInit, AfterContentCh
     get isRaised(): boolean;
     private _appearance;
     /**
-     * The appearance style of a form field, whether the label is fluid or fixed.
+     * The appearance of the form field. Defaults to `fluid`.
      */
     get appearance(): DaffFormFieldApperanace;
     set appearance(value: DaffFormFieldApperanace);
@@ -206,25 +246,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: {}; }]>;
 }
 
 /**
@@ -232,13 +254,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/hero/README.md

@@ -4,7 +4,7 @@ A hero is a top-level container designed to be large and captivating, typically
 ## Overview
 Heroes are the first visual element users see on a page and are intended to make a bold statement. They're flexible and extensible, including pre-styled content containers for common layouts such as titles, subtitles, taglines, and body content. Heroes should only be used once per page.
 
-<design-land-example-viewer-container example="basic-hero"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="basic-hero"></daff-docs-example-viewer>
 
 ## Best practices
 
@@ -103,21 +103,21 @@ A hero consists of the following components, displayed in the order listed:
 ### Colors
 Use the `color` property to change the background of a hero.
 
-<design-land-example-viewer-container example="hero-theming"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="hero-theming"></daff-docs-example-viewer>
 
 ### Text alignment
 Control hero-specific text alignment with the `textAlignment` property. It defaults to `left` and **does not** affect `[daffHeroBody]` content or nested elements.
 
-<design-land-example-viewer-container example="hero-text-alignment"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="hero-text-alignment"></daff-docs-example-viewer>
 
 ### Compact
 Use the `compact` property on hero to reduce padding and suit UIs with tighter spacing requirements.
 
-<design-land-example-viewer-container example="compact-hero"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="compact-hero"></daff-docs-example-viewer>
 
 ## Examples
 
 ### Hero with two columns
 Heroes are flexible enough to support custom grid layouts for more complex arrangements:
 
-<design-land-example-viewer-container example="hero-with-grid"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="hero-with-grid"></daff-docs-example-viewer>

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.
+<daff-docs-example-viewer example="basic-image"></daff-docs-example-viewer>
 
 ## 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.
+<daff-docs-example-viewer example="skeleton-image"></daff-docs-example-viewer>
 
-**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: {}; }]>;
 }
 
 /**