diff --git a/docs/xplat/src/content/en/components/layouts/accordion.mdx b/docs/xplat/src/content/en/components/layouts/accordion.mdx index 3ecda645ec..6224c6ff21 100644 --- a/docs/xplat/src/content/en/components/layouts/accordion.mdx +++ b/docs/xplat/src/content/en/components/layouts/accordion.mdx @@ -1,92 +1,77 @@ --- -title: "{Platform} Accordion | Accordion | Infragistics" -description: Accordion is used to build vertical expandable panels in accordion menu. -keywords: "{Platform} Accordion, {ProductName}, Infragistics" +title: "{Platform} Accordion Component | Layouts | Infragistics" +description: "{Platform} Accordion is a layout component for organizing expandable content panels in a single vertical container." +keywords: "{Platform} Accordion, accordion component, expandable panels, {ProductName}, Infragistics" license: MIT mentionedTypes: ["Accordion", "Infragistics.Controls.Layouts.Implementation.ExpansionPanel"] namespace: Infragistics.Controls +relatedComponents: ["ExpansionPanel"] llms: - description: "The {ProductName} Accordion is a GUI component for building vertical expandable panels with clickable headers and associated content sections, displayed in a single container." + description: "The {ProductName} Accordion is a layout component for organizing expandable content panels in a single vertical container." --- import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +# Accordion Component +The {ProductName} Accordion is a layout component for organizing expandable content panels in a single vertical container. -# {Platform} Accordion Overview +## Overview -The {ProductName} Accordion is a GUI component for building vertical expandable panels with clickable headers and associated content sections, displayed in a single container. The accordion is commonly used to reduce the need of scrolling across multiple sections of content on a single page. It offers keyboard navigation and API to control the underlying panels' expansion state. +The accordion groups related content into stacked sections so you can reveal details progressively instead of showing every section at once. -Users are enabled to interact and navigate among a list of items, such as thumbnails or labels. Each one of those items can be toggled (expanded or collapsed) in order to reveal the containing information. Depending on the configuration, there can be a single or multiple expanded items at a time. +### When to Use -## {Platform} Accordion Example +Use the accordion when you need to organize secondary content, FAQs, settings groups, or other vertically stacked sections that users expand on demand. -The following is a basic {ProductName} Accordion example of a FAQ section. It operates as an accordion, with individually working sections. You can toggle each text block with a single click, while expanding multiple panels at the same time. This way you can read information more easily, without having to go back and forth between an automatically expanding and collapsing panel, which conceals the previously opened section every time. +### When Not to Use -In it, you can see how to define an accordion and its expansion panels. The sample also demonstrates the two types of expansion behavior. The switch button sets the property to toggle between single and multiple branches to be expanded at a time. +Use the [Expansion Panel](./expansion-panel.md) when you need a single standalone expandable section instead of a coordinated container that manages multiple panels together. - + -## Getting Started with {Platform} Accordion +## Getting Started - - -First, you need to install the {ProductName} by running the following command: +Before you add the accordion, complete the shared {ProductName} setup in the [Getting Started](../general-getting-started.md) topic. -```cmd -npm install {PackageWebComponents} -``` + -Before using the , you need to register it as follows: +Register the accordion and expansion panel components before you use them. ```ts -import { defineComponents, IgcAccordionComponent } from 'igniteui-webcomponents'; +import { + defineComponents, + IgcAccordionComponent, + IgcExpansionPanelComponent, +} from 'igniteui-webcomponents'; -defineComponents(IgcAccordionComponent); +defineComponents(IgcAccordionComponent, IgcExpansionPanelComponent); ``` -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. - -First, you need to the install the corresponding {ProductName} npm package by running the following command: - -```cmd -npm install igniteui-react -``` - -You will then need to import the and the and its necessary CSS, like so: +Import the React wrappers and the theme stylesheet before you render the accordion. ```tsx -import { - IgrAccordion, - IgrExpansionPanel, -} from "igniteui-react"; -import "igniteui-webcomponents/themes/light/bootstrap.css"; - +import { IgrAccordion, IgrExpansionPanel } from 'igniteui-react'; +import 'igniteui-webcomponents/themes/light/bootstrap.css'; ``` -Before using the , you need to register it as follows: - -```csharp -// in Program.cs file +Register the accordion module in `Program.cs`. +```csharp builder.Services.AddIgniteUIBlazor(typeof(IgbAccordionModule)); ``` - - - - -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +Add the theme stylesheet to your host page. ```razor @@ -94,51 +79,31 @@ You will also need to link an additional CSS file to apply the styling to the -Now you can start with a basic configuration of the and its panels. - ## Usage -Each section in the {Platform} Accordion Component is defined using an {Platform} Expansion Panel. -Panels provide and properties, which give you the ability to configure the states of the panel as per your requirement. +Build the accordion by placing one or more components inside an container. -### Declaring an Accordion +### Declare Panels -The accordion wraps all expansion panels declared inside it. +Use an accordion when you want one container to manage the expansion behavior of several related panels. ```html - - Title Panel 1 -

Content Panel 1

- - - Title Panel 2 -

Content Panel 2

- + + Title Panel 1 +

Content Panel 1

+ + + Title Panel 2 +

Content Panel 2

+ ``` - - -```razor - - - Title Panel 1 -

Content Panel 1

- - - Title Panel 2 -

Content Panel 2

- - -``` - - - ```tsx @@ -156,66 +121,139 @@ The accordion wraps all expansion panels declared inside it. + + +```razor + + + Title Panel 1 +

Content Panel 1

+ + + Title Panel 2 +

Content Panel 2

+ + +``` + + + +### Control Expansion Behavior + +Set to switch between one-open-panel behavior and multiple-open-panel behavior. + -Using the accessor you can get a reference to the collection containing all expansion panels children of the . +Use the accessor when you need a reference to the child panels collection. -```typescript +```ts private accordion: IgcAccordionComponent; private panels: IgcExpansionPanelComponent[]; constructor() { - this.accordion = document.getElementById("accordion") as IgcAccordionComponent; - this.panels = this.accordion.panels; + this.accordion = document.getElementById('accordion') as IgcAccordionComponent; + this.panels = this.accordion.panels; } ``` -As demonstrated above, the property gives you the ability to set whether single or multiple panels can be expanded at a time. - -By using the and methods you can respectively collapse and expand all s of the programmatically. +Use and to collapse or expand the available panels programmatically. -If property is set to **true** calling method would expand only the focused panel. +If is `true`, calling expands only the focused panel. -### {Platform} Accordion Customization Example +### Customize Panel Content + +Customize the panel headers and content through the underlying slots. + + -With the {Platform} Accordion, you can customize the header and content panel's appearance. +### Nest Accordions -The sample below demonstrates how elaborate filtering options can be implemented using the built-in slots of the . +Nest an accordion inside an expansion panel when you need a second level of grouped disclosure. - + -### Nested {Platform} Accordions Scenario +## Best Practices -In the following {Platform} Accordion example is created a complex FAQ section in order to illustrate how you can go about this common application scenario. In the sample nested is achieved by adding an accordion inside an expansion panel. +Use the accordion to reduce scanning cost, not to hide essential primary content. - +- Group only related sections in the same accordion so the expansion behavior feels predictable. +- Set `singleExpand` when users should compare one section at a time, such as FAQ or settings flows. +- Keep panel titles short and descriptive so users can decide what to open without reading body text. +- Use nested accordions sparingly; too many disclosure levels make orientation harder. -## Keyboard Navigation +## Properties -Keyboard navigation in the {Platform} Accordion provides a rich variety of keyboard interactions to the end-user. This functionality is enabled by default and allows end-users to easily navigate through the panels. +The accordion exposes a small set of container-level controls; panel-specific state is configured on each . -The Accordion navigation is compliant with W3C accessibility standards and convenient to use. +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `singleExpand` | `boolean` | `false` | Controls whether one or multiple panels can stay expanded at the same time. | +| `panels` | `IgcExpansionPanelComponent[]` | n/a | Returns the collection of child expansion panels in the accordion. | -**Key Combinations** -- ↓ - moves the focus to the panel below -- ↑ - moves the focus to the panel above -- ALT + ↓ - opens the focused panel in the accordion -- ALT + ↑ - closes the focused panel in the accordion -- SHIFT + ALT + ↓ - opens all enabled panels (if singleExpand is set to true opens the focused panel) -- SHIFT + ALT + ↑ - closes all enabled panels -- HOME - navigates to the FIRST enabled panel in the accordion -- END - navigates to the LAST enabled panel in the accordion +## Methods - +Use the accordion methods when you need to change panel state from your code. +| Name | Description | +| -- | -- | +| `showAll()` | Expands the available panels. When `singleExpand` is `true`, only the focused panel expands. | +| `hideAll()` | Collapses the available panels. | + +## Accessibility + +The accordion supports keyboard interaction for moving focus between panels and changing their expanded state. + +### Keyboard Interaction + +Use the keyboard shortcuts below to move through the accordion and open or close panels. + +| Key | Action | +| -- | -- | +| Down Arrow | Moves focus to the panel below. | +| Up Arrow | Moves focus to the panel above. | +| Alt + Down Arrow | Opens the focused panel. | +| Alt + Up Arrow | Closes the focused panel. | +| Shift + Alt + Down Arrow | Opens all enabled panels. If `singleExpand` is `true`, opens only the focused panel. | +| Shift + Alt + Up Arrow | Closes all enabled panels. | +| Home | Moves focus to the first enabled panel. | +| End | Moves focus to the last enabled panel. | + +### Screen Readers / ARIA + +The accordion's accessibility semantics are provided through its child expansion panels and their headers. + +- Use clear title text for each panel so assistive technologies can announce a meaningful label. +- Keep interactive content inside panel bodies in a logical tab order. +- Add any app-specific labeling or surrounding context your layout requires. + +### Accessibility Compliance + +[VERIFY: official accessibility conformance target for the accordion component] + +| Criterion | How the component complies | +| -- | -- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | The accordion supports keyboard commands for moving focus and opening or closing panels. | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order) | Focus moves through enabled panels in sequence, with shortcuts for jumping to the first and last panel. | + +Your responsibilities: + +- Provide panel titles that describe the content behind each disclosure area. +- Preserve a logical focus order in the surrounding page layout. +- Validate any custom styling against your application's contrast and focus-indicator requirements. ## API References + + +## Dependencies + +The accordion depends on for its visible sections and on the shared theme stylesheet for its default appearance in React and Blazor. + ## Additional Resources - [{ProductName} **Forums**]({ForumsLink}) diff --git a/docs/xplat/src/content/en/components/layouts/avatar.mdx b/docs/xplat/src/content/en/components/layouts/avatar.mdx index 97c2f86fe5..2492e50b24 100644 --- a/docs/xplat/src/content/en/components/layouts/avatar.mdx +++ b/docs/xplat/src/content/en/components/layouts/avatar.mdx @@ -1,104 +1,103 @@ --- -title: "{Platform} Avatar | Layout Controls | Infragistics" -description: Use Infragistics' {Platform} avatar component to display an image, icon, or initials. -keywords: avatar, layout, {ProductName}, Infragistics +title: "{Platform} Avatar Component | Layouts | Infragistics" +description: "{Platform} Avatar represents a user, entity, or object with an image, initials, or custom content." +keywords: "{Platform} Avatar, avatar component, profile image, initials, {ProductName}, Infragistics" license: MIT -mentionedTypes: ["Avatar"] +mentionedTypes: ["Avatar", "Badge", "Icon"] +relatedComponents: ["Badge"] llms: - description: "The {ProductName} Avatar helps to display initials, images, or icons in your application." + description: "The {ProductName} Avatar represents a user, entity, or object with an image, initials, or custom content." --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +# Avatar Component -# {Platform} Avatar +The {ProductName} Avatar represents a user, entity, or object with an image, initials, or custom content. -The {ProductName} Avatar helps to display initials, images, or icons in your application. +## Overview -## {Platform} Icon Avatar Example +Use the avatar to provide a compact visual identity in lists, cards, profile menus, and activity feeds. - +### When to Use +Use the avatar when a UI needs a small representation of a person, organization, object, or account, such as a profile image, initials, or an icon. +### When Not to Use -## Usage +Use the [Badge](../inputs/badge.md) component when you need to show a count, status, or notification indicator instead of representing an entity. Badges can also decorate avatars when both identity and status need to appear together. + - +## Anatomy +The avatar is a single host element that renders an image, initials, or the default slot. -First, you need to install the {ProductName} npm package by running the following command: +{/*TODO: Add an avatar anatomy image when a component-parts visual is available.*/} -```cmd -npm install {PackageWebComponents} +```html + +
+ AZ + + A photo of Ana Zane + + +
+ ``` - +## Getting Started +Before you add the avatar, complete the shared {ProductName} setup in the [Getting Started](../general-getting-started.md) topic. + - +Register the avatar component before you use it. +```ts +import { defineComponents, IgcAvatarComponent } from 'igniteui-webcomponents'; +defineComponents(IgcAvatarComponent); +``` -First, you need to the install the corresponding {ProductName} npm package by running the following command: + -```cmd -npm install igniteui-react -``` + -You will then need to import the and its necessary CSS, like so: +Import the React wrapper and theme stylesheet before you render the avatar. ```tsx import { IgrAvatar } from 'igniteui-react'; import 'igniteui-webcomponents/themes/light/bootstrap.css'; ``` - - -Before using the , you need to register it as follows: - - -```csharp -// in Program.cs file +Register the avatar module in `Program.cs`. +```csharp builder.Services.AddIgniteUIBlazor(typeof(IgbAvatarModule)); ``` - - - - - - -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +Add the theme stylesheet to your host page. ```razor ``` - +## Usage - - -```ts -import { defineComponents, IgcAvatarComponent } from 'igniteui-webcomponents'; - -defineComponents(IgcAvatarComponent); -``` - - +Render an avatar with an image source, initials, or custom content in the default slot. -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. +### Basic Declaration -The is capable of displaying images, initials, or any other content, including icons. Declaring an is as simple as: +Add an avatar with no attributes when you need an empty avatar container to style or populate later. @@ -124,11 +123,20 @@ The is capable of displaying images, initia -The avatar has several attributes that allow rendering different content based on the context. The most basic way to display content in the boundaries of the avatar is to provide content between the opening and closing tags. +### Content + +Set only the content source you intend to show; the avatar renders an image when is available, otherwise it renders or default slot content. ```html + + + + + @@ -139,8 +147,15 @@ The avatar has several attributes that allow rendering different content based o ```tsx + + + + - + ``` @@ -149,6 +164,12 @@ The avatar has several attributes that allow rendering different content based o ```razor + + + + @@ -156,18 +177,18 @@ The avatar has several attributes that allow rendering different content based o -### Initials + + + + +### Shape -If the attribute is set all children elements of the avatar will be ignored and the string passed to this attribute will be displayed. +Set to `square`, `rounded`, or `circle`. ```html - - - - - + ``` @@ -175,9 +196,7 @@ If the a ```tsx - - - + ``` @@ -185,120 +204,147 @@ If the a ```razor - - - - - + ``` - - - + +### Size -### Image - -The avatar can also display an image when the attribute is assigned a valid URL to a static asset. In that case the value will be ignored and children elements will not be rendered. - - +Set `--ig-size` to one of the shared size tokens when you need a preset avatar size. -```html - - - +```css +igc-avatar { + --ig-size: var(--ig-size-large); +} ``` - + - +## Best Practices -```tsx - - - -``` +Use a consistent avatar strategy within the same UI region so repeated identities are easy to scan. - +| Do | Do Not | +| -- | -- | +| Use one content pattern per list or card group, such as all images or all initials. | Mix images, initials, and icons in the same repeated list without a clear reason. | +| Provide `alt` text when an image avatar identifies a specific person or entity. | Leave meaningful image avatars with only the default accessible label. | +| Use initials for predictable fallback identity when a profile image is unavailable. | Use initials to encode counts, status, or notification state. | +| Decorate an avatar with a badge for status or notification indicators. | Replace an identity avatar with a badge when both identity and status matter. | +## Properties - +The avatar exposes a small set of inputs for its content and shape. -```razor - - - -``` +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `alt` | `string` | n/a | Sets alternative text for the image avatar. | +| `initials` | `string` | n/a | Sets text initials rendered when no image is displayed. | +| `shape` | `"square" \| "rounded" \| "circle"` | `"square"` | Sets the avatar shape. | +| `src` | `string` | n/a | Sets the image source URL. | - +## Styling - + +The avatar appearance is controlled through theme variables and CSS parts. +| Variable | What it changes | +| -- | -- | +| `--ig-avatar-background` | Avatar background color. | +| `--ig-avatar-color` | Text and initials color. | +| `--ig-avatar-icon-color` | Slotted icon color. | +| `--ig-avatar-border-radius` | Border radius used by rounded avatars. | +| `--ig-avatar-size` | Avatar width and height. | +| `--ig-size` | Shared component size token used to derive preset avatar sizes. | -### Shape +| CSS Part | Description | +| -- | -- | +| `base` | The avatar wrapper. | +| `initials` | The initials wrapper. | +| `image` | The image element. | -The avatar supports three shapes - `circle`, `rounded`, and `square`. The default shape of the avatar is `square` and it can be changed via the `shape` attribute. +### Sass Theming - +Use the function when your application customizes Ignite UI themes through Sass. +```scss +@use "igniteui-theming/sass/themes" as *; +$custom-avatar-theme: avatar-theme( + $background: #72da67, + $border-radius: 16px, + $size: 3rem +); +:root { + @include tokens($custom-avatar-theme); +} +``` -### Size +### CSS Variables -Apart from the shape, the size of the avatar can also be changed by utilizing the `--ig-size` CSS variable. The supported sizes are `small` (default), `medium`, and `large`. The following code snippet shows how to use a different component size: +Set component CSS variables directly when you need local styling without a Sass build step. ```css igc-avatar { - --ig-size: var(--ig-size-large); + --ig-avatar-background: var(--ig-success-500); + --ig-avatar-color: var(--ig-success-500-contrast); + --ig-avatar-border-radius: 20px; +} + +igc-avatar::part(base) { + border: 2px solid var(--ig-success-700); } ``` - +## Accessibility +The avatar is a non-interactive identity visual with accessible image semantics. +### Keyboard Interaction +The avatar does not receive focus and has no keyboard interaction. -### Styling +| Key | Action | +| -- | -- | +| n/a | The avatar is not keyboard interactive. | -The component exposes several CSS parts, giving you full control over its style: +### Screen Readers / ARIA -|Name|Description| -|--|--| -| `base` | The base wrapper of the avatar. | -| `initials` | The initials wrapper of the avatar. | -| `image` | The image wrapper of the avatar. | -| `icon` | The icon wrapper of the avatar. | +The avatar initializes with image semantics and a default accessible label of `avatar`. -```css -igc-avatar { - --ig-avatar-background: var(--ig-success-500); -} +- Set `alt` when a `src` image represents a specific person, entity, or object. +- Add an explicit `aria-label` when projected custom content needs a different accessible name. +- Treat decorative avatars as redundant when adjacent text already identifies the same entity. -igc-avatar::part(base) { - --size: 60px; - color: var(--ig-success-500-contrast); - border-radius: 20px; -} -``` +### Accessibility Compliance - +[VERIFY: official accessibility conformance target for the avatar component] +| Criterion | How the component complies | +| -- | -- | +| [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content) | The avatar has an accessible label, and image avatars can receive specific alternative text through `alt`. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value) | The component initializes with image semantics and exposes content-related ARIA information. | +Your responsibilities: +- Provide a descriptive label or `alt` text when the avatar conveys identity. +- Keep sufficient contrast between the avatar background and text or icon color when overriding styles. +- Avoid duplicating the same identity announcement when adjacent text already names the person or entity. ## API References + + + + +## Dependencies + +The avatar uses the shared theme stylesheet for its default appearance in React and Blazor. Slotted icons require the component to be registered or imported. + ## Additional Resources - [{ProductName} **Forums**]({ForumsLink}) diff --git a/docs/xplat/src/content/en/components/layouts/card.mdx b/docs/xplat/src/content/en/components/layouts/card.mdx index 1734dcb20c..2d32c1ab93 100644 --- a/docs/xplat/src/content/en/components/layouts/card.mdx +++ b/docs/xplat/src/content/en/components/layouts/card.mdx @@ -1,76 +1,114 @@ --- -title: Card Component -description: Present users with dashboards and engaging text, images, icons or buttons as an entry point for detailed information with Ignite UI for Web Card component. -keywords: "{ProductName}, UI controls, Web widgets, web widgets, UI widgets, Native Web Components Suite, Native Web Controls, Native Web Components Library, Web Card component, Web Card controls" +title: "{Platform} Card Component | Layouts | Infragistics" +description: "{Platform} Card organizes related media, text, and actions in one flexible content container." +keywords: "{Platform} Card, card component, content container, media card, {ProductName}, Infragistics" license: MIT mentionedTypes: ["Card", "CardActions", "CardContent", "CardHeader", "CardMedia", "Avatar", "Button", "Icon", "IconButton", "Ripple"] llms: - description: "The {ProductName} Card displays text, images, icons, and buttons in a visually rich presentation that can serve as an entry point to more detailed information." + description: "The {ProductName} Card organizes related media, text, and actions in one flexible content container." --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +# Card Component -# {Platform} Card Overview +The {ProductName} Card organizes related media, text, and actions in one flexible content container. -The {ProductName} Card displays text, images, icons, and buttons in a visually rich presentation that can serve as an entry point to more detailed information. Cards can be used to create a multimedia dashboard. +## Overview +Use the card to group content about a single subject, such as a product, article, contact, location, or dashboard item. -## {Platform} Card Example +### When to Use - +Use the card when related information benefits from a shared container with optional header, media, body content, and actions. -
+### When Not to Use -## Usage +Avoid cards for dense tabular data, long-form reading, or workflows where the container adds visual noise without making content easier to scan. Use the underlying layout, list, or grid pattern that best matches the content instead. -Cards allow you to easily display content composed of different types of objects or similar objects whose size and supported actions can vary. + -### Getting Started +## Anatomy - +The card is a container whose standard building blocks are header, media, content, and actions. -First, you need to install the {ProductName} by running the following command: +{/*TODO: Add a card anatomy image when a component-parts visual is available.*/} -```cmd -npm install {PackageWebComponents} +```html + + + ... + + + + Card title + Card subtitle + + +

Card content

+ + + Read more + + + ``` - +## Getting Started - +Before you add the card, complete the shared {ProductName} setup in the [Getting Started](../general-getting-started.md) topic. + + -First, you need to the install the corresponding {ProductName} npm package by running the following command: +Register the card component before you use it. The card registration includes the card header, media, content, and actions sub-components. -```cmd -npm install igniteui-react +```ts +import { + defineComponents, + IgcAvatarComponent, + IgcButtonComponent, + IgcCardComponent, + IgcIconButtonComponent, +} from 'igniteui-webcomponents'; + +defineComponents(IgcCardComponent, IgcAvatarComponent, IgcButtonComponent, IgcIconButtonComponent); ``` -You will then need to import the and its necessary CSS, like so: + + + + +Import the React wrappers and theme stylesheet before you render the card. ```tsx -import { IgrCard, IgrCardHeader, IgrCardContent, IgrCardMedia, IgrCardActions } from 'igniteui-react'; +import { + IgrAvatar, + IgrButton, + IgrCard, + IgrCardActions, + IgrCardContent, + IgrCardHeader, + IgrCardMedia, + IgrIconButton, +} from 'igniteui-react'; import 'igniteui-webcomponents/themes/light/bootstrap.css'; ``` -Before using the , you need to register it as follows: - -```csharp -// in Program.cs file +Register the card module in `Program.cs`. +```csharp builder.Services.AddIgniteUIBlazor(typeof(IgbCardModule)); +builder.Services.AddIgniteUIBlazor(typeof(IgbAvatarModule)); +builder.Services.AddIgniteUIBlazor(typeof(IgbButtonModule)); +builder.Services.AddIgniteUIBlazor(typeof(IgbIconButtonModule)); ``` - - - - -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +Add the theme stylesheet to your host page. ```razor @@ -78,48 +116,31 @@ You will also need to link an additional CSS file to apply the styling to the - - -```ts -import { defineComponents, IgcCardComponent } from 'igniteui-webcomponents'; - -defineComponents(IgcCardComponent ); -``` +## Usage - +Compose a card from the card container and whichever sub-components your content needs. -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. +### Basic Card -Then, to represent the demo card template, we can add the following code: +Place media, title, subtitle, body text, and actions in the corresponding card sub-components. ```html - - - - - New York - City in New York - - -

New York City comprises 5 boroughs sitting where the Hudson River meets the Atlantic Ocean. At its core is Manhattan, a densely populated borough that’s among the world’s major commercial, financial and cultural centers.

- - - - - Read more - -
- - - - - - -
- + + New York city skyline + + + New York + City in New York + + +

New York City comprises five boroughs where the Hudson River meets the Atlantic Ocean.

+ + + Read more + ``` @@ -129,33 +150,19 @@ Then, to represent the demo card template, we can add the following code: ```tsx - - - - - New York City - City in New York - - -

New York City comprises 5 boroughs sitting where the - Hudson River meets the Atlantic Ocean. At its core is Manhattan, - a densely populated borough that’s among the world’s major commercial, - financial and cultural centers.

- - - - Read more - - -
- - - - - - -
- + + New York city skyline + + + New York + City in New York + + +

New York City comprises five boroughs where the Hudson River meets the Atlantic Ocean.

+ + + Read more + ``` @@ -165,59 +172,35 @@ Then, to represent the demo card template, we can add the following code: ```razor - - - - - New York City - City in New York - - -

New York City comprises 5 boroughs sitting where the - Hudson River meets the Atlantic Ocean. At its core is Manhattan, - a densely populated borough that's among the world's major commercial, - financial and cultural centers.

- - - - - Read more - -
- - - - - - -
- + + New York city skyline + + + New York + City in New York + + +

New York City comprises five boroughs where the Hudson River meets the Atlantic Ocean.

+ + + Read more + ``` -You will notice a few things above. First, to _tag_ an element as a header title, we need to place it between the tags and set its slot name to `title`. Conversely, to define a subtitle, we need to set the slot name to `subtitle`. When slotting content into the `title` and `subtitle` slots, we recommend using `` rather than heading elements (`

`–`

`). Heading elements carry built-in styling (such as font size, line height, and margins) that can interfere with the component's intended typography and layout. A `` provides a neutral container that inherits the component’s styles cleanly. - -Any image or video we want to show in the card, we wrap inside the tags. The allows us to size the content placed inside so that it maintains its aspect ratio while filling the element’s entire content box. If the object's aspect ratio does not match the aspect ratio of its box, then the object will be clipped to fit. - -You can place anything inside the tags. Usually text goes there. - -Finally, the is where you'd place any actionable items, like buttons. +### Header Slots -### Media, Thumbs, and Avatars - -If you want to display an image or icon in the card header next to the title and subtitle, assign the element's slot attribute to `thumbnail`. For the best results, we recommend using an [`igc-avatar`](../layouts/avatar.md) component for the `thumbnail` slot, as it integrates seamlessly with the card header's layout and styling. - -Taking the card above as an example, we can edit the contents of the and add an avatar with `slot="thumbnail"`: +Use the header slots to define thumbnail, title, subtitle, and additional header content. ```html - - Title - Subtitle + + Title + Subtitle ``` @@ -227,9 +210,9 @@ Taking the card above as an example, we can edit the contents of the - - Title - Subtitle + + Title + Subtitle ``` @@ -239,355 +222,242 @@ Taking the card above as an example, we can edit the contents of the - - Title - Subtitle + + Title + Subtitle ``` -The above example will show the avatar alongside the title and subtitle in the card header. - -### Outlined cards -The card has an `outlined` attribute which, if set, removes any shadows from the card, replacing them with a thin border to separate the card from the background. - -### Horizontal Layout +Use neutral inline elements such as `` for `title` and `subtitle` when you want to inherit the card typography without browser heading margins. -By default all sections of the card (header, content, media, actions) are laid out vertically. This is nice when we have a lot of vertical space. Say we wanted to lay out the sections in the card horizontally. We can achieve such a layout with some simple CSS. +### Elevated Appearance -Here's an example of an outlined horizontal card: +Set when the card should use the elevated visual treatment. ```html - -
-
- - - Rozes - Under the Grave (2016) - - -

As I have always said: I write what’s real and what’s true, - even if it means throwing myself under the bus.

- -
-
- - - - - -
+ + ... ``` - - -```razor - -
-
- - ROZES-Under-the-Grave - Rozes - Under the Grave (2016) - - -

As I have always said: I write what's real and what's true, - even if it means throwing myself under the bus.

- -
-
- - - - - -
- -``` - - - ```tsx - -
-
- - - Rozes - Under the Grave (2016) - - -

As I have always said: I write what’s real and what’s true, - even if it means throwing myself under the bus.

- -
-
- - skip_previous - play_arrow - skip_next - -
+ + ... ``` -We are using an additional `div` element to bundle the and together, keeping them aligned vertically, and applying the `.card-horizontal` class to the wrapping `div` element to align the two sections of the card horizontally. - -The styles that `.card-horizontal` class applies are: - -```css -.card-horizontal { - display: flex; - flex-direction: row; - flex: 1 1 0%; -} - -.card-horizontal img { - width: 64px; - height: 64px; -} + -.card-horizontal igc-card-actions { - justify-content: center; -} +```razor + + ... + ``` -If everything went well, our card should look like this: - - - -### Alternative layouts + -You can get even more creative with the layout of the . +### Actions -Below is an example showing how you can create a semi-horizontal card, where we have every section of the card laid out vertically, while the appears alongside the vertical sections. +Use for buttons and icon buttons, and place content in the `start`, default, or `end` slots. ```html - -
-
- - MD - HERE - by Mellow D - - -

