Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PTL-1756: Review of the Interaction pages #2078

Merged
merged 6 commits into from
Jan 8, 2025
Merged

PTL-1756: Review of the Interaction pages #2078

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3dd7611
PTL-1755: review of interaction pages
wjhendry Jan 3, 2025
3e89232
interim
wjhendry Jan 6, 2025
fc10aaf
Final updates
wjhendry Jan 7, 2025
cbc0b78
Update docs/001_develop/03_client-capabilities/008_interaction/anchor…
wjhendry Jan 8, 2025
e33de49
Update anchored-region.mdx
wjhendry Jan 8, 2025
e3a8a0c
Update listbox.mdx
wjhendry Jan 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 12 additions & 10 deletions docs/001_develop/03_client-capabilities/008_interaction/accordian.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,16 @@ import AccordionDemo from '/examples/ui/client-capabilities/interaction/accordio
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Accordions allow users to expand or collapse sections of content on a page.
Accordions enable users to expand or collapse sections of content on a page.

Use cases:
* Presenting multiple sections of content
* Allow the users to show or hide different sections of related information
* presenting multiple sections of content
* enabling users to show or hide specific sections of related information


## Example
You can see an accordion in action in the example below. This has three panels (accordion items) that can be expanded or collapsed by clicking on the `+` or `-` icons.

<AccordionDemo />

<Tabs defaultValue="genesis" values={[{ label: 'Genesis', value: 'genesis', }, { label: 'React', value: 'react', }, { label: 'Angular', value: 'angular', }]}>
Expand Down Expand Up @@ -155,7 +157,7 @@ Use cases:
<tr>
<td>expand-mode</td>
<td><code>"single" | "multi"</code></td>
<td>When using the <em>default</em> <code>multi</code> expand mode, the user can expand multiple sections at the same time. When using the <code>single</code> expand mode, the user can only expand one section at a time.</td>
<td>When using the default <code>multi</code> expand mode, the user can expand multiple sections at the same time. When using the <code>single</code> expand mode, the user can only expand one section at a time.</td>
<td>

```typescript
Expand All @@ -169,7 +171,7 @@ Use cases:

### Properties

This component doesn't have any properties which are not also controlled via attributes.
The properties of this component are all controlled via attributes.

### Slots

Expand Down Expand Up @@ -263,10 +265,10 @@ This component doesn't have any properties which are not also controlled via att

| Slot | Description |
| --- | --- |
| Default | The default slot for accordion item content |
| start | Content which can be provided between the heading and the icon |
| end | Content which can be provided between the start slot and icon |
| heading | Content which serves as the accordion item heading and text of the expand button |
| Default | The default slot for placing accordion item content |
| start | Content to be placed between the heading and the icon |
| end | Content to be placed between the start slot and icon |
| heading | Content that serves as the accordion item heading and the text of the expand button |
| expanded-icon | The expanded icon |
| collapsed-icon | The collapsed icon |

Expand All @@ -275,7 +277,7 @@ This component doesn't have any properties which are not also controlled via att
| Part | Description |
| --- | --- |
| heading | Wraps the button |
| button | The button which serves to invoke the item |
| button | The button that serves to invoke the item |
| heading-content | Wraps the slot for the heading content within the button |
| icon | The icon container |
| expanded-icon | The expanded icon slot |
Expand Down
28 changes: 15 additions & 13 deletions docs/001_develop/03_client-capabilities/008_interaction/anchor.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,16 @@ import AnchorDemo from '/examples/ui/client-capabilities/interaction/anchor.js';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Anchors add different types of links to your page.
Anchors enable you to show links of different types of in a page.

Use cases:
* Creating a hyperlink to a different page
* Linking to a specific region of the current page
* An email link which pre-populates the recipient field
* a hyperlink to a different page
* linking to a specific region of the current page
* an email link that pre-populates the recipient field

## Example
There are three working links in the example below.

<AnchorDemo />

<Tabs defaultValue="genesis" values={[{ label: 'Genesis', value: 'genesis', }, { label: 'React', value: 'react', }, { label: 'Angular', value: 'angular', }]}>
Expand Down Expand Up @@ -114,7 +116,7 @@ Use cases:
<tr>
<td>download</td>
<td><code>string | boolean</code></td>
<td>Causes the browser to treat the linked URL as a download. This attributes only works for same-origin URLs, or when using the <code>blob:</code> and <code>data:</code> schemes. Different browsers will behave slightly differently for downloads, such as asking the user where to save the file or automatically saving to a downloads directory.</td>
<td>Causes the browser to treat the linked URL as a download. This attributes only works for same-origin URLs, or when using the <code>blob:</code> and <code>data:</code> schemes. Different browsers behave slightly differently for downloads, such as asking the user where to save the file or automatically saving to a downloads directory.</td>
<td>

```typescript
Expand All @@ -126,7 +128,7 @@ Use cases:
<tr>
<td>href</td>
<td><code>string</code></td>
<td>The URL that the hyperlink points to. This is commonly to another page, but it could be to a region of the current page. You can also use schemes such as <code>mailto:</code>, <code>javascript:</code>, <code>tel:</code>, and <code>sms:</code></td>
<td>The URL that the hyperlink points to. This is commonly to another page in your app, but it could be to a region of the current page. You can also use schemes such as <code>mailto:</code>, <code>javascript:</code>, <code>tel:</code>, and <code>sms:</code></td>
<td>

