@daffodil/design 0.90.0 → 0.92.3-rc.0

package/switch/src/switch-theme.scss

@@ -1,45 +1,53 @@
 @use '../../scss/theming' as *;
 
+// stylelint-disable selector-class-pattern
 @mixin daff-switch-theme($theme) {
 	$primary: daff-get-palette($theme, primary);
 	$white: daff-get-base-color($theme, 'white');
 	$neutral: daff-get-palette($theme, neutral);
+	$base-contrast: daff-get-base-color($theme, base-contrast);
 	$mode: daff-get-theme-mode($theme);
 
 	.daff-switch {
-		&__toggle {
-			border: 2px solid transparent;
+		$root: '.daff-switch';
 
-			&.daff-checked {
+		&__label {
+			color: $base-contrast;
+		}
+
+		&.checked {
+			#{$root}__toggle {
 				background-color: daff-color($primary);
 			}
+		}
 
-			@include light($mode) {
+		@include light($mode) {
+			&__toggle {
 				background-color: daff-color($neutral, 30);
 
-				&:focus-within {
-					border: 2px solid daff-color($neutral, 20);
-				}
-
 				&::before {
 					background-color: $white;
 				}
-			}
 
-			@include dark($mode) {
-				background-color: daff-color($neutral, 80);
-
-				&:focus-within {
-					border: 2px solid daff-color($neutral, 90);
+				&:focus {
+					&::after {
+						outline: 2px solid rgba($base-contrast, 0.08);
+					}
 				}
+			}
+		}
+
+		@include dark($mode) {
+			&__toggle {
+				background-color: daff-color($neutral, 70);
 
 				&::before {
-					background-color: daff-color($neutral, 40);
+					background-color: $white;
 				}
 
-				&.daff-checked {
-					&::before {
-						background-color: $white;
+				&:focus {
+					&::after {
+						outline: 2px solid rgba($base-contrast, 0.15);
 					}
 				}
 			}

package/tabs/README.md

@@ -4,7 +4,7 @@ Tabs provide a way to navigate between panels that display related content witho
 ## Overview
 Tabs help organize related content into manageable sections, making it easier for users to find and focus on specific information. They're particularly useful for displaying content in compact spaces, such as within [modals](/libs/design/modal/README.md) or [cards](/libs/design/card/README.md), allowing users to switch between sections without navigating away from the current view.
 
-<design-land-example-viewer-container example="basic-tabs"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="basic-tabs"></daff-docs-example-viewer>
 
 ## Best practices
 

package/tabs/index.d.ts

@@ -1,7 +1,7 @@
 import * as i0 from '@angular/core';
 import { TemplateRef, ElementRef, AfterContentInit, OnInit, EventEmitter, QueryList, ChangeDetectorRef } from '@angular/core';
 import * as i1 from '@daffodil/design';
-import { DaffPrefixDirective, DaffSuffixDirective, DaffSelectableDirective } from '@daffodil/design';
+import { DaffDisableable, DaffDisableableDirective, DaffPrefixDirective, DaffSuffixDirective, DaffSelectableDirective } from '@daffodil/design';
 import { Location } from '@angular/common';
 import { Params } from '@angular/router';
 
@@ -23,11 +23,14 @@ import { Params } from '@angular/router';
  * </daff-tab>
  * ```
  */
-declare class DaffTabComponent {
+declare class DaffTabComponent implements DaffDisableable {
+    private disabledDirective;
     /**
+     * @docs-private
+     *
      * Whether the tab is disabled.
      */
-    disabled: boolean;
+    get disabled(): boolean;
     /**
      * @docs-private
      */
@@ -45,9 +48,9 @@ declare class DaffTabComponent {
      * @docs-private
      */
     panelId: string;
-    constructor();
+    constructor(disabledDirective: DaffDisableableDirective);
     static ɵfac: i0.ɵɵFactoryDeclaration<DaffTabComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<DaffTabComponent, "daff-tab", never, { "disabled": { "alias": "disabled"; "required": false; }; "id": { "alias": "id"; "required": false; }; }, {}, never, ["daff-tab-label", "daff-tab-panel"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DaffTabComponent, "daff-tab", never, { "id": { "alias": "id"; "required": false; }; }, {}, never, ["daff-tab-label", "daff-tab-panel"], true, [{ directive: typeof i1.DaffDisableableDirective; inputs: { "disabled": "disabled"; }; outputs: {}; }]>;
 }
 
 /**

package/tag/README.md

@@ -1,20 +1,12 @@
 # Tag
-Tags are compact visual indicators used to display short pieces of information, such as status, categories, or labels. They typically contain an icon, text label, and optionally a delete button for removable items.
+Tags are compact visual indicators used to display short pieces of information such as status, categories, or labels.
 
 ## Overview
 Tag supports flexible content projection to allow for various combinations of icons, labels, and interactive elements within a consistent container.
 
-| Attribute | Description |
-| --------- | ----------- |
-| `daff-tag` | Flexible tag container that can contain an icon, a label, and a dismiss button |
-
-
-**Basic tag**
-<design-land-example-viewer-container example="basic-tag"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="basic-tag"></daff-docs-example-viewer>
 
 ## Usage
-
-### Within a standalone component
 To use tag in a standalone component, import `DAFF_TAG_COMPONENTS` directly into your custom component.
 
 ```ts
@@ -31,10 +23,10 @@ export class CustomComponent {}
 ```
 
 ## Anatomy
-Tags should always have a label, unless you are only using an icon that is universally understood and accessible.
+Tags should always include a text label unless the icon is universally understood and accessible.
 
-### Icon support
-An icon can be rendered within the tag using the `daffPrefix` directive.
+### Icon
+Use the `[daffPrefix]` element to display a leading visual icon for a tag.
 
 ```html
 <daff-tag>
@@ -43,45 +35,47 @@ An icon can be rendered within the tag using the `daffPrefix` directive.
 </daff-tag>
 ```
 
-### Dismissible support
-A tag can be made dismissible by setting the `dismissible` property to `true`. This displays a close button that emits a `closeTag` event when clicked.
+## Features
+
+### Dismissible tag
+Set `dismissible` to `true` to display a close button. The button emits a `closeTag` event when clicked.
 
 ```html
-<daff-tag dismissible (closeTag)="onCloseTag()">
+<daff-tag [dismissible]="true" (closeTag)="onCloseTag()">
   <fa-icon [icon]="faCircleCheck" daffPrefix></fa-icon>
   <div>Tag label</div>
 </daff-tag>
 ```
 
-### Disabled state
-Tags can be disabled by setting the `disabled` property to `true`. Disabled tags cannot be dismissed.
+### Disabled
+Set `disabled` to `true` to disable the tag. Disabled tags cannot be dismissed.
 
 ```html
-<daff-tag dismissible disabled>
+<daff-tag [disabled]="true">
   <fa-icon [icon]="faCircleCheck" daffPrefix></fa-icon>
   <div>Disabled tag</div>
 </daff-tag>
 ```
 
 ## Sizes
-Use the `size` property to control tag dimensions. The default size is `md`. Supported sizes: `sm`, `md`, `lg`.
+Use the `size` property to control tag dimensions. Supported sizes: `sm`, `md` (default), `lg`.
 
-<design-land-example-viewer-container example="sizeable-tag"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="sizable-tag"></daff-docs-example-viewer>
 
 ## Colors
 Use the `color` property to change the color of a tag. Supported colors: `primary`, `secondary`, `tertiary`, `dark`, `light`, `theme`, `theme-contrast`.
 
-> Note: `dark`, `light`, and `theme` should be used on appropriate backgrounds for sufficient contrast.
-
-<design-land-example-viewer-container example="colorable-tag"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="colorable-tag"></daff-docs-example-viewer>
 
-## Status indicators
-Status indicators help users understand the type of information a tag represents and its importance relative to other tags in the same context. Use the `status` property to convey different semantic meanings. Supported status: `warn`, `critical`, `info`, `success`.
+## Status
+Use the `status` property to convey semantic meaning. Supported statuses: `warn`, `critical`, `info`, `success`.
 
-<design-land-example-viewer-container example="statusable-tag"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="statusable-tag"></daff-docs-example-viewer>
 
 ## Accessibility
-Daffodil uses semantic HTML elements and proper ARIA attributes to ensure an accessible experience by default.
+No additional accessibility annotations are needed.
+
+### Keyboard interactions
+Default tags are not interactive and do not receive focus.
 
-- The close button supports the `disabled` state with appropriate `aria-disabled` attributes
-- Use appropriate contrast ratios for text and background colors
+Dismissible tags include a focusable close button that can be activated with `Enter` or `Space`.

package/tag/index.d.ts

@@ -18,7 +18,7 @@ declare class DaffTagSizableDirective extends DaffSizableDirective<DaffTagSize>
  *
  * @example
  * ```html
- *  <daff-tag dismissible (closeTag)="onCloseTag()">
+ *  <daff-tag [dismissible]="true" (closeTag)="onCloseTag()">
  *    <fa-icon daffPrefix [icon]="faCircleCheck"></fa-icon>
  *    <div>Label</div>
  *  </daff-tag>

package/tag/src/tag-theme.scss

@@ -9,12 +9,14 @@
 	$critical: daff-get-palette($theme, critical);
 	$success: daff-get-palette($theme, success);
 	$neutral: daff-get-palette($theme, neutral);
+	$black: daff-get-base-color($theme, 'black');
+	$white: daff-get-base-color($theme, 'white');
 	$mode: daff-get-theme-mode($theme);
 
 	.daff-tag {
 		@include light($mode) {
 			background: daff-color($neutral, 20);
-			color: daff-color($neutral, 110);
+			color: $black;
 
 			&.daff-primary {
 				background: daff-color($primary, 10);
@@ -42,13 +44,13 @@
 			}
 
 			&.daff-theme {
-				background: daff-color($neutral, 0);
-				color: daff-color($neutral, 110);
+				background: $white;
+				color: $black;
 			}
 
 			&.daff-theme-contrast {
-				background: daff-color($neutral, 110);
-				color: daff-color($neutral, 0);
+				background: $black;
+				color: $white;
 			}
 
 			&.daff-warn {
@@ -102,13 +104,13 @@
 			}
 
 			&.daff-theme {
-				background: daff-color($neutral, 110);
-				color: daff-color($neutral, 0);
+				background: $black;
+				color: $white;
 			}
 
 			&.daff-theme-contrast {
-				background: daff-color($neutral, 0);
-				color: daff-color($neutral, 110);
+				background: $white;
+				color: $black;
 			}
 
 			&.daff-warn {

package/text-snippet/README.md

@@ -4,7 +4,7 @@ A text snippet is used to display a section of text with the ability to show or
 ## Overview
 Text snippets provide a way to show previews of long content while allowing users to expand and read the full text when needed. They help condense screen space by truncating long text blocks such as product descriptions, reviews, or articles. By default, content is displayed in condensed mode with a toggle button to expand or collapse the full text.
 
-<design-land-example-viewer-container example="basic-text-snippet"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="basic-text-snippet"></daff-docs-example-viewer>
 
 ## Best practices
 

package/text-snippet/src/text-snippet-theme.scss

@@ -0,0 +1,12 @@
+@use '../../scss/theming' as *;
+
+@mixin daff-text-snippet-theme($theme) {
+	$base-contrast: daff-get-base-color($theme, base-contrast);
+
+	.daff-text-snippet {
+		&__toggle {
+			border-bottom: thin solid $base-contrast;
+			color: $base-contrast;
+		}
+	}
+}

package/textarea/README.md

@@ -1,10 +1,10 @@
 # Textarea
-Textarea allows a native HTML `<textarea>` element to work with the [Form Field](/libs/design/src/atoms/form/form-field/README.md) component.
+Textarea works alongside the HTML textarea element, with additional custom styling and functionality.
 
 ## Overview
-The textarea component has the same functionality as a native HTML `<textarea>` element, with additional custom styling and functionality. It **cannot** be used by itself and must be contained within a [DaffFormFieldComponent](/libs/design/src/atoms/form/form-field/README.md).
+Textarea has the same functionality as a native HTML textarea element, with additional custom styling and functionality. It **cannot** be used by itself and must be contained within a [form field](/libs/design/src/atoms/form/form-field/README.md).
 
-<design-land-example-viewer-container example="basic-textarea"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="basic-textarea"></daff-docs-example-viewer>
 
 ## Usage
 To use textarea, import `DaffTextareaComponent` directly into your custom component:
@@ -22,7 +22,37 @@ import { DaffTextareaComponent } from '@daffodil/design/textarea';
 export class CustomComponent {}
 ```
 
-## Examples
+## Anatomy
+Textarea must be used inside `<daff-form-field>` to enable proper state management and provide enhanced UI features such as hints, error messages, prefixes, and suffixes. The form field component also ensures accessibility compliance. For more details, see the [form field documentation](/libs/design/form-field/README.md).
 
-### Disabled textarea
-<design-land-example-viewer-container example="basic-textarea"></design-land-example-viewer-container>
+### Basic structure
+```html
+<daff-form-field>
+  <daff-form-label>Comments</daff-form-label>
+  <textarea daff-textarea name="comments"></textarea>
+</daff-form-field>
+```
+
+## States
+
+### Disabled
+Textarea can be disabled in two ways: using Angular's reactive forms with `FormControl` or with the native HTML `disabled` attribute.
+
+<daff-docs-example-viewer example="textarea-disabled"></daff-docs-example-viewer>
+
+### Error
+Textarea supports validation and error messages through Angular's form validation system. Use `<daff-error-message>` within the form field to display context-specific error messages. Error messages automatically appear when the textarea is invalid and has been touched or submitted.
+
+<daff-docs-example-viewer example="textarea-error"></daff-docs-example-viewer>
+
+Multiple error messages can be displayed conditionally based on the type of validation error. The form field component handles the styling and positioning of error messages.
+
+## Hints
+Hints provide additional context or instructions to help users complete the textarea field correctly. Use `<daff-hint>` within the form field to display helpful information below the textarea. Unlike error messages, hints are always visible and provide guidance rather than validation feedback.
+
+<daff-docs-example-viewer example="textarea-hint"></daff-docs-example-viewer>
+
+## Accessibility
+When `<daff-form-label>` is used within `<daff-form-field>`, the label automatically associates with the textarea using the `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.

package/textarea/index.d.ts

@@ -24,16 +24,16 @@ declare class DaffTextareaComponent extends DaffFormFieldControl<string> impleme
      * @docs-private
      */
     get internalId(): string;
-    /**
-     * @docs-private
-     */
-    get disabledAttribute(): true;
     /**
      * @docs-private
      *
      * Implemented as part of DaffFormFieldControl.
      */
     disabled: boolean;
+    /**
+     * @docs-private
+     */
+    get disabledAttribute(): boolean;
     private _required;
     /**
      * @docs-private

package/toast/README.md

@@ -6,7 +6,7 @@ Toasts communicate updates about actions or events that require attention but ar
 
 For short messages tied to page-level content or actions, use the [Notification](/libs/design/notification/README.md) component.
 
-<design-land-example-viewer-container example="default-toast"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="default-toast"></daff-docs-example-viewer>
 
 ## Usage
 Add `provideDaffToast()` to the root provider of your application to enable toast functionality:
@@ -58,14 +58,14 @@ By default, toasts without actions dismiss automatically after `5000ms`. Toasts
 
 > Actionable toasts should remain persistent. If a duration is required, make sure it is long enough for users to engage with the actions.
 
-<design-land-example-viewer-container example="toast-with-custom-duration"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="toast-with-custom-duration"></daff-docs-example-viewer>
 
 ### Close button
 The close button is hidden by default. When a toast contains actions, the `dismissible` property is ignored.
 
 For non-actionable toasts, the close button can be displayed by setting `dismissible: true`.
 
-<design-land-example-viewer-container example="dismissible-toast"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="dismissible-toast"></daff-docs-example-viewer>
 
 ## Stacking
 A maximum of three toasts can be displayed at once. Toasts stack vertically with the most recent toast at the top.
@@ -73,7 +73,7 @@ A maximum of three toasts can be displayed at once. Toasts stack vertically with
 ## Statuses
 Toast status can be set when opening a toast through the `DaffToastService` by using a `DaffStatus` value.
 
-<design-land-example-viewer-container example="toast-status"></design-land-example-viewer-container>
+<daff-docs-example-viewer example="toast-status"></daff-docs-example-viewer>
 
 ## Positions
 On desktop, toasts appear in the top-right corner by default.

package/tree/README.md

@@ -1,20 +1,15 @@
 # Tree
-Trees are used to visualize hierarchial information. They are often used to display navigational structures like nested lists of links.
+Trees display hierarchical information in a nested, expandable format.
 
 ## Overview
-The `DaffTreeComponent` renders a tree structure. Typically, this is a structure of `<a>` and `<button>` elements that allow users to either navigate to a page, or explore the tree to find an item inside the tree that they want to navigate to.
+Trees help users navigate complex structures by organizing content into parent and child relationships. They're commonly used for navigation menus, file browsers, and category lists. For flat lists without nested content, use the [navigation list](/libs/design/list/README.md) instead.
 
-Instead of defining a recursive tree structure of components, which is often prohibitively slow when rendering large trees, the `DaffTreeComponent` renders a flattened tree, using padding to indicate the nesting level of the tree elements.
-
-Generally, tree usage consists of taking existing tree data, converting it to the `DaffTreeData` format, setting the `tree` input on the `DaffTreeComponent`, and providing templates for the cases where the tree element has children or not.
-
-<design-land-example-viewer-container example="basic-tree">
-</design-land-example-viewer-container>
+<daff-docs-example-viewer example="basic-tree"></daff-docs-example-viewer>
 
 ## Usage
 
 ### Within a standalone component
-To use sidebar in a standalone component, import `DAFF_TREE_COMPONENTS` directly into your custom component:
+To use tree in a standalone component, import `DAFF_TREE_COMPONENTS` directly into your custom component:
 
 ```ts
 import { DAFF_TREE_COMPONENTS } from '@daffodil/design/tree';
@@ -30,7 +25,7 @@ export class CustomComponent {}
 ```
 
 ### Within a module (deprecated)
-To use sidebar in a module, import `DaffTreeModule` into your custom module:
+To use tree in a module, import `DaffTreeModule` into your custom module:
 
 ```ts
 import { NgModule } from '@angular/core';
@@ -38,7 +33,7 @@ import { DaffTreeModule } from '@daffodil/design/tree';
 import { CustomComponent } from './custom.component';
 
 @NgModule({
-	declarations: [
+  declarations: [
     CustomComponent,
   ],
   exports: [
@@ -51,23 +46,45 @@ import { CustomComponent } from './custom.component';
 export class CustomComponentModule { }
 ```
 
+> **Warning**
+>
 > This method is deprecated. It's recommended to update all custom components to standalone.
 
-## Features
-The `DaffTreeComponent` controls the rendering of the structure of the tree and provides template slots so that you can control the ultimate UI rendered for each node.
+## Anatomy
+A tree consists of the following parts:
 
-Currently, we support two kind of templates: `daffTreeItemWithChildrenTpl` and `daffTreeItemTpl`. These templates allow you to control the content of each tree node. In the case of `daffTreeItemWithChildrenTpl`, a `click` handler will be automatically applied (along with an icon indicating the expanded state) to the template to allow users to automatically open and close the node.
+### Container
+`<daff-tree>`: The main wrapper that holds the tree and accepts your data.
 
-```html
-<ng-template #daffTreeItemWithChildrenTpl let-node>
-  <button daffTreeItem [node]="node">{{ node.title }} </button>
-</ng-template>
+### Node templates
+Define how each tree item looks:
+
+- `#daffTreeItemWithChildrenTpl`: For items that can expand to show children. Click handling and icons are added automatically.
+- `#daffTreeItemTpl`: For items at the end of a branch with no children.
 
-<ng-template #daffTreeItemTpl let-node>
-  <a daffTreeItem [node]="node" [routerLink]="node.url">{{ node.title }}</a>
-</ng-template>
+### Tree item
+`[daffTreeItem]`: Added to links or buttons inside your templates to connect them to the tree.
+
+### Basic structure
+```html
+<daff-tree [tree]="treeData">
+  <ng-template #daffTreeItemWithChildrenTpl let-node>
+    <button daffTreeItem [node]="node">{{ node.title }}</button>
+  </ng-template>
+
+  <ng-template #daffTreeItemTpl let-node>
+    <a daffTreeItem [node]="node" [routerLink]="node.url">{{ node.title }}</a>
+  </ng-template>
+</daff-tree>
 ```
 
 ## Accessibility
+The tree follows the [disclosure navigation menu](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/) pattern rather than the [tree view](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/) pattern.
+
+### Daffodil provides
+- Unique `id` automatically assigned to each tree item
+- `aria-expanded` indicating whether a parent item is open or closed
 
-The `DaffTreeComponent` follows the specification for a [disclosure navigation menu](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/) instead of a [tree view](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).
+### Developer responsibilities
+- Use links (`<a>`) for navigation and buttons (`<button>`) for expanding sections
+- Write clear, descriptive text for each tree item