feat(design): deprecate DaffColorable and clean up documentation (#4422)

Author: xelaint

libs/design/src/core/colorable/README.md

@@ -0,0 +1,72 @@
+# Colorable
+
+Colorable enforces consistent use of color across components.
+
+## Overview
+
+`DaffColorableDirective` applies color-specific CSS classes and validates the color in dev mode. When a color is set, the corresponding `daff-[color]` class is added.
+
+## Supported colors
+
+| Color | CSS Class |
+|---|---|
+| `primary` | `.daff-primary` |
+| `secondary` | `.daff-secondary` |
+| `tertiary` | `.daff-tertiary` |
+| `light` | `.daff-light` |
+| `dark` | `.daff-dark` |
+| `theme` | `.daff-theme` |
+| `theme-contrast` | `.daff-theme-contrast` |
+
+## Usage
+
+Use `daffColorable` as an attribute selector:
+
+```html
+<div daffColorable [color]="'primary'">Colored content</div>
+```
+
+Or as an Angular host directive:
+
+```ts
+import { DaffColorableDirective } from '@daffodil/design';
+
+@Component({
+  selector: 'custom-component',
+  template: 'custom-component.html',
+  hostDirectives: [
+    {
+      directive: DaffColorableDirective,
+      inputs: ['color'],
+    },
+  ],
+})
+export class CustomComponent { }
+```
+
+### Setting a default color
+
+Set `defaultColor` to apply a color when `color` is not explicitly provided:
+
+```ts
+constructor(private colorable: DaffColorableDirective) {
+  this.colorable.defaultColor = 'primary';
+}
+```
+
+## Styling
+
+Use the applied CSS class to style each color variant:
+
+```scss
+.custom-component {
+  &.daff-primary {
+    background: theme.daff-color($primary, 10);
+    color: daff-color($primary, 90);
+  }
+}
+```
+
+## Warnings
+
+A console warning is shown in dev mode if a color is not part of the supported colors.

libs/design/src/core/colorable/colorable.directive.spec.ts

@@ -11,7 +11,7 @@ import { By } from '@angular/platform-browser';
 
 import {
   DaffColorableDirective,
-  DaffPalette,
+  DaffColor,
 } from '@daffodil/design';
 
 @Component({
@@ -23,7 +23,7 @@ import {
 })
 
 class WrapperComponent {
-  color: DaffPalette;
+  color: DaffColor;
 }
 
 describe('@daffodil/design | DaffColorableDirective', () => {

libs/design/src/core/colorable/colorable.directive.ts

@@ -8,83 +8,23 @@ import {
 } from '@angular/core';
 
 import {
-  DaffColorable,
-  DaffPalette,
-  DaffPaletteEnum,
+  DaffColor,
+  DaffColorEnum,
 } from './colorable';
 
-const colorInPalette = (color: string) => (<any>Object).values(DaffPaletteEnum).includes(color);
+const isDaffColor = (color: string) => (<any>Object).values(DaffColorEnum).includes(color);
 
 const validateColor = (color: string) => {
   if(isDevMode()) {
-    if(color !== undefined && !colorInPalette(color)) {
-      console.warn(color + ' is not a valid color in DaffPalette');
+    if(color !== undefined && !isDaffColor(color)) {
+      console.warn(color + ' is not a valid color in DaffColor');
     }
   }
 };
 
 /**
- * `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.
- *
- * Supported colors: `primary | secondary | tertiary | light | dark | theme | theme-contrast`
- *
- * | Color | Class |
- * | -------- | ----- |
- * | `primary` | `.daff-primary`|
- * | `secondary` | `.daff-secondary`|
- * | `tertiary` | `.daff-tertiary`|
- * | `light` | `daff-light` |
- * | `dark` | `daff-dark` |
- * | `theme` | `daff-theme`|
- * | `theme-contrast` | `.daff-theme-contrast`|
- *
- *  `white` and `black` have been deprecated in favor of `light` and `dark`.
- *
- * @example Implementing it as an attribute directive
- *
- * ```html
- * <div daffColorable [color]="primary">Colored content</div>
- * ```
- *
- *  ```scss
- * .div {
- *  &.daff-primary {
- *    color: daff-color($primary);
- *  }
- * }
- * ```
- *
- * In this example, the `daff-primary` class is applied to the `div` element, allowing you to
- * use the color class to style the `div`.
- *
- * @example Implementing it as an Angular host directive
- *
- * ```ts
- * @Component({
- *  selector: 'custom-component',
- *  template: 'custom-component.html',
- *  hostDirectives: [
- *    {
- *      directive: DaffColorableDirective,
- *      inputs: ['color'],
- *    },
- *  ],
- * })
- * export class CustomComponent {
- *  @HostBinding('class.custom-component') class = true;
- * }
- * ```
- *
- * ```scss
- * .custom-component {
- *  &.daff-primary {
- *    background: daff-color($primary, 10);
- *    color: daff-color($primary, 90);
- *  }
- * }
- * ```
+ * Enforces consistent use of {@link DaffColor} on a component by applying
+ * color-specific CSS classes and validating the color in dev mode.
  */
 @Directive({
   selector: '[daffColorable]',
@@ -100,23 +40,16 @@ const validateColor = (color: string) => {
     '[class.daff-white]': 'color === "white"',
   },
 })
-export class DaffColorableDirective implements DaffColorable, OnChanges, OnInit {
+export class DaffColorableDirective implements OnChanges, OnInit {
   /**
-   * Sets the color on a component.
+   * The color of the component.
    */
-  @Input() color: DaffPalette;
+  @Input() color: DaffColor;
 
   /**
-   * Sets a default color.
-   *
-   * @example
-   * ```ts
-   * constructor(private colorableDirective: DaffColorableDirective) {
-   *  this.colorableDirective.defaultColor = 'theme';
-   * }
-   * ```
+   * The default color used when no color is set.
    */
-  defaultColor: DaffPalette;
+  defaultColor: DaffColor;
 
   /**
    * @docs-private

libs/design/src/core/colorable/colorable.ts

@@ -1,61 +1,66 @@
+/**
+ * @deprecated Deprecated in version 0.92.0. Will be removed in version 1.0.0.
+ */
 export interface DaffColorable {
-  color: DaffPalette;
+  color: DaffColor;
 }
 
 /**
- * These are the valid options that can be passed to a DaffColorable component.
+ * The available color options.
+ */
+export type DaffColor = 'primary' | 'secondary' | 'tertiary' | 'light' | 'dark' | 'theme' | 'theme-contrast' | 'black' | 'white' | undefined;
+
+/**
+ * @deprecated Deprecated in version 0.92.0. Will be removed in version 1.0.0.
  */
-export type DaffPalette = 'primary' | 'secondary' | 'tertiary' | 'light' | 'dark' | 'theme' | 'theme-contrast' | 'black' | 'white' | undefined;
+export type DaffPalette = DaffColor;
 
 /**
- * Enumerates the available color palette options for a component.
- * These values can be used to apply specific color styles to components within the application.
+ * The available color options.
  */
-export enum DaffPaletteEnum {
+export enum DaffColorEnum {
   /**
-   * Your primary color.
+   * The primary color.
    */
   Primary = 'primary',
 
   /**
-   * Your secondary color.
+   * The secondary color.
    */
   Secondary = 'secondary',
 
   /**
-   * Your tertiary color.
+   * The tertiary color.
    */
   Tertiary = 'tertiary',
 
   /**
-   * A light color that does not change based on the defined theme.
+   * A light color that does not change based on the theme.
    */
   Light = 'light',
 
   /**
-   * A dark color that does not change based on the defined theme.
+   * A dark color that does not change based on the theme.
    */
   Dark = 'dark',
 
   /**
-   * A color that matches the defined theme.
+   * A color that matches the theme.
    */
   Theme = 'theme',
 
   /**
-   * A color that contrasts against the defined theme.
+   * A color that contrasts against the theme.
    */
   ThemeContrast = 'theme-contrast',
 
   /**
    * @deprecated Deprecated in version 0.82.0. Will be removed in version 1.0.0.
-   * Black. It's dark.
    */
   Black = 'black',
 
   /**
    * @deprecated Deprecated in version 0.82.0. Will be removed in version 1.0.0.
-   * White. It's bright.
    */
   White = 'white',
 }

libs/design/src/core/colorable/public_api.ts

@@ -1,5 +1,6 @@
 export {
   DaffPalette,
-  DaffColorable,
+  DaffColor,
 } from './colorable';
+export { DaffColorable } from './colorable';
 export { DaffColorableDirective } from './colorable.directive';