@daffodil/design 0.91.0 → 0.92.3-rc.0

package/form-field/README.md

@@ -2,19 +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';
@@ -29,110 +30,64 @@ 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:
-
-```ts
-import { NgModule } from '@angular/core';
-import { DaffFormFieldModule } from '@daffodil/design/form-field';
-import { CustomComponent } from './custom.component';
-
-@NgModule({
-	declarations: [
-    CustomComponent,
-  ],
-  exports: [
-    CustomComponent,
-  ],
-  imports: [
-    DaffFormFieldModule,
-  ],
-})
-export class CustomComponentModule { }
-```
-
-> **Warning**
->
-> This method is deprecated. It's recommended to update all custom components to standalone.
+> **Deprecation notice:**
+> 
+> `DaffFormFieldModule` is deprecated. Use the standalone component imports instead.
 
 ## Anatomy
-
-### 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.
+A form field is composed of a wrapper, label, form control, prefix, suffix, action, hint, and error message:
 
 ```html
 <daff-form-field>
-  <daff-form-label>First Name</daff-form-label>
-  <input daff-input type="text" name="first-name" required />
+  <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>
 ```
 
+- **`<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.
 
-### Hints
-Hints are shown below the form field and are used to provide helpful information that assists users in correctly completing a field.
+## Features
 
-```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>
-```
-
-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>
-```
+### Appearances
+Form field supports two `appearances`: `fluid` and `fixed`. It will default to `fluid` if an `appearance` is not specified.
 
-### 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.
+- `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.
 
-```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>
-```
+<daff-docs-example-viewer example="form-field-appearances"></daff-docs-example-viewer>
 
 ### 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]` 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>
+> In a fluid appearance, avoid using a suffix alongside an action.
 
-<design-land-example-viewer-container example="form-field-with-suffix"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="form-field-with-action"></daff-docs-example-viewer>
 
-## 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.
+### Validated hints
+Use the `validated` property on `<daff-hint>` to apply validation styling:
 
-<design-land-example-viewer-container example="form-field-appearances"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="form-field-validated-hint"></daff-docs-example-viewer>
 
-## Setting a custom ID
+### 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
@@ -146,7 +101,7 @@ Form fields automatically generate IDs to handle accessibility. You can override
 >
 > 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
+### 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.
@@ -165,13 +120,21 @@ 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
 
-### Daffodil provides
+### Built-in behavior
 
 - `<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.
@@ -193,5 +156,7 @@ export class CustomControlComponent implements DaffFormFieldControl<any> {}
 
 ## 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

@@ -7,11 +7,10 @@ import { DaffFormFieldLabelDirective, DaffHintComponent, DaffErrorMessageCompone
 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>;
 }
@@ -25,11 +24,11 @@ interface DaffFormFieldState {
 }
 
 /**
- * An abstract class that form controls must implement to be used with the DaffFormFieldComponent.
+ * Form controls must extend this class to be used inside `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.
- *
+ * > 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> {
@@ -101,6 +100,9 @@ declare abstract class DaffFormFieldControl<T> {
 }
 
 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;
@@ -119,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;
     /**
@@ -178,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);

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

@@ -8,7 +8,7 @@ Image builds on Angular's [`NgOptimizedImage`](https://angular.dev/guide/image-o
 - Ensuring accessibility by requiring descriptive `alt` text
 - Maintaining proper aspect ratios for responsive designs
 
-<design-land-example-viewer-container example="basic-image"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="basic-image"></daff-docs-example-viewer>
 
 ## Usage
 
@@ -70,7 +70,7 @@ All four of the following attributes are required and will throw an error if mis
 ## Skeleton screen
 Use the `skeleton` property to display a placeholder skeleton screen that helps reduce load-time frustration.
 
-<design-land-example-viewer-container example="skeleton-image"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="skeleton-image"></daff-docs-example-viewer>
 
 ## Priority loading
 Use the `priority` property to mark an image as a priority for loading. Priority images are loaded eagerly and not lazy-loaded.