docs(design): tag examples with @example (#3392)

libs/design/button/src/button/basic/button.component.ts

@@ -13,7 +13,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffButtonComponent is a rectangular contained button with background color.
  *
- * ## Usage
+ * @example Basic button
  * ```html
  * <button daff-button>
  *  <div daffPrefix></div>

libs/design/button/src/button/flat/flat.component.ts

@@ -13,7 +13,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffFlatButtonComponent is a rectangular contained button no background.
  *
- * ## Usage
+ * @example Flat button
  * ```html
  * <button daff-flat-button>
  *  <div daffPrefix></div>

libs/design/button/src/button/icon/icon.component.ts

@@ -13,7 +13,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffIconButtonComponent is an icon button used with icon fonts.
  *
- * ## Usage
+ * @example Icon button
  * ```html
  * <button daff-icon-button>
  *  <fa-icon [icon]="faPlus"></fa-icon>

libs/design/button/src/button/raised/raised.component.ts

@@ -13,7 +13,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffRaisedButtonComponent is a rectangular contained button with background color and elevation.
  *
- * ## Usage
+ * @example Raised button
  * ```html
  * <button daff-raised-button>
  *  <div daffPrefix></div>

libs/design/button/src/button/stroked/stroked.component.ts

@@ -14,7 +14,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffStrokedButtonComponent is a rectangular outlined button with no background color.
  *
- * ## Usage
+ * @example Stroked button
  * ```html
  * <button daff-stroked-button>
  *  <div daffPrefix></div>

libs/design/button/src/button/underline/underline.component.ts

@@ -14,7 +14,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffUnderlineButtonComponent is a borderless button with a custom underline style.
  *
- * ## Usage
+ * @example Underline button
  * ```html
  * <button daff-underline-button>
  *  <div daffPrefix></div>

libs/design/sidebar/src/sidebar-viewport/sidebar-viewport.component.ts

@@ -46,23 +46,25 @@ import { DaffSidebarComponent } from '../sidebar/sidebar.component';
 import { DaffSidebarViewportBackdropComponent } from '../sidebar-viewport-backdrop/sidebar-viewport-backdrop.component';
 
 /**
- * The DaffSidebarViewport is the "holder" of sidebars throughout an entire application.
- * It's generally only used once, like
+ * The DaffSidebarViewportComponent is the "holder" of sidebars throughout an entire application.
  *
- * ```html
- * <daff-sidebar-viewport>
- *    <daff-sidebar></daff-sidebar>
- *    <p>Some Content</p>
- * </daff-sidebar-viewport>
- * ```
- *
- * Importantly, its possible for there to be multiple sidebars of many modes
- * at the same time. @see {@link DaffSidebarMode }
+ * `<daff-sidebar-viewport>` should only ever be used once in an application,
+ * but it's possible for there to be multiple sidebars of many modes
+ * at the same time. See {@link DaffSidebarMode}.
  *
  * Since this is a functional component, it's possible to have multiple "open" sidebars
  * at the same time. As a result, this component attempts to gracefully handle these situations.
  * However, importantly, there can only be one sidebar of each mode, on each side, at any given time.
+ *
  * If this is violated, this component will throw an exception.
+ *
+ * @example Using the sidebar viewport
+ * ```html
+ * <daff-sidebar-viewport>
+ *    <daff-sidebar></daff-sidebar>
+ *    <p>Site content</p>
+ * </daff-sidebar-viewport>
+ * ```
  */
 @Component({
   selector: 'daff-sidebar-viewport',

libs/design/src/core/article-encapsulated/article-encapsulated.directive.ts

@@ -7,15 +7,13 @@ import {
  * `DaffArticleEncapsulatedDirective` is used to encapsulate custom components within an article,
  * preventing {@link DaffArticleComponent } styles from bleeding into the component.
  *
- * ## Usage
- *
- * ### Implementing it as an attribute directive
+ * @example Implementing it as an attribute directive
  *
  * ```html
  * <my-custom-component daffArticleEncapsulated></my-custom-component>
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * @example Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -25,8 +23,9 @@ import {
  *  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.
+ * This directive will apply the `daff-ae` class to the component, ensuring that it is encapsulated from the article's styles.
  */
 @Directive({
   selector: '[daffArticleEncapsulated]',

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

@@ -26,15 +26,36 @@ const validateColor = (color: string) => {
  * 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
+ * Supported colors: `primary | secondary | tertiary | black | white | theme | theme-contrast`
  *
- * ### Implementing it as an attribute directive
+ * | Color | Class |
+ * | -------- | ----- |
+ * | `primary` | `.daff-primary`|
+ * | `secondary` | `.daff-secondary`|
+ * | `tertiary` | `.daff-tertiary`|
+ * | `black` | `.daff-black`|
+ * | `white` | `.daff-white`|
+ * | `theme` | `daff-theme`|
+ * | `theme-contrast` | `.daff-theme-contrast`|
+ *
+ * @example Implementing it as an attribute directive
  *
  * ```html
- * <div daffColorable [color]="componentColor">Colored content</div>
+ * <div daffColorable [color]="primary">Colored content</div>
+ * ```
+ *
+ *  ```scss
+ * .div {
+ *  &.daff-primary {
+ *    color: daff-color($primary);
+ *  }
+ * }
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * 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({
@@ -48,30 +69,19 @@ const validateColor = (color: string) => {
  *    },
  *  ],
  * })
- * export class CustomComponent { }
+ * export class CustomComponent {
+ *  @HostBinding('class.custom-component') class = true;
+ * }
  * ```
  *
  * ```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:
- *
- * - `daff-primary`: Applied when the color is `primary`.
- * - `daff-secondary`: Applied when the color is `secondary`.
- * - `daff-tertiary`: Applied when the color is `tertiary`.
- * - `daff-black`: Applied when the color is `black`.
- * - `daff-white`: Applied when the color is `white`.
- * - `daff-theme`: Applied when the color is `theme`.
- * - `daff-theme-contrast`: Applied when the color is `theme-contrast`.
  */
 @Directive({
   selector: '[daffColorable]',

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

@@ -9,9 +9,7 @@ import {
  * 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.
  *
- * ## Usage
- *
- * ### Implementing it as an attribute directive
+ * @example Implementing it as an attribute directive
  *
  * ```html
  * <div daffCompactable [compact]="isCompact">Content goes here</div>
@@ -20,7 +18,7 @@ import {
  * 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
+ * @example Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -37,20 +35,18 @@ import {
  * export class CustomComponent { }
  * ```
  *
+ * The directive applies the `daff-compact` class to the component and
+ * should be defined in your styles to display the compact state as desired.
+ *
  * ```scss
- * .custom-component {
+ * :host {
  *  padding: 8px 16px;
  *
  *  &.daff-compact {
  *    padding: 4px 8px;
  *  }
  * }
  * ```
- *
- * ## Styles
- *
- * The `daff-compact` class should be defined in your styles to display the compact
- * state as desired.
  */
 @Directive({
   selector: '[daffCompactable]',

libs/design/src/core/focus/stack.service.ts

@@ -25,6 +25,7 @@ export class DaffFocusStackService {
    * Generally, you will probably want to call this before you transition focus
    * onto a new element.
    *
+   * @example Using the push function
    * ```ts
    * this._focusStack.push(this._doc.activeElement);
    * ```
@@ -37,8 +38,9 @@ export class DaffFocusStackService {
   /**
    * Focuses on the HTML element at the top of a stack.
    *
+   * @example Using the focus function
    * ```ts
-   * this._focusStack.push(this._doc.activeElement);
+   * this._focusStack.focus(this._doc.activeElement);
    * ```
    */
   focus() {

libs/design/src/core/manage-container-layout/manage-container-layout.directive.ts

@@ -26,9 +26,7 @@ import {
  * 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
+ * @example Implementing it as an attribute directive
  *
  * ```html
  * <my-custom-component daffManageContainerLayout>
@@ -43,7 +41,7 @@ import {
  * }
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * @example Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({

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

@@ -16,7 +16,7 @@ import { DaffOpenableStateError } from './utils/state-error';
  * A directive that opens or closes a component. It should only be used as an [Angular Host Directive](https://angular.dev/guide/directives/directive-composition-api).
  * This directive is stateless by default, but it supports both a state and stateless implementation. Only one version should be used within a component.
  *
- * ## Example
+ * @example Using the DaffOpenableDirective
  * ```ts
  * import {
  *  Component,
@@ -74,6 +74,7 @@ export class DaffOpenableDirective implements DaffOpenable, OnChanges {
 
   /** Whether or not a component should handle state
    *
+   * @example Setting the `stateless` property on a component
    * ```ts
    * constructor(private openDirective: DaffOpenableDirective) {
    *  this.openDirective.stateless = false;

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

@@ -17,17 +17,15 @@ import {
  * `DaffSizableDirective` allows for dynamic sizing of a component by setting
  * CSS classes based on the specified size.
  *
- * ## Usage
- *
- * ### Implementing it as an attribute directive
+ * @example Implementing it as an attribute directive
  *
  * ```html
  * <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
+ * @example Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -45,7 +43,7 @@ import {
  * ```
  *
  * ```scss
- * .custom-component {
+ * :host {
  *  &.daff-sm {
  *    width: 24px;
  *  }
@@ -56,9 +54,7 @@ import {
  * }
  * ```
  *
- * ## Styles
- *
- * The directive applies the following CSS classes based on the size:
+ * The directive applies the following CSS classes to the component based on the size:
  *
  * - `daff-xs`: Applied when the size is `xs`.
  * - `daff-sm`: Applied when the size is `sm`.

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

@@ -12,15 +12,13 @@ import {
  * input property. When `skeleton` is `true`, the `daff-skeleton` CSS class
  * is applied, which should style the component to look like a loading placeholder.
  *
- * ## Usage
- *
- * ### Implementing it as an attribute directive
+ * @example Implementing it as an attribute directive
  *
  * ```html
  * <div daffSkeletonable [skeleton]="isLoading">Content</div>
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * @example Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -38,14 +36,14 @@ import {
  * ```
  *
  * ```scss
- * .daff-skeleton {
- *  @include state.skeleton-screen(48px, 24px);
+ * :host {
+ *  .daff-skeleton {
+ *    @include state.skeleton-screen(48px, 24px);
+ *  }
  * }
  * ```
  *
- * ## Styles
- *
- * The `daff-skeleton` class should be defined in your styles to display the loading
+ * The directive applies the `daff-skeleton` class to the component 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.
  */
 @Directive({