```typescript
Expand All @@ -150,7 +152,7 @@ Use cases:
<tr>
<td>ping</td>
<td><code>string</code></td>
<td>A space separated list of URLs to which to send a <code>PING</code> message. This is commonly used for tracking.</td>
<td>A space-separated list of URLs to which to send a <code>PING</code> message. This is commonly used for tracking.</td>
<td>

```typescript
Expand Down Expand Up @@ -213,22 +215,22 @@ Use cases:

### Properties

This component doesn't have any properties which are not also controlled via attributes.
The properties of this component are all controlled via [attributes](#attributes).

### Slots

|Slot|Description|
|---|---|
|Default|This elements which are contained in the anchor region, and will trigger the `href` when clicked.|
|start|Content which can be provided before the anchor content.|
|end|Content which can be provided after the anchor content.|
|Default| The elements that are contained in the anchor region, and which trigger the `href` when clicked.|
|start| Optional content to be placed before the anchor content.|
|end| Optional content to be placed after the anchor content.|

### Parts

| Part | Description |
| --- | --- |
| control | The anchor element |
| content | The element wrapping anchor content
| control | The anchor element. |
| content | The element wrapping the anchor content. |

### Events fired

Expand Down
43 changes: 22 additions & 21 deletions docs/001_develop/03_client-capabilities/008_interaction/anchored-region.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,17 @@ import AnchoredRegion from '/examples/ui/client-capabilities/interaction/anchore
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Anchored regions are containers which position content relative to the anchor element. The anchored region can react to the available space between the anchor and a parent "viewport" element such that the region is placed on the side of the anchor with the most available space, or even resize itself based on that space.
Anchored regions are containers that position content relative to the anchor element.

The anchored region can react to the available space between the anchor and a parent `viewport` element. Depending on the attributes set, the region can be placed on the side of the anchor with the most available space, or it can resize itself based on that space.

Use cases:
* Creating a layout which is reactive to layout changes
* Creating a layout where elements are not viewed in DOM order (1)
* creating a component that is visible relative to another component (for information, this component is used to implement the [Tooltip](/develop/client-capabilities/interaction/client-interaction-tooltip/) component)
* creating a layout that reacts to layout changes
* creating a layout where elements are not viewed in DOM order (1)

:::warning
(1) Elements which are viewed differently to the DOM order may cause accessibility issues with screen readers.
(1) Elements that are not viewed in the same order as the DOM order could cause accessibility issues with screen readers.
:::

## Example
Expand Down Expand Up @@ -134,8 +137,6 @@ The live example includes css styling to ensure the components fit into the exam

### Attributes



<table>
<thead>
<tr>
Expand All @@ -149,7 +150,7 @@ The live example includes css styling to ensure the components fit into the exam
<tr>
<td>anchor</td>
<td><code>string</code></td>
<td>The HTML ID of the anchor element this region is positioned relative to. Default: ""</td>
<td>The HTML ID of the anchor element this region is positioned relative to. </td>
<td>

```typescript
Expand All @@ -161,7 +162,7 @@ The live example includes css styling to ensure the components fit into the exam
<tr>
<td>viewport</td>
<td><code>string</code></td>
<td>The HTML ID of the viewport element this region is positioned relative to. Default: ""</td>
<td>The HTML ID of the viewport element this region is positioned relative to. </td>
<td>

```typescript
Expand All @@ -173,7 +174,7 @@ The live example includes css styling to ensure the components fit into the exam
<tr>
<td>horizontal-positioning-mode</td>
<td><code>"uncontrolled" | "locktodefault" | "dynamic"</code></td>
<td>Sets logic for horizontal placement. Default: "uncontrolled". <code>locktodefault</code> forces the default position, <code>dynamic</code> decides placement based on available space, and <code>uncontrolled</code> does not control placement on the horizontal axis</td>
<td>Controls horizontal placement. Default: "uncontrolled". <code>locktodefault</code> forces the default position, <code>dynamic</code> decides placement based on available space, and <code>uncontrolled</code> does not control placement on the horizontal axis</td>
<td>

```typescript
Expand All @@ -197,7 +198,7 @@ The live example includes css styling to ensure the components fit into the exam
<tr>
<td>horizontal-viewport-lock</td>
<td><code>boolean</code></td>
<td>Whether region remains in viewport on horizontal axis. Default: false</td>
<td>Controls whether the region remains in the viewport on the horizontal axis. Default: false</td>
wjhendry marked this conversation as resolved.
Show resolved Hide resolved
<td>

```typescript
Expand All @@ -209,7 +210,7 @@ The live example includes css styling to ensure the components fit into the exam
<tr>
<td>horizontal-inset</td>
<td><code>boolean</code></td>
<td>Whether region overlaps anchor on horizontal axis. Default: false</td>
<td>Controls whether the region can overlap the anchor on the horizontal axis. Default: false</td>
<td>

```typescript
Expand All @@ -221,7 +222,7 @@ The live example includes css styling to ensure the components fit into the exam
<tr>
<td>horizontal-threshold</td>
<td><code>number</code></td>
<td>How narrow the space allocated to the default position has to be before the widest area is selected for the layout.</td>
<td>Sets how narrow the space allocated to the default position has to be before the widest area is selected for the layout.</td>
<td>

```typescript
Expand Down Expand Up @@ -269,7 +270,7 @@ The live example includes css styling to ensure the components fit into the exam
<tr>
<td>vertical-viewport-lock</td>
<td><code>boolean</code></td>
<td>Whether region remains in viewport on vertical axis (i.e. detatches from the anchor). Default: false</td>
<td>Controls whether the anchored region always remains fully in the viewport on the horizontal axis. If true, the position is adjusted to stay within viewport bounds, detaching from the anchor if necessary. This prevents overflow and clipping. Default: false</td>
wjhendry marked this conversation as resolved.
Show resolved Hide resolved
<td>

```typescript
Expand All @@ -281,7 +282,7 @@ The live example includes css styling to ensure the components fit into the exam
<tr>
<td>vertical-inset</td>
<td><code>boolean</code></td>
<td>Whether the region overlaps the anchor on the vertical axis</td>
<td>Controls whether the region can overlap the anchor on the vertical axis</td>
<td>

```typescript
Expand All @@ -293,7 +294,7 @@ The live example includes css styling to ensure the components fit into the exam
<tr>
<td>vertical-threshold</td>
<td><code>number</code></td>
<td>Space threshold before tallest area is selected for layout</td>
<td>Space threshold before the tallest area is selected for layout</td>
<td>

```typescript
Expand All @@ -317,7 +318,7 @@ The live example includes css styling to ensure the components fit into the exam
<tr>
<td>fixed-placement</td>
<td><code>boolean</code></td>
<td>Whether region uses fixed positioning instead of absolute. Default: false</td>
<td>Controls whether the region uses fixed positioning instead of absolute. Default: false</td>
<td>

```typescript
Expand All @@ -343,7 +344,7 @@ The live example includes css styling to ensure the components fit into the exam

### Properties

You should only be reading these properties via the code, rather than setting them on the template.
You should only read these properties via the code. Do not set them on the template.

|Property|Type|Description|
|--|--|--|
Expand All @@ -355,11 +356,11 @@ You should only be reading these properties via the code, rather than setting th

|Slot|Description|
|---|---|
|Default|This elements which are contained in the anchored region.|
|Default|The elements that are contained in the anchored region.|

### Parts

This component doesn't have any css parts. Style the content in the default slot directly.
This component doesn't have any css parts. Style the content directly in the default slot.

### Events fired

Expand All @@ -376,7 +377,7 @@ This component doesn't have any css parts. Style the content in the default slot
<tr>
<td>loaded</td>
<td><code>this</code></td>
<td>Fires when the region is loaded and visible</td>
<td>Fires when the region is loaded and visible.</td>
<td>

```typescript
Expand All @@ -388,7 +389,7 @@ This component doesn't have any css parts. Style the content in the default slot
<tr>
<td>positionchange</td>
<td><code>this</code></td>
<td>Fires when the position has changed</td>
<td>Fires when the position has changed.</td>
<td>

```typescript
Expand Down
25 changes: 14 additions & 11 deletions docs/001_develop/03_client-capabilities/008_interaction/dialog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,16 @@ import DialogDemo from '/examples/ui/client-capabilities/interaction/dialog.js';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Dialogs are popup menus which take focus and prohibit the user interacting with the content behind.
A dialog is a pop-up dialog (rectangular panel) that takes focus, and prohibits the user from interacting with the content behind.

Use cases:
* Popup notification
* Configuration box
* pop-up notification
* configuration box

## Example
The example below shows the component in action. Clicking on the `Open Dialog` button displays a dialog with some simple text. Click in the `x` in the top right corner to remove the dialog.


<DialogDemo />

<Tabs defaultValue="genesis" values={[{ label: 'Genesis', value: 'genesis', }, { label: 'React', value: 'react', }, { label: 'Angular', value: 'angular', }]}>
Expand Down Expand Up @@ -168,7 +171,7 @@ Use cases:
<tr>
<td>position</td>
<td><code>'center' | 'left' | 'right'</code></td>
<td>The position of the dialog. <code>center</code> is the default.</td>
<td>The position of the dialog. Default is <code>center</code>.</td>
<td>

```typescript
Expand All @@ -180,7 +183,7 @@ Use cases:
<tr>
<td>show-close-icon</td>
<td><code>boolean</code></td>
<td>Enables the close icon in the top right corner of the dialog. <code>true</code> is the default.</td>
<td>Enables the close icon in the top right corner of the dialog. Default is <code>true</code>.</td>
<td>

```typescript
Expand Down Expand Up @@ -235,24 +238,24 @@ Use cases:

|Method|Description|Example|
|--|--|--|
|show|Show the dialog|`dialogRef.show()`|
|close|Hides the dialog|`dialogRef.close()`|
|show|Shows the dialog. |`dialogRef.show()`|
|close|Hides the dialog. |`dialogRef.close()`|

### Slots

|Slot|Description|
|---|---|
|Default|All the content which you want to display on the dialog box when shown.|
|Default|All the content that you want to display on the dialog box when shown.|
|top|Can be used to set a title section for the dialog.|
|bottom|Can be used to set a footer section for the dialog.|

### Parts

| Part | Description |
| --- | --- |
|dialog|the base html `dialog` tag|
|top|The top part of the dialog which contains the dialog header|
|bottom|The bottom part of the dialog which contains the dialog footer|
|dialog|The base html `dialog` tag.|
|top|The top part of the dialog, which contains the dialog header.|
|bottom|The bottom part of the dialog, which contains the dialog footer.|

### Events fired

Expand Down
Loading