@daffodil/design 0.75.0 → 0.76.0

package/fesm2022/daffodil-design.mjs

@@ -1460,18 +1460,45 @@ const validateColor = (color) => {
     }
 };
 /**
- * The `DaffColorableDirective` allows a component to conditionally apply color-specific
+ * `DaffColorableDirective` allows a component to conditionally apply color-specific
  * styles by setting CSS classes based on the specified color. This directive is useful
  * for applying different color palettes to a component in an Angular application.
  *
  * ## Usage
  *
- * ## Example
+ * ### Implementing it as an attribute directive
  *
  * ```html
  * <div daffColorable [color]="componentColor">Colored content</div>
  * ```
  *
+ * ### Implementing it as an Angular host directive
+ *
+ * ```ts
+ * @Component({
+ *  standalone: true,
+ *  selector: 'custom-component',
+ *  template: 'custom-component.html',
+ *  hostDirectives: [
+ *    {
+ *      directive: DaffColorableDirective,
+ *      inputs: ['color'],
+ *    },
+ *  ],
+ * })
+ * export class CustomComponent { }
+ * ```
+ *
+ * ```scss
+ * .custom-component {
+ *
+ *  &.daff-primary {
+ *    background: daff-color($primary, 10);
+ *    color: daff-color($primary, 90);
+ *  }
+ * }
+ * ```
+ *
  * ## Styles
  *
  * The directive applies the following CSS classes based on the color:
@@ -1585,23 +1612,50 @@ var DaffStatusEnum;
 })(DaffStatusEnum || (DaffStatusEnum = {}));
 
 /**
- * The `DaffStatusableDirective` allows a component to conditionally apply status-specific
+ * `DaffStatusableDirective` allows a component to conditionally apply status-specific
  * styles by setting CSS classes based on the specified status. This directive is useful
- * for indicating different statuses such as warnings, errors, or success states.
+ * for indicating different statuses such as warning, danger, or success states.
+ *
+ * ## Usage
  *
- * ## Example
+ * ### Implementing it as an attribute directive
  *
  * ```html
  * <div daffStatusable [status]="componentStatus">Status content</div>
  * ```
  *
+ * ### Implementing it as an Angular host directive
+ *
+ * ```ts
+ * @Component({
+ *  standalone: true,
+ *  selector: 'custom-component',
+ *  template: 'custom-component.html',
+ *  hostDirectives: [
+ *    {
+ *      directive: DaffStatusableDirective,
+ *      inputs: ['status'],
+ *    },
+ *  ],
+ * })
+ * export class CustomComponent { }
+ *
+ * ```scss
+ * .custom-component {
+ *
+ *  &.daff-danger {
+ *    background: daff-color($red, 10);
+ *    color: daff-color($red, 90);
+ *  }
+ * }
+ * ```
  * ## Styles
  *
  * The directive applies the following CSS classes based on the status:
  *
- * - `daff-warn`: Applied when the status is `Warn`.
- * - `daff-danger`: Applied when the status is `Danger`.
- * - `daff-success`: Applied when the status is `Success`.
+ * - `daff-warn`: Applied when the status is `warn`.
+ * - `daff-danger`: Applied when the status is `danger`.
+ * - `daff-success`: Applied when the status is `success`.
  */
 class DaffStatusableDirective {
     /**
@@ -1632,15 +1686,48 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.10", ngImpo
             }] } });
 
 /**
- * The `DaffSkeletonableDirective` allows a component to display a skeleton loading
+ * `DaffSkeletonableDirective` allows a component to display a skeleton loading
  * state by conditionally applying a CSS class. This is useful for indicating to
  * users that content is loading or being processed. This directive can be used to
  * apply a skeleton loading state to any component by toggling the `skeleton`
  * input property. When `skeleton` is `true`, the `daff-skeleton` CSS class
  * is applied, which should style the component to look like a loading placeholder.
  *
- * The styles for the`daff-skeleton` class should be defined component's
- * stylesheets to display the loading state as desired.
+ * ## Usage
+ *
+ * ### Implementing it as an attribute directive
+ *
+ * ```html
+ * <div daffSkeletonable [skeleton]="isLoading">Content</div>
+ * ```
+ *
+ * ### Implementing it as an Angular host directive
+ *
+ * ```ts
+ * @Component({
+ *  standalone: true,
+ *  selector: 'custom-component',
+ *  template: 'custom-component.html',
+ *  hostDirectives: [
+ *    {
+ *      directive: DaffSkeletonableDirective,
+ *      inputs: ['skeleton'],
+ *    },
+ *  ],
+ * })
+ * export class CustomComponent { }
+ * ```
+ *
+ * ```scss
+ * .daff-skeleton {
+ *  @include state.skeleton-screen(48px, 24px);
+ * }
+ * ```
+ *
+ * ## Styles
+ *
+ * The `daff-skeleton` class should be defined in your styles to display the loading
+ * state as desired. It can be used in conjuction with the `skeleton-screen` mixin, which provides predefined loading styles.
  */
 class DaffSkeletonableDirective {
     constructor() {
@@ -1670,21 +1757,52 @@ var DaffTextAlignmentEnum;
 })(DaffTextAlignmentEnum || (DaffTextAlignmentEnum = {}));
 
 /**
- * The `DaffTextAlignableDirective` allows for dynamic text alignment of a component
- * by setting CSS classes based on the specified text alignment. This directive is
+ * `DaffTextAlignableDirective` allows for dynamic text alignment of a component by
+ * setting CSS classes based on the specified text alignment. This directive is
  * useful when text alignment needs to be managed dynamically in an Angular component.
  *
- * ## Example
+ * ## Usage
+ *
+ * ### Implementing it as an attribute directive
  *
  * ```html
  * <div daffTextAlignable textAlignment="center">Aligned text</div>
+ *
+ * In this example, the `daff-center` class is added to the `div` element, allowing
+ * you to style the `div` as you wish using the class.
+ *
+ * ```
+ *
+ * ### Implementing it as an Angular host directive
+ *
+ * ```ts
+ * @Component({
+ *  standalone: true,
+ *  selector: 'custom-component',
+ *  template: 'custom-component.html',
+ *  hostDirectives: [
+ *    {
+ *      directive: DaffTextAlignableDirective,
+ *      inputs: ['textAlignment'],
+ *    },
+ *  ],
+ * })
+ * export class CustomComponent { }
+ * ```
+ *
+ * ```scss
+ * .custom-component {
+ *  &.daff-left {
+ *    text-align: left;
+ *  }
+ * }
  * ```
  *
  * ## Why not just use CSS?
  *
  * While the native CSS `text-align` property can be used for static text alignment,
  * the `DaffTextAlignableDirective` provides a structured and consistent way to handle
- * dynamic text alignment within Angular components in more complex use-cases
+ * dynamic text alignment within Angular components in more complex use-cases where the
  * application of `text-align:center` would cause unexpected side effects.
  */
 class DaffTextAlignableDirective {
@@ -1720,11 +1838,13 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.10", ngImpo
             }] } });
 
 /**
- * The `DaffCompactableDirective` allows a component to conditionally apply a compact
+ * `DaffCompactableDirective` allows a component to conditionally apply a compact
  * style by toggling a CSS class. This is useful for creating components that can
  * switch between regular and compact styles based on the `compact` property.
  *
- * ## Example
+ * ## Usage
+ *
+ * ### Implementing it as an attribute directive
  *
  * ```html
  * <div daffCompactable [compact]="isCompact">Content goes here</div>
@@ -1733,6 +1853,33 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.10", ngImpo
  * In this example, the `daff-compact` class is applied to the `div` element when
  * `isCompact` is `true`, making the `div` display its compact state.
  *
+ * ### Implementing it as an Angular host directive
+ *
+ * ```ts
+ * @Component({
+ *  standalone: true,
+ *  selector: 'custom-component',
+ *  template: 'custom-component.html',
+ *  hostDirectives: [
+ *    {
+ *      directive: DaffCompactableDirective,
+ *      inputs: ['compact'],
+ *    },
+ *  ],
+ * })
+ * export class CustomComponent { }
+ * ```
+ *
+ * ```scss
+ * .custom-component {
+ *  padding: 8px 16px;
+ *
+ *  &.daff-compact {
+ *    padding: 4px 8px;
+ *  }
+ * }
+ * ```
+ *
  * ## Styles
  *
  * The `daff-compact` class should be defined in your styles to display the compact
@@ -1759,7 +1906,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.10", ngImpo
             }] } });
 
 /**
- * A directive that gives a component the ability to manage a DaffContainerComponent's layout.
+ * `DaffManageContainerLayoutDirective` gives a component the ability to manage a `DaffContainerComponent`'s layout.
  * By including this directive, predetermined layout styles are passed down to the container.
  *
  * To understand the motivation for this directive, consider:
@@ -1780,6 +1927,43 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.10", ngImpo
  * The former may inappropriately constrain the width of its child elements,
  * while the latter (without `DaffManageContainerLayoutDirective`) may unexpectedly
  * interfere in the layout features of its parent element (i.e. display: grid, display: flex).
+ *
+ * ## Usage
+ *
+ * ### Implementing it as an attribute directive
+ *
+ * ```html
+ * <my-custom-component daffManageContainerLayout>
+ *  <daff-container size="lg"></daff-container>
+ * </my-custom-component>
+ * ```
+ *
+ * ```scss
+ * :host {
+ *  display: grid;
+ *  grid-template-columns: 1fr 1fr;
+ * }
+ * ```
+ *
+ * ### Implementing it as an Angular host directive
+ *
+ * ```ts
+ * @Component({
+ *  standalone: true,
+ *  selector: 'my-custom-component',
+ *  template: 'my-custom-component.html',
+ *  hostDirectives: [{ directive: DaffManageContainerLayoutDirective }],
+ * })
+ * export class MyCustomComponent { }
+ *
+ * ```scss
+ * :host {
+ *  display: grid;
+ *  grid-template-columns: 1fr 1fr;
+ * }
+ * ```
+ *
+ * This directive will apply the `daff-manage-container-layout` class to your component, ensuring that the styles set on `:host` are passed down to the container.
  */
 class DaffManageContainerLayoutDirective {
     constructor() {
@@ -1800,17 +1984,29 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.10", ngImpo
             }] } });
 
 /**
- * The `DaffArticleEncapsulatedDirective` is used to encapsulate custom components
- * within an article, preventing article styles from bleeding into the component.
+ * `DaffArticleEncapsulatedDirective` is used to encapsulate custom components within an article,
+ * preventing {@link DaffArticleComponent } styles from bleeding into the component.
+ *
+ * ## Usage
  *
- * ## Example
+ * ### Implementing it as an attribute directive
  *
  * ```html
  * <my-custom-component daffArticleEncapsulated></my-custom-component>
  * ```
  *
- * This directive will apply the `daff-ae` class to your component, ensuring that it is encapsulated
- * from the article's styles.
+ * ### Implementing it as an Angular host directive
+ *
+ * ```ts
+ * @Component({
+ *  standalone: true,
+ *  selector: 'custom-component',
+ *  template: 'custom-component.html',
+ *  hostDirectives: [{ directive: DaffArticleEncapsulatedDirective }],
+ * })
+ * export class CustomComponent { }
+ *
+ * This directive will apply the `daff-ae` class to your component, ensuring that it is encapsulated from the article's styles.
  */
 class DaffArticleEncapsulatedDirective {
     constructor() {
@@ -2155,14 +2351,57 @@ var DaffSizableEnum;
 })(DaffSizableEnum || (DaffSizableEnum = {}));
 
 /**
- * The `DaffSizableDirective` allows for dynamic sizing of a component by setting
+ * `DaffSizableDirective` allows for dynamic sizing of a component by setting
  * CSS classes based on the specified size.
  *
- * ## Example
+ * ## Usage
+ *
+ * ### Implementing it as an attribute directive
  *
  * ```html
- * <div daffSizable [size]="componentSize">Sized content</div>
+ * <div daffSizable [size]="small">Sized content</div>
  * ```
+ * In this example, the `daff-small` class is applied to the `div` element, allowing you to
+ * use the class to style the `div`.
+ *
+ * ### Implementing it as an Angular host directive
+ *
+ * ```ts
+ * @Component({
+ *  standalone: true,
+ *  selector: 'custom-component',
+ *  template: 'custom-component.html',
+ *  hostDirectives: [
+ *    {
+ *      directive: DaffSizableDirective,
+ *      inputs: ['size'],
+ *    },
+ *  ],
+ * })
+ * export class CustomComponent { }
+ * ```
+ *
+ * ```scss
+ * .custom-component {
+ *  &.daff-sm {
+ *    width: 24px;
+ *  }
+ *
+ *  &.daff-md {
+ *    width: 32px;
+ *  }
+ * }
+ * ```
+ *
+ * ## Styles
+ *
+ * The directive applies the following CSS classes based on the size:
+ *
+ * - `daff-xs`: Applied when the size is `xs`.
+ * - `daff-sm`: Applied when the size is `sm`.
+ * - `daff-md`: Applied when the size is `md`.
+ * - `daff-lg`: Applied when the size is `lg`.
+ * - `daff-xl`: Applied when the size is `xl`.
  */
 class DaffSizableDirective {
     /**