Far far away, behind the word mountains, - far from the countries Vokalia and Consonantia, - there live the blind texts.

- - - play album - -
- - - -
- + + Like + Share + + ``` - + -```razor - -
-
- - - HERE - by Mellow D - - -

Far far away, behind the word mountains, - far from the countries Vokalia and Consonantia, - there live the blind texts.

- - - Play Album - -
- - here_media - -
- +```tsx + + Like + Share + + ``` - + -```tsx - -
-
- - - HERE - by Mellow D - - -

Far far away, behind the word mountains, - far from the countries Vokalia and Consonantia, - there live the blind texts.

- - - Play Album - -
- - - - -
- +```razor + + Like + Share + + ``` +### Custom Layouts + +Wrap card sections in your own layout containers when you need horizontal or split card compositions. + ```css -.semi-horizontal { - display: flex; - flex-direction: row; - flex-grow: 1; +.card-horizontal { + display: flex; + flex-direction: row; + flex: 1 1 0%; } -.card-media { - width: 96px; - min-width: 96px; +.card-horizontal igc-card-actions { + justify-content: center; } ``` - + -### Card Actions + -The card actions area allows additional configuration to what we have already mentioned. -The area is intended to hold actionable items, like buttons. There are two slots available that can be used to position content: `start` and `end`. We can assign these slots to any element placed inside the , and it will be positioned accordingly, either at the `start` or the `end` of the area. These slots can be used with any type of content, but we highly recommend sticking to actionable elements, or wrappers of actionable elements, as shown in the example below: +## Best Practices - +Use cards when the content describes one subject and the grouped presentation helps users scan or compare items. -```html - - - - Read more - -
- - - - - - -
- -``` +| Do | Do Not | +| -- | -- | +| Keep each card focused on one subject or decision. | Combine unrelated content in one card because it fits visually. | +| Put primary information in the header or content area and secondary commands in actions. | Hide essential information behind actions or icon-only controls without labels. | +| Use consistent card structure across repeated cards. | Mix header, media, and action placement randomly in the same card group. | +| Use accessible image `alt` text for card media that communicates meaning. | Treat meaningful media as decorative. | - +## Properties - +The card API exposes container appearance and action-layout controls. -```razor - - - - Read more - -
- - - - - - -
- -``` +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `elevated` | `boolean` | `false` | Sets the card to use an elevated appearance with shadow. | +| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Sets the layout orientation of . | - +## Styling - + -```tsx - - - Read more - - -
- - - - - - -
- -``` +The card appearance is controlled through theme variables and CSS parts on the card header. - +| Variable | What it changes | +| -- | -- | +| `--ig-card-background` | Card background color. | +| `--ig-card-outline-color` | Card outline color. | +| `--ig-card-header-text-color` | Card title text color. | +| `--ig-card-subtitle-text-color` | Card subtitle text color. | +| `--ig-card-content-text-color` | Card content text color. | +| `--ig-card-actions-text-color` | Card actions text color. | +| `--ig-card-resting-shadow` | Card shadow in its resting state. | +| `--ig-card-hover-shadow` | Card shadow in its hover state. | +| `--ig-card-border-radius` | Card border radius. | -You can also add more content in-between by simply omitting the slot property and let the elements go to the default slot. +| CSS Part | Description | +| -- | -- | +| `header` | Card header text container. | +| `title` | Title slot wrapper. | +| `subtitle` | Subtitle slot wrapper. | -## Styling +### Sass Theming -Since the card is a container that wraps different elements, styling is done by styling its building blocks - the , , and sub-components. +Use the function when your application customizes Ignite UI themes through Sass. -```css -igc-card { - background-color: var(--ig-secondary-900); -} +```scss +@use "igniteui-theming/sass/themes" as *; -igc-card-content, -igc-card-header::part(title) { - color: var(--ig-primary-500-contrast); +$custom-card-theme: card-theme( + $background: #1f2937, + $border-radius: 12px, + $header-text-color: #ffffff, + $content-text-color: #e5e7eb +); + +:root { + @include tokens($custom-card-theme); } +``` -igc-card-header > *[slot="subtitle"] { - color: var(--ig-warn-500); - opacity: 0.9; +### CSS Variables + +Set component CSS variables directly when you need local styling without a Sass build step. + +```css +igc-card { + --ig-card-background: var(--ig-secondary-900); + --ig-card-header-text-color: var(--ig-secondary-900-contrast); + --ig-card-content-text-color: var(--ig-secondary-900-contrast); } -igc-icon-button::part(base) { - background-color: var(--ig-primary-300); +igc-card-header::part(subtitle) { + color: var(--ig-warn-500); } ``` - +## Accessibility + +The card itself is a non-interactive container; keyboard and ARIA behavior come from the semantic content and interactive controls placed inside it. + +### Keyboard Interaction + +The card does not receive focus unless you add focusable content inside it. + +| Key | Action | +| -- | -- | +| Tab | Moves focus through interactive elements inside the card, such as buttons or links. | + +### Screen Readers / ARIA -### Summary -In this article we covered a lot of ground with the card component. We created a simple card and added some images to make it a bit more appealing. We used some additional {Platform} inside our card, like avatars, buttons and icons, to enrich the experience and add some functionality. And finally, we changed the card's appearance by changing the major colors of the building blocks. +The card renders slotted content and does not add a landmark role by default. -
+- Use semantic headings, links, buttons, images, and lists inside the card content. +- Provide `alt` text for meaningful media. +- Add an accessible name to icon-only buttons in the actions area. +- Add a role or label to the card container only when your application needs one for its information architecture. + +### Accessibility Compliance + +[VERIFY: official accessibility conformance target for the card component] + +| Criterion | How the component complies | +| -- | -- | +| [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships) | The card preserves the semantic structure of slotted headings, text, media, and controls. | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | Interactive card content remains reachable by keyboard when authors use keyboard-operable controls. | + +Your responsibilities: + +- Use semantic elements for titles, body content, media, and actions. +- Provide accessible names for icon-only buttons and meaningful images. +- Preserve logical focus order when building custom horizontal or split card layouts. +- Keep sufficient contrast when overriding card colors. ## API References -
-
-
-
-
-
-
-
-
+ + + + + + + + + + + +## Dependencies + +The card uses its own header, media, content, and actions sub-components. Cards that include thumbnails, actions, icons, or ripples also depend on the corresponding , , , , and components. ## Additional Resources diff --git a/docs/xplat/src/content/en/components/layouts/carousel.mdx b/docs/xplat/src/content/en/components/layouts/carousel.mdx index 57029288e2..e35a6bbdd4 100644 --- a/docs/xplat/src/content/en/components/layouts/carousel.mdx +++ b/docs/xplat/src/content/en/components/layouts/carousel.mdx @@ -1,43 +1,45 @@ --- -title: "{Platform} Carousel | Infragistics" -description: Use {ProductName} Carousel component to navigate through a collection of slides, cards or page-based interfaces with endless programmatic features. Try it now -keywords: "{ProductName}, UI controls, {Platform} widgets, web widgets, UI widgets, {Platform}, Native {Platform} Components Suite, Native {Platform} Controls, Native {Platform} Components Library, {Platform} Carousel component, {Platform} Carousel control" +title: "{Platform} Carousel Component | Layouts | Infragistics" +description: "{Platform} Carousel is a slideshow component for presenting slides, cards, and other page-like content in a sequential viewport." +keywords: "{Platform} Carousel, carousel component, slideshow, slides, {ProductName}, Infragistics" license: MIT -mentionedTypes: ["Carousel"] +mentionedTypes: ["Carousel", "CarouselSlide", "CarouselIndicator"] llms: - description: "The {ProductName} Carousel is a responsive, lightweight component that provides the most flexible way to create slideshow-like web experience for users who navigate back and forth through a collection of images with text slides, links, and other html elements." + description: "The {ProductName} Carousel is a slideshow component for presenting slides, cards, and other page-like content in a sequential viewport." --- import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +# Carousel Component -# {Platform} Carousel Overview +The {ProductName} Carousel is a slideshow component for presenting slides, cards, and other page-like content in a sequential viewport. -The {ProductName} Carousel is a responsive, lightweight component that provides the most flexible way to create slideshow-like web experience for users who navigate back and forth through a collection of images with text slides, links, and other html elements. +## Overview -The {Platform} Carousel component allows you to use animations, slide transitions, and customization so you can easily tweak the interface and build {Platform} custom carousel. +The carousel displays one slide at a time and provides built-in navigation, indicators, animations, and automatic transitions for sequential content. -## {Platform} Carousel Example -The {Platform} Carousel demo you see below shows slides containing only images. +### When to Use - +Use the carousel when users move through a series of slides, images, or short content panels in order and the previous or next action is part of the experience. -## Usage +### When Not to Use - +Do not use the carousel when users need to compare several items at once or jump directly among many sections without stepping through intermediate slides. -First, you need to install the {ProductName} by running the following command: + -```cmd -npm install {PackageWebComponents} -``` +## Getting Started -You will then need to import the , its necessary CSS, and register its module, like so: +Before you add the carousel, complete the shared {ProductName} setup in the [Getting Started](../general-getting-started.md) topic. + + + +Register the carousel component before you render it. ```ts -import { defineComponents, IgcCarouselComponent } from "igniteui-webcomponents"; +import { defineComponents, IgcCarouselComponent } from 'igniteui-webcomponents'; import 'igniteui-webcomponents/themes/light/bootstrap.css'; defineComponents(IgcCarouselComponent); @@ -47,13 +49,7 @@ defineComponents(IgcCarouselComponent); -First, you need to the install the corresponding {ProductName} npm package by running the following command: - -```cmd -npm install igniteui-react -``` - -You will then need to import the , its necessary CSS, and register its module, like so: +Import the carousel wrappers and the theme stylesheet before you render the component. ```tsx import { IgrCarousel, IgrCarouselSlide } from 'igniteui-react'; @@ -64,15 +60,13 @@ import 'igniteui-webcomponents/themes/light/bootstrap.css'; -Before using the , you need to register it as follows: +Register the carousel module in `Program.cs`. ```csharp -// in Program.cs file - builder.Services.AddIgniteUIBlazor(typeof(IgbCarouselModule)); ``` -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +Add the theme stylesheet to your host page. ```razor @@ -80,25 +74,27 @@ You will also need to link an additional CSS file to apply the styling to the -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. +## Usage + +Build the carousel by wrapping one or more slides inside an container. -Now that you have the {ProductName} Carousel imported, you can start with a basic configuration of the and its slides. +### Create Slides -Use the selector to wrap your slides. The slides may feature any valid html content inside, including other components. +Render each slide inside a and place any valid HTML content inside the slide body. ```html - - - - - - - - - + + + + + + + + + ``` @@ -108,15 +104,15 @@ Use the selector to wrap your slides. The ```tsx - - - - - - - - - + + + + + + + + + ``` @@ -126,33 +122,34 @@ Use the selector to wrap your slides. The ```razor - - ignite-ui-angular-indigo-design - - - slider-image-chart - - - ignite-ui-angular-charts - + + ignite-ui-angular-indigo-design + + + slider-image-chart + + + ignite-ui-angular-charts + ``` -If you want a slide to be active by default, use the attribute: +### Set the Initial Slide + +Set the attribute on the slide that should render first. ```html + ... - - ... - - - ... - + + + ... + ``` @@ -162,13 +159,12 @@ If you want a slide to be active by default, use the ... - - ... - - - ... - + ``` -If no active slide is set, the first one will be set by default. If there are multiple active slides on initial rendering or subsequent updates, only the last one will be taken into account. +If no slide is marked as active, the first slide becomes active by default. If multiple slides are active, only the last active slide is used. -## Examples - -### Carousel Configuration - -By default, the has its property set to **false** (looping occurs when the first slide comes after the last by navigating using the Next action, or when the last slide comes after the first by using the Previous action). The looping behavior can be disabled by setting the value of the property to **true**. - - - -```html - - ... - -``` - - - - - -```tsx - - ... - -``` - - - - - -```razor - - ... - -``` - - - -To keep track of each slide index, the carousel has indicators that are positioned at the `end` of the carousel by default. In order to change this behavior, use the property and assign it to `start`. - - - -```html - - ... - -``` - - - - - -```tsx - - ... - -``` - - - - - -```razor - - ... - -``` - - - -By default, the displays its navigation buttons and indicators. Use the property to hide the indicators and the property to hide the navigation buttons. - - - -```html - - ... - -``` - - - - - -```tsx - - ... - -``` - - +### Configure Navigation - - -```razor - - ... - -``` - - - -The supports vertical mode. Use the property to enable it. +Configure looping, indicator placement, navigation visibility, and orientation through the carousel inputs. ```html - - ... + + ... ``` @@ -309,8 +211,13 @@ The supports vertical mode. Use the ```tsx - - ... + + ... ``` @@ -319,35 +226,40 @@ The supports vertical mode. Use the ```razor - - ... + + ... ``` -### Custom indicators +### Customize Indicators -To add {Platform} custom carousel indicators, use the : +Provide elements when you want custom inactive and active indicator content. ```html - - 🤍 - ❤️ - - - 🤍 - ❤️ - - - the_red_ice_forest - - - yosemite - + + Inactive + Active + + + Inactive + Active + + + the_red_ice_forest + + + yosemite + ``` @@ -358,24 +270,18 @@ To add {Platform} custom carousel indicators, use the 🤍 - - ❤️ - + Inactive + Active - 🤍 - - ❤️ - + Inactive + Active - + - + ``` @@ -386,102 +292,38 @@ To add {Platform} custom carousel indicators, use the ❤️ - - - 🤍 - ❤️ - - - the_red_ice_forest - - - yosemite - - -``` - - - -The {ProductName} Carousel component allows users to use different elements for the active and inactive states of a single indicator. It is mandatory to provide two elements for each indicator slot (**empty** and **active**) when declaring an indicator, even if they are the same. We recommend using a `` element for symbol or emoji indicators, and an [``](../layouts/icon.md) component for icon indicators. - -### Custom navigation buttons - -The navigation buttons can also be customized. To achieve this, use the `previous-button` and `next-button` slots: - - - -```html - - - - ... - -``` - - - - - -```tsx - - - - ... - -``` - - - - - -```razor - - - - ... + + Inactive + Active + + + Inactive + Active + + + the_red_ice_forest + + + yosemite + ``` -Just like with the custom indicators, we recommend using a `` element for symbol or emoji navigation buttons, and an [``](../layouts/icon.md) component for icon navigation buttons. +Provide both the default content and the `active` slot content for each indicator, even when they render the same kind of element. -### Slide containing other components +### Customize Navigation Buttons -This carousel is going to contain slides with forms and images: +Use the `previous-button` and `next-button` slots when you need custom navigation controls. ```html - -
- -
- - - - - - - Sign In -
-
- - -
- -
- - - - Search -
-
- + + + ... ``` @@ -491,35 +333,9 @@ This carousel is going to contain slides with forms and images: ```tsx - -
- -
- - - - - - - - Sign In - -
-
- - -
- -
- - - - - Search - -
-
- + + + ... ``` @@ -529,55 +345,29 @@ This carousel is going to contain slides with forms and images: ```razor - -
- -
- - - - - - - Sign In -
-
- - -
- -
- - - - Search -
-
- + + + ... ``` -#### Demo - - - +### Mix Other Components Into Slides +Place forms, images, and other interactive content inside slides when each slide represents a compact task or card-like view. -## Animations + -Animated slide transitions provide the end-users a nice experience when interacting with the carousel. +### Change the Animation -The carousel is configured to use the `slide` animation by default, but it also supports `fade` as an alternative animation. - -Use the property to change the animation. +Set to switch between the supported transition modes or to disable transitions. ```html - ... + ... ``` @@ -587,7 +377,7 @@ Use the - ... + ... ``` @@ -597,56 +387,29 @@ Use the - ... + ... ``` -Setting `none` to the property disables the animations. - -### Demo - -The demo below demonstrates the different types of animations, which the carousel supports. - - - -## Navigation - -Transition and navigation are the most important carousel features. +Set `none` as the animation type when you want to turn off slide transition animations. -The navigation in the carousel can be handled by the user through navigation buttons, indicators, keyboard navigation and touch interaction on mobile devices. + -### Touch gestures +### Enable Automatic Transitions -By default, the carousel can be used on any touch-enabled device. - -The carousel [animations](carousel.md#animations) are fully supported on touch devices, which makes the carousel consistent with any platform and great when used in progressive web applications ([PWA](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps)). - -### Keyboard navigation - -- Navigation buttons - - SPACE or ENTER key - navigates to the next/previous slide. -- Indicators - - 🡐 key - navigates to the previous (next in Right-to-Left mode) slide. - - 🡒 key - navigates to the next (previous in Right-to-Left mode) slide. - - HOME key - navigates to the first (last in Right-to-Left mode) slide. - - END key - navigates to the last (first in Right-to-Left mode) slide. - -### Automatic transitioning - -The can be easily configured to change the slides automatically, without any user interaction. This way you can create your own slideshow by only setting a transition interval to the property, which determines the amount of time in milliseconds between slides transition. +Set the property to move through slides automatically. -Hovering the mouse over any carousel content or moving keyboard focus to any of the carousel content pauses automatic transitioning. Automatic transitioning resumes when the mouse moves away from the carousel or when keyboard focus moves out of the carousel content. +Hovering the carousel or moving keyboard focus into carousel content pauses automatic transitioning. Transitioning resumes when the pointer or focus leaves the carousel unless pause-on-interaction is disabled. -This can be prevented by setting property to **true**. ```html - ... + ... ``` @@ -656,7 +419,7 @@ This can be prevented by setting - ... + ... ``` -## Advanced Example +### Build a Thumbnail Navigator -Let's create a fully automated carousel with looping enabled. We will configure the indicators to be a thumbnail representation of each slide. +Combine automatic transitions, vertical layout, hidden navigation buttons, and custom indicators when you want a thumbnail-driven slideshow. -To achieve this goal, we have to do the following configurations to the carousel: -- enable the property -- enable the property -- enable the property -- add transition -- add custom for each slide + -Our carousel will look like this in the template: +## Best Practices - +Use the carousel to support a focused sequence, not to hide unrelated content behind motion. -```html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - - - - - -```tsx -const images = [ - { - src: "assets/images/carousel/WonderfulCoast.png", - alt: "Wonderful Coast", - }, - { - src: "assets/images/carousel/CulturalDip.png", - alt: "Cultural Dip", - }, - { - src: "assets/images/carousel/GoldenBeaches.png", - alt: "Golden Beaches", - }, - { - src: "assets/images/carousel/IslandOfHistory.png", - alt: "Island Of History", - }, - { - src: "assets/images/carousel/AmazingBridge.png", - alt: "Amazing Bridge", - }, -]; - - - {images.map((image, index) => { - return ( - - - {image.alt} - - - {`${image.alt} - {`${image.alt} - - - ); - })} - -``` +- Keep slide content concise so users can understand one view before moving to the next. +- Avoid autoplay for dense or task-critical content unless users can easily pause and reorient. +- Use custom indicators only when they communicate slide identity better than the default indicators. +- Ensure each slide image or card has meaningful alternative text and visible context. +- Prefer direct navigation patterns over a carousel when users need random access to many items. - +## Properties - +The carousel exposes container and slide properties; use the generated API reference for the complete surface. -```razor - - - - - - - - - - - - - - - - - - - - - - - - WonderfulCoast - - - CulturalDip - - - GoldenBeaches - - - IslandOfHistory - - - AmazingBridge - - -``` +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `active` | build-generated | build-generated | Build injects verified core slide properties here from the typed API source. | +| `animationType` | build-generated | build-generated | Build injects verified core carousel properties here from the typed API source. | +| `disableLoop` | build-generated | build-generated | Build injects verified core carousel properties here from the typed API source. | +| `disablePauseOnInteraction` | build-generated | build-generated | Build injects verified core carousel properties here from the typed API source. | +| `hideIndicators` | build-generated | build-generated | Build injects verified core carousel properties here from the typed API source. | +| `hideNavigation` | build-generated | build-generated | Build injects verified core carousel properties here from the typed API source. | +| `indicatorsOrientation` | build-generated | build-generated | Build injects verified core carousel properties here from the typed API source. | +| `interval` | build-generated | build-generated | Build injects verified core carousel properties here from the typed API source. | +| `vertical` | build-generated | build-generated | Build injects verified core carousel properties here from the typed API source. | - +## Accessibility -These configurations will have the following result: +The carousel provides roles, labels, live-region behavior, and keyboard navigation for both slide selection and previous or next navigation. - +### Keyboard Interaction -## Accessibility +Use the keyboard shortcuts below to operate the navigation buttons and indicators. -### WAI-ARIA Roles, States, and Properties +| Key | Action | +| -- | -- | +| Space or Enter on a navigation button | Moves to the previous or next slide, depending on the focused button. | +| Left Arrow on an indicator | Moves to the previous slide, or the next slide in right-to-left mode. | +| Right Arrow on an indicator | Moves to the next slide, or the previous slide in right-to-left mode. | +| Home on an indicator | Moves to the first slide, or the last slide in right-to-left mode. | +| End on an indicator | Moves to the last slide, or the first slide in right-to-left mode. | -- The Carousel base element role is [`region`](https://www.w3.org/TR/wai-aria-1.1/#region) - section containing content that is relevant to specific purpose and users will likely want to be able to navigate easily. -- Carousel indicators are with role [`tab`](https://www.w3.org/TR/wai-aria-1.1/#tab) - grouping label providing a mechanism for selecting the tab content that is to be rendered to the user -- The element that serves as the container for the set of tabs (carousel indicators) is with role [`tablist`](https://www.w3.org/TR/wai-aria-1.1/#tablist). -- Each slide element is set with role [`tabpanel`](https://www.w3.org/TR/wai-aria-1.1/#tabpanel). +### Screen Readers / ARIA -### ARIA support +The carousel uses explicit roles and labels for the region, indicator list, indicators, and slides. -#### Carousel component +- The carousel container uses the `region` role and `aria-roledescription="carousel"`. +- The indicators container uses the `tablist` role, and each indicator uses the `tab` role. +- Each slide uses the `tabpanel` role and `aria-roledescription="slide"`. +- The navigation buttons use `aria-label` values of `Previous slide` and `Next slide`. +- The slides container uses `aria-live`, which is `polite` by default and switches to `off` while automatic playback is active. +- Slides use generated labels in the form `{index + 1} of {total}`, and indicators use generated labels in the form `Slide {index + 1}`. -- **Attributes** - - [aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/#aria-roledescription) set to "carousel". - - [aria-live](https://www.w3.org/TR/wai-aria-1.1/#aria-live) - used to set the priority with which screen reader should treat updates to live regions - the possible settings are: **off** and **polite**. The default setting is **polite** and is set to the element that serves as the container for the set of slides. When the option is set and the carousel is in playing state, the **aria-live** attribute would be set to **off**. - - [aria-label](https://www.w3.org/TR/wai-aria/states_and_properties#aria-label) (navigation buttons) - "Previous slide"/"Next slide". +### Accessibility Compliance -#### Slide component +[VERIFY: official accessibility conformance target for the carousel component] -- **Attributes** - - id - follows the pattern `"igc-carousel-slide-${incremented_number}"`. - - [aria-roledescription](https://www.w3.org/TR/wai-aria-1.1/#aria-roledescription) set to "slide". - - [aria-label](https://www.w3.org/TR/wai-aria/#aria-label) follows the pattern `"${index + 1} of ${total}"`. +| Criterion | How the component complies | +| -- | -- | +| [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships) | The carousel exposes structural roles for the region, tab list, tabs, and tab panels. | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | Users can navigate slides from buttons and indicators with keyboard commands. | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order) | Focus moves through the carousel controls in a defined order, and indicator shortcuts provide predictable movement across slides. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value) | Buttons, indicators, and slides expose names and state through ARIA roles, labels, and selection state. | -#### Indicator component +Your responsibilities: -- **Attributes** - - [aria-label](https://www.w3.org/TR/wai-aria/#aria-label) follows the pattern "Slide `${index + 1}`" - - [aria-selected](https://www.w3.org/TR/wai-aria-1.1/#aria-selected) set to **true** or **false** based on the active slide. +- Provide meaningful text alternatives for slide images and other non-text content. +- Ensure custom indicator and navigation content remains understandable without relying on color alone. +- Verify focus order and contrast when you place interactive controls inside slides. +- Evaluate autoplay timing against your application's accessibility requirements. ## API References + - - - + +## Dependencies + +The carousel relies on for slide content, optional elements for custom indicators, and the shared theme stylesheet for its default appearance. + ## Additional Resources - [{ProductName} **Forums**]({ForumsLink}) diff --git a/docs/xplat/src/content/en/components/layouts/divider.mdx b/docs/xplat/src/content/en/components/layouts/divider.mdx index 53931a2091..6fdedda12d 100644 --- a/docs/xplat/src/content/en/components/layouts/divider.mdx +++ b/docs/xplat/src/content/en/components/layouts/divider.mdx @@ -1,54 +1,53 @@ --- -title: "{Platform} Divider | Layout Controls | Infragistics" -description: Use Infragistics' {Platform} divider component to easily create a horizontal/vertical rule as a break between content to better organize information on a page. -keywords: "{ProductName}, UI controls, {Platform} widgets, Web widgets, UI widgets, {Platform}, Native {Platform} Components Suite, Native {Platform} Controls, Native {Platform} Components Library, {Platform} DIvider components, {Platform} Divider controls" +title: "{Platform} Divider Component | Layouts | Infragistics" +description: "{Platform} Divider is a layout component for separating related content with a horizontal or vertical rule." +keywords: "{Platform} Divider, divider component, layout separator, {ProductName}, Infragistics" license: MIT mentionedTypes: ["Divider"] llms: - description: "The {ProductName} Divider allows the content author to easily create a horizontal/vertical rule as a break between content to better organize information on a page." + description: "The {ProductName} Divider is a layout component for separating related content with a horizontal or vertical rule." --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +# Divider Component -# {Platform} Divider +The {ProductName} Divider is a layout component for separating related content with a horizontal or vertical rule. -The {ProductName} Divider allows the content author to easily create a horizontal/vertical rule as a break between content to better organize information on a page. +## Overview -## {Platform} Divider Example +The divider creates a lightweight visual boundary between adjacent pieces of content without introducing a new container or interaction model. - +### When to Use +Use the divider when you need a subtle visual separator between sections, list groups, form areas, or menu items. +### When Not to Use -## Dependencies +Do not use the divider when spacing, headings, or card boundaries already communicate the separation clearly without an extra rule. + + +## Getting Started + +Before you add the divider, complete the shared {ProductName} setup in the [Getting Started](../general-getting-started.md) topic. +Register the divider component before you use it. -First, you need to install the {ProductName} npm package by running the following command: +```ts +import { defineComponents, IgcDividerComponent } from 'igniteui-webcomponents'; -```cmd -npm install {PackageWebComponents} +defineComponents(IgcDividerComponent); ``` - - - - -First, you need to the install the corresponding {ProductName} npm package by running the following command: - -```cmd -npm install igniteui-react -``` - -You will then need to import the , its necessary CSS, and register its module, like so: +Import the divider wrapper, its module registration, and the theme stylesheet before you render the component. ```tsx import { IgrDividerModule, IgrDivider } from 'igniteui-react'; @@ -57,50 +56,31 @@ import 'igniteui-webcomponents/themes/light/bootstrap.css'; IgrDividerModule.register(); ``` - - -Before using the , you need to register it as follows: - - -```csharp -// in Program.cs file +Register the divider module in `Program.cs`. +```csharp builder.Services.AddIgniteUIBlazor(typeof(IgbDividerModule)); ``` - - - - - - -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +Add the theme stylesheet to your host page. ```razor ``` - +## Usage - - -```ts -import { defineComponents, IgcDividerComponent } from 'igniteui-webcomponents'; - -defineComponents(IgcDividerComponent); -``` - - +Render the divider wherever you need a visual break between related pieces of content. -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. +### Declare a Divider -The is capable of displaying images, initials, or any other content, including icons. Declaring an is as simple as: +Start with the default horizontal divider when you need a basic separator line. @@ -126,10 +106,9 @@ The is capable of displaying images, initi -## Usage -### Vertical Divider +### Make the Divider Vertical -If the attribute is set the direction of the divider would be changed from horizontal to vertical. +Set when the separator should run top-to-bottom instead of left-to-right. @@ -155,12 +134,11 @@ If the - - + -### Type +### Change the Line Style -The attribute determines whether to render a `solid` or a `dashed` divider line. The default value is `solid`. +Set the attribute to switch between `solid` and `dashed` rendering. @@ -186,40 +164,33 @@ The attribute d - + +### Add Inset Spacing -### Inset Divider - -The can be set in on both sides. To `inset` the divider, set the attribute to true in combination with the `--inset` css variable. This will shrink the divider line from both sides. The default value of the attribute is false. +Set together with the `--inset` CSS variable when you want the divider to shrink from both sides. ```css -/* DividerStyles.css */ -.withInset{ - --inset: 100px; - --color:red; +.withInset { + --inset: 100px; + --color: red; } ``` ```html -// Both side -// Left side only - + ``` - ```tsx -// Both side -// Left side only - + ``` @@ -227,21 +198,17 @@ The can be set in on both sides. To `inset ```razor -// Both side -// Left side only ``` + - - +### Separate Select Items -### Using Divider Inside Select Component - -The following sample illustrates how the can be integrated within the in order to distinguish two groups of items. +Place a divider inside to split option groups visually. @@ -265,7 +232,6 @@ The following sample illustrates how the c Item 2 - ``` @@ -274,29 +240,82 @@ The following sample illustrates how the c ```razor - Item 1 - Item 2 - - Item 2 + Item 1 + Item 2 + + Item 2 ``` - + + +## Best Practices + +Use the divider to clarify grouping, not as a default decoration between every element. + +- Add a divider only when two adjacent content groups need an explicit visual boundary. +- Prefer horizontal dividers for stacked content and vertical dividers for side-by-side layouts. +- Keep inset and color customizations consistent with the surrounding layout system. +- Avoid overusing dashed or colored dividers when plain spacing already communicates structure. + +## Properties +Use the generated API reference for the full surface; the rows below mark the core options covered on this page. -## CSS Variables -### Inset -The `--inset` css variable shrinks the divider by the given amount from the start. If middle is set it will shrink from both sides. +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `middle` | build-generated | build-generated | Build injects verified core divider properties here from the typed API source. | +| `type` | build-generated | build-generated | Build injects verified core divider properties here from the typed API source. | +| `vertical` | build-generated | build-generated | Build injects verified core divider properties here from the typed API source. | -### Color -The `--color` css variable sets the color of the divider. +## Styling +Use CSS variables to control divider inset and color without changing the markup structure. +| Variable | What it changes | +| -- | -- | +| `--inset` | Shrinks the divider from the start edge, or from both sides when `middle` is enabled. | +| `--color` | Sets the divider line color. | + +## Accessibility + +The divider is a visual separator and does not introduce keyboard interaction of its own. + +### Keyboard Interaction + +The divider does not define component-specific keyboard shortcuts. + +| Key | Action | +| -- | -- | +| n/a | The divider is not an interactive control. | + +### Screen Readers / ARIA + +The divider is intended as a structural visual aid rather than an interactive widget. + +- Keep the divider in a layout context where the surrounding headings, labels, or grouping already communicate the content structure. +- Do not rely on the divider alone to explain meaning that must also be available to assistive technologies. + +### Accessibility Compliance + +[VERIFY: official accessibility conformance target for the divider component] + +| Criterion | How the component complies | +| -- | -- | +| [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships) | The divider can reinforce visual grouping when it is paired with an accessible surrounding structure. | + +Your responsibilities: + +- Provide headings, labels, or other semantic grouping around the divider where structure matters. +- Avoid using color or line style alone to communicate meaning. +- Validate custom divider colors against your application's contrast requirements when they convey state or emphasis. ## API References + + ## Additional Resources - [{ProductName} **Forums**]({ForumsLink}) diff --git a/docs/xplat/src/content/en/components/layouts/dock-manager-customization.mdx b/docs/xplat/src/content/en/components/layouts/dock-manager-customization.mdx index 246a860c1c..fc738fff71 100644 --- a/docs/xplat/src/content/en/components/layouts/dock-manager-customization.mdx +++ b/docs/xplat/src/content/en/components/layouts/dock-manager-customization.mdx @@ -1,85 +1,112 @@ --- -title: "{Platform} Dock Manager | Customization | Infragistics" -description: Use Infragistics' {Platform} dock manager component to manage the layout through panes, with the ability to customize it. Check out {ProductName} dock manager tutorials! -keywords: dock manager, layout, customization, {ProductName} +title: "{Platform} Dock Manager Component Customization | Layouts | Infragistics" +description: "The Infragistics {Platform} Dock Manager provides customization options for docking, pane focus, pane headers, dragging, and fixed-size split layouts." +keywords: "{Platform}, dock manager, layout, customization, {ProductName}" license: commercial mentionedTypes: ["DockManager", "ContentPane"] llms: - description: "The Infragistics {Platform} Dock Manager component provides you with the properties needed to further customize the layout to suit your specific application requirements." + description: "The Infragistics {Platform} Dock Manager provides customization options for docking, pane focus, pane headers, dragging, and fixed-size split layouts." +relatedComponents: ["Splitter", "Tabs"] --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +# Dock Manager Component -## Customizing {Platform} Dock Manager +The Infragistics {Platform} Dock Manager provides customization options for docking, pane focus, pane headers, dragging, and fixed-size split layouts. -The Infragistics {Platform} Dock Manager component provides you with the properties needed to further customize the layout to suit your specific application requirements. -Let's dive in and explore how {Platform} DockManager empowers you to create exceptional user interfaces and enhance the productivity of your applications! +## Overview -
+This topic focuses on the runtime customization features that let you tune how Dock Manager behaves for dragging, docking, pane visibility, and pane sizing. -## Proximity Dock +### When to Use -In this mode the joystick indicators are hidden and docking can be accomplished by dragging a pane close to the border of another pane. While dragging a pane, when the mouse cursor reaches the area corresponding to the dock position, a dock preview is shown. On mouse up the dragged pane is docked in the previewed location. To enable proximity docking, simply set the `proximityDock` property to **true**. +Use these customization options when the default dock manager behavior is close to your needs but the workspace still requires tighter control over docking precision, pane movement, pane header visibility, or programmatic pane activation. + +### When Not to Use + +Do not use Dock Manager customization APIs for simple two-pane resizing or basic tab switching. For straightforward pane sizing, use the [Splitter](./splitter.md) component, and for simple view switching, use the [Tabs](./tabs.md) component. + + + +## Getting Started + +Before you customize Dock Manager, complete the shared setup and base component registration described in the [Dock Manager](./dock-manager.md) topic. + + + +Use an `IgcDockManagerComponent` instance when you need to toggle runtime customization properties from code. ```ts -this.dockManager.proximityDock = true; +import { IgcDockManagerComponent } from 'igniteui-dockmanager'; ``` -### Inner Docking - -In order to right dock a dragged pane 1 in pane 2, the cursor should be in the area defined by the right border of pane 2 and the right border offset to left. The offset distance is specified as a proximity dock threshold and is set to a value of 50px. In cases where there is a splitter, docking can be performed from both sides of the splitter. + -### Outer Docking -To perform outer dock, you must first meet specific criteria. In Dock Manager, outer docking is only allowed within a document host, meaning you will be docking the target pane to the outer regions of the document host. + -In order to perform an outer top dock for example, must fall within the region defined by the top border of the document host and stay within the top border offset. The offset distance is specified as a proximity dock outer threshold and is explicitly set to a value of 25px. The proximity dock threshold's value of 50px remains unchanged which essentially means that in this scenario, only a 25px area is available for inner docking. In cases where there is a splitter inside the document host, outer dock can be performed from both sides of the splitter. +Use an `IgrDockManager` instance when you need to toggle runtime customization properties from code. -> NOTE: When proximity dock is enabled, users would not be able to perform an outer dock for both left and right and top and bottom positions from a single pane. For example in a scenario where two split panes are present with a splitter between them, users will be able to perform only an outer left dock when the dragged pane is over the left split pane and vice versa. +```tsx +import { IgrDockManager } from 'igniteui-react-dockmanager'; +``` -Try it for yourself in the sample below: + - +## Usage +Set the dock manager customization properties that match your workspace behavior, then combine them with samples or layout updates for the user scenarios your app supports. -## Focus Panes Programmatically +### Enable Proximity Dock -The `focusPane` method allows developers to dynamically and programmatically focus a specific pane within the layout by providing the `contentId` of the desired pane. +Set the `proximityDock` property when panes should dock by pointer proximity instead of relying on joystick indicators. ```ts -this.dockManager.focusPane('content1'); +this.dockManager.proximityDock = true; ``` -When using the `focusPane` method, the behavior varies depending on the state of the targeted pane. Here's how it works: +In proximity dock mode, dragging near a pane border shows a docking preview and dropping the pane completes the dock operation. -1. **Floating Panes**: If the pane is floating, invoking `focusPane` will bring it into focus, set it as the activePane and ensure it appears on top of any other floating panes. +#### Inner Docking -2. **Unpinned Panes**: When the targeted pane is unpinned, `focusPane` will flyout the pane to its open state. +Inner docking is triggered near the interior borders of the target pane. The existing topic documents a 50px proximity threshold for these docking targets. -3. **Regular Pinned Panes**: For regular pinned panes, `focusPane` will set the pane as the `activePane`. +#### Outer Docking +Outer docking is available inside a document host and uses a smaller outer threshold region near the document host borders. The existing topic documents a 25px outer threshold and notes that, with proximity dock enabled, a single hovered pane cannot expose both opposing outer dock directions at the same time. -By utilizing this method, developers can effortlessly control the visibility and positioning of panes based on user interaction or application events. + -Try it for yourself in the sample below: +### Focus Panes Programmatically - +Use the `focusPane` method to activate a specific pane by its `contentId`. +```ts +this.dockManager.focusPane('content1'); +``` + +The current topic verifies these behaviors: + +- Floating panes are brought to the front and focused. +- Unpinned panes are flown out into their open state. +- Regular pinned panes become the active pane. + -## Auto-hide Pane Headers +### Auto-hide Pane Headers -With the `showPaneHeaders` property of the DockManager, developers now have the flexibility to control the visibility of pane headers within the `layout`. By default, `showPaneHeaders` is set to `always` ensuring that pane headers are always visible. When set to `onHoverOnly`, all pane headers will be hidden until you hover your mouse over the top edge of a content pane. The corresponding pane header will appear and it will smoothly hide once your mouse moves away. Take a look at the example below: +Set the `showPaneHeaders` property when pane headers should be always visible or appear only on hover. - +The existing topic verifies `always` as the default behavior and `onHoverOnly` as the mode that hides pane headers until the pointer reaches the top edge of a content pane. + -## Control Inner Docking -By default, the Dock Manager allows users to effortlessly drag and dock panes inside each other, creating tabs. To provide more control over this functionality, we've introduced two properties - `allowInnerDock` and `acceptsInnerDock`. +### Control Inner Docking -By setting the `acceptsInnerDock` property of an , developers can control docking inside specific content panes. When this property is set to false, users will be restricted from performing inner docking in the specified pane. +Use `allowInnerDock` and `acceptsInnerDock` to decide whether panes can be grouped inside each other as tabs. +Set `acceptsInnerDock` on a specific content pane when that target should reject inner docking: @@ -94,35 +121,25 @@ By setting the `acceptsInnerDock` property of an -If you wish to disable inner docking throughout the DockManager, simply set `allowInnerDock` to **false**. This property determines whether the end user is permitted to inner dock panes at all. - +Set `allowInnerDock` on the dock manager when inner docking should be disabled entirely: ```ts this.dockManager.allowInnerDock = false; ``` - - - -## Control Pane Dragging - -With the `containedInBoundaries` property, developers can control whether the sides of floating panes are always contained within the DockManager. When set to **true**, pane dragging will stop once any of the sides attempt to move beyond the DockManager boundaries. + +### Keep Floating Panes Within Boundaries -Try it in the example below: +Set `containedInBoundaries` when floating panes should stop at the dock manager edges instead of moving beyond the visible workspace. - +The current topic verifies that, when this property is `true`, pane dragging stops once any pane side attempts to move outside the dock manager boundaries. + -## Highlight Resizing Panes +### Highlight Resizing Panes -When users resize panes by dragging a splitter, it is not always obvious which panes are affected, especially in more complex layouts. To make this interaction clearer, the Dock Manager can draw a border around the panes that are currently being resized. This visual cue helps users immediately understand which parts of the layout will grow or shrink as they move the splitter. - -You can enable and style this behavior by configuring the following CSS custom properties on the Dock Manager host element (or a parent element): - -- `--igc-resize-target-border-color` – controls the color of the resize target border. -- `--igc-resize-target-border-width` – controls the thickness of the border (for example, `2px`). -- `--igc-resize-target-border-style` – controls the border style (for example, `solid`, `dashed`). +Set resize-target styling variables when users need stronger visual feedback about which panes are affected during splitter resizing. ```css igc-dockmanager { @@ -132,21 +149,13 @@ igc-dockmanager { } ``` -Once these variables are set, any pane that is impacted by a splitter drag will be wrapped with the configured border for the duration of the resize operation, giving users clear, immediate feedback about which panes are being adjusted. - -## Split Panes Fixed Size Mode - -By default, each pane in a split layout receives a relative size compared to its siblings and that size defaults to 100. For example, if you have two sibling panes where the first pane has its size set to 400 and the second one to 200, the first will be twice the size of the second and together they will fill all the available space. +The configured border is applied for the duration of the resize interaction to the panes affected by the active splitter drag. -If, for certain panes, you want explicit pixel-based sizing instead of relative sizing, you can turn on fixed size mode by setting the `useFixedSize` property of the parent split pane to **true**. When this property is enabled, all children are sized in pixels based on their `size` property. In the previous example, the first pane will span 400 pixels and the second pane 200 pixels. Resizing via the splitter changes only the size of the pane you are interacting with, without redistributing space across its siblings. +### Use Fixed-size Split Panes -As soon as the sum of the child panes' sizes exceeds the available size of the parent, the split pane becomes scrollable. The dock manager now also provides built-in autoscrolling to keep the user focused on their content: - -- When users **drag panes toward the edges** of a fixed-size root pane, the container scrolls in the direction of the drag so they can easily reach off-screen areas. -- When users **resize panes via the splitter**, the container scrolls as needed to reveal newly expanded content. - -For a **horizontal** split pane, autoscrolling happens to the **left** or **right**; for a **vertical** split pane, it happens to the **top** or **bottom**, depending on the direction of the drag or resize. +Set `useFixedSize` on a parent split pane when child `size` values should be interpreted as pixels instead of relative sizing weights. +By default, split-pane sizes are relative to sibling panes. When `useFixedSize` is `true`, child pane sizes are treated as explicit pixel values, and resizing changes only the interacted pane instead of redistributing space proportionally across siblings. @@ -159,13 +168,13 @@ const splitPaneRelativeSize: IgcSplitPane = { type: IgcDockManagerPaneType.contentPane, contentId: 'content1', header: 'Pane 1', - size: 400 // Size will be relative to siblings + size: 400 }, { type: IgcDockManagerPaneType.contentPane, contentId: 'content2', header: 'Pane 2', - size: 200 // Size will be relative to siblings + size: 200 } ] } @@ -179,13 +188,13 @@ const splitPaneFixedSize: IgcSplitPane = { type: IgcDockManagerPaneType.contentPane, contentId: 'content3', header: 'Pane 3', - size: 400 // Size will be applied in pixels + size: 400 }, { type: IgcDockManagerPaneType.contentPane, contentId: 'content4', header: 'Pane 4', - size: 200 // Size will be applied in pixels + size: 200 } ] } @@ -193,15 +202,99 @@ const splitPaneFixedSize: IgcSplitPane = { -Please note that when you dock a pane inside a split pane that has `useFixedSize` set to **true** the docked pane will then have the same width/height (depending on the split pane orientation) as the floating pane. +When the sum of child pane sizes exceeds the parent size, the split pane becomes scrollable. The existing topic also documents built-in autoscrolling during drag and resize interactions for fixed-size root panes. + + -Try it for yourself in the sample below: +## Best Practices - +Use Dock Manager customization options to reduce friction in real workspace tasks, not to expose every possible movement or docking mode by default. +- Enable proximity docking only when it improves speed without making dock targets ambiguous for users. +- Use `focusPane` for deliberate app flows such as opening tools, surfacing validation results, or restoring saved workspace context. +- Hide pane headers on hover only when users can still discover pane actions reliably. +- Disable inner docking for panes that should remain structurally separate from tabbed content groups. +- Use fixed-size split panes for deliberate pixel-based layouts, not for layouts that should naturally rebalance with available space. + +## Properties + +Use the generated API reference for the full surface; the rows below mark the core customization options covered on this page. + +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `proximityDock` | build-generated | build-generated | Build injects verified dock manager customization properties here from the typed API source. | +| `showPaneHeaders` | build-generated | build-generated | Build injects verified dock manager customization properties here from the typed API source. | +| `allowInnerDock` | build-generated | build-generated | Build injects verified dock manager customization properties here from the typed API source. | +| `containedInBoundaries` | build-generated | build-generated | Build injects verified dock manager customization properties here from the typed API source. | +| `acceptsInnerDock` | build-generated | build-generated | Build injects verified content pane customization properties here from the typed API source. | +| `useFixedSize` | build-generated | build-generated | Build injects verified split pane customization properties here from the typed API source. | +| `size` | build-generated | build-generated | Build injects verified split pane sizing properties here from the typed API source. | + +## Methods + +Use dock manager methods when you need to change pane focus programmatically. + +| Name | Description | +| -- | -- | +| `focusPane` | Focuses a pane by `contentId`. | + +## Styling + +Use CSS variables to customize the visual feedback for resize-target highlighting during splitter operations. + +| Variable | What it changes | +| -- | -- | +| `--igc-resize-target-border-color` | The color of the border drawn around panes affected by a splitter resize. | +| `--igc-resize-target-border-width` | The thickness of the resize-target border. | +| `--igc-resize-target-border-style` | The line style of the resize-target border. | + +```css +igc-dockmanager { + --igc-resize-target-border-color: #0078d4; + --igc-resize-target-border-width: 2px; + --igc-resize-target-border-style: solid; +} +``` + +## Accessibility + +Dock Manager customization changes how panes appear, move, and reveal actions, so accessibility review should cover both the base component behavior and the customization choices you enable. + +### Keyboard Interaction + +[VERIFY: keyboard impact of proximity dock, auto-hidden pane headers, fixed-size split-pane customization, and programmatic focus changes] + +### Screen Readers / ARIA + +[VERIFY: screen reader impact of pane-header visibility changes, focusPane behavior, and resize-target highlighting] + +### Accessibility Compliance + +[VERIFY: official accessibility conformance target for Dock Manager customization scenarios] + +| Criterion | How the component complies | +| -- | -- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | [VERIFY: keyboard operability with the customization options covered on this page] | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order) | Programmatic pane focusing and customized pane visibility should preserve a predictable focus sequence. | +| [2.5.7 Dragging Movements](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements) | [VERIFY: non-drag alternatives or constraints for the customization features on this page] | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value) | [VERIFY: semantic exposure after customization of pane headers and docking behavior] | + +Your responsibilities: + +- Verify that hidden-on-hover pane headers remain discoverable and operable for keyboard and assistive technology users. +- Preserve clear pane names when using `focusPane` or changing docking behavior programmatically. +- Validate contrast and visibility for resize-target highlighting after overriding its CSS variables. ## API References + + + +## Dependencies + +This topic depends on the base Dock Manager component setup and layout model described in the main [Dock Manager](./dock-manager.md) topic. + +## Additional Resources -
-
+- [Dock Manager](./dock-manager.md) +- [{ProductName} **GitHub**]({GithubLink}) diff --git a/docs/xplat/src/content/en/components/layouts/dock-manager-electron.mdx b/docs/xplat/src/content/en/components/layouts/dock-manager-electron.mdx index 5c57aadbb5..3dea841ab3 100644 --- a/docs/xplat/src/content/en/components/layouts/dock-manager-electron.mdx +++ b/docs/xplat/src/content/en/components/layouts/dock-manager-electron.mdx @@ -1,11 +1,12 @@ --- -title: "{Platform} Dock Manager | Desktop Integration | Infragistics" -description: Use Infragistics' {Platform} dock manager component to manage the layout of multi-window Electron desktop application. Check out {ProductName} dock manager tutorials! -keywords: dock manager, layout, {ProductName}, Infragistics +title: "{Platform} Dock Manager Component | Desktop Integration | Infragistics" +description: "The Infragistics {Platform} Dock Manager can be integrated into a multi-window Electron application to move panes across windows and manage each window layout." +keywords: "dock manager, layout, electron, {ProductName}, Infragistics" license: commercial mentionedTypes: ["DockManager", "DocumentHost", "DockManagerLayout", "DockManagerPaneType", "ContentPane", "SplitPane", "TabGroupPane", "PinnedLocation", "PaneHeaderElement"] llms: - description: "The Infragistics {Platform} Dock Manager component can be used in a multi-window Electron desktop application to manage the layout of each window, drag panes outside of a window in order to create a new window and drag/drop panes from one window to another." + description: "The Infragistics {Platform} Dock Manager can be integrated into a multi-window Electron application to move panes across windows and manage each window layout." +relatedComponents: ["Splitter", "Tabs"] --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; @@ -13,35 +14,71 @@ import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; import { Image } from 'astro:assets'; import dockmanagerElectronApp from '@xplat-images/dockmanager-electron-app.gif'; +# Dock Manager Component -# {Platform} Dock Manager Desktop Integration +The Infragistics {Platform} Dock Manager can be integrated into a multi-window Electron application to move panes across windows and manage each window layout. -The Infragistics {Platform} Dock Manager component can be used in a multi-window [Electron](https://www.electronjs.org/) desktop application to manage the layout of each window, drag panes outside of a window in order to create a new window and drag/drop panes from one window to another. You could find a sample implementation of such application in the following repository https://github.com/IgniteUI/dock-manager-electron-app. +## Overview -{/*TODO: Add a gif of the application and a link to download the exe*/} -{Platform} Dock Manager desktop integration +This topic shows how to extend Dock Manager beyond a single browser window so panes can be dragged out into new Electron windows and dropped back into other dock manager instances. + +### When to Use + +Use this integration pattern when your desktop app needs detachable tool windows, cross-window pane movement, and a separate dock manager layout per Electron window. + +### When Not to Use -## Implementation +Do not use Electron-specific window integration when the app only needs in-window floating panes or simple layout resizing. For single-window layouts, use the base [Dock Manager](./dock-manager.md) behavior, and for simpler pane sizing use the [Splitter](./splitter.md) component. -Let's go through the most important parts of the implementation of this application. +[VERIFY: live Electron Dock Manager demo sample path] + +## Anatomy + +The Electron integration combines one Dock Manager instance per renderer window with custom drag-and-drop coordination and window management logic in the Electron main and renderer processes. + +{Platform} Dock Manager desktop integration ### Project Structure -We have used the [Electron Forge](https://www.electronforge.io/) CLI tool and its [Typescript + Webpack](https://www.electronforge.io/templates/typescript-+-webpack-template) template to create an Electron application. Electron has two types of processes: Main and Renderer. -- The Main process creates web pages by creating **BrowserWindow** instances. Each **BrowserWindow** instance runs the web page in its Renderer process. -- The Renderer process manages only the corresponding web page. +The referenced implementation uses [Electron Forge](https://www.electronforge.io/) with the [TypeScript + Webpack](https://www.electronforge.io/templates/typescript-+-webpack-template) template. -The **index.ts** script specifies the entry point of the Electron application that will run the Main process. Most of the code of our application is inside the **renderer.ts** file which runs in the Renderer process. The **index.html** represents the content of the web page. The styles of the web page are hosted in the **index.css** file. +- The main process creates `BrowserWindow` instances. +- Each `BrowserWindow` hosts a renderer process. +- `index.ts` is the Electron main-process entry point. +- `renderer.ts` hosts most of the Dock Manager integration logic. +- `index.html` and `index.css` define the page markup and styles for each renderer window. -### Dock Manager Setup +## Getting Started -After installing the Dock Manager package, we have registered the Dock Manager component using the **defineCustomElements()** in the **renderer.ts** file. This allows to add the **``** in the **index.html** file. +Before you build the Electron integration, complete the base Dock Manager setup in the [Dock Manager](./dock-manager.md) topic and add the Electron application shell that will host your dock manager instances. -For the Dock Manager pane contents we have used **iframe** elements which host different urls. In our case these urls point to [Ignite UI for Angular](https://www.infragistics.com/products/ignite-ui-angular) samples. Since the **iframe** elements are self-contained, moving them from one window to another is easily accomplished. + + +Register the Dock Manager component in the renderer process before you render ``. + +```ts +import { defineCustomElements } from 'igniteui-dockmanager'; -### Drag and drop +defineCustomElements(); +``` + + -In order to support dragging panes outside the application window we have replaced the built-in drag/drop which creates in-application floating panes with a custom implementation based on the [HTML Drag and Drop API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API). We have subscribed to the `PaneHeaderConnected` and `TabHeaderConnected` events which are fired when a header element is connected to the DOM. When a header element is connected we reset the built-in and attach `DragStart` and `DragEnd` event listeners. +## Usage + +Set up a Dock Manager instance in each renderer window, replace the built-in pane drag flow where needed, and coordinate pane transfer between windows through Electron window management APIs. + +### Set Up the Renderer Content + +Render an `` inside the Electron renderer page and use `iframe` elements as pane contents when the content should remain self-contained while moving between windows. + +The existing implementation uses `iframe` elements that host external URLs so those content nodes can be transferred between windows with minimal coupling. + +### Replace the Built-in Pane Drag Flow + +Use custom drag handling when panes should be dragged outside the current application window instead of being limited to in-window floating panes. + +The existing integration subscribes to the `paneHeaderConnected` and `tabHeaderConnected` events, clears the built-in instance, and wires native drag event handlers to the connected header element. @@ -64,8 +101,9 @@ dockManager.addEventListener('paneHeaderConnected', paneHeaderConnected); +### Notify Dock Manager About Drag Start -In the `PaneHeaderDragStart` function we set the property of the Dock Manager component which will notify it that a drag operation has been started. +Set the property when the native drag operation starts so Dock Manager can track which pane is being moved. @@ -79,7 +117,9 @@ const paneHeaderDragStart = async (pane: IgcContentPane, event: DragEvent) => { -We have subscribed to the `DragOver` and `drop` events of the `document` element. In the `DragOver` listener we notify the Dock Manager that the mouse is dragged over it by setting its property. This forces the Dock Manager to display its docking indicators. +### Show Docking Indicators During Document Drag + +Handle `dragover` on the document and update so the target Dock Manager can display docking indicators during the native drag operation. ```ts const handleDocumentDragOver = (event: DragEvent) => { @@ -95,14 +135,17 @@ document.addEventListener('dragover', handleDocumentDragOver); document.addEventListener('drop', handleDocumentDrop); ``` -In the `paneHeaderDragEnd` function we detect if the pane was dropped outside the application window and we call the `droppedOutOfWindow` function. +### Handle Drops Outside the Current Window + +Detect when a drag ends outside the current application window and branch into your out-of-window pane transfer logic. + + ```ts const paneHeaderDragEnd = async (event: DragEvent) => { event.preventDefault(); // ... - // dropped outside of the application if (event.dataTransfer.dropEffect === 'none') { await droppedOutOfWindow(event); } @@ -110,7 +153,11 @@ const paneHeaderDragEnd = async (event: DragEvent) => { } ``` -When the pane header is dropped inside a document we call the `DropPane` method which notifies the Dock Manager that the dragged pane was dropped. If the pane was dropped on a docking indicator the method returns **true**. If the pane was dropped in the same window it was dragged from, the pane will be docked to its new position automatically. However, if it was dropped in another window we call the `droppedInAnotherWindow` function which first removes the pane from the source Dock Manager and then adds it to the new one. + + +### Dock Panes Into the Target Window + +Call the Dock Manager drop API when a pane is dropped over a document and then check whether the content belongs to the current dock manager or needs to be transferred in from another window. @@ -123,7 +170,6 @@ const handleDocumentDrop = async (event: DragEvent) => { if (docked) { const contentElement = dockManager.querySelector('[slot=' + contentId + ']'); - // if the content element is missing from the current dock manager it means it comes from another window if (!contentElement) { await droppedInAnotherWindow(); } @@ -133,7 +179,11 @@ const handleDocumentDrop = async (event: DragEvent) => { -When a pane is dropped out of its current window, we need to remove the from its Dock Manager component and update the layout. +If the pane is dropped in the same window it was dragged from, Dock Manager re-docks it in place. If it is dropped in another window, the implementation removes the pane from the source Dock Manager and adds it to the target one. + +### Remove the Pane From the Source Layout + +Remove the from the source Dock Manager and reassign the layout so the source window reflects the updated pane tree. @@ -145,7 +195,9 @@ dockManager.layout = { ...dockManager.layout }; -Next, we need to move the pane content element to its new window. For this purpose, we use the [document.adoptNode()](https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptNode) method, which allows us to transfer the content element node to the new document and finally, append it as a child of the new Dock Manager component. +### Move Pane Content to the New Window + +Use `document.adoptNode()` to transfer the pane content node into the target window document and append it to the target Dock Manager instance. @@ -159,9 +211,9 @@ newDockManager.appendChild(adoptedNode); -### Window Management +### Configure Electron Window Management -We are using the native [window.open()](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) method to open a new window in the Renderer process. We set the `nativeWindowOpen` option to **true** when creating the `BrowserWindow` in the **index.ts**. This gives us direct access to the child `Window` object and its `document`. You could read more about opening windows from the Renderer process in this Electron [topic](https://www.electronjs.org/docs/api/window-open). Please note that the `nativeWindowOpen` option is still experimental. +Open child windows from the renderer process with `window.open()` and enable `nativeWindowOpen` on the Electron `BrowserWindow` so the renderer receives direct access to the child `Window` object and its `document`. ```ts mainWindow = new BrowserWindow({ @@ -173,14 +225,88 @@ mainWindow = new BrowserWindow({ }); ``` -In this application we have implemented an `IDockManagerWindow` type which could be either a main window (`IMainDockManagerWindow`) or a child window (`IChildDockManagerWindow`). The main window is the one created when the application starts. It contains references to all its child windows. A child window is created when a pane is dropped out of a window and has a reference to the main window of the application. +The referenced implementation models windows through an `IDockManagerWindow` abstraction with separate main-window and child-window variants so each child window can resolve back to the main application window. + +## Best Practices + +Use Electron integration only when the app truly benefits from multi-window pane movement and window-specific layouts. + +- Keep pane content self-contained so moving it between windows does not break shared state unexpectedly. +- Reassign the Dock Manager layout after pane removal so the source window stays in sync with the transferred content. +- Restrict cross-window drag logic to the pane headers or tabs that should actually support window detachment. +- Centralize window bookkeeping so child windows can always resolve the owning main window and active dock manager instance. +- Test out-of-window drag, cross-window drop, and window-close recovery together because the integration depends on both Dock Manager state and Electron window lifecycle state. + +## Properties + +Use the generated API reference for the full surface; the rows below mark the core Dock Manager properties used by the Electron integration. + +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `draggedPane` | build-generated | build-generated | Build injects verified dock manager drag-state properties here from the typed API source. | +| `dropPosition` | build-generated | build-generated | Build injects verified dock manager drag-state properties here from the typed API source. | +| `layout` | build-generated | build-generated | Build injects verified dock manager layout properties here from the typed API source. | + +## Methods + +Use dock manager methods when you need to complete pane transfer and docking during Electron drag-and-drop flows. + +| Name | Description | +| -- | -- | +| `dropPane` | Notifies Dock Manager that the dragged pane has been dropped. | +| `removePane` | Removes a pane from the current dock manager layout. | + +## Events + +Use dock manager events when you need to attach custom drag behavior to pane or tab headers. -For the full source code please clone the [repository](https://github.com/IgniteUI/dock-manager-electron-app). +| Name | Description | +| -- | -- | +| `paneHeaderConnected` | Fires when a pane header element is connected to the DOM. | +| `tabHeaderConnected` | Fires when a tab header element is connected to the DOM. | +## Accessibility + +Electron integration changes how panes move across windows, so accessibility validation should include cross-window focus movement and drag alternatives in addition to the base Dock Manager behavior. + +### Keyboard Interaction + +[VERIFY: keyboard support and non-pointer alternatives for Electron window detaching and cross-window pane transfer] + +### Screen Readers / ARIA + +[VERIFY: screen reader behavior for moving panes across windows and adopting pane content into another document] + +### Accessibility Compliance + +[VERIFY: official accessibility conformance target for Dock Manager Electron integration scenarios] + +| Criterion | How the component complies | +| -- | -- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | [VERIFY: keyboard operability of the Electron-specific pane transfer workflow] | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order) | [VERIFY: predictable focus behavior after panes move into another window] | +| [2.5.7 Dragging Movements](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements) | [VERIFY: non-drag alternatives or documented limitations for cross-window pane movement] | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value) | [VERIFY: semantic exposure after pane content is rehosted in another window document] | + +Your responsibilities: + +- Preserve clear pane headers so users can identify panes before and after they move between windows. +- Validate focus restoration when a pane is dropped into a new Electron window. +- Provide accessible alternatives if your Electron integration depends on pointer-only drag gestures. ## API References -
-
-
-
+ + + + + +## Dependencies + +This integration depends on the base Dock Manager setup plus an Electron application shell with renderer and main processes. The referenced implementation uses Electron Forge and Electron `BrowserWindow` configuration. + +## Additional Resources + +- [Dock Manager](./dock-manager.md) +- [dock-manager-electron-app](https://github.com/IgniteUI/dock-manager-electron-app) +- [{ProductName} **GitHub**]({GithubLink}) diff --git a/docs/xplat/src/content/en/components/layouts/dock-manager-embedding-frames.mdx b/docs/xplat/src/content/en/components/layouts/dock-manager-embedding-frames.mdx index 50b94ab1ca..aa9b387181 100644 --- a/docs/xplat/src/content/en/components/layouts/dock-manager-embedding-frames.mdx +++ b/docs/xplat/src/content/en/components/layouts/dock-manager-embedding-frames.mdx @@ -1,57 +1,63 @@ --- -title: "{Platform} Dock Manager | Embed Frames | Infragistics" -description: Use Infragistics' {Platform} dock manager to embed interactive content using panes. View {ProductName} dock manager tutorials! -keywords: dock manager, embed frames, {ProductName}, Infragistics +title: "{Platform} Dock Manager Component | Embed Frames | Infragistics" +description: "The Infragistics {Platform} Dock Manager provides a pane-based layout for embedding interactive frame content inside an application workspace." +keywords: "dock manager, embed frames, {ProductName}, Infragistics" license: commercial mentionedTypes: ["DockManager"] llms: - description: "The Infragistics {Platform} Dock Manager component provides you with the layout for embedding interactive content in your application using panes." + description: "The Infragistics {Platform} Dock Manager provides a pane-based layout for embedding interactive frame content inside an application workspace." +relatedComponents: ["Tabs", "Splitter"] --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Embedding Frames in Dock Manager +# Dock Manager Component -The Infragistics {Platform} Dock Manager component provides you with the layout for embedding interactive content in your application using panes. +The Infragistics {Platform} Dock Manager provides a pane-based layout for embedding interactive frame content inside an application workspace. -## {Platform} Embedding Frames in Dock Manager Example +## Overview +This topic covers the Dock Manager usage pattern where panes host embedded frame content as part of a larger docked workspace. - +### When to Use +Use embedded frames in Dock Manager when your app needs multiple isolated content surfaces, external tools, or self-contained views arranged in dockable panes. +### When Not to Use +Do not use embedded frames when the content can be rendered directly inside the current view without iframe-style isolation. For simple view switching, use the [Tabs](./tabs.md) component, and for simpler pane sizing use the [Splitter](./splitter.md) component. -{/*
- -
*/} + -
+## Getting Started -{/* -## Usage - -Once the Dock Manager is imported, you can add it on the page: +Before you embed frame content in Dock Manager, complete the base component setup in the [Dock Manager](./dock-manager.md) topic. +Render an `` instance and assign the layout that will host your embedded content panes. + ```html - - + ``` +## Usage + +Define a Dock Manager layout, then assign embedded content to the pane slots that should host the interactive frames. + +### Define the Pane Layout + +Set the property with content panes that describe where the embedded content should appear. + ```ts import { IgcDockManagerPaneType, IgcSplitPaneOrientation, IgcDockManagerComponent } from 'igniteui-dockmanager'; -// ... - -this.dockManager = document.getElementById("dockManager") as IgcDockManagerComponent; +this.dockManager = document.getElementById('dockManager') as IgcDockManagerComponent; this.dockManager.layout = { rootPane: { type: IgcDockManagerPaneType.splitPane, @@ -69,6 +75,10 @@ this.dockManager.layout = { +### Provide Embedded Content + +Match each pane `contentId` with a slotted content element so the embedded frame content renders inside the correct pane. + ```html @@ -77,9 +87,64 @@ this.dockManager.layout = { ``` - */} + + +[VERIFY: frame-specific markup, iframe guidance, or isolation constraints for this Dock Manager embedding scenario] + +## Best Practices + +Use embedded frame content only where pane isolation is worth the added complexity. + +- Keep each embedded pane focused on one task so the docked workspace stays understandable. +- Give embedded content predictable width and height behavior so pane resizing does not produce clipped surfaces. +- Use clear pane headers so users can identify each embedded view quickly. +- Prefer direct component rendering over embedded frames when the content does not need isolation. +## Properties + +Use the generated API reference for the full surface; the rows below mark the core Dock Manager property used by this topic. + +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `layout` | build-generated | build-generated | Build injects verified Dock Manager layout properties here from the typed API source. | + +## Accessibility + +Embedded frame content adds another focus and navigation boundary, so accessibility review should cover both the Dock Manager host and the embedded content itself. + +### Keyboard Interaction + +[VERIFY: keyboard interaction expectations for embedded frame content inside Dock Manager panes] + +### Screen Readers / ARIA + +[VERIFY: screen reader behavior for embedded frame content and pane labeling in this scenario] + +### Accessibility Compliance + +[VERIFY: official accessibility conformance target for Dock Manager embedding-frame scenarios] + +| Criterion | How the component complies | +| -- | -- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | [VERIFY: keyboard operability across the dock manager host and embedded frames] | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order) | [VERIFY: predictable focus movement into and out of embedded frame panes] | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value) | [VERIFY: semantic exposure of pane headers and embedded content regions] | + +Your responsibilities: + +- Provide clear pane headers so users can identify the embedded content in each pane. +- Ensure embedded content has its own accessible naming and keyboard support where required. +- Validate focus order when users move between the dock manager host and the embedded content. ## API References -
+ + +## Dependencies + +This topic depends on the base Dock Manager setup and layout model described in the main [Dock Manager](./dock-manager.md) topic. + +## Additional Resources + +- [Dock Manager](./dock-manager.md) +- [{ProductName} **GitHub**]({GithubLink}) diff --git a/docs/xplat/src/content/en/components/layouts/dock-manager-updating-panes.mdx b/docs/xplat/src/content/en/components/layouts/dock-manager-updating-panes.mdx index 0e58a5f973..067b01640d 100644 --- a/docs/xplat/src/content/en/components/layouts/dock-manager-updating-panes.mdx +++ b/docs/xplat/src/content/en/components/layouts/dock-manager-updating-panes.mdx @@ -1,57 +1,63 @@ --- -title: "{Platform} Dock Manager | Updating Panes | Infragistics" -description: Use Infragistics' {Platform} dock manager control to create interactive content using panes that can update based on actions. Check out {ProductName} dock manager tutorials! -keywords: dock manager, layout, updating panes, {ProductName} +title: "{Platform} Dock Manager Component | Updating Panes | Infragistics" +description: "The Infragistics {Platform} Dock Manager provides a pane-based layout for interactive content that updates in response to user actions." +keywords: "dock manager, layout, updating panes, {ProductName}" license: commercial mentionedTypes: ["DockManager"] llms: - description: "The Infragistics {Platform} Dock Manager component provides you with the layout for creating interactive content in your application using panes that can update based on actions of end-users." + description: "The Infragistics {Platform} Dock Manager provides a pane-based layout for interactive content that updates in response to user actions." +relatedComponents: ["Tabs", "Splitter"] --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Updating Panes in Dock Manager +# Dock Manager Component -The Infragistics {Platform} Dock Manager component provides you with the layout for creating interactive content in your application using panes that can update based on actions of end-users. +The Infragistics {Platform} Dock Manager provides a pane-based layout for interactive content that updates in response to user actions. -## {Platform} Updating Panes in Dock Manager Example +## Overview +This topic covers the Dock Manager usage pattern where pane content reacts to end-user actions and updates within the docked workspace. - +### When to Use +Use updating panes in Dock Manager when the workspace needs multiple coordinated views that respond to user actions without leaving the current layout. +### When Not to Use +Do not use Dock Manager when a single region update or a lightweight view switch is enough. For simple view switching, use the [Tabs](./tabs.md) component, and for simpler pane sizing use the [Splitter](./splitter.md) component. -{/*
- -
*/} + -
+## Getting Started -{/* -## Usage - -Once the Dock Manager is imported, you can add it on the page: +Before you build updating panes in Dock Manager, complete the base component setup in the [Dock Manager](./dock-manager.md) topic. +Render an `` instance and assign the layout that will host the interactive pane content. + ```html - - + ``` +## Usage + +Define a Dock Manager layout, then place interactive content into the pane slots so updates can happen within the docked workspace. + +### Define the Pane Layout + +Set the property with content panes that describe where the interactive views should render. + ```ts import { IgcDockManagerPaneType, IgcSplitPaneOrientation, IgcDockManagerComponent } from 'igniteui-dockmanager'; -// ... - -this.dockManager = document.getElementById("dockManager") as IgcDockManagerComponent; +this.dockManager = document.getElementById('dockManager') as IgcDockManagerComponent; this.dockManager.layout = { rootPane: { type: IgcDockManagerPaneType.splitPane, @@ -69,6 +75,10 @@ this.dockManager.layout = { +### Provide Interactive Pane Content + +Match each pane `contentId` with a slotted content element so the pane content can react to user actions in place. + ```html @@ -77,9 +87,65 @@ this.dockManager.layout = { ``` - */} + + +[VERIFY: specific pane-update pattern, event flow, or data-binding guidance demonstrated by the updating-panes sample] + +## Best Practices + +Use updating panes when each pane contributes to a coordinated workflow instead of duplicating the same information in multiple places. + +- Keep pane responsibilities distinct so users can understand what each pane updates and why. +- Use clear pane headers so users can identify which pane changed after an interaction. +- Keep pane content sized predictably so runtime updates do not cause clipped or unstable layouts. +- Prefer direct in-app updates over full pane replacement when the user should maintain context in the current workspace. +## Properties + +Use the generated API reference for the full surface; the rows below mark the core Dock Manager property used by this topic. + +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `layout` | build-generated | build-generated | Build injects verified Dock Manager layout properties here from the typed API source. | + +## Accessibility + +Updating panes can change visible content without changing the overall docked layout, so accessibility review should confirm that users can detect, reach, and understand those updates. + +### Keyboard Interaction + +[VERIFY: keyboard interaction expectations for pane updates triggered by user actions in this Dock Manager scenario] + +### Screen Readers / ARIA + +[VERIFY: screen reader announcements or update semantics for changing pane content in this Dock Manager scenario] + +### Accessibility Compliance + +[VERIFY: official accessibility conformance target for Dock Manager updating-pane scenarios] + +| Criterion | How the component complies | +| -- | -- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | [VERIFY: keyboard operability of the interactive pane-update workflow] | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order) | [VERIFY: predictable focus behavior when pane content updates] | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value) | [VERIFY: semantic exposure of pane headers and updated content regions] | +| [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages) | [VERIFY: announcement behavior for meaningful pane content updates] | + +Your responsibilities: + +- Provide clear pane headers so users can identify which pane changed. +- Ensure important pane updates are communicated accessibly when the new content is not obvious from focus movement alone. +- Validate focus order when interactions in one pane trigger updates in another pane. ## API References -
+ + +## Dependencies + +This topic depends on the base Dock Manager setup and layout model described in the main [Dock Manager](./dock-manager.md) topic. + +## Additional Resources + +- [Dock Manager](./dock-manager.md) +- [{ProductName} **GitHub**]({GithubLink}) diff --git a/docs/xplat/src/content/en/components/layouts/dock-manager.mdx b/docs/xplat/src/content/en/components/layouts/dock-manager.mdx index d42b1e3853..add37ca560 100644 --- a/docs/xplat/src/content/en/components/layouts/dock-manager.mdx +++ b/docs/xplat/src/content/en/components/layouts/dock-manager.mdx @@ -1,11 +1,12 @@ --- -title: "{Platform} Dock Manager | Layout Controls | Infragistics" -description: Use Infragistics' {Platform} dock manager component to manage the layout through panes, with the ability to customize it by pinning, resizing, moving and hiding panes. Check out {ProductName} dock manager tutorials! -keywords: dock manager, layout, {ProductName}, Infragistics +title: "{Platform} Dock Manager Component | Layouts | Infragistics" +description: "The Infragistics {Platform} Dock Manager arranges application views in panes that users can dock, float, resize, pin, hide, and persist." +keywords: "{Platform}, dock manager, layout, Infragistics" license: commercial mentionedTypes: ["DockManager", "DocumentHost", "DockManagerLayout", "DockManagerPaneType", "ContentPane", "SplitPane", "TabGroupPane", "PinnedLocation", "PaneHeaderElement"] llms: - description: "The Infragistics {Platform} Dock Manager provides a means to manage the layout of your application through panes, allowing your end-users to customize it further by pinning, resizing, moving, maximizing and hiding panes." + description: "The Infragistics {Platform} Dock Manager arranges application views in panes that users can dock, float, resize, pin, hide, and persist." +relatedComponents: ["Splitter", "Tabs"] --- import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; @@ -19,40 +20,79 @@ import dockmanagerDocumentHostDocking from '@xplat-images/dockmanager-document-h import dockmanagerSplitterDocking from '@xplat-images/dockmanager-splitter-docking.jpg'; import dockmanagerEdgeDocking from '@xplat-images/dockmanager-edge-docking.jpg'; +# Dock Manager Component -# {Platform} Dock Manager Overview +The Infragistics {Platform} Dock Manager arranges application views in panes that users can dock, float, resize, pin, hide, and persist. -The Infragistics {Platform} Dock Manager provides a means to manage the layout of your application through panes, allowing your end-users to customize it further by pinning, resizing, moving, maximizing and hiding panes. +## Overview -## {Platform} Dock Manager Example +Dock Manager gives you a desktop-style workspace where multiple tools, documents, and supporting views can share the same page and still remain user-configurable at runtime. -This example shows most functionalities and docking options of the that you can use in your application. +### When to Use - +Use Dock Manager when the page needs a complex workspace with multiple panes, floating windows, tabbed documents, runtime docking, and layout persistence. +### When Not to Use +Do not use Dock Manager for simple fixed pane resizing or lightweight tab switching. For simpler split layouts, use the [Splitter](./splitter.md) component, and for switching between related views inside one region, use the [Tabs](./tabs.md) component. + -
+## Anatomy +Dock Manager renders a pane hierarchy where content panes are grouped inside split panes, tab groups, document hosts, and optional floating windows. - +### Pane Types +The dock manager layout is composed from the following pane types: -To install the Dock Manager package execute the following command: +- +- +- +- -```cmd -npm install --save {PackageDockManager} -``` +### Docking Indicators - +Dragging a floating pane can show different docking targets depending on the hovered location. + +#### Root Docking + +Root docking docks a pane against the outer edges of the dock manager and makes it a direct child of the layout root pane. + +Dock Manager root docking indicators + +#### Pane Docking + +Pane docking docks a floating pane around an existing content pane or tab group, or groups it into tabs. + +Dock Manager pane docking indicators + +#### Document Host Docking + +Document host docking adds targets that dock relative to the active document region. + +Dock Manager document host docking indicators + +#### Splitter Docking + +Splitter docking inserts a pane directly into an existing split boundary for more precise placement. + +Dock Manager splitter docking indicators + +#### Edge Docking + +Edge docking appears when root docking is disabled and lets users insert panes at the start or end of the root split direction. +Dock Manager edge docking indicators - -Then it is necessary to import and call the **defineComponents()** function: +## Getting Started + +Before you add Dock Manager, install the dock manager package and complete the shared {ProductName} setup in the [Getting Started](../general-getting-started.md) topic. +Register the dock manager component before you use it. + ```ts import { defineComponents, IgcDockManagerComponent } from 'igniteui-dockmanager'; @@ -60,46 +100,57 @@ defineComponents(IgcDockManagerComponent); ``` - - -
+ - +Import the dock manager wrapper before you render the component. +```tsx +import { IgrDockManager } from 'igniteui-react-dockmanager'; +``` + ## Usage -Once the Dock Manager is imported, you can add it on the page: +Render a dock manager, assign a layout object, then configure pane types, docking behavior, layout updates, persistence, events, and localization. + +### Render the Component + +Add the dock manager host first, then assign its layout and matching slotted content. + ```html ``` + + ```tsx ``` + -Since the Dock Manager component uses ShadowDOM and slots it is not supported on older browsers like Internet Explorer 11 and Edge 18 and below (non-Chromium versions). +Dock Manager relies on Shadow DOM and slots, so it does not support older non-Chromium browsers such as Internet Explorer 11 and Edge 18 and earlier. -The Dock Manager has a property, which describes the layout of the panes. To start defining a layout, you should set the property and add child panes. Here is how you can define a layout with a single content pane: +### Define the Initial Layout + +Set the property with a root pane and child panes to describe the workspace structure. + ```ts import { IgcDockManagerPaneType, IgcSplitPaneOrientation, IgcDockManagerComponent } from 'igniteui-dockmanager'; -// ... - -this.dockManager = document.getElementById("dockManager") as IgcDockManagerComponent; +this.dockManager = document.getElementById('dockManager') as IgcDockManagerComponent; this.dockManager.layout = { rootPane: { type: IgcDockManagerPaneType.splitPane, @@ -113,17 +164,16 @@ this.dockManager.layout = { ] } }; - ``` + -```tsx -import { IgrDockManager, IgrDockManagerPaneType, IgrSplitPaneOrientation } from 'igniteui-react-dockmanager'; -// ... +```tsx +import { IgrDockManager, IgrDockManagerPaneType, IgrSplitPaneOrientation } from 'igniteui-react-dockmanager'; -this.dockManager = document.getElementById("dockManager") as IgrDockManager; +this.dockManager = document.getElementById('dockManager') as IgrDockManager; this.dockManager.layout = { rootPane: { type: IgrDockManagerPaneType.splitPane, @@ -141,178 +191,76 @@ this.dockManager.layout = { -To load the content of the panes, the Dock Manager uses [slots](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot). The [slot](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/slot) attribute of the content element should match the of the content pane in the layout configuration. It is highly recommended to set width and height of the content elements to **100%** for predictable response when the end-user is resizing panes. +### Provide Slotted Content - -```html - -
Content 1
- -``` - +Match each pane `contentId` with a slotted content element so the dock manager can render the pane body. - -```tsx - -
Content 1
- -``` - - -The Dock Manager defines several pane types: -- -- -- -- - -Each type of pane has a property. Depending on the parent orientation the size may affect either the width or the height of the pane. By default, the size of a pane is relative to the sizes of its sibling panes and defaults to 100. If you have two sibling panes, where the first one has its size set to 200 and the second one - size set to 100, the first will be twice the size of the second one and these two panes would fill up all the available space. If the absolute size of their parent is 900px, they will be sized to 600px and 300px respectively. If, for certain panes, you want to specify their sizes in pixels, instead of relying on the relative distribution of all the available space, you should set the `useFixedSize` of the parent split pane. +Set the content element width and height to `100%` when the content should resize predictably with the pane. - For more information on this refer to [Split Panes Fixed Size Mode](dock-manager-customization.md#split-panes-fixed-size-mode) topic. - - -The end-user can perform the following actions to customize the layout at runtime: -- Pin/unpin a pane -- Resize a pane -- Close a pane -- Drag a pane to make it float -- Move a floating pane -- Dock a floating pane -- Maximize a pane - -All of these are reflected in the property of the Dock Manager. - -### Content Pane -The represents a pane with header and content. It can be hosted inside a Split Pane or a Tab Group Pane. Here is how a content pane is defined: - - -```ts -const contentPane: IgcContentPane = { - type: IgcDockManagerPaneType.contentPane, - contentId: 'content1', - header: 'Pane 1' -} -``` - - - -```tsx -const contentPane: IgrContentPane = { - type: IgrDockManagerPaneType.contentPane, - contentId: 'content1', - header: 'Pane 1' -} -``` - - -The property is used to provide a text header for the content pane. This text is rendered at several places: the top content pane header, the tab header if the pane is in a tab group and the unpinned header if the pane is unpinned. You can provide a custom slot content for each of these places respectively using the , and properties. If any of these properties is not set, the text is used. Here is how to provide a tab header slot content: - - ```html
Content 1
- Pane 1 Tab ``` - - -```ts -const contentPane: IgcContentPane = { - type: IgcDockManagerPaneType.contentPane, - contentId: 'content1', - header: 'Pane 1', - tabHeaderId: 'tabHeader1' -} -``` + ```tsx
Content 1
- Pane 1 Tab ``` - - -```tsx -const contentPane: IgrContentPane = { - type: IgrDockManagerPaneType.contentPane, - contentId: 'content1', - header: 'Pane 1', - tabHeaderId: 'tabHeader1' -} -``` -When a pane is unpinned, it appears as a tab header at one of the edges of the Dock Manager. If the end-user selects it, its content appears over the docked pinned panes. To unpin a content pane, set its property to **false**. +### Configure Content Panes + +Use content panes for the actual tools, views, and document surfaces inside the docked layout. + +The property provides the visible pane title. Use , , and when different header slot content is needed for the pane header, tab header, or unpinned header. + ```ts const contentPane = { type: IgcDockManagerPaneType.contentPane, contentId: 'content1', header: 'Pane 1', - isPinned: false -} + tabHeaderId: 'tabHeader1' +}; ``` + + ```tsx const contentPane = { type: IgrDockManagerPaneType.contentPane, contentId: 'content1', header: 'Pane 1', - isPinned: false -} + tabHeaderId: 'tabHeader1' +}; ``` - - -The property affects only content panes that are docked outside a document host. Also, content panes hosted in a floating pane cannot be unpinned. -By default, the unpin destination for a content pane is calculated automatically based on the location of the pane relative to the document host. When more than one document host is defined, the nearest one in the parent hierarchy of the unpinned content pane will be used. If there is no document host defined, the default location is used - `Left`. It is also possible to set the desired destination of the unpinned pane by using the property. + -You can configure which end-user operations are allowed for a content pane using its , , and properties. +Use to unpin a pane, to choose its edge, and the `allowClose`, `allowPinning`, `allowDocking`, `allowFloating`, `documentOnly`, `disabled`, and `hidden` properties to control runtime behavior for each pane. -When defining a content pane, you can set the property to true so the pane can be docked only in a document host. +### Arrange Panes with Split and Tab Groups -To restrict the user interaction with the content pane and its content, you can set the property to true. This will prevent all user interactions with the pane unless it is a single floating pane. The latter could be moved, maximized or closed (according to the pane's settings for maximizing and closing), so the user can have a look at the elements under it but will not be able to interact with its content. +Use split panes to divide space horizontally or vertically, and use tab groups when multiple content panes should share the same area as tabs. -By default, when you close a pane it gets removed from the object. However, in some cases you would want to temporary hide the pane and show it later again. In order to do that without changing the object you can use the property of the content pane. Setting the property to **true** will hide it from the UI, but it will remain in the object. In order to override the default close behavior you can subscribe to the `PaneClose` event like this: +Each pane type has a property. The size is relative to sibling panes unless the parent split pane uses fixed sizing. -```ts -this.dockManager.addEventListener('paneClose', ev => { - for (const pane of ev.detail.panes) { - pane.hidden = true; - } - ev.preventDefault(); -}); -``` - - - -```tsx -this.dockManager.addEventListener('paneClose', ev => { - for (const pane of ev.detail.panes) { - pane.hidden = true; - } - ev.preventDefault(); -}); -``` - -### Split Pane - -The is a container pane which stacks all of its child horizontally or vertically based on its property. Here is how a horizontal split pane with two child content panes is defined: - - ```ts -const splitPane: IgcSplitPane = { +const splitPane = { type: IgcDockManagerPaneType.splitPane, orientation: IgcSplitPaneOrientation.horizontal, panes: [ @@ -327,62 +275,52 @@ const splitPane: IgcSplitPane = { header: 'Pane 2' } ] -} +}; ``` - - -```tsx -const splitPane: IgrSplitPane = { - type: IgrDockManagerPaneType.splitPane, - orientation: IgrSplitPaneOrientation.horizontal, +```ts +const tabGroupPane = { + type: IgcDockManagerPaneType.tabGroupPane, panes: [ { - type: IgrDockManagerPaneType.contentPane, + type: IgcDockManagerPaneType.contentPane, contentId: 'content1', header: 'Pane 1' }, { - type: IgrDockManagerPaneType.contentPane, + type: IgcDockManagerPaneType.contentPane, contentId: 'content2', header: 'Pane 2' } ] -} +}; ``` - -The split pane may contain child panes of all pane types including other split panes. - -By default, if the split pane is empty it is not displayed. Yet if you would like to change that behavior you can set its property to true and the split pane will be presented in the UI even when there is no panes inside it. - -### Tab Group Pane + -The displays its child content as the tabs of a tab component. Here is how a tab group pane with a content pane for each of its two tabs is defined: + - -```ts -const tabGroupPane: IgcTabGroupPane = { - type: IgcDockManagerPaneType.tabGroupPane, +```tsx +const splitPane = { + type: IgrDockManagerPaneType.splitPane, + orientation: IgrSplitPaneOrientation.horizontal, panes: [ { - type: IgcDockManagerPaneType.contentPane, + type: IgrDockManagerPaneType.contentPane, contentId: 'content1', header: 'Pane 1' }, { - type: IgcDockManagerPaneType.contentPane, + type: IgrDockManagerPaneType.contentPane, contentId: 'content2', header: 'Pane 2' } ] -} +}; ``` - - ```tsx -const tabGroupPane: IgrTabGroupPane = { +const tabGroupPane = { type: IgrDockManagerPaneType.tabGroupPane, panes: [ { @@ -396,23 +334,21 @@ const tabGroupPane: IgrTabGroupPane = { header: 'Pane 2' } ] -} +}; ``` - -If there is not enough space to display all tab headers, the tab group shows **More tabs** menu, which contains the non-visible tabs. If you click a tab item in that menu, the tab gets selected and moved to the first position. - -The tabs also can be reordered without being detached from the tab group in which they are located. You can click on a tab of your choice and drag it left or right to the position you want it to be. If you drag the selected tab outside of the tabs area it will be detached into a floating pane. + -In case you would like the tab group pane to be displayed in the UI when it has no tabs, you can set the property to true. +Set when an empty split or tab group should still remain visible in the UI. -### Document Host +### Add a Document Host -The is an area of tabs for documents, similar to the one in Visual Studio for code editing and design view. Here is how to define a document host with two document tabs: +Use a document host when the workspace needs a dedicated tabbed document region similar to an IDE editor surface. + ```ts -const docHost: IgcDocumentHost = { +const docHost = { type: IgcDockManagerPaneType.documentHost, rootPane: { type: IgcDockManagerPaneType.splitPane, @@ -429,19 +365,21 @@ const docHost: IgcDocumentHost = { { type: IgcDockManagerPaneType.contentPane, contentId: 'content4', - header: "List" + header: 'List' } ] } ] } -} +}; ``` + + ```tsx -const docHost: IgrDocumentHost = { +const docHost = { type: IgrDockManagerPaneType.documentHost, rootPane: { type: IgrDockManagerPaneType.splitPane, @@ -458,23 +396,27 @@ const docHost: IgrDocumentHost = { { type: IgrDockManagerPaneType.contentPane, contentId: 'content4', - header: "List" + header: 'List' } ] } ] } -} +}; ``` + -### Floating Pane +### Add Floating Panes + +Use floating panes when a view should open in a detached window above the main docked layout. -The floating pane is a split pane rendered above all other ones in a floating window. The floating pane definitions are stored in the property of the . Here is how to add a floating pane with a single content pane inside: +Floating pane definitions are stored in . + ```ts -const layout: IgcDockManagerLayout = { +const layout = { rootPane: { // ... }, @@ -497,11 +439,13 @@ const layout: IgcDockManagerLayout = { ] }; ``` + + ```tsx -const layout: IgrDockManagerLayout = { +const layout = { rootPane: { // ... }, @@ -524,119 +468,49 @@ const layout: IgrDockManagerLayout = { ] }; ``` - - -The , and properties represent absolute dimensions in pixels. Please note that these properties are applied only for the split panes in the array. - -With the and - you can set whether resizing floating panes is allowed. The `allowFloatingPanesResize` is an **IgcDockManagerComponent** property, so if the value is set to **false** none of the floating panes can be resized. The `floatingResizable` property can be applied separately on each split pane in the `floatingPanes` array and if the property value is not set, it defaults to the value of the `allowFloatingPanesResize` property. If the `floatingResizable` property is set for a specific pane, its value takes precedence over the `allowFloatingPanesResize` property value. - -### Active Pane - -The Dock Manager component highlights the content pane which contains the focus and exposes it in its property. You can programmatically change the active pane by setting the property. You can also listen for changes of the property by subscribing to the `ActivePaneChanged` event: - - -```ts -this.dockManager.addEventListener('activePaneChanged', ev => { - console.log(ev.detail.oldPane); - console.log(ev.detail.newPane); -}); -``` - - -```tsx -this.dockManager.addEventListener('activePaneChanged', ev => { - console.log(ev.detail.oldPane); - console.log(ev.detail.newPane); -}); -``` -### Docking - -When you start dragging a floating pane, different docking indicators will appear depending on the position of the dragged pane. There are four main types of docking - root docking, pane docking, document host docking and splitter docking. Edge docking is available as an additional behavior when root docking is disabled and works along the orientation of the root split pane. - -#### Root Docking - -In this type of docking while dragging a pane, four arrow docking indicators will appear close to the four edges of the dock manager. Once released, the dragged pane will become a direct child of the Dock Manager's . Visually, the newly docked pane will snap into place at the respective edge and occupy up to half of the dock manager's width or height, shifting all the other content to the other half. - -dockmanager-root-docking - -#### Pane Docking - -Docking indicators will appear in the center of a content pane or a tab group pane when dragging the floating pane over it. Once released, the dragged pane will snap into place on any side of the target pane or get grouped together with the target pane to create a tabbed layout. Based on the combination of the initial layout and the dock position, the docking operation may cause the dynamic creation of a new split or tab group pane that would become the new parent of both the dragged and the target panes. - -dockmanager-pane-docking - -#### Document Host Docking - -If the dragged pane is over a document host, then additional docking indicators will appear that will allow for docking relative to the target pane or the whole document host. - -dockmanager-document-host-docking - -#### Splitter Docking - -Splitter docking lets your end-users place panes with precision inside an existing split layout. While dragging a floating pane, if the cursor moves close to any splitter between two panes, a docking indicator will appear over that splitter. - -When the user drops the pane over this indicator, the dock manager inserts the pane into the split pane that owns the targeted splitter, adjusting the neighboring panes to make room. This makes it easy to refine complex layouts by inserting new tools or views exactly between two existing panes, without having to restructure the entire layout. - -If your scenario requires a simpler experience without this level of precision, splitter docking can be disabled by setting the Dock Manager `allowSplitterDock` property to **false**. - -dockmanager-splitter-docking - -#### Edge Docking +Use , , and for absolute floating pane dimensions in pixels. Use and to control whether floating panes can be resized. -Edge docking gives your end-users a simple way to add important panes at the very beginning or at the very end of their main layout, without having to carefully target a specific splitter or pane. Once root docking is disabled by setting the `allowRootDock` property to **false**, the dock manager automatically enables edge docking indicators along the first and last positions of the root split pane. Since the root split pane is either horizontal or vertical, edge docking is available only in that single direction (left/right for a horizontal root or top/bottom for a vertical root). +### Configure Docking Behavior -This behavior is especially useful when the root pane is scrollable (when its `useFixedSize` property is set to **true** and the content extends beyond the visible area). In these scenarios, users can: +Dock Manager lets end users pin, unpin, resize, close, float, move, dock, and maximize panes at runtime, and those changes are reflected in the object. -- For a **horizontal** root split pane, drag any pane towards the **left** edge to dock it as the first item, or towards the **right** edge to dock it as the last item. -- For a **vertical** root split pane, drag any pane towards the **top** edge to dock it as the first item, or towards the **bottom** edge to dock it as the last item. +Set `allowRootDock` to `false` to disable root docking and enable edge docking. Set `allowSplitterDock` to `false` when the layout should not allow precise splitter insertion while dragging a pane. -When the user drops the pane over the edge docking indicator, the dock manager inserts the pane at the chosen edge and automatically scrolls it into view. This ensures that newly added tool windows or dashboards are immediately visible, even in complex, scrollable layouts. +### Update the Layout at Runtime -dockmanager-edge-docking - -### Update Layout - -In some scenarios you may need to customize the layout of the Dock Manager by adding or removing a pane, changing orientation, etc., for example: +Mutate the layout object when you need to add, remove, or rearrange panes programmatically, then reassign the layout object so the UI reflects the changes. + ```ts -const splitPane = this.dockManager.layout.rootPane.panes[0] as IgcSplitPane; -const contentPane = splitPane.panes[0] as IgcContentPane; +const splitPane = this.dockManager.layout.rootPane.panes[0]; +const contentPane = splitPane.panes[0]; this.dockManager.removePane(contentPane); +this.dockManager.layout = { ...this.dockManager.layout }; ``` + + ```tsx -const splitPane = this.dockManager.layout.rootPane.panes[0] as IgrSplitPane; -const contentPane = splitPane.panes[0] as IgrContentPane; +const splitPane = this.dockManager.layout.rootPane.panes[0]; +const contentPane = splitPane.panes[0]; this.dockManager.removePane(contentPane); -``` - - -This will only update the layout object. To trigger an update of the Dock Manager so the changes are reflected in the UI, the layout object should be re-assigned: - - -```ts this.dockManager.layout = { ...this.dockManager.layout }; ``` - - -```tsx -this.dockManager.layout = { ...this.dockManager.layout }; -``` -### Save/Load Layout +### Save and Restore Layouts -To restore or persist a layout, you simply have to get/set the value of the property. Here is how to save the layout as a stringified JSON: +Persist the current layout by serializing the property, then restore it by assigning the parsed object back to the dock manager. + ```ts private savedLayout: string; @@ -647,11 +521,12 @@ private saveLayout() { private loadLayout() { this.dockManager.layout = JSON.parse(this.savedLayout); } - ``` + + ```tsx private savedLayout: string; @@ -666,181 +541,131 @@ private loadLayout() { - -### Adding Panes At Runtime - -Contents and panes can be added to the at runtime. In the example below, you can see how you can add content, document and floating panes. - - - +### Add Panes at Runtime +Add new content, document, or floating panes dynamically when the workspace grows in response to user actions. + -
- - -### Events - -The Dock Manager component raises events when specific end-user interactions are performed for example closing, pinning, resizing and dragging a pane. You can find the full list of Dock Manager events in this [topic]({environment:infragisticsBaseUrl}/products/ignite-ui/dock-manager/docs/typescript/latest/interfaces/igcdockmanagereventmap.html). - - - +### Handle Pane Events +Use dock manager events when your app needs to intercept pane actions such as closing, pinning, resizing, dragging, or active-pane changes. -
- - - - - - Here is how to add an event listener for the `PaneClose` event: +The existing topic verifies `paneClose` and `activePaneChanged` examples. [VERIFY: complete generated event surface and exact event reference topic] + ```ts this.dockManager.addEventListener('paneClose', ev => console.log(ev.detail)); ``` - - - - -
- - - - - - +```ts +this.dockManager.addEventListener('activePaneChanged', ev => { + console.log(ev.detail.oldPane); + console.log(ev.detail.newPane); +}); +``` + + +```tsx +this.dockManager.addEventListener('activePaneChanged', ev => { + console.log(ev.detail.oldPane); + console.log(ev.detail.newPane); +}); +``` + -
- -## Customization +### Localize Strings -The Dock Manager component provides the option to customize all buttons using slots and parts. To change any of the buttons you simply have to define your own element inside the Dock Manager and set the slot attribute to the corresponding identifier. +Localize the strings used for context menus, tooltips, and ARIA attributes with either registered language bundles or per-instance resource strings. -Let's utilize these slots and parts to create a customized Dock Manager layout. First, we will provide our own icons, using the `closeButton`, `maximizeButton`, `minimizeButton`, `pinButton` and `unpinButton` slots: +Dock Manager reads the page `lang` attribute by default and falls back to English when the language is missing or unsupported. -```html - -
Content 1
-
Content 2
-
Content 3
- - - +```ts +import { registerI18n } from 'igniteui-i18n-core'; +import { DockManagerResourceStringsES } from 'igniteui-i18n-resources'; - +registerI18n(DockManagerResourceStringsES, 'es'); +``` - +```ts +import { addResourceStrings } from 'igniteui-dockmanager'; - +const dockManagerStringsFr: IgcDockManagerResourceStrings = { + close: 'Fermer', + // ... +}; - - +addResourceStrings('fr', dockManagerStringsFr); ``` - +Use the property when you want to override strings directly for a specific dock manager instance. -```tsx - -
Content 1
-
Content 2
-
Content 3
- {/* ... */} +## Best Practices - +Use Dock Manager for intentional workspaces where end-user layout control is a feature, not incidental complexity. - +- Keep pane headers concise so floating windows, tabs, and unpinned headers remain easy to scan. +- Use a document host for document-like surfaces and reserve content panes outside it for supporting tools and navigation. +- Persist user-customized layouts when the same workspace is expected across sessions. +- Disable docking modes your app does not need so the drag-and-drop experience stays understandable. +- Give slotted content a predictable width and height so resizing panes does not produce clipped or collapsed content. - +## Properties - +Use the generated API reference for the full surface; the rows below mark the core options covered on this page. - - -``` +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `layout` | build-generated | build-generated | Build injects verified core dock manager properties here from the typed API source. | +| `allowFloatingPanesResize` | build-generated | build-generated | Build injects verified core dock manager properties here from the typed API source. | +| `allowRootDock` | build-generated | build-generated | Build injects verified core dock manager properties here from the typed API source. | +| `allowSplitterDock` | build-generated | build-generated | Build injects verified core dock manager properties here from the typed API source. | +| `resourceStrings` | build-generated | build-generated | Build injects verified core dock manager properties here from the typed API source. | +| `isPinned` | build-generated | build-generated | Build injects verified core content pane properties here from the typed API source. | +| `hidden` | build-generated | build-generated | Build injects verified core content pane properties here from the typed API source. | +| `size` | build-generated | build-generated | Build injects verified pane sizing properties here from the typed API source. | - +## Methods -Then, we will use the exposed parts in our stylesheet. This way we have full control of the component's styling: +Use dock manager methods when you need to update or extend the pane layout from code. -```css -igc-dockmanager::part(unpinned-tab-area) { - background: #bee9ec; -} +| Name | Description | +| -- | -- | +| `removePane` | Removes a pane from the current layout object. | +| `addResourceStrings` | Registers translated dock manager resource strings. | -igc-dockmanager::part(unpinned-tab-area--left) { - border-right: 1px dashed #004d7a; -} +## Events -igc-dockmanager::part(unpinned-tab-area--bottom) { - border-top: 1px dashed #004d7a; -} +Use dock manager events when your app needs to react to user-driven pane changes. -igc-dockmanager::part(tab-header-close-button), -igc-dockmanager::part(pane-header-close-button) { - background-color: #e73c7e; -} - -igc-dockmanager::part(pane-header-pin-button), -igc-dockmanager::part(pane-header-unpin-button) { - background: rgb(218, 218, 218); - border: none; - width: 24px; - height: 24px; - color: #fff; -} +| Name | Description | +| -- | -- | +| `paneClose` | Fires when panes are being closed and can be intercepted. | +| `activePaneChanged` | Fires when the active pane changes. | -igc-dockmanager::part(tabs-maximize-button), -igc-dockmanager::part(tabs-minimize-button), -igc-dockmanager::part(pane-header-minimize-button), -igc-dockmanager::part(pane-header-maximize-button) { - width: 24px; - height: 24px; - border: none; - transition: opacity 250ms ease-in-out; - opacity: 0.3; - margin-right: 15px; - margin-top: -5px; - margin-left: 0px; -} -``` +## Styling -If everything went well, we should now have a DockManager with customized icons and tab area. Let's have a look at it: +Use CSS parts, slots, and theme variables to customize dock manager headers, buttons, docking affordances, splitters, and floating windows. - + +### Slots -Below you can find a list containing the slot names for all of the buttons as well as the splitter handle: +Use the following slots to replace built-in buttons or the splitter handle: | Slot name | Description | -| ----------|------------ | +| -- | -- | | `closeButton` | The close buttons. | | `paneHeaderCloseButton` | The close buttons of the pane headers. | | `tabHeaderCloseButton` | The close buttons of the tab headers. | @@ -852,133 +677,74 @@ Below you can find a list containing the slot names for all of the buttons as we | `unpinButton` | The unpin buttons. | | `splitterHandle` | The splitter handle. | -You can find each slot's corresponding part in the **CSS Parts** under **Styling** section of this page. - -### CSS Variables - -The following table describes all CSS variables used for styling the dock-manager component: - -| CSS variable | Description | -| -------------------- | ------------------------------------------------------------------------------- | -| `--igc-background-color` | The background color of the header inside the pane navigator component. | -| `--igc-accent-color` | The background color of the buttons inside the pane header actions part on focus. | -| `--igc-active-color` | The text and box-shadow color used for the components in active state. | -| `--igc-border-color` | The border bottom color of the pane header component. | -| `--igc-font-family` | The font-family of the dock-manager component. | -| `--igc-dock-background` | The background color of the dock-manager, tab and floating-pane components. | -| `--igc-dock-text` | The text color of the dock-manager and the floating pane components. | -| `--igc-pane-header-background` | The background color of the pane header component. | -| `--igc-pane-header-text` | The text color of the pane header component. | -| `--igc-pane-content-background` | The background color of the content inside the dock-manager and the tab panel components. | -| `--igc-pane-content-text` | The text color of the content inside the dock-manager and the tab panel components. | -| `--igc-tab-text` | The text color of the tab header component. | -| `--igc-tab-background` | The background color of the tab header component. | -| `--igc-tab-border-color` | The border color of the tab header component. | -| `--igc-tab-text-active` | The text color of the selected tab header component. | -| `--igc-tab-background-active` | The background color of the selected tab header component. | -| `--igc-tab-border-color-active` | The border color of the selected tab header component. | -| `--igc-pinned-header-background` | The background color of the unpinned pane header component. | -| `--igc-pinned-header-text` | The text color of the unpinned pane header component. | -| `--igc-splitter-background` | The background color of the splitter component. | -| `--igc-splitter-handle` | The background color of the splitter handle. | -| `--igc-button-text` | The color of the buttons inside the pane header actions part. | -| `--igc-flyout-shadow-color` | The box-shadow color of the content pane component. | -| `--igc-joystick-background` | The background color of the joystick and the root docking indicator components. | -| `--igc-joystick-border-color` | The border color of the joystick and the root docking indicator components. | -| `--igc-joystick-icon-color` | The icon color of the joystick and the root docking indicator components. | -| `--igc-joystick-background-active` | The hover background color of the joystick and the root docking indicator components. | -| `--igc-joystick-icon-color-active` | The hover icon color of the joystick and the root docking indicator components. | -| `--igc-floating-pane-border-color` | The border color of the floating panes. | -| `--igc-context-menu-background` | The background color of the context menu items. | -| `--igc-context-menu-background-active` | The background color of the context menu items on hover and focus. | -| `--igc-context-menu-color` | The text color of the context menu items. | -| `--igc-context-menu-color-active` | The text color of the context menu items on hover and focus. | -| `--igc-drop-shadow-background` | The background color of the drop shadow. | -| `--igc-disabled-color` | The text color of the components in disabled state. | - -## Keyboard Navigation - -Keyboard navigation enhances the accessibility of the **Dock Manager** and provides a rich variety of interactions to the end-user like navigating through all panes, splitting the view in multiple directions through docking the active pane, etc. - - -The shortcuts are as follows: - -### Docking - -- CMD/CTRL + SHIFT + ↑ Docks to global top -- CMD/CTRL + SHIFT + ↓ Docks to global bottom -- CMD/CTRL + SHIFT + → Docks to global right -- CMD/CTRL + SHIFT + ← Docks to global left -- SHIFT + ↑ With multiple tabs in a tab group splits the view and docks the focused tab above -- SHIFT + ↓ With multiple tabs in a tab group splits the view and docks the focused tab below -- SHIFT + → With multiple tabs in a tab group splits the view and docks the focused tab right -- SHIFT + ← With multiple tabs in a tab group splits the view and docks the focused tab left - -### Navigating -- CMD/CTRL + F6 or CMD/CTRL + → Focuses next tab in document host -- CMD/CTRL + SHIFT + F6 or CMD/CTRL + ← Focuses previous tab in document host -- ALT + F6 Focuses next content pane -- ALT + SHIFT + F6 Focuses previous content pane - -### Pane Navigator - -The following keyboard shortcuts show a navigator from which you can iterate through panes and documents. - -- CMD/CTRL + F7 or CMD/CTRL + F8 Starts from the first document forward -- ALT + F7 or ALT + F8 Starts from the first pane forward -- CMD/CTRL + SHIFT + F7 or CMD/CTRL + SHIFT + F8 Starts from the last document backwards -- ALT + SHIFT + F7 or ALT + SHIFT + F8 Starts from the last pane backwards - -### Other -- ALT + F3 Closes the active pane - -Practice all of the above mentioned actions in the sample [demo](dock-manager.md#{PlatformLower}-dock-manager-example). - -## Styling - -The Dock Manager uses a shadow DOM to encapsulate his styles and behaviors. As a result, you can't simply target its internal elements with the usual CSS selectors. That is why we expose components **parts** that can be targeted with the **::part** CSS selector. - -```css -igc-dockmanager::part(content-pane) { - border-radius: 10px; -} -``` - -In the following example, we demonstrate the ability of customizing the Dock Manager through some of the CSS parts that we've exposed. - - - - - - -
+ + +### Styling Variables + +| Variable | What it changes | +| -- | -- | +| `--igc-background-color` | The background color of the header inside the pane navigator component. | +| `--igc-accent-color` | The background color of focused buttons inside the pane header actions area. | +| `--igc-active-color` | The text and box-shadow color used in active state. | +| `--igc-border-color` | The border-bottom color of the pane header component. | +| `--igc-font-family` | The font family of the dock manager. | +| `--igc-dock-background` | The background color of the dock manager, tab, and floating pane surfaces. | +| `--igc-dock-text` | The text color of the dock manager and floating panes. | +| `--igc-pane-header-background` | The background color of pane headers. | +| `--igc-pane-header-text` | The text color of pane headers. | +| `--igc-pane-content-background` | The background color of pane content and tab panels. | +| `--igc-pane-content-text` | The text color of pane content and tab panels. | +| `--igc-tab-text` | The text color of tab headers. | +| `--igc-tab-background` | The background color of tab headers. | +| `--igc-tab-border-color` | The border color of tab headers. | +| `--igc-tab-text-active` | The text color of the selected tab header. | +| `--igc-tab-background-active` | The background color of the selected tab header. | +| `--igc-tab-border-color-active` | The border color of the selected tab header. | +| `--igc-pinned-header-background` | The background color of the unpinned pane header. | +| `--igc-pinned-header-text` | The text color of the unpinned pane header. | +| `--igc-splitter-background` | The background color of the splitter component. | +| `--igc-splitter-handle` | The background color of the splitter handle. | +| `--igc-button-text` | The color of buttons inside the pane header actions area. | +| `--igc-flyout-shadow-color` | The box-shadow color of the content pane component. | +| `--igc-joystick-background` | The background color of joystick and root docking indicators. | +| `--igc-joystick-border-color` | The border color of joystick and root docking indicators. | +| `--igc-joystick-icon-color` | The icon color of joystick and root docking indicators. | +| `--igc-joystick-background-active` | The hover background color of joystick and root docking indicators. | +| `--igc-joystick-icon-color-active` | The hover icon color of joystick and root docking indicators. | +| `--igc-floating-pane-border-color` | The border color of floating panes. | +| `--igc-context-menu-background` | The background color of context menu items. | +| `--igc-context-menu-background-active` | The background color of context menu items on hover and focus. | +| `--igc-context-menu-color` | The text color of context menu items. | +| `--igc-context-menu-color-active` | The text color of context menu items on hover and focus. | +| `--igc-drop-shadow-background` | The background color of the drop shadow. | +| `--igc-disabled-color` | The text color used in disabled state. | ### CSS Parts | Part name | Description | -| ---------|------------ | +| -- | -- | | `content-pane` | The content pane component. | -| `pane-header` | The content pane header component. | +| `pane-header` | The content pane header component. | | `pane-header-content` | The content area of the content pane header. | | `pane-header-actions` | The actions area of the content pane header. | -| `active` | Indicates an active state. Applies to `pane-header`, `pane-header-content`, `pane-header-actions`, `tab-header`. | -| `floating` | Indicates a floating pane placement. Applies to `pane-header`, `pane-header-content`, `pane-header-actions`. | -| `window` | Indicates a floating window placement. Applies to `pane-header`, `pane-header-content`, `pane-header-actions`. | +| `active` | Indicates an active state for pane headers and tab headers. | +| `floating` | Indicates a floating pane placement. | +| `window` | Indicates a floating window placement. | | `split-pane` | The split pane component. | | `splitter` | The resizing splitter component. | | `splitter-base` | The base element of the splitter component. | -| `splitter-ghost`| The ghost element of the splitter component. | +| `splitter-ghost` | The ghost element of the splitter component. | | `unpinned-pane-header` | The unpinned pane header component. | | `tab-header` | The tab header component. | | `tab-header-more-options-button` | The more options button in the tab header. | | `tab-header-close-button` | The close button in the tab header. | -| `selected` | Indicates a selected state. Applies to `tab-header` and `tab-header-close-button`. | -| `hovered` | Indicates a hovered state. Applies to `tab-header-close-button`. | +| `selected` | Indicates a selected tab state. | +| `hovered` | Indicates a hovered tab close-button state. | | `header-title` | The text title of the tab header. | | `tab-strip-area` | The tab strip area containing the tab headers. | | `tab-strip-actions` | The tab strip area containing the tab actions. | -| `top` | Indicates a top tabs position. Applies to `tab-header`, `tab-strip-area`, `tab-strip-actions`. | -| `bottom` | Indicates a bottom tabs position. Applies to `tab-header`, `tab-strip-area`, `tab-strip-actions`. | +| `top` | Indicates a top tab-strip position. | +| `bottom` | Indicates a bottom tab-strip position. | | `context-menu` | The context menu component. | | `context-menu-item` | An item in the context menu component. | | `docking-preview` | The docking preview area. | @@ -988,8 +754,8 @@ In the following example, we demonstrate the ability of customizing the Dock Man | `pane-navigator` | The pane navigator component. | | `pane-navigator-header` | The header area of the pane navigator. | | `pane-navigator-body` | The body area of the pane navigator. | -| `pane-navigator-items-group` | An items group in the pane navigator component. | -| `pane-navigator-items-group-title` | The title element of an items group in the pane navigator. | +| `pane-navigator-items-group` | An items group in the pane navigator. | +| `pane-navigator-items-group-title` | The title element of a pane navigator group. | | `pane-navigator-item` | An item in the pane navigator. | | `pane-header-close-button` | The close button in the pane header. | | `pane-header-maximize-button` | The maximize button in the pane header. | @@ -1002,19 +768,57 @@ In the following example, we demonstrate the ability of customizing the Dock Man | `context-menu-unpin-button` | The unpin button in the context menu. | | `context-menu-close-button` | The close button in the context menu. | | `splitter-handle` | The splitter handle. | -| `horizontal` | Indicates a horizontal position. Applies to `splitter-handle`. | -| `vertical` | Indicates a vertical position. Applies to `splitter-handle`. | +| `horizontal` | Indicates a horizontal splitter-handle position. | +| `vertical` | Indicates a vertical splitter-handle position. | +```css +igc-dockmanager::part(unpinned-tab-area) { + background: #bee9ec; +} - +igc-dockmanager::part(unpinned-tab-area--left) { + border-right: 1px dashed #004d7a; +} +igc-dockmanager::part(unpinned-tab-area--bottom) { + border-top: 1px dashed #004d7a; +} + +igc-dockmanager::part(tab-header-close-button), +igc-dockmanager::part(pane-header-close-button) { + background-color: #e73c7e; +} +igc-dockmanager::part(pane-header-pin-button), +igc-dockmanager::part(pane-header-unpin-button) { + background: rgb(218, 218, 218); + border: none; + width: 24px; + height: 24px; + color: #fff; +} + +igc-dockmanager::part(tabs-maximize-button), +igc-dockmanager::part(tabs-minimize-button), +igc-dockmanager::part(pane-header-minimize-button), +igc-dockmanager::part(pane-header-maximize-button) { + width: 24px; + height: 24px; + border: none; + transition: opacity 250ms ease-in-out; + opacity: 0.3; + margin-right: 15px; + margin-top: -5px; + margin-left: 0px; +} +``` ### Themes -The Dock Manager comes with a light and a dark theme. The light theme is the default one. To change it to dark, you only need to import the **igc.themes.css** file in your css and add the **dark-theme** class to the Dock Manager or any of its parents: +Dock Manager ships with light and dark themes. + ```scss @import '~igniteui-dockmanager/dist/collection/styles/igc.themes'; ``` @@ -1026,6 +830,7 @@ The Dock Manager comes with a light and a dark theme. The light theme is the def + ```scss @import 'igniteui-dockmanager/dist/collection/styles/igc.themes'; ``` @@ -1036,48 +841,70 @@ The Dock Manager comes with a light and a dark theme. The light theme is the def +## Accessibility -## Localization +Dock Manager supports extensive keyboard-driven pane navigation and docking, but accessibility documentation for pane semantics, announcements, and conformance should stay explicit because this component manages a complex workspace model. -The Dock Manager lets you localize the strings used in context menus, tooltips, and ARIA attributes. By default, it reads the [lang](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) attribute from the root `` element to determine which language to use. If the [lang](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) attribute is missing or set to an unsupported value, the Dock Manager uses [English (en)]({environment:infragisticsBaseUrl}/products/ignite-ui/dock-manager/docs/typescript/latest/index.html#IgcDockManagerResourceStringsEN). +### Keyboard Interaction - -Ready-to-use Dock Manager resource strings for Spanish (`es`), Japanese (`ja`), and Korean (`ko`) are provided via the `igniteui-i18n-resources` peer dependency. To use one of these languages, install `igniteui-i18n-resources` and register the corresponding bundle with `igniteui-i18n-core`: +Use the following keyboard shortcuts to navigate panes, move documents, and close the active pane. -```ts -import { registerI18n } from 'igniteui-i18n-core'; -import { DockManagerResourceStringsES } from 'igniteui-i18n-resources'; +| Key | Action | +| -- | -- | +| Cmd/Ctrl + Shift + Up Arrow | Docks to the global top. | +| Cmd/Ctrl + Shift + Down Arrow | Docks to the global bottom. | +| Cmd/Ctrl + Shift + Right Arrow | Docks to the global right. | +| Cmd/Ctrl + Shift + Left Arrow | Docks to the global left. | +| Shift + Up Arrow | With multiple tabs in a tab group, splits the view and docks the focused tab above. | +| Shift + Down Arrow | With multiple tabs in a tab group, splits the view and docks the focused tab below. | +| Shift + Right Arrow | With multiple tabs in a tab group, splits the view and docks the focused tab right. | +| Shift + Left Arrow | With multiple tabs in a tab group, splits the view and docks the focused tab left. | +| Cmd/Ctrl + F6 or Cmd/Ctrl + Right Arrow | Focuses the next tab in the document host. | +| Cmd/Ctrl + Shift + F6 or Cmd/Ctrl + Left Arrow | Focuses the previous tab in the document host. | +| Alt + F6 | Focuses the next content pane. | +| Alt + Shift + F6 | Focuses the previous content pane. | +| Cmd/Ctrl + F7 or Cmd/Ctrl + F8 | Starts pane navigation from the first document forward. | +| Alt + F7 or Alt + F8 | Starts pane navigation from the first pane forward. | +| Cmd/Ctrl + Shift + F7 or Cmd/Ctrl + Shift + F8 | Starts pane navigation from the last document backward. | +| Alt + Shift + F7 or Alt + Shift + F8 | Starts pane navigation from the last pane backward. | +| Alt + F3 | Closes the active pane. | -registerI18n(DockManagerResourceStringsES, 'es'); -``` +### Screen Readers / ARIA -If you need to support a different language, use the [addResourceStrings]({environment:infragisticsBaseUrl}/products/ignite-ui/dock-manager/docs/typescript/latest/index.html#addResourceStrings) method to provide your own translated strings: +[VERIFY: screen reader roles, aria attributes, pane announcements, and localized accessible names for Dock Manager] -```ts -import { addResourceStrings } from 'igniteui-dockmanager'; +### Accessibility Compliance -const dockManagerStringsFr: IgcDockManagerResourceStrings = { - close: 'Fermer', - // ... -}; +[VERIFY: official accessibility conformance target for the Dock Manager component] -addResourceStrings('fr', dockManagerStringsFr); -``` +| Criterion | How the component complies | +| -- | -- | +| [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships) | [VERIFY: semantic structure of document hosts, tab groups, panes, and pane headers] | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | Dock Manager exposes a broad keyboard shortcut model for docking, pane navigation, and pane closing. | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order) | [VERIFY: predictable focus movement across pane headers, tab headers, navigator items, and pane content] | +| [2.5.7 Dragging Movements](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements) | Keyboard docking and navigation shortcuts provide non-drag interaction paths for layout changes. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value) | [VERIFY: semantic exposure of panes, tabs, context menus, and active states] | - +Your responsibilities: -The Dock Manager also exposes a property that you can use to modify individual strings directly. When you set the property, the Dock Manager uses the strings you provide regardless of the [lang](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) attribute on the page. +- Provide clear pane headers so users can identify panes in docked, tabbed, floating, and unpinned states. +- Preserve accessible names when replacing built-in buttons through slots. +- Validate focus visibility and color contrast after restyling pane headers, tabs, splitters, and docking indicators. +## API References - + + + + + + +## Dependencies -## API References +Dock Manager depends on the `igniteui-dockmanager` package. Localization bundles can additionally use `igniteui-i18n-core` and `igniteui-i18n-resources`, and theme switching uses the dock manager theme stylesheet. +## Additional Resources -
-
-
-
-
-
+- [`Dock Manager Customization`](./dock-manager-customization.md) +- [{ProductName} **GitHub**]({GithubLink}) diff --git a/docs/xplat/src/content/en/components/layouts/expansion-panel.mdx b/docs/xplat/src/content/en/components/layouts/expansion-panel.mdx index 2eec4c0a6f..fbe816c24f 100644 --- a/docs/xplat/src/content/en/components/layouts/expansion-panel.mdx +++ b/docs/xplat/src/content/en/components/layouts/expansion-panel.mdx @@ -1,56 +1,55 @@ --- -title: "{Platform} Expansion Panel | Expansion Panel | Infragistics" -description: Expansion Panel component provides an easily configurable expandable component with two states - collapsed and expanded. -keywords: "{Platform} Expansion Panel, {ProductName}, Infragistics" +title: "{Platform} Expansion Panel Component | Layouts | Infragistics" +description: "{Platform} Expansion Panel is an expandable container for showing or hiding related content in a collapsible section." +keywords: "{Platform} Expansion Panel, expansion panel component, collapsible panel, {ProductName}, Infragistics" license: MIT mentionedTypes: ["Infragistics.Controls.Layouts.Implementation.ExpansionPanel"] namespace: Infragistics.Controls +relatedComponents: ["Accordion"] llms: - description: "The {ProductName} Expansion Panel is a lightweight accordion component which can be rendered in two states - collapsed or expanded." + description: "The {ProductName} Expansion Panel is an expandable container for showing or hiding related content in a collapsible section." --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Expansion Panel Overview +# Expansion Panel Component -The {ProductName} Expansion Panel is a lightweight accordion component which can be rendered in two states - collapsed or expanded. The expansion panel can be toggled using mouse click, or keyboard interactions. +The {ProductName} Expansion Panel is an expandable container for showing or hiding related content in a collapsible section. -## {Platform} Expansion Panel Example +## Overview - +The expansion panel reveals content on demand and keeps the surrounding layout compact until the user opens the panel. -## Usage +### When to Use - +Use the expansion panel when you need a single collapsible section for optional details, settings, filters, or grouped content that users open only when needed. -First, you need to install the {ProductName} by running the following command: +### When Not to Use -```cmd -npm install {PackageWebComponents} -``` +Use the [Accordion](./accordion.md) when you need a container that coordinates multiple related expansion panels instead of a single standalone collapsible section. + + + +## Getting Started + +Before you add the expansion panel, complete the shared {ProductName} setup in the [Getting Started](../general-getting-started.md) topic. + + -Before using the , you need to register it as follows: +Register the expansion panel component before you use it. ```ts -import {defineComponents, IgcExpansionPanelComponent} from 'igniteui-webcomponents'; +import { defineComponents, IgcExpansionPanelComponent } from 'igniteui-webcomponents'; defineComponents(IgcExpansionPanelComponent); ``` -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. - -First, you need to the install the corresponding {ProductName} npm package by running the following command: - -```cmd -npm install igniteui-react -``` - -You will then need to import the , its necessary CSS, and register its module, like so: +Import the expansion panel wrapper and the theme stylesheet before you render the component. ```tsx import { IgrExpansionPanel } from 'igniteui-react'; @@ -59,7 +58,27 @@ import 'igniteui-webcomponents/themes/light/bootstrap.css'; -The simplest way to start using the is as follows: + + +Register the expansion panel module in `Program.cs`. + +[VERIFY: exact Blazor module registration symbol for the expansion panel] + +Add the theme stylesheet to your host page. + +```razor + +``` + + + +## Usage + +Render the expansion panel around a title, optional subtitle, and body content that users can reveal or collapse. + +### Declare a Panel + +Start with a single panel and place the title, subtitle, and body content inside the component. @@ -67,10 +86,11 @@ The simplest way to start using the Golden Retriever Medium-large gun dog -

The Golden Retriever is a medium-large gun dog that retrieves shot waterfowl, such as ducks - and upland game birds, during hunting and shooting parties.[3] The name "retriever" refers to the breed's ability - to retrieve shot game undamaged due to their soft mouth. Golden retrievers have an instinctive love of water, and - are easy to train to basic or advanced obedience standards.

+

+ The Golden Retriever is a medium-large gun dog that retrieves shot waterfowl, such as ducks + and upland game birds, during hunting and shooting parties.[3] The name "retriever" refers to + the breed's ability to retrieve shot game undamaged due to their soft mouth. +

``` @@ -84,84 +104,49 @@ The simplest way to start using the Medium-large gun dog The Golden Retriever is a medium-large gun dog that retrieves shot waterfowl, such as ducks - and upland game birds, during hunting and shooting parties.[3] The name retriever refers to the breeds ability - to retrieve shot game undamaged due to their soft mouth. Golden retrievers have an instinctive love of water, and - are easy to train to basic or advanced obedience standards. + and upland game birds, during hunting and shooting parties.[3] The name retriever refers to + the breeds ability to retrieve shot game undamaged due to their soft mouth. ``` -## Binding to events - -The Expansion Panel component raises the following events: - - - -- **igcClosed** - Raised when the expansion panel is collapsed -- **igcOpened** - Raised when the expansion panel is expanded -- **igcClosing** - Raised when the expansion panel starts collapsing -- **igcOpening** - Raised when the expansion panel starts expanding - - - - - -- **Closed** - Raised when the expansion panel is collapsed -- **Opened** - Raised when the expansion panel is expanded -- **Closing** - Raised when the expansion panel starts collapsing -- **Opening** - Raised when the expansion panel starts expanding - - - - - -- **Closed** - Raised when the expansion panel is collapsed -- **Opened** - Raised when the expansion panel is expanded -- **Closing** - Raised when the expansion panel starts collapsing -- **Opening** - Raised when the expansion panel starts expanding - - +### Respond to Open and Close Events -The following sample demonstrates how we can add some logic to our component to make it show/hide the `subtitle` depending on the current state of the panel. +Bind to the panel events when your app needs to react to expansion state changes. -We can do this by binding to the `igcOpened` and `igcClosed` event emitters: +Use the `igcOpened` and `igcClosed` event emitters to react after the panel state changes. -We can do this by binding to the `Opened` and `Closed` events: +Use the `Opened` and `Closed` events to react after the panel state changes. -We can do this by binding to the `Opened` and `Closed` events: +Use the `Opened` and `Closed` events to react after the panel state changes. - - -## Component Customization -The control allows all sorts of content to be added inside of its body. It can render [input](../inputs/input.md), charts and even other expansion panels! + -The allows for easy customization of the header through the exposed `title`, `subTitle` and `indicator` slots. +### Customize Header Content -Configuring the position of the expansion indicator can be done through the property of the Expansion Panel. The possible options are **start**, **end** or **none**. +Use the `title`, `subtitle`, and `indicator` slots to adjust how the panel header is rendered. -The next code sample demonstrates how to configure the component's button to go on the **right** side. +Set to place the indicator at the `start`, `end`, or hide it with `none`. - + -### Recommended Elements for Slots +### Choose Slot Content -When slotting content into the `title` and `subtitle` slots, we recommend using `` elements rather than heading elements (`

`–`

`). Heading elements carry built-in styling (such as font size, line height, and margins) that can interfere with the component's intended typography and layout. Using a `` gives you a neutral container that inherits the component's styles cleanly. - -The `indicator` slot is intended for icon-like content. We recommend using the [``](../layouts/icon.md) component for this purpose. Alternatively, if you don't want to use an icon for the indicator, a `` element can be used to display text, symbols, or emojis. +Use neutral inline elements in the header slots so the component controls the layout consistently. @@ -199,27 +184,49 @@ The `indicator` slot is intended for icon-like content. We recommend using the [ -## Keyboard Navigation +Use `` for `title` and `subtitle` content, and use [``](../layouts/icon.md) or another compact indicator element in the `indicator` slot. + +## Best Practices + +Use the expansion panel to progressively disclose supporting content, not to bury primary actions or critical information. + +- Keep the title concise so users can decide whether to open the panel before reading the body. +- Use the subtitle only when it adds useful context without repeating the title. +- Keep indicator content simple so the open and closed state remains clear. +- Avoid nesting too many interactive elements in the header area where users expect a straightforward toggle. -The {ProductName} Expansion Panel keyboard navigation is compliant with W3C accessibility standards and convenient to use. +## Properties -**Key Combinations** +Use the generated API reference for the complete surface; the rows below mark the core options covered on this page. -- ALT + ↓ - expands the focused panel -- ALT + ↑ - collapses the focused panel -- SPACE/ENTER - toggle the expansion state of the focused panel +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `indicatorPosition` | build-generated | build-generated | Build injects verified core expansion panel properties here from the typed API source. | + +## Events + +Use the panel events when you need to track opening and closing before or after the state changes. + +| Name | Description | +| -- | -- | +| `igcClosed` / `Closed` | Raised when the expansion panel is collapsed. | +| `igcOpened` / `Opened` | Raised when the expansion panel is expanded. | +| `igcClosing` / `Closing` | Raised when the expansion panel starts collapsing. | +| `igcOpening` / `Opening` | Raised when the expansion panel starts expanding. | ## Styling -The component exposes several CSS parts, giving you full control over its style: +Use CSS parts to style the header, text, indicator, and content areas of the panel. + + -|Name|Description| -|--|--| -| `header` | The container of the expansion indicator, title and subtitle. | +| CSS Part | Description | +| -- | -- | +| `header` | The container of the expansion indicator, title, and subtitle. | | `title` | The title container. | | `subtitle` | The subtitle container. | | `indicator` | The indicator container. | -| `content` | The expansion panel's content wrapper. | +| `content` | The expansion panel content wrapper. | ```css igc-expansion-panel { @@ -249,12 +256,43 @@ igc-expansion-panel::part(subtitle) { } ``` - +## Accessibility + +The expansion panel supports keyboard toggling and exposes a dedicated header area for announcing state and content grouping. + +### Keyboard Interaction + +Use the keyboard shortcuts below to open, close, or toggle the focused panel. + +| Key | Action | +| -- | -- | +| Alt + Down Arrow | Expands the focused panel. | +| Alt + Up Arrow | Collapses the focused panel. | +| Space / Enter | Toggles the expansion state of the focused panel. | - +### Screen Readers / ARIA + +[VERIFY: screen reader roles, aria attributes, and announcements for the expansion panel] + +### Accessibility Compliance + +[VERIFY: official accessibility conformance target for the expansion panel component] + +| Criterion | How the component complies | +| -- | -- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | The panel supports keyboard commands for expanding, collapsing, and toggling its state. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value) | [VERIFY: state and semantic exposure for the expansion panel header and content region] | + +Your responsibilities: + +- Provide clear header text that describes the content behind the disclosure area. +- Keep custom indicator visuals understandable without relying only on color. +- Validate contrast and focus visibility when you restyle the panel header or indicator. ## API References + + ## Additional Resources - [{ProductName} **Forums**]({ForumsLink}) diff --git a/docs/xplat/src/content/en/components/layouts/icon.mdx b/docs/xplat/src/content/en/components/layouts/icon.mdx index c488faebe4..1c64b1d4cc 100644 --- a/docs/xplat/src/content/en/components/layouts/icon.mdx +++ b/docs/xplat/src/content/en/components/layouts/icon.mdx @@ -1,66 +1,53 @@ --- -title: "{Platform} Icon Component | {ProductName}" -description: See how you can easily get started with {Platform} Icon Component. Choose icons and select from different styling options to customize them further. -keywords: "{ProductName}, UI controls, {Platform} widgets, web widgets, UI widgets, {Platform}, Native {Platform} Components Suite, Native {Platform} Controls, Native {Platform} Components Library, {Platform} Icon components, {Platform} Icon controls" +title: "{Platform} Icon Component | Layouts | Infragistics" +description: "{Platform} Icon is a display component for rendering registered SVG icons with configurable size, styling, and RTL mirroring." +keywords: "{Platform} Icon, icon component, SVG icons, {ProductName}, Infragistics" license: MIT mentionedTypes: ["Icon"] llms: - description: "The {Platform} Icon component allows you to easily display font or choose from a large set of predefined SVG icons, but it also gives you the ability to create custom font icons for your project." + description: "The {ProductName} Icon is a display component for rendering registered SVG icons with configurable size, styling, and RTL mirroring." --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +# Icon Component -# {Platform} Icon Overview +The {ProductName} Icon is a display component for rendering registered SVG icons with configurable size, styling, and RTL mirroring. -The {Platform} Icon component allows you to easily display font or choose from a large set of predefined SVG icons, but it also gives you the ability to create custom font icons for your project. Benefiting from a number of attributes, you can define or change the size of the icon in use or apply different styles to it. +## Overview -## {Platform} Icon Example +The icon component renders SVG icons from registered collections and gives you a lightweight way to control size, color, and direction-sensitive presentation. - +### When to Use -## Usage +Use the icon component when you need reusable visual symbols for actions, navigation, status, or compact labels across your UI. - +### When Not to Use -First, you need to install the {ProductName} by running the following command: +Do not use the icon component as the only source of meaning when users also need readable text, labels, or instructions to understand an action. -```cmd -npm install {PackageWebComponents} -``` - -```ts -import { defineComponents, IgcIconComponent } from "igniteui-webcomponents"; + -defineComponents(IgcIconComponent); -``` +## Getting Started -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. +Before you add the icon component, complete the shared {ProductName} setup in the [Getting Started](../general-getting-started.md) topic. - + -Before using the , you need to register it as follows: +Register the icon component before you use it. - - -```csharp -// in Program.cs file +```ts +import { defineComponents, IgcIconComponent } from 'igniteui-webcomponents'; -builder.Services.AddIgniteUIBlazor(typeof(IgbIconModule)); +defineComponents(IgcIconComponent); ``` -First, you need to the install the corresponding {ProductName} npm package by running the following command: - -```cmd -npm install igniteui-react -``` - -You will then need to import the , its necessary CSS, and register its module, like so: +Import the icon wrapper and the theme stylesheet before you render the component. ```tsx import { IgrIcon } from 'igniteui-react'; @@ -71,7 +58,13 @@ import 'igniteui-webcomponents/themes/light/bootstrap.css'; -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +Register the icon module in `Program.cs`. + +```csharp +builder.Services.AddIgniteUIBlazor(typeof(IgbIconModule)); +``` + +Add the theme stylesheet to your host page. ```razor @@ -79,38 +72,47 @@ You will also need to link an additional CSS file to apply the styling to the -The doesn't contain any icons on its own. It's a conduit for displaying any _registered_ SVG images. - -### Adding Icons +## Usage - +Register icons first, then render them by name and collection through the component. -To register an image as an icon, all you have to do is import one of the 2 utility functions from the icons registry service that allows you to add icons to an icon collection. +### Register Icons from a File -```ts -import { - registerIcon, - registerIconFromText, -} from "igniteui-webcomponents"; -``` +Use the icon registration helpers when you want to load an SVG from an external file into a named collection. -The function allows you to register an SVG image as an icon from an external file: + ```ts +import { registerIcon, registerIconFromText } from 'igniteui-webcomponents'; + registerIcon( - "search", - "https://unpkg.com/material-design-icons@3.0.1/action/svg/production/ic_build_24px.svg", - "material" + 'search', + 'https://unpkg.com/material-design-icons@3.0.1/action/svg/production/ic_build_24px.svg', + 'material' ); ``` - + + +```tsx +import { registerIcon } from 'igniteui-webcomponents'; + +constructor() { + registerIcon( + 'search', + 'https://unpkg.com/material-design-icons@3.0.1/action/svg/production/ic_build_24px.svg', + 'material' + ); +} + + +``` -To register an image as an icon, all you need to do is call one of the 2 "register" methods on a single element that allow you to add icons to an icon collection on your page. + -The method allows you to register an SVG image as an icon from an external file: + ```razor @@ -120,49 +122,31 @@ The - - -To register an image as an icon, all you need to do is call one of the 2 "register" methods on a single element that allow you to add icons to an icon collection on your page. - -The method allows you to register an SVG image as an icon from an external file: +### Register Icons from SVG Text -```tsx -constructor() { - registerIconFromText("search", "https://unpkg.com/material-design-icons@3.0.1/action/svg/production/ic_build_24px.svg", "material"); -} - - -``` - - - -The method above will add an icon named `search` to a cached collection named `material`. - -In order to use the newly registered icon, all you have to do is to pass the name and collection to the element: +Use the text-based registration method when the SVG markup is available directly in your application. -```html - -``` - - - - +```ts +const searchIcon = + ''; -```razor - +registerIconFromText('search', searchIcon, 'material'); ``` @@ -170,26 +154,22 @@ In order to use the newly registered icon, all you have to do is to pass the nam ```tsx - -``` - - - -The second method for registering icons is by passing an SVG string to the method: +import { registerIconFromText } from 'igniteui-webcomponents'; - - - -```ts const searchIcon = ''; -registerIconFromText("search", searchIcon, "material"); +constructor() { + registerIconFromText('search', searchIcon, 'material'); +} + ``` + + ```razor @@ -198,50 +178,58 @@ registerIconFromText("search", searchIcon, "material"); protected override void OnAfterRender(bool firstRender) { - base.OnAfterRender(firstRender); - if (this.IconRef != null && firstRender) - { - const string searchIcon = ""; - this.IconRef.RegisterIconFromText("search", searchIcon, "material"); - } + base.OnAfterRender(firstRender); + if (this.IconRef != null && firstRender) + { + const string searchIcon = ""; + this.IconRef.RegisterIconFromText("search", searchIcon, "material"); + } } } ``` + +### Render a Registered Icon + +Pass the icon name and collection to the icon component after the icon is registered. + + + +```html + +``` + + ```tsx -const searchIcon = - ''; + +``` -constructor() { - registerIconFromText("search", searchIcon, "material"); -} + - + + +```razor + ``` + -Then you'd use it in the same way as described in the component sample above. +### Change the Size -### Size -The icon component supports three icon sizes - `small`, `medium`(default), and `large`. In order to change the size of the icon, you can utilize the `--ig-size` CSS variable as follows: +Use the sizing CSS variables when you need the icon to match the surrounding layout scale. + + - ```css igc-icon { --ig-size: var(--ig-size-large); } ``` - -```razor - -``` - - @@ -254,23 +242,31 @@ igc-icon { ```css .size-small { - --ig-size: var(--ig-size-small); + --ig-size: var(--ig-size-small); } .size-medium { - --ig-size: var(--ig-size-medium); + --ig-size: var(--ig-size-medium); } .size-large { - --ig-size: var(--ig-size-large); + --ig-size: var(--ig-size-large); } ``` - + + +```razor + +``` + + + + -You can also set a custom size for the icon component. The best way to do this is by using the `--size` CSS variable. +Set `--size` when you need a custom pixel size instead of the shared size tokens. ```css igc-icon { @@ -278,9 +274,9 @@ igc-icon { } ``` -### Mirrored +### Mirror Icons for RTL -Some icons need to look a little different when used in Right-to-Left(RTL) mode. For that reason we provide a `mirrored` attribute that, when set, flips the icon horizontally. +Set the `mirrored` attribute when the icon should flip horizontally in right-to-left layouts. @@ -290,6 +286,14 @@ Some icons need to look a little different when used in Right-to-Left(RTL) mode. + + +```tsx + +``` + + + ```razor @@ -298,17 +302,45 @@ Some icons need to look a little different when used in Right-to-Left(RTL) mode. - +## Best Practices -```tsx - -``` +Use icons to reinforce meaning and save space, not to replace necessary text or labels. - +- Pair icons with accessible labels when the action or state is not obvious from context alone. +- Keep icon collections consistent across the product so the same symbol means the same thing everywhere. +- Use mirrored icons only for direction-sensitive symbols in RTL layouts. +- Avoid relying on icon color alone to communicate status or urgency. + +## Properties + +Use the generated API reference for the full surface; the rows below mark the core options covered on this page. + +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `collection` | build-generated | build-generated | Build injects verified core icon properties here from the typed API source. | +| `mirrored` | build-generated | build-generated | Build injects verified core icon properties here from the typed API source. | +| `name` | build-generated | build-generated | Build injects verified core icon properties here from the typed API source. | +| `size` | build-generated | build-generated | Build injects verified core icon properties here from the typed API source. | + +## Methods + +Use the icon registration methods when you need to load SVGs into a named collection at runtime. + +| Name | Description | +| -- | -- | +| `registerIcon()` / `RegisterIcon()` | Registers an SVG icon from an external file into a collection. | +| `registerIconFromText()` / `RegisterIconFromText()` | Registers an SVG icon from inline SVG text into a collection. | ## Styling -The icon component can be styled by applying styles directly to the element; +Style the icon directly through the host element and sizing variables. + + + +| Variable | What it changes | +| -- | -- | +| `--ig-size` | Applies one of the shared component size tokens to the icon. | +| `--size` | Sets a custom explicit icon size. | ```css igc-icon { @@ -317,10 +349,41 @@ igc-icon { } ``` - +## Accessibility + +Icons are visual symbols, so their accessibility depends on the surrounding label, role, and text context provided by your app. + +### Keyboard Interaction + +The icon component does not define component-specific keyboard shortcuts. + +| Key | Action | +| -- | -- | +| n/a | The icon is not an interactive control by itself. | + +### Screen Readers / ARIA + +[VERIFY: screen reader behavior and aria requirements for the icon component] + +### Accessibility Compliance + +[VERIFY: official accessibility conformance target for the icon component] + +| Criterion | How the component complies | +| -- | -- | +| [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content) | [VERIFY: how decorative versus meaningful icon usage is exposed and what authors must provide] | +| [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships) | Icons can support visual structure, but semantic meaning still depends on the surrounding accessible content. | + +Your responsibilities: + +- Provide an accessible name or adjacent text when an icon conveys an action or state. +- Hide purely decorative icons from assistive technologies when appropriate. +- Ensure icon color and size choices remain understandable in your overall UI. ## API References + + ## Additional Resources - [{ProductName} **Forums**]({ForumsLink}) diff --git a/docs/xplat/src/content/en/components/layouts/splitter.mdx b/docs/xplat/src/content/en/components/layouts/splitter.mdx index ca597fd835..8bb491fd05 100644 --- a/docs/xplat/src/content/en/components/layouts/splitter.mdx +++ b/docs/xplat/src/content/en/components/layouts/splitter.mdx @@ -1,43 +1,51 @@ --- -title: "{Platform} Splitter Component | Layout Controls | Infragistics" -description: "Use the {ProductName} Splitter component to create two resizable panes with horizontal or vertical layouts, collapse and expand behavior, keyboard support, and nested split views." -keywords: "splitter, split panes, resizable panes, web components splitter, {Platform} splitter, {ProductName}" +title: "{Platform} Splitter Component | Layouts | Infragistics" +description: "{Platform} Splitter is a resizable split-pane layout component for dividing content into start and end regions." +keywords: "splitter, split panes, resizable panes, {Platform} splitter, {ProductName}" license: MIT mentionedTypes: ["Splitter", "SplitterResizeEventArgs"] llms: - description: "The {ProductName} Splitter provides a resizable split-pane layout that divides content into two areas: start and end." + description: "The {ProductName} Splitter is a resizable split-pane layout component for dividing content into start and end regions." --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; -import ApiRef from 'igniteui-astro-components/components/mdx/ApiRef.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; -# {Platform} Splitter Overview +# Splitter Component -The {ProductName} Splitter provides a resizable split-pane layout that divides content into two areas: `start` and `end`. Users can drag the splitter bar, use keyboard shortcuts, or collapse and expand panes with built-in controls. You can also nest splitters to build complex dashboard-style layouts. +The {ProductName} Splitter is a resizable split-pane layout component for dividing content into start and end regions. -## {Platform} Splitter Example +## Overview + +The splitter separates content into two panes and lets users resize, collapse, expand, and nest those regions to build adaptable layouts. + +### When to Use + +Use the splitter when users need direct control over how much space related panes receive, such as navigation-and-content, editor-and-preview, or dashboard layouts. + +### When Not to Use + +Do not use the splitter when fixed layout sections or responsive stacking already solve the problem without requiring user-driven pane resizing. - + + + - - + -## Getting Started with {Platform} Splitter + - +## Getting Started -First, you need to install the {ProductName} by running the following command: +Before you add the splitter, complete the shared {ProductName} setup in the [Getting Started](../general-getting-started.md) topic. -```cmd -npm install {PackageWebComponents} -``` + -Before using the , you need to register it as follows: +Register the splitter component before you use it. ```ts import { defineComponents, IgcSplitterComponent } from 'igniteui-webcomponents'; @@ -45,19 +53,11 @@ import { defineComponents, IgcSplitterComponent } from 'igniteui-webcomponents'; defineComponents(IgcSplitterComponent); ``` -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. - -First, you need to install the corresponding {ProductName} npm package by running the following command: - -```cmd -npm install igniteui-react -``` - -You will then need to import the and its necessary CSS, like so: +Import the splitter wrapper and the theme stylesheet before you render the component. ```tsx import { IgrSplitter } from 'igniteui-react'; @@ -68,20 +68,15 @@ import 'igniteui-webcomponents/themes/light/bootstrap.css'; -```csharp -// in Program.cs file +Register the splitter module in `Program.cs`. +```csharp builder.Services.AddIgniteUIBlazor( typeof(IgbSplitterModule) ); ``` - - - - - -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +Add the theme stylesheet to your host page. ```razor @@ -89,9 +84,13 @@ You will also need to link an additional CSS file to apply the styling to the -## Using {Platform} Splitter +## Usage + +Place pane content in the `start` and `end` slots, then configure orientation, size constraints, and interactions as needed. -Use the `start` and `end` slots to place pane content: +### Declare Start and End Panes + +Use the `start` and `end` slots to define the two regions managed by the splitter. @@ -126,14 +125,11 @@ Use the `start` and `end` slots to place pane content: -We recommend using a `
` or other semantic elements such as `
` or `
` for the `start` and `end` slots of the Splitter component. - -### Orientation +Use a `
` or another semantic container such as `
` or `
` for pane content. -Set the property to control pane direction: +### Change the Orientation -- `horizontal` (default): start and end panes are rendered left and right. -- `vertical`: start and end panes are rendered top and bottom. +Set to choose between horizontal and vertical pane flow. @@ -168,15 +164,17 @@ Set the pro -### Pane Size and Constraints +### Set Pane Sizes and Constraints -Use size properties to set initial and constrained pane sizes: +Use the size and min/max properties to define the initial pane distribution and resizing limits. -- , -- , -- , +The splitter supports: -Values accept CSS length values such as `px` and `%`. +- and +- and +- and + +These values accept CSS length values such as `px` and `%`. @@ -227,24 +225,26 @@ Values accept CSS length values such as `px` and `%`. -### Collapsing and Resizing +### Control Resizing and Collapse Behavior + +Use the interaction properties when you need to limit resizing or collapse affordances. -Use these properties to control interactions: +The splitter exposes: -- : disables pane resizing. -- : disables pane collapsing. -- : hides the drag handle. -- : hides collapse and expand buttons. +- +- +- +- -You can also collapse or expand panes programmatically: +You can also toggle a pane programmatically. ```ts const splitter = document.querySelector('igc-splitter') as IgcSplitterComponent; -splitter.toggle('start'); // collapse start pane -splitter.toggle('start'); // expand start pane +splitter.toggle('start'); +splitter.toggle('start'); ``` @@ -283,35 +283,58 @@ const toggleStartPane = () => { -### Nested Splitters +### Nest Splitters -Splitters can be nested to create multi-region layouts. +Nest splitters when a two-pane layout needs further subdivision in one or both regions. - + -## Events +## Best Practices -The Splitter emits the following events during resize operations: +Use the splitter when user-controlled pane sizing improves the workflow, not as a default page chrome element. - +- Set sensible minimum sizes so pane content remains usable while resizing. +- Reserve collapsing for panes that users can safely hide and restore. +- Use nested splitters sparingly so the layout stays understandable. +- Prefer semantic pane content wrappers so each region keeps clear structure and landmarks. -- `igcResizeStart`: fired once when resizing starts. -- `igcResizing`: fired continuously while resizing. -- `igcResizeEnd`: fired once when resizing ends. +## Properties -The event detail includes current `startPanelSize`, `endPanelSize`, and `delta` for ongoing and end events. +Use the generated API reference for the full surface; the rows below mark the core options covered on this page. - +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `orientation` | build-generated | build-generated | Build injects verified core splitter properties here from the typed API source. | +| `startSize` | build-generated | build-generated | Build injects verified core splitter properties here from the typed API source. | +| `endSize` | build-generated | build-generated | Build injects verified core splitter properties here from the typed API source. | +| `startMinSize` | build-generated | build-generated | Build injects verified core splitter properties here from the typed API source. | +| `endMinSize` | build-generated | build-generated | Build injects verified core splitter properties here from the typed API source. | +| `startMaxSize` | build-generated | build-generated | Build injects verified core splitter properties here from the typed API source. | +| `endMaxSize` | build-generated | build-generated | Build injects verified core splitter properties here from the typed API source. | +| `disableResize` | build-generated | build-generated | Build injects verified core splitter properties here from the typed API source. | +| `disableCollapse` | build-generated | build-generated | Build injects verified core splitter properties here from the typed API source. | +| `hideDragHandle` | build-generated | build-generated | Build injects verified core splitter properties here from the typed API source. | +| `hideCollapseButtons` | build-generated | build-generated | Build injects verified core splitter properties here from the typed API source. | - +## Methods -- : fired once when resizing starts. -- : fired continuously while resizing. -- : fired once when resizing ends. +Use the splitter methods when you need to collapse or expand panes from code. -The event detail includes current `StartPanelSize`, `EndPanelSize`, and `Delta` for ongoing and end events. +| Name | Description | +| -- | -- | +| `toggle()` / `Toggle()` | Collapses or expands the specified pane position. | - +## Events + +Use the resize events when your application needs to react to interactive pane changes. + +| Name | Description | +| -- | -- | +| `igcResizeStart` / `ResizeStart` | Fired once when resizing starts. | +| `igcResizing` / `Resizing` | Fired continuously while resizing. | +| `igcResizeEnd` / `ResizeEnd` | Fired once when resizing ends. | + +Resize events include pane size and delta information in the event detail. @@ -358,44 +381,33 @@ const handleResizeEnd = (event: CustomEvent) => { -## Keyboard Navigation - -When the splitter bar is focused: - -| Keys | Description | -| ---- | ----------- | -| Arrow Left / Arrow Right | Resize panes in horizontal orientation | -| Arrow Up / Arrow Down | Resize panes in vertical orientation | -| Home | Snap start pane to its minimum size | -| End | Snap start pane to its maximum size | -| Ctrl + Arrow Left / Arrow Up | Collapse or expand the start pane | -| Ctrl + Arrow Right / Arrow Down | Collapse or expand the end pane | - ## Styling -The component exposes CSS parts for styling: +Use CSS parts and theme variables to style the splitter bar, drag handle, pane surfaces, and collapse controls. -| Name | Description | + + +| CSS Part | Description | +| ---- | ----------- | +| `splitter-bar` | The draggable separator between panes. | +| `drag-handle` | The drag handle element in the splitter bar. | +| `start-pane` | The start pane container. | +| `end-pane` | The end pane container. | +| `start-collapse-btn` | Button that collapses the start pane. | +| `end-collapse-btn` | Button that collapses the end pane. | +| `start-expand-btn` | Button that expands the start pane. | +| `end-expand-btn` | Button that expands the end pane. | + +| Variable | What it changes | | ---- | ----------- | -| `splitter-bar` | The draggable separator between panes | -| `drag-handle` | The drag handle element in the splitter bar | -| `start-pane` | The start pane container | -| `end-pane` | The end pane container | -| `start-collapse-btn` | Button that collapses the start pane | -| `end-collapse-btn` | Button that collapses the end pane | -| `start-expand-btn` | Button that expands the start pane | -| `end-expand-btn` | Button that expands the end pane | - -It also supports theme CSS variables, including: - -- `--bar-color` -- `--handle-color` -- `--expander-color` -- `--bar-color-active` -- `--handle-color-active` -- `--expander-color-active` -- `--focus-color` -- `--size` +| `--bar-color` | Sets the splitter bar color. | +| `--handle-color` | Sets the drag handle color. | +| `--expander-color` | Sets the collapse and expand control color. | +| `--bar-color-active` | Sets the splitter bar color while active. | +| `--handle-color-active` | Sets the drag handle color while active. | +| `--expander-color-active` | Sets the control color while active. | +| `--focus-color` | Sets the focus indicator color. | +| `--size` | Sets the splitter bar size. | ```css igc-splitter { @@ -409,12 +421,49 @@ igc-splitter { } ``` - +## Accessibility + +The splitter supports keyboard resizing and collapsing so users can operate pane layout changes without a pointer. + +### Keyboard Interaction + +Use the keyboard shortcuts below when the splitter bar is focused. + +| Key | Action | +| ---- | ----------- | +| Arrow Left / Arrow Right | Resizes panes in horizontal orientation. | +| Arrow Up / Arrow Down | Resizes panes in vertical orientation. | +| Home | Snaps the start pane to its minimum size. | +| End | Snaps the start pane to its maximum size. | +| Ctrl + Arrow Left / Arrow Up | Collapses or expands the start pane. | +| Ctrl + Arrow Right / Arrow Down | Collapses or expands the end pane. | + +### Screen Readers / ARIA + +[VERIFY: screen reader roles, aria attributes, and announcements for the splitter component] + +### Accessibility Compliance + +[VERIFY: official accessibility conformance target for the splitter component] + +| Criterion | How the component complies | +| -- | -- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | The splitter supports keyboard shortcuts for resizing and collapsing panes. | +| [2.5.7 Dragging Movements](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements) | Users can resize panes with keyboard shortcuts in addition to dragging the splitter bar. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value) | [VERIFY: semantic exposure of the splitter bar and pane state] | + +Your responsibilities: + +- Provide clear surrounding labels or landmarks so users understand what each pane contains. +- Keep minimum pane sizes large enough for content and controls to remain operable. +- Validate contrast and focus visibility when restyling the splitter bar and controls. ## API References - -- [`Styling & Themes`](../themes/overview.md) + + + ## Additional Resources +- [`Styling & Themes`](../themes/overview.md) - [{ProductName} **Forums**]({ForumsLink}) - [{ProductName} **GitHub**]({GithubLink}) diff --git a/docs/xplat/src/content/en/components/layouts/stepper.mdx b/docs/xplat/src/content/en/components/layouts/stepper.mdx index 725665e1c3..e84eef7ac5 100644 --- a/docs/xplat/src/content/en/components/layouts/stepper.mdx +++ b/docs/xplat/src/content/en/components/layouts/stepper.mdx @@ -1,11 +1,11 @@ --- -title: "{Platform} Stepper Component - {ProductName}" -description: "{Platform} Stepper component is used to visualize content as a process and to show its progress by dividing the content into logical steps. Try it for FREE." +title: "{Platform} Stepper Component | Layouts | Infragistics" +description: "{Platform} Stepper is a workflow component for guiding users through a sequence of ordered steps." keywords: "{Platform} Stepper, {ProductName}, Infragistics" license: MIT mentionedTypes: ["Stepper"] llms: - description: "The {Platform} Stepper Component provides a wizard-like workflow and is used for showing progress through numbered steps." + description: "The {ProductName} Stepper is a workflow component for guiding users through a sequence of ordered steps." --- import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; @@ -16,30 +16,37 @@ import { Image } from 'astro:assets'; import stepperStep from '@xplat-images/stepper/stepper-step.png'; import stepperContenttop from '@xplat-images/stepper/stepper-contentTop.png'; +# Stepper Component -# {Platform} Stepper Overview +The {ProductName} Stepper is a workflow component for guiding users through a sequence of ordered steps. -The {Platform} Stepper Component provides a wizard-like workflow and is used for showing progress through numbered steps. It enables developers to divide a lengthy content into a sequence of logical steps, helping end-users more easily navigate the entire process. The {Platform} Stepper is displayed as a vertical or a horizontal line. The {Platform} Stepper has multiple features like step validation, styling, orientation and keyboard navigation. +## Overview -## {Platform} Stepper Example +The stepper breaks a process into distinct stages so users can track progress, understand their position, and complete each step in sequence. -The following {ProductName} Stepper Example below shows the component in action. It visualizes the process that an end-user must pass through to configure an order details, following several consecutive steps. +### When to Use - +Use the stepper when users move through a structured multi-step flow such as checkout, onboarding, or setup. -
+### When Not to Use -## Getting Started with {Platform} Stepper +Do not use the stepper when users need freeform navigation across unrelated sections or when the sequence is too short to justify a dedicated progress pattern. - + -First, you need to install the {ProductName} by running the following command: +## Anatomy -```cmd -npm install {PackageWebComponents} -``` +The stepper is composed of steps, each with header and content regions, and supports optional indicator, title, and subtitle content. + +Stepper step anatomy + +## Getting Started -Before using the , you need to register it as follows: +Before you add the stepper, complete the shared {ProductName} setup in the [Getting Started](../general-getting-started.md) topic. + + + +Register the stepper component before you use it. ```ts import { defineComponents, IgcStepperComponent } from 'igniteui-webcomponents'; @@ -47,19 +54,11 @@ import { defineComponents, IgcStepperComponent } from 'igniteui-webcomponents'; defineComponents(IgcStepperComponent); ``` -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. - -First, you need to the install the corresponding {ProductName} npm package by running the following command: - -```cmd -npm install igniteui-react -``` - -You will then need to import the and its necessary CSS, like so: +Import the stepper wrappers and the theme stylesheet before you render the component. ```tsx import { IgrStepper, IgrStep } from 'igniteui-react'; @@ -70,19 +69,15 @@ import 'igniteui-webcomponents/themes/light/bootstrap.css'; -```csharp -// in Program.cs file +Register the stepper module in `Program.cs`. +```csharp builder.Services.AddIgniteUIBlazor( typeof(IgbStepperModule) ); ``` - - - - -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +Add the theme stylesheet to your host page. ```razor @@ -90,14 +85,13 @@ You will also need to link an additional CSS file to apply the styling to the -Now you can start with a basic configuration of the {Platform} and its steps. +## Usage -## How To Use {Platform} Stepper -The is the representation of every step that belongs to the . Steps provide , , , and properties, which give you the ability to configure the step states according to your business requirement. +Build the stepper by declaring steps, then configure orientation, flow rules, step types, and animations for the user journey. -### Declaring {Platform} Stepper +### Declare Steps -Steps can be declared the following way: +Use inside to define each stage in the process. @@ -144,14 +138,12 @@ Steps can be declared the following way: -For each step the user has the ability to configure the indicator, title and subtitle using the `indicator`, `title`, and `subtitle` slots. +### Configure Header and Content Slots -For the `title` and `subtitle` slots, we recommend using `` elements rather than heading elements (`

`–`

`). Heading elements carry built-in styling (such as font size, line height, and margins) that can interfere with the component's intended typography and layout. Using a `` gives you a neutral container that inherits the component's styles cleanly. - -For the `indicator` slot, we also recommend using a `` element for symbol or emoji indicators, and an [``](../layouts/icon.md) component for icon indicators. +Use the `indicator`, `title`, and `subtitle` slots to shape each step header, and place the step body in the default slot. -The `default` slot renders the content of the step. +The default slot renders the content of the step. @@ -207,43 +199,33 @@ The `default` slot renders the content of the -stepper-step - -### Orientation in {Platform} Stepper - -You can customize the stepper orientation through the exposed property. It could be set to **horizontal** or **vertical**. - -**Horizontal Stepper Orientation** - -**horizontal** is the default value for the orientation property. - -When the {Platform} stepper is horizontally orientated you have the opportunity to determine whether the steps' content would be displayed above or below the steps' headers. This could be achieved by setting the boolean property, which default value is **false**. In case it is enabled the steps' content would be displayed above the steps' headers. +Use `` for `title` and `subtitle`, and prefer `` or [``](../layouts/icon.md) for indicator content. -stepper-contentTop +### Change the Orientation -**Vertical Stepper Orientation** +Set to switch between horizontal and vertical step layouts. -You can easily switch from the horizontal to vertical layout. In order to change the default orientation you should set the property to **vertical**. +When the stepper is horizontal, use to place the active step content above the headers instead of below them. -The sample below demonstrates how stepper orientation and titles position could be changed runtime. +Stepper content top example - + -
+### Set Step States -### Step States +Use the step state properties to control flow and presentation for each step. -{Platform} supports five steps states and each of them apply different styles by default: +The step component supports: -- **active** - Determines whether the step is the currently displayed. By design, if the user does not explicitly set some step’s active attribute to **true**, the initial active step would be the first non-disabled step. -- **disabled** - Determines whether the step is intractable. By default, the disabled attribute of a step is set to **false**. -- **invalid** - Determines whether the step is valid. Based on its value it is decided whether the user will have the ability to move forward in linear stepper mode. Its default value is **false**. -- **optional** - By default, the optional attribute of a step is set to **false**. If validity of a step in linear stepper is not required, then the optional attribute can be enabled in order to be able to move forward independently from the step validity. -- **complete** - By default, the complete attribute of a step returns **false**. The user, however, can override this default complete behavior by setting the complete attribute as needed. When step is marked as complete not only that the style of the step header is changed by default, but also the style of the progress line between the completed step and the next one. +- +- +- +- +- -### Linear {Platform} Stepper +### Use Linear Flow -The {Platform} gives you the opportunity to set its steps flow using the property. By default, linear is set to **false** and the user is enabled to select any non-disabled step in the . +Set when users must complete steps in sequence. @@ -290,148 +272,125 @@ The {Platform} gives you the opportunity t -When the linear property is set to **true**, the stepper will require the current non-optional step to be valid before proceeding to the next one. - -If the current non-optional step is not valid you cannot go forward to the next step until you validate the current one. +When linear mode is enabled, the current non-optional step must be valid before the user can continue to the next one. -Optional steps validity is not taken into account in order to move forward. +Optional step validity is not taken into account in order to move forward. -### Step Interactions - - provides the following API methods for step interactions: -- **navigateTo** – activates the step by given index. -- **next** - activates the next non-disabled step. -- **prev** – activates the previous non-disabled step. -- **reset** – resets the stepper to its initial state. - - -The reset method would reset the stepper to its initial state, i.e. activates the first step. It would not clear the step`s content. This should be done manually. - - -### Customizing the Steps - -The {ProductName} Stepper gives you the ability to configure different options for titles, indicators and more. +### Navigate Programmatically -This could be achieved through the property of the . It takes the following values: -- Full **(default value)** -- Indicator -- Title +Use the stepper methods when your application controls movement between steps. -**full** +The stepper provides: -If titles and subtitles are defined, with this setup both indicators and titles would be rendered. - -The user would also have the ability to define the position of the title for the steps, so it could be placed before, after, above or below the step indicator. -The user can configure the title position using the property. It takes the following values: -- undefined **(default value)** -- end -- start -- bottom -- top - -When the {Platform} is horizontally orientated and the title position **is not defined**, the titles would be displayed **below** the indicators. - -When the orientation is set to vertical and the title position **is not defined**, the titles would be displayed **after** the indicators. +- `navigateTo` +- `next` +- `prev` +- `reset` -**titlePosition** property is applicable **only** when the stepper stepType property is set to **full**. +The `reset` method returns the stepper to its initial state and activates the first step, but it does not clear the step content. -**indicator** +### Change the Step Type -If you want to display only indicators for the steps, set the stepType option to **indicator**. +Set to render full headers, indicators only, or titles only. -The step indicator supports any content, however with the restriction that its size would be always **24 pixels**. Having this in mind, we recommend using or as step indicators. +When `stepType` is `full`, use the `titlePosition` property to place the title before, after, above, or below the indicator. -**Title** + -If you want to display only titles for the steps, set the stepType option to **title**. +### Adapt Content Height -In this way if subtitles are defined, they will also be rendered below the step title. +Set `--body-grid-rows` to `0fr` when you want the content region height to follow the active step instead of matching the tallest step. - -This container could be re-templated as per your requirement without any size restrictions. For example, you could add an indicator with size greater than 24 pixels inside it. - +```css +igc-stepper { + --body-grid-rows: 0fr; +} +``` -The sample below demonstrates all exposed step types and how they could be changed: + - +### Change Stepper Animations -### Dynamic Step Height +Set and to control the transition style for each orientation. -When the is horizontally oriented, the content area height is determined by the step with the most content. All other steps share this fixed height, which may result in visible empty space in steps with less content. +Set `animationDuration` to change the transition duration, or set the animation type to `none` to disable animations. -To override the fixed height and have the content area adapt to the active step's content, set the **--body-grid-rows** CSS variable to **0fr** (the default is **1fr**): + -```css -igc-stepper { - --body-grid-rows: 0fr; -} -``` +## Best Practices - +Use the stepper to support a real sequence, not as a decorative progress marker for unrelated sections. -### Stepper Animations +- Keep step titles short and specific so users can quickly understand the flow. +- Use subtitles only when they add context that the title cannot carry alone. +- Reserve linear mode for flows that truly require completion in order. +- Keep optional, invalid, and complete states aligned with real business rules so progress feedback stays trustworthy. -The {Platform} Animations provide the end-users with a beautiful experience interacting with the defined steps. The available animation options differ depending on the orientation of the stepper. +## Properties -When the stepper is horizontally orientated, it is configured to use the `slide` animation by default. It also supports `fade` as an alternative. The animations are configured through the input. +Use the generated API reference for the full surface; the rows below mark the core options covered on this page. -In a vertically orientated layout, the animation type could be defined using the property. By default, its value is set to `grow` and the user has the ability to set it to `fade` as well. +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `orientation` | build-generated | build-generated | Build injects verified core stepper properties here from the typed API source. | +| `contentTop` | build-generated | build-generated | Build injects verified core stepper properties here from the typed API source. | +| `linear` | build-generated | build-generated | Build injects verified core stepper properties here from the typed API source. | +| `stepType` | build-generated | build-generated | Build injects verified core stepper properties here from the typed API source. | +| `horizontalAnimation` | build-generated | build-generated | Build injects verified core stepper properties here from the typed API source. | +| `verticalAnimation` | build-generated | build-generated | Build injects verified core stepper properties here from the typed API source. | +| `animationDuration` | build-generated | build-generated | Build injects verified core stepper properties here from the typed API source. | -Setting `none` to both animation type inputs disables stepper animations. +## Methods -The component also gives you the ability to configure the duration of the transition between the steps. This could be achieved through the `animationDuration` property, which takes a number as an argument and it is common to both orientations. The default value is set to 320ms. +Use the stepper methods when you need to move between steps from code. - +| Name | Description | +| -- | -- | +| `navigateTo` | Activates the step at the given index. | +| `next` | Activates the next non-disabled step. | +| `prev` | Activates the previous non-disabled step. | +| `reset` | Returns the stepper to its initial active step. | -
+## Styling -## Keyboard Navigation +Use CSS parts to customize step headers, indicators, titles, subtitles, and content containers. -The {ProductName} Stepper provides a rich variety of keyboard interactions to the end-user. This functionality is enabled by default and allows end-users to easily navigate through the steps. -The {Platform} navigation is compliant with [W3 accessability standards](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/) and convenient to use. + + + -**Key Combinations** + -- TAB - moves the focus to the next tabbable element -- SHIFT + TAB - moves the focus to the previous tabbable element -- ↓ - moves the focus to the header of the next accessible step when the stepper is **vertically orientated** -- ↑ - moves the focus to the header of the previous accessible step when the stepper is **vertically orientated** -- ← - moves the focus to the header of the previous accessible step in both orientations -- → - moves the focus to the header of the next accessible step in both orientations -- HOME - moves the focus to the header of the FIRST enabled step in the stepper -- END - moves the focus to the header of the LAST enabled step in the stepper -- ENTER or SPACE - activates the currently focused step + -## Styling {Platform} Stepper + -You can change the appearance of the , by using some of the exposed CSS parts listed below: + | Part name | Description | | ---------|------------ | | `header-container` | Wrapper of the step's header and its separators. | -| `disabled` | Indicates a disabled state. Applies to header-container. | -| `complete-start` | Indicates a complete state of the current step. Applies to header-container. | -| `complete-end` | Indicates a complete state of the previous step. Applies to header-container. | -| `optional` | Indicates an optional state. Applies to header-container. | -| `invalid` | Indicates an invalid state. Applies to header-container. | -| `top` | Indicates that the title should be above the indicator. Applies to header-container. | -| `bottom` | Indicates that the title should be below the indicator. Applies to header-container. | -| `start` | Indicates that the title should be before the indicator. Applies to header-container. | -| `end` | Indicates that the title should be after the indicator. Applies to header-container. | +| `disabled` | Indicates a disabled state. Applies to `header-container`. | +| `complete-start` | Indicates a complete state of the current step. Applies to `header-container`. | +| `complete-end` | Indicates a complete state of the previous step. Applies to `header-container`. | +| `optional` | Indicates an optional state. Applies to `header-container`. | +| `invalid` | Indicates an invalid state. Applies to `header-container`. | +| `top` | Indicates that the title should be above the indicator. Applies to `header-container`. | +| `bottom` | Indicates that the title should be below the indicator. Applies to `header-container`. | +| `start` | Indicates that the title should be before the indicator. Applies to `header-container`. | +| `end` | Indicates that the title should be after the indicator. Applies to `header-container`. | | `header` | Wrapper of the step's indicator and text. | | `indicator` | The indicator of the step. | | `text` | Wrapper of the step's title and subtitle. | -| `empty` | Indicates that no title and subtitle has been provided to the step. Applies to text. | +| `empty` | Indicates that no title and subtitle has been provided to the step. Applies to `text`. | | `title` | The title of the step. | | `subtitle` | The subtitle of the step. | | `body` | Wrapper of the step's content. | -| `content` | The steps content. | - -Using these CSS parts we can customize thе appearance of the component like this: +| `content` | The step content. | ```css igc-step::part(title) { @@ -445,26 +404,52 @@ igc-step::part(indicator) { } ``` - +## Accessibility - +The stepper provides keyboard step navigation and stateful progress feedback for sequential workflows. - +### Keyboard Interaction - +Use the keyboard shortcuts below to move focus and activate steps. - +| Key | Action | +| -- | -- | +| Tab | Moves focus to the next tabbable element. | +| Shift + Tab | Moves focus to the previous tabbable element. | +| Down Arrow | Moves focus to the header of the next accessible step when the stepper is vertically oriented. | +| Up Arrow | Moves focus to the header of the previous accessible step when the stepper is vertically oriented. | +| Left Arrow | Moves focus to the header of the previous accessible step in both orientations. | +| Right Arrow | Moves focus to the header of the next accessible step in both orientations. | +| Home | Moves focus to the first enabled step header. | +| End | Moves focus to the last enabled step header. | +| Enter or Space | Activates the currently focused step. | - +### Screen Readers / ARIA + +[VERIFY: screen reader roles, aria attributes, and announcements for the stepper component] + +### Accessibility Compliance + +[VERIFY: official accessibility conformance target for the stepper component] + +| Criterion | How the component complies | +| -- | -- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | The stepper supports keyboard navigation and activation across accessible steps. | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order) | Focus moves through step headers in a predictable order. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value) | [VERIFY: semantic exposure of step headers, active state, and content relationships] | + +Your responsibilities: -
+- Provide clear step titles and subtitles that describe each stage of the workflow. +- Keep optional and invalid states aligned with real validation logic. +- Validate contrast and focus visibility when restyling indicators, text, and separators. ## API References -
-
-
-
+ + + + ## Additional Resources diff --git a/docs/xplat/src/content/en/components/layouts/tabs.mdx b/docs/xplat/src/content/en/components/layouts/tabs.mdx index eca6e4b0e4..27d311083c 100644 --- a/docs/xplat/src/content/en/components/layouts/tabs.mdx +++ b/docs/xplat/src/content/en/components/layouts/tabs.mdx @@ -1,55 +1,54 @@ --- -title: "{Platform} Tabs Control | Layout Controls | {ProductName}" -description: "{Platform} Tabs component allows users to place tabs at the top and switch between similar data sets. Try it Now" +title: "{Platform} Tabs Component | Layouts | {ProductName}" +description: "{Platform} Tabs is a navigation component for switching between related content sections in a single tabbed interface." keywords: "{Platform}, UI controls, web widgets, UI widgets, {Platform} Tabs Component, Infragistics" license: MIT mentionedTypes: ["Tabs", "Tab", "Icon", "IconButton", "RadioGroup"] llms: - description: "The {Platform} Tabs is a lightweight and user-friendly component that organizes corresponding content in a tab format or a collection of tabs typically placed horizontally." + description: "The {ProductName} Tabs is a navigation component for switching between related content sections in a single tabbed interface." --- import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +# Tabs Component -# {Platform} Tabs Overview +The {ProductName} Tabs is a navigation component for switching between related content sections in a single tabbed interface. -The {Platform} Tabs is a lightweight and user-friendly component that organizes corresponding content in a tab format or a collection of tabs typically placed horizontally. The {Platform} Tab enables end-users to easily click through and display different views. There are several features and customization options like tab orientation, templating, built-in header styles, animation, scroll buttons, and more. +## Overview -The {ProductName} Tabs organizes and switches between similar data sets. The tabs are placed at the top of the data content. When a tab is selected its corresponding content is displayed. +Tabs organize similar content into labeled views so users can switch context quickly without leaving the current page or layout. -## {Platform} Tabs Example +### When to Use -The {Platform} Tabs example below displays three different tabs aligned in a single line so you can navigate across each in a fast and easy way. +Use tabs when users need to move between related sections, settings groups, or data views while keeping the same surrounding context. - +### When Not to Use -## How to use Tabs with {ProductName} +Do not use tabs when the content sequence is procedural, deeply nested, or large enough that users need direct page-level navigation instead of inline view switching. - + -First, you need to install the {ProductName} by running the following command: +## Getting Started -```cmd -npm install {PackageWebComponents} -``` +Before you add tabs, complete the shared {ProductName} setup in the [Getting Started](../general-getting-started.md) topic. - + - +Register the tabs component before you use it. -First, you need to the install the corresponding {ProductName} npm package by running the following command: +```ts +import { defineComponents, IgcTabsComponent } from 'igniteui-webcomponents'; -```cmd -npm install igniteui-react +defineComponents(IgcTabsComponent); ``` -Before using the , you need to import it as follows: - +Import the tabs wrappers before you render the component. + ```tsx import { IgrTabs, IgrTab } from "igniteui-react"; ``` @@ -58,27 +57,21 @@ import { IgrTabs, IgrTab } from "igniteui-react"; -```csharp -// in Program.cs file +Register the tabs module in `Program.cs`. +```csharp builder.Services.AddIgniteUIBlazor(typeof(IgbTabsModule)); ``` - - -```ts -import { defineComponents, IgcTabsComponent } from 'igniteui-webcomponents'; +## Usage -defineComponents(IgcTabsComponent); -``` - - +Declare tabs, then configure selection behavior, alignment, scrolling, and slot content for your tab headers. -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. +### Declare Tabs -Simple declaration is done as follows: +Use inside to define the header label and body content for each tab. @@ -137,21 +130,21 @@ Simple declaration is done as follows: -Tab text can be set either as simple string using the property or by assigning children to the `label` slot. Any remaining children in the `default` slot are rendered as the tab content. +Set the tab text with the property or with content in the `label` slot. Any remaining default-slot content becomes the tab body. -When using the `label` slot, we recommend using a `` element when you want to provide text and an [``](../layouts/icon.md) or [``](../inputs/icon-button.md) component when you want to display icons. +### Control Selection -### Selection +Use the tab selection API when your app needs to react to or control which tab is active. -The emits event when the user selects an item either by key press or click. The method allows you to select a tab by specifying the or its id. +The component emits the event when the user selects a tab, and the method selects a tab by item reference or id. -If the selected tab is not specified on initial load, the first tab that is not disabled will be selected. +If no selected tab is specified on initial load, the first tab that is not disabled is selected. -The default behavior, which selects a tab when the user is navigating with the arrow keys, could be modified by the property. Setting it to `Manual` will focus the next/previous tab on arrow key press, but the tab will be selected only after pressing SPACE or ENTER +Set the property to `Manual` when arrow-key navigation should move focus without selecting the next tab until the user presses Space or Enter. -### Disabled Tab +### Disable Tabs -A tab is disabled by setting the attribute: +Set the attribute when a tab should remain visible but unavailable for interaction. @@ -177,79 +170,93 @@ A tab is disabled by setting the property controls how {Platform} tabs are positioned. It accepts the following values: +Set the property to control how tabs are distributed inside the header. -- `Start` (default): the width of the tab depends on the content (label, icon, both) and all tabs have equal padding. First tab is aligned to the tabs container's left side. -- `Center`: the width of the tab depends on the content and occupies the tabs container's center. -- `End`: the width of the tab depends on the content and all tabs have equal padding. Last tab is aligned to the tabs container's right side. -- `Justify`: all tabs are equal in width and fully fit the tabs container. +The component supports: -If the space is not enough to fit all tabs, scroll buttons are displayed. +- `Start` +- `Center` +- `End` +- `Justify` - +If the available space is not enough to fit all tabs, the tabs header shows scroll buttons. -### Scrolling + -Scroll buttons are shown when the available space is not enough to render all {Platform} tabs. The start scroll button is disabled if the first tab is in view. Respectively, when last tab is in view the end scroll button is disabled. By pressing one of the scroll buttons the tabs are scrolled so the tab in that direction is fully visible, or if it is already visible the previous/next tab in that direction is displayed. +### Handle Overflow Scrolling - +Use the built-in scroll buttons when the tab headers overflow the available space. -### Keyboard Navigation +The start scroll button is disabled when the first tab is in view, and the end scroll button is disabled when the last tab is in view. -|Keys|Description| -|----|-----------| -| ← | Selects previous (next in Right-to-Left mode) tab. If is set to `Manual` only focuses the tab. Scrolls to end if on first tab. | -| → | Selects next (previous in Right-to-Left mode) tab. If is set to `Manual` only focuses the tab. Scrolls to start if on last tab. | -| HOME | Selects the first tab. | -| END | Selects the last tab. | -| ENTER / SPACE | Selects the focused tab when is `Manual` | + -### Prefix / Suffix +### Add Prefix and Suffix Content -Besides the `label` slot, which can be used to display an icon, text, or both, each tab also provides `prefix` and `suffix` slots for displaying additional content at the beginning and/or the end. When slotting content into the `prefix` and `suffix` slots, we recommend using a `` element for symbols or emojis, and an [``](../layouts/icon.md) or [``](../inputs/icon-button.md) component for icons. +Use the `prefix` and `suffix` slots when you need extra content before or after the main tab label. - +Use a `` for text or symbols, and prefer [``](../layouts/icon.md) or [``](../inputs/icon-button.md) for icon content. -## Styling + + +## Best Practices + +Use tabs to switch between peer views, not to hide unrelated or overly complex navigation structures. + +- Keep tab labels short so users can scan all available views quickly. +- Use disabled tabs only when users benefit from seeing future or unavailable options in context. +- Choose manual activation when tab content is expensive or disruptive to load on arrow-key focus movement. +- Avoid combining too many tabs with long labels in narrow layouts where scrolling becomes the default interaction. + +## Properties + +Use the generated API reference for the full surface; the rows below mark the core options covered on this page. -The component exposes several CSS parts, giving you full control over its style: +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `activation` | build-generated | build-generated | Build injects verified core tabs properties here from the typed API source. | +| `alignment` | build-generated | build-generated | Build injects verified core tabs properties here from the typed API source. | +| `label` | build-generated | build-generated | Build injects verified core tab properties here from the typed API source. | +| `disabled` | build-generated | build-generated | Build injects verified core tab properties here from the typed API source. | - +## Methods + +Use the tabs methods when you need to select a tab from code. | Name | Description | -|--|--| -| `selected-indicator` | The selected indicator. | -| `start-scroll-button` | The start scroll button displayed when the tabs overflow. | -| `end-scroll-button` | The end scroll button displayed when the tabs overflow. | +| -- | -- | +| `select` | Selects a tab by reference or id. | - +## Styling - +Use CSS parts to customize the selected indicator, scroll buttons, tab headers, and tab body regions. + + + +The component exposes the following CSS parts: | Name | Description | -|--|--| -| `headers` | The wrapper which includes the tabs and the scroll buttons. | -| `headers-content` | The container for the tabs which represents the available space for rendering of the tabs. | -| `headers-wrapper` | The wrapper for the tabs and the selected indicator. | -| `headers-scroll` | The container for the tabs. | +| -- | -- | | `selected-indicator` | The selected indicator. | | `start-scroll-button` | The start scroll button displayed when the tabs overflow. | | `end-scroll-button` | The end scroll button displayed when the tabs overflow. | -| `content` | The container for the content where the data is displayed. | - - +| `headers` | The wrapper that includes the tabs and the scroll buttons. | +| `headers-content` | The container for the tabs that represents the available space for rendering. | +| `headers-wrapper` | The wrapper for the tabs and the selected indicator. | +| `headers-scroll` | The container for the tabs. | +| `content` | The container for the tab content where the data is displayed. | The component exposes the following CSS parts: -|Name|Description| -|--|--| -| `content` | Tab header's label slot container. | -| `prefix` | Tab header's label prefix. | -| `suffix` | Tab header's label suffix. | +| Name | Description | +| -- | -- | +| `content` | The tab header label-slot container. | +| `prefix` | The tab header prefix content. | +| `suffix` | The tab header suffix content. | | `tab-header` | The header of a single tab. | -| `tab-body` | Holds the body content of a single tab, only the body of the selected tab is visible. | +| `tab-body` | Holds the body content of a single tab; only the selected tab body is visible. | ```css igc-tab::part(tab-header), @@ -288,10 +295,43 @@ igc-tab::part(tab-header)::before { } ``` - +## Accessibility + +Tabs support keyboard selection patterns and focus movement for switching between related content views. + +### Keyboard Interaction + +Use the keyboard shortcuts below to move focus and select tabs. + +| Key | Action | +| -- | -- | +| Left Arrow | Selects the previous tab, or the next tab in right-to-left mode. If activation is `Manual`, only focuses the tab. | +| Right Arrow | Selects the next tab, or the previous tab in right-to-left mode. If activation is `Manual`, only focuses the tab. | +| Home | Selects the first tab. | +| End | Selects the last tab. | +| Enter / Space | Selects the focused tab when activation is `Manual`. | + +### Screen Readers / ARIA + +[VERIFY: screen reader roles, aria attributes, and announcements for the tabs component] + +### Accessibility Compliance + +[VERIFY: official accessibility conformance target for the tabs component] + +| Criterion | How the component complies | +| -- | -- | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | Tabs support keyboard navigation and selection. | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order) | Focus moves predictably across the tab headers. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value) | [VERIFY: semantic exposure of tabs, selected state, and tab panels] | + +Your responsibilities: +- Provide clear tab labels that distinguish each view. +- Keep decorative prefix and suffix content from replacing the accessible name of the tab. +- Validate contrast and focus visibility when restyling tab headers, indicators, and scroll buttons. -## API Reference +## API References @@ -302,4 +342,4 @@ igc-tab::part(tab-header)::before { ## Additional Resources - [{ProductName} **Forums**]({ForumsLink}) -- [{ProductName} **GitHub**]({GithubLink}) \ No newline at end of file +- [{ProductName} **GitHub**]({GithubLink}) diff --git a/docs/xplat/src/content/en/components/layouts/tile-manager.mdx b/docs/xplat/src/content/en/components/layouts/tile-manager.mdx index bf4af3b91f..e604723347 100644 --- a/docs/xplat/src/content/en/components/layouts/tile-manager.mdx +++ b/docs/xplat/src/content/en/components/layouts/tile-manager.mdx @@ -1,70 +1,75 @@ --- -title: "{Platform} Tile Manager Component - {ProductName}" -description: "{Platform} Tile Manager component enables the display of content in individual tiles." -keywords: "{Platform} Tile Manager, {ProductName}, Infragistics, UI controls, {Platform} widgets, web widgets, UI widgets, {Platform}, Native {Platform} Components Suite, Native {Platform} Controls, Native {Platform} Components Library, Layout components" +title: "{Platform} Tile Manager Component | Layouts | {ProductName}" +description: "{Platform} Tile Manager arranges content in interactive tiles that users can move, resize, maximize, and save as a reusable layout." +keywords: "{Platform}, UI controls, web widgets, UI widgets, {Platform} Tile Manager Component, Infragistics" license: MIT -mentionedTypes: ["TileManager", "Tile"] +mentionedTypes: ["TileManager", "Tile", "Icon", "IconButton"] llms: - description: "The {ProductName} Tile Manager component enables the display of content in individual tiles." + description: "The {ProductName} Tile Manager arranges content in interactive tiles that users can move, resize, maximize, and save as a reusable layout." +relatedComponents: ["Splitter"] --- -import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; import Sample from 'igniteui-astro-components/components/mdx/Sample.astro'; import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro'; +import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; import { Image } from 'astro:assets'; import tileManagerActions from '@xplat-images/tile-manager-actions.png'; +# Tile Manager Component -# {Platform} Tile Manager Overview +The {ProductName} Tile Manager arranges content in interactive tiles that users can move, resize, maximize, and save as a reusable layout. -The {ProductName} Tile Manager component enables the display of content in individual tiles. It allows users to interact with these tiles by rearranging and resizing them, giving them the freedom to customize the layout and appearance of the content according to their preferences. This flexibility enhances the user experience by enabling a more personalized and efficient way to view and manage content. +## Overview -## {Platform} Tile Manager Example +Tile Manager helps you build dashboard-style layouts where each content region stays visible as a tile and the user can personalize how those regions are arranged. -The following {ProductName} Tile Manager Example shows the component in action. +### When to Use - +Use Tile Manager when the page needs a multi-panel workspace with persistent tiles that users can reorder, resize, maximize, or restore. - -Due to the iframe permissions policy, the fullscreen button in this example will only work when the example is opened in standalone mode by clicking the 'Expand to fullscreen' button in the top-right corner. - +### When Not to Use -## Usage +Do not use Tile Manager when the layout only needs fixed pane resizing. For simple adjacent panes without draggable, serializable tiles, use the [Splitter](./splitter.md) component instead. -The provides a base tile layout behavior, managing the placement of tiles in maximized or normal state. The tiles can be sized independently of each other and used to form complex layouts. End users can reorder tiles by dragging and dropping them, providing a flexible and intuitive experience. + -The Tile Manager offers two components that we can use: + +Due to the iframe permissions policy, the fullscreen button in this example only works after you open the sample in standalone mode from the top-right fullscreen action. + -- - This component represents an individual tile displayed within the Tile Manager. -- - This is the main component that contains all of the tile components, serving as the container for the entire tile layout. +## Anatomy -### Getting Started +Tile Manager combines a grid container with individual tiles that render a header, content area, and optional action or resize adorners. - +### Tile Header Actions -To start using the Tile Manager, first, you need to install the {ProductName} by running the following command: +By default, the tile header can show maximize and fullscreen actions. -```cmd -npm install {PackageWebComponents} -``` +Tile Manager tile header actions - - - +### Slots -To start using the Tile Manager, first, you need to install the {ProductName} by running the following command: +The component exposes the following slots: -```cmd -npm install igniteui-react -``` +| Slot name | Description | +| -- | -- | +| `title` | Content for the tile header. | +| `fullscreen-action` | Replaces the default fullscreen action content. | +| `maximize-action` | Replaces the default maximize action content. | +| `actions` | Custom content rendered after the default actions. | +| `side-adorner` | Replaces the default horizontal resize adorner. | +| `corner-adorner` | Replaces the default diagonal resize adorner. | +| `bottom-adorner` | Replaces the default vertical resize adorner. | - +## Getting Started -Before using the Tile Manager, you need to import it as follows: +Before you add Tile Manager, complete the shared {ProductName} setup in the [Getting Started](../general-getting-started.md) topic. +Register the tile manager component before you use it. + ```ts import { defineComponents, IgcTileManagerComponent } from 'igniteui-webcomponents'; @@ -75,6 +80,8 @@ defineComponents(IgcTileManagerComponent); +Import the tile manager wrappers and a theme stylesheet before you render the component. + ```tsx import { IgrTile, IgrTileManager } from 'igniteui-react'; import 'igniteui-webcomponents/themes/light/bootstrap.css'; @@ -84,14 +91,13 @@ import 'igniteui-webcomponents/themes/light/bootstrap.css'; +Register the tile manager module in `Program.cs`. ```csharp -// in Program.cs file - builder.Services.AddIgniteUIBlazor(typeof(IgbTileManagerModule)); ``` -You will also need to link an additional CSS file to apply the styling to the component. The following needs to be placed in the **wwwroot/index.html** file in a **Blazor Web Assembly** project or the **Pages/_Host.cshtml** file in a **Blazor Server** project: +Link the theme stylesheet in your host page. ```razor @@ -99,87 +105,30 @@ You will also need to link an additional CSS file to apply the styling to the -Now you can start with a basic configuration of the {Platform} Tile Manager. - - - -```html - - -

Tile 1

- - -

Tile 2

- - -

Tile 3

- - -``` - - - - - -```razor - - -

Tile 1

- - -

Tile 2

- - -

Tile 3

- - -``` - - - - - -```tsx - - -

Tile 1

- - -

Tile 2

- - -

Tile 3

- - -``` - - - -For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. +## Usage -## Layout +Declare a tile manager with child tiles, then configure layout behavior, actions, resizing, dragging, and layout persistence. -### Columns and Rows +### Declare Tiles -We can specify the number of grid columns for our Tile Manager. To do this, simply set the property to the desired number of columns. If the number is less than one or the property is not set, the Tile Manager will create as many columns as can fit, with each column being at least 200px wide and expanding to equally share the available space. When the viewport dimensions change, the tiles will also rearrange themselves to maximize the use of space. +Use inside to define each tile's header and content. ```html - + - Tile 1 header -

Tile 1 Content

+ Tile 1 +

Tile 1 content

 - Tile 2 header -

Tile 2 Content

+ Tile 2 +

Tile 2 content

 - Tile 3 header -

Tile 3 Content

+ Tile 3 +

Tile 3 content

 - ... ``` @@ -188,20 +137,19 @@ We can specify the number of grid columns for our Tile Manager. To do this, simp ```tsx - + - Tile 1 header -

Tile 1 Content

+ Tile 1 +

Tile 1 content

 - Tile 2 header -

Tile 2 Content

+ Tile 2 +

Tile 2 content

 - Tile 3 header -

Tile 3 Content

+ Tile 3 +

Tile 3 content

 - ... ``` @@ -210,158 +158,37 @@ We can specify the number of grid columns for our Tile Manager. To do this, simp ```razor - + - Tile 1 header -

Tile 1 Content

+ Tile 1 +

Tile 1 content

 - Tile 2 header -

Tile 2 Content

+ Tile 2 +

Tile 2 content

 - Tile 3 header -

Tile 3 Content

+ Tile 3 +

Tile 3 content

 - ... ``` -In this code snippet, the three tiles in the Tile Manager will be arranged into 2 rows and 2 columns. +### Configure the Grid -### Gap +Set layout properties on to control the number of columns, tile spacing, and minimum tile track sizes. -Another property that can be used in the Tile Manager is the property, which defines the space between tiles. The value of the property must be a number followed by a length unit (e.g., px, rem, em, ...). This value will apply to both the horizontal gap (width) and the vertical gap (height) between tiles. +Use to define a fixed column count, to set spacing, and with to control the minimum track sizes. - + -```html - - - Tile 1 header -

Tile 1 Content

- - - Tile 2 header -

Tile 2 Content

- - ... - -``` +### Size and Position Individual Tiles - +Set tile-level properties when a tile should span more space or start from a specific row or column. - - -```tsx - - - Tile 1 header -

Tile 1 Content

- - - Tile 2 header -

Tile 2 Content

- - ... - -``` - - - - - -```razor - - - Tile 1 header -

Tile 1 Content

- - - Tile 2 header -

Tile 2 Content

- - ... - -``` - - - -### Minimum width and height - -We also have properties for setting the minimum width of the columns () and the minimum height of the rows () in the Tile Manager. Similar to the gap property, the values for these properties must be a number followed by a length unit. These values will define the minimum width for all columns and the minimum height for all rows in the Tile Manager. - - - -```html - - - Tile 1 header -

Tile 1 Content

- - - Tile 2 header -

Tile 2 Content

- - ... - -``` - - - - - -```tsx - - - Tile 1 header -

Tile 1 Content

- - - Tile 2 header -

Tile 2 Content

- - ... - -``` - - - - - -```razor - - - Tile 1 header -

Tile 1 Content

- - - Tile 2 header -

Tile 2 Content

- - ... - -``` - - - -### Example - - - -## Tile component - -The Tile component has properties that can be set individually for each tile. Some of these properties include: - -- The property specifies how many columns the tile will span across in the layout, allowing you to control its horizontal size. -- The property determines how many rows the tile will span vertically, adjusting the tile's height within the layout. -- The property specifies the starting column where the tile is placed. -- The property specifies the starting row where the tile is placed. -- The property hides the default fullscreen action button. -- The property hides the default maximize toggle action button. -- The property prevents the tile from being resized by the user. +The and properties control the rendered span. The property sets the starting row. [VERIFY: exact API target for the tile starting column member currently referenced as `colStart`] @@ -369,13 +196,12 @@ The Tile component has properties that can be set individually for each tile. So Tile 1 header -

Tile 1 Content

+

Tile 1 content

 Tile 2 header -

Tile 2 Content

+

Tile 2 content

 - ... ``` @@ -387,13 +213,12 @@ The Tile component has properties that can be set individually for each tile. So Tile 1 header -

Tile 1 Content

+

Tile 1 content

 Tile 2 header -

Tile 2 Content

+

Tile 2 content

 - ... ``` @@ -405,115 +230,37 @@ The Tile component has properties that can be set individually for each tile. So Tile 1 header -

Tile 1 Content

+

Tile 1 content

 Tile 2 header -

Tile 2 Content

- - ... - -``` - - - -The Tile component also exposes several slots which you can use: - -| Slot name | Description | -| ---------|------------ | -| `title` | Content for the tile header. | -| `fullscreen-action` | Overwrite the default fullscreen action content. | -| `maximize-action` | Overwrite the default maximize action content. | -| `actions` | Custom content rendered after the default actions. | -| `side-adorner` | Overwrite the default horizontal resize adorner. | -| `corner-adorner` | Overwrite the default diagonal resize adorner. | -| `bottom-adorner` | Overwrite the default vertical resize adorner. | - -When using the `title` slot, we recommend using a `` element rather than heading elements (`

`–`

`). Heading elements carry built-in styling (such as font size, line height, and margins) that can interfere with the component's intended typography and layout. Using a `` gives you a neutral container that inherits the component's styles cleanly. - -When using the `fullscreen-action`, `maximize-action`, `actions`, `side-adorner`, `corner-adorner` and `bottom-adorner` slots, we recommend using an [``](../layouts/icon.md) or [``](../inputs/icon-button.md) component for custom icons. - -### Header section actions - -By default, the header section includes two action buttons: - -- The `maximize` button enlarges the tile's content to fill the entire width of the Tile Manager, offering a wider view of the content. -- The `fullscreen` button enables the tile to open in fullscreen mode in the user's browser. - -tile-manager-actions - -If you want to display just one of the two buttons, you can set either or property. To customize the appearance you can use the `maximize-action` slot for the maximize button, or the `fullscreen-action` slot for the fullscreen button. - - - -```html - - - - -

Tile 1 Content

- - -``` - - - - - -```tsx - - - - -

Tile 1 Content

- - -``` - - - - - -```razor - - - - -

Tile 1 Content

+

Tile 2 content

 ``` -You also have the option to disable both action buttons and create custom ones according to your preferences. +### Customize Header Actions - +Use tile action properties and slots when you need to show, hide, or replace the default maximize and fullscreen buttons. -In this example, we created custom action buttons using the Ignite UI Icon Button component. +Set or to hide the default actions. Use the `maximize-action` and `fullscreen-action` slots to replace the button content, and the `actions` slot to append custom actions after the defaults. -## Resizing +When you provide a `title` slot, use a `` instead of a heading element so the tile header keeps the intended spacing and typography. -Resizing in the Tile Manager is a functionality that allows tiles to be resized using three different resize adorners. + -- **Side Adorner**: Adjusts the width by modifying the column span. -- **Bottom Adorner**: Adjusts the height by modifying the row span. -- **Corner Adorner**: Adjusts both width and height simultaneously. +### Enable Resizing -To ensure smooth resizing, a ghost element is used instead of directly modifying the tile’s dimensions. This element appears on top of the original tile, displaying its current dimensions when resizing begins, and it updates in real time as the user drags any of the resize handles. +Set the tile manager resize mode when users need to change tile dimensions interactively. - -If the ghost element exceeds the available grid space, it will automatically adjust to the largest possible span within the grid's limits. - - -The Tile Manager automatically rearranges itself when a tile changes size, ensuring that there is minimal empty space. That's why expanding a tile may push adjacent tiles into new positions, while shrinking creates gaps that other tiles may fill dynamically. This ensures that the Tile Manager stays as compact as possible, without any overlapping tiles, and that all movements remain within the defined grid structure. - -We can use the property to control how resizing is applied in the Tile Manager. It can be set to `none`, `hover` or `always`, which determines when the resize adorners are visible. The default value is `none` and the tile could not be resized. +The property controls when resize adorners appear. The verified values shown on this page are `none`, `hover`, and `always`. ```html - +

Tile 1

 @@ -555,35 +302,17 @@ We can use the -You can see the difference between the three states in the example below: - - - -### Snapping - -Tiles resize in full grid units, meaning they can only grow or shrink by whole columns or rows. The ghost element snaps to the next column or row when expanding past the halfway point and to the previous one when shrinking past the halfway mark. This applies to all adorners (bottom, side and corner), ensuring tiles always stay aligned to the grid. - -Grid gaps are also considered, keeping the layout consistent during resizing. - -### Limitations - -There are several constraints and limitations in the resizing process: - -- A tile cannot be resized smaller than its defined minimum width or height (, ). -- A tile cannot exceed the maximum available horizontal space in the grid. - -## Reorder + +If the resize ghost exceeds the available grid space, it adjusts to the largest span the current grid can fit. + -You can reorder tiles in the Tile Manager using the drag-and-drop feature. By default, tiles are not draggable. To enable this functionality, set the property on the Tile Manager to either `tile` or `tile-header`. + -- With the `tile` option, you can click and hold anywhere on an individual tile to start dragging it. -- With the `tile-header` option, you can only click and hold in the tile's header section to start the dragging process. +### Reorder Tiles - -While the tile is in maximized or fullscreen state, the tile cannot be dragged. - +Set the drag mode when users need to reorder tiles with drag and drop. -Similar to resizing, when you initiate the drag-and-drop process, a ghost element appears beneath the tile you’ve grabbed. As you drag the tile, the ghost element moves with it, dynamically reordering the other tiles in real time. This allows you to preview how the tile grid will look when you drop the tile. +Use the property with `tile` to drag from any tile surface or `tile-header` to drag only from the header. @@ -591,11 +320,11 @@ Similar to resizing, when you initiate the drag-and-drop process, a ghost elemen Tile 1 header -

Tile 1 Content

+

Tile 1 content

 Tile 2 header -

Tile 2 Content

+

Tile 2 content

 ``` @@ -608,11 +337,11 @@ Similar to resizing, when you initiate the drag-and-drop process, a ghost elemen Tile 1 header -

Tile 1 Content

+

Tile 1 content

 Tile 2 header -

Tile 2 Content

+

Tile 2 content

 ``` @@ -625,46 +354,91 @@ Similar to resizing, when you initiate the drag-and-drop process, a ghost elemen Tile 1 header -

Tile 1 Content

+

Tile 1 content

 Tile 2 header -

Tile 2 Content

+

Tile 2 content

 ``` - + +Tiles cannot be dragged while they are maximized or in fullscreen mode. + -## Serialization + -The Tile Manager provides methods that help manage the layout of tiles: +### Save and Restore Layouts -- The method allows you to save the current arrangement of tiles in the Tile Manager, it captures the current order, size and position of all tiles, so you can later restore it to this exact configuration. -- The method enables you to load a previously saved layout. When called, it restores the tiles to the exact state they were in when the layout was saved, including their order, size and position. +Use the tile manager layout methods when your app needs to persist and restore user personalization. - +The method saves the current tile order, size, and placement. The method restores a previously saved layout. + + + +## Best Practices + +Use Tile Manager for user-personalized dashboards, not as a general replacement for every grid or layout container. + +- Keep tile titles short and descriptive so users can identify tiles quickly while dragging or maximizing them. +- Reserve fullscreen and maximize behavior for content that benefits from temporary focus, such as charts, grids, or editors. +- Set minimum row and column sizes that preserve readable content when tiles are resized. +- Use `tile-header` drag mode when the tile body contains interactive controls that should not start drag operations accidentally. +- Persist user layout changes when the workspace is meant to be revisited across sessions. + +## Properties + +Use the generated API reference for the full surface; the rows below mark the core options covered on this page. + +| Name | Type | Default | Description | +| -- | -- | -- | -- | +| `columnCount` | build-generated | build-generated | Build injects verified core tile manager properties here from the typed API source. | +| `gap` | build-generated | build-generated | Build injects verified core tile manager properties here from the typed API source. | +| `minColumnWidth` | build-generated | build-generated | Build injects verified core tile manager properties here from the typed API source. | +| `minRowHeight` | build-generated | build-generated | Build injects verified core tile manager properties here from the typed API source. | +| `resizeMode` | build-generated | build-generated | Build injects verified core tile manager properties here from the typed API source. | +| `dragMode` | build-generated | build-generated | Build injects verified core tile manager properties here from the typed API source. | +| `colSpan` | build-generated | build-generated | Build injects verified core tile properties here from the typed API source. | +| `rowSpan` | build-generated | build-generated | Build injects verified core tile properties here from the typed API source. | + +## Methods + +Use the tile manager methods when you need to persist or restore a layout from code. + +| Name | Description | +| -- | -- | +| `saveLayout` | Saves the current tile arrangement. | +| `loadLayout` | Restores a previously saved tile arrangement. | ## Styling -You can also customize the appearance of the two components - and . -The exposes only one CSS property - `base` which can be used for styling the base wrapper of the Tile Manager. -The exposes several CSS properties we can use: +Use CSS parts and tile slots to restyle the tile manager surface, tile headers, content area, and resize adorners. + + + +The component exposes the following CSS parts: | Part name | Description | -| ---------|------------ | +| -- | -- | +| `base` | The wrapping container of the tile manager. | + +The component exposes the following CSS parts: + +| Part name | Description | +| -- | -- | | `base` | The wrapping container of the tile component. | -| `header` | The header container of the tile, including title and actions parts. | +| `header` | The header container of the tile, including the title and actions parts. | | `title` | The title container. | | `actions` | The actions container. | | `content-container` | The container wrapping the tile default slot. | -| `trigger-side` | The horizontal adorner. | -| `trigger` | The diagonal adorner | -| `trigger-bottom` | The vertical adorner. | +| `trigger-side` | The horizontal resize adorner. | +| `trigger` | The diagonal resize adorner. | +| `trigger-bottom` | The vertical resize adorner. | -Using these CSS parts you can customize the appearance of the two components as follows: +Use the `side-adorner`, `corner-adorner`, and `bottom-adorner` slots when you need to replace the default resize affordances with custom icon content. ```css igc-tile-manager::part(base) { @@ -693,8 +467,6 @@ igc-tile:nth-child(n+2)::part(trigger) { } ``` -You can also change the icon of the adorners to a custom one using the `side-adorner`, `corner-adorner`, and `bottom-adorner` slots. For instance: - ```html @@ -734,20 +506,49 @@ You can also change the icon of the adorners to a custom one using the `side-ado - +## Accessibility -## API Reference +Tile Manager combines keyboard focus, tile actions, drag behavior, and resize behavior, so the page should document both the built-in support and any app-level accessibility requirements clearly. -- -- -- [`Styling & Themes`](../themes/overview.md) +### Keyboard Interaction -## Additional Resources +[VERIFY: keyboard interaction model for Tile Manager, tile actions, drag, resize, maximize, and fullscreen] + +### Screen Readers / ARIA + +[VERIFY: screen reader roles, aria attributes, action button labels, and resize / drag announcements for Tile Manager and Tile] + +### Accessibility Compliance + +[VERIFY: official accessibility conformance target for the Tile Manager component] + +| Criterion | How the component complies | +| -- | -- | +| [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships) | [VERIFY: semantic structure of tiles, headers, and content regions] | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) | [VERIFY: keyboard operability of tile actions and any drag / resize alternatives] | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order) | [VERIFY: predictable focus order across tile headers, actions, and content] | +| [2.5.7 Dragging Movements](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements) | [VERIFY: non-drag alternative for tile movement or documented limitation] | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value) | [VERIFY: semantic exposure of tiles, action buttons, and state changes] | + +Your responsibilities: -- -- -- +- Provide clear tile titles so screen reader users can distinguish each workspace region. +- Ensure custom maximize, fullscreen, and resize adorner content preserves an accessible name. +- Validate focus visibility and contrast after restyling tile headers, action buttons, and resize handles. +## API References + + + + + + +## Dependencies + +Tile Manager depends on a theme stylesheet for its visual styling, and custom action or adorner content commonly uses the icon components referenced in this topic. + +## Additional Resources + +- [`Styling & Themes`](../themes/overview.md) - [{ProductName} **Forums**]({ForumsLink}) - [{ProductName} **GitHub**]({GithubLink}) -